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

package/cli-utils/diff-utils.js

@@ -0,0 +1,273 @@
+'use strict'
+
+const { spawnSync } = require('child_process')
+const path = require('path')
+const fs = require('fs')
+const { findRepoRoot } = require('./doc-tools-utils')
+
+/**
+ * Run the cluster documentation generator script for a specific release/tag.
+ *
+ * Invokes the external `generate-cluster-docs.sh` script with the provided mode, tag,
+ * and Docker-related options.
+ *
+ * @param {string} mode - Operation mode passed to the script (for example, "generate" or "clean").
+ * @param {string} tag - Release tag or version to generate docs for.
+ * @param {Object} options - Runtime options.
+ * @param {string} options.dockerRepo - Docker repository used by the script.
+ * @param {string} options.consoleTag - Console image tag passed to the script.
+ * @param {string} options.consoleDockerRepo - Console Docker repository used by the script.
+ */
+function runClusterDocs (mode, tag, options) {
+  const script = path.join(__dirname, 'generate-cluster-docs.sh')
+  const args = [mode, tag, options.dockerRepo, options.consoleTag, options.consoleDockerRepo]
+  console.log(`Running ${script} with arguments: ${args.join(' ')}`)
+  const r = spawnSync('bash', [script, ...args], { stdio: 'inherit' })
+  if (r.status !== 0) process.exit(r.status)
+}
+
+/**
+ * Cleanup old diff files, keeping only the 2 most recent.
+ *
+ * @param {string} diffDir - Directory containing diff files
+ */
+function cleanupOldDiffs (diffDir) {
+  try {
+    console.log('Cleaning up old diff JSON files (keeping only 2 most recent)…')
+
+    const absoluteDiffDir = path.resolve(diffDir)
+    if (!fs.existsSync(absoluteDiffDir)) {
+      return
+    }
+
+    // Get all diff files sorted by modification time (newest first)
+    const files = fs.readdirSync(absoluteDiffDir)
+      .filter(file => file.startsWith('redpanda-property-changes-') && file.endsWith('.json'))
+      .map(file => ({
+        name: file,
+        path: path.join(absoluteDiffDir, file),
+        time: fs.statSync(path.join(absoluteDiffDir, file)).mtime.getTime()
+      }))
+      .sort((a, b) => b.time - a.time)
+
+    // Delete all but the 2 most recent
+    if (files.length > 2) {
+      files.slice(2).forEach(file => {
+        console.log(`   Removing old file: ${file.name}`)
+        fs.unlinkSync(file.path)
+      })
+    }
+  } catch (error) {
+    console.error(`  Failed to cleanup old diff files: ${error.message}`)
+  }
+}
+
+/**
+ * Generate a detailed JSON report describing property changes between two releases.
+ *
+ * @param {string} oldTag - Release tag or identifier for the "old" properties set.
+ * @param {string} newTag - Release tag or identifier for the "new" properties set.
+ * @param {string} outputDir - Directory where the comparison report will be written.
+ */
+function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
+  try {
+    console.log('\nGenerating detailed property comparison report...')
+
+    // Look for the property JSON files in the standard location
+    const repoRoot = findRepoRoot()
+    const attachmentsDir = path.join(repoRoot, 'modules/reference/attachments')
+    const oldJsonPath = path.join(attachmentsDir, `redpanda-properties-${oldTag}.json`)
+    const newJsonPath = path.join(attachmentsDir, `redpanda-properties-${newTag}.json`)
+
+    if (!fs.existsSync(oldJsonPath)) {
+      console.log(`Warning: Old properties JSON not found at: ${oldJsonPath}`)
+      console.log('   Skipping detailed property comparison.')
+      return
+    }
+
+    if (!fs.existsSync(newJsonPath)) {
+      console.log(`Warning: New properties JSON not found at: ${newJsonPath}`)
+      console.log('   Skipping detailed property comparison.')
+      return
+    }
+
+    // Ensure output directory exists
+    const absoluteOutputDir = path.resolve(outputDir)
+    fs.mkdirSync(absoluteOutputDir, { recursive: true })
+
+    // Run the property comparison tool
+    const propertyExtractorDir = path.resolve(__dirname, '../tools/property-extractor')
+    const compareScript = path.join(propertyExtractorDir, 'compare-properties.js')
+    const reportFilename = `redpanda-property-changes-${oldTag}-to-${newTag}.json`
+    const reportPath = path.join(absoluteOutputDir, reportFilename)
+    const args = [compareScript, oldJsonPath, newJsonPath, oldTag, newTag, absoluteOutputDir, reportFilename]
+
+    const result = spawnSync('node', args, {
+      stdio: 'inherit',
+      cwd: propertyExtractorDir
+    })
+
+    if (result.error) {
+      console.error(`Error: Property comparison failed: ${result.error.message}`)
+    } else if (result.status !== 0) {
+      console.error(`Error: Property comparison exited with code: ${result.status}`)
+    } else {
+      console.log(`Done: Property comparison report saved to: ${reportPath}`)
+    }
+  } catch (error) {
+    console.error(`Error: Error generating property comparison: ${error.message}`)
+  }
+}
+
+/**
+ * Update property overrides file with version information for new properties
+ *
+ * @param {string} overridesPath - Path to property-overrides.json file
+ * @param {object} diffData - Diff data from property comparison
+ * @param {string} newTag - Version tag for new properties (e.g., "v25.3.3")
+ */
+function updatePropertyOverridesWithVersion (overridesPath, diffData, newTag) {
+  try {
+    console.log('\nUpdating property overrides with version information...')
+
+    // Load existing overrides
+    let overridesRoot = { properties: {} }
+    if (fs.existsSync(overridesPath)) {
+      const overridesContent = fs.readFileSync(overridesPath, 'utf8')
+      overridesRoot = JSON.parse(overridesContent)
+
+      if (!overridesRoot.properties) {
+        overridesRoot.properties = {}
+      }
+    }
+
+    const overrides = overridesRoot.properties
+    const newProperties = diffData.details?.newProperties || []
+
+    if (newProperties.length === 0) {
+      console.log('   No new properties to update')
+      return
+    }
+
+    let updatedCount = 0
+    let createdCount = 0
+
+    newProperties.forEach(prop => {
+      const propertyName = prop.name
+
+      if (overrides[propertyName]) {
+        if (overrides[propertyName].version !== newTag) {
+          overrides[propertyName].version = newTag
+          updatedCount++
+        }
+      } else {
+        overrides[propertyName] = { version: newTag }
+        createdCount++
+      }
+    })
+
+    // Save updated overrides (sorted)
+    const sortedOverrides = {}
+    Object.keys(overrides).sort().forEach(key => {
+      sortedOverrides[key] = overrides[key]
+    })
+
+    overridesRoot.properties = sortedOverrides
+    fs.writeFileSync(overridesPath, JSON.stringify(overridesRoot, null, 2) + '\n', 'utf8')
+
+    if (updatedCount > 0 || createdCount > 0) {
+      console.log('Done: Updated property overrides:')
+      if (createdCount > 0) {
+        console.log(`   • Created ${createdCount} new override ${createdCount === 1 ? 'entry' : 'entries'}`)
+      }
+      if (updatedCount > 0) {
+        console.log(`   • Updated ${updatedCount} existing override ${updatedCount === 1 ? 'entry' : 'entries'}`)
+      }
+
+      newProperties.forEach(prop => {
+        console.log(`   • ${prop.name} → ${newTag}`)
+      })
+    }
+  } catch (error) {
+    console.error(`Warning: Failed to update property overrides: ${error.message}`)
+  }
+}
+
+/**
+ * Create a unified diff patch between two directories and clean them up.
+ *
+ * @param {string} kind - Logical category for the diff (for example, "metrics" or "rpk")
+ * @param {string} oldTag - Identifier for the "old" version
+ * @param {string} newTag - Identifier for the "new" version
+ * @param {string} oldTempDir - Path to the directory containing the old output
+ * @param {string} newTempDir - Path to the directory containing the new output
+ */
+function diffDirs (kind, oldTag, newTag, oldTempDir, newTempDir) {
+  // Backwards compatibility: if temp directories not provided, use autogenerated paths
+  if (!oldTempDir) {
+    oldTempDir = path.join('autogenerated', oldTag, kind)
+  }
+  if (!newTempDir) {
+    newTempDir = path.join('autogenerated', newTag, kind)
+  }
+
+  const diffDir = path.join('tmp', 'diffs', kind, `${oldTag}_to_${newTag}`)
+
+  if (!fs.existsSync(oldTempDir)) {
+    console.error(`Error: Cannot diff: missing ${oldTempDir}`)
+    process.exit(1)
+  }
+  if (!fs.existsSync(newTempDir)) {
+    console.error(`Error: Cannot diff: missing ${newTempDir}`)
+    process.exit(1)
+  }
+
+  fs.mkdirSync(diffDir, { recursive: true })
+
+  // Generate traditional patch
+  const patch = path.join(diffDir, 'changes.patch')
+  const cmd = `diff -ru "${oldTempDir}" "${newTempDir}" > "${patch}" || true`
+  const res = spawnSync(cmd, { stdio: 'inherit', shell: true })
+
+  if (res.error) {
+    console.error(`Error: diff failed: ${res.error.message}`)
+    process.exit(1)
+  }
+  console.log(`Done: Wrote patch: ${patch}`)
+
+  // Safety guard: only clean up directories that are explicitly passed as temp directories
+  const tmpRoot = path.resolve('tmp') + path.sep
+  const workspaceRoot = path.resolve('.') + path.sep
+
+  // Only clean up if directories were explicitly provided as temp directories
+  const explicitTempDirs = arguments.length >= 5
+
+  if (explicitTempDirs) {
+    [oldTempDir, newTempDir].forEach(dirPath => {
+      const resolvedPath = path.resolve(dirPath) + path.sep
+      const isInTmp = resolvedPath.startsWith(tmpRoot)
+      const isInWorkspace = resolvedPath.startsWith(workspaceRoot)
+
+      if (isInWorkspace && isInTmp) {
+        try {
+          fs.rmSync(dirPath, { recursive: true, force: true })
+          console.log(`🧹 Cleaned up temporary directory: ${dirPath}`)
+        } catch (err) {
+          console.warn(`Warning: Could not clean up directory ${dirPath}: ${err.message}`)
+        }
+      } else {
+        console.log(`ℹ️  Skipping cleanup of directory outside tmp/: ${dirPath}`)
+      }
+    })
+  } else {
+    console.log('ℹ️  Using autogenerated directories - skipping cleanup for safety')
+  }
+}
+
+module.exports = {
+  runClusterDocs,
+  cleanupOldDiffs,
+  generatePropertyComparisonReport,
+  updatePropertyOverridesWithVersion,
+  diffDirs
+}

package/cli-utils/doc-tools-utils.js

@@ -0,0 +1,54 @@
+'use strict'
+
+const path = require('path')
+const fs = require('fs')
+
+/**
+ * Searches upward from a starting directory to locate the repository root.
+ *
+ * Traverses parent directories from the specified start path, returning the first
+ * directory containing either a `.git` folder or a `package.json` file.
+ * Exits the process with an error if no such directory is found.
+ *
+ * @param {string} [start] - The directory to begin the search from. Defaults to cwd.
+ * @returns {string} The absolute path to the repository root directory.
+ */
+function findRepoRoot (start = process.cwd()) {
+  let dir = start
+  while (dir !== path.parse(dir).root) {
+    if (
+      fs.existsSync(path.join(dir, '.git')) ||
+      fs.existsSync(path.join(dir, 'package.json'))
+    ) {
+      return dir
+    }
+    dir = path.dirname(dir)
+  }
+  console.error('Error: Could not find repo root (no .git or package.json in any parent)')
+  process.exit(1)
+}
+
+/**
+ * Prints an error message to stderr and exits the process with a non-zero status.
+ *
+ * @param {string} msg - The error message to display before exiting.
+ */
+function fail (msg) {
+  console.error(`Error: ${msg}`)
+  process.exit(1)
+}
+
+/**
+ * Common options for automation tasks
+ */
+const commonOptions = {
+  dockerRepo: 'redpanda',
+  consoleTag: 'latest',
+  consoleDockerRepo: 'console'
+}
+
+module.exports = {
+  findRepoRoot,
+  fail,
+  commonOptions
+}