@ttsc/evidence 0.30.4 → 0.31.0

package/native/comments.go

@@ -29,7 +29,7 @@ type sourceSpan struct {
   end int
 }
 
-// forEachCommentToken visits every real comment in `file` in source order.
+// forEachComment visits every real comment in `file` in source order.
 //
 // TypeScript's parser, rather than a context-free scanner, owns the lexical
 // goal for regular expressions, templates, and JSX. The parsed AST retains

package/native/config.go

@@ -663,6 +663,9 @@ func normalizeSwaggerSource(value string) (string, string) {
   }
   parsed, err := url.Parse(value)
   if err != nil {
+    if displaySwaggerSource(value) != value || strings.Contains(value, "://") {
+      return "", "invalid Swagger source '" + displaySwaggerSource(value) + "': the URL could not be parsed."
+    }
     return "", "invalid Swagger source '" + value + "': " + causeText(err) + "."
   }
   if !drive && parsed.Scheme != "" {
@@ -670,15 +673,15 @@ func normalizeSwaggerSource(value string) (string, string) {
       return "", "unsupported URL scheme '" + parsed.Scheme + "'; only http: and https: are supported."
     }
     if parsed.Host == "" {
-      return "", "Swagger URL '" + value + "' has no host."
+      return "", "Swagger URL '" + displaySwaggerSource(value) + "' has no host."
     }
     if parsed.Fragment != "" {
-      return "", "Swagger URL '" + value + "' must not contain a fragment."
+      return "", "Swagger URL '" + displaySwaggerSource(value) + "' must not contain a fragment."
     }
     return value, ""
   }
   if !drive && strings.Contains(value, "://") {
-    return "", "invalid Swagger source URL '" + value + "'."
+    return "", "invalid Swagger source URL '" + displaySwaggerSource(value) + "'."
   }
   // A trailing separator is read before cleaning, because `path.Clean` removes
   // it — after which `docs/` and `docs` are one string and the author who

package/native/declaration.go

@@ -31,18 +31,12 @@ var hiddenDeclarationTags = []string{"@internal", "@hidden", "@ignore"}
 // sentence silently delete an obligation. Text after the tag is a comment for
 // humans and is not read.
 func commentHidingTag(comment string) string {
-  comment = strings.TrimSpace(comment)
-  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) {
+  body, _, _ := documentationCommentBody(comment)
+  for _, region := range documentationRegions(body, true) {
+    if region.fence {
       continue
     }
+    line := region.text
     for _, tag := range hiddenDeclarationTags {
       if line != tag && !strings.HasPrefix(line, tag+" ") {
         continue
@@ -65,21 +59,14 @@ func parseCommentDeclarations(
   comment string,
   tagBoundaries bool,
 ) []parsedDeclaration {
-  trimmed := strings.TrimLeftFunc(comment, unicode.IsSpace)
-  leadingLines := strings.Count(comment[:len(comment)-len(trimmed)], "\n")
-  comment = trimmed
-  jsdoc := strings.HasPrefix(comment, "/**") || tagBoundaries
-  comment = strings.TrimPrefix(comment, "/**")
-  comment = strings.TrimPrefix(comment, "/*")
-  comment = strings.TrimSuffix(comment, "*/")
-  lines := strings.Split(comment, "\n")
+  body, leadingLines, documented := documentationCommentBody(comment)
+  jsdoc := documented || tagBoundaries
   type pendingDeclaration struct {
     tag        tagKind
     body       []string
     lineOffset int
   }
   var pending *pendingDeclaration
-  fence := commentFence{}
   parsed := []parsedDeclaration{}
   flush := func() {
     if pending == nil {
@@ -94,15 +81,12 @@ func parseCommentDeclarations(
     })
     pending = nil
   }
-  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)
-      }
+  for index, region := range documentationRegions(body, false) {
+    if region.fence {
+      flush()
       continue
     }
+    line := region.text
     tag, body, found := declarationLine(line)
     if found {
       flush()
@@ -329,15 +313,9 @@ func (review parsedReview) marker() string {
 // other `@`-opening line closes the review above it, so a review sharing a
 // block with `@param` or a following `@evidence` swallows neither.
 func parseReviews(comment string) []parsedReview {
-  trimmed := strings.TrimLeftFunc(comment, unicode.IsSpace)
-  leadingLines := strings.Count(comment[:len(comment)-len(trimmed)], "\n")
-  comment = trimmed
-  comment = strings.TrimPrefix(comment, "/**")
-  comment = strings.TrimPrefix(comment, "/*")
-  comment = strings.TrimSuffix(comment, "*/")
+  comment, leadingLines, _ := documentationCommentBody(comment)
   reviews := []parsedReview{}
   var pending *parsedReview
-  fence := commentFence{}
   var body []string
   flush := func() {
     if pending == nil {
@@ -352,16 +330,12 @@ func parseReviews(comment string) []parsedReview {
     pending = nil
     body = nil
   }
-  for index, 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) {
-      if pending != nil {
-        body = append(body, line)
-      }
+  for index, region := range documentationRegions(comment, true) {
+    if region.fence {
+      flush()
       continue
     }
+    line := region.text
     if reviews, remainder, opened := reviewLine(line); opened {
       flush()
       pending = &parsedReview{
@@ -471,8 +445,8 @@ 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.
+// commentFence recognizes example delimiters. Its callers decide whether a
+// recognized example terminates annotation prose or belongs to a TODO's text.
 type commentFence struct {
   marker rune
   length int

package/native/documentation_regions.go

@@ -0,0 +1,214 @@
+package evidence
+
+import (
+  "strings"
+  "unicode"
+)
+
+// documentationRegionLine preserves one source line while separating annotation
+// prose from a fenced example. A fence is also a pending-annotation boundary.
+type documentationRegionLine struct {
+  // text is visible annotation prose with the original line slot retained.
+  text string
+
+  // fence ends pending prose and suppresses tags throughout the example.
+  fence bool
+}
+
+// documentationCommentBody removes only a real native wrapper. Mapped Prisma
+// and Markdown bodies have no wrapper, so their initial indentation and blank
+// lines must survive to retain relative columns and diagnostic line offsets.
+func documentationCommentBody(comment string) (string, int, bool) {
+  trimmed := strings.TrimLeftFunc(comment, unicode.IsSpace)
+  prefix := ""
+  jsdoc := strings.HasPrefix(trimmed, "/**")
+  if jsdoc {
+    prefix = "/**"
+  } else if strings.HasPrefix(trimmed, "/*") {
+    prefix = "/*"
+  }
+  if prefix == "" {
+    return comment, 0, false
+  }
+  leading := strings.Count(comment[:len(comment)-len(trimmed)], "\n")
+  body := strings.TrimPrefix(trimmed, prefix)
+  body = strings.TrimSuffix(strings.TrimRightFunc(body, unicode.IsSpace), "*/")
+  return body, leading, jsdoc
+}
+
+// documentationRegions reads examples after removing comment decoration and
+// ordinary common indentation. It shares region decisions between citations,
+// reviews and withdrawal without merging their distinct semantic records.
+// Fences take precedence over HTML and code spans; HTML contents cannot open a
+// fence. Equal backtick runs protect literal HTML delimiters, including spans
+// crossing a newline. Unmatched code delimiters remain ordinary prose.
+func documentationRegions(body string, slashDecoration bool) []documentationRegionLine {
+  lines := strings.Split(body, "\n")
+  baseline := -1
+  for index, line := range lines {
+    line = strings.TrimSuffix(line, "\r")
+    stripped := strings.TrimLeft(line, " \t")
+    if strings.HasPrefix(stripped, "*") {
+      line = strings.TrimPrefix(stripped[1:], " ")
+    } else if slashDecoration && strings.HasPrefix(stripped, "///") {
+      line = strings.TrimPrefix(stripped[3:], " ")
+    }
+    lines[index] = line
+    if strings.TrimSpace(line) != "" {
+      columns, _ := documentationColumns(line)
+      if baseline < 0 || columns < baseline {
+        baseline = columns
+      }
+    }
+  }
+  content := strings.Join(lines, "\n")
+  mates := documentationCodeMates(content)
+  result := make([]documentationRegionLine, len(lines))
+  fence := commentFence{}
+  html := false
+  codeEnd := 0
+  tagEnd := 0
+  offset := 0
+  for index, line := range lines {
+    columns, cursor := documentationColumns(line)
+    relative := columns - baseline
+    delimiter := "    " + line[cursor:]
+    if relative >= 0 && relative <= 3 {
+      delimiter = strings.Repeat(" ", relative) + line[cursor:]
+    }
+    if !html && fence.consume(delimiter) {
+      result[index].fence = true
+      codeEnd, tagEnd = 0, 0
+      offset += len(line) + 1
+      continue
+    }
+    masked := []byte(line)
+    for at := 0; at < len(line); {
+      if html {
+        end := len(line)
+        if closing := strings.Index(line[at:], "-->"); closing >= 0 {
+          end = at + closing + 3
+          html = false
+        }
+        for position := at; position < end; position++ {
+          masked[position] = ' '
+        }
+        at = end
+        continue
+      }
+      if codeEnd > offset+at || tagEnd > offset+at {
+        at++
+        continue
+      }
+      if relative < 4 {
+        if line[at] == '\\' && at+1 < len(line) {
+          at += 2
+          continue
+        }
+        if end, ok := mates[offset+at]; ok {
+          codeEnd = end
+          at++
+          continue
+        }
+        if strings.HasPrefix(line[at:], "<!--") {
+          html = true
+          // Empty HTML comments may close with an overlapping final dash.
+          if strings.HasPrefix(line[at:], "<!-->") {
+            for position := at; position < at+5; position++ {
+              masked[position] = ' '
+            }
+            at += 5
+            html = false
+          } else if strings.HasPrefix(line[at:], "<!--->") {
+            for position := at; position < at+6; position++ {
+              masked[position] = ' '
+            }
+            at += 6
+            html = false
+          }
+          continue
+        }
+        if line[at] == '<' {
+          if end := documentationTagEnd(content, offset+at); end > offset+at {
+            tagEnd = end
+            at++
+            continue
+          }
+        }
+      }
+      at++
+    }
+    result[index].text = strings.TrimSpace(string(masked))
+    offset += len(line) + 1
+  }
+  return result
+}
+
+// documentationCodeMates indexes the next equal backtick run in one linear
+// reverse pass. A run without a closing mate must not hide later HTML syntax.
+func documentationCodeMates(content string) map[int]int {
+  mates := map[int]int{}
+  next := map[int]int{}
+  for end := len(content); end > 0; {
+    end--
+    if content[end] != '`' {
+      continue
+    }
+    start := end
+    for start > 0 && content[start-1] == '`' {
+      start--
+    }
+    // Escapes apply to opening prose, not to a closing run inside code. The
+    // forward reader skips escaped openers before consulting this mate index.
+    length := end - start + 1
+    if closing, ok := next[length]; ok {
+      mates[start] = closing + length
+    }
+    next[length] = start
+    end = start
+  }
+  return mates
+}
+
+// documentationTagEnd keeps quoted attribute delimiters literal without adding
+// an element-specific policy such as treating every pre element as an example.
+func documentationTagEnd(line string, start int) int {
+  cursor := start + 1
+  if cursor < len(line) && line[cursor] == '/' {
+    cursor++
+  }
+  if cursor >= len(line) || !((line[cursor] >= 'a' && line[cursor] <= 'z') || (line[cursor] >= 'A' && line[cursor] <= 'Z')) {
+    return start
+  }
+  quote := byte(0)
+  for cursor++; cursor < len(line); cursor++ {
+    char := line[cursor]
+    if quote != 0 {
+      if char == quote {
+        quote = 0
+      }
+    } else if char == '\'' || char == '"' {
+      quote = char
+    } else if char == '>' {
+      return cursor + 1
+    }
+  }
+  return len(line)
+}
+
+// documentationColumns measures four-column tab stops while retaining the byte
+// position where content starts. Fence grammar consumes the relative columns.
+func documentationColumns(line string) (int, int) {
+  columns, cursor := 0, 0
+  for cursor < len(line) {
+    if line[cursor] == ' ' {
+      columns++
+    } else if line[cursor] == '\t' {
+      columns += 4 - columns%4
+    } else {
+      break
+    }
+    cursor++
+  }
+  return columns, cursor
+}

package/native/documented.go

@@ -14,10 +14,11 @@ import (
 //
 // Evidence declarations are read from one place only — the JSDoc blocks a node
 // reports — so an export without a block is not merely undocumented, it is
-// structurally unable to carry a citation. The graph never says so: coverage is
-// counted from the evidence side, so an obligation is discharged by whichever
-// host does have a block while every undocumented export in the same claim
-// contributes nothing and looks exactly like a passing file.
+// structurally unable to carry a citation. Ordinary graph coverage is counted
+// from the evidence side, so another host can discharge the obligation while
+// an undocumented export contributes nothing. A checklist instead keeps every
+// selected host's obligation, including hosts without a block. This rule checks
+// the documentation itself in either mode.
 type documentedRule struct{}
 
 type documentedOptions struct {

package/native/exports.go

@@ -214,7 +214,6 @@ func dedupeModuleExports(exports []moduleExport) []moduleExport {
   return unique
 }
 
-// reachedSymbol is one public address an entry traversal arrived at.
 // traversedPopulation is what selecting modules and walking their exports
 // yields: the obligations, the scopes above them, and the addresses that reach
 // them.
@@ -243,6 +242,7 @@ type publishedAddress struct {
   Unit     *evidenceUnit
 }
 
+// reachedSymbol is one public address an entry traversal arrived at.
 type reachedSymbol struct {
   // Address is the accessor path from the entry, segment by segment.
   Address []string

package/native/fingerprint.go

@@ -31,14 +31,8 @@ func normalizeFingerprintText(text string) string {
   for len(lines) != 0 && lines[len(lines)-1] == "" {
     lines = lines[:len(lines)-1]
   }
-  // Leading blank lines go for a sharper reason. A TypeScript node's position is
-  // its *full* start, meaning the end of the previous token, so an undocumented
-  // declaration's span begins with whatever blank lines and `//` comments sit
-  // above it. Keeping them made inserting one blank line elsewhere in the file
-  // expire a review, and inconsistently: the same edit above a *documented*
-  // declaration is neutral, because the whole leading run through `*/` is
-  // excluded as a tag position. Dropping them makes both cases agree and honors
-  // the rule that a reformat which changes no content expires nothing.
+  // Leading whitespace remains artifact content. TypeScript declaration spans
+  // discard their unowned leading trivia separately in withoutLeadingTrivia.
   return strings.Join(lines, "\n")
 }
 

package/native/glob.go

@@ -49,7 +49,10 @@ func compileGlob(raw string) (globPattern, error) {
     value = strings.TrimPrefix(value, "./")
   }
   if value == "" {
-    return globPattern{}, errors.New("the exclusion marker '!' must be followed by a glob")
+    if exclude && strings.TrimPrefix(raw, "!") == "" {
+      return globPattern{}, errors.New("the exclusion marker '!' must be followed by a glob")
+    }
+    return globPattern{}, errors.New("glob '" + raw + "' names no path below the project root")
   }
   if filepath.IsAbs(value) ||
     hasWindowsDrivePrefix(value) ||

package/native/graph.go

@@ -1,7 +1,6 @@
 package evidence
 
 import (
-  "os"
   "path/filepath"
   "sort"
   "strings"
@@ -13,8 +12,25 @@ type graphRule struct{}
 
 func (graphRule) Name() string { return graphRuleName }
 
+// UsesProjectInputReader declares the actual external-input read boundary.
+// Native readers use the supplied generation reader; external bridges withdraw
+// completeness because their independent module/input reads are not observed.
+func (graphRule) UsesProjectInputReader() bool { return true }
+
 func (graphRule) NeedsTypeChecker() bool { return false }
 
+// Check builds artifact populations and checks each active claim's obligations.
+//
+// Claim populations are loaded first because a healthy empty population owes
+// nothing; its references must not trigger unrelated reads or failures. Failed
+// populations remain active, and their health prevents partial inventories from
+// producing a false coverage result. TypeScript identities come from parsed
+// declarations, while Markdown, Prisma and Swagger retain their own hierarchies.
+//
+// Inventory construction, address resolution and obligation evaluation are
+// separate stages so selectors never invent declarations or decide identity.
+// Successful publication reuses those inventories for editor hints; diagnostics
+// and Program-cycle coordination remain owned by the host's project-rule API.
 func (graphRule) Check(ctx *rule.ProjectContext) {
   if ctx == nil {
     return
@@ -31,6 +47,7 @@ func (graphRule) Check(ctx *rule.ProjectContext) {
     reportProblems(ctx, problems)
     return
   }
+  config.inputs = evidenceInputReader{host: ctx.Inputs}
   resolveGraphSeverities(&config, ctx.Severity)
   config = enabledGraphConfig(config)
   if len(config.Claims) == 0 {
@@ -42,7 +59,7 @@ func (graphRule) Check(ctx *rule.ProjectContext) {
     ctx.Report("Evidence graph could not resolve the project root. Run ttsc with a project config or explicit project root so project-relative evidence globs have one stable base.")
     return
   }
-  info, err := os.Stat(root)
+  info, err := config.inputs.Stat(root)
   if err != nil || !info.IsDir() {
     ctx.Report("Evidence graph project root '" + root + "' is not a readable directory. Fix the ttsc project identity before evaluating evidence globs.")
     return
@@ -62,9 +79,11 @@ func (graphRule) Check(ctx *rule.ProjectContext) {
     ctx.Sources,
     claimPopulationConfig(config, artifactTypeScript),
   )
+  markdownSnapshot := &markdownCapture{}
   markdownClaims, markdownClaimProblems := loadMarkdownInventories(
     root,
     claimPopulationConfig(config, artifactMarkdown),
+    markdownSnapshot,
   )
   prismaClaims, prismaClaimProblems := loadPrismaInventories(
     root,
@@ -89,15 +108,15 @@ func (graphRule) Check(ctx *rule.ProjectContext) {
   config = activeGraphConfig(config, markdownClaims, prismaClaims, typescript)
   governed := map[string]bool{}
   extendTypeScriptInventories(root, ctx.Sources, config, typescript, nil)
-  recordGovernedTypeScriptFiles(ctx.Sources, declared, governed)
-  markdown, markdownProblems := loadMarkdownInventories(root, config)
+  recordGovernedTypeScriptFiles(root, ctx.Sources, declared, governed)
+  markdown, markdownProblems := loadMarkdownInventories(root, config, markdownSnapshot)
   prisma, prismaProblems := loadPrismaInventories(root, config)
   swagger, swaggerProblems := loadSwaggerInventories(root, config)
   diagnostics = append(diagnostics, markdownProblems...)
   diagnostics = append(diagnostics, prismaProblems...)
   diagnostics = append(diagnostics, swaggerProblems...)
   diagnostics = append(diagnostics, unreadableTypeScriptTags(typescript, governed, declared)...)
-  loader := newTypeScriptLoader(root, typescript)
+  loader := newTypeScriptLoader(root, typescript, config.inputs)
   states, stateProblems := materializeClaimStates(
     config,
     markdown,
@@ -112,7 +131,9 @@ func (graphRule) Check(ctx *rule.ProjectContext) {
   if len(diagnostics) == 0 {
     // Published only on a clean evaluation, because the host reads state
     // from a rule that passed and reporting anything marks this one failed
-    // (`linthost/hints.go:147-149`, `linthost/project_engine.go:68-77`).
+    // (`collectProjectHints` in `linthost/hints.go` skips a rule whose status is
+    // not passed, and `projectReporter` in `linthost/project_engine.go` marks a
+    // rule failed once it reports).
     // Setting it unconditionally would not widen the gate; it would only
     // hide where the gate is.
     cycle.Corpus = graphCorpus{
@@ -164,7 +185,7 @@ func claimPopulationConfig(
     claim.References = nil
     claims = append(claims, claim)
   }
-  return graphConfig{Claims: claims}
+  return graphConfig{Claims: claims, inputs: config.inputs}
 }
 
 // activeGraphConfig omits healthy claim populations that contain no own unit
@@ -660,14 +681,13 @@ func evaluateEvidenceGraph(
       continue
     }
     candidates := declarationCandidates(declaration.Target, targets, markdownTargets)
-    // The configuration guard refuses a code population to a claim that
-    // cannot address one, but the address map is built from every claim at
-    // once — so a Markdown claim could still land on a symbol materialized
-    // by some *other* claim's TypeScript reference. Measured: it resolved
-    // silently, which left repository-wide name uniqueness load-bearing
-    // through a door the guard does not cover. Closing it here rather than
-    // by scoping the whole map keeps resolution global for the artifacts
-    // that are addressed by path, where a shared map costs nothing.
+    // The address map is built from every claim at once, so a claim that
+    // addresses code only through a file-qualified link, such as a Markdown
+    // claim, could still land on a symbol materialized by some *other* claim's
+    // TypeScript reference through a plain token. That would resolve silently
+    // and make repository-wide name uniqueness load-bearing. Refusing it here
+    // rather than scoping the whole map keeps resolution global for the
+    // artifacts that are addressed by path, where a shared map costs nothing.
     if declaration.Type != artifactTypeScript {
       addressable, code := splitCodeCandidates(candidates)
       if len(addressable) == 0 && len(code) != 0 {
@@ -937,9 +957,16 @@ func evaluateEvidenceGraph(
           for _, unit := range covered {
             targets = append(targets, "'"+unit.Target+"'")
           }
+          // The exclusion alternative is offered only where this reference
+          // accepts one: a checklist is the pairing `noEvidenceExclude` is allowed
+          // beside, and there the exclusion would be refused as forbidden.
+          repair := "Cite each item this host answers for, or write @evidenceExclude on this scope when none of it applies here."
+          if reference.Spec.Policy.NoExclude {
+            repair = "Cite each item this host answers for; this reference forbids @evidenceExclude."
+          }
           problems = problems.add(
             severity,
-            "Aggregate @evidence target '"+scopesByID[scopeID].Target+"' at "+declaration.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": this reference is a checklist, so a citation answers for the item it names, and this target names a scope containing "+decimal(len(covered))+" item(s) ("+strings.Join(targets, ", ")+") rather than one of them. Cite each item this host answers for, or write @evidenceExclude on this scope when none of it applies here."+untrueTagWarning,
+            "Aggregate @evidence target '"+scopesByID[scopeID].Target+"' at "+declaration.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": this reference is a checklist, so a citation answers for the item it names, and this target names a scope containing "+decimal(len(covered))+" item(s) ("+strings.Join(targets, ", ")+") rather than one of them. "+repair+untrueTagWarning,
           )
           for _, unit := range covered {
             for _, hostID := range keyHosts {
@@ -976,7 +1003,7 @@ func evaluateEvidenceGraph(
           if first := byScope[scopeID]; first != nil {
             problems = problems.add(
               severity,
-              "Duplicate @evidence for '"+scopesByID[scopeID].Target+"' on the same host at "+declaration.location()+"; first declared at "+first.location()+".",
+              "Duplicate @evidence for '"+scopesByID[scopeID].Target+"' on the same host at "+declaration.location()+"; first declared at "+first.location()+". Delete the repeated citation.",
             )
           } else {
             byScope[scopeID] = declaration
@@ -1084,13 +1111,13 @@ func evaluateEvidenceGraph(
           }
           problems = problems.add(
             severity,
-            "Conflicting acknowledgements for '"+conflictingUnit.Target+"' in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": @evidence at "+evidence.location()+" overlaps @evidenceExclude at "+exclusion.location()+". Delete whichever is untrue of this host."+untrueTagWarning,
+            "Conflicting acknowledgements for '"+conflictingUnit.Target+"' in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": @evidence at "+evidence.location()+" overlaps @evidenceExclude at "+exclusion.location()+". Delete whichever of the two is untrue."+untrueTagWarning,
           )
         }
         if duplicateExclusionUnit != nil {
           problems = problems.add(
             severity,
-            "Duplicate @evidenceExclude for '"+duplicateExclusionUnit.Target+"' in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": exclusion at "+declaration.location()+" overlaps exclusion at "+firstExclusion.location()+".",
+            "Duplicate @evidenceExclude for '"+duplicateExclusionUnit.Target+"' in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+": exclusion at "+declaration.location()+" overlaps exclusion at "+firstExclusion.location()+". Delete one of the two exclusions.",
           )
         }
       }
@@ -1108,7 +1135,7 @@ func evaluateEvidenceGraph(
           }
           problems = problems.add(
             severity,
-            "Evidence host "+host.Readable+" at "+host.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+" cites "+decimal(count)+" distinct selected evidence unit(s); singleEvidencePerSymbol requires exactly 1. Split this host so each unit has one that owns it, or keep positive @evidence citations on this semantic host to exactly one distinct unit.",
+            "Evidence host "+host.Readable+" at "+host.location()+" in "+claimLabel(state.Spec)+" "+referenceLabel(reference.Spec)+" cites "+decimal(count)+" distinct selected evidence unit(s); singleEvidencePerSymbol requires exactly 1. Keep positive @evidence citations on this semantic host to exactly one distinct unit: cite the one unit it answers for, or split the host so that each unit has a host of its own."+untrueTagWarning,
           )
         }
       }
@@ -1206,9 +1233,18 @@ func evaluateEvidenceGraph(
         host = "unsupported or non-exported declaration"
       }
       if declaration.Tag == tagExclude {
+        // The carriers differ by artifact kind, so the repair names only the ones
+        // this kind has: an unattached run exists in Prisma schemas alone.
+        repair := "Move the exclusion onto a selected host of the claim."
+        switch declaration.Type {
+        case artifactTypeScript:
+          repair = "Move the exclusion onto a supported public export in a matching claim file."
+        case artifactPrisma:
+          repair = "Move the exclusion onto a selected model, column, or relation, or into a top-level unattached '///' run in a matching claim file."
+        }
         problems = problems.add(
           outOfScopeLevels[id],
-          "Out-of-scope @evidenceExclude carrier at "+declaration.location()+" for "+strings.Join(obligations, "; ")+", target '"+displayTarget(declaration.Target)+"': '"+host+"' is not an eligible exclusion carrier in these matching claim files. Move the exclusion to a supported public export or selected declaration host, or use a top-level unattached Prisma documentation comment.",
+          "Out-of-scope @evidenceExclude carrier at "+declaration.location()+" for "+strings.Join(obligations, "; ")+", target '"+displayTarget(declaration.Target)+"': '"+host+"' is not an eligible exclusion carrier in these matching claim files. "+repair+untrueTagWarning,
         )
         continue
       }
@@ -1421,7 +1457,7 @@ func hiddenTargetProblem(
   hidden *evidenceUnit,
   context string,
 ) string {
-  return "Hidden evidence target '" + displayTarget(declaration.Target) + "' at " + declaration.location() + " for " + context + ": " + hidden.Readable + " at " + hidden.location() + " carries '" + hidden.Hidden + "' in its documentation comment, which removes it from the evidence population along with everything nested inside it. Remove the tag if the declaration is public contract, or drop this citation if it is not. Do not remove '@hidden' from the target to make this citation legal." + untrueTagWarning
+  return "Hidden evidence target '" + displayTarget(declaration.Target) + "' at " + declaration.location() + " for " + context + ": " + hidden.Readable + " at " + hidden.location() + " carries '" + hidden.Hidden + "' in its documentation comment, which removes it from the evidence population along with everything nested inside it. Remove the tag if the declaration is public contract, or drop this citation if it is not. Do not remove '" + hidden.Hidden + "' from the target to make this citation legal." + untrueTagWarning
 }
 
 func declarationResolutionUncertain(owners []claimState) bool {
@@ -1659,7 +1695,7 @@ func resolveReferenceEntry(
 ) (string, string) {
   entry := loader.packageEntryModule(reference.Package)
   if entry == "" {
-    return "", claimLabel(claim) + " " + referenceLabel(reference) + " could not resolve the declaration entry of package '" + reference.Package + "'. Install it, or select its declarations with 'files'; the entry is read from the 'types' condition of 'exports', then 'typesVersions', then 'types'."
+    return "", claimLabel(claim) + " " + referenceLabel(reference) + " could not resolve the declaration entry of package '" + reference.Package + "'. Install it, or select its declarations with 'files'; the entry is read from the 'types' condition of 'exports', then 'typesVersions', then 'types' or 'typings'. A package with none of those resolves only when its 'exports' target or 'main' names TypeScript source itself."
   }
   return entry, ""
 }

package/native/graph_nodes.go

@@ -30,7 +30,8 @@ func (graphRule) GraphNodes(ctx *rule.GraphContext) []rule.GraphNode {
   corpus := cycle.Corpus
   // Addresses of every materialized unit, so a parent can be named by the
   // address a citation would use rather than by the rule's internal id. A
-  // parent outside the selected set resolves to nothing and the host clears it,
+  // parent outside the selected set is still named by its address here, and the
+  // host clears a parent that no published node carries (`linthost/graph_nodes.go`),
   // which leaves the child at the top of its chain instead of inventing one.
   addresses := map[string]string{}
   for _, inventories := range []map[string]*artifactInventory{