@ttsc/evidence 0.29.0 → 0.30.0

package/lib/structures/ITtscEvidenceGraphTypeScriptReference.d.ts

@@ -13,13 +13,25 @@ import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphRefere
  * contracts deserve documentary proof.
  */
 export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGraphReferenceBase<"typescript"> {
+    /**
+     * Explicit directory whose TypeScript exports are read from disk.
+     *
+     * Resolves relative to the lint project's root, or accepts an absolute path.
+     * Files patterns select entry modules relative to this directory. Their
+     * re-exports must remain inside it. Active Program sources take precedence
+     * over disk snapshots. The directory is watched for changes and new files.
+     *
+     * Cannot combine with package. Omit both to select only the active Program.
+     * File-qualified citation paths remain relative to the citing file.
+     */
+    root?: string;
     /**
      * Installed package whose declarations form this population.
      *
-     * Omit it to select the active project. When present, {@link files} resolves
-     * against the package root instead of the project root, so the globs read as
-     * a consumer thinks of the package rather than carrying its `node_modules`
-     * location.
+     * Omit it to select the active project or the explicit {@link root}. When
+     * present, {@link files} resolves against the package root instead of the
+     * project root, so the globs read as a consumer thinks of the package rather
+     * than carrying its `node_modules` location.
      *
      * A package population is read from disk rather than from the `ttsc` program.
      * That is the point: a symbol nothing imports is absent from the program by
@@ -39,8 +51,8 @@ export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGrap
      * `ttsc` project. A matching file outside the project's `tsconfig` program is
      * not available to the rule and does not count as a match.
      *
-     * When {@link package} is set these are package-relative instead, and the
-     * files are read from disk rather than from the program.
+     * With {@link root} or {@link package}, these are relative to that directory or
+     * package and entry files can be read from disk outside the Program.
      *
      * These are globs, not regular expressions. `*` matches within one path
      * segment, `**` crosses any number of path segments, and `?` matches one

package/lib/typings/TtscEvidenceGraphTypeScriptSymbol.d.ts

@@ -58,8 +58,9 @@
  * prepend their namespace, such as `Orders.create`. A namespace itself uses its
  * qualified name, such as `Orders` or `Outer.Inner`. A local declaration
  * exposed as `export { Local as Public }` therefore uses `Public`. A named
- * default declaration keeps its declaration name; anonymous and default-only
- * aliases have no stable target and are not selected. Members of an ambient
+ * default declaration or default alias is publicly addressed as `default`;
+ * anonymous default classes and functions also have that stable address. A
+ * default-only local binding is not a named export. Members of an ambient
  * namespace are public without their own `export` modifier. A type-only alias
  * exposes a namespace or a class, its public type-space descendants, and
  * everything an object-shaped type alias, or an interface no class merges with,
@@ -79,17 +80,15 @@
  * form. Static class members use `ClassName.member`; instance members use
  * `ClassName.prototype.member`, and a constructor parameter property is an
  * instance member addressed that way. Computed names are not selected, even
- * when their expression is a literal. Literal names must be whitespace-free
- * because a declaration target is one whitespace-delimited token. A dot inside
- * a literal name is rendered unchanged; if that spelling collides with
- * qualification, the target is ambiguous.
+ * when their expression is a literal. File-qualified accessors use bracketed
+ * JSON strings for literal names, including spaces and dots. Existing inline
+ * links keep their dotted spelling and report ambiguous literal qualification.
  *
- * These targets deliberately omit file paths. If selected files expose the same
- * qualified target, a declaration using that target is ambiguous; rename or
- * further qualify the public symbols. A re-export whose declaration lives in
- * another file does not create a second unit in the barrel file. TypeScript
- * target characters are matched exactly; Markdown path-separator normalization
- * does not rewrite literal symbol names.
+ * A code citation identifies its module through a file path or the citing
+ * TypeScript module's imports. A re-export whose declaration lives in another
+ * file does not create a second unit in the barrel file. TypeScript target
+ * characters are matched exactly; Markdown path-separator normalization does
+ * not rewrite literal symbol names.
  *
  * Every supported public declaration described here may carry
  * `@evidenceExclude` when its file belongs to a claim, even when that claim's

package/native/config.go

@@ -288,6 +288,7 @@ func decodeReference(
     Type:     kind,
     Policy:   policy,
     Root:     root,
+    Rooted:   kind == artifactTypeScript && object["root"] != nil,
     Files:    files,
     Source:   source,
     Package:  packageName,
@@ -434,24 +435,8 @@ func rejectChecklistConflicts(
   return problems
 }
 
-// rejectForeignTypeScriptReference refuses a code population to a claim that
-// cannot address one.
-//
-// A symbol is cited through an inline link, and that link resolves in the
-// citing module's import scope — which only a TypeScript file has. Every other
-// claim would have to fall back to matching the bare name against one
-// repository-wide table, and that makes symbol-name uniqueness across the whole
-// repository load-bearing: two modules exporting `IPage` make the citation
-// impossible, and the only repair such a diagnostic can offer is renaming
-// production code to suit a lint rule.
-//
-// The check is here rather than at resolution because a configuration error
-// belongs where the configuration is read. Reported once per reference, before
-// any file is opened, instead of once per citation that later fails to resolve.
-//
-// What this gives up is the decision it reverses: documentation can no longer
-// cite code, and the inverse obligation is not the same one. Do not restore the fallback
-// without restoring that record.
+// Code citations require an import scope or the Markdown/TypeScript file-link
+// grammar. Bare repository-wide symbol lookup remains unavailable.
 func rejectForeignTypeScriptReference(
   claimKind artifactKind,
   referenceKind artifactKind,
@@ -459,13 +444,13 @@ func rejectForeignTypeScriptReference(
 ) string {
   if referenceKind != artifactTypeScript ||
     claimKind == artifactTypeScript ||
+    claimKind == artifactMarkdown ||
     claimKind == "" {
     return ""
   }
   return "Invalid evidence/graph configuration at " + path +
-    ".type: only a TypeScript claim can cite TypeScript evidence, because a symbol citation resolves through the citing module's imports and a " +
-    string(claimKind) +
-    " comment has none. Invert the obligation so the code cites this artifact, or move the citation into TypeScript."
+    ".type: TypeScript evidence requires a Markdown or TypeScript claim; a " + string(claimKind) +
+    " claim does not support file-qualified code citations. Move the citation to a supported claim."
 }
 
 // decodeTypeScriptReference reads the two ways a TypeScript population is
@@ -482,6 +467,9 @@ func decodeTypeScriptReference(
   problems := []string{}
   reference := referenceSpec{}
   if raw, exists := object["package"]; exists {
+    if _, rooted := object["root"]; rooted {
+      problems = append(problems, "Invalid evidence/graph configuration at "+path+": 'root' and 'package' select different TypeScript populations and cannot be combined. Choose one base and its 'files' patterns.")
+    }
     var value string
     if err := json.Unmarshal(raw, &value); err != nil {
       problems = append(problems, "Invalid evidence/graph configuration at "+path+".package: expected an installed package name.")
@@ -588,15 +576,8 @@ func decodeClaimRoot(
   return decodePopulationRoot(raw, configPath)
 }
 
-// decodeRoot reads the directory a Markdown or Prisma population resolves
-// against.
-//
-// The property is refused on the two artifact kinds that cannot use it, and
-// each refusal names the channel that artifact does have. A TypeScript
-// population is materialized from the ttsc Program, so a directory outside the
-// project contains no file it could ever reach — `package` is the escape there,
-// and it already exists. A Swagger reference names one exact document, so the
-// location belongs in `file`, where it is visible without a second property.
+// decodeRoot reads a population directory. A TypeScript reference uses its
+// presence to opt into disk loading; Swagger still owns one exact file.
 func decodeRoot(
   raw json.RawMessage,
   kind artifactKind,
@@ -606,11 +587,7 @@ func decodeRoot(
     return "", nil
   }
   switch kind {
-  case artifactMarkdown, artifactPrisma:
-  case artifactTypeScript:
-    return "", []string{
-      "Invalid evidence/graph configuration at " + configPath + ": a TypeScript reference selects the active ttsc program with 'files', or an installed package with 'package'; only a TypeScript claim accepts 'root'.",
-    }
+  case artifactMarkdown, artifactPrisma, artifactTypeScript:
   case artifactSwagger:
     return "", []string{
       "Invalid evidence/graph configuration at " + configPath + ": a Swagger reference owns one exact document; write the ancestor-relative or absolute location in 'file' instead.",

package/native/declaration.go

@@ -35,10 +35,14 @@ func commentHidingTag(comment string) string {
   comment = strings.TrimPrefix(comment, "/**")
   comment = strings.TrimPrefix(comment, "/*")
   comment = strings.TrimSuffix(comment, "*/")
+  fence := commentFence{}
   for _, rawLine := range strings.Split(comment, "\n") {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
     line = strings.TrimSpace(strings.TrimPrefix(line, "///"))
+    if fence.consume(line) {
+      continue
+    }
     for _, tag := range hiddenDeclarationTags {
       if line != tag && !strings.HasPrefix(line, tag+" ") {
         continue
@@ -75,6 +79,7 @@ func parseCommentDeclarations(
     lineOffset int
   }
   var pending *pendingDeclaration
+  fence := commentFence{}
   parsed := []parsedDeclaration{}
   flush := func() {
     if pending == nil {
@@ -92,6 +97,12 @@ func parseCommentDeclarations(
   for index, rawLine := range lines {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
+    if fence.consume(line) {
+      if pending != nil {
+        pending.body = append(pending.body, line)
+      }
+      continue
+    }
     tag, body, found := declarationLine(line)
     if found {
       flush()
@@ -136,6 +147,7 @@ func declarationLine(line string) (tagKind, string, bool) {
   }{
     {marker: "@evidenceExclude", tag: tagExclude},
     {marker: "@evidence", tag: tagEvidence},
+    {marker: "@link", tag: tagEvidence},
   } {
     if !strings.HasPrefix(line, candidate.marker) {
       continue
@@ -144,7 +156,11 @@ func declarationLine(line string) (tagKind, string, bool) {
     if remainder != "" && remainder[0] != ' ' && remainder[0] != '\t' {
       continue
     }
-    return candidate.tag, strings.TrimSpace(remainder), true
+    body := strings.TrimSpace(remainder)
+    if candidate.marker == "@link" {
+      body = fileLinkPrefix + body
+    }
+    return candidate.tag, body, true
   }
   return "", "", false
 }
@@ -161,6 +177,9 @@ func splitDeclarationBody(body string) (string, string) {
   if body == "" {
     return "", ""
   }
+  if target, reason, found := splitFileLinkBody(body); found {
+    return target, reason
+  }
   if target, reason, found := splitInlineLinkBody(body); found {
     return target, reason
   }
@@ -221,6 +240,9 @@ func inlineLinkTarget(target string) string {
 
 // displayTarget renders a target the way its author wrote it.
 func displayTarget(target string) string {
+  if isFileLinkTarget(target) {
+    return strings.TrimPrefix(target, fileLinkPrefix)
+  }
   if isInlineLinkTarget(target) {
     return "{@link " + inlineLinkTarget(target) + "}"
   }
@@ -315,6 +337,7 @@ func parseReviews(comment string) []parsedReview {
   comment = strings.TrimSuffix(comment, "*/")
   reviews := []parsedReview{}
   var pending *parsedReview
+  fence := commentFence{}
   var body []string
   flush := func() {
     if pending == nil {
@@ -333,6 +356,12 @@ func parseReviews(comment string) []parsedReview {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
     line = strings.TrimSpace(strings.TrimPrefix(line, "///"))
+    if fence.consume(line) {
+      if pending != nil {
+        body = append(body, line)
+      }
+      continue
+    }
     if reviews, remainder, opened := reviewLine(line); opened {
       flush()
       pending = &parsedReview{
@@ -442,6 +471,26 @@ func containsWhitespace(value string) bool {
   return false
 }
 
+// Fences inside documentation are examples, not declarations. Their text is
+// still retained when it belongs to a pending reason or review description.
+type commentFence struct {
+  marker rune
+  length int
+}
+
+func (fence *commentFence) consume(line string) bool {
+  marker, length, remainder, opened := markdownFence(line)
+  if opened {
+    if fence.marker == 0 {
+      fence.marker, fence.length = marker, length
+    } else if marker == fence.marker && length >= fence.length && strings.TrimSpace(remainder) == "" {
+      fence.marker, fence.length = 0, 0
+    }
+    return true
+  }
+  return fence.marker != 0
+}
+
 func lineAt(content string, offset int) int {
   if offset < 0 {
     return 1

package/native/default_exports.go

@@ -0,0 +1,62 @@
+package evidence
+
+import shimast "github.com/microsoft/typescript-go/shim/ast"
+
+// Default aliases retain the named declaration's identity. Anonymous class
+// and function declarations own the module's default identity directly.
+func typeScriptDeclarationName(node *shimast.Node) string {
+  if node == nil {
+    return ""
+  }
+  if name := declarationName(node.Name()); name != "" {
+    return name
+  }
+  if isDefaultExported(node) {
+    return "default"
+  }
+  return ""
+}
+
+func collectDefaultExportBindings(statements *shimast.NodeList) map[string]exportedName {
+  bindings := map[string]exportedName{}
+  if statements == nil {
+    return bindings
+  }
+  for _, statement := range statements.Nodes {
+    if statement == nil {
+      continue
+    }
+    if statement.Kind == shimast.KindExportAssignment {
+      assignment := statement.AsExportAssignment()
+      expression := assignment.Expression
+      if !assignment.IsExportEquals && expression != nil && expression.Kind == shimast.KindIdentifier {
+        local := declarationName(expression)
+        bindings[local] = exportedName{Public: local}
+      }
+    }
+    if statement.Kind != shimast.KindExportDeclaration {
+      continue
+    }
+    declaration := statement.AsExportDeclaration()
+    if declaration.ModuleSpecifier != nil || declaration.ExportClause == nil || declaration.ExportClause.Kind != shimast.KindNamedExports {
+      continue
+    }
+    for _, element := range declaration.ExportClause.AsNamedExports().Elements.Nodes {
+      specifier := element.AsExportSpecifier()
+      if declarationName(specifier.Name()) != "default" {
+        continue
+      }
+      local := specifier.PropertyName
+      if local == nil {
+        local = specifier.Name()
+      }
+      name := declarationName(local)
+      typeOnly := declaration.IsTypeOnly || specifier.IsTypeOnly
+      if previous, exists := bindings[name]; exists {
+        typeOnly = typeOnly && previous.TypeOnly
+      }
+      bindings[name] = exportedName{Public: name, TypeOnly: typeOnly}
+    }
+  }
+  return bindings
+}

package/native/export_resolution.go

@@ -0,0 +1,275 @@
+package evidence
+
+import (
+  "sort"
+  "strings"
+)
+
+// Export names are finite even when modules re-export each other. Discover
+// that vocabulary before resolving bindings, and expand namespace paths only
+// after a binding is known. A module recursion guard cannot answer whether a
+// particular export exists: the module may be busy resolving another name.
+type typeScriptExportResolver struct {
+  loader   *typeScriptLoader
+  modules  map[string]*typeScriptExportModule
+  bindings map[scopedTargetKey][]reachedSymbol
+  owned    *ownedUnitIndex
+}
+
+type typeScriptExportModule struct {
+  exports []moduleExport
+  targets map[string]string
+  names   map[string]bool
+  named   map[string][]moduleExport
+  stars   []moduleExport
+}
+
+func newTypeScriptExportResolver(loader *typeScriptLoader, entries []string) *typeScriptExportResolver {
+  resolver := &typeScriptExportResolver{loader: loader, modules: map[string]*typeScriptExportModule{}, bindings: map[scopedTargetKey][]reachedSymbol{}}
+  resolver.owned = newOwnedUnitIndex(loader)
+  for _, entry := range entries {
+    resolver.load(entry)
+  }
+  keys := make([]string, 0, len(resolver.modules))
+  for key := range resolver.modules {
+    keys = append(keys, key)
+  }
+  sort.Strings(keys)
+  // Only star edges add names. Namespace and named re-exports already have
+  // explicit names, so namespace cycles cannot grow this fixed point forever.
+  for changed := true; changed; {
+    changed = false
+    for _, key := range keys {
+      module := resolver.modules[key]
+      for _, export := range module.stars {
+        target := resolver.modules[module.targets[export.Specifier]]
+        if target == nil {
+          continue
+        }
+        for name := range target.names {
+          if name != "default" && !module.names[name] {
+            module.names[name] = true
+            changed = true
+          }
+        }
+      }
+    }
+  }
+  if loader.boundary != nil {
+    for _, key := range keys {
+      module := resolver.modules[key]
+      for _, export := range module.exports {
+        if export.Specifier == "" || export.Namespace || export.Imported == "" {
+          continue
+        }
+        target := module.targets[export.Specifier]
+        if resolver.modules[target] == nil {
+          continue
+        }
+        if len(resolver.resolve(target, export.Imported)) == 0 {
+          loader.failures[key+" -> "+export.Specifier+"#"+export.Imported] = "the module has no public export named '" + export.Imported + "'"
+        }
+      }
+    }
+  }
+  return resolver
+}
+
+func (resolver *typeScriptExportResolver) load(entry string) {
+  if _, loaded := resolver.modules[entry]; loaded {
+    return
+  }
+  inventory := resolver.loader.inventory(entry)
+  if inventory == nil {
+    return
+  }
+  module := &typeScriptExportModule{exports: inventory.Exports, targets: map[string]string{}, names: map[string]bool{}, named: map[string][]moduleExport{}}
+  declarations := map[string]bool{}
+  if inventory.Source != nil && inventory.Source.Statements != nil {
+    for _, statement := range inventory.Source.Statements.Nodes {
+      if statement == nil {
+        continue
+      }
+      for _, declaration := range topLevelDeclaredNames(statement) {
+        declarations[declaration.Name] = true
+      }
+      if name := typeScriptDeclarationName(statement); name != "" {
+        declarations[name] = true
+      }
+    }
+  }
+  resolver.modules[entry] = module
+  for _, export := range module.exports {
+    if resolver.loader.boundary != nil && export.Specifier == "" && !declarations[export.Local] {
+      resolver.loader.failures[entry+"#"+export.Public] = "the exported binding '" + export.Local + "' has no declaration in this module"
+      continue
+    }
+    if export.Public != "" {
+      module.names[export.Public] = true
+      module.named[export.Public] = append(module.named[export.Public], export)
+    } else if export.Specifier != "" {
+      module.stars = append(module.stars, export)
+    }
+    if export.Specifier == "" {
+      continue
+    }
+    if _, resolved := module.targets[export.Specifier]; resolved {
+      continue
+    }
+    target := resolver.loader.resolve(entry, export.Specifier)
+    module.targets[export.Specifier] = target
+    if target != "" {
+      resolver.load(target)
+    }
+  }
+}
+
+// accessor follows only the namespace segments the citation actually names.
+// Each hop consumes at least one query segment, so namespace cycles are finite.
+// Legacy inline spelling can join several query segments into a literal export
+// name; Address records the consumed query segments for the remaining lookup.
+func (resolver *typeScriptExportResolver) accessor(entry string, segments []string, prefix []string, typeOnly bool, legacy bool) []reachedSymbol {
+  if len(segments) == 0 {
+    return nil
+  }
+  result := []reachedSymbol{}
+  limit := 1
+  if legacy {
+    limit = len(segments)
+  }
+  for consumed := 1; consumed <= limit; consumed++ {
+    name := strings.Join(segments[:consumed], ".")
+    for _, binding := range resolver.resolve(entry, name) {
+      binding.Address = append(append([]string{}, prefix...), segments[:consumed]...)
+      binding.TypeOnly = binding.TypeOnly || typeOnly
+      // Keep namespace prefixes for diagnostics, including when the next name
+      // is missing. They never become units in lookup or population traversal.
+      result = append(result, binding)
+      if binding.Local == "" {
+        result = append(result, resolver.accessor(binding.Path, segments[consumed:], binding.Address, binding.TypeOnly, legacy)...)
+      }
+    }
+  }
+  return result
+}
+
+func (resolver *typeScriptExportResolver) lookup(entry string, segments []string, legacy bool) []*evidenceUnit {
+  result := []*evidenceUnit{}
+  seen := map[string]bool{}
+  for _, binding := range resolver.accessor(entry, segments, nil, false, legacy) {
+    if binding.Local == "" {
+      continue
+    }
+    target := append([]string{binding.Local}, segments[len(binding.Address):]...)
+    for _, unit := range resolver.owned.of(binding.Path, binding.Local) {
+      if binding.TypeOnly && unit.ValueSpace && !unit.TypeSpace {
+        continue
+      }
+      matches := encodeTypeScriptIdentity(unit.Identity) == encodeTypeScriptIdentity(target)
+      if legacy {
+        matches = strings.Join(unit.Identity, ".") == strings.Join(target, ".")
+      }
+      if matches && !seen[unit.ID] {
+        seen[unit.ID] = true
+        result = append(result, unit)
+      }
+    }
+  }
+  return result
+}
+
+func (resolver *typeScriptExportResolver) resolve(module string, name string) []reachedSymbol {
+  key := scopedTargetKey{path: module, target: name}
+  if cached, exists := resolver.bindings[key]; exists {
+    return cached
+  }
+  resolved := resolver.resolveFrom(key, map[scopedTargetKey]bool{})
+  resolver.bindings[key] = resolved
+  return resolved
+}
+
+func (resolver *typeScriptExportResolver) resolveFrom(key scopedTargetKey, visited map[scopedTargetKey]bool) []reachedSymbol {
+  if visited[key] {
+    return nil
+  }
+  if cached, exists := resolver.bindings[key]; exists {
+    return cached
+  }
+  module := resolver.modules[key.path]
+  if module == nil {
+    return nil
+  }
+  visited[key] = true
+  defer delete(visited, key)
+  result := []reachedSymbol{}
+  byBinding := map[scopedTargetKey]int{}
+  add := func(binding reachedSymbol, typeOnly bool) {
+    binding.TypeOnly = binding.TypeOnly || typeOnly
+    identity := scopedTargetKey{path: binding.Path, target: binding.Local}
+    if index, exists := byBinding[identity]; exists {
+      result[index].TypeOnly = result[index].TypeOnly && binding.TypeOnly
+      return
+    }
+    byBinding[identity] = len(result)
+    result = append(result, binding)
+  }
+  exports := module.named[key.target]
+  if len(exports) == 0 && key.target != "default" {
+    exports = module.stars
+  }
+  for _, export := range exports {
+    if export.Specifier == "" {
+      local := export.Public
+      if export.Identity != "" {
+        local = export.Identity
+      }
+      add(reachedSymbol{Path: key.path, Local: local}, export.TypeOnly)
+      continue
+    }
+    target := module.targets[export.Specifier]
+    if resolver.modules[target] == nil {
+      continue
+    }
+    if export.Namespace {
+      add(reachedSymbol{Path: target}, export.TypeOnly)
+      continue
+    }
+    imported := key.target
+    if export.Imported != "" {
+      imported = export.Imported
+    }
+    for _, binding := range resolver.resolveFrom(scopedTargetKey{path: target, target: imported}, visited) {
+      add(binding, export.TypeOnly)
+    }
+  }
+  return result
+}
+
+func (resolver *typeScriptExportResolver) traverse(entry string, prefix []string, visited map[string]bool, typeOnly bool) []reachedSymbol {
+  if visited[entry] {
+    return nil
+  }
+  module := resolver.modules[entry]
+  if module == nil {
+    return nil
+  }
+  visited[entry] = true
+  defer delete(visited, entry)
+  names := make([]string, 0, len(module.names))
+  for name := range module.names {
+    names = append(names, name)
+  }
+  sort.Strings(names)
+  reached := []reachedSymbol{}
+  for _, name := range names {
+    for _, binding := range resolver.resolve(entry, name) {
+      binding.Address = append(append([]string{}, prefix...), name)
+      binding.TypeOnly = binding.TypeOnly || typeOnly
+      reached = append(reached, binding)
+      if binding.Local == "" {
+        reached = append(reached, resolver.traverse(binding.Path, binding.Address, visited, binding.TypeOnly)...)
+      }
+    }
+  }
+  return reached
+}