@heroiclands/package-build 0.6.1 → 3.0.1

package/engine/macros.mjs

@@ -0,0 +1,333 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Macros pack compiler — produces JSON pack files for the "macros" Foundry
+ * compendium from markdown notes in the `assets/content/` tree.
+ *
+ * A `type: macro` note compiles into **two** documents, and this module writes
+ * only the first of them:
+ *
+ * 1. the **Macro**, whose `command` is the script the note carries; and
+ * 2. a **JournalEntry** holding the note's documentation, compiled by the
+ *    journals pass exactly as an item's prose is (see `item-docs.mjs`) and
+ *    addressed by the virtual `docmacro/<shortcode>` qualifier.
+ *
+ * **The command is read from the raw markdown, never from the journal
+ * pipeline's output.** The two copies diverge on purpose: the journal's is
+ * table-expanded and wikilink-converted, so it is prose *about* the script,
+ * while the executable copy must be exactly what the author typed. The
+ * command is the first **language-tagged** JS fence on the page anchored
+ * `{#script}`; prose around it and any later fence are ignored here and still
+ * render in the journal.
+ *
+ * **Why an anchored page rather than "the first fence in the note".** The
+ * anchor is what makes the script addressable — `[[docmacro-autoattack#script]]`
+ * opens the page holding it — and what lets a note document its macro with
+ * example snippets that are plainly not the macro.
+ *
+ * **This does not compile data into code.** A Macro's `command` is authored
+ * source shipped as content and executed by Foundry's own macro runner under
+ * the user's permission — the mechanism the security model already blesses.
+ * Nothing here evaluates, compiles, or revives anything.
+ *
+ * Not a standalone script — exports the `Macros` compiler class, imported and
+ * driven by `packages/content-build/engine/generate.mjs` (via `npm run build:compiledb`).
+ *
+ * The walk itself — filtering by package and type, skipping drafts,
+ * expanding tables, converting wikilinks, writing the JSON and counting
+ * errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
+ * states only what makes this pass its own (#1509).
+ */
+
+import log from "loglevel";
+
+import {
+    sohlField,
+    resolveName,
+    resolveImg,
+    defaultStats,
+} from "./helpers.mjs";
+import { BasePackCompiler } from "./base-compiler.mjs";
+import { splitPages } from "./journals.mjs";
+
+/**
+ * The anchor the executable script lives under: `# Script {#script}`.
+ *
+ * A reserved slug rather than a heading name, because the heading is prose an
+ * author may word freely ("The Script", "Source") while the address must be
+ * stable — it is what the compiler looks for and what an inbound section link
+ * spells.
+ */
+export const MACRO_SCRIPT_ANCHOR = "script";
+
+/**
+ * The Foundry macro types (`CONST.MACRO_TYPES`).
+ *
+ * Only `script` compiles. `chat` is a real Foundry type but a different
+ * document altogether — its `command` is chat text, not source, so none of the
+ * fence rules above apply to it — and half-implementing it would ship a macro
+ * whose body was a code block posted verbatim into chat.
+ */
+export const MACRO_TYPES = Object.freeze(["script", "chat"]);
+
+/** The Foundry macro scopes (`CONST.MACRO_SCOPES`), in schema order. */
+export const MACRO_SCOPES = Object.freeze(["global", "actors", "actor"]);
+
+/**
+ * Foundry's own default macro artwork, used when a note authors no `img`.
+ *
+ * A core path, deliberately: it is not translated by {@link resolveImg} (which
+ * roots `icons/…` under this system's assets), so it must be stated after that
+ * translation rather than as authored frontmatter.
+ */
+export const DEFAULT_MACRO_IMG = "icons/svg/dice-target.svg";
+
+/** The fence tags that mark a block as the macro's executable source. */
+const JS_FENCE_TAGS = new Set(["js", "javascript"]);
+
+/**
+ * The body of the first **language-tagged** JavaScript fence in a markdown
+ * block, verbatim.
+ *
+ * "Language-tagged" is the whole rule: an untagged fence is a code sample
+ * whose language nobody stated, and treating it as the macro's source would
+ * make an author's illustrative snippet executable. A fence tagged for another
+ * language is skipped for the same reason.
+ *
+ * The opening delimiter may be longer than three backticks, so a script may
+ * itself contain a fence; the closing delimiter must be at least as long, as
+ * CommonMark requires.
+ *
+ * @param {string} markdown - The markdown to search.
+ * @returns {string|null} The fence's contents, with no trailing newline, or
+ *   `null` when the block holds no tagged JS fence.
+ */
+export function extractJsFence(markdown) {
+    const lines = String(markdown ?? "").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const open = lines[i].match(/^\s*(`{3,})\s*([^\s`]*)/);
+        if (!open) continue;
+        const [, delim, info] = open;
+        // Every fence is consumed, tagged or not — the scan resumes after its
+        // close, so a snippet inside an untagged block can never be read as
+        // the macro's source.
+        let end = -1;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (new RegExp(`^\\s*\`{${delim.length},}\\s*$`).test(lines[j])) {
+                end = j;
+                break;
+            }
+        }
+        // An unterminated fence closes nothing, so there is no verbatim body
+        // to take and nothing after it to keep scanning.
+        if (end === -1) return null;
+        if (JS_FENCE_TAGS.has(info.toLowerCase())) {
+            return lines.slice(i + 1, end).join("\n");
+        }
+        i = end;
+    }
+    return null;
+}
+
+/**
+ * The `command` a macro note compiles to: the first tagged JS fence on its
+ * `{#script}` page.
+ *
+ * Read from the **raw** note body, before tables are expanded and wikilinks
+ * converted, so the executable copy is exactly what the author wrote even
+ * where the journal's rendered copy of the same fence is not.
+ *
+ * @param {string} body - The note's markdown body, frontmatter stripped.
+ * @param {string} name - The macro's name, for the error messages.
+ * @returns {string} The macro's command.
+ * @throws {Error} When the note declares no `{#script}` page, or that page
+ *   holds no language-tagged JS fence. Either is a build error: a macro with
+ *   no command is a macro-bar button that does nothing.
+ */
+export function macroCommand(body, name) {
+    const page = splitPages(String(body ?? ""), name).find(
+        (p) => p.anchorSlug === MACRO_SCRIPT_ANCHOR,
+    );
+    if (!page) {
+        throw new Error(
+            `macro "${name}": no page declares the {#${MACRO_SCRIPT_ANCHOR}} ` +
+                `anchor — a macro's source lives under a heading carrying it, ` +
+                `e.g. "# Script {#${MACRO_SCRIPT_ANCHOR}}"`,
+        );
+    }
+    const command = extractJsFence(page.markdown);
+    if (command === null) {
+        throw new Error(
+            `macro "${name}": the {#${MACRO_SCRIPT_ANCHOR}} page holds no ` +
+                `language-tagged JavaScript fence — tag it \`\`\`js (an ` +
+                `untagged fence is a code sample, not the macro's source)`,
+        );
+    }
+    return command;
+}
+
+/**
+ * The **Foundry** macro type a note compiles to — not the note's `type:`,
+ * which stays `macro` because that is what routes it to this pack.
+ *
+ * Foundry's schema initialises `type` to `CHAT`, so a script macro has to say
+ * so explicitly; this states it for every note and defaults the authored field
+ * to `script`, which is the only kind that compiles.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} label - The macro, for the error message.
+ * @returns {"script"} The macro type.
+ * @throws {Error} For `chat`, and for any value Foundry does not define.
+ */
+export function resolveMacroType(fm, label) {
+    const raw = String(sohlField(fm, "macroType", "script") ?? "script");
+    if (raw === "script") return "script";
+    if (raw === "chat") {
+        throw new Error(
+            `macro "${label}": sohl.macroType "chat" is not supported — a chat ` +
+                `macro's command is chat text rather than source, so none of ` +
+                `the {#${MACRO_SCRIPT_ANCHOR}} fence rules apply to it`,
+        );
+    }
+    throw new Error(
+        `macro "${label}": unknown sohl.macroType "${raw}" — Foundry defines ` +
+            `${MACRO_TYPES.join(", ")}`,
+    );
+}
+
+/**
+ * The Foundry macro scope a note compiles to.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} label - The macro, for the error message.
+ * @returns {string} One of {@link MACRO_SCOPES}.
+ * @throws {Error} When the authored scope is not one Foundry defines — it
+ *   would fail the schema's `choices` validation at load and be replaced by
+ *   the default, shipping a macro whose authored reach had quietly widened.
+ */
+export function resolveMacroScope(fm, label) {
+    const raw = String(sohlField(fm, "macroScope", "global") ?? "global");
+    if (!MACRO_SCOPES.includes(raw)) {
+        throw new Error(
+            `macro "${label}": unknown sohl.macroScope "${raw}" — Foundry ` +
+                `defines ${MACRO_SCOPES.join(", ")}`,
+        );
+    }
+    return raw;
+}
+
+/**
+ * A compiled Macro document, in the shape the LevelDB packer consumes.
+ *
+ * @typedef {object} MacroDocument
+ * @property {string} name - The macro's display name.
+ * @property {string} type - The Foundry macro type; always `script`.
+ * @property {null} author - No authoring user; Foundry's field is nullable.
+ * @property {string} img - The Foundry-relative artwork path.
+ * @property {string} scope - One of {@link MACRO_SCOPES}.
+ * @property {string} command - The script the macro runs.
+ * @property {string|null} folder - The folder id, or `null` for the root.
+ * @property {number} sort - Sort order within its folder.
+ * @property {{default: number}} ownership - Default ownership level.
+ * @property {object} flags - Document flags from frontmatter.
+ * @property {string} _id - The Foundry document id.
+ * @property {object} _stats - The `_stats` block.
+ * @property {string} _key - The LevelDB key, `!macros!<id>`.
+ */
+
+/**
+ * The compendium envelope for one Macro.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {object} opts
+ * @param {string} opts.command - The command, from {@link macroCommand}.
+ * @param {string|null} [opts.folder] - The resolved folder id.
+ * @param {object} [opts.stats] - The `_stats` block.
+ * @returns {MacroDocument} The Macro document.
+ * @throws {Error} When the frontmatter's macro type or scope is unusable.
+ */
+export function buildMacroEntry(
+    fm,
+    { command, folder = null, stats = defaultStats() },
+) {
+    const name = resolveName(fm);
+    const id = fm.id;
+    return {
+        name,
+        // Stated rather than defaulted: Foundry's schema initialises `type` to
+        // CHAT, so an omitted type ships a macro that posts its own source
+        // into chat instead of running.
+        type: resolveMacroType(fm, name),
+        author: null,
+        img: resolveImg(fm.img) || DEFAULT_MACRO_IMG,
+        scope: resolveMacroScope(fm, name),
+        command,
+        folder,
+        sort: 0,
+        ownership: { default: 0 },
+        flags: fm.flags || {},
+        _id: id,
+        _stats: stats,
+        _key: `!macros!${id}`,
+    };
+}
+
+/**
+ * Macros pack compiler.
+ *
+ * Walks the content tree and compiles every `package: sohl`, `type: macro`
+ * note into one Macro document. The same note's documentation is compiled by
+ * the journals pass; neither pass reads the other's output.
+ */
+export class Macros extends BasePackCompiler {
+    static id = "macros";
+    static label = "macro";
+
+    /**
+     * The command must be exactly what the author typed, so this pass reads the
+     * note as authored: no table expansion, no wikilink conversion, and no
+     * content-wide link index it would never consult. The journals pass
+     * compiles the converted copy of the same body independently.
+     */
+    static convertsWikilinks = false;
+
+    /**
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True for a `macro` note.
+     */
+    selects(fm) {
+        return fm.type === "macro";
+    }
+
+    /**
+     * Compile one note into a Macro.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} body - The note body, frontmatter stripped and otherwise
+     *   exactly as authored.
+     * @returns {MacroDocument} The Macro document.
+     */
+    buildEntry(fm, body) {
+        const name = resolveName(fm);
+        return buildMacroEntry(fm, {
+            command: macroCommand(body, name),
+            folder: this.folderResolver(sohlField(fm, "folder", null)),
+        });
+    }
+
+    /** @inheritdoc */
+    reportDetail(stats) {
+        log.debug(`Skipped ${stats.skippedOther} non-macro file(s)`);
+    }
+}

package/engine/manifest-emit.mjs

@@ -0,0 +1,339 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Emitting this package's cross-package link manifest (#58).
+ *
+ * `engine/kb-manifest.mjs` owns the *format* — what an entry may say, how a
+ * version is read, how a foreign file resolves. This module owns the *pass*:
+ * walking a content tree and deriving, for every note it publishes, the
+ * addresses that entry states. The two halves were split across the format
+ * module and a hand-written script in each consuming repository, which is how
+ * the two scripts came to differ in ways nobody chose — one routes its UUIDs
+ * through the pack router and one does not, and neither knew.
+ *
+ * **The base is not an input.** Both scripts built a site-absolute URL and
+ * handed {@link buildManifest} the base it was built from, whose first act is
+ * to strip that same prefix back off; the value never reached the file. So
+ * nothing here composes one. An address is derived package-relative from the
+ * start, by {@link packageAddress}, and the emitting build's mount point is not
+ * a fact it has to be told (#1465).
+ *
+ * **The address scheme is configuration, and it is shared with the site build.**
+ * Where the content tree mounts inside the package and which note is a section's
+ * landing page differ between repositories and are both load-bearing — `sohl`
+ * records `kb/affliction/aconite/` and `thalorna` records
+ * `affiliation/the-aerarium-imperii/`. Reading one setting here and in the page
+ * emitter is what stops a manifest asserting an address the site does not
+ * publish, which resolves at build time and 404s for the reader.
+ *
+ * **Anchors are computed, not approximated.** The pass that splits a note into
+ * journal pages is {@link splitPages}, a pure function over the markdown body,
+ * so running it costs a parse and no I/O. Both scripts already ran it. An entry
+ * that silently lost its anchors would degrade every cross-package section link
+ * in every consumer, so there is no mode in which they are skipped.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { packageAddress } from "./content-address.mjs";
+import { canonicalKey, writeManifests } from "./kb-manifest.mjs";
+import { walkMarkdownTree } from "./helpers.mjs";
+import { compendiumUuid, packForType, pageUuid } from "./ids.mjs";
+import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
+import { journalPageId, splitPages } from "./journals.mjs";
+import { routerFor } from "./pack-router.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+
+/**
+ * The reserved anchor name for a journal's **first** page.
+ *
+ * Every journal has one and it is what an item's `docHtml` points at, but it
+ * carries no authored `{#slug}` — so without a reserved name the one page that
+ * always exists would be the one page the manifest could not address. It cannot
+ * collide with an authored slug, which is `[a-z0-9-]+`.
+ */
+export const LEAD_ANCHOR = "$lead";
+
+/**
+ * Every page of a note's journal, as `anchorName → whole UUID`.
+ *
+ * Whole, not a fragment appended to the entry's UUID: nothing owns a page
+ * address, so a complete link restates no fact, and it keeps the page-id hash
+ * out of the published contract entirely — a consumer resolves
+ * `[[docaffliction-aconite#crafting]]` with a lookup instead of reimplementing
+ * a sha256/base64/truncate rule.
+ *
+ * @param {string} entryUuid - The journal entry's UUID.
+ * @param {string} entryId - The entry's id, which page ids hash against.
+ * @param {string} body - The note's markdown body.
+ * @param {string} name - The note's name, used as the lead page's title.
+ * @returns {Record<string, string>} The anchors.
+ */
+export function anchorsOf(entryUuid, entryId, body, name) {
+    const anchors = {};
+    splitPages(body, name).forEach((page, index) => {
+        const uuid = pageUuid(entryUuid, journalPageId(entryId, page, index));
+        if (index === 0) anchors[LEAD_ANCHOR] = uuid;
+        if (page.anchorSlug) anchors[page.anchorSlug] = uuid;
+    });
+    return anchors;
+}
+
+/**
+ * The manifest entries a single note produces.
+ *
+ * An item note produces **two**: the item, and separately the JournalEntry its
+ * prose compiles into. They are two documents with two UUIDs, so they get two
+ * addresses; the item's entry points at the other by address rather than
+ * repeating its UUID, because the doc entry owns that fact (#1499). A `macro`
+ * note is the same arrangement (#1514), which is why the type set comes from
+ * {@link hasDocEntry} rather than being spelled here — the journals compiler
+ * reads the same one, so a manifest cannot claim documentation nothing compiled.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @param {string} name - The note's display name.
+ * @param {string} address - The note's package-relative address.
+ * @param {string} body - The note's markdown body.
+ * @param {object} ctx - Resolved identities: `{ contentPackage,
+ *   foundryPackageId, packRouter }`.
+ * @returns {Array<object>} One or two entries, in {@link buildManifest}'s shape.
+ */
+export function entriesForNote(fm, name, address, body, ctx) {
+    const { contentPackage, foundryPackageId, packRouter } = ctx;
+    const key = canonicalKey(contentPackage, fm.type, fm.shortcode);
+    // `buildManifest` records `packageRelative(url, base)`, so the pair it is
+    // given has to round-trip. The address is already package-relative, so the
+    // honest pair is the address under a base of `"/"` — which strips straight
+    // back off. Composing a real mount point here and removing it again is what
+    // the two consumer scripts did, and the value provably never reached the
+    // file.
+    const url = `/${address}`;
+
+    // A published address must name the pack the document actually shipped in:
+    // a consumer resolves the UUID verbatim, and a repository may ship several
+    // packs of one type (#1566).
+    const uuidFor = (type, id, routeFm) =>
+        id ?
+            compendiumUuid(
+                foundryPackageId,
+                type,
+                id,
+                routeFm ?
+                    packRouter.resolveOrNull(routeFm, packForType(type).docType)
+                :   packRouter.defaultOf("JournalEntry"),
+            )
+        :   undefined;
+
+    if (hasDocEntry(fm.type)) {
+        const docKey = canonicalKey(
+            contentPackage,
+            `doc${fm.type}`,
+            fm.shortcode,
+        );
+        const docEntryId = fm.id ? itemDocEntryId(fm.id) : undefined;
+        const docUuid = uuidFor("doc", docEntryId);
+        return [
+            {
+                key,
+                fm,
+                name,
+                url,
+                uuid: uuidFor(fm.type, fm.id, fm),
+                doc: docKey,
+            },
+            {
+                key: docKey,
+                fm,
+                name,
+                // On the web the item note renders as one page which *is* its
+                // documentation, so both addresses resolve to the same URL.
+                url,
+                uuid: docUuid,
+                anchors:
+                    docUuid ?
+                        anchorsOf(docUuid, docEntryId, body ?? "", name)
+                    :   undefined,
+            },
+        ];
+    }
+
+    // Everything else is one document. A `doc` note compiles into a journal in
+    // its own right, so its anchors sit on its own entry.
+    const own = uuidFor(fm.type, fm.id, fm);
+    return [
+        {
+            key,
+            fm,
+            name,
+            url,
+            uuid: own,
+            anchors:
+                own && fm.type === "doc" ?
+                    anchorsOf(own, fm.id, body ?? "", name)
+                :   undefined,
+        },
+    ];
+}
+
+/**
+ * Every note this package publishes, as manifest entries.
+ *
+ * Drafts are excluded because the site does not publish them, and an entry for
+ * an unpublished page is exactly the dead link the manifest exists to prevent.
+ * A note belonging to another content package is skipped for the same reason in
+ * reverse: this build is not authoritative for it, and its own build says where
+ * it lives.
+ *
+ * A note that has no address is **reported, not guessed** — the finding carries
+ * the file and the reason, so a caller can print it or fail on it. Inventing an
+ * address would put an entry in the manifest asserting a page that does not
+ * exist.
+ *
+ * @param {string} contentBase - Absolute path to the content tree.
+ * @param {object} ctx - `{ contentPackage, foundryPackageId, packRouter,
+ *   scheme }`.
+ * @returns {{entries: Array<object>, notes: number,
+ *   skipped: Array<{file: string, reason: string}>}}
+ */
+export function collectManifestEntries(contentBase, ctx) {
+    const entries = [];
+    const skipped = [];
+    // Counted separately because they are genuinely different numbers: an item
+    // note yields two entries, so reporting one as the other overstates how
+    // much of the tree is published.
+    let notes = 0;
+    for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
+        contentBase,
+        { skipDirectories: ctx.skipDirectories },
+    )) {
+        if (!fm || fm.package !== ctx.contentPackage) continue;
+        if (fm.draft === true) continue;
+        if (!fm.type || !fm.shortcode) continue;
+
+        const rel = path.relative(contentBase, absPath);
+        const base = path.basename(absPath);
+        const name = fm.name?.full ?? path.basename(absPath, ".md");
+
+        let address;
+        try {
+            address = packageAddress(fm, name, {
+                isReadme: base.toLowerCase() === "readme.md",
+                scheme: ctx.scheme,
+            });
+        } catch (err) {
+            skipped.push({ file: rel, reason: err.message });
+            continue;
+        }
+        notes += 1;
+        entries.push(...entriesForNote(fm, name, address, body ?? "", ctx));
+    }
+    return { entries, notes, skipped };
+}
+
+/**
+ * The identities and scheme an emission runs against, from configuration.
+ *
+ * Resolved in one place and passed down, rather than read at each use, so the
+ * pass itself is a pure function of its context and a test can drive it without
+ * standing up a configuration.
+ *
+ * @param {object} [config] - A resolved configuration; loaded when omitted.
+ * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,
+ *   scheme: {prefix: string, landing: string}, web: boolean,
+ *   skipDirectories: readonly string[]}}
+ */
+export function manifestContext(config = loadPackConfig()) {
+    return {
+        contentPackage: config.contentPackage,
+        foundryPackageId: config.foundryPackage,
+        packRouter: routerFor(config),
+        scheme: config.publish.address,
+        web: config.publish.site,
+        // The walk's own configuration, threaded through rather than left to
+        // its default, so a caller that passes a config drives every read.
+        skipDirectories: config.skipDirectories,
+    };
+}
+
+/**
+ * Emits this package's link manifest.
+ *
+ * One package, because a configuration declares exactly one `contentPackage`
+ * and nothing in the surface can express a second. {@link writeManifests} keeps
+ * its package→entries map — it is the general writer — but there is no setting
+ * here to choose with.
+ *
+ * @param {object} [options] - Options.
+ * @param {string} [options.contentBase] - The content tree; defaults to the
+ *   configured `paths.content`.
+ * @param {string} [options.outDir] - Where to write; defaults to the configured
+ *   `paths.manifestOut`.
+ * @param {object} [options.config] - A resolved configuration; loaded when
+ *   omitted.
+ * @returns {{written: Array<{package: string, file: string, count: number}>,
+ *   entries: number, notes: number,
+ *   skipped: Array<{file: string, reason: string}>}}
+ * @throws {Error} When the repository does not declare that it publishes a
+ *   manifest, when the tree is absent, or when it yields no published note — a
+ *   manifest claiming this package publishes nothing is worse than none, since
+ *   a consumer reads it as authoritative and turns every link into this package
+ *   into a reported typo.
+ */
+export function emitLinkManifest({ contentBase, outDir, config } = {}) {
+    const resolved = config ?? loadPackConfig();
+    const tree = contentBase ?? resolved.paths.content;
+    const dir = outDir ?? resolved.paths.manifestOut;
+    const ctx = manifestContext(resolved);
+
+    // A repository that has not declared it publishes a manifest must not
+    // produce one: the file is vendored by consumers and read as authoritative,
+    // so emitting it is a statement about this package rather than a local
+    // convenience. Checked here rather than in the command, so a library caller
+    // cannot route around the declaration.
+    if (!resolved.publish.manifests.publish) {
+        throw new Error(
+            `this repository does not publish a link manifest — set ` +
+                `\`publish.manifests.publish: true\` in its content-build ` +
+                `configuration to change that`,
+        );
+    }
+
+    if (!fs.existsSync(tree)) {
+        throw new Error(`no content tree at ${tree}`);
+    }
+
+    const { entries, notes, skipped } = collectManifestEntries(tree, ctx);
+    if (entries.length === 0) {
+        throw new Error(
+            `${tree} yielded no published notes, so the manifest would ` +
+                `claim this package publishes nothing`,
+        );
+    }
+
+    const written = writeManifests(
+        new Map([[ctx.contentPackage, entries]]),
+        dir,
+        // The one surviving role of a base: `undefined` is the statement "this
+        // build publishes no pages", and no entry then carries a `path`
+        // (#1516). The value itself cancels — every address above is already
+        // package-relative — so it is a sentinel, not a location.
+        ctx.web ? { [ctx.contentPackage]: "/" } : undefined,
+        { [ctx.contentPackage]: ctx.foundryPackageId },
+    );
+
+    return { written, entries: entries.length, notes, skipped };
+}