@redpanda-data/docs-extensions-and-macros 4.12.5 → 4.13.0

package/tools/generate-cli-docs.js

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+
+/**
+ * Generate CLI Reference Documentation
+ *
+ * This script automatically generates AsciiDoc documentation for the doc-tools CLI
+ * by executing commands with --help and parsing the output, then enhancing it with
+ * JSDoc comments from the source code.
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Execute a CLI command and capture help output
+ */
+function getHelpOutput(command) {
+  try {
+    return execSync(`npx doc-tools ${command} --help`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+  } catch (error) {
+    // Commander exits with code 0 for help, but some shells treat it as error
+    return error.stdout || '';
+  }
+}
+
+/**
+ * Sanitize path values in option descriptions to remove user-specific absolute paths
+ */
+function sanitizePathInDescription(description) {
+  // Get the repository root path for relativization
+  const repoRoot = path.resolve(__dirname, '..');
+  
+  let sanitized = description;
+  
+  // First, handle repository root paths specifically
+  const repoRootEscaped = repoRoot.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const repoRootPattern = new RegExp(repoRootEscaped, 'g');
+  
+  sanitized = sanitized.replace(repoRootPattern, '<repository-root>');
+  
+  // Then handle any remaining long absolute paths that contain our repo structure
+  // This regex matches paths that look like they're part of our repository
+  const longPathPattern = /\/[^\/\s"')]*docs-extensions-and-macros[^\/\s"')]*(?:\/[^\/\s"')\]]+)*/g;
+  
+  sanitized = sanitized.replace(longPathPattern, (match) => {
+    // If this path wasn't already replaced and looks like a subpath, make it relative
+    if (!match.includes('<repository-root>')) {
+      const relativePath = path.relative(repoRoot, match);
+      if (relativePath && !relativePath.startsWith('..') && relativePath !== match) {
+        return `./${relativePath}`;
+      }
+      return '<repository-root>';
+    }
+    return match;
+  });
+  
+  // Finally, handle generic home directory patterns for any remaining absolute paths
+  const homePattern = /\/(?:Users|home)\/[^\/\s"')]+/g;
+  sanitized = sanitized.replace(homePattern, '~');
+  
+  return sanitized;
+}
+
+/**
+ * Parse command help output into structured data
+ */
+function parseHelp(helpText) {
+  const lines = helpText.split('\n');
+  const result = {
+    usage: '',
+    description: '',
+    options: [],
+    commands: []
+  };
+
+  let currentSection = null;
+  let currentItem = null;
+
+  for (const line of lines) {
+    // Usage line
+    if (line.startsWith('Usage:')) {
+      result.usage = line.replace('Usage:', '').trim();
+      currentSection = null;
+    }
+    // Options section
+    else if (line === 'Options:') {
+      currentSection = 'options';
+    }
+    // Commands section
+    else if (line === 'Commands:') {
+      currentSection = 'commands';
+    }
+    // Option or command line (starts with spaces and has content)
+    else if (line.match(/^  \S/) && currentSection) {
+      // Match option/command name (everything up to 2+ spaces) and description
+      const match = line.match(/^  (.+?)\s{2,}(.*)/);
+      if (match) {
+        currentItem = {
+          name: match[1].trim(),
+          description: match[2].trim()
+        };
+        result[currentSection].push(currentItem);
+      }
+    }
+    // Continuation of description (more indentation than option lines)
+    else if (line.match(/^\s{10,}/) && currentItem) {
+      currentItem.description += ' ' + line.trim();
+    }
+    // Description (first non-empty line that's not a section)
+    else if (line.trim() && !currentSection && !result.description && !line.startsWith('Usage:')) {
+      result.description = line.trim();
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse JSDoc comments from source file
+ */
+function parseJSDocComments(sourceFile) {
+  const content = fs.readFileSync(sourceFile, 'utf8');
+  const comments = {};
+
+  // Regex to match JSDoc comments followed by command definitions
+  // Matches both top-level commands and automation.command()
+  const pattern = /\/\*\*\s*([\s\S]*?)\s*\*\/\s*(?:programCli|automation)\s*\.command\(['"]([^'"]+)['"]\)/g;
+
+  let match;
+  while ((match = pattern.exec(content)) !== null) {
+    const [, commentText, commandName] = match;
+
+    // Parse the comment into sections
+    const parsed = {
+      description: '',
+      why: '',
+      example: '',
+      requirements: ''
+    };
+
+    // Extract sections
+    const descMatch = commentText.match(/@description\s*([\s\S]*?)(?=@\w+|$)/);
+    if (descMatch) {
+      parsed.description = descMatch[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s*/, '').trim())
+        .filter(line => line)
+        .join(' ');
+    }
+
+    const whyMatch = commentText.match(/@why\s*([\s\S]*?)(?=@\w+|$)/);
+    if (whyMatch) {
+      parsed.why = whyMatch[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s*/, '').trim())
+        .filter(line => line)
+        .join(' ');
+    }
+
+    const exampleMatch = commentText.match(/@example\s*([\s\S]*?)(?=@\w+|$)/);
+    if (exampleMatch) {
+      parsed.example = exampleMatch[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, ''))
+        .join('\n')
+        .trim();
+    }
+
+    const reqMatch = commentText.match(/@requirements\s*([\s\S]*?)(?=@\w+|$)/);
+    if (reqMatch) {
+      parsed.requirements = reqMatch[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, ''))
+        .join('\n')
+        .trim();
+    }
+
+    comments[commandName] = parsed;
+  }
+
+  return comments;
+}
+
+/**
+ * Generate AsciiDoc for a command
+ */
+function generateCommandDoc(commandName, helpData, jsdoc, level = 2) {
+  const heading = '='.repeat(level);
+  let doc = `${heading} ${commandName || 'doc-tools'}\n\n`;
+
+  // Add extended description from JSDoc if available
+  if (jsdoc && jsdoc.description) {
+    doc += `${jsdoc.description}\n\n`;
+  } else if (helpData.description) {
+    doc += `${helpData.description}\n\n`;
+  }
+
+  // Add "Why use it" section if available
+  if (jsdoc && jsdoc.why) {
+    doc += `*Why use it:*\n\n${jsdoc.why}\n\n`;
+  }
+
+  if (helpData.usage) {
+    doc += `*Usage:*\n\n`;
+    doc += `[,bash]\n----\n${helpData.usage}\n----\n\n`;
+  }
+
+  if (helpData.options.length > 0) {
+    doc += `*Options:*\n\n`;
+    helpData.options.forEach(opt => {
+      const name = opt.name.replace(/\s+/g, ' ');
+      const sanitizedDescription = sanitizePathInDescription(opt.description);
+      doc += `\`${name}\`::\n${sanitizedDescription}\n\n`;
+    });
+  }
+
+  if (helpData.commands.length > 0) {
+    doc += `*Commands:*\n\n`;
+    helpData.commands.forEach(cmd => {
+      const cmdName = cmd.name.split(' ')[0];
+      doc += `* \`${cmdName}\` - ${cmd.description}\n`;
+    });
+    doc += `\n`;
+  }
+
+  // Add examples from JSDoc if available
+  if (jsdoc && jsdoc.example) {
+    doc += `*Examples:*\n\n[,bash]\n----\n${jsdoc.example}\n----\n\n`;
+  }
+
+  // Add requirements from JSDoc if available
+  if (jsdoc && jsdoc.requirements) {
+    doc += `*Requirements:*\n\n${jsdoc.requirements}\n\n`;
+  }
+
+  return doc;
+}
+
+/**
+ * Main generation function
+ */
+function generateDocs() {
+  console.log('Generating CLI documentation...');
+
+  // Parse JSDoc comments from source
+  const sourceFile = path.join(__dirname, '..', 'bin', 'doc-tools.js');
+  console.log('  Parsing JSDoc comments from source...');
+  const jsdocs = parseJSDocComments(sourceFile);
+  console.log(`  Found ${Object.keys(jsdocs).length} documented commands`);
+
+  let doc = `= Doc Tools CLI Reference
+:toc:
+:toclevels: 3
+
+Auto-generated reference documentation for the \`doc-tools\` command-line interface.
+
+IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm run generate:cli-docs\` to regenerate.
+
+`;
+
+  // Get main help
+  const mainHelp = getHelpOutput('');
+  const mainData = parseHelp(mainHelp);
+  doc += generateCommandDoc('', mainData, null, 2);
+
+  // Top-level commands (excluding 'generate' which has subcommands)
+  const topLevelCommands = [
+    'install-test-dependencies',
+    'get-redpanda-version',
+    'get-console-version',
+    'link-readme',
+    'fetch',
+    'setup-mcp'
+  ];
+
+  topLevelCommands.forEach(cmd => {
+    console.log(`  Generating docs for: ${cmd}`);
+    const help = getHelpOutput(cmd);
+    const data = parseHelp(help);
+    const jsdoc = jsdocs[cmd];
+    doc += generateCommandDoc(cmd, data, jsdoc, 2);
+  });
+
+  // Generate command and its subcommands
+  console.log('  Generating docs for: generate');
+  const generateHelp = getHelpOutput('generate');
+  const generateData = parseHelp(generateHelp);
+  doc += generateCommandDoc('generate', generateData, null, 2);
+
+  // Generate subcommands
+  const generateSubcommands = [
+    'property-docs',
+    'metrics-docs',
+    'rpk-docs',
+    'rpcn-connector-docs',
+    'helm-spec',
+    'cloud-regions',
+    'crd-spec',
+    'bundle-openapi'
+  ];
+
+  generateSubcommands.forEach(subcmd => {
+    console.log(`    Generating docs for: generate ${subcmd}`);
+    const help = getHelpOutput(`generate ${subcmd}`);
+    const data = parseHelp(help);
+    const jsdoc = jsdocs[subcmd];
+    doc += generateCommandDoc(`generate ${subcmd}`, data, jsdoc, 3);
+  });
+
+  // Write to file
+  const outputPath = path.join(__dirname, '..', 'CLI_REFERENCE.adoc');
+  fs.writeFileSync(outputPath, doc);
+  console.log(`✓ Generated: ${outputPath}`);
+}
+
+// Run if executed directly
+if (require.main === module) {
+  generateDocs();
+}
+
+module.exports = { generateDocs };

package/tools/get-console-version.js

@@ -24,9 +24,11 @@ module.exports = async function getConsoleVersion({ beta = false, fromAntora = f
   }
 
   // Initialize GitHub client
+  const { getGitHubToken } = require('../cli-utils/github-token');
   const { Octokit } = await import('@octokit/rest');
-  const octokit = process.env.REDPANDA_GITHUB_TOKEN
-    ? new Octokit({ auth: process.env.REDPANDA_GITHUB_TOKEN })
+  const token = getGitHubToken();
+  const octokit = token
+    ? new Octokit({ auth: token })
     : new Octokit();
 
   // Fetch latest release info

package/tools/get-redpanda-version.js

@@ -20,9 +20,11 @@ module.exports = async function getRedpandaVersion({ beta = false, fromAntora =
   }
 
   // Load Octokit
+  const { getGitHubToken } = require('../cli-utils/github-token');
   const { Octokit } = await import('@octokit/rest');
-  const octokit = process.env.REDPANDA_GITHUB_TOKEN
-    ? new Octokit({ auth: process.env.REDPANDA_GITHUB_TOKEN })
+  const token = getGitHubToken();
+  const octokit = token
+    ? new Octokit({ auth: token })
     : new Octokit();
 
   // Fetch version data

package/tools/metrics/metrics.py

@@ -155,14 +155,15 @@ if __name__ == "__main__":
 
     tag_modified = sys.argv[1].strip()
 
-    # Resolve the base autogenerated folder at the repo root
+    # Resolve the repo root
     repo_root = os.getcwd()
-    gen_path = os.path.join(repo_root, "autogenerated")
-    if not os.path.isdir(gen_path):
-        logging.error(f"autogenerated folder not found at: {gen_path}")
-        sys.exit(1)
 
-    # Build the output directory using the already provided tag_modified.
+    # Build the output directory in modules/reference/pages for docs build
+    reference_pages_dir = os.path.join(repo_root, "modules", "reference", "pages")
+    ensure_directory_exists(reference_pages_dir)
+
+    # Also create versioned output in autogenerated for diffing
+    gen_path = os.path.join(repo_root, "autogenerated")
     output_dir = os.path.join(gen_path, tag_modified, "metrics")
     ensure_directory_exists(output_dir)
 
@@ -189,11 +190,22 @@ if __name__ == "__main__":
         "internal": internal_metrics
     }
 
-    # Define output file paths.
+    # Define output file paths in modules/reference/pages (primary location for docs build)
+    PUBLIC_METRICS_REFERENCE = os.path.join(reference_pages_dir, "public-metrics-reference.adoc")
+    INTERNAL_METRICS_REFERENCE = os.path.join(reference_pages_dir, "internal-metrics-reference.adoc")
+
+    # Also save versioned copies in autogenerated for diffing
     JSON_OUTPUT_FILE = os.path.join(output_dir, "metrics.json")
     ASCIIDOC_OUTPUT_FILE = os.path.join(output_dir, "metrics.adoc")
     INTERNAL_ASCIIDOC_OUTPUT_FILE = os.path.join(output_dir, "internal-metrics.adoc")
 
+    # Write to modules/reference/pages (primary location)
+    output_asciidoc(public_metrics, PUBLIC_METRICS_REFERENCE)
+    output_asciidoc(internal_metrics, INTERNAL_METRICS_REFERENCE)
+
+    # Write to autogenerated for versioning and diffing
     output_json(merged_metrics, JSON_OUTPUT_FILE)
     output_asciidoc(public_metrics, ASCIIDOC_OUTPUT_FILE)
     output_asciidoc(internal_metrics, INTERNAL_ASCIIDOC_OUTPUT_FILE)
+
+    logging.info(f"✅ Generated {len(public_metrics)} public metrics and {len(internal_metrics)} internal metrics")

package/tools/property-extractor/Makefile

@@ -78,7 +78,13 @@ redpanda-git:
 	@if [ -d "$(REDPANDA_SRC)" ]; then \
 	  git -C "$(REDPANDA_SRC)" fetch --all --tags -q; \
 	else \
-	  git clone -q https://github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
+	  GH_TOKEN=$${REDPANDA_GITHUB_TOKEN:-$${GITHUB_TOKEN:-$${GH_TOKEN}}}; \
+	  if [ -n "$$GH_TOKEN" ]; then \
+	    echo "🔑 Using authenticated clone (token provided)"; \
+	    git clone -q https://$$GH_TOKEN@github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
+	  else \
+	    git clone -q https://github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
+	  fi; \
 	fi; \
 	if git -C "$(REDPANDA_SRC)" rev-parse --verify -q "$(TAG)" >/dev/null; then \
 	  echo "🔖 Checking out '$(TAG)'"; \

package/tools/property-extractor/cloud_config.py

@@ -117,7 +117,7 @@ def fetch_cloud_config(github_token: Optional[str] = None) -> CloudConfig:
         GitHubAuthError: Authentication or access problems with the GitHub API (including 401/403 responses).
         NetworkError: Network connectivity or timeout failures when contacting the GitHub API.
         CloudConfigParsingError: Failure to parse or validate the repository YAML files or their expected structure.
-        CloudConfigError: Generic configuration error (e.g., missing token) or unexpected internal failures.
+        CloudConfigError: Generic configuration error (for example, missing token) or unexpected internal failures.
     """
     if not github_token:
         github_token = os.environ.get('GITHUB_TOKEN') or os.environ.get('REDPANDA_GITHUB_TOKEN')
@@ -246,10 +246,10 @@ def fetch_cloud_config(github_token: Optional[str] = None) -> CloudConfig:
                 logger.warning(f"Skipping file with missing name/url: {file}")
                 continue
             
-            # Look for version YAML files (e.g., "25.1.yml", "25.2.yml")
+            # Look for version YAML files (for example, "25.1.yml", "25.2.yml")
             if file_name.endswith('.yml'):
                 version_part = file_name.replace('.yml', '')
-                # Check if it looks like a version number (e.g., "25.1", "25.2.1")
+                # Check if it looks like a version number (for example, "25.1", "25.2.1")
                 if version_part.replace('.', '').isdigit():
                     version_files.append((version_part, download_url))
                     logger.debug(f"Found version file: {file_name} -> {version_part}")
@@ -282,7 +282,7 @@ def fetch_cloud_config(github_token: Optional[str] = None) -> CloudConfig:
                 "No valid version files found in cloudv2/install-pack directory.\n"
                 f"Found {len(version_files)} files but none had valid version formats.\n"
                 f"Available files: {[v[0] for v in version_files]}\n"
-                "Expected version format: 'X.Y' or 'X.Y.Z' (e.g., '25.1', '25.2.1')\n"
+                "Expected version format: 'X.Y' or 'X.Y.Z' (for example, '25.1', '25.2.1')\n"
                 "Contact cloud team to verify configuration file naming convention."
             )
             logger.error(error_msg)

package/tools/property-extractor/constant_resolver.py

@@ -2,7 +2,7 @@
 """
 Resolves C++ constant references to their actual values.
 
-For properties that use constants as default values (e.g., `ss::sstring{net::tls_v1_2_cipher_suites}`),
+For properties that use constants as default values (for example, `ss::sstring{net::tls_v1_2_cipher_suites}`),
 this module looks up the constant definition and extracts the actual string value.
 """
 
@@ -30,7 +30,7 @@ class ConstantResolver:
         Resolve a C++ constant name to its actual string value.
 
         Args:
-            constant_name: The constant name (e.g., "net::tls_v1_2_cipher_suites" or "tls_v1_2_cipher_suites")
+            constant_name: The constant name (for example, "net::tls_v1_2_cipher_suites" or "tls_v1_2_cipher_suites")
 
         Returns:
             The actual string value, or None if not found
@@ -72,8 +72,8 @@ class ConstantResolver:
         Search for a constant definition in files matching the given patterns.
 
         Args:
-            patterns: List of file patterns to search (e.g., ['net/tls.cc'])
-            identifier: The constant identifier (e.g., 'tls_v1_2_cipher_suites')
+            patterns: List of file patterns to search (for example, ['net/tls.cc'])
+            identifier: The constant identifier (for example, 'tls_v1_2_cipher_suites')
 
         Returns:
             The constant's string value, or None if not found
@@ -111,7 +111,7 @@ class ConstantResolver:
         - constexpr std::array<std::string_view, N> array_name = {val1, val2, val3};
 
         Args:
-            array_name: The array constant name (e.g., "supported_sasl_mechanisms")
+            array_name: The array constant name (for example, "supported_sasl_mechanisms")
 
         Returns:
             List of string values from the array, or None if not found
@@ -230,7 +230,7 @@ class ConstantResolver:
         Finds the class definition and extracts the `static constexpr const char* name` value.
 
         Args:
-            class_ref: Qualified class name (e.g., "security::scram_sha256_authenticator")
+            class_ref: Qualified class name (for example, "security::scram_sha256_authenticator")
 
         Returns:
             Dict with 'value' and 'is_enterprise' keys, or None if not found
@@ -420,12 +420,12 @@ def resolve_validator_enum_constraint(validator_name: str, resolver: ConstantRes
 
     For validators like validate_sasl_mechanisms, this function:
     1. Finds the validator function in validators.cc
-    2. Parses it to find what constant array it validates against (e.g., supported_sasl_mechanisms)
+    2. Parses it to find what constant array it validates against (for example, supported_sasl_mechanisms)
     3. Resolves that array to get the actual enum values
-    4. Checks for enterprise values (e.g., enterprise_sasl_mechanisms)
+    4. Checks for enterprise values (for example, enterprise_sasl_mechanisms)
 
     Args:
-        validator_name: Name of the validator function (e.g., "validate_sasl_mechanisms")
+        validator_name: Name of the validator function (for example, "validate_sasl_mechanisms")
         resolver: ConstantResolver instance
 
     Returns:
@@ -521,8 +521,8 @@ def resolve_runtime_validation_enum_constraint(property_name: str, defined_in: s
         }
 
     Args:
-        property_name: Name of the property (e.g., "sasl_mechanism")
-        defined_in: Path where property is defined (e.g., "src/v/kafka/client/configuration.cc")
+        property_name: Name of the property (for example, "sasl_mechanism")
+        defined_in: Path where property is defined (for example, "src/v/kafka/client/configuration.cc")
         resolver: ConstantResolver instance
 
     Returns:

package/tools/property-extractor/property_extractor.py

@@ -233,7 +233,7 @@ class ConstexprCache:
             position (int): Position in the file
 
         Returns:
-            str: Namespace (e.g., "model" or "config::tls")
+            str: Namespace (for example, "model" or "config::tls")
         """
         # Look backwards from position to find namespace declaration
         preceding = content[:position]
@@ -403,7 +403,7 @@ def process_enterprise_value(enterprise_str):
     2. C++ scoped enum-like tokens (foo::bar::BAZ) → "BAZ".
     3. Lambda expressions (strings starting with "[](" and ending with "}") → a short
        human-readable hint such as "Enterprise feature enabled" or context-specific text.
-    4. Simple literal values (e.g., "true", "false", "OIDC", or quoted strings) → returned as-is.
+    4. Simple literal values (for example, "true", "false", "OIDC", or quoted strings) → returned as-is.
     
     Parameters:
         enterprise_str (str): Raw C++ expression text to be converted.
@@ -496,7 +496,7 @@ def resolve_cpp_function_call(function_name):
     functions from source using general patterns. No hardcoded patterns needed.
 
     Parameters:
-        function_name (str): Fully-qualified C++ function name to resolve (e.g., "model::kafka_audit_logging_topic")
+        function_name (str): Fully-qualified C++ function name to resolve (for example, "model::kafka_audit_logging_topic")
 
     Returns:
         str or None: The literal string returned by the C++ function, or None if not found in cache
@@ -509,7 +509,7 @@ def resolve_cpp_function_call(function_name):
         logger.debug(f"Resolved function '{function_name}' -> '{cached_result}' from cache")
         return cached_result
 
-    # Also try without namespace qualifier (e.g., "kafka_audit_logging_topic")
+    # Also try without namespace qualifier (for example, "kafka_audit_logging_topic")
     if '::' in function_name:
         simple_name = function_name.split('::')[-1]
         cached_result = _constexpr_cache.lookup_function(simple_name)
@@ -529,7 +529,7 @@ def resolve_constexpr_identifier(identifier):
     Searches common Redpanda source locations for constexpr string or string_view definitions matching the given identifier and returns the literal if found.
 
     Parameters:
-        identifier (str): The identifier name to resolve (e.g., "scram" or "net::tls_v1_2_cipher_suites").
+        identifier (str): The identifier name to resolve (for example, "scram" or "net::tls_v1_2_cipher_suites").
 
     Returns:
         str or None: The resolved literal string value if found, otherwise `None`.
@@ -546,7 +546,7 @@ def resolve_constexpr_identifier(identifier):
         logger.debug(f"Could not find Redpanda source directory to resolve identifier: {identifier}")
         return None
 
-    # Strip namespace qualifier if present (e.g., "net::tls_v1_2_cipher_suites" -> "tls_v1_2_cipher_suites")
+    # Strip namespace qualifier if present (for example, "net::tls_v1_2_cipher_suites" -> "tls_v1_2_cipher_suites")
     search_identifier = identifier.split('::')[-1] if '::' in identifier else identifier
     
     # Pattern to match constexpr string_view definitions
@@ -1567,7 +1567,7 @@ def resolve_type_and_default(properties, definitions):
     └─────────────────────────────────────────────────────────────────────────
 
     HOW TO ADD NEW TYPE DEFINITIONS:
-    1. Identify the C++ type that needs a definition (e.g., new_endpoint_type)
+    1. Identify the C++ type that needs a definition (for example, new_endpoint_type)
     2. Analyze the C++ struct/class to determine JSON schema structure
     3. Add entry to definitions.json with appropriate JSON Schema:
        {
@@ -1662,10 +1662,10 @@ def resolve_type_and_default(properties, definitions):
 
         This function recognises common C++ patterns produced by the extractor and maps them to values suitable for JSON schema defaults and examples. Handled cases include:
         - std::nullopt -> null
-        - zero-argument functions (e.g., model::kafka_audit_logging_topic()) resolved from source when possible
-        - enum tokens (e.g., fips_mode_flag::disabled -> "disabled")
+        - zero-argument functions (for example, model::kafka_audit_logging_topic()) resolved from source when possible
+        - enum tokens (for example, fips_mode_flag::disabled -> "disabled")
         - constexpr identifiers and simple string constructors resolved to their literal strings when available
-        - known default constructors and truncated type names mapped to sensible defaults (e.g., duration -> 0, path -> "")
+        - known default constructors and truncated type names mapped to sensible defaults (for example, duration -> 0, path -> "")
         - simple heuristics for unknown constructors and concatenated expressions
 
         Returns:
@@ -1722,7 +1722,7 @@ def resolve_type_and_default(properties, definitions):
                     base = base + "s"
                 return f'"{num} {base}"'
 
-            # Evaluate arithmetic in duration constructors (e.g., "60 * 5" -> "300 seconds")
+            # Evaluate arithmetic in duration constructors (for example, "60 * 5" -> "300 seconds")
             if "*" in value:
                 try:
                     result = safe_arithmetic_eval(value)
@@ -1854,12 +1854,12 @@ def resolve_type_and_default(properties, definitions):
         - Integer and boolean literals → Python int and bool.
         - Object constructors (Type(arg1, arg2) or Type{...}) → dict mapping constructor arguments to the object's properties when a corresponding type definition exists.
         - Nested constructors → nested dicts with their fields expanded.
-        - Array initializer lists (e.g., {Type(...), Type(...)}) → Python list with each element expanded.
+        - Array initializer lists (for example, {Type(...), Type(...)}) → Python list with each element expanded.
         - Special-case mappings for known type patterns (for example, an address-type constructor expanded into {"address", "port"} when the target type expects that shape).
         If a default cannot be resolved or the type is an enum, the original input is returned unchanged; the string "null" is converted to None. If default_str is not a string, it is returned as-is.
         
         Parameters:
-            type_name (str): The resolved type name for the default value (e.g., "model::broker_endpoint" or a primitive type like "string").
+            type_name (str): The resolved type name for the default value (for example, "model::broker_endpoint" or a primitive type like "string").
             default_str (str | any): The C++ default expression to expand, or a non-string value already decoded.
         
         Returns:
@@ -1881,7 +1881,7 @@ def resolve_type_and_default(properties, definitions):
                 else:
                     return processed
         
-        # Handle string type with constructor syntax (e.g., ss::sstring{scram})
+        # Handle string type with constructor syntax (for example, ss::sstring{scram})
         if type_name == "string" and ("{" in default_str or "(" in default_str):
             tname, args = parse_constructor(default_str)
             if tname and args:
@@ -1897,7 +1897,7 @@ def resolve_type_and_default(properties, definitions):
         type_def = resolve_definition_type(resolve_type_with_namespace(type_name, definitions))
         if "enum" in type_def:
             # Strip C++ namespace qualifiers from enum values
-            # e.g., model::partition_autobalancing_mode::continuous → continuous
+            # for example, model::partition_autobalancing_mode::continuous → continuous
             if isinstance(default_str, str) and '::' in default_str:
                 return default_str.split('::')[-1]
             return default_str
@@ -2775,7 +2775,7 @@ def main():
 
     # Load overrides file (contains both property and definition overrides)
     overrides = None
-    if options.overrides:
+    if options.overrides and os.path.exists(options.overrides):
         try:
             with open(options.overrides) as f:
                 overrides = json.load(f)
@@ -2790,6 +2790,8 @@ def main():
         except Exception as e:
             logging.error(f"Failed to load overrides file: {e}")
             sys.exit(1)
+    elif options.overrides:
+        logger.info(f"Overrides file not found: {options.overrides} (skipping)")
 
     # DEPRECATED: Support legacy --definitions flag for backward compatibility
     # Users should migrate to putting definitions in overrides.json under "definitions" key

package/tools/property-extractor/topic_property_extractor.py

@@ -444,8 +444,8 @@ class TopicPropertyExtractor:
         if not re.match(r'^[a-zA-Z][a-zA-Z0-9._-]*$', prop_name):
             return False
 
-        # Reject Java-style package names (e.g., "redpanda.core.admin.Service")
-        # Topic properties use lowercase with dots (e.g., "cleanup.policy", "segment.ms")
+        # Reject Java-style package names (for example, "redpanda.core.admin.Service")
+        # Topic properties use lowercase with dots (for example, "cleanup.policy", "segment.ms")
         # Split by dots and check each segment - reject if any segment after first has uppercase
         segments = prop_name.split('.')
         for i, segment in enumerate(segments):