winmd-inspect: disambiguate colliding names with fabricated namespaces

Disambiguate the names two reached declarations would otherwise share, so every
signature spelling resolves to the declaration it names and the generated source
compiles. Builds on the nesting slice; the frontier reservation the shadow check
and contention need is the following slice.

The projection is one flat top-level Swift scope, so a name is ambiguous when two
or more of the emitted top-level declarations bear it, of any kind. Only a value
type can be wrapped, so an ambiguous value type is emitted fully
namespace-qualified under fabricated namespace `enum` containers
(`A.Point`/`B.Point`) while the same-named `protocol` stays bare. A closure
integration test pins this cross-kind case end to end — a reached struct
`A.Point` beside an interface, then a delegate, `B.Point` — so the value type
wraps under `enum A` while the emitted non-value declaration stays a bare
top-level `Point`, no redeclaration. Ambiguity is
counted over the projected (arity-stripped) name and only over the reached
declarations, so an unreachable same-named type never forces a wrap; the
qualification keys off the value type's raw `namespace.name` identity and confirms
the reference resolves locally. One `Storage.spelling(resolved:qualifying:)` rule
drives the decode spelling, the emit nesting, and — through a `spelling(of id:)`
overload — the inheritance clause, so a nested base under a wrapped encloser reads
`A.Outer.IChild` exactly as a signature naming it decodes, and the three seams
cannot drift. Nesting folds only a type's *primary* declaration into its
container: a custom template may frame the type with a file-scope `import`
header or an `extension` footer, which Swift permits only at file scope, so
`Surface.partition` — locating the primary declaration off the syntax tree —
splits them off the rendered body and they bubble up, through every enclosing
container, to the roots. This is symmetric across a real `.type` container and a
fabricated `.space` namespace: `nest` renders a node as a (header, declaration,
footer) triple, folds each member's declaration in, and accumulates its members'
hoisted headers and footers to pass further up. A hoisted auxiliary lands in the
root file scope, so the per-scope collision check attributes it there rather than
its container — and every nested type's auxiliaries hoist, however deep it sits,
so two descendants of different wrapped containers each hoisting a same-named
`struct Helper` are a file-scope redeclaration a per-container check would miss.

Emittedness — which reached types the closure actually declares — is read from
the rendered body off the syntax tree (`Surface.declarations`): the top-level
`struct`/`class`/`enum`/`protocol`/`actor` and `typealias` names, so per-type
boilerplate, a documented-but-omitted ABI helper, a value declaration of the
type's name, a nested member, or a declaration inside a comment does not count. Every *other* top-level name a body declares — not just the primary and
the specially recognised generic `<name>ABI` helper, but any auxiliary a custom
template emits (a `struct A` beside a `protocol IRoot`) — is recorded as a scope
occupant, so the per-scope collision check faults a fabricated namespace `enum A`
or another declaration that redeclares it. The collision tally and the emit both
key off this emitted set, computed once after a reachability prune, so a body is
spelled with the same set that folds it into the tree. The emitted set is
re-pruned against the *bodied* declarations before it drives the tally: the first
prune propagates a node's references on its metadata kind, but a custom template
may omit an intermediate declaration (render nothing for a reached `struct
Point`), so a type reached only through that omitted node — a `Widget` a `Point`
field names — is an orphan the emitted source never references, dropped rather
than left to render unattached and fault an unrelated collision. A by-value type nested
beneath a generic encloser — named directly or through a `TypeRef`, its kind read
off the resolved definition — is dropped rather than misrendered as an
ABI-changing opaque pointer; but only a genuinely *by-value* occurrence poisons
its owner — a reference solely behind a pointer, byref, or array embeds no layout
and renders as an opaque pointer, so it drops nothing — and its referent is left
unrecorded, so the decode spells that opaque pointer rather than an uncompilable
`UnsafeMutablePointer<Outer.Inner>` naming a type the closure never emits.

The collision fixtures assemble their metadata through `WinMDFixture`, an in-target
`#~` assembler that interns the heaps and computes the table ranges, with a fluent
`WinMDBuilder` facade that assigns rids, links member lists, encodes signatures,
and resolves references — so a scenario reads in a dozen declarative lines instead
of a hundred of hand-encoded bytes.

This slice also reserves the frontier names a signature spells but the closure
does not emit, so a reached value type sharing a name with one contends —
wrapping and spelling namespace-qualified rather than bare and capturing the
frontier's reference. The frontier set is derived once from the emitted-set
complement: the walk records every spelled reference — a signature-named type or
an interface's named base — as its emitted top-level spelling paired with the
`TypeDef` Id it resolves to (its outermost encloser's, so a nested `A.Inner`
turns on its root `A`), and a reference is a frontier exactly when that Id is
absent from the emitted set. `Storage.collisions(contended:)` bumps a reached
value type whose projected name a frontier bears to ambiguous — so an emitted
signature naming both a local `A.Point` and an external `Point` wraps `A.Point`
rather than leaving both positions bound to the generated bare `Point`. Whether a
fabricated namespace would then *shadow* one of those bare references is the
following slice; this slice reserves and contends.

The reservation reads the metadata resolution, not the rendered text. The decode
records every signature reference of every emitted owner in `spelled` — its
owner, the local `Id` it resolves to (or nil for an external), and its category
— so a reference is a frontier exactly when that referent is unemitted. The
template spells names; it does not choose which references the surface bears, so
the closure keys renderedness off that graph rather than re-scanning the
rendered body for each label. A reached value type still contends with a
frontier of its projected name, and a literal identifier a template writes that
no signature references is absent from `spelled` and reserves nothing.

The synthesized fallback root (`IUnknown`) is not a frontier only when a
*top-level* local interface of that name is emitted: the bare `protocol IRoot:
IUnknown` resolves at file scope, so a metadata-nested `Outer.IUnknown` does not
satisfy the exemption, and with several local `IUnknown`s the reached one is
chosen. The exemption is keyed on a fallback flag, not the spelling, so an
explicit external `IUnknown` parameter or base stays a frontier.

A `known`-bridged reference reserves the frontier under its bridge leaf name,
keyed on the identity's leaf component as the decode spells it: a nested
`Outer.Inner` bridged `wellknown Inner …` reserves `InnerBridge`, not the
enclosing root `Outer`. Keying the bridge on the qualified `Outer.Inner` missed
it and reserved `Outer`, so a reached `A.InnerBridge` of the bridge name stayed
uncontended and captured the frontier bare rather than wrapping under `enum A`.

The base render tolerates a `Queries/bases.sql` override predating the `ref`/`def`
provenance columns. The bundled render reads those columns to resolve a local
base's Id, so a copied override carrying the former `(base, spec)` view shape
faults on the missing column; `heritage` catches that `SQLError.column` and
re-runs a legacy shape that resolves each base to a local interface by name —
the best-effort resolution the provenance replaced — so an emitted local base
keeps its Id (not mistaken for a frontier) and the older override renders
rather than failing, the extension-point tolerance `fields`/`requires` get.

Author: compnerd

Sources/SQLEngineWinMD/Database+SQL.swift

@@ -56,8 +56,10 @@ public import WinMD
 extension WinMD.Storage: SQLEngine.Catalog {
   /// The optional tables the bundled queries reference — tables ECMA-335 lets a
   /// database omit from the tables stream (`TypeSpec` §II.22.39 when nothing is
-  /// generic-instantiated, `NestedClass` §II.22.32 when nothing nests) that a
-  /// bundled view or the closure walk still names. `table(named:)` resolves an
+  /// generic-instantiated, `NestedClass` §II.22.32 when nothing nests,
+  /// `ClassLayout` §II.22.8 when no type declares an explicit layout or packing)
+  /// that a bundled view or the closure walk still names. `table(named:)`
+  /// resolves an
   /// absent one to an empty relation and `relations()` enumerates it, so a
   /// `SELECT … FROM` such a table reads no rows rather than faulting on a
   /// missing relation. Only these are synthesised — not the whole table
@@ -1058,13 +1060,15 @@ extension WinMD.Storage {
   /// undecodable signature, or an unresolvable one.
   package borrowing func decode(return method: Int,
                                  generics: Array<String>? = nil,
-                                 in dialect: Dialect) -> String? {
+                                 in dialect: Dialect,
+                                 qualifying: Set<String> = []) -> String? {
     guard let table = opened("MethodDef") else { return nil }
     let cursor = WinMD.Cursor(copy self, table)
     guard let tuple = cursor[method - 1],
         let row = Row<Metadata.Tables.MethodDef>(tuple),
         let signature = try? row.prototype,
-        let resolver = try? Resolver(of: signature, with: self) else {
+        let resolver = try? Resolver(of: signature, with: self,
+                                     qualifying: qualifying) else {
       return nil
     }
     return signature.returns.decode(generics: generics, with: resolver,
@@ -1087,7 +1091,8 @@ extension WinMD.Storage {
   /// it, so threading it is always safe.
   package borrowing func decode(parameter: Int,
                                  generics: Array<String>? = nil,
-                                 for dialect: Dialect) -> String? {
+                                 for dialect: Dialect,
+                                 qualifying: Set<String> = []) -> String? {
     guard let table = opened("Param") else { return nil }
     let params = WinMD.Cursor(copy self, table)
     guard let param = params[parameter - 1],
@@ -1107,7 +1112,8 @@ extension WinMD.Storage {
     guard position >= 1, position <= signature.parameters.count else {
       return nil
     }
-    guard let resolver = try? Resolver(of: signature, with: self) else {
+    guard let resolver = try? Resolver(of: signature, with: self,
+                                       qualifying: qualifying) else {
       return nil
     }
     let name = param.ordinal(for: "Name").flatMap { try? param.string($0) }
@@ -1126,13 +1132,15 @@ extension WinMD.Storage {
   /// type through it. `nil` mirrors the same undecodable contract — an absent
   /// row, an undecodable signature, or an unresolvable one — so the walk can
   /// treat a malformed field as a frontier.
-  package borrowing func decode(field: Int, in dialect: Dialect) -> String? {
+  package borrowing func decode(field: Int, in dialect: Dialect,
+                                qualifying: Set<String> = []) -> String? {
     guard let table = opened("FieldDef") else { return nil }
     let cursor = WinMD.Cursor(copy self, table)
     guard let tuple = cursor[field - 1],
         let row = Row<Metadata.Tables.FieldDef>(tuple),
         let signature = try? row.declaration,
-        let resolver = try? Resolver(of: signature, with: self) else {
+        let resolver = try? Resolver(of: signature, with: self,
+                                     qualifying: qualifying) else {
       return nil
     }
     return signature.type.decode(with: resolver, dialect: dialect)
@@ -1160,6 +1168,40 @@ extension WinMD.Storage {
     return resolver.identities
   }
 
+  /// The type identities the `MethodDef` at 1-based `method` `Id` names in its
+  /// *return* position — the return-spelled subset of `identities(method:)`, so
+  /// the closure walk categorizes a method's references as returned or
+  /// parameter. A reference named in both positions is in both subsets. An
+  /// absent or undecodable row yields the empty set.
+  package borrowing func returned(method: Int) -> Set<Referent> {
+    guard let table = opened("MethodDef") else { return [] }
+    let cursor = WinMD.Cursor(copy self, table)
+    guard let tuple = cursor[method - 1],
+        let row = Row<Metadata.Tables.MethodDef>(tuple),
+        let signature = try? row.prototype,
+        let resolver = try? Resolver(of: signature, with: self) else {
+      return []
+    }
+    return resolver.returned
+  }
+
+  /// The type identities the `MethodDef` at 1-based `method` `Id` names in its
+  /// *parameter* positions — the parameter-spelled subset of
+  /// `identities(method:)`; a reference named in both a return and a parameter
+  /// is in `returned(method:)` too. An absent or undecodable row yields the
+  /// empty set.
+  package borrowing func parameters(method: Int) -> Set<Referent> {
+    guard let table = opened("MethodDef") else { return [] }
+    let cursor = WinMD.Cursor(copy self, table)
+    guard let tuple = cursor[method - 1],
+        let row = Row<Metadata.Tables.MethodDef>(tuple),
+        let signature = try? row.prototype,
+        let resolver = try? Resolver(of: signature, with: self) else {
+      return []
+    }
+    return resolver.parameters
+  }
+
   /// The distinct type identities named in the signature of the `FieldDef` at
   /// 1-based `field` `Id` — the referenced-type set a struct's field contributes
   /// to the closure walk (edge E6).

Sources/SQLEngineWinMD/Resources/Queries/bases.sql

@@ -1,6 +1,15 @@
 CREATE VIEW bases AS
+-- Each plain base carries the InterfaceImpl provenance the render resolves it
+-- by: `ref` is the base's `Interface_TypeRef` Id (a reference the render follows
+-- through the scope chain), `def` its `Interface_TypeDef` Id (a local definition
+-- named directly). Exactly one is non-NULL per plain arm. The render keys the
+-- inheritance spelling off the resolved *identity* rather than correlating the
+-- name against a separate query — an external base that merely shares a bare
+-- `TypeName` with a local nested interface must not adopt the local one's Id.
 SELECT
   b.TypeName AS base,
+  b.Id AS ref,
+  NULL AS def,
   NULL AS spec
 FROM
   InterfaceImpl i
@@ -10,6 +19,8 @@ WHERE
 UNION
 SELECT
   d.TypeName AS base,
+  NULL AS ref,
+  d.Id AS def,
   NULL AS spec
 FROM
   InterfaceImpl i
@@ -18,19 +29,15 @@ WHERE
   i.Class = :parent
 UNION
 -- A generic base interface is named through a TypeSpec: the InterfaceImpl's
--- Interface coded index tags TypeSpec, which has no TypeName of its own. A
--- generic instantiation (GENERICINST <base> <args…>) resolves to its generic
--- base, whose Id the adapter decodes to the TypeSpec's Base_TypeRef or
--- Base_TypeDef key -- the 1-based Id of the base in its table. So the name
--- reads through a seekable join against the TypeRef and TypeDef base tables,
--- mirroring the `identities` view's two TypeSpec arms without re-evaluating a
--- four-way UNION per InterfaceImpl row. Without these arms the generic base is
--- dropped. The TypeSpec's own Id rides alongside as `spec` (NULL on a plain
--- base): the generic definition's TypeName carries an invalid arity suffix and
--- drops the type arguments, so the render decodes the complete constructed
--- spelling from the TypeSpec signature rather than emitting that TypeName.
+-- Interface coded index tags TypeSpec, which has no TypeName of its own. The
+-- name reads through a seekable join against the TypeRef and TypeDef base
+-- tables, mirroring the `identities` view's two TypeSpec arms. The TypeSpec's
+-- own Id rides alongside as `spec` (NULL on a plain base); the render omits a
+-- generic base (`spec IS NULL`), so its `ref`/`def` are NULL.
 SELECT
   r.TypeName AS base,
+  NULL AS ref,
+  NULL AS def,
   i.Interface_TypeSpec AS spec
 FROM
   InterfaceImpl i
@@ -41,6 +48,8 @@ WHERE
 UNION
 SELECT
   d.TypeName AS base,
+  NULL AS ref,
+  NULL AS def,
   i.Interface_TypeSpec AS spec
 FROM
   InterfaceImpl i