@heroiclands/package-build 5.0.0 → 6.1.0

package/types/engine/diagnostics.d.mts

@@ -150,3 +150,31 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
     line?: number;
     column?: number;
 };
+/**
+ * Where a **key or value in a YAML document** sits, addressed by its path.
+ *
+ * {@link positionOfLiteral} is the plain search, and it is the wrong tool for a
+ * configuration file: a pack name like `items` or `actors` appears in the
+ * `packs:` block, in a folder's list, in a path, and often in prose, so the
+ * first occurrence is routinely not the one the finding is about — which is the
+ * one thing the located form exists to prevent.
+ *
+ * A path resolves the exact node instead. The document is re-parsed here rather
+ * than threaded from the loader because the loader returns plain data: `yaml`
+ * discards ranges once a document is materialised, and carrying a parallel
+ * position tree through configuration resolution would be a second
+ * representation of the same file to keep in step.
+ *
+ * Every failure — unparseable text, an `.mjs` configuration, a path that
+ * resolves to nothing — yields `{}`, so a caller spreads the result and the
+ * position is dropped rather than guessed.
+ *
+ * @param {string} text - The document's contents.
+ * @param {ReadonlyArray<string|number>} keyPath - Path to the node: map keys as
+ *   strings, sequence entries as numbers.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+export function positionOfYamlPath(text: string, keyPath: ReadonlyArray<string | number>): {
+    line?: number;
+    column?: number;
+};

package/types/engine/generate.d.mts

@@ -6,8 +6,9 @@
  * and an actor's embedded items may be sourced from any of them. Finding one
  * pack and stopping is how embedded-item resolution would silently miss every
  * item that landed in another. Returned in configured order, which is also the
- * order they compile in, so a pack later in the list cannot be read before it
- * is written.
+ * order they compile in — {@link orderPassesByDependency} keeps the declared
+ * order among packs of one type — and every one of them is written before the
+ * actors pass that reads them.
  *
  * @param {object} [config] - The resolved build configuration. Defaults to this
  *   repository's.
@@ -16,6 +17,53 @@
  *   caller that needs one, refuses that itself.
  */
 export function itemPackJsonDirs(config?: object): string[];
+/**
+ * The passes to run, ordered so that each one follows the output it reads.
+ *
+ * **Declaration order is presentation, not compile order (#73).** The same
+ * `packs:` list is the manifest's `packs` array, which a consumer orders for a
+ * reader browsing compendiums; the actors pass, meanwhile, resolves each
+ * being's embedded items against the item passes' *output*. Making one list
+ * satisfy both meant an Actor pack declared first compiled only where a
+ * previous run had already left `build/packs-json` populated — green on a warm
+ * tree, exit 1 on every fresh checkout and every CI runner, and `build/` is
+ * gitignored so that is the state CI always starts from.
+ *
+ * **The reordering is the smallest one that works.** Each step takes the
+ * *earliest declared* pass whose dependencies are all already emitted, so a
+ * list that was already in a workable order comes back untouched, and one that
+ * was not moves exactly the passes that had to move. A dependency is satisfied
+ * only when **every** pack of that type has run: a being addresses an item by
+ * `(type, shortcode)` without knowing which Item pack ships it, so waiting for
+ * one of several would resolve some beings and silently fail others.
+ *
+ * A dependency on a type this configuration declares no pack of is not waited
+ * for. A package may ship an Actor pack and no Item pack; the pass that needs
+ * one refuses on its own, with a message about items rather than about order.
+ *
+ * @param {readonly object[]} packs - The passes to be run, as declared.
+ * @returns {object[]} A new list, in compile order. The input is untouched.
+ * @throws {Error} If the passes read each other's output in a cycle, which no
+ *   order can satisfy. Only reachable from a mis-declared compiler, so it names
+ *   the passes rather than blaming the pack list.
+ */
+export function orderPassesByDependency(packs: readonly object[]): object[];
+/**
+ * The dependencies this run cannot satisfy by ordering, because the pass that
+ * would produce them is not in it.
+ *
+ * Ordering answers the whole-package build; a run restricted to one pack
+ * (`content-build package compile <name>`) cannot conjure the passes it left
+ * out. Where their output is already on disk from an earlier run that is fine
+ * — it is how compiling one pack at a time is meant to work — so this reports
+ * only what is genuinely absent, and names the pack that would write it rather
+ * than the directory that is missing.
+ *
+ * @param {readonly object[]} running - The passes this run will execute.
+ * @param {object} config - The resolved build configuration.
+ * @returns {string[]} One message per unsatisfiable dependency.
+ */
+export function unsatisfiedPassDependencies(running: readonly object[], config: object): string[];
 /**
  * The passes that compiled nothing when they were expected to compile
  * something — a build failure, not a quiet no-op.

package/types/engine/homepage.d.mts

@@ -5,6 +5,87 @@
  * @returns {boolean} Whether it is a homepage note.
  */
 export function isHomepage(fm: object | null | undefined): boolean;
+/**
+ * The address-bearing fields one note authors, in the order it authored them.
+ *
+ * Authoring order rather than declaration order, so a caller emitting one
+ * diagnostic per finding emits them top to bottom down the file — the order a
+ * reader and a compiler-output parser both expect.
+ *
+ * Presence is the whole test: `shortcode:` authored empty still says "this page
+ * has an address of its own", and a value cannot make the claim true.
+ *
+ * Returned without a locator, because the two things that would supply one —
+ * the raw note text and the position helper — belong to the caller. This
+ * mirrors {@link module:engine/retired-fields}, whose retired-field messages
+ * are likewise positioned by whoever reports them.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {Array<{key: string, message: string}>} One entry per field the note
+ *   authored, empty for any note that is not a homepage.
+ */
+export function checkHomepageAddressFields(fm: object | null | undefined): Array<{
+    key: string;
+    message: string;
+}>;
+/**
+ * Require exactly one homepage note in a content tree (#52).
+ *
+ * "Exactly one" is two rules, and they are **one severity** because they are
+ * one defect: a package whose front page is not the page a person chose.
+ *
+ * - _None_ and the package serves nothing at `/<package>/`. That is the failure
+ *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   homepage(s)` and exits 0.
+ * - _Two_ and it serves a page nobody chose. Every homepage is written to the
+ *   same {@link HOMEPAGE_DESTINATION}, so the second overwrites the first and
+ *   the package's front page is decided by the order the walk happened to reach
+ *   the files in — by *filename*, on a type whose whole point is that it is
+ *   routed by frontmatter. There is no "first wins" convention to fall back on,
+ *   so nothing here can pick the right one.
+ *
+ * Neither has a safe default, so neither is a warning. A warning is the right
+ * severity for something a build can proceed past correctly, and a build that
+ * proceeds past either of these publishes the wrong front page while reporting
+ * success — which is the exact outcome a warning would be tolerating.
+ *
+ * **Two is reported once per note, not once for the tree.** Each note is a
+ * place an author has to open and edit, and a single finding saying "there are
+ * two" sends them hunting for the second.
+ *
+ * **None is located at the tree, honestly.** There is no file to name, so the
+ * locator is the content root — the directory the note is missing from, which
+ * is a real path and the one the author adds it to. No line and no column are
+ * invented for it, per the diagnostic rules in
+ * {@link module:engine/diagnostics}. {@link lintContentTree} already reports an
+ * empty walk against the same locator.
+ *
+ * The rule reads no `site:` configuration and does not vary by
+ * `publish.site`: that setting chooses whether the *content* surfaces are
+ * published, and the homepage is the floor underneath both modes.
+ *
+ * @param {ReadonlyArray<{file: string}>} found - The homepage notes, in walk
+ *   order. Paths may be absolute or relative to the working directory.
+ * @param {object} options - Options.
+ * @param {string} options.contentBase - Root of the content tree, for the
+ *   locator when there is no file to name.
+ * @param {string} [options.contentPackage] - The package this tree builds.
+ *   Dropped from the message when unknown rather than guessed.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "error", message: string}>} The findings, one per offending note.
+ */
+export function checkHomepageCount(found: ReadonlyArray<{
+    file: string;
+}>, { contentBase, contentPackage }: {
+    contentBase: string;
+    contentPackage?: string | undefined;
+}): Array<{
+    file: string;
+    line?: number;
+    column?: number;
+    severity: "error";
+    message: string;
+}>;
 /**
  * The title a homepage publishes under.
  *
@@ -46,49 +127,40 @@ export function homepageFrontmatter(fm: object, { contentPackage, title }: {
     title: string;
 }): object;
 /**
- * The package homepage — a note that compiles to a **page** rather than to a
- * compendium document (#51).
- *
- * Every HeroicLands package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
- * and what a reader finds there is one markdown file in the content tree,
- * written by a person: what the module is, which system it needs, how to install
- * it, where its source lives. Nothing about it is derived.
- *
- * **Authored, not assembled.** An earlier sketch generated the page in tiers —
- * identity and licence from the manifest, install URL from the release address,
- * "requires" links from `relationships`, a card per configured section. It would
- * have worked and needed almost no authoring, and it produces a page nobody
- * chose the contents of. The things that matter most on these pages cannot be
- * derived: that Kethira requires buying the book from Keléstia, what Thalorna's
- * setting *is*, which of twenty sections a reader should start with. So the only
- * thing defaulted here is the title, from `packageBuild.manifest.title`, so that
- * the package's name is not written twice.
- *
- * **Dispatched by `type`, not by filename.** A fixed `homepage.md` the walker
- * special-cased would be the anomaly: notes are routed by frontmatter, not by
- * location, and `NOTE_SCHEMAS` already routes `doc`, `macro`, `being` and the
- * map types. `homepage` is one more entry whose compile step emits a page. It is
- * deliberately not `README.md`: `landing: readme` already means "a `README.md`
- * is its section's landing page", and `sohl-thalorna/assets/content/README.md`
- * is a developer explainer about the source tree — adopting that name would make
- * Thalorna's public front page its build documentation.
- *
- * **Engine, not `sohl/`.** The `engine/` ÷ `sohl/` line separates *note-format*
- * knowledge from *game-system* knowledge, and a homepage is note format: it
- * carries no `system` block, mirrors no item builder, and would mean the same
- * thing for a game system that is not SoHL. Reachability is the symptom that
- * makes it obvious — `HarnMaster-3-FoundryVTT` declares no `itemBuilders`, so a
- * type living in the SoHL registry would be unavailable to HM3 and to every HM3
- * module, which is most of the packages that need a homepage and nothing else.
- *
- * **Its address is the package's, not the note's.** A homepage publishes at
- * `/<contentPackage>/` because that is where the package is, so `name.full`,
- * `shortcode` and `id` decide nothing on it (#53 refuses them outright; this
- * module simply never reads them). It compiles into no document, so it carries
- * no compendium UUID and appears in no pack and in no link-manifest entry.
- *
- * @module
+ * Every address a homepage carries, wherever it is written.
+ *
+ * **Both halves of the page are in scope, and that is the finding rather than
+ * the assumption.** Of the six homepages authored today, four carry every link
+ * in the body as ordinary markdown and two carry them in `landing:` — and the
+ * one whose dead links prompted the check has an *empty body*, so a body-only
+ * reading would have found nothing at all on it. A dead link in a card is
+ * exactly as broken as one in a paragraph.
+ *
+ * Three shapes are gathered, and the caller needs to tell them apart because
+ * the rules differ:
+ *
+ * - **`url`** — package-relative, resolved against the site by the theme.
+ * - **`href`** — already resolved, used verbatim.
+ * - **prose and body markdown links** — emitted as written and resolved by the
+ *   browser against the landing's own address, which *is* the package root, so
+ *   a relative one means the same thing a `url` does.
+ *
+ * `banner:` is not an address: it is an image path resolved through the CDN
+ * base, and `banner: none` is a sentinel rather than a target. Top-level
+ * `title` and `description` are not walked either — they are set as text, never
+ * rendered as markdown.
+ *
+ * @param {object|null|undefined} fm - The note's frontmatter.
+ * @param {string} [body] - The note's markdown body.
+ * @returns {Array<{field: string, url: string, kind: string}>} Every address,
+ *   frontmatter first and then the body, each with the dotted path it was
+ *   written at.
  */
+export function homepageAddresses(fm: object | null | undefined, body?: string): Array<{
+    field: string;
+    url: string;
+    kind: string;
+}>;
 /**
  * The note type that compiles to the package homepage.
  *
@@ -116,3 +188,55 @@ export const HOMEPAGE_FIELDS: readonly import("./field-spec.mjs").FieldSpec[];
  * @type {string}
  */
 export const HOMEPAGE_DESTINATION: string;
+/**
+ * The top-level fields a homepage refuses, and what each one would decide (#53).
+ *
+ * A note's URL derives from `name.full` and its identity from
+ * `(type, shortcode)`. The homepage is the one page for which neither holds: it
+ * publishes at `/<package>/`, fixed by the package id. An author fluent in the
+ * conventions writes them here expecting exactly what they do everywhere else,
+ * and gets none of it.
+ *
+ * **They were never inert, which is why ignoring them was the wrong answer.** A
+ * `shortcode` puts the note in the address index and in the `dataview` link
+ * universe, so `[[homepage-<shortcode>]]` resolves *green* — to
+ * `homepage/<slug>/`, an address derived from `name.full` and published by
+ * nothing, because a homepage is written to {@link HOMEPAGE_DESTINATION} at the
+ * package root. A build that reports a live link to a 404 is worse than one
+ * that says nothing. It also inflates `content-build lint`'s address tally, so
+ * the lint and the link manifest disagree about what the package publishes.
+ *
+ * **A named class, not an allow-list, and that boundary is the decision.** The
+ * documented envelope is `type` plus an optional `title`, and `landing`,
+ * `description` and `banner` are legitimate beside them — but a homepage's
+ * frontmatter is *emitted into the published page*
+ * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
+ * parameter this build has never heard of and has no standing to refuse.
+ * Rejecting unknown keys would make every new theme parameter wait on a
+ * package-build release. What is refused is the specific class that makes a
+ * false claim about *where this page is*.
+ *
+ * `aliases` is deliberately not in the class: {@link homepageFrontmatter}
+ * already drops it from every emitted page, with a reason of its own, so
+ * authoring one is the same no-op it is on any other page rather than a wrong
+ * belief about this one's address.
+ *
+ * @type {ReadonlyMap<string, string>}
+ */
+export const HOMEPAGE_REFUSED_FIELDS: ReadonlyMap<string, string>;
+/**
+ * The two frontmatter keys that hold an address, and what each one means.
+ *
+ * They are **not** interchangeable, and a check that treated them as one would
+ * be wrong about both. The theme resolves a `url` against the site with
+ * `relURL`, so a package writes `kb/rules/` and is served `/sohl/kb/rules/`
+ * without ever naming its own prefix. An `href` is an address that is *already*
+ * resolved and is used verbatim — which is what `cards.source: sections` fills
+ * in, since a section's permalink already carries the prefix.
+ *
+ * So a leading `/` is a defect in a `url` (it is prefixed a second time) and
+ * correct in an `href`.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const HOMEPAGE_ADDRESS_KEYS: ReadonlySet<string>;

package/types/engine/pack-config.d.mts

@@ -56,6 +56,19 @@ export function configFromData(data: unknown, configPath: string): import("../co
  *   compilers know neither what to compile nor where to put it.
  */
 export function loadPackConfig(): import("../config.mjs").ContentBuildConfig;
+/**
+ * The file {@link loadPackConfig} resolved the configuration from.
+ *
+ * A diagnostic about a *configured* value has to name the file it was declared
+ * in, and re-deriving that path at the point of the finding would be a second
+ * resolution free to disagree with the first — the `PACKAGE_BUILD_CONFIG`
+ * override, the upward walk and the one-file-per-directory rule all have to
+ * come out the same way. This reports the path actually read.
+ *
+ * @returns {string} Its absolute path.
+ * @throws {Error} As {@link loadPackConfig}, when there is no configuration.
+ */
+export function packConfigPath(): string;
 /** The stem every consuming repository declares its build under. */
 export const CONFIG_BASENAME: "package-build.config";
 /**

package/types/engine/site-build.d.mts

@@ -50,9 +50,9 @@ export function collectTreePages(tree: object, ctx: object): {
  * packages ship under is a property of the code path rather than of a
  * configuration that happens to be empty (#55).
  *
- * Returned as a list rather than as the one note there should be. Requiring
- * exactly one is #52's, and it is a separate decision — this reports what it
- * found so a count is visible either way.
+ * Returned as a list rather than as the one note there should be, because the
+ * count is what {@link checkHomepageCount} judges (#52) — this walk reports
+ * what it found, and {@link buildSite} decides whether that is one.
  *
  * @param {string} contentBase - Absolute path to the content tree.
  * @param {object} ctx - `{ skipDirectories }`.
@@ -65,10 +65,16 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * Writes each homepage at the package's own root.
  *
  * Its own writer, deliberately small. A homepage is authored markdown published
- * verbatim — no table expansion, no section landing, and (until #54) no link
- * resolution — so routing it through {@link renderPages} would buy it a pipeline
- * it has no input for, and would make homepage-only mode depend on the index,
- * the foreign manifests and the table universe that mode exists to not build.
+ * verbatim — no table expansion, no section landing and no link resolution — so
+ * routing it through {@link renderPages} would buy it a pipeline it has no input
+ * for, and would make homepage-only mode depend on the index, the foreign
+ * manifests and the table universe that mode exists to not build.
+ *
+ * **Verbatim is the answer to #54, not a gap left by it.** A landing's links
+ * could not be *resolved* here without giving `homepage` mode the index its
+ * licensing fence exists to not build, so they are **checked** instead:
+ * {@link auditHomepageLinks} reads the `landing:` addresses and the body's
+ * markdown links, and reports a wikilink on the page rather than resolving one.
  *
  * @param {string} outRoot - The package's site root — the configured `site.out`,
  *   one level above the content mount.
@@ -123,6 +129,31 @@ export function gatesFailed(gates: any): boolean;
  * @returns {Map<string, object[]>} Package → the notes it may tabulate.
  */
 export function tableUniverse(pages: object[]): Map<string, object[]>;
+/**
+ * The front matter a section's landing states about itself.
+ *
+ * The section metadata a configuration resolved, ready to be written or merged
+ * onto a page. Two things happen here and nothing else does:
+ *
+ * - **`title` leads.** It is the one key every landing has carried since the
+ *   first one, and a landing whose block opened with `banner:` would be a
+ *   gratuitous diff on every consumer's tree.
+ * - **An absent value is left off**, not written as `undefined` — which is not
+ *   a value YAML can carry, and would abort the serializer.
+ *
+ * Everything else the section declared is passed through. That is the point of
+ * the function: before #91 both writers transcribed `title` and `banner` by
+ * name, so the vocabulary lived in three places — the schema that admits a key
+ * and the two writers that copy it — and a key added to the schema alone
+ * validated cleanly and then reached no page. The *schema* is the bound worth
+ * keeping (see `normalizeSectionMeta`, which refuses a key it does not know and
+ * names it); a second, silent bound in the writers is not.
+ *
+ * @param {object} meta - A resolved `site.sections` / `site.readmeSections`
+ *   entry.
+ * @returns {object} Its front matter, `title` first.
+ */
+export function sectionFrontmatter(meta: object): object;
 /**
  * The frontmatter a page publishes with.
  *

package/types/manifest.d.mts

@@ -59,6 +59,60 @@ export function releaseUrls({ repoUrl, version, artifact }: {
  * @returns {object[]} The manifest's `packs` array.
  */
 export function manifestPacks(config: object): object[];
+/**
+ * What `packFolders` and the derived `packs[]` disagree about.
+ *
+ * `packFolders` is the one **declared** manifest key that names something the
+ * build **derives**: every other declared key states a fact about the package
+ * (`title`, `socket`, `grid`) or addresses a staged file (`esmodules`,
+ * `styles`, `languages`), and a staged file is a different relation, checked
+ * against the stage rather than against configuration. So this is the one place
+ * a declaration can go stale against a value the build already computed — and
+ * until now nothing compared them (#81).
+ *
+ * `HarnMaster-3-FoundryVTT` shipped the consequence: its folder named four
+ * packs, three of which had not existed since the compendium was consolidated,
+ * and omitted `items` — 1,577 of 1,597 documents, loose in Foundry's compendium
+ * browser, with the build reporting nothing (HM3#420).
+ *
+ * **The two findings are not the same finding**, and giving them one severity
+ * gets one of them wrong:
+ *
+ * - _A folder names a pack that does not exist_ is an **error**. Foundry
+ *   resolves the name against the package's own packs and silently skips what
+ *   it cannot find, so the declaration does nothing at all; there is no
+ *   arrangement in which it is intended, and the fix is unambiguous.
+ * - _A pack no folder names_ is a **warning**. It is legal and can be
+ *   deliberate — a package may want one pack at the root — so failing on it
+ *   would break working packages for a matter of taste. But a package that
+ *   bothered to declare a folder rarely meant to leave one out, which is
+ *   exactly how HM3's `items` went unnoticed.
+ * - _A package declaring no folders_ says **nothing**. Everything at the root
+ *   is the majority arrangement, not an omission.
+ *
+ * Errors come first, in declaration order, then warnings in pack order: the
+ * unresolvable names are what a reader fixes, and a folder gaining a name often
+ * settles a warning too.
+ *
+ * @param {object} options
+ * @param {unknown} [options.packFolders] - The declared `packFolders`.
+ * @param {ReadonlyArray<{name: string}>} [options.packs] - The derived packs,
+ *   as {@link manifestPacks} returns them.
+ * @returns {Array<{severity: "error"|"warning", message: string, pack: string,
+ *   folder?: string, keyPath: Array<string|number>}>} The findings, ordered.
+ */
+export function packFolderFindings({ packFolders, packs }: {
+    packFolders?: unknown;
+    packs?: readonly {
+        name: string;
+    }[] | undefined;
+}): Array<{
+    severity: "error" | "warning";
+    message: string;
+    pack: string;
+    folder?: string;
+    keyPath: Array<string | number>;
+}>;
 /**
  * The `relationships` block as published — every declared dependency, with the
  * build's own keys dropped.
@@ -109,20 +163,32 @@ export function buildManifest({ config, packageJson, artifact, flags }: {
 /**
  * Write the generated manifest into the staged package.
  *
+ * The declared `packFolders` is checked against the derived `packs[]` first,
+ * and an unresolvable name **stops the write**: a manifest already known to
+ * describe packs the package does not ship should not reach the stage, where
+ * the next command would deploy it (#81). See {@link packFolderFindings} for
+ * the rule and why its two findings carry different severities.
+ *
  * @param {object} options - As {@link buildManifest}, plus where to write.
  * @param {object} options.config - The resolved content configuration.
  * @param {object} options.packageJson - The repository's `package.json`.
  * @param {string} options.artifact - `system` or `module`.
  * @param {string} options.outDir - Directory to write into.
  * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @param {string} [options.configFile] - Absolute path of the configuration
+ *   file the manifest was resolved from, so a finding about it can be located.
+ *   Omitting it costs the position, not the finding.
  * @returns {Promise<{path: string, manifest: object}>} Where it went, and what.
+ * @throws {Error} When a `packFolders` entry names a pack the package does not
+ *   ship. Nothing is written in that case.
  */
-export function writeManifest({ config, packageJson, artifact, outDir, flags, }: {
+export function writeManifest({ config, packageJson, artifact, outDir, flags, configFile, }: {
     config: object;
     packageJson: object;
     artifact: string;
     outDir: string;
     flags?: Record<string, object> | undefined;
+    configFile?: string | undefined;
 }): Promise<{
     path: string;
     manifest: object;

package/types/sohl/kb-passes.d.mts

@@ -54,11 +54,15 @@ export function rewriteRepoLinks(body: string, docRel: string, options: object):
  * Both run inside code-fence protection, so neither can rewrite a fenced example.
  *
  * @param {object} options - Resolved from `site.passOptions`.
- * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map.
+ * @param {string} [options.symbolMap] - Path to the TypeDoc symbol map,
+ *   relative to `repoRoot`. Absent means no API links; present and unusable is
+ *   a build failure.
  * @param {string} [options.apiBase] - Where the API documentation is served.
  * @param {string} [options.blob] - GitHub blob base for repository files.
  * @param {string} options.repoRoot - The repository root, for relative paths.
  * @returns {{beforeLinks: Function, afterLinks: Function}} The bundle.
+ * @throws {Error} When a configured `symbolMap` cannot be resolved, read,
+ *   parsed, or is not a name → page object.
  */
 export function sohlKbPass(options: {
     symbolMap?: string | undefined;