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

package/extensions/url-to-xref.js

@@ -35,12 +35,23 @@ const { raiseListenerLimit } = require('./util/raise-listener-limit')
  *   generator wrapped across a line break. An unlabeled URL becomes xref:...[]
  *   so Antora fills in the target page title, except when it carries a
  *   fragment, where link text has to be supplied (see linkTextFor).
+ * - A URL with a fragment is converted only when the anchor exists on the
+ *   target page: a section id, an explicit [[id]], [#id] or anchor:id[]
+ *   anchor, or one of those in a partial the page includes (property
+ *   headings live in generated partials). A URL whose page resolves but whose
+ *   anchor does not stays a URL and is reported as a broken anchor, since an
+ *   xref to it would pass Antora's page check and still land at the top of
+ *   the page.
  * - Targets in the latest version of a component emit an unversioned xref;
  *   targets pinned to an older version emit version@component:module:page.
  * - URLs pointing at a page's former path resolve through the page-aliases the
  *   page declares (see buildUrlMap).
  * - URLs carrying a query string are left raw, because an xref cannot express
  *   one; they are reported at info level rather than as warnings.
+ * - A resolver context may name a localComponent (see
+ *   cli-utils/docs-links-to-xrefs.js, which converts generated pages before
+ *   they are committed): targets in that component are written as
+ *   module:page xrefs, the form the docs repos use for same-component links.
  */
 
 // Rewrites for URL shapes that predate the current docs.redpanda.com site
@@ -80,6 +91,7 @@ module.exports.register = function ({ config = {} }) {
     const unmapped = new Map()
     const withQueryString = new Set()
     const withoutLinkText = new Set()
+    const missingAnchor = new Map()
     const files = contentCatalog
       .getPages((page) => page.out)
       .concat(contentCatalog.findBy({ family: 'partial' }))
@@ -96,11 +108,18 @@ module.exports.register = function ({ config = {} }) {
       }
       for (const url of result.withQueryString) withQueryString.add(url)
       for (const url of result.withoutLinkText) withoutLinkText.add(url)
+      for (const url of result.missingAnchor) {
+        if (!missingAnchor.has(url)) missingAnchor.set(url, new Set())
+        missingAnchor.get(url).add(file.path)
+      }
     }
     if (logUnconverted) {
       for (const [url, pages] of unmapped) {
         logger.warn(`No published page matches ${url} (found in: ${[...pages].join(', ')})`)
       }
+      for (const [url, pages] of missingAnchor) {
+        logger.warn(`Anchor not found on the target page of ${url}; left as a URL (found in: ${[...pages].join(', ')})`)
+      }
     }
     if (withQueryString.size) {
       logger.info(
@@ -111,7 +130,7 @@ module.exports.register = function ({ config = {} }) {
     if (withoutLinkText.size) {
       logger.info(
         `Left ${withoutLinkText.size} docs URL${withoutLinkText.size === 1 ? '' : 's'} with a fragment as raw ` +
-          `link${withoutLinkText.size === 1 ? '' : 's'} (no link text could be resolved from the target page): ` +
+          `link${withoutLinkText.size === 1 ? '' : 's'} (the target page could not be read to check the fragment): ` +
           `${[...withoutLinkText].join(', ')}`
       )
     }
@@ -335,31 +354,49 @@ function resolveUrlPath (urlPath, resolverContext) {
   return undefined
 }
 
-function entryToXref (entry, fragment, label) {
+function entryToXref (entry, fragment, label, localComponent) {
   const versionPrefix = entry.latest || !entry.version ? '' : `${entry.version}@`
-  return `xref:${versionPrefix}${entry.component}:${entry.module}:${entry.relative}${fragment || ''}[${label || ''}]`
+  // Content that is itself part of a component (a page a generator writes into
+  // the docs repo) names a target in that component by module and page only,
+  // the way the docs repos write xrefs by hand. A version-pinned xref still
+  // has to name its component.
+  const componentPrefix = !versionPrefix && localComponent && entry.component === localComponent ? '' : `${entry.component}:`
+  return `xref:${versionPrefix}${componentPrefix}${entry.module}:${entry.relative}${fragment || ''}[${label || ''}]`
 }
 
 // Parsed heading id -> heading text, cached per target file.
 const headingsByFile = new WeakMap()
 const EXPLICIT_ANCHOR_PATTERNS = [
   /^\[\[([\w:.-]+)(?:,.*)?\]\]$/,
-  /^\[#([\w:.-]+)(?:[,.].*)?\]$/,
+  /^\[#([\w:-]+)(?:[,.%].*)?\]$/,
   /^\[id="?([\w:.-]+)"?(?:,.*)?\]$/,
 ]
 const HEADING_RX = /^(={1,6})\s+(\S.*)$/
+const INLINE_ANCHOR_RX = /\[\[([\w:.-]+)(?:,[^\]]*)?\]\]|\banchor:([\w:.-]+)\[/g
+
+/**
+ * The anchors a page publishes, id -> heading text (undefined for an anchor
+ * on something other than a heading), or undefined when the page has no
+ * contents to read. Cached per page.
+ */
+function pageAnchors (page, resolveInclude) {
+  const contents = page && page.contents && page.contents.toString()
+  if (!contents) return undefined
+  let anchors = headingsByFile.get(page)
+  if (!anchors) headingsByFile.set(page, (anchors = pageHeadingIds(contents, page, resolveInclude)))
+  return anchors
+}
 
 /**
  * Returns the link text for a converted URL, or undefined when the URL should
- * be left alone.
+ * be left alone. Callers check the fragment against pageAnchors first.
  *
  * A labeled URL keeps its label, and an unlabeled URL without a fragment gets
  * empty text so that Antora fills in the target page title. An unlabeled URL
  * *with* a fragment has to be given text explicitly: Antora cannot resolve a
  * section title, so `xref:page.adoc#anchor[]` renders the raw resource id as
  * the link text. Prefer the heading the fragment points at, then the page
- * title; if neither can be read, the caller leaves the URL as a raw link,
- * which still displays sensibly.
+ * title (an anchor on a paragraph or table has no heading of its own).
  */
 function linkTextFor (label, fragment, page, resolveInclude) {
   // A trailing ^ opens a URL link in a new window; an xref would print it.
@@ -367,11 +404,19 @@ function linkTextFor (label, fragment, page, resolveInclude) {
   label = (label || '').replace(/\^$/, '')
   if (label) return label
   if (!fragment) return ''
-  const contents = page && page.contents && page.contents.toString()
-  if (!contents) return undefined
-  let headings = headingsByFile.get(page)
-  if (!headings) headingsByFile.set(page, (headings = pageHeadingIds(contents, page, resolveInclude)))
-  return headings.get(fragment.slice(1)) || documentTitle(contents)
+  const anchors = pageAnchors(page, resolveInclude)
+  if (!anchors) return undefined
+  return anchors.get(fragmentId(fragment)) || documentTitle(page.contents.toString())
+}
+
+/** The anchor id of a URL fragment (`#a%2Fb` is `a/b`), without the `#`. */
+function fragmentId (fragment) {
+  const raw = fragment.slice(1)
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    return raw
+  }
 }
 
 // Only the first level of includes is followed, and only this many per page:
@@ -380,7 +425,7 @@ function linkTextFor (label, fragment, page, resolveInclude) {
 const MAX_INCLUDES_SEARCHED = 50
 
 /**
- * Collects the heading ids of a page plus those of the partials it includes.
+ * Collects the anchor ids of a page plus those of the partials it includes.
  * The reference pages that carry most anchor targets are thin wrappers around
  * generated partials — every property heading on the cluster and broker
  * property pages lives in one — and Antora has not resolved includes yet at
@@ -407,10 +452,14 @@ function pageHeadingIds (contents, page, resolveInclude) {
 }
 
 /**
- * Maps every heading id in a page to its text, covering explicit anchors
- * ([[id]], [#id], [id=...]) and the ids Asciidoctor generates from heading
- * text. Id generation is approximated: a mismatch only costs the page-title
- * fallback.
+ * Maps every anchor id in a page to its heading text: the ids Asciidoctor
+ * generates from heading text, explicit block anchors ([[id]], [#id],
+ * [id=...], on a heading or any other block) and inline anchors ([[id]] or
+ * anchor:id[] inside a line). An anchor that is not on a heading maps to
+ * undefined. Id generation is approximated with the docs sites' settings
+ * (idprefix empty, idseparator -); a heading whose id comes out differently
+ * is reported as a missing anchor and its URL is left as written, which
+ * still works.
  */
 function parseHeadingIds (contents) {
   const ids = new Map()
@@ -420,13 +469,18 @@ function parseHeadingIds (contents) {
     const anchor = EXPLICIT_ANCHOR_PATTERNS.reduce((found, pattern) => found || pattern.exec(line), null)
     if (anchor) {
       pendingId = anchor[1]
+      if (!ids.has(pendingId)) ids.set(pendingId, undefined)
       continue
     }
+    for (const inline of line.matchAll(INLINE_ANCHOR_RX)) {
+      const id = inline[1] || inline[2]
+      if (!ids.has(id)) ids.set(id, undefined)
+    }
     const heading = HEADING_RX.exec(line)
     if (heading) {
       const text = sanitizeLinkText(heading[2])
       const id = pendingId || autoId(text)
-      if (id && text && !ids.has(id)) ids.set(id, text)
+      if (id && text && ids.get(id) === undefined) ids.set(id, text)
     }
     if (line) pendingId = undefined
   }
@@ -467,8 +521,9 @@ function autoId (text) {
  * Rewrites every mappable docs URL in content. Returns the updated content,
  * the number of conversions, the internal URLs that matched no published page,
  * the internal URLs that carry a query string (which an xref cannot express),
- * and the internal URLs left alone because no link text could be resolved for
- * their fragment.
+ * the internal URLs left alone because their target page could not be read to
+ * check the fragment, and the internal URLs whose page resolves but whose
+ * anchor is not on it.
  */
 function convertContent (content, resolverContext) {
   const { hostnames, ignore = [] } = resolverContext
@@ -478,6 +533,7 @@ function convertContent (content, resolverContext) {
   const unmapped = []
   const withQueryString = []
   const withoutLinkText = []
+  const missingAnchor = []
   for (const match of scanContentUrls(content)) {
     let url
     try {
@@ -505,17 +561,31 @@ function convertContent (content, resolverContext) {
       unmapped.push(match.url)
       continue
     }
+    if (url.hash) {
+      const anchors = pageAnchors(entry.page, resolverContext.resolveInclude)
+      if (!anchors) {
+        withoutLinkText.push(match.url)
+        continue
+      }
+      // The page resolves but the anchor does not: an xref would pass
+      // Antora's check and still land at the top of the page. Keep the URL,
+      // which the site's broken-anchor checks can still see, and report it.
+      if (!anchors.has(fragmentId(url.hash))) {
+        missingAnchor.push(match.url)
+        continue
+      }
+    }
     const label = linkTextFor(match.label, url.hash, entry.page, resolverContext.resolveInclude)
     if (label === undefined) {
       withoutLinkText.push(match.url)
       continue
     }
-    result += content.slice(cursor, match.start) + entryToXref(entry, url.hash, label)
+    result += content.slice(cursor, match.start) + entryToXref(entry, url.hash, label, resolverContext.localComponent)
     cursor = match.end
     converted++
   }
   result += content.slice(cursor)
-  return { content: result, converted, unmapped, withQueryString, withoutLinkText }
+  return { content: result, converted, unmapped, withQueryString, withoutLinkText, missingAnchor }
 }
 
 module.exports.buildUrlMap = buildUrlMap

package/extensions/util/connect-docs-asset.js

@@ -5,8 +5,9 @@
 // Every connect release (vX.Y.Z, including prereleases) publishes a
 // redpanda-connect-docs.tar.gz asset whose root is `modules/`: the tree that
 // connect's docs generator writes under its docs/ directory. Only
-// modules/components/partials/** and modules/components/examples/** belong to
-// the reference. Releases from before the asset existed answer 404.
+// modules/components/partials/**, modules/components/examples/**, and
+// modules/components/attachments/** (the release's connect-<version>.json)
+// belong to the reference. Releases from before the asset existed answer 404.
 //
 // The same tree can come from a local directory instead (a connect checkout's
 // docs/ after running its generator), or from a local copy of the tarball.
@@ -19,7 +20,7 @@ const OWNER = 'redpanda-data'
 const REPO = 'connect'
 const ASSET_NAME = 'redpanda-connect-docs.tar.gz'
 const MODULE = 'components'
-const FAMILY_DIRS = { partials: 'partial', examples: 'example' }
+const FAMILY_DIRS = { partials: 'partial', examples: 'example', attachments: 'attachment' }
 const DOWNLOAD_ATTEMPTS = 3
 const DOWNLOAD_TIMEOUT_MS = 120000
 
@@ -28,10 +29,10 @@ function assetUrl (tag) {
 }
 
 // The Antora resource of a path inside the tree, or null for anything outside
-// modules/components/partials and modules/components/examples.
+// modules/components/partials, examples, and attachments.
 function toResource (entryPath) {
   const p = String(entryPath || '').replace(/\\/g, '/').replace(/^(\.\/)+/, '')
-  const m = p.match(/^modules\/components\/(partials|examples)\/(.+)$/)
+  const m = p.match(/^modules\/components\/(partials|examples|attachments)\/(.+)$/)
   if (!m || m[2].endsWith('/')) return null
   // A path that climbs out of its directory is not part of the tree.
   if (m[2].split('/').some((segment) => segment === '..' || segment === '')) return null

package/extensions/validate-attributes.js

@@ -7,6 +7,8 @@
 'use strict';
 
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
+const { getTaxonomy } = require('../extension-utils/taxonomy')
+const { checkTaxonomy, createTaxonomyReport, logTaxonomyReport } = require('../extension-utils/taxonomy-categories')
 
 module.exports.register = function ({ config }) {
   raiseListenerLimit(this)
@@ -18,15 +20,22 @@ module.exports.register = function ({ config }) {
     const validCategories = siteCatalog.attributeFile['page-valid-categories'];
     if (!validCategories) return logger.warn('No page-valid-categories attribute found - skipping attribute validation')
     const categoryMap = createCategoryMap(validCategories);
+    // The taxonomy (shared/modules/ROOT/attachments/taxonomy.yml) when the
+    // docs repo has it; null keeps the valid-categories-only behavior.
+    const taxonomy = getTaxonomy({ contentCatalog, siteCatalog, logger });
+    const report = createTaxonomyReport();
     const pages = contentCatalog.findBy({ family: 'page' });
     pages.forEach((page) => {
       let pageCategories = page.asciidoc.attributes['page-categories'];
       if (!pageCategories) return;
       let pageCategoryList = pageCategories.split(',').map(c => c.trim());
-      const validatedCategories = validateCategories(pageCategoryList, page.asciidoc.attributes['page-relative-src-path'], categoryMap, logger);
+      const pageInfo = page.asciidoc.attributes['page-relative-src-path'];
+      if (taxonomy) pageCategoryList = checkTaxonomy(pageCategoryList, { taxonomy, categoryMap, page, report });
+      const validatedCategories = validateCategories(pageCategoryList, pageInfo, categoryMap, logger);
       page.asciidoc.attributes['page-categories'] = validatedCategories
       processEnvironmentAttributes(page, logger);
     })
+    if (taxonomy) logTaxonomyReport(report, logger);
   })
 }
 

package/extensions/version-fetcher/fetch-latest-docker-tag.js

@@ -4,30 +4,50 @@
  * The function separates tags into stable (tags not including "-beta") and beta (tags including "-beta"),
  * sorts each group by their major.minor version in descending order, and returns the top tag from each.
  *
+ * It also returns every stable tag it saw (`stableReleases`), so callers can
+ * pick the newest release of an older line, not just the newest overall.
+ * Docker Hub lists the most recently pushed tags first, so the first page
+ * already holds every line that still gets patches. Pass `maxPages` to reach
+ * further back.
+ *
  * @param {string} dockerNamespace - The Docker Hub namespace (organization or username)
  * @param {string} dockerRepo - The repository name on Docker Hub
  * @param {Object} logger - Optional Antora logger instance for logging
- * @returns {Promise<{ latestStableRelease: string|null, latestBetaRelease: string|null }>}
+ * @param {{ maxPages?: number, fetch?: Function }} options - How many pages of 100 tags to read (default 1), and an optional fetch implementation for tests
+ * @returns {Promise<{ latestStableRelease: string|null, latestBetaRelease: string|null, stableReleases: string[] }>}
  */
-module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
-  const { default: fetch } = await import('node-fetch');
+module.exports = async (dockerNamespace, dockerRepo, logger = null, { maxPages = 1, fetch: fetchImpl } = {}) => {
+  const fetch = fetchImpl || (await import('node-fetch')).default;
 
   try {
-    // Fetch a list of tags from Docker Hub.
-    const url = `https://hub.docker.com/v2/repositories/${dockerNamespace}/${dockerRepo}/tags?page_size=100`;
-    const response = await fetch(url);
+    // Fetch a list of tags from Docker Hub. Only the first page is required:
+    // a later page that fails costs older lines, not the latest release.
+    const results = [];
+    let url = `https://hub.docker.com/v2/repositories/${dockerNamespace}/${dockerRepo}/tags?page_size=100`;
+    for (let page = 1; url && page <= maxPages; page++) {
+      const response = await fetch(url);
 
-    if (!response.ok) {
-      throw new Error(`Docker Hub API responded with status ${response.status}`);
-    }
+      if (!response.ok) {
+        const message = `Docker Hub API responded with status ${response.status}`;
+        if (page === 1) throw new Error(message);
+        if (logger) {
+          logger.warn(`${message} for page ${page} of ${dockerRepo} tags; using the first ${results.length} tags.`);
+        } else {
+          console.warn(`${message} for page ${page} of ${dockerRepo} tags; using the first ${results.length} tags.`);
+        }
+        break;
+      }
 
-    const data = await response.json();
+      const data = await response.json();
+      results.push(...(data.results || []));
+      url = data.next;
+    }
 
     // Regex to capture major and minor version numbers (e.g. "v2.3")
     const versionRegex = /^v(\d+)\.(\d+)/;
 
     // Filter tags to include only those matching the version pattern.
-    let tags = data.results.filter(tag => versionRegex.test(tag.name));
+    let tags = results.filter(tag => versionRegex.test(tag.name));
 
     // For specific repositories (e.g. "redpanda-operator"), you might want to filter out certain versions.
     if (dockerRepo === 'redpanda-operator') {
@@ -61,7 +81,8 @@ module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
 
     return {
       latestStableRelease: latestStableReleaseVersion || null,
-      latestBetaRelease: latestBetaReleaseVersion || null
+      latestBetaRelease: latestBetaReleaseVersion || null,
+      stableReleases: sortedStable.map(tag => tag.name)
     };
 
   } catch (error) {
@@ -72,7 +93,8 @@ module.exports = async (dockerNamespace, dockerRepo, logger = null) => {
     }
     return {
       latestStableRelease: null,
-      latestBetaRelease: null
+      latestBetaRelease: null,
+      stableReleases: []
     };
   }
 };

package/extensions/version-fetcher/get-latest-redpanda-helm-version-from-operator.js

@@ -1,7 +1,17 @@
 /**
- * Fetches the latest Helm chart version from the redpanda-operator repository
- * by converting docker tag format v<major>.<minor>.<patch> to release/v<major>.<minor>.x
- * and checking the Chart.yaml file in that branch.
+ * Fetches the latest Helm chart version for an operator release line from the
+ * redpanda-operator repository.
+ *
+ * A stable chart version comes from the newest stable `charts/redpanda/v<major>.<minor>.*`
+ * tag, because a tag marks a chart that was actually published (what
+ * `helm search repo` reports). A release branch's Chart.yaml can be bumped
+ * ahead of the published chart, so it is only the fallback, and the only
+ * source for beta versions.
+ *
+ * The chart has lived at more than one path over time (for example,
+ * `charts/redpanda/Chart.yaml` on release/v25.1.x and
+ * `charts/redpanda/chart/Chart.yaml` from release/v25.2.x on), so the fallback
+ * tries each known path in order.
  *
  * @param {object} github - The GitHub API client.
  * @param {string} owner - The repository owner.
@@ -13,7 +23,50 @@
  */
 module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag, logger = null) => {
   const yaml = require('js-yaml');
-  const path = 'charts/redpanda/chart/Chart.yaml';
+  const semver = require('semver');
+  const chartPaths = ['charts/redpanda/chart/Chart.yaml', 'charts/redpanda/Chart.yaml'];
+  const warn = (message) => (logger ? logger.warn(message) : console.warn(message));
+  const logError = (message) => (logger ? logger.error(message) : console.error(message));
+
+  // Returns the newest stable published chart version of a release line, or
+  // null when the line has no stable chart tag or the lookup fails.
+  const getChartVersionFromTags = async (major, minor) => {
+    if (!github.git?.listMatchingRefs) return null;
+    const tagPrefix = 'charts/redpanda/v';
+    const prefix = `${tagPrefix}${major}.${minor}.`;
+    try {
+      const { data } = await github.git.listMatchingRefs({ owner, repo, ref: `tags/${prefix}` });
+      let newest = null;
+      for (const { ref } of data || []) {
+        const version = semver.valid(String(ref).slice(`refs/tags/${tagPrefix}`.length));
+        if (!version || semver.prerelease(version)) continue;
+        if (semver.major(version) !== Number(major) || semver.minor(version) !== Number(minor)) continue;
+        if (!newest || semver.gt(version, newest)) newest = version;
+      }
+      return newest;
+    } catch (error) {
+      warn(`Could not list ${prefix}* tags in ${owner}/${repo}: ${error.message || error}`);
+      return null;
+    }
+  };
+
+  // Returns the chart version from the first known Chart.yaml path on a
+  // branch, or null when none of the paths exist there.
+  const getChartVersionFromBranch = async (dockerTag, branchName) => {
+    for (const path of chartPaths) {
+      try {
+        const contentResponse = await github.repos.getContent({ owner, repo, path, ref: branchName });
+        const contentDecoded = Buffer.from(contentResponse.data.content, 'base64').toString('utf8');
+        return yaml.load(contentDecoded)?.version || null;
+      } catch (error) {
+        if (error.status === 404) continue;
+        logError(`Failed to fetch ${path} from branch ${branchName}: ${error.message || error}`);
+        return null;
+      }
+    }
+    warn(`Fetched operator ${dockerTag} from Docker Hub but found no Helm chart for it: no ${chartPaths.join(' or ')} on branch ${branchName} (the branch may not exist yet)`);
+    return null;
+  };
 
   /**
    * Helper function to fetch chart version from a branch derived from a docker tag
@@ -38,44 +91,15 @@ module.exports = async (github, owner, repo, stableDockerTag, betaDockerTag, log
         return null;
       }
 
-      const major = versionMatch[1];
-      const minor = versionMatch[2];
-
-      // Convert to release/v<major>.<minor>.x format
-      const branchName = `release/v${major}.${minor}.x`;
-
-      try {
-
-        // Fetch Chart.yaml from the specified branch
-        const contentResponse = await github.repos.getContent({
-          owner,
-          repo,
-          path,
-          ref: branchName,
-        });
+      const [, major, minor] = versionMatch;
+      const isBeta = /-beta/.test(dockerTag);
 
-        const contentBase64 = contentResponse.data.content;
-        const contentDecoded = Buffer.from(contentBase64, 'base64').toString('utf8');
-        const chartYaml = yaml.load(contentDecoded);
-        const version = chartYaml.version || null;
-        return version;
-      } catch (error) {
-        if (error.status === 404) {
-          // Branch doesn't exist yet - this is expected for unreleased versions
-          if (logger) {
-            logger.warn(`Fetched operator ${dockerTag} from Docker Hub but branch ${branchName} not found in GitHub (source may not be released yet)`);
-          } else {
-            console.warn(`Fetched operator ${dockerTag} from Docker Hub but branch ${branchName} not found in GitHub (source may not be released yet)`);
-          }
-        } else {
-          if (logger) {
-            logger.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
-          } else {
-            console.error(`Failed to fetch Chart.yaml for branch ${branchName}:`, error.message);
-          }
-        }
-        return null;
+      if (!isBeta) {
+        const published = await getChartVersionFromTags(major, minor);
+        if (published) return published;
       }
+
+      return await getChartVersionFromBranch(dockerTag, `release/v${major}.${minor}.x`);
     } catch (error) {
       if (logger) {
         logger.error(`Error processing docker tag ${dockerTag}:`, error.message);

package/extensions/version-fetcher/list-connect-releases.js

@@ -1,10 +1,10 @@
 'use strict'
 
 // The most recent releases of a repository, newest first, as the GitHub API
-// lists them (one page of at most `limit` releases). Each release carries its
+// lists them (the requested page of at most `limit` releases). Each release carries its
 // assets, so a caller can check for an asset without downloading it. Throws
 // when the API is unavailable, so the caller can fall back to git tags.
-module.exports = async (github, owner, repo, limit) => {
-  const { data } = await github.rest.repos.listReleases({ owner, repo, per_page: limit })
+module.exports = async (github, owner, repo, limit, page = 1) => {
+  const { data } = await github.rest.repos.listReleases({ owner, repo, per_page: limit, page })
   return Array.isArray(data) ? data.slice(0, limit) : []
 }

package/extensions/version-fetcher/release-lines.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// Helpers for pinning an attribute to the release line a component version
+// documents, rather than to the newest release overall. The lines come from
+// the fetched release tags themselves, so a new release line is picked up as
+// soon as it ships and nothing needs a manual version map.
+
+const semver = require('semver');
+
+/**
+ * Returns the newest stable tag of each major.minor release line.
+ *
+ * Only plain `v<major>.<minor>.<patch>` tags count. Prereleases are skipped,
+ * and so are the legacy operator tags such as `v2.3.15-24.3.18`, whose suffix
+ * semver reads as a prerelease. Patches are compared as semver, so the result
+ * does not depend on the order the registry lists tags in.
+ *
+ * @param {string[]} tags - Release tags, for example ['v26.1.12', 'v26.1.9'].
+ * @returns {Map<string, string>} Release line (for example '26.1') to its newest tag.
+ */
+function latestStablePerLine (tags) {
+  const lines = new Map();
+  for (const tag of tags || []) {
+    if (typeof tag !== 'string' || !tag.startsWith('v')) continue;
+    const parsed = semver.parse(tag.slice(1));
+    if (!parsed || parsed.prerelease.length || parsed.build.length) continue;
+    const line = `${parsed.major}.${parsed.minor}`;
+    const current = lines.get(line);
+    if (!current || semver.gt(parsed, current.slice(1))) lines.set(line, tag);
+  }
+  return lines;
+}
+
+/**
+ * Returns the release line an Antora component version names, or null when
+ * the version is not a `major.minor` pair (for example, an unversioned
+ * component or a version named after something other than a release).
+ *
+ * @param {string|null|undefined} version - The component version, for example '25.3'.
+ * @returns {string|null}
+ */
+function releaseLineOf (version) {
+  const match = /^(\d+)\.(\d+)$/.exec(String(version ?? ''));
+  return match ? `${Number(match[1])}.${Number(match[2])}` : null;
+}
+
+/**
+ * Returns true when a component version documents an older release line than
+ * the component's latest version. Only those versions are pinned to their own
+ * line. The latest version, prereleases ahead of it, and unversioned
+ * components keep the newest release overall.
+ *
+ * @param {string} version - The component version.
+ * @param {string} latestVersion - The component's latest version.
+ * @returns {boolean}
+ */
+function isOlderReleaseLine (version, latestVersion) {
+  const line = releaseLineOf(version);
+  const latestLine = releaseLineOf(latestVersion);
+  if (!line || !latestLine) return false;
+  return semver.lt(`${line}.0`, `${latestLine}.0`);
+}
+
+module.exports = { latestStablePerLine, releaseLineOf, isOlderReleaseLine };