winmd-inspect: nest metadata-nested value types into Swift nesting

Fold the flat closure emission into real Swift nesting, so a metadata-nested
value type emits as a nested type under its container chain and every signature
that names it resolves to that declaration. Disambiguating the names two reached
declarations would otherwise share is the next slice.

A metadata-nested value type emits as a real nested Swift type under its
enclosing-`TypeDef` container chain (`Outer.Inner`), and every signature that
names it spells the same dot-path, so the declaration and its uses agree and two
same-named nested types under different enclosers stay distinct. The walk emits
the enclosing value type too — even when only `Outer.Inner` is named and nothing
references `Outer` directly — so the container `Inner` nests inside actually
exists; a value type nests only when every enclosing level is an emitted
value-type container (`struct`/`enum`), else it is a dropped frontier the
consumer defines (an enclosing `protocol` cannot nest a value type, an excluded
runtime `class` is not emitted). An interface or delegate is a Swift `protocol`,
which cannot nest, so a metadata-nested one is a dropped frontier and only a
top-level one is a legal root. The flat emission folds into a containment forest
whose roots render in the walk's post-order, so a dependency precedes the type
naming it and a top-level type keeps its position.

A custom struct/enum template may open with a header comment and append a
brace-delimited footer around its main declaration; the child block is spliced
before the *main declaration's* closing brace — matched by a brace-depth count
over the body's *code* (braces inside a `//` or `/* */` comment or a single- or
triple-quoted string literal are skipped, the block-comment and multiline-string
states held across lines), from the first code `{` — not the last brace-only
line, so the child nests inside the container rather than above the declaration
(a header comment's or a multiline literal's braces) or into the footer (the
last brace).

A nested type's enclosing dot-path strips the CLR arity suffix from every
component, not only the leaf, and the strip lives at the single escape seam,
before each component is keyword-escaped, so a storage spelling and a
directly-resolved one escape identically and a generic instantiation's base
(`` `protocol`<…> ``) composes without a second strip that would cut the escape
backtick. But a *generic* encloser has no valid unqualified spelling — a member
of `Outer`1` is `Outer<T>.Inner`, needing the enclosing specialization the
projection does not yet emit, which the arity-stripped `Outer.Inner` misbinds
if the consumer supplies the generic `Outer` — so a reference into a type nested
under a generic encloser is dropped as an unsupported frontier rather than
spelled uncompilable, resolved (like a `TypeSpec` or a null index) to nothing.

An interface whose base is a metadata-nested interface names that base through
the same enclosing dot-path (`Outer.IChild`) its own nested declaration and a
signature naming it both wear, so the refinement resolves rather than reading
the bare `TypeName`, which binds no visible declaration. The selected base is
resolved to its local definition through the same `requires` scope-chain walk
the closure uses, so a base named directly through an `Interface_TypeDef` and
one named through an `Interface_TypeRef` — whose nested references the walk
follows to the local nested definition — alike carry the enclosing path; the
`.render *` batch resolves a `TypeRef` base by the same recursion. Each path
component is keyword-escaped separately. A top-level or external base resolves
to no enclosing path and spells bare, as does a base a `-I` override names that
matches no local definition.

Integration tests cover two same-named nested value types each nested under its
encloser, an enclosing value type reached only through a nested member, a child
nested inside its container despite a header comment's braces, a trailing
footer, and a multiline string literal's braces, a reference into a type nested
under a generic encloser dropped as an unsupported frontier, a generic
instantiation whose
already-stripped keyword base keeps its escape, and a top-level interface whose
base is a nested interface — named through an `Interface_TypeDef`, and (resolved
by the scope-chain walk) through an `Interface_TypeRef` — spelled through its
enclosing path.

Author: compnerd

Sources/WinMD/Storage.swift

@@ -224,4 +224,319 @@ public struct Storage: ~Escapable {
     }
     return nil
   }
+
+  // MARK: - Nesting
+
+  /// The lexically enclosing type of the type `tuple` names — its immediate
+  /// encloser — or `nil` when the type is top-level.
+  ///
+  /// A `TypeRef` nests through its `ResolutionScope`: a scope that is itself a
+  /// `TypeRef` is the enclosing reference, and any other scope (a `Module`, a
+  /// `ModuleRef`, or an `AssemblyRef`) makes the reference top-level. A
+  /// `TypeDef` nests through the `NestedClass` table (§II.22.32) — the
+  /// `EnclosingClass` of the row whose `NestedClass` names this definition,
+  /// found by binary search when the table is stored sorted on its key and by a
+  /// linear scan otherwise. Any other table has no enclosing and yields `nil`.
+  /// It is `package` so the synthesis decode and the render adapter compose one
+  /// nested type's dot-path from the same walk.
+  @_lifetime(copy self)
+  package func enclosing(_ tuple: borrowing Tuple)
+      throws(WinMDError) -> Tuple? {
+    // The enclosing tuple is opened off `self` (not off the borrowed `tuple`)
+    // so its lifetime tracks the storage rather than the shorter-lived
+    // argument, which is what a recursive walk returns through.
+    switch tuple.table.number {
+    case Metadata.Tables.TypeRef.number:
+      guard let scope = tuple.ordinal(for: "ResolutionScope") else {
+        return nil
+      }
+      // Tag 3 of `ResolutionScope` selects `TypeRef`: a scope that is itself a
+      // `TypeRef` is the enclosing reference; a `Module`/`ModuleRef`/
+      // `AssemblyRef` scope makes the reference top-level.
+      let coded = ResolutionScope(rawValue: tuple[scope])
+      guard coded.tag == 3, coded.row != 0 else { return nil }
+      return try self.tuple(coded.row - 1,
+                            of: Metadata.Tables.TypeRef.self)
+    case Metadata.Tables.TypeDef.number:
+      guard let table = opened(Metadata.Tables.NestedClass.number) else {
+        return nil
+      }
+      // The `NestedClass` (ordinal 0) column holds the 1-based `TypeDef` Id of
+      // the nested type; `EnclosingClass` (ordinal 1) its encloser.
+      let child = tuple.row + 1
+      let count = Int(table.rows)
+      if sorted & (1 << Metadata.Tables.NestedClass.number) != 0 {
+        let lower = bound(table, 0, child, count, strict: false)
+        guard lower < count, Tuple(lower, table, self)[0] == child else {
+          return nil
+        }
+        return try self.tuple(Tuple(lower, table, self)[1] - 1,
+                              of: Metadata.Tables.TypeDef.self)
+      }
+      for index in 0 ..< count where Tuple(index, table, self)[0] == child {
+        return try self.tuple(Tuple(index, table, self)[1] - 1,
+                              of: Metadata.Tables.TypeDef.self)
+      }
+      return nil
+    default:
+      return nil
+    }
+  }
+
+  /// The dot-path name of the type `tuple` names, from its outermost encloser —
+  /// `Foo.Bar` for a `Bar` nested under `Foo`, `Foo.Bar.Baz` for a deeper
+  /// nesting — or the bare `TypeName` for a top-level type.
+  ///
+  /// The components are joined raw (unescaped); a caller that spells the path
+  /// as target source escapes each component separately, so a keyword component
+  /// is delimited within the path rather than treated as one identifier.
+  package func qualified(_ tuple: borrowing Tuple)
+      throws(WinMDError) -> String {
+    // Each component is a declaration name spelled arity-stripped: a generic
+    // encloser `Outer``1` nests as `Outer` and the generic decode strips the
+    // leaf, so strip every component of the enclosing path here — a signature
+    // spelling `Outer.Inner`, not the unresolved `Outer``1.Inner`. The suffix
+    // marks only a generic definition, which is never a `known` bridge or
+    // `System.Guid` (both non-generic), so the identity this feeds still
+    // matches those lookups, and a top-level component is already projected at
+    // the seam that qualifies it.
+    let name = try projected(bare(tuple))
+    guard let outer = try enclosing(tuple) else { return name }
+    return try qualified(outer) + "." + name
+  }
+
+  /// Whether any *enclosing* type of `tuple` is generic — its raw `TypeName`
+  /// carries the CLR arity suffix (a backtick). Such a nesting has no valid
+  /// unqualified spelling: a member of `Outer``1` is `Outer<T>.Inner`, which
+  /// needs the enclosing specialization, while both `qualified`'s arity-stripped
+  /// `Outer.Inner` and appending the generic arguments to the leaf misname it.
+  /// Projecting the WinRT generic-nesting specialization is a deferred redesign,
+  /// so a reference into such a type is an unsupported frontier the caller drops
+  /// rather than spelling. Only an *encloser*'s arity matters: the leaf's own
+  /// generic arity is stripped and supplied by the decode's own clause.
+  package func enclosedByGeneric(_ tuple: borrowing Tuple)
+      throws(WinMDError) -> Bool {
+    guard let outer = try enclosing(tuple) else { return false }
+    if try bare(outer).contains("`") { return true }
+    return try enclosedByGeneric(outer)
+  }
+
+  /// The dot-path name of the `TypeDef` at 1-based `id` — the `qualified`
+  /// spelling addressed by `Id` rather than by an already-fetched `Tuple`, for
+  /// a caller (the render's inheritance clause) that holds only the resolved
+  /// base `Id`. A missing row spells empty, the same absent-name the caller's
+  /// bare fallback would.
+  package func qualified(of id: Int) throws(WinMDError) -> String {
+    guard let tuple = try self.tuple(id - 1, of: Metadata.Tables.TypeDef.self)
+    else {
+      return ""
+    }
+    return try qualified(tuple)
+  }
+
+  /// The enclosing `TypeDef` chain of the `TypeDef` at 1-based `id`, outermost
+  /// first — each an `(id, name)` pair — for the render to group a nested type
+  /// under a container per level. An empty array for a top-level type.
+  package func nesting(of id: Int)
+      throws(WinMDError) -> Array<(id: Int, name: String)> {
+    guard let tuple = try self.tuple(id - 1, of: Metadata.Tables.TypeDef.self),
+        let outer = try enclosing(tuple) else {
+      return []
+    }
+    return try nesting(of: outer.row + 1) + [(outer.row + 1, bare(outer))]
+  }
+
+  // MARK: - Kind and qualification
+
+  /// The projection kind of a named type — how the render spells and nests it.
+  ///
+  /// The partition is the one the SQL `types` view draws: an `interface` (the
+  /// `tdInterface` flag), a `delegate`/`structure`/`enumeration` (told apart by
+  /// the base its `Extends` names — `System.MulticastDelegate`/`System.ValueType`
+  /// /`System.Enum`), or a runtime `class` (anything else). Only a `structure`
+  /// or `enumeration` is a value type, spelled fully namespace-qualified and
+  /// nested; the rest spell by their bare name.
+  package enum Kind: Sendable, Equatable {
+    case interface
+    case delegate
+    case structure
+    case enumeration
+    case `class`
+
+    /// Whether the kind is a value type — a `structure` or an `enumeration` —
+    /// the render namespace-qualifies and nests, as opposed to a `protocol`
+    /// (`interface`/`delegate`) or a runtime `class` it spells bare.
+    package var value: Bool {
+      self == .structure || self == .enumeration
+    }
+  }
+
+  /// The projection kind of the `TypeDef` the `tuple` names, classified exactly
+  /// as the SQL `types` view does so the decode spelling and the emit nesting
+  /// agree from one source.
+  ///
+  /// The `tdInterface` flag (`0x20`) marks an interface regardless of its base;
+  /// otherwise the base type the `Extends` coded index names classifies the row
+  /// — `System.Enum` an enumeration, `System.MulticastDelegate` a delegate,
+  /// `System.ValueType` a structure, anything else (or no base) a runtime class.
+  package func kind(_ tuple: borrowing Tuple) throws(WinMDError) -> Kind {
+    if let flags = tuple.ordinal(for: "Flags"), tuple[flags] & 0x20 == 0x20 {
+      return .interface
+    }
+    guard let extends = tuple.ordinal(for: "Extends") else { return .class }
+    let base = TypeDefOrRef(rawValue: tuple[extends])
+    guard let parent = try resolve(base) else { return .class }
+    switch try names(parent) {
+    case ("System", "Enum"):              return .enumeration
+    case ("System", "MulticastDelegate"): return .delegate
+    case ("System", "ValueType"):         return .structure
+    default:                              return .class
+    }
+  }
+
+  /// The outermost encloser of the type `tuple` names — the top of its nesting
+  /// chain, itself when top-level — reached by climbing `enclosing`. The result
+  /// is opened off `self`, so its lifetime tracks the storage.
+  @_lifetime(copy self)
+  private func outermost(_ tuple: borrowing Tuple)
+      throws(WinMDError) -> Tuple {
+    guard let up = try enclosing(tuple) else {
+      return Tuple(tuple.row, tuple.table, self)
+    }
+    return try outermost(up)
+  }
+
+  /// The local `TypeDef` the named type `reference` resolves to, or `nil` when
+  /// it names no local definition.
+  ///
+  /// A `TypeDef` reference already names a local definition. A `TypeRef` resolves
+  /// through its `ResolutionScope` chain — a module-scoped reference to the
+  /// non-nested `TypeDef` of the same (namespace, name), a `TypeRef`-scoped
+  /// (nested) reference to the nested `TypeDef` under the local definition its
+  /// enclosing reference resolves to — exactly the walk the render's `references`
+  /// CTE performs. A reference whose chain terminates at a `ModuleRef` or
+  /// `AssemblyRef` (an external assembly) resolves to nothing; a `TypeSpec`
+  /// names no definition.
+  @_lifetime(copy self)
+  package func definition(of reference: TypeDefOrRef)
+      throws(WinMDError) -> Tuple? {
+    guard let tuple = try resolve(reference) else { return nil }
+    switch tuple.table.number {
+    case Metadata.Tables.TypeDef.number:
+      return tuple
+    case Metadata.Tables.TypeRef.number:
+      return try definition(reference: tuple)
+    default:
+      return nil
+    }
+  }
+
+  /// The local `TypeDef` the `TypeRef` `tuple` resolves to through its
+  /// `ResolutionScope` chain, or `nil` when the reference is external.
+  @_lifetime(copy self)
+  private func definition(reference tuple: borrowing Tuple)
+      throws(WinMDError) -> Tuple? {
+    guard let ordinal = tuple.ordinal(for: "ResolutionScope") else {
+      return nil
+    }
+    let scope = ResolutionScope(rawValue: tuple[ordinal])
+    let target = try names(tuple)
+    // A `TypeRef`-scoped (tag 3) reference is nested: resolve its enclosing
+    // reference to a local `TypeDef`, then match the nested `TypeDef` directly
+    // under it by `TypeName` — a nested type's namespace is empty, so the match
+    // is by name under the encloser, never by namespace.
+    if scope.tag == 3, scope.row != 0 {
+      guard let enclosing = try self.tuple(scope.row - 1,
+                                           of: Metadata.Tables.TypeRef.self),
+          let encloser = try definition(reference: enclosing) else {
+        return nil
+      }
+      return try nested(target.name, in: encloser.row + 1)
+    }
+    // A `Module`-scoped (tag 0) reference is local and top-level; any other
+    // scope — a `ModuleRef`/`AssemblyRef`, or a null scope — is external.
+    guard scope.tag == 0, scope.row != 0 else { return nil }
+    return try toplevel(target.namespace, target.name)
+  }
+
+  /// The non-nested local `TypeDef` named (`namespace`, `name`), or `nil` — the
+  /// anchor a module-scoped reference resolves to.
+  @_lifetime(copy self)
+  private func toplevel(_ namespace: String, _ name: String)
+      throws(WinMDError) -> Tuple? {
+    guard let table = opened(Metadata.Tables.TypeDef.number) else { return nil }
+    for row in 0 ..< Int(table.rows) {
+      let tuple = Tuple(row, table, self)
+      let (space, simple) = try names(tuple)
+      guard space == namespace, simple == name else { continue }
+      // A nested type shares a bare (namespace, name) with a top-level one only
+      // by coincidence, and the empty namespace collapses every nested type's
+      // pair — so the module-scoped reference names the non-nested definition.
+      switch try enclosing(tuple) {
+      case .none: return tuple
+      case .some: continue
+      }
+    }
+    return nil
+  }
+
+  /// The local nested `TypeDef` named `name` directly under the `TypeDef` at
+  /// 1-based `encloser` `Id`, or `nil` — the nested reference's resolution step.
+  @_lifetime(copy self)
+  private func nested(_ name: String, in encloser: Int)
+      throws(WinMDError) -> Tuple? {
+    guard let table = opened(Metadata.Tables.NestedClass.number) else {
+      return nil
+    }
+    // The `NestedClass` column (ordinal 0) is the nested `TypeDef` Id, the
+    // `EnclosingClass` column (ordinal 1) its encloser.
+    for index in 0 ..< Int(table.rows) {
+      let link = Tuple(index, table, self)
+      guard link[1] == encloser else { continue }
+      guard let child = try self.tuple(link[0] - 1,
+                                       of: Metadata.Tables.TypeDef.self) else {
+        continue
+      }
+      if try bare(child) == name { return child }
+    }
+    return nil
+  }
+
+  /// The bare `TypeName` of the type `tuple` names — the empty string when it
+  /// carries no such column.
+  private func bare(_ tuple: borrowing Tuple) throws(WinMDError) -> String {
+    guard let name = tuple.ordinal(for: "TypeName") else { return "" }
+    return try tuple.string(name)
+  }
+
+  /// A `TypeName` with its CLR generic-arity suffix removed — the projected
+  /// declaration name the render actually emits and the decode spells. The
+  /// suffix is a backtick and an arity count (`Foo` backtick `1`), which the
+  /// projection strips, so a generic `Foo` and a non-generic `Foo` project to
+  /// the one Swift name and collide. The collision tally and the qualification
+  /// identity key off this projected name so they match the emission; a name
+  /// without the suffix is returned unchanged.
+  private func projected(_ name: String) -> String {
+    String(name.prefix { $0 != "`" })
+  }
+
+  /// The (namespace, name) the `TypeDef`/`TypeRef` `tuple` names — the empty
+  /// string for either column it lacks.
+  private func names(_ tuple: borrowing Tuple)
+      throws(WinMDError) -> (namespace: String, name: String) {
+    let name = try bare(tuple)
+    guard let space = tuple.ordinal(for: "TypeNamespace") else {
+      return ("", name)
+    }
+    return (try tuple.string(space), name)
+  }
+
+  /// The open table numbered `number`, or `nil` when the database omits it —
+  /// the population-count slot lookup `rows(of:)`/`tuple(_:of:)` share, reduced
+  /// to the `Table` for a direct row read.
+  private func opened(_ number: Int) -> Table? {
+    guard valid & (1 << number) != 0 else { return nil }
+    let slot = (valid & ((1 << number) - 1)).nonzeroBitCount
+    return tables[slot]
+  }
 }

Sources/WinMDSynthesis/Decode.swift

@@ -426,13 +426,39 @@ extension TypeDefOrRef {
     if identity == kGuid {
       return classification(parameter, dialect: dialect)
     }
-    // A named type's simple name is a bare identifier that may collide with a
-    // target keyword (`protocol`, `repeat`); escape it as the render escapes a
-    // declaration name. A well-known spelling is curated and never a keyword.
-    return dialect.known[identity] ?? dialect.escape(identity.name)
+    // A well-known spelling (a Win32 primitive, curated and never a keyword)
+    // wins first, keyed on the `Identity` — so a known value type keeps its
+    // target name rather than an enclosing dot-path. Otherwise the type spells
+    // by its `Identity` name, which carries the enclosing dot-path a nested
+    // type resolves to (`Outer.Inner`) and the bare name a top-level one does.
+    // Either is a possibly dot-pathed identifier escaped per component
+    // (`dialect.escape` escapes one identifier, so a keyword component like
+    // `repeat` is delimited within the path rather than the whole treated as a
+    // single name); a top-level name has no dot and escapes unchanged.
+    if let known = dialect.known[identity] { return known }
+    return qualify(identity.name, dialect)
   }
 }
 
+/// Escapes a possibly dot-pathed named-type spelling per component through
+/// `dialect`, rejoining with `.` — so a nested type (`Foo.repeat`) escapes each
+/// identifier in turn (`` Foo.`repeat` ``) rather than the path as a whole. A
+/// top-level name (no dot) escapes as the single identifier it is.
+///
+/// Each component's CLR arity suffix (`` `1 ``) is stripped before it is
+/// escaped: the strip must precede the escape, since the suffixed `protocol``1`
+/// never matches a keyword while the stripped `protocol` does, and doing it
+/// here — the single seam every spelling escapes through — keeps a storage
+/// spelling (whose path `Storage.qualified` already stripped) and a
+/// directly-resolved one (whose identity still carries the suffix) escaping
+/// identically, so a generic instantiation's base needs no separate strip that
+/// would cut this escape.
+private func qualify(_ name: String, _ dialect: Dialect) -> String {
+  name.split(separator: ".", omittingEmptySubsequences: false)
+      .map { dialect.escape(String($0.prefix { $0 != "`" })) }
+      .joined(separator: ".")
+}
+
 /// The `System.Guid` identity that decodes to `IID`/`CLSID`.
 private let kGuid = Identity(namespace: "System", name: "Guid")
 
@@ -467,15 +493,18 @@ extension SignatureType {
     // opaque pointer; a generic over it is meaningless, so degrade to that
     // opaque pointer rather than emit `UnsafeMutableRawPointer<…>`.
     if base == dialect.opaque { return base }
-    // Strip the CLR arity suffix, THEN escape the base identifier: the full
-    // `Foo``1` never matches a keyword, so a keyword base (`protocol``1`) must
-    // be escaped after the strip, not before, to spell `` `protocol`<…> ``.
-    let name = dialect.escape(String(base.prefix { $0 != "`" }))
+    // The base already spells the generic definition ready to compose: the
+    // per-component arity strip lives at the escape seam (`qualify`), before
+    // the escape, since the suffixed `Foo``1` never matches a keyword — so a
+    // keyword leaf reads `` `protocol` `` and a namespace-qualified one
+    // `Outer.`protocol` `. Re-stripping the arity here would scan to that
+    // escape backtick and empty the leaf (`` `protocol` `` → `<…>`), so the
+    // base composes with the arguments as it stands.
     let arguments = arguments
         .map { $0.decode(parameter: parameter, generics: generics,
                          with: resolver, dialect: dialect) }
         .joined(separator: ", ")
-    return "\(name)\(dialect.generic.open)\(arguments)\(dialect.generic.close)"
+    return "\(base)\(dialect.generic.open)\(arguments)\(dialect.generic.close)"
   }
 }