@heroiclands/package-build 20.3.1 → 20.5.0

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

@@ -34,7 +34,7 @@ export function deepMerge(base: any, overlay: any): any;
  * vocabulary, so a reference is translated forward through the system's map
  * before it reaches this function; see
  * {@link SystemActorCompiler#embeddedSubtype} for why the translation goes that
- * way and not the other (#140).
+ * way and not the other.
  *
  * @param {string} subType - The Foundry Item subtype.
  * @param {string} shortcode - The item's `system.shortcode`.
@@ -43,7 +43,7 @@ export function deepMerge(base: any, overlay: any): any;
 export function itemAddress(subType: string, shortcode: string): string;
 /**
  * The key one predefined item is held under **for the package that publishes
- * it** — the address a `model:` naming that package resolves through (#334).
+ * it** — the address a `model:` naming that package resolves through.
  *
  * The unqualified {@link itemAddress} stays beside it, and the two answer
  * different questions. A `model` that names no package means *this* one and
@@ -70,11 +70,12 @@ export function packagedItemAddress(pkg: string, subType: string, shortcode: str
  * A shortcode is case-sensitive and routinely mixed — `Clb`, `LtShoe`,
  * `HsTunic` — while an **address** is not: `readQualifier` normalises what it
  * reads, and every canonical address is lowercase. So the moment a `model:` is
- * read as an address (#334), `weapongear-clb` has to find the document whose
- * `system.shortcode` is `Clb`, and an exact match cannot (#346).
+ * read as an address, `weapongear-clb` has to find the document whose
+ * `system.shortcode` is `Clb`, and an exact match cannot.
  *
  * Folding is safe because the fold is already the address: no two items in any
- * published tree differ only by the case of their shortcode, and #340 will make
+ * published tree differ only by the case of their shortcode, and the rule
+ * makes
  * that impossible rather than merely true.
  *
  * **This is not {@link itemAddress}, and must not become it.** That one seeds
@@ -116,13 +117,13 @@ export function embeddedIdentity(item: object): string;
  * four corpora holds 180 items, at which 64 bits collide with probability
  * around 10⁻¹⁵.
  *
- * **It takes no index** (#268). Keying on a position meant reordering a being's
+ * **It takes no index**. Keying on a position meant reordering a being's
  * item list renumbered every id after the change, so a re-import created new
  * documents beside the old ones — while nothing about those documents had
  * changed, only their neighbours. The identity always exists or must be stated;
  * see {@link embeddedIdentity}.
  *
- * Keyed by the **document subtype**, so renaming a note type (#78) leaves every
+ * Keyed by the **document subtype**, so renaming a note type leaves every
  * embedded id where it was.
  *
  * @param {string} actorId - The owning actor's id.
@@ -186,7 +187,7 @@ export class SystemActorCompiler extends BasePackCompiler {
     foreignSourceDirs: any;
     /**
      * Every package a `model:` may name besides this one — the dependencies
-     * whose item catalogues were supplied (#334).
+     * whose item catalogues were supplied.
      *
      * @returns {Set<string>} The dependency package ids.
      */
@@ -210,7 +211,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      * The Foundry Item subtype an embedded reference's `type` addresses.
      *
      * **The reference is in the note vocabulary; the address is in the
-     * document's** (#140). An actor writes `(type, shortcode)` with the type an
+     * document's**. An actor writes `(type, shortcode)` with the type an
      * author authors, while {@link itemAddress} keys the predefined items by
      * the subtype each compiled document carries — so exactly one of the two
      * sides has to translate, and it is this one. The system's map is a
@@ -223,6 +224,31 @@ export class SystemActorCompiler extends BasePackCompiler {
      *   subtype, or why the reference names none.
      */
     embeddedSubtype(type: string): import("./document-subtypes.mjs").ReferencedSubtype;
+    /**
+     * Read an entry's `model:` — the address of the item it is a copy of.
+     *
+     * The address grammar is the wikilink one, so a `model` is written at
+     * whatever length says what it means: `skill-wpnc` within this package,
+     * `sohl-sohl-skill-wpnc` to reach another. The system segment defaults from
+     * the block the entry sits in — `<system>.items` — which is what makes the
+     * short form name an *Item* here while the same string in body prose names
+     * a page.
+     *
+     * It replaced a top-level `shortcode:` that meant something different from
+     * the `system.shortcode` beside it and could not say which package a
+     * template came from.
+     *
+     * @param {unknown} model - The authored value.
+     * @param {number} index - The entry's position, for the message.
+     * @param {string} ctx - Diagnostic context (the actor's label).
+     * @returns {{type: string, shortcode: string, package: string|null}|null}
+     *   The parsed address, or `null` after reporting why it is not one.
+     */
+    readModel(model: unknown, index: number, ctx: string): {
+        type: string;
+        shortcode: string;
+        package: string | null;
+    } | null;
     /**
      * Resolve one embedded item from a `(type, shortcode?, overlay)`
      * descriptor. If `shortcode` is given, the predefined item is fetched
@@ -230,7 +256,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      * descriptor must carry enough fields to stand alone. The embedded
      * item's `_id` is regenerated deterministically from
      * `(actorId, subType, shortcode, indexKey)` so re-exports are stable —
-     * from the **document subtype**, so that renaming a note type (#78) leaves
+     * from the **document subtype**, so that renaming a note type leaves
      * every embedded id exactly where it was.
      * Returns null if the descriptor cannot be resolved.
      *
@@ -239,45 +265,24 @@ export class SystemActorCompiler extends BasePackCompiler {
      * @param {string} type - The **note** type the reference names.
      * @param {string|null} shortcode - The referenced item's shortcode, or
      *   `null` for a stand-alone entry.
-     * @param {object} [overlay] - The entry's remaining properties.
+     * @param {object} overlay - The entry's remaining properties.
      * @param {string} indexKey - Where the reference sits, for a diagnostic.
-     *   It no longer reaches the id (#268) — it names the entry in a message.
+     *   It names the entry in a message and does not reach the id.
      * @param {string} ctx - Diagnostic context (the actor's label).
      * @param {object} [at] - Where to locate a finding.
      * @param {string} [at.fmKey] - The frontmatter key the reference sits
      *   under, so an unresolved one is reported at the reference rather than
      *   at the note.
+     * @param {string|null} [at.modelPackage] - The package a `model:` names,
+     *   where the template comes from another package's catalogue. Given one,
+     *   the packaged address is what resolves and nothing local shadows it.
      * @returns {object|null} The embedded item, or null when it resolved to
      *   nothing — always with a finding emitted.
      */
-    /**
-     * Read an entry's `model:` — the address of the item it is a copy of.
-     *
-     * The address grammar is the wikilink one (#336), so a `model` is written at
-     * whatever length says what it means: `skill-wpnc` within this package,
-     * `sohl-sohl-skill-wpnc` to reach another. The system segment defaults from
-     * the block the entry sits in — `<system>.items` — which is what makes the
-     * short form name an *Item* here while the same string in body prose names
-     * a page.
-     *
-     * It replaced a top-level `shortcode:` that meant something different from
-     * the `system.shortcode` beside it and could not say which package a
-     * template came from (#334).
-     *
-     * @param {unknown} model - The authored value.
-     * @param {number} index - The entry's position, for the message.
-     * @param {string} ctx - Diagnostic context (the actor's label).
-     * @returns {{type: string, shortcode: string, package: string|null}|null}
-     *   The parsed address, or `null` after reporting why it is not one.
-     */
-    readModel(model: unknown, index: number, ctx: string): {
-        type: string;
-        shortcode: string;
-        package: string | null;
-    } | null;
-    resolveEmbedded(itemsMap: any, actorId: any, type: any, shortcode: any, overlay: any, indexKey: any, ctx: any, { fmKey, modelPackage }?: {
-        modelPackage?: null | undefined;
-    }): any;
+    resolveEmbedded(itemsMap: Map<string, object>, actorId: string, type: string, shortcode: string | null, overlay: object, indexKey: string, ctx: string, { fmKey, modelPackage }?: {
+        fmKey?: string | undefined;
+        modelPackage?: string | null | undefined;
+    }): object | null;
     #private;
 }
 import { BasePackCompiler } from "./base-compiler.mjs";

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

@@ -11,7 +11,7 @@
  */
 export function isAddressSegment(value: unknown): boolean;
 /**
- * The one charset every segment of a canonical address is held to (#59).
+ * The one charset every segment of a canonical address is held to.
  *
  * An address is a hyphen-joined tuple — `package-system-type-shortcode`, so
  * `sohl-none-doc-gear` — and it is read back by **counting segments**, with a
@@ -41,7 +41,7 @@ export function isAddressSegment(value: unknown): boolean;
  * digits only.
  *
  * Case *was* deliberately unconstrained, on the reasoning that case has no
- * bearing on the separator — which is true, and beside the point (#340).
+ * bearing on the separator — which is true, and beside the point.
  *
  * **Two names that differ only in case are two names nobody can tell apart.** A
  * shortcode is how a person names a thing when writing a reference —
@@ -53,10 +53,10 @@ export function isAddressSegment(value: unknown): boolean;
  * `sohl-sohl-weapongear-clb` and its `_id` derived from that. The authored name
  * and its address disagreed, and everything downstream keys on the address —
  * which left two notes differing only in case sharing one address, one `_id` and
- * one URL, with nothing to report it. It also forced two exceptions elsewhere:
- * #336 had to exempt the shortcode from the lowercase rule it pinned on every
- * other segment, and #346 had to fold the shortcode's case in the item catalogue
- * because an address is lowercased when read.
+ * one URL, with nothing to report it. It also forces two exceptions elsewhere:
+ * the shortcode has to be exempted from the lowercase rule pinned on every
+ * other segment, and its case has to be folded in the item catalogue because
+ * an address is lowercased when read.
  *
  * One case, one spelling, no exceptions. Every tree already complies but two,
  * and nothing in any of them collides when folded.

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

@@ -39,9 +39,60 @@ export function readItemAddresses(dirs: readonly string[]): Map<string, {
     shortcode: string;
     file: string;
 }>;
-export function declaredPredecessors(contentBase: any, { skipDirectories, maps, config, records, problems }?: {
-    maps?: readonly import("./document-subtypes.mjs").DocumentSubtypeMap[] | undefined;
-}): Map<any, any>;
+/**
+ * Every rename the tree's notes **declare**, as old address → where it went.
+ *
+ * Read from the content tree rather than from compiled output, because a
+ * declaration is authored and the compiled document does not carry it: nothing
+ * downstream consumes `renamedFrom:`, so emitting it into every pack to let one
+ * diagnostic read it back would put a build-time note in shipped data forever.
+ * The tree is already read by this module for the same reason
+ * ({@link noteFilesById}) — to place a finding where its author can fix it.
+ *
+ * **A declaration is keyed by document subtype, not by note type.** The address
+ * space is the one consumers resolve against, and it is spelled in compiled
+ * documents: `hm3` compiles a `projectile` note into a `missilegear` item,
+ * so that is the address a rename of it moves. {@link referencedSubtype} is the
+ * function that already answers this for a being's embedded `(type, shortcode)`
+ * references, so both sides read the same rule rather than a second copy of it.
+ *
+ * **An entry is emitted for every system that maps the type**, whether or not
+ * the note declares that system's block. Over-emitting is inert — the diff uses
+ * an entry only when the baseline published the old address *and* this build
+ * publishes the new one, and a system the note does not compile for satisfies
+ * neither — while asking which blocks a note declares would put a second,
+ * subtly different answer to that question in a third place.
+ *
+ * **First claim wins on a collision.** Two notes naming one predecessor is a
+ * contradiction — an address has one successor — and it is reported as an error
+ * by `engine/content-lint.mjs`, where both notes are in hand and can both be
+ * named. Picking one here keeps this a map; it is not a resolution, and nothing
+ * rests on which one it picked.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} opts
+ * @param {readonly string[]} [opts.skipDirectories] - The corpus scope. Stated
+ *   by the caller, never defaulted — see {@link addressCorpus}.
+ * @param {readonly object[]} [opts.maps] - The document-subtype maps.
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {readonly object[]} [opts.records] - Index records the caller already
+ *   derived, shared with {@link noteFilesById} so one command reads one corpus.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, so one of them does not abort the diff before it reports.
+ * @returns {Map<string, {to: string, file: string, shortcode: string}>} Old
+ *   address → the address the declaring note publishes at now, and that note.
+ */
+export function declaredPredecessors(contentBase: string, { skipDirectories, maps, config, records, problems }?: {
+    skipDirectories?: readonly string[] | undefined;
+    maps?: readonly object[] | undefined;
+    config?: object | undefined;
+    records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
+}): Map<string, {
+    to: string;
+    file: string;
+    shortcode: string;
+}>;
 /**
  * Every address the baseline published that this build does not.
  *
@@ -57,7 +108,7 @@ export function declaredPredecessors(contentBase: any, { skipDirectories, maps,
  * @param {Map<string, {to: string, file: string}>} [opts.predecessors] - The
  *   declared renames, from {@link declaredPredecessors}. Omitted, the diff
  *   falls back to the id join alone and reports an unpinned rename as a
- *   withdrawal, which is what it did before #278.
+ *   withdrawal, which is what it did before.
  * @returns {Array<object>} One finding per departed address, in address order
  *   so two runs read the same. `kind` is `"renamed"` (with `to`, and `declared`
  *   when it was the note's word rather than an id match) or `"withdrawn"`.
@@ -85,12 +136,15 @@ export function diffItemAddresses(baseline: Map<string, object>, current: Map<st
  *   id is derived against. See {@link addressCorpus} for why that matters.
  * @param {readonly object[]} [opts.records] - Index records the caller already
  *   derived, shared with {@link declaredPredecessors}.
+ * @param {object[]} [opts.problems] - Collects the notes the index cannot
+ *   record, so one of them does not abort the diff before it reports.
  * @returns {Map<string, string>} Document id → the note's absolute path.
  */
 export function noteFilesById(contentBase: string, { skipDirectories, config, records, problems }?: {
     skipDirectories?: readonly string[] | undefined;
     config?: object | undefined;
     records?: readonly object[] | undefined;
+    problems?: object[] | undefined;
 }): Map<string, string>;
 /**
  * Where to send the reader for one finding.
@@ -105,7 +159,7 @@ export function noteFilesById(contentBase: string, { skipDirectories, config, re
  * A **declared** rename knows its note without any lookup — the declaration is
  * how it was found — and is reported at the `renamedFrom:` line rather than the
  * `shortcode:` line, because that is the line the finding is about and the one
- * the author deletes once the declaration has done its work (#278).
+ * the author deletes once the declaration has done its work.
  *
  * @param {object} finding - One finding from {@link diffItemAddresses}.
  * @param {Map<string, string>} noteFiles - From {@link noteFilesById}.
@@ -126,7 +180,7 @@ export function locateAddressFinding(finding: object, noteFiles: Map<string, str
  * known — and says so, rather than leaving the reader to wonder whether one was
  * looked for.
  *
- * **A declared rename says it is declared** (#278). The two claims are not
+ * **A declared rename says it is declared**. The two claims are not
  * equally checkable: an id match is a fact in the artefacts, while a
  * declaration is an author's word, and a reader deciding whether to trust the
  * successor needs to know which one they have. Saying "the same document" of a

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

@@ -5,7 +5,7 @@
  * note is one this build **refused** — it declares a retired frontmatter field
  * — and it is an error; a skipped one legitimately belongs to another pass, and
  * there are thousands of those. Folding the first into the second is what let a
- * whole tree be filtered out in silence (#56).
+ * whole tree be filtered out in silence.
  *
  * @typedef {object} PassStats
  * @property {number} compiled - Notes that became a document.
@@ -13,7 +13,7 @@
  * @property {number} skippedOther - Notes this pass does not claim.
  * @property {number} declined - Notes this pack **refused** — one declaring a
  *   retired frontmatter field, or one routed to a system pack whose system it
- *   says nothing about (#58). Counted as errors, never as skips.
+ *   says nothing about. Counted as errors, never as skips.
  */
 /**
  * The shared walk → filter → expand → convert → build → write → count loop.
@@ -51,7 +51,7 @@ export class BasePackCompiler {
      * 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
+     * the macros pass, whose `command` is executable source. A pass
      * that says so also skips building the content-wide link index it would
      * never read.
      *
@@ -67,7 +67,7 @@ export class BasePackCompiler {
      * passes wrote — so an Actor pass must run after every Item pass, and it
      * says so here.
      *
-     * The generator derives the compile order from this (#73), so the order
+     * The generator derives the compile order from this, so the order
      * `packs:` declares is presentation only — it is the manifest's `packs`
      * array as well, and a consumer orders that for a reader. A pass that
      * reads another's output states the dependency once, in the class that
@@ -82,7 +82,7 @@ export class BasePackCompiler {
     static readsPackOutputOf: readonly string[];
     /**
      * Whether this pass's document **is** a system's data, and therefore takes
-     * only notes that carry that system's block (#58).
+     * only notes that carry that system's block.
      *
      * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
      * and an `actors-sohl` from one tree — and the note-side half of that is
@@ -112,7 +112,7 @@ export class BasePackCompiler {
      * legal on every note whatever its type, because
      * `BLOCK_DOCUMENT_PROPERTIES` maps it onto `document.img` — so a note whose
      * document has no such property authors it, validates, compiles, and loses
-     * the value with nothing said. That is #349: `Parrot` in `sohl-thalorna`
+     * the value with nothing said: `Parrot` in `sohl-thalorna`
      * had declared `img:` since long before the art rule existed and compiled
      * `img: null` exactly as a note declaring nothing does. Naming the fields
      * here is what lets the lint tell an inert key from a live one.
@@ -134,13 +134,19 @@ export class BasePackCompiler {
      *   never descends into. Required: see {@link assertStatedScope}.
      * @param {(address: string|null) => string|null} [options.folderResolver] -
      *   Resolves a `packFolder` — a folder note's address — to the Foundry
-     *   folder id it materialises as in this pack (#255, #257).
+     *   folder id it materialises as in this pack.
      * @param {string} [options.packName] - The pack this pass writes.
+     * @param {string|null} [options.packSystem] - The system that pack declares,
+     *   which decides the `_stats` it stamps and the system block a note must
+     *   carry to reach it. `null` for a pack that declares none.
      * @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.
+     * @param {object} [options.corpus] - The corpus this compile is running
+     *   over, derived once and shared by every pass. A pass handed none derives
+     *   its own in `prepare`, and reports that corpus's problems itself.
      */
     constructor({ contentBase, dest, skipDirectories, folderResolver, packName, packSystem, docType, router, routingReporter, corpus, }?: {
         contentBase: string;
@@ -148,11 +154,13 @@ export class BasePackCompiler {
         skipDirectories: readonly string[];
         folderResolver?: ((address: string | null) => string | null) | undefined;
         packName?: string | undefined;
+        packSystem?: string | null | undefined;
         docType?: string | undefined;
         router?: {
             resolve: Function;
         } | undefined;
         routingReporter?: boolean | undefined;
+        corpus?: object | undefined;
     });
     /** @type {string} */
     contentBase: string;
@@ -163,7 +171,7 @@ export class BasePackCompiler {
     /** @type {number} */
     errorCount: number;
     /**
-     * Emitted-`system` findings, one per `documentType|subtype|field` (#155).
+     * Emitted-`system` findings, one per `documentType|subtype|field`.
      *
      * A key the compiler writes is on **every** document of a subtype, so
      * reporting it where it is found would print the same sentence 3,126 times
@@ -219,10 +227,10 @@ export class BasePackCompiler {
      * @type {number}
      */
     unresolvedLinks: number;
-    packSystem: any;
-    corpus: any;
+    packSystem: string | null;
+    corpus: object | undefined;
     /**
-     * The `_stats` block every entry this pass emits is stamped with (#48).
+     * The `_stats` block every entry this pass emits is stamped with.
      *
      * Per pack rather than per package, because a module may ship the same
      * content for two systems — `harn-ensemble` has an `actors-hm3` pack and an
@@ -252,8 +260,7 @@ export class BasePackCompiler {
      * routed *here* and carries nothing for this pack's system is an authoring
      * mistake with a hollow document at the end of it, not a note that belongs
      * to another pass. Skipping it quietly is how a whole tree compiles to
-     * documents nobody can use — the failure mode #1502 and #56 are both
-     * instances of.
+     * documents nobody can use.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {boolean} True when the note may be compiled here; `false` when
@@ -266,7 +273,7 @@ export class BasePackCompiler {
     eligibleFor(fm: object): boolean;
     /**
      * A refusal only this pass can make, because its subject is the note's
-     * **type** (#330).
+     * **type**.
      *
      * The `assertNo*Field` family above it in the walk is type-agnostic by
      * construction: it runs before `selects`, so that a note declaring a
@@ -291,7 +298,7 @@ export class BasePackCompiler {
      * Whether this pass claims a note. **Required.**
      *
      * Called only for a note this build compiles — every note in the tree
-     * belongs to the configured content package (#56) — so a subclass decides
+     * belongs to the configured content package — so a subclass decides
      * on `type` alone.
      *
      * @param {object} fm - The note's frontmatter.
@@ -368,8 +375,7 @@ export class BasePackCompiler {
         column?: number;
     }): void;
     /**
-     * Report every `<system>.system` key the receiving subtype does not declare
-     * (#58).
+     * Report every `<system>.system` key the receiving subtype does not declare.
      *
      * An **error**, not a warning: Foundry drops an unknown `system` key at
      * construction without a word, so the alternative is a document shipped
@@ -390,7 +396,7 @@ export class BasePackCompiler {
     reportUndeclaredSystemData(fm: object, block: string, documentType: string, subType: string): number;
     /**
      * Record every `system` key the *compiled document* carries that the
-     * receiving subtype does not declare (#155).
+     * receiving subtype does not declare.
      *
      * The sibling of {@link BasePackCompiler#reportUndeclaredSystemData}, and
      * the half that sees what no declaration states. A compiler writes keys of
@@ -434,7 +440,7 @@ export class BasePackCompiler {
     /**
      * Emit the collected emitted-`system` findings, once each.
      *
-     * An **error**, for the reason #60 made its sibling one: the value is gone
+     * An **error**, for the reason its sibling is one: the value is gone
      * at load and the build says nothing, and severity that varied by *which
      * part of the build wrote the key* would make the less fixable half the
      * quieter one. What varies is the message, which says whose fix it is —
@@ -529,7 +535,7 @@ export class BasePackCompiler {
  * note is one this build **refused** — it declares a retired frontmatter field
  * — and it is an error; a skipped one legitimately belongs to another pass, and
  * there are thousands of those. Folding the first into the second is what let a
- * whole tree be filtered out in silence (#56).
+ * whole tree be filtered out in silence.
  */
 export type PassStats = {
     /**
@@ -547,7 +553,7 @@ export type PassStats = {
     /**
      * - Notes this pack **refused** — one declaring a
      * retired frontmatter field, or one routed to a system pack whose system it
-     * says nothing about (#58). Counted as errors, never as skips.
+     * says nothing about. Counted as errors, never as skips.
      */
     declined: number;
 };

package/types/engine/bundle-notes.d.mts

@@ -35,7 +35,7 @@ export function bareAddress(value: unknown): string | null;
  * `### type: bundle` table puts it — the closed container, so a misspelled
  * `content` is a finding rather than a silently empty Adventure. It is accepted
  * at the top level too, exactly as a folder note's `parent` is: an author
- * following #259's own example rather than the specification should get a
+ * following the shipped example rather than the specification should get a
  * bundle, not a silent default.
  *
  * **Order is the author's**, and it is kept: an Adventure's `SetField` attaches
@@ -124,9 +124,9 @@ export function buildAdventure({ id, name, img, description, caption, folder, fl
  * world's collection already holds that `_id`, then creates or updates each.
  * Afterwards the documents live independently and the Adventure has no further
  * role. **It is an installer** — a set of document *copies* packaged for
- * one-shot import (#259).
+ * one-shot import.
  *
- * That is the whole difference from a folder (#256), which is a live grouping
+ * That is the whole difference from a folder, which is a live grouping
  * **by reference** that persists in the pack. A bundle carries copies and
  * exists to be imported once, so the two are not variations on one idea.
  *

package/types/engine/bundles.d.mts

@@ -8,7 +8,7 @@
  * the first.
  *
  * A **folder** document is skipped. It is emitted into every pack that holds
- * something filed in it (#257), so it is not one pack's document and has no
+ * something filed in it, so it is not one pack's document and has no
  * single note behind it; a bundle that wants folders is a question this pass
  * refuses rather than guesses at — see {@link Bundles#resolveAddress}.
  *
@@ -20,6 +20,15 @@
  *   pack, which reordering cannot fix.
  */
 export function loadBundleSources(sourceDirs: Readonly<Record<string, readonly string[]>>): Map<string, object>;
+/**
+ * Adventure pack compiler.
+ *
+ * Walks the content tree and compiles every `type: bundle` note into one
+ * Adventure per system, holding **copies** of the compiled documents its
+ * `contents` addresses name. Reading other passes' output is what
+ * {@link Bundles.readsPackOutputOf} declares, and what the generator orders the
+ * compile by.
+ */
 export class Bundles extends BasePackCompiler {
     /**
      * @param {object} options - As {@link BasePackCompiler}, plus:

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

@@ -94,12 +94,12 @@ export function matchAllOutsideCode(markdown: string, pattern: RegExp, options?:
  * **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
+ * its examples are exactly the input a looser rule mangles. 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
+ * block — the documented "fences of any length" case — leaked its
  * contents.
  *
  * @param {string} body - The markdown body.
@@ -114,7 +114,7 @@ export function protectCode(body: string, transform: (masked: string) => string)
  * 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
+ * `[[0]]` inside a fence being turned into a link, and it depended on
  * the surrounding literal's shape (`[[1,2],[3,4]]` survived), so the corruption
  * looked arbitrary.
  *

package/types/engine/compendiums.d.mts

@@ -6,7 +6,7 @@
  * @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).
+ *     compiles a package other than this repository's.
  * @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
@@ -15,10 +15,10 @@
  * @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
+ * — 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
+ *     Level. 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}.

package/types/engine/compile-corpus.d.mts

@@ -4,7 +4,7 @@
  * @param {object} opts - Options.
  * @param {string} opts.contentBase - Root of the content tree.
  * @param {readonly string[]} opts.skipDirectories - The scope, stated by the
- *   caller as every corpus read requires (#243).
+ *   caller as every corpus read requires.
  * @param {object} opts.router - The pack router this compile resolved. Shared
  *   by every pass, which is what makes one link index correct for all of them.
  * @param {object} [opts.config] - The resolved configuration.