feat(codegen): add CLI and integration tests

Click-based CLI entry point (overture-codegen generate) that
wires discovery → extraction → output layout → rendering:

- Discovers models via discover_models() entry points
- Filters themes, extracts specs, builds placement registry
- Renders markdown pages with field tables, examples, cross-
  references, and sidebar metadata
- Supports --theme filtering and --output-dir targeting

Integration tests verify extraction against real Overture
models (Building, Division, Segment, etc.) to catch schema
drift. CLI tests verify end-to-end generation, output
structure, and link integrity.

Author: mojodna

packages/overture-schema-codegen/src/overture/schema/codegen/cli.py

@@ -0,0 +1,195 @@
+"""CLI entrypoint for schema code generation."""
+
+import json
+import logging
+from pathlib import Path, PurePosixPath
+
+import click
+
+from overture.schema.core.discovery import discover_models
+
+from .markdown_pipeline import generate_markdown_pages
+from .model_extraction import extract_model
+from .module_layout import (
+    OUTPUT_ROOT,
+    compute_schema_root,
+    entry_point_class,
+    entry_point_module,
+)
+from .specs import (
+    FeatureSpec,
+    is_model_class,
+    is_union_alias,
+)
+from .union_extraction import extract_union
+
+log = logging.getLogger(__name__)
+
+__all__ = ["cli"]
+
+_OUTPUT_FORMATS = ("markdown",)
+
+_FEATURE_FRONTMATTER = "---\nsidebar_position: 1\n---\n\n"
+
+
+def _write_output(
+    content: str,
+    output_dir: Path | None,
+    output_path: PurePosixPath,
+) -> None:
+    """Write content to a file under output_dir, or stdout."""
+    if output_dir:
+        file_path = output_dir / output_path
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(content)
+    else:
+        click.echo(content)
+        click.echo()  # separate entries with a blank line in stdout mode
+
+
+@click.group()
+def cli() -> None:
+    """Overture Schema code generator.
+
+    Generate documentation and code from Pydantic schema models.
+    """
+
+
+@cli.command("list")
+def list_models() -> None:
+    """List all discovered models."""
+    models = discover_models()
+    names = sorted(
+        model.__name__ if isinstance(model, type) else str(model)
+        for model in models.values()
+    )
+    for name in names:
+        click.echo(name)
+
+
+@cli.command()
+@click.option(
+    "--format",
+    "output_format",
+    required=True,
+    type=click.Choice(_OUTPUT_FORMATS),
+    help="Output format",
+)
+@click.option(
+    "--theme",
+    multiple=True,
+    help="Filter to specific theme(s); repeatable (e.g., --theme buildings --theme places)",
+)
+@click.option(
+    "--output-dir",
+    type=click.Path(path_type=Path),
+    default=None,
+    help="Write output to directory (default: stdout)",
+)
+def generate(
+    output_format: str,
+    theme: tuple[str, ...],
+    output_dir: Path | None,
+) -> None:
+    """Generate code/docs from discovered models."""
+    all_models = discover_models()
+
+    # Schema root from ALL entry points (before theme filter).
+    module_paths = [entry_point_module(k.entry_point) for k in all_models]
+    schema_root = compute_schema_root(module_paths)
+
+    models = (
+        {k: v for k, v in all_models.items() if k.theme in theme}
+        if theme
+        else all_models
+    )
+
+    if output_dir:
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    feature_specs: list[FeatureSpec] = []
+    for key, entry in models.items():
+        if is_model_class(entry):
+            feature_specs.append(extract_model(entry, entry_point=key.entry_point))
+        elif is_union_alias(entry):
+            feature_specs.append(
+                extract_union(
+                    entry_point_class(key.entry_point),
+                    entry,
+                    entry_point=key.entry_point,
+                )
+            )
+
+    _generate_markdown(feature_specs, schema_root, output_dir)
+
+
+def _generate_markdown(
+    feature_specs: list[FeatureSpec],
+    schema_root: str,
+    output_dir: Path | None,
+) -> None:
+    """Generate markdown with directory layout and placement-aware links."""
+    pages = generate_markdown_pages(feature_specs, schema_root)
+
+    for page in pages:
+        content = (
+            f"{_FEATURE_FRONTMATTER}{page.content}" if page.is_feature else page.content
+        )
+        _write_output(content, output_dir, page.path)
+
+    if output_dir:
+        feature_paths = {page.path for page in pages if page.is_feature}
+        all_paths = {page.path for page in pages}
+        _write_category_files(output_dir, all_paths, feature_paths)
+
+
+def _ancestor_dirs(paths: set[PurePosixPath]) -> set[PurePosixPath]:
+    """Collect all ancestor directories for a set of file paths."""
+    dirs: set[PurePosixPath] = set()
+    for path in paths:
+        parent = path.parent
+        while parent != OUTPUT_ROOT:
+            dirs.add(parent)
+            parent = parent.parent
+    return dirs
+
+
+def _top_level_positions(
+    dirs: set[PurePosixPath],
+    feature_paths: set[PurePosixPath],
+) -> dict[PurePosixPath, int]:
+    """Assign sidebar positions: feature dirs first, then non-feature, both alphabetical."""
+    feature_dir_names = {p.parts[0] for p in feature_paths}
+    top_level = sorted(d for d in dirs if d.parent == OUTPUT_ROOT)
+    feature_dirs = [d for d in top_level if d.name in feature_dir_names]
+    non_feature_dirs = [d for d in top_level if d.name not in feature_dir_names]
+    return {d: i for i, d in enumerate(feature_dirs + non_feature_dirs, start=1)}
+
+
+def _write_category_files(
+    output_dir: Path,
+    all_paths: set[PurePosixPath],
+    feature_paths: set[PurePosixPath],
+) -> None:
+    """Write _category_.json files for Docusaurus sidebar navigation."""
+    dirs = _ancestor_dirs(all_paths)
+    positions = _top_level_positions(dirs, feature_paths)
+
+    for dir_path in sorted(dirs):
+        label = dir_path.name.replace("_", " ").title()
+        category: dict[str, object] = {"label": label}
+        if dir_path in positions:
+            category["position"] = positions[dir_path]
+
+        file_path = output_dir / dir_path / "_category_.json"
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        file_path.write_text(json.dumps(category, indent=2) + "\n")
+
+
+def main() -> None:
+    """Run the CLI entry point."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

packages/overture-schema-codegen/src/overture/schema/codegen/link_computation.py

@@ -31,7 +31,7 @@ def resolve_link_or_slug(self, name: str) -> str:
 
 
 def _is_normalized(path: PurePosixPath) -> bool:
-    """True when the path contains no '..' or '.' components (except root '.')."""
+    """Check whether the path contains no '..' or '.' components (except root '.')."""
     return ".." not in path.parts and path.parts.count(".") <= 1
 
 
@@ -41,8 +41,12 @@ def relative_link(source: PurePosixPath, target: PurePosixPath) -> str:
     Both paths must be normalized (no ``..`` components) and relative
     to the same output root.
     """
-    assert _is_normalized(source), f"Source path not normalized: {source}"
-    assert _is_normalized(target), f"Target path not normalized: {target}"
+    if not _is_normalized(source):
+        msg = f"Source path not normalized: {source}"
+        raise ValueError(msg)
+    if not _is_normalized(target):
+        msg = f"Target path not normalized: {target}"
+        raise ValueError(msg)
     source_dir = source.parent
     # Count how many levels up from source_dir to common ancestor,
     # then descend to target. PurePosixPath doesn't have os.path.relpath,

packages/overture-schema-codegen/src/overture/schema/codegen/markdown_pipeline.py

@@ -0,0 +1,160 @@
+"""Markdown generation pipeline: render pages without I/O.
+
+Orchestrates tree expansion, type collection, placement, reverse
+references, and rendering into a list of RenderedPage objects. The
+caller decides what to do with them (write to disk, add frontmatter,
+stream to stdout, etc.).
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+import overture.schema.system.primitive as _system_primitive
+from overture.schema.system.primitive import GeometryType
+
+from .example_loader import ExampleRecord, load_examples
+from .link_computation import LinkContext
+from .markdown_renderer import (
+    render_enum,
+    render_feature,
+    render_geometry_from_values,
+    render_newtype,
+    render_primitives_from_specs,
+)
+from .model_extraction import expand_model_tree
+from .path_assignment import (
+    GEOMETRY_PAGE,
+    PRIMITIVES_PAGE,
+    build_placement_registry,
+    resolve_output_path,
+)
+from .primitive_extraction import (
+    extract_primitives,
+    partition_primitive_and_geometry_names,
+)
+from .reverse_references import UsedByEntry, compute_reverse_references
+from .specs import (
+    EnumSpec,
+    FeatureSpec,
+    ModelSpec,
+    NewTypeSpec,
+    SupplementarySpec,
+    UnionSpec,
+)
+from .type_collection import collect_all_supplementary_types
+
+__all__ = ["RenderedPage", "generate_markdown_pages"]
+
+
+@dataclass(frozen=True, slots=True)
+class RenderedPage:
+    """A rendered page with its content and output path."""
+
+    content: str
+    path: PurePosixPath
+    is_feature: bool = False
+
+
+def _load_model_examples(
+    spec: FeatureSpec,
+) -> list[ExampleRecord] | None:
+    """Load examples for a feature spec, returning None when absent."""
+    if isinstance(spec, UnionSpec):
+        pyproject_source = spec.members[0] if spec.members else None
+        validation_type = spec.source_annotation
+        model_fields = spec.common_base.model_fields
+    else:
+        pyproject_source = spec.source_type
+        validation_type = spec.source_type
+        model_fields = spec.source_type.model_fields if spec.source_type else {}
+    if not pyproject_source:
+        return None
+    field_names = [f.name for f in spec.fields]
+    examples = load_examples(
+        validation_type,
+        spec.name,
+        field_names,
+        pyproject_source=pyproject_source,
+        model_fields=model_fields,
+    )
+    return examples or None
+
+
+def _render_supplement(
+    name: str,
+    spec: SupplementarySpec,
+    registry: dict[str, PurePosixPath],
+    reverse_refs: dict[str, list[UsedByEntry]],
+) -> RenderedPage:
+    """Render a single supplementary page (enum, NewType, or sub-model)."""
+    output_path = resolve_output_path(name, registry)
+    ctx = LinkContext(output_path, registry)
+    used_by = reverse_refs.get(name)
+
+    if isinstance(spec, EnumSpec):
+        content = render_enum(spec, link_ctx=ctx, used_by=used_by)
+    elif isinstance(spec, NewTypeSpec):
+        content = render_newtype(spec, ctx, used_by=used_by)
+    elif isinstance(spec, ModelSpec):
+        content = render_feature(spec, ctx, used_by=used_by)
+    else:
+        raise TypeError(f"Unhandled SupplementarySpec variant: {type(spec).__name__}")
+
+    return RenderedPage(content=content, path=output_path)
+
+
+def generate_markdown_pages(
+    feature_specs: Sequence[FeatureSpec],
+    schema_root: str,
+) -> list[RenderedPage]:
+    """Generate all markdown pages from feature specs.
+
+    Returns rendered pages without writing to disk. The caller handles
+    I/O, frontmatter injection, and any output-format-specific concerns
+    (like Docusaurus category files).
+    """
+    cache: dict[type, ModelSpec] = {}
+    for spec in feature_specs:
+        expand_model_tree(spec, cache)
+
+    primitive_names, geometry_names = partition_primitive_and_geometry_names(
+        _system_primitive
+    )
+    all_specs = collect_all_supplementary_types(feature_specs)
+    registry = build_placement_registry(
+        feature_specs, all_specs, primitive_names, geometry_names, schema_root
+    )
+
+    reverse_refs = compute_reverse_references(feature_specs, all_specs)
+
+    pages: list[RenderedPage] = []
+
+    for spec in feature_specs:
+        output_path = registry[spec.name]
+        ctx = LinkContext(output_path, registry)
+        examples = _load_model_examples(spec)
+        used_by = reverse_refs.get(spec.name)
+        content = render_feature(spec, link_ctx=ctx, examples=examples, used_by=used_by)
+        pages.append(RenderedPage(content=content, path=output_path, is_feature=True))
+
+    for name, supp_spec in all_specs.items():
+        pages.append(_render_supplement(name, supp_spec, registry, reverse_refs))
+
+    pages.append(
+        RenderedPage(
+            content=render_primitives_from_specs(
+                extract_primitives(primitive_names, _system_primitive)
+            ),
+            path=PRIMITIVES_PAGE,
+        )
+    )
+
+    pages.append(
+        RenderedPage(
+            content=render_geometry_from_values([m.value for m in GeometryType]),
+            path=GEOMETRY_PAGE,
+        )
+    )
+
+    return pages