@redpanda-data/docs-extensions-and-macros 5.38.3 → 5.38.5

package/package.json

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

package/tools/lint-strings/rules/common.js

@@ -127,6 +127,18 @@ function findBareCodeTokens (text, name = null) {
   return found
 }
 
+/**
+ * A short window of `text` around the first occurrence of `needle`, for use in
+ * rule messages so the writer can see the offending phrase in context.
+ */
+function excerpt (text, needle, width = 60) {
+  const at = text.toLowerCase().indexOf(needle.toLowerCase())
+  if (at === -1) return text.slice(0, width)
+  const start = Math.max(0, at - Math.floor(width / 2))
+  const slice = text.slice(start, start + width)
+  return `${start > 0 ? '...' : ''}${slice}${start + width < text.length ? '...' : ''}`
+}
+
 const COMMON_RULES = [
   {
     name: 'empty-description',
@@ -203,6 +215,49 @@ const COMMON_RULES = [
       return issues
     }
   },
+  {
+    name: 'em-dash',
+    description: 'Em dash in prose that ships to docs.redpanda.com',
+    severity: 'warning',
+    check: (decl) => {
+      const text = decl.string || ''
+      if (!text.includes('\u2014')) return []
+      // The docs style guide takes commas, parentheses or a sentence break
+      // instead of em dashes. Reference docs generated from these strings pass
+      // prose through unchanged, so an em dash here is published verbatim, and
+      // correcting it in the generated partial is undone by the next
+      // regeneration.
+      const count = (text.match(/\u2014/g) || []).length
+      return [{
+        message: `Contains ${count} em dash${count === 1 ? '' : 'es'}. Use a comma, parentheses, or a separate sentence: "${excerpt(text, '\u2014')}"`
+      }]
+    }
+  },
+  {
+    name: 'latin-abbreviation',
+    description: 'Latin abbreviation instead of plain English',
+    severity: 'warning',
+    check: (decl) => {
+      const text = decl.string || ''
+      if (!text) return []
+      const issues = []
+      // "e.g." and "i.e." are both ruled out by the style guide's terminology
+      // list. Match the abbreviation only, so "e.g" inside a longer token such
+      // as a URL or an identifier is left alone.
+      for (const [abbr, replacement] of [['e.g.', '"for example"'], ['i.e.', '"that is"']]) {
+        // Boundaries on both sides: the abbreviation must not be part of a
+        // longer token, so a host or identifier that happens to contain it
+        // (https://e.g.example/path) is left alone.
+        const pattern = new RegExp(`(^|[^\\w.])${abbr.replace(/\./g, '\\.')}(?=$|[^\\w])`, 'i')
+        if (pattern.test(text)) {
+          issues.push({
+            message: `Uses "${abbr}". Write ${replacement} instead: "${excerpt(text, abbr)}"`
+          })
+        }
+      }
+      return issues
+    }
+  },
   {
     name: 'unbalanced-backticks',
     description: 'Odd number of backticks ships broken markup',

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

@@ -196,6 +196,33 @@ function mergeOverrides(target, overrides) {
   return target;
 }
 
+/**
+ * House-style regressions that a regeneration would reintroduce.
+ *
+ * Generated prose passes through unchanged by design (see
+ * helpers/renderConnectDescription.js), so when a writer corrects an em dash or
+ * an "e.g." in a published partial instead of upstream, the next regeneration
+ * silently puts it back. Comparing the published text with the incoming text
+ * catches exactly that case: a style issue the published file does not have and
+ * the new one does. Same rules the doc-strings lint applies at the source, so
+ * the two agree on what counts as a regression.
+ *
+ * @param {string} published current on-disk partial
+ * @param {string} incoming regenerated partial
+ * @returns {string[]} rule names whose hit count increases
+ */
+function styleRegressions (published, incoming) {
+  return STYLE_REGRESSION_RULES
+    .filter(({ count }) => count(incoming) > count(published))
+    .map(({ label }) => label);
+}
+
+const STYLE_REGRESSION_RULES = [
+  { label: 'em dash', count: (text) => (text.match(/\u2014/g) || []).length },
+  { label: '"e.g."', count: (text) => (text.match(/(^|[^\w.])e\.g\./gi) || []).length },
+  { label: '"i.e."', count: (text) => (text.match(/(^|[^\w.])i\.e\./gi) || []).length }
+];
+
 /**
  * Resolves $ref references in an object by replacing them with their definitions.
  * Supports JSON Pointer style references like "#/definitions/client_certs".
@@ -448,6 +475,7 @@ async function generateRpcnConnectorDocs(options) {
   let partialsWritten = 0;
   const descriptionReports = [];
   const lostSectionWarnings = [];
+  const styleRegressionWarnings = [];
   // typeDir/name keys handled this run; used after the loop to blank
   // description partials orphaned by a connector deleted upstream.
   const visitedDescriptionPartials = new Set();
@@ -487,6 +515,12 @@ async function generateRpcnConnectorDocs(options) {
       if (fieldsOut.trim()) {
         const fPath = path.join(fieldsOutRoot, type, `${name}.adoc`);
         fs.mkdirSync(path.dirname(fPath), { recursive: true });
+        if (fs.existsSync(fPath)) {
+          const regressions = styleRegressions(fs.readFileSync(fPath, 'utf8'), fieldsOut);
+          if (regressions.length) {
+            styleRegressionWarnings.push({ partial: path.relative(process.cwd(), fPath), issues: regressions });
+          }
+        }
         fs.writeFileSync(fPath, fieldsOut);
         if (!writeFullDrafts) {
           partialsWritten++;
@@ -587,7 +621,12 @@ async function generateRpcnConnectorDocs(options) {
             // because it left the upstream description or because a human
             // added it here -- so warn before overwriting instead of
             // dropping it without a trace.
-            const lost = lostMetadataSections(fs.readFileSync(dPath, 'utf8'), descriptionOut);
+            const publishedDescription = fs.readFileSync(dPath, 'utf8');
+            const regressions = styleRegressions(publishedDescription, descriptionOut);
+            if (regressions.length) {
+              styleRegressionWarnings.push({ partial: path.relative(process.cwd(), dPath), issues: regressions });
+            }
+            const lost = lostMetadataSections(publishedDescription, descriptionOut);
             if (lost.length) {
               lostSectionWarnings.push({ partial: path.relative(process.cwd(), dPath), sections: lost });
               console.warn(
@@ -938,6 +977,7 @@ async function generateRpcnConnectorDocs(options) {
     draftFiles,
     descriptionReports,
     lostSectionWarnings,
+    styleRegressionWarnings,
     orphanSweepSkipped,
     descriptionBackfill
   };

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

@@ -164,6 +164,29 @@ function renderLostSectionWarnings(warnings) {
   return lines;
 }
 
+/**
+ * Render the house-style regression block.
+ *
+ * A regeneration reintroducing an em dash or an "e.g." that the published
+ * partial does not have means the correction was made in the generated file
+ * instead of upstream, so every release undoes it again. Surfacing it in the
+ * summary is what tells the reviewer the diff contains reverted copy, which
+ * the schema delta above never shows.
+ * @param {Array<{partial: string, issues: string[]}>} warnings
+ * @returns {string[]} lines (empty when there is nothing to warn about)
+ */
+function renderStyleRegressionWarnings(warnings) {
+  if (!Array.isArray(warnings) || warnings.length === 0) return [];
+  const lines = [];
+  lines.push('> [!WARNING]');
+  lines.push('> **This update reintroduces house-style issues that the published docs do not have.** The fix belongs upstream in the Connect source, or in `docs-data/overrides.json`: correcting the generated partial is undone by the next regeneration.');
+  for (const w of warnings) {
+    lines.push(`> - \`${w.partial}\` adds: ${w.issues.join(', ')}`);
+  }
+  lines.push('');
+  return lines;
+}
+
 function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, draftedConnectors = null) {
   const lines = [];
 
@@ -176,6 +199,7 @@ function generateMultiVersionPRSummary(masterDiff, binaryAnalysis = null, drafte
   lines.push('<!-- PR_SUMMARY_START -->');
   lines.push('');
   lines.push(...renderLostSectionWarnings(masterDiff?.lostSectionWarnings));
+  lines.push(...renderStyleRegressionWarnings(masterDiff?.styleRegressionWarnings));
   lines.push(...renderDescriptionReports(masterDiff?.descriptionReports));
   lines.push('## Redpanda Connect Documentation Update');
   lines.push('');
@@ -583,6 +607,7 @@ function generatePRSummary(diffData, binaryAnalysis = null, draftedConnectors =
   lines.push('<!-- PR_SUMMARY_START -->');
   lines.push('');
   lines.push(...renderLostSectionWarnings(diffData.lostSectionWarnings));
+  lines.push(...renderStyleRegressionWarnings(diffData.styleRegressionWarnings));
   lines.push(...renderDescriptionReports(diffData.descriptionReports));
 
   // Detect if this is a master diff
@@ -1364,13 +1389,17 @@ function printPRSummary(diffData, binaryAnalysis = null, draftedConnectors = nul
  * something each call site has to remember.
  *
  * @param {object} result generator result
- * @param {{descriptionReports: Array, lostSectionWarnings: Array}} into accumulators, mutated in place
- * @returns {{descriptionReports: Array, lostSectionWarnings: Array}} the same accumulators
+ * @param {{descriptionReports: Array, lostSectionWarnings: Array, styleRegressionWarnings?: Array}} into accumulators, mutated in place
+ * @returns {{descriptionReports: Array, lostSectionWarnings: Array, styleRegressionWarnings: Array}} the same accumulators
  */
 function collectGeneratorReports (result, into) {
   if (!result) return into;
   into.descriptionReports.push(...(result.descriptionReports || []));
   into.lostSectionWarnings.push(...(result.lostSectionWarnings || []));
+  // Tolerate an accumulator created before this key existed, so an older call
+  // site collects what it knows about instead of throwing.
+  if (!into.styleRegressionWarnings) into.styleRegressionWarnings = [];
+  into.styleRegressionWarnings.push(...(result.styleRegressionWarnings || []));
   return into;
 }
 
@@ -1381,5 +1410,6 @@ module.exports = {
   printPRSummary,
   renderDescriptionReports,
   renderLostSectionWarnings,
+  renderStyleRegressionWarnings,
   truncateToSentence
 };

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

@@ -500,7 +500,18 @@ function updateWhatsNew ({ dataDir, oldVersion, newVersion, binaryAnalysis }) {
     const firstMatch = versionHeading.exec(contentWithoutOldSection)
     const insertIdx = firstMatch ? firstMatch.index : contentWithoutOldSection.length
 
-    const updated = contentWithoutOldSection.slice(0, insertIdx) + section + '\n' + contentWithoutOldSection.slice(insertIdx)
+    // Entries in this file are separated by two blank lines. Normalize both
+    // boundaries instead of appending a newline to whatever is already there:
+    // the insertion point already carries the separator that preceded the
+    // previous first entry, so adding to it gave every new entry one more blank
+    // line than the entries below it, which then had to be corrected by hand
+    // after each release. Mirrors the rpk what's-new fix in #285.
+    const before = contentWithoutOldSection.slice(0, insertIdx).replace(/\n*$/, '')
+    const after = contentWithoutOldSection.slice(insertIdx).replace(/^\n*/, '')
+    const entry = section.replace(/^\n*/, '').replace(/\n*$/, '')
+    const updated = after
+      ? `${before}\n\n\n${entry}\n\n\n${after}`
+      : `${before}\n\n\n${entry}\n`
 
     if (startIdx !== -1) {
       console.log(`♻️  whats-new.adoc: replaced section for Version ${diff.comparison.newVersion}`)
@@ -1236,13 +1247,14 @@ async function handleRpcnConnectorDocs (options) {
   let partialsWritten, partialFiles
   const descriptionReports = []
   const lostSectionWarnings = []
+  const styleRegressionWarnings = []
   // Both generator call sites (partials and drafts) feed the same PR summary,
   // so they collect through one function. Pushed inline, the draft call site
   // silently dropped descriptionReports for months: the structure reports for
   // newly drafted connectors, the ones most likely to need an upstream fix,
   // never reached the summary.
   const { collectGeneratorReports } = require('./pr-summary-formatter.js')
-  const collect = (result) => collectGeneratorReports(result, { descriptionReports, lostSectionWarnings })
+  const collect = (result) => collectGeneratorReports(result, { descriptionReports, lostSectionWarnings, styleRegressionWarnings })
 
   try {
     const result = await generateRpcnConnectorDocs({
@@ -2109,22 +2121,24 @@ async function handleRpcnConnectorDocs (options) {
 
   // Generate PR summary
   try {
-    const { printPRSummary, renderLostSectionWarnings, renderDescriptionReports } = require('./pr-summary-formatter.js')
+    const { printPRSummary, renderLostSectionWarnings, renderStyleRegressionWarnings, renderDescriptionReports } = require('./pr-summary-formatter.js')
     // Use master diff if available, otherwise use single diff. Content-loss
     // warnings and structure reports ride the diff object so they land in the
     // PR summary body instead of dying in the collapsed workflow log.
     const summaryDiff = masterDiff || diffJson
     if (summaryDiff) {
       if (lostSectionWarnings.length) summaryDiff.lostSectionWarnings = lostSectionWarnings
+      if (styleRegressionWarnings.length) summaryDiff.styleRegressionWarnings = styleRegressionWarnings
       if (descriptionReports.length) summaryDiff.descriptionReports = descriptionReports
       printPRSummary(summaryDiff, binaryAnalysis, draftFiles, masterDiff ? true : false)
-    } else if (lostSectionWarnings.length || descriptionReports.length) {
+    } else if (lostSectionWarnings.length || styleRegressionWarnings.length || descriptionReports.length) {
       // No diff to summarize (no prior version, or versions match), but this
       // run still produced content-loss warnings or description-structure
       // reports that a reviewer needs to see -- print them on their own
       // instead of losing them because there was nothing to diff against.
       const lines = [
         ...renderLostSectionWarnings(lostSectionWarnings),
+        ...renderStyleRegressionWarnings(styleRegressionWarnings),
         ...renderDescriptionReports(descriptionReports)
       ]
       console.log('\n' + lines.join('\n') + '\n')

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

@@ -1718,7 +1718,15 @@ function formatDescription(desc, customTransformations = null, options = {}) {
 
   // Merge backticked environment variables with adjacent paths
   // e.g., `$HOME`/.local/bin → `$HOME/.local/bin`
-  result = result.replace(/`(\$[A-Z_][A-Z0-9_]*)`(\/[^\s`]+)/g, '`$1$2`')
+  // The continuation excludes a trailing ) . , ; : ! ? so sentence punctuation
+  // immediately after the path (no space) lands outside the code span instead
+  // of being swallowed into it, e.g. "...(defaults to `$HOME/.local/bin)`" or
+  // "...saved in `$HOME/.local/bin.` This" -- both published on
+  // rpk-plugin-install.adoc before this fix. The continuation past the slash
+  // is optional, so a bare trailing slash ($HOME/, $PWD/ -- both real in the
+  // rpk source) still merges into `$HOME/` instead of staying split as
+  // `$HOME`/.
+  result = result.replace(/`(\$[A-Z_][A-Z0-9_]*)`(\/(?:[^\s`]*[^\s`).,;:!?])?)/g, '`$1$2`')
 
   // Add backticks around file paths (but not if already backticked)
   // Must check both the slash and the path aren't already inside backticks