@redpanda-data/docs-extensions-and-macros 5.3.0 → 5.3.2

package/bin/doc-tools.js

@@ -27,7 +27,8 @@ const {
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
   updatePropertiesJsonWithVersion,
-  cleanupOldDiffs
+  cleanupOldDiffs,
+  resolveDiffBaseline
 } = require('../cli-utils/diff-utils')
 
 // Import other utilities
@@ -890,6 +891,7 @@ automation
   .option('-t, --tag <tag>', 'Git tag for released content (GA/beta)')
   .option('-b, --branch <branch>', 'Branch name for in-progress content')
   .option('--diff <oldTag>', 'Diff properties against <oldTag> and restore removed deprecated properties. Recommended for accurate output; falls back to latest-redpanda-tag from antora.yml if not specified')
+  .option('--regenerate-old-baseline', 'Re-extract the --diff tag from source instead of using the committed attachments/redpanda-properties-<oldTag>.json baseline')
   .option('--overrides <path>', 'Optional JSON file with property description overrides', 'docs-data/property-overrides.json')
   .option('--output-dir <dir>', 'Where to write all generated files', 'modules/reference')
   .option('--cloud-support', 'Add AsciiDoc tags to generated property docs to indicate which ones are supported in Redpanda Cloud. This data is fetched from the cloudv2 repository so requires a GitHub token with repo permissions. Set the token as an environment variable using GITHUB_TOKEN, GH_TOKEN, or REDPANDA_GITHUB_TOKEN', true)
@@ -982,7 +984,13 @@ automation
     // When a diff is needed, skip AsciiDoc generation during extraction so we
     // can merge removed deprecated properties first and generate only once.
     if (needsDiff) {
-      make(oldTag, overridesPath, templates, outputDir, { skipPartials: true })
+      const { useCommitted, baselinePath } = resolveDiffBaseline(outputDir, oldTag, options.regenerateOldBaseline)
+      if (useCommitted) {
+        console.log(`Using committed baseline for ${oldTag}: ${baselinePath}`)
+        console.log('   Pass --regenerate-old-baseline to rebuild it from source instead.')
+      } else {
+        make(oldTag, overridesPath, templates, outputDir, { skipPartials: true })
+      }
       make(newTag, overridesPath, templates, outputDir, { skipPartials: true })
     } else {
       make(newTag, overridesPath, templates, outputDir)
@@ -992,7 +1000,16 @@ automation
     // the new JSON so they appear in the generated documentation.
     if (needsDiff) {
       const diffOutputDir = overridesPath ? path.dirname(path.resolve(overridesPath)) : outputDir
-      generatePropertyComparisonReport(oldTag, newTag, diffOutputDir)
+      try {
+        generatePropertyComparisonReport(oldTag, newTag, diffOutputDir)
+      } catch (err) {
+        // A missing baseline only warns inside generatePropertyComparisonReport.
+        // Reaching this catch means both inputs existed and the comparison
+        // itself failed, so fail the run: continuing would silently drop
+        // removed-deprecated restoration and "Introduced in" version stamping.
+        console.error(`Error: Property comparison failed: ${err.message}`)
+        process.exit(1)
+      }
 
       try {
         const diffReportPath = path.join(diffOutputDir, `redpanda-property-changes-${oldTag}-to-${newTag}.json`)
@@ -1012,7 +1029,11 @@ automation
           }
         }
       } catch (err) {
-        console.warn(`Warning: Failed to generate PR summary: ${err.message}`)
+        // The diff report exists but could not be read or applied. Fail the
+        // run rather than shipping docs that are missing removed-deprecated
+        // restoration or version stamps.
+        console.error(`Error: Failed to process the property diff report: ${err.message}`)
+        process.exit(1)
       }
 
       cleanupOldDiffs(diffOutputDir)
@@ -1040,15 +1061,32 @@ automation
 
       try {
         const jsonDir = path.resolve(outputDir, 'attachments')
+        // Invariant: always retain the comparison pair this run actually used
+        // (the current tag's JSON and the diff baseline's JSON) in addition to
+        // the 2 newest versioned JSONs. A backport run can compare tags that
+        // are not the 2 newest, and the next run's comparison needs its
+        // baseline JSON to survive. Mirrors the retention in
+        // tools/property-extractor/Makefile (generate-docs cleanup).
+        const parseVersion = f => f.match(/^redpanda-properties-v([\d.]+)\.json$/)[1].split('.').map(Number)
+        const byVersionDesc = (a, b) => {
+          const [va, vb] = [parseVersion(a), parseVersion(b)]
+          for (let i = 0; i < Math.max(va.length, vb.length); i++) {
+            if ((vb[i] || 0) !== (va[i] || 0)) return (vb[i] || 0) - (va[i] || 0)
+          }
+          return 0
+        }
         const propertyFiles = fs.readdirSync(jsonDir)
           .filter(f => /^redpanda-properties-v[\d.]+\.json$/.test(f))
-          .sort()
+          .sort(byVersionDesc)
 
-        const keepFile = `redpanda-properties-${newTag}.json`
-        const filesToDelete = propertyFiles.filter(f => f !== keepFile)
+        const filesToKeep = new Set(propertyFiles.slice(0, 2))
+        for (const tag of [newTag, oldTag]) {
+          if (tag) filesToKeep.add(`redpanda-properties-${tag}.json`)
+        }
+        const filesToDelete = propertyFiles.filter(f => !filesToKeep.has(f))
 
         if (filesToDelete.length > 0) {
-          console.log('🧹 Cleaning up old property JSON files...')
+          console.log('🧹 Cleaning up old property JSON files (keeping the 2 newest plus the comparison pair)...')
           filesToDelete.forEach(file => {
             fs.unlinkSync(path.join(jsonDir, file))
             console.log(`   Deleted: ${file}`)

package/cli-utils/diff-utils.js

@@ -65,9 +65,16 @@ function cleanupOldDiffs (diffDir) {
 /**
  * Generate a detailed JSON report describing property changes between two releases.
  *
+ * When either input JSON is missing the comparison is skipped with a warning
+ * (a genuinely new oldest tag legitimately has no baseline). When both inputs
+ * exist but the comparison itself fails, this throws so callers fail loudly
+ * instead of silently dropping removed-deprecated restoration and version
+ * stamping.
+ *
  * @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.
+ * @throws {Error} When both input JSONs exist but the comparison fails to run or exits non-zero.
  */
 function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
   try {
@@ -81,13 +88,14 @@ function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
 
     if (!fs.existsSync(oldJsonPath)) {
       console.log(`Warning: Old properties JSON not found at: ${oldJsonPath}`)
-      console.log('   Skipping detailed property comparison.')
+      console.log('   Skipping detailed property comparison: no diff report will be generated, so removed deprecated properties are not restored and new properties are not stamped with "Introduced in" versions.')
+      console.log(`   This is expected only when ${oldTag} has never been extracted (for example, the oldest supported release).`)
       return
     }
 
     if (!fs.existsSync(newJsonPath)) {
       console.log(`Warning: New properties JSON not found at: ${newJsonPath}`)
-      console.log('   Skipping detailed property comparison.')
+      console.log('   Skipping detailed property comparison: no diff report will be generated, so removed deprecated properties are not restored and new properties are not stamped with "Introduced in" versions.')
       return
     }
 
@@ -107,15 +115,19 @@ function generatePropertyComparisonReport (oldTag, newTag, outputDir) {
       cwd: propertyExtractorDir
     })
 
+    // Both inputs exist, so a failed comparison is a hard error: continuing
+    // would silently skip removed-deprecated restoration and version stamping
     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}`)
+      throw new Error(`Property comparison failed to run: ${result.error.message}`)
+    }
+    if (result.status !== 0) {
+      throw new Error(`Property comparison exited with code ${result.status}`)
     }
+    console.log(`Done: Property comparison report saved to: ${reportPath}`)
   } catch (error) {
     console.error(`Error: Error generating property comparison: ${error.message}`)
+    // Propagate so callers fail loudly instead of shipping incomplete docs
+    throw error
   }
 }
 
@@ -346,7 +358,30 @@ function diffDirs (kind, oldTag, newTag, oldTempDir, newTempDir) {
   }
 }
 
+/**
+ * Decide whether a committed baseline attachment can serve as the old side of
+ * a property diff. Rebuilding the old tag in place overwrites the committed
+ * attachment with a fresh extraction, so any contamination in that extraction
+ * silently becomes both the stored baseline and the diff input (the diff then
+ * compares the run against its own output and reports no new properties).
+ * @param {string} outputDir - Docs output dir that contains attachments/
+ * @param {string} oldTag - Old version tag (for example, v26.1.14)
+ * @param {boolean} [regenerate=false] - Force re-extraction even if a baseline exists
+ * @returns {{useCommitted: boolean, baselinePath: string}}
+ */
+function resolveDiffBaseline (outputDir, oldTag, regenerate = false) {
+  const attachmentsDir = path.resolve(outputDir, 'attachments')
+  const baselinePath = path.resolve(attachmentsDir, `redpanda-properties-${oldTag}.json`)
+  const relativePath = path.relative(attachmentsDir, baselinePath)
+  if (relativePath.startsWith('..') || path.isAbsolute(relativePath) || relativePath.includes(path.sep)) {
+    throw new Error(`Invalid old tag "${oldTag}": baseline must resolve within the attachments directory`)
+  }
+  return { useCommitted: !regenerate && fs.existsSync(baselinePath), baselinePath }
+}
+
 module.exports = {
+  resolveDiffBaseline,
+
   runClusterDocs,
   cleanupOldDiffs,
   generatePropertyComparisonReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",

package/tools/property-extractor/Makefile

@@ -72,19 +72,30 @@ clean:
 	@rm -rf $(VENV) $(TMP_ROOT) $(REPO_ROOT)/autogenerated
 
 # --- Clone or update Redpanda, checkout TAG or default branch ---
+# Clones are shallow: the extractor only reads source files at a single tag,
+# so full history is wasted time and disk.
+# Auth is passed as a per-invocation HTTP header (git -c before the clone
+# subcommand), never embedded in the remote URL, so no token is persisted in
+# the clone's .git/config. The clone lives inside the installed package dir,
+# so a persisted token would be readable by anything that can list it.
 redpanda-git:
 	@mkdir -p "$(TMP_ROOT)"
 	@echo "🔄 Cloning/updating Redpanda into $(REDPANDA_SRC)…"
 	@if [ -d "$(REDPANDA_SRC)" ]; then \
-	  git -C "$(REDPANDA_SRC)" fetch --all --tags -q; \
+	  git -C "$(REDPANDA_SRC)" fetch --depth 1 -q origin "+refs/tags/$(TAG):refs/tags/$(TAG)" 2>/dev/null || \
+	    git -C "$(REDPANDA_SRC)" fetch --depth 1 -q origin "+refs/heads/$(TAG):refs/remotes/origin/$(TAG)" 2>/dev/null || \
+	    git -C "$(REDPANDA_SRC)" fetch --all --tags -q; \
 	else \
 	  GH_TOKEN=$${REDPANDA_GITHUB_TOKEN:-$${GITHUB_TOKEN:-$${GH_TOKEN}}}; \
+	  REPO_URL="https://github.com/redpanda-data/redpanda.git"; \
 	  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)"; \
+	    AUTH_HEADER="AUTHORIZATION: basic $$(printf '%s' "x-access-token:$$GH_TOKEN" | base64 | tr -d '\n')"; \
 	  else \
-	    git clone -q https://github.com/redpanda-data/redpanda.git "$(REDPANDA_SRC)"; \
+	    AUTH_HEADER=""; \
 	  fi; \
+	  git -c http.https://github.com/.extraheader="$$AUTH_HEADER" clone -q --depth 1 --branch "$(TAG)" "$$REPO_URL" "$(REDPANDA_SRC)" 2>/dev/null || \
+	    git -c http.https://github.com/.extraheader="$$AUTH_HEADER" clone -q --depth 1 "$$REPO_URL" "$(REDPANDA_SRC)"; \
 	fi; \
 	if git -C "$(REDPANDA_SRC)" rev-parse --verify -q "origin/$(TAG)" >/dev/null 2>&1; then \
 	  echo "🔖 Checking out remote branch 'origin/$(TAG)'"; \
@@ -94,24 +105,44 @@ redpanda-git:
 	  echo "🔖 Checking out '$(TAG)'"; \
 	  git -C "$(REDPANDA_SRC)" checkout -q "$(TAG)"; \
 	else \
-	  DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" symbolic-ref --short refs/remotes/origin/HEAD); \
-	  echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
-	  git -C "$(REDPANDA_SRC)" checkout -q "$${DEFAULT_BRANCH}"; \
+	  DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || true); \
+	  if [ -n "$$DEFAULT_BRANCH" ]; then \
+	    echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
+	    git -C "$(REDPANDA_SRC)" checkout -q "$${DEFAULT_BRANCH}"; \
+	  else \
+	    DEFAULT_BRANCH=$$(git -C "$(REDPANDA_SRC)" ls-remote --symref origin HEAD | awk '/^ref:/ {sub(/^refs\/heads\//, "", $$2); print $$2; exit}'); \
+	    if [ -z "$$DEFAULT_BRANCH" ]; then \
+	      echo "❌ Tag '$(TAG)' not found and the default branch could not be determined"; \
+	      exit 1; \
+	    fi; \
+	    echo "⚠️ Tag '$(TAG)' not found; falling back to '$${DEFAULT_BRANCH}'"; \
+	    git -C "$(REDPANDA_SRC)" fetch --depth 1 -q origin "$$DEFAULT_BRANCH"; \
+	    git -C "$(REDPANDA_SRC)" checkout -q FETCH_HEAD; \
+	  fi; \
 	fi
 
 # --- Clone Tree-sitter grammar & generate parser ---
+# Skips npm install and parser generation when the generated output already
+# exists for the pinned grammar version, so repeat builds stay fast
 treesitter:
 	@echo "🌲 Ensuring tree-sitter-cpp grammar…"
 	@if [ ! -d "$(TREESITTER_DIR)/.git" ]; then \
 	  rm -rf "$(TREESITTER_DIR)"; \
 	  git clone https://github.com/tree-sitter/tree-sitter-cpp.git "$(TREESITTER_DIR)"; \
 	fi
-	@echo "🔄 Ensuring tree-sitter-cpp is at compatible version v0.20.5…"
-	@cd "$(TREESITTER_DIR)" && \
-	  git fetch --tags -q && \
-	  git checkout -q v0.20.5
-	@echo "🔧 Generating parser in $(TREESITTER_DIR)…"
-	@cd "$(TREESITTER_DIR)" && export CFLAGS="-Wno-unused-but-set-variable" && npm install --silent && export CFLAGS="-Wno-unused-but-set-variable" && $(TREE_SITTER) generate
+	@CURRENT_TAG=$$(git -C "$(TREESITTER_DIR)" describe --tags --exact-match 2>/dev/null || true); \
+	if [ "$$CURRENT_TAG" = "v0.20.5" ] && [ -f "$(TREESITTER_DIR)/src/parser.c" ]; then \
+	  echo "✅ tree-sitter-cpp parser already generated at v0.20.5; skipping regeneration"; \
+	else \
+	  echo "🔄 Ensuring tree-sitter-cpp is at compatible version v0.20.5…"; \
+	  cd "$(TREESITTER_DIR)" && \
+	    git fetch --tags -q && \
+	    git checkout -q v0.20.5 && \
+	    echo "🔧 Generating parser in $(TREESITTER_DIR)…" && \
+	    export CFLAGS="-Wno-unused-but-set-variable" && \
+	    npm install --silent && \
+	    $(TREE_SITTER) generate; \
+	fi
 
 # --- Install Node.js dependencies for Handlebars ---
 node-deps:
@@ -146,6 +177,9 @@ generate-docs: node-deps
 	else \
 	  echo "   ⚠️  Source file $(TOOL_ROOT)/gen/$(TAG)-properties.json not found, skipping copy"; \
 	fi
+	@# Invariant: keep at least 2 versioned JSONs, the current release plus the
+	@# diff baseline that the next run's comparison depends on. Mirrors the
+	@# retention in bin/doc-tools.js (post-run property JSON cleanup).
 	@echo "🧹 Cleaning up old versioned JSON files (keeping only 2 most recent)…"
 	@cd "$(OUTPUT_JSON_DIR)" && \
 	  ls -t redpanda-properties-*.json 2>/dev/null | tail -n +3 | while read file; do \

package/tools/property-extractor/cloud_config.py

@@ -434,6 +434,22 @@ def fetch_cloud_config(github_token: Optional[str] = None) -> CloudConfig:
         raise CloudConfigError(error_msg) from e
 
 
+def _match_name_or_alias(prop_name: str, prop_data: Dict, cloud_set: Set[str]) -> Optional[str]:
+    """
+    Return the name under which a property appears in a cloud property set.
+
+    Checks the property's own name first, then each entry in its `aliases`
+    array. Returns the matching name, or None when neither the name nor any
+    alias is in the set.
+    """
+    if prop_name in cloud_set:
+        return prop_name
+    for alias in prop_data.get('aliases') or []:
+        if alias in cloud_set:
+            return alias
+    return None
+
+
 def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> Dict:
     """
     Annotate property definitions with cloud-support metadata derived from a CloudConfig.
@@ -492,29 +508,39 @@ def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> D
                 continue
             
             processed_count += 1
-            
+
             # Initialize cloud metadata with defaults
             prop_data['cloud_editable'] = False
             prop_data['cloud_readonly'] = False
             prop_data['cloud_supported'] = False
             prop_data['cloud_byoc_only'] = False
-            
-            # Determine cloud support status
-            if prop_name in editable_props:
+
+            # Determine cloud support status. Match on the property's current
+            # name or any of its aliases, so a property renamed in Redpanda
+            # still picks up cloud metadata when the cloud configuration
+            # references the old name.
+            editable_match = _match_name_or_alias(prop_name, prop_data, editable_props)
+            readonly_match = None if editable_match else _match_name_or_alias(prop_name, prop_data, readonly_props)
+
+            if editable_match:
+                if editable_match != prop_name:
+                    logger.info(f"Property '{prop_name}' matched cloud editable configuration via alias '{editable_match}'")
                 prop_data['cloud_editable'] = True
                 prop_data['cloud_readonly'] = False
                 prop_data['cloud_supported'] = True
                 cloud_supported_count += 1
                 editable_count += 1
-                
-                # Check if BYOC only
-                if cloud_config.is_byoc_only(prop_name):
+
+                # Check if BYOC only, using the name the cloud configuration knows
+                if cloud_config.is_byoc_only(editable_match):
                     prop_data['cloud_byoc_only'] = True
                     byoc_only_count += 1
                 else:
                     prop_data['cloud_byoc_only'] = False
-                    
-            elif prop_name in readonly_props:
+
+            elif readonly_match:
+                if readonly_match != prop_name:
+                    logger.info(f"Property '{prop_name}' matched cloud readonly configuration via alias '{readonly_match}'")
                 prop_data['cloud_editable'] = False
                 prop_data['cloud_readonly'] = True
                 prop_data['cloud_supported'] = True
@@ -565,11 +591,14 @@ def add_cloud_support_metadata(properties: Dict, cloud_config: CloudConfig) -> D
         logger.warning("  2. Property names don't match between sources")
         logger.warning("  3. All properties are self-managed only")
     
-    # Check for potential mismatches
-    unmatched_cloud_props = (editable_props | readonly_props) - {
-        name for name, data in properties.items() 
-        if isinstance(data, dict) and data.get('config_scope') in ['cluster', 'broker', 'topic']
-    }
+    # Check for potential mismatches, counting aliases as known names so a
+    # renamed property does not show up as missing
+    extracted_cloud_names = set()
+    for name, data in properties.items():
+        if isinstance(data, dict) and data.get('config_scope') in ['cluster', 'broker', 'topic']:
+            extracted_cloud_names.add(name)
+            extracted_cloud_names.update(data.get('aliases') or [])
+    unmatched_cloud_props = (editable_props | readonly_props) - extracted_cloud_names
     
     if unmatched_cloud_props:
         logger.info(f"Cloud configuration contains {len(unmatched_cloud_props)} properties not found in extracted properties:")

package/tools/property-extractor/compare-properties.js

@@ -364,8 +364,10 @@ function generateConsoleReport(report, oldVersion, newVersion) {
 /**
  * Write a structured JSON comparison report to disk.
  *
- * Produces a JSON file containing a comparison header (old/new versions and timestamp),
+ * Produces a JSON file containing a comparison header (old/new versions),
  * a summary with counts for each change category, and the full details object passed as `report`.
+ * The report is deterministic: rerunning the comparison on the same inputs
+ * produces byte-identical output, so committed reports do not churn.
  *
  * @param {Object} report - Comparison details object produced by compareProperties; expected to contain arrays: `newProperties`, `changedDefaults`, `changedDescriptions`, `changedTypes`, `deprecatedProperties`, `removedProperties`, and `emptyDescriptions`.
  * @param {string} oldVersion - The previous version identifier included in the comparison header.
@@ -376,8 +378,7 @@ function generateJsonReport(report, oldVersion, newVersion, outputPath) {
   const jsonReport = {
     comparison: {
       oldVersion,
-      newVersion,
-      timestamp: new Date().toISOString()
+      newVersion
     },
     summary: {
       newProperties: report.newProperties.length,

package/tools/property-extractor/pr-summary-formatter.js

@@ -20,7 +20,7 @@
  *
  * Input format (diff data from compare-properties.js):
  *   {
- *     comparison: { oldVersion, newVersion, timestamp },
+ *     comparison: { oldVersion, newVersion },
  *     summary: { newProperties, changedDefaults, ... },
  *     details: { newProperties: [...], changedDefaults: [...], ... }
  *   }
@@ -278,11 +278,14 @@ function generatePRSummary(diffData) {
   lines.push('</details>');
   lines.push('');
 
-  // Footer
+  // Footer. The timestamp only appears in reports generated before the
+  // field was removed to keep committed diff reports deterministic.
   lines.push('---');
   lines.push('');
-  lines.push(`*Generated: ${diffData.comparison.timestamp}*`);
-  lines.push('');
+  if (diffData.comparison.timestamp) {
+    lines.push(`*Generated: ${diffData.comparison.timestamp}*`);
+    lines.push('');
+  }
   lines.push('<!-- PR_SUMMARY_END -->');
 
   return lines.join('\n');

package/tools/property-extractor/property_extractor.py

@@ -79,7 +79,7 @@ ENUM_PATTERN = re.compile(r'^[a-zA-Z0-9_:]+::([a-zA-Z0-9_]+)$')  # Match full qu
 CONSTRUCTOR_PATTERN = re.compile(r'([a-zA-Z0-9_:]+)\((.*)\)')
 BRACED_CONSTRUCTOR_PATTERN = re.compile(r'([a-zA-Z0-9_:]+)\{(.*)\}')
 DIGIT_SEPARATOR_PATTERN = re.compile(r"(?<=\d)'(?=\d)")
-FUNCTION_CALL_PATTERN = re.compile(r'([a-zA-Z0-9_:]+)\(\)')
+FUNCTION_CALL_PATTERN = re.compile(r'([a-zA-Z0-9_:.]+)\(\)$')
 CHRONO_PATTERN = re.compile(r'std::chrono::([a-zA-Z]+)\s*\{\s*(\d+)\s*\}')
 CHRONO_PAREN_PATTERN = re.compile(r'(?:std::)?chrono::([a-zA-Z]+)\s*\(\s*([^)]+)\s*\)')
 TIME_UNIT_PATTERN = re.compile(r'(\d+)\s*(min|s|ms|h)')
@@ -159,6 +159,15 @@ class ConstexprCache:
             re.compile(r'const\s+model::ns\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(\s*"([^"]+)"\s*\)'),
         ]
 
+        # Member accessors on inline constants used in property defaults,
+        # for example model::schema_registry_internal_tp.topic() -> "_schemas".
+        # Each entry maps a variable declaration to the member name whose call
+        # returns the captured string, cached under "<variable>.<member>".
+        member_accessor_patterns = [
+            # Pattern: inline const model::topic_partition name{model::topic{"value"}, ...}
+            (re.compile(r'inline\s+const\s+(?:model::)?topic_partition\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\{\s*(?:model::)?topic\{\s*"([^"]+)"\s*\}'), 'topic'),
+        ]
+
         # Legacy specific patterns (kept for compatibility, but general patterns should cover these)
         function_patterns = {}
 
@@ -206,6 +215,17 @@ class ConstexprCache:
                                         qualified_name = f"{namespace}::{func_name}"
                                         self.function_cache[qualified_name] = func_value
 
+                            # Extract member accessors on inline constants
+                            for pattern, member in member_accessor_patterns:
+                                for match in pattern.finditer(content):
+                                    var_name = match.group(1)
+                                    value = match.group(2)
+                                    key = f"{var_name}.{member}"
+                                    namespace = self._extract_namespace_for_function(content, match.start())
+                                    self.function_cache[key] = value
+                                    if namespace:
+                                        self.function_cache[f"{namespace}::{key}"] = value
+
                             # Legacy: Extract function definitions from hardcoded patterns (if any)
                             for func_name, patterns in function_patterns.items():
                                 for pattern in patterns:
@@ -301,16 +321,35 @@ _constexpr_cache = ConstexprCache()
 _type_definitions_cache = {}
 
 # Import topic property extractor
+# Set from --path in main() so every consumer of the Redpanda source uses the
+# tree the caller pointed at, regardless of the current working directory. The
+# hardcoded search below is only a fallback for direct module use.
+_redpanda_source_override = None
+
+
+def set_redpanda_source(path):
+    """Record the Redpanda source directory passed via --path."""
+    global _redpanda_source_override
+    _redpanda_source_override = path
+
+
 def find_redpanda_source():
     """
-    Locate the Redpanda source directory by searching standard locations.
-    
-    The property extractor looks for the Redpanda source code in multiple
-    locations to handle different execution contexts (project root, tools directory, etc.).
-    
+    Locate the Redpanda source directory.
+
+    Prefers the path passed via --path (recorded by set_redpanda_source);
+    falls back to searching standard locations relative to the current
+    working directory. Before this preference existed, running the extractor
+    from any directory that did not match a hardcoded guess silently
+    disabled the ConstantResolver: no validator enums, no enterprise enum
+    metadata, no constexpr resolution, with only a debug-level log line.
+
     Returns:
         str or None: Path to the Redpanda source directory if found, None otherwise.
     """
+    if _redpanda_source_override and os.path.exists(_redpanda_source_override):
+        return _redpanda_source_override
+
     redpanda_source_paths = [
         'tmp/redpanda',  # Current directory
         '../tmp/redpanda',  # Parent directory  
@@ -705,6 +744,13 @@ def transform_files_with_properties(files_with_properties):
         if src_v_path.exists():
             constant_resolver = ConstantResolver(src_v_path)
             logger.debug(f"Initialized ConstantResolver with path: {src_v_path}")
+    if constant_resolver is None:
+        logger.warning(
+            "Redpanda source directory not found: validator enum extraction "
+            "and enterprise enum metadata are DISABLED for this run. "
+            "Properties like sasl_mechanisms will be missing items.enum and "
+            "x-enum-metadata. Pass --path to the Redpanda checkout to fix this."
+        )
 
     transformers = [
         EnterpriseTransformer(), ## this must be the first, as it modifies current data
@@ -922,6 +968,32 @@ def merge_properties_and_definitions(properties, definitions):
     return dict(properties=properties, definitions=definitions)
 
 
+# Phantom stub entries created by apply_property_overrides during the current
+# run. An entry is recorded whenever an override key matches no extracted
+# property and a placeholder doc entry is fabricated from the override alone.
+# Tracked at module level so the run summary in main() can report them all in
+# one place at the end of the run.
+phantom_stub_entries = []
+
+
+def report_phantom_stubs():
+    """Log one prominent warning block listing every phantom stub created from overrides."""
+    if not phantom_stub_entries:
+        return
+    logger.warning("=" * 70)
+    logger.warning(
+        f"⚠️  {len(phantom_stub_entries)} override "
+        f"{'entry' if len(phantom_stub_entries) == 1 else 'entries'} matched no extracted property"
+    )
+    for entry in phantom_stub_entries:
+        logger.warning(
+            f"Override key '{entry['name']}' matched no extracted property — created a stub entry "
+            f"with config_scope '{entry['config_scope']}'. If the property was renamed or removed, "
+            f"update docs-data/property-overrides.json."
+        )
+    logger.warning("=" * 70)
+
+
 def apply_property_overrides(properties, overrides, overrides_file_path=None):
     """
     Apply overrides from an overrides mapping to the extracted properties, mutating and returning the properties dictionary.
@@ -941,6 +1013,7 @@ def apply_property_overrides(properties, overrides, overrides_file_path=None):
     Returns:
         dict: The same properties mapping with overrides applied and any new properties created.
     """
+    phantom_stub_entries.clear()
     if overrides and "properties" in overrides:
         for prop, override in overrides["properties"].items():
             # First check if property exists by key
@@ -962,7 +1035,13 @@ def apply_property_overrides(properties, overrides, overrides_file_path=None):
                 else:
                     # Create new property from override
                     logger.info(f"Creating new property from override: {prop}")
-                    properties[prop] = _create_property_from_override(prop, override, overrides_file_path)
+                    new_property = _create_property_from_override(prop, override, overrides_file_path)
+                    properties[prop] = new_property
+                    # Record the phantom stub so the run summary can flag it loudly
+                    phantom_stub_entries.append({
+                        "name": prop,
+                        "config_scope": new_property.get("config_scope"),
+                    })
     return properties
 
 
@@ -2856,6 +2935,11 @@ def main():
         treesitter_dir, destination_path
     )
 
+    # Every consumer of the Redpanda source (ConstantResolver, constexpr
+    # fallback search) must use the tree the caller pointed at, not a
+    # cwd-relative guess.
+    set_redpanda_source(options.path)
+
     # Pre-build constexpr cache for performance
     # This avoids repeated filesystem walks when resolving C++ identifiers and function calls
     logger.info("🔧 Building constexpr identifier cache...")
@@ -3053,5 +3137,16 @@ def main():
             logging.error(f"Failed to write enhanced output file: {e}")
             sys.exit(1)
 
+    # Surface phantom stubs prominently at the end of the run. These are
+    # override keys that matched no extracted property, so a placeholder doc
+    # entry was fabricated from the override alone.
+    if phantom_stub_entries:
+        report_phantom_stubs()
+        phantom_names = ", ".join(entry["name"] for entry in phantom_stub_entries)
+        print(
+            f"⚠️  Phantom stub entries created from overrides: "
+            f"{len(phantom_stub_entries)} ({phantom_names})"
+        )
+
 if __name__ == "__main__":
     main()