refactor(codegen): reorganize flat layout into sub-packages

Move modules into three sub-packages matching the architecture layers:

- extraction/ (14 modules): type analysis, specs, extractors, constraints
- layout/ (2 modules): module layout, type collection
- markdown/ (6 modules + templates): pipeline, renderer, type formatting,
  links, paths, reverse references

Three modules renamed to drop redundant prefixes:
  field_constraint_description → extraction/field_constraints
  model_constraint_description → extraction/model_constraints
  example_loader → extraction/examples

Templates flattened from templates/markdown/ to markdown/templates/.

Author: sethfitz

packages/overture-schema-codegen/README.md

@@ -67,13 +67,13 @@ module structure. Link computation and reverse references enable cross-page navi
 Jinja2 templates for feature pages (with field tables, constraint sections, and
 examples), enum pages, NewType pages, and aggregate primitive/geometry reference pages.
 
-`markdown_pipeline.py` orchestrates the full pipeline without I/O, returning
+`markdown/pipeline.py` orchestrates the full pipeline without I/O, returning
 `list[RenderedPage]`. The CLI writes files to disk with Docusaurus frontmatter.
 
 ## Programmatic use
 
 ```python
-from overture.schema.codegen.type_analyzer import analyze_type, TypeKind
+from overture.schema.codegen.extraction.type_analyzer import analyze_type, TypeKind
 
 info = analyze_type(some_annotation)
 assert info.kind == TypeKind.PRIMITIVE

packages/overture-schema-codegen/docs/design.md

@@ -60,7 +60,7 @@ Extraction           TypeInfo, FieldSpec, ModelSpec, EnumSpec, ...
 Discovery            discover_models() from overture-schema-core
 ```
 
-`markdown_pipeline.py` orchestrates the pipeline without I/O: it expands feature trees,
+`markdown/pipeline.py` orchestrates the pipeline without I/O: it expands feature trees,
 collects supplementary types, builds placement registries, computes reverse references,
 and calls renderers -- returning `RenderedPage` objects. The CLI (`cli.py`) is a thin
 Click wrapper that calls `generate_markdown_pages()` and writes files to disk.
@@ -74,26 +74,26 @@ graph TD
     DM -->|"dict[ModelKey, type]"| EX
 
     subgraph Extraction
-        EX["type_analyzer / extractors"]
+        EX["extraction/type_analyzer / extractors"]
         EX -->|"ModelSpec, UnionSpec"| TREE["expand_model_tree()"]
     end
 
     TREE -->|"FeatureSpec[]"| OL
 
     subgraph "Output Layout"
-        OL["type_collection"]
-        OL -->|"SupplementarySpec{}"| PA["path_assignment"]
-        PA -->|"dict[str, Path]"| LC["link_computation"]
-        RR["reverse_references"]
+        OL["layout/type_collection"]
+        OL -->|"SupplementarySpec{}"| PA["markdown/path_assignment"]
+        PA -->|"dict[str, Path]"| LC["markdown/link_computation"]
+        RR["markdown/reverse_references"]
     end
 
     subgraph Rendering
-        R["markdown_renderer"]
-        TR["type_registry"] -.->|"type name resolution"| R
+        R["markdown/renderer"]
+        TR["extraction/type_registry"] -.->|"type name resolution"| R
     end
 
     subgraph Orchestration
-        MP["markdown_pipeline"]
+        MP["markdown/pipeline"]
     end
 
     OL --> MP
@@ -139,12 +139,12 @@ NewType active at that depth.
 
 Extraction is split by entity kind:
 
-- `model_extraction.py`: Pydantic model -> `ModelSpec` (fields in MRO-aware
+- `extraction/model_extraction.py`: Pydantic model -> `ModelSpec` (fields in MRO-aware
   documentation order, alias-resolved names, model-level constraints)
-- `enum_extraction.py`: Enum class -> `EnumSpec`
-- `newtype_extraction.py`: NewType -> `NewTypeSpec`
-- `union_extraction.py`: Discriminated union alias -> `UnionSpec`
-- `primitive_extraction.py`: Numeric primitives -> `PrimitiveSpec`
+- `extraction/enum_extraction.py`: Enum class -> `EnumSpec`
+- `extraction/newtype_extraction.py`: NewType -> `NewTypeSpec`
+- `extraction/union_extraction.py`: Discriminated union alias -> `UnionSpec`
+- `extraction/primitive_extraction.py`: Numeric primitives -> `PrimitiveSpec`
 
 Each calls `analyze_type()` for field types. Tree expansion (`expand_model_tree()`)
 walks MODEL-kind fields to populate nested model references, with a shared cache and
@@ -212,7 +212,7 @@ syntax. Extraction and the type registry carry no presentation logic.
 
 ### Type registry
 
-`type_registry.py` maps type names to per-target string representations via
+`extraction/type_registry.py` maps type names to per-target string representations via
 `TypeMapping`. `format_type_string()` wraps the resolved name with list/optional
 qualifiers. `is_semantic_newtype()` distinguishes NewTypes that deserve their own
 identity (like `FeatureVersion` wrapping `int32`) from pass-through aliases to
@@ -223,12 +223,12 @@ registered primitives.
 Jinja2 templates for feature, enum, NewType, primitives, and geometry pages.
 `render_feature()` expands MODEL-kind fields inline with dot-notation (e.g.,
 `sources[].dataset`), stopping at cycle boundaries. `format_type()` in
-`markdown_type_format.py` converts `TypeInfo` into link-aware display strings using
+`markdown/type_format.py` converts `TypeInfo` into link-aware display strings using
 `LinkContext`.
 
 ### Constraint prose
 
-`field_constraint_description.py` and `model_constraint_description.py` convert
+`extraction/field_constraints.py` and `extraction/model_constraints.py` convert
 constraint objects into human-readable descriptions. Field constraints produce inline
 text. Model constraints produce section-level descriptions and per-field notes, with
 consolidation for related conditional constraints (`require_if` / `forbid_if` grouped by
@@ -249,13 +249,13 @@ rather than being split into dot-notation rows. The pipeline computes `dict_path
 ## Extension Points
 
 **Adding a new output target** (Arrow schemas next, PySpark expressions after): Add a
-column to `TypeMapping` in `type_registry.py` for type-name resolution. Write a new
-renderer module that consumes specs and the type registry. The extraction layer and
+column to `TypeMapping` in `extraction/type_registry.py` for type-name resolution. Write
+a new renderer module that consumes specs and the type registry. The extraction layer and
 output layout are target-independent.
 
-**Adding a new type kind**: Add a variant to `TypeKind` in `type_analyzer.py`. Handle it
-in the terminal classification of `analyze_type()`. Add an extraction function and spec
-dataclass if needed. Update renderers to handle the new kind.
+**Adding a new type kind**: Add a variant to `TypeKind` in `extraction/type_analyzer.py`.
+Handle it in the terminal classification of `analyze_type()`. Add an extraction function
+and spec dataclass if needed. Update renderers to handle the new kind.
 
 **Adding a new constraint type**: The iterative unwrapper collects it automatically (any
 `Annotated` metadata becomes a `ConstraintSource`). Add a case to

packages/overture-schema-codegen/docs/walkthrough.md

@@ -71,7 +71,7 @@ unions. From that point forward both model features and union features satisfy t
 
 Two modules with no internal dependencies. Both serve multiple layers.
 
-### case_conversion.py
+### extraction/case_conversion.py
 
 Converts PascalCase to snake_case with two compiled regexes. `_ACRONYM_BOUNDARY` inserts
 an underscore between an uppercase run and a capitalized word start: `HTMLParser`
@@ -87,7 +87,7 @@ the system passes through this function.
 'hex_color.md'
 ```
 
-### docstring.py
+### extraction/docstring.py
 
 Distinguishes author-written docstrings from auto-generated ones. Both `Enum` and
 `NewType` produce default docstrings that vary across Python versions. Rather than
@@ -202,7 +202,7 @@ handle them directly.
 
 ## 4. Data structures
 
-`specs.py` defines the vocabulary shared between extraction and rendering. Every spec is
+`extraction/specs.py` defines the vocabulary shared between extraction and rendering. Every spec is
 a dataclass with no methods beyond field access and, in `UnionSpec`'s case, one cached
 property.
 
@@ -240,7 +240,7 @@ individual ones.
 
 ### Classification functions
 
-Three functions at the bottom of `specs.py` classify discovery results. `is_model_class`
+Three functions at the bottom of `extraction/specs.py` classify discovery results. `is_model_class`
 is a `TypeGuard` that checks `isinstance(obj, type) and issubclass(obj, BaseModel)`.
 `is_union_alias` calls `analyze_type` and checks for `UNION` kind -- the only place
 outside the type analyzer that touches Python type annotations. `filter_model_classes`
@@ -377,7 +377,7 @@ Two modules convert constraint objects into human-readable text.
 
 ### Field constraints
 
-`field_constraint_description.py` pattern-matches constraint types. `Interval` renders
+`extraction/field_constraints.py` pattern-matches constraint types. `Interval` renders
 as `lower <= x <= upper` using Unicode comparison operators. Single-bound constraints
 (`Ge`, `Gt`, `Le`, `Lt`) render as `>= value` or `< value`. Length constraints
 (`MinLen`, `MaxLen`) render as plain prose (e.g. "Minimum length: 1"). `GeometryTypeConstraint` lists
@@ -396,7 +396,7 @@ docstring, class name, and pattern. Otherwise it delegates to
 
 ### Model constraints
 
-`model_constraint_description.py` handles model-level constraints from decorators.
+`extraction/model_constraints.py` handles model-level constraints from decorators.
 `analyze_model_constraints` returns two things in one pass: a list of section-level
 descriptions and a dict mapping field names to the constraint descriptions that
 reference them.
@@ -504,7 +504,7 @@ provenance rather than direct field reference.
 
 ## 13. Markdown type formatting
 
-`markdown_type_format.py` converts `TypeInfo` into display strings for markdown output.
+`markdown/type_format.py` converts `TypeInfo` into display strings for markdown output.
 
 `format_type` handles the full range of field types. Single-value Literals render as
 `"value"` in backticks. Semantic NewTypes and enums/models get markdown links via
@@ -530,11 +530,11 @@ function uses `source_type.__name__` rather than `base_type` for link resolution
 
 ## 14. Markdown rendering
 
-`markdown_renderer.py` is the template driver.
+`markdown/renderer.py` is the template driver.
 
 ### Templates
 
-Six Jinja2 templates in `templates/markdown/`. `feature.md.jinja2` renders a field table
+Six Jinja2 templates in `markdown/templates/`. `feature.md.jinja2` renders a field table
 with Name, Type, and Description columns, an optional Constraints section, an optional
 Examples section, and a "Used By" partial. `enum.md.jinja2` renders a bullet list of
 values. `newtype.md.jinja2` shows underlying type and constraints with provenance links.
@@ -629,7 +629,7 @@ skip rather than failing the pipeline.
 
 ### The pipeline
 
-`generate_markdown_pages` in `markdown_pipeline.py` is the "main" function. It takes
+`generate_markdown_pages` in `markdown/pipeline.py` is the "main" function. It takes
 feature specs and a schema root, returns rendered pages without touching the filesystem.
 Eight steps:
 

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

@@ -8,20 +8,20 @@
 
 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 (
+from .extraction.model_extraction import extract_model
+from .extraction.specs import (
+    FeatureSpec,
+    is_model_class,
+    is_union_alias,
+)
+from .extraction.union_extraction import extract_union
+from .layout.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
+from .markdown.pipeline import generate_markdown_pages
 
 log = logging.getLogger(__name__)