@redpanda-data/docs-extensions-and-macros 5.13.3 → 5.13.5

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-redpanda-version.js

@@ -36,20 +36,45 @@ module.exports = async (github, owner, repo, logger = null) => {
         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);
 
-      // Resolved separately from the stable release: an RC whose tag cannot be
-      // resolved should cost us the RC, not the stable version the caller
-      // probably asked for. Only a missing tag is tolerated; transient errors
-      // still propagate so retryWithBackoff can retry them.
+      // 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) {
@@ -59,7 +84,7 @@ module.exports = async (github, owner, repo, logger = null) => {
             repo,
             ref: `tags/${latestRcRelease.tag_name}`
           });
-          latestRcReleaseCommitHash = rcCommitData.data.object.sha;
+          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.`;
@@ -75,11 +100,11 @@ module.exports = async (github, owner, repo, logger = null) => {
       return {
         latestRedpandaRelease: latestRedpandaRelease ? {
           version: latestRedpandaRelease.tag_name,
-          commitHash: latestRedpandaReleaseCommitHash.substring(0, 7)
+          commitHash: latestRedpandaReleaseCommitHash
         } : null,
         latestRcRelease: resolvedRcRelease ? {
           version: resolvedRcRelease.tag_name,
-          commitHash: latestRcReleaseCommitHash.substring(0, 7)
+          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/macros/enterprise.js

@@ -31,6 +31,12 @@
  * registry is available (for example, outside an Antora build), the macros
  * fall back to unvalidated rendering with a single warning.
  *
+ * A registry entry's `since` field, when set, is checked against the page
+ * being converted, not the newest release: a mention or table row for a
+ * feature whose `since` postdates the page's own version renders unstyled,
+ * the same way an unreleased feature renders on released docs, because as
+ * of that page's version the feature had not shipped yet.
+ *
  * Document or site attributes:
  *
  *   enterprise-validate        'warn' (default) to log unknown feature names,
@@ -55,6 +61,7 @@
 
 const yaml = require('js-yaml')
 const chalk = require('chalk')
+const semver = require('semver')
 const { buildBadgeHtml, DEFAULT_TOOLTIPS } = require('./badge')
 
 const $enterpriseRegistry = Symbol('$enterpriseRegistry')
@@ -211,6 +218,81 @@ function reportUnreleasedFeature ({ feature, mode, filePath }) {
   console.warn(chalk.yellow(message))
 }
 
+/**
+ * Parse a version string into a semver for comparison, or undefined when it
+ * cannot be parsed. Lenient the same way `semver.coerce` is: Redpanda docs
+ * versions are "MAJOR.MINOR", not full semver, so an exact-match parse would
+ * reject every one of them.
+ */
+function coerceVersion (raw) {
+  if (raw === undefined || raw === null) return undefined
+  return semver.coerce(String(raw)) || undefined
+}
+
+/**
+ * Whether a registry entry's `since` version has shipped as of the page
+ * being converted.
+ *
+ * enterprise-features.yml lives in the non-versioned 'shared' component, so
+ * every version branch reads the exact same entry -- unlike property data,
+ * which has one JSON file per release and is checked against the page's
+ * own version (see PROPERTY_AND_ENTERPRISE_REFERENCES.adoc). Without this
+ * check, a feature that ships in 26.3 renders as fully available -- linked,
+ * badge-free, no warning -- on a 24.1 page that predates it by two years.
+ *
+ * Returns true (shipped) when `since` is absent, unparsable, or the page's
+ * own version cannot be determined. That default favors data quality over
+ * release-readiness: unlike an unrecognized `status`, which fails closed
+ * because it is the one mistake that could publish an unreleased feature,
+ * a `since` typo or a build with no page-version context has no such
+ * asymmetry to protect against, so it defaults to not gating rather than
+ * hiding a shipped feature over unrelated bad data. An unparsable `since`
+ * is still reported, the same way an unrecognized `status` is: the failure
+ * mode differs (not gated, instead of gated), but a silent typo is exactly
+ * as easy to miss either way.
+ *
+ * @param {object} entry - Registry entry.
+ * @param {object} [config] - Extension config, used to read the page's own
+ *   version.
+ * @param {object} [report] - {mode, filePath, contentCatalog} to report an
+ *   unparsable since value. Omit to check silently.
+ */
+function isFeatureShippedOnPage (entry, config, report) {
+  const since = entry && entry.since
+  if (since === undefined || since === null || String(since).trim() === '') return true
+  const sinceVersion = coerceVersion(since)
+  if (!sinceVersion) {
+    if (report && report.mode !== 'off') {
+      const where = report.filePath ? ` in ${report.filePath}` : ''
+      const message =
+        `enterprise:${entry.name}[]${where}: registry has since: '${since}', which is not a parsable version, so the since-gating check is skipped and the feature renders as already shipped. ` +
+        'Fix the since value in enterprise-features.yml (e.g. "26.3"), or remove the key if the feature has always been available.'
+      if (report.contentCatalog) warnOnce(report.contentCatalog, `since:${entry.name}`, message)
+      else console.warn(chalk.yellow(message))
+    }
+    return true
+  }
+  const src = config && config.file && config.file.src
+  const pageVersion = src && coerceVersion(src.version)
+  if (!pageVersion) return true
+  return semver.gte(pageVersion, sinceVersion)
+}
+
+/**
+ * Report an inline mention of a feature before its `since` version, on a
+ * page whose own version predates it.
+ */
+function reportFeatureNotYetShipped ({ feature, since, pageVersion, mode, filePath }) {
+  if (mode === 'off') return
+  const where = filePath ? ` in ${filePath}` : ''
+  const message =
+    `enterprise:${feature}[]${where}: '${feature}' is marked since: ${since} in the enterprise features registry, but this page is version ${pageVersion}, which predates it. ` +
+    'The mention renders as plain text with no enterprise styling, tooltip, or link. ' +
+    'Move the mention to a page whose version is at or after the since version, or remove since if the feature covers this version too.'
+  if (mode === 'error') throw new Error(message)
+  console.warn(chalk.yellow(message))
+}
+
 /**
  * The badge for a registry entry, wrapped for use in generated AsciiDoc.
  *
@@ -436,6 +518,8 @@ function buildEnterpriseContent ({ feature, text, xref, url, tooltip, licensingP
  * @param {object} [opts]
  * @param {string} [opts.title] - Table title override.
  * @param {string} [opts.heading] - Third column heading override.
+ * @param {object} [opts.config] - Extension config, used to read the page's
+ *   own version for since-gating (see isFeatureShippedOnPage).
  * @returns {string}
  */
 function buildFeatureTable (features, scope, opts = {}) {
@@ -456,7 +540,13 @@ function buildFeatureTable (features, scope, opts = {}) {
     // did not fail there either.
     .filter((feature) => {
       const status = entryStatus(feature, report)
-      return includeUnreleased || status !== STATUS_UNRELEASED
+      if (!includeUnreleased && status === STATUS_UNRELEASED) return false
+      // since only describes a shipped feature's first version, so it does
+      // not apply to one that has not released at all yet. Silent, like the
+      // unreleased filter above: an older version's table naturally does not
+      // list a feature that did not exist yet on that version, which is not
+      // a writer mistake worth warning about.
+      return status === STATUS_UNRELEASED || isFeatureShippedOnPage(feature, opts.config, report)
     })
     .sort((a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base' }))
   const title = opts.title || TABLE_TITLES[scope]
@@ -517,6 +607,18 @@ function enterpriseInlineMacro (config) {
         reportUnreleasedFeature({ feature, mode, filePath })
         return self.createInline(parent, 'quoted', attributes.text || feature)
       }
+      if (!isFeatureShippedOnPage(entry, config, { mode, filePath, contentCatalog: config && config.contentCatalog })) {
+        // isFeatureShippedOnPage only returns false when entry.since parsed,
+        // so entry is defined here.
+        reportFeatureNotYetShipped({
+          feature,
+          since: entry.since,
+          pageVersion: config && config.file && config.file.src && config.file.src.version,
+          mode,
+          filePath,
+        })
+        return self.createInline(parent, 'quoted', attributes.text || feature)
+      }
       let content = buildEnterpriseContent({
         feature,
         text: attributes.text,
@@ -568,6 +670,7 @@ function enterpriseFeaturesBlockMacro (config) {
         // Prerelease docs describe the upcoming release, so they list features
         // that are still only in a release candidate.
         includeUnreleased: isPrereleasePage(config, parent.getDocument()),
+        config,
       })
       // A block anchor before the macro call ([[my-id]]) is consumed into the
       // macro's id attribute. Re-emit it so crossrefs to the table keep working.
@@ -598,3 +701,4 @@ module.exports.buildFeatureTable = buildFeatureTable
 module.exports.parseRegistry = parseRegistry
 module.exports.resolveEntryXref = resolveEntryXref
 module.exports.resolveTooltipAttribute = resolveTooltipAttribute
+module.exports.isFeatureShippedOnPage = isFeatureShippedOnPage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.13.3",
+  "version": "5.13.5",
   "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.

package/tools/enterprise-features/verify.js

@@ -12,6 +12,7 @@
  */
 
 const yaml = require('js-yaml')
+const semver = require('semver')
 
 const VALID_SCOPES = ['redpanda', 'console', 'connect', 'operator', 'cloud']
 const SOURCE_KINDS = ['core-enum', 'core-property', 'connect-plugin', 'manual']
@@ -58,6 +59,14 @@ function lintRegistry (source) {
     } else if (!feature.source.value || !String(feature.source.value).trim()) {
       findings.push(finding('error', 'registry-lint', `'${name}' has an empty source value; manual entries need a justification.`))
     }
+    if (feature.since !== undefined && feature.since !== null && String(feature.since).trim() !== '') {
+      const since = String(feature.since).trim()
+      // Lenient the same way the enterprise macro's own coerceVersion is:
+      // docs versions are "MAJOR.MINOR", not full semver.
+      if (!semver.coerce(since)) {
+        findings.push(finding('error', 'registry-lint', `'${name}' has since '${since}', which is not a parsable version.`))
+      }
+    }
   }
   return { features: data.features, findings }
 }