overture-schema-codegen 0.1.1.dev0__py3-none-any.whl

overture/schema/codegen/markdown/link_computation.py

@@ -0,0 +1,70 @@
+"""Relative link computation between rendered output files."""
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+from overture.schema.system.case import to_snake_case
+
+from ..extraction.specs import TypeIdentity
+
+__all__ = ["LinkContext", "relative_link"]
+
+
+@dataclass
+class LinkContext:
+    """Placement context for resolving cross-directory markdown links."""
+
+    page_path: PurePosixPath
+    registry: dict[TypeIdentity, PurePosixPath]
+
+    def resolve_link(self, identity: TypeIdentity) -> str | None:
+        """Resolve *identity* to a relative link if it exists in the registry."""
+        if identity in self.registry:
+            return relative_link(self.page_path, self.registry[identity])
+        return None
+
+    def resolve_link_or_slug(self, identity: TypeIdentity) -> str:
+        """Resolve *identity* to a relative link, falling back to a slug filename.
+
+        Always returns a usable link string. Use when the caller needs a
+        link regardless of whether the type has a registered page.
+        """
+        return self.resolve_link(identity) or f"{to_snake_case(identity.name)}.md"
+
+
+def _is_normalized(path: PurePosixPath) -> bool:
+    """Check whether the path contains no '..' or '.' components (except root '.')."""
+    return ".." not in path.parts and path.parts.count(".") <= 1
+
+
+def relative_link(source: PurePosixPath, target: PurePosixPath) -> str:
+    """Compute a relative path from source file to target file.
+
+    Both paths must be normalized (no `..` components) and relative
+    to the same output root.
+    """
+    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,
+    # so compute manually.
+    source_parts = source_dir.parts
+    target_parts = target.parts
+
+    # Find common prefix length
+    common = 0
+    for s, t in zip(source_parts, target_parts, strict=False):
+        if s != t:
+            break
+        common += 1
+
+    ups = len(source_parts) - common
+    downs = target_parts[common:]
+
+    parts = [".."] * ups + list(downs)
+    return "/".join(parts) if parts else "."

overture/schema/codegen/markdown/path_assignment.py

@@ -0,0 +1,114 @@
+"""Map types to markdown output file paths.
+
+Uses module-mirrored output directories: output paths derive from
+the source Python module path relative to schema_root.
+"""
+
+from collections.abc import Sequence
+from pathlib import PurePosixPath
+
+from overture.schema.system.case import to_snake_case
+
+from ..extraction.specs import (
+    ModelSpec,
+    PydanticTypeSpec,
+    SupplementarySpec,
+    TypeIdentity,
+)
+from ..layout.module_layout import compute_output_dir, output_dir_for_entry_point
+
+__all__ = [
+    "GEOMETRIC_PAGE",
+    "NUMERIC_PAGE",
+    "build_placement_registry",
+    "resolve_output_path",
+]
+
+# Aggregate page paths.
+NUMERIC_PAGE = PurePosixPath("system/numeric.md")
+GEOMETRIC_PAGE = PurePosixPath("system/geometric.md")
+
+
+def build_placement_registry(
+    model_specs: Sequence[ModelSpec],
+    all_specs: dict[TypeIdentity, SupplementarySpec],
+    numeric_names: list[TypeIdentity],
+    geometry_names: list[TypeIdentity],
+    schema_root: str,
+) -> dict[TypeIdentity, PurePosixPath]:
+    """Build a mapping from TypeIdentity to output file paths.
+
+    Uses module-mirrored output directories: output paths derive from
+    the source Python module path relative to schema_root.
+    """
+    registry: dict[TypeIdentity, PurePosixPath] = _aggregate_page_entries(
+        numeric_names, geometry_names
+    )
+
+    feature_dirs: set[PurePosixPath] = set()
+    for spec in model_specs:
+        spec_dir = output_dir_for_entry_point(spec.entry_point, schema_root)
+        registry[spec.identity] = _md_path(spec_dir, spec.name)
+        feature_dirs.add(spec_dir)
+
+    for tid, supp_spec in all_specs.items():
+        if tid in registry:
+            continue
+        if isinstance(supp_spec, PydanticTypeSpec):
+            registry[tid] = _md_path(
+                PurePosixPath("pydantic") / supp_spec.source_module, tid.name
+            )
+            continue
+        source_module = getattr(supp_spec.source_type, "__module__", None)
+        if source_module is None:
+            continue
+        output_dir = compute_output_dir(source_module, schema_root)
+        output_dir = _nest_under_types(output_dir, feature_dirs)
+        registry[tid] = _md_path(output_dir, tid.name)
+
+    return registry
+
+
+def resolve_output_path(
+    identity: TypeIdentity,
+    registry: dict[TypeIdentity, PurePosixPath] | None,
+) -> PurePosixPath:
+    """Look up a type's output path from the registry, with flat-file fallback."""
+    if registry is not None and identity in registry:
+        return registry[identity]
+    return _md_path(PurePosixPath(""), identity.name)
+
+
+def _aggregate_page_entries(
+    numeric_names: list[TypeIdentity],
+    geometry_names: list[TypeIdentity],
+) -> dict[TypeIdentity, PurePosixPath]:
+    """Pre-populate registry entries for types documented on aggregate pages."""
+    entries: dict[TypeIdentity, PurePosixPath] = dict.fromkeys(
+        numeric_names, NUMERIC_PAGE
+    )
+    entries.update(dict.fromkeys(geometry_names, GEOMETRIC_PAGE))
+    return entries
+
+
+def _nest_under_types(
+    output_dir: PurePosixPath, feature_dirs: set[PurePosixPath]
+) -> PurePosixPath:
+    """Insert `types/` after the feature directory portion.
+
+    If *output_dir* equals or is a subdirectory of a feature directory,
+    returns a path with `types/` inserted after the feature directory.
+    Otherwise returns *output_dir* unchanged.
+    """
+    for fd in sorted(feature_dirs, key=lambda p: len(p.parts), reverse=True):
+        try:
+            relative = output_dir.relative_to(fd)
+        except ValueError:
+            continue
+        return fd / "types" / relative
+    return output_dir
+
+
+def _md_path(directory: PurePosixPath, name: str) -> PurePosixPath:
+    """Build a .md file path from a directory and a PascalCase type name."""
+    return directory / f"{to_snake_case(name)}.md"

overture/schema/codegen/markdown/pipeline.py

@@ -0,0 +1,198 @@
+"""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 Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+import overture.schema.system.geometric as _system_geometric
+import overture.schema.system.numeric as _system_numeric
+from overture.schema.system.geometric import GeometryType
+
+from ..extraction.examples import ExampleRecord, load_examples
+from ..extraction.numeric_extraction import extract_numerics
+from ..extraction.specs import (
+    EnumSpec,
+    ModelSpec,
+    NewTypeSpec,
+    PydanticTypeSpec,
+    RecordSpec,
+    SupplementarySpec,
+    TypeIdentity,
+    UnionSpec,
+)
+from ..extraction.type_analyzer import is_newtype
+from ..layout.type_collection import collect_all_supplementary_types
+from .link_computation import LinkContext
+from .path_assignment import (
+    GEOMETRIC_PAGE,
+    NUMERIC_PAGE,
+    build_placement_registry,
+    resolve_output_path,
+)
+from .renderer import (
+    render_enum,
+    render_geometry_from_values,
+    render_model,
+    render_newtype,
+    render_numeric_from_specs,
+    render_pydantic_type,
+)
+from .reverse_references import UsedByEntry, compute_reverse_references
+
+__all__ = [
+    "RenderedPage",
+    "generate_markdown_pages",
+    "partition_numeric_and_geometry_types",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RenderedPage:
+    """A rendered page with its content and output path."""
+
+    content: str
+    path: PurePosixPath
+    is_model: bool = False
+
+
+def _load_model_examples(
+    spec: ModelSpec,
+) -> 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(
+    tid: TypeIdentity,
+    spec: SupplementarySpec,
+    registry: dict[TypeIdentity, PurePosixPath],
+    reverse_refs: dict[TypeIdentity, list[UsedByEntry]],
+) -> RenderedPage:
+    """Render a single supplementary type page."""
+    output_path = resolve_output_path(tid, registry)
+    ctx = LinkContext(output_path, registry)
+    used_by = reverse_refs.get(tid)
+
+    match spec:
+        case EnumSpec():
+            content = render_enum(spec, link_ctx=ctx, used_by=used_by)
+        case NewTypeSpec():
+            content = render_newtype(spec, ctx, used_by=used_by)
+        case RecordSpec():
+            content = render_model(spec, ctx, used_by=used_by)
+        case PydanticTypeSpec():
+            content = render_pydantic_type(spec, link_ctx=ctx, used_by=used_by)
+        case _:
+            raise TypeError(
+                f"Unhandled SupplementarySpec variant: {type(spec).__name__}"
+            )
+
+    return RenderedPage(content=content, path=output_path)
+
+
+def partition_numeric_and_geometry_types(
+    numeric_module: object,
+    geometric_module: object,
+) -> tuple[list[TypeIdentity], list[TypeIdentity]]:
+    """Discover numeric and geometry types from their source modules' exports.
+
+    NewType exports of *numeric_module* are numeric types.
+    Non-constraint class/enum exports of *geometric_module* are geometry types.
+    """
+    numerics: list[TypeIdentity] = []
+    for name in getattr(numeric_module, "__all__", []):
+        obj = getattr(numeric_module, name)
+        if is_newtype(obj):
+            numerics.append(TypeIdentity(obj, name))
+
+    geometries: list[TypeIdentity] = []
+    for name in getattr(geometric_module, "__all__", []):
+        obj = getattr(geometric_module, name)
+        if isinstance(obj, type) and not name.endswith("Constraint"):
+            geometries.append(TypeIdentity(obj, name))
+
+    return numerics, geometries
+
+
+def generate_markdown_pages(
+    model_specs: Sequence[ModelSpec],
+    schema_root: str,
+    *,
+    external_specs: Mapping[TypeIdentity, SupplementarySpec] | None = None,
+) -> 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).
+
+    `external_specs` are supplementary types documented on their own but not
+    reachable by walking feature field trees -- a `RootModel` entry point,
+    which serializes as its bare root value and so appears in no feature as
+    a named reference. They join the collected supplementary types and
+    render, place, and cross-reference identically.
+    """
+    numeric_names, geometry_names = partition_numeric_and_geometry_types(
+        _system_numeric, _system_geometric
+    )
+    all_specs = collect_all_supplementary_types(model_specs)
+    if external_specs:
+        all_specs = {**all_specs, **external_specs}
+    registry = build_placement_registry(
+        model_specs, all_specs, numeric_names, geometry_names, schema_root
+    )
+
+    reverse_refs = compute_reverse_references(model_specs, all_specs)
+
+    pages: list[RenderedPage] = []
+
+    for spec in model_specs:
+        output_path = registry[spec.identity]
+        ctx = LinkContext(output_path, registry)
+        examples = _load_model_examples(spec)
+        used_by = reverse_refs.get(spec.identity)
+        content = render_model(spec, link_ctx=ctx, examples=examples, used_by=used_by)
+        pages.append(RenderedPage(content=content, path=output_path, is_model=True))
+
+    for tid, supp_spec in all_specs.items():
+        pages.append(_render_supplement(tid, supp_spec, registry, reverse_refs))
+
+    pages.append(
+        RenderedPage(
+            content=render_numeric_from_specs(extract_numerics(numeric_names)),
+            path=NUMERIC_PAGE,
+        )
+    )
+
+    pages.append(
+        RenderedPage(
+            content=render_geometry_from_values([m.value for m in GeometryType]),
+            path=GEOMETRIC_PAGE,
+        )
+    )
+
+    return pages