@heroiclands/package-build 20.3.1 → 20.5.0

package/lang.mjs

@@ -29,13 +29,13 @@
  *   `expandObject` **throws**: it cannot create a `Note` property on the string
  *   `"The Pall"`. Foundry catches that throw and discards the **entire** file,
  *   so one colliding pair drops every translation in it and each string renders
- *   as its raw key (#636). A key must be a leaf **or** a branch, never both.
+ *   as its raw key. A key must be a leaf **or** a branch, never both.
  * - **A Handlebars placeholder.** Foundry interpolates with `format()` and
  *   SINGLE braces, so a `{{…}}` value renders literally unless some call site
- *   happens to hand it to a Handlebars pass (#1353).
+ *   happens to hand it to a Handlebars pass.
  * - **Data baked into a key segment.** A segment carrying anything but
  *   `[A-Za-z0-9_-]` is a path or a UUID in a key, and a dotted payload is how
- *   the collision above gets in (#636, #1351).
+ *   the collision above gets in.
  *
  * Every function here is pure — it takes source text and returns findings, and
  * touches no filesystem and emits nothing. The caller owns discovery and

package/manifest.mjs

@@ -18,16 +18,13 @@
  * so there is one job here with two spellings: assemble the manifest from the
  * repository's configuration and write it into the build stage.
  *
- * **There is no template any more.** A manifest used to be a hand-authored
- * `system.template.json` that this module stamped a few fields into — which
- * made it the one build input still written as JSON, by hand, per repository,
- * with no schema and nothing checking it. Worse, it declared facts the
- * configuration also declared: the pack list twice, in two formats, with
- * nothing checking that the pairs agreed. `sohl-kethira-basic` hand-maintained
- * its whole `module.json`, and its `download` named an older version than the
- * module claimed.
+ * **There is no template.** A `system.template.json` this module stamped a few
+ * fields into would be the one build input written as JSON, by hand, per
+ * repository, with no schema and nothing checking it — and it would declare
+ * facts the configuration also declares, the pack list twice in two formats,
+ * with nothing checking that the pairs agree.
  *
- * So the manifest is generated (#9). Three kinds of key end up in it:
+ * So the manifest is generated. Three kinds of key end up in it:
  *
  * - **Declared** — the `packageBuild.manifest` block, emitted unchanged, so a
  *   key Foundry adds in a later version needs no release of this package.
@@ -122,7 +119,7 @@ export function releaseUrls({ repoUrl, version, artifact }) {
 }
 
 /**
- * Where this release publishes its content index (#239).
+ * Where this release publishes its content index.
  *
  * **Pinned to this version, like `download` and unlike `manifest`.** A
  * consumer reaches this URL by reading the dependency's manifest, so the
@@ -183,7 +180,7 @@ const MANIFEST_KEY_ORDER = Object.freeze([
 /**
  * The manifest's `packs`, derived from the one pack list the build already has.
  *
- * The two used to be written separately — `package-build.config.yaml` declared
+ * The two are not written separately, with `package-build.config.yaml` declaring
  * a pack's name and type, and the manifest template declared them again beside
  * a label, a path and a system id, with nothing checking that the pairs agreed.
  * They are one list now.
@@ -265,12 +262,12 @@ function namedPacks(folders, at) {
  * `styles`, `languages`), and a staged file is a different relation, checked
  * against the stage rather than against configuration. So this is the one place
  * a declaration can go stale against a value the build already computed — and
- * until now nothing compared them (#81).
+ * until now nothing compared them.
  *
  * `HarnMaster-3-FoundryVTT` shipped the consequence: its folder named four
  * packs, three of which had not existed since the compendium was consolidated,
  * and omitted `items` — 1,577 of 1,597 documents, loose in Foundry's compendium
- * browser, with the build reporting nothing (HM3#420).
+ * browser, with the build reporting nothing.
  *
  * **The two findings are not the same finding**, and giving them one severity
  * gets one of them wrong:
@@ -343,14 +340,14 @@ export function packFolderFindings({ packFolders, packs = [] }) {
  *
  * `relationships` is the one manifest block with a second reader.
  * `@heroiclands/content-build` consumes it too, and v1.8.0 added
- * `itemCatalog: true` as an opt-in on a declared dependency
- * (content-build#82): it selects that package's Item packs as a resolution
+ * `itemCatalog: true` as an opt-in on a declared dependency: it selects that
+ * package's Item packs as a resolution
  * source for the actors pass. That is an instruction to the build, not a fact
  * about the shipped package — Foundry's relationship schema does not define
  * it, and someone reading a published manifest cannot tell a build directive
  * from a declaration about what the package needs.
  *
- * So the block is filtered rather than copied whole (#29). The rule is the
+ * So the block is filtered rather than copied whole. The rule is the
  * distinction, not the name: a key listed here answers *how is this built?*,
  * and every key that survives answers *what does this package depend on?*.
  * `itemCatalog` is the first build-time key to land on a relationship and is
@@ -441,7 +438,7 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     };
     if (config.compatibility) derived.compatibility = config.compatibility;
 
-    // `requiresSystem` is the gate half of the declare/require split (#48). It
+    // `requiresSystem` is the gate half of the declare/require split. It
     // emits the `relationships.systems` entry Foundry's `supportsSystem` reads,
     // reusing the `systems:` declaration rather than restating it — a second
     // transcription is free to disagree with what it copied, which is how
@@ -476,8 +473,8 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
 
     const merged = { ...declared, ...derived };
 
-    // The index every consumer resolves this package's addresses through
-    // (#239). Written unconditionally, because a package that publishes no
+    // The index every consumer resolves this package's addresses through.
+    // Written unconditionally, because a package that publishes no
     // index is one nothing can link into — and the failure of an absent one is
     // a dead link in somebody else's build, which is exactly the kind of
     // silence this replaced the vendored manifest to end.
@@ -562,7 +559,7 @@ function reportPackFolders(findings, configFile) {
  * The declared `packFolders` is checked against the derived `packs[]` first,
  * and an unresolvable name **stops the write**: a manifest already known to
  * describe packs the package does not ship should not reach the stage, where
- * the next command would deploy it (#81). See {@link packFolderFindings} for
+ * the next command would deploy it. See {@link packFolderFindings} for
  * the rule and why its two findings carry different severities.
  *
  * @param {object} options - As {@link buildManifest}, plus where to write.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "20.3.1",
+    "version": "20.5.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -101,7 +101,6 @@
         "CHANGELOG-content-build.md",
         "CHANGELOG.md",
         "CONTENT.md",
-        "MIGRATING.md",
         "README.md",
         "bin",
         "bundle.mjs",

package/release.mjs

@@ -19,7 +19,7 @@
  * advertises, so a release publishes `<artifact>.zip`, the whole staged tree,
  * and `<artifact>.json` beside it, which is what an already installed package
  * re-fetches to notice a new version. A package that ships content publishes a
- * third: the content index other packages resolve its addresses through (#239),
+ * third: the content index other packages resolve its addresses through,
  * named by the `flags.metadataUrl` the manifest advertises. Every name is fixed
  * by what the manifest says, not chosen here — see `manifest.mjs`.
  *
@@ -37,7 +37,7 @@ import path from "node:path";
 // archiver 8 is pure ESM and exports **classes**, with no default export. The
 // old `import archiver from "archiver"` factory call throws at import —
 // `does not provide an export named 'default'` — which is how this repository's
-// release job came to fail before a single byte was written (#1683).
+// release job came to fail before a single byte was written.
 import { ZipArchive } from "archiver";
 
 /**
@@ -57,10 +57,17 @@ import { ZipArchive } from "archiver";
  *   Determines both asset names.
  * @param {string} [opts.metadataDir] - Where the build writes its content
  *   index, consulted when the advertised file was not staged.
+ * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
+ *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   bytes: number, version: string}>} The paths written, the archive's size,
- *   and the version the manifest declares. `metadata` is absent when the
- *   manifest advertises no content index.
+ *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   bytes: number, version: string}>} The paths written, what the book build
+ *   found, the archive's size, and the version the manifest declares.
+ *   `metadata` is absent when the manifest advertises no content index, and
+ *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
+ *   book was built, and otherwise the reason none was — itself `null` when the
+ *   book builder could not be loaded, which is reported through
+ *   `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -69,6 +76,7 @@ export async function packRelease({
     outDir = "build/dist",
     artifact = "system",
     metadataDir = "build/content-index",
+    pdf = true,
 } = {}) {
     const stage = path.resolve(stageDir);
     const out = path.resolve(outDir);
@@ -112,17 +120,69 @@ export async function packRelease({
 
     const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
 
+    // Last, and never fatal: the archive and the manifest are the release, and
+    // a book that failed to set is a reported problem rather than a reason to
+    // publish neither.
+    const book =
+        pdf ?
+            await packReleasePdf({ out, version: manifest.version })
+        :   { pdf: null, findings: [], reason: "the release was asked not to build one" };
+
     return {
         zip: zipPath,
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
+        ...(book.pdf ? { pdf: book.pdf } : {}),
+        pdfFindings: book.findings,
+        pdfSkipped: book.pdf ? null : book.reason,
         bytes: archive.pointer(),
         version: manifest.version,
     };
 }
 
 /**
- * Place the content index the manifest advertises beside the archive (#239).
+ * Build the book that ships beside the archive.
+ *
+ * **Imported when it is used, not when this module is.** The book build pulls
+ * in a markdown parser, DuckDB and the whole content engine; `release.mjs`
+ * otherwise exists to zip a directory, and every consumer that publishes no
+ * book would pay for that graph on `import`. A dynamic import inside the one
+ * function that needs it keeps the cost where the benefit is.
+ *
+ * **Not building is the normal case and never an error.** A package publishing
+ * only a homepage, one with no `pdf:` block and one with no content tree have
+ * each said they publish no book. Four of the six packages that install this
+ * toolchain are in exactly that position, so a release that failed for the
+ * absence of a PDF would break more releases than it helped.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.out - The release directory.
+ * @param {string} opts.version - The version the manifest declares.
+ * @returns {Promise<{pdf: string|null, findings: object[], reason: string|null}>}
+ *   What was built, and what was found on the way.
+ */
+async function packReleasePdf({ out, version }) {
+    let buildPdf;
+    try {
+        ({ buildPdf } = await import("./engine/pdf-build.mjs"));
+    } catch (err) {
+        return {
+            pdf: null,
+            findings: [
+                {
+                    severity: "warning",
+                    message: `the book builder could not be loaded: ${err.message}`,
+                },
+            ],
+            reason: null,
+        };
+    }
+    const result = await buildPdf({ out, version });
+    return { pdf: result.pdf, findings: result.findings, reason: result.reason };
+}
+
+/**
+ * Place the content index the manifest advertises beside the archive.
  *
  * **The asset's name comes from the manifest, not from here.** `flags.metadataUrl`
  * is the URL every consumer fetches, so its basename is by definition the name

package/sohl/actors.mjs

@@ -17,21 +17,21 @@
  * The machinery an actor of any system needs — the predefined-item catalogue,
  * reference translation through the system's map, embedding and its stable ids,
  * the anchored prose sections — lives in
- * {@link module:engine/actor-compiler}, where a second system reaches it
- * (#139). What is left here is SoHL's data model: the body structure and its
+ * {@link module:engine/actor-compiler}, where a second system reaches it.
+ * What is left here is SoHL's data model: the body structure and its
  * movement profiles, the attributes-and-items frontmatter that becomes embedded
  * documents, the opening mastery level a skill is baked with, and the `system`
  * block itself.
  *
  * One content type today, and the actor subtype it produces is **declared**
  * rather than assumed to be the same word: `sohl/document-subtypes.mjs` maps
- * `being` → `Actor` / `being`, and this pass looks it up (#79). It read
+ * `being` → `Actor` / `being`, and this pass looks it up. It read
  * `ACTOR_VAULT_TYPE = "being"` here and emitted `type: "being"` several hundred
  * lines below, which made the two vocabularies agree by coincidence.
  *
  * It was two content types — `character` and `creature` — which compiled to the
  * same `being` with no branch anywhere between them; they were retired in
- * SoHL#1580 and are now reported by `assertTypeNotRetired` in
+ * retired, and are reported by `assertTypeNotRetired` in
  * `engine/ids.mjs`.
  *
  * Attributes (`sohl.attributes` map) become embedded attribute items with
@@ -56,16 +56,16 @@ import {
 import { openingMasteryLevel } from "./skill-base.mjs";
 import { SystemActorCompiler, renderSection } from "../engine/actor-compiler.mjs";
 // Which Foundry Actor subtype a note's `type` compiles into. Looked up in the
-// system's declared map, never inferred from the type itself (#79).
+// system's declared map, never inferred from the type itself.
 import { documentSubtype } from "../engine/document-subtypes.mjs";
 import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 // The note-level `sohl:` block: `sohl.system` onto the document's `system`
 // verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
-// shared top-level forms for this system alone (#58).
+// shared top-level forms for this system alone.
 import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
 import { readField, retiredTopLevelKey } from "../engine/field-spec.mjs";
 // The retirement window's reports, shared with the frontmatter lint so the two
-// cannot say different things about the same key (#305, #332).
+// cannot say different things about the same key.
 import {
     legacyKeyMessage,
     locateFrontmatterKey,
@@ -76,7 +76,7 @@ import {
  * The system this pass compiles for — the block its notes write.
  *
  * Read from the map rather than spelled here, so the block name and the subtype
- * map are one statement (#58/#79).
+ * map are one statement.
  *
  * @type {string}
  */
@@ -98,7 +98,7 @@ const DEFAULT_IMG = {
  * and the note's top level and nothing else — so `data.portrait`, the position
  * the specification names and `sohl-thalorna` writes on 646 beings, was
  * invisible, and `?? defaultImg` on the next line turned every miss into the
- * generic person icon rather than into a complaint (#332). Going through
+ * generic person icon rather than into a complaint. Going through
  * {@link module:engine/field-spec.readField} is what makes the mapping table
  * executable here as it already is for HM3's `data.species`.
  *
@@ -115,7 +115,7 @@ const PORTRAIT_FIELD = Object.freeze({
     shape: "path",
     // The two empties survive, because the caller's `?? defaultImg` is what
     // tells them apart: `null` and an absent key mean "no art named, default
-    // me", `""` means "ship blank on purpose" (#218).
+    // me", `""` means "ship blank on purpose".
     read: (raw) => resolveImg(raw),
     default: null,
     describe: "Path to the portrait image.",
@@ -190,11 +190,19 @@ function extractBodyAndMovement(fm) {
     };
 }
 
+/**
+ * SoHL's Actor compile pass.
+ *
+ * Declares SoHL's note-type → document-subtype map and builds a `being` note's
+ * document: the body structure and its movement profiles, the embedded
+ * attribute and item documents the frontmatter names, and the `system` block.
+ * Everything else is {@link module:engine/actor-compiler}'s.
+ */
 export class Actors extends SystemActorCompiler {
     /**
      * SoHL's note-type → document-subtype map — the one declaration that says
      * which block this pass reads, which notes it claims, and what each
-     * becomes (#79). It is also what every embedded reference is translated
+     * becomes. It is also what every embedded reference is translated
      * through, which is why a subclass replaces one thing and not two.
      *
      * @type {import("../engine/document-subtypes.mjs").DocumentSubtypeMap}
@@ -298,7 +306,7 @@ export class Actors extends SystemActorCompiler {
     }
 
     /**
-     * Bake each unopened skill's opening mastery level into the document (#46).
+     * Bake each unopened skill's opening mastery level into the document.
      *
      * A skill whose `masteryLevelBase` is still null once the note's frontmatter
      * has been merged onto the catalogue entry is *not yet opened*, and the
@@ -352,7 +360,7 @@ export class Actors extends SystemActorCompiler {
         const id = fm.id;
         const ctx = `actor "${name}"`;
         // The document's own subtype, and the art that goes with it. Both are
-        // looked up from the note's `type` rather than spelled here (#79).
+        // looked up from the note's `type` rather than spelled here.
         const subType = /** @type {string} */ (
             documentSubtype(this.constructor.documentSubtypes, fm.type, fm, {
                 absPath: this.currentNote?.absPath,
@@ -365,13 +373,13 @@ export class Actors extends SystemActorCompiler {
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
-        // The two retiring positions a declared field may be read from (#305,
-        // #332). **Warnings**, on the pattern every retirement in this package
+        // The two retiring positions a declared field may be read from.
+        // **Warnings**, on the pattern every retirement in this package
         // follows: the note compiles to the correct document either way, so
         // reddening a tree over one would refuse before the sweep rather than
-        // after it. What they buy is a count — the whole reason #332 was
-        // invisible for so long is that nothing said which position a value
-        // had come from, and a default is indistinguishable from a miss.
+        // after it. What they buy is a count — without one, nothing says which
+        // position a value came from, and a default is indistinguishable from
+        // a miss.
         const portraitReports = {
             block: SYSTEM,
             onLegacyKey: (field) =>
@@ -398,25 +406,25 @@ export class Actors extends SystemActorCompiler {
         const system = {
             // The frontmatter shortcode is the actor's stable `(type, shortcode)`
             // key — and, for a being that is an archetype, its archetype
-            // identity (the dedup/override key of the Create-dialog picker, #604).
+            // identity (the dedup/override key of the Create-dialog picker).
             shortcode: fm.shortcode || "",
             // Required nullable number: a priority, or `null` for a being that
-            // is not a template (#126 / archetype contract #604). The field was
-            // `system.archetype` until #266 / sohl#1836; the emitted key moves
+            // is not a template (the archetype contract). `system.archetype`
+            // is the legacy spelling; the emitted key moves
             // with the schema, since an undeclared `system` key is discarded at
             // construction without a warning.
             templatePriority: systemTemplatePriority(fm, ctx),
-            // Nullish, not `||` (#218): a note that names no portrait gets the
+            // Nullish, not `||`: a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
             // Resolved through the declaration so `data.portrait` is reached at
-            // all — see {@link PORTRAIT_FIELD} (#332).
+            // all — see {@link PORTRAIT_FIELD}.
             portrait: readField(PORTRAIT_FIELD, fm, portraitReports) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };
 
         // Fill `system.body` (+ the base-actor movement fields) from the being's
-        // frontmatter, rather than embedding a corpus item (#535). The `sohl`
+        // frontmatter, rather than embedding a corpus item. The `sohl`
         // block mirrors `system` field-for-field: `sohl.body` nests the body
         // (`structure` / `weight` / …), with `currentMoveMedium` /
         // `movementProfiles` flat alongside it. An **incorporeal** being omits
@@ -441,14 +449,14 @@ export class Actors extends SystemActorCompiler {
         }
 
         // Whatever the note authors under `sohl.system`, at the DataModel's own
-        // paths (#58). This pass has no field declaration, so it claims
+        // paths. This pass has no field declaration, so it claims
         // nothing: every authored path is the author's, and the fields above
         // are what a note that authors none still gets.
         mergeSystemData(system, fm, { block: SYSTEM });
         this.reportUndeclaredSystemData(fm, SYSTEM, "Actor", subType);
         // And what this pass wrote itself. There is no field declaration for a
         // being at all, so *every* key here is a compiler emission — including
-        // `templatePriority` (#126), which nothing compared until #155.
+        // `templatePriority`, which nothing compared until.
         this.reportEmittedSystemData(system, {
             fm,
             block: SYSTEM,
@@ -462,7 +470,7 @@ export class Actors extends SystemActorCompiler {
         return {
             name,
             type: subType,
-            // Nullish, not `||` — see the portrait above (#218).
+            // Nullish, not `||` — see the portrait above.
             img: resolveImg(blockProperty(fm, SYSTEM, "img")) ?? defaultImg,
             _id: id,
             system,
@@ -483,7 +491,7 @@ export class Actors extends SystemActorCompiler {
             ownership: { default: 0 },
             // Whatever the note authors, and nothing else. The priority used to
             // be spliced in here as `flags.sohl.docArchetype`; it is a schema
-            // field now and sits in `system` (#126).
+            // field now and sits in `system`.
             flags: blockProperty(fm, SYSTEM, "flags", {}),
             _stats: this.stats,
             _key: `!actors!${id}`,

package/sohl/affiliation-standings.mjs

@@ -13,12 +13,12 @@
 
 /**
  * The affiliation standings an authored `relation` map may use — one
- * affiliation's stance toward another (#1404).
+ * affiliation's stance toward another.
  *
  * Plain ESM for the same reason `./default-item-art.mjs` is: the pack scripts
  * run under bare `node`, so they cannot read the runtime's TypeScript
  * `AFFILIATION_STANDING`. This module is where the pipeline reads the list
- * from, rather than restating it inside a compiler (#1510).
+ * from, rather than restating it inside a compiler.
  *
  * The runtime keeps its own `defineType("SOHL.Affiliation.Standing", { … })`
  * declaration in `src/utils/constants.ts`, because that literal is *parsed out

package/sohl/being-info.mjs

@@ -24,9 +24,9 @@
  * **It lives here because it was living in two places.** Both
  * `Song-of-Heroic-Lands-FoundryVTT` and `sohl-thalorna` carried a copy, and the
  * copies drifted: SoHL's caller still gated the derivation on `character` and
- * `creature`, the two types #1580 merged into `being`, so it had matched
+ * `creature`, the two legacy spellings of `being`, so it had matched
  * nothing since the merge and all 95 of its being pages published with empty
- * sidebar sections (SoHL#1696). thalorna's copy checked `being` and was right.
+ * sidebar sections. thalorna's copy checked `being` and was right.
  * Nothing failed in either repository; the pages built and shipped.
  *
  * {@link isBeing} exists for that reason. The bug was not in the derivation —
@@ -36,14 +36,14 @@
  * @module
  */
 
-// The retirement window for a renamed note type (#78): an embedded reference
+// The retirement window for a renamed note type: an embedded reference
 // still spelling `armorgear` names the same gear group as `armor`.
 import { currentType } from "../engine/ids.mjs";
 
 /**
  * The note `type` whose pages carry a being info block.
  *
- * One name, since #1580 merged `character` and `creature` into the `being` they
+ * One name: `character` and `creature` are the `being` they
  * had always compiled into. The retired names are deliberately **not** accepted
  * as aliases: they throw elsewhere in the system, and tolerating them here
  * would hide the next drift of this kind rather than surface it.
@@ -68,7 +68,7 @@ export function isBeing(fm) {
  * added in a single place rather than in each consumer's site build.
  *
  * Keyed by **note** type, which is what a being's embedded `(type, shortcode)`
- * references spell — and since #78 three of those are no longer the document
+ * references spell — and three of those are not the document
  * subtype they compile into. A reference still on a renamed spelling is
  * normalised at the lookup below rather than given a second row here.
  *

package/sohl/default-item-art.mjs

@@ -27,15 +27,15 @@
  * runtime can both import it. A `.ts` module could not be required by the build
  * scripts (they run under bare `node`, without the bundler that resolves the
  * `@src` alias and strips types). Keeping one map here is what prevents the
- * build-time and runtime defaults from drifting apart (issue #932 was exactly
+ * build-time and runtime defaults from drifting apart (which is exactly
  * that drift: the builder had a default, runtime did not).
  *
  * It lives in this package rather than in the system's `src/` tree because the
- * pack pipeline is installed as a dependency (#1501): a relative path out of
+ * pack pipeline is installed as a dependency: a relative path out of
  * the package would resolve to garbage once the pipeline runs from
  * `node_modules`. The runtime imports it back through the package's
- * `./sohl/default-item-art` entry point, so there is still exactly one map
- * (#1510). Injecting the map through configuration instead would re-open #932,
+ * `./sohl/default-item-art` entry point, so there is still exactly one map.
+ * Injecting the map through configuration instead would re-open that drift,
  * because the two sides would once more be free to disagree.
  *
  * Paths are fully resolved (`systems/sohl/...`) — the served path both layers
@@ -44,7 +44,7 @@
  * **The keys are SoHL *document* subtypes, not markdown note types.** The
  * runtime reads this with `itemData.type`, which is a Foundry Item subtype, and
  * that is the vocabulary a compendium document carries. The two vocabularies
- * were the same string until #78 renamed three note types (`armorgear` →
+ * would be the same string but for three renamed note types (`armorgear` →
  * `armor`, and its two siblings), and this map stayed on the document side
  * because that is the side the runtime cannot translate: `sohl/item-builders.mjs`
  * asks SoHL's own note-type → subtype map before it looks art up here, so the

package/sohl/document-subtypes.mjs

@@ -13,11 +13,11 @@
 
 /**
  * **SoHL's note-type → document-subtype map** — which Foundry document, and
- * which subtype of it, a note of each content type compiles into (#79).
+ * which subtype of it, a note of each content type compiles into.
  *
  * The mechanism is `engine/document-subtypes.mjs`; what a *game system* does
  * with it is here, which is the `engine/` ÷ `sohl/` line this package draws
- * everywhere else (#36). A second system declares its own map in its own half
+ * everywhere else. A second system declares its own map in its own half
  * and shares nothing but the mechanism.
  *
  * **Every row is written out, identity rows included.** `skill → skill` looks
@@ -31,7 +31,7 @@
  * **Three rows are no longer the identity, and that is what the map was for.**
  * `armor`, `concoction` and `projectile` were renamed from the `…gear`
  * spellings that named SoHL's *document* subtype rather than the thing the note
- * is about (#78); the subtypes themselves did not move, so those three rows now
+ * is about; the subtypes themselves did not move, so those three rows now
  * say two different words where they used to say one twice. Landing the rename
  * cost exactly what having the map first promised it would: a data change on
  * three lines here, and no mechanism change anywhere.
@@ -40,7 +40,7 @@
  * before this map is consulted — so a tree that has not swept its 30,741
  * embedded `(type, shortcode)` references compiles byte-identically. `weapon`
  * is deliberately **not** among them: both systems call that document a
- * `weapongear`, so the name says nothing SoHL-specific and #78 left it alone.
+ * `weapongear`, so the name says nothing SoHL-specific and is left alone.
  *
  * **What this map is not.** It says which document a note becomes, never what
  * that document contains: the `system` block comes from the item registry's
@@ -59,7 +59,7 @@ import { defineDocumentSubtypes } from "../engine/document-subtypes.mjs";
  *
  * The Item rows are the thirteen types the item registry declares; the one
  * Actor row is `being`, which was two types (`character` and `creature`)
- * compiling to the same actor until they were retired in SoHL#1580. Types this
+ * compiling to the same actor before they were retired. Types this
  * map does not name — `doc`, `macro`, the three map types — compile into
  * documents that carry no system subtype at all, so they have no row and never
  * needed one.

package/sohl/index.mjs

@@ -16,7 +16,7 @@
  * Lands data model that a generic content module must never receive.
  *
  * The item-type registry and its builders, the items and actors compilers, the
- * default-art map, and the affiliation standings live here (#1512). Nothing in
+ * default-art map, and the affiliation standings live here. Nothing in
  * `@heroiclands/package-build/engine` exports any of it, so an adventure module
  * that builds journals, macros, and scenes never receives `buildWeaponGear`.
  *
@@ -33,7 +33,7 @@
 /** The item-type registry: every type that compiles into an Item, and its builder. */
 export * as itemBuilders from "./item-builders.mjs";
 
-/** This system's note-type → document-subtype map, identity rows included (#79). */
+/** This system's note-type → document-subtype map, identity rows included. */
 export * as documentSubtypes from "./document-subtypes.mjs";
 
 /** The Item compiler. */
@@ -47,7 +47,7 @@ export * as kbPasses from "./kb-passes.mjs";
 
 // Flat as well as namespaced: the Foundry runtime imports these by name through
 // their own entry points, and they were this barrel's surface before the
-// compilers arrived (#1510).
+// compilers arrived.
 export { DEFAULT_ITEM_ART, defaultItemArt } from "./default-item-art.mjs";
 export { AFFILIATION_STANDINGS } from "./affiliation-standings.mjs";
 export { BEING_TYPE, GEAR_TYPE_TO_KEY, deriveBeingInfo, isBeing } from "./being-info.mjs";

package/sohl/item-builders.mjs

@@ -18,20 +18,20 @@
  * There is one list, not two. This repository hands {@link ITEM_BUILDERS} to
  * the build as `itemBuilders` in `package-build.config.yaml`, and `itemTypes()`
  * — the whitelist — is derived from that table's own keys, so a type cannot be
- * whitelisted for compilation without a builder to compile it. Previously the
+ * whitelisted for compilation without a builder to compile it. Split, the
  * whitelist and the builder table were maintained by hand and had already
- * drifted: `trait` — an item type **retired in #651**, absent from
+ * drifted: `trait` — a **retired** item type, absent from
  * `documentTypes.Item` and reported by world migration as unrecognized — was
  * still advertised as compilable, so a `type: trait` note passed the gate and
  * then died on `BUILDERS[type] is not a function`, swallowed as a per-file
- * error (#1504).
+ * error.
  *
  * **The builders are generated, not written.** Each type's `system` builder
  * comes from its field declaration in `item-fields.mjs` by way of
  * {@link buildFromFields}, so the vocabulary a note may write is readable data
  * rather than statements buried in a function body — which is what lets the
- * authoring reference be generated and a note be linted against its type
- * (#22). One consequence worth naming: the registry's keys are now
+ * authoring reference be generated and a note be linted against its type.
+ * One consequence worth naming: the registry's keys are now
  * {@link ITEM_FIELDS}'s keys, so adding an item type is one edit *there* (plus
  * its `documentTypes.Item` declaration and its default art), and removing one
  * is likewise a single deletion.
@@ -43,7 +43,7 @@
  * own evaluation. The table travels into configuration; the engine's
  * `item-registry.mjs` reads it back out and the Item compiler dispatches
  * through that, which is how a consumer's own table is the one its notes
- * compile with (#1563).
+ * compile with.
  */
 
 import { defaultItemArt } from "./default-item-art.mjs";
@@ -86,7 +86,7 @@ const FINALIZERS = Object.freeze({
  *
  * **The art map is keyed by the document subtype**, which the runtime reads
  * with a Foundry `Item`'s own `type`, so this asks SoHL's map what an `armor`
- * note becomes before looking art up (#78). Translating on the build side is
+ * note becomes before looking art up. Translating on the build side is
  * the only place it can happen: the runtime has no note in hand. Every SoHL
  * Item row is one-to-one, so `documentSubtype` needs no frontmatter and cannot
  * throw for a discriminator.