@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/system-block.mjs

@@ -13,7 +13,7 @@
 
 /**
  * **The per-system frontmatter block** — how one note feeds more than one game
- * system (#58).
+ * system.
  *
  * A note is system-agnostic. The only system-specific things it carries are the
  * properties *named after a system*, and within one:
@@ -21,7 +21,7 @@
  * | property | maps to |
  * | --- | --- |
  * | `<system>.system` | `document.system` — the DataModel schema, verbatim paths |
- * | `<system>.type` | `document.type` — the subtype (#79's discriminator) |
+ * | `<system>.type` | `document.type` — the subtype discriminator          |
  * | `<system>.img` | `document.img` |
  * | `<system>.items` | `document.items` — actors only |
  * | `<system>.effects` | `document.effects` |
@@ -47,7 +47,7 @@
  *
  * 1. `S.system.<to>` — authored directly, wins outright;
  * 2. `S.<legacyKey>` — the legacy in-block position the corpus still writes,
- *    kept until #126 moves it;
+ *    kept until the corpus moves it;
  * 3. the shared top-level property the field **declares** as its source, which
  *    may be a dotted path (`data.portrait`) rather than a sibling key;
  * 3b. for a `data.` source, the bare top-level key that container gathered it
@@ -56,15 +56,15 @@
  *
  * ## Steps 2 and 3 are two declarations, because they are two positions
  *
- * They used to be one: both were keyed on `name`, which was fine only while the
- * shared source and the in-block key were the same word. `data:` (#128) ended
+ * They are not one: keying both on `name` holds only while the
+ * shared source and the in-block key were the same word. `data:` ended
  * that — a shared source is now a path *into* a container, so `data.species`
  * and `species` are two spellings of two different places, and no single value
  * of `name` reached both. `name: "species"` read `hm3.species` and could not
  * see `data.species`; `name: "data.species"` read the shared source and could
  * not see `hm3.species`. Each yielded the field's **default** wherever only the
  * other position was authored — silently, since the field compiles and the
- * document is emitted with the value simply gone (#305).
+ * document is emitted with the value simply gone.
  *
  * That made every move into `data:` a flag day. Each of this package's other
  * retirements — `package:`, `image`, `archetype`, `relation` — works because
@@ -77,11 +77,11 @@
  * that declares one is mid-sweep by construction, which is what
  * {@link module:engine/field-spec.readsLegacyKey} reports on.
  *
- * ## Step 3 has a retiring position too, and it is derived (#332)
+ * ## Step 3 has a retiring position too, and it is derived
  *
  * `legacyKey` retires the *in-block* position, and for a while that looked like
  * the whole of what `data:` left behind. It is not. The facts `data:` holds
- * were not invented by it — #128 **gathered** them out of the note's open top
+ * were not invented by it — the sweep **gathered** them out of the note's open top
  * level, where `portrait:` sat beside `img:` and `shortcode:` — so a field that
  * declares `data.portrait` has two shared spellings to read, not one, and
  * reading only the current one is the same silent miss `legacyKey` exists to
@@ -112,7 +112,7 @@
  * It was not a harmless coincidence either, because step 3 answers **without**
  * applying `field.default` — only step 2 does — so an authored `title: null`
  * reached the field's coercion unguarded and shipped as the literal string
- * `"null"` in fifteen documents (#218).
+ * `"null"` in fifteen documents.
  *
  * So a field may declare `topLevelMeans`: what the top-level key of that name
  * means *instead*. Declaring it removes the whole shared level — step 3 and the
@@ -132,9 +132,8 @@
  *
  * A block is addressed by name, and the name arrives from the caller — a
  * system's own document-subtype map declares it (`DocumentSubtypeMap.block`).
- * That is the `engine/` ÷ `sohl/` line this package draws everywhere else
- * (#36): note-format knowledge here, game-system knowledge in the system's own
- * half.
+ * That is the `engine/` ÷ `sohl/` line this package draws everywhere else:
+ * note-format knowledge here, game-system knowledge in the system's own half.
  *
  * @module
  */
@@ -393,7 +392,7 @@ const DATA_PREFIX = "data.";
 /**
  * The bare top-level key a `data:`-sourced field is being swept off — step 3b.
  *
- * `data:` (#128) did not invent the facts it holds; it *gathered* them, out of
+ * `data:` did not invent the facts it holds; it *gathered* them, out of
  * the note's open top level where each was a sibling of `img` and `shortcode`.
  * So the retiring spelling of `data.portrait` is not a second declaration
  * anyone has to write — it is `portrait`, mechanically, and the same holds for
@@ -466,8 +465,8 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
 
     // 2. The legacy in-block position, keyed on `legacyKey` — the shared
     //    source is a path into `data:` and the in-block key is a bare word, so
-    //    the two are declared separately (#305). Every note in every tree
-    //    writes here today, and will until #126 moves them; dropping it would
+    //    the two are declared separately. Every note in every tree
+    //    writes here today, and will until the corpus moves them; dropping it would
     //    be a corpus migration disguised as a mechanism change.
     const declared = systemBlock(fm, block);
     const legacyKey = legacyKeyOf(field);
@@ -482,14 +481,14 @@ export function resolveFieldValue(field, fm, { block = "sohl" } = {}) {
 
     // 3. The shared property this field declares as its source — unless the
     //    field declares that the top-level key of that name means something
-    //    else, in which case there is no shared position to read (#218).
+    //    else, in which case there is no shared position to read.
     if (field.topLevelMeans === undefined) {
         const shared = getFrontmatter(fm, field.name, undefined);
         if (shared !== undefined) return { value: shared, from: "shared" };
 
         // 3b. The bare top-level key the `data:` source was gathered off — the
         //     retiring *shared* position, exactly as `legacyKey` is the
-        //     retiring *in-block* one (#332). Without it a field declaring
+        //     retiring *in-block* one. Without it a field declaring
         //     `data.portrait` cannot see the `portrait:` every tree still
         //     writes, and the miss arrives at the caller's `?? default` as an
         //     ordinary absence: 646 `sohl-thalorna` beings compiled the generic
@@ -556,7 +555,7 @@ export function systemDataPaths(data, prefix = "") {
  *
  * It stayed invisible while those maps were authored *outside* `<system>.system`
  * and so were never walked. The moment the corpus moves them to the destination
- * (#126) every one of them lights up — 62 findings on `sohl-thalorna` alone,
+ * every one of them lights up — 62 findings on `sohl-thalorna` alone,
  * none of them a defect.
  *
  * So descent is conditional on the schema declaring something *beneath* the
@@ -621,7 +620,7 @@ function declaresChildren(declared, path) {
  * @param {object} options - Options.
  * @param {Iterable<string>} options.known - The keys this system declares on
  *   top of the shared vocabulary: its generators, its toolchain keys, and —
- *   until #126 moves them — the field names its notes still author in the
+ *   until the corpus moves them — the field names its notes still author in the
  *   block.
  * @returns {string[]} The unrecognized keys, in authored order.
  */

package/engine/systems.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The closed registry of system ids, and the `none` that stands for no system
- * at all (#59).
+ * at all.
  *
  * A canonical address carries the system in a fixed position —
  * `harnadventures-none-being-grod` — so "which systems exist" is a question the
@@ -47,7 +47,7 @@
 
 // The one charset, read rather than restated — a system id is an address
 // segment like any other, and a second spelling of the pattern is how the
-// disagreements in #202/#203 happened.
+// disagreements between them arise.
 import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
 
 /**

package/engine/web-wikilinks.mjs

@@ -22,7 +22,7 @@
  *   `[[type-shortcode#slug|Text]]`  → `[Text](/section/slug/#slug)`
  *   `[[#slug|Text]]`                → `[Text](#slug)`
  *
- * **Every link is an address and carries a label** (#180). One written without
+ * **Every link is an address and carries a label**. One written without
  * a label addresses nothing and is reported — see
  * {@link unlabelledLinkMessage}, which states the rule for this build and the
  * pack build together.
@@ -34,22 +34,22 @@
  * Lives here rather than in a consumer so every package resolves a link the
  * same way. `sohl-thalorna` carried a forked copy of this as
  * `utils/site-wikilinks.mjs`, already 3 KB adrift from the original, which is
- * exactly the drift one rule with two implementations produces (#20).
+ * exactly the drift one rule with two implementations produces.
  */
 
 // How an address *parses* is the pack build's own rule, so the two builds
 // cannot drift apart on it: they disagreed once over the unlabelled hyphen
 // form, which the packs showed as a raw shortcode and the knowledgebase as a
-// name (#1409).
+// name.
 import { readQualifier } from "./wikilinks.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The canonical `package-system-type-shortcode` key, so a package-qualified
 // address is matched the way a vendored manifest publishes it — by the
-// segments the target supplies, with the system wildcarded unless stated (#59).
+// segments the target supplies, with the system wildcarded unless stated.
 import { canonicalKey, expandAddress, readCanonicalKey } from "./content-address.mjs";
 import { NO_SYSTEM } from "./systems.mjs";
 // The one rule about a link's shape both builds share: it carries a label, and
-// {@link unlabelledLinkMessage} is the one place that says so (#180).
+// {@link unlabelledLinkMessage} is the one place that says so.
 import { unlabelledLinkMessage } from "./wikilink-syntax.mjs";
 // One slug rule for the whole build — see `./content-slug.mjs`. This module
 // carried a copy that dropped non-ASCII letters rather than transliterating
@@ -68,7 +68,7 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  * parse as an address at all.
  *
  * The KB index is keyed by the canonical `type/shortcode`, so a target written
- * in the hyphen separator — which is what the content tree authors (#1398) —
+ * in the hyphen separator — which is what the content tree authors —
  * has to be rewritten to it before lookup. The target is read by the pack
  * build's own {@link readQualifier}, so recognising an address and resolving
  * one can never disagree: the two separators and the optional leading package
@@ -77,7 +77,7 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  * It takes the **parsed** qualifier rather than the raw target because the
  * caller needs the parse for a second purpose: `unknown-type` and
  * `not-an-address` are different findings with different fixes, and only the
- * `reason` tells them apart (#184). Reading the target twice would let the two
+ * `reason` tells them apart. Reading the target twice would let the two
  * readings drift.
  *
  * The build indexes an item note under both `skill/climb` and `docskill/climb`,
@@ -88,7 +88,7 @@ import { authoredLabel, WIKILINK, isSamePage, parseWikilink } from "./wikilink-s
  */
 function lookupRead(index, read, contentPackage) {
     if (!read || read.reason) return undefined;
-    // Every omitted segment defaults from where the link is written (#336) —
+    // Every omitted segment defaults from where the link is written —
     // package from the citing package, system from the block, which on a page
     // body is `none` — so the target expands to exactly one canonical address
     // and this is a plain lookup. No filter, no single-hit rule, and no
@@ -104,7 +104,7 @@ function lookupRead(index, read, contentPackage) {
     // A local target may also be keyed by its short form. On the KB that is not
     // a second answer: an item note renders as **one page** which is its own
     // documentation, so `skill/climb`, `docskill/climb` and both canonical
-    // addresses are all the same value (#1362) — the fallback cannot pick
+    // addresses are all the same value — the fallback cannot pick
     // differently, only earlier. It stays because an index built before the
     // canonical documentation key was added still carries the short one, and
     // because a page collision here is caught by the site index's own
@@ -127,10 +127,10 @@ function lookupRead(index, read, contentPackage) {
  * This is deliberately identical to the pack compiler's own `unresolvedLink`,
  * down to the class name and the `title` wording. One authored link renders on
  * two surfaces, and the two builds have drifted before over exactly this kind
- * of detail (#1409) — matching markup is what keeps a reader's cue the same in
+ * of detail — matching markup is what keeps a reader's cue the same in
  * a journal and on the page. Duplicated rather than imported only because the
  * function is not exported from `@heroiclands/package-build`; hoisting it there
- * is HeroicLands/content-build#13.
+ * is.
  *
  * The knowledgebase renders with `unsafe = true` (`kb/hugo.toml`), so raw HTML
  * in generated markdown reaches the page. That makes escaping obligatory: this
@@ -154,7 +154,7 @@ function unresolvedLink(text, target) {
 }
 
 /**
- * How a link to a **draft** note renders (#183).
+ * How a link to a **draft** note renders.
  *
  * A note tagged `draft` exists so a link into it is not dead, and nothing more.
  * Unmarked, a reader follows a promising link into an empty page and an author
@@ -173,8 +173,8 @@ function unresolvedLink(text, target) {
  * **Byte-identical with the pack build's copy** in `wikilinks.mjs`, down to the
  * class name and the `title` wording — one authored link renders on two
  * surfaces, and the two builds have drifted before over exactly this kind of
- * detail (#1409). Duplicated rather than imported for the same reason
- * {@link unresolvedLink} is; hoisting both is HeroicLands/content-build#13.
+ * detail. Duplicated rather than imported for the same reason
+ * {@link unresolvedLink} is; hoisting both is.
  *
  * The argument is already-built markup and is deliberately not escaped; the
  * *authored* text inside it was escaped, or made into a link, by the caller.
@@ -198,7 +198,7 @@ function draftLink(inner) {
 const FRONTMATTER_WIKILINK = new RegExp(WIKILINK.source, "g");
 
 /**
- * Every wikilink authored inside a frontmatter value (#1428).
+ * Every wikilink authored inside a frontmatter value.
  *
  * Wikilinks are resolved in a note's **body** — by {@link resolveWebWikilinks}
  * here, and by the pack compilers' `convertWikilinks` for Foundry. Frontmatter
@@ -267,19 +267,19 @@ function isPlainMap(value) {
  * `section/slug`), then in the vendored `ctx.foreign` manifests. A target is a
  * *partial* address: an omitted package means this package, an omitted system
  * is a wildcard, and exactly one match resolves — two are `ambiguous`. A link written
- * without a label addresses nothing at all and is reported as such (#180) —
+ * without a label addresses nothing at all and is reported as such —
  * there is no second namespace left for it to name.
  *
  * Only a slash-qualified target reaches the raw key, which is what keeps
  * `section/slug` addressable without a page's own slug answering for it.
  *
- * **Every target that resolves nowhere fails the build** (#184), and is
+ * **Every target that resolves nowhere fails the build**, and is
  * classified into the vocabulary all three resolvers share — `unlabelled`,
  * `not-an-address`, `unknown-type`, `ambiguous`, `unresolved`. Failures are
  * collected in `ctx.errors`, each carrying the authored `link` and its
  * `occurrence` so a caller can report the line and column it sits on.
  *
- * There used to be one exception: a hyphen-form address was let through while
+ * There is deliberately no exception letting a hyphen-form address through while
  * any linkable package had no vendored manifest, since a real cross-package
  * reference and a typo look identical from here. The pack compilers and the
  * link checker never made that allowance, so its only surviving effect was to
@@ -287,13 +287,13 @@ function isPlainMap(value) {
  * instead.
  *
  * A target that resolves nowhere still renders through {@link unresolvedLink}
- * rather than as bare prose (#1665): the author's text is kept, marked so a
+ * rather than as bare prose: the author's text is kept, marked so a
  * reader can see a link was intended. The marking and the failure are separate
  * jobs and always were — the mark is for whoever reads the page a *previous*
  * build emitted, the failure is for the author of this one.
  *
  * A target that **resolved** to an entry with no page is not this case and is
- * not marked: a pack-only package (#1516) publishes Foundry addresses and no
+ * not marked: a pack-only package publishes Foundry addresses and no
  * web pages, so the author wrote a real address and there is simply nothing to
  * link to.
  *
@@ -302,7 +302,7 @@ function isPlainMap(value) {
  *   foreign, type, errors, src, file }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type; `foreign`
- *   is the cross-package manifest index (#1446). `src` is the page's display
+ *   is the cross-package manifest index. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
  *   stands in.
  * @returns {string} The body with wikilinks rewritten.
@@ -311,7 +311,7 @@ export function resolveWebWikilinks(body, ctx) {
     // How many times each authored link has been seen, so two identical links
     // on one page are located at their own positions in the source file — the
     // same counting the checker does, and what turns a finding into a
-    // `file:line:column:` diagnostic rather than a note-wide one (#17, #184).
+    // `file:line:column:` diagnostic rather than a note-wide one.
     const seen = new Map();
     /**
      * Records a finding, and returns the marked-up link it renders as.
@@ -338,16 +338,16 @@ export function resolveWebWikilinks(body, ctx) {
     };
 
     // Code is verbatim: a `[[…]]` inside a code fence, an indented block or an
-    // inline span is source text, not a link (#1505).
+    // inline span is source text, not a link.
     return replaceOutsideCode(body, WIKILINK, (all, rawInner) => {
         const parsed = parseWikilink(rawInner);
         const { target, anchor, display } = parsed;
         // An empty label is not a label: `[[x|]]` addresses the target and
-        // shows its name, so `""` falls through to the same place `null` does
-        // (#113). One reading, from {@link authoredLabel}.
+        // shows its name, so `""` falls through to the same place `null` does.
+        // One reading, from {@link authoredLabel}.
         const label = authoredLabel({ display });
 
-        // **Every link carries a label** (#180). Without one there is nothing
+        // **Every link carries a label**. Without one there is nothing
         // to resolve against — the alias namespace a bare `[[Text]]` named is
         // retired — and nothing to show either, a shortcode being an address
         // rather than prose. Reported before the same-page form, because the
@@ -362,7 +362,7 @@ export function resolveWebWikilinks(body, ctx) {
             return `[${label ?? anchor}](#${slugify(anchor)})`;
         }
 
-        // The canonical separator (#1398) has to be resolved, not merely
+        // The canonical separator has to be resolved, not merely
         // recognised. `null` here means the target is not an address at all,
         // which is a defect: there is no other namespace to try.
         const read = readQualifier(target, ctx.contentTypes ?? new Set(), ctx.packages);
@@ -374,10 +374,10 @@ export function resolveWebWikilinks(body, ctx) {
             // a page's bare slug cannot answer for an address.
             (rawKey.includes("/") ? ctx.index.get(rawKey) : undefined) ??
             // A manifest entry carries the same `{ url, name }` shape as a
-            // local one (#1446), so a cross-package hit needs no special case
+            // local one, so a cross-package hit needs no special case
             // below. Local wins: a live build is authoritative and a vendored
             // manifest can only be staler.
-            // A short form names *this* package (#336), so it never reaches a
+            // A short form names *this* package, so it never reaches a
             // vendored manifest; only a fully qualified address does.
             (ctx.foreign && read?.package ?
                 lookupRead(ctx.foreign, read, ctx.contentPackage)
@@ -387,8 +387,8 @@ export function resolveWebWikilinks(body, ctx) {
             // shortcode is not display text), so the document's **current**
             // name stands in and a rename shows at every citation.
             const text = label ?? hit.name;
-            // A pack-only package publishes Foundry addresses and no pages
-            // (#1516), so its entries carry no `path` and resolve to no URL.
+            // A pack-only package publishes Foundry addresses and no pages,
+            // so its entries carry no `path` and resolve to no URL.
             // The address is real — this is not a typo and must not fail the
             // build — but there is nothing on the web to point at, so the
             // reader gets the text and no href. Emitting the href anyway is
@@ -396,8 +396,8 @@ export function resolveWebWikilinks(body, ctx) {
             // as a link and goes nowhere.
             const link =
                 hit.url ? `[${text}](${anchor ? `${hit.url}#${slugify(anchor)}` : hit.url})` : text;
-            // A link into a note that exists but is not written renders marked
-            // (#183). Presentation only — the href above is unchanged, and a
+            // A link into a note that exists but is not written renders marked.
+            // Presentation only — the href above is unchanged, and a
             // `[[#anchor]]` self-link is not marked because the reader is
             // already on the page it would be telling them about.
             return hit.draft ? draftLink(link) : link;
@@ -413,7 +413,7 @@ export function resolveWebWikilinks(body, ctx) {
         // it parses as an address.)
         const siteAddress = prefix !== null && ctx.sections.has(prefix);
 
-        // **An address resolving nowhere is a failure, unconditionally** (#184).
+        // **An address resolving nowhere is a failure, unconditionally**.
         //
         // It was gated on a manifest-completeness check — while any linkable package was
         // invisible here, `Rules/Bestiary.md` addressing `being-grkrahk` in the
@@ -443,7 +443,7 @@ export function resolveWebWikilinks(body, ctx) {
             : read?.reason === "unknown-type" ? "unknown-type"
                 // Every link is an address, and this is not one. Distinct from
                 // a dead address, because the fix is different: a name has to
-                // become an address, not be corrected (#180).
+                // become an address, not be corrected.
             : "not-an-address";
 
         // Whether or not it failed the build, the link renders marked: the

package/engine/wikilink-syntax.mjs

@@ -29,7 +29,7 @@
  * The web side's pattern omitted `\n` from the excluded set, so an unclosed
  * bracket consumed everything up to the next `]]` anywhere in the document —
  * the same shape of corruption a hand-rolled code-fence regex caused on the one
- * page whose subject is link syntax (SoHL#1665). It was also internally
+ * page whose subject is link syntax. It was also internally
  * inconsistent: its *frontmatter* scan excluded newlines while its body scan did
  * not.
  *
@@ -45,7 +45,7 @@
  * ({@link LINK_FINDING_REASONS}) and the message each one reports through
  * ({@link linkFindingMessage}). Three builds read one authored link; an author
  * meets whichever ran first, and a consumer switching on a `reason` should not
- * be switching on which build produced it (#184).
+ * be switching on which build produced it.
  *
  * @module
  */
@@ -72,7 +72,7 @@ export const WIKILINK = /\[\[([^\]\n]+)\]\]/g;
  * @property {string|null} display - The text after `|`, or `null` when the link
  *   is unlabelled. `null` and `""` differ: an author may write `[[x|]]`.
  * @property {boolean} labelled - Whether a `|` was present at all. A link
- *   without one addresses nothing and is a finding (#180) — see
+ *   without one addresses nothing and is a finding — see
  *   {@link unlabelledLinkMessage} — so every reader has to be able to ask.
  */
 
@@ -111,12 +111,12 @@ export function parseWikilink(rawInner) {
  * `display: null` does. The two are still distinguishable through
  * {@link ParsedWikilink.labelled}, which is the thing that genuinely differs:
  * `[[x|]]` is labelled and `[[x]]` is not, and only the first addresses
- * anything (#180).
+ * anything.
  *
  * Stated here because the two resolvers had already drawn the line in two
  * places and drawn it differently: the packs tested falsiness and were right,
  * the web tested `??` — which falls through on `null` only — and emitted
- * `[](/url/)`, a link with no clickable text, through every build (#113). That
+ * `[](/url/)`, a link with no clickable text, through every build. That
  * is the same drift this module exists to prevent, in the case its own
  * {@link ParsedWikilink} docstring calls out. One reading, one place.
  *
@@ -136,12 +136,12 @@ export function authoredLabel({ display }) {
  * the form to write rather than a value to correct: there is no value that
  * makes an unlabelled link resolve.
  *
- * **Why there is nothing left for a bare link to mean** (#180). The pipe used
+ * **Why there is nothing left for a bare link to mean**. The pipe used
  * to select between two namespaces — address and alias — and the alias one was
  * empty in practice: across 8,305 wikilinks in three content trees, not one
  * bare `[[Alias]]` resolved to a note. What the index it looked up in *did* do
  * was fold every note's `name.full` into itself, which forbade two notes of a
- * type from sharing a display name (#179). So the namespace is gone, every
+ * type from sharing a display name. So the namespace is gone, every
  * link is an address, and an address needs the pipe that says so.
  *
  * The **link part may still be an anchor**: `[[#slug|Text]]` addresses a
@@ -160,16 +160,16 @@ export function unlabelledLinkMessage(target) {
 }
 
 /**
- * Every way a link can fail, named once for all three resolvers (#184).
+ * Every way a link can fail, named once for all three resolvers.
  *
  * A link is read in three places — the checker (`content-links.mjs`), the pack
  * compilers (`wikilinks.mjs`) and the web resolver (`web-wikilinks.mjs`) — and
- * each used to name the failures in its own words. `unknown` in one was
+ * each would otherwise name the failures in its own words. `unknown` in one is
  * `unresolved` in another and `broken type/shortcode` in the third, so a
  * consumer switching on a `reason` was switching on which build had produced
  * it. The set is closed and lives here, beside the syntax the three share.
  *
- * - `unlabelled` — no `|`, so the link addresses nothing (#180).
+ * - `unlabelled` — no `|`, so the link addresses nothing.
  * - `not-an-address` — labelled, but the target does not parse as an address.
  * - `unknown-type` — definitely qualified, but names no type this build knows.
  * - `unresolved` — parses as an address, and nothing publishes it.
@@ -198,12 +198,12 @@ export const LINK_FINDING_REASONS = Object.freeze(
  * package publishing it is not a declared dependency — or is one whose index
  * has not been fetched — and the link itself looks identical in every case.
  *
- * This used to be a **warning** in the checker and, in the site build, nothing
+ * As a **warning** in the checker and, in the site build, nothing
  * at all until every linkable package's manifest was accounted for — on the
  * reasoning that a bare `[[Name]]` might be a placeholder for a note nobody had
- * written yet. That reasoning was a property of the bare form, which is retired
- * (#180); the intent behind it now has a real spelling, a `draft`-tagged note
- * that exists and resolves and renders marked (#183). So an address naming no
+ * written yet. That reasoning was a property of the bare form, which is retired;
+ * the intent behind it now has a real spelling, a `draft`-tagged note
+ * that exists and resolves and renders marked. So an address naming no
  * note is a typo or an omission, both want fixing, and all three builds say so.
  *
  * @param {string} target - The address as authored, named in the message.
@@ -226,9 +226,9 @@ export function unresolvedAddressMessage(target) {
  * message names the claimants so the author can choose between them without
  * going looking.
  *
- * **The correction is the canonical form**, all four segments (#59). Omission
+ * **The correction is the canonical form**, all four segments. Omission
  * runs strictly left to right, so there is no `package-type-shortcode` to offer
- * — naming a package means naming the system before the type. That used to be
+ * — naming a package means naming the system before the type. That would be
  * the correction here, back when a written target could state three segments at
  * most; the grammar is positional now, and a three-segment target names a
  * *system*, not a package.