Add support for a --diff flag

Author: JakeSCahill

bin/doc-tools.js

@@ -3,6 +3,7 @@
 const { execSync, spawnSync } = require('child_process');
 const { Command } = require('commander');
 const path = require('path');
+const fs = require('fs');
 
 // --------------------------------------------------------------------
 // Dependency check functions
@@ -60,7 +61,7 @@ function checkPython() {
     }
   }
   if (!found) {
-    console.error('Error: Python 3.10 or higher is required but not found.\nPlease install Python and ensure `python3 --version` or `python --version` returns at least 3.10.');
+    console.error('Error: Python 3.10 or higher is required but not found.\nPlease install Python and ensure `python3 --version` or `python --version` returns at least 3.10: https://www.geeksforgeeks.org/how-to-install-python-on-mac/');
     process.exit(1);
   }
 }
@@ -69,7 +70,7 @@ function checkCompiler() {
   const gccInstalled = checkCommandExists('gcc');
   const clangInstalled = checkCommandExists('clang');
   if (!gccInstalled && !clangInstalled) {
-    console.error('Error: A C++ compiler (such as gcc or clang) is required but not found. Please install one.');
+    console.error('Error: A C++ compiler (such as gcc or clang) is required but not found. Please install one: https://osxdaily.com/2023/05/02/how-install-gcc-mac/');
     process.exit(1);
   }
 }
@@ -162,75 +163,136 @@ const commonOptions = {
   consoleDockerRepo: 'console'
 };
 
-// Subcommand: generate-metrics-docs.
+function runClusterDocs(mode, tag, options) {
+  const script = path.join(__dirname, '../cli-utils/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', shell: true });
+  if (r.status !== 0) process.exit(r.status);
+}
+
+// helper to diff two autogenerated directories
+function diffDirs(kind, oldTag, newTag) {
+  const oldDir  = path.join('autogenerated', oldTag, kind);
+  const newDir  = path.join('autogenerated', newTag, kind);
+  const diffDir = path.join('autogenerated', 'diffs', kind, `${oldTag}_to_${newTag}`);
+  const patch   = path.join(diffDir, 'changes.patch');
+
+  if (!fs.existsSync(oldDir)) {
+    console.error(`❌ Cannot diff: missing ${oldDir}`);
+    process.exit(1);
+  }
+  if (!fs.existsSync(newDir)) {
+    console.error(`❌ Cannot diff: missing ${newDir}`);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(diffDir, { recursive: true });
+
+  const cmd = `diff -ru "${oldDir}" "${newDir}" > "${patch}" || true`;
+  const res = spawnSync(cmd, { stdio: 'inherit', shell: true });
+
+  if (res.error) {
+    console.error(`❌ diff failed: ${res.error.message}`);
+    process.exit(1);
+  }
+  console.log(`✅ Wrote patch: ${patch}`);
+}
+
 automation
   .command('metrics-docs')
   .description('Extract Redpanda metrics and generate JSON/AsciiDoc docs')
   .option('--tag <tag>', 'Redpanda tag (default: latest)', commonOptions.tag)
-  .option('--docker-repo <repo>', 'Redpanda Docker repository (default: redpanda or redpanda-unstable when --tag is an RC version)', commonOptions.dockerRepo)
-  .option('--console-tag <tag>', 'Redpanda Console tag (default: latest)', commonOptions.consoleTag)
-  .option('--console-docker-repo <repo>', 'Redpanda Console Docker repository (default: console)', commonOptions.consoleDockerRepo)
+  .option('--docker-repo <repo>', '...', commonOptions.dockerRepo)
+  .option('--console-tag <tag>', '...', commonOptions.consoleTag)
+  .option('--console-docker-repo <repo>', '...', commonOptions.consoleDockerRepo)
+  .option('--diff <oldTag>', 'Also diff autogenerated metrics from <oldTag> → <tag>')
   .action((options) => {
-    // Verify dependencies common to these automations.
     verifyMetricsDependencies();
-    // Build argument array for the Bash automation script.
-    const args = [
-      'metrics',
-      options.tag,
-      options.dockerRepo,
-      options.consoleTag,
-      options.consoleDockerRepo
-    ];
-    const scriptPath = path.join(__dirname, '../cli-utils/generate-cluster-docs.sh');
-    console.log(`Running ${scriptPath} with arguments: ${args.join(' ')}`);
-    const result = spawnSync('bash', [scriptPath, ...args], { stdio: 'inherit', shell: true });
-    process.exit(result.status);
+
+    const newTag = options.tag;
+    const oldTag = options.diff;
+
+    if (oldTag) {
+      const oldDir = path.join('autogenerated', oldTag, 'metrics');
+      if (!fs.existsSync(oldDir)) {
+        console.log(`⏳ Generating metrics docs for old tag ${oldTag}…`);
+        runClusterDocs('metrics', oldTag, options);
+      }
+    }
+
+    console.log(`⏳ Generating metrics docs for new tag ${newTag}…`);
+    runClusterDocs('metrics', newTag, options);
+
+    if (oldTag) {
+      diffDirs('metrics', oldTag, newTag);
+    }
+
+    process.exit(0);
   });
 
-// Subcommand: generate-property-docs.
 automation
   .command('property-docs')
   .description('Extract properties from Redpanda source')
-  .option('--tag <tag>', 'Git tag or branch of Redpanda to extract from (default: dev)', 'dev')
+  .option('--tag <tag>', 'Git tag or branch to extract from (default: dev)', 'dev')
+  .option('--diff <oldTag>', 'Also diff autogenerated properties from <oldTag> → <tag>')
   .action((options) => {
     verifyPropertyDependencies();
-    const cwd = path.resolve(__dirname, '../tools/property-extractor');
-    const tag = options.tag || 'dev';
-    const result = spawnSync('make', ['build', `TAG=${tag}`], {
-      cwd,
-      stdio: 'inherit'
-    });
-    if (result.error) {
-      console.error('Failed to run `make build`:', result.error.message);
-      process.exit(1);
-    } else if (result.status !== 0) {
-      console.error(`make build exited with status code ${result.status}`);
-      process.exit(result.status);
+
+    const newTag = options.tag;
+    const oldTag = options.diff;
+    const cwd    = path.resolve(__dirname, '../tools/property-extractor');
+    const make   = (tag) => {
+      console.log(`⏳ Building property docs for ${tag}…`);
+      const r = spawnSync('make', ['build', `TAG=${tag}`], { cwd, stdio: 'inherit' });
+      if (r.error  ) { console.error(r.error); process.exit(1); }
+      if (r.status !== 0) process.exit(r.status);
+    };
+
+    if (oldTag) {
+      const oldDir = path.join('autogenerated', oldTag, 'properties');
+      if (!fs.existsSync(oldDir)) make(oldTag);
     }
-    process.exit(result.status);
-    });
 
-// Subcommand: generate-rpk-docs.
+    make(newTag);
+
+    if (oldTag) {
+      diffDirs('properties', oldTag, newTag);
+    }
+
+    process.exit(0);
+  });
+
 automation
   .command('rpk-docs')
   .description('Generate documentation for rpk commands')
   .option('--tag <tag>', 'Redpanda tag (default: latest)', commonOptions.tag)
-  .option('--docker-repo <repo>', 'Redpanda Docker repository (default: redpanda or redpanda-unstable when --tag is an RC version)', commonOptions.dockerRepo)
-  .option('--console-tag <tag>', 'Redpanda Console tag (default: latest)', commonOptions.consoleTag)
-  .option('--console-docker-repo <repo>', 'Redpanda Console Docker repository (default: console)', commonOptions.consoleDockerRepo)
+  .option('--docker-repo <repo>', '...', commonOptions.dockerRepo)
+  .option('--console-tag <tag>', '...', commonOptions.consoleTag)
+  .option('--console-docker-repo <repo>', '...', commonOptions.consoleDockerRepo)
+  .option('--diff <oldTag>', 'Also diff autogenerated rpk docs from <oldTag> → <tag>')
   .action((options) => {
     verifyMetricsDependencies();
-    const args = [
-      'rpk',
-      options.tag,
-      options.dockerRepo,
-      options.consoleTag,
-      options.consoleDockerRepo
-    ];
-    const scriptPath = path.join(__dirname, '../cli-utils/generate-cluster-docs.sh');
-    console.log(`Running ${scriptPath} with arguments: ${args.join(' ')}`);
-    const result = spawnSync('bash', [scriptPath, ...args], { stdio: 'inherit', shell: true });
-    process.exit(result.status);
+
+    const newTag = options.tag;
+    const oldTag = options.diff;
+
+    if (oldTag) {
+      const oldDir = path.join('autogenerated', oldTag, 'rpk');
+      if (!fs.existsSync(oldDir)) {
+        console.log(`⏳ Generating rpk docs for old tag ${oldTag}…`);
+        runClusterDocs('rpk', oldTag, options);
+      }
+    }
+
+    console.log(`⏳ Generating rpk docs for new tag ${newTag}…`);
+    runClusterDocs('rpk', newTag, options);
+
+    if (oldTag) {
+      diffDirs('rpk', oldTag, newTag);
+    }
+
+    process.exit(0);
   });
 
 programCli

cli-utils/generate-cluster-docs.sh

@@ -58,19 +58,19 @@ fi
 # Go back to where we were
 cd "$ORIGINAL_PWD"
 
-# Ensure Python venv (always create under cli-utilsvenv)
+# Ensure Python venv (always create under cli-utils/venv)
 "$SCRIPT_DIR"/python-venv.sh \
   "$SCRIPT_DIR"/venv \
   "$SCRIPT_DIR"/../tools/metrics/requirements.txt
 
 if [[ "$MODE" == "metrics" ]]; then
   "$SCRIPT_DIR"/venv/bin/python \
     "$SCRIPT_DIR"/../tools/metrics/metrics.py \
-    "$MAJOR_MINOR"
+    "$TAG"
 else
   "$SCRIPT_DIR"/venv/bin/python \
     "$SCRIPT_DIR"/../tools/gen-rpk-ascii.py \
-    "$MAJOR_MINOR"
+    "$TAG"
 fi
 
 echo "✅ Redpanda cluster docs generated successfully!"

cli-utils/start-cluster.sh

@@ -50,4 +50,4 @@ docker compose up -d
 
 # Return to original directory
 cd "$CALLER_PWD"
-echo "✅ Cluster is up (quickstart version: ${MAJOR_MINOR})"
+echo "✅ Cluster is up (version: ${TAG})"

tools/property-extractor/Makefile

@@ -22,7 +22,7 @@ REDPANDA_SRC  := $(TMP_ROOT)/redpanda
 TREESITTER_DIR:= $(TOOL_ROOT)/tree-sitter/tree-sitter-cpp
 VENV          := $(TOOL_ROOT)/tmp/redpanda-property-extractor-venv
 PYTHON        := $(VENV)/bin/python
-OUTPUT_DIR    := $(REPO_ROOT)/autogenerated/$(VERSION)/properties
+OUTPUT_DIR    := $(REPO_ROOT)/autogenerated/$(TAG)/properties
 TREE_SITTER   := npx tree-sitter
 
 # --- Main build: venv, fetch code, build parser, extract & docgen ---