@heroiclands/package-build 20.3.1 → 20.5.0

package/engine/base-compiler.mjs

@@ -19,7 +19,7 @@
  * failed are the same in every pass. They were written out
  * once per pass — three times when this was filed, five by the time it landed —
  * so a fix to any of them had to be made everywhere, and the passes drifted
- * apart in exactly the places nobody was comparing (#1509).
+ * apart in exactly the places nobody was comparing.
  *
  * A pass now states only what makes it that pass:
  *
@@ -43,7 +43,7 @@
  * `selects` answers *which document type* a pass claims, and it is the same
  * answer for every pack of that type. Which **pack of that type** a claimed
  * note lands in is a second question, answered by the pack router from the
- * note's own `pack:` declaration (#1566) — so a subclass never has to know that
+ * note's own `pack:` declaration — so a subclass never has to know that
  * its type ships in more than one pack.
  *
  * **This is the extension point.** The pack list is data
@@ -74,7 +74,7 @@ import {
     statsForPack,
 } from "./helpers.mjs";
 // The record accessors only — see `engine/index-records.mjs` for why they live
-// apart from the index that builds them (#243).
+// apart from the index that builds them.
 import { isNoteRecord, noteFile } from "./index-records.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
@@ -98,7 +98,7 @@ import { locateFrontmatterKey } from "./retired-fields.mjs";
  * 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.
@@ -106,7 +106,7 @@ import { locateFrontmatterKey } from "./retired-fields.mjs";
  * @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.
  */
 
 /**
@@ -148,7 +148,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.
      *
@@ -165,7 +165,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
@@ -181,7 +181,7 @@ export class BasePackCompiler {
 
     /**
      * 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
@@ -212,7 +212,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.
@@ -237,7 +237,7 @@ export class BasePackCompiler {
     errorCount = 0;
 
     /**
-     * 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
@@ -301,13 +301,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,
@@ -347,7 +353,7 @@ export class BasePackCompiler {
             writable: false,
         });
         // The walk's scope, stated by whoever built this pass rather than
-        // resolved from the working directory (#243). Every walk this compiler
+        // resolved from the working directory. Every walk this compiler
         // makes — its own, the table corpus, the link index, the SQL tables —
         // uses this one answer.
         Object.defineProperty(this, "skipDirectories", {
@@ -360,14 +366,14 @@ export class BasePackCompiler {
         this.router = router;
         this.routingReporter = routingReporter;
         // The corpus this compile is running over, derived once by
-        // `generatePacksJson` and shared by every pass (#243). A pass that is
+        // `generatePacksJson` and shared by every pass. A pass that is
         // handed none derives its own in `prepare`, which is what a consumer
         // constructing one compiler directly does.
         this.corpus = corpus;
     }
 
     /**
-     * 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
@@ -410,8 +416,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
@@ -424,7 +429,7 @@ export class BasePackCompiler {
     eligibleFor(fm) {
         if (!this.constructor.requiresSystemBlock || !this.packSystem) return true;
         if (carriesSystemBlock(fm, this.packSystem)) return true;
-        // Another system's pack of this document type will claim it (#139). A
+        // Another system's pack of this document type will claim it. A
         // note carrying only `hm3:` routes here because this pack is the
         // *default* of its document type, and defaults are declared per type
         // rather than per system — but it is not an incomplete note, it is
@@ -446,7 +451,7 @@ export class BasePackCompiler {
 
     /**
      * 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
@@ -473,7 +478,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.
@@ -524,7 +529,7 @@ export class BasePackCompiler {
         // The corpus, and the three whole-tree derivations built over it. Every
         // one of them is a pure function of (tree, scope, router), which do not
         // vary between the passes of a single compile — so `generatePacksJson`
-        // derives them once and hands them to each pass (#243).
+        // derives them once and hands them to each pass.
         //
         // The measurement that motivated it: compiling `sohl` read every note
         // **20 times**, four per pass — this link index, the table corpus, the
@@ -580,14 +585,14 @@ export class BasePackCompiler {
             type: fm.type,
             id: fm.id,
             // Where this note is, so a link that resolves nowhere is reported
-            // at a position an author can open rather than by note name (#17).
+            // at a position an author can open rather than by note name.
             file: absPath,
             bodyLine,
             bodyColumn,
             lineMap,
             // A `[[#slug]]` self-link addresses the source note, which has no
             // entry in the index — so where its own documents landed has to
-            // travel with it (#1566).
+            // travel with it.
             pack: this.router?.resolveOrNull(fm, packForType(fm.type).docType),
             docPack: this.router?.resolveOrNull(fm, "JournalEntry"),
             index: this.linkIndex,
@@ -636,8 +641,7 @@ export class BasePackCompiler {
     }
 
     /**
-     * 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
@@ -657,8 +661,8 @@ export class BasePackCompiler {
      */
     reportUndeclaredSystemData(fm, block, documentType, subType) {
         const absPath = this.currentNote?.absPath;
-        // Whose schema, where a build has more than one system: this pack's
-        // (#139). `undefined` — a pack that declares no system — keeps the
+        // Whose schema, where a build has more than one system: this pack's.
+        // `undefined` — a pack that declares no system — keeps the
         // package-wide answer this always used.
         const findings = checkAuthoredSystemData(fm, {
             block,
@@ -676,7 +680,7 @@ export class BasePackCompiler {
 
     /**
      * 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
@@ -734,7 +738,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 —
@@ -859,7 +863,7 @@ export class BasePackCompiler {
         }
         if (stats.declined) {
             // Its own line, at error level: these are not skips, and burying
-            // them in the skipped tally is the defect (#56). Each one has
+            // them in the skipped tally is the defect. Each one has
             // already been named individually as a diagnostic.
             log.error(
                 `Declined ${stats.declined} note(s) — each named above, with ` +
@@ -892,7 +896,7 @@ export class BasePackCompiler {
         // refusal, because it *is* the same refusal: the index defers to
         // `assertNoDeclaredPackage` for a retired `package:`, which is the
         // check this loop makes a few lines further down. All that changed is
-        // which pass sees the note first (#243).
+        // which pass sees the note first.
         if (this.reportsCorpusProblems) {
             for (const problem of this.corpus.problems ?? []) {
                 stats.declined++;
@@ -911,7 +915,7 @@ export class BasePackCompiler {
         }
 
         // The corpus, from the index this compile derived once — not a walk of
-        // this pass's own (#243). Each note is then read for its **prose**: the
+        // this pass's own. Each note is then read for its **prose**: the
         // index carries what is *about* a note and deliberately not its text,
         // nor the `bodyLine`/`bodyColumn` a diagnostic needs, and this pass has
         // to have the body anyway. So the read is one this pass was already
@@ -922,7 +926,7 @@ export class BasePackCompiler {
             const absPath = noteFile(this.contentBase, record);
             const { frontmatter: fm, body, bodyLine, bodyColumn } = parseMarkdownFile(absPath);
             // Which note this pass is on, so anything it calls can report a
-            // position without every method having to be handed one (#17).
+            // position without every method having to be handed one.
             this.currentNote = { absPath, bodyLine, bodyColumn };
             // A file carrying no frontmatter at all is not a note.
             if (!fm) {
@@ -933,12 +937,12 @@ export class BasePackCompiler {
             // note is answered whichever pass would have claimed it — and
             // whatever the declared value says.
             //
-            // - `package:` (#56): a note's package is the repository's
+            // - `package:`: a note's package is the repository's
             //   configured one, so declaring it restates a constant.
-            // - `draft:` (#69): it excluded the note from the packs, the
+            // - `draft:`: it excluded the note from the packs, the
             //   manifest and the site, and no checker reported the links that
             //   left dangling.
-            // - `aliases:` (#180): it fed the alias index, which the bare
+            // - `aliases:`: it fed the alias index, which the bare
             //   `[[Alias]]` form was looked up in; the form is retired, so the
             //   list has no reader left. The nested `name.aliases` is a
             //   different field and is **not** refused — it is reserved, and
@@ -973,7 +977,7 @@ export class BasePackCompiler {
             }
             // The id this note's document is filed under: its authored `id`
             // if it pins one, otherwise the id derived from its canonical
-            // address (#270). Resolved for every note this pass claims, and
+            // address. Resolved for every note this pass claims, and
             // through the one function every other corpus reader calls — the
             // wikilink index, the content index and the Foundry-address pass
             // must all compute the id this pass compiles under, and none of
@@ -1021,7 +1025,7 @@ export class BasePackCompiler {
                     stats.skippedOther++;
                     continue;
                 }
-                // The type-specific half of the retired-field family (#330):
+                // The type-specific half of the retired-field family:
                 // what a note of *this* type may not write, which needs the
                 // type's own field declaration and so cannot be asked before
                 // `selects`. Counted as a declined note for the same reason
@@ -1048,7 +1052,7 @@ export class BasePackCompiler {
                 this.errorCount++;
                 // `position` is set by whatever failed if it knew where — an
                 // unresolved address, a bad table directive — so the report
-                // points at the line rather than at the note (#17).
+                // points at the line rather than at the note.
                 this.noteError(
                     `${this.noteLabel(fm)} failed to compile: ${err.message}`,
                     err.position,

package/engine/bundle-notes.mjs

@@ -21,9 +21,9 @@
  * 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.
  *
@@ -140,7 +140,7 @@ export function bareAddress(value) {
  * `### 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
@@ -269,7 +269,7 @@ export function buildAdventure({
         _id: id,
         _stats: stats,
         // The Foundry *collection* name, not the pack's: a pack directory may
-        // be called anything (#1566), and the key names the collection the
+        // be called anything, and the key names the collection the
         // record belongs to inside it.
         _key: `!adventures!${id}`,
     };

package/engine/bundles.mjs

@@ -13,11 +13,11 @@
 
 /**
  * Adventure pack compiler — `type: bundle` notes → Foundry `Adventure`
- * documents (#259).
+ * documents.
  *
- * The specification and the vocabulary landed in #263, which left the type
+ * The specification and the vocabulary leave the type
  * declared and uncompiled: authoring one said so, in as many words. This is the
- * pass, and the two decisions #263 recorded are settled here.
+ * pass, and the two decisions it records are settled here.
  *
  * **Which pack.** Not the `adventures` **companion**. The scenes pass already
  * writes one Adventure per pinned place into that pack, and a companion is
@@ -32,7 +32,7 @@
  * the router's rule for `pack:`, so there is one answer and not two. One note
  * can compile into two documents — an item and the JournalEntry its prose
  * became — and the second is bundled only when the note names it by its own
- * `doc…` address, which is the address that already exists for it (#1362).
+ * `doc…` address, which is the address that already exists for it.
  * Nothing is inferred: naming `miscgear-bowlcer` puts the *item* in the bundle
  * and not its description page.
  *
@@ -41,7 +41,7 @@
  * a reader of every other one, which it states in
  * {@link Bundles.readsPackOutputOf} rather than leaving to the order a
  * consumer happened to write its pack list in — the generator derives the
- * compile order from that declaration (#73).
+ * compile order from that declaration.
  *
  * **A pack's `system:` constrains what its Adventures may hold.** An
  * `Adventure` has no `system` field, so a bundle spanning two systems cannot be
@@ -83,7 +83,7 @@ import { readQualifier } from "./wikilinks.mjs";
  * 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}.
  *
@@ -119,6 +119,15 @@ export function loadBundleSources(sourceDirs) {
     return documents;
 }
 
+/**
+ * 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 {
     static id = "bundles";
     static label = "bundle";
@@ -126,7 +135,7 @@ export class Bundles extends BasePackCompiler {
     /**
      * Every document type a bundle can hold a copy of.
      *
-     * The declaration the generator orders passes by (#73): an Adventure holds
+     * The declaration the generator orders passes by: an Adventure holds
      * *compiled* documents, so every pass that produces one runs first. Stated
      * here, in the class that does the reading, rather than in each consuming
      * repository's pack list.
@@ -225,7 +234,7 @@ export class Bundles extends BasePackCompiler {
             throw new Error(
                 `bundle "${bundleName}" lists the folder "${address}". A ` +
                     `folder is not a member: it materialises in every pack ` +
-                    `holding something filed in it (#257), so it belongs to no ` +
+                    `holding something filed in it, so it belongs to no ` +
                     `one pack and there is no single copy to bundle. List the ` +
                     `documents instead`,
             );

package/engine/code-fences.mjs

@@ -18,7 +18,7 @@
  * 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.
  *
@@ -378,12 +378,12 @@ export function matchAllOutsideCode(markdown, pattern, 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.

package/engine/compendiums.mjs

@@ -25,13 +25,13 @@
  *
  * **This module has no import-time side effects.** It creates no directories,
  * reads no manifest, configures no logger, and parses no argv — every path and
- * pack list is a parameter, defaulted from the resolved build configuration
- * (#1508), which a caller may replace wholesale to compile another package's
+ * pack list is a parameter, defaulted from the resolved build configuration,
+ * which a caller may replace wholesale to compile another package's
  * tree. Those side effects belong to the command
  * line that drives it (`bin/build-compendiums.mjs`), so the library can be
  * imported by another repository's build, or by a test, without a stray
  * `build/` tree appearing or the shared `loglevel` singleton being
- * reconfigured (#1507). In particular, a *module* repository ships
+ * reconfigured. In particular, a *module* repository ships
  * `module.json` rather than `system.template.json`, so importing must not
  * depend on the latter existing.
  *
@@ -64,7 +64,7 @@ import { loadPackConfig } from "./pack-config.mjs";
  * @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
@@ -73,10 +73,10 @@ import { loadPackConfig } from "./pack-config.mjs";
  * @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}.
@@ -137,7 +137,7 @@ export async function compilePacks({
         // LevelDB key. Nothing in Foundry ties the two together on read: a
         // missing Level record only warns, and the next world launch persists
         // the emptied `levels` array — so the map is lost for good and the
-        // only symptom is a blank battlemap (#1538). Assert it on the bytes
+        // only symptom is a blank battlemap. Assert it on the bytes
         // just written, which is the one place the compendium CLI's write path
         // is observable.
         const problems = await verifyPackSceneLevels(stage);
@@ -164,7 +164,7 @@ export async function compilePacks({
  * @param {number} [options.ownership=0]          Value to reset default ownership to.
  * @param {string} [options.lastModifiedBy]       The stamped author id. Defaults to
  *     the configured one — the same value `buildStats` stamps, so a compiled
- *     entry and a re-cleaned one never disagree (#1508).
+ *     entry and a re-cleaned one never disagree.
  */
 function cleanPackEntry(
     data,

package/engine/compile-corpus.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The corpus one compile runs over, and everything derived from it (#243).
+ * The corpus one compile runs over, and everything derived from it.
  *
  * **A compile read every note twenty times.** Measured over `sohl`'s 1,685
  * notes: 33,700 reads, exactly twenty per note. Four per pass — the
@@ -24,10 +24,9 @@
  * to all of them.
  *
  * So they are derived **once**, here, and every pass is handed the result. That
- * is #243's claim stated at the point where it costs the most: not that
+ * is the claim stated at the point where it costs the most: not that
  * re-deriving is wasteful, but that N passes each answering "which files are
- * the corpus?" is N answers that can differ — which is what #241 was, and what
- * the twenty reads were paying for.
+ * the corpus?" is N answers that can differ.
  *
  * **This module exists apart from the compilers for an import reason.**
  * Deriving the index reaches the pack router and the manifest emitter, and
@@ -50,7 +49,7 @@ import { prepareTreeSqlTables } from "./sql-tables.mjs";
  * @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.

package/engine/content-address.mjs

@@ -19,13 +19,13 @@
  * address other packages link to. Stating it twice is how a manifest comes to
  * assert a URL that resolves at build time and 404s for the reader.
  *
- * **A page's URL is its address** — `<package>/<type>-<shortcode>/` (#181), and
- * it carries **no `<system>` segment** even though the canonical address does
- * (#59). That is not an omission: a note publishes one page however many
+ * **A page's URL is its address** — `<package>/<type>-<shortcode>/`, and
+ * it carries **no `<system>` segment** even though the canonical address does.
+ * That is not an omission: a note publishes one page however many
  * systems' documents it compiles into, so there is nothing for the segment to
  * distinguish, and adding it would split one page's URL in two. The canonical
  * address names a *document*; this names a *page*. It
- * used to be derived from `name.full`, which made a display string load-bearing
+ * is not derived from `name.full`, which would make a display string load-bearing
  * in three separate ways: a rename moved the URL and nothing redirected, two
  * notes in one section could derive the same URL so a uniqueness check had to
  * run, and a long name had to be abbreviated through a word table to keep the
@@ -62,7 +62,7 @@ export { DEFAULT_ADDRESS_SCHEME };
  */
 export { NO_SYSTEM };
 
-/** The knowledgebase's mount within this package's site (#1470). */
+/** The knowledgebase's mount within this package's site. */
 export const KB_PREFIX = "kb/";
 
 /**
@@ -73,7 +73,7 @@ export const KB_PREFIX = "kb/";
  * key's **last two segments** — which is what makes a manifest entry's `path`
  * derivable from the key it is filed under rather than transported beside it.
  *
- * It was once the key's whole tail, and #59 ended that: the key gained a
+ * It is not the key's whole tail: the key carries a
  * `<system>` segment, so its tail is now `system-type-shortcode` and a slug is
  * the tail with that segment dropped. The behaviour here is unchanged, and
  * deliberately — a page has no system to name (see the module note above), so
@@ -81,11 +81,11 @@ export const KB_PREFIX = "kb/";
  * consumer deriving a `path` from a key drops the *package and the system*, not
  * the package alone.
  *
- * The hyphen is a separator and never occurs inside a segment: a shortcode is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced by `content-lint.mjs`)
- * and a type is a bare word. That is the same charset guarantee positional key
- * parsing rests on, so the address and the key cannot disagree about where one
- * ends and the other begins.
+ * The hyphen is a separator and never occurs inside a segment: a shortcode
+ * matches `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`, enforced by
+ * `content-lint.mjs`) and a type is a bare word. That is the same charset
+ * guarantee positional key parsing rests on, so the address and the key
+ * cannot disagree about where one ends and the other begins.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string} The address segment, e.g. `weapongear-dagger`.
@@ -131,9 +131,9 @@ export function addressSlug(fm) {
  *
  * **It is a pure function of the frontmatter**, and takes no options. Nothing
  * about the file the note was read from reaches it: the `README.md` convention
- * that made one note address a whole section is retired with the section itself
- * (#204), so every note is addressed alike and there is one rule and no branch.
- * It took an address scheme until #215, to validate a `landing` rule it then
+ * that made one note address a whole section is retired with the section itself,
+ * so every note is addressed alike and there is one rule and no branch.
+ * It takes no address scheme; the `landing` rule it once validated is
  * discarded; with that key retired, `prefix` was the only thing left in the
  * scheme and the paragraph above is the reason it never applied.
  *
@@ -169,9 +169,9 @@ export function packageAddress(fm) {
  * merge is a real conflict rather than an artefact of two packages sharing a
  * namespace. `(type, shortcode)` alone is unique only *within* a package, and
  * two independently authored packages reaching for the same short string is a
- * matter of time (#1499).
+ * matter of time.
  *
- * **The system segment (#59).** A package may ship content for more than one
+ * **The system segment.** A package may ship content for more than one
  * system, and one note then compiles into a document per system — an actor in
  * `actors-sohl` *and* an actor in `actors-hm3`. Without a system segment both
  * land on one key, so the address cannot name either of them. `harn-ensemble`
@@ -234,7 +234,7 @@ export function blockSystem(keyPath) {
 /**
  * Expand a written address to the one canonical address it names.
  *
- * **An omitted segment defaults from where the link is written** (#336) — it is
+ * **An omitted segment defaults from where the link is written** — it is
  * not a wildcard, and resolution is not a search. Package omitted means the
  * citing note's own; system omitted means {@link blockSystem} of the key path it
  * was written under. So every short form has exactly one expansion, computed
@@ -311,12 +311,12 @@ export const CANONICAL_KEY_SEGMENTS = 4;
  *
  * Parsing is plain positional counting: split on the separator, require
  * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
- * **The charset rule is what makes that sound** — every segment is
- * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
- * so the hyphen is purely a separator and the count alone determines every
- * field. That is enforced at each of the three sources rather than assumed of
- * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
- * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * **The charset rule is what makes that sound** — every segment matches
+ * `ADDRESS_SEGMENT_PATTERN` (`engine/address-charset.mjs`), so the hyphen is
+ * purely a separator and the count alone determines every field. That is
+ * enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs`, `contentPackage` by
+ * `defineConfig`, and types are bare words. Were any of them free to
  * carry a hyphen, no amount of counting would recover the fields and the reader
  * would need a vocabulary to match against instead.
  *
@@ -440,7 +440,7 @@ export const DOCUMENT_ID_NAMESPACE = "document";
 
 /**
  * The Foundry `_id` of the document a note compiles into, derived from its
- * canonical address (#270).
+ * canonical address.
  *
  * A note used to author this — an opaque 16-character string, one per note,
  * that said nothing its address did not and that no check guaranteed. The

package/engine/content-charset.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The charset authored content is held to, so a book can choose its face (#377).
+ * The charset authored content is held to, so a book can choose its face.
  *
  * The packs and the website render in whatever font the reader's browser or
  * Foundry supplies, and a glyph nobody has is somebody else's problem. **A book