@heroiclands/package-build 20.3.1 → 20.5.0

package/engine/actor-compiler.mjs

@@ -13,14 +13,13 @@
 
 /**
  * **The Actor pass, for any system** — the parts of compiling a note into a
- * Foundry Actor that belong to the note format rather than to a game system
- * (#139).
+ * Foundry Actor that belong to the note format rather than to a game system.
  *
  * The whole of it lived in `sohl/actors.mjs`, where the system-specific facts
- * were already funnelled through one map (`static documentSubtypes`, added by
- * #79) and one block constant. A second system needs everything except the
- * shape of the `system` block itself, so that everything moved here and each
- * half declares what differs:
+ * were already funnelled through one map (`static documentSubtypes`) and one
+ * block constant. A second system needs everything except the shape of the
+ * `system` block itself, so all of it lives here and each half declares what
+ * differs:
  *
  * | stated by the subclass | what it decides |
  * | --- | --- |
@@ -35,7 +34,7 @@
  * - **Reference translation.** A being addresses its embedded items in the
  *   *note* vocabulary and the catalogue is keyed in the *document's*, so
  *   {@link SystemActorCompiler#embeddedSubtype} translates each reference
- *   forward through this system's map before the lookup (#140).
+ *   forward through this system's map before the lookup.
  * - **Embedding.** Merging a note's overlay onto a catalogue entry, deriving a
  *   stable embedded id from the owning actor and the address, and re-keying the
  *   embedded document and its effects for the LevelDB flattening.
@@ -60,15 +59,15 @@ import { BasePackCompiler } from "./base-compiler.mjs";
 import { contentPackage } from "./content-package.mjs";
 // Which Foundry Actor subtype a note's `type` compiles into, and which note
 // types are actors at all. Looked up in the system's declared map, never
-// inferred from the type itself (#79).
+// inferred from the type itself.
 import { mapsNoteType, noteTypesFor, referencedSubtype } from "./document-subtypes.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 // An `items:` entry's `system:` overlay is merged verbatim, so it reaches the
-// document by a path no field declaration sits on — including, until #330, the
+// document by a path no field declaration sits on — including the
 // fields the document is supposed to write for itself in play.
 import { itemFields } from "./item-registry.mjs";
 import { runtimeOnlyIn, runtimeOnlyMessage } from "./runtime-only-fields.mjs";
-// A `model:` is an address, read by the same grammar every wikilink is (#336),
+// A `model:` is an address, read by the same grammar every wikilink is,
 // so an author writes one form and meets one set of messages.
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -132,7 +131,7 @@ export function deepMerge(base, overlay) {
  * 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`.
@@ -144,7 +143,7 @@ export function itemAddress(subType, shortcode) {
 
 /**
  * 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
@@ -174,11 +173,12 @@ export function packagedItemAddress(pkg, subType, shortcode) {
  * 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
@@ -229,13 +229,13 @@ export function embeddedIdentity(item) {
  * 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.
@@ -277,7 +277,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
     const shadowed = [];
     for (const itemsSourceDir of itemsSourceDirs) {
         if (!fs.existsSync(itemsSourceDir)) {
-            // The generator orders the actors pass after every Item pass (#73),
+            // The generator orders the actors pass after every Item pass,
             // so a whole-package build cannot reach this. What can is a run
             // restricted to this one pack, or a caller constructing the
             // compiler itself — neither of which reordering a pack list fixes,
@@ -321,13 +321,13 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             const { _key, ...rest } = doc;
             map.set(address, rest);
             // And under this package's own name, so a `model:` that names this
-            // package explicitly resolves to the same item (#334).
+            // package explicitly resolves to the same item.
             map.set(catalogueKey(doc.type, shortcode, contentPackage()), rest);
         }
     }
     for (const foreignEntry of foreignSourceDirs) {
         // Each dependency's directory arrives with the package that published
-        // it (#334), so a foreign template gets its own canonical address
+        // it, so a foreign template gets its own canonical address
         // rather than sharing the local address space.
         const foreignDir = typeof foreignEntry === "string" ? foreignEntry : foreignEntry.dir;
         const foreignPackage = typeof foreignEntry === "string" ? null : foreignEntry.package;
@@ -352,7 +352,7 @@ export function loadItemsMap(itemsSourceDirs, foreignSourceDirs = []) {
             // eslint-disable-next-line no-unused-vars
             const { _key, ...rest } = doc;
             // Its own package-qualified address, which a `model:` naming that
-            // package resolves through and nothing local can shadow (#334).
+            // package resolves through and nothing local can shadow.
             if (foreignPackage) {
                 map.set(catalogueKey(doc.type, shortcode, foreignPackage), rest);
             }
@@ -411,8 +411,8 @@ export class SystemActorCompiler extends BasePackCompiler {
      * because {@link SystemActorCompiler#resolveEmbedded} is called per entry
      * and has no note lifecycle of its own.
      *
-     * `frontmatter-lint.mjs` makes the same finding from frontmatter alone
-     * (#228), and this does not replace it — the lint is a separate command, so
+     * `frontmatter-lint.mjs` makes the same finding from frontmatter alone,
+     * and this does not replace it — the lint is a separate command, so
      * without a check here a colliding pair would compile to two documents with
      * one `_id` and reach the LevelDB packer as an opaque duplicate key.
      *
@@ -422,12 +422,12 @@ export class SystemActorCompiler extends BasePackCompiler {
 
     // An actor's embedded items are resolved against the *output* of the item
     // passes, so every Item pack compiles before this one. Declared rather than
-    // left to the order `packs:` happens to list (#73).
+    // left to the order `packs:` happens to list.
     static readsPackOutputOf = Object.freeze(["Item"]);
 
     /**
      * An Actor **is** a system's data, so this pack takes only notes carrying
-     * this system's block (#58).
+     * this system's block.
      */
     static requiresSystemBlock = true;
 
@@ -449,7 +449,7 @@ export class SystemActorCompiler extends BasePackCompiler {
 
     /**
      * 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.
      */
@@ -465,10 +465,10 @@ export class SystemActorCompiler extends BasePackCompiler {
         super(options);
         // Where the items passes wrote their JSON. Stated by the caller rather
         // than assumed to be this pack's sibling: the packs' locations are
-        // configuration, and a consumer may put them anywhere (#1508). Every
-        // Item pack, because a repository may ship more than one (#1566).
+        // configuration, and a consumer may put them anywhere. Every
+        // Item pack, because a repository may ship more than one.
         //
-        // **Optional, and empty is a legitimate package (#49).** This used to
+        // **Optional, and empty is a legitimate package.** This used to
         // throw unless at least one Item pack was declared, which asked a
         // package to declare the very thing it may exist not to have. An Item
         // pack is system-bound by construction — Foundry requires `system` on
@@ -560,7 +560,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
@@ -576,37 +576,10 @@ export class SystemActorCompiler extends BasePackCompiler {
         return referencedSubtype(this.documentSubtypes, type, "Item");
     }
 
-    /**
-     * Resolve one embedded item from a `(type, shortcode?, overlay)`
-     * descriptor. If `shortcode` is given, the predefined item is fetched
-     * from `itemsMap` and the overlay deep-merged on top. If absent, the
-     * 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
-     * every embedded id exactly where it was.
-     * Returns null if the descriptor cannot be resolved.
-     *
-     * @param {Map<string, object>} itemsMap - The predefined items, by address.
-     * @param {string} actorId - The owning actor's id, seeding embedded ids.
-     * @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 {string} indexKey - Where the reference sits, for a diagnostic.
-     *   It no longer reaches the id (#268) — it names the entry in a message.
-     * @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.
-     * @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
+     * 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
@@ -615,7 +588,7 @@ export class SystemActorCompiler extends BasePackCompiler {
      *
      * 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).
+     * template came from.
      *
      * @param {unknown} model - The authored value.
      * @param {number} index - The entry's position, for the message.
@@ -653,6 +626,36 @@ export class SystemActorCompiler extends BasePackCompiler {
         return { type: read.type, shortcode: read.shortcode, package: read.package ?? null };
     }
 
+    /**
+     * Resolve one embedded item from a `(type, shortcode?, overlay)`
+     * descriptor. If `shortcode` is given, the predefined item is fetched
+     * from `itemsMap` and the overlay deep-merged on top. If absent, the
+     * 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 leaves
+     * every embedded id exactly where it was.
+     * Returns null if the descriptor cannot be resolved.
+     *
+     * @param {Map<string, object>} itemsMap - The predefined items, by address.
+     * @param {string} actorId - The owning actor's id, seeding embedded ids.
+     * @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 {string} indexKey - Where the reference sits, for a diagnostic.
+     *   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.
+     */
     resolveEmbedded(
         itemsMap,
         actorId,
@@ -675,7 +678,7 @@ export class SystemActorCompiler extends BasePackCompiler {
             this.errorCount++;
             return null;
         }
-        // A `model:` may name the package its template comes from (#334). Where
+        // A `model:` may name the package its template comes from. Where
         // it does, the packaged address is used and nothing local can shadow
         // it; where it does not, the unqualified one is, and a local definition
         // still wins over a dependency's as it always has.
@@ -687,7 +690,7 @@ export class SystemActorCompiler extends BasePackCompiler {
 
         // The entry's `system:` overlay is merged verbatim, so it reaches the
         // document without passing a single field declaration — which left it
-        // the one position a runtime-only field stayed authorable at once #330
+        // the one position a runtime-only field would stay authorable at once
         // closed the item note's own. Asked of the **overlay** rather than of
         // the merged result: the template it merges onto is a compiled
         // document, which by then carries none, and a finding has to name what

package/engine/address-charset.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * 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
@@ -43,7 +43,7 @@
  * 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 —
@@ -55,10 +55,10 @@
  * `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/engine/address-diff.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Diffing a package's published item addresses against a released one (#66).
+ * Diffing a package's published item addresses against a released one.
  *
  * A package's `(type, shortcode)` addresses are a **published interface**.
  * Every satellite that declares `itemCatalog: true` assembles its beings out of
@@ -48,10 +48,10 @@
  * mean" from string similarity would be worse than saying nothing, because a
  * wrong one sends the reader to the wrong fix.
  *
- * **#270 narrowed that match, and a declaration is what makes up the
+ * **That match is narrow, and a declaration is what makes up the
  * difference.** The join rested on the id being independent of the shortcode: a
  * note authored its `_id`, so the `Tabri` → `Taburi` commit changed the
- * shortcode alone and left the id to join the two sides. Since #270 an id is
+ * shortcode alone and left the id to join the two sides. An id is
  * *derived from the canonical address*, which carries the shortcode — so
  * renaming a shortcode moves the id too, both sides of the join move together,
  * and the match finds nothing. It stays exact for a note that **pins** an `id`,
@@ -61,7 +61,7 @@
  * one.
  *
  * So an author who has just renamed a shortcode **says so**, with
- * `renamedFrom:` on the note that made the change (#278, and see
+ * `renamedFrom:` on the note that made the change (and see
  * `engine/note-renames.mjs`). That is neither a guess nor an identity match but
  * testimony from the only party that knows, and the diagnostic reports which of
  * the two it had rather than blending them — a reader can verify a matched id
@@ -74,7 +74,7 @@
  *
  * **Severity is decided per case.** A withdrawal is legitimate — content is
  * allowed to be retired — so it is reported and does not fail a build. A rename
- * is equally legitimate as a decision (#1397's charset rule forces some), which
+ * is equally legitimate as a decision (the charset rule forces some), which
  * is why it does not fail one either; what it must not do is happen in silence.
  * A caller that wants a gate passes `error` and treats any finding as one.
  *
@@ -91,7 +91,7 @@ import path from "node:path";
 import { formatDiagnostic, positionInFrontmatter } from "./diagnostics.mjs";
 import { positionOfLiteral } from "./diagnostics.mjs";
 import { assertStatedScope } from "./helpers.mjs";
-// The corpus, read from the one pass that derives it (#243). Nothing in the
+// The corpus, read from the one pass that derives it. Nothing in the
 // index's import graph reaches this module — only `bin/` imports it — so this
 // is a plain static import, as in the link checker.
 import { indexRecordsFor, isNoteRecord, noteFile } from "./content-index.mjs";
@@ -173,59 +173,19 @@ export function readItemAddresses(dirs) {
     return space;
 }
 
-/**
- * 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.
- * @returns {Map<string, {to: string, file: string, shortcode: string}>} Old
- *   address → the address the declaring note publishes at now, and that note.
- */
 /**
  * The corpus both reads below share, as content-index records.
  *
  * **One walk, not two.** `addresses diff` reads the tree twice — once for the
- * declarations and once to place its findings — and until #243 those were two
+ * declarations and once to place its findings — and those would otherwise be
+ * two
  * independent walks that each parsed every note. They are now one derivation,
  * shared: the caller derives the records and hands them to both, so the two
  * halves of a single command cannot disagree about which files the corpus is,
  * or about the ids in it.
  *
  * **The id is why it matters, and not only tidiness.** `noteFilesById` joins
- * tree-side ids against ids read out of the *compiled packs*. Since #270 an id
+ * tree-side ids against ids read out of the *compiled packs*. An id
  * is derived from the canonical address, whose first segment is the content
  * package — and the tree side used to derive it through `resolveNoteId(fm)`
  * with no package, which falls back to `contentPackage()` and so to whichever
@@ -257,6 +217,49 @@ function addressCorpus(contentBase, { skipDirectories, config, records, problems
     return indexRecordsFor({ contentBase, config, skipDirectories, problems });
 }
 
+/**
+ * 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,
     { skipDirectories, maps = KNOWN_DOCUMENT_SUBTYPE_MAPS, config, records, problems } = {},
@@ -315,7 +318,7 @@ export function declaredPredecessors(
  * @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"`.
@@ -393,6 +396,8 @@ export function diffItemAddresses(baseline, current, { baseline: label, predeces
  *   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, { skipDirectories, config, records, problems } = {}) {
@@ -431,7 +436,7 @@ export function noteFilesById(contentBase, { skipDirectories, config, records, p
  * 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}.
@@ -480,7 +485,7 @@ export function locateAddressFinding(finding, noteFiles) {
  * 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/engine/anchored-sections.mjs

@@ -19,7 +19,7 @@
  * `{#dossier}` and `{#spoilers}`. *Which field* each lands in is a system's
  * business — SoHL writes the first to an actor's `appearance`, HM3 to an
  * actor's and an item's `description` — but *finding* it is not, so the
- * extraction lives here where every compiler reaches it (#139).
+ * extraction lives here where every compiler reaches it.
  *
  * It was a pair of private functions inside the SoHL actors pass, which is
  * where the convention was first needed and not where it belongs: the anchors

package/engine/anchors.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The anchors a note declares on its headings — read in one place (#243).
+ * The anchors a note declares on its headings — read in one place.
  *
  * **A leaf, deliberately.** This is asked by the link checker, by the content
  * index, and by the builds that emit a link, and they cannot all import one