@ttsc/evidence 0.30.4 → 0.31.1

package/native/prisma_locator.go

@@ -1,7 +1,6 @@
 package evidence
 
 import (
-  "os"
   "strings"
   "unicode"
 )
@@ -23,14 +22,16 @@ const (
   prismaBlockComment prismaCommentForm = "block"
 )
 
-// prismaCommentRun is one contiguous comment block and the declaration it
-// attaches to.
+// prismaCommentRun is one comment run and the declaration it attaches to.
 //
-// Body preserves the run's own line spacing — a line the run skipped is empty
-// rather than absent — so a tag's offset inside the body is still its offset in
-// the file. Key is the declaration the run documents, empty when it documents
-// nothing unless FileLevel identifies a top-level triple-slash exclusion
-// carrier.
+// A run is either the contiguous documentation block above one declaration or a
+// single comment line that can never document one: a `//` line, or a comment
+// that shares its line with code. Body preserves a documentation run's own line
+// spacing — a line the run skipped is empty rather than absent — so a tag's
+// offset inside the body is still its offset in the file. Key is the
+// declaration the run documents, empty when it documents nothing unless
+// FileLevel identifies a top-level triple-slash exclusion carrier. Trailing
+// marks the single-line run whose comment shares its line with code.
 type prismaCommentRun struct {
   Form      prismaCommentForm
   Path      string
@@ -38,6 +39,7 @@ type prismaCommentRun struct {
   Body      string
   Key       string
   FileLevel bool
+  Trailing  bool
 }
 
 // prismaFileScan is everything one schema file yields to the native side.
@@ -46,12 +48,20 @@ type prismaFileScan struct {
   Comments  []prismaCommentRun
 }
 
+// prismaByteOrderMark is the UTF-8 encoding of U+FEFF, spelled as bytes so the
+// constant is visible in an editor that hides the character.
+const prismaByteOrderMark = "\xef\xbb\xbf"
+
+// prismaLineBreaks rewrites every line terminator Prisma's grammar accepts to
+// `\n`, taking `\r\n` as one terminator rather than two.
+var prismaLineBreaks = strings.NewReplacer("\r\n", "\n", "\r", "\n")
+
 // prismaBlockKeywords are the top-level block openers Prisma's grammar accepts.
 //
-// All six are recognized even though only `model`, `view`, and `type` can own a
-// unit, because recognizing a block is how the scan knows when it is *not*
-// inside one. Dropping `datasource` and `generator` would leave their settings
-// looking like members of whatever block was declared before them.
+// All six are recognized even though only `model` and `view` own a unit, because
+// recognizing a block is how the scan knows when it is *not* inside one.
+// Dropping `datasource` and `generator` would leave their settings looking like
+// members of whatever block was declared before them.
 var prismaBlockKeywords = map[string]bool{
   "model":      true,
   "view":       true,
@@ -61,7 +71,13 @@ var prismaBlockKeywords = map[string]bool{
   "generator":  true,
 }
 
-// prismaMemberBlocks are the blocks whose members this graph addresses.
+// prismaMemberBlocks are the blocks whose names and members the scan locates.
+//
+// Locating a block is not owning a unit for it. A `type` block is a composite
+// type, which is outside the unit model: the parser reports it apart from the
+// models the units are built from, so its locations are recorded and never
+// looked up, and a citation written in one is reported as documenting something
+// that is not a model, column, or relation.
 var prismaMemberBlocks = map[string]bool{
   "model": true,
   "view":  true,
@@ -90,11 +106,13 @@ var prismaMemberBlocks = map[string]bool{
 func locatePrismaDeclarations(
   root string,
   sources []string,
+  readers ...evidenceInputReader,
 ) (map[string]prismaLocation, []prismaCommentRun) {
+  inputs := inputReader(readers)
   locations := map[string]prismaLocation{}
   comments := []prismaCommentRun{}
   for _, source := range sources {
-    content, err := os.ReadFile(resolveProjectPath(root, source))
+    content, err := inputs.ReadFile(resolveProjectPath(root, source))
     if err != nil {
       continue
     }
@@ -120,14 +138,27 @@ func locatePrismaDeclarations(
 //   - A run followed by a block attribute or by the block's closing brace
 //     documents nothing.
 //
+// A comment that shares its line with code never joins a run. Prisma reads a
+// trailing `///` or `/* */` as documentation of the field on its own line, and
+// never of the declaration below it, and this graph reads a citation only from
+// the lines above a declaration, so such a comment is reported instead.
+//
 // A run that documents nothing keeps an empty Key rather than being dropped,
 // because a citation written there is a citation that will never be honoured —
 // and this rule reports that rather than letting it pass for a tag that works.
+//
+// The scan reads the text the parser was handed, not the bytes on disk: the
+// bridge decodes a file as UTF-8, which drops a leading byte order mark, and
+// Prisma's grammar ends a line at `\n`, `\r\n`, or a lone `\r`. A scan that kept
+// the mark would fail to recognise a first-line block opener or to attach a
+// first-line comment, and one that split on `\n` alone would see a lone-`\r`
+// file as a single line.
 func scanPrismaFile(
   source string,
   content string,
   locations map[string]prismaLocation,
 ) prismaFileScan {
+  content = prismaLineBreaks.Replace(strings.TrimPrefix(content, prismaByteOrderMark))
   scan := prismaFileScan{Locations: locations}
   record := func(key string, line int) {
     if key == "" {
@@ -155,8 +186,7 @@ func scanPrismaFile(
     pending = nil
   }
   for index, raw := range lines {
-    line := strings.TrimSuffix(raw, "\r")
-    code, comment, form, stillCommented := prismaPartsOf(line, commented)
+    code, comment, form, stillCommented := prismaPartsOf(raw, commented)
     commented = stillCommented
     trimmed := strings.TrimSpace(code)
     if comment != "" || form != "" {
@@ -222,9 +252,9 @@ type prismaPendingComment struct {
   Form prismaCommentForm
   Line int
   Text string
-  // Trailing marks a comment that shared its line with code. Prisma treats
-  // such a comment as the field's trailing comment rather than as
-  // documentation, so it can never document the declaration below it.
+  // Trailing marks a comment that shared its line with code. Such a comment
+  // belongs to the line it sits on, never to the declaration below it, so it
+  // cannot join the documentation run above that declaration.
   Trailing bool
   // TopLevel marks a comment written outside every Prisma block. A detached
   // documentation run there may carry claim-local exclusions for the file
@@ -232,12 +262,16 @@ type prismaPendingComment struct {
   TopLevel bool
 }
 
-// prismaCommentRuns groups pending comment lines into one run per form.
+// prismaCommentRuns turns the pending comment lines above one declaration into
+// runs.
 //
-// Only the doc-comment run can carry a citation, so the other two are grouped
-// solely to be reported. Keeping the doc run's body line-aligned is what lets a
-// tag inside it be reported at the line it was written on: a line the run
-// skipped becomes an empty line rather than disappearing.
+// Every `///` and `/* */` line that does not share its line with code is joined
+// into the one documentation run, and that run alone can carry a citation. Every
+// other line, a `//` comment or a comment trailing code, becomes a run of its
+// own, and exists solely to be reported. Keeping the documentation run's body
+// line-aligned is what lets a tag inside it be reported at the line it was
+// written on: a line the run skipped becomes an empty line rather than
+// disappearing.
 func prismaCommentRuns(
   source string,
   pending []prismaPendingComment,
@@ -258,11 +292,12 @@ func prismaCommentRuns(
       continue
     }
     runs = append(runs, prismaCommentRun{
-      Form: comment.Form,
-      Path: source,
-      Line: comment.Line,
-      Body: comment.Text,
-      Key:  "",
+      Form:     comment.Form,
+      Path:     source,
+      Line:     comment.Line,
+      Body:     comment.Text,
+      Key:      "",
+      Trailing: comment.Trailing,
     })
   }
   if len(documenting) != 0 {
@@ -294,8 +329,8 @@ func prismaCommentRuns(
 // String contents are dropped from the code rather than kept, because a brace
 // inside one must not open or close a block — `@default("}")` is a legal field
 // that a naive brace count reads as the end of its model. The comment text is
-// returned rather than discarded, because two of the three forms cannot carry a
-// citation and this rule reports one written there instead of ignoring it.
+// returned rather than discarded, because a `//` comment cannot carry a citation
+// and this rule reports one written there instead of ignoring it.
 func prismaPartsOf(
   line string,
   commented bool,
@@ -345,7 +380,9 @@ func prismaPartsOf(
       } else if form == "" {
         form = prismaLineComment
       }
-      comment.WriteString(strings.TrimSpace(string(runes[rest:])))
+      // One ordinary padding space follows the documentation prefix; further
+      // indentation belongs to the body and decides whether a fence is literal.
+      comment.WriteString(strings.TrimPrefix(string(runes[rest:]), " "))
       break
     }
     if char == '/' && index+1 < len(runes) && runes[index+1] == '*' {
@@ -358,7 +395,7 @@ func prismaPartsOf(
     }
     code.WriteRune(char)
   }
-  return code.String(), strings.TrimSpace(comment.String()), form, commented
+  return code.String(), strings.TrimRight(comment.String(), " \t\r"), form, commented
 }
 
 // prismaBlockHead reads `model <Name>` from a block opener.

package/native/review.go

@@ -18,7 +18,8 @@ import (
 // second one is never put.
 //
 // The rule puts it. Every `@evidence` and `@evidenceExclude` on a public
-// identity must be answered by an `@evidenceReview` naming the same target, so a
+// identity must be answered by `@evidenceReview` or `@evidenceExcludeReview`,
+// respectively, naming the same target, so a
 // citation cannot be produced without a separately addressed statement written
 // as its own act.
 //
@@ -145,12 +146,6 @@ func judgeReviewedHost(ctx *rule.Context, host documentedHost) {
   }
 }
 
-// acknowledgementQuestion is what a review of this tag has to answer.
-//
-// The two are not the same question and the diagnostic says which one is open. A
-// citation is verified by checking that this declaration does what the cited unit
-// describes. An exclusion is verified by checking that the unit genuinely does not
-// apply here, which no reading of this declaration can establish on its own.
 // reviewExample shows the shape of a check that answers this tag's question.
 //
 // The two examples differ because the two checks do. A citation is answered by
@@ -164,6 +159,12 @@ func reviewExample(tag tagKind) string {
   return "A review of a citation names what you read or ran, as in 'read the section's three rules and ran the checkout test'."
 }
 
+// acknowledgementQuestion is what a review of this tag has to answer.
+//
+// The two are not the same question and the diagnostic says which one is open. A
+// citation is verified by checking that this declaration does what the cited unit
+// describes. An exclusion is verified by checking that the unit genuinely does not
+// apply here, which no reading of this declaration can establish on its own.
 func acknowledgementQuestion(tag tagKind) string {
   if tag == tagExclude {
     return "The exclusion states that this claim does not cover that target."

package/native/rooted_typescript.go

@@ -2,7 +2,6 @@ package evidence
 
 import (
   "io/fs"
-  "os"
   "path/filepath"
   "sort"
   "strings"
@@ -14,7 +13,7 @@ func materializeRootedTypeScriptReference(claim claimSpec, reference referenceSp
   state := referenceState{Spec: reference, Healthy: false, UnitsByScope: map[string][]*evidenceUnit{}}
   context := claimLabel(claim) + " " + referenceLabel(reference)
   base := reference.Base
-  if info, err := os.Stat(base.Absolute); err != nil || !info.IsDir() {
+  if info, err := loader.inputs.Stat(base.Absolute); err != nil || !info.IsDir() {
     cause := "the path names a file"
     if err != nil {
       cause = causeText(err)
@@ -25,13 +24,13 @@ func materializeRootedTypeScriptReference(claim claimSpec, reference referenceSp
   if !resolved {
     return state, []string{unresolvedBaseProblem(base, artifactTypeScript)}
   }
-  from, resolved = physicalTypeScriptPath(from)
+  from, resolved = physicalTypeScriptPath(from, loader.inputs)
   if !resolved {
     return state, []string{unresolvedBaseProblem(base, artifactTypeScript)}
   }
   entries := map[string]bool{}
   problems := []string{}
-  err := filepath.WalkDir(from, func(current string, entry fs.DirEntry, walkErr error) error {
+  err := loader.inputs.WalkDir(from, func(current string, entry fs.DirEntry, walkErr error) error {
     if walkErr != nil {
       return walkErr
     }

package/native/swagger.go

@@ -8,6 +8,7 @@ import (
   "net/url"
   "os"
   "os/exec"
+  "regexp"
   "sort"
   "strings"
   "time"
@@ -65,7 +66,8 @@ type swaggerNormalizationResult struct {
 // document's bytes — an entry that answers a later cycle with the wrong
 // document, forever.
 //
-// It is empty for a remote source, which never participates in reuse.
+// It is empty for a remote source, whose successful result is reused by URL
+// rather than by content for the process lifetime.
 type swaggerDocumentInventory struct {
   Source     string             `json:"source"`
   Operations []swaggerOperation `json:"operations"`
@@ -114,16 +116,37 @@ func loadSwaggerInventories(
   // two-hundred-operation one pay nearly the same. A resident host repeats
   // this every cycle, so an unchanged document is re-normalized on every
   // TypeScript keystroke that triggers a rebuild.
-  digests := swaggerContentDigests(root, sources)
+  config.inputs.Unavailable()
+  digests := swaggerContentDigests(root, sources, config.inputs)
+  trace := newEvidenceBridgeTrace("swagger")
+  if trace != nil {
+    trace.nativeLookup = true
+    trace.record("bridge-lookup", os.Getpid(), map[string]any{
+      "bridge": "swagger", "root": root, "sources": sources,
+      "nativeDigests": digests, "nativeLookup": true,
+    })
+  }
   pending := []string{}
   problems := graphDiagnostics{}
   severity := artifactSeverity(config, artifactSwagger)
   for _, source := range sources {
     outcome, hit := lookupSwaggerDocument(source, digests[source])
     if !hit {
+      if trace != nil {
+        _, present := digests[source]
+        trace.record("bridge-cache-miss", os.Getpid(), map[string]any{
+          "bridge": "swagger", "source": source, "nativeDigest": digests[source], "nativeDigestPresent": present,
+        })
+      }
       pending = append(pending, source)
       continue
     }
+    if trace != nil {
+      _, present := digests[source]
+      trace.record("bridge-cache-hit", os.Getpid(), map[string]any{
+        "bridge": "swagger", "source": source, "nativeDigest": digests[source], "nativeDigestPresent": present,
+      })
+    }
     problems = problems.add(
       swaggerSeverity(config, source),
       swaggerUnitsFromOutcome(source, inventories[source], outcome)...,
@@ -133,9 +156,13 @@ func loadSwaggerInventories(
     return inventories, problems
   }
 
-  result, err := normalizeSwaggerSources(root, pending)
+  result, err := normalizeSwaggerSources(root, pending, trace)
   if err != nil {
-    message := "Evidence graph could not run its Swagger normalizer: " + causeText(err) + ". Swagger references require Node.js and the installed @typia/interface, @typia/utils, and yaml dependencies."
+    reason := causeText(err)
+    for _, source := range pending {
+      reason = redactSwaggerError(source, reason)
+    }
+    message := "Evidence graph could not run its Swagger normalizer: " + reason + ". Swagger references require Node.js and the installed @typia/interface, @typia/utils, and yaml dependencies."
     for _, source := range pending {
       inventories[source].LoadFailed = true
       inventories[source].Problems = append(
@@ -229,22 +256,41 @@ func configuredSwaggerSources(config graphConfig) []string {
   return sources
 }
 
+// normalizeSwaggerSources retains the real Node request/Run/unmarshal boundary.
+// Optional private trace context pairs the caller's existing local digest map;
+// direct calls remain unpaired and do not invent native lookup values. Actual
+// pending source order, wire bytes, returned outcomes and cache keys are kept.
 func normalizeSwaggerSources(
   root string,
   sources []string,
+  traces ...*evidenceBridgeTrace,
 ) (swaggerNormalizationResult, error) {
+  var trace *evidenceBridgeTrace
+  if len(traces) != 0 {
+    trace = traces[0]
+  } else {
+    trace = newEvidenceBridgeTrace("swagger")
+  }
   request, err := json.Marshal(swaggerNormalizationRequest{
     Root:    root,
     Sources: sources,
   })
   if err != nil {
+    trace.preparationFailure(err)
     return swaggerNormalizationResult{}, err
   }
+  if trace != nil {
+    trace.record("bridge-request", os.Getpid(), map[string]any{
+      "bridge": "swagger", "root": root, "sources": sources, "nativeLookup": trace.nativeLookup,
+    })
+  }
   node := os.Getenv("TTSC_NODE_BINARY")
   if node == "" {
     node, err = exec.LookPath("node")
     if err != nil {
-      return swaggerNormalizationResult{}, errors.New("Node.js executable was not found")
+      failure := errors.New("Node.js executable was not found")
+      trace.preparationFailure(failure)
+      return swaggerNormalizationResult{}, failure
     }
   }
   ctx, cancel := context.WithTimeout(context.Background(), swaggerBridgeTimeout)
@@ -256,20 +302,43 @@ func normalizeSwaggerSources(
   stderr := &limitedBuffer{Limit: swaggerBridgeErrorLimit}
   command.Stdout = stdout
   command.Stderr = stderr
-  if err := command.Run(); err != nil {
-    if ctx.Err() == context.DeadlineExceeded {
+  start := trace.attempt(command)
+  runErr := command.Run()
+  deadlineExceeded := false
+  if runErr != nil {
+    deadlineExceeded = ctx.Err() == context.DeadlineExceeded
+  }
+  end := time.Time{}
+  if trace != nil {
+    end = time.Now().UTC()
+  }
+  if runErr != nil {
+    trace.result(command, stdout, stderr, start, end, runErr, "not-attempted", nil, nil, nil)
+    if deadlineExceeded {
       return swaggerNormalizationResult{}, errors.New("Swagger normalizer exceeded its 60 second timeout")
     }
     detail := strings.TrimSpace(stderr.String())
     if detail == "" {
-      detail = err.Error()
+      detail = runErr.Error()
     }
     return swaggerNormalizationResult{}, errors.New(detail)
   }
   var result swaggerNormalizationResult
   if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
+    trace.result(command, stdout, stderr, start, end, nil, "failed", err, nil, nil)
     return swaggerNormalizationResult{}, errors.New("Swagger normalizer returned invalid JSON: " + err.Error())
   }
+  if trace != nil {
+    documents := make([]string, 0, len(result.Documents))
+    problems := make([]string, 0, len(result.Problems))
+    for _, document := range result.Documents {
+      documents = append(documents, document.Source)
+    }
+    for _, problem := range result.Problems {
+      problems = append(problems, problem.Source)
+    }
+    trace.result(command, stdout, stderr, start, end, nil, "succeeded", nil, documents, problems)
+  }
   return result, nil
 }
 
@@ -315,27 +384,66 @@ func isRemoteSwaggerSource(source string) bool {
   return err == nil && (parsed.Scheme == "http" || parsed.Scheme == "https")
 }
 
+var swaggerErrorURL = regexp.MustCompile(`(?i)https?://[^\s"'<>]+`)
+
+// displaySwaggerSource presents a URL without userinfo, query or fragment.
+// Lexical boundaries also cover malformed URLs rejected by net/url. Local
+// filesystem paths retain their spelling; this value never enters cache or
+// transport identity. A malformed HTTP spelling without an authority has no
+// reliably separable host/path and is shown only with its scheme.
 func displaySwaggerSource(source string) string {
-  parsed, err := url.Parse(source)
-  if err != nil || (parsed.Scheme != "http" && parsed.Scheme != "https") {
+  lower := strings.ToLower(source)
+  if !strings.Contains(source, "://") && !strings.HasPrefix(lower, "http:") && !strings.HasPrefix(lower, "https:") {
     return source
   }
-  if parsed.User != nil {
-    parsed.User = url.User("***")
+  suffix := strings.IndexAny(source, "?#")
+  base := source
+  if suffix >= 0 {
+    base = source[:suffix]
+  }
+  scheme := strings.Index(base, "://")
+  if scheme < 0 {
+    return source[:strings.Index(source, ":")+1] + "[redacted]"
   }
-  if parsed.RawQuery != "" {
-    parsed.RawQuery = "<redacted>"
+  start := scheme + 3
+  end := len(base)
+  if slash := strings.Index(base[start:], "/"); slash >= 0 {
+    end = start + slash
+  }
+  if user := strings.LastIndex(base[start:end], "@"); user >= 0 {
+    base = base[:start] + "***@" + base[start+user+1:]
+  } else if _, err := url.Parse(base[:end]); err != nil {
+    // A malformed authority can be truncated userinfo, not a separable host.
+    base = base[:start] + "[redacted]" + base[end:]
+  }
+  if suffix >= 0 {
+    base += "?[redacted]"
+  }
+  return base
+}
+
+// redactSwaggerError sanitizes remote diagnostic presentation, including every
+// repeated or foreign URL reflected by an external error. Exact source lookup
+// and cache state retain their raw keys. Local filesystem causes stay intact.
+func redactSwaggerError(source string, message string) string {
+  if displaySwaggerSource(source) == source && !isRemoteSwaggerSource(source) {
+    return message
   }
-  return parsed.String()
+  message = strings.ReplaceAll(message, source, displaySwaggerSource(source))
+  return swaggerErrorURL.ReplaceAllStringFunc(message, displaySwaggerSource)
 }
 
 type limitedBuffer struct {
   bytes.Buffer
   Limit int
+  // Exceeded observes the existing failure boundary without changing its bytes
+  // or return error. A captured prefix cannot be a complete wire observation.
+  Exceeded bool
 }
 
 func (buffer *limitedBuffer) Write(content []byte) (int, error) {
   if buffer.Len()+len(content) > buffer.Limit {
+    buffer.Exceeded = true
     remaining := buffer.Limit - buffer.Len()
     if remaining > 0 {
       _, _ = buffer.Buffer.Write(content[:remaining])

package/native/swagger_cache.go

@@ -3,7 +3,6 @@ package evidence
 import (
   "crypto/sha256"
   "encoding/hex"
-  "os"
   "strings"
   "sync"
 )
@@ -33,7 +32,9 @@ const swaggerCacheLimit = 64
 var swaggerDocuments = newSwaggerCache()
 
 // swaggerRemoteDocuments remembers a URL's operations for the process lifetime,
-// keyed by the address rather than by content.
+// keyed by the address rather than by content, within the same entry bound as
+// the local cache: a session reading more distinct URLs than the bound fetches
+// the oldest again.
 //
 // A remote document has no key without fetching it, so it cannot be revalidated
 // the way a local file is. The choice is therefore not "cache or revalidate" but
@@ -65,7 +66,7 @@ var swaggerRemoteDocuments = newSwaggerCache()
 // non-empty. Inferring rejection from the message would turn a reason-less
 // failure into zero operations and no diagnostic — a rejected document that
 // reads exactly like an empty but passing one, which is the shape
-// `test_evidence_graph_reports_swagger_source_failures` exists to forbid.
+// `TestSwaggerReportsARejectionThatCarriesNoReason` exists to forbid.
 type swaggerDocumentOutcome struct {
   Operations []swaggerOperation
   Rejected   bool
@@ -126,18 +127,20 @@ func (cache *swaggerCache) store(digest string, outcome swaggerDocumentOutcome)
 //
 // The digest is the whole cache key, which is what makes staleness structural
 // rather than improbable: identical bytes normalize to identical operations, so
-// a hit can only return what the current file means. An edit, a truncation, or
-// a same-length replacement all change the digest and miss. A missing or
-// unreadable file yields no digest and is normalized as before, which keeps the
-// normalizer's own diagnostic for it.
+// a hit returns what the current file means to the normalizer that first read
+// it. The key names no project root and no normalizer installation. An edit, a
+// truncation, or a same-length replacement all change the digest and miss. A
+// missing or unreadable file yields no digest and is normalized as before, which
+// keeps the normalizer's own diagnostic for it.
 //
 // An HTTP(S) source never participates. A URL has no validator without a
 // fetch, and the fetch is most of what the normalizer costs, so a remote
 // document cannot be shown unchanged without paying the price of finding out.
-func swaggerContentDigests(root string, sources []string) map[string]string {
+func swaggerContentDigests(root string, sources []string, readers ...evidenceInputReader) map[string]string {
+  inputs := inputReader(readers)
   digests := map[string]string{}
   for _, source := range sources {
-    digest := swaggerContentDigest(root, source)
+    digest := swaggerContentDigest(root, source, inputs)
     if digest != "" {
       digests[source] = digest
     }
@@ -145,11 +148,12 @@ func swaggerContentDigests(root string, sources []string) map[string]string {
   return digests
 }
 
-func swaggerContentDigest(root string, source string) string {
+func swaggerContentDigest(root string, source string, readers ...evidenceInputReader) string {
+  inputs := inputReader(readers)
   if isRemoteSwaggerSource(source) {
     return ""
   }
-  content, err := os.ReadFile(swaggerSourcePath(root, source))
+  content, err := inputs.ReadFile(swaggerSourcePath(root, source))
   if err != nil {
     return ""
   }
@@ -262,7 +266,7 @@ func swaggerUnitsFromOutcome(
 // that trails off after a colon reads like a formatting bug rather than a
 // broken document.
 func swaggerNormalizationFailure(source string, message string) string {
-  reason := causeReason(strings.TrimSpace(message))
+  reason := causeReason(strings.TrimSpace(redactSwaggerError(source, message)))
   if reason == "" {
     reason = "the normalizer reported no reason"
   }

package/native/todo.go

@@ -86,6 +86,11 @@ func todoMessage(entry string) string {
 // '@todo' shares a block with '@param' or '@evidence' without swallowing them.
 // The tag name matches case-insensitively, because '@TODO' is the same promise
 // shouted.
+//
+// A fenced example is not read for tags, as it is not by the declaration parser:
+// a '@todo' shown inside one is documentation of the tag rather than a debt. A
+// fence inside an entry's text stays part of it, so the example is not cut out
+// of the debt it follows.
 func todoEntries(comment string) []string {
   comment = strings.TrimSpace(comment)
   comment = strings.TrimPrefix(comment, "/**")
@@ -100,9 +105,16 @@ func todoEntries(comment string) []string {
     entries = append(entries, strings.TrimSpace(strings.Join(pending, " ")))
     pending = nil
   }
+  fence := commentFence{}
   for _, rawLine := range strings.Split(comment, "\n") {
     line := strings.TrimSpace(rawLine)
     line = strings.TrimSpace(strings.TrimPrefix(line, "*"))
+    if fence.consume(line) {
+      if pending != nil && line != "" {
+        pending = append(pending, line)
+      }
+      continue
+    }
     if remainder, opened := todoLine(line); opened {
       flush()
       pending = []string{remainder}