@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/content-icons.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Naming an interface icon in a note, without drawing it there (#378).
+ * Naming an interface icon in a note, without drawing it there.
  *
  * The user guide describes Foundry's interface, and it did so by pasting
  * Unicode lookalikes of the icons the sheets actually draw: `☆` for the improve
@@ -23,11 +23,11 @@
  * every sheet change.
  *
  * They are also the worst characters in the corpus to typeset. Of the eight
- * book faces probed for #377, **none** carries `✕ ✗ ✎ ☆ ⚗ ➕`; in a Libertinus
+ * book faces probed, **none** carries `✕ ✗ ✎ ☆ ⚗ ➕`; in a Libertinus
  * setting `✕` resolves to macOS LastResort, which draws a tofu box.
  *
  * **Neither obvious fix works.** Keeping the dingbats pins the book to some
- * icon-capable font forever, which is the coupling #377 exists to remove.
+ * icon-capable font forever, which is the coupling this exists to remove.
  * Pasting Font Awesome's own codepoints is worse: they live in the Private Use
  * Area, which is unassigned by definition, so they break search, copy-paste and
  * screen readers, and no charset check can validate them.
@@ -69,15 +69,81 @@ import fs from "node:fs";
 import path from "node:path";
 
 /**
- * The Font Awesome styles a registry entry may name.
+ * A **family** is an icon font, and a consumer declares the ones it ships.
+ *
+ * Nothing here names Font Awesome, or Game-Icons, or any other font. A registry
+ * entry is a promise that a glyph will render, and only the package that ships
+ * the font can keep it: the Game-Icons webfont is built by a consumer from its
+ * own templates, and even Font Awesome — which Foundry supplies in-app — is
+ * present on neither the knowledgebase nor the page of a book unless somebody
+ * puts it there. A toolchain that shipped a table would be promising on a
+ * consumer's behalf.
+ *
+ * The vocabulary is the consumer's for a second reason, independent of fonts. A
+ * name like `victory-star-tester` is one game system's concept; another system
+ * compiled by this same toolchain has different icons meaning different things.
+ * What is shared is the *mechanism* — the syntax, the resolution, the checks —
+ * and that is what lives here.
+ *
+ * A family declares:
+ *
+ * - `class` — the prefix its stylesheet uses (`fa`, `ginf`, `bi`).
+ * - `styles` — the weights it ships, in the spelling its classes use. An empty
+ *   list means the font has none, and then a `style` on an entry names
+ *   something that does not exist and is reported rather than rendered.
+ * - `describe` — one line, so a finding can say which font it means.
+ *
+ * @typedef {object} IconFamily
+ * @property {string} class - The stylesheet's class prefix.
+ * @property {readonly string[]} styles - The weights it ships; empty for none.
+ * @property {string} describe - One line, for a finding.
+ */
+
+/**
+ * A resolved registry: the families a package ships, and the icons it names.
+ *
+ * `defaultFamily` is what an entry that names none belongs to. It is optional,
+ * and where a package declares exactly one family that one is it — so a
+ * single-font package writes no `family` anywhere.
+ *
+ * @typedef {object} IconRegistry
+ * @property {Readonly<Record<string, IconFamily>>} families
+ * @property {string|undefined} defaultFamily
+ * @property {Readonly<Record<string, object>>} icons
+ */
+
+/**
+ * The registry a package that declares none gets: nothing at all.
  *
- * Free ships these three and no others, so a `light` or `duotone` entry would
- * name a glyph the shipped font does not contain — refused here rather than
- * discovered as a blank space in a printed book.
+ * Empty rather than a starter set, because a starter set is a promise about
+ * fonts this package does not ship. A tree with no `icons:` configured names no
+ * icons, and `:icon-star:` in one of its notes renders as its own literal text
+ * and is reported — which is the visible failure, not a silent one.
  *
- * @type {readonly string[]}
+ * @type {IconRegistry}
  */
-export const ICON_STYLES = Object.freeze(["solid", "regular", "brands"]);
+export const EMPTY_ICON_REGISTRY = Object.freeze({
+    families: Object.freeze({}),
+    defaultFamily: undefined,
+    icons: Object.freeze({}),
+});
+
+/**
+ * The family an entry draws from, named or defaulted.
+ *
+ * @param {{family?: string}} entry - A registry entry.
+ * @param {IconRegistry} [registry] - The registry it came from.
+ * @returns {string|undefined} The family name, or nothing when neither the
+ *   entry nor the registry says.
+ */
+export function familyOf(entry, registry = EMPTY_ICON_REGISTRY) {
+    if (entry?.family) return entry.family;
+    if (registry?.defaultFamily) return registry.defaultFamily;
+    // One declared family is unambiguous, so a single-font package writes no
+    // `family` on any entry and states no default either.
+    const names = Object.keys(registry?.families ?? {});
+    return names.length === 1 ? names[0] : undefined;
+}
 
 /**
  * The sizes a note may ask for, and what each means on a page.
@@ -176,52 +242,6 @@ export function parseIconAttributes(raw) {
     return { attrs, problems };
 }
 
-/**
- * The icons the user guide already depicts, under the names it should call them.
- *
- * Each entry is read off the interface it describes rather than invented, and
- * that is meant literally — the table was checked against the system's own
- * templates, which is how `delete` came to be `fa-trash` rather than the
- * `fa-trash-can` first written here. The sheets draw `fa-trash` twenty-five
- * times and `fa-trash-can` never, so the first spelling would have printed an
- * icon the reader has never seen on screen. A registry that is not checked
- * against the interface is just a second place to be wrong.
- *
- * The names are what a *writer* would reach for — `delete`, not `trash` —
- * because the writer is the one typing them; the Font Awesome spelling is this
- * table's business, not theirs.
- *
- * **Three entries share `xmark`, and that is the point of naming rather than
- * drawing.** A `✕` in the guide means "not applicable" in a Healing Rate
- * column, "remove this row" on a control, and "close" on a dialog's corner. One
- * glyph, three sentences, three different things for a reader who cannot see
- * it — so they are three names with three labels, and the fact that Font
- * Awesome happens to draw them identically stays in this table.
- *
- * `run` and `expand` are likewise distinct: `▶` runs an action, and its label
- * should say so. `fa-play` is what the sheets use for it.
- *
- * @type {Readonly<Record<string, {style: string, icon: string, label: string}>>}
- */
-export const DEFAULT_ICONS = Object.freeze({
-    affiliation: { style: "solid", icon: "certificate", label: "affiliation" },
-    star: { style: "solid", icon: "star", label: "star" },
-    "star-outline": { style: "regular", icon: "star", label: "hollow star" },
-    diamond: { style: "solid", icon: "diamond", label: "diamond" },
-    edit: { style: "solid", icon: "pen-to-square", label: "edit" },
-    delete: { style: "solid", icon: "trash", label: "delete" },
-    add: { style: "solid", icon: "plus", label: "add" },
-    remove: { style: "solid", icon: "xmark", label: "remove" },
-    "not-applicable": { style: "solid", icon: "xmark", label: "not applicable" },
-    close: { style: "solid", icon: "xmark", label: "close" },
-    menu: { style: "solid", icon: "ellipsis-vertical", label: "actions menu" },
-    run: { style: "solid", icon: "play", label: "run this action" },
-    expand: { style: "solid", icon: "caret-right", label: "expand" },
-    shield: { style: "solid", icon: "shield-halved", label: "armour" },
-    compass: { style: "solid", icon: "compass", label: "guided tour" },
-    flask: { style: "solid", icon: "flask", label: "under construction" },
-});
-
 /**
  * The shape a note writes, and the one this module claims.
  *
@@ -229,7 +249,7 @@ export const DEFAULT_ICONS = Object.freeze({
  * surface that also renders `:smile:` can tell the two apart without a lookup,
  * and a reader can tell what `:icon-star:` is without knowing this module
  * exists. Names are lowercase, digits and hyphens — the charset an address
- * segment already uses (#59), so nothing new has to be explained.
+ * segment already uses, so nothing new has to be explained.
  *
  * Not `:name[content]`. That is remark-directive syntax, and this toolchain
  * parses with markdown-it; a directive would render as its own literal text.
@@ -257,12 +277,13 @@ export const ICON_PATTERN = /:icon-([a-z0-9]+(?:-[a-z0-9]+)*):(?:\{([^}]*)\})?/g
  * Look one name up.
  *
  * @param {string} name - The name written between the colons, without `icon-`.
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
- * @returns {{style: string, icon: string, label: string}|null} The entry, or
- *   `null` when the registry does not declare it.
+ * @param {IconRegistry} [registry] - The package's registry.
+ * @returns {object|null} The entry, or `null` when the registry does not
+ *   declare it.
  */
-export function resolveIcon(name, registry = DEFAULT_ICONS) {
-    return Object.prototype.hasOwnProperty.call(registry, name) ? registry[name] : null;
+export function resolveIcon(name, registry = EMPTY_ICON_REGISTRY) {
+    const icons = registry?.icons ?? {};
+    return Object.prototype.hasOwnProperty.call(icons, name) ? icons[name] : null;
 }
 
 /** HTML-escape a value going into an attribute. */
@@ -277,13 +298,41 @@ const attr = (value) =>
  * an icon dropped into a sentence has no such parent, and "the ☆ toggles it"
  * read aloud as "the toggles it" is a sentence with a hole in it.
  *
- * @param {{style: string, icon: string, label: string}} entry - A registry entry.
+ * @param {object} entry - A registry entry.
+ * @param {Record<string, string>} [attrs] - The token's attributes.
+ * @param {IconRegistry} [registry] - The registry the entry came from, which is
+ *   what says how its family spells a class.
  * @returns {string} An `<i>` element.
  */
-export function iconHtml(entry, attrs = {}) {
-    const classes = [`fa-${attr(entry.style)}`, `fa-${attr(entry.icon)}`];
+export function iconHtml(entry, attrs = {}, registry = EMPTY_ICON_REGISTRY) {
+    const family = registry?.families?.[familyOf(entry, registry)];
+    // A family nothing declares is reported by `checkIconRegistry`, not
+    // invented here: guessing a prefix would put a class on the page that no
+    // stylesheet defines, which looks like a missing glyph rather than a
+    // configuration mistake.
+    if (!family) return "";
+    const prefix = family.class;
+    const styles = family.styles ?? [];
+
+    // A family with weights spells the weight and the name as two classes; one
+    // without has a single class and no weight to spell.
+    const classes =
+        styles.length ?
+            [`${prefix}-${attr(entry.style)}`, `${prefix}-${attr(entry.icon)}`]
+        :   [`${prefix}-${attr(entry.icon)}`];
+
+    // Fixed width, where the glyph needs it. This is the table's to say, not a
+    // note's: whether an ellipsis is too narrow to sit in a column of controls
+    // is a fact about that glyph, and the same everywhere it is drawn. A note
+    // names the meaning and the table owns how it is set.
+    if (styles.length && entry.fixedWidth) classes.push(`${prefix}-fw`);
+
+    // The size classes are Font Awesome's, and the Game-Icons stylesheet this
+    // toolchain's consumers generate mirrors its box metrics deliberately, so
+    // they apply to both families.
     const sized = attrs.size ? ICON_SIZES[attrs.size] : undefined;
     if (sized) classes.push(sized.class);
+
     return `<i class="${classes.join(" ")}" role="img" aria-label="${attr(entry.label)}"></i>`;
 }
 
@@ -311,11 +360,11 @@ export function iconsIn(text) {
  *
  * @param {string} text - The file's contents.
  * @param {string} file - Path to report.
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * @param {IconRegistry} [registry] - The package's registry.
  * @returns {Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>} The unknown names.
  */
-export function lintIcons(text, file, registry = DEFAULT_ICONS) {
+export function lintIcons(text, file, registry = EMPTY_ICON_REGISTRY) {
     const findings = [];
     for (const { name, index, raw, problems } of iconsIn(text)) {
         const before = text.slice(0, index);
@@ -326,7 +375,7 @@ export function lintIcons(text, file, registry = DEFAULT_ICONS) {
         if (!resolveIcon(name, registry)) {
             // Nearest declared name, when there is an obvious one: a typo is the
             // common case and the registry is short enough to say what was meant.
-            const suggestion = nearestName(name, Object.keys(registry));
+            const suggestion = nearestName(name, Object.keys(registry?.icons ?? {}));
             findings.push({
                 ...at,
                 message:
@@ -393,47 +442,117 @@ function editDistance(a, b) {
 }
 
 /**
- * Refuse a registry that names a style Font Awesome Free does not ship.
+ * What is wrong with a package's declared registry.
+ *
+ * Both halves are checked, because either alone is unusable: an icon naming a
+ * family nothing declares has no class prefix, and a family nothing names is a
+ * font declared for no reason.
+ *
+ * A **style** is checked against the family's own `styles`, not against a list
+ * here. Font Awesome Free ships three weights and another font ships none or
+ * five, and only the declaration knows which — so a `duotone` entry is refused
+ * because the family that entry belongs to does not list `duotone`, which is a
+ * statement the consumer made about the font it actually ships.
  *
- * @param {Record<string, object>} registry - A package's icon table.
+ * @param {{families?: object, icons?: object}} registry - A package's declared
+ *   registry, before it is resolved.
  * @param {string} [where="icons"] - Where to say the fault is.
  * @returns {Array<{severity: "warning", message: string}>} What is wrong with it.
  */
 export function checkIconRegistry(registry, where = "icons") {
     const findings = [];
-    for (const [name, entry] of Object.entries(registry ?? {})) {
-        const at = `\`${where}.${name}\``;
+    const warn = (message) =>
+        findings.push({ severity: /** @type {const} */ ("warning"), message });
+
+    const families = registry?.families ?? {};
+    const icons = registry?.icons ?? {};
+
+    for (const [name, family] of Object.entries(families)) {
+        const at = `\`${where}.families.${name}\``;
+        if (!family || typeof family !== "object") {
+            warn(`${at} is not a family — it takes \`class\`, \`styles\` and \`describe\``);
+            continue;
+        }
+        if (typeof family.class !== "string" || !family.class) {
+            warn(`${at} declares no \`class\`, so nothing says how its glyphs are spelled`);
+        }
+        if (family.styles !== undefined && !Array.isArray(family.styles)) {
+            warn(
+                `${at} declares \`styles\` that is not a list — write \`[]\` for a font with no weights`,
+            );
+        }
+        if (typeof family.describe !== "string" || !family.describe) {
+            warn(`${at} declares no \`describe\`, so a finding cannot say which font it means`);
+        }
+    }
+
+    for (const [name, entry] of Object.entries(icons)) {
+        const at = `\`${where}.icons.${name}\``;
         if (!entry || typeof entry !== "object") {
-            findings.push({
-                severity: /** @type {const} */ ("warning"),
-                message: `${at} is not an icon entry — it takes \`style\`, \`icon\` and \`label\``,
-            });
+            warn(`${at} is not an icon entry — it takes \`icon\` and \`label\``);
             continue;
         }
-        if (!ICON_STYLES.includes(entry.style)) {
-            findings.push({
-                severity: /** @type {const} */ ("warning"),
-                message:
-                    `${at} names style \`${entry.style}\`, and Font Awesome Free ships ` +
-                    `only ${ICON_STYLES.join(", ")} — a glyph in any other style is ` +
-                    `absent from the font a book would embed`,
-            });
+
+        const familyName = familyOf(entry, { families, defaultFamily: registry?.defaultFamily });
+        if (!familyName) {
+            warn(
+                `${at} names no family and the registry declares ${Object.keys(families).length} of ` +
+                    `them, so nothing says which font draws it — name one on the entry, or ` +
+                    `declare a \`defaultFamily\``,
+            );
+            continue;
+        }
+        const family = families[familyName];
+        if (!family) {
+            const declared = Object.keys(families);
+            warn(
+                `${at} names family \`${familyName}\`, and the families this package ` +
+                    `declares are: ${declared.length ? declared.join(", ") : "none"}`,
+            );
+            continue;
+        }
+
+        const styles = Array.isArray(family.styles) ? family.styles : [];
+        if (styles.length && !styles.includes(entry.style)) {
+            warn(
+                `${at} names style \`${entry.style}\`, and ${family.describe} ships ` +
+                    `only ${styles.join(", ")} — a glyph in any other style is absent ` +
+                    `from the font a book would embed`,
+            );
         }
+
+        // A style on a font with no weights is not a harmless extra key: it
+        // says the author expected a weight, and what they get is not what
+        // they asked for.
+        if (!styles.length && entry.style !== undefined) {
+            warn(
+                `${at} names style \`${entry.style}\`, and ${family.describe} has no ` +
+                    `weights — the style is ignored, so a filled and hollow pair cannot ` +
+                    `be spelled this way`,
+            );
+        }
+
+        // The same rule `style` gets: a font with no weights ships no `-fw`
+        // class either, so asking for one asks for a width it cannot give.
+        if (!styles.length && entry.fixedWidth !== undefined) {
+            warn(
+                `${at} asks for fixed width, and ${family.describe} ships no such ` +
+                    `class — the request is ignored, so a glyph that needs the width ` +
+                    `will not get it`,
+            );
+        }
+
         if (typeof entry.icon !== "string" || !entry.icon) {
-            findings.push({
-                severity: /** @type {const} */ ("warning"),
-                message: `${at} declares no \`icon\`, so nothing names the glyph to draw`,
-            });
+            warn(`${at} declares no \`icon\`, so nothing names the glyph to draw`);
         }
         if (typeof entry.label !== "string" || !entry.label) {
-            findings.push({
-                severity: /** @type {const} */ ("warning"),
-                message:
-                    `${at} declares no \`label\`, and an icon with no accessible name ` +
-                    `is read aloud as a gap in the sentence`,
-            });
+            warn(
+                `${at} declares no \`label\`, and an icon with no accessible name is ` +
+                    `read aloud as a gap in the sentence`,
+            );
         }
     }
+
     return findings;
 }
 
@@ -447,7 +566,7 @@ export function checkIconRegistry(registry, where = "icons") {
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {readonly string[]} [opts.skipDirectories] - Directory names to ignore.
- * @param {Record<string, object>} [opts.registry] - The package's icon table.
+ * @param {IconRegistry} [opts.registry] - The package's registry.
  * @returns {{findings: Array<{file: string, line: number, column: number,
  *   severity: "warning", message: string}>, files: number}} What it found.
  */
@@ -495,14 +614,22 @@ export function lintContentIcons(contentBase, { skipDirectories = [], registry }
  * is reported by {@link lintIcons}, and a rendered page that still shows
  * `:icon-stra:` is how the author finds it without reading a log.
  *
- * @param {Record<string, object>} [registry] - Defaults to {@link DEFAULT_ICONS}.
+ * **A function is accepted as well as a table**, and resolved per render. The
+ * shared markdown-it instance is a module-level constant, so it is built before
+ * any configuration is read; a getter lets it draw the package's own registry
+ * without the module load order deciding whether that registry exists yet.
+ *
+ * @param {Record<string, object>|(() => Record<string, object>)} [registry] -
+ *   The registry, or something that returns it.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function iconPlugin(registry = DEFAULT_ICONS) {
+export function iconPlugin(registry = EMPTY_ICON_REGISTRY) {
+    const tableOf = () =>
+        typeof registry === "function" ? (registry() ?? EMPTY_ICON_REGISTRY) : registry;
     return (md) => {
         /** @type {any} */ (md).inline.ruler.before("emphasis", "heroiclands_icon", iconRule);
         /** @type {any} */ (md).renderer.rules.heroiclands_icon = (tokens, idx) =>
-            iconHtml(tokens[idx].meta.entry, tokens[idx].meta.attrs);
+            iconHtml(tokens[idx].meta.entry, tokens[idx].meta.attrs, tableOf());
 
         /**
          * @param {any} state - markdown-it inline state.
@@ -518,7 +645,7 @@ export function iconPlugin(registry = DEFAULT_ICONS) {
             const m = re.exec(state.src.slice(start));
             if (!m) return false;
 
-            const entry = resolveIcon(m[1], registry);
+            const entry = resolveIcon(m[1], tableOf());
             // Not ours to consume: leaving the source untouched is what makes an
             // unrecognised name visible on the page instead of vanishing.
             if (!entry) return false;

package/engine/content-index.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Emitting this package's content index (#224).
+ * Emitting this package's content index.
  *
  * Every content build already walks the whole note tree and parses every note's
  * frontmatter — the pack compilers, the site build, and the content-table
@@ -21,7 +21,7 @@
  * "which beings carry no `kbcat`?", "what does this table actually select?",
  * "did that type rename leave anything behind?" have no answer short of writing
  * a throwaway script that re-walks the tree. Eight dead Bestiary tables shipped
- * for weeks behind exactly that gap (#223).
+ * for weeks behind exactly that gap.
  *
  * This module publishes the walk. One line of JSON per note, in
  * [JSON Lines](https://jsonlines.org/) — the whole frontmatter, plus where the
@@ -62,7 +62,7 @@
  * to every player, and a build artifact has no business there.
  *
  * **What it deliberately does not carry: the note's text, and positions within
- * it.** #243 asks whether the index should record a position for every
+ * it.** The question is whether the index should record a position for every
  * frontmatter key, so that a pass reading the index could report a field defect
  * without opening the file. It should not, and the numbers are not close: over
  * `sohl`'s 1,685 notes the index is 3.0 MB and holds 50,598 leaf values, so a
@@ -94,7 +94,7 @@ import unidecode from "unidecode";
 import { metadataFileName } from "./metadata-index.mjs";
 import { addressSlug, canonicalKey } from "./content-address.mjs";
 // One reader for a note's anchors, shared with the link checker and with the
-// builds that emit a link (#243). Re-exported because this is where callers
+// builds that emit a link. Re-exported because this is where callers
 // have always addressed it.
 import { collectAnchors } from "./anchors.mjs";
 import { subtypeRow, NO_SYSTEM, systemOf } from "./document-subtypes.mjs";
@@ -105,7 +105,7 @@ import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./note-claims.mjs";
  *
  * The specification's word, not this module's: the canonical address carries it
  * in the same position — `harnadventures-none-being-grod` — so the index and
- * the address say "no system" the same way (#59).
+ * the address say "no system" the same way.
  *
  * @type {string}
  */
@@ -115,12 +115,12 @@ import { entriesForNote, foundryIdentities } from "./foundry-entries.mjs";
 import { walkMarkdownTree } from "./helpers.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 // The retired-field refusal and the key locator, so a note authoring a derived
-// key is reported where it is rather than as a bare abort (#243).
+// key is reported where it is rather than as a bare abort.
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 // The record accessors, which live apart so that a module the compilers load
-// can read a record without importing this one and closing a cycle (#243).
+// can read a record without importing this one and closing a cycle.
 // Re-exported because this is where callers have always addressed them.
 import { authoredFrontmatter, DERIVED_KEYS, isNoteRecord, noteFile } from "./index-records.mjs";
 
@@ -281,7 +281,7 @@ export function asciiAliases(aliases) {
  * plus the pack router — frontmatter and configuration, nothing from a compiled
  * pack — so the index's frontmatter walk already has every input. Deriving it
  * twice is how two artifacts describing one note start disagreeing, which is
- * the failure the merge is meant to end (#239).
+ * the failure the merge is meant to end.
  *
  * The shape flattens the manifest's *two* entries for an item note onto the one
  * record the index keeps per note. An item compiles into a document **and** a
@@ -339,7 +339,7 @@ function foundryEntries({ frontmatter, address, body, manifest }) {
  * shipped map produced and said nothing about the other.
  *
  * Only `sohl` can appear today, because `KNOWN_DOCUMENT_SUBTYPE_MAPS` holds one
- * map and #139 tracks the missing `hm3/` half. The shape is system-keyed now so
+ * map, the `hm3/` half being separate. The shape is system-keyed so
  * that adding it is one more key rather than a second breaking change to an
  * artifact consumers have already started reading.
  *
@@ -369,7 +369,7 @@ function foundryBlock(entry, system) {
  * Refuse a note that authors a key the index derives, and say where.
  *
  * **Located, because every reader of the index is now a reporter of this.**
- * Until #243 the only pass that built a record was the emitter, so aborting
+ * With the emitter the only pass building a record, aborting
  * with a bare message was the whole story. Now the link check and the address
  * diff read the index too, and a bare abort in one of them reports *nothing*
  * about the tree — the one malformed note takes every other finding with it,
@@ -378,7 +378,7 @@ function foundryBlock(entry, system) {
  * can emit `file:line:column: error: …` like any other finding.
  *
  * **`package:` keeps its own words.** It is not a name collision but a *retired
- * field* (#56), and the correction is to delete it, not to rename it — which is
+ * field*, and the correction is to delete it, not to rename it — which is
  * what {@link module:engine/note-package.assertNoDeclaredPackage} has always
  * said, and had no caller to say it to. Deferring to it means one message for
  * one mistake rather than two that contradict each other about the fix.
@@ -517,7 +517,7 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
             // The journal's own `_id`, taken from the entry rather than
             // re-derived: every entry the index gives an identity to publishes
             // both the id and the UUID, computed once by whatever owns that
-            // entry's derivation (#310).
+            // entry's derivation.
             id: entry.id,
             nameAscii: asciiName(frontmatter?.name?.full),
             address: { slug: address.slug, canonical: entry.key },
@@ -537,7 +537,7 @@ export function collectContentIndex(
 ) {
     const records = [];
     // Passed through rather than defaulted away: an absent scope is the
-    // caller's omission, and `walkMarkdownTree` says so (#243).
+    // caller's omission, and `walkMarkdownTree` says so.
     const walkOpts = { skipDirectories };
 
     for (const { frontmatter, body, bodyLine, absPath } of walkMarkdownTree(
@@ -545,7 +545,7 @@ export function collectContentIndex(
         walkOpts,
     )) {
         const fm = frontmatter ?? {};
-        // The id the note's document is filed under (#270), resolved before
+        // The id the note's document is filed under, resolved before
         // the record is built so the index publishes the address *and* the id
         // that address derives.
         resolveNoteId(fm, { pkg: contentPackage });
@@ -579,7 +579,7 @@ export function collectContentIndex(
         }
         records.push(record);
 
-        // An item note is two documents, so it is two records (#239).
+        // An item note is two documents, so it is two records.
         const doc = foundryEntries({
             frontmatter: fm,
             address: record.address,
@@ -637,7 +637,7 @@ export function serializeContentIndex(records) {
  *
  * The half of {@link emitContentIndex} that derives rather than emits, so a
  * pass that needs the corpus in memory — a SQL content table, the link check,
- * and in time every reader #243 converts — builds it the same way the artifact
+ * and in time every converted reader — builds it the same way the artifact
  * is built, rather than by walking and parsing again with its own idea of the
  * scope.
  *
@@ -648,7 +648,7 @@ export function serializeContentIndex(records) {
  *   caller that resolved one of its own; defaults to the resolved
  *   configuration's. Stated separately from `config` because a caller that was
  *   *handed* a scope must be able to pass it on rather than have it silently
- *   replaced by the one its configuration happens to carry (#243).
+ *   replaced by the one its configuration happens to carry.
  * @param {object[]} [opts.problems] - Supplied by a **reader**: a note that
  *   cannot be recorded is pushed here as a diagnostic and skipped, instead of
  *   aborting the derivation. Omitted, the note throws — which is the contract