@redpanda-data/docs-extensions-and-macros 5.52.0 → 5.54.0

package/tools/redpanda-release-notes/generate-release-notes.js

@@ -0,0 +1,242 @@
+// Orchestrate release-notes generation: parse the body, render a candidate
+// section, and insert it into the target page under the mechanical guards
+// (GA-only, floor, idempotency). Pure and IO-free: callers pass the page
+// content in and get the updated content back; the doc-tools action does the
+// file read/write, and the workflow fetches the release body.
+
+const { parseReleaseBody } = require('./parse-release-body');
+const { renderReleaseSection, normalizeVersion } = require('./render-release-notes');
+
+const LOG_TAG = '[release-notes]';
+
+/**
+ * Compares two `X.Y.Z` versions numerically.
+ *
+ * @param {string} a - A version (optionally v-prefixed).
+ * @param {string} b - A version (optionally v-prefixed).
+ * @return {number} -1 if a < b, 0 if equal, 1 if a > b.
+ */
+function compareVersions(a, b) {
+  const pa = normalizeVersion(a).split('.').map(Number);
+  const pb = normalizeVersion(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Reports whether a tag is a GA release. Release notes are added for GA tags
+ * only; a prerelease (for example `v26.2.3-rc1`) gets no section.
+ *
+ * @param {string} tag - The release tag.
+ * @return {boolean} True if the tag is a bare `vX.Y.Z` with no prerelease suffix.
+ */
+function isGaTag(tag) {
+  return /^v?\d+\.\d+\.\d+$/.test(String(tag || '').trim());
+}
+
+/**
+ * Reads the `:earliest-tracked-version:` floor attribute from the page.
+ *
+ * @param {string} pageContent - The target page content.
+ * @return {string|null} The bare floor version, or null if the attribute is absent.
+ */
+function readFloor(pageContent) {
+  const m = String(pageContent).match(/^:earliest-tracked-version:\s*(.+?)\s*$/m);
+  return m ? normalizeVersion(m[1]) : null;
+}
+
+/**
+ * Reports whether the page already has a section for this version, so a re-run
+ * for an already-published tag is a no-op rather than a duplicate.
+ *
+ * @param {string} pageContent - The target page content.
+ * @param {string} version - The release version (optionally v-prefixed).
+ * @return {boolean} True if a `== vX.Y.Z (` heading is already present.
+ */
+function hasVersionSection(pageContent, version) {
+  const v = normalizeVersion(version).replace(/[.]/g, '\\.');
+  return new RegExp(`^==\\s+v${v}\\s*\\(`, 'm').test(String(pageContent));
+}
+
+/**
+ * Inserts a rendered section into the page in descending-version order: before
+ * the first existing `== vX.Y.Z` heading OLDER than the section, so a later
+ * backfill of an older release lands below the newer ones already present
+ * rather than jumping to the top. When the section is older than every existing
+ * release, it is inserted AFTER the last version section — before the next
+ * top-level heading following it (the older-versions footer or any other), else
+ * at the end — so a footerless page stays ordered. When there are no version
+ * sections yet, it goes before the older-versions footer, else the first
+ * top-level heading, else the end. The section's own version is read with
+ * multiline matching, so a leading blank line or comment does not hide it.
+ *
+ * @param {string} pageContent - The target page content.
+ * @param {string} sectionText - The rendered section (ending in a newline).
+ * @return {string} The page content with the section inserted.
+ */
+function insertReleaseSection(pageContent, sectionText) {
+  const lines = String(pageContent).split('\n');
+  const sectionLines = sectionText.replace(/\n+$/, '').split('\n');
+  const versionHeading = /^==\s+v(\d+\.\d+\.\d+)\s*\(/;
+  // Multiline: the curated section may open with a blank line or an AsciiDoc
+  // comment, so the heading is not guaranteed to be at character zero.
+  const newVer = (sectionText.match(/^==\s+v(\d+\.\d+\.\d+)\s*\(/m) || [])[1];
+
+  const insertAt = (i) => {
+    // The anchor heading is already preceded by a blank line, so the section
+    // plus one blank separator keeps exactly one blank line on each side.
+    lines.splice(i, 0, ...sectionLines, '');
+    return lines.join('\n');
+  };
+  const appendAtEnd = () => {
+    const tail = lines[lines.length - 1] === '' ? [] : [''];
+    return [...lines, ...tail, ...sectionLines, ''].join('\n');
+  };
+
+  // 1) Descending order: before the first existing section older than this one.
+  //    A new newest release lands at the top this way too.
+  if (newVer) {
+    for (let i = 0; i < lines.length; i++) {
+      const m = lines[i].match(versionHeading);
+      if (m && compareVersions(newVer, m[1]) > 0) return insertAt(i);
+    }
+  }
+
+  // 2) Older than every existing section (or version unknown): sit AFTER the
+  //    last version section — before the next top-level heading that follows it
+  //    (the older-versions footer or any other), else at the end. This keeps a
+  //    footerless page ordered correctly instead of jumping to the top.
+  let lastVersionIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (versionHeading.test(lines[i])) lastVersionIdx = i;
+  }
+  if (lastVersionIdx !== -1) {
+    for (let i = lastVersionIdx + 1; i < lines.length; i++) {
+      if (/^==\s/.test(lines[i])) return insertAt(i);
+    }
+    return appendAtEnd();
+  }
+
+  // 3) No version sections at all: before the older-versions footer, else
+  //    before the first top-level heading, else at the end.
+  const footerIdx = lines.findIndex((l) => /^==\s+Release notes for older versions/i.test(l));
+  if (footerIdx !== -1) return insertAt(footerIdx);
+  const firstHeadingIdx = lines.findIndex((l) => /^==\s/.test(l));
+  if (firstHeadingIdx !== -1) return insertAt(firstHeadingIdx);
+  return appendAtEnd();
+}
+
+/**
+ * Builds a candidate release section from a raw release body.
+ *
+ * @param {Object} options
+ * @param {string} options.body - The raw rpchangelog release body markdown.
+ * @param {string} options.version - The release version (`v26.2.3` or `26.2.3`).
+ * @param {string} options.date - The release date as `YYYY-MM-DD`.
+ * @return {string} The rendered AsciiDoc section.
+ */
+function buildReleaseSection({ body, version, date }) {
+  const { sections } = parseReleaseBody(body);
+  return renderReleaseSection({ version, date, sections });
+}
+
+/**
+ * Asserts that an externally-produced (curated) section carries exactly one
+ * `== vX.Y.Z (date)` heading whose version matches the requested tag. Phase 2
+ * inserts the section verbatim, and the idempotency guard keys off the tag, so
+ * a heading that disagrees with the tag would defeat idempotency and let
+ * reruns insert duplicates. This is malformed input, so it throws (fail loud)
+ * rather than returning a skip.
+ *
+ * @param {string} section - The curated section text.
+ * @param {string} version - The bare `X.Y.Z` version the tag resolved to.
+ * @throws {Error} If the section has zero or several release headings, or one
+ *   whose version does not match.
+ */
+function assertSectionMatchesTag(section, version) {
+  // Count heading-ish lines loosely (any `== v<digit>…`) so a single MALFORMED
+  // heading fails as malformed rather than slipping through as "found 0".
+  const headingish = String(section).match(/^==\s+v\d.*$/gm) || [];
+  if (headingish.length !== 1) {
+    throw new Error(`Curated section must contain exactly one "== vX.Y.Z (YYYY-MM-DD)" heading; found ${headingish.length}.`);
+  }
+  // Validate the complete heading: version, a YYYY-MM-DD date, a closing paren,
+  // and nothing trailing.
+  const m = headingish[0].match(/^==\s+v(\d+\.\d+\.\d+)\s+\(\d{4}-\d{2}-\d{2}\)\s*$/);
+  if (!m) {
+    throw new Error(`Malformed release heading ${JSON.stringify(headingish[0])}; expected "== vX.Y.Z (YYYY-MM-DD)".`);
+  }
+  if (m[1] !== version) {
+    throw new Error(`Curated section heading (v${m[1]}) does not match the requested tag (v${version}).`);
+  }
+}
+
+/**
+ * Generates the updated page content for a release, applying the GA, floor, and
+ * idempotency guards. Never throws for a guard miss: returns a `skipped` status
+ * so the workflow can no-op cleanly.
+ *
+ * Two phases, because the LLM curation step sits between them:
+ * - Phase 1 (pass `body`): build the de-noised candidate section from the raw
+ *   release body. This candidate is the curation step's input.
+ * - Phase 2 (pass `section`): insert the curated section the skill produced.
+ * Exactly one of `body` or `section` is supplied. The guards apply in both
+ * phases, since they depend on the tag and the page, not on the entries.
+ *
+ * @param {Object} options
+ * @param {string} [options.body] - Raw rpchangelog release body (phase 1).
+ * @param {string} [options.section] - A pre-built/curated section to insert (phase 2).
+ * @param {string} options.tag - The release tag (`v26.2.3`).
+ * @param {string} [options.date] - The authored release date as `YYYY-MM-DD` (phase 1 only).
+ * @param {string} options.pageContent - The current target page content.
+ * @return {{status: 'ok'|'skipped', reason?: string, section?: string, content?: string}}
+ */
+function generateReleaseNotes({ body, section, tag, date, pageContent }) {
+  if (body == null && section == null) {
+    throw new Error('Provide either body (phase 1) or section (phase 2).');
+  }
+  if (body != null && section != null) {
+    throw new Error('Provide only one of body or section, not both.');
+  }
+
+  if (!isGaTag(tag)) {
+    return { status: 'skipped', reason: `not a GA tag: ${tag}` };
+  }
+  const version = normalizeVersion(tag);
+
+  const floor = readFloor(pageContent);
+  if (floor && compareVersions(version, floor) <= 0) {
+    return { status: 'skipped', reason: `version ${version} is not newer than the floor ${floor}` };
+  }
+
+  if (hasVersionSection(pageContent, version)) {
+    return { status: 'skipped', reason: `page already has a section for v${version}` };
+  }
+
+  let finalSection;
+  if (section != null) {
+    assertSectionMatchesTag(section, version);
+    finalSection = section;
+  } else {
+    finalSection = buildReleaseSection({ body, version, date });
+  }
+  const content = insertReleaseSection(pageContent, finalSection);
+  return { status: 'ok', section: finalSection, content };
+}
+
+module.exports = {
+  generateReleaseNotes,
+  buildReleaseSection,
+  assertSectionMatchesTag,
+  insertReleaseSection,
+  compareVersions,
+  isGaTag,
+  readFloor,
+  hasVersionSection,
+  LOG_TAG,
+};

package/tools/redpanda-release-notes/parse-release-body.js

@@ -0,0 +1,241 @@
+// Parse a Self-Managed rpchangelog release body into a structured, de-noised model.
+//
+// Input is the raw GitHub Release body a release captain pastes into the
+// streaming-enterprise release (the output of `rpchangelog.py rel`): markdown
+// with `## Features` / `## Bug Fixes` / `## Improvements` sections, each a list
+// of `*` bullets carrying `by @author in [#PR](url)` suffixes and, sometimes,
+// a leading `[#issue](url)` reference.
+//
+// This module does ONLY the deterministic, no-judgment work: split into
+// sections, join wrapped bullet lines, strip source noise, unescape backticks,
+// de-duplicate backport repeats, and normalize category order/case. It does NOT
+// rewrite voice, add `Area::` labels, normalize units, phrase CVEs, or drop
+// bodyless entries — those need editorial judgment and belong to the curation
+// step that runs on the generated page.
+
+const LOG_TAG = '[release-notes]';
+
+// Canonical page order and headings: Features, then Bug fixes, then Improvements
+// (improvements last — they are usually internal detail, least relevant to a
+// reader scanning what changed). This matches rpchangelog's raw source order
+// (Features -> Bug Fixes -> Improvements), so the reorder only recases the
+// "Bug Fixes" heading. It deliberately differs from ADP, which puts fixes last.
+const KIND_FEATURE = 'feature';
+const KIND_IMPROVEMENT = 'improvement';
+const KIND_FIX = 'fix';
+
+const PAGE_ORDER = [KIND_FEATURE, KIND_FIX, KIND_IMPROVEMENT];
+const PAGE_TITLE = {
+  [KIND_FEATURE]: 'Features',
+  [KIND_IMPROVEMENT]: 'Improvements',
+  [KIND_FIX]: 'Bug fixes',
+};
+
+/**
+ * Maps a source `##` heading to a canonical kind by keyword, mirroring ADP's
+ * `sectionKind`. Returns null for a heading that is not one of the three
+ * release-note categories (for example rpchangelog's `--show-extra` `None` /
+ * `Unclear` sections), so the caller can ignore it.
+ *
+ * @param {string} heading - The heading text after the `##` marker.
+ * @return {string|null} One of the KIND_* constants, or null if unrecognized.
+ */
+function sectionKind(heading) {
+  const h = heading.toLowerCase();
+  if (h.includes('feature')) return KIND_FEATURE;
+  if (h.includes('improvement')) return KIND_IMPROVEMENT;
+  if (h.includes('fix')) return KIND_FIX;
+  return null;
+}
+
+/**
+ * Strips the trailing attribution blocks rpchangelog appends to every bullet:
+ * ` by @author` optionally followed by ` in [#PR](url)`, repeated once per PR
+ * when a change was aggregated from several PRs (the backport case). Works from
+ * the end of the string so it only ever removes trailing attribution, never a
+ * legitimate mid-sentence "by".
+ *
+ * @param {string} text - A single bullet's text.
+ * @return {string} The text with trailing attribution removed.
+ */
+function stripAttribution(text) {
+  const trailing = /\s+by\s+@[A-Za-z0-9][A-Za-z0-9._-]*(?:\s+in\s+\[#\d+\]\([^)]*\))?\s*$/i;
+  let out = text;
+  while (trailing.test(out)) {
+    out = out.replace(trailing, '');
+  }
+  return out;
+}
+
+/**
+ * Strips a leading `[#issue](url)` reference that rpchangelog prepends when a
+ * PR body declared `Fixes: #N`. Only the leading reference is removed; links
+ * inside the sentence are left alone.
+ *
+ * @param {string} text - A single bullet's text.
+ * @return {string} The text with a leading issue reference removed.
+ */
+function stripLeadingIssueRef(text) {
+  return text.replace(/^\s*\[#\d+\]\([^)]*\)\s+/, '');
+}
+
+/**
+ * Cleans one bullet: remove attribution and leading issue ref, unescape
+ * backslash-escaped backticks (`\`` -> `` ` ``) that survive from the PR body,
+ * collapse whitespace introduced by joining wrapped lines, and apply the two
+ * context-free mechanical normalizations — AsciiDoc brace escaping and the
+ * standard-mandated unit notation. House-style spelling and voice are left to
+ * the editorial curation step.
+ *
+ * @param {string} raw - The joined raw bullet text.
+ * @return {string} The cleaned entry text.
+ */
+function cleanEntry(raw) {
+  let text = raw.replace(/\s+/g, ' ').trim();
+  text = stripLeadingIssueRef(text);
+  text = stripAttribution(text);
+  text = text.replace(/\\`/g, '`');
+  text = normalizeUnits(text);
+  text = escapeAsciiDocBraces(text);
+  return text.trim();
+}
+
+/**
+ * Rewrites the source's underscore data-size notation to the readable unit the
+ * standard requires (`4_MiB` -> `4 MiB`). Only a digit followed by `_` and a
+ * size unit is touched, so identifiers such as `s3_fifo` or `last_offset_delta`
+ * are left alone.
+ *
+ * @param {string} text - The entry text.
+ * @return {string} The text with data-size units normalized.
+ */
+function normalizeUnits(text) {
+  return text.replace(/(\d)_((?:[KMGT]i?)?B)\b/g, '$1 $2');
+}
+
+/**
+ * Escapes AsciiDoc attribute-reference braces so a literal `{id}` in the source
+ * renders as text rather than an (empty) attribute substitution. Braces already
+ * escaped are left as-is. AsciiDoc substitutes attributes even inside inline
+ * monospace, so this applies everywhere in the entry, including within backticks.
+ *
+ * @param {string} text - The entry text.
+ * @return {string} The text with unescaped braces escaped.
+ */
+function escapeAsciiDocBraces(text) {
+  return text.replace(/(?<!\\)([{}])/g, '\\$1');
+}
+
+/**
+ * Parses a raw rpchangelog release body into de-noised, de-duplicated entries
+ * grouped by canonical category in page order.
+ *
+ * @param {string} body - The raw GitHub Release body markdown.
+ * @return {{sections: Array<{kind: string, title: string, entries: string[]}>}}
+ *   Sections in page order (Features, Bug fixes, Improvements); a category with
+ *   no entries is omitted.
+ */
+function parseReleaseBody(body) {
+  if (typeof body !== 'string' || body.trim() === '') {
+    throw new Error('Release body is empty.');
+  }
+
+  // Drop HTML comments up front (rpchangelog strips them from PR bodies, but a
+  // pasted body may still carry some).
+  const cleaned = body.replace(/<!--[\s\S]*?-->/g, '');
+
+  const buckets = {
+    [KIND_FEATURE]: [],
+    [KIND_IMPROVEMENT]: [],
+    [KIND_FIX]: [],
+  };
+
+  let currentKind = null; // kind of the section we are inside, or null to ignore
+  let current = null; // the bullet text being accumulated, or null between bullets
+
+  const flush = () => {
+    if (current !== null && currentKind && buckets[currentKind]) {
+      const entry = cleanEntry(current);
+      if (entry) buckets[currentKind].push(entry);
+    }
+    current = null;
+  };
+
+  const lines = cleaned.split(/\r?\n/);
+  for (const line of lines) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      flush();
+      currentKind = sectionKind(heading[1]);
+      continue;
+    }
+
+    // The changelog footer ends the release notes; nothing after it is an entry.
+    if (/^\s*\*\*(?:Partial|Full)\s+Changelog\*\*/i.test(line)) {
+      flush();
+      currentKind = null;
+      continue;
+    }
+
+    if (currentKind === null) continue;
+
+    const bullet = line.match(/^\s*[*-]\s+(.*)$/);
+    if (bullet) {
+      flush();
+      current = bullet[1];
+      continue;
+    }
+
+    if (line.trim() === '') {
+      // Blank line: entries in this format are contiguous, so a blank marks the
+      // end of the current bullet rather than a continuation.
+      flush();
+      continue;
+    }
+
+    // A non-blank, non-bullet line continues the current wrapped bullet.
+    if (current !== null) {
+      current += ' ' + line.trim();
+    }
+  }
+  flush();
+
+  const sections = [];
+  for (const kind of PAGE_ORDER) {
+    const seen = new Set();
+    const entries = [];
+    for (const entry of buckets[kind]) {
+      // De-duplicate backport repeats: the same change aggregated from several
+      // PRs yields identical text once attribution is stripped.
+      const key = entry.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      entries.push(entry);
+    }
+    if (entries.length > 0) {
+      sections.push({ kind, title: PAGE_TITLE[kind], entries });
+    }
+  }
+
+  if (sections.length === 0) {
+    console.warn(`${LOG_TAG} WARN: no Features/Improvements/Bug fixes entries found in the release body.`);
+  }
+
+  return { sections };
+}
+
+module.exports = {
+  parseReleaseBody,
+  // Exported for unit tests and reuse.
+  sectionKind,
+  stripAttribution,
+  stripLeadingIssueRef,
+  cleanEntry,
+  normalizeUnits,
+  escapeAsciiDocBraces,
+  PAGE_ORDER,
+  PAGE_TITLE,
+  KIND_FEATURE,
+  KIND_IMPROVEMENT,
+  KIND_FIX,
+};

package/tools/redpanda-release-notes/render-release-notes.js

@@ -0,0 +1,70 @@
+// Render a parsed release model into a candidate AsciiDoc release-notes section.
+//
+// Output is a `== vX.Y.Z (date)` section with `=== Features` / `=== Bug fixes`
+// / `=== Improvements` subsections of plain `*` bullets. Entries are emitted as
+// bullets carrying the de-noised source prose verbatim: this is a CANDIDATE for
+// the curation step, which rewrites voice, converts bullets to `Area::`
+// definition-list items, normalizes units, and phrases CVEs. This renderer adds
+// no `Area::` labels and makes no editorial change.
+
+const LOG_TAG = '[release-notes]';
+
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Normalizes a tag or version to a bare `X.Y.Z` (strips a leading `v`).
+ *
+ * @param {string} version - A version or tag, such as `v26.2.3` or `26.2.3`.
+ * @return {string} The bare `X.Y.Z` version.
+ */
+function normalizeVersion(version) {
+  return String(version || '').trim().replace(/^v/i, '');
+}
+
+/**
+ * Renders one release section as AsciiDoc.
+ *
+ * @param {Object} options
+ * @param {string} options.version - The release version (`v26.2.3` or `26.2.3`).
+ * @param {string} options.date - The release date as `YYYY-MM-DD` (authored; the
+ *   captain confirms it on the PR).
+ * @param {Array<{title: string, entries: string[]}>} options.sections - Sections
+ *   in page order, as produced by parseReleaseBody.
+ * @return {string} The AsciiDoc section, ending with a single trailing newline.
+ * @throws {Error} If the version or date is malformed, or there are no sections.
+ */
+function renderReleaseSection({ version, date, sections }) {
+  const v = normalizeVersion(version);
+  if (!VERSION_RE.test(v)) {
+    throw new Error(`Invalid version: ${JSON.stringify(version)}. Expected X.Y.Z (optionally v-prefixed).`);
+  }
+  if (!DATE_RE.test(String(date || '').trim())) {
+    throw new Error(`Invalid date: ${JSON.stringify(date)}. Expected YYYY-MM-DD.`);
+  }
+  if (!Array.isArray(sections) || sections.length === 0) {
+    throw new Error('No release-note sections to render.');
+  }
+
+  const lines = [`== v${v} (${String(date).trim()})`, ''];
+  for (const section of sections) {
+    if (!section.entries || section.entries.length === 0) continue;
+    lines.push(`=== ${section.title}`, '');
+    for (const entry of section.entries) {
+      lines.push(`* ${entry}`);
+    }
+    lines.push('');
+  }
+
+  // Trim the trailing blank line to exactly one terminating newline.
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines.join('\n') + '\n';
+}
+
+module.exports = {
+  renderReleaseSection,
+  normalizeVersion,
+  VERSION_RE,
+  DATE_RE,
+  LOG_TAG,
+};