@redpanda-data/docs-extensions-and-macros 5.48.1 → 5.50.0

package/bin/doc-tools.js

@@ -2755,6 +2755,7 @@ programCli
   .option('--format <format>', 'Output format: human or json', 'human')
   .option('--skip-rules <list>', 'Comma-separated rule ids to skip')
   .option('--only-rules <list>', 'Comma-separated rule ids to run exclusively')
+  .option('--reviewed <file>', 'Diff mode: skip declarations whose fingerprint is listed in <file> (already reviewed on an earlier push)')
   .option('--strict', 'Exit 1 when any error-severity finding exists (default: always exit 0 - suggest, never block)')
   .action((options) => {
     const { runCli } = require('../tools/lint-strings')
@@ -2908,6 +2909,92 @@ overridesGroup
     }
   })
 
+/**
+ * @description Build the plain-text prompt an external LLM triage call
+ * should send for one UPSTREAMABLE or SPLIT KEEP_UNTIL_UPSTREAMED audit row.
+ * Reads a single candidate object (not an array) from --candidate. See
+ * tools/overrides-audit/triage.js for the prompt contract.
+ *
+ * @why Separated from the actual LLM call so the workflow that runs it can
+ * use whatever action/model it wants; this command only builds the prompt.
+ *
+ * @example
+ * npx doc-tools overrides triage-prompt --candidate candidate.json
+ */
+overridesGroup
+  .command('triage-prompt')
+  .description('Build the triage prompt for one UPSTREAMABLE/SPLIT candidate')
+  .requiredOption('--candidate <path>', 'Path to a single candidate row JSON file (one object, not an array)')
+  .action((options) => {
+    const { buildTriagePrompt } = require('../tools/overrides-audit/triage')
+    try {
+      const candidate = JSON.parse(fs.readFileSync(path.resolve(options.candidate), 'utf8'))
+      console.log(buildTriagePrompt(candidate))
+    } catch (err) {
+      fail(err.message)
+    }
+  })
+
+/**
+ * @description Parse the raw text an LLM triage call returned for one
+ * candidate and merge it into that candidate's manifest row, adding
+ * agent_verdict / agent_reason / triage_failed. Any malformed, empty, or
+ * unexpected response degrades to a safe AMBIGUOUS verdict rather than
+ * throwing — a triage call failing is not a reason to fail the pipeline,
+ * it's a reason to ask a human. See tools/overrides-audit/triage.js.
+ *
+ * @example
+ * npx doc-tools overrides triage-parse --candidate candidate.json --response response.txt
+ */
+overridesGroup
+  .command('triage-parse')
+  .description('Merge an LLM triage response into a candidate row')
+  .requiredOption('--candidate <path>', 'Path to the candidate row JSON file this response answers')
+  .requiredOption('--response <path>', 'Path to the raw text file the LLM triage call returned')
+  .action((options) => {
+    const { triageCandidate } = require('../tools/overrides-audit/triage')
+    try {
+      const candidate = JSON.parse(fs.readFileSync(path.resolve(options.candidate), 'utf8'))
+      // A triage call that failed before writing its output leaves no
+      // response file. Treat that as an empty response so it reaches the
+      // AMBIGUOUS fallback instead of failing the command.
+      let rawResponse = ''
+      try {
+        rawResponse = fs.readFileSync(path.resolve(options.response), 'utf8')
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err
+      }
+      console.log(JSON.stringify(triageCandidate(candidate, rawResponse), null, 2))
+    } catch (err) {
+      fail(err.message)
+    }
+  })
+
+/**
+ * @description Render one plain-English markdown report section from a
+ * batch of triaged candidate rows (rows already carrying agent_verdict from
+ * triage-parse). See tools/overrides-audit/report.js for what each section
+ * contains and what happens to rows outside the requested verdict.
+ *
+ * @example
+ * npx doc-tools overrides report --candidates triaged.json --section upstream
+ */
+overridesGroup
+  .command('report')
+  .description('Build a plain-English markdown report section from triaged candidates')
+  .requiredOption('--candidates <path>', 'Path to a JSON array of triaged candidate rows')
+  .addOption(new Option('--section <section>', 'Which report section to build').choices(['upstream', 'retirement', 'ambiguous']).makeOptionMandatory())
+  .action((options) => {
+    const { buildUpstreamSection, buildRetirementSection, buildAmbiguousDigest } = require('../tools/overrides-audit/report')
+    const BUILDERS = { upstream: buildUpstreamSection, retirement: buildRetirementSection, ambiguous: buildAmbiguousDigest }
+    try {
+      const candidates = JSON.parse(fs.readFileSync(path.resolve(options.candidates), 'utf8'))
+      console.log(BUILDERS[options.section](candidates))
+    } catch (err) {
+      fail(err.message)
+    }
+  })
+
 programCli.addCommand(automation)
 /**
  * validate kapa-source-groups

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.48.1",
+  "version": "5.50.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/lint-strings/diff.js

@@ -20,7 +20,14 @@ const { spawnSync } = require('child_process')
  */
 const SURFACE_ROUTES = [
   { surface: 'properties', pattern: /^src\/v\/config\// },
-  { surface: 'metrics', pattern: /(^|\/)[^/]*probe\.cc$|^src\/v\/metrics\// },
+  // Metrics are registered wherever a component exposes them, not in files
+  // with a predictable name: raft/consensus.cc, cluster/rm_stm.cc and
+  // headers such as kafka/server/kafka_probe.h all call sm::description. So
+  // route every non-test C++ source under src/v (config/ has already matched
+  // properties above) and let the scanner, which skips any file with no
+  // description() call, decide what is a declaration. Test directories are
+  // excluded the same way the whole-repo scan excludes them.
+  { surface: 'metrics', pattern: /^src\/v\/(?!(?:.*\/)?tests?\/).*\.(?:cc|h)$/ },
   { surface: 'rpk', pattern: /^src\/go\/rpk\/pkg\/cli\// },
   // Both chart layouts ship: charts/<name>/chart/values.yaml (redpanda,
   // console) and charts/<name>/values.yaml (connectors).

package/tools/lint-strings/index.js

@@ -1,7 +1,10 @@
 'use strict'
 
+const crypto = require('crypto')
 const fs = require('fs')
+const os = require('os')
 const path = require('path')
+const { spawnSync } = require('child_process')
 
 const { runRules, mergeResults } = require('./engine')
 const { getDiffLines, classifyDiff, spanIntersects, SURFACE_ROUTES } = require('./diff')
@@ -54,6 +57,9 @@ function rulesFor (surface) {
  *   only declarations whose span intersects lines changed since this ref
  * @param {string[]} [options.skipRules]
  * @param {string[]} [options.onlyRules]
+ * @param {Set<string>} [options.reviewedFingerprints] - Diff mode: skip
+ *   declarations (and removals) whose fingerprint is in this set, so a PR
+ *   review sees each string once across pushes
  * @param {Function} [options.log] - Progress logger (stderr by default)
  * @returns {Object} { findings, summary, unsupported_surfaces }
  */
@@ -64,6 +70,7 @@ function lintStrings (options) {
     diffBase = null,
     skipRules = [],
     onlyRules = null,
+    reviewedFingerprints = null,
     log = (msg) => process.stderr.write(`${msg}\n`)
   } = options
 
@@ -83,12 +90,16 @@ function lintStrings (options) {
 
   const results = []
   const unsupportedSurfaces = []
-  let removedSurfaceFiles = []
+  const reviewed = reviewedFingerprints || new Set()
+  const pending = []
+  let alreadyReviewed = 0
+  let removal = { rawFiles: [], declarations: [] }
 
   if (diffBase) {
     const { changed, removed } = getDiffLines(repoPath, diffBase)
     const classified = classifyDiff(changed)
-    removedSurfaceFiles = collectRemovals(removed, surfaces)
+    const removedBySurface = classifyDiff(removed)
+    const headBySurface = {}
 
     for (const [surfaceName, files] of Object.entries(classified)) {
       if (!SURFACES[surfaceName]) {
@@ -101,13 +112,40 @@ function lintStrings (options) {
 
       const surface = SURFACES[surfaceName]
       log(`[${surfaceName}] ${files.size} changed file(s) in diff; extracting declarations at HEAD...`)
-      const fileSet = new Set(files.keys())
-      const declarations = surface
-        .extract({ repo: repoPath, files: fileSet, log })
-        .filter((decl) => spanIntersects(decl.line_start, decl.line_end, files.get(decl.file)))
-      for (const decl of declarations) decl.in_pr_diff = true
+      // Files that only lost lines are extracted too: a declaration that
+      // still exists at HEAD, in any touched file, was edited or moved, not
+      // removed.
+      const removedFiles = removedBySurface[surfaceName] ? [...removedBySurface[surfaceName].keys()] : []
+      const touchedFiles = new Set([...files.keys(), ...removedFiles])
+      // A surface whose extraction covers the whole surface anyway (the
+      // properties extractor parses every config file on each run) supplies
+      // context from all of it, so a property in an untouched file that
+      // names, or is named by, a changed one is still on its page. Review
+      // scope stays the touched files either way.
+      const everything = surface.contextScope === 'surface' ? surface.extract({ repo: repoPath, log }) : null
+      const head = everything
+        ? everything.filter((d) => touchedFiles.has(d.file))
+        : surface.extract({ repo: repoPath, files: touchedFiles, log })
+      headBySurface[surfaceName] = head
+      const declarations = []
+      for (const decl of head) {
+        if (!touches(decl, files.get(decl.file))) continue
+        decl.in_pr_diff = true
+        decl.fingerprint = fingerprint(decl)
+        if (reviewed.has(decl.fingerprint)) {
+          alreadyReviewed++
+          continue
+        }
+        declarations.push(decl)
+        pending.push({ ...pendingEntry(decl), context: pageContext(decl, everything || head) })
+      }
       results.push(runRules(declarations, rulesFor(surface), { skipRules, onlyRules }))
     }
+
+    removal = collectRemovals({ repoPath, diffBase, removed: removedBySurface, surfaces, requested, headBySurface, log })
+    const kept = removal.declarations.filter((decl) => !reviewed.has(decl.fingerprint))
+    alreadyReviewed += removal.declarations.length - kept.length
+    removal.declarations = kept
   } else {
     for (const surfaceName of requested) {
       const surface = SURFACES[surfaceName]
@@ -119,34 +157,266 @@ function lintStrings (options) {
   }
 
   const merged = mergeResults(results)
+  for (const finding of merged.findings) {
+    if (finding.in_pr_diff) finding.fingerprint = fingerprint(finding)
+  }
   merged.findings.sort((a, b) =>
     a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file) || (a.line_start || 0) - (b.line_start || 0))
   merged.unsupported_surfaces = unsupportedSurfaces
+  if (diffBase) {
+    merged.declarations = pending
+    merged.summary.alreadyReviewed = alreadyReviewed
+  }
+  merged.summary.removedDeclarations = removal.declarations.map(pendingEntry)
+  const removedSurfaceFiles = [...removal.rawFiles, ...removedFilesFor(removal.declarations)]
+    .sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
   merged.summary.removedSurfaceFiles = removedSurfaceFiles
   merged.summary.removedSurfaceLines = removedSurfaceFiles.reduce((sum, entry) => sum + entry.lines, 0)
   return merged
 }
 
 /**
- * Deletions in files that route to a doc-string surface, so a deletion-only PR
- * still registers as touching a surface. Reported separately from
- * totalDeclarations because a removed declaration is absent from HEAD and
- * therefore cannot be extracted or linted.
+ * A declaration's anchor lines: its span, plus any lines a surface records
+ * separately because the declared name lives outside it (metrics names sit
+ * in the enclosing make_*() call).
+ */
+function spansOf (decl) {
+  const spans = [[decl.line_start, decl.line_end]]
+  const extra = decl.meta && decl.meta.name_lines
+  if (extra) spans.push(extra)
+  return spans
+}
+
+function inSpans (decl, line) {
+  return spansOf(decl).some(([start, end]) => start != null && line >= start && line <= end)
+}
+
+function touches (decl, lineSet) {
+  return spansOf(decl).some(([start, end]) => spanIntersects(start, end, lineSet))
+}
+
+const CONTEXT_LIMIT = 15
+const CONTEXT_STRING_LIMIT = 600
+
+/**
+ * The other strings a reader sees alongside this one, so a review can judge
+ * a string against its page rather than on its own: a flag's usage next to
+ * its command's Long text and examples, a property that names another
+ * property, the fields around an API field.
  *
- * Surfaces routed without a registered extractor are included: the gate cares
- * that documented content went away, not whether we can lint what replaced it.
+ * - rpk: every other string declared in the same file, which is the
+ *   command's Short, Long and flags (rpk keeps one command per file).
+ * - api: the declarations nearest by line, which are the enclosing message
+ *   or rpc and its neighbors.
+ * - properties and metrics: declarations whose string names this one, or
+ *   that this string names, plus (metrics) its neighbors in the same group.
  *
- * @param {Map<string, Set<number>>} removed - From getDiffLines().removed
- * @param {string[]|null} surfaces - Explicit --surface narrowing, if any
+ * Drawn from declarations already extracted for the diff, so it costs no
+ * extra extraction. Deterministic, capped, and order-stable.
+ */
+function pageContext (decl, all) {
+  const others = all.filter((d) => d !== decl && d.string != null)
+  const byDistance = (d) => Math.abs((d.line_start || 0) - (decl.line_start || 0))
+  const sameFile = others.filter((d) => d.file === decl.file)
+  let picked
+  if (decl.surface === 'rpk') {
+    // The command's Short and Long always, then the flags nearest this
+    // declaration, so a changed flag late in a long command keeps its
+    // neighbors when the cap applies. Shown in source order.
+    const isText = (d) => d.meta && (d.meta.kind === 'short' || d.meta.kind === 'long')
+    const text = sameFile.filter(isText)
+    const flags = sameFile.filter((d) => !isText(d)).sort((a, b) => byDistance(a) - byDistance(b))
+    picked = [...text, ...flags].slice(0, CONTEXT_LIMIT)
+      .sort((a, b) => (a.line_start || 0) - (b.line_start || 0))
+  } else if (decl.surface === 'api') {
+    picked = sameFile.sort((a, b) => byDistance(a) - byDistance(b)).slice(0, 6)
+  } else {
+    const mentions = (text, name) => Boolean(text && name) &&
+      new RegExp(`(^|[^A-Za-z0-9_])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^A-Za-z0-9_])`).test(text)
+    const related = others.filter((d) => mentions(d.string, decl.name) || mentions(decl.string, d.name))
+    const neighbors = decl.surface === 'metrics'
+      ? sameFile.filter((d) => !related.includes(d)).sort((a, b) => byDistance(a) - byDistance(b)).slice(0, 2)
+      : []
+    picked = [...related, ...neighbors]
+  }
+  return picked.slice(0, CONTEXT_LIMIT).map((d) => ({
+    name: d.name,
+    kind: (d.meta && d.meta.kind) || d.surface,
+    file: d.file,
+    line_start: d.line_start,
+    string: d.string.length > CONTEXT_STRING_LIMIT ? `${d.string.slice(0, CONTEXT_STRING_LIMIT)}...` : d.string
+  }))
+}
+
+/**
+ * Stable identity for one version of one doc string. A PR review records the
+ * fingerprints it has seen, and a later push skips any declaration whose
+ * surface, name and text are unchanged, so rebases, moves and unrelated edits
+ * never re-review a string. Editing the string changes the fingerprint.
+ */
+function fingerprint (decl) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify([decl.surface, decl.name, decl.string == null ? null : decl.string]))
+    .digest('hex')
+    .slice(0, 16)
+}
+
+function removalFingerprint (surfaceName, identity) {
+  return crypto.createHash('sha256')
+    .update(JSON.stringify(['removed', surfaceName, identity]))
+    .digest('hex')
+    .slice(0, 16)
+}
+
+/**
+ * Where a declaration lives, for matching the merge-base side against HEAD.
+ * Bare names repeat on most surfaces (a `name` field in many proto messages,
+ * `enabled` in many CRD structs, the same flag on many rpk commands), so each
+ * surface supplies a contextual identity; without one, the name is used.
  */
-function collectRemovals (removed, surfaces) {
+function identityOf (surface, decl) {
+  return surface.identity ? surface.identity(decl) : decl.name
+}
+
+function pendingEntry (decl) {
+  return {
+    surface: decl.surface,
+    name: decl.name,
+    file: decl.file,
+    line_start: decl.line_start,
+    line_end: decl.line_end,
+    fingerprint: decl.fingerprint
+  }
+}
+
+function removedFilesFor (declarations) {
+  const byFile = new Map()
+  for (const decl of declarations) {
+    const key = `${decl.surface}\0${decl.file}`
+    const lines = (decl.removed_lines || 0)
+    byFile.set(key, { surface: decl.surface, file: decl.file, lines: (byFile.has(key) ? byFile.get(key).lines : 0) + lines })
+  }
+  return [...byFile.values()].sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
+}
+
+/**
+ * Materialize the merge-base version of `files` into a scratch tree, so a
+ * surface extractor can read the pre-image. A surface that declares
+ * baseScope 'directory' gets the whole directories instead: the properties
+ * extractor pairs each .cc with its .h.
+ */
+function materializeBase (repoPath, diffBase, files, scope = 'file') {
+  const mb = spawnSync('git', ['merge-base', diffBase, 'HEAD'], { cwd: repoPath, encoding: 'utf8' })
+  if (mb.status !== 0) throw new Error(`git merge-base ${diffBase} HEAD failed: ${mb.stderr}`)
+  const base = mb.stdout.trim()
+  const paths = scope === 'directory' ? [...new Set(files.map((f) => path.dirname(f)))] : files
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'lint-strings-base-'))
+  const archive = spawnSync('git', ['archive', '--format=tar', base, '--', ...paths], { cwd: repoPath, maxBuffer: 1024 * 1024 * 1024 })
+  if (archive.status !== 0) {
+    fs.rmSync(scratch, { recursive: true, force: true })
+    throw new Error(`git archive ${base} failed: ${archive.stderr}`)
+  }
+  const untar = spawnSync('tar', ['-x', '-C', scratch], { input: archive.stdout })
+  if (untar.status !== 0) {
+    fs.rmSync(scratch, { recursive: true, force: true })
+    throw new Error(`tar failed: ${untar.stderr}`)
+  }
+  return scratch
+}
+
+/**
+ * Doc-string declarations the diff removed or renamed.
+ *
+ * A deleted line only matters when it belonged to a declaration: removing an
+ * include, a struct field or a checksum from a surface file is not a removed
+ * surface. So the old side of each affected file is extracted at the merge
+ * base, and a declaration counts as removed when its span there lost lines
+ * and HEAD, across every file the diff touched, holds fewer declarations with
+ * its identity (see identityOf) than the merge base did. Still present means
+ * it was edited or moved, and HEAD-side review covers it. Counting, rather
+ * than asking whether the identity appears at all, keeps a deletion visible
+ * when another declaration shares the identity and survives.
+ *
+ * Declarations are absent from HEAD by construction, so they cannot be linted;
+ * they are reported for the published-content check instead.
+ *
+ * Surfaces routed without a registered extractor, and any base extraction
+ * that fails, fall back to counting raw deleted lines: without an extractor
+ * there is no way to tell, and the gate should err toward reviewing.
+ *
+ * @returns {{ rawFiles: Array, declarations: Array }}
+ */
+function collectRemovals ({ repoPath, diffBase, removed, surfaces, requested, headBySurface, log }) {
   const only = surfaces && surfaces.length > 0 ? new Set(surfaces) : null
-  const entries = []
-  for (const [surface, files] of Object.entries(classifyDiff(removed))) {
-    if (only && !only.has(surface)) continue
-    for (const [file, lines] of files) entries.push({ surface, file, lines: lines.size })
+  const rawFiles = []
+  const declarations = []
+
+  for (const [surfaceName, files] of Object.entries(removed)) {
+    if (only && !only.has(surfaceName)) continue
+    const surface = SURFACES[surfaceName]
+    const raw = () => {
+      for (const [file, lines] of files) rawFiles.push({ surface: surfaceName, file, lines: lines.size })
+    }
+    if (!surface || !requested.includes(surfaceName)) {
+      raw()
+      continue
+    }
+
+    let scratch = null
+    try {
+      scratch = materializeBase(repoPath, diffBase, [...files.keys()], surface.baseScope)
+      log(`[${surfaceName}] ${files.size} file(s) lost lines; extracting declarations at the merge base...`)
+      const baseDecls = surface.extract({ repo: scratch, files: new Set(files.keys()), log })
+      const head = headBySurface[surfaceName] ||
+        surface.extract({ repo: repoPath, files: new Set(files.keys()), log })
+      const keyOf = (decl) => JSON.stringify(identityOf(surface, decl))
+      const headCount = new Map()
+      for (const decl of head) headCount.set(keyOf(decl), (headCount.get(keyOf(decl)) || 0) + 1)
+      const baseCount = new Map()
+      const touched = new Map()
+      for (const decl of baseDecls) {
+        const key = keyOf(decl)
+        baseCount.set(key, (baseCount.get(key) || 0) + 1)
+        const lost = files.get(decl.file)
+        if (!touches(decl, lost)) continue
+        let count = 0
+        for (const line of lost) if (inSpans(decl, line)) count++
+        if (!touched.has(key)) touched.set(key, [])
+        touched.get(key).push({ decl, count })
+      }
+      // HEAD lost `deficit` declarations with this identity. When more
+      // touched ones share it than went missing, report the ones that lost
+      // the most lines: a deleted declaration loses its whole span.
+      const gone = new Map()
+      for (const [key, list] of touched) {
+        const deficit = baseCount.get(key) - (headCount.get(key) || 0)
+        if (deficit <= 0) continue
+        const picked = [...list].sort((a, b) => b.count - a.count || a.decl.line_start - b.decl.line_start).slice(0, deficit)
+        for (const entry of picked) gone.set(entry.decl, entry.count)
+      }
+      for (const decl of baseDecls) {
+        if (!gone.has(decl)) continue
+        const count = gone.get(decl)
+        declarations.push({
+          surface: surfaceName,
+          name: decl.name,
+          file: decl.file,
+          line_start: decl.line_start,
+          line_end: decl.line_end,
+          string: decl.string,
+          removed_lines: count,
+          fingerprint: removalFingerprint(surfaceName, identityOf(surface, decl))
+        })
+      }
+    } catch (err) {
+      log(`[${surfaceName}] could not extract the merge-base side (${err.message}); counting raw deleted lines instead`)
+      raw()
+    } finally {
+      if (scratch) fs.rmSync(scratch, { recursive: true, force: true })
+    }
   }
-  return entries.sort((a, b) => a.surface.localeCompare(b.surface) || a.file.localeCompare(b.file))
+
+  return { rawFiles, declarations }
 }
 
 /**
@@ -175,9 +445,15 @@ function formatHuman (result) {
   lines.push('='.repeat(60))
   lines.push(`Declarations checked: ${summary.totalDeclarations}`)
   lines.push(`Declarations flagged: ${summary.flaggedDeclarations}`)
-  if (summary.removedSurfaceLines) {
+  if (summary.alreadyReviewed) {
+    lines.push(`Already reviewed on an earlier push (skipped): ${summary.alreadyReviewed}`)
+  }
+  for (const decl of summary.removedDeclarations || []) {
+    lines.push(`Removed or renamed: ${decl.name} (${decl.surface}, ${decl.file})`)
+  }
+  if (summary.removedSurfaceLines && !(summary.removedDeclarations || []).length) {
     lines.push(`Lines deleted from doc-string surfaces: ${summary.removedSurfaceLines} ` +
-      `(${summary.removedSurfaceFiles.length} file(s); removed declarations cannot be extracted from HEAD)`)
+      `(${summary.removedSurfaceFiles.length} file(s) with no extractor, so every deleted line counts)`)
   }
   lines.push(`Errors: ${summary.errors}  Warnings: ${summary.warnings}  Info: ${summary.info}`)
   if (Object.keys(summary.byRule).length > 0) {
@@ -202,6 +478,22 @@ function formatHuman (result) {
   return lines.join('\n')
 }
 
+/**
+ * Read a --reviewed file: fingerprints separated by whitespace or commas.
+ * Anything that is not a 16-hex-digit fingerprint is ignored, and a missing
+ * file is an empty set, so a first run and a corrupted cache both mean
+ * "review everything" rather than an error.
+ */
+function readFingerprints (file) {
+  let text = ''
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch {
+    return new Set()
+  }
+  return new Set(text.split(/[\s,]+/).filter((token) => /^[0-9a-f]{16}$/.test(token)))
+}
+
 /**
  * CLI entry point shared by bin/doc-tools.js and direct invocation
  * (node tools/lint-strings --repo <path> ...).
@@ -217,7 +509,8 @@ function runCli (options) {
       surfaces: options.surface ? String(options.surface).split(',').map((s) => s.trim()).filter(Boolean) : null,
       diffBase: options.diff || null,
       skipRules: options.skipRules ? String(options.skipRules).split(',').map((s) => s.trim()).filter(Boolean) : [],
-      onlyRules: options.onlyRules ? String(options.onlyRules).split(',').map((s) => s.trim()).filter(Boolean) : null
+      onlyRules: options.onlyRules ? String(options.onlyRules).split(',').map((s) => s.trim()).filter(Boolean) : null,
+      reviewedFingerprints: options.reviewed ? readFingerprints(options.reviewed) : null
     })
   } catch (err) {
     console.error(`Error: ${err.message}`)
@@ -230,11 +523,13 @@ function runCli (options) {
     console.log(formatHuman(result))
   }
 
-  if (options.strict && result.summary.errors > 0) process.exit(1)
-  process.exit(0)
+  // exitCode, not process.exit(): exiting immediately drops whatever part of
+  // a large report is still buffered when stdout is a pipe, so a caller
+  // piping --format json into another process got truncated JSON.
+  process.exitCode = options.strict && result.summary.errors > 0 ? 1 : 0
 }
 
-module.exports = { lintStrings, formatHuman, runCli, SURFACES, rulesFor }
+module.exports = { lintStrings, formatHuman, runCli, SURFACES, rulesFor, fingerprint, readFingerprints, pageContext }
 
 // Direct usage: node tools/lint-strings --repo <path> [--surface a,b]
 //   [--diff <base>] [--format json|human] [--strict]
@@ -249,10 +544,11 @@ if (require.main === module) {
     else if (arg === '--format') options.format = args[++i]
     else if (arg === '--skip-rules') options.skipRules = args[++i]
     else if (arg === '--only-rules') options.onlyRules = args[++i]
+    else if (arg === '--reviewed') options.reviewed = args[++i]
     else if (arg === '--strict') options.strict = true
     else {
       console.error(`Unknown argument: ${arg}`)
-      console.error('Usage: node tools/lint-strings --repo <path> [--surface a,b] [--diff <base>] [--format json|human] [--skip-rules a,b] [--only-rules a,b] [--strict]')
+      console.error('Usage: node tools/lint-strings --repo <path> [--surface a,b] [--diff <base>] [--format json|human] [--skip-rules a,b] [--only-rules a,b] [--reviewed <file>] [--strict]')
       process.exit(2)
     }
   }

package/tools/lint-strings/rules/common.js

@@ -100,7 +100,9 @@ function maskNonProse (text) {
 const CODE_TOKEN_PATTERNS = Object.freeze([
   { id: 'identifier', re: /\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g },
   { id: 'flag', re: /(?<![\w-])--[a-z][a-z0-9]*(?:-[a-z0-9]+)*\b/g },
-  { id: 'path', re: /(?<![\w/])\/[a-z][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9_.{}-]+)+\/?/g }
+  // A path may not end in a period, so "served from /v1/brokers." reports
+  // `/v1/brokers`, not the sentence's full stop with it.
+  { id: 'path', re: /(?<![\w/])\/[a-z][a-zA-Z0-9_.-]*(?:\/[a-zA-Z0-9_.{}-]*[a-zA-Z0-9_{}-])+\/?/g }
 ])
 
 /**
@@ -276,7 +278,12 @@ const COMMON_RULES = [
     description: 'Code value or field name in prose without inline code',
     severity: 'warning',
     check: (decl) => {
-      const bare = findBareCodeTokens(decl.string, decl.name)
+      // A surface whose generator formats some code values itself declares
+      // which (convention.auto_inline_code); those are not findings there.
+      const auto = (decl.convention && decl.convention.auto_inline_code) || null
+      const bare = findBareCodeTokens(decl.string, decl.name).filter((b) => !auto ||
+        !((auto.kinds || []).includes(b.kind) ||
+          (b.kind === 'path' && (auto.path_prefixes || []).some((prefix) => b.token.startsWith(prefix)))))
       if (bare.length === 0) return []
       const list = bare.map((b) => `\`${b.token}\``).join(', ')
       return [{

package/tools/lint-strings/surfaces/api.js

@@ -761,11 +761,29 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. Field and message names
+ * repeat across messages (`name`, `enabled`), and rpc names across services,
+ * so the key is the proto package directory, the kind, and the dotted path
+ * inside the file. Proto names are unique per package, and buf keeps a
+ * package in one directory; a move to another package counts as a removal,
+ * which errs toward reviewing.
+ */
+function identity (decl) {
+  const meta = decl.meta || {}
+  let where = decl.name
+  if (meta.kind === 'field') where = meta.path || decl.name
+  else if (meta.kind === 'message' || meta.kind === 'enum') where = meta.block ? `${meta.block}.${decl.name}` : decl.name
+  else if (meta.kind === 'rpc-summary' || meta.kind === 'rpc-description') where = meta.service ? `${meta.service}.${decl.name}` : decl.name
+  return [path.dirname(decl.file), meta.kind || null, where]
+}
+
 module.exports = {
   name: 'api',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES,
   API_ROOTS,
   SUMMARY_KINDS,

package/tools/lint-strings/surfaces/connect.js

@@ -218,11 +218,23 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. Field names (`url`,
+ * `topic`, `enabled`) repeat across components, and a component name repeats
+ * across its input and output, so the key is the file, the kind and the name.
+ * Same-file repeats (nested object fields) are handled by counting in the
+ * caller.
+ */
+function identity (decl) {
+  return [decl.file, (decl.meta && decl.meta.kind) || null, decl.name]
+}
+
 module.exports = {
   name: 'connect',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES,
   // A connect description is the AsciiDoc page body, not a table cell:
   // bare | is legitimate table syntax there, and missing prose is handled