@redpanda-data/docs-extensions-and-macros 5.13.2 → 5.13.4

package/cli-utils/version.js

@@ -0,0 +1,73 @@
+'use strict';
+
+/**
+ * Shared `major.minor` derivation.
+ *
+ * Two variants exist because the callers have genuinely different contracts, and
+ * they live side by side here so a third copy never gets written:
+ *
+ * - `getMajorMinor` is strict. It is used by the OpenAPI bundler, where a bad
+ *   version is a build error and a Git branch name (for example, `dev`) must
+ *   pass through untouched.
+ * - `toShortVersion` is lenient. It is used by the Antora version fetcher, where
+ *   a non-semver release channel (for example, `nightly`) must simply not
+ *   produce a `-version-short` attribute rather than throw or leak the raw
+ *   value into the docs.
+ */
+
+// A complete semantic version, optionally with prerelease and build metadata.
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(-[\w.-]+)?(\+[\w.-]+)?$/;
+
+// A leading `<major>.<minor>` pair that is followed by a separator or the end of
+// the string. This also accepts two-part versions such as `26.2`, which Antora
+// components use, and which `SEMVER_PATTERN` rejects.
+const MAJOR_MINOR_PATTERN = /^(\d+)\.(\d+)(?:[.+-]|$)/;
+
+/**
+ * Return the major.minor portion of a semantic version string.
+ *
+ * Accepts a semantic version like `25.1.1` and yields `25.1`. A value that is
+ * not a semantic version (for example, the branch name `dev`) is returned
+ * unchanged.
+ * @param {string} version - Semantic version (for example, `'25.1.1'`) or a branch name.
+ * @returns {string} The `major.minor` string (for example, `'25.1'`) or the input unchanged.
+ * @throws {Error} If `version` is not a non-empty string, lacks major/minor parts, or if major/minor are not numeric.
+ */
+function getMajorMinor(version) {
+  if (!version || typeof version !== 'string') {
+    throw new Error('Version must be a non-empty string');
+  }
+
+  // Only process if valid semver, else return as-is (branch name)
+  if (!SEMVER_PATTERN.test(version)) {
+    return version;
+  }
+  const parts = version.split('.');
+  if (parts.length < 2) {
+    throw new Error(`Invalid version format: ${version}. Expected X.Y.Z format`);
+  }
+  const major = parseInt(parts[0], 10);
+  const minor = parseInt(parts[1], 10);
+  if (isNaN(major) || isNaN(minor)) {
+    throw new Error(`Major and minor versions must be numbers: ${version}`);
+  }
+  return `${major}.${minor}`;
+}
+
+/**
+ * Return the major.minor portion of a version, or `null` when there is none.
+ *
+ * Unlike `getMajorMinor`, this never throws and never returns a value that is
+ * not a `major.minor` pair, so a caller can treat `null` as "no short version
+ * exists for this release channel". Leading zeros are normalized, so `26.02.1`
+ * yields `26.2`. The `v` prefix is not accepted: sanitize it first.
+ * @param {string} version - Version without a `v` prefix (for example, `'26.2.1'`).
+ * @returns {string|null} The `major.minor` string, or `null` for anything else.
+ */
+function toShortVersion(version) {
+  if (!version || typeof version !== 'string') return null;
+  const match = MAJOR_MINOR_PATTERN.exec(version);
+  return match ? `${Number(match[1])}.${Number(match[2])}` : null;
+}
+
+module.exports = { getMajorMinor, toShortVersion };

package/extensions/REFERENCE.adoc

@@ -428,19 +428,53 @@ antora:
 
 This extension fetches the latest release versions from GitHub.
 
+=== Attributes
+
 The following attributes are available to all versions of all Antora components:
 
-`latest-console-version`: The latest release version of Redpanda Console.
-`latest-connect-version`: The latest release version of Redpanda Connect.
-`redpanda-beta-version`: The latest RC version of Redpanda.
-`redpanda-beta-commit`: The commit hash for the latest RC version of Redpanda.
+`latest-console-version`:: The latest release version of Redpanda Console.
+`latest-connect-version`:: The latest release version of Redpanda Connect.
+`redpanda-beta-version`:: The latest RC version of Redpanda.
+`redpanda-beta-commit`:: The commit hash for the latest RC version of Redpanda.
+`console-beta-version`:: The latest beta version of Redpanda Console.
+`operator-beta-version`:: The latest beta version of the Redpanda Operator.
+`helm-beta-version`:: The latest beta version of the Redpanda Helm chart.
+`latest-operator-version`:: The latest release version of the Redpanda Operator. This value keeps its `v` prefix (for example, `v25.1.3`) because pages pass it straight to `helm --version`.
+`latest-redpanda-helm-chart-version`:: The latest release version of the Redpanda Helm chart.
+
+The following attributes are available to the latest version of each Antora component:
+
+`full-version`:: The latest release version of Redpanda. Only ever moves forwards: if the component's `antora.yml` already pins a higher version, that pin wins.
+`latest-redpanda-version`:: The latest release version of Redpanda.
+`latest-release-commit`:: The commit hash for the latest release version of Redpanda.
+
+==== Tag and short-version siblings
+
+Most `<base>-version` attributes in the previous lists also get two siblings.
+`full-version` is the exception and gets neither, because it is set directly
+rather than through the shared helper, and it is the one attribute that only
+ever moves forwards.
+
+`<base>-tag`:: The version exactly as the release publishes it, including any `v` prefix (for example, `latest-redpanda-tag` is `v26.2.1`). Use this for container image tags and Git references. There is no tag attribute for `latest-operator-version` or `latest-redpanda-helm-chart-version`, which are already raw values.
+`<base>-version-short`:: Only the `major.minor` part (for example, `latest-redpanda-version-short` is `26.2` when `latest-redpanda-version` is `26.2.1`). Use this where a page needs the release line rather than an exact patch, such as a download directory or an install pack name.
 
-The following attributes are available to the latest version of the `ROOT` component (Redpanda docs):
+A short attribute is only set when a `major.minor` pair can be derived. Release channels that are not versions, such as `nightly` or `latest`, get a `-version` and a `-tag` but no `-version-short`, so a page never renders a fabricated release line.
+
+==== Seed a fallback in antora.yml
+
+Every attribute here depends on a successful GitHub lookup at build time. If a lookup fails, for example because of a rate limit or a missing token, the attribute is never set and any page that references it renders the attribute name in braces.
+
+To keep a page buildable, seed a soft default in the consuming component's `antora.yml`. The trailing `@` makes it a fallback that the extension overwrites when the fetch succeeds:
+
+[,yaml]
+----
+asciidoc:
+  attributes:
+    latest-redpanda-version: 26.2.1@
+    latest-redpanda-version-short: 26.2@
+----
 
-`full-version`: The latest release version of Redpanda.
-`latest-release-commit`: The commit hash for the latest release version of Redpanda.
-`latest-operator-version`: The latest release version of the Redpanda Operator.
-`latest-redpanda-helm-chart-version`: The latest release version of the Redpanda Helm chart.
+CAUTION: Do not seed `full-version` with a value higher than the current release. `full-version` is the one attribute the extension refuses to move backwards, so a pin that is ahead of the current release stays ahead.
 
 === Environment variables
 

package/extensions/version-fetcher/get-latest-console-version.js

@@ -13,8 +13,13 @@ module.exports = async (github, owner, repo, logger = null) => {
         per_page: 50
       });
 
-      // Filter valid semver tags and sort them to find the highest version
+      // Filter valid semver tags and sort them to find the highest version.
+      // Drafts are dropped first, before the map discards the flag: a draft has
+      // no published Docker image, so returning its tag hands the caller a
+      // CONSOLE_VERSION that cannot be pulled. Drafts are only visible to
+      // callers whose token has push access to the repository.
       const sortedReleases = releases.data
+        .filter(release => !release.draft)
         .map(release => release.tag_name)
         .filter(tag => semver.valid(tag.replace(/^v/, '')))
         .sort((a, b) => semver.rcompare(a.replace(/^v/, ''), b.replace(/^v/, '')));

package/extensions/version-fetcher/get-latest-redpanda-version.js

@@ -26,39 +26,85 @@ module.exports = async (github, owner, repo, logger = null) => {
         release => !release.tag_name.includes('-rc') && !release.draft
       );
 
-      // Find latest RC release (can be draft or not, adjust if needed)
+      // Find latest RC release that is NOT a draft. The primary risk is a draft
+      // outranking the real latest RC (a token with push access sees drafts;
+      // unauthenticated CI does not, which is why this stays invisible there).
+      // A draft's git tag usually already exists, but isn't guaranteed to --
+      // when it's missing, the getRef below 404s, which the caller now handles
+      // per-RC instead of letting it take down the whole lookup.
       const latestRcRelease = sortedReleases.find(
-        release => release.tag_name.includes('-rc')
+        release => release.tag_name.includes('-rc') && !release.draft
       );
 
-      let latestRedpandaReleaseCommitHash = null;
-      if (latestRedpandaRelease) {
-        const commitData = await github.rest.git.getRef({
-          owner,
-          repo,
-          ref: `tags/${latestRedpandaRelease.tag_name}`
-        });
-        latestRedpandaReleaseCommitHash = commitData.data.object.sha;
-      }
+      // A release can exist before its tag is pushed, which is routine for draft
+      // RCs, and GitHub answers the ref lookup with a 404. Losing the commit hash
+      // must not cost us the version: an uncaught 404 here aborts the whole
+      // lookup and every latest-redpanda-* attribute goes unset for the build.
+      const resolveCommitHash = async (release) => {
+        if (!release) return null;
+        try {
+          // Retry the ref lookup on its own. A rate limit or a 5xx is transient
+          // and deserves the attempts; swallowing it immediately turned one
+          // blip into a permanently unset commit attribute. Retrying HERE
+          // rather than letting the error escape is what keeps a exhausted
+          // retry from also costing us the version, which is strictly worse
+          // than losing the commit hash.
+          const commitData = await retryWithBackoff(
+            () => github.rest.git.getRef({ owner, repo, ref: `tags/${release.tag_name}` }),
+            { shouldRetry: isRetryableGitHubError, operationName: `getRef ${release.tag_name}` },
+            logger
+          );
+          return commitData.data.object.sha.substring(0, 7);
+        } catch (error) {
+          const message = `Could not resolve the commit for ${release.tag_name}, so its commit attribute is unset: ${error.status || ''} ${error.message || error}`;
+          if (logger) {
+            logger.warn(message);
+          } else {
+            console.warn(message);
+          }
+          return null;
+        }
+      };
+
+      const latestRedpandaReleaseCommitHash = await resolveCommitHash(latestRedpandaRelease);
 
+      // The RC's tag is resolved separately, not through resolveCommitHash:
+      // a missing tag must exclude the RC entirely (it's an unpublished
+      // draft slipping through by version alone, the bug this guards
+      // against), not just null out its commit hash while still reporting
+      // the draft's version as latest. Only a missing tag (404) is
+      // tolerated; any other error still propagates so retryWithBackoff can
+      // retry it.
       let latestRcReleaseCommitHash = null;
+      let resolvedRcRelease = latestRcRelease;
       if (latestRcRelease) {
-        const rcCommitData = await github.rest.git.getRef({
-          owner,
-          repo,
-          ref: `tags/${latestRcRelease.tag_name}`
-        });
-        latestRcReleaseCommitHash = rcCommitData.data.object.sha;
+        try {
+          const rcCommitData = await github.rest.git.getRef({
+            owner,
+            repo,
+            ref: `tags/${latestRcRelease.tag_name}`
+          });
+          latestRcReleaseCommitHash = rcCommitData.data.object.sha.substring(0, 7);
+        } catch (error) {
+          if (error.status !== 404) throw error;
+          const message = `No git tag for RC release ${latestRcRelease.tag_name}; ignoring it.`;
+          if (logger) {
+            logger.warn(message);
+          } else {
+            console.error(`⚠️  ${message}`);
+          }
+          resolvedRcRelease = null;
+        }
       }
 
       return {
         latestRedpandaRelease: latestRedpandaRelease ? {
           version: latestRedpandaRelease.tag_name,
-          commitHash: latestRedpandaReleaseCommitHash.substring(0, 7)
+          commitHash: latestRedpandaReleaseCommitHash
         } : null,
-        latestRcRelease: latestRcRelease ? {
-          version: latestRcRelease.tag_name,
-          commitHash: latestRcReleaseCommitHash.substring(0, 7)
+        latestRcRelease: resolvedRcRelease ? {
+          version: resolvedRcRelease.tag_name,
+          commitHash: latestRcReleaseCommitHash
         } : null
       };
     },

package/extensions/version-fetcher/set-latest-version.js

@@ -5,13 +5,14 @@ const { raiseListenerLimit } = require('../util/raise-listener-limit')
 module.exports.register = function ({ config }) {
   raiseListenerLimit(this)
   const GetLatestRedpandaVersion = require('./get-latest-redpanda-version');
-  const GetLatestConsoleVersion = require('./get-latest-console-version');
   const GetLatestDockerTag = require('./fetch-latest-docker-tag');
   const GetLatestHelmChartVersionFromOperator = require('./get-latest-redpanda-helm-version-from-operator');
   const GetLatestConnectVersion = require('./get-latest-connect');
   const logger = this.getLogger('set-latest-version-extension');
 
   const { getGitHubToken } = require('../../cli-utils/github-token');
+  // Shared with tools/bundle-openapi.js so there is one major.minor derivation.
+  const { toShortVersion } = require('../../cli-utils/version');
   const token = getGitHubToken();
 
   if (!token) {
@@ -92,7 +93,10 @@ module.exports.register = function ({ config }) {
             asciidoc.attributes['page-component-version-is-prerelease'] = 'true';
           }
 
-          // Set operator and helm chart attributes via helper function
+          // Set operator and helm chart attributes via helper function. These keep
+          // their raw fetched form, including the "v" prefix on
+          // latest-operator-version, because docs pages pass that value straight
+          // to `helm --version`. Only the short sibling is derived.
           updateAttributes(asciidoc, [
             { condition: latestVersions.operator, key: 'latest-operator-version', value: latestVersions.operator?.latestStableRelease },
             { condition: latestVersions.helmChart, key: 'latest-redpanda-helm-chart-version', value: latestVersions.helmChart?.latestStableRelease }
@@ -111,7 +115,9 @@ module.exports.register = function ({ config }) {
           // Special handling for Redpanda RC versions if in beta
           if (latestVersions.redpanda?.latestRcRelease?.version) {
             setVersionAndTagAttributes(asciidoc, 'redpanda-beta', latestVersions.redpanda.latestRcRelease.version, name, version);
-            asciidoc.attributes['redpanda-beta-commit'] = latestVersions.redpanda.latestRcRelease.commitHash;
+            if (latestVersions.redpanda.latestRcRelease.commitHash) {
+              asciidoc.attributes['redpanda-beta-commit'] = latestVersions.redpanda.latestRcRelease.commitHash;
+            }
           }
           if (latestVersions.console?.latestBetaRelease) {
             setVersionAndTagAttributes(asciidoc, 'console-beta', latestVersions.console.latestBetaRelease, name, version);
@@ -126,36 +132,66 @@ module.exports.register = function ({ config }) {
 
         if (!component.latest.asciidoc) component.latest.asciidoc = { attributes: {} };
 
-        // For Redpanda GA version, set both latest-redpanda-version and latest-redpanda-tag if available
-        if (semver.valid(latestVersions.redpanda?.latestRedpandaRelease?.version)) {
-          const currentVersion = component.latest.asciidoc.attributes['full-version'] || '0.0.0';
-          if (semver.gt(latestVersions.redpanda.latestRedpandaRelease.version, currentVersion)) {
-            // Required for backwards compatibility. Some docs still use full-version
-            component.latest.asciidoc.attributes['full-version'] = sanitizeVersion(latestVersions.redpanda.latestRedpandaRelease.version);
-            setVersionAndTagAttributes(component.latest.asciidoc, 'latest-redpanda', latestVersions.redpanda.latestRedpandaRelease.version, component.latest.name, component.latest.version);
-            component.latest.asciidoc.attributes['latest-release-commit'] = latestVersions.redpanda.latestRedpandaRelease.commitHash;
+        // For the Redpanda GA release, always publish latest-redpanda-version,
+        // latest-redpanda-tag, latest-redpanda-version-short and
+        // latest-release-commit. They describe the newest release, so they must
+        // not depend on how the component pins full-version: consuming repos seed
+        // full-version at the current GA (both docs and cloud-docs sit at 26.2.1
+        // today), which made the whole block unreachable and left those
+        // attributes unset until Redpanda shipped something strictly newer.
+        const gaRelease = latestVersions.redpanda?.latestRedpandaRelease;
+        if (semver.valid(gaRelease?.version)) {
+          setVersionAndTagAttributes(component.latest.asciidoc, 'latest-redpanda', gaRelease.version, component.latest.name, component.latest.version);
+          // An unresolvable tag leaves the commit hash null. Leave any antora.yml
+          // fallback in place rather than overwriting it with nothing.
+          if (gaRelease.commitHash) {
+            component.latest.asciidoc.attributes['latest-release-commit'] = gaRelease.commitHash;
+          }
+
+          // Required for backwards compatibility. Some docs still use full-version,
+          // and treat it as a floor, so only ever move it forwards. An unparseable
+          // pin counts as no pin, otherwise semver.gt throws and aborts the run.
+          const pinnedVersion = component.latest.asciidoc.attributes['full-version'];
+          if (!semver.valid(pinnedVersion) || semver.gt(gaRelease.version, pinnedVersion)) {
+            component.latest.asciidoc.attributes['full-version'] = sanitizeVersion(gaRelease.version);
           }
         }
       });
 
-      logger.info('Updated Redpanda documentation versions successfully:');
-      logger.info(`- Redpanda: ${latestVersions.redpanda.latestRedpandaRelease.version}${latestVersions.redpanda.latestRcRelease ? ', beta: ' + latestVersions.redpanda.latestRcRelease.version : ''}`);
-      logger.info(`- Connect: ${latestVersions.connect}`);
-      logger.info(`- Console: ${latestVersions.console.latestStableRelease}${latestVersions.console.latestBetaRelease ? ', beta: ' + latestVersions.console.latestBetaRelease : ''}`);
-      logger.info(`- Operator: ${latestVersions.operator?.latestStableRelease || 'unknown'}${latestVersions.operator?.latestBetaRelease ? ', beta: ' + latestVersions.operator.latestBetaRelease : ''}`);
-      logger.info(`- Helm chart: ${latestVersions.helmChart?.latestStableRelease || 'unknown'}${latestVersions.helmChart?.latestBetaRelease ? ', beta: ' + latestVersions.helmChart.latestBetaRelease : ''}`);
+      // Report what resolved and what did not. A failed lookup resolves to a null
+      // release rather than rejecting, so dereferencing it here used to throw and
+      // replace the real cause with a bare TypeError from the logger.
+      const summary = [
+        ['Redpanda', latestVersions.redpanda?.latestRedpandaRelease?.version, latestVersions.redpanda?.latestRcRelease?.version],
+        ['Connect', latestVersions.connect],
+        ['Console', latestVersions.console?.latestStableRelease, latestVersions.console?.latestBetaRelease],
+        ['Operator', latestVersions.operator?.latestStableRelease, latestVersions.operator?.latestBetaRelease],
+        ['Helm chart', latestVersions.helmChart?.latestStableRelease, latestVersions.helmChart?.latestBetaRelease],
+      ];
+      const unresolved = summary.filter(([, stableVersion]) => !stableVersion).map(([label]) => label);
+      if (unresolved.length) {
+        logger.error(`Could not resolve the latest version of: ${unresolved.join(', ')}. Pages that reference the matching attributes render the attribute name instead of a version unless antora.yml seeds a fallback.`);
+        logger.info('Updated Redpanda documentation versions with gaps:');
+      } else {
+        logger.info('Updated Redpanda documentation versions successfully:');
+      }
+      summary.forEach(([label, stableVersion, betaVersion]) => {
+        logger.info(`- ${label}: ${stableVersion || 'unknown'}${betaVersion ? ', beta: ' + betaVersion : ''}`);
+      });
     } catch (error) {
       logger.error(`Error updating versions: ${error}`);
     }
   });
 
-  // Helper function to set both latest-*version and latest-*tag attributes
+  // Helper function to set latest-*version, latest-*tag, and latest-*version-short attributes
   function setVersionAndTagAttributes(asciidoc, baseName, versionData, name = '', version = '') {
     if (versionData) {
       const versionWithoutPrefix = sanitizeVersion(versionData);
       asciidoc.attributes[`${baseName}-version`] = versionWithoutPrefix; // Without "v" prefix
       asciidoc.attributes[`${baseName}-tag`] = `${versionData}`;
 
+      setShortVersionAttribute(asciidoc, `${baseName}-version`, versionWithoutPrefix);
+
       if (name && version) {
         logger.debug(`Set ${baseName}-version to ${versionWithoutPrefix} and ${baseName}-tag to ${versionData} in ${name} ${version}`);
       } else {
@@ -164,6 +200,19 @@ module.exports.register = function ({ config }) {
     }
   }
 
+  // Helper function to set the major.minor sibling of a *-version attribute (for
+  // example, latest-operator-version v25.1.3 -> latest-operator-version-short
+  // 25.1). Release channels that are not versions (for example, nightly) get no
+  // short attribute rather than a misleading one.
+  function setShortVersionAttribute(asciidoc, versionKey, versionData) {
+    if (!versionData || typeof versionData !== 'string') return;
+    if (!versionKey.endsWith('-version')) return;
+    const shortVersion = toShortVersion(sanitizeVersion(versionData));
+    if (shortVersion) {
+      asciidoc.attributes[`${versionKey}-short`] = shortVersion;
+    }
+  }
+
   // Helper function to sanitize version by removing "v" prefix
   function sanitizeVersion(version) {
     return version.replace(/^v/, '');
@@ -174,6 +223,7 @@ module.exports.register = function ({ config }) {
     mappings.forEach(({ condition, key, value }) => {
       if (condition) {
         asciidoc.attributes[key] = value;
+        setShortVersionAttribute(asciidoc, key, value);
       }
     });
   }

package/package.json

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

package/tools/bundle-openapi.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { execSync, spawnSync } = require('child_process');
 const yaml = require('yaml');
+const { getMajorMinor } = require('../cli-utils/version');
 
 /**
  * Normalize a Git tag into a semantic version string.
@@ -39,36 +40,9 @@ function normalizeTag(tag) {
   return tag;
 }
 
-/**
- * Return the major.minor portion of a semantic version string.
- *
- * Accepts a semantic version like `25.1.1` and yields `25.1`. The special value
- * `'dev'` is returned unchanged.
- * @param {string} version - Semantic version (for example, `'25.1.1'`) or `'dev'`.
- * @returns {string} The `major.minor` string (for example, `'25.1'`) or `'dev'`.
- * @throws {Error} If `version` is not a non-empty string, lacks major/minor parts, or if major/minor are not numeric.
- */
-function getMajorMinor(version) {
-  if (!version || typeof version !== 'string') {
-    throw new Error('Version must be a non-empty string');
-  }
-  
-  // Only process if valid semver, else return as-is (branch name)
-  const semverPattern = /^\d+\.\d+\.\d+(-[\w\.-]+)?(\+[\w\.-]+)?$/;
-  if (!semverPattern.test(version)) {
-    return version;
-  }
-  const parts = version.split('.');
-  if (parts.length < 2) {
-    throw new Error(`Invalid version format: ${version}. Expected X.Y.Z format`);
-  }
-  const major = parseInt(parts[0], 10);
-  const minor = parseInt(parts[1], 10);
-  if (isNaN(major) || isNaN(minor)) {
-    throw new Error(`Major and minor versions must be numbers: ${version}`);
-  }
-  return `${major}.${minor}`;
-}
+// `getMajorMinor` lives in cli-utils/version.js so the Antora version fetcher and
+// this bundler share one major.minor derivation instead of drifting apart.
+// That module also exports the lenient `toShortVersion` variant.
 
 /**
  * Produce a new value with object keys sorted recursively for deterministic output.