@redpanda-data/docs-extensions-and-macros 5.54.0 → 5.56.0

package/tools/doc-impact-recording/index.js

@@ -0,0 +1,190 @@
+'use strict'
+
+/**
+ * Turn a Claude Code transcript into a doc-impact MCP recording.
+ *
+ * The doc-strings review asks the docs MCP server (docs.redpanda.com/mcp)
+ * whether published pages already cover a changed string. The doc-impact
+ * eval replays those answers per item, so an eval run sees the docs as they
+ * were when the review ran, not as they are today. A recording made later
+ * would already contain the writer's fix for the PR, and the pass would
+ * then correctly say "already documented" for a PR that needed docs.
+ *
+ * This reads the transcript the review step leaves behind and keeps only
+ * what a replay needs: the tool name, its arguments, and the result content.
+ * Nothing else from the transcript is copied, so the session's tokens,
+ * headers, environment and identity never reach the recording.
+ *
+ * The arguments are the model's own text, though, and the review reads
+ * untrusted PR content. A call whose arguments or result contain something
+ * shaped like a credential is dropped rather than saved, because the
+ * recording is uploaded as an artifact and log masking doesn't cover
+ * artifacts.
+ *
+ * Accepted input:
+ *   - the execution file anthropics/claude-code-action writes: one JSON
+ *     array of SDK messages;
+ *   - `claude -p --output-format stream-json` output: one message per line.
+ * Both carry the same message shapes, so one parser serves both.
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const DEFAULT_SERVER = 'redpanda-docs'
+
+// Credential shapes a recording must never carry: GitHub tokens (classic and
+// fine-grained), JWTs (which include GitHub App and OIDC tokens), and AWS
+// access key IDs.
+const SECRET_PATTERNS = [
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}/,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/,
+  /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/
+]
+
+/** Whether a value, serialized, contains anything shaped like a credential. */
+function looksSecret (value) {
+  const text = typeof value === 'string' ? value : JSON.stringify(value)
+  return SECRET_PATTERNS.some((re) => re.test(text || ''))
+}
+
+/** Messages from a transcript, in order. Lines that are not JSON are skipped. */
+function parseTranscript (text) {
+  const raw = String(text || '')
+  const trimmed = raw.trim()
+  if (trimmed.startsWith('[')) {
+    try {
+      const all = JSON.parse(trimmed)
+      if (Array.isArray(all)) return all.filter((m) => m && typeof m === 'object')
+    } catch {
+      // Not one JSON document; read it line by line below.
+    }
+  }
+  const out = []
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      const m = JSON.parse(line)
+      if (m && typeof m === 'object' && !Array.isArray(m)) out.push(m)
+    } catch {
+      // Progress lines and other non-JSON output are not messages.
+    }
+  }
+  return out
+}
+
+/** Tool-result content as an array of MCP content blocks. */
+function contentBlocks (content) {
+  if (content == null) return []
+  if (typeof content === 'string') return [{ type: 'text', text: content }]
+  if (Array.isArray(content)) return content.map((b) => (typeof b === 'string' ? { type: 'text', text: b } : b))
+  return [{ type: 'text', text: JSON.stringify(content) }]
+}
+
+function blocksOf (message) {
+  const content = message && message.message && message.message.content
+  return Array.isArray(content) ? content : []
+}
+
+/**
+ * Every call to one MCP server's tools, paired with its result, in call
+ * order. A call with no result (the run stopped first) is left out: a
+ * replay of it would answer with nothing the server ever said.
+ */
+function extractCalls (messages, { server = DEFAULT_SERVER } = {}) {
+  const prefix = `mcp__${server}__`
+  const calls = []
+  const byId = new Map()
+  for (const m of messages || []) {
+    if (m.type === 'assistant') {
+      for (const b of blocksOf(m)) {
+        if (b && b.type === 'tool_use' && typeof b.name === 'string' && b.name.startsWith(prefix)) {
+          const call = { tool: b.name.slice(prefix.length), arguments: b.input || {}, content: null, is_error: false }
+          calls.push(call)
+          byId.set(b.id, call)
+        }
+      }
+    } else if (m.type === 'user') {
+      for (const b of blocksOf(m)) {
+        if (b && b.type === 'tool_result' && byId.has(b.tool_use_id)) {
+          const call = byId.get(b.tool_use_id)
+          call.content = contentBlocks(b.content)
+          call.is_error = Boolean(b.is_error)
+        }
+      }
+    }
+  }
+  return calls.filter((c) => c.content !== null)
+}
+
+/** Split calls into the ones safe to save and the count dropped as secret-bearing. */
+function dropSecretCalls (calls) {
+  const kept = calls.filter((c) => !looksSecret(c.arguments) && !looksSecret(c.content))
+  return { kept, dropped: calls.length - kept.length }
+}
+
+/** The model the session ran on, from its init message. */
+function sessionModel (messages) {
+  const init = (messages || []).find((m) => m.type === 'system' && m.subtype === 'init')
+  return (init && typeof init.model === 'string' && init.model) || null
+}
+
+/**
+ * A recording in the shape the doc-impact eval replays:
+ * { item, recorded_at, server_url, model, source, calls: [{ tool, arguments, content, is_error }] }
+ */
+function buildRecording (messages, { item = null, recordedAt, serverUrl = null, model = null, server = DEFAULT_SERVER } = {}) {
+  const { kept, dropped } = dropSecretCalls(extractCalls(messages, { server }))
+  const recording = {
+    item,
+    recorded_at: recordedAt || new Date().toISOString(),
+    server_url: serverUrl,
+    model: model || sessionModel(messages),
+    source: 'production',
+    calls: kept
+  }
+  // Not enumerable, so it never reaches the written file.
+  Object.defineProperty(recording, 'droppedSecretCalls', { value: dropped })
+  return recording
+}
+
+/**
+ * CLI entry: read --execution-file, write --output. Writes nothing when the
+ * session made no docs calls it can save, and removes any file an earlier
+ * run left at --output, so the caller can tell "no calls" from "a
+ * recording" by the file's presence. Exits 0 either way; a missing or
+ * unreadable transcript is exit 1.
+ */
+function runCli (options, { log = console.log, error = console.error } = {}) {
+  const file = options.executionFile
+  let text
+  try {
+    text = fs.readFileSync(file, 'utf8')
+  } catch (e) {
+    error(`Cannot read the transcript at ${file}: ${e.message}`)
+    return 1
+  }
+  const messages = parseTranscript(text)
+  const recording = buildRecording(messages, {
+    item: options.item || null,
+    recordedAt: options.recordedAt,
+    serverUrl: options.serverUrl || null,
+    model: options.model || null,
+    server: options.server || DEFAULT_SERVER
+  })
+  if (recording.droppedSecretCalls) {
+    error(`Dropped ${recording.droppedSecretCalls} MCP call(s) whose arguments or result look like a credential.`)
+  }
+  if (!recording.calls.length) {
+    fs.rmSync(options.output, { force: true })
+    log(`No ${options.server || DEFAULT_SERVER} MCP calls to save in ${messages.length} transcript message(s); no recording written.`)
+    return 0
+  }
+  fs.mkdirSync(path.dirname(path.resolve(options.output)), { recursive: true })
+  fs.writeFileSync(options.output, JSON.stringify(recording, null, 2) + '\n')
+  log(`Wrote ${recording.calls.length} ${options.server || DEFAULT_SERVER} MCP call(s) to ${options.output}.`)
+  return 0
+}
+
+module.exports = { parseTranscript, extractCalls, sessionModel, buildRecording, dropSecretCalls, looksSecret, runCli, DEFAULT_SERVER }

package/tools/enterprise-features/detect-gating-changes.js

@@ -0,0 +1,393 @@
+'use strict'
+
+/**
+ * Finds enterprise gating changes in a Redpanda core diff that no doc string
+ * announces, and shapes them as doc-impact findings.
+ *
+ * The doc-strings review derives its published-content impact from the doc
+ * strings a PR changes. Two kinds of change carry no doc string at all and
+ * still change what the licensing docs say:
+ *
+ *   - a value added to (or removed from) `enum class license_required_feature`
+ *     in src/v/features/enterprise_features.h: the feature starts (or stops)
+ *     being reported by `rpk cluster license info` and
+ *     GET /v1/features/enterprise, and the enterprise features registry in
+ *     redpanda-data/docs needs an entry under an approved external name;
+ *   - a property wrapped in `config::enterprise<>` in
+ *     src/v/config/configuration.h: the property becomes (or stops being)
+ *     license-gated, so the licensing tables and the disable page change;
+ *   - a changed restricted value of an enterprise<> property in
+ *     src/v/config/configuration.cc: which values need a license changes,
+ *     with no change to the header or to any doc string.
+ *
+ * streaming-enterprise PR 579 (2026-10-07) was the first miss: it added
+ * `manual_finalization` to the enum and changed license enforcement, touched
+ * no doc string, and so filed nothing. This module reads the diff text only,
+ * so a test can hand it a saved patch; the CLI wrapper runs git.
+ *
+ * Detection is by added and removed lines, paired by name, so a value that
+ * merely moves within the enum is not reported. Both signals the header
+ * carries for an enum value are used (the member line inside the enum, and
+ * the `case license_required_feature::<name>:` line in format_to), so a
+ * hunk header that happens not to name the enum still detects.
+ *
+ * Each finding names ONE affected page, the licensing overview. The docs-site
+ * receiver falls back to matching a finding with no name match against open
+ * tickets that share at least two page topics, so two gating findings that
+ * both listed the overview and the disable page would be treated as one
+ * ticket however different the features. The disable page is named in the
+ * summary text instead.
+ */
+
+const ENUM_HEADER = 'src/v/features/enterprise_features.h'
+const CONFIG_HEADER = 'src/v/config/configuration.h'
+const CONFIG_SOURCE = 'src/v/config/configuration.cc'
+
+const LICENSING_OVERVIEW = 'https://docs.redpanda.com/streaming/current/get-started/licensing/overview/'
+const DISABLE_PAGE = 'https://docs.redpanda.com/streaming/current/get-started/licensing/disable-enterprise-features/'
+const REGISTRY_URL = 'https://github.com/redpanda-data/docs/blob/main/shared/modules/ROOT/partials/enterprise-features.yml'
+
+/**
+ * Split unified diff text into { path, lines[] } per file, where lines are
+ * the raw hunk lines (prefixed with ' ', '+', '-') and hunk headers.
+ */
+function splitFiles (diffText) {
+  const files = []
+  let current = null
+  for (const raw of String(diffText || '').split('\n')) {
+    const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(raw)
+    if (m) {
+      current = { path: m[2], lines: [] }
+      files.push(current)
+      continue
+    }
+    if (!current) continue
+    if (/^(\+\+\+|---|index |new file|deleted file|similarity|rename|old mode|new mode)/.test(raw)) continue
+    current.lines.push(raw)
+  }
+  return files
+}
+
+/**
+ * Enum values added and removed in enterprise_features.h.
+ * @returns {{added: string[], removed: string[]}}
+ */
+function enumChanges (lines) {
+  const added = new Set()
+  const removed = new Set()
+  // The member line only counts inside the enum. Track that from the hunk
+  // header and from context lines, both of which git carries in the diff.
+  // Only enum members count: `case license_required_feature::x:` labels move
+  // whenever the formatter is rewritten (26.2 replaced operator<< with a
+  // format_to switch), so a case label is never read as a feature change.
+  let inEnum = false
+  for (const line of lines) {
+    if (line.startsWith('@@')) {
+      inEnum = /enum class license_required_feature/.test(line)
+      continue
+    }
+    const body = line.slice(1)
+    if (/^\s*enum class license_required_feature\b/.test(body)) { inEnum = true; continue }
+    if (inEnum && /^\s*};/.test(body)) { inEnum = false; continue }
+    const sign = line[0]
+    if (sign !== '+' && sign !== '-') continue
+    const target = sign === '+' ? added : removed
+    const member = inEnum && /^\s*([a-z][a-z0-9_]*)\s*,?\s*(\/\/.*)?$/.exec(body)
+    if (member) target.add(member[1])
+  }
+  return {
+    added: [...added].filter((n) => !removed.has(n)).sort(),
+    removed: [...removed].filter((n) => !added.has(n)).sort()
+  }
+}
+
+// One declaration can span lines (clang-format wraps a long template
+// argument list, so `enterprise<...>` and the member name land on separate
+// lines). Lines are joined into statements before matching: a statement ends
+// at a `;`, and also at a brace, an access specifier or a preprocessor line,
+// so a declaration never absorbs the line before it.
+const ENTERPRISE_DECL = /^\s*(?:config::)?enterprise<[\s\S]*>\s*([a-z][a-z0-9_]*)\s*;\s*$/
+
+// Comments and attributes are dropped before joining: a `/* ... */` or
+// `[[attr]]` line above a declaration has no `;` or brace, so it would
+// otherwise be glued to the front of the declaration and hide it.
+function stripComments (text, state) {
+  let out = ''
+  let rest = text
+  // A hunk can start inside a block comment whose opener is above it; a
+  // line that starts with `*` or `*/` is read as part of that comment.
+  if (!state.inBlock && /^\s*\*(\s|\/|$)/.test(rest)) state.inBlock = true
+  while (rest) {
+    if (state.inBlock) {
+      const end = rest.indexOf('*/')
+      if (end === -1) return out
+      state.inBlock = false
+      rest = rest.slice(end + 2)
+      continue
+    }
+    const line = rest.indexOf('//')
+    const block = rest.indexOf('/*')
+    if (block !== -1 && (line === -1 || block < line)) {
+      out += rest.slice(0, block) + ' '
+      state.inBlock = true
+      rest = rest.slice(block + 2)
+      continue
+    }
+    out += line === -1 ? rest : rest.slice(0, line)
+    break
+  }
+  return out.replace(/\[\[[^\]]*\]\]/g, ' ')
+}
+
+/**
+ * Join C++ source lines into statements. Each statement carries whether any
+ * of its lines is marked `changed`.
+ * @param {Array<{text: string, changed?: boolean}>} lines
+ * @returns {Array<{text: string, changed: boolean}>}
+ */
+function joinStatements (lines) {
+  const out = []
+  let buf = []
+  let changed = false
+  const flush = () => {
+    if (buf.length) out.push({ text: buf.join(' '), changed })
+    buf = []
+    changed = false
+  }
+  const state = { inBlock: false }
+  for (const { text, changed: c } of lines) {
+    const body = stripComments(text, state).trim()
+    if (!body) continue
+    if (/^#/.test(body) || /^(public|private|protected)\s*:$/.test(body)) { flush(); continue }
+    buf.push(body)
+    changed = changed || Boolean(c)
+    if (/[;{}]$/.test(body)) flush()
+  }
+  flush()
+  return out
+}
+
+/**
+ * Names of every property wrapped in enterprise<> in a configuration.h text.
+ * @param {string} headerText
+ * @returns {string[]}
+ */
+function enterprisePropertyNames (headerText) {
+  const names = new Set()
+  for (const st of joinStatements(String(headerText || '').split('\n').map((text) => ({ text })))) {
+    const m = ENTERPRISE_DECL.exec(st.text)
+    if (m) names.add(m[1])
+  }
+  return [...names].sort()
+}
+
+/**
+ * Properties whose declaration gained or lost the enterprise<> wrapper in
+ * configuration.h. A declaration changed in place shows as a -/+ pair with
+ * the same name; the wrapper is on exactly one side. Each side of each hunk
+ * (context plus its own changed lines) is joined into statements, so a
+ * declaration that wraps across lines is read whole.
+ * @returns {{added: string[], removed: string[]}}
+ */
+function enterprisePropertyChanges (lines) {
+  const added = new Set()
+  const removed = new Set()
+  const collect = (side, target) => {
+    for (const st of joinStatements(side)) {
+      if (!st.changed) continue
+      const m = ENTERPRISE_DECL.exec(st.text)
+      if (m) target.add(m[1])
+    }
+  }
+  let oldSide = []
+  let newSide = []
+  const flushHunk = () => {
+    collect(oldSide, removed)
+    collect(newSide, added)
+    oldSide = []
+    newSide = []
+  }
+  for (const line of lines) {
+    if (line.startsWith('@@')) { flushHunk(); continue }
+    const sign = line[0]
+    const text = line.slice(1)
+    if (sign === '-') oldSide.push({ text, changed: true })
+    else if (sign === '+') newSide.push({ text, changed: true })
+    else if (sign === ' ') { oldSide.push({ text }); newSide.push({ text }) }
+  }
+  flushHunk()
+  return {
+    added: [...added].filter((n) => !removed.has(n)).sort(),
+    removed: [...removed].filter((n) => !added.has(n)).sort()
+  }
+}
+
+/**
+ * Enterprise properties whose restricted value changed in configuration.cc.
+ * An enterprise<> property's initializer takes its restricted value (or a
+ * predicate) between `*this` and the property's name literal:
+ *
+ *     , audit_enabled(
+ *       *this,
+ *       true, // restricted value
+ *       "audit_enabled",
+ *
+ * so a changed line between a `*this,` line and the `"<name>",` line of a
+ * property in `enterpriseNames` changes which values need a license. Only
+ * the initializer is read: a restricted value that names a constant or a
+ * function defined elsewhere (sasl_mechanisms reads
+ * enterprise_sasl_mechanisms) changes where that is defined, and is not
+ * seen here.
+ * @param {string[]} lines - hunk lines of configuration.cc
+ * @param {Set<string>} enterpriseNames
+ * @returns {string[]}
+ */
+function restrictedValueChanges (lines, enterpriseNames) {
+  const found = new Set()
+  let init = null
+  let changed = false
+  for (const line of lines) {
+    if (line.startsWith('@@')) { init = null; changed = false; continue }
+    const sign = line[0]
+    if (sign !== ' ' && sign !== '+' && sign !== '-') continue
+    const body = line.slice(1)
+    const opens = /^\s*,\s*([a-z][a-z0-9_]*)\s*\(/.exec(body)
+    if (opens) { init = opens[1]; changed = false; continue }
+    if (/^\s*\*this\s*,/.test(body)) { changed = sign !== ' '; continue }
+    // The name literal closes the restricted arguments. A string literal
+    // that is neither this initializer's name nor an enterprise property
+    // (http_authentication's restricted "OIDC") is a value, not the name.
+    const lit = /^\s*"([a-z][a-z0-9_]*)"\s*,/.exec(body)
+    if (lit && (lit[1] === init || enterpriseNames.has(lit[1]))) {
+      if (changed && enterpriseNames.has(lit[1])) found.add(lit[1])
+      changed = false
+      continue
+    }
+    // A hunk that starts after `*this` still counts the changed lines up to
+    // the name literal its context carries.
+    if (sign !== ' ') changed = true
+  }
+  return [...found].sort()
+}
+
+/**
+ * Detect enterprise gating changes in a diff.
+ * @param {string} diffText - unified diff (`git diff base...HEAD`)
+ * @param {object} [options]
+ * @param {string[]} [options.enterpriseNames] - properties wrapped in
+ *   enterprise<> at HEAD (see enterprisePropertyNames). Without it, a
+ *   configuration.cc change cannot be tied to an enterprise property and is
+ *   not reported.
+ * @returns {Array<{surface: string, name: string, change_kind: string, affected_pages: string[], summary: string}>}
+ */
+function detectGatingChanges (diffText, { enterpriseNames = [] } = {}) {
+  const findings = []
+  const files = splitFiles(diffText)
+  const header = files.find((f) => f.path === CONFIG_HEADER)
+  const headerChanged = new Set(header ? Object.values(enterprisePropertyChanges(header.lines)).flat() : [])
+  for (const file of files) {
+    if (file.path === ENUM_HEADER) {
+      const { added, removed } = enumChanges(file.lines)
+      for (const name of added) {
+        findings.push({
+          surface: 'enterprise-feature',
+          name,
+          change_kind: 'enterprise-feature-added',
+          affected_pages: [LICENSING_OVERVIEW],
+          summary: `\`${name}\` was added to \`license_required_feature\` in \`${ENUM_HEADER}\`. From the first release that contains this change, \`rpk cluster license info\` and \`GET /v1/features/enterprise\` report it and the license nag names it. The enterprise features registry (${REGISTRY_URL}) needs an entry under the approved external name, with a gating property and, where a property turns it off, a row on ${DISABLE_PAGE}; the weekly registry check fails until it has one. Any page that describes this feature's license behavior needs the new reporting and enforcement.`
+        })
+      }
+      for (const name of removed) {
+        findings.push({
+          surface: 'enterprise-feature',
+          name,
+          change_kind: 'enterprise-feature-removed',
+          affected_pages: [LICENSING_OVERVIEW],
+          summary: `\`${name}\` was removed from \`license_required_feature\` in \`${ENUM_HEADER}\`. The release that contains this change no longer reports it as an enterprise feature. The enterprise features registry entry that points at it (${REGISTRY_URL}) needs a new source pointer or a note, never deletion: a published external name stays in the registry.`
+        })
+      }
+    } else if (file.path === CONFIG_HEADER) {
+      const { added, removed } = enterprisePropertyChanges(file.lines)
+      for (const name of added) {
+        findings.push({
+          surface: 'enterprise-property',
+          name,
+          change_kind: 'enterprise-gate-added',
+          affected_pages: [LICENSING_OVERVIEW],
+          summary: `\`${name}\` is now wrapped in \`config::enterprise<>\` in \`${CONFIG_HEADER}\`, so a restricted value needs a license from the first release that contains this change. The enterprise features registry (${REGISTRY_URL}) needs an entry that names this property as its source or gating property, and ${DISABLE_PAGE} needs a row for the unrestricted value.`
+        })
+      }
+      for (const name of removed) {
+        findings.push({
+          surface: 'enterprise-property',
+          name,
+          change_kind: 'enterprise-gate-removed',
+          affected_pages: [LICENSING_OVERVIEW],
+          summary: `\`${name}\` is no longer wrapped in \`config::enterprise<>\` in \`${CONFIG_HEADER}\`, so it no longer needs a license. The registry entry that names it (${REGISTRY_URL}) and its row on ${DISABLE_PAGE} need to change.`
+        })
+      }
+    } else if (file.path === CONFIG_SOURCE) {
+      // A property whose wrapper changed in the header is already reported
+      // above; its initializer changes with it.
+      for (const name of restrictedValueChanges(file.lines, new Set(enterpriseNames))) {
+        if (headerChanged.has(name)) continue
+        findings.push({
+          surface: 'enterprise-property',
+          name,
+          change_kind: 'enterprise-restricted-value-changed',
+          affected_pages: [LICENSING_OVERVIEW],
+          summary: `The restricted value of \`${name}\`, a \`config::enterprise<>\` property, changed in \`${CONFIG_SOURCE}\`, so which values need a license changes from the first release that contains this change. The enterprise features registry entry that names it (${REGISTRY_URL}) and its row on ${DISABLE_PAGE} need the new restricted and unrestricted values.`
+        })
+      }
+    }
+  }
+  return findings
+}
+
+/**
+ * Shape findings as the doc-impact report the review workflow dispatches
+ * (the same JSON the model writes to doc-impact.json), or null when there is
+ * nothing to report.
+ */
+function buildDocImpact (findings) {
+  if (!findings || findings.length === 0) return null
+  // The dispatch schema allows ten findings. Title, body and findings all
+  // come from the same capped list, so the ticket never names a change the
+  // findings (which the receiver dedupes on) leave out; the overflow is
+  // counted instead.
+  const capped = findings.slice(0, 10)
+  const overflow = findings.length - capped.length
+  const names = capped.map((f) => `\`${f.name}\``).join(', ')
+  const bullets = capped.map((f) => `- ${f.name} (${f.change_kind}): ${f.summary}`).join('\n')
+  return {
+    findings: capped,
+    proposed_ticket: {
+      title: `Update enterprise feature docs for ${capped.map((f) => f.name).join(', ')}${overflow > 0 ? ` and ${overflow} more` : ''}`,
+      body: [
+        `This PR changes which features Redpanda gates on an enterprise license, without changing any doc string, so the licensing docs do not pick it up on regeneration: ${names}.`,
+        '',
+        bullets,
+        ...(overflow > 0 ? [`- ${overflow} more gating change(s) are not listed here; see the PR diff.`] : []),
+        '',
+        `Registry: ${REGISTRY_URL}`,
+        `Licensing overview: ${LICENSING_OVERVIEW}`,
+        `Disable page: ${DISABLE_PAGE}`,
+        '',
+        'The change is on the default branch until a release contains it; the docs change belongs to the version branch for that release. Confirm the affected release with the PR author.'
+      ].join('\n')
+    }
+  }
+}
+
+module.exports = {
+  ENUM_HEADER,
+  CONFIG_HEADER,
+  CONFIG_SOURCE,
+  detectGatingChanges,
+  buildDocImpact,
+  enumChanges,
+  enterprisePropertyChanges,
+  enterprisePropertyNames,
+  restrictedValueChanges,
+  splitFiles
+}

package/tools/enterprise-features/verify.js

@@ -12,6 +12,7 @@
  */
 
 const yaml = require('js-yaml')
+const { generatedMarker } = require('../../cli-utils/generated-marker')
 const semver = require('semver')
 
 // Mirrors macros/enterprise.js: no 'cloud' scope, because Redpanda Cloud has
@@ -197,7 +198,7 @@ function buildMappingPartial (features, enumValues) {
     }
   }
   const lines = [
-    '// Generated by `doc-tools validate enterprise-features --write-mapping`. Do not edit.',
+    generatedMarker('validate enterprise-features --write-mapping', 'the enterprise feature names reported by rpk cluster license info'),
     '// Maps the internal feature names reported by `rpk cluster license info`',
     '// (enterprise_features_in_use) to their documented names.',
     '[cols="1m,2a"]',

package/tools/gen-rpk-ascii.py

@@ -26,6 +26,11 @@ rpk_basic_command = ["rpk"]
 
 def assert_period(s):return s if s.endswith('.') else s + '.'
 
+# Same marker shape as cli-utils/generated-marker.js (no version, so a release
+# does not rewrite every page); convert-to-markdown reads it.
+GENERATED_MARKER = ("// This content is autogenerated. Do not edit manually. "
+                    "Generated by doc-tools (rpk-docs) from the rpk command help in redpanda-data/streaming-enterprise.")
+
 def escape_chars(s):
 
     s = s.replace("./<timestamp>-bundle.zip", "./&lt;timestamp&gt;-bundle.zip")
@@ -311,7 +316,8 @@ def build_ascii(ascii_result, executed_command, explanation, usage, it_flags, fl
     if not os.path.exists(rpk_gen_dir):
         os.makedirs(rpk_gen_dir)
 
-    # Construct the asciidoc content
+    # Construct the asciidoc content, marker first
+    ascii_result += GENERATED_MARKER + "\n"
     ascii_result += "= " + executed_command
     ascii_result += "\n:description: " + executed_command
     ascii_result += "\n\n" + explanation

package/tools/lint-strings/fixtures/connect/lint_connect.go

@@ -23,6 +23,14 @@ When a consumer group is specified this input consumes one or more topics.
 
 This fixture exercises the ` + "`raw` + interpreted + `raw`" + ` concatenation idiom.
 
+ifndef::env-cloud[]
+Set the consumer group in the input config so this paragraph publishes only to the self-managed docs.
+endif::[]
+
+ifdef::env-cloud[]
+The consumer group is managed for you, so this paragraph publishes only to the Cloud docs.
+endif::[]
+
 == Metadata
 
 This heading and the table below are legitimate AsciiDoc:

package/tools/lint-strings/fixtures/crd/lint_types.go

@@ -15,9 +15,12 @@ type WidgetSpec struct {
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="ClusterSource is immutable"
 	ClusterSource *ClusterSource `json:"cluster"`
 	// Text is the actual unescaped text of a widget. The Go name matches
-	// the json name (case only), so this conforms.
+	// the json name up to case, and it still opens with the Go name.
 	// +required
 	Text string `json:"text,omitempty"`
+	// maxBytes is the largest widget payload accepted. It opens with the
+	// YAML key instead of what the field does.
+	MaxBytes int `json:"maxBytes,omitempty"`
 	// Specifies how many replicas to run. Conforming: describes behavior,
 	// never names the field.
 	// +kubebuilder:default=3