@redpanda-data/docs-extensions-and-macros 5.10.0 → 5.11.1

package/cli-utils/helm-commented-values.js

@@ -0,0 +1,361 @@
+'use strict'
+
+/**
+ * Extracts documentation for commented-out values in a Helm chart's
+ * values.yaml, and injects the resulting entries into the AsciiDoc reference
+ * that `doc-tools generate helm-spec` produces.
+ *
+ * helm-docs only renders rows for keys that exist in the YAML tree, so
+ * optional values that ship commented out (for example `external.domain` in
+ * the Redpanda chart) never appear in the generated reference, even when the
+ * chart author wrote a `# --` description for them. This module closes that
+ * gap without requiring any change to chart behavior.
+ *
+ * Two comment conventions are recognized:
+ *
+ * 1. helm-docs style, attached to a commented-out key. A comment block that
+ *    contains a `# -- description` marker and is immediately followed by a
+ *    commented-out key documents that key. The key's path is derived from
+ *    the enclosing uncommented keys by indentation:
+ *
+ *      external:
+ *        # -- Optional domain advertised to external clients.
+ *        # domain: local
+ *
+ *    yields `external.domain`.
+ *
+ * 2. Explicit, fully-qualified syntax that works anywhere in the file:
+ *
+ *      # @doc external.addresses -- Optional list of advertised addresses.
+ *      # @default -- `nil`
+ *
+ * In both forms, an optional `# @default -- text` line overrides the
+ * displayed default, which is otherwise `nil`.
+ */
+
+// Key names never contain dots or slashes: a dotted or slashed "key" in a
+// comment is prose or a URL (`# docker.redpanda.com/...:4.101.0`), and
+// treating it as a key both fabricates a path and truncates the description.
+// Fully-qualified dotted paths are supported through the @doc syntax instead.
+const COMMENTED_KEY_RE = /^(\s*)#(\s{0,4})([a-z][A-Za-z0-9_-]*):\s*(.*)$/
+const REAL_KEY_RE = /^(\s*)([A-Za-z0-9_."/-]+):(.*)$/
+// `(?!-)` keeps comment dividers such as `# ----------------` from being
+// mistaken for an empty description marker.
+const DESC_MARKER_RE = /^\s*#\s*--\s*(?!-)(.*)$/
+const AT_DOC_RE = /^\s*#\s*@doc\s+([A-Za-z0-9_./-]+)\s+--\s*(.*)$/
+const AT_DEFAULT_RE = /^\s*#\s*@default\s+--\s*(.*)$/
+const COMMENT_RE = /^\s*#\s?(.*)$/
+// A block scalar header may carry an explicit indentation indicator digit on
+// either side of the chomping indicator: `|2`, `|-2`, `|2-`, `>2`, ...
+const BLOCK_SCALAR_RE = /[|>][0-9]?[+-]?[0-9]?\s*(#.*)?$/
+const LIST_ITEM_RE = /^\s*-\s/
+
+/**
+ * Parse values.yaml text and return entries for documented commented-out keys.
+ *
+ * @param {string} yamlText - Raw contents of values.yaml.
+ * @returns {Array<{path: string, description: string, default: string}>}
+ */
+function extractCommentedValueDocs (yamlText) {
+  const lines = yamlText.split(/\r?\n/)
+  const entries = []
+  const stack = [] // enclosing real keys: { name, indent }
+
+  // Accumulating comment block: { descLines, default, candidate }. The
+  // candidate is the key the block documents; emission is deferred to the
+  // end of the block so that a later key line at the same depth supersedes a
+  // prose line that merely looks like a key (`# example:`, `# default: 30s`).
+  let block = null
+  let atDoc = null // accumulating @doc entry: { path, descLines, default }
+  let skipScalarIndent = -1 // inside a block scalar when >= 0
+  let suppressInnerIndent = -1 // inside an emitted commented key's subtree when >= 0
+
+  const flushAtDoc = () => {
+    if (atDoc) {
+      entries.push({
+        path: atDoc.path,
+        description: atDoc.descLines.join('\n').trim(),
+        default: atDoc.default || '`nil`',
+      })
+      atDoc = null
+    }
+  }
+
+  // Emit the active block's candidate, if any, and close the block. The
+  // emitted key suppresses its own commented subtree until real content
+  // appears, so nested example structures do not emit bogus paths.
+  const flushBlock = () => {
+    if (block && block.candidate) {
+      const { name, effIndent } = block.candidate
+      const parents = stack.filter((k) => k.indent < effIndent).map((k) => k.name)
+      entries.push({
+        path: [...parents, name].join('.'),
+        description: block.descLines.join('\n').trim(),
+        default: block.default || '`nil`',
+      })
+      suppressInnerIndent = effIndent
+    }
+    block = null
+  }
+
+  for (const line of lines) {
+    // Skip the body of block scalars so their content is never mistaken for
+    // keys or comments.
+    if (skipScalarIndent >= 0) {
+      const indent = line.match(/^\s*/)[0].length
+      if (line.trim() === '' || indent > skipScalarIndent) continue
+      skipScalarIndent = -1
+    }
+
+    const atDocMatch = line.match(AT_DOC_RE)
+    if (atDocMatch) {
+      flushAtDoc()
+      flushBlock()
+      atDoc = { path: atDocMatch[1], descLines: [atDocMatch[2]], default: '' }
+      continue
+    }
+
+    const atDefault = line.match(AT_DEFAULT_RE)
+    if (atDefault) {
+      if (atDoc) atDoc.default = atDefault[1].trim()
+      else if (block) block.default = atDefault[1].trim()
+      continue
+    }
+
+    const commentedKey = line.match(COMMENTED_KEY_RE)
+    if (commentedKey) {
+      // A commented-out key line terminates an @doc entry rather than being
+      // swallowed into its description, so @doc lines can sit directly above
+      // the commented key they document.
+      flushAtDoc()
+      // Authors indent a commented key either before the marker ("  # child:")
+      // or after it ("#   child:"), and the two forms mean the same nesting.
+      // Counting only one side made them disagree: a child indented before the
+      // marker escaped its parent's subtree and was emitted as a top-level
+      // path. Fold both sides into one depth, treating the single space that
+      // separates "#" from its text as punctuation rather than indentation, so
+      // the result lines up with the real-key indents held on the stack.
+      const effIndent = commentedKey[1].length + Math.max(0, commentedKey[2].length - 1)
+      // A previously emitted commented key suppresses its own commented
+      // subtree, so nested example structures do not emit bogus paths.
+      if (suppressInnerIndent >= 0 && effIndent > suppressInnerIndent) {
+        block = null
+        continue
+      }
+      suppressInnerIndent = -1
+      // Only bare keys or simple scalar values look like real chart values.
+      // Prose such as `# Warning: If you use LoadBalancers...` has spaces in
+      // the trailing text and is rejected.
+      const value = commentedKey[4].trim()
+      // Reject URL-like lines such as `# https://github.com/...`, where the
+      // "key" is a URL scheme and the "value" is the scheme-relative part.
+      const simpleValue = (value === '' || !/\s/.test(value)) && !value.startsWith('/')
+      if (block && simpleValue) {
+        if (!block.candidate || effIndent <= block.candidate.effIndent) {
+          // The last key-shaped line at the block's shallowest depth wins:
+          // an earlier line at the same depth was prose shaped like a key,
+          // and deeper lines are nested example structures.
+          block.candidate = { name: commentedKey[3], effIndent }
+        }
+        continue
+      }
+    }
+
+    const descMarker = line.match(DESC_MARKER_RE)
+    if (descMarker) {
+      flushAtDoc()
+      flushBlock()
+      block = { descLines: [descMarker[1]], default: '', candidate: null }
+      continue
+    }
+
+    const comment = line.match(COMMENT_RE)
+    if (comment && line.trim().startsWith('#')) {
+      if (atDoc) atDoc.descLines.push(comment[1])
+      // Description lines precede the documented key; once a candidate
+      // exists, trailing comment lines belong to its example structure.
+      else if (block && !block.candidate) block.descLines.push(comment[1])
+      continue
+    }
+
+    // Any non-comment line ends comment accumulation. Only real content also
+    // ends subtree suppression: a blank line inside a commented-out example
+    // structure must not re-enable emission against a stale parent key, since
+    // the real-key stack is not rebuilt by comment lines.
+    flushAtDoc()
+    flushBlock()
+    if (line.trim() === '') continue
+    suppressInnerIndent = -1
+
+    if (LIST_ITEM_RE.test(line)) continue
+
+    const realKey = line.match(REAL_KEY_RE)
+    if (realKey) {
+      const indent = realKey[1].length
+      while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+        stack.pop()
+      }
+      stack.push({ name: realKey[2].replace(/^"|"$/g, ''), indent })
+      if (BLOCK_SCALAR_RE.test(realKey[3])) skipScalarIndent = indent
+    }
+  }
+
+  flushAtDoc()
+  flushBlock()
+  return entries
+}
+
+/**
+ * Check a dotted value path against a chart's values.schema.json. A path is
+ * rejected only when the walk can prove the schema forbids it: an object
+ * level whose `properties` lack the segment, whose `patternProperties` (if
+ * any) do not match it, and whose `additionalProperties` is `false`.
+ * Anything the walk cannot interpret ($ref, allOf, open objects) is allowed,
+ * so an incomplete schema never hides documentation.
+ *
+ * @param {object} schema - Parsed values.schema.json.
+ * @param {string} path - Dotted value path, for example `external.domain`.
+ * @returns {boolean}
+ */
+function isPathAllowedBySchema (schema, path) {
+  let node = schema
+  for (const segment of path.split('.')) {
+    if (!node || typeof node !== 'object' || node.$ref || node.allOf || node.anyOf || node.oneOf) {
+      return true
+    }
+    const props = node.properties
+    if (props && Object.prototype.hasOwnProperty.call(props, segment)) {
+      node = props[segment]
+      continue
+    }
+    if (node.patternProperties) {
+      const pattern = Object.keys(node.patternProperties)
+        .find((p) => { try { return new RegExp(p).test(segment) } catch { return true } })
+      if (pattern !== undefined) {
+        node = node.patternProperties[pattern]
+        continue
+      }
+    }
+    return node.additionalProperties !== false
+  }
+  return true
+}
+
+/**
+ * Split extracted entries into those permitted by the chart's
+ * values.schema.json and those provably rejected by it, such as keys whose
+ * `# --` comment is a deprecation notice for a removed value.
+ *
+ * @param {Array<{path: string}>} entries
+ * @param {object} schema - Parsed values.schema.json.
+ * @returns {{accepted: Array, rejected: Array}}
+ */
+function filterEntriesBySchema (entries, schema) {
+  const accepted = []
+  const rejected = []
+  for (const entry of entries) {
+    (isPathAllowedBySchema(schema, entry.path) ? accepted : rejected).push(entry)
+  }
+  return { accepted, rejected }
+}
+
+// Neutralize description lines that would otherwise parse as AsciiDoc
+// structure when injected at block level: section titles re-parent the
+// following sections, and an unclosed block delimiter swallows the rest of
+// the document. `{empty}` renders as nothing but demotes the line to a
+// plain paragraph.
+function sanitizeDescription (text) {
+  return text
+    .split('\n')
+    .map((line) => (/^(=+\s|-{2,}\s*$|[=*_.+]{4,}\s*$|\|===)/.test(line) ? `{empty}${line}` : line))
+    .join('\n')
+}
+
+/**
+ * Inject extracted entries into a generated AsciiDoc Helm reference.
+ *
+ * Sections are matched by their `=== link:++<url>?...path=<key>++[<key>]`
+ * headings. New sections reuse the Artifact Hub URL prefix of the existing
+ * sections and are inserted in alphabetical key order. Keys that are already
+ * documented are skipped.
+ *
+ * @param {string} adoc - The converted AsciiDoc document.
+ * @param {Array<{path: string, description: string, default: string}>} entries
+ * @returns {{doc: string, injected: string[], sectionsFound: number}}
+ */
+function injectIntoAsciiDoc (adoc, entries) {
+  // The label may itself contain brackets (`[storage.volume[0].name]` in the
+  // connectors chart), so it is matched to end of line rather than to the
+  // first closing bracket.
+  const headingRe = /^=== link:\+\+(https?:\/\/[^+]*[?&]path=)([^+]+)\+\+\[.*\]\s*$/gm
+  const sections = []
+  let match
+  while ((match = headingRe.exec(adoc)) !== null) {
+    sections.push({ index: match.index, urlPrefix: match[1], key: match[2] })
+  }
+  if (sections.length === 0) {
+    return { doc: adoc, injected: [], sectionsFound: 0 }
+  }
+
+  const urlPrefix = sections[0].urlPrefix
+  // Tracks both keys present in the document and keys queued for injection,
+  // so a path extracted twice (for example, from both @doc and # -- comments
+  // for the same key) is only injected once.
+  const existingKeys = new Set(sections.map((s) => s.key))
+  const additions = []
+  for (const entry of entries) {
+    if (existingKeys.has(entry.path)) continue
+    existingKeys.add(entry.path)
+    additions.push(entry)
+  }
+  additions.sort((a, b) => a.path.localeCompare(b.path))
+
+  let doc = adoc
+  const injected = []
+
+  for (const entry of additions) {
+    // Recompute section offsets after each insertion.
+    const current = []
+    headingRe.lastIndex = 0
+    while ((match = headingRe.exec(doc)) !== null) {
+      current.push({ index: match.index, key: match[2] })
+    }
+    const after = current.find((s) => s.key.localeCompare(entry.path) > 0)
+
+    const section = [
+      `=== link:++${urlPrefix}${entry.path}++[${entry.path}]`,
+      '',
+      sanitizeDescription(entry.description),
+      '',
+      `*Default:* ${entry.default}`,
+      '',
+      '',
+    ].join('\n')
+
+    if (after) {
+      doc = doc.slice(0, after.index) + section + doc.slice(after.index)
+    } else {
+      // Append after the final section, before the next heading (levels 1-3)
+      // if one exists, so a trailing non-values subsection stays last.
+      const last = current[current.length - 1]
+      const rest = doc.slice(last.index)
+      const nextHeading = rest.search(/\n={1,3} /)
+      if (nextHeading > 0) {
+        const cut = last.index + nextHeading + 1
+        doc = doc.slice(0, cut) + section + doc.slice(cut)
+      } else {
+        doc = doc.trimEnd() + '\n\n' + section
+      }
+    }
+    injected.push(entry.path)
+  }
+
+  return { doc, injected, sectionsFound: sections.length }
+}
+
+module.exports = {
+  extractCommentedValueDocs,
+  injectIntoAsciiDoc,
+  filterEntriesBySchema,
+  isPathAllowedBySchema,
+}

package/cli-utils/self-managed-docs-branch.js

@@ -1,37 +1,45 @@
-const https = require('https');
 const yaml = require('js-yaml');
 const { spawnSync } = require('child_process');
+const { getGitHubToken } = require('./github-token');
+
+const ANTORA_URL = 'https://raw.githubusercontent.com/redpanda-data/docs/main/antora.yml'
+
+const TOKEN_HINT = ' The docs repository is private, so set GIT_CREDENTIALS (or GITHUB_TOKEN / REDPANDA_GITHUB_TOKEN / ACTIONS_BOT_TOKEN) so the fetch can authenticate.'
+const REJECTED_HINT = ' A GitHub token was sent but rejected, so it may be expired or not grant access to the docs repository (the default Actions GITHUB_TOKEN is scoped to its own repository).'
 
 /**
  * Retrieves the current Self-Managed documentation version from the remote antora.yml file.
  *
+ * The docs repository is private, and raw.githubusercontent serves private
+ * content as 404 rather than 401 when unauthenticated, so the fetch sends a
+ * Bearer token when one is available. It also returns 404 (not 401) for a
+ * REJECTED token, so a 404 with a token is retried once without
+ * authentication before being treated as real.
+ *
+ * @param {object} [deps] - Injectable for tests: { fetchImpl, token }.
  * @returns {Promise<string>} Resolves with the version string (for example, "25.1").
  *
  * @throws {Error} If the antora.yml file cannot be fetched, parsed, or if the version field is missing.
  */
-function fetchRemoteAntoraVersion() {
-  const url = 'https://raw.githubusercontent.com/redpanda-data/docs/main/antora.yml'
-  return new Promise((resolve, reject) => {
-    https.get(url, res => {
-      if (res.statusCode !== 200) {
-        return reject(new Error(`Failed to fetch antora.yml: ${res.statusCode}`))
-      }
-      let body = ''
-      res.on('data', chunk => (body += chunk))
-      res.on('end', () => {
-        try {
-          const cfg = yaml.load(body)
-          if (cfg.version == null) {
-            throw new Error('version field missing')
-          }
-          const version = String(cfg.version).trim()
-          resolve(version)
-        } catch (err) {
-          reject(err)
-        }
-      })
-    }).on('error', reject)
-  })
+async function fetchRemoteAntoraVersion(deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch
+  const ghToken = 'token' in deps ? deps.token : getGitHubToken()
+
+  let resp = await fetchImpl(ANTORA_URL, ghToken ? { headers: { Authorization: `Bearer ${ghToken}` } } : undefined)
+  const hint = ghToken ? REJECTED_HINT : TOKEN_HINT
+  if (resp.status === 404 && ghToken) {
+    await resp.body?.cancel().catch(() => {})
+    resp = await fetchImpl(ANTORA_URL)
+  }
+  if (!resp.ok) {
+    await resp.body?.cancel().catch(() => {})
+    throw new Error(`Failed to fetch antora.yml: ${resp.status}${resp.status === 404 ? hint : ''}`)
+  }
+  const cfg = yaml.load(await resp.text())
+  if (cfg.version == null) {
+    throw new Error('version field missing')
+  }
+  return String(cfg.version).trim()
 }
 
 /**

package/cli-utils/setup-mcp.js

@@ -141,7 +141,8 @@ async function setupMCP(options = {}) {
 
         // Check if configuration matches desired mode
         const isCorrectNpxConfig = mode === 'npx' && existingCommand === 'npx' &&
-                                    existingArgs.includes('doc-tools-mcp');
+                                    existingArgs.includes('doc-tools-mcp') &&
+                                    existingArgs.some(a => a === `--package=${packageName}`);
         const isCorrectLocalConfig = mode === 'local' && existingCommand === 'node' &&
                                       existingArgs[0] === localPath;
 
@@ -149,7 +150,7 @@ async function setupMCP(options = {}) {
           needsUpdate = true;
           console.log(chalk.yellow('⚠ ') + ' MCP server configured but with different setup:');
           console.log(chalk.gray(`  Current: ${existingCommand} ${existingArgs.join(' ')}`));
-          const newSetup = mode === 'local' ? `node ${localPath}` : 'npx -y doc-tools-mcp';
+          const newSetup = mode === 'local' ? `node ${localPath}` : `npx -y --package=${packageName} doc-tools-mcp`;
           console.log(chalk.gray(`  New:     ${newSetup}\n`));
         } else {
           console.log(chalk.green('✓') + ` MCP server already configured correctly\n`);
@@ -197,7 +198,7 @@ async function setupMCP(options = {}) {
   if (mode === 'local') {
     command = `claude mcp add --transport stdio --scope user ${serverName} -- node ${localPath}`;
   } else {
-    command = `claude mcp add --transport stdio --scope user ${serverName} -- npx -y doc-tools-mcp`;
+    command = `claude mcp add --transport stdio --scope user ${serverName} -- npx -y --package=${packageName} doc-tools-mcp`;
   }
 
   // Execute the command

package/mcp/USER_GUIDE.adoc

@@ -1202,7 +1202,7 @@ claude mcp add --transport stdio --scope user redpanda-docs-tool-assistant -- \
 [,bash]
 ----
 claude mcp add --transport stdio --scope user redpanda-docs-tool-assistant -- \
-  npx -y doc-tools-mcp
+  npx -y --package=@redpanda-data/docs-extensions-and-macros doc-tools-mcp
 ----
 
 This adds the MCP server configuration to `~/.claude.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.10.0",
+  "version": "5.11.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -24,6 +24,7 @@
     "build": "antora --to-dir docs --fetch local-antora-playbook.yml",
     "serve": "wds --node-resolve --open preview/test/ --watch --root-dir docs",
     "test": "jest",
+    "test:unit": "jest --config jest.unit.config.js",
     "test:e2e": "jest __tests__/e2e/",
     "test:mcp": "jest __tests__/mcp/",
     "test:mcp:integration": "jest __tests__/mcp/integration.test.js",

package/tools/enterprise-features/parsers.js

@@ -112,23 +112,9 @@ function parseDisableTable (source) {
   return rows
 }
 
-/**
- * Extract the enterprise-components attribute list from rp-connect-docs
- * antora.yml, without a YAML dependency on the full file structure.
- *
- * @param {object} antoraConfig - Parsed antora.yml object.
- * @returns {string[]|undefined} The list, or undefined when absent.
- */
-function extractAntoraEnterpriseComponents (antoraConfig) {
-  const attributes = antoraConfig && antoraConfig.asciidoc && antoraConfig.asciidoc.attributes
-  const list = attributes && attributes['enterprise-components']
-  return Array.isArray(list) ? list.map(String) : undefined
-}
-
 module.exports = {
   parseCoreEnum,
   parseEnterpriseProperties,
   parseConnectEnterprisePlugins,
   parseDisableTable,
-  extractAntoraEnterpriseComponents,
 }

package/tools/enterprise-features/verify.js

@@ -122,22 +122,36 @@ function checkCoreProperties (features, enterpriseProperties, allPropertyNames)
 }
 
 /**
- * Compare connect info.csv enterprise plugins against the stale
- * enterprise-components list in rp-connect-docs antora.yml (when given).
+ * Validate registry connect-plugin pointers against the enterprise plugins
+ * in connect's info.csv.
+ *
+ * This used to diff info.csv against the hand-maintained
+ * enterprise-components list in rp-connect-docs antora.yml, but
+ * rp-connect-docs#485 removed that list (it had gone stale — the exact drift
+ * this validator exists to catch). Per-plugin enterprise status in the docs
+ * now comes from the generated connector catalog, which is built from the
+ * same connect metadata as info.csv, so it cannot drift by construction.
+ * What can still go stale is the registry itself: any entry that pins a
+ * specific plugin via `source: {kind: connect-plugin}` must name a plugin
+ * that info.csv actually marks enterprise.
+ *
+ * The check also reports what it verified, so a run with zero pinned
+ * plugins is visibly a shallow pass rather than a silent one.
  */
-function checkConnect (infoCsvPlugins, antoraList) {
+function checkConnect (infoCsvPlugins, features, connectRef) {
   const findings = []
-  if (!antoraList) return findings
-  for (const plugin of infoCsvPlugins) {
-    if (!antoraList.includes(plugin)) {
-      findings.push(finding('error', 'connect-list', `Plugin '${plugin}' is enterprise in info.csv but missing from the enterprise-components list in rp-connect-docs antora.yml.`))
-    }
-  }
-  for (const plugin of antoraList) {
-    if (!infoCsvPlugins.includes(plugin)) {
-      findings.push(finding('error', 'connect-list', `Plugin '${plugin}' is in the enterprise-components list in rp-connect-docs antora.yml but not enterprise in info.csv.`))
+  const pinned = []
+  const source = connectRef ? `info.csv@${connectRef}` : 'info.csv'
+  for (const feature of features) {
+    if (feature.source && feature.source.kind === 'connect-plugin') {
+      const value = String(feature.source.value).trim()
+      pinned.push(value)
+      if (!infoCsvPlugins.includes(value)) {
+        findings.push(finding('error', 'connect-list', `'${feature.name}' points at connect plugin '${value}', which is not an enterprise plugin in ${source} (renamed, removed, or no longer enterprise).`))
+      }
     }
   }
+  findings.push(finding('info', 'connect-list', `${source} lists ${infoCsvPlugins.length} enterprise plugin(s); ${pinned.length} pinned by registry connect-plugin entries. Individual plugins are documented by the generated connector catalog; the licensing table covers them through the aggregate connect-scope entries.`))
   return findings
 }
 
@@ -200,7 +214,7 @@ function buildMappingPartial (features, enumValues) {
  * @param {string} [sources.coreHeader] - enterprise_features.h contents.
  * @param {string} [sources.configurationHeader] - configuration.h contents.
  * @param {string} [sources.infoCsv] - connect info.csv contents.
- * @param {string[]} [sources.antoraEnterpriseComponents]
+ * @param {string} [sources.connectRef] - ref the info.csv was fetched at, for messages.
  * @param {string} [sources.disablePage] - disable-enterprise-features.adoc contents.
  * @param {string[]} [sources.allPropertyNames] - full property list for gating checks.
  * @returns {{findings: object[], features: object[], enumValues: string[]}}
@@ -223,7 +237,7 @@ function runChecks (sources) {
   }
   if (sources.infoCsv) {
     const plugins = parsers.parseConnectEnterprisePlugins(sources.infoCsv)
-    findings.push(...checkConnect(plugins, sources.antoraEnterpriseComponents))
+    findings.push(...checkConnect(plugins, features, sources.connectRef))
   } else {
     findings.push(finding('info', 'connect-list', 'Skipped: no connect info.csv provided.'))
   }

package/tools/generate-cli-docs.js

@@ -299,6 +299,7 @@ IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm
     'property-docs',
     'metrics-docs',
     'rpk-docs',
+    'rpk-env-partial',
     'rpcn-connector-docs',
     'helm-spec',
     'cloud-regions',

package/tools/rpk-docs/generate-rpk-docs.js

@@ -2588,6 +2588,10 @@ async function generateRpkDocs(options = {}) {
     overrides,
     outputDir,
     cloudSecretDir, // Directory for rpk cloud and rpk security secret commands
+    // Directory for the shared -X -> RPK_* env vars partial. The handler passes
+    // the partials dir it already derived; when absent (direct callers, tests)
+    // it is derived from outputDir the same way.
+    envPartialDir,
     rpkVersion,
     pluginVersions = {},
     draftMissing = false,
@@ -3155,6 +3159,21 @@ async function generateRpkDocs(options = {}) {
     navResult = updateNavFile(navFile, commands, resolvedOverrides, topLevelWithSubcommands, effectiveProtectedPlugins)
   }
 
+  // Regenerate the shared -X -> RPK_* env vars partial from the same tree,
+  // so it always matches the rpk build the command pages came from. Trees
+  // from rpk versions that predate x_options (redpanda#31520) skip with a
+  // note; `doc-tools generate rpk-env-partial` covers those via its
+  // -X list fallback.
+  const envPartialResult = writeEnvVarsPartial(
+    tree,
+    envPartialDir || derivePartialsDir(outputDir)
+  )
+  if (envPartialResult.written) {
+    console.log(`  Regenerated env vars partial (${envPartialResult.keyCount} -X options): ${envPartialResult.output}`)
+  } else {
+    console.log('  Env vars partial not regenerated: tree has no x_options (rpk predates redpanda#31520)')
+  }
+
   return {
     commandCount: commands.length,
     filesGenerated,
@@ -3162,12 +3181,55 @@ async function generateRpkDocs(options = {}) {
     filesFailed,
     filesDeleted,
     subdirectoriesCreated: createdSubdirs.size,
+    envPartial: envPartialResult,
     ...navResult
   }
 }
 
+/**
+ * Resolve the partials directory of the Antora module that owns the rpk pages.
+ *
+ * For the docs layout (`.../modules/reference/pages/rpk`) this is the sibling
+ * of `pages`, so `.../modules/reference/partials`. For an arbitrary
+ * `--output-dir` there is no `pages` segment to anchor on, so fall back to a
+ * `partials` directory beside the output. Walking a fixed number of levels up
+ * from outputDir is wrong for arbitrary paths: it escapes the output tree and
+ * can land on an unrelated directory.
+ *
+ * @param {string} outputDir - The rpk pages output directory
+ * @returns {string} Absolute or relative path to the partials directory
+ */
+function derivePartialsDir (outputDir) {
+  const normalized = String(outputDir).replace(/\\/g, '/')
+  const pagesIndex = normalized.lastIndexOf('/pages/')
+  if (pagesIndex !== -1) {
+    return path.join(normalized.substring(0, pagesIndex), 'partials')
+  }
+  return path.join(path.dirname(normalized), 'partials')
+}
+
+/**
+ * Write the -X -> RPK_* env vars partial from a command tree's x_options.
+ * @param {Object} tree - Parsed rpk command tree
+ * @param {string} partialsDir - Directory the partial is written into
+ * @returns {{written: boolean, keyCount?: number, output?: string}}
+ */
+function writeEnvVarsPartial (tree, partialsDir) {
+  if (!Array.isArray(tree.x_options) || tree.x_options.length === 0) {
+    return { written: false }
+  }
+  const { renderPartial, keyToEnvVar } = require('./generate-x-env-partial.js')
+  const options = tree.x_options.map(o => ({ name: o.name, env: o.env || keyToEnvVar(o.name) }))
+  const output = path.join(partialsDir, 'rpk-env-vars.adoc')
+  fs.mkdirSync(path.dirname(output), { recursive: true })
+  fs.writeFileSync(output, renderPartial(options))
+  return { written: true, keyCount: options.length, output }
+}
+
 module.exports = {
   generateRpkDocs,
+  writeEnvVarsPartial,
+  derivePartialsDir,
   mergeCommandOverrides,
   applyOverridesToTree,
   resolveReferences,