@heroiclands/package-build 22.17.1 → 22.17.2

package/engine/content-lint.mjs

@@ -22,7 +22,7 @@
  * disagree without anything detecting it, which the canonical-separator
  * handling already did once on each side.
  *
- * Five rules, all about a note's identity:
+ * Four rules, all about a note's identity:
  *
  * 1. **Shape** — a `shortcode` is strictly lowercase ASCII-alphanumeric. It is
  *    the identity key referenced from saved world data, and it is half of the
@@ -34,12 +34,7 @@
  *    reason the other two do: it is a statement about which note holds which
  *    address, it needs no `site:` configuration to decide, and a package with
  *    no front page is misconfigured whether or not anyone runs a site build.
- * 4. **Vacated addresses** — a `renamedFrom:` entry names an address this note
- *    once held and nothing holds now. It is the same statement as
- *    rule 2 read backwards, and it needs the same whole-tree view: an entry can
- *    only be checked against every *other* note's address, and two notes
- *    claiming one predecessor is the uniqueness rule applied to the past.
- * 5. **The vocabulary a package's kind leaves it** — a package compiling no
+ * 4. **The vocabulary a package's kind leaves it** — a package compiling no
  *    Foundry documents publishes `doc` and `homepage` notes and nothing else.
  *    It is here rather than with the claim check in `note-claims.mjs` because
  *    that check runs at compile, and this is the case where no compile runs.
@@ -72,7 +67,6 @@ import { assertStatedScope } from "./helpers.mjs";
 // The corpus, read from the one pass that derives it.
 import { authoredFrontmatter, indexRecordsFor, isNoteRecord, noteFile } from "./content-index.mjs";
 import { checkHomepageCount, isHomepage } from "./homepage.mjs";
-import { declaresRenamedFrom, renamedFrom, renamedFromEntries } from "./note-renames.mjs";
 
 /**
  * The shape every `shortcode` must match: lowercase ASCII letters and digits
@@ -175,110 +169,6 @@ function collectNotes(contentBase, { skipDirectories, config, records, problems
     return notes;
 }
 
-/**
- * What one note's `renamedFrom:` says, checked against itself.
- *
- * The entries a note can be wrong about on its own: a value that is not a
- * shortcode, one naming the address the note holds *now*, one written twice.
- * Every one of them is silent without a check — a malformed entry is skipped by
- * the diff, so the author who wrote it sees the rename they were trying to
- * announce reported as a withdrawal anyway, with nothing saying why.
- *
- * The cross-note questions are not here, because one note cannot answer them:
- * whether an entry names an address some *other* note still publishes, and
- * whether two notes claim one predecessor, both need the whole tree and are
- * asked in {@link lintContentTree} once it has one.
- *
- * @param {object} note - The note, as {@link collectNotes} yields it.
- * @param {() => string} raw - Reads the file, deferred so a clean note costs
- *   nothing.
- * @returns {Array<object>} The findings.
- */
-function checkRenamedFrom({ fm, file }, raw) {
-    if (!declaresRenamedFrom(fm)) return [];
-    const findings = [];
-    const at = (value) => positionInFrontmatter(raw(), "renamedFrom", value);
-    const shortcode = typeof fm.shortcode === "string" ? fm.shortcode.trim() : "";
-
-    // A rename is a statement about where this note's address moved *to*, so a
-    // note with no address of its own has made no such statement. Reported
-    // before the entries: telling the author their entries are fine would be
-    // the less useful half of the answer.
-    if (!shortcode) {
-        return [
-            {
-                file,
-                ...at(undefined),
-                severity: "error",
-                message:
-                    "`renamedFrom` names the address this note used to hold, " +
-                    "but the note declares no `shortcode`, so it holds none now " +
-                    "and nothing was renamed",
-            },
-        ];
-    }
-
-    const seen = new Set();
-    for (const entry of renamedFromEntries(fm)) {
-        // Not `String(entry)`: the point is that the author wrote something
-        // that is not a shortcode, and rendering a list as `a,b` would show
-        // them a string they never typed.
-        if (typeof entry !== "string" || !entry.trim()) {
-            findings.push({
-                file,
-                ...at(undefined),
-                severity: "error",
-                message:
-                    `\`renamedFrom\` takes shortcodes, and one entry is ` +
-                    `${entry === "" || (typeof entry === "string" && !entry.trim()) ? "blank" : `a ${typeof entry}`}; ` +
-                    `it is skipped, so the rename it was meant to announce is ` +
-                    `still reported as a withdrawal`,
-            });
-            continue;
-        }
-        const value = entry.trim();
-        if (!isValidShortcode(value)) {
-            findings.push({
-                file,
-                ...at(value),
-                severity: "error",
-                message:
-                    `\`renamedFrom: ${value}\` is not strictly alphanumeric — ` +
-                    `lowercase letters and digits only (${ADDRESS_SEGMENT_PATTERN.source}) — ` +
-                    `so it is not an address this package ever published — a ` +
-                    `shortcode is held to one charset whether it is current or past`,
-            });
-            continue;
-        }
-        if (value === shortcode) {
-            findings.push({
-                file,
-                ...at(value),
-                severity: "error",
-                message:
-                    `\`renamedFrom: ${value}\` is this note's own shortcode, so ` +
-                    `it declares a rename from itself; name the shortcode it ` +
-                    `was published under before, or drop the key`,
-            });
-            continue;
-        }
-        if (seen.has(value)) {
-            findings.push({
-                file,
-                ...at(value),
-                // The declaration still works — the reader de-duplicates — so
-                // this is tidiness, and failing a build over it would red a
-                // tree whose renames are all correctly announced.
-                severity: "warning",
-                message: `\`renamedFrom: ${value}\` is listed twice; the repeat says nothing new`,
-            });
-            continue;
-        }
-        seen.add(value);
-    }
-    return findings;
-}
-
 /**
  * Lint every address in a content tree.
  *
@@ -313,9 +203,6 @@ export function lintContentTree(
 
     /** @type {Map<string, Array<{file: string, absPath: string}>>} */
     const byKey = new Map();
-    /** @type {Map<string, Array<{file: string, absPath: string, shortcode: string}>>} */
-    const claimedPredecessors = new Map();
-
     for (const note of notes) {
         const { fm, absPath, file } = note;
         const shortcode = fm.shortcode;
@@ -324,7 +211,7 @@ export function lintContentTree(
         // tree costs one pass rather than two.
         const raw = () => fs.readFileSync(absPath, "utf8");
 
-        // Rule 5, and it is the whole of the check for a package that compiles
+        // Rule 4, and it is the whole of the check for a package that compiles
         // nothing: no pass downstream would report the note, because the pass
         // that reports an unclaimed type is a compile pass and none runs.
         const type = typeof fm.type === "string" ? fm.type.trim() : "";
@@ -341,25 +228,6 @@ export function lintContentTree(
             });
         }
 
-        // Before the keyless `continue` below, because a note declaring a
-        // rename while carrying no address of its own is exactly one of the
-        // things this reports — and reaching it after the skip would mean it
-        // never ran on the case that needs it most.
-        findings.push(...checkRenamedFrom(note, raw));
-        if (shortcode) {
-            // The de-duplicated reader, not the raw entries: a note that listed
-            // one predecessor twice has made one claim, and indexing it twice
-            // would make the note collide with itself and be reported as two
-            // notes claiming one address.
-            for (const value of renamedFrom(fm)) {
-                if (value === shortcode) continue;
-                const claim = `${fm.type}:${value}`;
-                const seen = claimedPredecessors.get(claim);
-                if (seen) seen.push({ file, absPath, shortcode });
-                else claimedPredecessors.set(claim, [{ file, absPath, shortcode }]);
-            }
-        }
-
         // Folder documents and keyless entries carry no address at all.
         if (!shortcode) continue;
 
@@ -436,52 +304,5 @@ export function lintContentTree(
         }
     }
 
-    // The two questions about a declared rename that need the whole tree.
-    // Both are the uniqueness rule above, applied to the past: an
-    // address has one holder, so it has one successor and it cannot be both
-    // vacated and occupied.
-    for (const [claim, claimants] of claimedPredecessors) {
-        const live = byKey.get(claim);
-        if (live) {
-            for (const { file, absPath } of claimants) {
-                findings.push({
-                    file,
-                    ...positionInFrontmatter(
-                        fs.readFileSync(absPath, "utf8"),
-                        "renamedFrom",
-                        claim.slice(claim.indexOf(":") + 1),
-                    ),
-                    severity: "error",
-                    message:
-                        `\`renamedFrom\` claims "${claim}", which ` +
-                        `${live.map((f) => f.file).join(", ")} still publishes; ` +
-                        `that address was never vacated, so nothing was renamed ` +
-                        `away from it`,
-                });
-            }
-        }
-        if (claimants.length < 2) continue;
-        // Named on every claimant rather than once on the address, for the same
-        // reason a duplicate address is: each is a file an author has to open,
-        // and a finding naming only the address sends them hunting for the rest.
-        for (const { file, absPath, shortcode } of claimants) {
-            const others = claimants.filter((c) => c.file !== file);
-            findings.push({
-                file,
-                ...positionInFrontmatter(
-                    fs.readFileSync(absPath, "utf8"),
-                    "renamedFrom",
-                    claim.slice(claim.indexOf(":") + 1),
-                ),
-                severity: "error",
-                message:
-                    `"${claim}" is claimed as a predecessor by more than one ` +
-                    `note — this one (now "${shortcode}") and ` +
-                    `${others.map((c) => `${c.file} (now "${c.shortcode}")`).join(", ")}; ` +
-                    `an address had one holder, so it has one successor`,
-            });
-        }
-    }
-
     return { findings, notes: notes.length, keys: byKey.size };
 }

package/engine/frontmatter-lint.mjs

@@ -57,6 +57,7 @@
 import { isAddressTuple } from "./address.mjs";
 import { authoredNoteKeys, NOTE_TOP_LEVEL_KEY_SET } from "./note-frontmatter.mjs";
 import { AddressEntries } from "./address-values.mjs";
+import { addressPositions } from "./note-addresses.mjs";
 import { authoredFields, readsLegacyKey } from "./field-spec.mjs";
 import {
     legacyKeyOf,
@@ -79,7 +80,6 @@ import { DEFAULT_PARENT } from "./folder-notes.mjs";
 import {
     dataFields,
     declaredTags,
-    exclusiveTagGroups,
     subTypeCharsetMessage,
     typeCharsetMessage,
 } from "./note-vocabulary.mjs";
@@ -597,6 +597,115 @@ function checkDataReferences(note, field, value, segments, context, index) {
     return findings;
 }
 
+/**
+ * Read values at a schema-declared address path, expanding wildcard segments.
+ * @param {unknown} value - The value at the current path.
+ * @param {readonly string[]} path - Remaining declaration path.
+ * @param {readonly (string|number)[]} [actual] - Authored path so far.
+ * @returns {Array<{value: unknown, path: Array<string|number>}>} Values and their paths.
+ */
+function valuesAtAddressPath(value, path, actual = []) {
+    if (!path.length) return [{ value, path: [...actual] }];
+    const [head, ...tail] = path;
+    if (head === "*") {
+        const entries =
+            Array.isArray(value) ? value.map((entry, index) => [index, entry])
+            : value && typeof value === "object" && !isAddressTuple(value) ? Object.entries(value)
+            : [];
+        return entries.flatMap(([key, entry]) =>
+            valuesAtAddressPath(entry, tail, [...actual, key]),
+        );
+    }
+    if (!value || typeof value !== "object" || isAddressTuple(value)) return [];
+    return valuesAtAddressPath(value[head], tail, [...actual, head]);
+}
+
+/**
+ * Resolve system-block addresses declared by the system's own field schema.
+ * @param {object} note - A note from the link index.
+ * @param {object} opts
+ * @param {object} opts.index - The address index.
+ * @param {Record<string, readonly object[]>} [opts.schemas] - Note schemas.
+ * @param {Readonly<Record<string, object>>} [opts.systems] - Declared system blocks.
+ * @returns {object[]} Located findings for unresolved addresses.
+ */
+export function systemAddressFindings(note, { index, schemas, systems } = {}) {
+    if (!index?.addressHit) return [];
+    const findings = [];
+    const fm = note.fm ?? {};
+    for (const position of addressPositions(fm, { schemas, systemBlocks: systems })) {
+        const block = position.path[0];
+        if (!Object.hasOwn(systems ?? {}, block) || position.path[1] === "packFolder") continue;
+        const candidates = valuesAtAddressPath(fm, position.path);
+        for (const candidate of candidates) {
+            let values;
+            if (position.shape === "list") {
+                values =
+                    Array.isArray(candidate.value) ?
+                        candidate.value.map((value, index) => ({
+                            value,
+                            path: [...candidate.path, index],
+                        }))
+                    :   [];
+            } else if (position.shape === "keys") {
+                values =
+                    candidate.value instanceof AddressEntries ?
+                        candidate.value.entries.map((entry) => ({
+                            value: entry.target,
+                            path: [...candidate.path, entry.sourceKey],
+                            key: true,
+                        }))
+                    : candidate.value && typeof candidate.value === "object" ?
+                        Object.keys(candidate.value).map((key) => ({
+                            value: key,
+                            path: [...candidate.path, key],
+                            key: true,
+                        }))
+                    :   [];
+            } else if (position.shape === "scalar-or-map" && mapEntries(candidate.value)) {
+                values = Object.entries(mapEntries(candidate.value)).map(([key, value]) => ({
+                    value,
+                    path: [...candidate.path, key],
+                }));
+            } else {
+                values = [candidate];
+            }
+
+            for (const item of values) {
+                if (item.value == null || item.value === "") continue;
+                const context = {
+                    package: index.contentPackage,
+                    system: position.system ?? block,
+                    type: position.type,
+                    types: index.types,
+                };
+                const address =
+                    isAddressTuple(item.value) ? item.value
+                    : typeof item.value === "string" ?
+                        parseAddress(item.value, context, {
+                            declared: true,
+                            legacyShortcodeCase: position.legacyShortcodeCase,
+                        })
+                    :   null;
+                if (!address || address.reason) continue;
+                if (position.accepts && !acceptsType(address, position.accepts)) continue;
+                const target = renderAddress(address);
+                if (index.addressHit(target)) continue;
+                const path = item.path;
+                findings.push({
+                    file: note.file,
+                    ...positionOfFrontmatterPath(note.raw ?? "", path, { key: item.key }),
+                    severity: "error",
+                    message:
+                        `\`${path.map(String).join(".")}\` names ${target}, which does not ` +
+                        `resolve in this package or its declared dependencies`,
+                });
+            }
+        }
+    }
+    return findings;
+}
+
 /**
  * Check one `scalar-or-map` field written in its map form, entry by entry.
  *
@@ -774,14 +883,6 @@ function checkSubType(note, { type, entry }) {
  * findings above become none while a settlement tagged `vilage` is still
  * caught.
  *
- * **A group declared as a slot is checked twice over.** Its tags are the
- * alternative answers to one question — a being is a `character` or a
- * `creature` — so two of them on one note is refused outright, by
- * {@link checkExclusiveTags}, on top of the near miss every group gets. An
- * *unfilled* slot is not a finding: the kind is authored deliberately, and
- * nothing can tell a being nobody has classified yet from one the author means
- * to leave unclassified.
- *
  * @param {object} note - The note.
  * @param {object} opts
  * @param {string} opts.type - The note's declared `type`, which scopes the
@@ -816,55 +917,6 @@ function checkTags(note, { type }) {
     return findings;
 }
 
-/**
- * Refuse a note that fills one single-valued tag slot twice.
- *
- * This is the whole of what "a closed tag vocabulary" can mean while `tags:`
- * stays open. A slot's values are alternatives, not attributes: a being is a
- * `character` or a `creature`, so a note carrying both has answered the
- * question twice and every reader of the tag — an index, a query, a renderer —
- * gets to pick. That is the same silent wrongness a misspelt classifying tag
- * is, and it gets the same answer.
- *
- * **An error, not a warning**, because a warning does not change the build's
- * exit code and a contradiction that still ships is a contradiction nobody
- * fixes.
- *
- * **Located on the `tags` key**, because the fault is the list rather than
- * either entry in it — both values are correctly spelt, and pointing at one of
- * them would say the wrong one is the wrong one.
- *
- * @param {object} note - The note.
- * @param {object} opts
- * @param {string} opts.type - The note's declared `type`, which scopes the
- *   slots checked.
- * @returns {object[]} Findings.
- */
-function checkExclusiveTags(note, { type }) {
-    const authored = (note.fm ?? {}).tags;
-    if (!Array.isArray(authored)) return [];
-
-    const carried = new Set(
-        authored.filter((t) => typeof t === "string" && t.trim()).map((t) => t.trim()),
-    );
-    const findings = [];
-    for (const { slot, tags } of exclusiveTagGroups(type)) {
-        const filled = tags.filter((t) => carried.has(t));
-        if (filled.length < 2) continue;
-        findings.push({
-            file: note.file,
-            ...positionInFrontmatter(note.raw ?? "", "tags"),
-            severity: "error",
-            message:
-                `a ${type}'s ${slot} is one tag, and this note carries ` +
-                `${filled.map((t) => `"${t}"`).join(" and ")}. Those are the alternative ` +
-                `answers to one question (${tags.join(", ")}), so carrying two of them ` +
-                `states no ${slot} at all. Keep the one that is true, or neither`,
-        });
-    }
-    return findings;
-}
-
 /**
  * The frontmatter fields that name artwork.
  *
@@ -1421,7 +1473,6 @@ export function lintNote(
     // type's property — `draft` belongs to any note and `village` to a place —
     // so the finding must survive the early returns below.
     findings.push(...checkTags(note, { type }));
-    findings.push(...checkExclusiveTags(note, { type }));
 
     // A refused field must be one the note *wrote*: `resolveNoteId` fills
     // `fm.id` in place, so the parsed frontmatter carries a derived id the
@@ -1753,6 +1804,8 @@ export function lintNote(
         }
     }
 
+    findings.push(...systemAddressFindings(note, { index, schemas, systems }));
+
     return findings;
 }
 

package/engine/helpers.mjs

@@ -177,7 +177,8 @@ export function renderFoundryMarkdown(body, captions, footnoteNumbers, docId) {
  * @param {string} filePath - Markdown file to read.
  * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
  * @returns {{frontmatter: object|null, body: string, description: string,
- *   bodyLine?: number, bodyColumn?: number}} Parsed note and body position.
+ *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
+ *   line?: number, column?: number}}} Parsed note and body position.
  */
 export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const content = fs.readFileSync(filePath, "utf8");
@@ -189,8 +190,19 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     try {
         frontmatter = yaml.parse(fmMatch[1]) || {};
     } catch (err) {
-        log.warn(`YAML parse error in ${filePath}: ${err.message}`);
-        return { frontmatter: null, body: "", description: "" };
+        const firstLine = String(err.message).split("\n", 1)[0];
+        const message = firstLine.replace(/ at line \d+, column \d+.*$/, "");
+        const location = err.linePos?.[0];
+        return {
+            frontmatter: null,
+            body: "",
+            description: "",
+            parseError: {
+                message: `YAML parse error: ${message}`,
+                ...(Number.isInteger(location?.line) ? { line: location.line + 1 } : {}),
+                ...(Number.isInteger(location?.col) ? { column: location.col } : {}),
+            },
+        };
     }
     if (addressContext) {
         try {

package/engine/index.mjs

@@ -178,9 +178,6 @@ export * as infoboxRender from "./infobox-render.mjs";
 /** The id a note's document is filed under: its pin, or its address. */
 export * as noteIds from "./note-ids.mjs";
 
-/** The shortcodes a note declares it used to be published under. */
-export * as noteRenames from "./note-renames.mjs";
-
 /** The published content index packages exchange addresses through. */
 export * as metadataIndex from "./metadata-index.mjs";
 

package/engine/map-graphviz.mjs

@@ -55,7 +55,10 @@ export function renderDot(dotPath, outPath, { engine, format = "svg", nop, dpi =
                 .filter(
                     (error) =>
                         error.level === "warning" &&
-                        !error.message.includes("no hard-coded metrics for 'Helvetica-Bold'"),
+                        !error.message.includes("no hard-coded metrics for 'Helvetica-Bold'") &&
+                        !/^Warning: no value for width of non-ASCII character \d+\. Falling back to width of space character$/.test(
+                            error.message,
+                        ),
                 )
                 .map((error) => error.message)
                 .join("; "),

package/engine/note-frontmatter.mjs

@@ -18,6 +18,7 @@ export const NOTE_TOP_LEVEL_KEYS = Object.freeze([
     "data",
     "hm3",
     "sohl",
+    "dnd5e",
 ]);
 
 /** Membership test for the top-level vocabulary. */

package/engine/note-vocabulary.mjs

@@ -571,15 +571,6 @@ export const DECLARED_TAGS = Object.freeze({
             "unguilded",
         ]),
     }),
-    /**
-     * What kind of being this is — a person, or one of the beasts and made
-     * things. A being is one or the other, so the group is a slot.
-     */
-    beingKind: Object.freeze({
-        types: ["being"],
-        exclusive: "kind",
-        tags: Object.freeze(["character", "creature"]),
-    }),
     /** A note's working state, which any note may carry. */
     state: Object.freeze({ types: null, tags: Object.freeze([DRAFT_TAG]) }),
     /** Who may read a completed note. */
@@ -692,10 +683,7 @@ export const NOTE_VOCABULARY = Object.freeze({
 
     being: Object.freeze({
         stubbable: true,
-        // Derived from the note's `(type, subType)` by each system's map, which
-        // lands with. Declared open until it does, because inventing the
-        // values here would put a second, weaker answer beside the real one.
-        subTypes: null,
+        subTypes: Object.freeze(["npc", "character", "creature"]),
         // Whether an authored `age` disagrees with what `born` and the
         // package's declared present compute — see `engine/being-age.mjs`.
         check: checkBeingAge,

package/engine/subtype-registry.mjs

@@ -43,10 +43,6 @@ import { HM3_DOCUMENT_SUBTYPES } from "../hm3/document-subtypes.mjs";
 /**
  * The note-type → document-subtype maps this toolchain ships.
  *
- * Two, since `hm3/` landed — and it joined this list rather than the
- * claim table growing a second copy of the same fact, which is what the list
- * was for.
- *
  * The union is what makes the vocabulary wider than any one repository's
  * configuration: `armorlocation` is a real content type because HM3 maps it,
  * however a given repository is configured, so a tree full of them is a
@@ -90,7 +86,7 @@ export const KNOWN_DOCUMENT_SUBTYPE_MAPS = Object.freeze([
 export const DEFAULT_DOCUMENT_SUBTYPES = SOHL_DOCUMENT_SUBTYPES;
 
 /**
- * Every system this toolchain ships a map for, by id.
+ * Every system identifier with declared system-specific document types.
  *
  * Derived from {@link KNOWN_DOCUMENT_SUBTYPE_MAPS}, so registering a map is the
  * whole of adding a system to every reader that asks "which systems are there?"
@@ -156,7 +152,7 @@ export const ACTOR_TYPES = Object.freeze(
 /**
  * The map one system ships, by its id.
  *
- * @param {string|undefined} system - The system id (`"sohl"`, `"hm3"`).
+ * @param {string|undefined} system - The system id.
  * @returns {import("./document-subtypes.mjs").DocumentSubtypeMap|undefined} Its
  *   map, or `undefined` where this toolchain ships none for it.
  */

package/engine/systems.mjs

@@ -20,10 +20,8 @@
  * address grammar asks on every note, and the issue's answer is that it comes
  * from a **registry rather than from a hardcoded set**: known system ids are
  * declared here, once, an unknown value is an error, and _adding a system is a
- * data change_. Before this module the same fact was spelled in as many places
- * as needed it — a `NO_SYSTEM` constant in the content index, a `map.system`
- * per document-subtype map, a system-keyed table per compiler — none of which
- * could refuse a value none of the others had heard of.
+ * data change_. The same fact is read by address parsing, configuration and
+ * linting.
  *
  * **`none` is a word, deliberately.** It is not a YAML null (`null`, `~`, or an
  * empty value), because those spell "nobody filled this in", and a note that
@@ -38,8 +36,8 @@
  * the configuration loader, by a compiler, and by a lint without closing a
  * cycle around any of them. In particular the ids are *declared* here rather
  * than derived from `KNOWN_DOCUMENT_SUBTYPE_MAPS` — deriving them would drag
- * `sohl/` and `hm3/` behind every import of this file, for a list of two
- * words. `tests/systems.test.ts` holds the two in step instead, which is where
+ * system-specific modules behind every import of this file. `tests/systems.test.ts`
+ * holds the registry and note-key vocabulary in step, which is where
  * the agreement between a registry and its implementations belongs.
  *
  * @module
@@ -66,11 +64,11 @@ export const NO_SYSTEM = "none";
 export const NOTE_SYSTEM = "note";
 
 /**
- * Every game system this toolchain compiles for.
+ * Every game system identifier this toolchain recognizes.
  *
- * The registry, and the only place the list is written down. Adding a system
- * is an edit to this set plus the map and compilers that make it real — a data
- * change, not a search for every place a name was spelled.
+ * The registry, and the only place the list is written down. A recognized id
+ * can have no system-specific document types; adding one of those requires a
+ * subtype map and compiler as well.
  *
  * `none` is **not** a member: it marks the absence of a system, and a caller
  * asking "is this a system" and a caller asking "is this a well-formed
@@ -79,7 +77,7 @@ export const NOTE_SYSTEM = "note";
  *
  * @type {ReadonlySet<string>}
  */
-export const SYSTEM_IDS = Object.freeze(new Set(["sohl", "hm3"]));
+export const SYSTEM_IDS = Object.freeze(new Set(["sohl", "hm3", "dnd5e"]));
 
 /**
  * Everything the `<system>` segment of an address may say.
@@ -127,8 +125,8 @@ export function isSystemSegment(value) {
  *
  * The nullish case is called out by name because it is the likely mistake and
  * the least legible failure: a YAML `null`, a `~`, or a key written with no
- * value at all reaches here as `undefined`, and "expected one of sohl, hm3,
- * none" would leave a reader hunting for the value they cannot see.
+ * value at all reaches here as `undefined`, and a list of accepted values
+ * would leave a reader hunting for the value they cannot see.
  *
  * @param {unknown} value - The offending value.
  * @param {string} [where] - What carried it, for the message — a note path, a

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.17.1",
+    "version": "22.17.2",
     "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",

package/types/engine/actor-compiler.d.mts

@@ -230,11 +230,11 @@ export class SystemActorCompiler extends BasePackCompiler {
      * The actor's two pieces of art, resolved, with the being default beneath
      * them.
      *
-     * **The default is chosen from the note's tags**, which only a compiler can
-     * read: a `character` falls back to one file and a `creature` to another,
-     * and both are addresses in the package that ships them. A tree whose index
-     * cannot answer that address — a dependency not yet fetched — falls through
-     * to the subtype's own default, so the document is never left with no art.
+     * **The default follows the note's `subType`**, with tags as a compatibility
+     * fallback for content trees that have not migrated. Both addresses belong
+     * to the package that ships them. A tree whose index cannot answer an
+     * address — a dependency not yet fetched — falls through to the document
+     * subtype's own default, so the document is never left with no art.
      *
      * `tokenIcon` unset follows `icon`, and the fallback is applied after
      * resolution rather than before: a note naming an icon and no token icon