@heroiclands/package-build 20.3.0 → 20.4.0

package/engine/derived-fields.mjs

@@ -0,0 +1,174 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * `system` keys a note may **never** author, because the *compiler* writes them
+ * from the note itself.
+ *
+ * The third of three refusals that read alike and state different facts:
+ *
+ * | module | refuses a field | because |
+ * | --- | --- | --- |
+ * | `retired-fields.mjs` | a note may no longer declare | it has been withdrawn |
+ * | `runtime-only-fields.mjs` | a note never could | the *document* writes it in play |
+ * | this one | a note never could | the *compiler* writes it, from the note |
+ *
+ * The distinction between the last two is where the value comes from, and it
+ * decides what an author is told. A runtime-only field has no compile-time
+ * value at all, so the fix is to delete the key. A derived one **does** have a
+ * compile-time value — it is already being written, from somewhere else in the
+ * same note — so the fix is to move the content to wherever the compiler reads
+ * it from, and the message has to say where that is.
+ *
+ * ## Why an authored value cannot be the source of anything
+ *
+ * The compiler writes the key unconditionally. An authored one is therefore at
+ * best redundant, and at worst the wrong type in a shipped document: SoHL's
+ * `docHtml` holds a `@UUID` pointing at the JournalEntry a note's prose
+ * compiled into, so a note writing prose there ships a string where every
+ * reader expects a pointer, with nothing to report it.
+ *
+ * Either way the text is not reaching a reader the way its author intended. It
+ * was written as a description, and the field it was written into is not where
+ * descriptions live — the note's own body is.
+ *
+ * ## Declared by the compiler, not named here
+ *
+ * A derived key is a fact about a *pass*, not about a schema: it exists because
+ * that compiler chose to write it. So the list is a static on the compiler and
+ * this module knows no key names, which is what lets a second system declare
+ * its own — HM3 derives `description` from an anchored prose section exactly as
+ * SoHL derives `docHtml` from the body.
+ *
+ * @module
+ */
+
+import { getFrontmatter } from "./frontmatter.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { SYSTEM_DATA_KEY, systemData } from "./system-block.mjs";
+
+/**
+ * What a note authoring a derived key is told, in one place.
+ *
+ * Shared by every caller that can meet one, so an author meets the same
+ * sentence whichever runs first. It names the correction rather than only the
+ * fault, because "delete this" is not the fix here: the text is wanted, and
+ * there is somewhere it belongs.
+ *
+ * @param {string} key - The **whole key the note wrote**, from the region it
+ *   sits in down to the field: `sohl.system.docHtml`. Composed by the caller,
+ *   because only it knows where it found the value.
+ * @param {string} from - Where the compiler reads the value from, completing
+ *   "the compiler writes it from …". The declaration carries it.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function derivedMessage(key, from, file) {
+    return (
+        `\`${key}:\` is written by the compiler, not authored` +
+        (file ? ` — ${file}` : "") +
+        `. It is derived from ${from}, and the compiler writes it ` +
+        `unconditionally, so an authored value is overwritten or ships the ` +
+        `wrong type. Move the text to ${from} and delete the key`
+    );
+}
+
+/**
+ * The derived keys a note actually writes, in declaration order.
+ *
+ * **Presence is the whole test**, as it is for a retired or a runtime-only
+ * field: an authored empty string is as much a claim on the key as prose is,
+ * and it is the same belief the message exists to correct. So the question is
+ * whether the path resolves to anything at all, never whether the value is a
+ * usable one.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives. A pass that derives nothing passes.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @returns {{key: string, from: string}[]} The offending declarations.
+ */
+export function authoredDerivedKeys(fm, keys, { block } = {}) {
+    if (!fm || typeof fm !== "object" || !block) return [];
+    return derivedIn(systemData(fm, block), keys);
+}
+
+/**
+ * The same question asked of a `system` block directly.
+ *
+ * A note's own block is reached through {@link authoredDerivedKeys}, but it is
+ * not the only place an author writes one: an actor note's `items:` entries
+ * carry a `system:` overlay that is deep-merged onto the template verbatim,
+ * with no field declaration in the path at all. That overlay is a `system`
+ * block by every meaning except where it sits, and a `docHtml` written there
+ * ships exactly as one written on the item's own note.
+ *
+ * @param {Record<string, unknown>|null|undefined} data - The authored `system`
+ *   data.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives.
+ * @returns {{key: string, from: string}[]} The offending declarations.
+ */
+export function derivedIn(data, keys) {
+    if (!data || typeof data !== "object") return [];
+    return (keys ?? []).filter(
+        (entry) =>
+            typeof entry?.key === "string" &&
+            entry.key !== "" &&
+            getFrontmatter(data, entry.key, undefined) !== undefined,
+    );
+}
+
+/**
+ * Refuse a note that authors any key its compiler derives.
+ *
+ * Refused rather than reported, for the reason its two siblings are: the note
+ * is not compiled, so nothing it would have emitted reaches a pack, and each
+ * caller counts the refused note and emits a located diagnostic — a refusal is
+ * never a silent skip.
+ *
+ * The **first** offending key is thrown on. A note authoring two of them is one
+ * mistake with one fix, and the build stops on this note either way.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {readonly {key: string, from: string}[]} [keys] - What the compiler
+ *   derives.
+ * @param {object} options - Options.
+ * @param {string} options.block - The system block to look in.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already.
+ * @param {string} [options.absPath] - The note's file on disk, read only on the
+ *   failing path to locate the offending line and column. The position rides on
+ *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note authors one.
+ */
+export function assertNoDerivedFields(fm, keys, { block, file, absPath } = {}) {
+    const [entry] = authoredDerivedKeys(fm, keys, { block });
+    if (!entry) return;
+
+    const wrote = `${block}.${SYSTEM_DATA_KEY}.${entry.key}`;
+    const err = new Error(`${derivedMessage(wrote, entry.from, file)}.`);
+    // The **leaf** of the key, which is how the note writes it: a locator
+    // handed a dotted path would find nothing. Deliberately not anchored at
+    // column 1 — the key lives two levels in, under `<block>.system`.
+    const leaf = entry.key.split(".").pop();
+    const position = locateFrontmatterKey(absPath, /** @type {string} */ (leaf));
+    if (position) err.position = position;
+    throw err;
+}

package/engine/diagnostics.mjs

@@ -18,8 +18,7 @@
  * in "The Capital Nome"` — has told the author what is wrong and not where it
  * is. A name is not an address: finding it means searching the tree for a note
  * whose `name.full` matches and then searching that file for the link, and
- * four identical warnings on one note are indistinguishable from one another
- * (#17).
+ * four identical warnings on one note are indistinguishable from one another.
  *
  * So every diagnostic about a note is emitted in the form every C-family
  * compiler, `tsc` and ESLint already use:
@@ -185,7 +184,7 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
  * same name answers when no top-level one is present — which is usually what a
  * reader wants, the key being unique in nearly every note. Pass `topLevel` where
  * it is not: `aliases` is both a retired top-level field and a **permitted**
- * `name.aliases` (#180), and a finding about the first must never open on the
+ * `name.aliases`, and a finding about the first must never open on the
  * second, which would tell an author to delete a field they are allowed to
  * write.
  *
@@ -387,7 +386,7 @@ export function yamlKeyPath(field) {
  * the same name is legal in two regions — `data.weight` and a top-level
  * `weight` are different keys, and a search finds whichever comes first.
  *
- * So this is the located form for the closed regions (#128). It reuses
+ * So this is the located form for the closed regions. It reuses
  * {@link positionOfYamlPath} rather than repeating its parse, which is what
  * keeps a finding about `data.weight` pointing at `data.weight`.
  *

package/engine/document-subtypes.mjs

@@ -13,8 +13,7 @@
 
 /**
  * **The note-type → document-subtype map** — the mechanism that stops a build
- * inferring a Foundry document's subtype from the markdown note's `type`
- * (#79).
+ * inferring a Foundry document's subtype from the markdown note's `type`.
  *
  * A note's `type` and the subtype of the document it compiles into are two
  * vocabularies, and until now they were the same identifier for one reason
@@ -26,7 +25,7 @@
  * risk with **one** system, not merely with two.
  *
  * **The mechanism is here; the declaration is the system's.** That is the
- * `engine/` ÷ `sohl/` line everywhere else in this package (#36): note-format
+ * `engine/` ÷ `sohl/` line everywhere else in this package: note-format
  * knowledge here, game-system knowledge there. `sohl/document-subtypes.mjs`
  * declares SoHL's own map, *including its identity rows* — the coincidence of
  * names may never stand in for a mapping, so `skill` → `skill` is written out
@@ -59,7 +58,7 @@
  * *compiled documents*, which carry only the subtype. {@link referencedSubtype}
  * is the translation for that side, and the reason it is separate from
  * {@link documentSubtype} is that a reference has no frontmatter of its own to
- * read a discriminator from (#140).
+ * read a discriminator from.
  *
  * @module
  */
@@ -207,7 +206,7 @@ function frozenRow(system, noteType, row) {
  * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and
  * {@link systemOf} all arrive here. A note still spelling `armorgear` finds the
  * `armor` row, compiles into the `armorgear` document it always did, and keeps
- * the address it publishes at; only the *report* tells it to move (#78).
+ * the address it publishes at; only the *report* tells it to move.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The note's declared `type`.
@@ -317,7 +316,7 @@ export function documentSubtype(map, noteType, fm, { file, absPath } = {}) {
  */
 
 /**
- * The document subtype a `(type, shortcode)` **reference** addresses (#140).
+ * The document subtype a `(type, shortcode)` **reference** addresses.
  *
  * A being's frontmatter names each embedded item by the *note's* type — the
  * vocabulary an author writes — while the predefined items it resolves against
@@ -354,7 +353,7 @@ export function documentSubtype(map, noteType, fm, { file, absPath } = {}) {
  * retirement exists to stop.
  *
  * A **renamed** spelling is the opposite case and resolves normally, through
- * the same {@link currentType} every other lookup goes through (#78). It has to
+ * the same {@link currentType} every other lookup goes through. It has to
  * be this side as much as the note's own `type:`: the overwhelming majority of
  * the 31,000 occurrences of the old names are `(type, shortcode)` references
  * inside a being's `items:` list, so a window that resolved notes but not

package/engine/field-reference.mjs

@@ -20,7 +20,7 @@
  * types, each with a shape, a default and a requiredness, is exactly the kind of
  * prose that drifts silently from the code it describes. The declarations
  * (`fields` on each `itemBuilders` entry) already *are* that table, so the page
- * is rendered from them rather than transcribed (#22).
+ * is rendered from them rather than transcribed.
  *
  * **It ships here, not in the consumer.** Any repository can define an item
  * type of its own, so "what frontmatter does this type accept?" is a question
@@ -104,7 +104,7 @@ function fieldTable(fields) {
             `\`${field.name}\``,
             cell(field.shape ?? "as authored"),
             field.required ? "**yes**" : "no",
-            // Three different answers, and the third is not a value (#329). A
+            // Three different answers, and the third is not a value. A
             // required field has no default because omitting it fails the
             // build; an `omitWhenAbsent` field has none because omitting it
             // omits the *key*, leaving the data model to answer. Rendering
@@ -128,7 +128,7 @@ function fieldTable(fields) {
  * the note level the fallback is off, and an author has no way to tell from the
  * table — the field is there, the value is written, and the document ships the
  * default. So the reason each such field declares is rendered beside its table
- * rather than left in the source (#218).
+ * rather than left in the source.
  *
  * Below the table, not inside it: the reason is a sentence or two, and
  * {@link padTable} pads every column to its widest cell, so a cell holding it
@@ -148,7 +148,7 @@ function sharedExemptions(fields) {
 }
 
 /**
- * The fields of one type that a note may **never** write (#330).
+ * The fields of one type that a note may **never** write.
  *
  * A type's table lists what an author writes, and says nothing about the rest
  * of its schema — which is right for a constant or a derived value, since
@@ -208,15 +208,15 @@ function workedExample(type, fields) {
         `type: ${type}`,
         "shortcode: xmpl",
         // No `package:`. A note's package is the repository's configured
-        // `contentPackage`, and declaring the field is a build error (#56) —
+        // `contentPackage`, and declaring the field is a build error —
         // this example is the smallest note that compiles.
         //
         // No `id:` either, for the same reason it is not shown optional-first:
-        // a note's document `_id` derives from its canonical address (#270,
-        // #277), and the authored field is the escape hatch for keeping a
+        // a note's document `_id` derives from its canonical address, and the
+        // authored field is the escape hatch for keeping a
         // document's identity across a shortcode rename, not part of the
         // envelope. This block is the one an author copies as a template, so
-        // showing the field taught every note in the tree to write it (#314).
+        // showing the field taught every note in the tree to write it.
         "sohl:",
         "  templatePriority: null",
     ];

package/engine/field-spec.mjs

@@ -17,8 +17,8 @@
  * **The declaration is the builder, not a description of one.** A builder used
  * to be an opaque function: the mapping from a note's `sohl:` frontmatter to
  * the emitted `system` block existed only inside its body, so nothing could
- * read it — not a documentation generator, not a validator, not a person
- * (#22). The obvious repair, a table written *beside* the function, buys very
+ * read it — not a documentation generator, not a validator, not a person.
+ * The obvious repair, a table written *beside* the function, buys very
  * little: two statements of one rule drift, and nothing notices.
  *
  * So the table is the only statement. {@link buildFromFields} turns a field
@@ -50,19 +50,19 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
 /**
  * @typedef {object} FieldSpec
  * @property {string} to - Dotted path in the emitted `system` block — and,
- *   since #58, the path a note authors the field at directly:
+ *   the path a note authors the field at directly:
  *   `<system>.system.<to>`.
  * @property {string} [name] - The **shared, top-level property this field draws
  *   from** when the note authors no value at `<system>.system.<to>`. Dotted for
  *   a path into a shared container (`data.portrait`), which is now the ordinary
- *   case: `data:` (#128) puts every type-specific fact under one.
+ *   case: `data:` puts every type-specific fact under one.
  *
- *   It used to mean "frontmatter key under `sohl:`", and that reading is the
+ *   Read as "frontmatter key under `sohl:`", that meaning is the
  *   degenerate case where the shared source and the system destination happen
  *   to share a name. They constantly do not — one shared `data.portrait` feeds
  *   `sohl.system.portrait` *and* `hm3.system.bioImage` — so the source is
- *   declared rather than matched by spelling (#58). The in-block position is
- *   still read, second, until #126 moves the corpus off it — keyed on
+ *   declared rather than matched by spelling. The in-block position is
+ *   still read, second, until the corpus moves off it — keyed on
  *   `legacyKey` where the two spellings differ.
  *
  *   Absent means the value is not authored at all — see `value`.
@@ -70,8 +70,8 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   the system block** — the second position of the resolution order — when
  *   that is not `name`. Absent, the position is keyed on `name`.
  *
- *   The two were one property until #305, which held only while a field's
- *   shared source and its in-block key were the same word. `data:` (#128) ended
+ *   As one property the two would hold only while a field's
+ *   shared source and its in-block key were the same word. `data:` ended
  *   that: a shared source is a path into a container, so `data.species` and
  *   `species` name two different places and no single value reached both.
  *   `name: "species"` could not see `data.species`; `name: "data.species"`
@@ -87,7 +87,7 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  * @property {string} [topLevelMeans] - **What the note's top-level key of this
  *   name means instead** — declared only where it means something else, and
  *   stating it removes the shared top-level position from this field's
- *   resolution order (#218).
+ *   resolution order.
  *
  *   A field's `name` doubles as its identity and as the shared property it
  *   draws from, which is right wherever the two levels state the same quantity
@@ -114,7 +114,7 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   if the two positions hold unrelated quantities then the *in-block* position
  *   is not the note-level field either, so a check about the note-level field
  *   reads past it. `engine/frontmatter-lint.mjs` resolves that through
- *   `collidingBlockKeys`. Read for the emitted field alone until #312, which is
+ *   `collidingBlockKeys`. Reading it for the emitted field alone is
  *   how an affiliation's office style came to answer for its page heading.
  * @property {string} [shape] - Human-readable shape, for documentation. Comes
  *   paired with `read` from one of the coercion constants below.
@@ -130,10 +130,9 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   third step of {@link module:engine/system-block.resolveFieldValue}'s order,
  *   so the value resolves whichever region carries it. What it tells the
  *   author-facing surfaces is which of the two is the field's *home*, so a
- *   message about it names `img` rather than sending an author to `sohl.img`
- *   (#142).
+ *   message about it names `img` rather than sending an author to `sohl.img`.
  * @property {"string"|"number"|"boolean"|"list"|"map"} [kind] - The value's
- *   shape, for the frontmatter linter (#19). Distinct from `shape`, which is
+ *   shape, for the frontmatter linter. Distinct from `shape`, which is
  *   prose for a reader, and from `read`, which is what the compiler does: a
  *   field may declare `kind` without changing a byte of what it emits, and
  *   several do — `weight` is coerced leniently but is still a number, and
@@ -146,7 +145,7 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  * @property {any|((fm: object) => any)} [value] - For a field with no `name`:
  *   the constant, or a function deriving it from the frontmatter.
  * @property {boolean} [omitWhenAbsent] - **The key is left out entirely when
- *   the note does not carry the field** (#329), rather than written from a
+ *   the note does not carry the field**, rather than written from a
  *   declared default.
  *
  *   Every other field answers absence with a value: an unauthored `weight` is
@@ -181,7 +180,7 @@ export { legacyKeyOf, retiredTopLevelKey, setPath };
  *   which the generated reference states in the field's own row.
  * @property {string} [runtimeOnly] - **What the field holds once play has
  *   started** — declared on a field the *document* writes for itself, which no
- *   note may author (#330).
+ *   note may author.
  *
  *   A schema declares plenty of fields a compiled document has no business
  *   carrying: an affliction's `onsetDate` is the world time its onset fired
@@ -295,7 +294,7 @@ export const BLANK_IS_DEFAULT = Object.freeze({
  *
  * **Only for a field that declares a `legacyKey`.** Every other field's
  * in-block position is simply where it lives; reporting those would put a
- * finding on every field of every note in every tree, which is #126's corpus
+ * finding on every field of every note in every tree, which is the corpus
  * migration rather than a signal anyone could act on.
  *
  * @param {FieldSpec} field - The declaration.
@@ -309,7 +308,7 @@ export function readsLegacyKey(field, from) {
 
 /**
  * Whether a resolution read a field from the top-level key `data:` gathered it
- * off — the shared level's retiring position (#332).
+ * off — the shared level's retiring position.
  *
  * {@link readsLegacyKey}'s sibling, and the same signal: a finding here counts
  * one note still on the pre-`data:` spelling, so the sweep has something to
@@ -335,7 +334,7 @@ export function readsRetiredTopLevel(field, from) {
  *
  * The *position* is resolved by {@link resolveFieldValue} — `<system>.system`
  * first, then the legacy in-block key, then the declared shared source, then
- * the default (#58). The **coercion** is applied here, once, wherever the value
+ * the default. The **coercion** is applied here, once, wherever the value
  * came from: a field's `read` is a statement about the field, not about where
  * an author happened to write it, so `weight: "7"` reads as `7` at every one of
  * those positions.
@@ -347,12 +346,12 @@ export function readsRetiredTopLevel(field, from) {
  *   against. The default is the one block every existing tree authors; a
  *   second system passes its own.
  * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Called with each
- *   field read from the position it is being swept off (#305). A callback
+ *   field read from the position it is being swept off. A callback
  *   rather than a returned list because the caller is a compiler, which already
  *   knows the note and how to locate a key in it; this module knows neither and
  *   would have to invent a finding shape to say so.
  * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Called with
- *   each field read from the top-level key `data:` gathered it off (#332). The
+ *   each field read from the top-level key `data:` gathered it off. The
  *   shared level's counterpart to `onLegacyKey`, and a separate callback
  *   because it is a separate position: a note may have moved one of the two and
  *   not the other, and a caller that conflated them would tell its author to
@@ -370,7 +369,7 @@ export function readField(field, fm, options = {}) {
  * every caller wants. A builder has one further question — *should the key be
  * written at all* — and it cannot be answered from the value: `null` from a
  * note and `null` from a declared default are the same value and opposite
- * facts (#329).
+ * facts.
  *
  * So the position rides back beside the value, resolved **once**. The
  * alternative is a builder that calls {@link resolveFieldValue} for the source
@@ -403,7 +402,7 @@ export function readFieldEntry(field, fm, { block = "sohl", onLegacyKey, onRetir
  * The question {@link FieldSpec.omitWhenAbsent} turns on, asked of the
  * *position* rather than of the value — which cannot answer it, since a
  * declared `default: null` and an authored `null` are indistinguishable once
- * the value is in hand (#329).
+ * the value is in hand.
  *
  * `undefined` counts as absent whatever position reported it, because writing
  * the key then emits a value `JSON.stringify` drops — the key present in the
@@ -434,17 +433,17 @@ export function isAuthored(from, value) {
  *   systems declare the same shared source and different destinations.
  * @param {(field: FieldSpec) => void} [options.onLegacyKey] - Passed through to
  *   {@link readField}: called with each field the note authored at the position
- *   it is being swept off (#305).
+ *   it is being swept off.
  * @param {(field: FieldSpec) => void} [options.onRetiredTopLevel] - Passed
  *   through to {@link readField}: called with each field the note authored at
- *   the top-level key `data:` gathered it off (#332).
+ *   the top-level key `data:` gathered it off.
  * @returns {(fm: object) => object} A `system`-block builder.
  */
 export function buildFromFields(fields, { block = "sohl", onLegacyKey, onRetiredTopLevel } = {}) {
     return function buildDeclaredSystem(fm) {
         const out = {};
         for (const field of fields) {
-            // A runtime-only field is not this builder's to write (#330). It is
+            // A runtime-only field is not this builder's to write. It is
             // declared so that the path is *claimed* — so the verbatim
             // passthrough leaves it alone and the refusal has a name — not so
             // that a compile-time answer is invented for a question only play
@@ -457,8 +456,8 @@ export function buildFromFields(fields, { block = "sohl", onLegacyKey, onRetired
                 onLegacyKey,
                 onRetiredTopLevel,
             });
-            // The other conditional row: a field whose *absence* is meaningful
-            // (#329). Writing a declared default would answer a question the
+            // The other conditional row: a field whose *absence* is meaningful.
+            // Writing a declared default would answer a question the
             // note did not ask — "this affliction's onset takes `null` days" —
             // and would make the field's unset state indistinguishable from an
             // authored one for every reader downstream. Omitting the key leaves
@@ -490,8 +489,8 @@ export function authoredFields(fields) {
  * The fields of a declaration a note may **never** write.
  *
  * The complement of {@link authoredFields} in the direction that matters: those
- * are the fields an author may write, these are the ones authoring is an error
- * (#330). Everything else in a declaration — a constant, a derived value — is
+ * are the fields an author may write, these are the ones authoring is an error.
+ * Everything else in a declaration — a constant, a derived value — is
  * simply not authored, which is a statement about the *builder* rather than
  * about the author, and says nothing about what happens if a note writes the
  * path anyway.

package/engine/folder-notes.mjs

@@ -16,9 +16,9 @@
  *
  * A `Folder` is a real Foundry document, and it was the last kind this package
  * compiled from bespoke configuration — `*-folders.yaml`, five files per tree —
- * rather than from a note. That was the one hole in the rule #243 establishes,
+ * rather than from a note. That is the one hole in the rule,
  * *the compiler follows the index*: a pass cannot follow the index for things
- * the index does not contain (#256).
+ * the index does not contain.
  *
  * Three things follow from a folder being a note, and each is a defect that
  * becomes unrepresentable rather than a tidiness win:
@@ -26,14 +26,14 @@
  * 1. **`parent` is an address**, resolved and checked like every other
  *    reference. A dangling parent stops being a special-cased
  *    `Unknown folder id` and becomes an ordinary dead-address finding.
- * 2. **Where a folder materialises is derived from what references it** (#257).
+ * 2. **Where a folder materialises is derived from what references it**.
  *    A documentation journal is filed beside the item it describes, which used
  *    to mean passing the *items* pack's folder id into the *journals* pack —
  *    verbatim, validated nowhere, and correct only where the two folder files
  *    happened to mirror each other. They did in one tree of three. With one
  *    folder note and one address there is no second file to disagree with the
  *    first, so a pack cannot fail to declare a folder something in it points at.
- * 3. **The Foundry id is derived from the address** (#258), the way a
+ * 3. **The Foundry id is derived from the address**, the way a
  *    `JournalEntryPage` id is already hashed from its anchor — with an authored
  *    `id` still winning, so a world already holding these folders keeps
  *    resolving them.
@@ -44,7 +44,7 @@
  *
  * **A folder note carries no prose.** It is structure, not content, so it wants
  * no documentation journal and takes no part in `docEntryTypes` — the one
- * decision #256 left open, settled the way it recommended.
+ * open decision, settled the way it recommended.
  *
  * @module
  */
@@ -109,7 +109,8 @@ export const DEFAULT_PARENT = "default";
  * `parent` and `color` are `data:` properties, which is where the
  * specification's `### type: folder` table puts them — the closed container,
  * so a misspelled `colour` is a finding rather than a theme parameter. They are
- * accepted at the top level too, because that is where #256's own example wrote
+ * accepted at the top level too, because that is where the canonical example
+ * writes
  * them and an author following the issue rather than the specification should
  * get a folder, not a silent default.
  *
@@ -194,7 +195,7 @@ export function folderAddress(pkg, shortcode) {
  * never run this build. Deriving it twice is how the index came to publish a
  * plausible-looking id that resolved to nothing — the general id rule hashes a
  * note's address under the `document` namespace, and a folder's is hashed under
- * {@link FOLDER_ID_NAMESPACE} (#310).
+ * {@link FOLDER_ID_NAMESPACE}.
  *
  * An **authored `id` still wins**, and is applied by the caller: this is the
  * derivation, not the resolution, so the pin rule stays stated once, where
@@ -212,8 +213,7 @@ export function folderDocId(pkg, shortcode) {
  * Collect every folder note in a content tree.
  *
  * The walk is the caller's to supply, so this stays testable without a tree on
- * disk and so one build cannot disagree with another about what the corpus is
- * (#243).
+ * disk and so one build cannot disagree with another about what the corpus is.
  *
  * @param {Iterable<{frontmatter: object|null, absPath: string}>} notes - As
  *   yielded by `walkMarkdownTree`.
@@ -237,7 +237,7 @@ export function collectFolderNotes(notes, pkg) {
         // The charset rule is load-bearing here rather than tidy: the address
         // is parsed by counting separators, so a hyphenated shortcode would be
         // read back as two segments and resolve to nothing, reporting nothing
-        // about why (#1397, #273).
+        // about why.
         if (!isAddressSegment(shortcode)) {
             throw Object.assign(
                 new Error(
@@ -266,7 +266,7 @@ export function collectFolderNotes(notes, pkg) {
                 Object.entries(parent).map(([pack, value]) => [pack, bareAddress(value)]),
             ),
             // An authored id is kept, and a folder without one derives a
-            // stable one from its address (#258). Keeping the authored id is
+            // stable one from its address. Keeping the authored id is
             // what makes this a build change rather than a world migration: a
             // world already holding these folders goes on resolving them.
             id: authoredId || folderDocId(pkg, shortcode),
@@ -283,7 +283,7 @@ export function collectFolderNotes(notes, pkg) {
  *
  * Three keys per folder, and no more: the canonical address, the
  * `folder-<shortcode>` short form, and the bare shortcode. They are the
- * suffixes of the canonical address the grammar admits (#273) — a `packFolder`
+ * suffixes of the canonical address the grammar admits — a `packFolder`
  * or `parent` field supplies the type itself, so a bare shortcode is a complete
  * address there.
  *
@@ -402,7 +402,7 @@ export function buildFolderNoteIndex(folders) {
      *
      * A folder cannot materialise without them: a `Folder` whose parent is
      * absent from the pack is an orphan Foundry renders at the root, so the
-     * tree would be broken at the top rather than merely incomplete (#257).
+     * tree would be broken at the top rather than merely incomplete.
      *
      * @param {FolderNote} folder - The folder.
      * @param {string} [pack] - The pack being compiled.
@@ -497,7 +497,7 @@ export function folderDocument(folder, parent, documentType, stats) {
  * Refuse a note that declares the retired `folder:` spelling.
  *
  * `folder:` named a compendium folder by the raw Foundry id declared in a
- * per-pack `*-folders.yaml`. Both halves are retired together (#260): the id
+ * per-pack `*-folders.yaml`. Both halves are retired together: the id
  * spelling has nothing left to resolve against once the YAML is gone, and the
  * YAML has no reader once the spelling is refused.
  *