@ttsc/evidence 0.31.5 → 0.32.1

package/README.md

@@ -117,6 +117,19 @@ One claim: the components under `src` implement the docs, so every H2 and H3 und
 
 The configuration is written once. The tags are written forever: `@evidence` cites, `@evidenceReview` verifies, and `@evidenceExclude` declines. [The tag reference](https://ttsc.dev/docs/evidence/tags) has the full grammar.
 
+A reason that needs paragraphs, a list or subheadings goes under an H2 to H4 heading, with the target on the heading and the explanation below it:
+
+```ts
+/**
+ * ## @evidence docs/discount.md#coupon-stacking
+ *
+ * Renders the per-issuer limit this section defines.
+ *
+ * - Reads the limit from props.
+ * - Names the issuer that reached it.
+ */
+```
+
 A false tag removes the error, not the problem. `@evidenceReview` asks for a separate statement of what was verified, which a human then judges:
 
 ```ts

package/native/declaration.go

@@ -60,70 +60,177 @@ func parseCommentDeclarations(
   tagBoundaries bool,
 ) []parsedDeclaration {
   body, leadingLines, documented := documentationCommentBody(comment)
-  jsdoc := documented || tagBoundaries
-  type pendingDeclaration struct {
-    tag        tagKind
-    body       []string
-    lineOffset int
-  }
-  var pending *pendingDeclaration
+  return parseRegionDeclarations(
+    documentationRegions(body, false),
+    documented || tagBoundaries,
+    leadingLines,
+  )
+}
+
+// parseRegionDeclarations reads the citations and exclusions of documentation
+// lines whose examples are already classified.
+//
+// It owns the annotation grammar independently of where the lines came from, so
+// every host that can spell an annotation agrees on where one begins, what it
+// says and where it ends. tagBoundaries has the meaning documented on
+// parseCommentDeclarations.
+func parseRegionDeclarations(
+  regions []documentationRegionLine,
+  tagBoundaries bool,
+  leadingLines int,
+) []parsedDeclaration {
+  var pending *pendingAnnotation
   parsed := []parsedDeclaration{}
   flush := func() {
     if pending == nil {
       return
     }
-    target, reason := splitDeclarationBody(strings.Join(pending.body, "\n"))
+    target, reason := pending.split()
     parsed = append(parsed, parsedDeclaration{
-      Tag:        pending.tag,
+      Tag:        pending.opener.tag,
       Target:     target,
       Reason:     reason,
       LineOffset: leadingLines + pending.lineOffset,
     })
     pending = nil
   }
-  for index, region := range documentationRegions(body, false) {
+  for index, region := range regions {
     if region.fence {
-      flush()
+      // An example never supplies prose. A line-form annotation ends at it; a
+      // heading section resumes after it, because headings rather than examples
+      // decide where a section ends.
+      if !pending.section() {
+        flush()
+      }
       continue
     }
-    line := region.text
-    tag, body, found := declarationLine(line)
-    if found {
+    if opener, opened := region.opener(); opened {
       flush()
-      pending = &pendingDeclaration{
-        tag:        tag,
-        body:       []string{body},
-        lineOffset: index,
+      // A review closes the declaration above it in every host, and it does so
+      // regardless of tagBoundaries. That flag answers whether *another tool's*
+      // `@tag` is a boundary, which is a property of the host's comment grammar:
+      // an HTML comment has no field syntax, so `@architecture approved this` is
+      // ordinary prose belonging to the reason above it, and a test pins that.
+      //
+      // A review is not another tool's tag. It belongs to this grammar, so it is
+      // always a boundary. Without this, an `@evidenceReview` written under an
+      // `@evidence` inside one Markdown comment was swallowed into that citation's
+      // reason: the review vanished and the reason grew a sentence its author
+      // addressed to a different question.
+      if !opener.review {
+        pending = &pendingAnnotation{opener: opener, lineOffset: index}
       }
       continue
     }
-    // A review closes the declaration above it in every host, and it does so
-    // regardless of tagBoundaries. That flag answers whether *another tool's*
-    // `@tag` is a boundary, which is a property of the host's comment grammar:
-    // an HTML comment has no field syntax, so `@architecture approved this` is
-    // ordinary prose belonging to the reason above it, and a test pins that.
-    //
-    // A review is not another tool's tag. It belongs to this grammar, so it is
-    // always a boundary. Without this, an `@evidenceReview` written under an
-    // `@evidence` inside one Markdown comment was swallowed into that citation's
-    // reason: the review vanished and the reason grew a sentence its author
-    // addressed to a different question.
-    if _, _, opened := reviewLine(line); opened {
+    if pending.closedBy(region) {
       flush()
       continue
     }
-    if jsdoc && strings.HasPrefix(line, "@") {
+    if tagBoundaries && region.opensTagBoundary() {
       flush()
       continue
     }
     if pending != nil {
-      pending.body = append(pending.body, line)
+      pending.lines = append(pending.lines, region.text)
     }
   }
   flush()
   return parsed
 }
 
+// annotationOpener is the start of one annotation as a documentation line
+// spells it.
+//
+// The line form opens with the tag itself. The heading form is an H2, H3 or H4
+// heading whose title opens with the tag, and it exists for explanations long
+// enough to need paragraphs, lists and subheadings of their own.
+type annotationOpener struct {
+  // review reports a verification statement rather than an acknowledgement.
+  review bool
+
+  // tag is the acknowledgement kind, or for a review the kind it answers for.
+  tag tagKind
+
+  // body is what follows the tag on the opening line: the target, and any
+  // reason or review remainder written beside it.
+  body string
+
+  // heading is the depth of a heading-form opener, or zero for the line form.
+  heading int
+}
+
+// openAnnotation reads the annotation one documentation line opens, if any.
+//
+// A heading of another depth stays an ordinary heading, and no heading opens
+// the line form because its first character is `#`. The five tags share one
+// spelling in both forms, so the two forms cannot disagree about which tag a
+// line carries: the title of a heading is read by the same matchers as a line.
+func openAnnotation(text string, heading int, title string) (annotationOpener, bool) {
+  if heading != 0 {
+    if heading < 2 || heading > 4 {
+      return annotationOpener{}, false
+    }
+    text = title
+  }
+  if tag, body, found := declarationLine(text); found {
+    return annotationOpener{tag: tag, body: body, heading: heading}, true
+  }
+  if reviews, remainder, opened := reviewLine(text); opened {
+    return annotationOpener{review: true, tag: reviews, body: remainder, heading: heading}, true
+  }
+  return annotationOpener{}, false
+}
+
+// opensAcknowledgement reports whether a documentation line opens a citation
+// or an exclusion in either form, for a caller that reports a tag it cannot
+// read and so needs only to know that one is there.
+func opensAcknowledgement(text string, heading int, title string) bool {
+  opener, opened := openAnnotation(text, heading, title)
+  return opened && !opener.review
+}
+
+// pendingAnnotation accumulates one annotation until a boundary ends it.
+type pendingAnnotation struct {
+  opener annotationOpener
+
+  // lines are the documentation lines after the opener that continue it.
+  lines []string
+
+  // lineOffset is the opener's line within the documentation body.
+  lineOffset int
+}
+
+// section reports whether this is a heading-form annotation. A nil receiver is
+// no annotation at all.
+func (pending *pendingAnnotation) section() bool {
+  return pending != nil && pending.opener.heading != 0
+}
+
+// closedBy reports whether a heading ends this annotation's explanation.
+//
+// Only a heading section has that structure. A heading of its own depth or
+// shallower is the next part of the surrounding document; a deeper heading
+// divides the explanation itself and stays inside it. A line-form annotation
+// keeps the continuation it always had, which a heading does not end.
+func (pending *pendingAnnotation) closedBy(region documentationRegionLine) bool {
+  return pending.section() && region.heading != 0 && region.heading <= pending.opener.heading
+}
+
+// split returns the annotation's target and the text after it.
+//
+// A line-form target may be written on the line after its tag, so its lines
+// are split as one body, as they always were. A heading section's target must
+// be on the heading: the heading body is split alone, which keeps the
+// explanation from ever becoming a target and keeps an unterminated link on the
+// heading from borrowing a closing brace from the prose under it.
+func (pending *pendingAnnotation) split() (string, string) {
+  if !pending.section() {
+    return splitDeclarationBody(strings.Join(append([]string{pending.opener.body}, pending.lines...), "\n"))
+  }
+  target, remainder := splitDeclarationBody(pending.opener.body)
+  return target, strings.TrimSpace(strings.Join(append([]string{remainder}, pending.lines...), "\n"))
+}
+
 func declarationLine(line string) (tagKind, string, bool) {
   for _, candidate := range []struct {
     marker string
@@ -314,43 +421,55 @@ func (review parsedReview) marker() string {
 // block with `@param` or a following `@evidence` swallows neither.
 func parseReviews(comment string) []parsedReview {
   comment, leadingLines, _ := documentationCommentBody(comment)
+  return parseRegionReviews(documentationRegions(comment, true), leadingLines)
+}
+
+// parseRegionReviews reads the reviews of documentation lines whose examples
+// are already classified, under the grammar parseRegionDeclarations applies to
+// acknowledgements. A heading-form review may carry its fingerprint on the
+// heading or open its description with it.
+func parseRegionReviews(regions []documentationRegionLine, leadingLines int) []parsedReview {
   reviews := []parsedReview{}
-  var pending *parsedReview
-  var body []string
+  var pending *pendingAnnotation
   flush := func() {
     if pending == nil {
       return
     }
-    target, remainder := splitDeclarationBody(strings.Join(body, "\n"))
+    target, remainder := pending.split()
     fingerprint, description := splitReviewFingerprint(remainder)
-    pending.Target = target
-    pending.Fingerprint = fingerprint
-    pending.Description = description
-    reviews = append(reviews, *pending)
+    reviews = append(reviews, parsedReview{
+      Reviews:     pending.opener.tag,
+      Target:      target,
+      Fingerprint: fingerprint,
+      Description: description,
+      LineOffset:  leadingLines + pending.lineOffset,
+    })
     pending = nil
-    body = nil
   }
-  for index, region := range documentationRegions(comment, true) {
+  for index, region := range regions {
     if region.fence {
-      flush()
+      if !pending.section() {
+        flush()
+      }
       continue
     }
-    line := region.text
-    if reviews, remainder, opened := reviewLine(line); opened {
+    if opener, opened := region.opener(); opened {
       flush()
-      pending = &parsedReview{
-        Reviews:    reviews,
-        LineOffset: leadingLines + index,
+      if opener.review {
+        pending = &pendingAnnotation{opener: opener, lineOffset: index}
       }
-      body = []string{remainder}
       continue
     }
-    if strings.HasPrefix(line, "@") {
+    if pending.closedBy(region) {
+      flush()
+      continue
+    }
+    if region.opensTagBoundary() {
       flush()
       continue
     }
     if pending != nil {
-      body = append(body, line)
+      pending.lines = append(pending.lines, region.text)
     }
   }
   flush()

package/native/documentation_regions.go

@@ -13,6 +13,52 @@ type documentationRegionLine struct {
 
   // fence ends pending prose and suppresses tags throughout the example.
   fence bool
+
+  // heading is the ATX depth when the line is a heading, or zero. A heading
+  // annotation's explanation ends at a heading of its own depth or shallower.
+  heading int
+
+  // title is the heading text without closing hashes or an explicit anchor,
+  // which are heading syntax and never part of an annotation's target or reason.
+  title string
+
+  // explanatory marks prose that can only continue an explanation: it opens no
+  // one-line annotation and ends none. Visible Markdown is read this way,
+  // because rendered prose carries annotations only under headings.
+  explanatory bool
+}
+
+// opener reads the annotation this line opens, if any. An explanatory line
+// opens one only as a heading.
+func (region documentationRegionLine) opener() (annotationOpener, bool) {
+  if region.explanatory && region.heading == 0 {
+    return annotationOpener{}, false
+  }
+  return openAnnotation(region.text, region.heading, region.title)
+}
+
+// opensTagBoundary reports whether the line opens some `@tag`, which ends a
+// pending explanation in hosts whose grammar gives tags that meaning.
+func (region documentationRegionLine) opensTagBoundary() bool {
+  return !region.explanatory && strings.HasPrefix(region.text, "@")
+}
+
+// documentationHeading reads an ATX heading from one line of documentation
+// prose or of a Markdown file's heading view, either of which may keep up to
+// three columns of margin.
+//
+// It uses the Markdown scanner's own heading grammar, so a heading inside a
+// documentation comment and a heading in a Markdown file agree on depth,
+// required spacing and closing hashes. The explicit `{#anchor}` suffix is
+// removed because it names the heading for Markdown addressing, which an
+// annotation's target or reason must never absorb.
+func documentationHeading(text string) (int, string) {
+  level, title, ok := markdownHeading(text)
+  if !ok {
+    return 0, ""
+  }
+  title, _ = markdownHeadingIdentity(title)
+  return level, title
 }
 
 // documentationCommentBody removes only a real native wrapper. Mapped Prisma
@@ -139,6 +185,11 @@ func documentationRegions(body string, slashDecoration bool) []documentationRegi
       at++
     }
     result[index].text = strings.TrimSpace(string(masked))
+    // A heading allows the same three columns of margin a fence does; four or
+    // more make the line indented code, which opens and ends nothing.
+    if relative >= 0 && relative <= 3 {
+      result[index].heading, result[index].title = documentationHeading(result[index].text)
+    }
     offset += len(line) + 1
   }
   return result

package/native/markdown.go

@@ -665,13 +665,55 @@ func scanMarkdownInventory(
   currentHost := "file"
   currentHostID := fileUnitID
   lexical, commentSpans := scanMarkdownRegions(content, lines)
+  sections := markdownAnnotationSections(lexical)
+  sectionAt := make([]int, len(lines))
+  for index := range sectionAt {
+    sectionAt[index] = -1
+  }
+  for position, section := range sections {
+    for index := section.start; index < section.end; index++ {
+      sectionAt[index] = position
+    }
+  }
+  // The latest outline heading at each depth, so an annotation section can
+  // name the heading it is nested in. Annotation headings never enter it: they
+  // are metadata about a section, not sections of their own.
+  outlineHosts := [7]markdownHost{}
+  sectionOwners := make([]markdownHost, len(sections))
   headingUnitIDs := [5]string{}
   for index := range lines {
+    if position := sectionAt[index]; position >= 0 {
+      section := sections[position]
+      if index == section.start {
+        // An annotation answers for the section it is nested in: the nearest
+        // heading shallower than its own, or the file. A heading of its own
+        // depth is a sibling it does not belong to.
+        sectionOwners[position] = markdownHost{symbol: "file", id: fileUnitID}
+        for depth := section.level - 1; depth >= 1; depth-- {
+          if outlineHosts[depth].symbol != "" {
+            sectionOwners[position] = outlineHosts[depth]
+            break
+          }
+        }
+      }
+      // Every line of the section, including a comment written in it, belongs
+      // to that owner, and none of them is any unit's content: an annotation is
+      // metadata exactly as an HTML comment is, so writing or editing one
+      // expires no review.
+      hostAtLine[index] = sectionOwners[position].symbol
+      hostIDAtLine[index] = sectionOwners[position].id
+      digestHostIDAtLine[index] = ""
+      continue
+    }
     visible := lexical[index].Heading
     level, title, ok := markdownHeading(visible)
     if ok {
       currentHost = "h" + decimal(level)
       currentHostID = "markdown:" + address.Key + ":" + currentHost + ":" + decimal(index+1)
+      outlineHosts[level] = markdownHost{symbol: currentHost, id: currentHostID}
+      for deeper := level + 1; deeper < len(outlineHosts); deeper++ {
+        outlineHosts[deeper] = markdownHost{}
+      }
       if level <= 4 {
         for descendantLevel := level; descendantLevel <= 4; descendantLevel++ {
           headingUnitIDs[descendantLevel] = ""
@@ -750,7 +792,7 @@ func scanMarkdownInventory(
     digestHostIDAtLine[index] = currentDigestHostID
   }
 
-  reportUnreadableMarkdownTags(inventory, address.Display, lexical)
+  reportUnreadableMarkdownTags(inventory, address.Display, lexical, sections)
 
   sequence := 0
   for _, match := range commentSpans {
@@ -795,10 +837,50 @@ func scanMarkdownInventory(
       })
     }
   }
+  for position, section := range sections {
+    owner := sectionOwners[position]
+    regions := markdownSectionRegions(lines, lexical, section)
+    for _, parsed := range parseRegionDeclarations(regions, false, 0) {
+      sequence++
+      line := section.start + 1 + parsed.LineOffset
+      inventory.Declarations = append(inventory.Declarations, &evidenceDeclaration{
+        ID:              "markdown:" + address.Key + ":" + decimal(line) + ":" + decimal(sequence),
+        HostID:          owner.id,
+        SemanticHostIDs: []string{owner.id},
+        Type:            artifactMarkdown,
+        Tag:             parsed.Tag,
+        Target:          parsed.Target,
+        Reason:          parsed.Reason,
+        Hosts:           symbolSet{owner.symbol: true},
+        Path:            address.Display,
+        Line:            line,
+        Sequence:        sequence,
+      })
+    }
+    for _, review := range parseRegionReviews(regions, 0) {
+      inventory.Reviews = append(inventory.Reviews, &evidenceReview{
+        SemanticHostIDs: []string{owner.id},
+        Reviews:         review.Reviews,
+        Type:            artifactMarkdown,
+        Target:          review.Target,
+        Fingerprint:     review.Fingerprint,
+        Description:     review.Description,
+        Path:            address.Display,
+        Line:            section.start + 1 + review.LineOffset,
+      })
+    }
+  }
   assignMarkdownDigests(inventory, content, lines, digestHostIDAtLine, commentSpans)
   return inventory, problems
 }
 
+// markdownHost names the host a Markdown line belongs to: the symbol a claim
+// selects it by and the identity its declarations record.
+type markdownHost struct {
+  symbol string
+  id     string
+}
+
 // 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
@@ -978,6 +1060,132 @@ func selectedByMarkdownPopulation(
   return false
 }
 
+// markdownAnnotationSection is one visible heading annotation: the zero-based
+// line of its opening heading, the line after its explanation, and the
+// opening heading's depth.
+type markdownAnnotationSection struct {
+  start int
+  end   int
+  level int
+}
+
+// markdownAnnotationSections finds every visible H2-H4 annotation heading and
+// the explanation under it.
+//
+// The headings are the outline's own: the lexical heading view decides them,
+// so a heading inside code, a rendered example or a comment opens nothing, and
+// one inside a blockquote or a list is not a heading of the document at all. A
+// section ends at the next heading of its depth or shallower, which is the next
+// part of the document, or at the next annotation heading, which starts its
+// own. A deeper ordinary heading divides the explanation and stays inside it.
+func markdownAnnotationSections(lexical []markdownLexicalLine) []markdownAnnotationSection {
+  sections := []markdownAnnotationSection{}
+  for index := 0; index < len(lexical); {
+    level, title := documentationHeading(lexical[index].Heading)
+    if _, opened := openAnnotation(lexical[index].Heading, level, title); level == 0 || !opened {
+      index++
+      continue
+    }
+    end := index + 1
+    for ; end < len(lexical); end++ {
+      next, nextTitle := documentationHeading(lexical[end].Heading)
+      if next == 0 {
+        continue
+      }
+      if _, opened := openAnnotation(lexical[end].Heading, next, nextTitle); opened || next <= level {
+        break
+      }
+    }
+    sections = append(sections, markdownAnnotationSection{start: index, end: end, level: level})
+    index = end
+  }
+  return sections
+}
+
+// markdownSectionRegions presents one visible annotation section to the shared
+// annotation grammar.
+//
+// Headings keep their outline reading, so the grammar sees the same depths the
+// outline does. Every other line is explanatory prose: it can explain, but in
+// rendered Markdown only a heading carries an annotation, so it opens and ends
+// none.
+func markdownSectionRegions(
+  lines []string,
+  lexical []markdownLexicalLine,
+  section markdownAnnotationSection,
+) []documentationRegionLine {
+  regions := make([]documentationRegionLine, 0, section.end-section.start)
+  for index := section.start; index < section.end; index++ {
+    if level, title := documentationHeading(lexical[index].Heading); level != 0 {
+      regions = append(regions, documentationRegionLine{
+        text:        strings.TrimSpace(lexical[index].Heading),
+        heading:     level,
+        title:       title,
+        explanatory: true,
+      })
+      continue
+    }
+    regions = append(regions, documentationRegionLine{
+      text:        markdownReadableProse(strings.TrimSuffix(lines[index], "\r"), lexical[index]),
+      explanatory: true,
+    })
+  }
+  return regions
+}
+
+// markdownReadableProse returns what a reader of the rendered document reads
+// as prose on one line, or nothing when the line is no prose.
+//
+// Whether a line explains is decided by the prose view: a line left empty once
+// code, rendered examples, comments and escapes are removed is an example or
+// metadata, so an example cannot supply a missing reason. Two visible lines are
+// no prose either. A closing fence is the code block's syntax although the
+// parser leaves it outside the block, and a line opening a tag is an
+// annotation nothing reads, which is reported on its own rather than becoming
+// the explanation of another.
+//
+// What an explaining line says is read from the heading view instead, which
+// removes comments but keeps inline code and the other inline text a reader
+// reads, so a review description shown in a diagnostic keeps its words.
+func markdownReadableProse(line string, lexical markdownLexicalLine) string {
+  if _, opened := markdownProseTag(markdownLineContent(lexical.Prose)); opened {
+    return ""
+  }
+  prose := markdownKeptText(line, lexical.Prose)
+  if prose == "" {
+    return ""
+  }
+  if _, _, _, fence := markdownFence(markdownLineContent(prose)); fence {
+    return ""
+  }
+  return markdownKeptText(line, lexical.Heading)
+}
+
+// markdownKeptText keeps the bytes of a line that a lexical view left
+// unmasked. A view never moves a byte, so comparing positions is exact, and a
+// sentinel a view writes over masked bytes differs from the source it hides.
+func markdownKeptText(line string, view string) string {
+  kept := []byte(line)
+  for index := range kept {
+    if index >= len(view) || view[index] != line[index] {
+      kept[index] = ' '
+    }
+  }
+  return strings.TrimSpace(string(kept))
+}
+
+// markdownProseTag returns the tag a line of visible prose opens, spelled the
+// way an unreadable-tag diagnostic names it.
+func markdownProseTag(content string) (string, bool) {
+  if tag, _, found := declarationLine(content); found {
+    return "@" + string(tag), true
+  }
+  if reviews, _, opened := reviewLine(content); opened {
+    return reviewMarkerFor(reviews), true
+  }
+  return "", false
+}
+
 func markdownFence(line string) (rune, int, string, bool) {
   indent := 0
   for indent < len(line) && line[indent] == ' ' {
@@ -1060,12 +1268,17 @@ func markdownSlug(title string) 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 Markdown declaration is read from an HTML comment or from an H2, H3 or H4
+// annotation heading of the document. 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 heading whose title opens a tag is the same mistake when it carries
+// nothing: an H1, H5 or H6, or a heading inside a blockquote or a list, which
+// is no heading of the document's outline. Every heading that does open an
+// annotation section is skipped, since the section reads it.
 //
 // 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
@@ -1082,18 +1295,28 @@ func reportUnreadableMarkdownTags(
   inventory *artifactInventory,
   location string,
   lexical []markdownLexicalLine,
+  sections []markdownAnnotationSection,
 ) {
   if inventory == nil {
     return
   }
+  openers := make(map[int]bool, len(sections))
+  for _, section := range sections {
+    openers[section.start] = true
+  }
   for index, line := range lexical {
     trimmed := markdownLineContent(line.Prose)
-    if tag, _, found := declarationLine(trimmed); found {
-      inventory.Unreadable = append(inventory.Unreadable, unreadableMarkdownProblem("@"+string(tag), location, index+1))
+    if tag, found := markdownProseTag(trimmed); found {
+      inventory.Unreadable = append(inventory.Unreadable, unreadableMarkdownProblem(tag, location, index+1, false))
       continue
     }
-    if reviews, _, opened := reviewLine(trimmed); opened {
-      inventory.Unreadable = append(inventory.Unreadable, unreadableMarkdownProblem(reviewMarkerFor(reviews), location, index+1))
+    if openers[index] {
+      continue
+    }
+    if level, title := documentationHeading(trimmed); level != 0 {
+      if tag, found := markdownProseTag(title); found {
+        inventory.Unreadable = append(inventory.Unreadable, unreadableMarkdownProblem(tag, location, index+1, true))
+      }
     }
   }
 }
@@ -1145,11 +1368,19 @@ func markdownListMarker(content string) int {
   return digits + 2
 }
 
-// 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) + " -->'."
+// unreadableMarkdownProblem names the position and the moves that fix it.
+//
+// Both carriers are named because either repairs the line: a visible heading
+// keeps a long explanation readable, and a comment keeps a short one out of the
+// rendered page.
+func unreadableMarkdownProblem(tag string, location string, line int, heading bool) string {
+  cause := "a Markdown declaration is read from an HTML comment or from an H2, H3 or H4 annotation heading, and this line is prose"
+  if heading {
+    cause = "a Markdown declaration is read from an HTML comment or from an H2, H3 or H4 heading of the document itself, and this heading is neither"
+  }
+  return "Unreadable " + tag + " at " + location + ":" + decimal(line) + ": " + cause + ", so nothing reads the tag." +
+    " Write it as a '## " + tag + " <target>' heading with " + unreadableMarkdownField(tag) + " below it," +
+    " or wrap it as '<!-- " + tag + " <target> " + unreadableMarkdownField(tag) + " -->'."
 }
 
 // unreadableMarkdownField names what follows a target for this tag.

package/native/prisma.go

@@ -910,11 +910,10 @@ func prismaCommentCarriesTag(body string) bool {
     if region.fence {
       continue
     }
-    trimmed := region.text
-    if _, _, found := declarationLine(trimmed); found {
+    if opensAcknowledgement(region.text, region.heading, region.title) {
       return true
     }
-    if prismaBuriedTag(trimmed) {
+    if prismaBuriedTag(region.text) {
       return true
     }
   }
@@ -936,11 +935,10 @@ func prismaBuriedTagLines(body string) []int {
     if region.fence {
       continue
     }
-    trimmed := region.text
-    if _, _, found := declarationLine(trimmed); found {
+    if opensAcknowledgement(region.text, region.heading, region.title) {
       continue
     }
-    if prismaBuriedTag(trimmed) {
+    if prismaBuriedTag(region.text) {
       offsets = append(offsets, offset)
     }
   }
@@ -965,8 +963,8 @@ func prismaBuriedTag(trimmed string) bool {
   if stripped == trimmed {
     return false
   }
-  _, _, found := declarationLine(stripped)
-  return found
+  heading, title := documentationHeading(stripped)
+  return opensAcknowledgement(stripped, heading, title)
 }
 
 // prismaNormalizationFailure words a rejected schema identically whether the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttsc/evidence",
-  "version": "0.31.5",
+  "version": "0.32.1",
   "description": "Evidence-graph lint contributor for @ttsc/lint: declare provenance with a JSDoc @evidence tag and fail the build when it is missing or dangling.",
   "main": "lib/index.js",
   "exports": {
@@ -45,12 +45,12 @@
     "@ttsc/lint": ">=0.31.0"
   },
   "devDependencies": {
-    "@wrtnlabs/evidence": "^0.3.1",
+    "@wrtnlabs/evidence": "^0.5.1",
     "@types/node": "^25.3.0",
     "rimraf": "^6.1.2",
     "typescript": "^7.0.2",
-    "@ttsc/lint": "0.31.5",
-    "ttsc": "0.31.5"
+    "ttsc": "0.32.1",
+    "@ttsc/lint": "0.32.1"
   },
   "dependencies": {
     "@prisma/prisma-schema-wasm": "7.10.0-2.d0368e25c88e68caa4d283b5f2d88d1b76ed9356",