@redpanda-data/docs-extensions-and-macros 4.13.1 → 4.13.2

package/bin/mcp-tools/property-docs.js

@@ -10,6 +10,8 @@ const { spawnSync } = require('child_process');
 const { findRepoRoot, getDocToolsCommand, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
 const { getAntoraStructure } = require('./antora');
 const { createJob } = require('./job-queue');
+const fs = require('fs');
+const path = require('path');
 
 /**
  * Generate Redpanda property documentation
@@ -59,6 +61,7 @@ function generatePropertyDocs(args) {
   const docTools = getDocToolsCommand(repoRoot);
 
   // Build command arguments
+  // Note: --cloud-support is enabled by default in the CLI, so we don't need to add it explicitly
   const baseArgs = ['generate', 'property-docs'];
 
   if (args.tag) {
@@ -73,6 +76,21 @@ function generatePropertyDocs(args) {
     baseArgs.push('--generate-partials');
   }
 
+  // Default to using property-overrides.json from docs-data if it exists
+  let overridesPath = args.overrides;
+  if (!overridesPath) {
+    // Try to find docs-data/property-overrides.json in current directory
+    const defaultOverrides = path.join(process.cwd(), 'docs-data', 'property-overrides.json');
+    if (fs.existsSync(defaultOverrides)) {
+      overridesPath = defaultOverrides;
+    }
+  }
+
+  if (overridesPath) {
+    baseArgs.push('--overrides');
+    baseArgs.push(overridesPath);
+  }
+
   // If background mode, create job and return immediately
   if (args.background) {
     const cmdArgs = [docTools.program, ...docTools.getArgs(baseArgs)];

package/bin/mcp-tools/rpcn-docs.js

@@ -12,6 +12,8 @@ const { execSync, spawnSync } = require('child_process');
 const { findRepoRoot, MAX_EXEC_BUFFER_SIZE, DEFAULT_COMMAND_TIMEOUT } = require('./utils');
 const { getAntoraStructure } = require('./antora');
 const cache = require('./cache');
+const fs = require('fs');
+const path = require('path');
 
 /**
  * Generate Redpanda Connect connector documentation
@@ -33,12 +35,16 @@ function generateRpConnectDocs(args = {}) {
   try {
     // Build command arguments array (no shell interpolation)
     const cmdArgs = ['doc-tools', 'generate', 'rpcn-connector-docs'];
-    
+
     // Add flags only when present, each as separate array entries
     if (args.fetch_connectors) cmdArgs.push('--fetch-connectors');
     if (args.draft_missing) cmdArgs.push('--draft-missing');
     if (args.update_whats_new) cmdArgs.push('--update-whats-new');
     if (args.include_bloblang) cmdArgs.push('--include-bloblang');
+    if (args.skip_cloud_detection) cmdArgs.push('--skip-cloud-detection');
+    if (args.skip_binary_analysis) cmdArgs.push('--skip-binary-analysis');
+    if (args.skip_cloud_analysis) cmdArgs.push('--skip-cloud-analysis');
+    if (args.skip_cgo_analysis) cmdArgs.push('--skip-cgo-analysis');
     if (args.data_dir) {
       cmdArgs.push('--data-dir');
       cmdArgs.push(args.data_dir);
@@ -51,9 +57,28 @@ function generateRpConnectDocs(args = {}) {
       cmdArgs.push('--csv');
       cmdArgs.push(args.csv);
     }
-    if (args.overrides) {
+
+    // Default to using overrides.json from docs-data if it exists
+    let overridesPath = args.overrides;
+    if (!overridesPath) {
+      // Try to find docs-data/overrides.json in current directory
+      const defaultOverrides = path.join(process.cwd(), 'docs-data', 'overrides.json');
+      if (fs.existsSync(defaultOverrides)) {
+        overridesPath = defaultOverrides;
+      }
+    }
+
+    if (overridesPath) {
       cmdArgs.push('--overrides');
-      cmdArgs.push(args.overrides);
+      cmdArgs.push(overridesPath);
+    }
+    if (args.cloud_version) {
+      cmdArgs.push('--cloud-version');
+      cmdArgs.push(args.cloud_version);
+    }
+    if (args.cgo_version) {
+      cmdArgs.push('--cgo-version');
+      cmdArgs.push(args.cgo_version);
     }
 
     const result = spawnSync('npx', cmdArgs, {

package/cli-utils/antora-utils.js

@@ -71,8 +71,8 @@ function getAntoraValue(keyPath) {
 
 /**
  * Safely sets a nested value in the Antora configuration, given a "dot path".
- * If the file or path does not exist, it will create intermediate objects as needed.
- * After setting the value, writes the updated YAML back to `antora.yml`.
+ * Uses surgical text replacement to preserve formatting, comments, and other content.
+ * Only works for asciidoc.attributes.* paths for now.
  *
  * @param {string} keyPath
  *   A dot-separated path to set (e.g. "asciidoc.attributes.latest-connect-version").
@@ -96,6 +96,57 @@ function setAntoraValue(keyPath, newValue) {
     return false;
   }
 
+  // For asciidoc.attributes.* paths, use surgical text replacement
+  if (keyPath.startsWith('asciidoc.attributes.')) {
+    const attributeName = keyPath.replace('asciidoc.attributes.', '');
+
+    try {
+      let fileContents = fs.readFileSync(antoraPath, 'utf8');
+
+      // Pattern to match the attribute line (handles various YAML formats)
+      // Matches: "  attribute-name: value" or "  attribute-name: 'value'" or "  attribute-name: \"value\""
+      const pattern = new RegExp(`^(\\s+${attributeName}:\\s*)(.*)$`, 'm');
+
+      // Format the new value (quote strings with special chars, leave numbers/booleans as-is)
+      let formattedValue = newValue;
+      if (typeof newValue === 'string') {
+        // Quote if it contains special characters or spaces
+        if (newValue.match(/[:\s#\[\]{},'"]|^[&*!|>@`]/) || newValue.startsWith('v')) {
+          formattedValue = `'${newValue}'`;
+        }
+      }
+
+      if (pattern.test(fileContents)) {
+        // Attribute exists - replace its value
+        fileContents = fileContents.replace(pattern, `$1${formattedValue}`);
+      } else {
+        // Attribute doesn't exist - add it in the attributes section
+        // Find the attributes: section and add it there
+        const attributesPattern = /^(\s+)attributes:\s*$/m;
+        const match = fileContents.match(attributesPattern);
+        if (match) {
+          const indent = match[1] + '  '; // Two more spaces for attribute items
+          const newLine = `${indent}${attributeName}: ${formattedValue}\n`;
+          // Insert after the "attributes:" line
+          const insertPos = match.index + match[0].length;
+          fileContents = fileContents.slice(0, insertPos) + '\n' + newLine + fileContents.slice(insertPos + 1);
+        } else {
+          console.error(`Could not find "attributes:" section in ${path.basename(antoraPath)}`);
+          return false;
+        }
+      }
+
+      fs.writeFileSync(antoraPath, fileContents, 'utf8');
+      return true;
+    } catch (err) {
+      console.error(`Error updating ${path.basename(antoraPath)}: ${err.message}`);
+      return false;
+    }
+  }
+
+  // For non-attribute paths, fall back to full YAML rewrite (legacy behavior)
+  console.warn(`Warning: ${keyPath} uses full YAML rewrite which may affect formatting`);
+
   let config;
   try {
     const fileContents = fs.readFileSync(antoraPath, 'utf8');

package/cli-utils/dependencies.js

@@ -0,0 +1,313 @@
+'use strict'
+
+const { execSync } = require('child_process')
+const { fail } = require('./doc-tools-utils')
+
+/**
+ * Ensures that a specified command-line tool is installed and operational.
+ *
+ * Attempts to execute the tool with a version flag to verify its presence. If the tool
+ * is missing or fails to run, the process exits with an error message and optional
+ * installation hint.
+ *
+ * @param {string} cmd - The name of the tool to check (for example, 'docker', 'helm-docs').
+ * @param {object} [opts] - Optional settings.
+ * @param {string} [opts.versionFlag='--version'] - The flag used to test the tool's execution.
+ * @param {string} [opts.help] - An optional hint or installation instruction shown on failure.
+ */
+function requireTool (cmd, { versionFlag = '--version', help = '' } = {}) {
+  try {
+    execSync(`${cmd} ${versionFlag}`, { stdio: 'ignore' })
+  } catch {
+    const hint = help ? `\n→ ${help}` : ''
+    fail(`'${cmd}' is required but not found.${hint}`)
+  }
+}
+
+/**
+ * Ensures that a command-line tool is installed by checking if it responds to a specified flag.
+ *
+ * @param {string} cmd - The name of the command-line tool to check.
+ * @param {string} [help] - Optional help text to display if the tool is not found.
+ * @param {string} [versionFlag='--version'] - The flag to use when checking if the tool is installed.
+ */
+function requireCmd (cmd, help, versionFlag = '--version') {
+  requireTool(cmd, { versionFlag, help })
+}
+
+/**
+ * Ensures that Python with a minimum required version is installed and available in the system PATH.
+ *
+ * Checks for either `python3` or `python` executables and verifies that the version is at least
+ * the specified minimum (default: 3.10). Exits the process with an error message if the
+ * requirement is not met.
+ *
+ * @param {number} [minMajor=3] - Minimum required major version of Python.
+ * @param {number} [minMinor=10] - Minimum required minor version of Python.
+ */
+function requirePython (minMajor = 3, minMinor = 10) {
+  const candidates = ['python3', 'python', 'python3.12', 'python3.11', 'python3.10']
+  for (const p of candidates) {
+    try {
+      const out = execSync(`${p} --version`, { encoding: 'utf8' }).trim()
+      const [maj, min] = out.split(' ')[1].split('.').map(Number)
+      if (maj > minMajor || (maj === minMajor && min >= minMinor)) {
+        return
+      }
+    } catch {
+      /* ignore & try next */
+    }
+  }
+  fail(
+    `Python ${minMajor}.${minMinor}+ not found or too old.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or install manually from your package manager or https://python.org`
+  )
+}
+
+/**
+ * Ensures that the Docker CLI is installed and the Docker daemon is running.
+ */
+function requireDockerDaemon () {
+  requireTool('docker', { help: 'https://docs.docker.com/get-docker/' })
+  try {
+    execSync('docker info', { stdio: 'ignore' })
+  } catch {
+    fail(`Docker daemon does not appear to be running.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or install and start Docker manually: https://docs.docker.com/get-docker/`)
+  }
+}
+
+/**
+ * Ensures that required dependencies for generating CRD documentation are installed.
+ */
+function verifyCrdDependencies () {
+  requireCmd('git', 'Install Git: https://git-scm.com/downloads')
+  requireCmd(
+    'crd-ref-docs',
+    `
+The 'crd-ref-docs' command is required but was not found.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or install manually (for macOS):
+
+1. Determine your architecture:
+   Run: \`uname -m\`
+
+2. Download and install:
+
+- For Apple Silicon (M1/M2/M3):
+  curl -fLO https://github.com/elastic/crd-ref-docs/releases/download/v0.1.0/crd-ref-docs_0.1.0_Darwin_arm64.tar.gz
+  tar -xzf crd-ref-docs_0.1.0_Darwin_arm64.tar.gz
+  chmod +x crd-ref-docs
+  sudo mv crd-ref-docs /usr/local/bin/
+
+- For Intel (x86_64):
+  curl -fLO https://github.com/elastic/crd-ref-docs/releases/download/v0.1.0/crd-ref-docs_0.1.0_Darwin_x86_64.tar.gz
+  tar -xzf crd-ref-docs_0.1.0_Darwin_x86_64.tar.gz
+  chmod +x crd-ref-docs
+  sudo mv crd-ref-docs /usr/local/bin/
+
+For more details, visit: https://github.com/elastic/crd-ref-docs
+    `.trim()
+  )
+  requireCmd(
+    'go',
+    `
+The 'go' command (Golang) is required but was not found.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or install manually on macOS:
+
+Option 1: Install via Homebrew (recommended):
+  brew install go
+
+Option 2: Download directly from the official site:
+  1. Visit: https://go.dev/dl/
+  2. Download the appropriate installer for macOS.
+  3. Run the installer and follow the instructions.
+
+After installation, verify it works:
+  go version
+
+For more details, see: https://go.dev/doc/install
+    `.trim(),
+    'version'
+  )
+}
+
+/**
+ * Ensures that all required tools for Helm documentation generation are installed.
+ */
+function verifyHelmDependencies () {
+  requireCmd(
+    'helm-docs',
+    `
+The 'helm-docs' command is required but was not found.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or install manually (for macOS):
+
+1. Determine your architecture:
+   Run: \`uname -m\`
+
+2. Download and install:
+
+- For Apple Silicon (M1/M2/M3):
+  curl -fLO https://github.com/norwoodj/helm-docs/releases/download/v1.11.0/helm-docs_1.11.0_Darwin_arm64.tar.gz
+  tar -xzf helm-docs_1.11.0_Darwin_arm64.tar.gz
+  chmod +x helm-docs
+  sudo mv helm-docs /usr/local/bin/
+
+- For Intel (x86_64):
+  curl -fLO https://github.com/norwoodj/helm-docs/releases/download/v1.11.0/helm-docs_1.11.0_Darwin_x86_64.tar.gz
+  tar -xzf helm-docs_1.11.0_Darwin_x86_64.tar.gz
+  chmod +x helm-docs
+  sudo mv helm-docs /usr/local/bin/
+
+Alternatively, if you use Homebrew:
+  brew install norwoodj/tap/helm-docs
+
+For more details, visit: https://github.com/norwoodj/helm-docs
+    `.trim()
+  )
+  requireCmd('pandoc', 'brew install pandoc or https://pandoc.org')
+  requireCmd('git', 'Install Git: https://git-scm.com/downloads')
+}
+
+/**
+ * Ensures all dependencies required for generating property documentation are installed.
+ */
+function verifyPropertyDependencies () {
+  requireCmd('make', 'Your OS package manager')
+  requirePython()
+
+  // Check for Node.js (required for Handlebars templates)
+  requireCmd('node', 'https://nodejs.org/en/download/ or use your package manager (for example, brew install node)')
+  requireCmd('npm', 'Usually installed with Node.js')
+
+  // Check for C++ compiler
+  let cppCompiler = null
+  try {
+    execSync('gcc --version', { stdio: 'ignore' })
+    cppCompiler = 'gcc'
+  } catch {
+    try {
+      execSync('clang --version', { stdio: 'ignore' })
+      cppCompiler = 'clang'
+    } catch {
+      fail(`A C++ compiler (gcc or clang) is required for tree-sitter compilation.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or install manually:
+
+On macOS, install Xcode Command Line Tools:
+  xcode-select --install
+
+On Linux (Ubuntu/Debian):
+  sudo apt update && sudo apt install build-essential
+
+On Linux (CentOS/RHEL/Fedora):
+  sudo yum groupinstall "Development Tools"
+  # or on newer versions:
+  sudo dnf groupinstall "Development Tools"
+
+After installation, verify with:
+  gcc --version
+  # or
+  clang --version`)
+    }
+  }
+
+  // Check for C++ standard library headers (critical for tree-sitter compilation)
+  const fs = require('fs')
+  const path = require('path')
+  const os = require('os')
+
+  let tempDir = null
+  let compileCmd = cppCompiler === 'gcc' ? 'gcc' : 'clang++'
+  try {
+    const testProgram = '#include <functional>\nint main() { return 0; }'
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cpp-test-'))
+    const tempFile = path.join(tempDir, 'test.cpp')
+    fs.writeFileSync(tempFile, testProgram)
+
+    execSync(`${compileCmd} -x c++ -fsyntax-only "${tempFile}"`, { stdio: 'ignore' })
+    fs.rmSync(tempDir, { recursive: true, force: true })
+  } catch {
+    if (tempDir) {
+      try {
+        fs.rmSync(tempDir, { recursive: true, force: true })
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+    fail(`C++ standard library headers are missing or incomplete.
+
+**Quick Install (Recommended):**
+Run the automated installer to set up all dependencies:
+  npm run install-test-dependencies
+
+Or fix manually:
+
+1. **Test if the issue exists**:
+   echo '#include <functional>' | ${compileCmd} -x c++ -fsyntax-only -
+
+2. **If the test fails, try these fixes in order**:
+   **Fix 1**: Reset developer path
+   sudo xcode-select --reset
+
+   **Fix 2**: Force reinstall Command Line Tools
+   sudo rm -rf /Library/Developer/CommandLineTools
+   xcode-select --install
+
+   Complete the GUI installation dialog that appears.
+
+3. **Verify the fix**:
+   echo '#include <functional>' | ${compileCmd} -x c++ -fsyntax-only -
+   If successful, you should see no output and the command should exit with code 0.
+`)
+  }
+}
+
+/**
+ * Ensures all required dependencies for generating Redpanda metrics documentation are installed.
+ */
+function verifyMetricsDependencies () {
+  requirePython()
+  requireCmd('curl')
+  requireCmd('tar')
+  requireDockerDaemon()
+}
+
+module.exports = {
+  requireTool,
+  requireCmd,
+  requirePython,
+  requireDockerDaemon,
+  verifyCrdDependencies,
+  verifyHelmDependencies,
+  verifyPropertyDependencies,
+  verifyMetricsDependencies
+}