@redpanda-data/docs-extensions-and-macros 5.56.1 → 5.58.0

package/tools/migrate-property-values.js

@@ -0,0 +1,1255 @@
+'use strict'
+
+/* Report hand-written property values in prose, and propose propval: macros.
+ *
+ * Finds sentences that mention a property (a prop: call or the backticked
+ * name) and state one of its values by hand -- "defaults to 128 MiB",
+ * "the default is `true`", "minimum 1 minute" -- and checks the written value
+ * against the property data for that repo's own version, chosen exactly the
+ * way the prop: macro chooses it (loadPropertiesFor in macros/prop.js).
+ *
+ * Every finding gets one status:
+ *
+ *   exact        The written text is exactly what propval: renders (human or
+ *                raw form). Replacing it changes nothing a reader sees, so
+ *                these are the only findings --write applies.
+ *   equivalent   Same value, different wording ("7 days" vs "1 week",
+ *                "128 MB" vs "128 MiB"). Proposed, never applied.
+ *   mismatch     The written value differs from the data. Most likely a real
+ *                doc error. Never applied.
+ *   unset        The data default is null (not set) but the prose states a
+ *                value. Redpanda often computes a runtime fallback for an
+ *                unset property (compaction_ctrl_backlog_size uses 10% of
+ *                free disk), so a human confirms it against the source.
+ *   unverifiable The value could not be compared: unparseable, the property
+ *                has no such field, the data does not state it for this
+ *                audience (Cloud defaults, ifdef::env-cloud[] blocks), or a
+ *                topic property is said to have no default of its own.
+ *   example-output A value shown in command output in a listing, literal or
+ *                fenced block. Its verdict is stale (a row that asserts the
+ *                default, such as SOURCE DEFAULT_CONFIG, shows another
+ *                value), matches, or unverifiable with a reason. Counted and
+ *                listed apart from prose findings, and never written.
+ *
+ * Tables are scanned: a statement in a cell belongs to the property that opens
+ * the row (or cell), and a Default column states the default of the row's
+ * property. Table findings are reported, never written.
+ *
+ * Skipped entirely: prose inside delimited blocks (listing, literal,
+ * passthrough, comment, fenced code; only command output in listing, literal
+ * and fenced blocks is read), headings, attribute entries, block titles, comment lines,
+ * ifndef::env-cloud[] content on a Cloud page, files carrying the
+ * generated-content marker, and the generated paths migrate-property-refs
+ * also excludes.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const yaml = require('js-yaml')
+const { loadPropertiesFor, isAvailable, describeDataset } = require('../macros/prop')
+const { fieldValue, unitOf, FIELDS, FORMAT_RAW, FORMAT_HUMAN } = require('../extension-utils/property-values')
+const { DEFAULT_EXCLUDE } = require('./migrate-property-refs')
+
+const PROPERTIES_JSON_RX = /^redpanda-properties-(v\d+\.\d+\.\d+(?:-[\w.]+)?)\.json$/
+const GENERATED_MARKER = 'This content is autogenerated. Do not edit manually.'
+const SKIP_LINE_RX = /^(=+\s|:[-\w]+!?:|\.[^.\s]|\/\/)/
+const DELIMITER_RX = /^(-{4,}|\.{4,}|\/{4,}|\+{4,}|`{3,}.*)\s*$/
+const TABLE_RX = /^[|!,:]={3,}\s*$/
+// A nested table (!===) opens and closes inside a cell of the outer table.
+const NESTED_TABLE_RX = /^!={3,}\s*$/
+// A tagged region: an including page can take this part of the file alone,
+// as cloud-docs does with include::streaming:...[tag=...].
+const TAG_RX = /^\s*\/\/\s*tag::[^[\s]+\[\]\s*$/m
+const CONDITIONAL_RX = /^(ifdef|ifndef)::([^[\s]*)\[(.*)\]\s*$/
+const IFEVAL_RX = /^ifeval::\[.*\]\s*$/
+const ENDIF_RX = /^endif::[^[\s]*\[\]\s*$/
+// A table line that starts a cell: |, or a cell spec such as a|, 2+|, 3*|.
+const CELL_START_RX = /^\s*(?:\d+(?:\.\d+)?[+*])?[adehlmsv]?(?=\|)\|/
+const HISTORICAL_RX = /release-notes|incompat-changes|whats-new|upgrade\//
+
+// A property mention: prop:name[...] or `name`.
+const MENTION_RX = /prop:([A-Za-z][A-Za-z0-9_.]*)\[[^\]]*\]|(?<![`\\])`([A-Za-z][A-Za-z0-9_.]*)`(?!`)/g
+
+// Value phrases. Each captures the text after the phrase, which parseValue
+// then reads one value from.
+const PHRASES = [
+  { field: 'default', rx: /\b(?:defaults?\s+to|default\s+(?:value\s+)?(?:is|of|=|:)|default\s+for\s+(?=prop:|xref:|`)|default\s*:|default\s+[-\u2013]\s+|is\s+set\s+to\s+(?=\S+\s+by\s+default)|by\s+default\s+(?:is|it\s+is)|default\s+setting\s+is)\s*/gi },
+  { field: 'min', rx: /\b(?:minimum|min\.?)(?:\s+(?:value|allowed\s+value))?\s*(?:is|of|=|:)?\s+(?:of\s+)?/gi },
+  { field: 'max', rx: /\b(?:maximum|max\.?)(?:\s+(?:value|allowed\s+value))?\s*(?:is|of|=|:)?\s+(?:of\s+)?/gi },
+]
+// The phrase must start within this many characters after the mention, with
+// no sentence boundary and no other property mention in between.
+const WINDOW = 120
+
+const BYTE_UNITS = {
+  b: 1, byte: 1, bytes: 1,
+  kb: 1000, kib: 1024, mb: 1000 ** 2, mib: 1024 ** 2, gb: 1000 ** 3, gib: 1024 ** 3, tb: 1000 ** 4, tib: 1024 ** 4,
+}
+// Docs commonly write KB/MB/GB for binary sizes, so those also match binary.
+const BYTE_BINARY_ALIAS = { kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3, tb: 1024 ** 4 }
+const TIME_UNITS_MS = {
+  ms: 1, millisecond: 1, milliseconds: 1,
+  s: 1000, sec: 1000, secs: 1000, second: 1000, seconds: 1000,
+  m: 60000, min: 60000, mins: 60000, minute: 60000, minutes: 60000,
+  h: 3600000, hr: 3600000, hrs: 3600000, hour: 3600000, hours: 3600000,
+  d: 86400000, day: 86400000, days: 86400000,
+  w: 604800000, week: 604800000, weeks: 604800000,
+  y: 31536000000, year: 31536000000, years: 31536000000,
+}
+const NULLISH = new Set(['null', 'none', 'no default', 'not set', 'unset', 'no limit', 'empty', 'nothing'])
+
+const norm = (text) => String(text).replace(/`/g, '').replace(/\s+/g, ' ').trim()
+
+/**
+ * Read one written value from the start of `text`.
+ *
+ * @returns {undefined | {written: string, length: number, backticked: boolean,
+ *   kind: 'number'|'null'|'bool'|'string', number?: number, unit?: string,
+ *   unitKind?: 'bytes'|'time', bool?: boolean, string?: string}}
+ */
+function parseValue (text) {
+  const backtick = text.match(/^`([^`]+)`/)
+  if (backtick) {
+    const inner = parseValue(backtick[1])
+    const base = { written: backtick[0], length: backtick[0].length, backticked: true }
+    if (inner && inner.length === backtick[1].length) return { ...inner, ...base }
+    return { ...base, kind: 'string', string: backtick[1] }
+  }
+  const quoted = text.match(/^"([^"]*)"/)
+  if (quoted) return { written: quoted[0], length: quoted[0].length, backticked: false, kind: 'string', string: quoted[1] }
+  const nullish = text.match(/^(no default|not set|unset|no limit|null|none|empty)\b/i)
+  if (nullish) return { written: nullish[0], length: nullish[0].length, backticked: false, kind: 'null' }
+  const bool = text.match(/^(true|false|enabled|disabled|on|off)(?![-\w])/i)
+  if (bool) {
+    const word = bool[1].toLowerCase()
+    return { written: bool[0], length: bool[0].length, backticked: false, kind: 'bool', bool: ['true', 'enabled', 'on'].includes(word), string: bool[1] }
+  }
+  const number = text.match(/^(-?\d(?:[,_']?\d)*(?:\.\d+)?)(?:\s*([A-Za-z]+)\b)?/)
+  if (number) {
+    const value = Number(number[1].replace(/[,_']/g, ''))
+    if (Number.isNaN(value)) return undefined
+    if (text.slice(number[1].length).startsWith('%')) {
+      return { written: `${number[1]}%`, length: number[1].length + 1, backticked: false, kind: 'number', number: value, unit: '%', unitKind: 'percent' }
+    }
+    const unit = number[2] && number[2].toLowerCase()
+    if (unit && BYTE_UNITS[unit] !== undefined) {
+      return { written: number[0], length: number[0].length, backticked: false, kind: 'number', number: value, unit, unitKind: 'bytes' }
+    }
+    if (unit && TIME_UNITS_MS[unit] !== undefined) {
+      return { written: number[0], length: number[0].length, backticked: false, kind: 'number', number: value, unit, unitKind: 'time' }
+    }
+    const bare = number[1]
+    return { written: bare, length: bare.length, backticked: false, kind: 'number', number: value }
+  }
+  const word = text.match(/^([A-Za-z_][\w.-]*[\w])/)
+  if (word) return { written: word[0], length: word[0].length, backticked: false, kind: 'string', string: word[1], bareWord: true }
+  return undefined
+}
+
+/**
+ * Compare a written value with one data value.
+ *
+ * @returns {{status: 'match'|'mismatch'|'unverifiable', note?: string}}
+ */
+function compareValue (parsed, dataValue, entry) {
+  // Topic properties such as retention.ms carry no units and formatUnits
+  // reads only an _ms suffix, so a .ms suffix is milliseconds too.
+  const unit = unitOf(entry) || (/\.ms$/.test(entry && entry.name) ? 'milliseconds' : '')
+  if (dataValue === null || dataValue === undefined || dataValue === '') {
+    if (parsed.kind === 'null') return { status: 'match' }
+    // "disabled" often means "null, so the feature is off".
+    if (parsed.kind === 'bool' && !parsed.bool) return { status: 'unverifiable', note: 'written as disabled; the data default is null' }
+    // Not set is not "no value": Redpanda often falls back to a computed
+    // value at runtime, which the prose may be describing.
+    return { status: 'unset', note: `not set in the data; the prose states ${norm(parsed.written)}, which may be a runtime fallback` }
+  }
+  if (parsed.unitKind === 'percent' && unit !== 'percent') {
+    return { status: 'unverifiable', note: 'written as a percentage' }
+  }
+  if (typeof dataValue === 'boolean') {
+    if (parsed.kind === 'bool') return { status: parsed.bool === dataValue ? 'match' : 'mismatch' }
+    if (parsed.kind === 'string' && /^(true|false)$/i.test(parsed.string)) return { status: (parsed.string.toLowerCase() === String(dataValue)) ? 'match' : 'mismatch' }
+    return { status: 'unverifiable', note: 'written value is not a boolean' }
+  }
+  if (typeof dataValue === 'number') {
+    if (parsed.kind === 'null') return { status: 'mismatch' }
+    if (parsed.kind !== 'number') return { status: 'unverifiable', note: 'written value is not a number' }
+    if (parsed.unitKind === 'time') {
+      const scale = unit === 'milliseconds' ? 1 : unit === 'seconds' ? 1000 : undefined
+      if (!scale) return { status: 'unverifiable', note: 'written as a duration, but the data gives no time unit for this property' }
+      const writtenMs = parsed.number * TIME_UNITS_MS[parsed.unit]
+      return { status: Math.abs(writtenMs - dataValue * scale) < 1e-6 ? 'match' : 'mismatch' }
+    }
+    if (parsed.unitKind === 'bytes') {
+      if (unit && unit !== 'bytes') return { status: 'unverifiable', note: `written in bytes, but the data's unit is ${unit}` }
+      const candidates = [BYTE_UNITS[parsed.unit], BYTE_BINARY_ALIAS[parsed.unit]].filter(Boolean)
+      const ok = candidates.some((factor) => Math.abs(parsed.number * factor - dataValue) < 0.5)
+      const note = unit ? undefined : 'the data gives no unit for this property; compared as bytes because the text is written in bytes'
+      return { status: ok ? 'match' : 'mismatch', ...(note ? { note } : {}) }
+    }
+    return { status: parsed.number === dataValue ? 'match' : 'mismatch' }
+  }
+  if (typeof dataValue === 'string') {
+    // An enum value can look like a keyword: 'none', 'disabled', 'true'.
+    if (norm(parsed.written).toLowerCase() === dataValue.toLowerCase()) return { status: 'match' }
+    if (parsed.kind === 'string' || parsed.kind === 'bool') {
+      const written = parsed.string
+      return { status: written.toLowerCase() === dataValue.toLowerCase() ? 'match' : 'mismatch' }
+    }
+    if (parsed.kind === 'number') return { status: parsed.written === dataValue ? 'match' : 'mismatch' }
+    if (parsed.kind === 'null') return { status: 'mismatch' }
+  }
+  return { status: 'unverifiable', note: 'the data value is a list or object' }
+}
+
+/**
+ * The data value a field compares against.
+ */
+function dataValueFor (entry, field) {
+  if (field === 'default') return { present: Object.prototype.hasOwnProperty.call(entry, 'default'), value: entry.default }
+  const key = field === 'min' ? 'minimum' : 'maximum'
+  return { present: entry[key] !== undefined && entry[key] !== null, value: entry[key] }
+}
+
+/**
+ * The propval: call that renders `written` exactly, if any: human first,
+ * then raw. Undefined when neither rendering equals the written text.
+ */
+function exactCall (name, field, entry, parsed) {
+  const target = norm(parsed.written)
+  const human = fieldValue(entry, field, { format: FORMAT_HUMAN })
+  if (human.ok && norm(human.text) === target) {
+    return { call: `propval:${name}[${field}]`, rendered: human.text }
+  }
+  const raw = fieldValue(entry, field, { format: FORMAT_RAW })
+  if (raw.ok && norm(raw.text) === target) {
+    return { call: `propval:${name}[${field},format=raw]`, rendered: raw.text }
+  }
+  return undefined
+}
+
+// xref:...properties/...adoc#anchor[label]: the anchor names the property
+// (dots become hyphens in topic property anchors).
+const XREF_RX = /xref:[^[\s]*propert[^[\s]*#([\w.-]+)\[[^\]]*\]/g
+// Sentence boundary: terminal punctuation, then whitespace, then something
+// that starts a sentence.
+const SENTENCE_RX = /[.!?](?=\s+(?:[A-Z*`(]|prop:|xref:))/g
+// A sentence that qualifies the statement to another audience, release, or
+// tool says nothing about this page's own default, so it is never compared
+// as if it did.
+const QUALIFIER_RX = /\b(?:earlier|prior|previous|older)\s+(?:versions?|releases?)\b|\b(?:before|until|prior to)\s+(?:Redpanda\s+)?v?\d+\.\d+|\bin\s+(?:Redpanda\s+)?v?\d+\.\d+\b|\bRedpanda Cloud\b|\bBYOC\b|\bDedicated\b|\bServerless\b|\bHelm\b|\bchart\b|\bclients?\b|\blibrar(?:y|ies)\b|\bdev-container\b|\bdev mode\b|\bKubernetes\b|\boperator\b/i
+// Macro attribute lists (prop:x[link=true,helm-path=auto]) are not prose, so
+// they never qualify a sentence.
+const stripMacroAttributes = (text) => text.replace(/\b(prop|propval):([A-Za-z][A-Za-z0-9_.]*)\[[^\]]*\]/g, '$1:$2[]')
+
+/**
+ * Every property mention on a line: prop: calls, property xrefs, and
+ * backticked names (outside any xref already counted).
+ */
+function findMentions (line, registry, requireSeparator) {
+  const has = (name) => Object.prototype.hasOwnProperty.call(registry.properties, name)
+  const mentions = []
+  for (const m of line.matchAll(XREF_RX)) {
+    const anchor = m[1]
+    const name = has(anchor) ? anchor : has(anchor.replace(/-/g, '.')) ? anchor.replace(/-/g, '.') : undefined
+    mentions.push({ name, start: m.index, end: m.index + m[0].length })
+  }
+  const inside = (index) => mentions.some((x) => index >= x.start && index < x.end)
+  for (const m of line.matchAll(MENTION_RX)) {
+    if (inside(m.index)) continue
+    const name = m[1] || m[2]
+    if (!has(name)) continue
+    if (!m[1] && requireSeparator && !/[_.]/.test(name)) continue
+    mentions.push({ name, start: m.index, end: m.index + m[0].length })
+  }
+  return mentions.filter((m) => m.name).sort((a, b) => a.start - b.start)
+}
+
+function sentenceBounds (line) {
+  const starts = [0]
+  for (const m of line.matchAll(SENTENCE_RX)) starts.push(m.index + 1)
+  const sentenceAt = (index) => {
+    let i = 0
+    while (i + 1 < starts.length && starts[i + 1] <= index) i++
+    return i
+  }
+  const text = (first, last) => line.slice(starts[first], last + 1 < starts.length ? starts[last + 1] : line.length)
+  return { sentenceAt, text }
+}
+
+/**
+ * Scan one line for value statements. Exported for unit testing.
+ *
+ * A statement belongs to the nearest property mention before it, in the same
+ * sentence or the one before ("Set prop:x[]. The default is 5."), provided no
+ * other property is mentioned in between.
+ *
+ * @param {string} line
+ * @param {object} ctx
+ * @param {object} ctx.registry - From loadPropertiesFor.
+ * @param {boolean} [ctx.requireSeparator] - Only treat backticked names that
+ *   contain _ or . as mentions (prop: calls and xrefs always count). Default
+ *   true, the rule migrate-property-refs uses for word-like names.
+ * @returns {object[]} findings, with column offsets of the value.
+ */
+function scanLine (line, { registry, requireSeparator = true, subject: rowSubject, qualifier: blockQualifier }) {
+  const findings = []
+  const mentions = findMentions(line, registry, requireSeparator)
+  if (!mentions.length && !rowSubject) return findings
+  const { sentenceAt, text } = sentenceBounds(line)
+  const claimed = new Set()
+  const between = (a, b) => mentions.filter((m) => m.start >= a && m.start < b)
+
+  const add = (mention, field, phrase, valueStart, association) => {
+    if (claimed.has(valueStart)) return
+    const parsed = parseValue(line.slice(valueStart))
+    if (!parsed) return
+    const entry = registry.properties[mention.name]
+    // A bare word only counts for string-valued properties; otherwise
+    // "defaults to the value of ..." would read "the" as a value.
+    if (parsed.bareWord && typeof entry.default !== 'string') return
+    // "defaults to `other_property`" is a reference, not a value.
+    if (parsed.kind === 'string' && parsed.string !== entry.default &&
+      Object.prototype.hasOwnProperty.call(registry.properties, parsed.string)) return
+    claimed.add(valueStart)
+    const context = text(sentenceAt(mention.start), sentenceAt(valueStart))
+    // A conditional ("If the cluster default is X") states no default.
+    const own = text(sentenceAt(valueStart), sentenceAt(valueStart))
+    const qualifier = stripMacroAttributes(context).match(QUALIFIER_RX) || own.match(/^\s*(?:If|When|Unless|Suppose)\b/) || (blockQualifier ? [blockQualifier] : null)
+    // Other properties on the line (the paragraph), or a list entry about
+    // another property, make the binding a guess, so it is never auto-safe.
+    const named = new Set([mention.name])
+    for (const m of mentions) named.add(m.name)
+    if (subject && subject.name) named.add(subject.name)
+    findings.push({
+      name: mention.name,
+      field,
+      phrase,
+      parsed,
+      start: valueStart,
+      end: valueStart + parsed.length,
+      association,
+      soleProperty: named.size === 1,
+      ...(qualifier ? { qualifier: qualifier[0].trim() } : {}),
+    })
+  }
+
+  // A list item or description-list entry that opens with a name
+  // ("* `x`: ...", "* prop:x[]. Default: 5") is about that name, so a
+  // statement in a later sentence of the entry belongs to it, not to whatever
+  // property the entry mentions along the way. A subject that is not a
+  // property (a Helm value, a client setting) claims the statement too, and
+  // then nothing is reported.
+  const subjectMatch = line.match(/^\s*(?:[*.-]+\s+|\d+\.\s+)?(?=prop:|xref:|`)/)
+  let subject
+  if (subjectMatch) {
+    const at = subjectMatch[0].length
+    subject = mentions.find((m) => m.start === at) || (/^`[^`]+`/.test(line.slice(at)) ? { name: undefined, start: at, end: at + line.slice(at).match(/^`[^`]+`/)[0].length } : undefined)
+  }
+
+  // The property a statement at `index` belongs to: the nearest mention
+  // before it in the same sentence, else (one sentence later) the entry's
+  // subject or the nearest mention, with no other property in between.
+  const ownerBefore = (index) => {
+    const before = mentions.filter((m) => m.end <= index)
+    const mention = before[before.length - 1]
+    if (mention && sentenceAt(index) === sentenceAt(mention.end) && index - mention.end <= 200 &&
+      !between(mention.end, index).some((m) => m.name !== mention.name)) {
+      return { mention, association: 'same-sentence' }
+    }
+    // In a table, anything else in the cell is about the row's property.
+    if (rowSubject) return { mention: { name: rowSubject.name, start: 0, end: 0 }, association: rowSubject.association }
+    if (subject && subject.end <= index && sentenceAt(index) > sentenceAt(subject.end)) {
+      return subject.name ? { mention: subject, association: 'list-subject' } : undefined
+    }
+    if (!mention || index - mention.end > 200) return undefined
+    if (between(mention.end, index).some((m) => m.name !== mention.name)) return undefined
+    if (sentenceAt(index) - sentenceAt(mention.end) !== 1) return undefined
+    return { mention, association: 'previous-sentence' }
+  }
+
+  for (const phrase of PHRASES) {
+    for (const p of line.matchAll(phrase.rx)) {
+      const valueStart = p.index + p[0].length
+      // "the default value of `x` is 5" / "the default for prop:x[] is 5".
+      if (/(?:of|for)\s*$/i.test(p[0]) || /^(?:of|for)\s/i.test(line.slice(valueStart))) {
+        const rest = line.slice(valueStart).replace(/^(?:of|for)\s+/i, '')
+        const offset = line.length - rest.length
+        const next = mentions.find((m) => m.start === offset)
+        if (next) {
+          const tail = line.slice(next.end).match(/^\s*(?:is|=|:|,)\s*/)
+          if (tail) add(next, phrase.field, p[0].trim(), next.end + tail[0].length, 'same-sentence')
+          continue
+        }
+      }
+      const owner = ownerBefore(p.index)
+      if (owner) add(owner.mention, phrase.field, p[0].trim(), valueStart, owner.association)
+    }
+  }
+
+  // "`x` is `true` by default", "is set to 5 by default".
+  for (const m of line.matchAll(/\b(?:is|are)\s+(?:set\s+to\s+)?(`[^`]+`|enabled|disabled|true|false|unset|-?\d(?:[,_']?\d)*(?:\.\d+)?(?:\s*[A-Za-z%]+)?)\s+by\s+default\b/gi)) {
+    const valueStart = m.index + m[0].lastIndexOf(m[1])
+    const owner = ownerBefore(m.index)
+    if (owner && owner.association === 'same-sentence') add(owner.mention, 'default', 'by default', valueStart, 'same-sentence')
+  }
+  // "By default, prop:x[] is set to `true`."
+  for (const m of line.matchAll(/\bby default,?\s+/gi)) {
+    const after = m.index + m[0].length
+    const mention = mentions.find((x) => x.start >= after && x.start - after <= 40)
+    if (!mention || sentenceAt(mention.start) !== sentenceAt(m.index)) continue
+    const tail = line.slice(mention.end).match(/^(?:\s+(?:cluster|topic|broker|configuration|config|property|properties|tunable))*\s+(?:is|are)\s+(?:set\s+to\s+)?/i)
+    if (tail) add(mention, 'default', 'by default', mention.end + tail[0].length, 'same-sentence')
+  }
+  // "By default, the property is empty." in a row or entry about one property.
+  for (const m of line.matchAll(/\bby default,?\s+(?:the|this)\s+property\s+is\s+(?:set\s+to\s+)?/gi)) {
+    const owner = ownerBefore(m.index)
+    if (owner) add(owner.mention, 'default', 'by default', m.index + m[0].length, owner.association)
+  }
+  // "No default", "There is no default.": a statement that the value is unset.
+  for (const m of line.matchAll(/\b[Nn]o default(?=\s*(?:[.,;)]|$))/g)) {
+    const owner = ownerBefore(m.index)
+    if (owner) add(owner.mention, 'default', 'no default', m.index, owner.association)
+  }
+  return findings
+}
+
+/**
+ * Classify one finding against the data.
+ */
+function classify (finding, registry) {
+  const entry = registry.properties[finding.name]
+  const out = {
+    property: finding.name,
+    field: finding.field,
+    phrase: finding.phrase,
+    written: finding.parsed.written,
+    association: finding.association || 'same-sentence',
+    autoSafe: false,
+  }
+  const human = fieldValue(entry, finding.field, { format: FORMAT_HUMAN })
+  const raw = fieldValue(entry, finding.field, { format: FORMAT_RAW })
+  if (human.ok) out.dataValue = human.text
+  if (raw.ok) out.dataRaw = raw.text
+  const cloud = registry.surface === 'cloud'
+  if (!isAvailable(registry, entry)) {
+    out.status = 'unverifiable'
+    out.reason = 'cloud-unavailable'
+    out.note = 'cloud_supported: false in the data, so propval: renders nothing on this page'
+    return out
+  }
+  const { present, value } = dataValueFor(entry, finding.field)
+  if (!present) {
+    out.status = 'unverifiable'
+    out.reason = 'no-such-field'
+    out.note = `the data has no ${finding.field} for this property`
+    return out
+  }
+  const compared = compareValue(finding.parsed, value, entry)
+  if (compared.note) out.note = compared.note
+  if (finding.qualifier) {
+    // The sentence is about another audience or release ("In Redpanda Cloud",
+    // "in earlier versions"), so this page's data cannot confirm or refute it.
+    out.status = 'unverifiable'
+    out.reason = compared.status === 'mismatch' ? 'qualified-differs' : 'qualified'
+    out.qualifier = finding.qualifier
+    return out
+  }
+  if (compared.status === 'unset') {
+    out.status = 'unset'
+    return out
+  }
+  if (cloud && finding.field === 'default') {
+    // The Cloud reference states no defaults, so propval: renders a
+    // placeholder here. Still compare with the self-managed default: a
+    // difference is worth a look, though it may be a Cloud-specific value.
+    out.status = 'unverifiable'
+    out.reason = compared.status === 'mismatch' ? 'cloud-default-differs-from-self-managed' : 'cloud-default'
+    return out
+  }
+  if (compared.status === 'mismatch' && finding.parsed.kind === 'null' && entry.config_scope === 'topic' && entry.corresponding_cluster_property) {
+    // "No default" for a topic property is true of the topic: it has no value
+    // of its own and inherits the cluster property's.
+    out.status = 'unverifiable'
+    out.reason = 'inherits-cluster-default'
+    out.note = `a topic property inherits ${entry.corresponding_cluster_property} when not set`
+    return out
+  }
+  if (compared.status === 'mismatch') {
+    out.status = 'mismatch'
+    return out
+  }
+  if (compared.status === 'unverifiable') {
+    const exact = exactCall(finding.name, finding.field, entry, finding.parsed)
+    if (exact) {
+      out.status = 'exact'
+      out.proposed = finding.parsed.backticked ? `\`${exact.call}\`` : exact.call
+      out.autoSafe = out.association === 'same-sentence'
+      delete out.note
+      return out
+    }
+    out.status = 'unverifiable'
+    out.reason = 'not-comparable'
+    return out
+  }
+  const exact = exactCall(finding.name, finding.field, entry, finding.parsed)
+  if (exact) {
+    out.status = 'exact'
+    out.proposed = finding.parsed.backticked ? `\`${exact.call}\`` : exact.call
+    // Only a statement in the same sentence as its property is applied
+    // automatically; one tied to an earlier sentence is a proposal.
+    out.autoSafe = out.association === 'same-sentence'
+  } else {
+    out.status = 'equivalent'
+    out.proposed = `propval:${finding.name}[${finding.field}]`
+  }
+  return out
+}
+
+/**
+ * Read an Antora component descriptor and its property attachments into the
+ * file shapes loadPropertiesFor reads from a content catalog.
+ */
+function readComponent (repoDir) {
+  const descriptor = yaml.load(fs.readFileSync(path.join(repoDir, 'antora.yml'), 'utf8')) || {}
+  const component = String(descriptor.name || '')
+  const version = descriptor.version === null || descriptor.version === undefined ? '' : String(descriptor.version)
+  const attributes = (descriptor.asciidoc && descriptor.asciidoc.attributes) || {}
+  const dir = path.join(repoDir, 'modules', 'reference', 'attachments')
+  const files = []
+  if (fs.existsSync(dir)) {
+    for (const name of fs.readdirSync(dir)) {
+      if (!PROPERTIES_JSON_RX.test(name)) continue
+      files.push({
+        src: { component, version, module: 'reference', family: 'attachment', relative: name },
+        contents: fs.readFileSync(path.join(dir, name)),
+      })
+    }
+  }
+  return { component, version, attributes, files }
+}
+
+/**
+ * A minimal content catalog over one or more component checkouts, enough for
+ * loadPropertiesFor to select a dataset exactly as it does in an Antora build.
+ */
+function catalogFor (components) {
+  const files = components.flatMap((c) => c.files)
+  return {
+    findBy: (query) => files.filter((file) => Object.entries(query).every(([key, value]) => file.src[key] === value)),
+    getComponent: (name) => {
+      const own = components.filter((c) => c.component === name)
+      if (!own.length) return undefined
+      const versions = own.map((c) => ({ version: c.version, asciidoc: { attributes: c.attributes } }))
+      return { name, versions, latest: versions[0] }
+    },
+  }
+}
+
+function isGenerated (content) {
+  return content.split('\n', 15).some((line) => line.includes(GENERATED_MARKER))
+}
+
+// ---------------------------------------------------------------------------
+// Example output in listing, literal and fenced blocks.
+//
+// Prose inside a block is never read, but a block that shows command output
+// can state a property's value as plainly as a sentence does:
+// `rpk topic describe` config tables, `rpk cluster config get` and `export`,
+// Admin API cluster_config responses, kafka-configs --describe, and
+// Key/Value/Source records (debug bundles, Topic resource status). A row
+// whose source is DEFAULT_CONFIG asserts the default, so it is compared, as
+// does output with no source (config get, export, Admin API) when the text
+// just before the block says it is the default. A row from another source, a property the page sets earlier, a Helm or
+// operator deployment, or a cluster started in dev-container mode or from a
+// bootstrap file is not a default, and is reported as unverifiable with the
+// reason. Example findings are never written.
+// ---------------------------------------------------------------------------
+
+// Sources that state the topic or broker has no value of its own.
+const DEFAULT_SOURCES = new Set(['DEFAULT_CONFIG', 'DEFAULT'])
+const COLUMN_HEADER_RX = /^\s*(?:KEY|NAME|PROPERTY)\s+VALUE(?:\s+SOURCE)?\s*$/i
+const STATUS_HEADER_RX = /^\s*NODE\s+CONFIG-VERSION\b/i
+// segment.bytes=1073741824 (DEFAULT_CONFIG)
+const EQUALS_SOURCE_RX = /^\s*([A-Za-z][\w.]*)=(\S*)\s+\(([A-Z_]+)\)\s*$/
+// kafka-configs --describe: segment.bytes=1073741824 sensitive=false synonyms={DEFAULT_CONFIG:log_segment_size=1073741824}
+const KAFKA_CONFIGS_RX = /^\s*([A-Za-z][\w.]*)=(\S*)\s+sensitive=\w+\s+synonyms=\{(?:([A-Z_]+):)?/
+// A field of a Key/Value/Source record, in JSON or YAML.
+const RECORD_FIELD_RX = /^(\s*(?:-\s+)?)"?(Key|key|Name|name|Value|value|Source|source)"?\s*:\s*(.*?)\s*,?\s*$/
+// A flat "name": value or name: value line (Admin API JSON, config export).
+const FLAT_FIELD_RX = /^\s*"?([a-z][a-z0-9_]*)"?\s*:\s*(.*?)\s*,?\s*$/
+const COMMAND_RX = /^\s*(?:\$\s+)?(?:\S*=\S*\s+)*(?:kubectl|helm|docker|rpk|internal-rpk|curl|kafka-configs(?:\.sh)?)\b/
+const HELM_PATH_RX = /(?:^|\/)kubernetes\/|(?:^|\/)k-[^/]*\.adoc$/
+const DEV_CONFIG_RX = /dev-container|--mode\s+dev|rpk container start|\bbootstrap\.ya?ml\b|\.bootstrap\.yaml/
+
+const unquote = (text) => {
+  const t = String(text).trim().replace(/,$/, '').trim()
+  const m = t.match(/^"(.*)"$/) || t.match(/^'(.*)'$/)
+  return m ? m[1] : t
+}
+
+/**
+ * The value rows a block of command output states. Exported for unit
+ * testing.
+ *
+ * @param {string[]} lines - The block's lines.
+ * @param {string} commands - Command text for the block: its own command
+ *   lines, else the previous block's when that one held only commands.
+ * @returns {{rows: object[], shape?: string}} rows of {name, value, source?,
+ *   offset} where offset is the line within the block.
+ */
+function parseExampleBlock (lines, commands = '') {
+  const rows = []
+  // rpk cluster config status lists versions and restart flags, no values.
+  if (lines.some((l) => STATUS_HEADER_RX.test(l))) return { rows, shape: 'cluster-config-status' }
+
+  // NAME/KEY VALUE SOURCE columns (rpk topic describe, kubectl go-templates).
+  const header = lines.findIndex((l) => COLUMN_HEADER_RX.test(l))
+  if (header >= 0) {
+    const hasSource = /SOURCE\s*$/i.test(lines[header])
+    for (let i = header + 1; i < lines.length; i++) {
+      const text = lines[i].trim()
+      if (!text) break
+      const tokens = text.split(/\s+/)
+      if (tokens.length < 2) break
+      const name = tokens[0]
+      let source
+      let rest = text.slice(name.length).trim()
+      if (hasSource && tokens.length >= 3 && /^[A-Z_]+$/.test(tokens[tokens.length - 1])) {
+        source = tokens[tokens.length - 1]
+        rest = rest.slice(0, rest.length - source.length).trim()
+      }
+      rows.push({ name, value: rest, source, offset: i })
+    }
+    return { rows, shape: 'config-table' }
+  }
+
+  // name=value (SOURCE) and kafka-configs --describe lines.
+  lines.forEach((l, offset) => {
+    const m = l.match(EQUALS_SOURCE_RX) || l.match(KAFKA_CONFIGS_RX)
+    if (m) rows.push({ name: m[1], value: m[2], source: m[3], offset })
+  })
+  if (rows.length) return { rows, shape: 'name-equals-value' }
+
+  // Key/Value/Source records: a record is the fields at one indentation
+  // within one list item or object.
+  const open = new Map()
+  const flush = (col) => {
+    const r = open.get(col)
+    open.delete(col)
+    if (r && r.name !== undefined && r.value !== undefined && r.source !== undefined) {
+      rows.push({ name: r.name, value: r.value, source: r.source, offset: r.offset })
+    }
+  }
+  lines.forEach((l, offset) => {
+    const m = l.match(RECORD_FIELD_RX)
+    if (!m) return
+    const col = m[1].length
+    const key = m[2].toLowerCase() === 'key' ? 'name' : m[2].toLowerCase()
+    const raw = m[3]
+    // A nested object or list ("Synonyms": [) is not a scalar field.
+    if (/^[[{]/.test(raw)) return
+    const r = open.get(col)
+    if (r && (r[key] !== undefined || /-\s+$/.test(m[1]))) flush(col)
+    if (!open.has(col)) open.set(col, {})
+    const rec = open.get(col)
+    rec[key] = unquote(raw)
+    if (key === 'value') rec.offset = offset
+  })
+  for (const col of [...open.keys()]) flush(col)
+  if (rows.length) return { rows, shape: 'records' }
+
+  const commandLines = lines.filter((l) => COMMAND_RX.test(l))
+  const output = lines.map((text, offset) => ({ text, offset })).filter((l) => l.text.trim() && !COMMAND_RX.test(l.text))
+
+  // rpk cluster config get <name>, with its output in the same block or the
+  // block after the command.
+  const gets = [...(commandLines.length ? commandLines.join('\n') : commands).matchAll(/\brpk\s+cluster\s+config\s+get\s+([a-z][a-z0-9_]*)/g)]
+  if (gets.length === 1 && output.length === 1) {
+    rows.push({ name: gets[0][1], value: output[0].text.trim().replace(/^\$\s+/, ''), offset: output[0].offset })
+    return { rows, shape: 'cluster-config-get' }
+  }
+
+  // An Admin API cluster_config response or an rpk cluster config export.
+  const context = commandLines.length ? commandLines.join('\n') : commands
+  const api = /\/v1\/cluster_config(?!\/)/.test(context)
+  const exported = /\brpk\s+cluster\s+config\s+export\b/.test(context)
+  if (api || exported) {
+    for (const { text, offset } of output) {
+      const m = text.match(FLAT_FIELD_RX)
+      if (m && !/^[[{]?$/.test(m[2])) rows.push({ name: m[1], value: unquote(m[2]), offset })
+    }
+    if (rows.length) return { rows, shape: api ? 'admin-api-cluster-config' : 'cluster-config-export' }
+  }
+  return { rows }
+}
+
+/**
+ * Compare a value as command output prints it (raw bytes, milliseconds,
+ * true/false, enum text) with a data value. Exact after unit normalization.
+ *
+ * @returns {{status: 'match'|'mismatch'|'unset'|'not-comparable', note?: string}}
+ */
+function compareRaw (written, dataValue, { scale = 1 } = {}) {
+  const text = String(written).trim()
+  if (dataValue === null || dataValue === undefined || dataValue === '') {
+    // Kafka reports "no limit" as -1.
+    if (/^(?:-1|null|none|)$/i.test(text)) return { status: 'match', ...(text === '-1' ? { note: '-1 is how Kafka reports an unset limit' } : {}) }
+    return { status: 'unset' }
+  }
+  if (typeof dataValue === 'boolean') {
+    if (!/^(true|false)$/i.test(text)) return { status: 'not-comparable' }
+    return { status: (text.toLowerCase() === 'true') === dataValue ? 'match' : 'mismatch' }
+  }
+  if (typeof dataValue === 'number') {
+    if (!/^-?\d+(?:\.\d+)?$/.test(text)) return { status: 'not-comparable' }
+    return { status: Number(text) === dataValue * scale ? 'match' : 'mismatch' }
+  }
+  if (typeof dataValue === 'string') {
+    if (text === dataValue) return { status: 'match' }
+    if (text.toLowerCase() === dataValue.toLowerCase()) return { status: 'match', note: 'differs only in case' }
+    return { status: /\s/.test(text) ? 'not-comparable' : 'mismatch' }
+  }
+  return { status: 'not-comparable' }
+}
+
+/**
+ * The property data a row compares against: the row's own entry, or for a
+ * topic property the cluster property it inherits (corresponding_cluster_
+ * property; alternate_cluster_property for a compacted topic), both from the
+ * property data. A Kafka broker alias such as log.segment.bytes is not in the
+ * data; its Redpanda-named synonym row is compared instead.
+ */
+function exampleTarget (registry, name, { compacted = false } = {}) {
+  const props = registry.properties
+  const entry = Object.prototype.hasOwnProperty.call(props, name) ? props[name] : undefined
+  if (!entry) return undefined
+  if (entry.config_scope === 'topic') {
+    const cluster = (compacted && entry.alternate_cluster_property) || entry.corresponding_cluster_property
+    if (cluster && Object.prototype.hasOwnProperty.call(props, cluster)) {
+      return { entry, data: props[cluster], cluster, via: compacted && cluster === entry.alternate_cluster_property ? 'alternate_cluster_property' : 'corresponding_cluster_property' }
+    }
+  }
+  return { entry, data: entry }
+}
+
+/**
+ * Where, before `beforeLine`, the page sets `names` to a value: a
+ * name=value or name: value assignment (rpk ... --set, -c, YAML, JSON, Helm
+ * config.cluster.name), or rpk cluster config set name value.
+ */
+function setEarlier (lines, beforeLine, names) {
+  const alternatives = names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')
+  const rx = new RegExp(`(?<![\\w.-])(?:${alternatives})"?\\s*[=:]\\s*(?!\\s*$)\\S|\\bconfig\\s+set\\s+(?:${alternatives})\\s+\\S`)
+  for (let i = beforeLine - 1; i >= 0; i--) {
+    if (rx.test(lines[i])) return i + 1
+  }
+  return undefined
+}
+
+/**
+ * Classify one example row. Exported for unit testing through scanDocument.
+ */
+function classifyExample (row, registry, ctx) {
+  const target = exampleTarget(registry, row.name, { compacted: ctx.compacted })
+  if (!target) return undefined
+  const { entry, data, cluster, via } = target
+  const out = {
+    property: row.name,
+    field: 'default',
+    phrase: ctx.shape,
+    written: row.value,
+    association: 'example-output',
+    autoSafe: false,
+    kind: 'example-output',
+    ...(row.source ? { source: row.source } : {}),
+    ...(cluster ? { clusterProperty: cluster, mappedBy: via } : {}),
+  }
+  const human = fieldValue(data, 'default', { format: FORMAT_HUMAN })
+  const raw = fieldValue(data, 'default', { format: FORMAT_RAW })
+  if (human.ok) out.dataValue = human.text
+  if (raw.ok) out.dataRaw = raw.text
+  // Seconds-based cluster property behind a .ms topic property.
+  const scale = cluster && /\.ms$/.test(row.name) && unitOf(data) === 'seconds' ? 1000 : 1
+  const compared = compareRaw(row.value, data.default, { scale })
+  if (compared.note) out.note = compared.note
+  const unverifiable = (reason, note) => {
+    out.status = 'example-output'
+    out.verdict = 'unverifiable'
+    out.reason = reason
+    if (note) out.note = note
+    out.differs = compared.status === 'mismatch'
+    return out
+  }
+  if (row.source && !DEFAULT_SOURCES.has(row.source)) {
+    return unverifiable('not-default-source', `source ${row.source} is not a default`)
+  }
+  if (!isAvailable(registry, entry)) {
+    return unverifiable('cloud-unavailable', 'cloud_supported: false in the data')
+  }
+  if (ctx.qualifier) return unverifiable('ifdef::env-cloud', 'inside ifdef::env-cloud[]: a Cloud value')
+  if (registry.surface === 'cloud') return unverifiable('cloud-default', 'the Cloud reference states no defaults')
+  // A DEFAULT_CONFIG row inherits the cluster value, so only a cluster-level
+  // setting earlier on the page changes what it shows; a topic-level one
+  // would have changed the row's source.
+  const topicDefaultRow = row.source && entry.config_scope === 'topic'
+  const watched = cluster ? [cluster] : topicDefaultRow ? [] : [row.name]
+  const set = watched.length ? setEarlier(ctx.lines, ctx.blockStart, watched) : undefined
+  if (set) return unverifiable('set-earlier-on-page', `the page sets ${cluster || row.name} at line ${set}`)
+  if (ctx.helm) return unverifiable('helm-operator-context', ctx.helm)
+  if (ctx.devConfig) return unverifiable('dev-or-bootstrap-config', ctx.devConfig)
+  if (!row.source && !ctx.statesDefault) return unverifiable('current-value', 'output with no source column shows the current value, and the text before it does not say it is the default')
+  if (compared.status === 'unset') return unverifiable('unset-in-data', `not set in the data; the output shows ${row.value}, which may be a runtime fallback`)
+  if (compared.status === 'not-comparable') return unverifiable('not-comparable')
+  out.status = 'example-output'
+  out.verdict = compared.status === 'match' ? 'matches' : 'stale'
+  return out
+}
+
+/**
+ * Scan one document. Exported for unit testing.
+ *
+ * @returns {{findings: object[], content: string}} content with exact
+ *   findings replaced (only used by --write).
+ */
+function scanDocument (content, registry, options = {}) {
+  const lines = content.split('\n')
+  const findings = []
+  const requireSeparator = options.requireSeparator !== false
+  const cloudSurface = registry.surface === 'cloud'
+  let open = null
+  let block = null
+  let lastBlock = null
+  let table = null
+  const helmPage = options.path && HELM_PATH_RX.test(options.path)
+  // A tagged file, or any partial (cloud-docs includes some partials whole),
+  // may be included in a Cloud page.
+  const taggedFile = TAG_RX.test(content) || /(?:^|\/)partials\//.test(options.path || '')
+  const devConfig = content.match(DEV_CONFIG_RX)
+
+  // Read the command output in a closed block and report its value rows.
+  const scanBlock = (b) => {
+    const texts = b.lines.map((l) => l.text)
+    const own = texts.filter((t) => COMMAND_RX.test(t))
+    // An output block's command is the previous block's, when that block held
+    // only commands and ended just before ("Input" / "Output" pairs).
+    const previous = lastBlock && b.start - lastBlock.end <= 12 && lastBlock.lines.every((l) => !l.text.trim() || COMMAND_RX.test(l.text) || /\\\s*$/.test(l.text) || /^\s+-/.test(l.text))
+      ? lastBlock.lines.map((l) => l.text).join('\n')
+      : ''
+    const commands = own.length ? own.join('\n') : previous
+    // Output with no source column shows the current value. It states the
+    // default only when the text just before it says so ("on a cluster with
+    // default settings", "the default is").
+    const leadEnd = previous ? lastBlock.start : b.start
+    const leadIn = lines.slice(Math.max(0, leadEnd - 11), Math.max(0, leadEnd - 1)).join('\n')
+    const { rows, shape } = parseExampleBlock(texts, commands)
+    if (!rows.length) return
+    const compacted = rows.some((r) => r.name === 'cleanup.policy' && /compact/.test(r.value))
+    let helm
+    if (helmPage) helm = 'on a Kubernetes page: the Helm chart or operator may set this value'
+    else if (/\b(?:kubectl|helm)\b/.test(commands)) helm = 'run through kubectl or helm: the Helm chart or operator may set this value'
+    const ctx = {
+      shape,
+      lines,
+      blockStart: b.start,
+      qualifier: b.state.qualifier,
+      compacted,
+      helm,
+      devConfig: devConfig ? `the page configures the cluster (${devConfig[0]}), which can change defaults` : undefined,
+      statesDefault: /\bdefaults?\b/i.test(leadIn),
+    }
+    for (const row of rows) {
+      const result = classifyExample(row, registry, ctx)
+      if (!result) continue
+      const at = b.lines[row.offset]
+      findings.push({ line: at.index + 1, text: at.text.trim(), ...result })
+    }
+  }
+  const conditions = []
+  const condition = () => conditionOf(conditions, cloudSurface)
+
+  // Classify the findings for one line (or the content of a single-line
+  // conditional at `offset`) and rewrite the auto-safe ones.
+  const emit = (index, line, lineFindings, offset = 0, { inTable = false, cloudExcluded = condition().cloudExcluded } = {}) => {
+    let rewritten = line
+    // Replace right to left so earlier offsets stay valid.
+    const classified = lineFindings.map((f) => ({ raw: f, result: classify(f, registry) }))
+    for (const { raw, result } of classified) {
+      const entry = registry.properties[raw.name]
+      if (result.autoSafe && raw.soleProperty === false) {
+        result.autoSafe = false
+        result.note = 'another property is named in the same sentence or entry: proposed only'
+      }
+      // A null default is "unset", which deserves a human look even when the
+      // prose says null.
+      if (result.autoSafe && raw.field === 'default' && (entry.default === null || entry.default === '')) {
+        result.autoSafe = false
+        result.note = 'the data leaves this unset: proposed only'
+      }
+      // cloud-docs can include this line. On Cloud, propval: renders a
+      // placeholder for a field the Cloud reference hides and for a property
+      // Cloud does not support, so outside ifndef::env-cloud[] a tagged file
+      // or a partial (either can be included in a Cloud page) is proposed only.
+      const cloudPlaceholder = (FIELDS[raw.field] && FIELDS[raw.field].cloudHidden) ||
+        (entry.config_scope === 'cluster' && entry.cloud_supported === false)
+      if (result.autoSafe && !cloudSurface && cloudPlaceholder && !cloudExcluded && taggedFile) {
+        result.autoSafe = false
+        result.note = 'proposed: page may be single-sourced; wrap in ifndef::env-cloud[] first'
+      }
+      // Release notes and upgrade notes describe a release, not the current
+      // value, so a later regeneration must not rewrite what they say.
+      if (result.autoSafe && options.historical) {
+        result.autoSafe = false
+        result.note = 'release or upgrade notes: proposed only'
+      }
+      if (result.autoSafe && inTable) {
+        result.autoSafe = false
+        result.note = 'in a table: proposed only'
+      }
+    }
+    for (const { raw, result } of [...classified].sort((a, b) => b.raw.start - a.raw.start)) {
+      if (result.autoSafe && options.write) {
+        rewritten = rewritten.slice(0, offset + raw.start) + result.proposed + rewritten.slice(offset + raw.end)
+      }
+    }
+    for (const { result } of classified) findings.push({ line: index + 1, text: line.trim(), ...result })
+    return rewritten
+  }
+
+  // One line inside a table. `t` carries the header, the cell count and the
+  // property the current row (or cell) is about.
+  const scanTableLine = (t, text, at, qualifier) => {
+    const trimmed = text.trim()
+    const cells = splitCells(text)
+    const subjectAt = (cellText) => {
+      const lead = cellText.match(/^\s*/)[0].length
+      const m = findMentions(cellText, registry, requireSeparator).find((x) => x.start === lead)
+      return m && m.name
+    }
+    // The first row, when it names no property, is the header.
+    if (t.header === undefined && trimmed) {
+      if (cells && cells.length > 1 && !findMentions(text, registry, requireSeparator).length) {
+        t.header = cells.map((c) => c.text.trim())
+        t.cols = cells.length
+        t.defaultCol = t.header.findIndex((h) => /^default(?:\s+value)?$/i.test(h))
+        return text
+      }
+      t.header = null
+    }
+    if (!cells) {
+      // A continuation of the current cell.
+      return emit(at, text, scanLine(text, { registry, requireSeparator, qualifier, subject: t.subject }), 0, { inTable: true })
+    }
+    const lineFindings = []
+    for (const c of cells) {
+      t.cell++
+      const col = t.cols ? t.cell % t.cols : -1
+      if (col === 0) t.subject = undefined
+      const name = subjectAt(c.text)
+      if (name) {
+        t.subject = { name, association: 'table-row' }
+        continue
+      }
+      if (col >= 0 && col === t.defaultCol && t.subject) {
+        const lead = c.text.match(/^\s*/)[0].length
+        const parsed = parseValue(c.text.slice(lead))
+        const entry = registry.properties[t.subject.name]
+        if (parsed && !(parsed.bareWord && typeof entry.default !== 'string')) {
+          lineFindings.push({ name: t.subject.name, field: 'default', phrase: 'Default column', parsed, start: c.start + lead, end: c.start + lead + parsed.length, association: 'table-default-column', ...(qualifier ? { qualifier } : {}) })
+        }
+      }
+    }
+    if (!lineFindings.length) {
+      lineFindings.push(...scanLine(text, { registry, requireSeparator, qualifier, subject: t.subject }))
+    }
+    return emit(at, text, lineFindings, 0, { inTable: true })
+  }
+
+  const out = lines.map((line, index) => {
+    const trimmed = line.trim()
+    const delimiter = trimmed.match(DELIMITER_RX)
+    if (delimiter) {
+      const fence = delimiter[1].startsWith('```') ? '```' : delimiter[1]
+      if (open === null) {
+        open = fence
+        // Listing, literal and fenced blocks can hold command output.
+        const state = condition()
+        block = /^[-.`]/.test(fence) && !state.hidden ? { start: index + 1, lines: [], state } : null
+      } else if (open === fence) {
+        open = null
+        if (block) {
+          block.end = index
+          scanBlock(block)
+          lastBlock = block
+        }
+        block = null
+      }
+      return line
+    }
+    if (open !== null) {
+      if (block) block.lines.push({ index, text: line })
+      return line
+    }
+    if (ENDIF_RX.test(trimmed)) {
+      conditions.pop()
+      return line
+    }
+    if (IFEVAL_RX.test(trimmed)) {
+      conditions.push({ type: 'ifeval', attrs: '' })
+      return line
+    }
+    const directive = trimmed.match(CONDITIONAL_RX)
+    if (directive) {
+      const frame = { type: directive[1], attrs: directive[2] }
+      if (!directive[3]) {
+        conditions.push(frame)
+        return line
+      }
+      // Single-line form: ifdef::env-cloud[The default is ...]
+      conditions.push(frame)
+      const state = condition()
+      conditions.pop()
+      if (state.hidden) return line
+      const offset = line.indexOf('[', line.indexOf('::')) + 1
+      const inner = directive[3]
+      return emit(index, line, scanLine(inner, { registry, requireSeparator, qualifier: state.qualifier }), offset, { cloudExcluded: state.cloudExcluded })
+    }
+    if (condition().hidden) return line
+    if (table && NESTED_TABLE_RX.test(trimmed)) return line
+    if (TABLE_RX.test(trimmed)) {
+      table = table ? null : { header: undefined, cols: 0, defaultCol: -1, cell: -1, subject: undefined }
+      return line
+    }
+    if (SKIP_LINE_RX.test(line)) return line
+    const { qualifier } = condition()
+    if (table) return scanTableLine(table, line, index, qualifier)
+    return emit(index, line, scanLine(line, { registry, requireSeparator, qualifier }))
+  })
+  return { findings, content: out.join('\n') }
+}
+
+/**
+ * Split a table line into cells, or undefined when the line continues the
+ * previous cell. A cell starts at a | (with an optional spec such as a| or
+ * 2+|) outside backticks; start is the offset of the cell's text.
+ */
+function splitCells (line) {
+  const lead = line.match(CELL_START_RX)
+  if (!lead) return undefined
+  const cells = []
+  let start = lead[0].length
+  let inCode = false
+  for (let i = start; i <= line.length; i++) {
+    const ch = line[i]
+    if (ch === '`') inCode = !inCode
+    if (i === line.length || (ch === '|' && !inCode && line[i - 1] !== '\\')) {
+      cells.push({ text: line.slice(start, i), start })
+      start = i + 1
+    }
+  }
+  return cells
+}
+
+/**
+ * Whether content under the open conditionals is hidden on this surface, the
+ * qualifier it carries, and whether it is excluded from Cloud (cloudExcluded).
+ * Only conditions that name env-cloud are interpreted; anything else is
+ * treated as visible. ifdef::env-cloud,x[] (OR) and ifdef::env-cloud+x[]
+ * (AND) both render on Cloud. ifndef::env-cloud,x[] renders only when none
+ * is set, so it is excluded from Cloud; ifndef::env-cloud+x[] is not.
+ */
+function conditionOf (conditions, cloudSurface) {
+  let hidden = false
+  let cloudExcluded = false
+  let qualifier
+  for (const { type, attrs } of conditions) {
+    const names = attrs.split(/[,+]/)
+    if (type === 'ifdef' && names.includes('env-cloud')) {
+      if (!cloudSurface) qualifier = 'ifdef::env-cloud'
+    } else if (type === 'ifndef' && !attrs.includes('+') && names.includes('env-cloud')) {
+      cloudExcluded = true
+      if (cloudSurface) hidden = true
+    }
+  }
+  return { hidden, qualifier, cloudExcluded }
+}
+
+/**
+ * Scan a repo checkout.
+ *
+ * @param {object} opts
+ * @param {string} opts.docsDir - Repo root containing antora.yml and modules/.
+ * @param {string[]} [opts.lenderDirs] - Other component checkouts whose
+ *   property data the repo may borrow (a Cloud repo borrows streaming's).
+ * @param {boolean} [opts.write] - Apply exact findings.
+ */
+function scanRepo ({ docsDir, lenderDirs = [], write = false, exclude = DEFAULT_EXCLUDE }) {
+  const own = readComponent(docsDir)
+  const lenders = lenderDirs.map(readComponent)
+  const catalog = catalogFor([own, ...lenders])
+  const registry = loadPropertiesFor(catalog, own.component, own.version)
+  if (!registry) {
+    return {
+      component: own.component,
+      version: own.version,
+      error: `no property data for ${own.component}@${own.version || 'unversioned'}: the prop macro would refuse to validate this version, so no value can be checked. ` +
+        (own.files.length ? `Found only ${own.files.map((f) => f.src.relative).join(', ')}.` : 'Pass --lender for a Cloud repo.'),
+    }
+  }
+  const findings = []
+  let files = 0
+  let changedFiles = 0
+  let skippedGenerated = 0
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const full = path.join(dir, entry.name)
+      const relative = path.relative(docsDir, full)
+      if (exclude.some((fragment) => `${relative}/`.includes(fragment) || relative.includes(fragment))) continue
+      if (entry.isDirectory()) walk(full)
+      else if (entry.name.endsWith('.adoc')) {
+        const original = fs.readFileSync(full, 'utf8')
+        if (isGenerated(original)) {
+          skippedGenerated++
+          continue
+        }
+        files++
+        const result = scanDocument(original, registry, { write, historical: HISTORICAL_RX.test(relative), path: relative })
+        for (const f of result.findings) findings.push({ file: relative, ...f })
+        if (write && result.content !== original) {
+          fs.writeFileSync(full, result.content)
+          changedFiles++
+        }
+      }
+    }
+  }
+  walk(path.join(docsDir, 'modules'))
+  const counts = { exact: 0, equivalent: 0, mismatch: 0, unset: 0, unverifiable: 0, autoSafe: 0, 'example-output': 0, exampleStale: 0 }
+  for (const f of findings) {
+    counts[f.status]++
+    if (f.autoSafe) counts.autoSafe++
+    if (f.verdict === 'stale') counts.exampleStale++
+  }
+  return {
+    component: own.component,
+    version: own.version,
+    dataset: describeDataset(registry),
+    surface: registry.surface,
+    files,
+    skippedGenerated,
+    findings,
+    counts,
+    changedFiles,
+  }
+}
+
+const dataCell = (f) => (f.dataRaw && f.dataRaw !== f.dataValue ? `${f.dataValue} (${f.dataRaw})` : f.dataValue)
+const mdEscape = (text) => String(text == null ? '' : text).replace(/\|/g, '\\|').replace(/\n/g, ' ')
+
+/**
+ * The example-output section of a repo's report.
+ */
+function renderExamples (out, examples) {
+  const by = (verdict) => examples.filter((f) => f.verdict === verdict)
+  const stale = by('stale')
+  const unverifiable = by('unverifiable')
+  out.push('', `### Example output (${examples.length}: ${stale.length} stale, ${by('matches').length} matching, ${unverifiable.length} unverifiable)`, '')
+  out.push('Values shown in command output in listing blocks. Reported only: a block is never rewritten. A topic property is compared with the cluster property it inherits in the data.', '')
+  out.push(`#### Stale (${stale.length})`, '')
+  if (stale.length) {
+    out.push('| File:line | Property | Cluster property | Shown | Default | Source | Output |', '|---|---|---|---|---|---|---|')
+    for (const f of stale) out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | \`${mdEscape(f.property)}\` | ${mdEscape(f.clusterProperty || '')} | ${mdEscape(f.written)} | ${mdEscape(dataCell(f))} | ${mdEscape(f.source || '')} | ${f.phrase} |`)
+  } else out.push('None.')
+  const differs = unverifiable.filter((f) => f.differs && f.reason !== 'not-default-source')
+  if (differs.length) {
+    out.push('', `#### Differ from the default in a context that may set them (${differs.length})`, '')
+    out.push('The output may show a configured value, not the default. Listed for a human to check.', '')
+    out.push('| File:line | Property | Cluster property | Shown | Default | Reason | Note |', '|---|---|---|---|---|---|---|')
+    for (const f of differs) out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | \`${mdEscape(f.property)}\` | ${mdEscape(f.clusterProperty || '')} | ${mdEscape(f.written)} | ${mdEscape(dataCell(f))} | ${f.reason} | ${mdEscape(f.note)} |`)
+  }
+  const byReason = {}
+  for (const f of unverifiable) byReason[f.reason] = (byReason[f.reason] || 0) + 1
+  if (Object.keys(byReason).length) out.push('', `#### Unverifiable by reason (${unverifiable.length})`, '', Object.entries(byReason).map(([k, v]) => `* ${k}: ${v}`).join('\n'))
+}
+
+/**
+ * Render scan results as Markdown.
+ */
+function renderMarkdown (results, { title = 'Hand-written property values report' } = {}) {
+  const out = [`# ${title}`, '']
+  out.push('Statuses: **exact** is what propval: renders. **auto-safe** is an exact match in the same sentence as its property, the only kind `--write` applies. **equivalent** is the same value worded differently, proposed only. **mismatch** differs from the data and is likely a doc error. **unset** states a value for a property the data leaves unset, which may be a runtime fallback. **unverifiable** could not be compared. **example output** is a value shown in command output in a listing block, counted apart and never written: **stale** when a row that asserts the default (such as SOURCE `DEFAULT_CONFIG`) shows another value.', '')
+  out.push('| Repo | Dataset | Files scanned | Findings | Mismatch | Unset | Exact | Auto-safe | Equivalent | Unverifiable | Example output (stale) |', '|---|---|---|---|---|---|---|---|---|---|---|')
+  for (const r of results) {
+    if (r.error) {
+      out.push(`| ${mdEscape(r.label || r.component)} | ${mdEscape(r.error)} | | | | | | | | | |`)
+      continue
+    }
+    out.push(`| ${mdEscape(r.label || r.component)} | ${mdEscape(r.dataset)} (${r.surface}) | ${r.files} | ${r.findings.length} | ${r.counts.mismatch} | ${r.counts.unset} | ${r.counts.exact} | ${r.counts.autoSafe} | ${r.counts.equivalent} | ${r.counts.unverifiable} | ${r.counts['example-output'] || 0} (${r.counts.exampleStale || 0}) |`)
+  }
+  for (const r of results) {
+    if (r.error) continue
+    out.push('', `## ${r.label || r.component}`, '')
+    const mismatches = r.findings.filter((f) => f.status === 'mismatch')
+    out.push(`### Mismatches (${mismatches.length})`, '')
+    if (mismatches.length) {
+      out.push('| File:line | Property | Field | Written | Data value | Tied to | Note |', '|---|---|---|---|---|---|---|')
+      for (const f of mismatches) {
+        out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | \`${mdEscape(f.property)}\` | ${f.field} | ${mdEscape(f.written)} | ${mdEscape(dataCell(f))} | ${f.association} | ${mdEscape(f.note)} |`)
+      }
+    } else out.push('None.')
+    const unset = r.findings.filter((f) => f.status === 'unset')
+    if (unset.length) {
+      out.push('', `### Not set in the data (${unset.length})`, '')
+      out.push('The data default is null, but the prose states a value. Redpanda often computes a fallback at runtime for an unset property; confirm it in the source.', '')
+      out.push('| File:line | Property | Field | Written | Note |', '|---|---|---|---|---|')
+      for (const f of unset) out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | \`${mdEscape(f.property)}\` | ${f.field} | ${mdEscape(f.written)} | ${mdEscape(f.note)} |`)
+    }
+    const qualified = r.findings.filter((f) => f.reason === 'qualified-differs')
+    if (qualified.length) {
+      out.push('', `### Qualified statements that differ from this version's data (${qualified.length})`, '')
+      out.push('The sentence names another audience or release, so the data cannot confirm it. Listed for a human to check.', '')
+      out.push('| File:line | Property | Written | Data value | Qualifier |', '|---|---|---|---|---|')
+      for (const f of qualified) out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | \`${mdEscape(f.property)}\` | ${mdEscape(f.written)} | ${mdEscape(dataCell(f))} | ${mdEscape(f.qualifier)} |`)
+    }
+    const cloudDiffers = r.findings.filter((f) => f.reason === 'cloud-default-differs-from-self-managed')
+    if (cloudDiffers.length) {
+      out.push('', `### Cloud defaults that differ from the self-managed default (${cloudDiffers.length})`, '')
+      out.push('The Cloud property reference states no defaults, so these cannot be verified. They may be Cloud-specific values or errors.', '')
+      out.push('| File:line | Property | Written | Self-managed default |', '|---|---|---|---|')
+      for (const f of cloudDiffers) out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | \`${mdEscape(f.property)}\` | ${mdEscape(f.written)} | ${mdEscape(f.dataValue)} |`)
+    }
+    for (const status of ['exact', 'equivalent']) {
+      const list = r.findings.filter((f) => f.status === status)
+      const heading = status === 'exact'
+        ? `Exact (${list.length}, ${list.filter((f) => f.autoSafe).length} auto-safe)`
+        : `Equivalent, proposed and never applied (${list.length})`
+      out.push('', `### ${heading}`, '')
+      if (!list.length) {
+        out.push('None.')
+        continue
+      }
+      out.push('| File:line | Written | Proposed | Renders | Auto-safe |', '|---|---|---|---|---|')
+      for (const f of list) out.push(`| ${mdEscape(`${f.file}:${f.line}`)} | ${mdEscape(f.written)} | \`${mdEscape(f.proposed.replace(/^`|`$/g, ''))}\` | ${mdEscape(f.proposed.includes('format=raw') ? f.dataRaw : f.dataValue)} | ${f.autoSafe ? 'yes' : 'no'} |`)
+    }
+    const unverifiable = r.findings.filter((f) => f.status === 'unverifiable' && !['cloud-default-differs-from-self-managed', 'qualified-differs'].includes(f.reason))
+    out.push('', `### Unverifiable (${unverifiable.length})`, '')
+    const byReason = {}
+    for (const f of unverifiable) byReason[f.reason] = (byReason[f.reason] || 0) + 1
+    out.push(Object.keys(byReason).length ? Object.entries(byReason).map(([k, v]) => `* ${k}: ${v}`).join('\n') : 'None.')
+    renderExamples(out, r.findings.filter((f) => f.status === 'example-output'))
+  }
+  return out.join('\n') + '\n'
+}
+
+module.exports = {
+  parseValue,
+  compareValue,
+  scanLine,
+  scanDocument,
+  classify,
+  scanRepo,
+  renderMarkdown,
+  parseExampleBlock,
+  compareRaw,
+  readComponent,
+  catalogFor,
+}