@redpanda-data/docs-extensions-and-macros 5.53.0 → 5.55.0

package/extensions/resolve-xrefs-in-attachments.js

@@ -1,6 +1,7 @@
 'use strict'
 
 const { raiseListenerLimit } = require('./util/raise-listener-limit')
+const { escapeHtml } = require('../extension-utils/html-utils')
 
 /**
  * Resolves AsciiDoc xrefs in JSON attachment files to HTML links.
@@ -240,15 +241,3 @@ function resolveXrefsInString (text, contentCatalog, context, logger) {
     }
   })
 }
-
-/**
- * Escape HTML special characters to prevent XSS.
- */
-function escapeHtml (text) {
-  if (!text) return ''
-  return String(text)
-    .replace(/&/g, '&')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-}

package/extensions/url-to-xref.js

@@ -362,6 +362,9 @@ const HEADING_RX = /^(={1,6})\s+(\S.*)$/
  * which still displays sensibly.
  */
 function linkTextFor (label, fragment, page, resolveInclude) {
+  // A trailing ^ opens a URL link in a new window; an xref would print it.
+  // A label that is only ^ counts as no label.
+  label = (label || '').replace(/\^$/, '')
   if (label) return label
   if (!fragment) return ''
   const contents = page && page.contents && page.contents.toString()

package/extensions/util/connect-catalog.js

@@ -2,9 +2,11 @@
 
 // Shared Redpanda Connect catalog helpers.
 //
-// The connect repo publishes its reference content (partials and examples)
-// through a content source that modify-connect-tag-playbook pins to the latest
-// release tag. Catalog data (support level, deprecation, Cloud availability)
+// The connect repo publishes its reference content (partials and examples) as
+// a release asset that modify-connect-tag-playbook adds to the content catalog
+// (or, to preview a connect branch, through a content source with explicit
+// refs). Either way the files carry a connect origin with the ref.
+// Catalog data (support level, deprecation, Cloud availability)
 // must come from the same ref, or the badges and catalog drift from the
 // reference content as soon as connect's main branch changes a flag before a
 // release. This module carries that ref between the extensions and turns the
@@ -13,6 +15,7 @@
 
 // Matches the GitHub URL (with or without .git) and a local clone whose
 // directory is named connect, which is how the source looks in local builds.
+// Files added from the release asset carry the GitHub URL.
 function isConnectSource (url) {
   return typeof url === 'string' && /(^|[/:])(redpanda-data\/)?connect(\.git)?\/?$/.test(url)
 }
@@ -42,7 +45,8 @@ function githubRepoOf (url) {
   return m ? { owner: m[1], repo: m[2] } : null
 }
 
-// The ref of the connect content source as Antora aggregated it. Only refs
+// The ref of the connect files in the content catalog: the release asset tag,
+// or the ref of the connect content source as Antora aggregated it. Only refs
 // that exist on the remote count: a tag, or a branch fetched from the remote.
 // A branch of a local clone may exist only on disk, so it is not used.
 function connectOriginRef (contentCatalog) {
@@ -64,7 +68,8 @@ function connectOriginRef (contentCatalog) {
 const CATALOG_RELATIVE = 'platforms/catalog.json'
 
 // The generated catalog.json in the content catalog, preferring the copy
-// from the connect content source over one another source provides.
+// from connect (the release asset or a connect content source) over one
+// another source provides.
 function findConnectCatalogFile (contentCatalog) {
   if (!contentCatalog || typeof contentCatalog.findBy !== 'function') return null
   const candidates = contentCatalog

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

@@ -0,0 +1,188 @@
+'use strict'
+
+// Reads the Redpanda Connect generated reference docs.
+//
+// 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/**, 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.
+
+const fs = require('fs')
+const path = require('path')
+const zlib = require('zlib')
+
+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', attachments: 'attachment' }
+const DOWNLOAD_ATTEMPTS = 3
+const DOWNLOAD_TIMEOUT_MS = 120000
+
+function assetUrl (tag) {
+  return `https://github.com/${OWNER}/${REPO}/releases/download/${encodeURIComponent(tag)}/${ASSET_NAME}`
+}
+
+// The Antora resource of a path inside the tree, or null for anything outside
+// modules/components/partials, examples, and attachments.
+function toResource (entryPath) {
+  const p = String(entryPath || '').replace(/\\/g, '/').replace(/^(\.\/)+/, '')
+  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
+  return { family: FAMILY_DIRS[m[1]], relative: m[2], path: `modules/components/${m[1]}/${m[2]}` }
+}
+
+// Every regular file in a gzipped tar, as [{ path, contents }]. Throws on a
+// corrupt or truncated archive rather than returning a partial list.
+async function readTarGz (buffer) {
+  let tarBuffer
+  // The real asset unpacks to a few tens of MB. The cap turns a bad asset
+  // into a clear error instead of running the build out of memory.
+  const limit = module.exports.maxUnpackedBytes
+  try {
+    tarBuffer = zlib.gunzipSync(buffer, { maxOutputLength: limit })
+  } catch (error) {
+    if (error.code === 'ERR_BUFFER_TOO_LARGE') {
+      throw new Error(`the archive unpacks to more than ${limit} bytes, which no real reference docs asset does`)
+    }
+    throw new Error(`not a valid gzip archive: ${error.message}`)
+  }
+  // A complete tar ends with two zero blocks. Without them the archive was cut
+  // short at an entry boundary, which the parser alone does not report.
+  const end = tarBuffer.subarray(Math.max(0, tarBuffer.length - 1024))
+  if (tarBuffer.length % 512 !== 0 || end.length < 1024 || end.some((b) => b !== 0)) {
+    throw new Error('not a valid tar archive: missing the end-of-archive marker, so the archive is truncated')
+  }
+  const { Parser } = require('tar')
+  return new Promise((resolve, reject) => {
+    const files = []
+    let failure = null
+    const parser = new Parser({ strict: true })
+    parser.on('entry', (entry) => {
+      if (entry.type !== 'File' && entry.type !== 'OldFile' && entry.type !== 'ContiguousFile') {
+        entry.resume()
+        return
+      }
+      const chunks = []
+      entry.on('data', (chunk) => chunks.push(chunk))
+      entry.on('end', () => files.push({ path: entry.path, contents: Buffer.concat(chunks) }))
+    })
+    const fail = (error) => { if (!failure) failure = error }
+    parser.on('warn', (code, message) => fail(new Error(`not a valid tar archive: ${message}`)))
+    parser.on('error', (error) => fail(new Error(`not a valid tar archive: ${error.message}`)))
+    parser.on('close', () => (failure ? reject(failure) : resolve(files)))
+    try {
+      parser.end(tarBuffer)
+    } catch (error) {
+      fail(new Error(`not a valid tar archive: ${error.message}`))
+      reject(failure)
+    }
+  })
+}
+
+// One download attempt: { status } on an HTTP error, { body } on success.
+// With a token it goes through the releases API, which works whether or not
+// the connect repo is public. The asset endpoint redirects to a short-lived
+// signed URL, which is fetched without the token.
+async function fetchAssetOnce (tag, { fetchImpl, token }) {
+  const timeout = () => AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS)
+  const ua = { 'User-Agent': 'Redpanda Docs' }
+  if (!token) {
+    const response = await fetchImpl(assetUrl(tag), { redirect: 'follow', signal: timeout(), headers: ua })
+    // Read the body here, so a connection that drops or times out
+    // mid-download is retried like a failed request.
+    return response.ok ? { body: Buffer.from(await response.arrayBuffer()) } : { status: response.status, statusText: response.statusText }
+  }
+  const auth = { ...ua, Authorization: `Bearer ${token}` }
+  const api = `https://api.github.com/repos/${OWNER}/${REPO}/releases/tags/${encodeURIComponent(tag)}`
+  const release = await fetchImpl(api, { signal: timeout(), headers: { ...auth, Accept: 'application/vnd.github+json' } })
+  // A token that is expired or lacks access must not break a build that the
+  // public download would serve. GitHub answers 404, not 403, for a repo the
+  // token can't see, so a 404 here falls back too, and is flagged so the
+  // caller can say why when the public download has no asset either.
+  if (release.status === 401 || release.status === 403) return fetchAssetOnce(tag, { fetchImpl, token: null })
+  if (release.status === 404) return { ...(await fetchAssetOnce(tag, { fetchImpl, token: null })), tokenCouldNotSee: true }
+  if (!release.ok) return { status: release.status, statusText: release.statusText }
+  const found = ((await release.json()).assets || []).find((a) => a.name === ASSET_NAME)
+  if (!found) return { status: 404, statusText: 'Not Found' }
+  let response = await fetchImpl(found.url, { redirect: 'manual', signal: timeout(), headers: { ...auth, Accept: 'application/octet-stream' } })
+  if (response.status === 401 || response.status === 403) return fetchAssetOnce(tag, { fetchImpl, token: null })
+  if (response.status >= 300 && response.status < 400 && response.headers.get('location')) {
+    response = await fetchImpl(response.headers.get('location'), { redirect: 'follow', signal: timeout(), headers: ua })
+  }
+  return response.ok ? { body: Buffer.from(await response.arrayBuffer()) } : { status: response.status, statusText: response.statusText }
+}
+
+// Downloads the asset of a release tag. Returns null when the release has no
+// asset (404). Throws on any other failure, after retrying network errors and
+// server errors. Pass the GitHub token when there is one: an unauthenticated
+// download only works while the connect repo is public.
+async function downloadAsset (tag, { fetchImpl = globalThis.fetch, logger, token = null } = {}) {
+  const url = token ? `the ${tag} release asset ${ASSET_NAME} through the GitHub API` : assetUrl(tag)
+  let lastError = null
+  for (let attempt = 1; attempt <= DOWNLOAD_ATTEMPTS; attempt++) {
+    let result
+    try {
+      result = await fetchAssetOnce(tag, { fetchImpl, token })
+    } catch (error) {
+      lastError = new Error(`could not download ${url}: ${error.message}`)
+    }
+    if (result && result.body) return result.body
+    if (result) {
+      if (result.status === 404) {
+        if (result.tokenCouldNotSee && logger) {
+          logger.warn(`The GitHub API found no ${tag} release of ${OWNER}/${REPO} with the GitHub token, and the public download has no ${ASSET_NAME} either. If the repo is private, check that the token has read access to it.`)
+        }
+        return null
+      }
+      lastError = new Error(`could not download ${url}: HTTP ${result.status} ${result.statusText || ''}`.trim())
+      // A client error other than 404 will not change on a retry.
+      if (result.status < 500 && result.status !== 429) break
+    }
+    if (attempt < DOWNLOAD_ATTEMPTS) {
+      if (logger) logger.warn(`${lastError.message}; retrying (${attempt}/${DOWNLOAD_ATTEMPTS - 1})`)
+      await new Promise((resolve) => setTimeout(resolve, module.exports.retryDelayMs * attempt))
+    }
+  }
+  throw lastError
+}
+
+function walk (dir, base, out) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name)
+    const rel = base ? `${base}/${entry.name}` : entry.name
+    if (entry.isDirectory()) walk(abs, rel, out)
+    else if (entry.isFile()) out.push({ path: rel, abspath: abs })
+  }
+  return out
+}
+
+// The files of a local copy of the tree: a directory that contains modules/
+// (or a connect checkout whose docs/ does), or a local .tar.gz of the asset.
+async function readLocal (location) {
+  const resolved = path.resolve(location)
+  let stat
+  try {
+    stat = fs.statSync(resolved)
+  } catch (error) {
+    throw new Error(`${resolved} does not exist`)
+  }
+  if (stat.isFile()) return readTarGz(fs.readFileSync(resolved))
+  let root = resolved
+  if (!fs.existsSync(path.join(root, 'modules')) && fs.existsSync(path.join(root, 'docs', 'modules'))) root = path.join(root, 'docs')
+  if (!fs.existsSync(path.join(root, 'modules', MODULE))) {
+    throw new Error(`${resolved} has no modules/${MODULE} directory`)
+  }
+  return walk(path.join(root, 'modules', MODULE), `modules/${MODULE}`, [])
+    .map((f) => ({ path: f.path, contents: fs.readFileSync(f.abspath) }))
+}
+
+// retryDelayMs is a property so tests can shorten the backoff.
+module.exports = { OWNER, REPO, ASSET_NAME, MODULE, retryDelayMs: 1000, maxUnpackedBytes: 512 * 1024 * 1024, assetUrl, toResource, readTarGz, downloadAsset, readLocal }

package/extensions/util/connect-github.js

@@ -0,0 +1,16 @@
+'use strict'
+
+// The GitHub API client the Redpanda Connect extensions use for release
+// lookups: authenticated when a token is available, retrying transient
+// failures but not rate limits or missing resources.
+
+const { getGitHubApiToken } = require('../../cli-utils/github-token')
+
+async function createGitHub () {
+  const { Octokit } = await import('@octokit/rest')
+  const { retry } = await import('@octokit/plugin-retry')
+  const token = getGitHubApiToken()
+  return new (Octokit.plugin(retry))({ userAgent: 'Redpanda Docs', auth: token || undefined, retry: { doNotRetry: [401, 403, 404, 429] } })
+}
+
+module.exports = { createGitHub }

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

@@ -0,0 +1,10 @@
+'use strict'
+
+// The most recent releases of a repository, newest first, as the GitHub API
+// 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, 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 };