@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/src/docs/assemble.js

@@ -0,0 +1,739 @@
+/**
+ * Assembly: turn the discovered doc roots into a plain content tree plus a
+ * navigation manifest, ready for a docs renderer (Zudoku today) to build.
+ *
+ * The seam of the whole design is here: assembly's output is a directory of
+ * markdown files, a generated `zudoku.config.ts`, and a publish manifest.
+ * Nothing downstream knows about Mesh; nothing upstream knows about Zudoku.
+ *
+ * What assembly does, per page:
+ *   - derives the title (front-matter `title:` → first `#` heading → filename)
+ *     and writes it into the assembled front-matter, so nav labels and page
+ *     titles can never drift apart
+ *   - rewrites links: a relative link between two published files is correct
+ *     *on disk* but meaningless at a route, so published targets become
+ *     routes, unpublished-but-real files become repo blob links (reported as
+ *     `external`), and links that resolve to nothing are reported `broken`
+ *   - footers the page with the exact repo file it came from, so a reader who
+ *     spots a mistake knows where to fix it
+ *
+ * It also emits the publish manifest — every source path that made it into
+ * the site — which the CI gate uploads and diffs so growing the public
+ * surface is a thing a reviewer sees.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { pathKind } from "./discover.js";
+import { hasReservedSegment } from "./schema.js";
+const DEFAULT_REPO_URL = "https://github.com/mesh-tech/mesh-platform";
+const DEFAULT_IGNORE_LINK_PREFIXES = ["node_modules/"];
+/**
+ * Split a markdown document into front-matter and body. Only a `---` fence on
+ * the very first line counts — a horizontal rule later in the prose is not
+ * front-matter. A YAML parse failure is not fatal: the document is treated as
+ * having no front-matter (the heading/filename title fallbacks still apply),
+ * because one bad page must not take the whole site down at assemble time.
+ */
+export function splitFrontMatter(markdown) {
+    const normalized = markdown.replace(/^\uFEFF/, "");
+    if (!normalized.startsWith("---\n") && !normalized.startsWith("---\r\n")) {
+        return { data: {}, body: markdown, hasFrontMatter: false };
+    }
+    const end = normalized.indexOf("\n---", 4);
+    if (end === -1)
+        return { data: {}, body: markdown, hasFrontMatter: false };
+    const rawBlock = normalized.slice(4, end);
+    const bodyStart = normalized.indexOf("\n", end + 1);
+    const body = (bodyStart === -1 ? "" : normalized.slice(bodyStart + 1)).replace(/^\r?\n/, "");
+    try {
+        const data = parseYaml(rawBlock);
+        if (data && typeof data === "object" && !Array.isArray(data)) {
+            return {
+                data: data,
+                body,
+                hasFrontMatter: true,
+            };
+        }
+    }
+    catch {
+        // fall through to the no-front-matter shape
+    }
+    return { data: {}, body, hasFrontMatter: true };
+}
+/** Serialize front-matter data + body back into a markdown document. */
+function joinFrontMatter(data, body) {
+    const lines = Object.entries(data).map(([key, value]) => {
+        if (typeof value === "number" || typeof value === "boolean")
+            return `${key}: ${value}`;
+        const text = String(value);
+        // Quote only when YAML would misread the bare form.
+        return /^[\w .,'’()/-]+$/.test(text)
+            ? `${key}: ${text}`
+            : `${key}: ${JSON.stringify(text)}`;
+    });
+    return `---\n${lines.join("\n")}\n---\n\n${body.replace(/^\s*\n/, "")}`;
+}
+// ---------------------------------------------------------------------------
+// Title derivation
+// ---------------------------------------------------------------------------
+/** First `#` heading text, or undefined. Headings inside code fences don't count. */
+function firstHeading(body) {
+    let inFence = false;
+    for (const line of body.split("\n")) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const match = /^#\s+(.+?)\s*#*\s*$/.exec(line);
+        if (match)
+            return match[1].trim();
+    }
+    return undefined;
+}
+/** Titleize a filename stem for the filename-fallback case: `hub-dev-local` → "Hub dev local". */
+function titleizeStem(stem) {
+    const words = stem.replace(/[-_]+/g, " ").trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/**
+ * The title derivation order, fixed by the design: front-matter `title:` →
+ * first `#` heading → filename. `sidebar_label` wins for the nav when present
+ * (Zudoku honours it), but the document still gets its real title.
+ */
+export function deriveTitle(frontMatter, body, source) {
+    const fmTitle = frontMatter.title;
+    if (typeof fmTitle === "string" && fmTitle.trim())
+        return fmTitle.trim();
+    const heading = firstHeading(body);
+    if (heading)
+        return heading;
+    const stem = path.posix.basename(source).replace(/\.md$/i, "");
+    return titleizeStem(stem);
+}
+function scanLinks(markdown) {
+    const hits = [];
+    const lines = markdown.split("\n");
+    let offset = 0;
+    let inFence = null;
+    for (const line of lines) {
+        const fenceMatch = /^(\s{0,3})(`{3,}|~{3,})/.exec(line);
+        if (fenceMatch) {
+            if (!inFence) {
+                inFence = { marker: fenceMatch[2][0] };
+            }
+            else if (fenceMatch[2].startsWith(inFence.marker)) {
+                inFence = null;
+            }
+            offset += line.length + 1;
+            continue;
+        }
+        if (inFence) {
+            offset += line.length + 1;
+            continue;
+        }
+        // Reference definitions: [id]: href — the href runs to end of line
+        // (optionally followed by a title). Rewrite in place.
+        const refDef = /^ {0,3}\[[^\]]+\]:\s*(\S+)/.exec(line);
+        if (refDef) {
+            const href = refDef[1];
+            const start = offset + line.indexOf(href);
+            hits.push({ start, end: start + href.length, href });
+            offset += line.length + 1;
+            continue;
+        }
+        // Inline links/images, skipping inline code spans.
+        let i = 0;
+        while (i < line.length) {
+            const ch = line[i];
+            if (ch === "`") {
+                const run = /^`+/.exec(line.slice(i))[0];
+                const close = line.indexOf(run, i + run.length);
+                i = close === -1 ? line.length : close + run.length;
+                continue;
+            }
+            if (ch === "<") {
+                const close = line.indexOf(">", i);
+                i = close === -1 ? line.length : close + 1;
+                continue;
+            }
+            if (ch === "!" && line[i + 1] === "[") {
+                i = scanBracketLink(line, i + 1, offset, hits);
+                continue;
+            }
+            if (ch === "[") {
+                i = scanBracketLink(line, i, offset, hits);
+                continue;
+            }
+            i++;
+        }
+        offset += line.length + 1;
+    }
+    return hits;
+}
+/**
+ * At `line[i] === "["`, try to read `[...](href …)` or `[...][id]`. Only the
+ * `(...)` form carries an inline href we can rewrite; reference uses are
+ * covered by rewriting their definitions.
+ */
+function scanBracketLink(line, open, lineOffset, hits) {
+    const closeBracket = line.indexOf("]", open);
+    if (closeBracket === -1)
+        return line.length;
+    if (line[closeBracket + 1] !== "(")
+        return closeBracket + 1;
+    let j = closeBracket + 2;
+    while (j < line.length && /\s/.test(line[j]))
+        j++;
+    if (line[j] === "<") {
+        const end = line.indexOf(">", j);
+        if (end === -1)
+            return line.length;
+        hits.push({
+            start: lineOffset + j + 1,
+            end: lineOffset + end,
+            href: line.slice(j + 1, end),
+        });
+        return end + 1;
+    }
+    const closeParen = line.indexOf(")", j);
+    if (closeParen === -1)
+        return line.length;
+    const inner = line.slice(j, closeParen).trim();
+    // href may be followed by a "title" — split on the first space.
+    const space = inner.search(/\s/);
+    const href = space === -1 ? inner : inner.slice(0, space);
+    if (href) {
+        const start = lineOffset + line.indexOf(href, j);
+        hits.push({ start, end: start + href.length, href });
+    }
+    return closeParen + 1;
+}
+/**
+ * Remove HTML comments (`<!-- … -->`, single- or multi-line) from a page body.
+ * They are invisible in any rendered output by definition — the source file
+ * keeps them — and multi-line comments currently crash Zudoku's MDX plugin
+ * (`chunks[startIndex].slice is not a function`), which turns one authored
+ * comment into a failed site build. Fenced code blocks are left alone: a doc
+ * *teaching* HTML comments shows them as code, and that code must survive.
+ */
+export function stripHtmlComments(body) {
+    const lines = body.split("\n");
+    const out = [];
+    let inFence = false;
+    let inComment = false;
+    for (const line of lines) {
+        if (/^\s*(```|~~~)/.test(line)) {
+            if (!inComment)
+                inFence = !inFence;
+            if (!inComment)
+                out.push(line);
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        let rest = line;
+        let rebuilt = "";
+        while (rest.length > 0) {
+            if (inComment) {
+                const end = rest.indexOf("-->");
+                if (end === -1) {
+                    rest = "";
+                    break;
+                }
+                inComment = false;
+                rest = rest.slice(end + 3);
+                continue;
+            }
+            const start = rest.indexOf("<!--");
+            if (start === -1) {
+                rebuilt += rest;
+                break;
+            }
+            rebuilt += rest.slice(0, start);
+            inComment = true;
+            rest = rest.slice(start + 4);
+        }
+        // A line that held only a comment collapses to nothing; a line with prose
+        // around a comment keeps its prose.
+        if (rebuilt.trim() !== "" || !inComment)
+            out.push(rebuilt.replace(/\s+$/, ""));
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function isAbsoluteHref(href) {
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(href);
+}
+function normalizeRepoPath(value) {
+    return path.posix
+        .normalize(value.replace(/\\/g, "/"))
+        .replace(/^\.\//, "")
+        .replace(/\/+$/, "");
+}
+function splitHash(href) {
+    const index = href.indexOf("#");
+    return index === -1
+        ? [href, ""]
+        : [href.slice(0, index), href.slice(index + 1)];
+}
+/**
+ * Resolve one link, exactly the #3503 semantics with routes instead of slugs:
+ *
+ *   - anchors, absolute URLs, mailto: → untouched
+ *   - an `ignoreLinkPrefixes` match → untouched (declared deliberately
+ *     unresolvable — the app-kit README's `node_modules/…` guidance exists in
+ *     a tenant's install, never in this repo)
+ *   - a file the portal publishes → that page's route
+ *   - a directory whose index/README the portal publishes → that route
+ *   - a real repo file the portal does not publish → a repo blob link
+ *     (reported `external`)
+ *   - nothing → reported `broken`
+ *   - a site-rooted path (`/guides/x`) → validated against the route set, so a
+ *     typo'd route fails the gate instead of shipping as a 404
+ */
+export function resolveLink(args) {
+    const { href, pageRoute, sourceDir, sourceIndex, routes, repoUrl } = args;
+    if (href.startsWith("#") || isAbsoluteHref(href))
+        return { href };
+    if (args.ignoreLinkPrefixes.some((prefix) => href.startsWith(prefix)))
+        return { href };
+    const [rawTarget, rawHash] = splitHash(href);
+    const hash = rawHash ? `#${rawHash}` : "";
+    if (rawTarget === "")
+        return { href };
+    // Site-rooted route reference.
+    if (rawTarget.startsWith("/")) {
+        const route = rawTarget.replace(/\/$/, "") || "/";
+        return routes.has(route)
+            ? { href: `${route}${hash}` }
+            : { href, issue: { kind: "broken", page: pageRoute, href } };
+    }
+    const repoPath = normalizeRepoPath(path.posix.join(sourceDir, rawTarget));
+    const page = sourceIndex.get(repoPath);
+    if (page)
+        return { href: `${page.route}${hash}` };
+    // A link to a directory conventionally means its index page.
+    for (const candidate of [`${repoPath}/index.md`]) {
+        const indexPage = sourceIndex.get(normalizeRepoPath(candidate));
+        if (indexPage)
+            return { href: `${indexPage.route}${hash}` };
+    }
+    const kind = args.pathKind(repoPath);
+    if (kind !== null) {
+        const base = repoUrl.replace(/\/$/, "").replace(/\/(blob|tree)$/, "");
+        return {
+            href: `${base}/${kind === "dir" ? "tree" : "blob"}/main/${repoPath}${hash}`,
+            issue: { kind: "external", page: pageRoute, href },
+        };
+    }
+    return { href, issue: { kind: "broken", page: pageRoute, href } };
+}
+/** Rewrite every link in a page body, collecting issues. */
+export function rewriteLinks(args) {
+    const issues = [];
+    const hits = scanLinks(args.body);
+    if (hits.length === 0)
+        return { body: args.body, issues };
+    const sourceDir = path.posix.dirname(args.page.source);
+    let out = "";
+    let cursor = 0;
+    for (const hit of hits) {
+        const resolution = resolveLink({
+            href: hit.href,
+            pageRoute: args.page.route,
+            sourceDir,
+            sourceIndex: args.sourceIndex,
+            routes: args.routes,
+            ignoreLinkPrefixes: args.ignoreLinkPrefixes,
+            pathKind: args.pathKind,
+            repoUrl: args.repoUrl,
+        });
+        out += args.body.slice(cursor, hit.start) + resolution.href;
+        cursor = hit.end;
+        if (resolution.issue)
+            issues.push(resolution.issue);
+    }
+    out += args.body.slice(cursor);
+    return { body: out, issues };
+}
+/** A page's full route: section slug + route path. "/" for the site home. */
+export function pageRoute(page) {
+    const joined = [page.root.slug, page.routePath].filter(Boolean).join("/");
+    return `/${joined}`.replace(/\/$/, "") || "/";
+}
+/** The assembled file path (no leading slash, with extension). */
+export function pageFilePath(route) {
+    return route === "/" ? "index.md" : `${route.slice(1)}.md`;
+}
+/**
+ * Assemble the discovered pages into `outDir`. Pure function of the repo tree
+ * — the same inputs always produce the same tree, manifest, and navigation.
+ */
+export function assemblePortal(options) {
+    const { repoRoot, discovery, outDir } = options;
+    const repoUrl = options.repoUrl ?? DEFAULT_REPO_URL;
+    const ignoreLinkPrefixes = options.ignoreLinkPrefixes ?? DEFAULT_IGNORE_LINK_PREFIXES;
+    // Build the page model first: routes must all exist before any link can be
+    // rewritten against them.
+    const pages = discovery.pages.map((page) => {
+        const route = pageRoute(page);
+        return {
+            source: page.source,
+            route,
+            filePath: pageFilePath(route),
+            title: "",
+            sectionTitle: page.root.config.title,
+            sectionOrder: page.root.config.order,
+            sectionSlug: page.root.slug,
+        };
+    });
+    const sourceIndex = new Map(pages.map((p) => [normalizeRepoPath(p.source), p]));
+    const routes = new Set(pages.map((p) => p.route));
+    const brokenLinks = [];
+    const externalLinks = [];
+    rmSync(outDir, { recursive: true, force: true });
+    mkdirSync(outDir, { recursive: true });
+    for (const page of pages) {
+        const raw = readFileSync(path.join(repoRoot, page.source), "utf-8");
+        const frontMatter = splitFrontMatter(raw);
+        const title = deriveTitle(frontMatter.data, frontMatter.body, page.source);
+        page.title = title;
+        const order = frontMatter.data.order;
+        if (typeof order === "number" && Number.isFinite(order))
+            page.order = order;
+        const rewritten = rewriteLinks({
+            body: stripHtmlComments(frontMatter.body),
+            page,
+            sourceIndex,
+            routes,
+            ignoreLinkPrefixes,
+            pathKind: (rel) => pathKind(path.join(repoRoot, rel)),
+            repoUrl,
+        });
+        for (const issue of rewritten.issues) {
+            (issue.kind === "broken" ? brokenLinks : externalLinks).push(issue);
+        }
+        // Front-matter: keep the author's, guarantee `title`. `showLastModified`
+        // is off — the assembled tree is rebuilt every run, so git-mtime-derived
+        // dates would say "today" on every page.
+        const outData = { ...frontMatter.data, title };
+        const blobBase = repoUrl.replace(/\/$/, "").replace(/\/(blob|tree)$/, "");
+        const sourceNote = `\n\n---\n\n<sub>Source: [\`${page.source}\`](${blobBase}/blob/main/${page.source}) — edit that file, not this page.</sub>\n`;
+        const outFile = path.join(outDir, page.filePath);
+        mkdirSync(path.dirname(outFile), { recursive: true });
+        writeFileSync(outFile, joinFrontMatter(outData, rewritten.body.trimEnd() + sourceNote));
+    }
+    const navigation = buildNavigation(pages);
+    // Fail-closed: no assembled output path may contain a reserved segment. The
+    // walk already skips reserved directories, so a violation here means the
+    // exclusion itself broke — exactly what the gate exists to catch.
+    const reservedViolations = pages
+        .map((p) => p.filePath)
+        .filter((filePath) => hasReservedSegment(filePath));
+    const publishManifest = {
+        version: 1,
+        count: pages.length,
+        sources: pages.map((p) => p.source).sort(),
+    };
+    return {
+        outDir,
+        pages,
+        navigation,
+        brokenLinks,
+        externalLinks,
+        publishManifest,
+        reservedViolations,
+    };
+}
+function titleizeDir(name) {
+    return titleizeStem(name);
+}
+/**
+ * Build the Zudoku navigation array from the assembled pages.
+ *
+ * Shape: one root category ("Documentation", clicking it lands on the home
+ * page) whose items are one non-collapsible category per doc root — the
+ * sidebar's section headers — each holding the section's tree: pages as doc
+ * items, directories as nested categories. A directory with an index page
+ * becomes a clickable category (its link); the section's own index page
+ * becomes the section category's link. Order is front-matter `order:` first,
+ * then filename — never declared anywhere but the files themselves.
+ */
+export function buildNavigation(pages) {
+    const sections = new Map();
+    for (const page of pages) {
+        const key = page.sectionSlug;
+        if (!sections.has(key)) {
+            sections.set(key, {
+                title: page.sectionTitle,
+                order: page.sectionOrder,
+                slug: page.sectionSlug,
+                pages: [],
+            });
+        }
+        sections.get(key).pages.push(page);
+    }
+    const sortedSections = [...sections.values()].sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+    const sortPages = (list) => [...list].sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) -
+        (b.order ?? Number.MAX_SAFE_INTEGER) ||
+        a.filePath.localeCompare(b.filePath));
+    // A nav doc reference (item or category link — same shape in both places).
+    // A `path` is a CUSTOM path in Zudoku: when it equals the file-derived
+    // route, the build moves the file's entry onto itself and deletes it
+    // (resolveCustomNavigationPaths compares `path === file` without the
+    // leading slash). The assembler already names files so the file route IS
+    // the desired route — so `path` is only emitted for the one genuinely
+    // custom mapping: the home page (file "index" → "/").
+    const docRef = (page) => {
+        const file = page.filePath.replace(/\.md$/, "");
+        return page.route === `/${file}`
+            ? file
+            : { type: "doc", file, path: page.route };
+    };
+    const items = [];
+    for (const section of sortedSections) {
+        const indexPage = section.pages.find((p) => p.route === `/${section.slug}` ||
+            (section.slug === "" && p.route === "/"));
+        const rest = section.pages.filter((p) => p !== indexPage);
+        // Group remaining pages by their section-relative directory.
+        const rootPages = [];
+        const dirs = new Map();
+        for (const page of rest) {
+            const rel = page.route.replace(/^\//, "");
+            const sectionPrefix = section.slug ? `${section.slug}/` : "";
+            const relParts = (sectionPrefix && rel.startsWith(sectionPrefix)
+                ? rel.slice(sectionPrefix.length)
+                : rel)
+                .split("/")
+                .filter(Boolean);
+            if (relParts.length <= 1) {
+                rootPages.push(page);
+                continue;
+            }
+            const dirKey = relParts.slice(0, -1).join("/");
+            if (!dirs.has(dirKey)) {
+                dirs.set(dirKey, {
+                    label: titleizeDir(relParts[relParts.length - 2]),
+                    routePath: relParts.slice(0, -1).join("/"),
+                    pages: [],
+                    dirs: new Map(),
+                });
+            }
+            dirs.get(dirKey).pages.push(page);
+        }
+        const byRoute = new Map(section.pages.map((p) => [p.route, p]));
+        const childItems = sortPages(rootPages).map(docRef);
+        for (const dir of [...dirs.values()].sort((a, b) => a.routePath.localeCompare(b.routePath))) {
+            const dirRoute = `/${[section.slug, dir.routePath].filter(Boolean).join("/")}`.replace(/\/$/, "") || "/";
+            const dirIndex = byRoute.get(dirRoute);
+            const grandchildren = sortPages(dir.pages.filter((p) => p !== dirIndex)).map(docRef);
+            if (grandchildren.length === 0 && dirIndex) {
+                childItems.push(docRef(dirIndex));
+                continue;
+            }
+            childItems.push({
+                type: "category",
+                label: dir.label,
+                ...(dirIndex ? { link: docRef(dirIndex) } : {}),
+                items: grandchildren,
+            });
+        }
+        items.push({
+            type: "category",
+            label: section.title,
+            collapsible: false,
+            ...(indexPage ? { link: docRef(indexPage) } : {}),
+            items: childItems,
+        });
+    }
+    return [
+        {
+            type: "category",
+            label: "Documentation",
+            link: { type: "doc", file: "index", path: "/" },
+            items,
+        },
+    ];
+}
+// ---------------------------------------------------------------------------
+// Generated config + manifests
+// ---------------------------------------------------------------------------
+/**
+ * Render the generated `zudoku.config.ts`. It is regenerated on every
+ * assemble and gitignored — the navigation manifest is derived state, and
+ * committed derived state is how the old manifest rotted.
+ */
+export function renderZudokuConfig(args) {
+    const versionLine = args.baseline
+        ? `Documents @mesh-tech/* ${args.baseline} · built from ${args.commit ?? "unknown"}`
+        : `Local build · ${args.commit ?? "unknown"}`;
+    const config = {
+        metadata: {
+            title: args.title,
+            description: args.description,
+        },
+        site: {
+            title: args.title,
+            logoUrl: "/",
+            footer: {
+                copyright: `${versionLine} · /version.json`,
+            },
+        },
+        theme: "THEME_IMPORT",
+        navigation: args.navigation,
+        docs: {
+            files: ["/content/**/*.{md,mdx}"],
+            defaultOptions: {
+                toc: true,
+                showLastModified: false,
+            },
+        },
+        redirects: [],
+        // Search is Zudoku's built-in Pagefind index — no config needed.
+    };
+    const json = JSON.stringify(config, null, 2).replace(`"THEME_IMPORT"`, "portalTheme");
+    return `/**
+ * GENERATED by \`mesh docs portal\` — do not edit.
+ *
+ * The navigation array is derived from the repo's docs.json roots and the
+ * markdown tree beneath them. To change what the site publishes, change the
+ * tree; to change section labels or order, change the root's docs.json.
+ * Regenerate: pnpm exec mesh docs portal --assemble-only
+ */
+import type { ZudokuConfig } from "zudoku";
+import { portalTheme } from "./theme.js";
+
+const config: ZudokuConfig = ${json};
+
+export default config;
+`;
+}
+/** version.json — the version-parity contract the parity monitor asserts. */
+export function renderVersionJson(args) {
+    return `${JSON.stringify({
+        meshBaseline: args.baseline ?? null,
+        commit: args.commit,
+        builtAt: args.builtAt,
+    }, null, 2)}\n`;
+}
+/** Best-effort short commit of the repo being assembled. */
+export function currentCommit(repoRoot) {
+    try {
+        return execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+            cwd: repoRoot,
+            encoding: "utf-8",
+        }).trim();
+    }
+    catch {
+        return "unknown";
+    }
+}
+/** The fixed lockstep group's version, read from app-kit's package.json. */
+export function currentBaseline(repoRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(repoRoot, "libs/app-kit/package.json"), "utf-8"));
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compute the publish set of another git ref WITHOUT checking it out — the
+ * docs.json files and tree listing are read via `git show`/`git ls-tree`, and
+ * the same discovery rules (reserved segments, README exclusion, include[])
+ * are applied to that listing. Lets a PR diff its publish set against its
+ * merge base in a CI job that has no second worktree and no installed deps
+ * for the base.
+ *
+ * APPROXIMATION, base side only: this reimplementation skips schema
+ * validation (an invalid docs.json publishes nothing in real discovery but
+ * is walked here), nested-root rejection, and route-collision detection, so
+ * it can OVER-report the base's publish set (a spurious "removed" row in the
+ * summary) — never under-report the head's. The head side is always real
+ * discovery; the gate's assertions never read this function.
+ */
+export function publishSetAtRef(repoRoot, ref) {
+    const git = (gitArgs) => execFileSync("git", gitArgs, {
+        cwd: repoRoot,
+        encoding: "utf-8",
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const allFiles = git(["ls-tree", "-r", "--name-only", ref])
+        .split("\n")
+        .filter(Boolean);
+    const docsJsonPaths = allFiles.filter((file) => file === "docs.json" || file.endsWith("/docs.json"));
+    const published = new Set();
+    for (const docsJsonPath of docsJsonPaths) {
+        const rootDir = docsJsonPath === "docs.json"
+            ? ""
+            : docsJsonPath.slice(0, -"/docs.json".length);
+        if (rootDir && hasReservedSegment(rootDir))
+            continue;
+        let config;
+        try {
+            config = JSON.parse(git(["show", `${ref}:${docsJsonPath}`]));
+        }
+        catch {
+            continue;
+        }
+        const prefix = rootDir ? `${rootDir}/` : "";
+        for (const file of allFiles) {
+            if (!file.startsWith(prefix) || !file.toLowerCase().endsWith(".md"))
+                continue;
+            const rel = file.slice(prefix.length);
+            if (hasReservedSegment(rel))
+                continue;
+            if (path.posix.basename(file).toLowerCase() === "readme.md")
+                continue;
+            published.add(file);
+        }
+        for (const include of config.include ?? []) {
+            const normalized = include.replace(/\\/g, "/").replace(/^\.\//, "");
+            if (hasReservedSegment(normalized))
+                continue;
+            if (allFiles.includes(normalized))
+                published.add(normalized);
+        }
+    }
+    return [...published].sort();
+}
+export function diffPublishSets(base, head) {
+    const baseSet = new Set(base);
+    const headSet = new Set(head);
+    return {
+        added: head.filter((source) => !baseSet.has(source)),
+        removed: base.filter((source) => !headSet.has(source)),
+    };
+}
+/** Render the publish-set diff as a GitHub job-summary markdown block. */
+export function renderPublishSetSummary(manifest, diff) {
+    const lines = [
+        `## Docs portal publish set`,
+        ``,
+        `**${manifest.count} pages publish** from this tree.`,
+        ``,
+    ];
+    if (diff && (diff.added.length > 0 || diff.removed.length > 0)) {
+        lines.push(`### Changes vs the merge base`, ``);
+        for (const source of diff.added)
+            lines.push(`- ➕ \`${source}\``);
+        for (const source of diff.removed)
+            lines.push(`- ➖ \`${source}\``);
+        lines.push(``, `Growing the public surface is a deliberate act — a reviewer should see this list.`);
+    }
+    else if (diff) {
+        lines.push(`No change vs the merge base.`);
+    }
+    lines.push(``, `<details><summary>Full publish set</summary>`, ``);
+    for (const source of manifest.sources)
+        lines.push(`- \`${source}\``);
+    lines.push(``, `</details>`);
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=assemble.js.map