@dogsbay/format-asciidoc 0.2.0-beta.101

package/dist/loaders/antora.js

@@ -0,0 +1,874 @@
+/**
+ * Antora corpus loader — component mode AND playbook mode (#067).
+ *
+ * Component mode detects `antora.yml` at the source root. Playbook mode
+ * detects `antora-playbook.yml` at the root with local `start_path`s and
+ * loads every component (see the PlaybookYml doc below). Reads the
+ * component manifest (name + version + nav file list + asciidoc
+ * attribute defaults), walks `modules/<name>/pages/**\/*.adoc`, and
+ * builds nav from the referenced `nav.adoc` files.
+ *
+ * **What's covered** (validated on couchbase docs-server + RHSI
+ * solution pattern — see docs-dev/antora-support.md for results):
+ *
+ * - Single-component mode (one antora.yml).
+ * - All modules under `modules/<name>/pages/` — ROOT pages get no
+ *   slug prefix; other modules' pages get a `<module-name>/` prefix.
+ *   `_`-prefixed files/dirs under pages/ are skipped (Antora publish
+ *   rule — they're include targets like `_attributes.adoc`).
+ * - nav.adoc parsing: depth-based list items (leading whitespace
+ *   tolerated), `.Section` block titles as top-level groups,
+ *   `include::[mod:]partial$nav.adoc[]` expansion with per-line module
+ *   context, module-coordinate + cross-component + external-URL
+ *   targets, `#fragment` preservation, `{counter:…}` label cleanup.
+ * - Per-page attributes: `antora.yml` `asciidoc.attributes:` (soft-set
+ *   `@` suffix stripped) + the module's `pages/_attributes.adoc` seed
+ *   + content-rooted `imagesdir` (modern `images/` or legacy
+ *   `assets/images/` layout, fs-probed per module).
+ * - Component name + version surfaced on `LoaderResult.component`.
+ * - Body-content translation (module-coordinate xrefs, `family$`
+ *   resource includes, tag filtering) lives in the engine behind its
+ *   `antora: true` option — cli.ts sets it when this loader is picked.
+ *
+ * **Deliberately out of scope (deferred):**
+ *
+ * - REMOTE playbook sources (git URLs) — a single-repo build cannot
+ *   fetch them; they warn by name and are skipped. Local start_paths
+ *   (the circleci shape) are fully supported.
+ * - Version axis emission into format-astro's version-axis machinery.
+ *   Playbook mode instead lays versions out the way Antora's own URLs
+ *   do (latest bare, older under `<component>/<version>/`), so a
+ *   reader's links resolve; wiring the axis is a follow-up.
+ *
+ * Sample antora.yml shape:
+ *
+ *   name: product
+ *   title: My Product
+ *   version: '2.0'        # null / ~ also valid (unversioned)
+ *   nav:
+ *     - modules/ROOT/nav.adoc
+ *     - modules/admin/nav.adoc
+ *   asciidoc:
+ *     attributes:
+ *       page-component-name: product
+ *
+ * Sample nav.adoc:
+ *
+ *   * xref:index.adoc[Introduction]
+ *   * Getting Started
+ *   ** xref:install.adoc[]
+ *   ** xref:configure.adoc[Configuration]
+ *
+ * See plans/asciidoc-corpus-loaders.md "Antora" section.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join, relative } from "node:path";
+import YAML from "yaml";
+import { prettifyName } from "./util.js";
+const ANTORA_YML = "antora.yml";
+const ROOT_MODULE = "ROOT";
+const PLAYBOOK_NAMES = ["antora-playbook.yml", "antora-playbook.yaml"];
+function walkPagesUnderModule(modulesDir, moduleName) {
+    const pagesDir = join(modulesDir, moduleName, "pages");
+    if (!existsSync(pagesDir))
+        return [];
+    const out = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            // Antora convention: files and directories whose names start with
+            // an underscore under pages/ are not published (e.g. the
+            // `_attributes.adoc` include target every page pulls in). They
+            // still convert as fragments downstream — just not as pages.
+            if (entry.name.startsWith("_"))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(full);
+            }
+            else if (entry.name.endsWith(".adoc")) {
+                const relFromPages = relative(pagesDir, full).replace(/\\/g, "/");
+                const pageSlug = relFromPages.replace(/\.adoc$/, "");
+                // ROOT pages get no module prefix; other modules get one.
+                const slug = moduleName === ROOT_MODULE ? pageSlug : `${moduleName}/${pageSlug}`;
+                out.push({ filePath: full, slug });
+            }
+        }
+    }
+    walk(pagesDir);
+    return out;
+}
+/**
+ * Locate a module's images directory, if any — modern `images/` or the
+ * legacy `assets/images/` layout. Returns the content-rooted imagesdir
+ * value the engine should prepend to relative image targets (the
+ * migrated content tree mirrors the source layout under `modules/`, and
+ * format-astro serves every content image at its content-relative URL),
+ * or undefined when the module ships no images.
+ */
+function moduleImagesdir(modulesDir, moduleName) {
+    if (existsSync(join(modulesDir, moduleName, "images"))) {
+        return `/modules/${moduleName}/images`;
+    }
+    if (existsSync(join(modulesDir, moduleName, "assets", "images"))) {
+        return `/modules/${moduleName}/assets/images`;
+    }
+    return undefined;
+}
+/**
+ * Parse simple `:name: value` attribute entries from a module's
+ * `pages/_attributes.adoc` (the de-facto Antora starter convention:
+ * every page opens with `include::_attributes.adoc[]`). Values keep
+ * raw `{ref}` syntax — Minja resolves nested refs downstream. A
+ * trailing `@` (Antora's soft-set marker) is stripped.
+ *
+ * Only plain value entries are read; unsetting (`:!name:`), continuation
+ * lines, and conditionals are skipped — this is a best-effort context
+ * seed so titles and inline refs resolve at import time, not a full
+ * AsciiDoc header parser.
+ */
+function parsePageAttributesFile(path) {
+    const out = {};
+    let content;
+    try {
+        content = readFileSync(path, "utf-8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of content.split("\n")) {
+        const m = line.match(/^:([A-Za-z0-9_][A-Za-z0-9_-]*):\s*(.*?)\s*$/);
+        if (!m)
+            continue;
+        out[m[1]] = stripSoftSetSuffix(m[2]);
+    }
+    return out;
+}
+/** Strip Antora's soft-set `@` suffix from an attribute value. */
+function stripSoftSetSuffix(value) {
+    return typeof value === "string" && value.endsWith("@")
+        ? value.slice(0, -1)
+        : value;
+}
+function listModules(sourceDir) {
+    const modulesDir = join(sourceDir, "modules");
+    if (!existsSync(modulesDir))
+        return [];
+    try {
+        return readdirSync(modulesDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+const NAV_INCLUDE_MAX_DEPTH = 5;
+/**
+ * Expand `include::[module:]partial$<rel>[…]` directives in nav content
+ * into the included files' lines — the Antora convention for composing
+ * the ROOT nav out of per-module `partials/nav.adoc` files (couchbase's
+ * ROOT nav pulls in 15 of them). Missing files warn and drop; module
+ * context switches for the included lines so their xrefs resolve under
+ * the right module.
+ */
+function expandNavLines(content, moduleName, modulesDir, depth = 0) {
+    const out = [];
+    if (depth > NAV_INCLUDE_MAX_DEPTH) {
+        console.warn("antora loader: nav include depth exceeded, truncating");
+        return out;
+    }
+    const includeRe = /^include::(?:([^:\s]+):)?partial\$([^\[\s]+)\[[^\]]*\]\s*$/;
+    for (const rawLine of content.split("\n")) {
+        const m = rawLine.match(includeRe);
+        if (!m) {
+            out.push({ line: rawLine, module: moduleName });
+            continue;
+        }
+        const incModule = m[1] || moduleName;
+        const incPath = join(modulesDir, incModule, "partials", m[2]);
+        if (!existsSync(incPath)) {
+            console.warn(`antora loader: nav include not found, skipping: ${incModule}:partial$${m[2]}`);
+            continue;
+        }
+        try {
+            const incContent = readFileSync(incPath, "utf-8");
+            out.push(...expandNavLines(incContent, incModule, modulesDir, depth + 1));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.warn(`antora loader: cannot read nav include ${incPath}: ${msg}`);
+        }
+    }
+    return out;
+}
+/**
+ * Parse expanded nav lines into a NavItem[] tree.
+ *
+ * Recognised shapes:
+ *   - `.Section Title`       → new top-level group; following items nest
+ *   - `*+ xref:…[label]`     → leaf (leading whitespace tolerated; depth
+ *                              = number of `*`)
+ *   - `*+ https://…[label]`  → external link leaf
+ *   - `*+ Plain text`        → group header (no link)
+ *
+ * Algorithm: stack-of-parents per depth; a `.Section` line resets the
+ * stack with the new group as the root container. Anything else
+ * (blank lines, prose, comments) is ignored.
+ */
+function parseNavAdoc(navLines, hrefPrefix) {
+    const root = [];
+    // Stack[d] = the children-array to push into for a depth-(d+1) item.
+    // stack[0] is the current top-level container (root, or the children
+    // of the active `.Section` group).
+    let stack = [root];
+    const itemRe = /^\s*(\*+)\s+(.+)$/;
+    const sectionRe = /^\.([^.\s].*)$/;
+    for (const { line: rawLine, module } of navLines) {
+        const line = rawLine.replace(/\s+$/, "");
+        if (line.startsWith("//"))
+            continue;
+        const sec = line.match(sectionRe);
+        if (sec) {
+            const group = { label: cleanNavLabel(sec[1]), children: [] };
+            root.push(group);
+            stack = [group.children];
+            continue;
+        }
+        const m = line.match(itemRe);
+        if (!m)
+            continue;
+        const depth = m[1].length;
+        const text = m[2].trim();
+        const item = parseNavItem(text, module, hrefPrefix);
+        if (!item)
+            continue;
+        // Find the parent array — if depth exceeds current stack length,
+        // we're going deeper than any actual parent; clamp to current top.
+        const parentIdx = Math.min(depth - 1, stack.length - 1);
+        const parent = stack[parentIdx];
+        parent.push(item);
+        // This item becomes the parent for depth+1 items. Allocate its
+        // children array up-front (so we can push later); if it stays
+        // empty, we strip it before returning.
+        if (!item.children)
+            item.children = [];
+        // Trim deeper-than-current entries; replace stack[depth] with our children.
+        stack.length = depth;
+        stack.push(item.children);
+    }
+    // Clean up: drop empty `children: []` arrays so leaves don't look
+    // like empty groups to downstream consumers.
+    function strip(items) {
+        for (const it of items) {
+            if (it.children && it.children.length === 0) {
+                delete it.children;
+            }
+            else if (it.children) {
+                strip(it.children);
+            }
+        }
+    }
+    strip(root);
+    return root;
+}
+/**
+ * Clean presentation noise out of a nav label: `{counter:x}` /
+ * `{counter2:x}` auto-numbering tokens (resolved at render time by
+ * Antora — pure numbering, dropped here), any leading run of leftover
+ * `{ref}` tokens + separator punctuation that the counter strip
+ * orphans (`{module}.{counter:sub} Use cases` → `Use cases`), and a
+ * trailing `^` (Antora's open-in-new-window marker).
+ */
+function cleanNavLabel(label) {
+    let out = label.replace(/\{counter2?:[^}]*\}/g, "");
+    out = out.replace(/^(?:\{[^}]*\}|[\s.)\-:])+/, "");
+    out = out.replace(/\^$/, "");
+    return out.trim();
+}
+/**
+ * Parse one nav item's text. Returns null for items that should be
+ * dropped entirely (currently nothing — cross-component xrefs degrade
+ * to label-only entries instead, so the nav structure survives).
+ */
+function parseNavItem(text, moduleName, hrefPrefix) {
+    // External link: `https://…[label]` or `link:https://…[label]`.
+    const urlMatch = text.match(/^(?:link:)?(https?:\/\/[^\[\s]+)\[([^\]]*)\]$/);
+    if (urlMatch) {
+        const label = cleanNavLabel(urlMatch[2]) || urlMatch[1];
+        return { label, href: urlMatch[1] };
+    }
+    // xref with any coordinate shape: xref:[version@][component:][module:]path[label]
+    const xrefMatch = text.match(/^xref:([^\[\s]+)\[([^\]]*)\]$/);
+    if (!xrefMatch) {
+        // Plain text — group header.
+        return { label: cleanNavLabel(text) };
+    }
+    let target = xrefMatch[1];
+    const rawLabel = xrefMatch[2];
+    // Split off a #fragment before extension handling (`index.adoc#use-cases`).
+    const hashIdx = target.indexOf("#");
+    const frag = hashIdx === -1 ? "" : target.substring(hashIdx);
+    if (hashIdx !== -1)
+        target = target.substring(0, hashIdx);
+    // Drop a version@ prefix (single-version corpus).
+    const atIdx = target.indexOf("@");
+    if (atIdx !== -1 && target.indexOf(":", atIdx) !== -1) {
+        target = target.substring(atIdx + 1);
+    }
+    const segs = target.split(":");
+    const label = cleanNavLabel(rawLabel) ||
+        prettifyName(basename(segs[segs.length - 1].replace(/\.adoc$/, "")));
+    if (segs.length > 2) {
+        // component:module:path — another component. Unresolvable in a
+        // single-component corpus (label-only, counted for the summary
+        // warning); in PLAYBOOK mode loadPlaybook resolves it against the
+        // loaded set (#067 review: 11 dead nav leaves on circleci), so the
+        // coordinate rides along on a private marker it strips afterwards.
+        crossComponentNavItems += 1;
+        const xrefPath = segs[segs.length - 1].replace(/^\/+/, "").replace(/\.adoc$/, "");
+        const item = { label };
+        if (xrefPath)
+            item._xref = { component: segs[0], module: segs[1] || ROOT_MODULE, path: xrefPath, frag };
+        return item;
+    }
+    const xrefModule = segs.length === 2 && segs[0] ? segs[0] : moduleName;
+    // A leading slash after the coordinate (`xref:mod:/page.adoc`) is
+    // author noise Antora normalizes away — joining it verbatim produced
+    // `mod//page` hrefs (#053 B).
+    const xrefPath = segs[segs.length - 1]
+        .replace(/^\/+/, "")
+        .replace(/\.adoc$/, "");
+    if (!xrefPath)
+        return { label };
+    const slug = xrefModule === ROOT_MODULE ? xrefPath : `${xrefModule}/${xrefPath}`;
+    return { label, href: `${hrefPrefix}/${slug}${frag}` };
+}
+// Count of nav entries that referenced another component this load()
+// run — reset per load, reported once as a summary warning.
+let crossComponentNavItems = 0;
+export const antoraLoader = {
+    name: "antora",
+    detect(sourceDir) {
+        if (!existsSync(sourceDir))
+            return false;
+        try {
+            const st = statSync(sourceDir);
+            if (!st.isDirectory())
+                return false;
+            // Component mode (root antora.yml) OR playbook mode (#067: a
+            // playbook at the root with at least one LOCAL start_path).
+            if (existsSync(join(sourceDir, ANTORA_YML)))
+                return true;
+            const pb = findPlaybook(sourceDir);
+            if (!pb)
+                return false;
+            const parsed = (YAML.parse(readFileSync(pb, "utf-8")) ?? {});
+            return playbookLocalStartPaths(sourceDir, parsed).local.length > 0;
+        }
+        catch {
+            return false;
+        }
+    },
+    async load(sourceDir, opts) {
+        const playbook = findPlaybook(sourceDir);
+        if (!existsSync(join(sourceDir, ANTORA_YML)) && playbook) {
+            return loadPlaybook(sourceDir, playbook, opts);
+        }
+        return loadSingleComponent(sourceDir, opts);
+    },
+};
+/** Path of the playbook file at `sourceDir`, or null. */
+function findPlaybook(sourceDir) {
+    for (const n of PLAYBOOK_NAMES) {
+        const p = join(sourceDir, n);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Local `start_path`s declared by a playbook — every source whose `url`
+ * is `.`/`./…`/an existing local dir. Remote sources are returned in
+ * `remote` so the caller can warn by name.
+ */
+function playbookLocalStartPaths(sourceDir, playbook) {
+    const local = [];
+    const remote = [];
+    for (const src of playbook.content?.sources ?? []) {
+        const url = (src.url ?? ".").trim();
+        const isLocal = url === "." || url.startsWith("./") || url.startsWith("../") ||
+            (!/^[a-z][a-z0-9+.-]*:/i.test(url) && existsSync(join(sourceDir, url)));
+        const base = url === "." ? sourceDir : join(sourceDir, url);
+        if (!isLocal) {
+            remote.push(url);
+            continue;
+        }
+        // `start_paths` may be a list or a comma-separated string; a comma
+        // INSIDE braces (`docs/{a,b}`) is brace syntax, not a separator.
+        const sps = src.start_paths !== undefined
+            ? Array.isArray(src.start_paths) ? src.start_paths : splitOutsideBraces(String(src.start_paths))
+            : [src.start_path ?? "."];
+        for (const sp of sps) {
+            if (!sp)
+                continue;
+            // Antora allows brace-expansion in start_paths (`docs/{a,b}`).
+            for (const expanded of expandBraces(sp)) {
+                const dir = join(base, expanded);
+                // A start_path that ESCAPES the corpus root (`url: ../sibling`)
+                // would load a component whose includes the #027 containment then
+                // refuses — half-working. Skip it, loudly (review).
+                const rel = relative(sourceDir, dir);
+                if (rel.startsWith("..")) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`antora loader: playbook start_path escapes the corpus root, skipping: ${dir}`);
+                    continue;
+                }
+                local.push(dir);
+            }
+        }
+    }
+    return { local, remote };
+}
+/** Split on commas that are not inside `{…}`. */
+function splitOutsideBraces(v) {
+    const out = [];
+    let depth = 0, cur = "";
+    for (const ch of v) {
+        if (ch === "{")
+            depth++;
+        else if (ch === "}")
+            depth = Math.max(0, depth - 1);
+        if (ch === "," && depth === 0) {
+            out.push(cur.trim());
+            cur = "";
+            continue;
+        }
+        cur += ch;
+    }
+    if (cur.trim())
+        out.push(cur.trim());
+    return out;
+}
+/** `docs/{a,b}` → [`docs/a`, `docs/b`]; no braces → [input]. */
+function expandBraces(p) {
+    const m = p.match(/^(.*)\{([^}]*)\}(.*)$/);
+    if (!m)
+        return [p];
+    return m[2].split(",").flatMap((alt) => expandBraces(`${m[1]}${alt.trim()}${m[3]}`));
+}
+/**
+ * Semver-ish version compare for "which is latest": numeric segments
+ * compare numerically (`4.10` > `4.9`), a common non-numeric prefix
+ * (`server-`) is ignored, unversioned (`~`/undefined) sorts LOWEST.
+ */
+function compareVersions(a, b) {
+    if (!a && !b)
+        return 0;
+    if (!a)
+        return -1;
+    if (!b)
+        return 1;
+    const parts = (v) => v.split(/[.\-]/).filter(Boolean);
+    const pa = parts(a), pb = parts(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const x = pa[i], y = pb[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const nx = /^\d+$/.test(x) ? Number(x) : NaN;
+        const ny = /^\d+$/.test(y) ? Number(y) : NaN;
+        if (!Number.isNaN(nx) && !Number.isNaN(ny)) {
+            if (nx !== ny)
+                return nx - ny;
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+async function loadPlaybook(sourceDir, playbookPath, opts) {
+    let playbook;
+    try {
+        playbook = (YAML.parse(readFileSync(playbookPath, "utf-8")) ?? {});
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`antora loader: cannot parse ${basename(playbookPath)}: ${msg}`);
+    }
+    const { local, remote } = playbookLocalStartPaths(sourceDir, playbook);
+    for (const r of remote) {
+        // eslint-disable-next-line no-console
+        console.warn(`antora loader: playbook source is remote and cannot be loaded in a single-repo build, skipping: ${r}`);
+    }
+    if (local.length === 0) {
+        throw new Error(`antora loader: ${basename(playbookPath)} declares no local content sources (nothing to load)`);
+    }
+    const playbookAttrs = {};
+    for (const [k, v] of Object.entries(playbook.asciidoc?.attributes ?? {})) {
+        playbookAttrs[k] = stripSoftSetSuffix(v);
+    }
+    // Load every local component. Slugs from loadSingleComponent are
+    // component-relative; we prefix them below once versions are known.
+    const loads = [];
+    for (const dir of local) {
+        if (!existsSync(join(dir, ANTORA_YML))) {
+            // eslint-disable-next-line no-console
+            console.warn(`antora loader: start_path has no ${ANTORA_YML}, skipping: ${relative(sourceDir, dir) || "."}`);
+            continue;
+        }
+        // Component nav hrefs are built with NO prefix here; the component
+        // prefix is applied uniformly below (so version dirs compose).
+        const r = await loadSingleComponent(dir, { ...opts, hrefPrefix: "" }, true);
+        const name = r.component?.name ?? basename(dir);
+        const version = r.component?.version;
+        // Duplicate (name, version) — Antora rejects it outright. Skipping the
+        // whole second component keeps pages/nav/mounts/components consistent
+        // (a first-wins-per-slug merge left them disagreeing — review).
+        if (loads.some((l) => l.name === name && (l.version ?? "") === (version ?? ""))) {
+            // eslint-disable-next-line no-console
+            console.warn(`antora loader: duplicate component ${name}@${version ?? "~"} at ${relative(sourceDir, dir)} — skipping (Antora rejects duplicate versions)`);
+            continue;
+        }
+        loads.push({
+            dir,
+            name,
+            title: r.component?.title,
+            version,
+            prerelease: r.component?.prerelease === true,
+            displayVersion: r.component?.displayVersion,
+            pages: r.pages,
+            nav: r.nav,
+            attributes: r.corpusAttributes ?? {},
+        });
+    }
+    if (loads.length === 0) {
+        throw new Error(`antora loader: none of the playbook's local start_paths contained an ${ANTORA_YML}`);
+    }
+    // Latest version per component name. Antora rule: a PRERELEASE version
+    // is never latest (the `version: main` / `next` pattern) unless every
+    // version of that name is prerelease.
+    const latest = new Map();
+    for (const l of loads) {
+        const cur = loads.find((c) => c.name === l.name && (c.version ?? "") === (latest.get(l.name) ?? "") && latest.has(l.name));
+        if (!latest.has(l.name)) {
+            latest.set(l.name, l.version);
+            continue;
+        }
+        const curPre = cur ? cur.prerelease : false;
+        if (curPre && !l.prerelease) {
+            latest.set(l.name, l.version);
+            continue;
+        }
+        if (!curPre && l.prerelease)
+            continue;
+        if (compareVersions(l.version, latest.get(l.name)) > 0)
+            latest.set(l.name, l.version);
+    }
+    const versionsOf = new Map();
+    for (const l of loads)
+        versionsOf.set(l.name, (versionsOf.get(l.name) ?? 0) + 1);
+    const hrefPrefix = opts.hrefPrefix ?? "";
+    // Slug prefix of the LATEST load per component name (cross-component
+    // nav xrefs and the engine's components map both resolve there).
+    const latestPrefixOf = new Map();
+    for (const l of loads) {
+        if (compareVersions(l.version, latest.get(l.name)) !== 0)
+            continue;
+        latestPrefixOf.set(l.name, l.name === ROOT_MODULE ? "" : `${l.name}/`);
+    }
+    const pages = [];
+    const nav = [];
+    // Group nav by component name, keeping first-seen playbook order.
+    const navGroups = new Map();
+    const seenSlugs = new Set();
+    for (const l of loads) {
+        const isRoot = l.name === ROOT_MODULE;
+        const isLatest = compareVersions(l.version, latest.get(l.name)) === 0;
+        const multiVersion = (versionsOf.get(l.name) ?? 1) > 1;
+        // Slug prefix: <component>[/<version>] — latest at the bare component
+        // path (Antora's `latest` redirect target); older versions nested.
+        const segs = [];
+        if (!isRoot)
+            segs.push(l.name);
+        if (!isLatest && l.version)
+            segs.push(l.version);
+        const prefix = segs.length ? segs.join("/") + "/" : "";
+        for (const p of l.pages) {
+            const slug = prefix + p.slug;
+            if (seenSlugs.has(slug)) {
+                // eslint-disable-next-line no-console
+                console.warn(`antora loader: duplicate page slug across components, keeping first: ${slug}`);
+                continue;
+            }
+            seenSlugs.add(slug);
+            const attrs = { ...playbookAttrs, ...(p.attributes ?? {}) };
+            // The component's content-rooted imagesdir (`/modules/<m>/images`)
+            // must sit under the mount prefix too — images are mirrored there.
+            if (prefix && typeof attrs.imagesdir === "string" && attrs.imagesdir.startsWith("/modules/")) {
+                attrs.imagesdir = `/${prefix}${attrs.imagesdir.slice(1)}`;
+            }
+            pages.push({
+                ...p,
+                slug,
+                ...(Object.keys(attrs).length ? { attributes: attrs } : {}),
+            });
+        }
+        // Nav: rewrite this component's hrefs under its prefix, and resolve
+        // cross-component coordinates against the loaded set (own name →
+        // this prefix; another name → its LATEST prefix; unknown → label-only).
+        const rewritten = resolveNavXrefs(prefixNavHrefs(l.nav, hrefPrefix, prefix), l.name, prefix, latestPrefixOf, hrefPrefix);
+        const label = l.title ?? l.name;
+        if (multiVersion) {
+            let group = navGroups.get(l.name);
+            if (!group) {
+                group = { label, children: [] };
+                navGroups.set(l.name, group);
+                nav.push(group);
+            }
+            const versionItem = {
+                label: (l.displayVersion ?? l.version) ? (isLatest ? `${l.displayVersion ?? l.version} (latest)` : (l.displayVersion ?? l.version)) : "unversioned",
+                children: rewritten,
+            };
+            versionItem._v = l.version;
+            versionItem._latest = isLatest;
+            group.children.push(versionItem);
+            // LATEST first (whatever its version string — a prerelease `main`
+            // would otherwise string-sort above the numbers), then the rest
+            // descending by the REAL version (labels may be display_version
+            // strings). Markers stripped after.
+            // (Markers are stripped once, after ALL loads — deleting them per push
+            // left earlier siblings keyless and inverted the order; review.)
+        }
+        else if (isRoot) {
+            // ROOT component's nav sits at the top level, first.
+            nav.unshift(...rewritten);
+        }
+        else {
+            nav.push({ label, children: rewritten });
+        }
+    }
+    // Order every multi-version group: LATEST first (whatever its version
+    // string — a prerelease `main` would string-sort above the numbers),
+    // then descending by the REAL version (labels may be display_version
+    // strings). Then strip the private markers.
+    for (const group of navGroups.values()) {
+        const kids = group.children;
+        kids.sort((a, b) => {
+            const la = a._latest ? 1 : 0, lb = b._latest ? 1 : 0;
+            if (la !== lb)
+                return lb - la;
+            return compareVersions(b._v, a._v);
+        });
+        for (const c of kids) {
+            delete c._v;
+            delete c._latest;
+        }
+    }
+    // Site-wide attribute values: playbook first, then each LATEST
+    // component's own (a site has ONE attributes block; a value two
+    // components disagree on stays with the first and is warned — the
+    // per-page attributes on PageSource still carry each component's own).
+    const corpusAttributes = { ...playbookAttrs };
+    const attrOwner = new Map();
+    for (const k of Object.keys(playbookAttrs))
+        attrOwner.set(k, "playbook");
+    for (const l of loads) {
+        if (compareVersions(l.version, latest.get(l.name)) !== 0)
+            continue;
+        for (const [k, v] of Object.entries(l.attributes)) {
+            if (!(k in corpusAttributes)) {
+                corpusAttributes[k] = v;
+                attrOwner.set(k, l.name);
+                continue;
+            }
+            if (corpusAttributes[k] !== v && attrOwner.get(k) !== "playbook") {
+                // eslint-disable-next-line no-console
+                console.warn(`antora loader: attribute "${k}" differs between components ${attrOwner.get(k)} and ${l.name}; site config keeps ${attrOwner.get(k)}'s value`);
+            }
+        }
+    }
+    const unresolved = countLabelOnlyLeaves(nav);
+    if (unresolved > 0) {
+        // eslint-disable-next-line no-console
+        console.warn(`antora loader: ${unresolved} nav entr${unresolved === 1 ? "y" : "ies"} reference components not in this playbook (kept as label-only items)`);
+    }
+    const result = { pages, nav };
+    if (Object.keys(corpusAttributes).length > 0)
+        result.corpusAttributes = corpusAttributes;
+    // Surface the FIRST component as `component` for callers that read
+    // it (single-component consumers); the full set is in `components`.
+    result.component = {
+        name: loads[0].name,
+        ...(loads[0].title ? { title: loads[0].title } : {}),
+        ...(loads[0].version ? { version: loads[0].version } : {}),
+    };
+    result.components = loads.map((l) => ({
+        name: l.name,
+        ...(l.title ? { title: l.title } : {}),
+        ...(l.version ? { version: l.version } : {}),
+        startPath: relative(sourceDir, l.dir).replace(/\\/g, "/") || ".",
+        latest: compareVersions(l.version, latest.get(l.name)) === 0,
+    }));
+    return result;
+}
+/**
+ * Resolve `_xref` markers (cross-component nav coordinates) now that every
+ * component is loaded, then strip the marker. Own component → this load's
+ * prefix; another loaded component → its latest prefix; unknown → stays
+ * label-only (the summary warning already counted it).
+ */
+function resolveNavXrefs(items, ownName, ownPrefix, latestPrefixOf, hrefPrefix) {
+    return items.map((it) => {
+        const marked = it;
+        const out = { ...it };
+        delete out._xref;
+        const x = marked._xref;
+        if (x && out.href === undefined) {
+            const prefix = x.component === ownName ? ownPrefix : latestPrefixOf.get(x.component);
+            if (prefix !== undefined) {
+                const slug = x.module === ROOT_MODULE ? x.path : `${x.module}/${x.path}`;
+                out.href = `${hrefPrefix}/${prefix}${slug}${x.frag}`;
+            }
+        }
+        if (it.children)
+            out.children = resolveNavXrefs(it.children, ownName, ownPrefix, latestPrefixOf, hrefPrefix);
+        return out;
+    });
+}
+/** Leaves (no children) with no href — cross-component refs that stayed unresolved. */
+function countLabelOnlyLeaves(items) {
+    let n = 0;
+    for (const it of items) {
+        if (it.children && it.children.length)
+            n += countLabelOnlyLeaves(it.children);
+        else if (it.href === undefined)
+            n += 1;
+    }
+    return n;
+}
+/** Strip `_xref` markers from a single-component nav (nothing to resolve them against). */
+function stripNavXrefs(items) {
+    return items.map((it) => {
+        const out = { ...it };
+        delete out._xref;
+        if (it.children)
+            out.children = stripNavXrefs(it.children);
+        return out;
+    });
+}
+/** Prepend `<hrefPrefix>/<prefix>` to every content href in a nav tree. */
+function prefixNavHrefs(items, hrefPrefix, prefix) {
+    return items.map((it) => {
+        const out = { ...it };
+        if (typeof it.href === "string" && !/^(?:https?:\/\/|mailto:|tel:)/i.test(it.href)) {
+            // Component-relative hrefs from loadSingleComponent are `/<slug>`.
+            const bare = it.href.replace(/^\/+/, "");
+            out.href = `${hrefPrefix}/${prefix}${bare}`;
+        }
+        if (it.children)
+            out.children = prefixNavHrefs(it.children, hrefPrefix, prefix);
+        return out;
+    });
+}
+async function loadSingleComponent(sourceDir, opts, keepNavXrefMarkers = false) {
+    const ymlPath = join(sourceDir, ANTORA_YML);
+    if (!existsSync(ymlPath)) {
+        throw new Error(`antora loader: ${ANTORA_YML} not found in ${sourceDir}`);
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(readFileSync(ymlPath, "utf-8"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`antora loader: cannot parse ${ANTORA_YML}: ${msg}`);
+    }
+    if (!parsed || typeof parsed !== "object" || !parsed.name) {
+        throw new Error(`antora loader: ${ANTORA_YML} must declare at least a 'name' field`);
+    }
+    const hrefPrefix = opts.hrefPrefix ?? "";
+    const componentAttrs = {};
+    for (const [k, v] of Object.entries(parsed.asciidoc?.attributes ?? {})) {
+        // Antora's soft-set marker (`value@`) is a precedence hint for the
+        // playbook merge — meaningless downstream; strip it.
+        componentAttrs[k] = stripSoftSetSuffix(v);
+    }
+    // Walk every module's pages/ to assemble PageSources. We don't
+    // restrict to modules listed in nav: — a corpus can have pages
+    // not referenced by nav (orphans), and the audit will surface
+    // them; the loader's job is to enumerate them all.
+    const modulesDir = join(sourceDir, "modules");
+    const moduleNames = listModules(sourceDir);
+    const pages = [];
+    for (const moduleName of moduleNames) {
+        // Per-module attribute context: component attrs, then the module's
+        // conventional `pages/_attributes.adoc` seed (so titles and inline
+        // refs resolve at import time), then the content-rooted imagesdir
+        // (so relative image targets resolve against the mirrored module
+        // assets — see plans/antora-support-gaps.md G4).
+        const moduleAttrs = { ...componentAttrs };
+        const attrsFile = join(modulesDir, moduleName, "pages", "_attributes.adoc");
+        if (existsSync(attrsFile)) {
+            Object.assign(moduleAttrs, parsePageAttributesFile(attrsFile));
+        }
+        const imagesdir = moduleImagesdir(modulesDir, moduleName);
+        if (imagesdir)
+            moduleAttrs.imagesdir = imagesdir;
+        for (const { filePath, slug } of walkPagesUnderModule(modulesDir, moduleName)) {
+            const page = { filePath, slug };
+            if (Object.keys(moduleAttrs).length > 0) {
+                page.attributes = { ...moduleAttrs };
+            }
+            pages.push(page);
+        }
+    }
+    // Build nav by parsing each referenced nav.adoc file. Concatenate
+    // multiple nav files at the top level — that's Antora's
+    // convention (each nav.adoc is a "section" of the overall nav).
+    // `include::[mod:]partial$nav.adoc[]` directives inside a nav are
+    // expanded first (couchbase composes its ROOT nav from 15 module
+    // nav partials).
+    crossComponentNavItems = 0;
+    const nav = [];
+    for (const navPath of parsed.nav ?? []) {
+        const navFullPath = join(sourceDir, navPath);
+        if (!existsSync(navFullPath)) {
+            // eslint-disable-next-line no-console
+            console.warn(`antora loader: nav file not found, skipping: ${navPath}`);
+            continue;
+        }
+        // Module name from the nav file's path — `modules/<name>/nav.adoc`.
+        const navRelative = relative(modulesDir, navFullPath).replace(/\\/g, "/");
+        const moduleName = navRelative.split("/")[0] ?? ROOT_MODULE;
+        try {
+            const content = readFileSync(navFullPath, "utf-8");
+            const navLines = expandNavLines(content, moduleName, modulesDir);
+            nav.push(...parseNavAdoc(navLines, hrefPrefix));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            // eslint-disable-next-line no-console
+            console.warn(`antora loader: cannot read ${navPath}: ${msg}`);
+        }
+    }
+    if (crossComponentNavItems > 0 && !keepNavXrefMarkers) {
+        // (Playbook mode resolves these against the loaded set and reports
+        // only what stays label-only — see loadPlaybook.)
+        // eslint-disable-next-line no-console
+        console.warn(`antora loader: ${crossComponentNavItems} nav entr${crossComponentNavItems === 1 ? "y" : "ies"} reference other components (kept as label-only items)`);
+    }
+    const result = { pages, nav: keepNavXrefMarkers ? nav : stripNavXrefs(nav) };
+    if (Object.keys(componentAttrs).length > 0)
+        result.corpusAttributes = { ...componentAttrs };
+    result.component = {
+        name: parsed.name,
+        ...(parsed.title ? { title: parsed.title } : {}),
+        ...(parsed.version ? { version: String(parsed.version) } : {}),
+        ...(parsed.prerelease ? { prerelease: true } : {}),
+        ...(parsed.display_version ? { displayVersion: String(parsed.display_version) } : {}),
+    };
+    return result;
+}
+//# sourceMappingURL=antora.js.map