@ttsc/evidence 0.25.0 → 0.26.1

package/native/typescript.go

@@ -14,7 +14,7 @@ func loadTypeScriptInventories(
   config graphConfig,
 ) map[string]*artifactInventory {
   inventories := map[string]*artifactInventory{}
-  extendTypeScriptInventories(root, sources, config, inventories)
+  extendTypeScriptInventories(root, sources, config, inventories, nil)
   return inventories
 }
 
@@ -30,6 +30,7 @@ func extendTypeScriptInventories(
   sources []*shimast.SourceFile,
   config graphConfig,
   inventories map[string]*artifactInventory,
+  governed map[string]bool,
 ) {
   bases := configuredBases(config, artifactTypeScript)
   for _, file := range sources {
@@ -42,6 +43,9 @@ func extendTypeScriptInventories(
         continue
       }
       address := base.addressOf(relative)
+      if governed != nil && matchesConfiguredTypeScriptFile(config, base, relative) {
+        governed[address.Key] = true
+      }
       if inventories[address.Key] != nil {
         continue
       }
@@ -129,12 +133,13 @@ func scanTypeScriptInventoryAt(
   file *shimast.SourceFile,
 ) *artifactInventory {
   inventory := &artifactInventory{
-    Address:   address.Key,
-    Path:      address.Display,
-    Type:      artifactTypeScript,
-    Imports:   collectImportBindings(file),
-    Exports:   collectModuleExports(file),
-    UnitNodes: map[string][]*shimast.Node{},
+    Address:     address.Key,
+    Path:        address.Display,
+    Type:        artifactTypeScript,
+    Imports:     collectImportBindings(file),
+    Exports:     collectModuleExports(file),
+    UnitNodes:   map[string][]*shimast.Node{},
+    UnitContent: map[string][]*shimast.Node{},
   }
   supportedHosts := map[*shimast.Node]symbolSet{}
   unitsByID := map[string]*evidenceUnit{}
@@ -151,6 +156,7 @@ func scanTypeScriptInventoryAt(
     false,
     "",
   )
+  withdrawHiddenHosts(inventory, supportedHosts)
   collectTypeScriptDeclarations(
     file,
     address.Key,
@@ -162,6 +168,7 @@ func scanTypeScriptInventoryAt(
   // used to derive them. Declarations now retain those IDs directly, so release
   // the transient index before this inventory enters the immutable graph.
   inventory.UnitNodes = nil
+  inventory.UnitContent = nil
   sort.Slice(inventory.Units, func(left int, right int) bool {
     if inventory.Units[left].Target != inventory.Units[right].Target {
       return inventory.Units[left].Target < inventory.Units[right].Target
@@ -171,6 +178,87 @@ func scanTypeScriptInventoryAt(
   return inventory
 }
 
+// withdrawHiddenHosts takes every declaration of a withdrawn identity out of
+// the host set, once materialization has decided which identities are withdrawn.
+//
+// Withdrawal is a property of the **identity**, while `supportedHosts` is filled
+// in one node at a time by whichever collector walked that container. Those two
+// facts disagree whenever an identity spans more than one declaration and the
+// author tagged only one of them, which is every overload run and every merged
+// interface: the unit came out marked, and the untagged sibling stayed a host,
+// so a declaration the author had taken out of the API went on discharging
+// coverage and acting as an exclusion carrier. Measured on both shapes; both
+// were silent, because the unit really was marked.
+//
+// Reconciling here rather than in each collector is what turns a list of
+// witnesses into one rule. A per-container withdrawal index closes the container
+// it indexes and nothing else, and there is one such container per declaration
+// form. This runs once, over the identities the whole file produced, so it
+// reaches a form nobody has written yet — but only as far as that form's
+// unit-to-node association goes, which is the condition below and the one place
+// this is not yet a closed class.
+//
+// A position is given up only when **every** identity that reaches it is
+// withdrawn. One node can host several: `export var price: number, live:
+// number` is two property identities sharing the statement TypeScript attaches
+// their block to, and withdrawing one of them must not take the other's only
+// host position with it. Judging per node alone did exactly that, and refused a
+// citation on a public declaration nobody had tagged. The exemplar is `var`
+// rather than `const` because a partial withdrawal needs a second declaration
+// of one identity, which for `const` is `TS2451`.
+//
+// What this cannot reach is a host node no unit records, so a form that
+// registers a position owes that position to its unit. The variable declarator
+// was the one that did not, and a withdrawn variable identity kept it until
+// `collectTypeScriptVariables` began recording it. `documentedHosts` filters on
+// the same association and was measured to answer identically either way, since
+// it takes the first of a unit's *host* nodes and a declarator is a host only
+// when its statement is one for the same symbol; the invariant is what was
+// broken there rather than an observable answer.
+//
+// A second fault travelled with that one and has its own cause, which is why
+// they are stated apart: a withdrawal tag read from a container is not the tag
+// of the declarations
+// inside it, so an inner declarator owes its own read, and recording the node
+// would have left that exactly where it was.
+//
+// `documentedHosts` needs no equivalent: it skips a withdrawn unit before it
+// ever consults the host set.
+func withdrawHiddenHosts(
+  inventory *artifactInventory,
+  supportedHosts map[*shimast.Node]symbolSet,
+) {
+  type hostPosition struct {
+    node   *shimast.Node
+    symbol string
+  }
+  live := map[hostPosition]bool{}
+  withdrawn := map[hostPosition]bool{}
+  for _, unit := range inventory.Units {
+    for _, node := range inventory.UnitNodes[unit.ID] {
+      position := hostPosition{node: node, symbol: unit.Symbol}
+      if unit.Hidden == "" {
+        live[position] = true
+        continue
+      }
+      withdrawn[position] = true
+    }
+  }
+  for position := range withdrawn {
+    if live[position] {
+      continue
+    }
+    hosts := supportedHosts[position.node]
+    if hosts == nil {
+      continue
+    }
+    delete(hosts, position.symbol)
+    if len(hosts) == 0 {
+      delete(supportedHosts, position.node)
+    }
+  }
+}
+
 // collectTypeScriptStatements materializes the public units one statement list
 // declares.
 //
@@ -197,9 +285,10 @@ func collectTypeScriptStatements(
   exports := collectLocalExportNames(statements)
   hiddenNames := collectHiddenDeclarationNames(file, statements)
   // Built on the first namespace this list holds rather than up front, so a
-  // file declaring none pays nothing. Every rebuild scans every configured
-  // source, and most of them have no namespace at all.
+  // file declaring none pays nothing.
   var functionNames map[string]bool
+  // The same, for the class an interface in this list may merge with.
+  var classNames map[string]bool
   for _, statement := range statements.Nodes {
     if statement == nil {
       continue
@@ -210,7 +299,7 @@ func collectTypeScriptStatements(
       if name == "" {
         continue
       }
-      targets := publicTypeScriptNames(
+      targets := publicTypeScriptExports(
         statement,
         name,
         exports,
@@ -224,26 +313,57 @@ func collectTypeScriptStatements(
       if memberHidden == "" {
         addTypeScriptHost(supportedHosts, statement, "type")
       }
-      for _, name := range targets {
-        identity := qualifyTypeScriptName(prefix, name)
+      // An interface merged with a class declares that class's instance
+      // members, so they take the instance address the class body form takes.
+      // Addressing them from the bare name instead published `Sale.charge` for
+      // a member reached as `Sale.prototype.charge`: a path no consumer can
+      // walk, a second unit for a method the class already declared, and an
+      // obligation that stayed owed however the real member was cited.
+      //
+      // The merge also brings the type-only rule with it. The members of an
+      // interface no class merges with are type-space and project through a
+      // type-only alias, a namespace or function partner included, but a
+      // class-merged one's are reached through the class value that alias does
+      // not expose, which is the address the class branch is already
+      // suppressed for. Publishing them here would breach that guard at
+      // exactly the address it exists to keep empty. What `target.TypeOnly`
+      // reaches, and what it does not, is stated once on the class branch this
+      // guard mirrors.
+      if classNames == nil {
+        classNames = collectClassDeclarationNames(statements)
+      }
+      mergedWithClass := classNames[name]
+      for _, target := range targets {
+        identity := qualifyTypeScriptName(prefix, target.Public)
         unit := addTypeScriptUnit(
           inventory,
           unitsByID,
           statement,
+          statement,
           "type",
           identity,
           parentID,
           memberHidden,
         )
+        memberOwner := identity
+        if mergedWithClass {
+          if typeOnlyProjection || target.TypeOnly {
+            continue
+          }
+          memberOwner = qualifyTypeScriptName(identity, "prototype")
+        }
         collectPropertyMembers(
           file,
           statement.AsInterfaceDeclaration().Members,
-          identity,
+          memberOwner,
           unit.ID,
           inventory,
           supportedHosts,
           unitsByID,
           memberHidden,
+          // Only the class merge makes these value-space. An interface's own
+          // members are type-space and a type-only export publishes them.
+          mergedWithClass,
         )
       }
     case shimast.KindTypeAliasDeclaration:
@@ -272,6 +392,7 @@ func collectTypeScriptStatements(
           inventory,
           unitsByID,
           statement,
+          statement,
           "type",
           identity,
           parentID,
@@ -287,6 +408,7 @@ func collectTypeScriptStatements(
             supportedHosts,
             unitsByID,
             memberHidden,
+            false,
           )
         }
       }
@@ -317,11 +439,12 @@ func collectTypeScriptStatements(
           inventory,
           unitsByID,
           statement,
+          statement,
           "function",
           qualifyTypeScriptName(prefix, name),
           parentID,
           memberHidden,
-        )
+        ).markSpace(true)
       }
     case shimast.KindVariableStatement:
       if typeOnlyProjection {
@@ -329,6 +452,7 @@ func collectTypeScriptStatements(
       }
       memberHidden := typeScriptHidingTag(file, statement, hidden)
       for symbol := range collectTypeScriptVariables(
+        file,
         statement,
         prefix,
         parentID,
@@ -347,23 +471,57 @@ func collectTypeScriptStatements(
         addTypeScriptHost(supportedHosts, statement, symbol)
       }
     case shimast.KindClassDeclaration:
-      if typeOnlyProjection {
+      name := declarationName(statement.Name())
+      if name == "" {
         continue
       }
-      name := declarationName(statement.Name())
-      memberHidden := hidingTagFor(hidden, hiddenNames, name)
-      for _, publicName := range publicTypeScriptNames(
+      // A class name is type-space, so a type-only alias exposes it exactly
+      // as it exposes an interface. What the alias withholds is the members:
+      // `C.prototype.field` and `C.staticField` are paths through the class
+      // *value*, and a type-only alias exposes no value to walk them from.
+      //
+      // This guard answers an export written in this file, where the
+      // declaration kind is in hand: `target.TypeOnly` sees `export type { C }`
+      // and `export { type C }` alike, and `typeOnlyProjection` sees a
+      // type-only alias of an enclosing namespace. A re-export naming another
+      // module has no such context and is answered at traversal time instead,
+      // from `evidenceUnit.ValueSpace`, which is why these members are marked
+      // there. The interface branch mirrors this guard for a class-merged
+      // interface and points here for the reason.
+      targets := publicTypeScriptExports(
         statement,
         name,
         exports,
-        false,
+        true,
         implicitlyExported,
-      ) {
-        collectClassCallables(
-          file,
+      )
+      if len(targets) == 0 {
+        continue
+      }
+      memberHidden := hidingTagFor(hidden, hiddenNames, name)
+      if memberHidden == "" {
+        addTypeScriptHost(supportedHosts, statement, "type")
+      }
+      for _, target := range targets {
+        identity := qualifyTypeScriptName(prefix, target.Public)
+        unit := addTypeScriptUnit(
+          inventory,
+          unitsByID,
+          statement,
           statement,
-          qualifyTypeScriptName(prefix, publicName),
+          "type",
+          identity,
           parentID,
+          memberHidden,
+        )
+        if typeOnlyProjection || target.TypeOnly {
+          continue
+        }
+        collectClassMembers(
+          file,
+          statement,
+          identity,
+          unit.ID,
           inventory,
           supportedHosts,
           unitsByID,
@@ -405,6 +563,7 @@ func collectTypeScriptStatements(
           inventory,
           unitsByID,
           statement,
+          statement,
           "type",
           identity,
           parentID,
@@ -434,11 +593,12 @@ func collectTypeScriptStatements(
 //
 // A namespace merges only with a function, a class, or an enum in the same
 // scope; a `const` or `let` of the same name is `TS2451`, measured against the
-// pinned compiler. Of the three legal partners only a function also
-// materializes a unit under the merged name — a class registers no unit of its
-// own and the collector has no enum case — so the function form is the one
-// shape where a namespace and the declaration it merges with are the same
-// public entity spelled twice.
+// pinned compiler. Only the function partner makes the namespace a static side
+// that materializes nothing. A class partner keeps its namespace, because a
+// companion namespace beside a class is authored contract — `namespace Sale`
+// holding `Sale.IProps` beside `class Sale` — rather than the generated
+// accessor machinery `get.path` and `get.Output` are. The collector has no enum
+// case, so an enum partner reaches nothing either way.
 //
 // The name alone decides, without consulting export modifiers, because
 // TypeScript refuses a merged declaration whose halves disagree on export
@@ -464,7 +624,76 @@ func collectFunctionDeclarationNames(
   return names
 }
 
+// collectClassDeclarationNames indexes the local names a statement list
+// declares as classes, which is what an interface in the same list merges with.
+//
+// The merge is what decides a member's address rather than its kind. An
+// interface merged with a class describes that class's instance side, so
+// `interface Sale { charge(): void }` beside `class Sale` declares the same
+// member the class body would and takes the same `Sale.prototype.charge`
+// address. A namespace is the other partner and adds statics instead, which is
+// why only the interface case moves.
+//
+// The whole list is indexed rather than only the statements already collected,
+// because merging does not depend on which declaration is written first, and
+// export modifiers are not consulted for the reason
+// `collectFunctionDeclarationNames` gives: TypeScript refuses a merge whose
+// halves disagree on export.
+func collectClassDeclarationNames(
+  statements *shimast.NodeList,
+) map[string]bool {
+  names := map[string]bool{}
+  if statements == nil {
+    return names
+  }
+  for _, statement := range statements.Nodes {
+    if statement == nil ||
+      statement.Kind != shimast.KindClassDeclaration {
+      continue
+    }
+    if name := declarationName(statement.Name()); name != "" {
+      names[name] = true
+    }
+  }
+  return names
+}
+
+// collectTypeScriptVariables materializes a variable statement's exported
+// declarators.
+//
+// A variable is a function only when a `const` is initialized with a function
+// value, and that is the inverse of the member rule in memberSymbol:
+// here the annotation decides nothing, because a variable's declared type
+// describes a value that already exists rather than stating a contract. The
+// three conditions below are each load-bearing and each measured separately, at
+// module and at namespace scope: a binding pattern's initializer belongs to the
+// pattern rather than to any leaf, `let` and `var` are excluded whatever they
+// hold, and the initializer is read syntactically because these rules run with
+// no type checker.
+// A declarator is both a host position and a unit node, and it has to be both.
+// It was only the first: `supportedHosts` held it while no unit recorded it, so
+// nothing that walks from a unit to its declarations could see it. Two answers
+// were wrong and both were silent. `withdrawHiddenHosts` could not take the
+// position away from a withdrawn identity, so a declaration the author had
+// removed from the API went on discharging coverage and carrying exclusions.
+// And a citation written on it resolved to no semantic host, so
+// `singleEvidencePerSymbol` counted the statement's identities as citing zero
+// units while the same run reported the obligation satisfied.
+//
+// A third consumer reads the same association and was measured to answer
+// identically either way. `hostNodesOf` keeps a unit's host nodes and takes the
+// first, and a declarator is a host only when its statement is one for the same
+// symbol, so `evidence/documented` always had the wrapper to look at. The
+// invariant was broken there rather than the answer, which is reason enough:
+// the next declaration form to register a position will not be so lucky.
+//
+// Its own withdrawal tag is read here for a separate fault rather than the same
+// one: the statement wrapper's tag was taken for every declarator it holds, so
+// `@internal` written on an inner declarator withdrew nothing. Recording the
+// node closes the first two and leaves this one standing, which is why #1126
+// states them apart.
 func collectTypeScriptVariables(
+  file *shimast.SourceFile,
   statement *shimast.Node,
   prefix []string,
   parentID string,
@@ -495,6 +724,7 @@ func collectTypeScriptVariables(
       isFunctionValue(value.Initializer) {
       symbol = "function"
     }
+    declaratorHidden := typeScriptHidingTag(file, declaration, hidden)
     for _, binding := range bindingIdentifierNodes(declaration.Name()) {
       name := declarationName(binding)
       targets := publicTypeScriptNames(
@@ -507,7 +737,7 @@ func collectTypeScriptVariables(
       if len(targets) == 0 {
         continue
       }
-      if hidden == "" {
+      if declaratorHidden == "" {
         addTypeScriptHost(supportedHosts, declaration, symbol)
       }
       for _, name := range targets {
@@ -515,14 +745,18 @@ func collectTypeScriptVariables(
           inventory,
           unitsByID,
           binding,
+          declaration,
           symbol,
           qualifyTypeScriptName(prefix, name),
           parentID,
-          hidden,
+          declaratorHidden,
         )
-        // The binding names the unit, but TypeScript attaches a
-        // variable's leading JSDoc to the statement wrapper, so that
-        // is where a citation for this unit actually lives.
+        // TypeScript attaches a variable's leading JSDoc to the statement
+        // wrapper, so that is where a citation for this unit lives and the
+        // wrapper is a position this identity owns. It is not this
+        // identity's content: the same wrapper declares every sibling of
+        // this declarator, and their text belongs to them.
+        unit.markSpace(true)
         inventory.recordUnitNode(unit.ID, statement)
       }
       found[symbol] = true
@@ -531,11 +765,33 @@ func collectTypeScriptVariables(
   return found
 }
 
-func collectClassCallables(
+// collectClassMembers materializes the public contract a class declares.
+//
+// A method is a function unit and a field is a property unit, which is the
+// mapping a reader already assumes: the class is the subject, its methods are
+// what the subject does, and its fields are the measured facts it carries.
+// `memberSymbol` owns the one exception, where a field written as a
+// callable joins the methods, and "written as" is literal: see
+// `isDirectFunctionType`.
+// Every member hangs below the class unit, so a citation on the class
+// acknowledges the members it selected.
+//
+// A constructor is not a unit of its own, now that the class is: construction
+// is how the subject comes to be, and the subject already carries that
+// obligation. It is still read, because the fields it declares through the
+// parameter-property shorthand are the class's fields; `collectParameterProperties`
+// takes those.
+//
+// Two shapes stay out entirely. An accessor, including an auto-accessor, is a
+// get/set pair rather than a member variable, which is the exclusion the
+// published contract has always stated. A member with no citable name — a
+// private identifier, an index signature, a computed name, a static block — has
+// no target an author could write.
+func collectClassMembers(
   file *shimast.SourceFile,
   statement *shimast.Node,
   classIdentity []string,
-  parentID string,
+  classID string,
   inventory *artifactInventory,
   supportedHosts map[*shimast.Node]symbolSet,
   unitsByID map[string]*evidenceUnit,
@@ -545,46 +801,246 @@ func collectClassCallables(
   if class.Members == nil {
     return
   }
+  // A member's own tag is read from the node in hand, and that is enough for
+  // the unit: `addTypeScriptUnit` keeps the first tag any declaration of an
+  // identity carries, so an overload run tagged on one half comes out marked
+  // whichever half is written first. The host set is reconciled against those
+  // identities afterwards by `withdrawHiddenHosts`, which is what stops the
+  // untagged half of a withdrawn member from staying a claim host.
+  //
+  // The constructor is resolved separately and up front, because it is the one
+  // container here that declares units without being one: its tag has to reach
+  // the parameter properties rather than a member of its own, and no unit of
+  // its own will carry it there.
+  constructorHidden := ""
+  constructorResolved := false
   for _, member := range class.Members.Nodes {
-    if member == nil || !isPublicClassMember(member) {
+    if member == nil {
+      continue
+    }
+    // A constructor is judged before the public check, because its own
+    // visibility is not its parameter properties'. A `private constructor`
+    // closes construction from outside; `public readonly price` on one of its
+    // parameters is still an instance field every holder of the object reads.
+    if member.Kind == shimast.KindConstructor {
+      // Resolved once per class rather than per declaration, so an overload
+      // run does not rescan the member list for every signature it holds.
+      if !constructorResolved {
+        constructorHidden = constructorHidingTag(file, class.Members, hidden)
+        constructorResolved = true
+      }
+      collectParameterProperties(
+        file,
+        member,
+        classIdentity,
+        classID,
+        inventory,
+        supportedHosts,
+        unitsByID,
+        constructorHidden,
+      )
+      continue
+    }
+    if !isPublicClassMember(member) {
       continue
     }
-    callable := false
+    symbol := ""
     switch member.Kind {
     case shimast.KindMethodDeclaration:
-      callable = true
+      symbol = "function"
     case shimast.KindPropertyDeclaration:
       if member.ModifierFlags()&shimast.ModifierFlagsAccessor != 0 {
         continue
       }
       property := member.AsPropertyDeclaration()
-      callable = isFunctionValue(property.Initializer) ||
-        isDirectFunctionType(property.Type)
-    }
-    if !callable {
+      symbol = memberSymbol(property.Initializer, property.Type)
+    default:
       continue
     }
-    memberName := declarationName(member.Name())
-    if memberName == "" {
+    addClassMemberUnit(
+      member,
+      declarationName(member.Name()),
+      symbol,
+      shimast.GetCombinedModifierFlags(member)&shimast.ModifierFlagsStatic != 0,
+      classIdentity,
+      classID,
+      inventory,
+      supportedHosts,
+      unitsByID,
+      typeScriptHidingTag(file, member, hidden),
+    )
+  }
+}
+
+// collectParameterProperties materializes the fields a constructor declares
+// through the parameter-property shorthand.
+//
+// `constructor(public readonly price: number)` declares the same public
+// instance field as `readonly price: number` written in the class body, and
+// TypeScript attaches a leading documentation block to the parameter, so it is
+// a real position a citation can live in. Reading only `class.Members` would
+// leave the shorthand invisible while the body form was selected, which is one
+// defect wearing two syntaxes.
+//
+// Every parameter property is an instance field. A constructor cannot be
+// static, and TypeScript refuses a parameter property on an overload
+// signature, so the implementation constructor is the only one that reaches
+// here with any.
+//
+// The tag `hidden` carries is the constructor's, already resolved across every
+// declaration of it by `constructorHidingTag`. The constructor is the only
+// container in this collector that declares units without being one, so
+// forwarding the class's tag alone would leave `@internal` on a constructor
+// inert while the same tag on a class or on the field itself withdraws.
+func collectParameterProperties(
+  file *shimast.SourceFile,
+  constructor *shimast.Node,
+  classIdentity []string,
+  classID string,
+  inventory *artifactInventory,
+  supportedHosts map[*shimast.Node]symbolSet,
+  unitsByID map[string]*evidenceUnit,
+  hidden string,
+) {
+  if constructor.ParameterList() == nil {
+    return
+  }
+  for _, parameter := range constructor.Parameters() {
+    if parameter == nil || !isParameterProperty(parameter) {
       continue
     }
-    identity := qualifyTypeScriptName(classIdentity, "prototype", memberName)
-    if shimast.GetCombinedModifierFlags(member)&shimast.ModifierFlagsStatic != 0 {
-      identity = qualifyTypeScriptName(classIdentity, memberName)
+    if !isPublicClassMember(parameter) {
+      continue
     }
-    memberHidden := typeScriptHidingTag(file, member, hidden)
-    addTypeScriptUnit(
+    value := parameter.AsParameterDeclaration()
+    addClassMemberUnit(
+      parameter,
+      declarationName(parameter.Name()),
+      memberSymbol(value.Initializer, value.Type),
+      false,
+      classIdentity,
+      classID,
       inventory,
+      supportedHosts,
       unitsByID,
-      member,
-      "function",
-      identity,
-      parentID,
-      memberHidden,
+      // A parameter property is declared exactly once, so its own tag is the
+      // only one below the constructor's and no identity index is needed.
+      typeScriptHidingTag(file, parameter, hidden),
     )
-    if memberHidden == "" {
-      addTypeScriptHost(supportedHosts, member, "function")
+  }
+}
+
+// constructorHidingTag resolves the withdrawal tag of a class's constructor
+// across every declaration of it.
+//
+// An overload run is one constructor written several times, and the tag may sit
+// on any of them: a signature is where a reader looks for the documentation,
+// while only the implementation declares parameter properties. Reading the tag
+// per node would make the withdrawal depend on which half the author documented,
+// which is the source-order accident every other merged declaration in this
+// collector already refuses.
+func constructorHidingTag(
+  file *shimast.SourceFile,
+  members *shimast.NodeList,
+  inherited string,
+) string {
+  if inherited != "" {
+    return inherited
+  }
+  if file == nil || members == nil {
+    return ""
+  }
+  for _, member := range members.Nodes {
+    if member == nil || member.Kind != shimast.KindConstructor {
+      continue
     }
+    if tag := typeScriptHidingTag(file, member, ""); tag != "" {
+      return tag
+    }
+  }
+  return ""
+}
+
+// isParameterProperty reports whether a constructor parameter also declares a
+// field, which is exactly what a property modifier says.
+//
+// The mask is TypeScript's own and holds five: the three accessibility
+// modifiers, `readonly`, and `override`. Naming the familiar four is what a
+// summary reaches for, and it is short by `override`, whose own meaning is
+// about the base class rather than about the field, so it does not read as a
+// field declaration at all. On a class extending one that declares `rate`,
+// `constructor(override rate: number)` compiles, emits the assignment, and
+// declares a public instance field. Take the mask rather than restating it;
+// upstream's own comment beside the constant enumerates four.
+func isParameterProperty(parameter *shimast.Node) bool {
+  return shimast.GetCombinedModifierFlags(parameter)&
+    shimast.ModifierFlagsParameterPropertyModifier != 0
+}
+
+// memberSymbol classifies one member variable by how it is written.
+//
+// Not by what it resolves to: an arrow or function initializer, or a type
+// annotation spelled as a function type, makes a member a callable, and one
+// annotated with an alias of that type does not. `isDirectFunctionType` says
+// why.
+//
+// Spelled once because the answer may not depend on which syntax declared the
+// member. A field in a class body, the same field written as a constructor
+// parameter property, and the same member spelled on an interface or an
+// object-shaped type alias are one contract in four spellings, and letting any
+// of them classify separately is the syntax dependence this collector exists to
+// remove. An interface once answered `property` to `charge: () => void` while a
+// class answered `function`, so a `symbol: "function"` claim over a file of
+// interfaces selected nothing, deactivated, and passed with no coverage.
+func memberSymbol(initializer *shimast.Node, declared *shimast.Node) string {
+  if isFunctionValue(initializer) || isDirectFunctionType(declared) {
+    return "function"
+  }
+  return "property"
+}
+
+// addClassMemberUnit registers one public class member under the address that
+// reaches it from the class.
+//
+// An instance member is addressed through `prototype` and a static member
+// directly, because those are the two paths a consumer can actually write. The
+// class unit is the parent, so the member is a structural descendant of the
+// subject that declares it rather than a sibling of the class's neighbours.
+// `memberHidden` is this declaration's own withdrawal tag, inherited from its
+// class. A sibling declaration of the same identity may carry one this node does
+// not; `addTypeScriptUnit` folds that into the unit, and `withdrawHiddenHosts`
+// then takes this node out of the host set.
+func addClassMemberUnit(
+  node *shimast.Node,
+  name string,
+  symbol string,
+  static bool,
+  classIdentity []string,
+  classID string,
+  inventory *artifactInventory,
+  supportedHosts map[*shimast.Node]symbolSet,
+  unitsByID map[string]*evidenceUnit,
+  memberHidden string,
+) {
+  if name == "" {
+    return
+  }
+  identity := qualifyTypeScriptName(classIdentity, "prototype", name)
+  if static {
+    identity = qualifyTypeScriptName(classIdentity, name)
+  }
+  addTypeScriptUnit(
+    inventory,
+    unitsByID,
+    node,
+    node,
+    symbol,
+    identity,
+    classID,
+    memberHidden,
+  ).markSpace(true)
+  if memberHidden == "" {
+    addTypeScriptHost(supportedHosts, node, symbol)
   }
 }
 
@@ -612,6 +1068,19 @@ func isFunctionValue(node *shimast.Node) bool {
   return false
 }
 
+// isDirectFunctionType reports whether a type annotation is written as a
+// function type, rather than whether it resolves to one.
+//
+// Syntactic on purpose, and this is the sentence every summary of the class
+// field rule gets wrong. `evidence/graph` declares `NeedsTypeChecker() false`,
+// so nothing here can follow `type Handler = () => void` to its target: a field
+// annotated `Handler` is a property, while the same field annotated
+// `() => void` is a function. Parentheses are unwrapped because they change
+// nothing a reader means; a constructor type, a union with a callable in it,
+// and an alias are all left alone because resolving them is the checker's job.
+//
+// Anyone restating this as "a field that holds a function" has restated
+// something else. Twice now, on shipped surfaces.
 func isDirectFunctionType(node *shimast.Node) bool {
   for node != nil && node.Kind == shimast.KindParenthesizedType {
     parenthesized := node.AsParenthesizedTypeNode()
@@ -666,6 +1135,13 @@ func collectTypeScriptModule(
     if name != "" {
       identity := qualifyTypeScriptName(qualified, name)
       innerHidden := typeScriptHidingTag(file, module.Body, hidden)
+      // No citation reaches this position today. TypeScript attaches a leading
+      // block to the outer declaration of a dotted namespace, so the tag on
+      // `export namespace Outer.Inner {}` resolves through the outer host and
+      // the inner one is written and never read. It is registered anyway,
+      // because the host set is derived from the unit set and a position a unit
+      // records must be in it; the day a form does attach a block here, the
+      // guard is the thing that was already right.
       if innerHidden == "" {
         addTypeScriptHost(supportedHosts, module.Body, "type")
       }
@@ -673,6 +1149,7 @@ func collectTypeScriptModule(
         inventory,
         unitsByID,
         module.Body,
+        module.Body,
         "type",
         identity,
         parentID,
@@ -695,6 +1172,29 @@ func collectTypeScriptModule(
   }
 }
 
+// collectPropertyMembers materializes the members an interface or an
+// object-shaped type alias declares.
+//
+// This is the other half of the four-spelling rule `collectClassMembers` owns,
+// and the two must stay in step: a member signature is a function unit and a
+// data member is a property unit, decided by `memberSymbol` from the annotation
+// as spelled. The classification is single-sourced there, while the member-kind
+// switch is written twice, once per container, so a kind added to one and not
+// the other is the drift this pair is most exposed to.
+//
+// The allowlist and the name check are the exclusion, and both gates matter. A
+// get or set signature is an accessor, which is a get/set pair rather than a
+// member variable and stays out on every container. A call signature, a
+// construct signature, and an index signature have no citable name, so an
+// author could not write a target for one. A computed name passes the switch
+// and is refused after it, for the same reason.
+//
+// That leaves a consequence worth stating rather than discovering: a
+// call-signature-only `interface Handler { (input: string): void }` contributes
+// no *member* unit, so a claim narrowed to `symbol: "function"` or `"property"`
+// over a file of them selects no host and deactivates silently. The interface
+// itself is still a `type` unit, so the default selector keeps such a claim
+// active; the qualifier is the whole statement here, not a detail of it.
 func collectPropertyMembers(
   file *shimast.SourceFile,
   members *shimast.NodeList,
@@ -704,12 +1204,22 @@ func collectPropertyMembers(
   supportedHosts map[*shimast.Node]symbolSet,
   unitsByID map[string]*evidenceUnit,
   hidden string,
+  valueSpace bool,
 ) {
   if members == nil {
     return
   }
   for _, member := range members.Nodes {
-    if member == nil || member.Kind != shimast.KindPropertySignature {
+    if member == nil {
+      continue
+    }
+    symbol := ""
+    switch member.Kind {
+    case shimast.KindPropertySignature:
+      symbol = memberSymbol(nil, member.AsPropertySignatureDeclaration().Type)
+    case shimast.KindMethodSignature:
+      symbol = "function"
+    default:
       continue
     }
     name := declarationName(member.Name())
@@ -722,13 +1232,14 @@ func collectPropertyMembers(
       inventory,
       unitsByID,
       member,
-      "property",
+      member,
+      symbol,
       identity,
       parentID,
       memberHidden,
-    )
+    ).markSpace(valueSpace)
     if memberHidden == "" {
-      addTypeScriptHost(supportedHosts, member, "property")
+      addTypeScriptHost(supportedHosts, member, symbol)
     }
   }
 }
@@ -816,10 +1327,20 @@ func typeScriptHidingTag(
   return ""
 }
 
+// addTypeScriptUnit materializes one declaration of an identity.
+//
+// `named` is the node that names the identity here and answers for where it is
+// reported. `content` is the node whose text is the identity's content at this
+// declaration. They are the same node for every form whose declaration carries
+// its own name, and they part for a variable, whose unit is named by a binding
+// identifier inside a declarator. One declarator can name several identities:
+// a destructuring pattern's leaves share it, and so do two aliases of one local
+// in an export list.
 func addTypeScriptUnit(
   inventory *artifactInventory,
   unitsByID map[string]*evidenceUnit,
-  node *shimast.Node,
+  named *shimast.Node,
+  content *shimast.Node,
   symbol string,
   identity []string,
   parentID string,
@@ -835,7 +1356,7 @@ func addTypeScriptUnit(
   // declaration that spells it. `interface I` beside `namespace I` is one
   // unit and two nodes, and a rule asking where that unit's JSDoc may live
   // has to see both.
-  inventory.recordUnitNode(id, node)
+  inventory.recordUnitContent(id, content)
   if unit := unitsByID[id]; unit != nil {
     // A merged identity is one unit, so one declaration marking itself
     // internal marks the identity. Both halves of `interface I` beside
@@ -854,7 +1375,7 @@ func addTypeScriptUnit(
     Type:     artifactTypeScript,
     Symbol:   symbol,
     Path:     inventory.Path,
-    Line:     lineAtNode(inventory.Path, node),
+    Line:     lineAtNode(inventory.Path, named),
     Readable: "TypeScript " + symbol + " '" + target + "'",
     Hidden:   hidden,
   }
@@ -880,6 +1401,19 @@ func addTypeScriptHost(
 // lineAtNode stores a byte offset until declarations are scanned against the
 // complete source text. A position inside the name is on the declaration
 // itself, while both the parent and name full starts may include leading trivia.
+//
+// An identifier is its own name and reports none, so it answers from its own
+// end rather than from the full start it would otherwise fall through to. A
+// full start begins where the previous token ended, so it lies in the node's
+// leading trivia rather than among its own tokens whenever any trivia sits
+// between the two. A variable unit is created from its binding identifier and
+// took that answer, which is a line above each leaf of a multi-line
+// destructuring pattern and two above a declarator whose documentation block
+// sits between it and the token before it.
+//
+// The last fallback is left as it was because no unit kind reaches it: every
+// form is created either from a declaration that carries a name or from an
+// identifier.
 func lineAtNode(_ string, node *shimast.Node) int {
   if node == nil {
     return 0
@@ -887,6 +1421,9 @@ func lineAtNode(_ string, node *shimast.Node) int {
   if name := node.Name(); name != nil && name.End() > 0 {
     return name.End() - 1
   }
+  if node.Kind == shimast.KindIdentifier && node.End() > 0 {
+    return node.End() - 1
+  }
   return node.Pos()
 }
 
@@ -958,10 +1495,15 @@ func collectTypeScriptDeclarations(
       docs[key] = current
     }
   })
+  attached := make(attachedCommentEnds, len(docs))
   keys := make([]string, 0, len(docs))
-  for key := range docs {
+  for key, entry := range docs {
     keys = append(keys, key)
+    if start, taken := attached[entry.node.End()]; !taken || entry.node.Pos() < start {
+      attached[entry.node.End()] = entry.node.Pos()
+    }
   }
+  reportUnreadableTypeScriptTags(file, location, attached, inventory)
   sort.Slice(keys, func(left int, right int) bool {
     leftNode := docs[keys[left]].node
     rightNode := docs[keys[right]].node
@@ -1006,11 +1548,31 @@ func collectTypeScriptDeclarations(
         Sequence:         sequence,
       })
     }
+    // Reviews are read from the same block by a separate pass into a separate
+    // slice. Sharing the declaration loop would put a review one field away
+    // from every acknowledgement map in evaluation.
+    for _, review := range parseReviews(content[entry.node.Pos():entry.node.End()]) {
+      inventory.Reviews = append(inventory.Reviews, &evidenceReview{
+        HostID:          hostID,
+        SemanticHostIDs: semanticHostIDs,
+        Reviews:         review.Reviews,
+        Type:            artifactTypeScript,
+        Target:          review.Target,
+        Fingerprint:     review.Fingerprint,
+        Description:     review.Description,
+        Path:            location,
+        Line:            baseLine + review.LineOffset,
+      })
+    }
   }
   for _, unit := range inventory.Units {
     // TypeScript AST positions are byte offsets; translate them only after
     // the complete source text is available.
     unit.Line = lineAt(content, unit.Line)
+    // The digest is deferred to the same pass for the same reason: the nodes
+    // are recorded while walking, and their text needs the source file that
+    // only the caller holds.
+    unit.Digest = typeScriptUnitDigest(file, inventory.UnitContent[unit.ID])
   }
 }
 
@@ -1197,3 +1759,74 @@ func encodeTypeScriptIdentity(identity []string) string {
   }
   return builder.String()
 }
+
+// matchesConfiguredTypeScriptFile reports whether a population rooted at this
+// base selects the file.
+//
+// The base is compared before the globs, for the reason the Markdown side
+// states: a walk covers one base at a time, and another base's patterns say
+// nothing about a path inside this one.
+func matchesConfiguredTypeScriptFile(
+  config graphConfig,
+  base populationBase,
+  path string,
+) bool {
+  for _, claim := range config.Claims {
+    if claim.Type == artifactTypeScript &&
+      claim.Base.Absolute == base.Absolute &&
+      claim.Files.matches(path) {
+      return true
+    }
+    for _, reference := range claim.References {
+      // A package reference reads an installed package from disk, and its
+      // globs are written as a consumer thinks of that package, so they
+      // resolve against the package root rather than the project. Matching
+      // them here against a project-relative path made `lib/**` claim a
+      // project's own `lib/`, and `**/*.ts` claim every file it has,
+      // including the `node_modules` this confinement exists to release.
+      if reference.Package != "" {
+        continue
+      }
+      if reference.Type == artifactTypeScript &&
+        reference.Base.Absolute == base.Absolute &&
+        reference.Files.matches(path) {
+        return true
+      }
+    }
+  }
+  return false
+}
+
+// recordGovernedTypeScriptFiles marks every address a declared population
+// selects.
+//
+// Separate from the scan because the two answer different questions. Scanning
+// is driven by the active configuration, since an inactive claim must make no
+// loader do work; governance is a property of what an author wrote, and a claim
+// that deactivated still declared its population. Reading them from one pass
+// silenced a file whose declarations were all commented out, which is exactly
+// the shape the diagnostic's second repair clause exists for.
+func recordGovernedTypeScriptFiles(
+  sources []*shimast.SourceFile,
+  declared graphConfig,
+  governed map[string]bool,
+) {
+  if governed == nil {
+    return
+  }
+  bases := configuredBases(declared, artifactTypeScript)
+  for _, file := range sources {
+    if file == nil || !isTypeScriptPath(file.FileName()) {
+      continue
+    }
+    for _, base := range bases {
+      relative, ok := relativeProjectPath(base.Absolute, file.FileName())
+      if !ok || !isTypeScriptPath(relative) {
+        continue
+      }
+      if matchesConfiguredTypeScriptFile(declared, base, relative) {
+        governed[base.addressOf(relative).Key] = true
+      }
+    }
+  }
+}