@heroiclands/package-build 20.3.1 → 20.5.0

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
  */
@@ -54,7 +54,7 @@ import path from "node:path";
 import log from "loglevel";
 
 import { NO_SYSTEM, canonicalKey } from "./content-address.mjs";
-import { isAddressSegment } from "./address-charset.mjs";
+import { ADDRESS_SEGMENT_PATTERN, isAddressSegment } from "./address-charset.mjs";
 import { makeId } from "./ids.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 
@@ -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,12 +237,14 @@ 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(
                     `folder shortcode "${shortcode}" is not strictly ` +
-                        `alphanumeric, so its address would not parse: ${absPath}`,
+                        `alphanumeric — lowercase letters and digits only ` +
+                        `(${ADDRESS_SEGMENT_PATTERN.source}) — so its address ` +
+                        `would not parse: ${absPath}`,
                 ),
                 { absPath },
             );
@@ -266,7 +268,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 +285,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 +404,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 +499,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.
  *

package/engine/foreign-catalog.mjs

@@ -120,7 +120,7 @@ export function catalogDir(config, id, version) {
 const itemsDir = (dir) => path.join(dir, "items");
 
 /**
- * The file a system publishes its `system` field sets as (#60).
+ * The file a system publishes its `system` field sets as.
  *
  * @type {string}
  */
@@ -166,7 +166,7 @@ function cacheSchemaArtifact(root, dir) {
 
 /**
  * What each extracted pack is, written beside the items rather than inferred
- * from the directory it landed in (#58).
+ * from the directory it landed in.
  *
  * A dependency may ship a pack per system — `items-sohl` and `items-hm3` — and
  * the two hold documents of the *same* `(type, shortcode)` addresses with
@@ -219,7 +219,7 @@ function cachedItemPacks(dir) {
  * Whether a dependency's cache is present and complete.
  *
  * **A cache without its pack manifest is incomplete**, not merely unlabelled.
- * One written before #58 holds the items and not what they are, and the two
+ * An older one holds the items and not what they are, and the two
  * ways of proceeding without it are both wrong: reading every pack resolves an
  * `hm3` reference against `sohl` documents — the silent-wrong-output failure
  * this scoping exists to remove — and reading none fails a build that was
@@ -309,7 +309,7 @@ async function extractItemPacks(id, version, manifest, root, dir) {
         );
     }
     // What each pack is, from the only place that knows: the manifest that
-    // declared it (#58). Written before the stamp, so the stamp continues to
+    // declared it. Written before the stamp, so the stamp continues to
     // mean the cache is whole.
     fs.writeFileSync(
         path.join(dir, ITEM_PACKS),
@@ -519,7 +519,7 @@ export async function fetchCatalogFromPath(config, rel, source) {
 }
 
 /**
- * Fetch one dependency's published content index (#239).
+ * Fetch one dependency's published content index.
  *
  * **The chain is entirely declared.** The relationship names the dependency's
  * manifest, the manifest advertises `flags.metadataUrl`, and that URL is the
@@ -720,7 +720,7 @@ export async function fetchAllCatalogs(config) {
  * Reads the cache only. A cold cache is an error naming the command that fills
  * it, rather than a download nobody asked for.
  *
- * **Scoped to one system when the caller compiles for one (#58)**, exactly as
+ * **Scoped to one system when the caller compiles for one**, exactly as
  * {@link module:engine/generate.itemPackJsonDirs} scopes the local half. The
  * two halves answer the same lookup — `loadItemsMap` merges them into one
  * address space keyed by `subType:shortcode` — so scoping only the local one
@@ -759,8 +759,7 @@ export function foreignItemCatalogDirs(config, system = null) {
         // the currently declared one, so that is the one to use. The
         // comparison is the content-index cache's, shared rather than
         // rewritten: a plain string sort would put `0.8.10` before `0.8.2` and
-        // silently resolve every embedded item against the older catalogue
-        // (#272).
+        // silently resolve every embedded item against the older catalogue.
         const newest = newestVersionDir(cached);
         const packSystems = cachedItemPacks(newest);
         const items = itemsDir(newest);
@@ -768,7 +767,7 @@ export function foreignItemCatalogDirs(config, system = null) {
             if (!entry.isDirectory()) continue;
             const packSystem = packSystems.get(entry.name) ?? null;
             if (system != null && packSystem != null && packSystem !== system) continue;
-            // The dependency's own id travels with its directory (#334): a
+            // The dependency's own id travels with its directory: a
             // being's `model:` names the package its template comes from, and
             // the address cannot be built from the path.
             dirs.push({ dir: path.join(items, entry.name), package: rel.id });

package/engine/foundry-entries.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Emitting this package's cross-package link manifest (#58).
+ * Emitting this package's cross-package link manifest.
  *
  * `engine/content-address.mjs` owns the address *grammar* — how a key is
  * version is read, how a foreign file resolves. This module owns the *pass*:
@@ -27,16 +27,16 @@
  * to strip that same prefix back off; the value never reached the file. So
  * nothing here composes one. An address is derived package-relative from the
  * start, by {@link packageAddress}, and the emitting build's mount point is not
- * a fact it has to be told (#1465).
+ * a fact it has to be told.
  *
- * **An entry's `path` is derivable from the key it is filed under** (#181).
+ * **An entry's `path` is derivable from the key it is filed under**.
  * `sohl-sohl-affliction-aconite` publishes at `affliction-aconite/` — the key
  * with its package and system segments dropped — because a page's URL *is* its
  * address; nothing in it comes from a display name, so a rename moves no URL and
  * no uniqueness check stands between the two. The system segment goes with the
  * package because a note publishes one page however many systems' documents it
- * compiles into (#59). Every entry is
- * derivable that way since #204 retired the section landing, which was the one
+ * compiles into. Every entry is
+ * derivable that way, sections being retired — the section landing was the one
  * that was not. The field is still written rather than left for a consumer to
  * compute, because an absent `path` already means something else entirely (a
  * package that publishes no pages).
@@ -124,8 +124,8 @@ export function anchorsOf(entryUuid, entryId, body, name) {
  * An item note produces **two**: the item, and separately the JournalEntry its
  * prose compiles into. They are two documents with two UUIDs, so they get two
  * addresses; the item's entry points at the other by address rather than
- * repeating its UUID, because the doc entry owns that fact (#1499). A `macro`
- * note is the same arrangement (#1514), which is why the type set comes from
+ * repeating its UUID, because the doc entry owns that fact. A `macro`
+ * note is the same arrangement, which is why the type set comes from
  * {@link hasDocEntry} rather than being spelled here — the journals compiler
  * reads the same one, so a manifest cannot claim documentation nothing compiled.
  *
@@ -137,7 +137,7 @@ export function anchorsOf(entryUuid, entryId, body, name) {
  * UUID. The two are one fact — a UUID ends in the id — but only the entry knows
  * which derivation produced it: an item's is its note's `fm.id`, and its
  * documentation journal's is {@link itemDocEntryId} of that. Stating it here is
- * what lets the content index publish an identity it did not re-derive (#310).
+ * what lets the content index publish an identity it did not re-derive.
  *
  * @param {object} ctx - Resolved identities: `{ contentPackage,
  *   foundryPackageId, packRouter }`.
@@ -161,11 +161,11 @@ export function entriesForNote(fm, name, address, body, ctx) {
 
     // A published address must name the pack the document actually shipped in:
     // a consumer resolves the UUID verbatim, and a repository may ship several
-    // packs of one type (#1566).
+    // packs of one type.
     const uuidFor = (type, id, routeFm) =>
         // A type this cannot name a single compendium document for has no UUID
         // to publish, whatever id it derives. That used to follow from such a
-        // note authoring no `id:`; since #270 every addressable note derives
+        // note authoring no `id:`; every addressable note derives
         // one, so "has an id" stopped being evidence a document exists and the
         // rule is stated where it belongs — beside the addresses — rather than
         // resting on an absent field. `collectFoundryEntries` skips such a note
@@ -175,7 +175,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // Two sets, for opposite reasons (see `note-claims.mjs`). A **homepage**
         // is in no pack: it compiles to a page and there is nothing to address.
         // A **folder** may be in several — it materialises in every pack holding
-        // a document that references it (#276) — so no one UUID identifies it,
+        // a document that references it — so no one UUID identifies it,
         // and its id is hashed under the `folder` namespace against its own
         // address rather than under `document`. Emitting one would publish an
         // `Item` UUID for a `Folder`, at an id no document carries.
@@ -222,7 +222,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 // content index publishes it beside the UUID, so an entry the
                 // index gives an identity to states both halves of it rather
                 // than leaving a consumer to parse the id back out of the
-                // UUID's last segment (#310).
+                // UUID's last segment.
                 id: docEntryId,
                 uuid: docUuid,
                 anchors: docUuid ? anchorsOf(docUuid, docEntryId, body ?? "", name) : undefined,
@@ -250,12 +250,11 @@ export function entriesForNote(fm, name, address, body, ctx) {
  * Every note this package publishes, as manifest entries.
  *
  * Every note in the tree is this package's, so nothing here selects by package:
- * the key's first segment is `contentPackage` (#56). A note still declaring the
+ * the key's first segment is `contentPackage`. A note still declaring the
  * retired `package:` or `draft:` field **throws** rather than being skipped —
  * skipping one silently is how a whole tree came to be filtered out of a
  * manifest that then claimed the package published nothing, and it is what let
- * a drafted note's inbound links look like links to a note that never existed
- * (#69).
+ * a drafted note's inbound links look like links to a note that never existed.
  *
  * A note that has no address is **reported, not guessed** — the finding carries
  * the file and the reason, so a caller can print it or fail on it. Inventing an
@@ -278,8 +277,8 @@ export function collectFoundryEntries(contentBase, ctx) {
         skipDirectories: ctx.skipDirectories,
     })) {
         if (!fm) continue;
-        // Its authored pin, or the id derived from its canonical address
-        // (#270). Resolved before anything reads `fm.id`, so the UUID this
+        // Its authored pin, or the id derived from its canonical address.
+        // Resolved before anything reads `fm.id`, so the UUID this
         // pass publishes is the one the pack passes compiled under.
         resolveNoteId(fm, { pkg: ctx.contentPackage });
         const rel = path.relative(contentBase, absPath);
@@ -294,7 +293,7 @@ export function collectFoundryEntries(contentBase, ctx) {
         assertNoSectionField(fm, { file: rel, absPath });
         assertNoTraitsField(fm, { file: rel, absPath });
         if (!fm.type || !fm.shortcode) continue;
-        // A homepage is addressed like every other note since #182, and a
+        // A homepage is addressed like every other note, and a
         // shortcode alone would now put it here. It stays out for the reason it
         // always did, which that change does not touch: a manifest entry is how
         // another package resolves a **document**, and a homepage compiles into
@@ -337,7 +336,7 @@ export function foundryIdentities(config = loadPackConfig()) {
         // Carried in the context rather than read from the global config at the
         // call site, so the pass really is a pure function of what it is handed
         // — which is what lets the content index drive the same derivation with
-        // a configuration it resolved itself (#239).
+        // a configuration it resolved itself.
         docEntryTypes: config.docEntryTypes,
     };
 }
@@ -348,7 +347,7 @@ export function foundryIdentities(config = loadPackConfig()) {
  * {@link foundryIdentities} plus what only a *manifest* emission needs. The
  * split is what lets the content index derive the same Foundry addresses from
  * the same code without also depending on whether the package publishes pages,
- * which is no part of a UUID (#239).
+ * which is no part of a UUID.
  *
  * @param {object} [config] - A resolved configuration; loaded when omitted.
  * @returns {{contentPackage: string, foundryPackageId: string, packRouter: object,