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

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

@@ -421,11 +421,22 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. json names repeat across
+ * structs (`enabled`, `name`), so the key is the Go package directory, the
+ * struct and the json name. Go type names are unique per package, and a
+ * package is one directory.
+ */
+function identity (decl) {
+  return [path.dirname(decl.file), (decl.meta && decl.meta.struct) || null, decl.name]
+}
+
 module.exports = {
   name: 'crd',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   loadConfig,
   collectInlinedTypes,
   UNDESCRIBED_EXTERNAL_TYPES,

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

@@ -472,6 +472,15 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. The name is the full
+ * values path, unique inside one values.yaml but repeated across charts, so
+ * the key is the file, the kind and the path.
+ */
+function identity (decl) {
+  return [decl.file, (decl.meta && decl.meta.kind) || null, decl.name]
+}
+
 module.exports = {
   name: 'helm',
   convention: CONVENTION,
@@ -480,6 +489,7 @@ module.exports = {
   publishableBlankKeys,
   scanKeyLines,
   misattachedMarkers,
+  identity,
   HELM_DOCS_MARKER_RE,
   rules: RULES
 }

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

@@ -197,7 +197,7 @@ function unescapeCpp (text) {
  * preceding make_* call that still encloses it, then read its first argument
  * if that argument is a string literal (adjacent literals concatenated).
  */
-function resolveMetricName (content, descIndex) {
+function resolveMetricName (content, descIndex, where = null) {
   const candidates = []
   MAKE_CALL.lastIndex = 0
   let match
@@ -213,6 +213,8 @@ function resolveMetricName (content, descIndex) {
     let i = openIndex + 1
     let name = ''
     let sawLiteral = false
+    let firstLiteral = -1
+    let lastLiteralEnd = -1
     while (i < content.length) {
       const ch = content[i]
       if (/\s/.test(ch)) {
@@ -228,11 +230,17 @@ function resolveMetricName (content, descIndex) {
         const end = skipLiteral(content, i)
         name += unescapeCpp(content.slice(i + 1, end - 1))
         sawLiteral = true
+        if (firstLiteral === -1) firstLiteral = i
+        lastLiteralEnd = end - 1
         i = end
         continue
       }
       break
     }
+    if (sawLiteral && where) {
+      where.start = firstLiteral
+      where.end = lastLiteralEnd
+    }
     return sawLiteral ? name : null
   }
   return null
@@ -268,16 +276,24 @@ function scanFile (content, file) {
     if (closeIndex === -1) continue
 
     const { verifiable, value } = parseArgument(masked.slice(openIndex + 1, closeIndex))
+    // The name literal sits in the enclosing make_*() call, outside the
+    // description span. Its lines are recorded so a rename counts as touching
+    // the declaration without widening the span a suggestion replaces.
+    const where = {}
+    const name = resolveMetricName(masked, match.index, where)
     declarations.push({
       surface: 'metrics',
-      name: resolveMetricName(masked, match.index),
+      name,
       file,
       line_start: lineOf(masked, match.index),
       line_end: lineOf(masked, closeIndex),
       string: value,
       declaration_text: null,
       convention: CONVENTION,
-      meta: { unverifiable: !verifiable }
+      meta: {
+        unverifiable: !verifiable,
+        name_lines: where.start != null ? [lineOf(masked, where.start), lineOf(masked, where.end)] : null
+      }
     })
     DESCRIPTION_CALL.lastIndex = closeIndex + 1
   }
@@ -359,10 +375,21 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. The extracted name is the
+ * make_*() argument without its add_group() prefix, so the same name repeats
+ * across groups; the file narrows it. Same-file repeats are handled by
+ * counting in the caller.
+ */
+function identity (decl) {
+  return [decl.file, decl.name]
+}
+
 module.exports = {
   name: 'metrics',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES
 }

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

@@ -242,6 +242,12 @@ const RULES = [
 
 module.exports = {
   name: 'properties',
+  // The extractor pairs each .cc with its .h, so a merge-base extraction needs
+  // the whole directory, not only the files that lost lines.
+  baseScope: 'directory',
+  // extract() runs the extractor over the whole repo and filters after, so
+  // page context can use every property at no extra cost.
+  contextScope: 'surface',
   convention: CONVENTION,
   extract,
   mapExtractorJson,

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

@@ -37,7 +37,15 @@ const CONVENTION = {
   case: 'sentence',
   terminal_period: false,
   verbatim_asciidoc: false,
-  transformer: 'formatDescription'
+  transformer: 'formatDescription',
+  // Code values formatDescription wraps in inline code by itself, so a bare
+  // one in the source is not a finding. Long is a Go raw string and cannot
+  // hold a backtick at all, which is why the generator does this. Keep in
+  // step with the auto-backtick passes in tools/rpk-docs/generate-rpk-docs.js.
+  auto_inline_code: {
+    kinds: ['flag'],
+    path_prefixes: ['/etc/', '/var/', '/usr/', '/home/', '/tmp/', '~/.']
+  }
 }
 
 // Composite literal only: gofmt writes `cobra.Command{` with no space, while
@@ -365,11 +373,22 @@ const RULES = [
   }
 ]
 
+/**
+ * Where a declaration lives, for removal matching. Flag names (`format`,
+ * `brokers`) and command names (`list`, `create`) repeat across the command
+ * tree, which the extractor does not resolve, so the key is the file, the
+ * kind and the name. Same-file repeats are handled by counting in the caller.
+ */
+function identity (decl) {
+  return [decl.file, (decl.meta && decl.meta.kind) || null, decl.name]
+}
+
 module.exports = {
   name: 'rpk',
   convention: CONVENTION,
   extract,
   scanFile,
+  identity,
   rules: RULES,
   // Shorts and flag usages are one-liners by convention; the generic
   // too-short prose rule would flag nearly every conforming declaration.

package/tools/overrides-audit/classify.js

@@ -326,7 +326,7 @@ function deepEqual (a, b) {
  */
 function row (fields) {
   const base = { name: fields.name, field: fields.field, class: fields.class }
-  for (const key of ['upstream_candidate_text', 'audience_scoped_text', 'upstream_ref', 'content_hash', 'source_file', 'source_line', 'note']) {
+  for (const key of ['upstream_candidate_text', 'audience_scoped_text', 'upstream_ref', 'content_hash', 'source_file', 'source_line', 'source_text', 'note']) {
     if (fields[key] !== undefined) base[key] = fields[key]
   }
   return base
@@ -357,7 +357,11 @@ function classifyDescription (name, override, sourceProp, opts = {}) {
     field: 'description',
     content_hash: contentHash(name, overrideText),
     source_file: sourceProp ? sourceProp.defined_in : undefined,
-    source_line: sourceProp && sourceProp.line_start !== undefined ? sourceProp.line_start : undefined
+    source_line: sourceProp && sourceProp.line_start !== undefined ? sourceProp.line_start : undefined,
+    // Raw source description text, carried through so the agent triage layer
+    // (tools/overrides-audit/triage.js) can compare it against the override
+    // candidate text without re-reading the extracted-properties JSON itself.
+    source_text: sourceProp ? normalizeText(sourceProp.description) : undefined
   }
   if (override.upstream_ref !== undefined) common.upstream_ref = override.upstream_ref
   // Shown, never upstreamed. A scoped paragraph exists precisely so the other

package/tools/overrides-audit/report.js

@@ -0,0 +1,169 @@
+/**
+ * Overrides Audit - Triage Report Sections
+ *
+ * Formats triaged candidates (classify.js rows extended with agent_verdict /
+ * agent_reason / triage_failed by triage.js's triageCandidate) into the
+ * plain-English markdown sections a downstream workflow glues into PR and
+ * issue bodies. This module never calls `gh` itself; it only builds strings.
+ *
+ * Every builder here returns a non-empty string even for an empty input
+ * array, so a caller can always embed the return value directly into a
+ * larger PR/issue body without checking for emptiness first.
+ */
+
+'use strict'
+
+/**
+ * Render one candidate's property name as a markdown subsection heading.
+ *
+ * @param {string} name - Property (or command) name.
+ * @returns {string} Markdown heading line.
+ */
+function heading (name) {
+  return `## ${name}`
+}
+
+/**
+ * Render a labeled block of text as an indented markdown blockquote, so long
+ * override/source text cannot be confused with the surrounding prose.
+ *
+ * @param {string} label - Label line, e.g. "Override text:".
+ * @param {string} text - The text to quote.
+ * @returns {string} Markdown block.
+ */
+function quotedBlock (label, text) {
+  const quoted = String(text)
+    .split('\n')
+    .map((line) => `> ${line}`)
+    .join('\n')
+  return `${label}\n\n${quoted}`
+}
+
+/**
+ * Build the "nothing happened this run" placeholder for an empty section.
+ * Never an empty string: this is meant to be embedded directly into a larger
+ * PR/issue body, and an empty string there reads as a rendering bug rather
+ * than "there was nothing to report."
+ *
+ * @param {string} noun - What there was none of, e.g. "properties to upstream".
+ * @returns {string} A one-line markdown message.
+ */
+function nothingThisRun (noun) {
+  return `Nothing to report: no ${noun} this run.`
+}
+
+/**
+ * Whether a row carries an explicitly successful triage state.
+ *
+ * triageCandidate always emits a boolean triage_failed, so anything other
+ * than exactly false (missing, null, a string, a number) is a row this code
+ * cannot trust. Such a row stays out of the actionable sections and lands in
+ * the ambiguous digest instead.
+ *
+ * @param {Object} row - A triaged candidate row.
+ * @returns {boolean} True only when triage_failed is exactly false.
+ */
+function triageSucceeded (row) {
+  return row.triage_failed === false
+}
+
+/**
+ * Build the markdown section listing candidates the agent triage layer
+ * decided are genuinely better in the override and should be ported
+ * upstream into engineering source (verdict UPSTREAM_OVERRIDE).
+ *
+ * @param {Object[]} candidates - Triaged rows (from triage.js's triageCandidate).
+ * @returns {string} Markdown section, always non-empty.
+ */
+function buildUpstreamSection (candidates) {
+  const rows = (candidates || []).filter((c) => c.agent_verdict === 'UPSTREAM_OVERRIDE' && triageSucceeded(c))
+  if (rows.length === 0) return nothingThisRun('property descriptions to upstream')
+
+  const parts = [
+    `Found ${rows.length} property description${rows.length === 1 ? '' : 's'} worth porting upstream into engineering source.`
+  ]
+  for (const row of rows) {
+    parts.push([
+      heading(row.name),
+      row.agent_reason,
+      // A SPLIT row's override also carries audience-scoped paragraphs or
+      // docs-only markup that the candidate text leaves out, so porting the
+      // prose alone does not make the override redundant.
+      row.class === 'KEEP_UNTIL_UPSTREAMED'
+        ? 'This PR ports that into the source description. The docs override stays after it ships, because it also carries audience-scoped paragraphs or docs-only markup that source does not; that content needs handling separately before the override can retire.'
+        : 'This PR ports that into the source description; once merged and released, the docs override becomes redundant and retires itself automatically.'
+    ].join('\n\n'))
+  }
+  return parts.join('\n\n')
+}
+
+/**
+ * Build the markdown section listing candidates the agent triage layer
+ * decided source has caught up to or surpassed, so the docs-side override
+ * should simply be deleted (verdict RETIRE_OVERRIDE). Engineering source is
+ * never touched for these.
+ *
+ * @param {Object[]} candidates - Triaged rows (from triage.js's triageCandidate).
+ * @returns {string} Markdown section, always non-empty.
+ */
+function buildRetirementSection (candidates) {
+  const rows = (candidates || []).filter((c) => c.agent_verdict === 'RETIRE_OVERRIDE' && triageSucceeded(c))
+  if (rows.length === 0) return nothingThisRun('overrides to retire')
+
+  const parts = [
+    `Found ${rows.length} docs override${rows.length === 1 ? '' : 's'} that source has caught up to; retiring them rather than touching engineering source.`
+  ]
+  for (const row of rows) {
+    parts.push([
+      heading(row.name),
+      row.agent_reason,
+      quotedBlock('Override text (current docs override):', row.upstream_candidate_text),
+      quotedBlock('Source text (what docs will render instead):', row.source_text),
+      '**Retiring this override; docs will now render source\'s description.**'
+    ].join('\n\n'))
+  }
+  return parts.join('\n\n')
+}
+
+/**
+ * Build one combined markdown digest of every candidate the agent triage
+ * layer could not confidently resolve either way: a real AMBIGUOUS verdict,
+ * a failed/malformed triage response (triage_failed: true), and a row with
+ * no explicit triage state (triage_failed missing or not a boolean) get exactly
+ * the same treatment here, because all three are equally unresolved from a
+ * human's point of view - a parse failure is not quietly dropped just
+ * because it never produced a real verdict.
+ *
+ * This is one digest, not one artifact per property, matching this
+ * codebase's "one rolling artifact, idempotently rebuilt every run" pattern
+ * (see tools/rpk-docs/generate-plugin-stubs.js for that idiom elsewhere):
+ * it is meant to become the body of a single rolling tracking issue that
+ * gets replaced wholesale each run, not appended to.
+ *
+ * @param {Object[]} candidates - Triaged rows (from triage.js's triageCandidate).
+ * @returns {string} Markdown digest, always non-empty.
+ */
+function buildAmbiguousDigest (candidates) {
+  const rows = (candidates || []).filter((c) => c.agent_verdict === 'AMBIGUOUS' || !triageSucceeded(c))
+  if (rows.length === 0) return nothingThisRun('ambiguous property descriptions')
+
+  const parts = [
+    `${rows.length} property description${rows.length === 1 ? '' : 's'} could not be confidently triaged and need a human call.`
+  ]
+  for (const row of rows) {
+    parts.push([
+      heading(row.name),
+      quotedBlock('Override text:', row.upstream_candidate_text),
+      quotedBlock('Source text:', row.source_text),
+      row.agent_reason,
+      'Needs a human call.'
+    ].join('\n\n'))
+  }
+  return parts.join('\n\n')
+}
+
+module.exports = {
+  buildUpstreamSection,
+  buildRetirementSection,
+  buildAmbiguousDigest
+}

package/tools/overrides-audit/triage.js

@@ -0,0 +1,225 @@
+/**
+ * Overrides Audit - Agent Triage Layer
+ *
+ * classify.js is deterministic: any UPSTREAMABLE or SPLIT KEEP_UNTIL_UPSTREAMED
+ * candidate whose override text differs from source is treated as "our text
+ * is better, push it upstream." That is not always true. Source can be
+ * independently improved between audit runs to something as good as or
+ * better than the override, and classify.js has no way to notice: it only
+ * compares normalized text for equality, never for which one reads better.
+ *
+ * This module is the missing judgment step. It does not call an LLM itself -
+ * a GitHub Actions workflow in the docs repo owns that call. This module only
+ * (a) builds the prompt that call should send, and (b) parses whatever text
+ * comes back into one of three verdicts, defaulting to the safest one
+ * (AMBIGUOUS, meaning "leave the override alone, ask a human") on any
+ * uncertainty at all. Silently guessing UPSTREAM_OVERRIDE or RETIRE_OVERRIDE
+ * on a malformed response would either write bad prose into engineering
+ * source or delete an override that source has not actually caught up to -
+ * both worse than asking a human.
+ */
+
+'use strict'
+
+const VERDICTS = Object.freeze({
+  UPSTREAM_OVERRIDE: 'UPSTREAM_OVERRIDE',
+  RETIRE_OVERRIDE: 'RETIRE_OVERRIDE',
+  AMBIGUOUS: 'AMBIGUOUS'
+})
+
+const VALID_VERDICTS = new Set(Object.values(VERDICTS))
+const ALLOWED_RESPONSE_KEYS = new Set(['verdict', 'reason'])
+
+/**
+ * Build the plain-text prompt an external LLM call should send for one
+ * triage candidate.
+ *
+ * The prompt is written for a reader who has never seen this codebase: it
+ * explains the two texts being compared, the three possible verdicts in
+ * plain terms, and when to refuse to choose. It requires strict JSON back
+ * with no markdown fences and no surrounding prose, because parseTriageResponse
+ * has to be able to trust the shape of a well-behaved response and only fall
+ * back defensively for a badly-behaved one.
+ *
+ * @param {Object} candidate - A classify.js manifest row for a `description`
+ *   field classified UPSTREAMABLE or KEEP_UNTIL_UPSTREAMED (SPLIT), extended
+ *   with `source_text` (see classify.js's `common.source_text`).
+ * @param {string} candidate.name - Property (or command) name.
+ * @param {string} candidate.upstream_candidate_text - The override's candidate text.
+ * @param {string} candidate.source_text - The current source description text.
+ * @param {string} [candidate.source_file] - File the source description lives in.
+ * @param {number} [candidate.source_line] - Line the source description starts at.
+ * @returns {string} The prompt text.
+ * @throws {Error} When `candidate` is missing `upstream_candidate_text` or `source_text`.
+ *   This is a programming-error guard, not the agent-response fallback below:
+ *   a caller that hands this function a REDUNDANT row, or any row that never
+ *   got a source_text, has a bug that should fail loudly, not produce a
+ *   prompt that quietly asks an LLM to compare a real string to `undefined`.
+ */
+function buildTriagePrompt (candidate) {
+  if (!candidate || typeof candidate.upstream_candidate_text !== 'string') {
+    throw new Error(`buildTriagePrompt: candidate for "${candidate && candidate.name}" is missing upstream_candidate_text`)
+  }
+  if (typeof candidate.source_text !== 'string') {
+    throw new Error(`buildTriagePrompt: candidate for "${candidate.name}" is missing source_text`)
+  }
+
+  const location = candidate.source_file
+    ? `${candidate.source_file}${candidate.source_line !== undefined ? `:${candidate.source_line}` : ''}`
+    : 'unknown location'
+
+  return `You are triaging one property description for a documentation team.
+
+A documentation site publishes reference docs for a configuration property named "${candidate.name}". Its description currently comes from a manually written "override" that the docs team keeps because, at some point in the past, the engineering source code's own description of this property was missing, wrong, or worse than what the docs team wrote. Engineering source now defines its own description for the same property, at ${location}.
+
+Your job is to compare the two descriptions below and decide what should happen next.
+
+OVERRIDE TEXT (currently shown to docs readers, and a candidate to copy into engineering source):
+"""
+${candidate.upstream_candidate_text}
+"""
+
+CURRENT SOURCE TEXT (what engineering's own code says today):
+"""
+${candidate.source_text}
+"""
+
+Choose exactly one of these three verdicts:
+
+1. UPSTREAM_OVERRIDE - The override text is genuinely better or more complete than the source text. The right move is to copy the override's wording into the engineering source code, so that source eventually says what the override already says.
+
+2. RETIRE_OVERRIDE - The source text has caught up to, or become as good as or better than, the override in substance. There is no longer a good reason to keep the override. The right move is to delete the docs-side override entirely and let the docs site render the source text as-is, without ever touching engineering source.
+
+3. AMBIGUOUS - You cannot confidently choose between the two options above. Choose this if you are genuinely uncertain, if the two texts each contain distinct real information and neither one is a strict subset of the other (so picking one would lose real content), or if judging the two texts correctly requires technical knowledge of this system that cannot be confirmed from the text alone. When in doubt, choose AMBIGUOUS rather than guessing. Guessing wrong here either writes bad text into engineering source code or throws away a description a docs reader currently relies on, so it is always safer to flag this for a human than to guess.
+
+Respond with strict JSON only. Do not use markdown code fences. Do not include any words, explanation, or punctuation outside the JSON object. The response must be exactly one JSON object shaped like this:
+
+{"verdict": "UPSTREAM_OVERRIDE" | "RETIRE_OVERRIDE" | "AMBIGUOUS", "reason": "one or two plain-English sentences a non-engineer documentation reviewer can understand, explaining the comparison you made and why this verdict follows from it"}
+`
+}
+
+/**
+ * Extract a JSON value from raw agent response text. Accepts only a whole
+ * JSON response or one wrapped in a single pair of markdown code fences, the
+ * one common way a model fails to follow "strict JSON only" without changing
+ * what it said. Prose around the JSON is rejected rather than stripped: that
+ * prose can contradict the embedded verdict (for example "I cannot decide"
+ * followed by a RETIRE_OVERRIDE object), so it is not safe to trust the object.
+ *
+ * @param {string} text - Raw response text.
+ * @returns {*} The parsed value.
+ * @throws {Error} When the (unfenced) response is not valid JSON.
+ */
+function extractJson (text) {
+  let candidate = text.trim()
+
+  // Strip a single pair of markdown code fences, ```json ... ``` or ``` ... ```.
+  const fenceMatch = candidate.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i)
+  if (fenceMatch) candidate = fenceMatch[1].trim()
+
+  return JSON.parse(candidate)
+}
+
+/**
+ * The safe, conservative fallback result for any response the parser cannot
+ * fully trust.
+ *
+ * @param {string} reason - Specific, human-readable explanation of what went wrong.
+ * @returns {{verdict: string, reason: string, triageFailed: boolean}}
+ */
+function ambiguousFallback (reason) {
+  return { verdict: VERDICTS.AMBIGUOUS, reason, triageFailed: true }
+}
+
+/**
+ * Defensively parse whatever text an LLM triage call returned.
+ *
+ * Clean JSON and JSON wrapped in markdown fences are accepted. JSON
+ * surrounded by stray prose, an empty or truncated response, or JSON that
+ * parses but carries an invalid or missing verdict or reason, or any field
+ * other than verdict and reason, is treated as
+ * a triage failure and mapped to the same safe AMBIGUOUS
+ * fallback: this function's job is to never let a malformed response be
+ * mistaken for a real UPSTREAM_OVERRIDE or RETIRE_OVERRIDE call.
+ *
+ * @param {string} rawText - Raw text returned by the LLM call.
+ * @returns {{verdict: string, reason: string, triageFailed: boolean}}
+ */
+function parseTriageResponse (rawText) {
+  if (typeof rawText !== 'string' || rawText.trim().length === 0) {
+    return ambiguousFallback('The triage call returned no response.')
+  }
+
+  let parsed
+  try {
+    parsed = extractJson(rawText)
+  } catch {
+    return ambiguousFallback('The triage response was not valid JSON.')
+  }
+
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return ambiguousFallback('The triage response was valid JSON but not a JSON object.')
+  }
+
+  // The prompt asks for exactly { verdict, reason }. An extra field such as
+  // needs_human_review or confidence can contradict the verdict, and nothing
+  // downstream reads it, so treat any extra key as a failed triage rather
+  // than silently dropping it.
+  const extraKeys = Object.keys(parsed).filter((key) => !ALLOWED_RESPONSE_KEYS.has(key))
+  if (extraKeys.length > 0) {
+    return ambiguousFallback(`The triage response included unexpected fields: ${extraKeys.join(', ')}.`)
+  }
+
+  // Case-sensitive on purpose: a case variant (e.g. "upstream_override") is a
+  // real deviation from the required response shape, worth surfacing as a
+  // failure rather than silently normalizing away.
+  if (typeof parsed.verdict !== 'string' || !VALID_VERDICTS.has(parsed.verdict)) {
+    return ambiguousFallback('The triage response used an unrecognized verdict value.')
+  }
+
+  if (typeof parsed.reason !== 'string' || parsed.reason.trim().length === 0) {
+    return ambiguousFallback('The triage response was missing a reason.')
+  }
+
+  return { verdict: parsed.verdict, reason: parsed.reason, triageFailed: false }
+}
+
+/**
+ * Combine a classify.js candidate row with the parsed result of a triage
+ * call, producing a manifest row extended with the agent's verdict.
+ *
+ * Field names follow classify.js's snake_case manifest-row convention rather
+ * than parseTriageResponse's camelCase return shape.
+ *
+ * @param {Object} candidate - A classify.js manifest row.
+ * @param {string} rawAgentResponse - Raw text returned by the LLM triage call.
+ * A RETIRE_OVERRIDE verdict on a SPLIT (KEEP_UNTIL_UPSTREAMED) candidate is
+ * downgraded to AMBIGUOUS, because retiring that override would also delete
+ * its audience-scoped or docs-only content.
+ *
+ * @returns {Object} `candidate` merged with `agent_verdict`, `agent_reason`, `triage_failed`.
+ */
+function triageCandidate (candidate, rawAgentResponse) {
+  let { verdict, reason, triageFailed } = parseTriageResponse(rawAgentResponse)
+  // A SPLIT (KEEP_UNTIL_UPSTREAMED) override also carries audience-scoped
+  // paragraphs or docs-only markup that the candidate text leaves out.
+  // Retiring the whole override would delete that content, so even when
+  // source prose has caught up, route the row to a human instead.
+  if (verdict === VERDICTS.RETIRE_OVERRIDE && candidate && candidate.class === 'KEEP_UNTIL_UPSTREAMED') {
+    verdict = VERDICTS.AMBIGUOUS
+    reason = `${reason} This override also carries audience-scoped paragraphs or docs-only markup that source does not, so it cannot be retired whole. Decide what to do with that content.`
+  }
+  return {
+    ...candidate,
+    agent_verdict: verdict,
+    agent_reason: reason,
+    triage_failed: triageFailed
+  }
+}
+
+module.exports = {
+  VERDICTS,
+  buildTriagePrompt,
+  parseTriageResponse,
+  triageCandidate
+}

package/tools/property-extractor/README.adoc

@@ -1231,7 +1231,12 @@ breaks. Two files feed it, both mirrors of the `docs` repo:
 fields the rendering and link layers read. `cloud_supported` is the point: it is what
 makes the "no Cloud link to a property Cloud does not publish" assertion real rather
 than assumed. Descriptions are deliberately absent, because the corpus test drives prose from
-the overrides file, and a full copy would be 695 KB of text that rots.
+the overrides file, and a full copy would be 695 KB of text that rots. The exceptions are
+overrides that act on the source description instead of replacing it: links with no prose of
+their own, which apply to the source description, and includes with no description of their
+own, which the generator appends to it. The snapshot keeps the source description for those
+properties. `.github/scripts/derive-property-snapshot.js` makes that call from the overrides
+file, and both the recipe below and `property-corpus-drift.sh` use it.
 
 Keep the overrides copy a faithful mirror. It previously doubled as
 `property-docs-overrides.test.js`'s fixture, someone hand-edited an `admin` entry into
@@ -1264,17 +1269,13 @@ TAG="$(git -C "$DOCS" ls-tree origin/main --name-only -- modules/reference/attac
 echo "Refreshing against $TAG"
 
 git -C "$DOCS" show "origin/main:modules/reference/attachments/redpanda-properties-${TAG}.json" \
+  > /tmp/redpanda-properties.json
+node .github/scripts/derive-property-snapshot.js /tmp/redpanda-properties.json \
+  __tests__/docs-data/property-overrides.json \
   | node -e '
     const fs = require("fs");
-    const src = JSON.parse(fs.readFileSync(0, "utf8"));
-    const keep = ["name","config_scope","type","cloud_supported","cloud_editable",
-                  "cloud_readonly","cloud_byoc_only","is_deprecated","nullable"];
-    const properties = {};
-    for (const [k, v] of Object.entries(src.properties || {})) {
-      properties[k] = Object.fromEntries(keep.filter((f) => f in v).map((f) => [f, v[f]]));
-    }
     const out = JSON.parse(fs.readFileSync("__tests__/docs-data/property-snapshot.json", "utf8"));
-    out.properties = properties;
+    out.properties = JSON.parse(fs.readFileSync(0, "utf8"));
     out.source_tag = process.argv[1];
     fs.writeFileSync("__tests__/docs-data/property-snapshot.json", JSON.stringify(out, null, 1) + "\n");
   ' "$TAG"

package/tools/property-extractor/transformers.py

@@ -2124,6 +2124,32 @@ class EnterpriseTransformer:
             restricted_vals = self._extract_list_items(params[0]["value"])
             info["params"] = params[1:]
 
+        # --- restricted scalar ahead of the name, with a trailing vector ---
+        # Pattern: (restricted, name, description, meta, default, ..., vector)
+        # enterprise<enum_set_property<T>> takes this shape: http_authentication
+        # is ("OIDC", "http_authentication", ...) ending in its allowed values.
+        # Without this branch the trailing vector wins as sanctioned_only and
+        # the restricted value is left where the name belongs. Anchored on the
+        # member name, so a scalar is only taken as a restriction when the
+        # argument after it is the property's own name.
+        elif (
+            len(params) >= 5
+            and "std::vector" in str(params[-1]["value"])
+            and params[0]["type"] in ("true", "false", "integer_literal", "string_literal", "qualified_identifier")
+            and self._clean_value(params[1]["value"]) == info.get("name_in_file")
+            and self._clean_value(params[0]["value"]) != info.get("name_in_file")
+        ):
+            restricted_vals = [self._clean_value(params[0]["value"])]
+            if "enum" in str(info.get("type") or ""):
+                # The trailing vector is the enum's allowed values; keep it for
+                # TypeTransformer.
+                enterprise_constructor = "restricted_only"
+                info["params"] = params[1:]
+            else:
+                enterprise_constructor = "restricted_with_sanctioned"
+                sanctioned_vals = self._extract_list_items(params[-1]["value"])
+                info["params"] = params[1:-1]
+
         # --- sanctioned_only (vector form) ---
         elif len(params) >= 5 and "std::vector" in str(params[-1]["value"]):
             enterprise_constructor = "sanctioned_only"