@heroiclands/package-build 0.6.0 → 3.0.0

package/types/engine/base-compiler.d.mts

@@ -0,0 +1,320 @@
+/**
+ * The tallies one pass accumulates while walking the tree.
+ *
+ * @typedef {object} PassStats
+ * @property {number} compiled - Notes that became a document.
+ * @property {number} skippedDraft - Notes marked `draft: true`.
+ * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
+ * @property {number} skippedOther - Notes this pass does not claim.
+ */
+/**
+ * The shared walk → filter → expand → convert → build → write → count loop.
+ *
+ * Subclass it, implement {@link BasePackCompiler#selects} and
+ * {@link BasePackCompiler#buildEntry}, and override the hooks the pass needs.
+ */
+export class BasePackCompiler {
+    /**
+     * The pack this pass writes. Subclasses state their own.
+     *
+     * @type {string}
+     */
+    static id: string;
+    /**
+     * The singular noun this pass calls one of its notes, in log messages —
+     * "item", "journal", "actor", "macro", "map". Capitalized for the
+     * missing-id error.
+     *
+     * @type {string}
+     */
+    static label: string;
+    /**
+     * Whether a claimed note with no `id` fails the build.
+     *
+     * True everywhere but the journals pass: a skipped document silently
+     * vanishes from the compendium while its knowledgebase page still builds,
+     * so the omission is invisible until someone looks for it.
+     *
+     * @type {boolean}
+     */
+    static requiresId: boolean;
+    /**
+     * Whether the body handed to {@link BasePackCompiler#buildEntry} has had
+     * its generated tables expanded and its wikilinks converted.
+     *
+     * False for a pass whose output must be exactly what the author typed —
+     * the macros pass, whose `command` is executable source (#1514). A pass
+     * that says so also skips building the content-wide link index it would
+     * never read.
+     *
+     * @type {boolean}
+     */
+    static convertsWikilinks: boolean;
+    /**
+     * @param {object} options
+     * @param {string} options.contentBase - Root of the content tree.
+     * @param {string} options.dest - Where this pass writes its JSON.
+     * @param {(path: string|null) => string|null} [options.folderResolver] -
+     *   Resolves a `sohl.folder` id against this pack's folder hierarchy.
+     * @param {string} [options.packName] - The pack this pass writes.
+     * @param {string} [options.docType] - The Foundry document type it holds.
+     * @param {{resolve: Function}} [options.router] - The pack router. Omit it
+     *   — as the unit suite does — and every claimed note is compiled here.
+     * @param {boolean} [options.routingReporter] - Whether this pass reports a
+     *   note of its type that routes nowhere.
+     */
+    constructor({ contentBase, dest, folderResolver, packName, docType, router, routingReporter, }?: {
+        contentBase: string;
+        dest: string;
+        folderResolver?: ((path: string | null) => string | null) | undefined;
+        packName?: string | undefined;
+        docType?: string | undefined;
+        router?: {
+            resolve: Function;
+        } | undefined;
+        routingReporter?: boolean | undefined;
+    });
+    /** @type {string} */
+    contentBase: string;
+    /** @type {string} */
+    outputDir: string;
+    /** @type {(path: string|null) => string|null} */
+    folderResolver: (path: string | null) => string | null;
+    /** @type {number} */
+    errorCount: number;
+    /**
+     * The pack this pass writes, and the Foundry document type it holds.
+     *
+     * Supplied by the generator from the configured pack list. Left undefined
+     * by a caller constructing a compiler directly (the unit suite), which
+     * turns routing off: with one pack there is nothing to route between.
+     *
+     * @type {string|undefined}
+     */
+    packName: string | undefined;
+    /** @type {string|undefined} */
+    docType: string | undefined;
+    /** @type {{resolve: Function}|undefined} */
+    router: {
+        resolve: Function;
+    } | undefined;
+    /**
+     * Whether this pass reports a note of its document type that routes
+     * nowhere.
+     *
+     * Every pack of a type claims the same notes, so all of them would report
+     * the same unroutable note. The **first configured pack of the type** owns
+     * the message, and the rest stay quiet — one error, named once, and the
+     * build still fails.
+     *
+     * @type {boolean}
+     */
+    routingReporter: boolean;
+    /**
+     * Entries this pass wrote to its own pack. Zero from a non-empty content
+     * tree is a build failure, not a quiet no-op — see `generate.mjs`.
+     *
+     * @type {number}
+     */
+    compiledCount: number;
+    /**
+     * Wikilinks left as literal text because nothing in the tree (or in a
+     * vendored manifest) publishes their target.
+     *
+     * @type {number}
+     */
+    unresolvedLinks: number;
+    /**
+     * Whether this pass's pack is the one a claimed note belongs in.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True to compile it here.
+     * @throws {import("./pack-router.mjs").PackRoutingError} When the note
+     *   routes to no pack at all — a build failure, never a silent drop.
+     */
+    routesHere(fm: object): boolean;
+    /**
+     * Whether this pass claims a note. **Required.**
+     *
+     * Called only for a note of the configured content package, so a subclass
+     * decides on `type` alone.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True to compile it.
+     */
+    selects(fm: object): boolean;
+    /**
+     * A further rejection the type filter cannot express, applied after the
+     * id check. The journals pass uses it to skip a doc-carrying note with no
+     * prose: there is no documentation to compile, and the document's own pass
+     * leaves its pointer empty to match.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} body - The note body, as authored.
+     * @returns {boolean} True to skip the note.
+     */
+    skipNote(fm: object, body: string): boolean;
+    /**
+     * What one note is called in this pass's log lines. The items pass names
+     * the item's type, which is more use than "item".
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {string} The label.
+     */
+    noteLabel(fm: object): string;
+    /**
+     * Everything the walk needs before it starts: the content-wide link index
+     * and table-search corpus here, plus whatever a subclass adds (a prior
+     * pack's output, an index of cross-references).
+     *
+     * @returns {Promise<void>}
+     */
+    prepare(): Promise<void>;
+    linkIndex: {
+        byShortcode: Map<any, any>;
+        byAlias: Map<any, any>;
+    } | undefined;
+    contentDocs: {
+        fm: object;
+        path: string;
+        tld: string;
+        folder: string;
+        absPath: string;
+    }[] | undefined;
+    /**
+     * The body {@link BasePackCompiler#buildEntry} receives.
+     *
+     * Generated tables expand before wikilinks are converted, so a cell a
+     * table emits is resolved along with the authored links.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} body - The note body, as authored.
+     * @returns {string} The converted markdown, or `body` itself for a pass
+     *   that does not convert.
+     */
+    convertBody(fm: object, body: string): string;
+    /**
+     * Reports a warning about the note being compiled.
+     *
+     * The file comes from the walk, so no caller has to carry it; a `position`
+     * is used when the caller could establish one and omitted otherwise —
+     * naming the file alone beats naming a line that is not the problem.
+     *
+     * @param {string} message - What is wrong, in one sentence.
+     * @param {{line?: number, column?: number}} [position] - Where, if known.
+     * @returns {void}
+     */
+    noteWarn(message: string, position?: {
+        line?: number;
+        column?: number;
+    }): void;
+    /**
+     * Reports an error about the note being compiled.
+     *
+     * @param {string} message - What is wrong, in one sentence.
+     * @param {{line?: number, column?: number}} [position] - Where, if known.
+     * @returns {void}
+     */
+    noteError(message: string, position?: {
+        line?: number;
+        column?: number;
+    }): void;
+    /**
+     * One note → one document. **Required.**
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} markdown - The body, from
+     *   {@link BasePackCompiler#convertBody}.
+     * @returns {object} The document, keyed for the pack.
+     */
+    buildEntry(fm: object, markdown: string): object;
+    /**
+     * Write one document into a directory, named for its name and id.
+     *
+     * @param {string} dir - The destination directory.
+     * @param {object} doc - The document.
+     */
+    writeTo(dir: string, doc: object): void;
+    /**
+     * Write one document into this pass's own pack.
+     *
+     * @param {object} doc - The document.
+     */
+    writeEntry(doc: object): void;
+    /**
+     * Compile one claimed note. The default builds its document and writes it;
+     * a pass whose note emits more than that (the scenes pass, which also
+     * bundles an Adventure) overrides this.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} markdown - The body, from
+     *   {@link BasePackCompiler#convertBody}.
+     * @returns {object} The document written to this pass's own pack.
+     */
+    compileNote(fm: object, markdown: string): object;
+    /**
+     * A note compiled successfully — where a pass keeps its own tallies.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {object} doc - The document just written.
+     */
+    onCompiled(fm: object, doc: object): void;
+    /**
+     * Work that needs every note compiled first, before the summary is logged.
+     *
+     * @param {PassStats} stats - The pass's tallies.
+     * @returns {Promise<void>}
+     */
+    finish(stats: PassStats): Promise<void>;
+    /**
+     * The pass's headline count.
+     *
+     * @param {PassStats} stats - The pass's tallies.
+     */
+    reportCompiled(stats: PassStats): void;
+    /**
+     * The pass's own trailing detail line, which names what it rejected in the
+     * terms that pass uses.
+     *
+     * @param {PassStats} stats - The pass's tallies.
+     */
+    reportDetail(stats: PassStats): void;
+    /**
+     * Log what the pass did.
+     *
+     * @param {PassStats} stats - The pass's tallies.
+     */
+    report(stats: PassStats): void;
+    /**
+     * Walk the content tree and compile every note this pass claims.
+     *
+     * @returns {Promise<void>}
+     */
+    compile(): Promise<void>;
+    currentNote: {
+        absPath: string;
+        bodyLine: number | undefined;
+        bodyColumn: number | undefined;
+    } | undefined;
+}
+/**
+ * The tallies one pass accumulates while walking the tree.
+ */
+export type PassStats = {
+    /**
+     * - Notes that became a document.
+     */
+    compiled: number;
+    /**
+     * - Notes marked `draft: true`.
+     */
+    skippedDraft: number;
+    /**
+     * - Notes with no `id`, where that is tolerated.
+     */
+    skippedNoId: number;
+    /**
+     * - Notes this pass does not claim.
+     */
+    skippedOther: number;
+};

package/types/engine/code-fences.d.mts

@@ -0,0 +1,102 @@
+/**
+ * Every code region in a markdown body, as character offsets into it.
+ *
+ * @param {string | null | undefined} markdown - The body (frontmatter already
+ *   stripped). An absent body has no code in it.
+ * @param {object} [options]
+ * @param {boolean} [options.spans=true] - Include inline code spans. Set false
+ *   to consider only block-level code.
+ * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
+ *   source order. `end` is exclusive.
+ */
+export function codeRegions(markdown: string | null | undefined, { spans }?: {
+    spans?: boolean | undefined;
+}): Array<{
+    start: number;
+    end: number;
+}>;
+/**
+ * `String.prototype.replace`, skipping anything inside code.
+ *
+ * A match inside a code region is returned as it was written, so the block
+ * stays verbatim; the replacer is not called for it at all, which matters when
+ * it records a side effect (an unresolved link, say).
+ *
+ * @param {string} markdown - The body.
+ * @param {RegExp} pattern - A **global** pattern to rewrite.
+ * @param {(...args: Array<any>) => string} replacer - As `replace` takes.
+ * @param {object} [options] - Passed to {@link codeRegions}.
+ * @returns {string} The rewritten body.
+ */
+export function replaceOutsideCode(markdown: string, pattern: RegExp, replacer: (...args: Array<any>) => string, options?: object): string;
+/**
+ * `String.prototype.matchAll`, skipping anything inside code.
+ *
+ * @param {string} markdown - The body.
+ * @param {RegExp} pattern - A **global** pattern to search for.
+ * @param {object} [options] - Passed to {@link codeRegions}.
+ * @returns {Array<RegExpMatchArray>} The matches outside code, in source order.
+ */
+export function matchAllOutsideCode(markdown: string, pattern: RegExp, options?: object): Array<RegExpMatchArray>;
+/**
+ * Run `transform` over a whole Markdown body while leaving code untouched.
+ *
+ * {@link replaceOutsideCode} is the right tool when the caller has a pattern.
+ * This is for the other shape: a transform that rewrites the **whole** body — a
+ * link rewriter, a path fixer — and must simply never see code. Each code run is
+ * stashed and replaced with a `\u0000<index>\u0000` sentinel; a NUL never occurs
+ * in Markdown source, so the sentinel cannot collide with prose and survives the
+ * transform unchanged before being restored.
+ *
+ * **Which runs count as code is {@link codeRegions}' rule, not a second copy of
+ * it.** The knowledgebase build carried its own regex once, and it was weaker in
+ * two ways that both corrupted the one page whose subject *is* link syntax — so
+ * its examples were exactly the input a looser rule mangles (SoHL#1665). A
+ * single-backtick span was allowed to cross newlines, so one odd backtick paired
+ * with another paragraphs away and every span after it paired wrongly: prose was
+ * masked as code while real spans were left exposed. And only three-backtick
+ * fences were recognised, so a four-backtick example holding a three-backtick
+ * block — the documented "fences of any length" case (#1505) — leaked its
+ * contents.
+ *
+ * @param {string} body - The markdown body.
+ * @param {(masked: string) => string} transform - Applied to the masked body.
+ * @returns {string} The transformed body, with every code run restored verbatim.
+ */
+export function protectCode(body: string, transform: (masked: string) => string): string;
+/**
+ * Where **code** lives in a markdown body, so a rewriter can leave it alone.
+ *
+ * A code block is verbatim: its contents are shown to the reader exactly as
+ * written. Every build-time rewriter that pattern-matches a body therefore has
+ * to know where code is — otherwise a source listing that happens to contain
+ * the rewriter's syntax is silently corrupted. Wikilink conversion met this as
+ * `[[0]]` inside a fence being turned into a link (#1505), and it depended on
+ * the surrounding literal's shape (`[[1,2],[3,4]]` survived), so the corruption
+ * looked arbitrary.
+ *
+ * Three forms are recognised, which is every form the content tree uses:
+ *
+ * - **Fenced blocks** — three or more backticks or tildes, closed by the same
+ *   character at least as long, or by the end of the document. A longer fence
+ *   contains a shorter one, so a markdown sample can quote a code sample. The
+ *   opening line, info string and all, is part of the block.
+ * - **Indented blocks** — four columns past the enclosing context, following a
+ *   blank line (an indent cannot interrupt a paragraph).
+ * - **Inline spans** — a run of backticks closed by a run of equal length,
+ *   within one paragraph.
+ *
+ * The fence syntax is the one `expandContentTables` already reads, and
+ * this module owns it now so the two can never disagree.
+ *
+ * **Known limits.** This is a scanner, not a markdown parser, and it errs
+ * towards treating something as code — a false positive leaves an author's text
+ * as written, a false negative rewrites it. List nesting is tracked only to the
+ * innermost open marker, so an indented block inside a deeply nested list may be
+ * read as list prose; a backslash-escaped backtick still counts as a span
+ * delimiter; and HTML blocks are not code (they are not verbatim in markdown
+ * either). None of these can turn code into a link — the failure this exists to
+ * prevent.
+ */
+/** A fence line, capturing its indent, its marker, and its info string. */
+export const FENCE_LINE: RegExp;

package/types/engine/compendiums.d.mts

@@ -0,0 +1,77 @@
+/**
+ * Generates each pack's per-entry JSON from `assets/content/` into
+ * `build/packs-json/<name>/`, then builds the LevelDB output from it. No
+ * committed JSON and no vault access. Destination: `<stageDest>/<name>/`.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]         The resolved build configuration, which
+ *     the two path arguments below default from. Supplying one is how a caller
+ *     compiles a package other than this repository's (#1508).
+ * @param {string[]} [opts.sourcePacks]  Every pack compiled from the content
+ *     tree, in compile order. Defaults to the configured pack directories.
+ * @param {string} [opts.stageDest]      Directory the LevelDB packs are built
+ *     into, one subdirectory per pack. Defaults to the configured stage.
+ * @param {string} [opts.packName]       Restrict the run to a single pack.
+ * @throws {Error} If pack JSON generation reported any error. Packs compiled
+ *     from incomplete or empty JSON ship blank or short compendiums, and the
+ *     omission is invisible until a player looks for content that is not there
+ *     (#1502) — so this is fatal, not a warning, and the caller is expected to
+ *     turn it into a failing exit code.
+ * @throws {Error} If a compiled pack ships a Scene that has lost its embedded
+ *     Level (#1538). Fatal for the same reason: Foundry reads a missing Level
+ *     record as "no levels" and persists that on the next world launch, so the
+ *     map image is gone before anyone notices it was ever at risk. See
+ *     {@link verifyPackSceneLevels}.
+ */
+export function compilePacks({ config, sourcePacks, stageDest, packName, }?: {
+    config?: object | undefined;
+    sourcePacks?: string[] | undefined;
+    stageDest?: string | undefined;
+    packName?: string | undefined;
+}): Promise<void>;
+/**
+ * Cleans and formats source JSON files, removing unnecessary permissions and flags and adding the proper spacing.
+ * @param {object} opts
+ * @param {object} [opts.config]       The resolved build configuration, which
+ *                                     `packDest` defaults from.
+ * @param {string} [opts.packDest]     Directory holding the extracted per-entry
+ *                                     JSON, one subdirectory per pack.
+ * @param {string} [opts.packName]     Name of pack to clean. If none provided, all packs will be cleaned.
+ * @param {string} [opts.entryName]    Name of a specific entry to clean.
+ *
+ * - `npm run build:clean` - Clean all source JSON files.
+ * - `npm run build:clean -- classes` - Only clean the source files for the specified compendium.
+ * - `npm run build:clean -- classes Barbarian` - Only clean a single item from the specified compendium.
+ */
+export function cleanPacks({ config, packDest, packName, entryName, }?: {
+    config?: object | undefined;
+    packDest?: string | undefined;
+    packName?: string | undefined;
+    entryName?: string | undefined;
+}): Promise<void>;
+/**
+ * Extracts compiled LevelDB packs back to per-entry JSON, rebuilding the folder
+ * hierarchy as directories.
+ *
+ * @param {object} opts
+ * @param {Array<{name: string}>} opts.packs  The packs the shipped Foundry
+ *     package declares — the manifest's `packs` array.
+ * @param {object} [opts.config]       The resolved build configuration, which
+ *                                     the two directories below default from.
+ * @param {string} [opts.stageDest]    Directory holding the compiled LevelDB
+ *                                     packs, one subdirectory per pack.
+ * @param {string} [opts.packDest]     Directory the extracted JSON is written
+ *                                     to, one subdirectory per pack.
+ * @param {string} [opts.packName]     Restrict the run to a single pack.
+ * @param {string} [opts.entryName]    Restrict the run to a single entry.
+ */
+export function unpackPacks({ packs, config, stageDest, packDest, packName, entryName, }: {
+    packs: Array<{
+        name: string;
+    }>;
+    config?: object | undefined;
+    stageDest?: string | undefined;
+    packDest?: string | undefined;
+    packName?: string | undefined;
+    entryName?: string | undefined;
+}): Promise<void>;

package/types/engine/content-address.d.mts

@@ -0,0 +1,61 @@
+/**
+ * The URL section a note routes to.
+ *
+ * A `doc` is narrative content whose only identity is its subtype label, so it
+ * routes by `category`; every other type names its own section.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string|undefined} The section, or `undefined` when the note has
+ *   none — a `doc` with no category has no address and is not published.
+ */
+export function sectionOf(fm: object): string | undefined;
+/**
+ * A note's address below the knowledgebase mount, e.g. `affliction/aconite/`.
+ *
+ * A `README.md` **is** its section's landing page rather than a page within it,
+ * so it addresses the section itself and has no slug of its own.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @param {string} name - The note's display name; the slug derives from it
+ *   (#1278), never from the shortcode, which is identity rather than
+ *   presentation.
+ * @param {boolean} isReadme - Whether the file is a `README.md`.
+ * @returns {string} The section-relative address, with a trailing slash.
+ * @throws {Error} When the name yields no usable slug.
+ */
+export function contentAddress(fm: object, name: string, isReadme: boolean): string;
+/**
+ * A note's address relative to its **package**, e.g. `kb/affliction/aconite/`.
+ *
+ * This is the form the link manifest records and the site build emits pages at,
+ * and it is one function because those two must agree — a manifest asserting an
+ * address the site does not publish resolves at build time and 404s for the
+ * reader, which is the failure this module exists to prevent.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @param {string} name - The note's display name; a page slug derives from it
+ *   (#1278), never from the shortcode, which is identity rather than
+ *   presentation.
+ * @param {object} [options] - Options.
+ * @param {boolean} [options.isReadme] - Whether the file is a `README.md`.
+ * @param {{prefix?: string, landing?: string}} [options.scheme] - The
+ *   repository's address scheme; defaults to {@link DEFAULT_ADDRESS_SCHEME}.
+ * @returns {string} The package-relative address, with a trailing slash and no
+ *   leading one.
+ * @throws {Error} When the note has no address — no section, a landing page
+ *   naming no section, or a name yielding no usable slug. Each is a note that
+ *   is not published, and inventing an address for one would put a dead entry
+ *   in the manifest.
+ */
+export function packageAddress(fm: object, name: string, { isReadme, scheme }?: {
+    isReadme?: boolean | undefined;
+    scheme?: {
+        prefix?: string;
+        landing?: string;
+    } | undefined;
+}): string;
+/** The knowledgebase's mount within this package's site (#1470). */
+export const KB_PREFIX: "kb/";
+import { DEFAULT_ADDRESS_SCHEME } from "../content-config.mjs";
+import { LANDING_RULES } from "../content-config.mjs";
+export { DEFAULT_ADDRESS_SCHEME, LANDING_RULES };

package/types/engine/content-links.d.mts

@@ -0,0 +1,87 @@
+/**
+ * Every `{#anchor}` a note declares on a heading.
+ *
+ * @param {string} body - The note's markdown body.
+ * @returns {Set<string>} The declared anchor slugs.
+ */
+export function anchorsOf(body: string): Set<string>;
+/**
+ * Load a content tree and build the index a link resolves against.
+ *
+ * The index mirrors what both builds construct, including the two addresses a
+ * doc-carrying note answers to: `type/shortcode` for the document, and
+ * `doc<type>/shortcode` for the JournalEntry its prose compiles into. Once a
+ * manifest publishes `doc<type>` entries that prefix is a *known type*, and the
+ * virtual reading that used to answer for it no longer fires — a real type owns
+ * its own name — so the note is indexed under both.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {string} [opts.manifestDir] - Where vendored foreign manifests live.
+ *   Omitted, no cross-package address resolves.
+ * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @returns {object} The notes, the index, and the resolvers built over it.
+ */
+export function buildLinkIndex(contentBase: string, { manifestDir, skipDirectories }?: {
+    manifestDir?: string | undefined;
+    skipDirectories?: readonly string[] | undefined;
+}): object;
+/**
+ * Every link in a tree that lands nowhere.
+ *
+ * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
+ * @returns {{deadAnchors: object[], deadAddresses: object[],
+ *   frontmatterLinks: object[], usedManifest: Set<string>}} The findings, and
+ *   which addresses a foreign manifest answered.
+ */
+export function auditLinks(index: ReturnType<typeof buildLinkIndex>): {
+    deadAnchors: object[];
+    deadAddresses: object[];
+    frontmatterLinks: object[];
+    usedManifest: Set<string>;
+};
+/**
+ * Walk a corpus from its root and report what nothing links to.
+ *
+ * A documentation set is a **book, not a pile of notes**: it has a page one,
+ * and everything in it should follow from that page by reading. A note with no
+ * inbound link still compiles into a pack and still publishes — it is simply
+ * impossible to arrive at. Nothing else in either build notices, because every
+ * other check asks whether a link *lands*, never whether a document is
+ * *reached*.
+ *
+ * **Which documents belong to the corpus is the caller's to say.** A
+ * repository's corpora are its own — one publishes rules and a user guide,
+ * another a setting gazetteer — so `scope` decides membership and this decides
+ * only reachability. Links out of the corpus are followed as real links; they
+ * are simply not pages of it.
+ *
+ * **`stopAt` marks a page walked *to* but not *through*.** An index page links
+ * to nearly everything it covers, so traversing one makes the whole check
+ * vacuous: a chapter could stop linking one of its own pages and the walk would
+ * still reach it by way of the index. Reachability has to hold along the
+ * reading path, which is why the exception exists and why it is deliberately
+ * narrow.
+ *
+ * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
+ * @param {object} opts
+ * @param {string} opts.root - The corpus's entry page, as a tree-relative path.
+ * @param {(note: object) => boolean} opts.scope - Whether a note belongs to the
+ *   corpus.
+ * @param {(note: object) => boolean} [opts.stopAt] - Whether a note is walked
+ *   to but not through.
+ * @returns {{root: object, reached: Set<object>, orphans: object[]}} The root,
+ *   everything reached from it, and the corpus members that were not.
+ * @throws {Error} When no note sits at `root` — a corpus with no page one
+ *   cannot be walked, and silently reporting every page as an orphan would
+ *   bury the actual mistake.
+ */
+export function walkReachability(index: ReturnType<typeof buildLinkIndex>, { root, scope, stopAt }: {
+    root: string;
+    scope: (note: object) => boolean;
+    stopAt?: ((note: object) => boolean) | undefined;
+}): {
+    root: object;
+    reached: Set<object>;
+    orphans: object[];
+};