@ttsc/evidence 0.29.0 → 0.30.0

package/native/exports.go

@@ -13,6 +13,9 @@ import (
 // another. Keeping the two apart is what lets identity stay with the declaring
 // file while reachability is decided by whoever re-exports it.
 type moduleExport struct {
+  // Identity overrides the local unit name for a default alias. The alias
+  // adds reachability without materializing a second declaration.
+  Identity string
   // Public is the name an importer sees. Empty for `export * from`, which
   // contributes its target's names rather than a name of its own.
   Public string
@@ -49,6 +52,7 @@ func collectModuleExports(file *shimast.SourceFile) []moduleExport {
     return exports
   }
   locals := collectLocalExportNames(file.Statements)
+  defaults := collectDefaultExportBindings(file.Statements)
   for _, statement := range file.Statements.Nodes {
     if statement == nil {
       continue
@@ -60,6 +64,13 @@ func collectModuleExports(file *shimast.SourceFile) []moduleExport {
     if !isSyntacticallyExported(statement) {
       continue
     }
+    if isDefaultExported(statement) {
+      name := typeScriptDeclarationName(statement)
+      if name != "" {
+        exports = append(exports, moduleExport{Public: "default", Local: name, Identity: name})
+      }
+      continue
+    }
     for _, declared := range topLevelDeclaredNames(statement) {
       exports = append(exports, moduleExport{
         Public: declared.Name,
@@ -68,8 +79,9 @@ func collectModuleExports(file *shimast.SourceFile) []moduleExport {
       for _, exported := range locals[declared.Name] {
         if exported.Public != declared.Name {
           exports = append(exports, moduleExport{
-            Public: exported.Public,
-            Local:  declared.Name,
+            Public:   exported.Public,
+            Local:    declared.Name,
+            TypeOnly: exported.TypeOnly,
           })
         }
       }
@@ -77,15 +89,41 @@ func collectModuleExports(file *shimast.SourceFile) []moduleExport {
   }
   for local, names := range locals {
     for _, exported := range names {
-      if exported.Public == "" {
+      if exported.Public == "" || exported.IdentityOnly {
         continue
       }
       exports = append(exports, moduleExport{
-        Public: exported.Public,
-        Local:  local,
+        Public:   exported.Public,
+        Local:    local,
+        TypeOnly: exported.TypeOnly,
       })
     }
   }
+  for local, binding := range defaults {
+    identity := local
+    chosen := false
+    for _, name := range locals[local] {
+      if !binding.TypeOnly && name.TypeOnly && !name.ValueIdentity {
+        continue
+      }
+      if !chosen || name.Public < identity {
+        identity, chosen = name.Public, true
+      }
+    }
+    exports = append(exports, moduleExport{Public: "default", Local: local, Identity: identity, TypeOnly: binding.TypeOnly})
+  }
+  imports := collectImportBindings(file)
+  for index := range exports {
+    export := &exports[index]
+    if export.Specifier != "" {
+      continue
+    }
+    if binding, imported := imports[export.Local]; imported {
+      export.Specifier, export.Imported, export.Namespace = binding.Specifier, binding.Imported, binding.Namespace
+      export.Identity = ""
+      export.TypeOnly = export.TypeOnly || binding.TypeOnly
+    }
+  }
   return dedupeModuleExports(exports)
 }
 
@@ -181,6 +219,7 @@ func dedupeModuleExports(exports []moduleExport) []moduleExport {
 // yields: the obligations, the scopes above them, and the addresses that reach
 // them.
 type traversedPopulation struct {
+  Code    *typeScriptExportResolver
   Units   []*evidenceUnit
   Reached []*evidenceUnit
   // Hidden are the reached declarations that withdrew themselves from the
@@ -198,9 +237,10 @@ type traversedPopulation struct {
 // several selected modules publish the same declaration: each address is legal
 // exactly where it is written, and none of them is legal everywhere.
 type publishedAddress struct {
-  Module  string
-  Address string
-  Unit    *evidenceUnit
+  Module   string
+  Address  string
+  Segments []string
+  Unit     *evidenceUnit
 }
 
 type reachedSymbol struct {
@@ -208,7 +248,8 @@ type reachedSymbol struct {
   Address []string
   // Path is the file that declares the symbol, which owns its identity.
   Path string
-  // Local is the name that file's inventory gives the declaration, which is
+  // Local is empty for a module namespace, which publishes names but declares
+  // no evidence unit. Otherwise it is the name that file's inventory gives the declaration, which is
   // the name it exposes rather than the binding it wrote. `export { a as b }`
   // declares one unit called `b`, so matching on `a` would find nothing.
   Local string
@@ -219,123 +260,6 @@ type reachedSymbol struct {
   TypeOnly bool
 }
 
-// traverseEntryExports walks a module's export graph and reports every public
-// symbol it reaches, with the address the entry gives it.
-//
-// Membership comes from reachability and identity comes from the declaring
-// file, so a symbol re-exported through two barrels is reached twice and still
-// resolves to one unit. Cycles are bounded by the visited set: a barrel that
-// re-exports itself is a real shape, not a reason to hang the build.
-func traverseEntryExports(
-  loader *typeScriptLoader,
-  entry string,
-  prefix []string,
-  visited map[string]bool,
-  typeOnly bool,
-) []reachedSymbol {
-  if visited[entry] {
-    return nil
-  }
-  visited[entry] = true
-  defer delete(visited, entry)
-
-  inventory := loader.inventory(entry)
-  if inventory == nil {
-    return nil
-  }
-  reached := []reachedSymbol{}
-  // Named re-exports are grouped by the module they come from and that module
-  // is walked once. Walking it per specifier would re-traverse the whole
-  // subtree for every name a barrel forwards, which is quadratic on exactly
-  // the wide generated barrels this selection exists to describe.
-  surfaces := map[string]map[string]reachedSymbol{}
-  surfaceOf := func(target string) map[string]reachedSymbol {
-    if surface, built := surfaces[target]; built {
-      return surface
-    }
-    surface := map[string]reachedSymbol{}
-    for _, nested := range traverseEntryExports(loader, target, nil, visited, false) {
-      if len(nested.Address) != 1 {
-        continue
-      }
-      existing, taken := surface[nested.Address[0]]
-      // First wins, because two paths to one declaration name the same unit and
-      // the entry has to keep describing a path that exists.
-      //
-      // The type-only mark is unioned, and only between paths to the same
-      // declaration. It differs per path while the population is the union of
-      // what the paths reach, so a value path has to clear a type-only one
-      // rather than lose to declaration order. Doing that unconditionally is
-      // two different mistakes: replacing the entry swaps `Path` and `Local`,
-      // and clearing the mark alone leaves `Path` from one entry with the mark
-      // from another, which is a combination no path produced. Two entries
-      // under one name are not always one declaration, since an explicit named
-      // re-export shadows a star, and either mistake publishes the value
-      // members of a declaration this module reaches type-only.
-      switch {
-      case !taken:
-        surface[nested.Address[0]] = nested
-      case existing.TypeOnly && !nested.TypeOnly &&
-        existing.Path == nested.Path && existing.Local == nested.Local:
-        existing.TypeOnly = false
-        surface[nested.Address[0]] = existing
-      }
-    }
-    surfaces[target] = surface
-    return surface
-  }
-  for _, export := range inventory.Exports {
-    if export.Specifier == "" {
-      // A declaration this module exposes is inventoried under the name it
-      // exposes it as. `export { local as renamed }` is one unit named
-      // `renamed`, so the local binding never identifies it.
-      reached = append(reached, reachedSymbol{
-        Address:  append(append([]string{}, prefix...), export.Public),
-        Path:     entry,
-        Local:    export.Public,
-        TypeOnly: typeOnly,
-      })
-      continue
-    }
-    target := loader.resolve(entry, export.Specifier)
-    if target == "" {
-      continue
-    }
-    switch {
-    case export.Namespace:
-      reached = append(reached, traverseEntryExports(
-        loader,
-        target,
-        append(append([]string{}, prefix...), export.Public),
-        visited,
-        typeOnly || export.TypeOnly,
-      )...)
-    case export.Imported == "":
-      reached = append(reached, traverseEntryExports(
-        loader,
-        target,
-        prefix,
-        visited,
-        typeOnly || export.TypeOnly,
-      )...)
-    default:
-      nested, found := surfaceOf(target)[export.Imported]
-      if !found {
-        continue
-      }
-      reached = append(reached, reachedSymbol{
-        Address: append(append([]string{}, prefix...), export.Public),
-        Path:    nested.Path,
-        Local:   nested.Local,
-        // The edge into this module and every edge the target itself walked
-        // both count, so a type-only hop anywhere on the path withholds.
-        TypeOnly: typeOnly || export.TypeOnly || nested.TypeOnly,
-      })
-    }
-  }
-  return reached
-}
-
 // materializeEntryUnits turns reached symbols into the units an obligation
 // counts, giving each its entry-relative address.
 //
@@ -362,8 +286,9 @@ func materializeEntryUnits(
   order := []string{}
   published := []publishedAddress{}
   candidates := newOwnedUnitIndex(loader)
+  exports := newTypeScriptExportResolver(loader, entries)
   for _, entry := range entries {
-    for _, symbol := range traverseEntryExports(loader, entry, nil, map[string]bool{}, false) {
+    for _, symbol := range exports.traverse(entry, nil, map[string]bool{}, false) {
       if symbol.Local == "" {
         continue
       }
@@ -403,14 +328,15 @@ func materializeEntryUnits(
           }
         }
         published = append(published, publishedAddress{
-          Module:  entry,
-          Address: target,
-          Unit:    current,
+          Module:   entry,
+          Address:  target,
+          Segments: append([]string{}, address...),
+          Unit:     current,
         })
       }
     }
   }
-  population := traversedPopulation{Published: published}
+  population := traversedPopulation{Published: published, Code: exports}
   for _, id := range order {
     unit := byID[id]
     sort.Strings(unit.Aliases)
@@ -460,6 +386,7 @@ func narrowTraversedPopulation(
     withdrawn[unit.ID] = true
   }
   narrowed := traversedPopulation{
+    Code:      published.Code,
     Reached:   published.Reached,
     Published: published.Published,
   }
@@ -509,26 +436,17 @@ func (index *ownedUnitIndex) of(path string, local string) []*evidenceUnit {
     }
     index.byPath[path] = roots
   }
-  root := local
-  if cut := strings.Index(local, "."); cut != -1 {
-    root = local[:cut]
-  }
-  return roots[root]
+  return roots[local]
 }
 
 // identitySuffix reports the segments below a reached declaration, and whether
 // the unit belongs to it at all.
 func identitySuffix(identity []string, local string) ([]string, bool) {
-  owner := strings.Split(local, ".")
-  if len(identity) < len(owner) {
+  // Local is one module export, including a quoted name containing a dot.
+  if len(identity) == 0 || identity[0] != local {
     return nil, false
   }
-  for index, segment := range owner {
-    if identity[index] != segment {
-      return nil, false
-    }
-  }
-  return identity[len(owner):], true
+  return identity[1:], true
 }
 
 func containsString(values []string, wanted string) bool {

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
+}