@redpanda-data/docs-extensions-and-macros 5.2.1 → 5.2.2

package/bin/doc-tools.js

@@ -26,6 +26,7 @@ const {
   diffDirs,
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
+  updatePropertiesJsonWithVersion,
   cleanupOldDiffs
 } = require('../cli-utils/diff-utils')
 
@@ -1002,6 +1003,12 @@ automation
 
           if (overridesPath && fs.existsSync(overridesPath)) {
             updatePropertyOverridesWithVersion(overridesPath, diffData, newTag)
+            // The overrides were baked into the extracted JSON during Phase 1,
+            // before the stamp above existed. Stamp the JSON too, so the
+            // AsciiDoc generated in Phase 3 shows "Introduced in" for
+            // properties new in this release instead of one release late.
+            const extractedJsonPath = path.resolve(outputDir, 'attachments', `redpanda-properties-${newTag}.json`)
+            updatePropertiesJsonWithVersion(extractedJsonPath, diffData, newTag)
           }
         }
       } catch (err) {

package/cli-utils/diff-utils.js

@@ -193,6 +193,88 @@ function updatePropertyOverridesWithVersion (overridesPath, diffData, newTag) {
   }
 }
 
+/**
+ * Stamp version information for new properties directly into an extracted
+ * properties JSON file (redpanda-properties-<tag>.json).
+ *
+ * Overrides are baked into this JSON during extraction, which happens before
+ * updatePropertyOverridesWithVersion stamps new properties into the overrides
+ * file — so without this step the AsciiDoc rendered from the JSON misses the
+ * "Introduced in" line for properties added in the release being generated
+ * (it would only appear on the next release's run).
+ *
+ * @param {string} jsonPath - Path to the extracted properties JSON file
+ * @param {object} diffData - Diff data from property comparison
+ * @param {string} newTag - Version tag for new properties (e.g., "v26.1.13")
+ */
+function updatePropertiesJsonWithVersion (jsonPath, diffData, newTag) {
+  try {
+    const newProperties = diffData.details?.newProperties || []
+    if (newProperties.length === 0) return
+    if (!fs.existsSync(jsonPath)) {
+      console.warn(`Warning: Cannot stamp versions: ${jsonPath} does not exist`)
+      return
+    }
+
+    // The stamp is a textual insertion, NOT a parse/re-serialize round-trip:
+    // JSON.stringify would corrupt values JavaScript numbers cannot represent
+    // (uint64 maxima like 18446744073709551615) and reformat floats (0.0 → 0)
+    // throughout the Python-generated file.
+    let raw = fs.readFileSync(jsonPath, 'utf8')
+    const indentUnit = (raw.match(/^([ \t]+)"/m) || [null, '    '])[1]
+
+    let stampedCount = 0
+    newProperties.forEach(prop => {
+      const updated = insertVersionIntoRawJson(raw, prop.name, newTag, indentUnit)
+      if (updated) {
+        raw = updated
+        stampedCount++
+      }
+    })
+
+    if (stampedCount > 0) {
+      JSON.parse(raw) // validate the surgical edits before touching the file
+      fs.writeFileSync(jsonPath, raw, 'utf8')
+      console.log(`Done: Stamped "Introduced in ${newTag}" on ${stampedCount} new ${stampedCount === 1 ? 'property' : 'properties'} in ${path.basename(jsonPath)}`)
+    }
+  } catch (error) {
+    console.error(`Warning: Failed to stamp versions into properties JSON: ${error.message}`)
+  }
+}
+
+/**
+ * Insert a `"version": "<newTag>",` field at the top of one property's object
+ * in the raw JSON text, leaving every other byte untouched.
+ *
+ * @param {string} raw - Full JSON file content
+ * @param {string} propName - Property key to stamp
+ * @param {string} newTag - Version tag to insert
+ * @param {string} indentUnit - One level of the file's indentation
+ * @returns {string|null} Updated content, or null when the property was not
+ *   found or already carries a version field.
+ */
+function insertVersionIntoRawJson (raw, propName, newTag, indentUnit) {
+  // Anchor the search to the top-level "properties" section when present, so
+  // an identically named key elsewhere (e.g. under "definitions") is not hit.
+  const sectionMatch = raw.match(new RegExp(`^${indentUnit}"properties": \\{`, 'm'))
+  const searchFrom = sectionMatch ? raw.indexOf(sectionMatch[0]) : 0
+
+  const escapedName = propName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const keyMatch = new RegExp(`^([ \t]+)"${escapedName}": \\{[ \t]*$`, 'm').exec(raw.slice(searchFrom))
+  if (!keyMatch) return null
+
+  const keyIndent = keyMatch[1]
+  const objStart = searchFrom + keyMatch.index + keyMatch[0].length
+
+  // Skip when the object already has a version field (scan up to its closing brace).
+  const close = new RegExp(`^${keyIndent}\\}`, 'm').exec(raw.slice(objStart))
+  const objBody = raw.slice(objStart, close ? objStart + close.index : raw.length)
+  if (new RegExp(`^${keyIndent}${indentUnit}"version":`, 'm').test(objBody)) return null
+
+  const insertion = `\n${keyIndent}${indentUnit}"version": ${JSON.stringify(newTag)},`
+  return raw.slice(0, objStart) + insertion + raw.slice(objStart)
+}
+
 /**
  * Create a unified diff patch between two directories and clean them up.
  *
@@ -269,5 +351,6 @@ module.exports = {
   cleanupOldDiffs,
   generatePropertyComparisonReport,
   updatePropertyOverridesWithVersion,
+  updatePropertiesJsonWithVersion,
   diffDirs
 }

package/package.json

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