fix(codegen): render list[NewType] as list<NewType>

list[PhoneNumber] rendered as "PhoneNumber (list)" — implying
PhoneNumber itself is a list type. The root cause: format_type
couldn't distinguish list layers outside a NewType from list layers
inside one.

Add newtype_outer_list_depth to TypeInfo, snapshotted from list_depth
when the type analyzer enters the first NewType. The renderer uses
this to choose list<X> syntax (list wraps the NewType) vs a (list)
qualifier (NewType wraps a list internally). Non-NewType identities
(enums, models) continue using list<X>.

Author: mojodna

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

@@ -125,9 +125,10 @@ layers in a fixed order, accumulating information into an `_UnwrapState`:
 
 The result is `TypeInfo` -- a flat dataclass that fully describes the unwrapped type:
 classification (`TypeKind`), optional/dict flags, `list_depth` (count of `list[...]`
-layers), accumulated constraints with provenance, NewType names, source type, literal
-values, and (for UNION kind) the tuple of concrete `BaseModel` member types. Dict types carry recursively analyzed `TypeInfo`
-for their key and value types.
+layers), `newtype_outer_list_depth` (list layers outside the outermost NewType boundary),
+accumulated constraints with provenance, NewType names, source type, literal values, and
+(for UNION kind) the tuple of concrete `BaseModel` member types. Dict types carry
+recursively analyzed `TypeInfo` for their key and value types.
 
 Multi-depth `Annotated` layers (common in practice, since NewTypes wrap `Annotated`
 types that wrap further NewTypes) are handled naturally by the loop -- each iteration

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

@@ -122,9 +122,11 @@ The function runs a single `while True` loop that peels layers in fixed order. E
 iteration handles one wrapper:
 
 **NewType** records names at two levels. The first NewType encountered becomes
-`outermost_newtype_name` (the user-facing identity, e.g. "FeatureVersion"). Subsequent
-NewTypes update `last_newtype_name` (the innermost, used for constraint provenance and
-as the terminal `base_type`). The loop unwraps via `__supertype__` and continues.
+`outermost_newtype_name` (the user-facing identity, e.g. "FeatureVersion") and snapshots
+the current `list_depth` into `newtype_outer_list_depth` -- capturing how many list
+layers appeared before the NewType boundary. Subsequent NewTypes update
+`last_newtype_name` (the innermost, used for constraint provenance and as the terminal
+`base_type`). The loop unwraps via `__supertype__` and continues.
 
 **Annotated** collects every metadata object as a `ConstraintSource`, tagging each with
 whichever NewType was most recently entered. This is how constraint provenance survives:
@@ -168,7 +170,8 @@ member separately.
 int32)` where `int32 = NewType("int32", Annotated[int, Field(ge=0, le=2147483647)])`.
 
 Iteration 1 sees `FeatureVersion`. It's a NewType -- record
-`outermost_newtype_name="FeatureVersion"`, unwrap to `int32`, continue. Iteration 2 sees
+`outermost_newtype_name="FeatureVersion"`, snapshot `newtype_outer_list_depth=0` (no list
+layers yet), unwrap to `int32`, continue. Iteration 2 sees
 `int32`. Also a NewType -- update `last_newtype_name="int32"`, unwrap to `Annotated[int,
 Field(ge=0, ...)]`, continue. Iteration 3 sees `Annotated`. Collect
 `ConstraintSource(source="int32", constraint=<Field metadata>)`, unwrap to `int`. The
@@ -185,10 +188,10 @@ rendering.
 ### _UnwrapState
 
 The accumulator dataclass carries state across iterations: optional/dict flags,
-`list_depth` (incremented per `list[...]` layer), the constraint list, both NewType name
-slots, and the captured description. Its
-`build_type_info` method assembles the final `TypeInfo` from accumulated state, freezing
-the constraint list into a tuple.
+`list_depth` (incremented per `list[...]` layer), `newtype_outer_list_depth` (snapshotted
+from `list_depth` when the first NewType is entered), the constraint list, both NewType
+name slots, and the captured description. Its `build_type_info` method assembles the
+final `TypeInfo` from accumulated state, freezing the constraint list into a tuple.
 
 ### walk_type_info
 
@@ -506,10 +509,16 @@ provenance rather than direct field reference.
 `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
 `_resolve_type_link`, which checks the `LinkContext` registry and falls back to plain
-code spans. Lists wrap `list_depth` times. Linked inner types use broken-backtick syntax
-(`` `list<` `` ... `` `>` ``) built as a single wrapper to avoid adjacent backticks that
-CommonMark would interpret as multi-backtick code span delimiters. Dict types render as `` `map<K, V>` ``. Qualifiers
-(optional, list, map) append in parentheses.
+code spans. For types with a linked identity (semantic NewTypes, enums, models), list
+rendering depends on where the list layers sit relative to the NewType boundary.
+`newtype_outer_list_depth > 0` means the list wraps the NewType (`list[PhoneNumber]`) and
+renders as `list<PhoneNumber>`. `is_list` with `newtype_name` set means the NewType
+wraps a list internally (`Sources` wrapping `list[SourceItem]`) and renders with a
+`(list)` qualifier. Non-NewType identities (enums, models) use `list<X>` syntax. Linked
+inner types use broken-backtick syntax (`` `list<` `` ... `` `>` ``) built as a single
+wrapper to avoid adjacent backticks that CommonMark would interpret as multi-backtick
+code span delimiters. Dict types render as `` `map<K, V>` ``. Qualifiers (optional, list,
+map) append in parentheses.
 
 Union members format independently -- each gets its own link resolution, joined with
 pipe separators escaped for table-cell safety.

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

@@ -143,11 +143,21 @@ def format_type(
             display = f"`{format_dict_type(ti)}`"
     elif identity:
         display = resolve_type_link(identity, ctx)
-        if ti.is_list and identity.name == ti.newtype_name:
+        # List layers outside a NewType wrap with list<> syntax (e.g., list[PhoneNumber]
+        # renders as list<PhoneNumber>). List layers inside a NewType use a (list)
+        # qualifier instead (e.g., Sources wrapping list[SourceItem] renders as
+        # Sources (list)), since the list-ness is an implementation detail of the type.
+        if ti.newtype_outer_list_depth > 0:
+            assert ti.is_list  # outer list layers are a subset of total list layers
+            display = _wrap_list_n(display, ti.newtype_outer_list_depth)
+        elif ti.is_list and ti.newtype_name is not None:  # list is inside the NewType
             qualifiers.append("list")
         elif ti.is_list:
             display = _wrap_list_n(display, ti.list_depth)
     else:
+        # Fallback: types without a linked identity. Registered primitives (int32,
+        # Geometry) and Pydantic types (HttpUrl) may still link to aggregate pages
+        # via the placement registry. Unregistered primitives render as plain code.
         base = resolve_type_name(ti, "markdown")
         link = _try_primitive_link(ti, base, ctx)
         if link and ti.is_list:

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

@@ -57,6 +57,7 @@ class TypeInfo:
     kind: TypeKind
     is_optional: bool = False
     list_depth: int = 0
+    newtype_outer_list_depth: int = 0
     is_dict: bool = False
     dict_key_type: TypeInfo | None = None
     dict_value_type: TypeInfo | None = None
@@ -113,10 +114,13 @@ class _UnwrapState:
       as the resolved ``base_type`` for the terminal type.
     - ``last_newtype_ref``: the most recently entered NewType callable,
       used as constraint provenance (which NewType contributed each constraint).
+    - ``newtype_outer_list_depth``: list layers accumulated before entering
+      the outermost NewType boundary.
     """
 
     is_optional: bool = False
     list_depth: int = 0
+    newtype_outer_list_depth: int = 0
     is_dict: bool = False
     dict_key_type: TypeInfo | None = None
     dict_value_type: TypeInfo | None = None
@@ -146,6 +150,7 @@ def build_type_info(
             kind=kind,
             is_optional=self.is_optional,
             list_depth=self.list_depth,
+            newtype_outer_list_depth=self.newtype_outer_list_depth,
             is_dict=self.is_dict,
             dict_key_type=self.dict_key_type,
             dict_value_type=self.dict_value_type,
@@ -176,6 +181,7 @@ def analyze_type(annotation: object) -> TypeInfo:
             state.last_newtype_name = name
             state.last_newtype_ref = annotation
             if state.outermost_newtype_name is None:
+                state.newtype_outer_list_depth = state.list_depth
                 state.outermost_newtype_name = name
                 state.outermost_newtype_ref = annotation
             annotation = annotation.__supertype__  # type: ignore[attr-defined]

packages/overture-schema-codegen/tests/test_markdown_type_format.py

@@ -29,38 +29,33 @@ class TestFormatType:
 
     def test_plain_str_renders_as_string(self) -> None:
         ti = analyze_type(str)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        assert format_type(field) == "`string`"
+        assert format_type(_make_field(ti)) == "`string`"
 
     def test_optional_adds_qualifier(self) -> None:
         ti = analyze_type(str | None)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=False)
-        assert format_type(field) == "`string` (optional)"
+        assert format_type(_make_field(ti, is_required=False)) == "`string` (optional)"
 
     def test_literal_renders_as_quoted_value(self) -> None:
         ti = analyze_type(Literal["places"])
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        assert format_type(field) == '`"places"`'
+        assert format_type(_make_field(ti)) == '`"places"`'
 
     def test_multi_value_literal_renders_comma_separated(self) -> None:
         ti = analyze_type(Literal["a", "b", "c"])
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        assert format_type(field) == '`"a"` \\| `"b"` \\| `"c"`'
+        assert format_type(_make_field(ti)) == '`"a"` \\| `"b"` \\| `"c"`'
 
     def test_enum_without_context_renders_as_code(self) -> None:
         class Color(str, Enum):
             RED = "red"
 
         ti = analyze_type(Color)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        assert format_type(field) == "`Color`"
+        assert format_type(_make_field(ti)) == "`Color`"
 
     def test_enum_with_link_context(self) -> None:
         class Color(str, Enum):
             RED = "red"
 
         ti = analyze_type(Color)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
+        field = _make_field(ti)
         ctx = LinkContext(
             page_path=PurePosixPath("buildings/building/building.md"),
             registry={
@@ -71,18 +66,15 @@ class Color(str, Enum):
 
     def test_list_of_primitives(self) -> None:
         ti = analyze_type(list[str])
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        assert format_type(field) == "`list<string>`"
+        assert format_type(_make_field(ti)) == "`list<string>`"
 
     def test_nested_list_of_primitives(self) -> None:
         ti = analyze_type(list[list[str]])
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        assert format_type(field) == "`list<list<string>>`"
+        assert format_type(_make_field(ti)) == "`list<list<string>>`"
 
     def test_registered_primitive_not_linked(self) -> None:
         ti = analyze_type(int32)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
-        result = format_type(field)
+        result = format_type(_make_field(ti))
         assert result == "`int32`"
         assert "](int32.md)" not in result
 
@@ -102,17 +94,19 @@ def test_dict_with_newtype_shows_semantic_name(self) -> None:
         assert result == "map<MyKey, int64>"
 
 
-def _make_union_field(ti: TypeInfo, *, is_required: bool = True) -> FieldSpec:
-    """Build a FieldSpec wrapping a union TypeInfo for test convenience."""
-    return FieldSpec(name="x", type_info=ti, description=None, is_required=is_required)
+def _make_field(
+    ti: TypeInfo, *, name: str = "x", is_required: bool = True
+) -> FieldSpec:
+    """Build a FieldSpec for test convenience."""
+    return FieldSpec(name=name, type_info=ti, description=None, is_required=is_required)
 
 
 class TestFormatUnionType:
     """Tests for UNION-kind TypeInfo in format_type."""
 
     def test_union_renders_all_members(self) -> None:
         ti = analyze_type(_ModelA | _ModelB)
-        result = format_type(_make_union_field(ti))
+        result = format_type(_make_field(ti))
         assert "`_ModelA`" in result
         assert "`_ModelB`" in result
         # Pipe separator escaped for table cells
@@ -131,13 +125,13 @@ def test_union_with_link_context_links_each_member(self) -> None:
                 ),
             },
         )
-        result = format_type(_make_union_field(ti), ctx)
+        result = format_type(_make_field(ti), ctx)
         assert "[`_ModelA`](types/model_a.md)" in result
         assert "[`_ModelB`](types/model_b.md)" in result
 
     def test_optional_union_adds_qualifier(self) -> None:
         ti = analyze_type(_ModelA | _ModelB | None)
-        result = format_type(_make_union_field(ti, is_required=False))
+        result = format_type(_make_field(ti, is_required=False))
         assert "(optional)" in result
         assert "`_ModelA`" in result
         assert "`_ModelB`" in result
@@ -149,14 +143,14 @@ def test_list_of_union_adds_qualifier(self) -> None:
             list_depth=1,
             union_members=(_ModelA, _ModelB),
         )
-        result = format_type(_make_union_field(ti))
+        result = format_type(_make_field(ti))
         assert "(list)" in result
         assert "`_ModelA`" in result
         assert "`_ModelB`" in result
 
     def test_union_members_unlinked_without_context(self) -> None:
         ti = analyze_type(_ModelA | _ModelB)
-        result = format_type(_make_union_field(ti))
+        result = format_type(_make_field(ti))
         # No markdown links without context
         assert "]()" not in result
         assert "[`" not in result
@@ -172,7 +166,7 @@ def test_union_partial_links(self) -> None:
                 )
             },
         )
-        result = format_type(_make_union_field(ti), ctx)
+        result = format_type(_make_field(ti), ctx)
         assert "[`_ModelA`](types/model_a.md)" in result
         assert "`_ModelB`" in result
         # _ModelB should NOT be linked
@@ -184,7 +178,7 @@ class TestPydanticTypeLinking:
 
     def test_pydantic_type_linked_when_in_registry(self) -> None:
         ti = analyze_type(HttpUrl)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
+        field = _make_field(ti)
         ctx = LinkContext(
             page_path=PurePosixPath("places/place/place.md"),
             registry={
@@ -199,7 +193,7 @@ def test_pydantic_type_linked_when_in_registry(self) -> None:
 
     def test_pydantic_type_unlinked_without_registry_entry(self) -> None:
         ti = analyze_type(HttpUrl)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
+        field = _make_field(ti)
         ctx = LinkContext(
             page_path=PurePosixPath("places/place/place.md"),
             registry={},
@@ -210,7 +204,7 @@ def test_pydantic_type_unlinked_without_registry_entry(self) -> None:
 
     def test_list_of_pydantic_type_linked(self) -> None:
         ti = analyze_type(list[HttpUrl])
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
+        field = _make_field(ti)
         ctx = LinkContext(
             page_path=PurePosixPath("places/place/place.md"),
             registry={
@@ -226,7 +220,7 @@ def test_list_of_pydantic_type_linked(self) -> None:
     def test_registered_primitive_links_to_aggregate_page(self) -> None:
         """int32 links to the primitives aggregate page when in registry."""
         ti = analyze_type(int32)
-        field = FieldSpec(name="x", type_info=ti, description=None, is_required=True)
+        field = _make_field(ti)
         ctx = LinkContext(
             page_path=PurePosixPath("places/place/place.md"),
             registry={
@@ -240,6 +234,59 @@ def test_registered_primitive_links_to_aggregate_page(self) -> None:
         assert "system/primitive/primitives.md" in result
 
 
+class TestListOfSemanticNewtype:
+    """Tests for list[SemanticNewType] rendering.
+
+    When a scalar NewType appears inside list[], the type renders as
+    list<NewTypeName> rather than NewTypeName (list). The (list) qualifier
+    is reserved for NewTypes that internally wrap a list.
+    """
+
+    def test_list_of_scalar_newtype_renders_list_syntax(self) -> None:
+        """list[ScalarNewType] renders as list<Name>, not Name (list)."""
+        ScalarNT = NewType("ScalarNT", str)
+        ti = analyze_type(list[ScalarNT])
+        result = format_type(_make_field(ti))
+        assert "list<" in result
+        assert "ScalarNT" in result
+        assert "(list)" not in result
+
+    def test_newtype_wrapping_list_renders_qualifier(self) -> None:
+        """NewType wrapping list[X] renders as Name (list)."""
+        ListNT = NewType("ListNT", list[str])
+        ti = analyze_type(ListNT)
+        result = format_type(_make_field(ti))
+        assert "(list)" in result
+        assert "ListNT" in result
+
+    def test_list_of_scalar_newtype_with_link(self) -> None:
+        """list[ScalarNewType] with link context renders linked list<Name>."""
+        ScalarNT = NewType("ScalarNT", str)
+        ti = analyze_type(list[ScalarNT])
+        field = _make_field(ti)
+        ctx = LinkContext(
+            page_path=PurePosixPath("places/place/place.md"),
+            registry={
+                TypeIdentity(ScalarNT, "ScalarNT"): PurePosixPath("system/scalar_nt.md")
+            },
+        )
+        result = format_type(field, ctx)
+        assert "list<" in result
+        assert "ScalarNT" in result
+        assert "system/scalar_nt.md" in result
+        assert "(list)" not in result
+
+    def test_nested_list_of_scalar_newtype_renders_nested_list_syntax(self) -> None:
+        """list[list[ScalarNewType]] renders as list<list<Name>>."""
+        ScalarNT = NewType("ScalarNT", str)
+        ti = analyze_type(list[list[ScalarNT]])
+        result = format_type(_make_field(ti))
+        assert "list<" in result
+        assert "list<`" in result or "`list<list<" in result
+        assert "ScalarNT" in result
+        assert "(list)" not in result
+
+
 class TestFormatUnderlyingUnionType:
     """Tests for UNION-kind TypeInfo in format_underlying_type."""