@redpanda-data/docs-extensions-and-macros 4.12.2 → 4.12.4

package/tools/property-extractor/Makefile

@@ -27,7 +27,10 @@ TREE_SITTER   := npx tree-sitter
 # Output directory configuration (can be overridden by environment variables)
 OUTPUT_AUTOGENERATED_DIR ?= $(REPO_ROOT)/modules/reference
 OUTPUT_ASCIIDOC_DIR      ?= $(OUTPUT_AUTOGENERATED_DIR)/pages
-OUTPUT_JSON_DIR          ?= $(OUTPUT_AUTOGENERATED_DIR)/examples
+# Always save versioned JSON files to attachments directory
+OUTPUT_JSON_DIR          ?= $(OUTPUT_AUTOGENERATED_DIR)/attachments
+# Diff JSON files are saved to overrides directory (if OVERRIDES is specified)
+OUTPUT_DIFF_DIR          ?= $(if $(OVERRIDES),$(or $(dir $(OVERRIDES)),$(OUTPUT_AUTOGENERATED_DIR)/attachments),$(OUTPUT_AUTOGENERATED_DIR)/attachments)
 OUTPUT_PARTIALS_DIR      ?= $(OUTPUT_AUTOGENERATED_DIR)/partials
 
 # --- Main build: venv, fetch code, build parser, extract & docgen ---
@@ -61,7 +64,7 @@ venv: $(TOOL_ROOT)/requirements.txt
 	fi; \
 	echo "🔄 Upgrading pip and installing requirements..."; \
 	$(VENV)/bin/pip install --upgrade pip --quiet; \
-	$(VENV)/bin/pip install --no-cache-dir -r $<;
+	$(VENV)/bin/pip install --no-cache-dir -r $< --quiet;
 
 # --- Clean out all generated state ---
 clean:
@@ -120,20 +123,70 @@ generate-docs: node-deps
 	@echo "📄 Copying properties JSON files to $(OUTPUT_JSON_DIR)…"
 	@if [ -f "$(TOOL_ROOT)/gen/$(TAG)-properties.json" ]; then \
 	  echo "   Source: $(TOOL_ROOT)/gen/$(TAG)-properties.json"; \
-	  echo "   Target: $(OUTPUT_JSON_DIR)/$(TAG)-properties.json"; \
-	  cp "$(TOOL_ROOT)/gen/$(TAG)-properties.json" "$(OUTPUT_JSON_DIR)/" && \
-	  echo "   ✅ Successfully copied $(TAG)-properties.json" || \
-	  { echo "   ❌ Failed to copy $(TAG)-properties.json"; exit 1; }; \
-	  if [ -f "$(OUTPUT_JSON_DIR)/$(TAG)-properties.json" ]; then \
-	    echo "   📊 Verification: Target file exists and has $$(wc -c < "$(OUTPUT_JSON_DIR)/$(TAG)-properties.json") bytes"; \
+	  echo "   Target: $(OUTPUT_JSON_DIR)/redpanda-properties-$(TAG).json"; \
+	  cp "$(TOOL_ROOT)/gen/$(TAG)-properties.json" "$(OUTPUT_JSON_DIR)/redpanda-properties-$(TAG).json" && \
+	  echo "   ✅ Successfully copied redpanda-properties-$(TAG).json" || \
+	  { echo "   ❌ Failed to copy redpanda-properties-$(TAG).json"; exit 1; }; \
+	  if [ -f "$(OUTPUT_JSON_DIR)/redpanda-properties-$(TAG).json" ]; then \
+	    echo "   📊 Verification: Target file exists and has $$(wc -c < "$(OUTPUT_JSON_DIR)/redpanda-properties-$(TAG).json") bytes"; \
 	  else \
 	    echo "   ❌ Verification failed: Target file does not exist"; exit 1; \
 	  fi; \
 	else \
 	  echo "   ⚠️  Source file $(TOOL_ROOT)/gen/$(TAG)-properties.json not found, skipping copy"; \
 	fi
+	@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 \
+	    echo "   Removing old file: $$file"; \
+	    rm -f "$$file"; \
+	  done || true
 	@echo "✅ Docs generated at $(OUTPUT_AUTOGENERATED_DIR)"
 
+# --- Compare two property files and generate a diff report ---
+# Usage: make compare OLD_TAG=v25.2.1 NEW_TAG=v25.2.9 OVERRIDES=path/to/overrides.json
+# This will compare the two versions and save the diff to the overrides directory
+compare:
+	@if [ -z "$(OLD_TAG)" ] || [ -z "$(NEW_TAG)" ]; then \
+	  echo "❌ Error: Both OLD_TAG and NEW_TAG must be specified"; \
+	  echo "   Usage: make compare OLD_TAG=v25.2.1 NEW_TAG=v25.2.9 OVERRIDES=path/to/overrides.json"; \
+	  exit 1; \
+	fi
+	@if [ -z "$(OVERRIDES)" ]; then \
+	  echo "❌ Error: OVERRIDES must be specified to determine where to save the diff"; \
+	  echo "   Usage: make compare OLD_TAG=v25.2.1 NEW_TAG=v25.2.9 OVERRIDES=path/to/overrides.json"; \
+	  exit 1; \
+	fi
+	@if [ ! -f "$(OUTPUT_JSON_DIR)/redpanda-properties-$(OLD_TAG).json" ]; then \
+	  echo "❌ Error: Old properties file not found: $(OUTPUT_JSON_DIR)/redpanda-properties-$(OLD_TAG).json"; \
+	  exit 1; \
+	fi
+	@if [ ! -f "$(OUTPUT_JSON_DIR)/redpanda-properties-$(NEW_TAG).json" ]; then \
+	  echo "❌ Error: New properties file not found: $(OUTPUT_JSON_DIR)/redpanda-properties-$(NEW_TAG).json"; \
+	  exit 1; \
+	fi
+	@echo "Comparing $(OLD_TAG) → $(NEW_TAG)"
+	@echo "   Diff will be saved to: $(OUTPUT_DIFF_DIR)"
+	@cd $(TOOL_ROOT) && \
+	  node compare-properties.js \
+	    "$(OUTPUT_JSON_DIR)/redpanda-properties-$(OLD_TAG).json" \
+	    "$(OUTPUT_JSON_DIR)/redpanda-properties-$(NEW_TAG).json" \
+	    $(OLD_TAG) \
+	    $(NEW_TAG) \
+	    "$(OUTPUT_DIFF_DIR)" \
+	    "redpanda-property-changes-$(OLD_TAG)-to-$(NEW_TAG).json"
+	@echo "✅ Diff saved to $(OUTPUT_DIFF_DIR)/redpanda-property-changes-$(OLD_TAG)-to-$(NEW_TAG).json"
+	@$(MAKE) cleanup-diffs OVERRIDES="$(OVERRIDES)"
+
+# --- Helper target to cleanup old diff files ---
+cleanup-diffs:
+	@echo "🧹 Cleaning up old diff JSON files (keeping only 2 most recent)…"
+	@cd "$(OUTPUT_DIFF_DIR)" && \
+	  ls -t redpanda-property-changes-*.json 2>/dev/null | tail -n +3 | while read file; do \
+	    echo "   Removing old file: $$file"; \
+	    rm -f "$$file"; \
+	  done || true
+
 # --- Debug helper to print all the key paths/vars ---
 check:
 	@echo "MODULE_ROOT:              $(MODULE_ROOT)"
@@ -142,6 +195,8 @@ check:
 	@echo "TREESITTER:               $(TREESITTER_DIR)"
 	@echo "VENV:                     $(VENV)"
 	@echo "PYTHON:                   $(PYTHON)"
+	@echo "OVERRIDES:                $(OVERRIDES)"
 	@echo "OUTPUT_ASCIIDOC_DIR:      $(OUTPUT_ASCIIDOC_DIR)"
 	@echo "OUTPUT_JSON_DIR:          $(OUTPUT_JSON_DIR)"
+	@echo "OUTPUT_DIFF_DIR:          $(OUTPUT_DIFF_DIR)"
 	@echo "OUTPUT_AUTOGENERATED_DIR: $(OUTPUT_AUTOGENERATED_DIR)"