@heroiclands/package-build 20.3.1 → 20.4.0

package/engine/homepage.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The package homepage — a note that compiles to a **page** rather than to a
- * compendium document (#51).
+ * compendium document.
  *
  * Every HeroicLands package is reachable at `https://www.heroiclands.org/<contentPackage>/`,
  * and what a reader finds there is one markdown file in the content tree,
@@ -49,11 +49,11 @@
  *
  * **Addressed like every other note.** A homepage declares a `shortcode` —
  * conventionally {@link HOMEPAGE_SHORTCODE} — and publishes at its address,
- * `/<package>/<type>-<shortcode>/`, written by the same rule as everything else
- * (#182). It used to publish at `/<package>/` from a fixed destination, and
+ * `/<package>/<type>-<shortcode>/`, written by the same rule as everything else.
+ * It used to publish at `/<package>/` from a fixed destination, and
  * that is why it refused `name` and `shortcode`: a URL derived from `name.full`
  * while the destination did not, so `[[homepage-<shortcode>]]` resolved *green*
- * to a page nothing wrote. A page's URL is its address now (#181), so the
+ * to a page nothing wrote. A page's URL is its address now, so the
  * computed address is the published one and there is nothing left to refuse.
  * The package's own `/<package>/` becomes a redirect its repository authors —
  * see `CONTENT.md` — rather than a page this build writes.
@@ -108,7 +108,7 @@ export const HOMEPAGE_SHORTCODE = "root";
  * The file a homepage is written to, relative to the package's site root.
  *
  * Its **address**, flat at the package root, and stated in the page's own `url`
- * — the same separation every other page has since #181, where the directory
+ * — the same separation every other page has, where the directory
  * decides the Hugo section and the front matter decides the URL. Flat rather
  * than inside a `homepage/` section directory, because a homepage is not one of
  * a kind: a section holding exactly one page would publish a landing at
@@ -133,14 +133,14 @@ export function isHomepage(fm) {
 }
 
 /**
- * The top-level field a homepage refuses, and what it would decide (#53).
+ * The top-level field a homepage refuses, and what it would decide.
  *
- * **One field, where there used to be three.** `name` and `shortcode` were
+ * **One field rather than three.** `name` and `shortcode` are
  * refused because a page's URL derived from `name.full` while a homepage's
  * destination was fixed, so the address a `shortcode` computed named a page the
- * site build never wrote. A page's URL is its address now (#181) and a homepage
+ * site build never wrote. A page's URL is its address now and a homepage
  * publishes at its own, so both fields decide exactly what they decide
- * everywhere else and are permitted (#182).
+ * everywhere else and are permitted.
  *
  * `id` is untouched by that, and stays: it is the Foundry document id a
  * compendium UUID is built from, and a homepage compiles into no document.
@@ -153,7 +153,7 @@ export function isHomepage(fm) {
  * package-build release.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
- * on every note whatever its type (#180), so it is answered there rather than
+ * on every note whatever its type, so it is answered there rather than
  * here.
  *
  * @type {ReadonlyMap<string, string>}
@@ -195,8 +195,8 @@ export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
  * **A refused field must be one the note *wrote*.** `resolveNoteId` fills
  * `fm.id` **in place** so every downstream reader sees one derived value —
  * deliberately, and documented as such — and this ran over the same object, so
- * a homepage that authors no `id` was told to delete one that is not there
- * (#319). Since the caller already owns the raw note text, it also answers
+ * a homepage that authors no `id` was told to delete one that is not there.
+ * Since the caller already owns the raw note text, it also answers
  * which keys the note actually declared; without an answer every key in `fm`
  * counts, which is the old behaviour and right for a caller holding authored
  * frontmatter only.
@@ -238,19 +238,17 @@ export function checkHomepageAddressFields(fm, { isAuthored } = {}) {
 }
 
 /**
- * Require exactly one homepage note in a content tree (#52).
+ * Require exactly one homepage note in a content tree.
  *
  * "Exactly one" is two rules, and they are **one severity** because they are
  * one defect: a package whose front page is not the page a person chose.
  *
  * - _None_ and the package serves nothing at `/<package>/`. That is the failure
- *   #50 exists to prevent, and it is silent — the site build reports `wrote 0
+ *   this exists to prevent, and it is silent — the site build reports `wrote 0
  *   homepage(s)` and exits 0.
  * - _Two_ and it serves a page nobody chose. **This is a cardinality rule, and
- *   since #182 it is only that.** It used to rest on the fixed destination
- *   every homepage shared — the second overwrote the first — so the address
- *   rule enforced it as a side effect. A homepage is written at its own address
- *   now, so two of them publish two pages and collide over nothing; the
+ *   only that.** A homepage is written at its own address, so two of them
+ *   publish two pages and collide over nothing; the
  *   duplicate-address check catches only the pair that happen to share a
  *   shortcode, and says nothing at all about a `homepage-root` beside a
  *   `homepage-front`. Which of the two the redirect at `/<package>/` should
@@ -375,17 +373,17 @@ export function homepageTitle(fm, config) {
  *
  * The note's own, plus the derived values every emitted page carries: the
  * resolved `title`, the package the build derived — no note declares one
- * (`package:` is retired, #56) and the theme's breadcrumb partial reads
+ * (`package:` is retired) and the theme's breadcrumb partial reads
  * `.Params.package` — and its **address**.
  *
  * The address is stated as `url` for the same reason every other page states
- * one (#181): Hugo publishes a page where its file sits unless told otherwise,
+ * one: Hugo publishes a page where its file sits unless told otherwise,
  * and a homepage's file sits at the package's site root. `slug` is written
  * beside it because it is the last segment of that address and Hugo's own key
  * for one; it decides nothing while `url` is present, but a page carrying only
  * `url` would report a slug Hugo had inferred from the filename.
  *
- * **Site-root relative, and so carrying no package base** (#217), exactly as
+ * **Site-root relative, and so carrying no package base**, exactly as
  * `pageFrontmatter` states a content page's: Hugo resolves a `url`
  * against `baseURL`, whose path is already where the package is served, so a
  * stated base was written twice and published the landing at
@@ -394,7 +392,7 @@ export function homepageTitle(fm, config) {
  *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
- * redirect stub at each one. The field is retired (#180) and refused before a
+ * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
  * @param {object} fm - The note's frontmatter.

package/engine/ids.mjs

@@ -40,8 +40,8 @@ export function makeId(namespace, value) {
 }
 
 /**
- * Every content type that compiles into a Foundry `Scene` — a **map note**
- * (#1525). The three differ only in derived canvas defaults, which is the map
+ * Every content type that compiles into a Foundry `Scene` — a **map note**.
+ * The three differ only in derived canvas defaults, which is the map
  * compiler's business; everything else treats them alike.
  *
  * Declared in this leaf module because several passes that must not depend on
@@ -56,7 +56,7 @@ export const MAP_TYPES = Object.freeze(new Set(["map"]));
 /**
  * The map subTypes, which differ only in the canvas defaults derived for them.
  *
- * They were three *types* until #174, which cost three entries in the pack
+ * As three *types* they would cost three entries in the pack
  * router, three in the claims set and three in every consumer's section config
  * — for one idea that the specification had always described as one type.
  *
@@ -74,8 +74,8 @@ export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap
  * addressed as `<type>` and `doc<type>`. These are one, so there is no
  * `docplace` and nothing synthesizes one.
  *
- * `doc` was the only member until #241. `place`, `lore` and `scenario` are in
- * the published content format and were declared for validation in #233, but
+ * `doc` was the only member until. `place`, `lore` and `scenario` are in
+ * the published content format and are declared for validation, but
  * nothing routed them: a note of one lint-ed clean and then compiled into
  * nothing, because {@link PACK_BY_TYPE} did not name it and the open-set
  * default sent it to the items pack. `sohl-thalorna` could not compile a single
@@ -95,7 +95,7 @@ export const JOURNAL_TYPES = Object.freeze(new Set(["doc", "place", "lore", "sce
  * building and not of the content: the same notes compiled by a different
  * repository belong to a different package. Baking the package into these
  * values is what made every link emitted by `sohl-thalorna` address the `sohl`
- * system (#1498) — correct here only by coincidence.
+ * system — correct here only by coincidence.
  *
  * @type {Readonly<Record<string, {pack: string, docType: string}>>}
  */
@@ -106,7 +106,7 @@ export const PACK_BY_TYPE = Object.freeze({
     macro: { pack: "macros", docType: "Macro" },
     being: { pack: "actors", docType: "Actor" },
     // A bundle is Foundry's `Adventure` — a set of document *copies* packaged
-    // for one-shot import (#259). The conventional name is `adventures`, which
+    // for one-shot import. The conventional name is `adventures`, which
     // is also what the scenes pass calls its **companion**; the two are
     // different packs and a repository shipping both names them apart, since
     // the router refuses a note that addresses a companion.
@@ -120,7 +120,7 @@ export const PACK_BY_TYPE = Object.freeze({
  * Content types that no longer exist, and what replaced each one.
  *
  * `character` and `creature` were retired in favour of the single `being` they
- * had always compiled into (SoHL#1580). They are recorded here rather than
+ * had always compiled into. They are recorded here rather than
  * simply deleted because deleting them is the one change that fails *quietly*:
  * every type not named in {@link PACK_BY_TYPE} falls through to the open item
  * set below, so a note or a link left on the old spelling would be routed to
@@ -137,7 +137,7 @@ export const RETIRED_TYPES = Object.freeze({
     character: "being",
     creature: "being",
     // The three map spellings, retired in favour of the single `map` whose
-    // subType they became (#174). Recorded rather than deleted for the same
+    // subType they became. Recorded rather than deleted for the same
     // reason as the two above: an unnamed type falls through to the open item
     // set, so a note or link left on one would be routed to the items pack.
     battlemap: "map",
@@ -178,7 +178,7 @@ export function assertTypeNotRetired(type, where) {
  * old one compiles into exactly the document it always did: refusing it would
  * fail a build over a note that is not wrong.
  *
- * So these retire in the three steps `package:` took (#56), and this table is
+ * So these retire in the three steps `package:` took, and this table is
  * the **first**: both spellings resolve, the current one is canonical, and the
  * retired one is *reported* — never refused. The sweep of the content trees and
  * the refusal come after, once no tree writes the old name. That is the same
@@ -186,7 +186,7 @@ export function assertTypeNotRetired(type, where) {
  * reason: a consumer must be able to adopt the new toolchain before its content
  * moves, and there are some 31,000 references to move.
  *
- * **Why these three, and why the other way round now.** #78 renamed
+ * **Why these three, and why this way round.** The specification renamed
  * `armorgear`, `concoctiongear` and `projectilegear` to `armor`, `concoction`
  * and `projectile`, on the argument that the suffix named the *SoHL document
  * subtype* a note compiled into rather than the thing the note is about. That
@@ -283,12 +283,12 @@ export const ITEM_PACK = Object.freeze({ pack: "items", docType: "Item" });
  * Item types are the open set — a new one is added whenever the system grows a
  * document type — so they are the **default** rather than an enumerated list. A
  * hand-maintained list is what made an entire content directory silently
- * unlinkable once (#1276); nothing to maintain, nothing to forget.
+ * unlinkable once; nothing to maintain, nothing to forget.
  *
  * The `docType` is the authority: it is a property of the *content type* and
  * holds however a repository names or splits its packs. The `pack` is the
  * conventional name only — a repository may rename its packs, or ship several
- * of one type (#1566), in which case the pack a particular note's document
+ * of one type, in which case the pack a particular note's document
  * lands in comes from `engine/pack-router.mjs` and is passed to
  * {@link compendiumUuid} explicitly. This module stays free of the
  * configuration so the link resolver above it can stay pure.
@@ -322,8 +322,8 @@ export function packForType(type) {
  * @param {string} id - The document's id.
  * @param {string} [packName] - The pack the document actually landed in, from
  *   the pack router. Supplied wherever the note is known, because a repository
- *   may ship several packs of one type and a UUID carries the pack name
- *   (#1566). Omitted only where there is no note to route — the conventional
+ *   may ship several packs of one type and a UUID carries the pack name.
+ * Omitted only where there is no note to route — the conventional
  *   name from {@link packForType} then stands in.
  * @returns {string} `Compendium.<packageId>.<pack>.<DocumentType>.<id>`
  */

package/engine/index-records.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The shape of a content-index record, and the accessors every reader of one
- * needs (#243).
+ * needs.
  *
  * **Why these live apart from the index that builds them.** Deriving records
  * reaches the pack router and the manifest emitter, and those reach the
@@ -38,7 +38,7 @@ import path from "node:path";
  * carry itself.
  *
  * `package` is the note's distribution unit — the configured `contentPackage`,
- * since a note declaring its own is a hard error (#56) — and it matches what
+ * since a note declaring its own is a hard error — and it matches what
  * the content-table expander puts on the same field, so a query reads the same
  * value from either. `file` namespaces the note's place in the tree, again
  * matching the expander's `file.*`.
@@ -69,9 +69,9 @@ export const DERIVED_KEYS = Object.freeze([
  * the machine that built the index, would differ between two checkouts of the
  * same tree, and would put someone's home directory in a published artifact. So
  * every pass that reads the index and then needs to open a note has to compose
- * the absolute form, and each of the readers converted for #243 had written its
+ * the absolute form, and each converted reader had written its
  * own `path.join(base, ...record.file.path.split("/"))`. Four copies of one
- * rule is what #243 exists to remove, so here it is once.
+ * rule is what this exists to remove, so here it is once.
  *
  * The split is on `"/"` rather than `path.sep` because the recorded path is
  * always POSIX — that is what makes the index identical on every platform.

package/engine/index.mjs

@@ -19,7 +19,7 @@
  * The content walk, frontmatter parsing, table generation, wikilink
  * resolution, id and folder derivation, the link manifest and the web-address
  * rule, `BasePackCompiler`, and the generic Foundry document compilers
- * (journals, macros, scenes) all live here (#1512).
+ * (journals, macros, scenes) all live here.
  *
  * **Each module is re-exported as its own namespace, not flattened.** Several
  * of them deliberately re-export a neighbour's symbol so a caller keeps one
@@ -51,13 +51,13 @@ export * as contentTree from "./content-tree.mjs";
 /** The consuming repository's resolved `package-build.config.yaml`. */
 export * as packConfig from "./pack-config.mjs";
 
-/** Which pack of a document type a note's document lands in (#1566). */
+/** Which pack of a document type a note's document lands in. */
 export * as packRouter from "./pack-router.mjs";
 
-/** Which note types a configuration compiles, and the notes nothing claims (#146). */
+/** Which note types a configuration compiles, and the notes nothing claims. */
 export * as noteClaims from "./note-claims.mjs";
 
-/** Folders as notes: the address index, the parent chain, and the emitted `Folder` (#256). */
+/** Folders as notes: the address index, the parent chain, and the emitted `Folder`. */
 export * as folderNotes from "./folder-notes.mjs";
 
 /** The content package a build compiles, and the Foundry package it ships in. */
@@ -72,6 +72,9 @@ export * as retiredFields from "./retired-fields.mjs";
 /** Schema fields a note may never declare, because play writes them. */
 export * as runtimeOnlyFields from "./runtime-only-fields.mjs";
 
+/** `system` keys a note may never declare, because the compiler derives them. */
+export * as derivedFields from "./derived-fields.mjs";
+
 /** The package homepage: the note type that compiles to a page, not a document. */
 export * as homepage from "./homepage.mjs";
 
@@ -95,13 +98,13 @@ export * as contentAddress from "./content-address.mjs";
 /** Which note-type → document-subtype maps this toolchain ships. */
 export * as subtypeRegistry from "./subtype-registry.mjs";
 
-/** The id a note's document is filed under: its pin, or its address (#270). */
+/** The id a note's document is filed under: its pin, or its address. */
 export * as noteIds from "./note-ids.mjs";
 
-/** The shortcodes a note declares it used to be published under (#278). */
+/** The shortcodes a note declares it used to be published under. */
 export * as noteRenames from "./note-renames.mjs";
 
-/** The published content index packages exchange addresses through (#239). */
+/** The published content index packages exchange addresses through. */
 export * as metadataIndex from "./metadata-index.mjs";
 
 /** Deriving this package's own link manifest from its content tree. */
@@ -122,6 +125,9 @@ export * as contentCharset from "./content-charset.mjs";
 /** Naming an interface icon in a note, without drawing one there. */
 export * as contentIcons from "./content-icons.mjs";
 
+/** Raw HTML in a note's prose, which no book renderer can read. */
+export * as contentHtml from "./content-html.mjs";
+
 /** Resolving every link in a tree, and the ones that land nowhere. */
 export * as contentLinks from "./content-links.mjs";
 
@@ -185,7 +191,7 @@ export * as compendiums from "./compendiums.mjs";
 // The region-event vocabulary stays flat as well as namespaced: the Foundry
 // runtime imports these three by name through
 // `@heroiclands/package-build/engine/region-events`, and they were part of this
-// barrel's surface before the pipeline arrived (#1510).
+// barrel's surface before the pipeline arrived.
 export {
     CURATED_REGION_EVENTS,
     EXCLUDED_REGION_EVENTS,

package/engine/item-compiler.mjs

@@ -14,7 +14,7 @@
 /**
  * **The Item pass, for any system** — everything about compiling a note into a
  * Foundry Item that is a fact about the *note format* rather than about a
- * particular game system (#139).
+ * particular game system.
  *
  * `sohl/items.mjs` was the whole of it, and every system-specific thing in it
  * was reached through one module-level constant read off SoHL's map. That is
@@ -55,24 +55,24 @@ import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId, itemDocPointer } from "./item-docs.mjs";
 // The whitelist and the per-type `system` builders both come from the resolved
 // configuration, so the types this pass claims and the builders it compiles
-// them with are one table — the consuming repository's, not this package's
-// (#1504/#1563).
+// them with are one table — the consuming repository's, not this package's.
 import { itemTypes, itemBuilder, itemArt, itemFields } from "./item-registry.mjs";
 import { currentType } from "./ids.mjs";
 // Which Foundry Item subtype a note's `type` compiles into. Looked up in the
-// system's declared map, never inferred from the type itself (#79).
+// system's declared map, never inferred from the type itself.
 import { documentSubtype, subtypeRow } from "./document-subtypes.mjs";
 // The note-level `<system>:` block: `<system>.system` onto the document's
 // `system` verbatim, and `<system>.img` / `.effects` / `.flags` overriding
-// their shared top-level forms for this system alone (#58).
+// their shared top-level forms for this system alone.
 import { blockField, blockProperty, claimedPaths, mergeSystemData } from "./system-block.mjs";
 // The other direction of the same declaration: a field the *document* writes in
-// play, which a note may not author and the builder does not emit (#330).
+// play, which a note may not author and the builder does not emit.
+import { assertNoDerivedFields } from "./derived-fields.mjs";
 import { assertNoRuntimeOnlyFields } from "./runtime-only-fields.mjs";
 
 /**
  * The description an item carries: a pointer to its **item doc**, the
- * JournalEntry the journals pass compiles this same body into (#1348).
+ * JournalEntry the journals pass compiles this same body into.
  *
  * The prose is not rendered into the item at all. Carrying it would duplicate
  * it onto every actor holding the item — 7.59 MB of copies across the actors
@@ -112,7 +112,7 @@ export class SystemItemCompiler extends BasePackCompiler {
 
     /**
      * An Item **is** a system's data, so this pack takes only notes carrying
-     * this system's block (#58).
+     * this system's block.
      */
     static requiresSystemBlock = true;
 
@@ -168,10 +168,10 @@ export class SystemItemCompiler extends BasePackCompiler {
     /**
      * Every content type that compiles into an item **for this system**.
      *
-     * The whitelist is the consuming repository's `itemBuilders` keys (#1504),
+     * The whitelist is the consuming repository's `itemBuilders` keys,
      * and the system's own map is a second filter on top of it: a type this
      * system maps onto some *other* document class is not an item however a
-     * registry spells it, which is the "no wrongly-typed document" half of #79.
+     * registry spells it, which is the "no wrongly-typed document" half of.
      * A type the map does not name at all is left to the registry — see
      * {@link SystemItemCompiler#itemSubtype}.
      *
@@ -181,7 +181,7 @@ export class SystemItemCompiler extends BasePackCompiler {
     selects(fm) {
         // Through {@link currentType}: the registry is keyed by the current
         // spelling, and a note still on a renamed one compiles unchanged
-        // during the retirement window (#78).
+        // during the retirement window.
         if (!fm.type || !itemTypes().has(currentType(fm.type))) return false;
         const map = /** @type {typeof SystemItemCompiler} */ (this.constructor).documentSubtypes;
         const row = subtypeRow(/** @type {never} */ (map), fm.type);
@@ -189,16 +189,36 @@ export class SystemItemCompiler extends BasePackCompiler {
     }
 
     /**
-     * Refuse a note authoring one of its type's **runtime-only** fields (#330).
+     * The `system` keys this pass writes for itself, and where each is read
+     * from.
      *
-     * A schema declares fields the document writes for itself — an affliction's
-     * `onsetDate` is the world time its onset fired at — and a note authoring
-     * one used to compile, because `<system>.system` is a verbatim passthrough
-     * and the field really is in the schema. The result was shipped content
-     * carrying one world's play state, with the build reporting success.
+     * A note authoring one is refused, because the compiler writes the key
+     * unconditionally: the authored value is overwritten, or survives as the
+     * wrong type in a shipped document. Declared here rather than named in the
+     * refusal so that a second system states its own — see
+     * {@link module:engine/derived-fields}.
      *
-     * The declaration says which, so nothing here knows a field name; see
-     * {@link module:engine/runtime-only-fields}.
+     * @type {readonly {key: string, from: string}[]}
+     */
+    static derivedSystemKeys = Object.freeze([]);
+
+    /**
+     * Refuse a note authoring a field it may not write.
+     *
+     * Two rules, which differ in where the value would have come from:
+     *
+     * - **Runtime-only.** A schema declares fields the document writes for
+     *   itself — an affliction's `onsetDate` is the world time its onset fired
+     *   at. A note authoring one compiles, because `<system>.system` is a
+     *   verbatim passthrough and the field really is in the schema, and the
+     *   result is shipped content carrying one world's play state with the
+     *   build reporting success.
+     * - **Derived.** This pass writes some keys from the note itself, so an
+     *   authored one is overwritten or ships the wrong type.
+     *
+     * Both declarations say which fields, so nothing here knows a field name;
+     * see {@link module:engine/runtime-only-fields} and
+     * {@link module:engine/derived-fields}.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {void}
@@ -209,6 +229,11 @@ export class SystemItemCompiler extends BasePackCompiler {
             block: this.system,
             absPath: this.currentNote?.absPath,
         });
+        assertNoDerivedFields(
+            fm,
+            /** @type {typeof SystemItemCompiler} */ (this.constructor).derivedSystemKeys,
+            { block: this.system, absPath: this.currentNote?.absPath },
+        );
     }
 
     /**
@@ -217,7 +242,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * **Looked up, not inferred.** For every type this system declares, the
      * emitted subtype is the map's, so the note vocabulary and the document
      * vocabulary are two separately-stated things rather than one string
-     * written twice (#79).
+     * written twice.
      *
      * **A type the map does not name belongs to the consumer**, and its
      * registry entry is the declaration: a repository shipping an item type of
@@ -226,7 +251,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * subtype of. That is an authored statement in the consumer's own
      * configuration, not a coincidence inside this package's source — and
      * refusing it here would silently drop every document of a type this system
-     * has no opinion about (#7/#1563).
+     * has no opinion about.
      *
      * @param {object} fm - The note's frontmatter.
      * @returns {string} The document's `type`.
@@ -251,7 +276,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * Nothing by default, which is the honest position for a system that has
      * not said otherwise: a key written here lands on every document of every
      * type, so inventing one that the receiving DataModel does not declare
-     * would be a finding on the whole pack (#155).
+     * would be a finding on the whole pack.
      *
      * @param {object} fm - The note's frontmatter.
      * @param {object} at - What the pass already knows about this note.
@@ -278,7 +303,7 @@ export class SystemItemCompiler extends BasePackCompiler {
      * field for it and an undeclared `system` key is discarded at load without
      * a word.
      *
-     * **This is the one emitted key nothing else can check** (#283). A `system`
+     * **This is the one emitted key nothing else can check**. A `system`
      * key this pass invents is caught by the emitted-`system` check against the
      * receiving schema, but a flag is declared by no schema — so an omission
      * here is silent, and was: the Actor pass wrote the priority and this one
@@ -313,14 +338,14 @@ export class SystemItemCompiler extends BasePackCompiler {
         // Whatever the note authors under `<system>.system`, at the DataModel's
         // own paths. A path a declared field already writes is left to that
         // field: its value came from the same authored place and went through
-        // the field's own coercion (#58).
+        // the field's own coercion.
         mergeSystemData(built, fm, {
             block: system,
             claimed: claimedPaths(itemFields(type, system)),
         });
         this.reportUndeclaredSystemData(fm, system, "Item", subType);
         // And what *this* pass wrote on its own initiative, which no field
-        // declaration states and so no other check can see (#155). Read off the
+        // declaration states and so no other check can see. Read off the
         // assembled block, so a key added to `commonSystem` is checked without
         // anyone remembering to list it.
         this.reportEmittedSystemData(built, {
@@ -336,7 +361,7 @@ export class SystemItemCompiler extends BasePackCompiler {
         // Read through the system block like every other item field. There is
         // one spelling: `packFolder` names a folder note by its address, the
         // `folder:` id spelling having been retired with the per-pack YAML it
-        // resolved against (#251, #255, #260).
+        // resolved against.
         const folder = this.folderResolver(blockField(fm, system, "packFolder", null), {
             isAddress: true,
         });
@@ -345,9 +370,9 @@ export class SystemItemCompiler extends BasePackCompiler {
             name,
             // The note's `type` addresses the builder and the default art —
             // both registries are keyed by content type — while the document's
-            // own subtype comes from the system's map (#79).
+            // own subtype comes from the system's map.
             type: subType,
-            // Nullish, not `||` (#218): `resolveImg` returns `null` for a
+            // Nullish, not `||`: `resolveImg` returns `null` for a
             // note that names no art and `""` for one that wants none, and only
             // the first may be replaced by the type's default.
             img: resolveImg(blockProperty(fm, system, "img")) ?? itemArt(type, system),
@@ -355,7 +380,7 @@ export class SystemItemCompiler extends BasePackCompiler {
             system: built,
             effects: Array.isArray(effects) ? [...effects] : [],
             // Whatever the note authors, plus whatever this system records in
-            // flags because its data model has nowhere else for it (#283).
+            // flags because its data model has nowhere else for it.
             flags: this.commonFlags(fm),
             _stats: this.stats,
             ownership: { default: 0 },

package/engine/item-docs.mjs

@@ -18,13 +18,13 @@
  * An item note's body describes what the thing *is*. That is documentation, and
  * documentation belongs in the journals pack, so each item note compiles into a
  * JournalEntry and the item's `system.docHtml` becomes nothing but a `@UUID`
- * link to that entry's first page — the description-as-pointer convention
- * (#1356), which {@link sohl.utils.descriptionLinkTarget} recognises and
+ * link to that entry's first page — the description-as-pointer convention,
+ * which {@link sohl.utils.descriptionLinkTarget} recognises and
  * Display Description follows.
  *
  * The prose then exists once. Previously every actor carrying an item carried
  * its own copy of that item's description: 7.59 MB across the actors pack, of
- * which only 133 KB was distinct text (#1348). Nothing about actors changes —
+ * which only 133 KB was distinct text. Nothing about actors changes —
  * they embed whatever the item carries, and what the item carries is now a link.
  *
  * **Two passes, no shared state.** The items pass writes the pointer; the
@@ -34,9 +34,9 @@
  *
  * **The shape generalises.** A `macro` note is the same arrangement: it
  * compiles into a Macro, and its prose into a JournalEntry addressed
- * `docmacro/<shortcode>` (#1514). So is a **map note**, which compiles into a
- * Scene and whose prose becomes the place description its map pins point at
- * (#1525). {@link docEntryTypes} is the one set both the compilers and the
+ * `docmacro/<shortcode>`. So is a **map note**, which compiles into a
+ * Scene and whose prose becomes the place description its map pins point at.
+ * {@link docEntryTypes} is the one set both the compilers and the
  * link manifest read to know which types work this way.
  *
  * Plain ESM with no Foundry and no filesystem access, so it is unit-testable.
@@ -56,8 +56,7 @@ import { packRouter } from "./pack-router.mjs";
  *
  * It is the consuming repository's `itemBuilders` keys, resolved once in
  * `item-registry.mjs` alongside the builder lookup the Item compiler dispatches
- * through — one object, so the whitelist and the table cannot disagree
- * (#1504/#1563).
+ * through — one object, so the whitelist and the table cannot disagree.
  */
 export { itemTypes };
 
@@ -66,7 +65,7 @@ export { itemTypes };
  * addressed by the virtual `doc<type>` qualifier.
  *
  * Every item type, plus `macro` — a macro note's body documents the script the
- * note also compiles into a Macro (#1514), which is the same shape as an item
+ * note also compiles into a Macro, which is the same shape as an item
  * and its description: one note, two documents, the prose living in the
  * journals pack.
  *
@@ -102,7 +101,7 @@ export function hasDocEntry(type) {
     // registry's keys and those are the *current* spelling of a note type. A
     // note still on a renamed one carries its documentation journal exactly as
     // before — this is the one lookup between an item compiling and its prose
-    // silently compiling into nothing (#78).
+    // silently compiling into nothing.
     return docEntryTypes().has(String(currentType(type)));
 }
 
@@ -136,7 +135,7 @@ export function itemDocEntryId(itemId) {
  * happens to contain a link, which the runtime would then show verbatim.
  *
  * @param {string} packageId - The Foundry package shipping the journals pack.
- *   Supplied rather than assumed (#1498).
+ *   Supplied rather than assumed.
  * @param {string} itemId - The item note's `id` frontmatter.
  * @param {string} name - The item's name, used as the link's label. It shows
  *   only if the target ever fails to resolve, where a broken link naming the
@@ -147,8 +146,7 @@ export function itemDocEntryId(itemId) {
  */
 export function itemDocPointer(packageId, itemId, name, firstPageId) {
     // An item doc is a *derived* document: it lands in the default
-    // JournalEntry pack whatever Item pack the item itself was routed to
-    // (#1566).
+    // JournalEntry pack whatever Item pack the item itself was routed to.
     const entryUuid = compendiumUuid(
         packageId,
         "doc",