@ttsc/evidence 0.29.0 → 0.30.0

package/native/file_link_diagnostics.go

@@ -0,0 +1,160 @@
+package evidence
+
+import (
+  "sort"
+
+  shimast "github.com/microsoft/typescript-go/shim/ast"
+)
+
+// Diagnostic inspection never creates an obligation. It distinguishes a
+// declaration the collector intentionally withheld from a misspelled address.
+func diagnoseFileLinkTarget(loader *typeScriptLoader, module string, segments []string, where string) string {
+  inventory := loader.inventory(module)
+  if inventory == nil {
+    return "Unreadable TypeScript evidence target" + where + ": " + loader.failure(module) + ". Restore the configured source file."
+  }
+  resolver := newTypeScriptExportResolver(loader, []string{module})
+  if len(resolver.lookup(module, segments, false)) != 0 {
+    return "Unselected TypeScript evidence target" + where + ": the declaration exists but this reference's files or symbol selection does not admit it. Select its symbol kind or cite a selected declaration."
+  }
+  exports := resolver.accessor(module, segments, nil, false, false)
+  sort.SliceStable(exports, func(left, right int) bool { return len(exports[left].Address) > len(exports[right].Address) })
+  for _, exported := range exports {
+    if exported.Local == "" {
+      namespace := formatFileAccessor(exported.Address)
+      if len(exported.Address) == len(segments) {
+        return "Unsupported TypeScript evidence target" + where + ": '" + namespace + "' is a module namespace, not a declared evidence unit. Cite a supported declaration inside it."
+      }
+      return "Missing TypeScript evidence export" + where + ": the module namespace '" + namespace + "' exports no declaration named '" + segments[len(exported.Address)] + "'. Correct the name inside that namespace."
+    }
+    if len(exported.Address) > len(segments) {
+      continue
+    }
+    if encodeTypeScriptIdentity(exported.Address) != encodeTypeScriptIdentity(segments[:len(exported.Address)]) {
+      continue
+    }
+    source := loader.inventory(exported.Path)
+    if source == nil || source.Source == nil {
+      continue
+    }
+    local := exported.Local
+    // Inventories use public local aliases, while the AST uses bindings.
+    for _, entry := range source.Exports {
+      if entry.Specifier == "" && entry.Public == local && entry.Local != "" {
+        local = entry.Local
+        break
+      }
+    }
+    tail := append([]string{local}, segments[len(exported.Address):]...)
+    if exported.TypeOnly {
+      identity := append([]string{exported.Local}, segments[len(exported.Address):]...)
+      for _, unit := range source.Units {
+        if unit.ValueSpace && !unit.TypeSpace && encodeTypeScriptIdentity(unit.Identity) == encodeTypeScriptIdentity(identity) {
+          return "Type-only TypeScript evidence target" + where + ": this export exposes no value through which the member can be addressed. Use a public value export or cite its type."
+        }
+      }
+    }
+    if cause := inspectUnavailableDeclaration(source.Source.Statements, tail); cause != "" {
+      return "Unsupported TypeScript evidence target" + where + ": " + cause + ". Cite a supported public declaration."
+    }
+    if len(segments) > len(exported.Address) {
+      return "Missing TypeScript evidence member" + where + ": the exported declaration has no addressable member '" + formatFileAccessor(segments[len(exported.Address):]) + "'. Correct the member name and use '.prototype' for an instance member."
+    }
+    return "Unsupported TypeScript evidence declaration" + where + ": the export is not a supported type, function, or property unit. Cite a supported declaration."
+  }
+  if inventory.Source != nil && inventory.Source.Statements != nil {
+    for _, statement := range inventory.Source.Statements.Nodes {
+      if statement == nil {
+        continue
+      }
+      for _, declared := range topLevelDeclaredNames(statement) {
+        if declared.Name == segments[0] {
+          return "Unexported TypeScript evidence declaration" + where + ": '" + segments[0] + "' is a local binding, not a public export of this module. Use its public alias or default export."
+        }
+      }
+    }
+  }
+  if cause := inspectUnavailableDeclaration(inventory.Source.Statements, segments); cause != "" {
+    return "Unsupported TypeScript evidence target" + where + ": " + cause + ". Export a supported declaration or correct the target."
+  }
+  return "Missing TypeScript evidence export" + where + ": the module exports no declaration named '" + segments[0] + "'. Use its public export name or correct the file."
+}
+
+func inspectUnavailableDeclaration(statements *shimast.NodeList, segments []string) string {
+  if statements == nil || len(segments) == 0 {
+    return ""
+  }
+  for _, statement := range statements.Nodes {
+    if statement == nil {
+      continue
+    }
+    if typeScriptDeclarationName(statement) != segments[0] {
+      continue
+    }
+    if len(segments) == 1 {
+      if !isSyntacticallyExported(statement) {
+        return "the declaration is not exported"
+      }
+      return "the declaration form is not supported by the evidence unit model"
+    }
+    tail := segments[1:]
+    var members *shimast.NodeList
+    class := statement.Kind == shimast.KindClassDeclaration
+    switch statement.Kind {
+    case shimast.KindClassDeclaration:
+      members = statement.AsClassDeclaration().Members
+    case shimast.KindInterfaceDeclaration:
+      members = statement.AsInterfaceDeclaration().Members
+    case shimast.KindTypeAliasDeclaration:
+      node := statement.AsTypeAliasDeclaration().Type
+      if node != nil && node.Kind == shimast.KindTypeLiteral {
+        members = node.AsTypeLiteralNode().Members
+      }
+    case shimast.KindModuleDeclaration:
+      body := statement.AsModuleDeclaration().Body
+      if body != nil && body.Kind == shimast.KindModuleBlock {
+        return inspectUnavailableDeclaration(body.AsModuleBlock().Statements, tail)
+      }
+    }
+    instance := class && len(tail) > 1 && tail[0] == "prototype"
+    if instance {
+      tail = tail[1:]
+    }
+    if members == nil || len(tail) != 1 {
+      continue
+    }
+    for _, member := range members.Nodes {
+      if member != nil && member.Kind == shimast.KindConstructor && instance {
+        for _, parameter := range member.Parameters() {
+          if parameter != nil && isParameterProperty(parameter) && declarationName(parameter.Name()) == tail[0] && !isPublicClassMember(parameter) {
+            return "the member is private or protected"
+          }
+        }
+      }
+      if member == nil || member.Name() == nil {
+        continue
+      }
+      name := member.Name()
+      if name.Kind != shimast.KindIdentifier && name.Kind != shimast.KindPrivateIdentifier && name.Kind != shimast.KindStringLiteral && name.Kind != shimast.KindNumericLiteral {
+        continue
+      }
+      if name.Text() != tail[0] {
+        continue
+      }
+      if class {
+        static := shimast.GetCombinedModifierFlags(member)&shimast.ModifierFlagsStatic != 0
+        if static == instance {
+          continue
+        }
+        if !isPublicClassMember(member) || name.Kind == shimast.KindPrivateIdentifier {
+          return "the member is private or protected"
+        }
+      }
+      if member.Kind == shimast.KindGetAccessor || member.Kind == shimast.KindSetAccessor || member.ModifierFlags()&shimast.ModifierFlagsAccessor != 0 {
+        return "accessors are not evidence units"
+      }
+      return "the member is not exposed as a supported public evidence unit"
+    }
+  }
+  return ""
+}

package/native/fingerprint.go

@@ -161,12 +161,12 @@ func (index *scopeIndex) compute(rootID string) string {
   if len(scope) == 0 {
     return ""
   }
-  // Ordered by address rather than by walk order, so the value does not depend
+  // Ordered by identity rather than by walk order, so the value does not depend
   // on which file the loader happened to read first, and by symbol as well
   // because two same-titled Markdown headings answer to one anchor.
   sort.Slice(scope, func(left int, right int) bool {
-    if scope[left].Target != scope[right].Target {
-      return scope[left].Target < scope[right].Target
+    if fingerprintIdentity(scope[left]) != fingerprintIdentity(scope[right]) {
+      return fingerprintIdentity(scope[left]) < fingerprintIdentity(scope[right])
     }
     if scope[left].Symbol != scope[right].Symbol {
       return scope[left].Symbol < scope[right].Symbol
@@ -178,7 +178,7 @@ func (index *scopeIndex) compute(rootID string) string {
     // NUL separates the fields because a target may contain any printable
     // character, and a joined pair that can be re-split ambiguously lets two
     // different scopes compose one digest.
-    composite.Write([]byte(unit.Target))
+    composite.Write([]byte(fingerprintIdentity(unit)))
     composite.Write([]byte{0})
     composite.Write([]byte(unit.Symbol))
     composite.Write([]byte{0})
@@ -188,6 +188,35 @@ func (index *scopeIndex) compute(rootID string) string {
   return presentedFingerprint(hex.EncodeToString(composite.Sum(nil)))
 }
 
+func fingerprintIdentity(unit *evidenceUnit) string {
+  if unit.Type == artifactTypeScript {
+    return unit.ID
+  }
+  return unit.Target
+}
+
+// A code review fingerprints the declaring inventory, before any public alias
+// or type-only edge projects its surface. Selection controls permission and
+// coverage; it cannot make one citation require multiple content fingerprints.
+func referenceReviewScopes(reference referenceState, loader *typeScriptLoader) *scopeIndex {
+  units := append(append([]*evidenceUnit{}, reference.Population...), reference.Hidden...)
+  if reference.Spec.Type != artifactTypeScript {
+    return newScopeIndex(units)
+  }
+  seen := map[string]bool{}
+  canonical := []*evidenceUnit{}
+  for _, unit := range units {
+    if seen[unit.Path] {
+      continue
+    }
+    seen[unit.Path] = true
+    if inventory := loader.inventory(unit.Path); inventory != nil {
+      canonical = append(canonical, inventory.Units...)
+    }
+  }
+  return newScopeIndex(canonical)
+}
+
 // scopeContribution is what one unit adds to its scope's composite.
 //
 // A withdrawn unit contributes the tag that withdrew it. That is what makes a

package/native/graph.go

@@ -378,6 +378,12 @@ func materializeClaimStates(
         continue
       }
       if reference.Type == artifactTypeScript {
+        if reference.Rooted {
+          rootedState, rootedProblems := materializeRootedTypeScriptReference(claim, reference, loader)
+          problems = problems.add(severity, rootedProblems...)
+          state.References = append(state.References, rootedState)
+          continue
+        }
         localState, localProblems := materializeLocalTypeScriptReference(
           claim,
           reference,
@@ -607,6 +613,7 @@ func evaluateEvidenceGraph(
   sort.Strings(declarationIDs)
 
   resolved := map[string]string{}
+  fileLinks := indexFileLinkClaims(states, loader)
   for _, id := range declarationIDs {
     severity := ownerSeverity(owners[id])
     declaration := declarations[id]
@@ -618,12 +625,23 @@ func evaluateEvidenceGraph(
       )
       continue
     }
+    if isFileLinkTarget(declaration.Target) {
+      unitID, problem := resolveFileLinkDeclaration(declaration, owners[id], loader, fileLinks, context)
+      if problem != "" {
+        problems = problems.add(severity, problem)
+      } else {
+        resolved[id] = unitID
+      }
+      continue
+    }
     if isInlineLinkTarget(declaration.Target) {
       unitID, problem := resolveInlineLinkDeclaration(
         declaration,
         loader,
         scopedTargets,
         scopedHidden,
+        fileLinks,
+        states,
         context,
       )
       if problem != "" {
@@ -655,7 +673,7 @@ func evaluateEvidenceGraph(
       if len(addressable) == 0 && len(code) != 0 {
         problems = problems.add(
           severity,
-          "Code evidence target '"+declaration.Target+"' at "+declaration.location()+" for "+context+": a "+string(declaration.Type)+" claim cannot cite a TypeScript symbol, because a symbol citation resolves through the citing module's imports and this artifact has none. Invert the obligation so the code cites this artifact, or move the citation into TypeScript.",
+          "Code evidence target '"+declaration.Target+"' at "+declaration.location()+" for "+context+": an unqualified symbol has no module identity in this artifact. In Markdown, write '@link <file.ts>#<Accessor> <reason>' using a path relative to this document. Otherwise move the citation to a TypeScript claim.",
         )
         continue
       }
@@ -935,12 +953,7 @@ func evaluateEvidenceGraph(
             // Withdrawn units are absent from Population by construction, and
             // the scope composite still needs their identities so a member
             // leaving the public surface moves the fingerprint.
-            reviewScopes = newScopeIndex(
-              append(
-                append([]*evidenceUnit{}, reference.Population...),
-                reference.Hidden...,
-              ),
-            )
+            reviewScopes = referenceReviewScopes(reference, loader)
           }
           if reviewLedgerForClaim == nil {
             reviewLedgerForClaim = newReviewLedger(state.Reviews)
@@ -1448,6 +1461,7 @@ func materializeEntryReference(
   state.Units = population.Units
   state.Hidden = population.Hidden
   state.Published = population.Published
+  state.Code = population.Code
   if failure := loader.failure(entry); failure != "" {
     state.Healthy = false
     return state, []string{
@@ -1539,6 +1553,7 @@ func materializeLocalTypeScriptReference(
   state.Units = population.Units
   state.Hidden = population.Hidden
   state.Published = population.Published
+  state.Code = population.Code
   applyTraversedScopes(&state, population.Reached)
   if !state.Healthy {
     return state, nil
@@ -1624,6 +1639,7 @@ func materializePackageGlobReference(
   state.Units = population.Units
   state.Hidden = population.Hidden
   state.Published = population.Published
+  state.Code = population.Code
   applyTraversedScopes(&state, population.Reached)
   if !state.Healthy {
     return state, problems
@@ -1691,6 +1707,8 @@ func resolveInlineLinkDeclaration(
   loader *typeScriptLoader,
   scopedTargets map[scopedTargetKey]map[string]*evidenceUnit,
   scopedHidden map[scopedTargetKey]*evidenceUnit,
+  fileLinks map[int]*fileLinkClaimIndex,
+  states []claimState,
   context string,
 ) (string, string) {
   target := inlineLinkTarget(declaration.Target)
@@ -1721,7 +1739,19 @@ func resolveInlineLinkDeclaration(
     return "", "Incomplete evidence target '" + displayTarget(declaration.Target) + "' at " + declaration.location() + " for " + context + ": a namespace import names a module rather than a unit. Name a symbol inside '" + binding.Specifier + "' that the named reference selects."
   }
   name := strings.Join(remaining, ".")
-  candidates := scopedTargets[scopedTargetKey{path: resolvedPath, target: name}]
+  identity, _ := loader.moduleIdentity(resolvedPath)
+  candidates, hidden := queryFileLinkClaims(fileLinks, states, identity, remaining, true)
+  for id, unit := range scopedTargets[scopedTargetKey{path: resolvedPath, target: name}] {
+    candidates[id] = unit
+  }
+  if len(candidates) == 0 && len(hidden) != 0 {
+    ids := make([]string, 0, len(hidden))
+    for id := range hidden {
+      ids = append(ids, id)
+    }
+    sort.Strings(ids)
+    return "", hiddenTargetProblem(declaration, hidden[ids[0]], context)
+  }
   switch len(candidates) {
   case 0:
     if hidden := scopedHidden[scopedTargetKey{

package/native/imports.go

@@ -19,6 +19,7 @@ type importBinding struct {
   Specifier string
   Imported  string
   Namespace bool
+  TypeOnly  bool
 }
 
 // collectImportBindings indexes a file's imports by the local name each binds.
@@ -52,6 +53,7 @@ func collectImportBindings(file *shimast.SourceFile) map[string]importBinding {
         Local:     name,
         Specifier: specifier,
         Imported:  "default",
+        TypeOnly:  clause.IsTypeOnly(),
       }
     }
     if clause.NamedBindings == nil {
@@ -64,6 +66,7 @@ func collectImportBindings(file *shimast.SourceFile) map[string]importBinding {
           Local:     name,
           Specifier: specifier,
           Namespace: true,
+          TypeOnly:  clause.IsTypeOnly(),
         }
       }
     case shimast.KindNamedImports:
@@ -91,6 +94,7 @@ func collectImportBindings(file *shimast.SourceFile) map[string]importBinding {
           Local:     local,
           Specifier: specifier,
           Imported:  imported,
+          TypeOnly:  clause.IsTypeOnly() || specifierNode.IsTypeOnly,
         }
       }
     }
@@ -124,19 +128,28 @@ var typeScriptModuleExtensions = []string{
 // must spell its sibling as `./x.js`, so refusing to map it back would make the
 // correct import form unresolvable.
 func moduleCandidates(base string) []string {
-  candidates := []string{base}
-  stripped := base
-  for _, emitted := range []string{".js", ".mjs", ".cjs"} {
-    if strings.HasSuffix(base, emitted) {
-      stripped = strings.TrimSuffix(base, emitted)
-      break
+  if isTypeScriptPath(base) {
+    return []string{base}
+  }
+  substitutions := map[string][]string{
+    ".js":  {".ts", ".tsx", ".d.ts"},
+    ".mjs": {".mts", ".d.mts"},
+    ".cjs": {".cts", ".d.cts"},
+  }
+  if extensions, emitted := substitutions[path.Ext(base)]; emitted {
+    stripped := strings.TrimSuffix(base, path.Ext(base))
+    candidates := make([]string, 0, len(extensions))
+    for _, extension := range extensions {
+      candidates = append(candidates, stripped+extension)
     }
+    return candidates
   }
+  candidates := []string{}
   for _, extension := range typeScriptModuleExtensions {
-    candidates = append(candidates, stripped+extension)
+    candidates = append(candidates, base+extension)
   }
   for _, extension := range typeScriptModuleExtensions {
-    candidates = append(candidates, path.Join(stripped, "index"+extension))
+    candidates = append(candidates, path.Join(base, "index"+extension))
   }
   return candidates
 }

package/native/inputs.go

@@ -35,10 +35,8 @@ func (graphRule) ProjectInputs(ctx *rule.ProjectInputContext) []rule.ProjectInpu
 // graphProjectInputs collects the external dependency of every configured
 // obligation.
 //
-// TypeScript claims and references are absent by design. Their inventories are
-// materialized from `ctx.Sources`, which is the Program the host already
-// watches, so declaring them again would ask for a second watcher on a file
-// that already has one.
+// Program sources are already watched. Rooted TypeScript references additionally
+// declare the directory containing their disk-loaded export closure.
 func graphProjectInputs(config graphConfig) []rule.ProjectInput {
   config = enabledGraphConfig(config)
   inputs := []rule.ProjectInput{}
@@ -49,6 +47,17 @@ func graphProjectInputs(config graphConfig) []rule.ProjectInput {
     }
     for _, reference := range claim.References {
       switch reference.Type {
+      case artifactTypeScript:
+        if reference.Rooted {
+          // Export traversal can reach a module outside the entry globs, and
+          // this pre-Program protocol cannot discover that closure. The root
+          // is its explicit boundary, including future files and repairs.
+          pattern := "**"
+          if reference.Root != "" {
+            pattern = strings.TrimSuffix(reference.Root, "/") + "/**"
+          }
+          inputs = append(inputs, rule.ProjectInput{Kind: rule.ProjectInputGlob, Pattern: pattern})
+        }
       case artifactMarkdown, artifactPrisma:
         inputs = append(inputs, globInputs(reference.Root, reference.Files)...)
       case artifactSwagger: