@ttsc/evidence 0.25.0 → 0.26.0

package/native/markdown.go

@@ -98,6 +98,11 @@ func loadMarkdownBase(
         problems = append(problems, inventoryProblem.Message)
       }
     }
+    // An unreadable tag is not a health question and not a symbol question
+    // either: the file loaded, its units are complete, and the tag reaches no
+    // host whichever symbol a reference selects. The walk already refuses a
+    // path no configured glob takes, so reaching here is enough to report.
+    problems = append(problems, inventory.Unreadable...)
     return nil
   })
   if err != nil {
@@ -148,6 +153,16 @@ func scanMarkdownInventory(
   hostAtLine := make([]string, len(lines))
   hostIDAtLine := make([]string, len(lines))
   fencedAtLine := make([]bool, len(lines))
+  // commentAtLine marks the lines a citation or a review can live on, so the
+  // content digest can leave them out. A fenced block is not marked: an
+  // `<!-- -->` inside one hosts no tag, and its text is content of the section.
+  commentAtLine := make([]bool, len(lines))
+  // The nearest heading *unit* enclosing each line, which is not the same as its
+  // host: a heading may open a region without materializing a unit. Kept apart
+  // from hostIDAtLine because that value decides where a declaration sits, and
+  // widening it would move citations rather than only digests.
+  digestHostIDAtLine := make([]string, len(lines))
+  currentDigestHostID := fileUnitID
   currentHost := "file"
   currentHostID := fileUnitID
   fenceMarker := rune(0)
@@ -160,6 +175,11 @@ func scanMarkdownInventory(
     if marker, length, remainder, ok := markdownFence(line); ok {
       fencedAtLine[index] = true
       hostIDAtLine[index] = currentHostID
+      // Fenced content is content. It hosts no tag, so it is never excluded as a
+      // tag position, and leaving it unattributed would drop every code block out
+      // of its section's digest: rewriting the example in a cited section would
+      // then expire nothing.
+      digestHostIDAtLine[index] = currentDigestHostID
       if fenceMarker == 0 {
         fenceMarker = marker
         fenceLength = length
@@ -176,6 +196,7 @@ func scanMarkdownInventory(
       fencedAtLine[index] = true
       hostAtLine[index] = currentHost
       hostIDAtLine[index] = currentHostID
+      digestHostIDAtLine[index] = currentDigestHostID
       continue
     }
     if inHTMLComment {
@@ -184,6 +205,8 @@ func scanMarkdownInventory(
       }
       hostAtLine[index] = currentHost
       hostIDAtLine[index] = currentHostID
+      digestHostIDAtLine[index] = currentDigestHostID
+      commentAtLine[index] = true
       continue
     }
     if strings.HasPrefix(trimmed, "<!--") {
@@ -193,6 +216,8 @@ func scanMarkdownInventory(
       }
       hostAtLine[index] = currentHost
       hostIDAtLine[index] = currentHostID
+      digestHostIDAtLine[index] = currentDigestHostID
+      commentAtLine[index] = true
       continue
     }
     level, title, ok := markdownHeading(line)
@@ -204,6 +229,21 @@ func scanMarkdownInventory(
           headingUnitIDs[descendantLevel] = ""
         }
       }
+      // A heading that materializes no unit still opens a region, and that
+      // region's content belongs to the nearest heading unit enclosing it. An
+      // H5, and an H2 whose title yields no anchor, are both such headings.
+      // Carrying the previous unit forward instead would attribute the region to
+      // whatever unit the walk happened to see last, which is a sibling rather
+      // than an ancestor when the skipped heading is shallower: editing text
+      // under an anchorless H2 would then expire a review of the H3 above it,
+      // which does not contain that text.
+      currentDigestHostID = fileUnitID
+      for ancestorLevel := level - 1; ancestorLevel >= 1; ancestorLevel-- {
+        if headingUnitIDs[ancestorLevel] != "" {
+          currentDigestHostID = headingUnitIDs[ancestorLevel]
+          break
+        }
+      }
       if level <= 4 && targetablePath {
         title, anchor := markdownHeadingIdentity(title)
         if anchor == "" {
@@ -235,13 +275,17 @@ func scanMarkdownInventory(
           }
           inventory.Units = append(inventory.Units, unit)
           headingUnitIDs[level] = unit.ID
+          currentDigestHostID = unit.ID
         }
       }
     }
     hostAtLine[index] = currentHost
     hostIDAtLine[index] = currentHostID
+    digestHostIDAtLine[index] = currentDigestHostID
   }
 
+  reportUnreadableMarkdownTags(inventory, address.Display, lines, fencedAtLine, commentAtLine)
+
   sequence := 0
   for _, match := range markdownCommentPattern.FindAllStringSubmatchIndex(content, -1) {
     if len(match) < 4 {
@@ -269,10 +313,74 @@ func scanMarkdownInventory(
         Sequence:        sequence,
       })
     }
+    for _, review := range parseReviews(comment) {
+      inventory.Reviews = append(inventory.Reviews, &evidenceReview{
+        HostID:          hostIDAtLine[line-1],
+        SemanticHostIDs: []string{hostIDAtLine[line-1]},
+        Reviews:         review.Reviews,
+        Type:            artifactMarkdown,
+        Target:          review.Target,
+        Fingerprint:     review.Fingerprint,
+        Description:     review.Description,
+        Path:            address.Display,
+        Line:            line + review.LineOffset,
+      })
+    }
   }
+  assignMarkdownDigests(inventory, lines, digestHostIDAtLine, commentAtLine)
   return inventory, problems
 }
 
+// assignMarkdownDigests gives every unit the text it alone owns.
+//
+// A heading owns its own line and the body under it up to the next heading, and a
+// deeper heading starts a unit of its own, so the partition is exactly what
+// `digestHostIDAtLine` records while walking. Composing a subtree belongs to
+// `scopeIndex`, which is why nothing is folded in here: an H2 whose own body never
+// changed keeps its own digest even when an H3 beneath it did.
+//
+// This is where Markdown and TypeScript genuinely differ. A document can be
+// partitioned into disjoint regions, so a Markdown unit's digest really is
+// independent of its subtree. A declaration cannot: `interface ISale`
+// textually contains the members it declares, so a TypeScript unit's digest
+// covers its descendants whether anything wants it to or not.
+// `evidenceUnit.Digest` records the consequence; do not carry the Markdown
+// intuition across.
+//
+// HTML comment lines are dropped because that is where a Markdown citation and
+// its review live. Leaving them in would make writing the review change the
+// digest the review's own fingerprint is checked against.
+func assignMarkdownDigests(
+  inventory *artifactInventory,
+  lines []string,
+  digestHostIDAtLine []string,
+  commentAtLine []bool,
+) {
+  owned := map[string][]string{}
+  for index := range lines {
+    id := digestHostIDAtLine[index]
+    if index < len(commentAtLine) && commentAtLine[index] {
+      continue
+    }
+    if id == "" {
+      continue
+    }
+    // A comment opening after prose on the same line is still a tag position:
+    // the declaration scan runs over the whole document, so it finds a citation
+    // or a review there. Only the comment span comes out, never the line, or the
+    // prose beside it would vanish from the digest and a real content change
+    // would stop expiring anything.
+    content := markdownCommentPattern.ReplaceAllString(
+      strings.TrimSuffix(lines[index], "\r"),
+      "",
+    )
+    owned[id] = append(owned[id], content)
+  }
+  for _, unit := range inventory.Units {
+    unit.Digest = contentDigest(strings.Join(owned[unit.ID], "\n"))
+  }
+}
+
 // matchesConfiguredMarkdownFile reports whether a population rooted at this base
 // selects the file.
 //
@@ -421,3 +529,158 @@ func markdownSlug(title string) string {
   }
   return strings.Trim(builder.String(), "-")
 }
+
+// reportUnreadableMarkdownTags records every tag written where this artifact
+// kind cannot read one.
+//
+// A Markdown declaration is read from an HTML comment, so the tag renders
+// invisibly and the author sees the same source either way. Written as prose it
+// reaches no host and used to be discarded without a word, leaving the coverage
+// diagnostic that follows to name the reference and suggest writing the
+// citation the author had already written. TypeScript answers this shape and
+// the Prisma bridge answers its own; this is the kind that was left silent.
+//
+// A fenced block is an example rather than a citation and stays silent, which
+// is not a concession: this product's own documentation shows tags inside
+// fences, and reporting them would fail its build. An indented code block is
+// the same case in another spelling, so four leading spaces are read as code
+// rather than as prose.
+//
+// The tag has to open its line, which is the discrimination every reader in
+// this package performs, so a sentence mentioning one describes it rather than
+// declaring it.
+func reportUnreadableMarkdownTags(
+  inventory *artifactInventory,
+  location string,
+  lines []string,
+  fencedAtLine []bool,
+  commentAtLine []bool,
+) {
+  if inventory == nil {
+    return
+  }
+  rendered := false
+  for index, rawLine := range lines {
+    line := strings.TrimSuffix(rawLine, "
+    if opens, closes := renderedCodeEdges(line); opens || closes {
+      rendered = opens
+      continue
+    }
+    if rendered {
+      continue
+    }
+    if index < len(fencedAtLine) && fencedAtLine[index] {
+      continue
+    }
+    if index < len(commentAtLine) && commentAtLine[index] {
+      continue
+    }
+    if strings.HasPrefix(line, "    ") || strings.HasPrefix(line, "  ") {
+      continue
+    }
+    trimmed := markdownLineContent(line)
+    if tag, _, found := declarationLine(trimmed); found {
+      inventory.Unreadable = append(
+        inventory.Unreadable,
+        unreadableMarkdownProblem("@"+string(tag), location, index+1),
+      )
+      continue
+    }
+    if reviews, _, opened := reviewLine(trimmed); opened {
+      inventory.Unreadable = append(
+        inventory.Unreadable,
+        unreadableMarkdownProblem(reviewMarkerFor(reviews), location, index+1),
+      )
+    }
+  }
+}
+
+// markdownLineContent drops the markers that carry a line rather than say
+// anything.
+//
+// A citation written as a bullet or inside a quote is the same mistake as one
+// written bare, and an author reaching for a list is if anything more likely
+// than one writing a lone paragraph. Reading the line without its marker is
+// what lets the report name them, while the tag still has to be the first
+// content on the line, so a sentence mentioning one goes on describing it.
+func markdownLineContent(line string) string {
+  content := strings.TrimSpace(line)
+  for {
+    stripped := strings.TrimSpace(strings.TrimPrefix(content, ">"))
+    if stripped != content {
+      content = stripped
+      continue
+    }
+    if marker := markdownListMarker(content); marker != 0 {
+      content = strings.TrimSpace(content[marker:])
+      continue
+    }
+    return content
+  }
+}
+
+// markdownListMarker reports the length of a leading list marker, or zero.
+func markdownListMarker(content string) int {
+  for _, bullet := range []string{"- ", "* ", "+ "} {
+    if strings.HasPrefix(content, bullet) {
+      return len(bullet)
+    }
+  }
+  digits := 0
+  for digits < len(content) && content[digits] >= '0' && content[digits] <= '9' {
+    digits++
+  }
+  if digits == 0 || digits+1 >= len(content) {
+    return 0
+  }
+  if punctuation := content[digits]; punctuation != '.' && punctuation != ')' {
+    return 0
+  }
+  if content[digits+1] != ' ' {
+    return 0
+  }
+  return digits + 2
+}
+
+// renderedCodeEdges reports whether a line opens or closes a block that renders
+// as code without being a fence.
+//
+// A documentation site shows examples through more than one syntax. An MDX page
+// passes a template literal to a component, and an HTML page uses `<pre>`; both
+// render as code, so both are examples in the sense a fence is, and the repair
+// this diagnostic names would delete the example from the rendered page rather
+// than fix anything. Only the two edges are recognized, because a page that
+// opens one and never closes it is a page whose own build fails first.
+func renderedCodeEdges(line string) (bool, bool) {
+  lowered := strings.ToLower(line)
+  switch {
+  case strings.Contains(lowered, "<pre"):
+    return !strings.Contains(lowered, "</pre>"), strings.Contains(lowered, "</pre>")
+  case strings.Contains(lowered, "</pre>"):
+    return false, true
+  case strings.Contains(line, "={`"):
+    return !strings.Contains(line, "`}"), strings.Contains(line, "`}")
+  case strings.Contains(line, "`}"):
+    return false, true
+  }
+  return false, false
+}
+
+// unreadableMarkdownProblem names the position and the move that fixes it.
+func unreadableMarkdownProblem(tag string, location string, line int) string {
+  return "Unreadable " + tag + " at " + location + ":" + decimal(line) +
+    ": a Markdown declaration is read from an HTML comment, and this line is prose, so nothing reads the tag." +
+    " Wrap it as '<!-- " + tag + " <target> " + unreadableMarkdownField(tag) + " -->'."
+}
+
+// unreadableMarkdownField names what follows a target for this tag.
+//
+// A review carries a description of what was checked rather than a reason, and
+// every other review diagnostic in this package says so. One template for both
+// families would tell an author to write the wrong field.
+func unreadableMarkdownField(tag string) string {
+  if strings.HasSuffix(tag, "Review") {
+    return "<what you checked>"
+  }
+  return "<reason>"
+}

package/native/model.go

@@ -15,6 +15,27 @@ const documentedRuleName = "evidence/documented"
 
 const todoRuleName = "evidence/todo"
 
+const reviewRuleName = "evidence/review"
+
+// Appended to every diagnostic a tag could silence, because the cheapest way to
+// clear one of these is to write a tag that is not true, and the reader is
+// usually an agent whose next action is conditioned on this text alone.
+//
+// It names the motive rather than the truth value. A tag written to pass may
+// happen to be true and is still wrong, and "do not write a false tag" invites
+// exactly that reading.
+//
+// "Leave standing" rather than "write", because writing is only one of the ways
+// a falsehood clears a diagnostic. A tag can also be moved onto a declaration
+// that does not own its target, or kept when the conflicting one is deleted.
+// One verb covers all three, so every diagnostic carries the same sentence and
+// the reader meets one rule rather than three variants of it.
+const untrueTagWarning = " Never leave an untrue tag standing just to pass this check; it removes the error, not the problem."
+
+// The same warning for the two review tags, which are written about a check
+// rather than about a host.
+const untrueReviewWarning = " Never leave an untrue review standing just to pass this check; it removes the error, not the problem."
+
 type artifactKind string
 
 const (
@@ -87,6 +108,45 @@ type referencePolicy struct {
   // SingleEvidencePerSymbol requires exactly one distinct selected unit from
   // every selected semantic claim host, including the hosts carrying no tag.
   SingleEvidencePerSymbol bool
+  // RequireReview demands that every acknowledgement of this population carry
+  // an `@evidenceReview` whose fingerprint matches the cited scope's current
+  // content, so a review expires when the thing it reviewed moves.
+  RequireReview bool
+}
+
+// evidenceReview is one verification statement bound to its host and target.
+//
+// It is a sibling of evidenceDeclaration rather than a variant of it. Nothing
+// that counts acknowledgements may reach a review, so the two never share a
+// slice, a map, or a type. Target is the token as written and is compared
+// against a declaration's target rather than resolved again: the citation and
+// its review spell one address, and resolving twice would let a review answer a
+// scope its citation does not name.
+type evidenceReview struct {
+  // HostID is the source-position identity, kept only so a carrier with no
+  // semantic identity can still be matched. It must not be the primary key: a
+  // merged identity's halves sit at different positions and therefore carry
+  // different HostIDs, so matching on it alone refuses a review written on
+  // `namespace I` for a citation on `interface I` — placement the graph
+  // elsewhere calls not worth a diagnostic, and which `evidence/review` accepts.
+  HostID string
+  // SemanticHostIDs are the selected graph identities this review is written on,
+  // which is what a citation is matched by.
+  SemanticHostIDs []string
+  // Reviews names which acknowledgement this review answers for. It is part of
+  // the match, never inferred: verifying a citation and verifying an exclusion
+  // are opposite questions, so a review of one must not discharge the other.
+  Reviews     tagKind
+  Type        artifactKind
+  Target      string
+  Fingerprint string
+  Description string
+  Path        string
+  Line        int
+}
+
+func (review *evidenceReview) location() string {
+  return review.Path + ":" + decimal(review.Line)
 }
 
 // entrySelected reports whether this reference materializes by traversal.
@@ -152,6 +212,56 @@ type evidenceUnit struct {
   // never selected and never hosts a declaration; it is retained only so a
   // citation of it can be told why the target it names is not there.
   Hidden string
+  // ValueSpace marks a unit reached only through a value: a function, a
+  // variable, a class member, or a member of an interface merged with a class.
+  //
+  // A type-only export exposes no value, so it exposes none of these either.
+  // The collector answers that for an export written in the declaring file,
+  // where it knows the declaration kind in hand. A re-export naming another
+  // module arrives at traversal time with no such context, which is what this
+  // field supplies: the same question, asked once at materialization and
+  // answered wherever reachability arrives through a type-only edge.
+  //
+  // It is read together with TypeSpace rather than alone, because a merged
+  // identity is written by more than one collector and a plain assignment would
+  // let source order decide.
+  ValueSpace bool
+  // TypeSpace marks a unit some declaration of which is reached without a
+  // value, and it wins over ValueSpace.
+  //
+  // One identity can be spelled by two collectors: `interface Order { member }`
+  // beside `namespace Order { export const member }` is one `property` unit
+  // written once by the member collector and once by the variable one. A
+  // type-only export exposes the interface half, so the unit survives, and the
+  // answer must not depend on which half the author wrote first.
+  TypeSpace bool
+  // Digest is this unit's content, hashed after normalization and with every
+  // position a tag can live in removed.
+  //
+  // How much "its content" is depends on the artifact, and the difference is
+  // load-bearing rather than incidental. A Markdown heading owns the lines
+  // between it and the next heading, so a subsection's body belongs to the
+  // subsection. A TypeScript unit owns its whole declaration text, which
+  // **contains** every nested member's text, because that is what a declaration
+  // is: there is no reading of `interface ISale` that excludes the members it
+  // declares, callables included.
+  //
+  // So a nested change moves both its own unit's digest and every enclosing
+  // unit's. `scopeIndex` composes ancestors and descendants anyway, so detection
+  // is unaffected, but nothing here may assume a unit's digest is independent of
+  // its subtree. A feature built on that assumption was reverted once already.
+  //
+  // Removing the documentation comment is what stops the review from
+  // invalidating itself: writing an `@evidenceReview` inside a unit that is
+  // itself cited would otherwise change the digest that the review's own
+  // fingerprint is checked against, and the repair would never terminate.
+  //
+  // Empty when the bridge that read this artifact reported no content for the
+  // unit, which is a loader gap rather than a configuration one: every
+  // reference kind may require a review, and every bridge digests what it
+  // parsed. A consumer of an empty digest reports nothing rather than
+  // comparing against nothing.
+  Digest string
 }
 
 func (unit *evidenceUnit) location() string {
@@ -204,7 +314,18 @@ type artifactInventory struct {
   Type         artifactKind
   Units        []*evidenceUnit
   Declarations []*evidenceDeclaration
-  Problems     []inventoryProblem
+  // Reviews are the verification statements this artifact carries, kept apart
+  // from Declarations so no consumer counting acknowledgements can reach one.
+  Reviews  []*evidenceReview
+  Problems []inventoryProblem
+  // Unreadable lists the tags this artifact carries in a position nothing can
+  // read, already worded as diagnostics.
+  //
+  // They are kept apart from Problems because they are not a health question.
+  // The file loaded and its units are complete, so treating one as a failed
+  // population would suppress the obligations the author still owes while
+  // telling them only about a comment.
+  Unreadable []string
   // LoadFailed distinguishes an unreadable or rejected artifact from a
   // healthy artifact that legitimately materializes no selected units.
   // Coverage is a completeness claim, so a failed inventory cannot be used
@@ -232,6 +353,18 @@ type artifactInventory struct {
   // physical JSDoc declaration to semantic claim-host identities, then releases
   // it; callers with no such use leave it nil.
   UnitNodes map[string][]*shimast.Node
+  // UnitContent maps a unit ID to the nodes whose text is that identity's
+  // content, and is a subset of UnitNodes.
+  //
+  // Belonging to an identity and being its content are different questions,
+  // and a variable is where they part. TypeScript attaches a variable's
+  // leading documentation to the statement wrapper, so the wrapper is a
+  // position this identity owns — but the wrapper is also where its siblings
+  // are declared, and their text is not this identity's content. Answering the
+  // second question with the first makes one declarator's edit move another
+  // declarator's fingerprint. Each declaration site states which of its nodes
+  // is which; nothing here is derived from spans.
+  UnitContent map[string][]*shimast.Node
 }
 
 func (inventory *artifactInventory) recordUnitNode(id string, node *shimast.Node) {
@@ -241,6 +374,23 @@ func (inventory *artifactInventory) recordUnitNode(id string, node *shimast.Node
   inventory.UnitNodes[id] = append(inventory.UnitNodes[id], node)
 }
 
+// recordUnitContent records a node as this identity's content, and as a
+// position it owns.
+//
+// Content is recorded through the position index rather than beside it, so the
+// subset the field documents holds by construction instead of by two callers
+// agreeing.
+func (inventory *artifactInventory) recordUnitContent(id string, node *shimast.Node) {
+  if inventory == nil || node == nil {
+    return
+  }
+  inventory.recordUnitNode(id, node)
+  if inventory.UnitNodes == nil || inventory.UnitContent == nil {
+    return
+  }
+  inventory.UnitContent[id] = append(inventory.UnitContent[id], node)
+}
+
 type inventoryProblem struct {
   Symbol  string
   Message string
@@ -251,6 +401,7 @@ type claimState struct {
   Paths        []string
   Hosts        []*evidenceUnit
   Declarations []*evidenceDeclaration
+  Reviews      []*evidenceReview
   References   []referenceState
   Healthy      bool
   // OutsideCarrier names declarations this claim selected from a file its
@@ -264,6 +415,12 @@ type referenceState struct {
   Paths  []string
   Units  []*evidenceUnit
   Scopes []*evidenceUnit
+  // Population is every unit this reference's files materialized, selected or
+  // not. Units and Scopes are both narrowed by the `symbol` selector, so
+  // neither can answer what a cited scope structurally contains, and a review
+  // fingerprint has to be a property of the cited address rather than of the
+  // reference that asked for it.
+  Population []*evidenceUnit
   // Published names the module-and-address pairs a citation may use, for a
   // population selected by walking module exports. Left empty when the
   // population's addresses belong to the files that declare them.
@@ -294,3 +451,24 @@ func decimal(value int) string {
   }
   return string(digits)
 }
+
+// markSpace records which space this declaration of the unit is reached
+// through, letting type-space win.
+//
+// A plain assignment made the answer depend on which half of a merged identity
+// the author wrote first, in the one shape where two collectors write one unit:
+// an interface member beside a namespace member of the same name. The
+// suppression it feeds is a silent one, so the divergence was a build going
+// green or red on declaration order with no message either way.
+//
+// Every site goes through here, including the ones that can only ever be value
+// space. A site that assigns the field directly is correct until the day its
+// address collides with a type-space one, and that is exactly the day nobody is
+// looking at it.
+func (unit *evidenceUnit) markSpace(valueSpace bool) {
+  if valueSpace {
+    unit.ValueSpace = true
+    return
+  }
+  unit.TypeSpace = true
+}

package/native/prisma.go

@@ -94,15 +94,24 @@ type prismaSetProblem struct {
 }
 
 type prismaModel struct {
-  Name          string        `json:"name"`
-  Documentation string        `json:"documentation"`
-  Fields        []prismaField `json:"fields"`
+  Name          string `json:"name"`
+  Documentation string `json:"documentation"`
+  // Digest is the model's own declaration, hashed by the bridge that parsed it,
+  // with its documentation and its fields left out. A field is a unit of its
+  // own and the scope composes them, so folding them in here would make one
+  // field's edit expire a review of every sibling.
+  Digest string        `json:"digest"`
+  Fields []prismaField `json:"fields"`
 }
 
 type prismaField struct {
   Name          string `json:"name"`
   Symbol        string `json:"symbol"`
   Documentation string `json:"documentation"`
+  // Digest is the field's own declaration, with its documentation left out.
+  // Its type, its attributes, and their arguments reach no other part of this
+  // process, so this is the only place a change to them is visible.
+  Digest string `json:"digest"`
 }
 
 // loadPrismaInventories materializes one inventory per configured schema file.
@@ -469,6 +478,7 @@ func prismaModelUnits(model prismaModel) []*evidenceUnit {
     Symbol:   "model",
     Readable: "Prisma model '" + model.Name + "'",
     Hidden:   modelHidden,
+    Digest:   model.Digest,
   }}
   seen := map[string]bool{}
   for _, field := range model.Fields {
@@ -493,6 +503,7 @@ func prismaModelUnits(model prismaModel) []*evidenceUnit {
       Symbol:   field.Symbol,
       Readable: "Prisma " + field.Symbol + " '" + model.Name + "." + field.Name + "'",
       Hidden:   fieldHidden,
+      Digest:   field.Digest,
     })
   }
   return units
@@ -566,6 +577,29 @@ func prismaDeclarationsFromComments(
           inventory.Declarations = append(inventory.Declarations, declaration)
         }
       }
+      // An unattached run is the one position that accepts `@evidenceExclude`
+      // and never `@evidence`, and a lint-only `.schema` ledger is built out of
+      // exactly these. Its exclusions owe a review like any other
+      // acknowledgement, so the review has to be readable here too. Collecting
+      // it only where a declaration is attached would leave the ledger reporting
+      // every exclusion unreviewed forever, with the repair written in a comment
+      // nothing reads back — the same dead end the attached case just escaped.
+      for _, review := range parseReviews(run.Body) {
+        shared := &evidenceReview{
+          HostID:          "prisma:" + run.Path + ":file",
+          SemanticHostIDs: []string{"prisma:" + run.Path + ":file"},
+          Reviews:         review.Reviews,
+          Type:            artifactPrisma,
+          Target:          review.Target,
+          Fingerprint:     review.Fingerprint,
+          Description:     review.Description,
+          Path:            run.Path,
+          Line:            run.Line + review.LineOffset,
+        }
+        for _, inventory := range hosted {
+          inventory.Reviews = append(inventory.Reviews, shared)
+        }
+      }
       continue
     }
     if run.Key == "" {
@@ -622,6 +656,28 @@ func prismaDeclarationsFromComments(
         inventory.Declarations = append(inventory.Declarations, declaration)
       }
     }
+    // Reviews are read here for the same reason the citations are. Without
+    // this, a Prisma claim citing a reference that requires a review reports
+    // every citation unreviewed forever, and the repair the message names —
+    // write the tag in this documentation comment — has no effect, because
+    // nothing reads the tag back out. A diagnostic must never name a repair the
+    // author cannot perform.
+    for _, review := range parseReviews(run.Body) {
+      shared := &evidenceReview{
+        HostID:          host.ID,
+        SemanticHostIDs: []string{host.ID},
+        Reviews:         review.Reviews,
+        Type:            artifactPrisma,
+        Target:          review.Target,
+        Fingerprint:     review.Fingerprint,
+        Description:     review.Description,
+        Path:            run.Path,
+        Line:            run.Line + review.LineOffset,
+      }
+      for _, inventory := range hosted {
+        inventory.Reviews = append(inventory.Reviews, shared)
+      }
+    }
   }
   return problems
 }