@heroiclands/package-build 20.3.1 → 20.4.0

package/engine/retired-fields.mjs

@@ -26,7 +26,7 @@
  * `aliases:`, `section:` and `traits:` have no such home — there is no
  * surviving concept any of them was part of — so they are refused here.
  *
- * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
+ * **What `draft:` did.** It excluded a note from the compiled packs, from
  * the link manifest and from a consuming site build. Nothing reported the
  * consequence: `content-links.mjs`, `site-index.mjs` and `content-lint.mjs`
  * never read the field, so a link into a drafted note was indistinguishable
@@ -35,13 +35,13 @@
  * *unresolvable*, silently — and it also suppressed real build failures, since
  * a note the compilers never reached could not fail on the defects it carried.
  *
- * **What `aliases:` did (#180).** It fed the alias index, which is what a bare
+ * **What `aliases:` did.** It fed the alias index, which is what a bare
  * `[[Alias]]` was looked up in. That form resolved to nothing anywhere in the
  * corpus, while the collision rule guarding it folded in every note's
- * `name.full` and so decided what a note could be named (#179). The form and
+ * `name.full` and so decided what a note could be named. The form and
  * the index are retired together, leaving the field with no reader at all.
  *
- * **What `section:` did (#202).** It named the section a `collection` note
+ * **What `section:` did.** It named the section a `collection` note
  * headed, under the `collection` landing rule — its only reader anywhere. That
  * rule is retired, a section being landed by the `README.md` in its directory,
  * so the field has none. No schema or vocabulary ever declared it either, and
@@ -56,11 +56,11 @@
  * reserved.test.ts` pins that equivalence so a future reader cannot be added
  * by accident.
  *
- * **What `traits:` did (#291).** It held a being's own description — gender,
+ * **What `traits:` did.** It held a being's own description — gender,
  * species, age, birthday, height, weight, frame and `appearance.*` — at the
  * note's top level. The content format gives those a home: `data:`, the closed
  * container for a subject's type-specific facts, which `being` declares every
- * one of them in. #128 moved all 2,533 notes that carried one, across four
+ * one of them in. Every note that carried one has been moved, across four
  * repositories, and this is the third step of that retirement.
  *
  * Refusing it matters more than refusing an ordinary dead key, because top
@@ -73,19 +73,19 @@
  * declares one, and the theme's gear sidebar reads it — so the refusal is
  * anchored at column 1 and never reaches inside a system block.
  *
- * **A field retired in favour of another is a third case (#142).** `draft:` and
+ * **A field retired in favour of another is a third case.** `draft:` and
  * `package:` were retired outright: nothing replaced them, so no value made
  * writing one right and refusal was the only honest answer. A *renamed* field
  * has a replacement, and the two spellings mean the same thing — so the note
  * still compiles, correctly, and refusing it would fail a build over a document
- * that is not wrong. Those retire in the three steps `package:` took (#56), and
+ * that is not wrong. Those retire in the three steps `package:` took, and
  * this module carries the **first**: both spellings are read, the current one
  * wins, and the retired one is *reported* rather than refused. See
  * {@link RETIRED_FIELD_ALIASES}.
  *
- * **The third step is deletion, and it needs no code (#149).** `image`, a map's
+ * **The third step is deletion, and it needs no code.** `image`, a map's
  * background art, is the first rename to have run all three: reported (#142),
- * swept (SoHL#1801 and the position move that followed), then dropped from the
+ * swept, then dropped from the
  * table. Removing the entry is the whole of it — with no alias, the spelling is
  * an ordinary unknown key in the `sohl:` block, which the frontmatter lint
  * already refuses as an error alongside the required field it failed to supply.
@@ -93,7 +93,7 @@
  * the record, and a retirement that needed a standing refusal would mean the
  * replacement never arrived. Do not keep a tombstone for one.
  *
- * **A retired *position* is the same case, and reads the same (#305).** A field
+ * **A retired *position* is the same case, and reads the same.** A field
  * whose shared source moved under `data:` is not renamed — `data.species` and
  * `hm3.species` are one field written in two places — but the retirement has
  * the identical shape: both are read, the one the note carries wins, and the
@@ -102,8 +102,9 @@
  * {@link module:engine/system-block.resolveFieldValue}'s answer; this module
  * only says what an author is told about it.
  *
- * **A field has two retiring positions, not one (#332).** The in-block key is
- * the obvious one; the other is the note's **top level**, because #128 did not
+ * **A field has two retiring positions, not one.** The in-block key is
+ * the obvious one; the other is the note's **top level**, because the sweep
+ * did not
  * invent the facts `data:` holds — it gathered them from exactly there. So
  * `portrait:` beside `img:` is the pre-`data:` spelling of `data.portrait`,
  * read for the same reason and reported by {@link retiredTopLevelMessage}. Both
@@ -184,11 +185,11 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
  * It says what the field fed and what to write instead, rather than which value
  * to correct: no value makes declaring it right.
  *
- * **What it did (#180).** It was the authored half of the alias index — the
+ * **What it did.** It was the authored half of the alias index — the
  * namespace a bare `[[Alias]]` was looked up in. Across the three content trees
  * not one bare link resolved through it, while the collision rule that kept it
  * unambiguous folded in every note's `name.full` and so dictated what a note
- * could be named (#179). The form is retired, so the list has no reader.
+ * could be named. The form is retired, so the list has no reader.
  *
  * **`name.aliases` is a different field and is not retired.** It fed the same
  * index, but unlike the top-level list it is being kept — reserved, unread,
@@ -275,10 +276,10 @@ export function declaresRetiredAliasesField(fm) {
  * It names what lands a section now rather than a value to correct: no value
  * makes declaring the field right.
  *
- * **What it did (#202).** It named the section a `collection` note headed,
+ * **What it did.** It named the section a `collection` note headed,
  * under the `collection` landing rule — the only reader it ever had, in the
  * second branch of `landingOf` (`engine/content-address.mjs`). That rule went
- * first, and the whole mechanism went with it (#204): a section is a Hugo
+ * first, and the whole mechanism went with it: a section is a Hugo
  * directory the note format does not carry, so no note lands one and a page
  * that introduces a type is an ordinary note addressed `doc-<type>`. Nothing
  * else read the field, and no schema or vocabulary declared it, so left in
@@ -438,14 +439,14 @@ export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel
  * `relation` is retired on an affiliation — which declares `relations` — and
  * remains an unknown key anywhere else.
  *
- * **`templatePriority` (#266).** The number that decides which of several
+ * **`templatePriority`.** The number that decides which of several
  * competing templates the Create dialog offers was called `archetype`, and
  * `archetypes` — one letter apart — is a list of what *sort* a character is.
  * A priority and a taxonomy cannot be told apart by a plural `s`, so the
  * priority takes the name that says what it is. The specification already
  * called it `templatePriority` on two of its three sides.
  *
- * **`relations` (SoHL#1781).** The field holds a *map* of standings, one per
+ * **`relations`.** The field holds a *map* of standings, one per
  * affiliation — its own description says so, and `resolveRelation` has always
  * read it that way. `relation` named the many as one, which every author had to
  * read past. Only `affiliation` declares the field, so the alias is reported
@@ -488,7 +489,7 @@ export function retiredAliasMessage(retired, current, file) {
  * What a note writing a field at its **legacy in-block position** is told.
  *
  * The same three-step retirement `retiredAliasMessage` announces, applied to a
- * *position* rather than a spelling (#305). A field whose shared source moved
+ * *position* rather than a spelling. A field whose shared source moved
  * under `data:` keeps reading the key its block still carries, that read wins,
  * and it is reported here so a sweep has something to count down — without it,
  * moving a field into `data:` would be a flag day across every repository that
@@ -518,9 +519,10 @@ export function legacyKeyMessage(block, field, file) {
 
 /**
  * What a note writing a field at the **top-level key `data:` gathered it off**
- * is told (#332).
+ * is told.
  *
- * {@link legacyKeyMessage}'s counterpart for the other retiring position. #128
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position. The
+ * sweep
  * did not invent the facts `data:` holds — it collected them out of the note's
  * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
  * of `data.portrait`, and both are read for the same reason both in-block

package/engine/runtime-only-fields.mjs

@@ -13,7 +13,7 @@
 
 /**
  * Schema fields a note may **never** author, because the document writes them
- * in play (#330).
+ * in play.
  *
  * `retired-fields.mjs` refuses a field a note may no longer declare; this
  * refuses one it never could. The two read alike deliberately — a note says one

package/engine/scene-levels.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * **Scene ↔ Level integrity** for a compiled compendium pack (issue #1538).
+ * **Scene ↔ Level integrity** for a compiled compendium pack.
  *
  * A v14 Scene keeps its map image on an embedded `Level`, and a compiled pack
  * stores the two in *separate* LevelDB keys: the Scene at `!scenes!<id>`

package/engine/scenes.mjs

@@ -13,8 +13,7 @@
 
 /**
  * Scenes pack compiler — map notes in `assets/content/` → Foundry `Scene`
- * documents, and the `Adventure` bundles that make their references resolve
- * (issue #1525).
+ * documents, and the `Adventure` bundles that make their references resolve.
  *
  * The translation itself lives in the framework-free `map-notes.mjs`; this
  * module is the pass that walks the tree, resolves what one note says about
@@ -44,7 +43,7 @@
  *
  * The walk itself — filtering by type, expanding tables, converting
  * wikilinks, writing the JSON and counting errors — belongs to {@link sohl.utils.packs.BasePackCompiler}; this module
- * states only what makes this pass its own (#1509).
+ * states only what makes this pass its own.
  */
 
 import fs from "fs";
@@ -62,12 +61,12 @@ import {
 import { BasePackCompiler } from "./base-compiler.mjs";
 // What an Adventure member may carry is one rule, and the module that owns the
 // Adventure states it: the scenes pass bundles its pinned places, and the
-// bundles pass compiles a note into one (#259).
+// bundles pass compiles a note into one.
 import { stripAdventureKeys } from "./bundle-notes.mjs";
 import { buildJournalEntry, splitPages, journalPageId } from "./journals.mjs";
 import { compendiumUuid, makeId, packForType } from "./ids.mjs";
 // The record accessors only — see `engine/index-records.mjs` for why they live
-// apart from the index that builds them (#243).
+// apart from the index that builds them.
 import { authoredFrontmatter, isNoteRecord, noteFile } from "./index-records.mjs";
 import { packRouter } from "./pack-router.mjs";
 import { foundryPackageId } from "./content-package.mjs";
@@ -124,8 +123,8 @@ export class Scenes extends BasePackCompiler {
      * A map note's `img` is its background art, and it is **required**: the map
      * compiler refuses a note without one. It lands on the scene's level rather
      * than on a property spelled `img`, which makes no difference to the
-     * question this declaration answers — the authored path reaches the output
-     * (#349). The place Adventure this pass bundles carries it too.
+     * question this declaration answers — the authored path reaches the output.
+     * The place Adventure this pass bundles carries it too.
      *
      * @type {readonly string[]}
      */
@@ -182,7 +181,7 @@ export class Scenes extends BasePackCompiler {
      * `generatePack` hands every pass the one router the compile resolved, and
      * that is the answer whenever a real compile is running — a second router
      * is a second answer to where a document landed, built from whichever
-     * configuration the working directory offers (#243). A compiler
+     * configuration the working directory offers. A compiler
      * constructed directly, as a consumer's or a test's is, has none, and falls
      * back exactly as `prepare` falls back to deriving its own corpus.
      *
@@ -196,19 +195,19 @@ export class Scenes extends BasePackCompiler {
         const maps = [];
         const effectsByAddress = new Map();
         // The corpus this compile derived once, not a walk of this pass's own
-        // (#243) — and a note is opened only when this pass needs its *prose*,
+        // — and a note is opened only when this pass needs its *prose*,
         // which for a map note means three files in `sohl` rather than 1,685.
         for (const record of this.corpus.records) {
             if (!isNoteRecord(record)) continue;
             // No retired-field test: this pass's own walk — the shared compile
-            // loop — is where a note still declaring `package:` (#56) or
-            // `draft:` (#69) is reported, once. Repeating either check here
+            // loop — is where a note still declaring `package:` or
+            // `draft:` is reported, once. Repeating either check here
             // would double the diagnostic or throw past it. A refused note is
             // indexed and then never compiled, so it reaches no document.
             const fm = authoredFrontmatter(record);
             const absPath = noteFile(this.contentBase, record);
             // The id is the index's, derived against the configuration this
-            // build resolved (#270, #243) — it was derived here through
+            // build resolved — it was derived here through
             // `resolveNoteId(fm)` with no package, which falls back to the
             // ambient one. What remains unset is a file with no address.
             if (!fm || !fm.id) continue;
@@ -218,10 +217,10 @@ export class Scenes extends BasePackCompiler {
                     type: fm.type,
                     // Where the owning item landed, so a region behaviour's
                     // effect reference addresses the right pack when a
-                    // repository ships several of one type (#1566).
+                    // repository ships several of one type.
                     // This compile's router, not a freshly built one: a
                     // second router is a second answer to where the document
-                    // landed, resolved from the working directory (#243).
+                    // landed, resolved from the working directory.
                     pack: this.#packRouter.resolveOrNull(fm, packForType(fm.type).docType),
                     effects: fm.effects,
                 });
@@ -409,7 +408,7 @@ export class Scenes extends BasePackCompiler {
         const name = resolveName(fm);
         const hasBody = Boolean(String(markdown).trim());
         // The same doc-entry id the journals pass derives, from the
-        // shared `docEntryTypes` arrangement (#1514) — so neither
+        // shared `docEntryTypes` arrangement — so neither
         // pass has to read the other's output.
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
         const { value: authoredFolder } = folderField(fm);
@@ -423,8 +422,8 @@ export class Scenes extends BasePackCompiler {
             journalEntryId: entryId,
             // A map note's prose is a derived JournalEntry: it lands in the
             // default JournalEntry pack, not in whichever Scene pack the map
-            // itself was routed to (#1566).
-            // This compile's router, as everywhere else in this pass (#243).
+            // itself was routed to.
+            // This compile's router, as everywhere else in this pass.
             journalPack: this.#packRouter.defaultOf("JournalEntry"),
             pageIds: hasBody ? this.#pageIds(markdown, entryId, name) : new Map(),
             knownActions: this.knownActions,
@@ -432,7 +431,7 @@ export class Scenes extends BasePackCompiler {
             ...this.#resolvers(this.index, this.effectsByAddress, fm.shortcode),
         });
         for (const message of warnings) {
-            // Named by file, like every other note diagnostic (#17). A map
+            // Named by file, like every other note diagnostic. A map
             // warning is about the note's frontmatter, which carries no
             // offset, so it names the file and stops there rather than
             // pointing at a line it cannot establish.
@@ -452,8 +451,8 @@ export class Scenes extends BasePackCompiler {
                     leadName: name,
                     // As in the journals pass: an address resolves in the
                     // pack that emits it, which is what makes the folder
-                    // materialise there too (#257). The id spelling that used
-                    // to cross packs verbatim is retired (#260).
+                    // materialise there too. The id spelling that used
+                    // to cross packs verbatim is retired.
                     folder: this.folderResolver(authoredFolder, { isAddress: true }),
                     flags: fm.flags,
                 })

package/engine/schema-check.mjs

@@ -13,7 +13,7 @@
 
 /**
  * What a builder **emits** into `system`, against what the receiving DataModel
- * **declares** (#60).
+ * **declares**.
  *
  * Foundry discards an unknown `system` key when a document is constructed, and
  * says nothing: the value is simply absent at load, while the build that wrote
@@ -22,7 +22,7 @@
  *
  * - **Emitted, not declared.** `mysticalability` emitted `assocMysteryCode`,
  *   which no DataModel defined — 0.8.x had replaced it with
- *   `assocAffiliationCode` (#35). And `affiliation.subType`, authored on all 21
+ *   `assocAffiliationCode`. And `affiliation.subType`, authored on all 21
  *   of `sohl-kethira-basic`'s deities, is not defined at the version that module
  *   targets, so the divine/arcane split evaporates on load.
  * - **Declared, not emitted.** The mirror image, fixed by hand in
@@ -39,8 +39,8 @@
  *
  * **The rest of the emission is only observable.** A compiler writes keys of
  * its own alongside the declared fields — `shortcode`, `actionDefs`, `notes`,
- * `docHtml`, and since #126 `templatePriority` — and those appear in neither set
- * {@link compareFields} compares, so nothing compared them at all (#155). They
+ * `docHtml` and `templatePriority` — and those appear in neither set
+ * {@link compareFields} compares, so nothing compared them at all. They
  * cannot be listed here without the list going stale the next time a compiler
  * grows a key, so they are read off the `system` object the compiler produced:
  * {@link compareEmittedSystem} takes the assembled block and asks what the
@@ -69,7 +69,7 @@ import { cachedSchemaPath, SCHEMA_ARTIFACT_FILE } from "./foreign-catalog.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { systemData, systemDataPaths, undeclaredPaths } from "./system-block.mjs";
 // A field the document writes for itself in play: declared by the schema,
-// emitted by no builder, and authored by no note (#330).
+// emitted by no builder, and authored by no note.
 import { runtimeOnlyFields } from "./field-spec.mjs";
 
 /**
@@ -77,7 +77,7 @@ import { runtimeOnlyFields } from "./field-spec.mjs";
  *
  * A mismatch stops the check rather than resolving anyway: a schema read under
  * the wrong shape would report confident nonsense in both directions, and a
- * silently skipped check is the state #60 exists to leave.
+ * silently skipped check is the state this exists to leave.
  *
  * @type {number}
  */
@@ -136,7 +136,7 @@ export function declaredFields(artifact, documentType, subtype) {
  * the path beneath it separately, so a comparison that knew only the leaf would
  * report the container as unemitted and the leaf as undeclared.
  *
- * **A runtime-only field is not in it** (#330). It declares a `to` in order to
+ * **A runtime-only field is not in it**. It declares a `to` in order to
  * *claim* the path — so the verbatim passthrough leaves it alone and the
  * refusal has something to name — and `buildFromFields` deliberately skips it,
  * because the document writes that field in play. Counting it here would make
@@ -196,7 +196,7 @@ function coveredByAncestor(path, emitted) {
  *   compile into.
  * @param {(type: string) => string} [opts.subtypeOf] - Maps a builder's type to
  *   the document subtype it emits. Defaults to identity, which is what the
- *   coincidence of names amounts to today (#79) — stated as a seam so that the
+ *   coincidence of names amounts to today — stated as a seam so that the
  *   explicit map replaces a default rather than a hard-coded assumption.
  * @returns {{undeclared: object[], unemitted: object[], skipped: string[]}}
  *   `undeclared` fails a build; `unemitted` is reported; `skipped` names the
@@ -226,14 +226,14 @@ export function compareFields({
         const declared = declaredFields(artifact, documentType, subtype);
         if (!declared) {
             // Not a finding: a builder may compile into a type this system does
-            // not define at all, which is a routing question (#79) rather than a
+            // not define at all, which is a routing question rather than a
             // field one. Named so the count is never mistaken for coverage.
             skipped.push(type);
             continue;
         }
 
         const emitted = emittedFields(fields);
-        // Paths the declaration says the *document* writes in play (#330). They
+        // Paths the declaration says the *document* writes in play. They
         // are neither emitted nor a defect, so they answer the unemitted
         // question below rather than appearing in it: "every compiled document
         // will carry the field's initial value" is exactly what a runtime-only
@@ -373,7 +373,7 @@ function undeclaredEmittedPaths(data, declared, enumerated, prefix = "") {
 
 /**
  * What a **compiled document** carries in `system`, against what the receiving
- * subtype declares (#155).
+ * subtype declares.
  *
  * The third of the three checks, and the only one whose emitted set is
  * *observed*. {@link compareFields} reads the `itemBuilders` declarations and
@@ -430,7 +430,7 @@ export function compareEmittedSystem({
 
     const declared = declaredFields(artifact, documentType, subtype);
     // Not a finding, for the same reason `compareFields` skips one: a subtype
-    // the artifact says nothing about is a routing question (#79), not a field
+    // the artifact says nothing about is a routing question, not a field
     // one, and guessing at it would report every key on the document.
     if (!declared) return [];
 
@@ -457,7 +457,7 @@ export function compareEmittedSystem({
  * The published schema this build should check itself against, or `null`.
  *
  * **Which system, and which version, are already settled.** `stats.systemId`
- * and `stats.systemVersion` are derived rather than authored (#48) — a system
+ * and `stats.systemVersion` are derived rather than authored — a system
  * package is its own system, and a module takes the one it requires — and the
  * version is the `compatibility.verified` it pins. So the question "whose
  * schema, at what version" has one answer here rather than a second set of
@@ -477,12 +477,12 @@ export function compareEmittedSystem({
  * stamps no system at all, and a system that has not adopted the artifact yet
  * is simply unchecked. Neither is an error, and the caller says which it was.
  *
- * **A build may have more than one system, and then the caller names it (#139).**
+ * **A build may have more than one system, and then the caller names it.**
  * `stats.systemId` is the package-wide answer, and a repository shipping content
  * for two systems has no package-wide answer — it is deliberately `null` there,
  * because a module feeding both `sohl` and `hm3` targets neither. Left at that,
  * every schema check in such a build would be skipped in silence, which is the
- * state #60 exists to remove: the five type names the two systems *share* are
+ * state this exists to remove: the five type names the two systems *share* are
  * exactly the ones a wrong-system emission hides in. So a pass supplies the
  * system its pack declares, and the version comes from that system's own
  * `systems:` entry rather than from a package-wide stamp.
@@ -606,7 +606,7 @@ const artifacts = new WeakMap();
  * The per-note check below runs thousands of times in a build and an artifact
  * never changes inside one, so reading and parsing it per note would be a
  * megabyte of JSON per hundred documents for an answer that is already known.
- * Keyed by system as well as by configuration since #139: a build with two
+ * Keyed by system as well as by configuration: a build with two
  * systems has two artifacts, and caching one of them under the configuration
  * alone would hand every pass whichever system asked first.
  *
@@ -624,7 +624,7 @@ function schemaFor(config, system = undefined) {
 
 /**
  * What a note authors under `<system>.system`, against what the receiving
- * subtype declares (#58).
+ * subtype declares.
  *
  * The **note-side** half of the check `compareFields` performs on the
  * declarations. A field list is checked once for the whole build because it is
@@ -649,7 +649,7 @@ function schemaFor(config, system = undefined) {
  * @param {string} opts.documentType - `Item`, `Actor`, …
  * @param {string} opts.subType - The document subtype the note compiles into.
  * @param {string} [opts.system] - The system whose published schema to read,
- *   where a build has more than one (#139). Defaults to the package-wide
+ *   where a build has more than one. Defaults to the package-wide
  *   `stats.systemId`.
  * @param {object} [opts.config] - The resolved build configuration.
  * @returns {{path: string, message: string}[]} One finding per undeclared path,
@@ -680,7 +680,7 @@ export function checkAuthoredSystemData(
 
 /**
  * The `system` block a compiler just assembled, against what the receiving
- * subtype declares (#155).
+ * subtype declares.
  *
  * The build-time face of {@link compareEmittedSystem}: it resolves the schema
  * the way every other check here does — the system's own committed artifact, or
@@ -703,7 +703,7 @@ export function checkAuthoredSystemData(
  * @param {readonly {to?: string}[]} [opts.fields] - The type's field
  *   declaration, which decides each finding's origin.
  * @param {string} [opts.system] - The system whose published schema to read,
- *   where a build has more than one (#139). Defaults to the package-wide
+ *   where a build has more than one. Defaults to the package-wide
  *   `stats.systemId`.
  * @param {object} [opts.config] - The resolved build configuration.
  * @returns {(EmissionFinding & {message: string})[]} One per undeclared path.

package/engine/schema-extract.mjs

@@ -17,7 +17,7 @@
  * The consuming half of this contract already lives in `schema-check.mjs`: a
  * content build subtracts what its builders emit from what a document will
  * actually receive, because Foundry discards an unknown `system` key at
- * construction and says nothing about it (#60). What was missing is the
+ * construction and says nothing about it. What was missing is the
  * producing half — until now each system carried its own extractor, and the
  * first one to exist hardcoded {@link SCHEMA_ARTIFACT_VERSION}, a constant this
  * package owns. Two producers stamping a third repository's constant by hand is