@ttsc/evidence 0.28.6 → 0.30.0

package/native/file_link.go

@@ -0,0 +1,370 @@
+package evidence
+
+import (
+  "encoding/json"
+  "net/url"
+  "path"
+  "path/filepath"
+  "sort"
+  "strings"
+  "unicode"
+)
+
+const fileLinkPrefix = "\x00file:"
+
+func isFileLinkTarget(target string) bool {
+  return strings.HasPrefix(target, fileLinkPrefix)
+}
+
+// splitFileLinkBody reads one address, allowing spaces only inside a quoted
+// accessor segment. Paths use percent encoding, so # always separates the file.
+func splitFileLinkBody(body string) (string, string, bool) {
+  forced := isFileLinkTarget(body)
+  if !forced {
+    for _, marker := range inlineLinkTags {
+      if strings.HasPrefix(body, marker) {
+        return "", "", false
+      }
+    }
+  }
+  body = strings.TrimPrefix(body, fileLinkPrefix)
+  file, _, qualified := strings.Cut(body, "#")
+  if decoded, err := url.PathUnescape(file); err == nil {
+    file = decoded
+  }
+  if !forced && (!qualified || !isTypeScriptPath(file)) {
+    return "", "", false
+  }
+  quoted, escaped := false, false
+  end := len(body)
+  for index, char := range body {
+    if escaped {
+      escaped = false
+      continue
+    }
+    if quoted && char == '\\' {
+      escaped = true
+      continue
+    }
+    if char == '"' {
+      quoted = !quoted
+    }
+    if !quoted && unicode.IsSpace(char) {
+      end = index
+      break
+    }
+  }
+  target := body[:end]
+  if target == "" {
+    return "", strings.TrimSpace(body[end:]), true
+  }
+  if link, problem := parseFileLink(target); problem == "" {
+    target = encodeFileLinkPath(link.File) + "#" + formatFileAccessor(link.Segments)
+  }
+  return fileLinkPrefix + target, strings.TrimSpace(body[end:]), true
+}
+
+type fileLink struct {
+  File     string
+  Segments []string
+}
+
+func parseFileLink(target string) (fileLink, string) {
+  target = strings.TrimPrefix(target, fileLinkPrefix)
+  file, accessor, found := strings.Cut(target, "#")
+  if !found || file == "" || accessor == "" {
+    return fileLink{}, "write a TypeScript file path followed by '#' and an exported declaration or member"
+  }
+  decoded, err := url.PathUnescape(file)
+  if err != nil || strings.ContainsAny(decoded, "\x00\r\n") || !isTypeScriptPath(decoded) {
+    return fileLink{}, "the file must be a TypeScript path with valid percent escapes; use %20 for a space and %23 for a literal '#'"
+  }
+  normalized := strings.ReplaceAll(decoded, "\\", "/")
+  // path.Clean collapses a UNC prefix; preserve that volume spelling.
+  unc := strings.HasPrefix(normalized, "//")
+  normalized = path.Clean(normalized)
+  if unc {
+    normalized = "/" + normalized
+  }
+  segments, problem := parseFileAccessor(accessor)
+  if problem != "" {
+    return fileLink{}, problem
+  }
+  return fileLink{File: normalized, Segments: segments}, ""
+}
+
+func parseFileAccessor(accessor string) ([]string, string) {
+  segments := []string{}
+  for len(accessor) != 0 {
+    if accessor[0] == '[' {
+      closing := -1
+      quoted, escaped := false, false
+      for index := 1; index < len(accessor); index++ {
+        char := accessor[index]
+        if escaped {
+          escaped = false
+          continue
+        }
+        if quoted && char == '\\' {
+          escaped = true
+          continue
+        }
+        if char == '"' {
+          quoted = !quoted
+        }
+        if !quoted && char == ']' {
+          closing = index
+          break
+        }
+      }
+      if closing < 0 {
+        return nil, "close the bracket accessor and its quoted member name"
+      }
+      literal := accessor[1:closing]
+      var segment string
+      if len(literal) > 0 && literal[0] == '"' {
+        if json.Unmarshal([]byte(literal), &segment) != nil {
+          return nil, "a bracket accessor must contain a JSON string or an unsigned integer"
+        }
+      } else {
+        if literal == "" || strings.Trim(literal, "0123456789") != "" || len(literal) > 1 && literal[0] == '0' {
+          return nil, "a bracket accessor must contain a JSON string or an unsigned integer"
+        }
+        segment = literal
+      }
+      segments = append(segments, segment)
+      accessor = accessor[closing+1:]
+    } else {
+      end := strings.IndexAny(accessor, ".[")
+      if end < 0 {
+        end = len(accessor)
+      }
+      segment := accessor[:end]
+      if !fileAccessorIdentifier(segment) {
+        return nil, "use dotted identifiers or brackets containing a JSON string for literal names"
+      }
+      segments = append(segments, segment)
+      accessor = accessor[end:]
+    }
+    if accessor == "" {
+      break
+    }
+    if accessor[0] == '.' {
+      accessor = accessor[1:]
+      if accessor == "" || accessor[0] == '[' {
+        return nil, "a dot must be followed by an identifier"
+      }
+    } else if accessor[0] != '[' {
+      return nil, "separate accessor segments with a dot or a bracket"
+    }
+  }
+  if len(segments) == 0 {
+    return nil, "name an exported declaration after '#'"
+  }
+  return segments, ""
+}
+
+func fileAccessorIdentifier(value string) bool {
+  for index, char := range value {
+    if char == '_' || char == '$' || unicode.IsLetter(char) || index > 0 && (unicode.IsDigit(char) || unicode.IsMark(char)) {
+      continue
+    }
+    return false
+  }
+  return value != ""
+}
+
+func formatFileAccessor(segments []string) string {
+  var result strings.Builder
+  for index, segment := range segments {
+    if fileAccessorIdentifier(segment) {
+      if index > 0 {
+        result.WriteByte('.')
+      }
+      result.WriteString(segment)
+    } else {
+      encoded, _ := json.Marshal(segment)
+      result.WriteByte('[')
+      result.Write(encoded)
+      result.WriteByte(']')
+    }
+  }
+  return result.String()
+}
+
+func encodeFileLinkPath(file string) string {
+  return (&url.URL{Path: file}).EscapedPath()
+}
+
+// resolveFileLinkDeclaration selects by module and segmented public accessor.
+// It never searches other files for a matching name. A review still annotates
+// this citation; the existing unit ID owns coverage and content fingerprints.
+func resolveFileLinkDeclaration(declaration *evidenceDeclaration, owners []claimState, loader *typeScriptLoader, index map[int]*fileLinkClaimIndex, context string) (string, string) {
+  where := " '" + displayTarget(declaration.Target) + "' at " + declaration.location() + " for " + context
+  if declaration.Type != artifactMarkdown && declaration.Type != artifactTypeScript {
+    return "", "Unsupported file-qualified evidence target" + where + ": use this syntax on a Markdown or TypeScript claim."
+  }
+  link, problem := parseFileLink(declaration.Target)
+  if problem != "" {
+    return "", "Malformed file-qualified evidence target" + where + ": " + problem + "."
+  }
+  absolute := filepath.FromSlash(link.File)
+  if !filepath.IsAbs(absolute) {
+    absolute = filepath.Join(filepath.Dir(resolveProjectPath(loader.root, declaration.Path)), absolute)
+  }
+  module := loader.projectPath(filepath.ToSlash(absolute))
+  identity, _ := loader.moduleIdentity(module)
+  candidates := map[string]*evidenceUnit{}
+  hidden := map[string]*evidenceUnit{}
+  selectedModule := false
+  key := scopedTargetKey{path: identity, target: encodeTypeScriptIdentity(link.Segments)}
+  for _, owner := range owners {
+    claim := index[owner.Spec.Index]
+    if claim == nil {
+      continue
+    }
+    selectedModule = selectedModule || claim.modules[identity]
+    for id, unit := range claim.targets[key] {
+      candidates[id] = unit
+    }
+    for id, unit := range claim.hidden[key] {
+      hidden[id] = unit
+    }
+  }
+  dynamic, withdrawn := queryFileLinkClaims(index, owners, identity, link.Segments, false)
+  for id, unit := range dynamic {
+    candidates[id] = unit
+  }
+  for id, unit := range withdrawn {
+    hidden[id] = unit
+  }
+  if len(candidates) == 1 {
+    for id := range candidates {
+      return id, ""
+    }
+  }
+  if len(candidates) > 1 {
+    descriptions := []string{}
+    for _, unit := range candidates {
+      descriptions = append(descriptions, unit.Readable+" at "+unit.location())
+    }
+    sort.Strings(descriptions)
+    return "", "Ambiguous file-qualified evidence target" + where + ": " + strings.Join(descriptions, "; ") + ". Select one symbol kind or an unambiguous public accessor."
+  }
+  if len(hidden) != 0 {
+    ids := []string{}
+    for id := range hidden {
+      ids = append(ids, id)
+    }
+    sort.Strings(ids)
+    return "", hiddenTargetProblem(declaration, hidden[ids[0]], context)
+  }
+  if !loader.exists(module) {
+    return "", "Missing TypeScript evidence file" + where + ": '" + module + "' does not exist. Correct the path relative to the citing file or restore the configured file."
+  }
+  if !selectedModule {
+    return "", "Out-of-population TypeScript evidence target" + where + ": '" + module + "' is not a module selected by this claim's TypeScript references. Configure its files and, for disk sources outside the Program, an explicit root."
+  }
+  if declarationResolutionUncertain(owners) {
+    return "", ""
+  }
+  return "", diagnoseFileLinkTarget(loader, module, link.Segments, where)
+}
+
+type fileLinkClaimIndex struct {
+  references map[string][]fileLinkReference
+  modules    map[string]bool
+  targets    map[scopedTargetKey]map[string]*evidenceUnit
+  hidden     map[scopedTargetKey]map[string]*evidenceUnit
+}
+
+// Build once per evaluation. Resolution is proportional to the number of
+// owning claims, not their complete populations for every citation.
+func indexFileLinkClaims(states []claimState, loader *typeScriptLoader) map[int]*fileLinkClaimIndex {
+  result := map[int]*fileLinkClaimIndex{}
+  for _, state := range states {
+    index := &fileLinkClaimIndex{modules: map[string]bool{}, targets: map[scopedTargetKey]map[string]*evidenceUnit{}, hidden: map[scopedTargetKey]map[string]*evidenceUnit{}, references: map[string][]fileLinkReference{}}
+    result[state.Spec.Index] = index
+    for _, reference := range state.References {
+      if reference.Spec.Type != artifactTypeScript {
+        continue
+      }
+      scopes := map[string]bool{}
+      for _, scope := range reference.Scopes {
+        scopes[scope.ID] = true
+      }
+      if reference.Code != nil {
+        modules := map[string]string{}
+        for _, entry := range reference.Paths {
+          identity, _ := loader.moduleIdentity(entry)
+          modules[identity] = entry
+        }
+        for _, address := range reference.Published {
+          identity, _ := loader.moduleIdentity(address.Module)
+          modules[identity] = address.Module
+        }
+        hidden := map[string]bool{}
+        for _, unit := range reference.Hidden {
+          hidden[unit.ID] = true
+        }
+        for identity, entry := range modules {
+          index.references[identity] = append(index.references[identity], fileLinkReference{entry: entry, code: reference.Code, scopes: scopes, hidden: hidden})
+        }
+      }
+      for _, entry := range reference.Paths {
+        module, _ := loader.moduleIdentity(entry)
+        index.modules[module] = true
+      }
+      for _, address := range reference.Published {
+        module, _ := loader.moduleIdentity(address.Module)
+        index.modules[module] = true
+        key := scopedTargetKey{path: module, target: encodeTypeScriptIdentity(address.Segments)}
+        target := index.targets
+        if address.Unit.Hidden != "" {
+          target = index.hidden
+        } else if !scopes[address.Unit.ID] {
+          continue
+        }
+        if target[key] == nil {
+          target[key] = map[string]*evidenceUnit{}
+        }
+        target[key][address.Unit.ID] = address.Unit
+      }
+    }
+  }
+  return result
+}
+
+type fileLinkReference struct {
+  entry  string
+  code   *typeScriptExportResolver
+  scopes map[string]bool
+  hidden map[string]bool
+}
+
+// Namespace cycles have infinitely many possible spellings but a citation has
+// finitely many segments. Resolve that path on demand, then apply the same
+// reference membership as the finite population index.
+func queryFileLinkClaims(index map[int]*fileLinkClaimIndex, owners []claimState, module string, segments []string, legacy bool) (map[string]*evidenceUnit, map[string]*evidenceUnit) {
+  found, hidden := map[string]*evidenceUnit{}, map[string]*evidenceUnit{}
+  for _, owner := range owners {
+    claim := index[owner.Spec.Index]
+    if claim == nil {
+      continue
+    }
+    for _, reference := range claim.references[module] {
+      for _, unit := range reference.code.lookup(reference.entry, segments, legacy) {
+        if unit.Hidden != "" {
+          if reference.hidden[unit.ID] {
+            hidden[unit.ID] = unit
+          }
+          continue
+        }
+        if reference.scopes[unit.ID] {
+          found[unit.ID] = unit
+        }
+      }
+    }
+  }
+  return found, hidden
+}

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