@redpanda-data/docs-extensions-and-macros 5.13.5 → 5.17.0

package/bin/mcp-tools/lint-doc-strings.js

@@ -0,0 +1,75 @@
+/**
+ * MCP Tools - Lint embedded doc strings in engineering source
+ */
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+
+// The CLI ships in this same package, so invoke it directly: this tool is
+// designed to run inside ENGINEERING repos (redpanda, redpanda-operator,
+// connect), where the docs-repo detection behind getDocToolsCommand does
+// not apply.
+const DOC_TOOLS_BIN = path.resolve(__dirname, '..', 'doc-tools.js');
+
+/**
+ * Lint user-facing doc strings embedded in engineering source code
+ * @param {Object} args - Arguments
+ * @param {string} args.repo - Path to the engineering checkout (required)
+ * @param {string} [args.surface] - Comma-separated surfaces (properties, metrics, rpk, helm, crd, connect)
+ * @param {string} [args.diff] - Base ref for declaration-anchored diff mode
+ * @param {string} [args.skip_rules] - Comma-separated rule ids to skip
+ * @param {string} [args.only_rules] - Comma-separated rule ids to run exclusively
+ * @returns {Object} Lint results (findings + summary, JSON)
+ */
+function lintDocStrings(args = {}) {
+  if (!args.repo) {
+    return {
+      success: false,
+      error: 'repo is required',
+      suggestion: 'Pass the absolute path of the engineering checkout to lint (for example, a local redpanda clone)'
+    };
+  }
+
+  const cliArgs = [DOC_TOOLS_BIN, 'lint-strings', '--repo', args.repo, '--format', 'json'];
+  if (args.surface) cliArgs.push('--surface', args.surface);
+  if (args.diff) cliArgs.push('--diff', args.diff);
+  if (args.skip_rules) cliArgs.push('--skip-rules', args.skip_rules);
+  if (args.only_rules) cliArgs.push('--only-rules', args.only_rules);
+
+  try {
+    const result = spawnSync(process.execPath, cliArgs, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: MAX_EXEC_BUFFER_SIZE,
+      timeout: DEFAULT_COMMAND_TIMEOUT
+    });
+
+    if (result.error) {
+      throw new Error(`Failed to execute command: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+      throw new Error(result.stderr || `Command failed with exit code ${result.status}`);
+    }
+
+    const parsed = JSON.parse(result.stdout);
+    return {
+      success: true,
+      summary: parsed.summary,
+      findings: parsed.findings,
+      unsupported_surfaces: parsed.unsupported_surfaces || []
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      suggestion: 'Check that the repo path exists. The properties surface additionally needs python3 and network access on first run (venv + tree-sitter grammar); lint a specific --surface to skip it.'
+    };
+  }
+}
+
+module.exports = {
+  lintDocStrings
+};

package/bin/mcp-tools/overrides-audit.js

@@ -0,0 +1,100 @@
+/**
+ * MCP Tools - Overrides Audit
+ */
+
+const { spawnSync } = require('child_process');
+const { findRepoRoot, getDocToolsCommand, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+
+/**
+ * Audit docs-side override entries against extracted source strings
+ * @param {Object} args - Arguments
+ * @param {string} args.overrides - Path to the overrides JSON file (for example "docs-data/property-overrides.json")
+ * @param {string} [args.extracted] - Path to the extracted source JSON (property extractor raw output; required for the properties surface)
+ * @param {string} [args.repo] - Redpanda checkout to extract raw source strings from (alternative to args.extracted, properties surface only)
+ * @param {string} [args.surface] - Override surface: 'properties', 'rpk', or 'connect'
+ * @param {string} [args.output] - Also write the JSON result to this file (relative to repo root)
+ * @returns {Object} Audit results with manifest and per-class summary
+ */
+function auditOverrides(args = {}) {
+  const repoRoot = findRepoRoot();
+
+  if (!args.overrides) {
+    return {
+      success: false,
+      error: 'Missing required argument: overrides',
+      suggestion: 'Pass the path to the overrides JSON file (for example "docs-data/property-overrides.json")'
+    };
+  }
+
+  try {
+    // Get doc-tools command (handles both local and installed)
+    const docTools = getDocToolsCommand(repoRoot);
+
+    // Build command arguments array (JSON output so the result is parseable)
+    const baseArgs = ['overrides', 'audit', '--overrides', args.overrides, '--format', 'json'];
+
+    if (args.extracted) {
+      baseArgs.push('--extracted');
+      baseArgs.push(args.extracted);
+    }
+
+    if (args.repo) {
+      baseArgs.push('--repo');
+      baseArgs.push(args.repo);
+    }
+
+    if (args.surface) {
+      baseArgs.push('--surface');
+      baseArgs.push(args.surface);
+    }
+
+    if (args.output) {
+      baseArgs.push('--output');
+      baseArgs.push(args.output);
+    }
+
+    const result = spawnSync(docTools.program, docTools.getArgs(baseArgs), {
+      cwd: repoRoot.root,
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: MAX_EXEC_BUFFER_SIZE,
+      timeout: DEFAULT_COMMAND_TIMEOUT
+    });
+
+    // Check for spawn errors
+    if (result.error) {
+      throw new Error(`Failed to execute command: ${result.error.message}`);
+    }
+
+    // Check for non-zero exit codes
+    if (result.status !== 0) {
+      const errorMsg = result.stderr || `Command failed with exit code ${result.status}`;
+      throw new Error(errorMsg);
+    }
+
+    const audit = JSON.parse(result.stdout);
+
+    return {
+      success: true,
+      surface: audit.surface,
+      summary: audit.summary,
+      cross_check: audit.cross_check || null,
+      manifest: audit.manifest,
+      files_generated: args.output ? [args.output] : [],
+      summary_text: `Classified ${audit.summary.total} override field(s) on the ${audit.surface} surface`
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      exitCode: err.status,
+      suggestion: 'Check that the overrides file exists and that --extracted points to the property extractor\'s raw JSON output (without overrides applied)'
+    };
+  }
+}
+
+module.exports = {
+  auditOverrides
+};

package/bin/mcp-tools/preview-doc-string.js

@@ -0,0 +1,71 @@
+/**
+ * MCP Tools - Preview one embedded doc string as it will publish
+ */
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
+
+// The CLI ships in this same package, so invoke it directly: this tool is
+// designed to run inside ENGINEERING repos (redpanda, redpanda-operator,
+// connect), where the docs-repo detection behind getDocToolsCommand does
+// not apply.
+const DOC_TOOLS_BIN = path.resolve(__dirname, '..', 'doc-tools.js');
+
+/**
+ * Render one doc-string declaration to its published snippet
+ * @param {Object} args - Arguments
+ * @param {string} args.repo - Path to the engineering checkout (required)
+ * @param {string} args.surface - properties|rpk|metrics|helm|crd|connect (required)
+ * @param {string} args.name - Declaration name (required)
+ * @param {string} [args.overrides] - Overrides JSON path (properties only)
+ * @returns {Object} Preview text
+ */
+function previewDocString(args = {}) {
+  for (const required of ['repo', 'surface', 'name']) {
+    if (!args[required]) {
+      return {
+        success: false,
+        error: `${required} is required`,
+        suggestion: 'Pass repo (engineering checkout path), surface (properties|rpk|metrics|helm|crd|connect), and name (the declaration to preview)'
+      };
+    }
+  }
+
+  const cliArgs = [DOC_TOOLS_BIN, 'preview-string', '--repo', args.repo, '--surface', args.surface, '--name', args.name];
+  if (args.overrides) cliArgs.push('--overrides', args.overrides);
+
+  try {
+    const result = spawnSync(process.execPath, cliArgs, {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: MAX_EXEC_BUFFER_SIZE,
+      timeout: DEFAULT_COMMAND_TIMEOUT
+    });
+
+    if (result.error) {
+      throw new Error(`Failed to execute command: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+      throw new Error(result.stderr || `Command failed with exit code ${result.status}`);
+    }
+
+    return {
+      success: true,
+      preview: result.stdout,
+      masked_by_override: result.stdout.includes('MASKED-BY-OVERRIDE')
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: err.message,
+      stdout: err.stdout || '',
+      stderr: err.stderr || '',
+      suggestion: 'Check the repo path and declaration name. For rpk flags, prefix the name with -- (for example --format).'
+    };
+  }
+}
+
+module.exports = {
+  previewDocString
+};

package/cli-utils/diff-utils.js

@@ -287,6 +287,82 @@ function insertVersionIntoRawJson (raw, propName, newTag, indentUnit) {
   return raw.slice(0, objStart) + insertion + raw.slice(objStart)
 }
 
+/**
+ * Repair property-reference anchors in the published properties JSON.
+ *
+ * The generated .adoc partials get their anchors normalized in Phase 3, but the
+ * JSON attachment is written in Phase 2 and the docs UI reads THAT for its
+ * property tooltips. So the two disagreed: the partials linked
+ * `<<flush-bytes>>` while the attachment still said `<<flushbytes>>`, which
+ * resolves to nothing.
+ *
+ * Like updatePropertiesJsonWithVersion above, this is a TEXTUAL edit and not a
+ * parse/re-serialize round-trip. That matters more here than anywhere else in
+ * the pipeline: this file carries the uint64 and int64 limits as property
+ * maxima, and JSON.stringify rounds all three (18446744073709551615 becomes
+ * 18446744073709552000, which the server rejects). Two separate attempts to
+ * make a round-trip safe by writing a lossless JSON parser were both wrong -
+ * one corrupted escaped-JSON examples, the other could be forged by a string
+ * containing its own marker - and neither was necessary, because
+ * normalizePropertyAnchors only ever rewrites `<<anchor` tokens and those can
+ * only occur inside a JSON string value. Applying it to the raw text therefore
+ * cannot touch a number, a key or the structure.
+ *
+ * @param {string} jsonPath - Path to the properties attachment.
+ * @returns {number} Anchors rewritten.
+ */
+function repairPropertyAnchorsInJson (jsonPath) {
+  try {
+    if (!fs.existsSync(jsonPath)) {
+      console.warn(`Warning: Cannot repair anchors: ${jsonPath} does not exist`)
+      return 0
+    }
+    const raw = fs.readFileSync(jsonPath, 'utf8')
+    // Parsed only to learn the property names. The parsed object is never
+    // written back; the edit is applied to `raw`.
+    let properties
+    try {
+      const data = JSON.parse(raw)
+      properties = data.properties || data.topic_properties
+    } catch (err) {
+      console.warn(`Warning: Cannot repair anchors: ${jsonPath} is not valid JSON (${err.message})`)
+      return 0
+    }
+    if (!properties || typeof properties !== 'object') return 0
+
+    const normalizePropertyAnchors = require('../tools/property-extractor/helpers/normalizePropertyAnchors')
+    const { text, rewrites } = normalizePropertyAnchors(raw, properties)
+    if (!rewrites.length) return 0
+
+    // Belt and braces: the edit is meant to touch nothing but anchors, so prove
+    // it before overwriting published data. Masking every <<...>> in both
+    // versions must leave the two byte-identical.
+    const mask = (v) => v.replace(/<<[^<>]*>>/g, '\u0000')
+    if (mask(raw) !== mask(text)) {
+      console.error('Error: anchor repair changed something other than an anchor; not writing')
+      return 0
+    }
+    // And the result must still parse.
+    try {
+      JSON.parse(text)
+    } catch (err) {
+      console.error(`Error: anchor repair produced invalid JSON (${err.message}); not writing`)
+      return 0
+    }
+
+    fs.writeFileSync(jsonPath, text)
+    const shown = [...new Set(rewrites.map((r) => `${r.from} -> ${r.to}`))]
+    console.log(
+      `Repaired ${rewrites.length} property anchor(s) in ${path.basename(jsonPath)}: ` +
+      shown.slice(0, 8).join(', ') + (shown.length > 8 ? `, +${shown.length - 8} more` : '')
+    )
+    return rewrites.length
+  } catch (err) {
+    console.warn(`Warning: Failed to repair property anchors: ${err.message}`)
+    return 0
+  }
+}
+
 /**
  * Create a unified diff patch between two directories and clean them up.
  *
@@ -387,5 +463,6 @@ module.exports = {
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
   updatePropertiesJsonWithVersion,
+  repairPropertyAnchorsInJson,
   diffDirs
 }

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

@@ -44,6 +44,8 @@ const REAL_KEY_RE = /^(\s*)([A-Za-z0-9_."/-]+):(.*)$/
 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*(.*)$/
+// helm-docs' bare word annotations: `# @raw`, `# @ignored`.
+const AT_WORD_RE = /^\s*#\s*@(\w+)\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`, ...
@@ -51,14 +53,40 @@ 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.
+ * The one values.yaml comment walk in this repo. Two consumers share it:
+ *
+ * - `extractCommentedValueDocs` below, which the helm-spec generator uses to
+ *   inject rows for documented commented-out keys.
+ * - `tools/lint-strings/surfaces/helm.js`, which needs the same attachment
+ *   decisions plus line spans, real-key (helm-docs) attachments, and the
+ *   blocks that attach to NOTHING.
+ *
+ * The linter used to hold a byte-identical copy of every regex above and a
+ * near-copy of this walk, so that "the linter never calls a marker dead that
+ * the generator in this repo renders" - a promise nothing enforced. When the
+ * copies drifted, the linter emitted exactly the false dead-marker the
+ * comment promised to prevent and every test stayed green. There is now one
+ * walk, so they cannot disagree.
+ *
+ * Records are the union of what both consumers need. Line numbers are
+ * 0-indexed; descriptions are returned as the raw comment lines so each
+ * consumer can join them its own way (the generator preserves newlines, the
+ * linter flattens to one line).
  *
  * @param {string} yamlText - Raw contents of values.yaml.
- * @returns {Array<{path: string, description: string, default: string}>}
+ * @param {object} [options]
+ * @param {boolean} [options.attachRealKeys=false] - Model helm-docs' own
+ *   attachment: a `# --` block sitting DIRECTLY above an uncommented key
+ *   documents that key, and a top-level uncommented key with no block above
+ *   it is recorded as undocumented. The generator leaves this off because
+ *   helm-docs already renders those rows; only the linter judges them.
+ * @returns {Array<object>} records: { kind: 'key'|'dead-marker', path,
+ *   descLines, default, annotations, lineStart, lineEnd, commentedOut,
+ *   topLevel, undocumented }
  */
-function extractCommentedValueDocs (yamlText) {
+function parseValuesFile (yamlText, { attachRealKeys = false } = {}) {
   const lines = yamlText.split(/\r?\n/)
-  const entries = []
+  const records = []
   const stack = [] // enclosing real keys: { name, indent }
 
   // Accumulating comment block: { descLines, default, candidate }. The
@@ -69,36 +97,81 @@ function extractCommentedValueDocs (yamlText) {
   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
+  let looseIgnored = false // bare `# @ignored` with no `# --` block above a key
+
+  const record = (fields) => {
+    records.push({
+      kind: 'key',
+      path: null,
+      descLines: [],
+      default: '',
+      annotations: {},
+      lineStart: 0,
+      lineEnd: 0,
+      commentedOut: false,
+      topLevel: false,
+      undocumented: false,
+      ...fields,
+    })
+  }
 
   const flushAtDoc = () => {
     if (atDoc) {
-      entries.push({
+      record({
         path: atDoc.path,
-        description: atDoc.descLines.join('\n').trim(),
-        default: atDoc.default || '`nil`',
+        descLines: atDoc.descLines,
+        default: atDoc.default,
+        annotations: atDoc.annotations,
+        lineStart: atDoc.line,
+        lineEnd: atDoc.lastLine,
+        commentedOut: true,
+        topLevel: !atDoc.path.includes('.'),
       })
       atDoc = null
     }
   }
 
+  // A `# --` block that reached the end of its life with no key to attach to.
+  // The generator drops these; the linter reports them, because their
+  // description silently never ships.
+  const emitDead = (b) => {
+    record({
+      kind: 'dead-marker',
+      descLines: b.descLines,
+      default: b.default,
+      annotations: b.annotations,
+      lineStart: b.markerLine,
+      lineEnd: b.lastLine,
+    })
+  }
+
   // 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) {
+    if (!block) return
+    if (block.candidate) {
       const { name, effIndent } = block.candidate
       const parents = stack.filter((k) => k.indent < effIndent).map((k) => k.name)
-      entries.push({
+      record({
         path: [...parents, name].join('.'),
-        description: block.descLines.join('\n').trim(),
-        default: block.default || '`nil`',
+        descLines: block.descLines,
+        default: block.default,
+        annotations: block.annotations,
+        lineStart: block.markerLine,
+        lineEnd: block.lastLine,
+        commentedOut: true,
+        topLevel: parents.length === 0,
       })
       suppressInnerIndent = effIndent
+    } else {
+      emitDead(block)
     }
     block = null
   }
 
-  for (const line of lines) {
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
     // Skip the body of block scalars so their content is never mistaken for
     // keys or comments.
     if (skipScalarIndent >= 0) {
@@ -111,14 +184,21 @@ function extractCommentedValueDocs (yamlText) {
     if (atDocMatch) {
       flushAtDoc()
       flushBlock()
-      atDoc = { path: atDocMatch[1], descLines: [atDocMatch[2]], default: '' }
+      atDoc = { line: i, lastLine: i, path: atDocMatch[1], descLines: [atDocMatch[2]], default: '', annotations: {} }
       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()
+      if (atDoc) { atDoc.default = atDefault[1].trim(); atDoc.lastLine = i }
+      else if (block) { block.default = atDefault[1].trim(); block.lastLine = i }
+      continue
+    }
+
+    const atWord = line.match(AT_WORD_RE)
+    if (atWord) {
+      if (block) { block.annotations[atWord[1]] = true; block.lastLine = i }
+      else if (atWord[1] === 'ignored') looseIgnored = true
       continue
     }
 
@@ -137,8 +217,10 @@ function extractCommentedValueDocs (yamlText) {
       // 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.
+      // subtree, so nested example structures do not emit bogus paths. A
+      // marker in there is documentation neither pipeline ever renders.
       if (suppressInnerIndent >= 0 && effIndent > suppressInnerIndent) {
+        if (block) emitDead(block)
         block = null
         continue
       }
@@ -157,6 +239,7 @@ function extractCommentedValueDocs (yamlText) {
           // and deeper lines are nested example structures.
           block.candidate = { name: commentedKey[3], effIndent }
         }
+        block.lastLine = i
         continue
       }
     }
@@ -165,16 +248,18 @@ function extractCommentedValueDocs (yamlText) {
     if (descMarker) {
       flushAtDoc()
       flushBlock()
-      block = { descLines: [descMarker[1]], default: '', candidate: null }
+      block = { markerLine: i, lastLine: i, descLines: [descMarker[1]], default: '', annotations: {}, candidate: null }
       continue
     }
 
     const comment = line.match(COMMENT_RE)
     if (comment && line.trim().startsWith('#')) {
-      if (atDoc) atDoc.descLines.push(comment[1])
+      if (atDoc) { atDoc.descLines.push(comment[1]); atDoc.lastLine = i }
       // 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])
+      // exists, trailing comment lines belong to its example structure and
+      // only extend the span.
+      else if (block && !block.candidate) { block.descLines.push(comment[1]); block.lastLine = i }
+      else if (block) block.lastLine = i
       continue
     }
 
@@ -183,26 +268,76 @@ function extractCommentedValueDocs (yamlText) {
     // structure must not re-enable emission against a stale parent key, since
     // the real-key stack is not rebuilt by comment lines.
     flushAtDoc()
+
+    const realKey = line.match(REAL_KEY_RE)
+    if (attachRealKeys && realKey && block && !block.candidate && block.lastLine === i - 1) {
+      // helm-docs' own attachment: the block sits DIRECTLY above a real key.
+      const indent = realKey[1].length
+      while (stack.length > 0 && stack[stack.length - 1].indent >= indent) stack.pop()
+      const name = realKey[2].replace(/^"|"$/g, '')
+      const keyPath = [...stack.map((k) => k.name), name].join('.')
+      stack.push({ name, indent })
+      if (!block.annotations.ignored) {
+        record({
+          path: keyPath,
+          descLines: block.descLines,
+          default: block.default,
+          annotations: block.annotations,
+          lineStart: block.markerLine,
+          lineEnd: i,
+          topLevel: indent === 0,
+        })
+      }
+      block = null
+      suppressInnerIndent = -1
+      if (BLOCK_SCALAR_RE.test(realKey[3])) skipScalarIndent = indent
+      continue
+    }
+
     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 })
+      const name = realKey[2].replace(/^"|"$/g, '')
+      stack.push({ name, indent })
       if (BLOCK_SCALAR_RE.test(realKey[3])) skipScalarIndent = indent
+      if (attachRealKeys && indent === 0 && !looseIgnored) {
+        // Top-level user-visible key with no attached `# --` marker.
+        record({ path: name, lineStart: i, lineEnd: i, topLevel: true, undocumented: true })
+      }
     }
+    looseIgnored = false
   }
 
   flushAtDoc()
   flushBlock()
-  return entries
+  return records
+}
+
+/**
+ * Parse values.yaml text and return entries for documented commented-out keys.
+ *
+ * A filter over `parseValuesFile`: the commented-out keys it attaches, with
+ * their comment lines joined the way the AsciiDoc injector wants them.
+ *
+ * @param {string} yamlText - Raw contents of values.yaml.
+ * @returns {Array<{path: string, description: string, default: string}>}
+ */
+function extractCommentedValueDocs (yamlText) {
+  return parseValuesFile(yamlText)
+    .filter((r) => r.kind === 'key' && r.commentedOut)
+    .map((r) => ({
+      path: r.path,
+      description: r.descLines.join('\n').trim(),
+      default: r.default || '`nil`',
+    }))
 }
 
 /**
@@ -354,8 +489,22 @@ function injectIntoAsciiDoc (adoc, entries) {
 }
 
 module.exports = {
+  parseValuesFile,
   extractCommentedValueDocs,
   injectIntoAsciiDoc,
   filterEntriesBySchema,
   isPathAllowedBySchema,
+  // Exported so the lint surface cannot hold its own copy. Every one of these
+  // was duplicated character-for-character before.
+  PATTERNS: {
+    COMMENTED_KEY_RE,
+    REAL_KEY_RE,
+    DESC_MARKER_RE,
+    AT_DOC_RE,
+    AT_DEFAULT_RE,
+    AT_WORD_RE,
+    COMMENT_RE,
+    BLOCK_SCALAR_RE,
+    LIST_ITEM_RE,
+  },
 }