@heroiclands/package-build 8.1.0 → 10.0.0

package/engine/journals.mjs

@@ -45,13 +45,7 @@
 
 import log from "loglevel";
 
-import {
-    sohlField,
-    makeId,
-    resolveName,
-    defaultStats,
-    md,
-} from "./helpers.mjs";
+import { sohlField, makeId, resolveName, defaultStats, md } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { anchorPageId } from "./wikilinks.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
@@ -98,12 +92,10 @@ export function splitPages(body, leadName = "Introduction") {
         // An H1 starts a page, as does any heading carrying an `{#slug}`
         // anchor: a Foundry UUID can only address a page, so a linkable
         // section has to be one.
-        const headingMatch =
-            !inCodeBlock ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
+        const headingMatch = !inCodeBlock ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
         const rawHeading = headingMatch?.[2]?.trim();
         const anchorMatch = rawHeading?.match(/^(.*?)\s*\{#([^}]+)\}\s*$/);
-        const startsPage =
-            headingMatch && (headingMatch[1].length === 1 || anchorMatch);
+        const startsPage = headingMatch && (headingMatch[1].length === 1 || anchorMatch);
         if (startsPage) {
             closeCurrent();
             current = {
@@ -371,8 +363,6 @@ export class Journals extends BasePackCompiler {
 
     /** @inheritdoc */
     reportDetail(stats) {
-        log.debug(
-            `Skipped ${stats.skippedOther} non-doc file(s) (not type:doc)`,
-        );
+        log.debug(`Skipped ${stats.skippedOther} non-doc file(s) (not type:doc)`);
     }
 }

package/engine/kb-manifest.mjs

@@ -90,18 +90,47 @@ export function canonicalKey(pkg, type, shortcode) {
 }
 
 /**
- * Reads a canonical key back into its parts.
+ * How many segments a canonical key has, and therefore how many the reader
+ * below counts.
  *
- * Unambiguous because no package, type or shortcode contains a hyphen — types
- * are bare words and shortcodes are `^[A-Za-z0-9]+$` (#1397).
+ * Named rather than written as a literal because it is the *grammar*, not an
+ * implementation detail of one function: it is the number a change to the
+ * address form would move, and the thing a reader of that change has to find.
  *
- * @param {string} key - A canonical key.
- * @returns {{package: string, type: string, shortcode: string}|null} The parts,
- *   or `null` when the key is not in canonical form.
+ * @type {number}
+ */
+export const CANONICAL_KEY_SEGMENTS = 3;
+
+/**
+ * Reads a canonical key back into its parts.
+ *
+ * Parsing is plain positional counting: split on the separator, require
+ * {@link CANONICAL_KEY_SEGMENTS} of them, and assign each position its field.
+ * **The charset rule is what makes that sound** — every segment is
+ * `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN` in `engine/address-charset.mjs`),
+ * so the hyphen is purely a separator and the count alone determines every
+ * field. That is enforced at each of the three sources rather than assumed of
+ * the data: shortcodes by `content-lint.mjs` (#1397), `contentPackage` by
+ * `defineConfig` (#59), and types are bare words. Were any of them free to
+ * carry a hyphen, no amount of counting would recover the fields and the reader
+ * would need a vocabulary to match against instead.
+ *
+ * **Nothing to read and nothing readable are different answers.** A key that
+ * cannot be canonical — `harn-adventures-skill-melee`, four segments — yields
+ * `null`, while an absent or blank input yields `undefined`. Both are falsy, so
+ * every call site (all of which test the result for truthiness) is unaffected;
+ * the distinction is there so a caller reporting "this key is unreadable" can
+ * tell that it has a key to report about.
+ *
+ * @param {unknown} key - A canonical key, or nothing.
+ * @returns {{package: string, type: string, shortcode: string}|null|undefined}
+ *   The parts; `null` when there is a string that is not in canonical form;
+ *   `undefined` when there is no key at all.
  */
 export function readCanonicalKey(key) {
+    if (key == null || key === "") return undefined;
     const parts = String(key).split("-");
-    if (parts.length !== 3) return null;
+    if (parts.length !== CANONICAL_KEY_SEGMENTS) return null;
     const [pkg, type, shortcode] = parts;
     if (!pkg || !type || !shortcode) return null;
     return { package: pkg, type, shortcode };
@@ -180,9 +209,7 @@ export const PACKAGE_BASE = Object.freeze({
  */
 function checkBase(base, what) {
     if (typeof base !== "string" || !base.endsWith("/")) {
-        throw new Error(
-            `${what}: package base ${JSON.stringify(base)} must end in a slash`,
-        );
+        throw new Error(`${what}: package base ${JSON.stringify(base)} must end in a slash`);
     }
     return base;
 }
@@ -226,8 +253,7 @@ export function resolvePackageUrl(rel, base) {
     checkBase(base, "resolvePackageUrl");
     if (typeof rel !== "string" || !rel || rel.startsWith("/")) {
         throw new Error(
-            `resolvePackageUrl: ${JSON.stringify(rel)} is not a package-` +
-                `relative address`,
+            `resolvePackageUrl: ${JSON.stringify(rel)} is not a package-` + `relative address`,
         );
     }
     return `${base}${rel}`;
@@ -289,8 +315,7 @@ export function buildManifest(pkg, entries, base, foundryPackage) {
         // address, so there is no fact being restated, and an anchor is not
         // required to live inside its own entry. Publishing the complete link
         // also keeps the page-id hash out of the published contract entirely.
-        if (e.anchors && Object.keys(e.anchors).length)
-            entry.anchors = e.anchors;
+        if (e.anchors && Object.keys(e.anchors).length) entry.anchors = e.anchors;
         out[e.key ?? canonicalKey(pkg, type, shortcode)] = entry;
     }
     return {
@@ -327,12 +352,7 @@ export function writeManifests(entriesByPackage, dir, bases, foundryPackages) {
     fs.mkdirSync(dir, { recursive: true });
     const written = [];
     for (const [pkg, entries] of entriesByPackage) {
-        const doc = buildManifest(
-            pkg,
-            entries,
-            bases?.[pkg],
-            foundryPackages?.[pkg],
-        );
+        const doc = buildManifest(pkg, entries, bases?.[pkg], foundryPackages?.[pkg]);
         const file = path.join(dir, `${pkg}.json`);
         fs.writeFileSync(file, `${JSON.stringify(doc, null, 2)}\n`);
         written.push({
@@ -430,10 +450,7 @@ export function loadForeignManifests(dir, localPackages, bases = PACKAGE_BASE) {
                         // Absent for an entry with no page. A consumer must
                         // tolerate that rather than invent an href, exactly as
                         // it already tolerates an entry with no `uuid`.
-                        url:
-                            v.path == null ?
-                                undefined
-                            :   resolvePackageUrl(v.path, base),
+                        url: v.path == null ? undefined : resolvePackageUrl(v.path, base),
                         uuid: v.uuid,
                         doc: v.doc,
                         anchors: v.anchors,

package/engine/macros.mjs

@@ -51,12 +51,7 @@
 
 import log from "loglevel";
 
-import {
-    sohlField,
-    resolveName,
-    resolveImg,
-    defaultStats,
-} from "./helpers.mjs";
+import { sohlField, resolveName, resolveImg, defaultStats } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { splitPages } from "./journals.mjs";
 
@@ -256,10 +251,7 @@ export function resolveMacroScope(fm, label) {
  * @returns {MacroDocument} The Macro document.
  * @throws {Error} When the frontmatter's macro type or scope is unusable.
  */
-export function buildMacroEntry(
-    fm,
-    { command, folder = null, stats = defaultStats() },
-) {
+export function buildMacroEntry(fm, { command, folder = null, stats = defaultStats() }) {
     const name = resolveName(fm);
     const id = fm.id;
     return {

package/engine/manifest-emit.mjs

@@ -142,11 +142,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
         :   undefined;
 
     if (hasDocEntry(fm.type)) {
-        const docKey = canonicalKey(
-            contentPackage,
-            `doc${fm.type}`,
-            fm.shortcode,
-        );
+        const docKey = canonicalKey(contentPackage, `doc${fm.type}`, fm.shortcode);
         const docEntryId = fm.id ? itemDocEntryId(fm.id) : undefined;
         const docUuid = uuidFor("doc", docEntryId);
         return [
@@ -166,10 +162,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
                 // documentation, so both addresses resolve to the same URL.
                 url,
                 uuid: docUuid,
-                anchors:
-                    docUuid ?
-                        anchorsOf(docUuid, docEntryId, body ?? "", name)
-                    :   undefined,
+                anchors: docUuid ? anchorsOf(docUuid, docEntryId, body ?? "", name) : undefined,
             },
         ];
     }
@@ -184,10 +177,7 @@ export function entriesForNote(fm, name, address, body, ctx) {
             name,
             url,
             uuid: own,
-            anchors:
-                own && fm.type === "doc" ?
-                    anchorsOf(own, fm.id, body ?? "", name)
-                :   undefined,
+            anchors: own && fm.type === "doc" ? anchorsOf(own, fm.id, body ?? "", name) : undefined,
         },
     ];
 }
@@ -221,10 +211,9 @@ export function collectManifestEntries(contentBase, ctx) {
     // note yields two entries, so reporting one as the other overstates how
     // much of the tree is published.
     let notes = 0;
-    for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(
-        contentBase,
-        { skipDirectories: ctx.skipDirectories },
-    )) {
+    for (const { frontmatter: fm, body, absPath } of walkMarkdownTree(contentBase, {
+        skipDirectories: ctx.skipDirectories,
+    })) {
         if (!fm) continue;
         const rel = path.relative(contentBase, absPath);
         assertNoDeclaredPackage(fm, {

package/engine/map-notes.mjs

@@ -51,14 +51,14 @@
 
 import crypto from "crypto";
 
-import { compendiumUuid, makeId, MAP_TYPES } from "./ids.mjs";
+import { compendiumUuid, makeId, MAP_SUBTYPES, MAP_TYPES } from "./ids.mjs";
 // The curated region-event vocabulary is shared verbatim with the runtime
 // bridge (`SohlRegionTriggerBehavior`), so an event this build accepts is
 // exactly one the bridge forwards.
-import {
-    CURATED_REGION_EVENTS,
-    EXCLUDED_REGION_EVENTS,
-} from "./region-events.mjs";
+import { CURATED_REGION_EVENTS, EXCLUDED_REGION_EVENTS } from "./region-events.mjs";
+// A map's background art is `img`, as every other note type's art is; `image`
+// is the retired spelling, still read through the retirement window (#142).
+import { readAliasedField } from "./retired-fields.mjs";
 
 /* -------------------------------------------------------------------- */
 /*  Note types and their canvas profiles                                */
@@ -66,7 +66,7 @@ import {
 
 // The set itself lives in `ids.mjs`, a leaf both this module and the
 // doc-carrying type set in `item-docs.mjs` can depend on without a cycle.
-export { MAP_TYPES };
+export { MAP_SUBTYPES, MAP_TYPES };
 
 /**
  * Whether a content note's type compiles into a Scene.
@@ -79,7 +79,7 @@ export function isMapType(type) {
 }
 
 /**
- * Per-type canvas defaults, emitted **explicitly** on every scene.
+ * Per-subtype canvas defaults, emitted **explicitly** on every scene.
  *
  * This is not a convenience. `grid.type`, `grid.distance` and `grid.units` all
  * declare `initial: () => game.system.grid.*`, and there is no `game` at build
@@ -89,7 +89,7 @@ export function isMapType(type) {
  *
  * @type {Readonly<Record<string, object>>}
  */
-export const MAP_TYPE_PROFILES = Object.freeze({
+export const MAP_SUBTYPE_PROFILES = Object.freeze({
     battlemap: Object.freeze({
         grid: { type: 1 /* SQUARE */, distance: 5, units: "ft" },
         tokenVision: true,
@@ -111,18 +111,23 @@ export const MAP_TYPE_PROFILES = Object.freeze({
 });
 
 /**
- * The canvas profile for a map type.
+ * The canvas profile for a map subType.
  *
- * @param {string} type - The note's `type`.
- * @returns {object} The profile from {@link MAP_TYPE_PROFILES}.
- * @throws {Error} When the type is not a map type — the build's fail-fast
- *   contract, so a typo never ships a scene with Foundry's own defaults.
+ * Keyed on the subType rather than the type since #174: every map note is
+ * `type: map`, and which canvas it derives is the one thing the three
+ * spellings ever decided.
+ *
+ * @param {string} subType - The note's `subType`.
+ * @returns {object} The profile from {@link MAP_SUBTYPE_PROFILES}.
+ * @throws {Error} When the subType is not a map subType — the build's
+ *   fail-fast contract, so a typo never ships a scene with Foundry's own
+ *   defaults.
  */
-export function mapProfile(type) {
-    const profile = MAP_TYPE_PROFILES[String(type)];
+export function mapProfile(subType) {
+    const profile = MAP_SUBTYPE_PROFILES[String(subType)];
     if (!profile) {
         throw new Error(
-            `unknown map type "${type}" — expected one of ${[...MAP_TYPES].join(", ")}`,
+            `unknown map subtype "${subType}" — expected one of ${MAP_SUBTYPES.join(", ")}`,
         );
     }
     return profile;
@@ -266,10 +271,7 @@ export function assertPixelGeometry(coords, geom) {
  * @throws {Error} When the coordinates read as pixels.
  */
 export function assertGridLocation(at, geom) {
-    const [gx, gy] = [
-        geom.dimensions[0] / geom.pxPerGrid,
-        geom.dimensions[1] / geom.pxPerGrid,
-    ];
+    const [gx, gy] = [geom.dimensions[0] / geom.pxPerGrid, geom.dimensions[1] / geom.pxPerGrid];
     if (at[0] > gx || at[1] > gy) {
         throw new Error(
             `${geom.label}: [${at.join(", ")}] lies outside the map's ` +
@@ -408,9 +410,7 @@ function buildWall(segment, spec, geom, { sceneId, id }) {
  * The shape forms a map note may author. `rect` is the short spelling of
  * `rectangle`, as the design's own examples use.
  */
-const SHAPE_FORMS = Object.freeze(
-    new Set(["rect", "rectangle", "circle", "ellipse", "polygon"]),
-);
+const SHAPE_FORMS = Object.freeze(new Set(["rect", "rectangle", "circle", "ellipse", "polygon"]));
 
 /**
  * Compile one authored shape into a Foundry shape record.
@@ -448,20 +448,14 @@ export function buildShape(spec, geom) {
     }
     const raw = spec[form];
     if (!Array.isArray(raw) || raw.some((n) => !Number.isFinite(n))) {
-        throw new Error(
-            `${geom.label}: ${form} takes a flat list of numbers in pixels`,
-        );
+        throw new Error(`${geom.label}: ${form} takes a flat list of numbers in pixels`);
     }
     assertPixelGeometry(raw, geom);
 
     switch (form) {
         case "rect":
         case "rectangle":
-            expectLength(
-                raw,
-                4,
-                `${geom.label}: rectangle is [x, y, width, height]`,
-            );
+            expectLength(raw, 4, `${geom.label}: rectangle is [x, y, width, height]`);
             return {
                 type: "rectangle",
                 x: raw[0],
@@ -506,8 +500,7 @@ export function buildShape(spec, geom) {
             // which is a line segment and encloses nothing.
             if (raw.length < 6) {
                 throw new Error(
-                    `${geom.label}: a polygon needs at least 3 points; got ` +
-                        `${raw.length / 2}`,
+                    `${geom.label}: a polygon needs at least 3 points; got ` + `${raw.length / 2}`,
                 );
             }
             return { type: "polygon", points: [...raw], hole };
@@ -601,9 +594,7 @@ const BEHAVIOR_SPECS = Object.freeze({
  *
  * @type {ReadonlySet<string>}
  */
-export const REGION_BEHAVIOR_TYPES = Object.freeze(
-    new Set(Object.keys(BEHAVIOR_SPECS)),
-);
+export const REGION_BEHAVIOR_TYPES = Object.freeze(new Set(Object.keys(BEHAVIOR_SPECS)));
 
 /**
  * Behaviour types a map note may **never** carry, and why.
@@ -657,8 +648,7 @@ function buildBehavior(key, spec, ctx) {
     const [type] = types;
 
     const banned = BANNED_REGION_BEHAVIOR_TYPES.get(type);
-    if (banned)
-        throw new Error(`${label}: "${type}" is not permitted — ${banned}`);
+    if (banned) throw new Error(`${label}: "${type}" is not permitted — ${banned}`);
     const behaviorSpec = BEHAVIOR_SPECS[type];
     if (!behaviorSpec) {
         throw new Error(
@@ -680,13 +670,7 @@ function buildBehavior(key, spec, ctx) {
         }
     }
 
-    const system = compileBehaviorSystem(
-        type,
-        authored,
-        behaviorSpec,
-        label,
-        ctx,
-    );
+    const system = compileBehaviorSystem(type, authored, behaviorSpec, label, ctx);
     const id = behaviorDocId(ctx.regionId, key, spec._id);
     const doc = {
         _id: id,
@@ -730,23 +714,17 @@ function compileBehaviorSystem(type, authored, behaviorSpec, label, ctx) {
             const { to, ...rest } = authored;
             return {
                 ...rest,
-                destinations: toList(to).map((addr) =>
-                    ctx.resolveRegionRef(addr, label),
-                ),
+                destinations: toList(to).map((addr) => ctx.resolveRegionRef(addr, label)),
             };
         }
         case "toggleBehavior": {
             const { enable, disable, ...rest } = authored;
             const out = { ...rest, events: [...authored.events] };
             if (enable) {
-                out.enable = toList(enable).map((a) =>
-                    ctx.resolveBehaviorRef(a, label),
-                );
+                out.enable = toList(enable).map((a) => ctx.resolveBehaviorRef(a, label));
             }
             if (disable) {
-                out.disable = toList(disable).map((a) =>
-                    ctx.resolveBehaviorRef(a, label),
-                );
+                out.disable = toList(disable).map((a) => ctx.resolveBehaviorRef(a, label));
             }
             return out;
         }
@@ -765,9 +743,7 @@ function compileBehaviorSystem(type, authored, behaviorSpec, label, ctx) {
         }
         case "applyActiveEffect": {
             return {
-                effects: toList(authored.effects).map((a) =>
-                    ctx.resolveEffectRef(a, label),
-                ),
+                effects: toList(authored.effects).map((a) => ctx.resolveEffectRef(a, label)),
             };
         }
         default:
@@ -821,13 +797,7 @@ const REGION_VISIBILITY = Object.freeze({
 });
 
 /** `CONST.EDGE_RESTRICTION_TYPES`. */
-const RESTRICTION_TYPES = Object.freeze([
-    "light",
-    "darkness",
-    "sight",
-    "sound",
-    "move",
-]);
+const RESTRICTION_TYPES = Object.freeze(["light", "darkness", "sight", "sound", "move"]);
 
 /**
  * Compile one authored region into a Region document with its behaviours.
@@ -917,7 +887,7 @@ export function buildScene(fm, ctx) {
     const sohl = fm.sohl ?? {};
     const sceneId = fm.id;
     if (!sceneId) throw new Error("a map note needs an `id`");
-    const profile = mapProfile(fm.type);
+    const profile = mapProfile(fm.subType);
 
     const dimensions = sohl.dimensions;
     if (
@@ -925,9 +895,7 @@ export function buildScene(fm, ctx) {
         dimensions.length !== 2 ||
         !dimensions.every((n) => Number.isInteger(n) && n > 0)
     ) {
-        throw new Error(
-            "`dimensions` is [width, height] in whole pixels — the map's own size",
-        );
+        throw new Error("`dimensions` is [width, height] in whole pixels — the map's own size");
     }
     const pxPerGrid = sohl.pxPerGrid;
     if (!Number.isInteger(pxPerGrid) || pxPerGrid <= 0) {
@@ -936,7 +904,11 @@ export function buildScene(fm, ctx) {
                 "match the art",
         );
     }
-    if (!sohl.image) throw new Error("a map note needs an `image`");
+    // Read from the note rather than from its `sohl:` block: art is not
+    // system-specific, so `img` is authored at the top level like every other
+    // type's, and `sohlField` honours the block for anything already there.
+    const img = readAliasedField(fm, "img");
+    if (!img) throw new Error("a map note needs an `img`");
 
     const warn = (message) => {
         if (ctx.warnings) ctx.warnings.push(message);
@@ -961,7 +933,7 @@ export function buildScene(fm, ctx) {
         tokenVision: profile.tokenVision,
         fog: { mode: profile.fog.mode },
         initialLevel: DEFAULT_LEVEL_ID,
-        levels: [buildLevel(sohl, sceneId)],
+        levels: [buildLevel(sohl, sceneId, img)],
         drawings: [],
         tokens: [],
         lights: buildLights(sohl, geom, inner),
@@ -981,9 +953,7 @@ export function buildScene(fm, ctx) {
 
     if (ctx.journalEntryId) {
         if (!ctx.packageId) {
-            throw new Error(
-                "a map note with a journal needs `packageId` in its compile context",
-            );
+            throw new Error("a map note with a journal needs `packageId` in its compile context");
         }
         // `Scene.journal` is a plain ForeignDocumentField, which
         // `ForeignDocumentField#initialize` unconditionally nulls inside a
@@ -992,19 +962,14 @@ export function buildScene(fm, ctx) {
         // pack needs the flag to find the entry at all.
         scene.journal = ctx.journalEntryId;
         scene.flags[ctx.packageId] = {
-            docUuid: compendiumUuid(
-                ctx.packageId,
-                "doc",
-                ctx.journalEntryId,
-                ctx.journalPack,
-            ),
+            docUuid: compendiumUuid(ctx.packageId, "doc", ctx.journalEntryId, ctx.journalPack),
         };
     }
     return scene;
 }
 
 /**
- * Synthesise the scene's single embedded Level from `image:` / `overlay:`.
+ * Synthesise the scene's single embedded Level from `img:` / `overlay:`.
  *
  * Authors never write `levels:`. A scene must ship at least one Level — the
  * client-side `_preCreate` net that would create one does not run for offline
@@ -1014,16 +979,20 @@ export function buildScene(fm, ctx) {
  *
  * @param {object} sohl - The note's `sohl:` block.
  * @param {string} sceneId - The owning scene's `_id`.
+ * @param {string} [img] - The background art, already resolved from the note.
+ *   Passed by {@link buildScene}, which reads it from the note rather than from
+ *   the block; defaults to whichever spelling the block itself carries, so a
+ *   direct two-argument call still works (#142).
  * @returns {object} The Level document, keyed for the pack.
  */
-export function buildLevel(sohl, sceneId) {
+export function buildLevel(sohl, sceneId, img = readAliasedField({ sohl }, "img")) {
     const level = {
         _id: DEFAULT_LEVEL_ID,
         name: sohl.levelName ?? "Ground",
         elevation: { bottom: 0, top: 20 },
         background: {
             color: sohl.backgroundColor ?? "#999999",
-            src: sohl.image,
+            src: img,
         },
         foreground: { src: sohl.overlay ?? null },
         sort: 0,
@@ -1050,9 +1019,7 @@ export function buildWalls(sohl, geom, ctx) {
         const label = `walls.${key}`;
         const segments = toList(spec.segments);
         if (!segments.length) {
-            throw new Error(
-                `${label}: a wall group needs at least one segment`,
-            );
+            throw new Error(`${label}: a wall group needs at least one segment`);
         }
         segments.forEach((segment, i) => {
             const id = makeId("scene-wall", `${ctx.sceneId}:${key}:${i}`);
@@ -1171,8 +1138,7 @@ export function buildSounds(sohl, geom, ctx) {
     return Object.entries(sohl.sounds ?? {}).map(([key, spec]) => {
         const label = `sounds.${key}`;
         const [x, y] = requirePosition(spec.position, { ...geom, label });
-        if (!spec.path)
-            throw new Error(`${label}: an ambient sound needs a path`);
+        if (!spec.path) throw new Error(`${label}: an ambient sound needs a path`);
         const id = spec._id || makeId("scene-sound", `${ctx.sceneId}:${key}`);
         return {
             _id: id,