@redpanda-data/docs-extensions-and-macros 5.38.2 → 5.38.4

package/macros/PROPERTY_AND_ENTERPRISE_REFERENCES.adoc

@@ -98,7 +98,9 @@ Two more things come from the same registry:
 * The licensing feature tables on the licensing pages are *generated* from it (`enterprise_features::redpanda[]` and friends), so the tables can never disagree with the registry.
 * `doc-tools validate enterprise-features` compares the registry against the actual license gates in Redpanda's source code and Connect's plugin list. When engineering ships a new license-gated feature, CI fails until someone decides its documented name -- naming stays a human decision, but forgetting is no longer possible.
 
-Like properties, feature links adapt to context: registry entries can carry Kubernetes- and Cloud-specific pages, chosen by the page's environment attributes.
+Like properties, feature links adapt to context: registry entries can carry a Kubernetes-specific page, chosen by the page's environment attributes.
+
+Cloud is different from Kubernetes here, not just another context to adapt to. Redpanda Cloud has no Enterprise Edition license, so on a page in a Cloud component `enterprise:` renders as plain text -- no styling, tooltip, or link -- the same way `prop:` renders a non-`cloud_supported` property as plain code there, and `enterprise_features::[]` renders nothing at all: no table and no admonition, because a note about a macro belongs to the writer, not the reader. Both macros report the Cloud page to the build log according to `enterprise-validate`, naming the page. That includes the Cloud rendering of single-sourced self-managed prose: the check reads the page actually being converted, regardless of which repo the mention was written in. See link:REFERENCE.adoc#cloud-pages[Cloud pages] in the macros reference.
 
 == Where to see all of this working
 

package/macros/REFERENCE.adoc

@@ -85,7 +85,7 @@ The macro target is the feature name, which can contain spaces. Named attributes
 xref::
 Optional Antora resource ID of the feature's documentation page. Overrides the registry entry's link. When neither is set, the term links to the licensing page.
 +
-Registry entries can carry environment-specific pages: on pages with the `env-cloud` attribute the entry's `xref-cloud` is used, on pages with `env-kubernetes` the entry's `xref-kubernetes` is used, and otherwise the entry's default `xref` (the Linux or generic self-managed page). This mirrors the `config_ref` macro's environment awareness.
+Registry entries can carry a Kubernetes-specific page: on pages with the `env-kubernetes` attribute the entry's `xref-kubernetes` is used, and otherwise the entry's default `xref` (the Linux or generic self-managed page). This mirrors the `config_ref` macro's environment awareness. There is no Cloud counterpart -- see <<cloud-pages>>.
 
 text::
 Optional display text override. Use it when the sentence needs different casing or phrasing than the feature name.
@@ -113,6 +113,15 @@ Set to `false` to render the term without a link.
 enterprise-beta-badge::
 Set to `false` to suppress the beta badge in prose. Generated tables always show it. See <<beta-features>>.
 
+[[cloud-pages]]
+=== Cloud pages
+
+Redpanda Cloud has no Enterprise Edition license -- customers never apply or manage one -- so a page in a Cloud component (recognized by its `env-cloud` attribute) has nothing true to say about a license, its expiration, or its restrictions. On such a page the macro renders the target as plain text with no styling, tooltip, or link, skipping registry validation and the release-status checks below entirely, and reports the mention according to `enterprise-validate`.
+
+This also covers the Cloud rendering of single-sourced self-managed prose: `env-cloud` is read from the document being converted, which reflects the page actually being rendered (the Cloud stub page), regardless of which repo the included `enterprise:` mention was written in. See the `prop` macro's <<prop-availability>> for the same mechanism applied to properties.
+
+The `enterprise_features` block macro is affected too: see <<cloud-pages-block>>.
+
 [[release-status]]
 === Release status
 
@@ -195,7 +204,7 @@ enterprise_features::connect[]
 enterprise_features::operator[title=Operator features,heading=What stops working]
 ----
 
-The target is the scope: `redpanda`, `console`, `connect`, `operator`, or `cloud`. Rows render alphabetically by feature name with three columns: the feature name (linked to its documentation page when the entry has an `xref` or `url`), the description, and the expiration or restriction behavior. Named attributes:
+The target is the scope: `redpanda`, `console`, `connect`, or `operator`. Rows render alphabetically by feature name with three columns: the feature name (linked to its documentation page when the entry has an `xref` or `url`), the description, and the expiration or restriction behavior. Named attributes:
 
 title::
 Optional table title override. The default is scope-specific, for example `Enterprise features in Redpanda`.
@@ -203,6 +212,9 @@ Optional table title override. The default is scope-specific, for example `Enter
 heading::
 Optional third-column heading override. The default is `Behavior Upon Expiration` for the `redpanda` scope and `Restrictions Without Valid License` for the other scopes.
 
+[[cloud-pages-block]]
+There is no `cloud` scope: Redpanda Cloud has no Enterprise Edition license, so there is no licensing table to generate for it (see <<cloud-pages>>). Calling this macro from a page in a Cloud component -- directly or through single-sourced self-managed content -- renders nothing: no table and no admonition. The diagnostic goes to the build log, reported according to `enterprise-validate` and naming the page, so it reaches the writer and never the reader.
+
 === Registration
 
 Registered together with the `enterprise` inline macro.

package/macros/enterprise.js

@@ -37,6 +37,15 @@
  * the same way an unreleased feature renders on released docs, because as
  * of that page's version the feature had not shipped yet.
  *
+ * Redpanda Cloud has no Enterprise Edition license -- customers never apply
+ * or manage one -- so both macros treat a page in a Cloud component
+ * (env-cloud) as having no enterprise feature to mark or list at all. The
+ * inline macro renders plain text with no styling, tooltip, or link, and the
+ * block macro renders nothing instead of a licensing table; both report to
+ * the build log according to enterprise-validate. This also covers the Cloud rendering of
+ * single-sourced self-managed prose: the document reflects the page being
+ * converted, regardless of which repo the included prose was written in.
+ *
  * Document or site attributes:
  *
  *   enterprise-validate        'warn' (default) to log unknown feature names,
@@ -62,6 +71,7 @@
 const yaml = require('js-yaml')
 const semver = require('semver')
 const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
+const { isAttributeSet } = require('./prop')
 const logger = require('@antora/logger')('enterprise-macro')
 
 const $enterpriseRegistry = Symbol('$enterpriseRegistry')
@@ -181,6 +191,42 @@ function isPrereleasePage (config, document) {
   return Boolean(componentVersion && componentVersion.prerelease)
 }
 
+/**
+ * Whether the page being converted belongs to a Cloud component.
+ *
+ * Read from the document rather than the component's antora.yml, because the
+ * document is what reflects a Cloud stub page's own attributes even when its
+ * content came from an included self-managed file -- the same mechanism
+ * resolveEntryXref already relied on for env-cloud.
+ *
+ * The value test is prop.js's isAttributeSet, so `env-cloud: false` reads as
+ * unset in both places. The two readers are still not interchangeable:
+ * prop.js asks the CATALOG about the page's component, while this asks the
+ * DOCUMENT being converted, which is the whole point above.
+ * rp-connect-components.js still uses a bare `!== undefined` for env-cloud,
+ * so `env-cloud: false` reads as Cloud there. Worth aligning separately, but
+ * not from here.
+ */
+function isCloudPage (document) {
+  return isAttributeSet(document && document.getAttribute('env-cloud'))
+}
+
+/**
+ * Report an enterprise: mention or enterprise_features::[] call on a page
+ * belonging to a Cloud component. Redpanda Cloud has no Enterprise Edition
+ * license, so nothing about a license, its expiration, or its restrictions
+ * is true there.
+ */
+function reportNoLicenseOnCloud ({ call, mode, filePath }) {
+  if (mode === 'off') return
+  const where = filePath ? ` in ${filePath}` : ''
+  const message =
+    `${call}${where}: this page belongs to a Cloud component, and Redpanda Cloud has no Enterprise Edition license. ` +
+    'Reword the content for Cloud instead of relying on this macro, or wrap it in ifndef::env-cloud[] if the same prose is single-sourced to a non-Cloud page too.'
+  if (mode === 'error') throw new Error(message)
+  logger.warn(message)
+}
+
 /**
  * Render the release-status badge for a registry entry.
  *
@@ -310,14 +356,15 @@ function buildBetaBadgeAsciiDoc (entry) {
   return html ? `pass:[${html}]` : ''
 }
 const REGISTRY_FILENAME = 'enterprise-features.yml'
-const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator', 'cloud']
+// No 'cloud' scope: Redpanda Cloud has no Enterprise Edition license, so
+// there is no licensing table to generate for it. See isCloudPage.
+const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator']
 
 const TABLE_TITLES = {
   redpanda: 'Enterprise features in Redpanda',
   console: 'Enterprise features in Redpanda Console',
   connect: 'Enterprise features in Redpanda Connect',
   operator: 'Enterprise features in the Redpanda Operator',
-  cloud: 'Enterprise features in Redpanda Cloud',
 }
 
 const THIRD_COLUMN_HEADINGS = {
@@ -438,12 +485,15 @@ function reportUnknownFeature ({ feature, mode, registry, filePath }) {
 }
 
 /**
- * Pick the environment-appropriate feature page from a registry entry.
- * Some features have separate documentation for Kubernetes, Linux
- * (self-managed), and Redpanda Cloud. Mirrors the config_ref macro's
- * environment-awareness: the env-cloud and env-kubernetes page attributes
- * select the xref-cloud and xref-kubernetes registry fields, falling back
- * to the default xref.
+ * Pick the environment-appropriate feature page from a registry entry. Some
+ * features have separate documentation for Kubernetes and Linux
+ * (self-managed). Mirrors the config_ref macro's environment-awareness: the
+ * env-kubernetes page attribute selects the xref-kubernetes registry field,
+ * falling back to the default xref.
+ *
+ * No Cloud counterpart: a page in a Cloud component never reaches this
+ * function, because isCloudPage short-circuits the inline macro to plain
+ * text first. See isCloudPage.
  *
  * @param {object} entry - Registry entry.
  * @param {object} document - Asciidoctor document (for env attributes).
@@ -451,7 +501,6 @@ function reportUnknownFeature ({ feature, mode, registry, filePath }) {
  */
 function resolveEntryXref (entry, document) {
   if (!entry) return undefined
-  if (document.getAttribute('env-cloud') !== undefined && entry['xref-cloud']) return entry['xref-cloud']
   if (document.getAttribute('env-kubernetes') !== undefined && entry['xref-kubernetes']) return entry['xref-kubernetes']
   return entry.xref
 }
@@ -577,6 +626,16 @@ function enterpriseInlineMacro (config) {
     self.$option('regexp', /enterprise:([^[]+)\[(|.*?[^\\])\]/)
     self.process(function (parent, target, attributes) {
       const document = parent.getDocument()
+      const mode = document.getAttribute('enterprise-validate', 'warn')
+      const filePath = config && config.file && config.file.src && config.file.src.path
+      if (isCloudPage(document)) {
+        // Redpanda Cloud has no Enterprise Edition license, so there is
+        // nothing to validate against the registry, no status to gate on,
+        // and no styling that would be true here. Bail out before any of
+        // that runs, the same way an unrecognized name bails out below.
+        reportNoLicenseOnCloud({ call: `enterprise:${target}[]`, mode, filePath })
+        return self.createInline(parent, 'quoted', attributes.text || target)
+      }
       let registry
       if (config && config.contentCatalog) {
         registry = loadRegistry(config)
@@ -591,14 +650,12 @@ function enterpriseInlineMacro (config) {
         } else {
           reportUnknownFeature({
             feature: target,
-            mode: document.getAttribute('enterprise-validate', 'warn'),
+            mode,
             registry,
-            filePath: config && config.file && config.file.src && config.file.src.path,
+            filePath,
           })
         }
       }
-      const mode = document.getAttribute('enterprise-validate', 'warn')
-      const filePath = config && config.file && config.file.src && config.file.src.path
       const status = entryStatus(entry, { mode, filePath, contentCatalog: config && config.contentCatalog })
       if (status === STATUS_UNRELEASED && !isPrereleasePage(config, document)) {
         // Documented for an upcoming release, referenced from released docs.
@@ -654,6 +711,23 @@ function enterpriseFeaturesBlockMacro (config) {
       if (!VALID_SCOPES.includes(scope)) {
         throw new Error(`enterprise_features::[] needs a scope of ${VALID_SCOPES.join(', ')} as its target, got '${scope}'.`)
       }
+      const document = parent.getDocument()
+      if (isCloudPage(document)) {
+        // Same reasoning as the inline macro: no license, no table.
+        reportNoLicenseOnCloud({
+          call: `enterprise_features::${scope}[]`,
+          mode: document.getAttribute('enterprise-validate', 'warn'),
+          filePath: config && config.file && config.file.src && config.file.src.path,
+        })
+        // Render NOTHING, not an admonition. The message is internal tooling
+        // language aimed at a writer, and all three docs-site playbooks run
+        // with enterprise-validate: warn, so an admonition here would ship to
+        // docs.redpanda.com and tell a reader about a macro. The diagnostic
+        // belongs in the build log, which reportNoLicenseOnCloud just wrote,
+        // and it names the page. This also makes the inline and block macros
+        // behave the same way on Cloud, which the docs claim.
+        return undefined
+      }
       const registry = config && config.contentCatalog ? loadRegistry(config) : undefined
       if (!registry) {
         warnNoRegistry(config && config.contentCatalog)
@@ -663,13 +737,13 @@ function enterpriseFeaturesBlockMacro (config) {
         title: attributes.title,
         heading: attributes.heading,
         report: {
-          mode: parent.getDocument().getAttribute('enterprise-validate', 'warn'),
+          mode: document.getAttribute('enterprise-validate', 'warn'),
           filePath: config && config.file && config.file.src && config.file.src.path,
           contentCatalog: config && config.contentCatalog,
         },
         // Prerelease docs describe the upcoming release, so they list features
         // that are still only in a release candidate.
-        includeUnreleased: isPrereleasePage(config, parent.getDocument()),
+        includeUnreleased: isPrereleasePage(config, document),
         config,
       })
       // A block anchor before the macro call ([[my-id]]) is consumed into the

package/macros/prop.js

@@ -1012,6 +1012,7 @@ module.exports.propertyAnchor = propertyAnchor
 module.exports.helmValuesPath = helmValuesPath
 module.exports.loadPropertiesFor = loadPropertiesFor
 module.exports.compareTags = compareTags
+module.exports.isAttributeSet = isAttributeSet
 module.exports.isPrerelease = isPrerelease
 module.exports.releaseSeries = releaseSeries
 module.exports.extractHeadingsWithTags = extractHeadingsWithTags

package/package.json

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

package/tools/enterprise-features/verify.js

@@ -14,7 +14,9 @@
 const yaml = require('js-yaml')
 const semver = require('semver')
 
-const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator', 'cloud']
+// Mirrors macros/enterprise.js: no 'cloud' scope, because Redpanda Cloud has
+// no Enterprise Edition license.
+const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator']
 const SOURCE_KINDS = ['core-enum', 'core-property', 'connect-plugin', 'manual']
 
 function finding (level, check, message) {

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')