@redpanda-data/docs-extensions-and-macros 5.35.1 → 5.37.0

package/extensions/kapa-source-groups.js

@@ -0,0 +1,180 @@
+/* Publishes the Kapa source-group mapping to the UI as an AsciiDoc attribute.
+ *
+ * Example use in the playbook:
+ *   antora:
+ *     extensions:
+ *       - require: '@redpanda-data/docs-extensions-and-macros/extensions/kapa-source-groups'
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * docs-ui's get-kapa-source-groups helper needs to turn the page's version
+ * segment into a Kapa source group id, so Ask AI retrieval is scoped to the docs
+ * version the reader is actually on (DOC-1807, DOC-2450). docs-ui does not depend
+ * on this package and must not carry a second copy of the mapping, which would
+ * drift silently. So the mapping travels as an attribute: generated here by
+ * `doc-tools generate kapa-source-groups`, committed to docs-data, and merged
+ * onto every component version at build time.
+ *
+ * Set on every component version rather than only the versioned ones, because the
+ * helper needs the mapping on unversioned pages too. Those resolve to the
+ * mapping's default_segment, and sending no filter there is exactly what caused
+ * DOC-2450: the reporter was on a page with no version of its own.
+ *
+ * DEGRADATION
+ * -----------
+ * Every failure sets nothing and warns. The helper treats a missing attribute as
+ * "send no source group", which is the pre-DOC-2450 behaviour of searching every
+ * version. That is the right way to fail: a wrong group is worse than no group,
+ * because scoping to a group that does not hold the reader's version returns only
+ * Kapa's global sources, silently and with no error.
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { raiseListenerLimit } = require('./util/raise-listener-limit')
+
+const ATTRIBUTE_NAME = 'kapa-source-groups'
+// Sits beside assets/widgets/, which proxy-api-docs.js already fetches from the
+// site origin, so the /api/ path needs no new hostname or auth.
+const ASSET_DIR = 'assets/data'
+const ASSET_FILENAME = 'kapa-source-groups.json'
+const DEFAULT_MAPPING_PATH = path.join(__dirname, '..', 'docs-data', 'kapa-source-groups.json')
+
+/**
+ * Validate the shape the helper depends on, so a malformed mapping is caught at
+ * build time with a named reason rather than producing pages that quietly lose
+ * version scoping.
+ *
+ * @param {*} mapping
+ * @returns {string|null} Reason it is unusable, or null when it is fine
+ */
+function validateMapping (mapping) {
+  if (!mapping || typeof mapping !== 'object') return 'not an object'
+  if (!mapping.segments || typeof mapping.segments !== 'object') return 'no segments object'
+  const segments = Object.keys(mapping.segments)
+  if (segments.length === 0) return 'segments is empty'
+  if (!mapping.default_segment) return 'no default_segment'
+  if (!mapping.segments[mapping.default_segment]) {
+    // The helper falls back to default_segment for every unversioned page, so a
+    // dangling default silently disables scoping across most of the site.
+    return `default_segment "${mapping.default_segment}" is not one of the segments (${segments.join(', ')})`
+  }
+  const missing = segments.filter((s) => !mapping.segments[s] || !mapping.segments[s].group_id)
+  if (missing.length) return `segments missing group_id: ${missing.join(', ')}`
+  return null
+}
+
+module.exports.register = function ({ config = {} } = {}) {
+  const logger = this.getLogger('kapa-source-groups-extension')
+
+  // Three listeners on a generator context that already carries 30+ extensions,
+  // which trips Node's default max-listeners warning. Raised before subscribing,
+  // per __tests__/extensions/raise-listener-limit.test.js.
+  raiseListenerLimit(this)
+  const mappingPath = config.mapping_file ? path.resolve(config.mapping_file) : DEFAULT_MAPPING_PATH
+
+  // Loaded on first use and reused by all three listeners, so a missing or
+  // broken mapping warns once per build rather than once per event.
+  let loaded = false
+  let cached = null
+  function load () {
+    if (loaded) return cached
+    loaded = true
+    cached = readMapping()
+    return cached
+  }
+
+  /** Read + validate, or return null having warned with the consequence. */
+  function readMapping () {
+    let mapping
+    try {
+      if (!fs.existsSync(mappingPath)) {
+        logger.warn(
+          `Kapa source-group mapping not found at ${mappingPath}. Ask AI will search every docs version. ` +
+          'Generate it with: doc-tools generate kapa-source-groups'
+        )
+        return null
+      }
+      mapping = JSON.parse(fs.readFileSync(mappingPath, 'utf8'))
+    } catch (err) {
+      logger.warn(`Could not read the Kapa source-group mapping at ${mappingPath}: ${err.message}. Ask AI will search every docs version.`)
+      return null
+    }
+    const problem = validateMapping(mapping)
+    if (problem) {
+      logger.warn(`Kapa source-group mapping at ${mappingPath} is unusable (${problem}). Ask AI will search every docs version.`)
+      return null
+    }
+    return mapping
+  }
+
+  // site.keys reaches EVERY page, including ones with no component: the 404 page
+  // renders the Ask AI panel but has no page.component or page.componentVersion,
+  // so a component-version attribute alone leaves it unscoped. Its layout pulls
+  // in head and header, both of which already read site.keys, so this is the one
+  // channel that covers it. Set in playbookBuilt because the site UI model is
+  // derived from the playbook.
+  this.on('playbookBuilt', ({ playbook }) => {
+    const mapping = load()
+    if (!mapping) return
+    playbook.site = playbook.site || {}
+    playbook.site.keys = playbook.site.keys || {}
+    if (playbook.site.keys[ATTRIBUTE_NAME] === undefined) {
+      playbook.site.keys[ATTRIBUTE_NAME] = JSON.stringify(mapping)
+    }
+  })
+
+  // The /api/ reference is Bump.sh HTML assembled by docs-site's proxy-api-docs
+  // edge function, which has no Antora page context and cannot import from
+  // node_modules. Publishing the mapping as a site asset lets that function read
+  // the default group at request time, in parallel with the widget fetches it
+  // already does. The alternative -- a UUID pasted into docs-ui's static widget
+  // context or a Netlify env var -- is a second copy of the mapping that drifts
+  // silently the first time a group is recreated.
+  this.on('beforePublish', ({ siteCatalog }) => {
+    const mapping = load()
+    if (!mapping) return
+    siteCatalog.addFile({
+      contents: Buffer.from(JSON.stringify(mapping, null, 2) + '\n', 'utf8'),
+      out: { path: path.join(ASSET_DIR, ASSET_FILENAME) },
+    })
+    logger.info(`Kapa source groups: published ${ASSET_DIR}/${ASSET_FILENAME} for the /api/ proxy.`)
+  })
+
+  this.on('contentClassified', async ({ contentCatalog }) => {
+    const mapping = load()
+    if (!mapping) return
+
+    // Serialised once. The helper accepts a string or an object, but a string is
+    // what survives Antora's attribute handling unchanged, and it keeps the
+    // attribute value comparable between builds.
+    const serialised = JSON.stringify(mapping)
+
+    let versions = 0
+    const components = await contentCatalog.getComponents()
+    for (const component of components) {
+      component.versions.forEach(({ asciidoc }) => {
+        if (!asciidoc) return
+        asciidoc.attributes = asciidoc.attributes || {}
+        // Do not clobber an explicit override: a playbook or antora.yml that
+        // already sets this wins, matching how add-global-attributes.js lets
+        // component attributes beat the shared file.
+        if (asciidoc.attributes[ATTRIBUTE_NAME] === undefined) {
+          asciidoc.attributes[ATTRIBUTE_NAME] = serialised
+        }
+        versions += 1
+      })
+    }
+
+    logger.info(
+      `Kapa source groups: set ${ATTRIBUTE_NAME} on ${versions} component version(s); ` +
+      `${Object.keys(mapping.segments).length} version segments, default "${mapping.default_segment}".`
+    )
+  })
+}
+
+module.exports.validateMapping = validateMapping
+module.exports.ATTRIBUTE_NAME = ATTRIBUTE_NAME
+module.exports.DEFAULT_MAPPING_PATH = DEFAULT_MAPPING_PATH
+module.exports.ASSET_DIR = ASSET_DIR
+module.exports.ASSET_FILENAME = ASSET_FILENAME

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "5.35.1",
+  "version": "5.37.0",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
@@ -92,7 +92,9 @@
     "./macros/enterprise": "./macros/enterprise.js",
     "./macros/prop": "./macros/prop.js",
     "./extensions/property-page-index": "./extensions/property-page-index.js",
-    "./extensions/render-property-descriptions": "./extensions/render-property-descriptions.js"
+    "./extensions/render-property-descriptions": "./extensions/render-property-descriptions.js",
+    "./extensions/kapa-source-groups": "./extensions/kapa-source-groups.js",
+    "./docs-data/kapa-source-groups.json": "./docs-data/kapa-source-groups.json"
   },
   "files": [
     "extensions",
@@ -104,7 +106,9 @@
     "tools",
     "docker-compose",
     "mcp",
-    "docs-data/rpk-overrides.schema.json"
+    "docs-data/rpk-overrides.schema.json",
+    "docs-data/kapa-source-groups.json",
+    "docs-data/kapa-source-groups.schema.json"
   ],
   "license": "ISC",
   "engines": {

package/tools/generate-cli-docs.js

@@ -138,11 +138,19 @@ function parseJSDocComments(sourceFile) {
   // was documented with the first command's prose. That is exactly what
   // happened to `generate migrate-rpcn-descriptions`, which shipped a
   // regenerated section describing migrate-rpcn-metadata.
-  const pattern = /\/\*\*\s*((?:(?!\*\/)[\s\S])*?)\s*\*\/\s*(?:programCli|automation|validation)\s*\.command\(['"]([^'"]+)['"]\)/g;
+  //
+  // The group is captured too, because a command NAME is not unique: the same
+  // name can be registered under both `automation` (generate) and `validation`
+  // (validate). `kapa-source-groups` is, and keying on the bare name alone made
+  // the later registration silently overwrite the earlier, so the
+  // `generate kapa-source-groups` section shipped describing the validate
+  // command, complete with validate examples under a generate usage line.
+  // Same failure as the migrate-rpcn one above, one level up.
+  const pattern = /\/\*\*\s*((?:(?!\*\/)[\s\S])*?)\s*\*\/\s*(programCli|automation|validation)\s*\.command\(['"]([^'"]+)['"]\)/g;
 
   let match;
   while ((match = pattern.exec(content)) !== null) {
-    const [, commentText, commandName] = match;
+    const [, commentText, group, commandName] = match;
 
     // Parse the comment into sections
     const parsed = {
@@ -189,7 +197,12 @@ function parseJSDocComments(sourceFile) {
         .trim();
     }
 
-    comments[commandName] = parsed;
+    // Keyed by the CLI path a reader would type, so `generate x` and
+    // `validate x` cannot collide. The bare name is kept as well, for the
+    // top-level commands registered straight onto programCli.
+    const groupPrefix = { automation: 'generate ', validation: 'validate ', programCli: '' }[group]
+    comments[`${groupPrefix}${commandName}`] = parsed;
+    if (comments[commandName] === undefined) comments[commandName] = parsed;
   }
 
   return comments;
@@ -290,7 +303,9 @@ IMPORTANT: This documentation is auto-generated. Do not edit manually. Run \`npm
     const label = commandPath.join(' ');
     console.log(`${'  '.repeat(level - 1)}Generating docs for: ${label}`);
     const data = parseHelp(getHelpOutput(label));
-    const jsdoc = jsdocs[commandPath[commandPath.length - 1]];
+    // Prefer the full command path, falling back to the bare name so that
+    // commands registered directly on programCli still resolve.
+    const jsdoc = jsdocs[label] || jsdocs[commandPath[commandPath.length - 1]];
     doc += generateCommandDoc(label, data, jsdoc, level);
     for (const child of data.commands) {
       // Commander lists `help [command]` in every group; it is not a command

package/tools/kapa-source-groups/fetch-with-deadline.js

@@ -0,0 +1,33 @@
+/**
+ * fetch() with a deadline that covers the WHOLE exchange, body included.
+ *
+ * The obvious shape, `try { res = await fetch(url, { signal }) } finally
+ * { clearTimeout(timer) }` and then `await res.text()`, only bounds the time to
+ * headers. fetch resolves as soon as headers arrive, the timer is cleared, and a
+ * server that then stalls mid-body holds the caller forever. For a scheduled
+ * check that is a job that never finishes rather than one that exits 2, so
+ * nobody is told and the next run queues behind it.
+ *
+ * @param {typeof fetch} fetchImpl
+ * @param {string} url
+ * @param {RequestInit} init - Merged with the abort signal
+ * @param {number} timeoutMs
+ * @param {(res: Response, signal: AbortSignal) => Promise<*>} read
+ *   Consumes the body while the timer is still armed. Return null for a
+ *   response you do not want to read (a non-OK status, say) so the caller can
+ *   inspect res.status first.
+ * @returns {Promise<{res: Response, body: *}>}
+ */
+async function fetchWithDeadline (fetchImpl, url, init, timeoutMs, read) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const res = await fetchImpl(url, { ...init, signal: controller.signal })
+    const body = await read(res, controller.signal)
+    return { res, body }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+module.exports = { fetchWithDeadline }

package/tools/kapa-source-groups/generate-kapa-source-groups.js

@@ -0,0 +1,319 @@
+// Standalone module to read Kapa source groups and emit the mapping that tells
+// each docs surface which group to scope a query to.
+// Usage: generateKapaSourceGroups({ apiKey, projectId, defaultSegment })
+//
+// WHY THIS EXISTS
+// ---------------
+// Kapa indexes several separately crawled copies of the Self-Managed docs (one
+// per version). Without scoping, a reader on a 25.1 page gets answers drawn from
+// any of them: one measured call returned the same architecture page six times at
+// six different versions. Source groups fix that at retrieval time, but the group
+// UUIDs live in the Kapa dashboard while the version list lives in Antora, so
+// something has to join the two. This generator is that join.
+//
+// The Kapa side is read-only by design: Kapa publishes no endpoint to create a
+// group or assign a source to one ("we do not provide an API endpoint for
+// uploading or managing sources"). So this reads the state a human created in the
+// dashboard and turns it into a committed artifact the build and the browser can
+// both consume. It never mutates Kapa.
+//
+// RESPONSE SHAPES (observed live 2026-09-04, project 97f44223)
+// -----------------------------------------------------------
+// GET /ingestion/v1/projects/:id/source-groups/
+//   { count, next, previous, results: [
+//       { id, name, type: 'product'|'version', description, sub_groups: [...], created_at, updated_at }
+//   ]}
+//
+// GET /ingestion/v1/projects/:id/sources/
+//   { count, next, previous, results: [
+//       { id, name, type: 'scrape'|'openapi'|'custom_qa'|'youtube'|..., source_groups: [...], ... }
+//   ]}
+//
+// Kapa's published OpenAPI schema declares BOTH `sub_groups` and `source_groups`
+// as `"type":"string"`. That is a spec bug: live responses return arrays. The
+// parsers below accept an array, a single object, a comma-separated string, or
+// null, so a schema fix on Kapa's side cannot break us either way.
+//
+// "GLOBAL" IS NOT A GROUP
+// ----------------------
+// The dashboard shows a "Global sources" row, and Kapa's own docs call it "a
+// special Global group that exists by default" with an ID. Both are misleading.
+// The API returns no such group, and an unassigned source reports
+// `source_groups: []`. Global is simply "assigned to no group". Assigning a
+// source to a version group is what takes it out of the global set; unassigned
+// sources stay global and are returned alongside whichever group a query scopes
+// to. That is what keeps Agentic Data Plane content reachable from every page.
+
+const { KAPA_API_BASE, kapaAuthHeaders } = require('../../cli-utils/kapa-credentials')
+const { fetchWithDeadline } = require('./fetch-with-deadline')
+
+/**
+ * Raised when Kapa's group tree itself is unusable: no groups, no version
+ * sub-groups, a duplicated group name, a group with no sources, or the default
+ * segment's group missing.
+ *
+ * `generate` treats all of these as fatal and names the reason, because every
+ * one of them describes a change someone made in the dashboard that the mapping
+ * cannot represent. The scheduled `validate` command does not call `generate`;
+ * it reads the sources endpoint directly and reports its own four gaps.
+ */
+class KapaGroupTreeError extends Error {
+  constructor (message) {
+    super(message)
+    this.name = 'KapaGroupTreeError'
+    this.code = 'KAPA_GROUP_TREE'
+  }
+}
+
+const REQUEST_TIMEOUT_MS = 15000
+
+/**
+ * Normalise the fields Kapa mis-declares as strings. Accepts an array, a single
+ * object, a comma-separated string of ids, or null/undefined.
+ *
+ * @param {*} value
+ * @returns {Array<object|string>}
+ */
+function toList (value) {
+  if (Array.isArray(value)) return value
+  if (value === null || value === undefined || value === '') return []
+  if (typeof value === 'string') {
+    return value.split(',').map((s) => s.trim()).filter(Boolean)
+  }
+  if (typeof value === 'object') return [value]
+  return []
+}
+
+/** Pull an id out of either an object or a bare id string. */
+function idOf (entry) {
+  if (typeof entry === 'string') return entry
+  return entry && typeof entry === 'object' ? entry.id || null : null
+}
+
+/**
+ * Fetch every page of a Kapa list endpoint.
+ *
+ * Both ingestion endpoints return count/next/previous but declare NO pagination
+ * query parameters, so the only supported way through is to follow `next`. At
+ * 22 sources this project fits in one page today; follow the cursor anyway so it
+ * does not quietly truncate later.
+ *
+ * @param {string} url - Absolute first-page URL
+ * @param {string} apiKey
+ * @param {Function} [fetchImpl] - Injectable for tests
+ * @returns {Promise<object[]>} Concatenated results
+ */
+async function fetchAllPages (url, apiKey, fetchImpl = globalThis.fetch) {
+  const out = []
+  let next = url
+  let guard = 0
+
+  while (next) {
+    if (++guard > 50) throw new Error(`Kapa pagination did not terminate after ${guard - 1} pages: ${url}`)
+
+    // The deadline covers the body read too; see fetch-with-deadline.js for
+    // why clearing the timer after headers alone is not a timeout.
+    const { res, body } = await fetchWithDeadline(
+      fetchImpl, next, { headers: kapaAuthHeaders(apiKey) }, REQUEST_TIMEOUT_MS,
+      (r) => (r.ok ? r.json() : null)
+    )
+
+    if (!res.ok) {
+      // 401/403 is the overwhelmingly likely failure and deserves its own hint:
+      // a wrong-project key returns 403, not an empty list.
+      const hint = res.status === 401 || res.status === 403
+        ? ' Check that KAPA_API_KEY is valid and belongs to the project in KAPA_PROJECT_ID.'
+        : ''
+      throw new Error(`Kapa API request failed: ${res.status} ${res.statusText} for ${next}.${hint}`)
+    }
+
+    if (!Array.isArray(body?.results)) {
+      throw new Error(`Kapa API returned an unexpected shape for ${next}: no results array.`)
+    }
+    out.push(...body.results)
+    next = body.next || null
+  }
+
+  return out
+}
+
+/**
+ * Flatten the group tree into parent + children.
+ *
+ * Kapa's hierarchy is two levels and is expressed top-down: a group carries
+ * `sub_groups`, and there is no parent_id/parent/level field anywhere in the
+ * schema. So children are only discoverable by descending from parents.
+ *
+ * @param {object[]} groups - `results` from the source-groups endpoint
+ * @returns {{parents: object[], childrenByParentId: Map<string, object[]>}}
+ */
+function flattenGroups (groups) {
+  const parents = []
+  const childrenByParentId = new Map()
+
+  for (const group of groups) {
+    const subs = toList(group.sub_groups).filter((s) => typeof s === 'object')
+    parents.push(group)
+    childrenByParentId.set(group.id, subs)
+  }
+
+  return { parents, childrenByParentId }
+}
+
+/**
+ * Build the segment -> group mapping.
+ *
+ * @param {object} options
+ * @param {string} options.apiKey
+ * @param {string} options.projectId
+ * @param {string} [options.defaultSegment='current'] - Segment used for pages with no version
+ * @param {string} [options.parentGroupName] - Restrict to one parent by name (default: the only parent that has children)
+ * @param {Function} [options.fetchImpl]
+ * @returns {Promise<string>} Pretty-printed JSON, newline-terminated
+ */
+async function generateKapaSourceGroups ({
+  apiKey,
+  projectId,
+  defaultSegment = 'current',
+  parentGroupName,
+  fetchImpl,
+} = {}) {
+  if (!apiKey) throw new Error('generateKapaSourceGroups requires an apiKey')
+  if (!projectId) throw new Error('generateKapaSourceGroups requires a projectId')
+
+  const base = `${KAPA_API_BASE}/ingestion/v1/projects/${encodeURIComponent(projectId)}`
+  const [groups, sources] = await Promise.all([
+    fetchAllPages(`${base}/source-groups/`, apiKey, fetchImpl),
+    fetchAllPages(`${base}/sources/`, apiKey, fetchImpl),
+  ])
+
+  if (groups.length === 0) {
+    // An empty list looks identical to "the dashboard work has not been done
+    // yet". Refuse rather than writing an empty mapping that would make every
+    // consumer silently fall back to unscoped retrieval.
+    throw new KapaGroupTreeError(
+      'Kapa returned no source groups. Create the parent group and its version sub groups in the ' +
+      'Kapa dashboard (Sources > Manage groups) before running this generator.'
+    )
+  }
+
+  const { parents, childrenByParentId } = flattenGroups(groups)
+
+  const candidates = parentGroupName
+    ? parents.filter((p) => p.name === parentGroupName)
+    : parents.filter((p) => (childrenByParentId.get(p.id) || []).length > 0)
+
+  if (candidates.length === 0) {
+    const names = parents.map((p) => `"${p.name}"`).join(', ')
+    throw new KapaGroupTreeError(
+      parentGroupName
+        ? `No source group named "${parentGroupName}". Groups present: ${names}.`
+        : 'No source group has any sub groups, so there are no version groups to map. ' +
+          `Add version sub groups under a parent in the Kapa dashboard. Groups present: ${names}.`
+    )
+  }
+  if (candidates.length > 1) {
+    const names = candidates.map((p) => `"${p.name}"`).join(', ')
+    throw new KapaGroupTreeError(
+      `Ambiguous parent group: ${names} all have sub groups. Pass --parent-group to choose one.`
+    )
+  }
+
+  const parent = candidates[0]
+  const children = childrenByParentId.get(parent.id) || []
+
+  // Which sources are assigned to each group. A version group with no sources
+  // is worse than no group at all: scoping to it returns only the global set, so
+  // the reader silently gets no version-specific content. Surface it.
+  const sourcesByGroupId = new Map()
+  for (const source of sources) {
+    for (const entry of toList(source.source_groups)) {
+      const gid = idOf(entry)
+      if (!gid) continue
+      if (!sourcesByGroupId.has(gid)) sourcesByGroupId.set(gid, [])
+      sourcesByGroupId.get(gid).push({ id: source.id, name: source.name })
+    }
+  }
+
+  const segments = {}
+  const empty = []
+  for (const child of children) {
+    const assigned = (sourcesByGroupId.get(child.id) || [])
+      .slice()
+      .sort((a, b) => a.name.localeCompare(b.name))
+    if (assigned.length === 0) empty.push(child.name)
+    if (Object.prototype.hasOwnProperty.call(segments, child.name)) {
+      // Silently overwriting makes half that version's sources unreachable at
+      // retrieval, and which group_id survives depends on the order Kapa
+      // returns sub_groups in, which it does not guarantee. So the committed
+      // file flaps between runs and the drift issue reads only "group id
+      // changed", with no hint that two groups share a name. Duplicating a name
+      // is an easy dashboard slip: re-creating a group instead of editing it.
+      throw new KapaGroupTreeError(
+        `Two sub groups under "${parent.name}" are both named "${child.name}" ` +
+        `(${segments[child.name].group_id} and ${child.id}). Rename or delete one in the Kapa ` +
+        'dashboard: a segment can map to only one group, and which one won here would depend on ' +
+        'the order Kapa happens to return them in.'
+      )
+    }
+    segments[child.name] = {
+      group_id: child.id,
+      group_name: child.name,
+      // Sorted so a reordering upstream cannot produce a docs diff.
+      source_ids: assigned.map((s) => s.id).sort(),
+      source_names: assigned.map((s) => s.name),
+    }
+  }
+
+  if (!segments[defaultSegment]) {
+    throw new KapaGroupTreeError(
+      `Default segment "${defaultSegment}" is not one of the version groups ` +
+      `(${Object.keys(segments).sort().join(', ') || 'none'}). Pages with no version would have ` +
+      'nothing to scope to, so this must be fixed before the mapping is usable.'
+    )
+  }
+
+  if (empty.length) {
+    throw new KapaGroupTreeError(
+      `These version groups have no sources assigned: ${empty.sort().join(', ')}. ` +
+      'Scoping a query to an empty group returns only global sources, so the reader would get no ' +
+      'version-specific content at all. Assign each Documentation (X) source to its group in the ' +
+      'Kapa dashboard (Sources > Configure), then re-run.'
+    )
+  }
+
+  // Sources deliberately left unassigned. These are the global set: always
+  // returned alongside whichever group a query scopes to. Recorded because the
+  // whole design depends on it (Agentic Data Plane must stay reachable from
+  // every page), so a future reader can see it was a choice, not an oversight.
+  const globalSources = sources
+    .filter((s) => toList(s.source_groups).length === 0)
+    .map((s) => s.name)
+    .sort((a, b) => a.localeCompare(b))
+
+  // Keys sorted throughout: this file is diff-checked in CI, so a stable order
+  // is what makes "no changes" mean "nothing changed upstream". Note there is
+  // deliberately no generated-at timestamp -- that is exactly what stops
+  // cloud-regions from being diff-checkable.
+  const mapping = {
+    project_id: projectId,
+    parent_group: { id: parent.id, name: parent.name, type: parent.type || null },
+    default_segment: defaultSegment,
+    segments: Object.fromEntries(
+      Object.keys(segments).sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).map((k) => [k, segments[k]])
+    ),
+    global_sources: globalSources,
+  }
+
+  return `${JSON.stringify(mapping, null, 2)}\n`
+}
+
+module.exports = {
+  KapaGroupTreeError,
+  generateKapaSourceGroups,
+  // Exported for unit tests.
+  toList,
+  idOf,
+  flattenGroups,
+  fetchAllPages,
+}