@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/item-registry.mjs

@@ -17,15 +17,15 @@
  *
  * Both are read from the one resolved configuration, so they are literally the
  * same object's keys and values: a type cannot be whitelisted for compilation
- * without the builder that compiles it, which is the guarantee #1504 exists
- * for. Where a consumer declares **several** registries, one per system (#58),
+ * without the builder that compiles it, which is the guarantee this exists
+ * for. Where a consumer declares **several** registries, one per system,
  * the vocabulary is their union and every lookup below takes the system that is
  * asking — a type both systems declare has two builders, and answering with one
  * of them because it was declared first is the silent-wrong-output failure this
  * package spends its time removing. The Item compiler dispatches through {@link itemBuilder}, so the table a
  * consumer configured is the table its notes compile with — the whitelist and
- * the dispatch used to come from different places, and a consumer supplying its
- * own registry got the types it asked for and the builders it did not (#1563).
+ * the dispatch would otherwise come from different places, and a consumer supplying its
+ * own registry got the types it asked for and the builders it did not.
  *
  * **The registry itself is a consumer's, and stays a leaf.** SoHL's lives in
  * `@heroiclands/package-build/sohl/item-builders`; the consumer names it in
@@ -52,9 +52,9 @@ import { resolveImg } from "./helpers.mjs";
  * **Derived, never authored.** These are the keys of the consuming
  * repository's `itemBuilders` registry, so the whitelist and the builder table
  * are the same list and cannot drift apart. They already had: `trait` was
- * whitelisted long after the item type was retired (#651), with no builder
+ * whitelisted long after the item type was retired, with no builder
  * behind it, so every `type: trait` note passed the gate and then failed to
- * compile (#1504).
+ * compile.
  *
  * An accessor rather than a hoisted constant, so that importing this module
  * needs no configuration (#2).
@@ -73,7 +73,7 @@ export function itemTypes() {
  * two systems declare the type. So a contested type without a system **throws**
  * rather than resolving: the alternative is a document built by one system's
  * builder and stamped with another's, which is exactly the shape of defect the
- * document-subtype map exists to stop (#79).
+ * document-subtype map exists to stop.
  *
  * @param {string} what - What is being looked up, for the message.
  * @param {"itemBuilders"|"itemArt"|"itemFields"} table - Which table.
@@ -87,7 +87,7 @@ function lookup(what, table, type, system) {
     // The registry is keyed by the current spelling of a note type, and a note
     // still on a renamed one resolves through it unchanged. One place, because
     // every type-keyed table this module reaches — builders, art, fields — is
-    // indexed here (#78).
+    // indexed here.
     type = currentType(type);
     if (system !== undefined) {
         const perSystem = /** @type {Record<string, Record<string, unknown>>} */ (
@@ -112,7 +112,7 @@ function lookup(what, table, type, system) {
  *
  * Unreachable through the compiler — its whitelist *is* this registry's keys —
  * so a throw here means a caller invented a type. It names the type rather than
- * failing as an anonymous `is not a function` (#1504).
+ * failing as an anonymous `is not a function`.
  *
  * @param {string} type - The note's `type` frontmatter.
  * @param {string} [system] - The system compiling it, where a build declares
@@ -139,9 +139,9 @@ export function itemBuilder(type, system) {
  * The frontmatter fields a type's registry entry declares, if any.
  *
  * Sparse by design: a type whose entry declares none compiles normally and is
- * simply undocumented (#22). What reads it is the `system`-block passthrough,
+ * simply undocumented. What reads it is the `system`-block passthrough,
  * which has to know which paths a declared field already writes before it
- * writes the rest (#58).
+ * writes the rest.
  *
  * @param {string} type - The item type.
  * @param {string} [system] - The system compiling it, where a build declares
@@ -160,7 +160,7 @@ export function itemFields(type, system) {
  *
  * Read from the consuming repository's `itemBuilders` registry, the same place
  * the type itself is declared, so a consumer's own type can bring art a
- * SoHL-owned table could never hold. Art used to be looked up in
+ * SoHL-owned table could never hold. Art is not looked up in
  * `sohl/default-item-art.mjs` instead: a type was configurable while its
  * default art was not, so a second consumer's items compiled only if every one
  * of its notes set `img:` (#7).
@@ -195,7 +195,7 @@ export function itemArt(type, system) {
         );
     }
     // `art` is non-empty by the guard above, so the translation never returns
-    // the `null` a note's unset `img:` would (#218); the coalesce states that
+    // the `null` a note's unset `img:` would; the coalesce states that
     // rather than leaving the declared `string` return a half-truth.
     return resolveImg(art) ?? "";
 }

package/engine/journals.mjs

@@ -28,13 +28,13 @@
  * keeps only a pointer to it. See `item-docs.mjs` for why, and for the ids the
  * two passes agree on. A macro note's `{#script}` page is compiled here like
  * any other: the macro pass reads the same page independently, and withholds
- * nothing from the journal (#1514).
+ * nothing from the journal.
  *
  * Folder placement is identical to the items pack: `sohl.packFolder` in
  * frontmatter is a folder **note's address**, resolved through the shared
- * address index by the constructor's `folderResolver` (#255, #260). A folder
+ * address index by the constructor's `folderResolver`. A folder
  * materialises in every pack holding a document that names it, so a journals
- * pack needs to declare nothing (#257) — which is what stopped this pass
+ * pack needs to declare nothing — which is what stopped this pass
  * filing documentation into folders its own pack had never heard of. A
  * documentation entry reuses its document's folder verbatim.
  *
@@ -43,7 +43,7 @@
  *
  * The walk itself — filtering by type, expanding tables, converting
  * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
- * states only what makes this pass its own (#1509).
+ * states only what makes this pass its own.
  */
 
 import log from "loglevel";
@@ -141,7 +141,7 @@ export function splitPages(body, leadName = "Introduction") {
  * on an identity alone:
  *
  * - **An anchor**, declared twice, has always collided.
- * - **A name**, repeated among the unanchored pages, collides since #268 took
+ * - **A name**, repeated among the unanchored pages, collides once
  *   the index out of the key. `MD024` with `siblings_only` already makes two
  *   sibling headings with the same text a lint error, so this is the same rule
  *   restated where the build can enforce it — a lint is a separate command, and
@@ -199,7 +199,7 @@ export function assertUniqueAnchors(rawPages, noteName) {
  * doc's first page without having compiled it (see
  * {@link sohl.utils.packs.itemDocPointer}).
  *
- * **It takes no index** (#268). A page used to be keyed by position *and* name,
+ * **It takes no index**. Keying a page by position *and* name,
  * so inserting a heading renumbered every page after it and a re-import created
  * new pages beside the old ones — while nothing about those pages had changed.
  * The anchored case above never took one, and is the shape this now shares.
@@ -275,7 +275,7 @@ export function buildPages(rawPages, entryId, noteName) {
  * @param {object} [params.stats] - The `_stats` block to stamp. Passed by the
  *   caller because it is a property of the *pack* being written, not of the
  *   entry: a module may ship the same content for two systems, and each pack's
- *   documents record the system version they were built against (#48). A
+ *   documents record the system version they were built against. A
  *   caller with no pack in hand gets the package-wide block.
  * @returns {object} The JournalEntry document, keyed for the pack.
  */
@@ -317,7 +317,7 @@ export class Journals extends BasePackCompiler {
     /**
      * **None.** A JournalEntry has no artwork — no `img` property, and no
      * nested place for one — so a note whose whole document is prose has
-     * nowhere to put an authored path (#349).
+     * nowhere to put an authored path.
      *
      * The emptiness is the declaration, in the sense `JOURNAL_ONLY_FIELDS` is:
      * it is what separates a pass that emits no art from one that has simply
@@ -338,13 +338,13 @@ export class Journals extends BasePackCompiler {
 
     /**
      * Journal notes, plus every doc-carrying note — an item's prose is its
-     * documentation, so it compiles here and the item keeps a pointer to it
-     * (#1348); a macro's is the same arrangement (#1514), and so is a map's,
-     * whose prose is the place description its pins point at (#1525).
+     * documentation, so it compiles here and the item keeps a pointer to it;
+     * a macro's is the same arrangement, and so is a map's,
+     * whose prose is the place description its pins point at.
      *
      * Two memberships, and they mean different things.
      * {@link module:engine/ids.JOURNAL_TYPES} is the types whose whole document
-     * *is* a journal — `doc`, and since #241 `place`, `lore` and `scenario`,
+     * *is* a journal — `doc`, `place`, `lore` and `scenario`,
      * which the content format has always described and nothing compiled.
      * {@link sohl.utils.packs.docEntryTypes}, read through
      * {@link sohl.utils.packs.hasDocEntry}, is the types whose prose becomes a
@@ -383,7 +383,7 @@ export class Journals extends BasePackCompiler {
      * the items pass wrote resolves to it (see
      * {@link sohl.utils.packs.itemDocPointer}). A macro's `{#script}` page is
      * compiled here like any other; nothing is withheld from the journal
-     * because the macro pass also reads it (#1514).
+     * because the macro pass also reads it.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} markdown - The body, tables expanded and wikilinks
@@ -404,12 +404,12 @@ export class Journals extends BasePackCompiler {
         // resolving it *here* is what cures the defect this comment used to
         // describe. A folder note has one definition and one address, so the
         // journals pack materialises the very folder the items pack does, by
-        // the same id (#257). There is no second folder file left to disagree
+        // the same id. There is no second folder file left to disagree
         // with the first, and so no arrangement to assume: the mirroring
         // failure is unrepresentable rather than merely reported.
         //
         // The id spelling used to cross packs verbatim here, on the assumption
-        // both declared it — the arrangement #260 retires with the YAML.
+        // both declared it — the arrangement retired with the YAML.
         const { value: authoredFolder } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress: true });
 

package/engine/macros.mjs

@@ -46,7 +46,7 @@
  *
  * The walk itself — filtering by type, expanding tables, converting
  * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
- * states only what makes this pass its own (#1509).
+ * states only what makes this pass its own.
  */
 
 import log from "loglevel";
@@ -261,7 +261,7 @@ export function buildMacroEntry(fm, { command, folder = null, stats = defaultSta
         // into chat instead of running.
         type: resolveMacroType(fm, name),
         author: null,
-        // Nullish, not `||` (#218): a macro note that names no art gets the
+        // Nullish, not `||`: a macro note that names no art gets the
         // shared default, one that writes `img: ""` ships blank on purpose.
         img: resolveImg(fm.img) ?? DEFAULT_MACRO_IMG,
         scope: resolveMacroScope(fm, name),
@@ -326,7 +326,7 @@ export class Macros extends BasePackCompiler {
             folder: this.folderResolver(folderField(fm).value, {
                 isAddress: folderField(fm).isAddress,
             }),
-            // This pack's system, not the package-wide one (#48).
+            // This pack's system, not the package-wide one.
             stats: this.stats,
         });
     }

package/engine/map-notes.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * **Map notes** — the markdown → Foundry `Scene` translation (issue #1525).
+ * **Map notes** — the markdown → Foundry `Scene` translation.
  *
  * A map note carries an *essence*: a curated, hand-owned subset of what a Scene
  * record holds, exactly as a weapon note carries a weapon's essence rather than
@@ -57,7 +57,7 @@ import { compendiumUuid, makeId, MAP_SUBTYPES, MAP_TYPES } from "./ids.mjs";
 // exactly one the bridge forwards.
 import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.mjs";
 // A map's background art is `img`, as every other note type's art is. `image`,
-// the spelling a map alone once used, is retired and gone (#149).
+// the spelling a map alone once used, is retired and gone.
 import { sohlField } from "./frontmatter.mjs";
 
 /* -------------------------------------------------------------------- */
@@ -113,7 +113,7 @@ export const MAP_SUBTYPE_PROFILES = Object.freeze({
 /**
  * The canvas profile for a map subType.
  *
- * Keyed on the subType rather than the type since #174: every map note is
+ * Keyed on the subType rather than the type: every map note is
  * `type: map`, and which canvas it derives is the one thing the three
  * spellings ever decided.
  *
@@ -556,7 +556,7 @@ const SCROLLING_TEXT_EVENTS = Object.freeze([
  * @type {Readonly<Record<string, {fields: string[], events?: readonly string[]}>>}
  */
 const BEHAVIOR_SPECS = Object.freeze({
-    // The SoHL bridge (#593).
+    // The SoHL bridge.
     trigger: { fields: ["events", "action"], events: CURATED_REGION_EVENTS },
     adjustDarknessLevel: { fields: ["mode", "modifier"] },
     applyActiveEffect: { fields: ["effects"] },
@@ -590,7 +590,7 @@ const BEHAVIOR_SPECS = Object.freeze({
 });
 
 /**
- * The behaviour types a map note may carry (issue #1525, v1).
+ * The behaviour types a map note may carry (v1).
  *
  * @type {ReadonlySet<string>}
  */
@@ -619,7 +619,7 @@ export const BANNED_REGION_BEHAVIOR_TYPES = Object.freeze(
         [
             "executeMacro",
             "its target Macro must ship in the same Adventure to resolve, and " +
-                "Adventure-bundled macros are not built yet (deferred from #1525).",
+                "Adventure-bundled macros are not built yet.",
         ],
     ]),
 );

package/engine/metadata-index.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The published content index — the artifact packages exchange addresses
- * through (#239).
+ * through.
  *
  * **A package publishes its own index; a consumer fetches the ones it depends
  * on.** That is the whole mechanism, and it replaces a vendored link manifest
@@ -94,7 +94,7 @@ export function metadataFileName(pkg) {
  * `itemCatalog: true` says a dependency supplies *items*; citing its
  * *addresses* is a separate edge, and a package may have either without the
  * other. `harn-ensemble` cites no foreign address and carries 324,016 embedded
- * item references (`HeroicLands/harn-ensemble#42`); a package citing addresses
+ * item references; a package citing addresses
  * and needing no items is the mirror of it. Gating the index on the catalogue
  * flag would serve neither.
  *
@@ -182,7 +182,7 @@ export function cachedMetadataFiles(config) {
  * The same fetched indexes, each paired with the package that published it.
  *
  * The id is what a SQL content table addresses a dependency's notes by
- * (`FROM sohl.notes`, #246), so the pairing has to survive the lookup —
+ * (`FROM sohl.notes`), so the pairing has to survive the lookup —
  * {@link cachedMetadataFiles} drops it, and a caller reconstructing the id from
  * the file name would be parsing a path to recover something the declaration
  * already stated.
@@ -230,7 +230,7 @@ export function cachedMetadataIndexes(config) {
  * rather than being written once per cache. Two copies would be two chances to
  * get it wrong, and the wrong answer is invisible: every cached version is a
  * complete, stamped, perfectly valid artifact, so picking the older one reports
- * nothing and simply resolves against stale data (#272).
+ * nothing and simply resolves against stale data.
  *
  * @param {string[]} dirs - Complete cache directories, named `<id>@<version>`.
  * @returns {string} The newest one.
@@ -426,7 +426,7 @@ export function cachedIndexPath(config, pkg) {
  * therefore reported against the index, once, instead of once per citing note.
  *
  * The realistic cause is a version skew: a dependency released before the
- * address grammar gained its `<system>` segment (#59) ships three-segment keys.
+ * address grammar gained its `<system>` segment ships three-segment keys.
  * Re-fetching after that dependency releases is the fix.
  *
  * @param {Map<string, object>} foreignIndex - The resolved foreign index.

package/engine/note-claims.mjs

@@ -13,8 +13,8 @@
 
 /**
  * **Which note types a configuration compiles at all** — the finding for a note
- * whose type nothing claims (#146), and the one for a note that loses a
- * document while the rest of it compiles (#152).
+ * whose type nothing claims, and the one for a note that loses a
+ * document while the rest of it compiles.
  *
  * Every compile pass answers one question about a note: _is this mine?_ A note
  * every pass answers "no" to is skipped as quietly as the thousands that
@@ -29,7 +29,7 @@
  *
  * This module supplies the missing complaint, and it is asked **once per
  * build** rather than once per pass. That is not an optimisation: it is the
- * only place the question can be answered correctly. #79's rule is that a
+ * only place the question can be answered correctly. The rule is that a
  * markdown type with no mapping in a given system produces no document *for
  * that system*, silently and correctly — so a per-pass check would report
  * `armorlocation` against every system that does not map it, which is precisely
@@ -51,13 +51,13 @@
  * who invented a word. Collapsing the two would send `harn-ensemble` to correct
  * five perfectly good notes.
  *
- * ## The partial case is a third condition, and it was invisible (#152)
+ * ## The partial case is a third condition, and it was invisible
  *
  * The table above asks whether a note is compiled *at all*, and a note that
  * compiles one of its two documents answers yes. But a note produces more than
  * one document as a matter of course — an item note an Item and the
  * JournalEntry its prose becomes, a map note a Scene and a JournalEntry, an
- * actor note an Actor and a JournalEntry since #337 — so a configuration
+ * actor note an Actor and a JournalEntry — so a configuration
  * missing a pack for *one* of them dropped that document while the rest of the
  * note compiled into a pack that does exist. The build succeeded and shipped
  * half of what was written.
@@ -85,7 +85,7 @@
 
 import { assertSuppliedCorpus, parseMarkdownFile } from "./helpers.mjs";
 // The record accessors only: this module is imported by the content index, so
-// importing the index back would close a cycle (#243).
+// importing the index back would close a cycle.
 import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
 import { JOURNAL_TYPES, MAP_TYPES, PACK_BY_TYPE, RETIRED_TYPES, currentType } from "./ids.mjs";
 import { itemTypes } from "./item-registry.mjs";
@@ -124,11 +124,11 @@ export const NEVER_PACKED_TYPES = Object.freeze(new Set([HOMEPAGE_TYPE]));
  * correctly and is worthless, because the configured vocabulary is *derived
  * from the routing*. Take a type's route away and it leaves the vocabulary too,
  * so the inference excuses precisely the mistake it was meant to catch. That is
- * not hypothetical: it is #241, where `place`, `lore` and `scenario` were
- * declared, validated and unrouted, and every gate reported success until a
- * downstream repository failed on 450 notes.
+ * not hypothetical: `place`, `lore` and `scenario` were declared, validated
+ * and unrouted, and every gate reported success until a downstream repository
+ * failed on the notes carrying them.
  *
- * A type leaves this set when it is implemented, the way `bundle` did in #259.
+ * A type leaves this set when it is implemented.
  * The membership is asserted, so it cannot be forgotten in either direction.
  *
  * @type {ReadonlySet<string>}
@@ -141,7 +141,7 @@ export const UNIMPLEMENTED_TYPES = Object.freeze(new Set(["vehicle"]));
  * A folder is the only one, and it is not unclaimed: it compiles to a real
  * `Folder` document. What it has no answer to is *which* pack claims it, because
  * that is not a property of the note — a folder materialises in every pack
- * holding a document that references it, and its ancestors with it (#257). So
+ * holding a document that references it, and its ancestors with it. So
  * it is exempt from the claim check for the opposite reason a homepage is:
  * a homepage is in no pack, and a folder may be in several.
  *
@@ -153,7 +153,7 @@ export const DERIVED_PACKED_TYPES = Object.freeze(new Set([FOLDER_TYPE]));
  * The note-type → document-subtype maps this toolchain ships.
  *
  * Declared in {@link module:engine/subtype-registry} and re-exported here,
- * where it has always been read from. It moved to a leaf in #270 so that
+ * where it is read from. It sits on a leaf so that
  * `helpers.mjs` could reach it: this module imports `walkMarkdownTree` from
  * there, so a dependency the other way would have closed a cycle.
  *
@@ -232,7 +232,7 @@ function mappingSystems(maps, type) {
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243). Defaults to the
+ *   compile and handed in — required, for the reason above. Defaults to the
  *   configured registries and the systems this toolchain ships.
  * @returns {ReadonlySet<string>} The note types such a pass would claim.
  */
@@ -263,8 +263,8 @@ export function noteTypesClaimedBy(docType, sources) {
             return Object.freeze(new Set(["macro"]));
         case "Scene":
             return Object.freeze(new Set(MAP_TYPES));
-        // The bundles pass: an Adventure is what a `bundle` note compiles into
-        // (#259). A **prebuilt** Adventure pack still claims nothing —
+        // The bundles pass: an Adventure is what a `bundle` note compiles into.
+        // A **prebuilt** Adventure pack still claims nothing —
         // {@link claimedNoteTypes} passes over it, because no note is routed
         // into a pack whose JSON is checked in rather than compiled.
         case "Adventure":
@@ -297,13 +297,13 @@ export const CLAIMABLE_DOCUMENT_TYPES = Object.freeze([
 ]);
 
 /**
- * Every document class a note of one type compiles into (#152).
+ * Every document class a note of one type compiles into.
  *
  * **A note produces more than one document, and that is the ordinary case.** An
  * item note compiles an Item *and* the JournalEntry its prose becomes; a map
- * note a Scene and a JournalEntry; since #337 an actor note an Actor and a
+ * note a Scene and a JournalEntry; an actor note an Actor and a
  * JournalEntry too. {@link claimedNoteTypes} unions over the configured packs
- * and so answers "is this note compiled *at all*", which is #146's question and
+ * and so answers "is this note compiled *at all*", and
  * cannot see a note that compiles one of its two documents and loses the other.
  *
  * Asked of the **claim table** rather than of a list of its own, so the set of
@@ -314,7 +314,7 @@ export const CLAIMABLE_DOCUMENT_TYPES = Object.freeze([
  * **Union across systems, never per system.** A type one system maps and
  * another does not appears once, because the `Item` and `Actor` rows already
  * fold the maps together — so this cannot report a document class a system
- * deliberately declines to produce, which is the silence #79 requires.
+ * deliberately declines to produce, which is the silence the rule requires.
  *
  * ## The JournalEntry row is the one that is per *note*
  *
@@ -361,7 +361,7 @@ export function documentClassesFor(type, sources, { hasProse } = {}) {
 
 /**
  * Whether a note carries a body at all — the condition `Journals.skipNote`
- * applies, asked from the outside (#152).
+ * applies, asked from the outside.
  *
  * Read from the file rather than from the index record, because a record
  * carries a note's frontmatter and its derived address and not its prose. The
@@ -388,13 +388,14 @@ function noteHasProse(absPath) {
  *
  * The union across the configured pack list, so a type claimed by any one pack
  * is claimed — which is what keeps a type deliberately unmapped for one system,
- * and claimed for another, silent (#79).
+ * and claimed for another, silent.
  *
  * **A prebuilt pack claims nothing.** Its per-document JSON is checked in
  * rather than compiled, so it has no pass and no note is routed into one —
  * which `content-config.mjs` already states by refusing `default: true`
  * alongside `prebuilt`. Counting it would tell an author their note is claimed
- * by a pack that will never look at it. Before #259 the point could not arise:
+ * by a pack that will never look at it. With no unimplemented type declared,
+ * the point cannot arise:
  * the only prebuilt pack in the wild is `harn-adventures`'s Adventure pack, and
  * no compiler was registered for that document type, so the row answered for
  * nothing whatever it was asked. Now one is.
@@ -404,7 +405,7 @@ function noteHasProse(absPath) {
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243).
+ *   compile and handed in — required, for the reason above.
  * @returns {ReadonlySet<string>} The claimed note types.
  */
 export function claimedNoteTypes(config = loadPackConfig(), sources) {
@@ -428,7 +429,7 @@ export function claimedNoteTypes(config = loadPackConfig(), sources) {
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243).
+ *   compile and handed in — required, for the reason above.
  * @returns {ReadonlySet<string>} The vocabulary.
  */
 export function noteTypeVocabulary(sources) {
@@ -483,7 +484,7 @@ function article(word) {
 function configurationMessage(type, config, sources) {
     // Every table below is keyed by the current spelling of a note type; the
     // message quotes the authored one, which is what the reader has in front of
-    // them (#78).
+    // them.
     const current = currentType(type);
     const documents = mappedDocuments(sources.maps, type);
     if (!documents.length && sources.itemTypes.has(current)) documents.push("Item");
@@ -550,10 +551,10 @@ function specifiedMessage(type) {
 }
 
 /**
- * The **partial** finding: the note compiles, and one of its documents does not
- * (#152).
+ * The **partial** finding: the note compiles, and one of its documents does not.
  *
- * #146's question is "does anything claim this note", and the answer is yes —
+ * The unclaimed check asks "does anything claim this note", and the answer is
+ * yes —
  * which is exactly why this went unreported. A note produces more than one
  * document, and a configuration missing a pack for one of them drops that
  * document while the rest of the note compiles into a pack that does exist. The
@@ -562,7 +563,8 @@ function specifiedMessage(type) {
  *
  * The message names the note, the document class with no pack, and the class
  * that *did* compile — the last because it is what distinguishes this from
- * #146's finding at a glance: the note is not unclaimed, it is half-claimed, and
+ * the unclaimed finding at a glance: the note is not unclaimed, it is
+ * half-claimed, and
  * the fix is a pack rather than a `type:`.
  *
  * @param {string} type - The note's declared `type`.
@@ -618,7 +620,7 @@ function authoringMessage(type) {
  * @param {ClaimSources} [sources] - What to answer from.
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
- *   compile and handed in — required, for the reason above (#243).
+ *   compile and handed in — required, for the reason above.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
@@ -632,7 +634,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
     // and no note is routed into it.
     const configured = new Set((config.packs ?? []).filter((p) => !p.prebuilt).map((p) => p.type));
 
-    // The corpus this compile derived once (#243), required rather than
+    // The corpus this compile derived once, required rather than
     // derived here: this module is imported *by* the content index, so it
     // could not derive one without closing a cycle — and the caller that wants
     // this answer is running a compile and already holds it.
@@ -651,13 +653,13 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // A **renamed** spelling is a live type, not an unknown one: it resolves
         // to the same row, the same registry entry and the same pack. So the
         // claim is asked of the current spelling while the finding quotes the
-        // authored one (#78). The rename itself is reported by the frontmatter
+        // authored one. The rename itself is reported by the frontmatter
         // lint, which can say what to write instead.
         const current = currentType(type);
 
         // Every document this note produces, against the classes this
         // configuration has a pack for. Three outcomes, and the middle one is
-        // #152's — it was invisible while the question was only "is anything
+        // the half-claimed one — invisible while the question is only "is anything
         // claiming this note", because the answer there is yes.
         const produces = documentClassesFor(current, resolved, {
             // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
@@ -673,7 +675,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
 
         // Some do and some do not: the note compiles, and one of its documents
         // is dropped in silence. A type nothing produces at all falls past this
-        // to the #146 messages below, where `produces` being empty is itself
+        // to the unclaimed messages below, where `produces` being empty is itself
         // part of the answer.
         if (compiled.length) {
             findings.push({

package/engine/note-ids.mjs

@@ -20,7 +20,7 @@
  * says everything the id said, is readable, and is the identity `content-lint`
  * already guards: a duplicate address is a build error, while a duplicate `id`
  * was checked nowhere. So the derived id inherits a guarantee, where the
- * authored one had none (#270).
+ * authored one had none.
  *
  * **An authored `id` always wins.** That is the pattern the map compiler
  * already uses and documents — `regionDocId(sceneId, key, pinned)` returns
@@ -73,15 +73,15 @@ function text(value) {
  * the rule but an application of it.** A `Folder` is a document of its own
  * class, and its id is hashed under the `folder` namespace so that a folder and
  * an item sharing a shortcode cannot derive one id — a collision Foundry would
- * not report, since it keys folders and documents in separate collections
- * (#258). So the answer for a folder comes from
+ * not report, since it keys folders and documents in separate collections.
+ * So the answer for a folder comes from
  * {@link module:engine/folder-notes.folderDocId}, the pass that emits those
  * documents, rather than from a second derivation here.
  *
  * That this function ever answered differently was invisible from inside a
  * build — no pass reads a folder's id from here — and surfaced only in the
  * content index, which is read from outside and had no way to be checked
- * against what shipped (#310).
+ * against what shipped.
  *
  * Returns `undefined` for a file with **no address** — no `type`, or no
  * `shortcode`. Such a file is not an addressable note, so it has no document
@@ -94,7 +94,7 @@ function text(value) {
  * @param {object|null|undefined} fm - Parsed frontmatter.
  * @param {object} [opts]
  * @param {string} [opts.pkg] - The owning content package. Defaults to the
- *   configured one, which is the only package a tree's notes belong to (#56).
+ *   configured one, which is the only package a tree's notes belong to.
  * @param {readonly object[]} [opts.maps] - The document-subtype maps, which
  *   decide the address's `<system>` segment.
  * @returns {string|undefined} The document's `_id`, or `undefined` when the

package/engine/note-package.mjs

@@ -19,10 +19,10 @@
  * single-sourced in the repository that ships it — so the package is a property
  * of the *repository*, not of the note, and no note declares it.
  *
- * It used to be a property of the note, and a **selector**: the compile loop
+ * It is not a property of the note, and not a **selector**: as one, the compile loop
  * read `package:` out of frontmatter and skipped anything that did not match
- * the configured value. That is the defect this module exists to remove
- * (#56). The skip was silent and it was bucketed as "belongs to another pass",
+ * the configured value. That is the defect this module exists to remove.
+ * The skip was silent and it was bucketed as "belongs to another pass",
  * so a tree whose notes named a package no configuration answered to compiled
  * **zero notes and exited 0** — which is exactly the state the un-migrated
  * `hm-loc-*` / `hm-adv-*` repositories are in today.
@@ -64,7 +64,7 @@ import { locateFrontmatterKey } from "./retired-fields.mjs";
  * field, so a collection note that scopes itself with `WHERE … and package =
  * "sohl"` would match nothing now that the field is gone, and would render an
  * **empty table** in silence. Supplying the derived value here is what kept the
- * sweep mechanical rather than a trap (#56) — and a query that never mentions
+ * sweep mechanical rather than a trap — and a query that never mentions
  * `package` is unaffected either way.
  *
  * The frontmatter is copied rather than written into: it is the note's own

package/engine/note-renames.mjs

@@ -12,12 +12,12 @@
  */
 
 /**
- * The shortcodes a note declares it used to be published under (#278).
+ * The shortcodes a note declares it used to be published under.
  *
  * A package's `(type, shortcode)` addresses are a published interface, and
  * `addresses diff` reports what a build stopped publishing — telling a
  * **rename** from a **withdrawal** by matching document ids across two
- * releases. #270 removed the property that rested on. An id is now derived from
+ * releases. The property that rested on is gone: 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, the match finds
  * nothing, and a rename is reported as a withdrawal with no successor named.
@@ -52,7 +52,7 @@
  * **It is transient.** Once every baseline a build is compared against post-dates
  * the rename, the declaration has nothing left to say and may be deleted. That
  * is the difference from an `id:` pin, which is permanent, opaque, and a second
- * identity for a thing that already has one (#270).
+ * identity for a thing that already has one.
  *
  * **It is one key per note, at the top level, however many systems the note
  * compiles into.** A shortcode is the note's, not a system block's: a note