@heroiclands/package-build 0.6.0 → 3.0.0

package/types/engine/journals.d.mts

@@ -0,0 +1,121 @@
+/**
+ * Splits a markdown body into pages by top-level H1 headings. Fenced
+ * code blocks are respected so `# foo` inside ``` blocks doesn't trigger
+ * a split. Content before the first H1 (if non-empty) becomes a leading
+ * page. Each H1 yields a page whose name is the heading
+ * text (with any `{#anchor-id}` suffix stripped out and surfaced as
+ * `anchorId`).
+ *
+ * `leadName` names that leading page. A journal note's is "Introduction",
+ * because it introduces the pages that follow. An item doc's is the item — a
+ * note with no headings at all is one page holding the whole description, and
+ * calling that page "Introduction" would label the description as a preamble to
+ * nothing.
+ *
+ * Returns an array of `{ name, anchorId, markdown }` in document order.
+ */
+export function splitPages(body: any, leadName?: string): {
+    name: string;
+    anchorSlug: null;
+    level: number;
+    markdown: string;
+}[];
+/**
+ * Two headings in one note sharing an `{#anchor}` derive the same page id, which
+ * the LevelDB packer reports only as an opaque duplicate-key collision. Catch it
+ * here, where the note and the slug can be named.
+ *
+ * @param {Array<{anchorSlug: string|null}>} rawPages - From {@link splitPages}.
+ * @param {string} noteName - The note, for the error message.
+ * @throws {Error} When an anchor is declared twice in the same note.
+ */
+export function assertUniqueAnchors(rawPages: Array<{
+    anchorSlug: string | null;
+}>, noteName: string): void;
+/**
+ * The id of one page within its entry.
+ *
+ * An anchored page takes the id its inbound links compute from the note id and
+ * the slug, so link and page agree without shared state. Every other page is
+ * keyed by its position and name, which is what lets the items pass address an
+ * item doc's first page without having compiled it (see
+ * {@link sohl.utils.packs.itemDocPointer}).
+ *
+ * @param {string} entryId - The owning JournalEntry's `_id`.
+ * @param {{anchorSlug: string|null, name: string}} page - From {@link splitPages}.
+ * @param {number} index - The page's position in the entry.
+ * @returns {string} A 16-character Foundry id.
+ */
+export function journalPageId(entryId: string, page: {
+    anchorSlug: string | null;
+    name: string;
+}, index: number): string;
+/**
+ * Compile split pages into JournalEntryPage documents.
+ *
+ * @param {Array<object>} rawPages - From {@link splitPages}.
+ * @param {string} entryId - The owning JournalEntry's `_id`.
+ * @param {string} noteName - The note, for error messages.
+ * @returns {Array<{_id: string, name: string, type: string,
+ *   title: {show: boolean, level: number},
+ *   text: {format: number, content: string}, _key: string}>} The page
+ *   documents, in order.
+ * @throws {Error} When the note has no content at all, or repeats an anchor.
+ */
+export function buildPages(rawPages: Array<object>, entryId: string, noteName: string): Array<{
+    _id: string;
+    name: string;
+    type: string;
+    title: {
+        show: boolean;
+        level: number;
+    };
+    text: {
+        format: number;
+        content: string;
+    };
+    _key: string;
+}>;
+/**
+ * Assemble one JournalEntry document from a note's converted markdown.
+ *
+ * Shared with the scenes pass, which needs the *same* entry a map note's prose
+ * compiles into so it can bundle it into an Adventure alongside the Scene. Two
+ * passes deriving the same document from the same body is what keeps a map
+ * pin's `pageId` pointing at a page that actually exists.
+ *
+ * @param {object} params
+ * @param {string} params.id - The entry's `_id`.
+ * @param {string} params.name - The entry's name.
+ * @param {string} params.markdown - The body, tables expanded and wikilinks
+ *   resolved.
+ * @param {string} [params.leadName] - Name for the page before the first
+ *   heading; see {@link splitPages}.
+ * @param {string|null} [params.folder] - The folder id, or `null`.
+ * @param {object} [params.flags] - Document flags.
+ * @returns {object} The JournalEntry document, keyed for the pack.
+ */
+export function buildJournalEntry({ id, name, markdown, leadName, folder, flags, }: {
+    id: string;
+    name: string;
+    markdown: string;
+    leadName?: string | undefined;
+    folder?: string | null | undefined;
+    flags?: object | undefined;
+}): object;
+export class Journals extends BasePackCompiler {
+    /**
+     * How many of the compiled entries were documentation for a document
+     * compiled elsewhere, for the summary.
+     *
+     * @type {number}
+     */
+    docEntries: number;
+    /** @inheritdoc */
+    onCompiled(fm: any): void;
+    /** @inheritdoc */
+    reportCompiled(stats: any): void;
+    /** @inheritdoc */
+    reportDetail(stats: any): void;
+}
+import { BasePackCompiler } from "./base-compiler.mjs";

package/types/engine/kb-manifest.d.mts

@@ -0,0 +1,214 @@
+/**
+ * The **canonical** address of a note: fully qualified, one spelling per
+ * document, and globally unique.
+ *
+ * The written form of a link may omit the package (`[[skill-lang]]`), which
+ * defaults it to the citing note's own. Everything internal — index keys,
+ * manifest keys, every lookup — uses this instead, so no consumer has to know
+ * what a short form defaulted to.
+ *
+ * Global uniqueness is what lets a foreign manifest merge straight into a local
+ * index: the keys cannot collide by accident, so a key already present on merge
+ * is a real conflict rather than an artefact of two packages sharing a
+ * namespace. `(type, shortcode)` alone is unique only *within* a package, and
+ * two independently authored packages reaching for the same short string is a
+ * matter of time (#1499).
+ *
+ * @param {string} pkg - The owning **content** package (`sohl`, `thalorna`) —
+ *   not the Foundry package, which varies per compilation target.
+ * @param {string} type - The note's `type`.
+ * @param {string} shortcode - The note's `shortcode`.
+ * @returns {string} `package/type/shortcode`, lowercased.
+ */
+export function canonicalKey(pkg: string, type: string, shortcode: string): string;
+/**
+ * Reads a canonical key back into its parts.
+ *
+ * Unambiguous because no package, type or shortcode contains a hyphen — types
+ * are bare words and shortcodes are `^[A-Za-z0-9]+$` (#1397).
+ *
+ * @param {string} key - A canonical key.
+ * @returns {{package: string, type: string, shortcode: string}|null} The parts,
+ *   or `null` when the key is not in canonical form.
+ */
+export function readCanonicalKey(key: string): {
+    package: string;
+    type: string;
+    shortcode: string;
+} | null;
+/**
+ * The package-relative address a site-absolute URL records as.
+ *
+ * Strips the emitting package's own base, so what lands in the manifest says
+ * *where in the package* a page is and nothing about where the package itself
+ * is mounted. A URL outside the base is an error rather than a best effort: it
+ * would record an address that silently resolves to the wrong place once a
+ * consumer prefixes its own base.
+ *
+ * @param {string} url - The site-absolute URL the emitting build publishes at.
+ * @param {string} base - That build's base for the package, e.g. `"/thalorna/"`.
+ * @returns {string} The address relative to `base`, with no leading slash.
+ */
+export function packageRelative(url: string, base: string): string;
+/**
+ * The URL a package-relative address resolves to in this build.
+ *
+ * Plain concatenation, which is what makes an absolute-origin base work: a base
+ * of `"https://thalorna.example.org/"` yields an absolute link, and one of
+ * `"/thalorna/"` a root-relative one, with no other rule to keep in step.
+ *
+ * @param {string} rel - The package-relative address from a manifest entry.
+ * @param {string} base - This build's base for that package.
+ * @returns {string} The resolved URL.
+ */
+export function resolvePackageUrl(rel: string, base: string): string;
+/**
+ * Builds one package's manifest from the KB build's own entries.
+ *
+ * Only notes carrying a `shortcode` appear: the shortcode is the stable
+ * identity another package addresses them by, and a note without one cannot be
+ * the target of a cross-package link at all.
+ *
+ * @param {string} pkg - The package name, e.g. `"sohl"`.
+ * @param {Array<object>} entries - KB entries (`{ fm, name, url }`).
+ * @param {string} [base] - Where *this* build serves `pkg`, stripped from each
+ *   entry's URL so the recorded address is package-relative (#1465). Omitted,
+ *   this build publishes no web surface for the package and no entry carries a
+ *   `path` — see below.
+ * @param {string} [foundryPackage] - The Foundry package this build ships the
+ *   compiled documents in. Given, each entry also carries the `uuid` /
+ *   `docUuid` a pack build resolves against; omitted, the manifest describes
+ *   the web surface only.
+ * @returns {object} The manifest document.
+ */
+export function buildManifest(pkg: string, entries: Array<object>, base?: string, foundryPackage?: string): object;
+/**
+ * Writes one manifest per package into `dir`.
+ *
+ * @param {Map<string, Array<object>>} entriesByPackage - Package → entries.
+ * @param {string} dir - Output directory; created if absent.
+ * @param {Record<string, string>} bases - Package → where *this* build serves
+ *   it, which is what each entry's address is recorded relative to. This is the
+ *   emitting build's own layout, not {@link PACKAGE_BASE}: a package's own site
+ *   commonly serves it at `"/"` while a consumer mounts it under a prefix.
+ * @param {Record<string, string>} [foundryPackages] - Package → the Foundry
+ *   package shipping its documents. Only a package this build publishes can
+ *   have one, since the UUID names where *this* repository ships them.
+ * @returns {Array<{ package: string, file: string, count: number }>} What was written.
+ */
+export function writeManifests(entriesByPackage: Map<string, Array<object>>, dir: string, bases: Record<string, string>, foundryPackages?: Record<string, string>): Array<{
+    package: string;
+    file: string;
+    count: number;
+}>;
+/**
+ * Loads vendored manifests for packages this build does not itself publish.
+ *
+ * A package built locally is skipped even if a manifest for it is present: the
+ * live build is authoritative and a vendored copy of it can only be stale.
+ *
+ * Each entry's package-relative address is resolved against this build's base
+ * for that package (#1465), so what the index holds is a usable `url` and every
+ * consumer downstream is unchanged by the format.
+ *
+ * @param {string} dir - Directory of vendored `<package>.json` manifests.
+ * @param {Iterable<string>} localPackages - Packages this build publishes.
+ * @param {Record<string, string>} [bases] - Package → base to resolve against;
+ *   defaults to {@link PACKAGE_BASE}.
+ * @returns {{ index: Map<string, object>, packages: Set<string>, stale: Array<object> }}
+ *   `index` maps the canonical `package-type-shortcode` → `{ url, name, uuid,
+ *   doc, anchors, type, package }`. Keys are globally unique, so this merges
+ *   directly into a local index with no prefixing and no separate lookup path.
+ *   `url` is `undefined` for an entry with no page (#1516) and `uuid` for one
+ *   that compiles into no document, so a caller must check the address it
+ *   intends to use rather than assume a hit carries it.
+ */
+export function loadForeignManifests(dir: string, localPackages: Iterable<string>, bases?: Record<string, string>): {
+    index: Map<string, object>;
+    packages: Set<string>;
+    stale: Array<object>;
+};
+/**
+ * Whether every linkable package is accounted for, locally or by manifest.
+ *
+ * This is what gates the dead-link guard. It is deliberately derived from data
+ * rather than set by a flag: the guard turns itself on the moment the last
+ * missing manifest appears, instead of waiting for someone to remember.
+ *
+ * @param {Iterable<string>} localPackages - Packages this build publishes.
+ * @param {Iterable<string>} manifestPackages - Packages loaded from manifests.
+ * @returns {{ complete: boolean, missing: Array<string> }}
+ */
+export function manifestsComplete(localPackages: Iterable<string>, manifestPackages: Iterable<string>): {
+    complete: boolean;
+    missing: Array<string>;
+};
+/**
+ * Packages that publish a manifest and therefore exchange addresses.
+ *
+ * The guard in {@link manifestsComplete} stays off until every one of these is
+ * accounted for, so adding a package here without also publishing its manifest
+ * relaxes the build rather than breaking it.
+ */
+export const LINK_PACKAGES: readonly string[];
+/**
+ * Manifest format version.
+ *
+ * Bumped to 2 by #1465: entries changed from a site-absolute `url` to a
+ * package-relative `path`. The two shapes are indistinguishable to a naive
+ * reader — prefixing a v1 `url` yields `/thalorna/thalorna/…`, which resolves,
+ * renders, and 404s — so the version is what makes a stale vendored file an
+ * error rather than a wrong link.
+ *
+ * Bumped to 4 by #1499: keys use the authored hyphen separator
+ * (`sohl-affliction-aconite`) so a key *is* the address an author writes; an
+ * item's documentation became an entry in its own right
+ * (`sohl-docaffliction-aconite`) rather than a second field; and entries gained
+ * `anchors`, mapping a note's named sections to the full UUID each compiled to.
+ *
+ * Bumped to 3 by #1499: keys became **canonical** — fully qualified
+ * `package/type/shortcode` rather than `type/shortcode` — and entries gained the
+ * Foundry `uuid` / `docUuid` beside the web `path`. A v2 key read as a v3 one
+ * addresses a package named after a type, so again the version is what turns a
+ * stale vendored file into an error.
+ *
+ * Bumped to 5 by #1516: `path` became optional, so a package that ships
+ * compendiums and publishes no site can still publish the Foundry addresses of
+ * its documents — the mirror of an entry that has a `path` and no `uuid`.
+ */
+export const MANIFEST_VERSION: 5;
+/**
+ * Every version this build can read, newest last.
+ *
+ * A version exists to stop a file whose values *read differently* from being
+ * resolved anyway, and that is the only thing it is allowed to gate. Every bump
+ * so far did change a reading — a v2 key read as a v4 one addresses a package
+ * named after a type — so each dropped its predecessors. **v5 did not**: it
+ * only permits an absent `path`, so every v4 value still means exactly what it
+ * meant, and refusing v4 would make a purely relaxing change a flag day in
+ * which every package must re-emit on the same afternoon or every build breaks
+ * (#1516).
+ *
+ * The unsafe direction is unchanged and still hard-fails: an older consumer
+ * meeting a newer file rejects it, because it cannot know what the new shape
+ * permits. Widening is therefore always safe to do here first and adopt
+ * elsewhere later.
+ */
+export const READABLE_VERSIONS: readonly number[];
+/**
+ * Where this build serves each package, keyed by package name.
+ *
+ * One line per package, and the only edit a relocation requires: point a
+ * package at another path (`"/setting/thalorna/"`) or another origin
+ * (`"https://thalorna.example.org/"`) and every inbound link into it follows.
+ * A base is a prefix, so it must end in `/`.
+ *
+ * Only *foreign* packages are consulted — a package this build publishes is
+ * authoritative in its own entries and never resolves through a manifest — but
+ * every linkable package is listed, because which are foreign depends on the
+ * consuming repository and this file is vendored into each of them.
+ */
+export const PACKAGE_BASE: Readonly<{
+    sohl: "/sohl/";
+    thalorna: "/thalorna/";
+}>;

package/types/engine/macros.d.mts

@@ -0,0 +1,201 @@
+/**
+ * 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: string): string | 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: string, name: string): string;
+/**
+ * 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: object, label: string): "script";
+/**
+ * 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: object, label: string): string;
+/**
+ * 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: object, { command, folder, stats }: {
+    command: string;
+    folder?: string | null | undefined;
+    stats?: object | undefined;
+}): MacroDocument;
+/**
+ * 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: readonly string[];
+/** The Foundry macro scopes (`CONST.MACRO_SCOPES`), in schema order. */
+export const MACRO_SCOPES: readonly string[];
+/**
+ * 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";
+/**
+ * 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 {
+    /**
+     * 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: object, body: string): MacroDocument;
+    /** @inheritdoc */
+    reportDetail(stats: any): void;
+}
+/**
+ * A compiled Macro document, in the shape the LevelDB packer consumes.
+ */
+export type MacroDocument = {
+    /**
+     * - The macro's display name.
+     */
+    name: string;
+    /**
+     * - The Foundry macro type; always `script`.
+     */
+    type: string;
+    /**
+     * - No authoring user; Foundry's field is nullable.
+     */
+    author: null;
+    /**
+     * - The Foundry-relative artwork path.
+     */
+    img: string;
+    /**
+     * - One of {@link MACRO_SCOPES}.
+     */
+    scope: string;
+    /**
+     * - The script the macro runs.
+     */
+    command: string;
+    /**
+     * - The folder id, or `null` for the root.
+     */
+    folder: string | null;
+    /**
+     * - Sort order within its folder.
+     */
+    sort: number;
+    /**
+     * - Default ownership level.
+     */
+    ownership: {
+        default: number;
+    };
+    /**
+     * - Document flags from frontmatter.
+     */
+    flags: object;
+    /**
+     * - The Foundry document id.
+     */
+    _id: string;
+    /**
+     * - The `_stats` block.
+     */
+    _stats: object;
+    /**
+     * - The LevelDB key, `!macros!<id>`.
+     */
+    _key: string;
+};
+import { BasePackCompiler } from "./base-compiler.mjs";

package/types/engine/manifest-emit.d.mts

@@ -0,0 +1,137 @@
+/**
+ * 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: string, entryId: string, body: string, name: string): Record<string, string>;
+/**
+ * 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: object, name: string, address: string, body: string, ctx: object): Array<object>;
+/**
+ * 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: string, ctx: object): {
+    entries: Array<object>;
+    notes: number;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
+/**
+ * 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?: object): {
+    contentPackage: string;
+    foundryPackageId: string;
+    packRouter: object;
+    scheme: {
+        prefix: string;
+        landing: string;
+    };
+    web: boolean;
+    skipDirectories: readonly string[];
+};
+/**
+ * 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 }?: {
+    contentBase?: string | undefined;
+    outDir?: string | undefined;
+    config?: object | undefined;
+}): {
+    written: Array<{
+        package: string;
+        file: string;
+        count: number;
+    }>;
+    entries: number;
+    notes: number;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
+/**
+ * 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";