@redpanda-data/docs-extensions-and-macros 5.3.6 → 5.3.7

package/package.json

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

package/tools/redpanda-connect/generate-rpcn-connector-docs.js

@@ -5,6 +5,7 @@ const path = require('path');
 const handlebars = require('handlebars');
 const yaml = require('yaml');
 const helpers = require('./helpers');
+const { lostMetadataSections } = require('./metadata-utils.js');
 
 // Register each helper under handlebars, verifying that it’s a function
 Object.entries(helpers).forEach(([name, fn]) => {
@@ -376,6 +377,7 @@ async function generateRpcnConnectorDocs(options) {
   }
 
   let partialsWritten = 0;
+  const lostSectionWarnings = [];
   let draftsWritten   = 0;
   const partialFiles  = [];
   const draftFiles    = [];
@@ -434,6 +436,25 @@ async function generateRpcnConnectorDocs(options) {
         const mPath = path.join(metadataOutRoot, typeDir, `${name}.adoc`);
         if (metadataOut.trim()) {
           fs.mkdirSync(path.dirname(mPath), { recursive: true });
+          if (fs.existsSync(mPath)) {
+            // Regeneration is authoritative, but a section vanishing from a
+            // published partial is usually content loss, not cleanup: the
+            // section either sits outside the upstream description's
+            // `== Metadata` block or was hand-migrated from a page, and
+            // overwriting drops it without a trace. Warn so the auto-docs PR
+            // reviewer can move the content to the connector page or restore
+            // it upstream before merging.
+            const lost = lostMetadataSections(fs.readFileSync(mPath, 'utf8'), metadataOut);
+            if (lost.length) {
+              lostSectionWarnings.push({ partial: path.relative(process.cwd(), mPath), sections: lost });
+              console.warn(
+                `Warning: regenerated metadata partial ${path.relative(process.cwd(), mPath)} ` +
+                `drops previously published section(s): ${lost.map((h) => `"${h}"`).join(', ')}. ` +
+                'If this content is still wanted, move it to the connector page or restore it ' +
+                "in the upstream description's Metadata section."
+              );
+            }
+          }
           fs.writeFileSync(mPath, metadataOut);
           if (!writeFullDrafts) {
             partialsWritten++;
@@ -657,7 +678,8 @@ async function generateRpcnConnectorDocs(options) {
     partialsWritten,
     draftsWritten,
     partialFiles,
-    draftFiles
+    draftFiles,
+    lostSectionWarnings
   };
 }
 

package/tools/redpanda-connect/metadata-utils.js

@@ -111,10 +111,69 @@ function descriptionWithMetadataInclude (item) {
   return description.slice(0, found.start) + metadataIncludeLine(item) + description.slice(found.end);
 }
 
+// Markdown-style fence delimiter (``` or ~~~, possibly with a language tag).
+// Metadata blocks can carry fenced examples alongside AsciiDoc ---- blocks.
+const FENCE_DELIMITER = /^(`{3,}|~{3,})/;
+
+/**
+ * Collect the section heading titles in an AsciiDoc block, ignoring lines
+ * inside `----` literal blocks and ```/~~~ fenced blocks. Titles are returned
+ * without their `=` markers so callers can compare sections across heading
+ * levels (the same section may be `==` in a connector description but `===`
+ * in a partial migrated from a page).
+ * @param {string} text
+ * @returns {string[]}
+ */
+function sectionHeadings (text) {
+  if (!text || typeof text !== 'string') return [];
+  const headings = [];
+  let inBlock = false;
+  let fence = null;
+  for (const line of text.split('\n')) {
+    // Layered state: while inside one delimiter kind, the only thing that
+    // matters is its own closer. A fence-like line inside a ---- literal
+    // block (or a ---- line inside a fence) is content, not a delimiter —
+    // treating it as one leaks the state and swallows every later heading.
+    if (inBlock) {
+      if (BLOCK_DELIMITER.test(line)) inBlock = false;
+      continue;
+    }
+    if (fence) {
+      const closer = line.match(FENCE_DELIMITER);
+      if (closer && closer[1][0] === fence) fence = null;
+      continue;
+    }
+    const fenceMatch = line.match(FENCE_DELIMITER);
+    if (fenceMatch) { fence = fenceMatch[1][0]; continue; }
+    if (BLOCK_DELIMITER.test(line)) { inBlock = true; continue; }
+    const m = line.match(/^=+\s+(\S.*)$/);
+    if (m) headings.push(m[1].trim());
+  }
+  return headings;
+}
+
+/**
+ * Report the section headings present in a previously generated metadata
+ * partial that are missing from its regenerated replacement. Regeneration is
+ * authoritative, but published content silently disappearing is how docs lose
+ * examples: a section that lives outside the upstream description's
+ * `== Metadata` block (or was hand-migrated from a page) is dropped without a
+ * trace on the next run. Callers use this to warn before overwriting.
+ * @param {string} oldContent existing partial on disk
+ * @param {string} newContent regenerated partial about to be written
+ * @returns {string[]} heading titles present in oldContent but not newContent
+ */
+function lostMetadataSections (oldContent, newContent) {
+  const newHeadings = new Set(sectionHeadings(newContent));
+  return sectionHeadings(oldContent).filter((h) => !newHeadings.has(h));
+}
+
 module.exports = {
   locateMetadata,
   extractMetadata,
   typeDirFor,
   metadataIncludeLine,
   descriptionWithMetadataInclude,
+  sectionHeadings,
+  lostMetadataSections,
 };

package/tools/redpanda-connect/pr-summary-formatter.js

@@ -122,6 +122,25 @@ function renderBloblangChanges(data, includeVersion = false) {
  * @param {array} draftedConnectors - Array of newly drafted connectors
  * @returns {string} Formatted summary
  */
+/**
+ * Render the content-loss warning block that leads the PR summary. These
+ * warnings exist to stop a merge, so they go at the top of the summary body
+ * rather than into the collapsed workflow log where nobody reads them.
+ * @param {Array<{partial: string, sections: string[]}>} warnings
+ * @returns {string[]} lines (empty when there is nothing to warn about)
+ */
+function renderLostSectionWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) return [];
+  const lines = [];
+  lines.push('> [!WARNING]');
+  lines.push('> **This update deletes previously published metadata sections.** Review before merging: move the content to the connector page or restore it in the upstream description.');
+  for (const w of warnings) {
+    lines.push(`> - \`${w.partial}\` drops: ${w.sections.map((h) => `"${h}"`).join(', ')}`);
+  }
+  lines.push('');
+  return lines;
+}
+
 function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, draftedConnectors = null) {
   const lines = [];
 
@@ -133,6 +152,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
 
   lines.push('<!-- PR_SUMMARY_START -->');
   lines.push('');
+  lines.push(...renderLostSectionWarnings(masterDiff?.lostSectionWarnings));
   lines.push('## Redpanda Connect Documentation Update');
   lines.push('');
   lines.push(`**Multi-Release Update:** ${startVersion} → ${endVersion}`);
@@ -538,6 +558,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   // Header with delimiters for GitHub Action parsing
   lines.push('<!-- PR_SUMMARY_START -->');
   lines.push('');
+  lines.push(...renderLostSectionWarnings(diffData.lostSectionWarnings));
 
   // Detect if this is a master diff
   if (!isMultiVersion && diffData.releases && diffData.totalSummary) {

package/tools/redpanda-connect/rpcn-connector-docs-handler.js

@@ -1130,6 +1130,7 @@ async function handleRpcnConnectorDocs (options) {
 
   console.log('Generating connector partials...')
   let partialsWritten, partialFiles
+  const lostSectionWarnings = []
 
   try {
     const result = await generateRpcnConnectorDocs({
@@ -1147,6 +1148,7 @@ async function handleRpcnConnectorDocs (options) {
     })
     partialsWritten = result.partialsWritten
     partialFiles = result.partialFiles
+    lostSectionWarnings.push(...(result.lostSectionWarnings || []))
   } catch (err) {
     console.error(`Error: Failed to generate partials: ${err.message}`)
     process.exit(1)
@@ -1940,6 +1942,7 @@ async function handleRpcnConnectorDocs (options) {
         fs.unlinkSync(tempDataPath)
         draftsWritten = draftResult.draftsWritten
         draftFiles = draftResult.draftFiles
+        lostSectionWarnings.push(...(draftResult.lostSectionWarnings || []))
       }
     } catch (err) {
       console.error(`Error: Could not draft missing: ${err.message}`)
@@ -1987,8 +1990,12 @@ async function handleRpcnConnectorDocs (options) {
   // Generate PR summary
   try {
     const { printPRSummary } = require('./pr-summary-formatter.js')
-    // Use master diff if available, otherwise use single diff
-    printPRSummary(masterDiff || diffJson, binaryAnalysis, draftFiles, masterDiff ? true : false)
+    // Use master diff if available, otherwise use single diff. Content-loss
+    // warnings ride the diff object so they lead the PR summary body instead
+    // of dying in the collapsed workflow log.
+    const summaryDiff = masterDiff || diffJson
+    if (lostSectionWarnings.length) summaryDiff.lostSectionWarnings = lostSectionWarnings
+    printPRSummary(summaryDiff, binaryAnalysis, draftFiles, masterDiff ? true : false)
   } catch (err) {
     console.error(`Warning: Failed to generate PR summary: ${err.message}`)
   }

package/tools/rpk-docs/generate-plugin-stubs.js

@@ -23,7 +23,7 @@ const { spawnSync } = require('child_process')
  * authoritative: dashified filenames cannot be reversed unambiguously
  * (rpk-ai-llm-provider could be `llm provider` or `llm-provider`).
  * @param {string} partialsDir - Directory of generated .adoc partials
- * @returns {Array<{file: string, title: string}>} Sorted by command path
+ * @returns {Array<{file: string, title: string, description: string|undefined}>} Sorted by command path
  */
 function readPartialTitles(partialsDir) {
   const partials = []
@@ -35,7 +35,11 @@ function readPartialTitles(partialsDir) {
       console.warn(`Warning: no title line in ${file}; skipping`)
       continue
     }
-    partials.push({ file, title: match[1].trim() })
+    // The partial repeats :description: inside its single-source tag, but
+    // Antora resolves page metadata with a header-only parse that never sees
+    // the include — the stub must carry the description in its own header.
+    const description = (content.match(/^:description:[ \t]*(.+)$/m) || [])[1]
+    partials.push({ file, title: match[1].trim(), description: description && description.trim() })
   }
   // Hierarchical order: sort by command words so parents precede children
   partials.sort((a, b) => {
@@ -114,12 +118,14 @@ function inferIncludePrefix(stubDir, plugin) {
  * @param {Object} params
  * @param {string} params.title - Command path (e.g. "rpk ai auth login")
  * @param {string} params.file - Partial filename
+ * @param {string} [params.description] - Meta description from the partial header
  * @param {string} params.includePrefix - Antora resource prefix
  * @param {Array<string>} params.attributes - Page attribute lines
  * @returns {string}
  */
-function renderStub({ title, file, includePrefix, attributes }) {
+function renderStub({ title, file, description, includePrefix, attributes }) {
   const lines = [`= ${title}`]
+  if (description) lines.push(`:description: ${description}`)
   for (const attr of attributes) lines.push(attr)
   lines.push('')
   lines.push(`include::${includePrefix}${file}[tag=single-source]`)