@heroiclands/package-build 20.3.1 → 20.5.0

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";
 
@@ -259,19 +259,6 @@ export function asciiAliases(aliases) {
     return aliases.map((alias) => asciiName(alias)).filter((alias) => alias !== null);
 }
 
-/**
- * Build one index record from a note's frontmatter and its place in the tree.
- *
- * @param {object} options - Options.
- * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
- * @param {string} options.relPath - Its path below the content root, POSIX-separated.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {string} [options.body] - The note's markdown body, for its anchors.
- * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
- * @returns {Record<string, any>} The record, keys sorted at every depth.
- * @throws {Error} When the note carries a key this module derives, which would
- *   otherwise be overwritten without a word.
- */
 /**
  * This note's Foundry addresses, or `null` where it has none.
  *
@@ -281,7 +268,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 +326,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 +356,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 +365,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.
@@ -410,6 +397,29 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
     }
 }
 
+/**
+ * Build one index record from a note's frontmatter and its place in the tree.
+ *
+ * The frontmatter as authored, plus what the index derives from it: the package
+ * it compiles as, its address, ASCII folds of its name and aliases, the anchors
+ * of its body, its Foundry block, the address of its documentation journal, and
+ * where the file sits within the tree.
+ *
+ * @param {object} options - Options.
+ * @param {Record<string, any>} options.frontmatter - The note's parsed frontmatter.
+ * @param {string} options.relPath - Its path below the content root, POSIX-separated.
+ * @param {string} [options.absPath] - The file, read only on the failing path to
+ *   locate the offending key.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {string} [options.body] - The note's markdown body, for its anchors.
+ * @param {number} [options.bodyLine] - The 1-based file line the body starts on.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @returns {Record<string, any>} The record, keys sorted at every depth.
+ * @throws {Error} When the note carries a key this module derives, which would
+ *   otherwise be overwritten without a word. `file` and, where the file was
+ *   read, `position` ride on the error.
+ */
 export function buildIndexRecord({
     frontmatter,
     relPath,
@@ -466,16 +476,6 @@ export function buildIndexRecord({
     );
 }
 
-/**
- * Read a content tree into index records, in the order they will be written.
- *
- * @param {string} contentBase - The content tree to walk.
- * @param {object} options - Options.
- * @param {string} options.contentPackage - The package the tree compiles as.
- * @param {Array<string>} [options.skipDirectories] - Directory names to skip.
- * @returns {Array<Record<string, any>>} The records, in a total order that does
- *   not depend on directory-read order.
- */
 /**
  * The record for an item note's **documentation journal**.
  *
@@ -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 },
@@ -531,13 +531,34 @@ function buildDocRecord({ frontmatter, address, entry, file, contentPackage, anc
     );
 }
 
+/**
+ * Read a content tree into index records, in the order they will be written.
+ *
+ * An item note yields two records — the item, and the documentation journal
+ * that is a document in its own right.
+ *
+ * @param {string} contentBase - The content tree to walk.
+ * @param {object} options - Options.
+ * @param {string} options.contentPackage - The package the tree compiles as.
+ * @param {readonly string[]} options.skipDirectories - The walk's scope, stated
+ *   by the caller. An absent one is the caller's omission, and
+ *   {@link module:engine/helpers.walkMarkdownTree} throws on it.
+ * @param {object} [options.manifest] - The package manifest, which the Foundry
+ *   entries are derived against.
+ * @param {object[]} [options.problems] - Supplied by a **reader**: a note that
+ *   cannot be recorded is pushed here as a diagnostic and skipped. Omitted, the
+ *   note throws — the contract the emitter needs, since an index missing a note
+ *   asserts that it does not exist.
+ * @returns {Array<Record<string, any>>} The records, in a total order that does
+ *   not depend on directory-read order.
+ */
 export function collectContentIndex(
     contentBase,
     { contentPackage, skipDirectories, manifest, problems },
 ) {
     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 +566,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 +600,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 +658,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 +669,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

package/engine/content-links.mjs

@@ -27,9 +27,9 @@
  *    written target is a *partial* address — the segments it omits are
  *    wildcards, and the package it omits is this one — so a target resolving to
  *    *several* notes is an ambiguity rather than a first match, and is reported
- *    naming every candidate (#59).
+ *    naming every candidate.
  * 3. **An unlabelled link.** `[[x]]` addresses nothing: the alias namespace it
- *    used to name is retired (#180), and a shortcode is an address rather than
+ *    once named is retired, and a shortcode is an address rather than
  *    prose, so the link has neither a resolvable target nor text to show. The
  *    correction is always `[[type-shortcode|Text]]`.
  * 4. **A wikilink authored in frontmatter.** Both builds walk a note's *body*
@@ -49,7 +49,7 @@
  * document is reachable from the book's root" — is a statement about what one
  * package publishes, not about the note format, so it belongs with the
  * publishing it describes; so does a retired hostname. Both are served by the
- * link graph returned here rather than implemented here (#20).
+ * link graph returned here rather than implemented here.
  *
  * @module
  */
@@ -61,7 +61,7 @@ import { matchAllOutsideCode } from "./code-fences.mjs";
 import { expandContentTables } from "./content-tables.mjs";
 import { collectAnchors } from "./anchors.mjs";
 // The corpus, and everything derived from it, read from the one place that
-// derives it (#243). Nothing in the index's own import graph reaches this
+// derives it. Nothing in the index's own import graph reaches this
 // module, so this is a plain static import rather than the deferred one
 // `sql-tables` needs to keep out of the compilers' cycle.
 import { authoredFrontmatter, indexRecordsFor, isNoteRecord, noteFile } from "./content-index.mjs";
@@ -88,7 +88,7 @@ import { readQualifier } from "./wikilinks.mjs";
  * Every `{#anchor}` a note declares on a heading.
  *
  * **Read from the content index's reader, not a second one.** This module kept
- * its own until #243, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
+ * its own, and the two disagreed: it matched `{#([a-z0-9-]+)}` while
  * {@link module:engine/content-index.collectAnchors} matches `{#([^}]+)}`, so
  * an anchor with a capital in it — `{#CalendarFormat}` — existed for the index
  * and for the compiler and did not exist for the link checker. Nothing links to
@@ -110,7 +110,7 @@ export function anchorsOf(body) {
  * Read a content tree into the index a link resolves against.
  *
  * **The corpus comes from the content index, not from a walk of this module's
- * own** (#243). Every pass used to answer "which files are the content?" for
+ * own**. Every pass used to answer "which files are the content?" for
  * itself and throw the answer away; this one now reads
  * {@link module:engine/content-index.indexRecordsFor}, which is the same
  * derivation the published artifact and the compilers are driven from. So a
@@ -118,7 +118,7 @@ export function anchorsOf(body) {
  * anchors it resolves against are the ones every other pass will emit — rather
  * than a second derivation that agrees with them only by inspection. That was
  * not hypothetical: this module carried its own anchor reader until the anchor
- * half of #243, and the two disagreed about which anchors existed.
+ * anchor half, and the two disagreed about which anchors existed.
  *
  * **The file is opened for its bytes and nothing else.** The index deliberately
  * carries no note *body*, and a link lives in the body — so each note is read
@@ -138,7 +138,7 @@ export function anchorsOf(body) {
  * @param {string} contentBase - Root of the content tree.
  * @param {object} [opts]
  * @param {object} [opts.config] - The resolved build configuration, whose
- *   fetched dependency indexes foreign addresses resolve through (#239), and
+ *   fetched dependency indexes foreign addresses resolve through, and
  *   whose `contentPackage` every local address is built from. Omitted, the
  *   ambient configuration is resolved and no cross-package address resolves.
  * @param {readonly string[]} [opts.skipDirectories] - The walk's scope, passed
@@ -162,10 +162,10 @@ export function buildLinkIndex(
 
     // The one package every note in this tree belongs to. Taken from the
     // configuration this build resolved — never from a note (`package:` is
-    // retired, so there is no second source an address could disagree with,
-    // #56) and never from the ambient one, which is a different configuration
+    // retired, so there is no second source an address could disagree with)
+    // and never from the ambient one, which is a different configuration
     // whenever a test injects one, `PACKAGE_BUILD_CONFIG` names one, or the
-    // command runs from a worktree (#243).
+    // command runs from a worktree.
     const resolved = config ?? loadPackConfig();
     const pkg = resolved.contentPackage;
 
@@ -197,12 +197,12 @@ export function buildLinkIndex(
         notes.push(note);
 
         // The anchors the index recorded, rather than a second reading of the
-        // same headings — the disagreement #243's anchor half removed.
+        // same headings — the disagreement the anchor half removes.
         anchors.set(note, new Set((record.anchors ?? []).map((a) => a.slug)));
 
         if (typeof fm.shortcode === "string" && fm.shortcode) {
             // Canonical addresses only. Every written target expands to one
-            // before lookup (#336), so there is nothing left for a short key to
+            // before lookup, so there is nothing left for a short key to
             // answer — and the short key was harmful: `type/shortcode` is
             // system-blind, set with a plain `Map.set`, so two notes in one
             // package sharing a `(type, shortcode)` across systems silently
@@ -245,7 +245,7 @@ export function buildLinkIndex(
     /** The searchable universe a `dataview` table draws its rows from. */
     const tableDocs = notes.map((n) => ({
         // Package present for a `WHERE … package = "…"` clause, synthesised
-        // rather than authored — see {@link searchableFrontmatter} (#56).
+        // rather than authored — see {@link searchableFrontmatter}.
         fm: searchableFrontmatter(n.fm, pkg),
         path: n.rel,
         tld: n.rel.split("/")[0],
@@ -259,14 +259,14 @@ export function buildLinkIndex(
      * @returns {Array<{target: string, anchor: string, text: string,
      *   occurrence: number, labelled: boolean}>} `target` is `""` for a
      *   same-page `[[#anchor]]`; `labelled` says whether the link carries the
-     *   `|` every link must have (#180).
+     *   `|` every link must have.
      */
     function linksOf(note) {
         let body = note.body;
         if (/^[ \t]*(?:`{3,}|~{3,})[ \t]*(?:dataview|sql)\b/im.test(body)) {
             body = expandContentTables(body, {
                 // Unfiltered: every note in the tree is this package's, so
-                // there is no other package's note to exclude (#56).
+                // there is no other package's note to exclude.
                 docs: tableDocs,
                 linkable: (d) => Boolean(d.fm.shortcode),
                 source: note.file,
@@ -301,22 +301,11 @@ export function buildLinkIndex(
         return out;
     }
 
-    /**
-     * The note an **address** names, or `undefined`.
-     *
-     * The qualifier is read with {@link readQualifier} rather than a second
-     * copy of the rule, so this cannot drift from what the builds do — the two
-     * separators, the first-hyphen split, and the optional leading package
-     * segment.
-     *
-     * @param {string} target - The link target, anchor already removed.
-     * @returns {object|undefined} The note it addresses.
-     */
     /**
      * Every indexed entry an address names, matching only the segments it
      * supplies.
      *
-     * This is the whole of #59's resolution rule in one place: a written
+     * This is the whole resolution rule in one place: a written
      * address is a *partial* one, unsupplied segments are wildcards, and the
      * caller requires exactly one hit. Nothing here decides an ambiguity — zero
      * and many are different findings with different fixes, so the count is
@@ -351,10 +340,24 @@ export function buildLinkIndex(
         return matchAddress([...byKey], q).map(([, v]) => v);
     }
 
+    /**
+     * The note an **address** names, or `undefined`.
+     *
+     * The qualifier is read with {@link readQualifier} rather than a second
+     * copy of the rule, so this cannot drift from what the builds do — the two
+     * separators, the first-hyphen split, and the optional leading package
+     * segment.
+     *
+     * @param {string} target - The link target, anchor already removed.
+     * @param {string} [keyPath] - The dotted frontmatter key path the link sits
+     *   under, which supplies the system an omitted segment defaults to — see
+     *   {@link blockSystem}. Body prose has none.
+     * @returns {object|undefined} The note it addresses.
+     */
     function resolveAddress(target, keyPath) {
         const qualified = readQualifier(target, types, packages);
         if (!qualified || qualified.reason) return undefined;
-        // Every omitted segment defaults from where the link is written (#336),
+        // Every omitted segment defaults from where the link is written,
         // so the target expands to exactly one canonical address and this is a
         // plain lookup. There is no candidate set, and therefore no single-hit
         // rule and no ambiguity to report.
@@ -370,21 +373,24 @@ export function buildLinkIndex(
      * Every foreign manifest entry an address names, in package order.
      *
      * A written target is a **partial** address, so this matches on the
-     * segments it supplies and wildcards the rest (#59). A target naming a
+     * segments it supplies and wildcards the rest. A target naming a
      * package necessarily names its system too — omission runs left to right —
      * so the fully qualified form matches at most one entry; a shorter one
      * names no package, and resolves against any foreign package that
      * publishes it. Either way only exactly one hit resolves. Two claimants make it ambiguous, which is a different finding
      * from resolving nowhere and has a different fix, so the count is returned
-     * rather than collapsed here (#184).
+     * rather than collapsed here.
      *
      * @param {string} target - The link target.
+     * @param {string} [keyPath] - The dotted frontmatter key path the link sits
+     *   under, which supplies the system an omitted segment defaults to — see
+     *   {@link blockSystem}. Body prose has none.
      * @returns {object[]} The foreign entries, each carrying its `package`.
      */
     function foreignHits(target, keyPath) {
         const q = readQualifier(target, types, packages);
         if (!q || q.reason) return [];
-        // An omitted package means *this* package (#336), so a short form
+        // An omitted package means *this* package, so a short form
         // addresses nothing foreign and never reaches a dependency's index.
         // Reaching another package is the fully qualified form's job, and
         // saying so is the whole point: a link that resolved into `sohl` only
@@ -411,6 +417,32 @@ export function buildLinkIndex(
         return hits.length === 1 ? hits[0] : null;
     }
 
+    /**
+     * The note or foreign entry a **frontmatter reference** names, or null.
+     *
+     * A `ref:` field holds a shortcode, not an address. The system persists it
+     * verbatim and resolves it at runtime against the items embedded on one
+     * actor, where packages do not exist: an actor assembled from several
+     * packages carries their items side by side. So a reference resolves when
+     * *any* reachable package declares the `(type, shortcode)` pair — package
+     * and system wildcarded, local notes first, then the fetched indexes.
+     *
+     * Distinct from {@link resolveAddress}, which defaults an omitted package
+     * to this one. That is the rule for a link, whose target is a document to
+     * point at; a reference names an item to stand beside.
+     *
+     * @param {string} target - The reference as `type-shortcode`.
+     * @returns {object|null} The note or foreign entry declaring it.
+     */
+    function referenceHit(target) {
+        const q = readQualifier(target, types, packages);
+        if (!q || q.reason) return null;
+        const local = matchAddress([...byKey], q);
+        if (local.length) return local[0][1];
+        const abroad = matchAddress([...foreign.index], q);
+        return abroad.length ? abroad[0][1] : null;
+    }
+
     return {
         notes,
         frontmatterLinks,
@@ -428,12 +460,13 @@ export function buildLinkIndex(
         /**
          * Resolve a link target the way both builds do, or `undefined`. Every
          * link is an address, so this is {@link resolveAddress} under the name
-         * the walkers use (#180).
+         * the walkers use.
          */
         resolve: resolveAddress,
         resolveAddress,
         manifestHit,
         foreignHits,
+        referenceHit,
         /** Whether a target reads as a qualified address at all. */
         isAddress: (target) => Boolean(readQualifier(target, types, packages)),
     };
@@ -453,7 +486,7 @@ export function buildLinkIndex(
 const SITE_HOST = /^(?:[a-z0-9-]+\.)*heroiclands\.org$/i;
 
 /**
- * Every package landing this build can name, as `package` → base (#87).
+ * Every package landing this build can name, as `package` → base.
  *
  * **A landing needs no manifest, and that is what makes it work.** The link
  * manifest indexes content notes, and a homepage is deliberately not one — it
@@ -578,13 +611,13 @@ function readAddress(url, packages) {
  * **What is checkable, stated plainly.** Only an address into this site is, and
  * only against facts this build already holds:
  *
- * - A **retired content type** in the path. The engine knows what used to exist
+ * - A **retired content type** in the path. The engine knows the retired names
  *   and what replaced it, so this is a fact rather than a guess — and it is
  *   exactly the SoHL defect.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
  *   a fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
- *   another package's landing (#87).
+ *   another package's landing.
  *
  *   That last case was exempt until the better form was identified, on the
  *   reasoning that a landing is in no link manifest so nothing could resolve it.
@@ -658,7 +691,7 @@ export function auditHomepageLinks(index) {
             // Landings first, and by the roster rather than by the manifest
             // package set: a landing is addressable in a repository that
             // has fetched no index at all, which is the case the fence creates
-            // and the case this rule exists for (#87).
+            // and the case this rule exists for.
             const landing = landingTarget(url, bases);
             if (landing) {
                 report(
@@ -749,7 +782,7 @@ export function auditHomepageLinks(index) {
  *
  * **How the link is *written* is a separate finding from where it points**, and
  * the two are kept apart because the corrections differ. An unlabelled link
- * (#180) has to become `[[type-shortcode|Text]]`; a labelled one whose target
+ * has to become `[[type-shortcode|Text]]`; a labelled one whose target
  * resolves nowhere has a shortcode to fix. Reporting a bare `[[Name]]` as a
  * dead address would send an author hunting for a note that was never named.
  *
@@ -761,7 +794,7 @@ export function auditHomepageLinks(index) {
  *   carries a `reason` from {@link LINK_FINDING_REASONS} —
  *   `"not-an-address"`, `"unknown-type"`, `"ambiguous"` (with the claiming
  *   `packages`), or `"unresolved"` — and every one of them is an **error**:
- *   the three resolvers agree on severity for every class (#184).
+ *   the three resolvers agree on severity for every class.
  */
 export function auditLinks(index) {
     const { notes, anchors, linksOf, resolve, manifestHit, isAddress } = index;
@@ -792,7 +825,7 @@ export function auditLinks(index) {
     for (const note of notes) {
         for (const { target, anchor, text, occurrence, labelled } of linksOf(note)) {
             // The label is required whatever the link part is, an anchor
-            // included — so this is tested before the same-page form (#180).
+            // included — so this is tested before the same-page form.
             if (!labelled) {
                 unlabelledLinks.push({
                     note,
@@ -824,7 +857,7 @@ export function auditLinks(index) {
                 // Two packages publish the short address, so it names neither.
                 // Reported as its own class: "no document has that identity" is
                 // false here — two do — and the fix is the qualified form
-                // rather than a corrected shortcode (#184).
+                // rather than a corrected shortcode.
                 deadAddresses.push({
                     ...at,
                     reason: "ambiguous",