@heroiclands/package-build 23.0.0 → 23.1.1

package/engine/place-relation-terms.mjs

@@ -0,0 +1,174 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The closed sets a place's `borders` and `routes` are held to, and the keys
+ * one entry of each carries.
+ *
+ * A leaf module, importing nothing: the note vocabulary reads the entry
+ * declarations as it loads, and {@link module:engine/place-relations}, which
+ * checks what the values mean, reaches the vocabulary through the Address
+ * reader.
+ *
+ * @module
+ */
+
+/* --------------------------------------------------------------------- */
+/*  The closed sets                                                       */
+/* --------------------------------------------------------------------- */
+
+/**
+ * The type a border's or a route's `to` names.
+ *
+ * It is both the default its `<type>` segment takes when an author omits it and
+ * the whole of the set the position accepts, which is what makes `vylar` and
+ * `place-vylar` the same Address and a `to` naming a `lore` note an error rather
+ * than a lookup that quietly finds nothing.
+ *
+ * @type {string}
+ */
+export const RELATION_TYPE = "place";
+
+/**
+ * The eight compass bearings, clockwise from north.
+ *
+ * Where a neighbour or a destination lies from the place stating it. The
+ * order is load-bearing: {@link oppositeBearing} reads four steps around it.
+ *
+ * @type {readonly string[]}
+ */
+export const BEARINGS = Object.freeze(["N", "NE", "E", "SE", "S", "SW", "W", "NW"]);
+
+/**
+ * The modes a route is travelled by: `land`, `boat` on a river or a lake,
+ * `ship` on open sea.
+ *
+ * @type {readonly string[]}
+ */
+export const ROUTE_MODES = Object.freeze(["land", "boat", "ship"]);
+
+/**
+ * The days markers a route may state.
+ *
+ * Each is "about this, under normal conditions": `10`, `20` and `30` are one,
+ * two and three ten-day weeks, `180` is many months, `360` is "who knows".
+ *
+ * @type {readonly number[]}
+ */
+export const TRAVEL_DAYS = Object.freeze([1, 2, 3, 5, 10, 20, 30, 45, 60, 90, 180, 360]);
+
+/**
+ * The terrain registry, each terrain naming the modes that cross it.
+ *
+ * A land terrain is crossed by land alone; open sea by ship; a river or a lake
+ * by boat; a coast by all three, because a coast road and a coasting voyage
+ * are both journeys along it.
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+export const TERRAIN_MODES = Object.freeze({
+    road: Object.freeze(["land"]),
+    track: Object.freeze(["land"]),
+    plain: Object.freeze(["land"]),
+    steppe: Object.freeze(["land"]),
+    hills: Object.freeze(["land"]),
+    mountains: Object.freeze(["land"]),
+    forest: Object.freeze(["land"]),
+    jungle: Object.freeze(["land"]),
+    marsh: Object.freeze(["land"]),
+    dunes: Object.freeze(["land"]),
+    desert: Object.freeze(["land"]),
+    ice: Object.freeze(["land"]),
+    coast: Object.freeze(["land", "boat", "ship"]),
+    "open-sea": Object.freeze(["ship"]),
+    river: Object.freeze(["boat"]),
+    lake: Object.freeze(["boat"]),
+});
+
+/**
+ * The terrain names, in registry order — the closed set a `terrain` list
+ * draws from.
+ *
+ * @type {readonly string[]}
+ */
+export const TERRAINS = Object.freeze(Object.keys(TERRAIN_MODES));
+
+/** A list entry's `to` and `bearing`, which both relations carry. */
+const RELATION_ENDS = Object.freeze([
+    Object.freeze({
+        name: "to",
+        kind: "address",
+        required: true,
+        shape: "the other place — its shortcode, or its Address",
+        describe: "The other place, by Address; the type defaults to `place`.",
+    }),
+    Object.freeze({
+        name: "bearing",
+        kind: "string",
+        required: true,
+        shape: `one of ${BEARINGS.join(", ")}`,
+        describe: "Where the other place lies from here.",
+    }),
+]);
+
+/**
+ * The keys a `borders` entry carries, as inner-key declarations. Both are
+ * required.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const BORDER_FIELDS = RELATION_ENDS;
+
+/**
+ * The keys a `routes` entry carries, as inner-key declarations. `to`,
+ * `bearing`, `mode` and `days` are required; `terrain` and `leagues` are
+ * optional.
+ *
+ * @type {readonly import("./data-keys.mjs").InnerKeySpec[]}
+ */
+export const ROUTE_FIELDS = Object.freeze([
+    ...RELATION_ENDS,
+    Object.freeze({
+        name: "mode",
+        kind: "string",
+        required: true,
+        shape: `one of ${ROUTE_MODES.join(", ")}`,
+        describe: "How the journey is travelled.",
+    }),
+    Object.freeze({
+        name: "days",
+        kind: "number",
+        required: true,
+        shape: `one of ${TRAVEL_DAYS.join(", ")}`,
+        describe: "About how many days the journey takes, under normal conditions.",
+    }),
+    Object.freeze({
+        name: "terrain",
+        kind: "list",
+        shape: "a list of terrains in travel order",
+        entries: Object.freeze({ kind: "string", shape: "a terrain" }),
+        describe: "The terrains crossed, in travel order, each crossable by the mode.",
+    }),
+    Object.freeze({
+        name: "leagues",
+        kind: "number",
+        shape: "a distance in leagues",
+        describe: "The distance, in leagues.",
+    }),
+]);
+
+/** The keys a `borders` entry carries. @type {readonly string[]} */
+export const BORDER_KEYS = Object.freeze(BORDER_FIELDS.map((field) => field.name));
+
+/** The keys a `routes` entry carries. @type {readonly string[]} */
+export const ROUTE_KEYS = Object.freeze(ROUTE_FIELDS.map((field) => field.name));

package/engine/place-relations.mjs

@@ -34,8 +34,8 @@
  * shortcode in different packages never answer for each other.
  *
  * **The value sets are closed and stated once.** The eight bearings, the three
- * travel modes, the days markers and the terrain registry are the constants
- * below, read by the lint, compared against the specification's tables by the
+ * travel modes, the days markers and the terrain registry are the constants of
+ * {@link module:engine/place-relation-terms}, re-exported here, read by the lint, compared against the specification's tables by the
  * test suite, and exported for a consumer drawing a map. A second copy of any
  * of them is one more list free to disagree.
  *
@@ -69,100 +69,31 @@ import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { acceptsType, parseAddress, renderAddress } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
 
-/* --------------------------------------------------------------------- */
-/*  The closed sets                                                       */
-/* --------------------------------------------------------------------- */
-
-/**
- * The type a border's or a route's `to` names.
- *
- * It is both the default its `<type>` segment takes when an author omits it and
- * the whole of the set the position accepts, which is what makes `vylar` and
- * `place-vylar` the same Address and a `to` naming a `lore` note an error rather
- * than a lookup that quietly finds nothing.
- *
- * @type {string}
- */
-export const RELATION_TYPE = "place";
-
-/**
- * The eight compass bearings, clockwise from north.
- *
- * Where a neighbour or a destination lies from the place stating it. The
- * order is load-bearing: {@link oppositeBearing} reads four steps around it.
- *
- * @type {readonly string[]}
- */
-export const BEARINGS = Object.freeze(["N", "NE", "E", "SE", "S", "SW", "W", "NW"]);
-
-/**
- * The modes a route is travelled by: `land`, `boat` on a river or a lake,
- * `ship` on open sea.
- *
- * @type {readonly string[]}
- */
-export const ROUTE_MODES = Object.freeze(["land", "boat", "ship"]);
-
-/**
- * The days markers a route may state.
- *
- * Each is "about this, under normal conditions": `10`, `20` and `30` are one,
- * two and three ten-day weeks, `180` is many months, `360` is "who knows".
- *
- * @type {readonly number[]}
- */
-export const TRAVEL_DAYS = Object.freeze([1, 2, 3, 5, 10, 20, 30, 45, 60, 90, 180, 360]);
-
-/**
- * The terrain registry, each terrain naming the modes that cross it.
- *
- * A land terrain is crossed by land alone; open sea by ship; a river or a lake
- * by boat; a coast by all three, because a coast road and a coasting voyage
- * are both journeys along it.
- *
- * @type {Readonly<Record<string, readonly string[]>>}
- */
-export const TERRAIN_MODES = Object.freeze({
-    road: Object.freeze(["land"]),
-    track: Object.freeze(["land"]),
-    plain: Object.freeze(["land"]),
-    steppe: Object.freeze(["land"]),
-    hills: Object.freeze(["land"]),
-    mountains: Object.freeze(["land"]),
-    forest: Object.freeze(["land"]),
-    jungle: Object.freeze(["land"]),
-    marsh: Object.freeze(["land"]),
-    dunes: Object.freeze(["land"]),
-    desert: Object.freeze(["land"]),
-    ice: Object.freeze(["land"]),
-    coast: Object.freeze(["land", "boat", "ship"]),
-    "open-sea": Object.freeze(["ship"]),
-    river: Object.freeze(["boat"]),
-    lake: Object.freeze(["boat"]),
-});
-
-/**
- * The terrain names, in registry order — the closed set a `terrain` list
- * draws from.
- *
- * @type {readonly string[]}
- */
-export const TERRAINS = Object.freeze(Object.keys(TERRAIN_MODES));
-
-/**
- * The keys a `borders` entry may carry. Both are required.
- *
- * @type {readonly string[]}
- */
-export const BORDER_KEYS = Object.freeze(["to", "bearing"]);
-
-/**
- * The keys a `routes` entry may carry. `to`, `bearing`, `mode` and `days` are
- * required; `terrain` and `leagues` are optional.
- *
- * @type {readonly string[]}
- */
-export const ROUTE_KEYS = Object.freeze(["to", "bearing", "mode", "days", "terrain", "leagues"]);
+import {
+    RELATION_TYPE,
+    BEARINGS,
+    ROUTE_MODES,
+    TRAVEL_DAYS,
+    TERRAIN_MODES,
+    TERRAINS,
+    BORDER_FIELDS,
+    ROUTE_FIELDS,
+    BORDER_KEYS,
+    ROUTE_KEYS,
+} from "./place-relation-terms.mjs";
+
+export {
+    RELATION_TYPE,
+    BEARINGS,
+    ROUTE_MODES,
+    TRAVEL_DAYS,
+    TERRAIN_MODES,
+    TERRAINS,
+    BORDER_FIELDS,
+    ROUTE_FIELDS,
+    BORDER_KEYS,
+    ROUTE_KEYS,
+};
 
 /**
  * The bearing the other end of a relation states, or `undefined` for a value
@@ -362,7 +293,6 @@ function checkRelation(note, { field, index }) {
             })
         :   undefined;
     const isRoute = field === "routes";
-    const keys = isRoute ? ROUTE_KEYS : BORDER_KEYS;
     const at = (i, key) =>
         positionOfFrontmatterPath(raw, ["data", field, i, ...(key ? [key] : [])]);
     const label = (i, key) => `\`data.${field}[${i}]${key ? `.${key}` : ""}\``;
@@ -373,31 +303,20 @@ function checkRelation(note, { field, index }) {
         message,
     });
     const error = (i, key, message) => findings.push(finding(i, key, "error", message));
+    // Absent, or not one value: the inner-key check's finding, made from the
+    // declaration, so nothing here repeats it.
+    const unread = (value) =>
+        value === undefined || value === null || value === "" || typeof value === "object";
 
     /** `to` → the modes it has been listed with, for the once-per-pair rule. */
     const seen = new Map();
 
     list.forEach((entry, i) => {
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-            error(
-                i,
-                undefined,
-                `${label(i)} must be a map — \`{ to: <shortcode>, bearing: <bearing>` +
-                    `${isRoute ? ", mode: <mode>, days: <days>" : ""} }\` — but reads ` +
-                    JSON.stringify(entry),
-            );
-            return;
-        }
-
-        for (const key of Object.keys(entry)) {
-            if (keys.includes(key)) continue;
-            error(
-                i,
-                key,
-                `"${key}" is not a key of a ${field} entry; an entry carries ` +
-                    `${oneOf(keys.map((k) => `\`${k}\``))} and nothing else`,
-            );
-        }
+        // An entry that is not a map, an undeclared key, a required key left
+        // out and a value of the wrong kind are the inner-key check's
+        // findings, made from `BORDER_FIELDS` and `ROUTE_FIELDS`. What is
+        // checked here is what the values mean.
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) return;
 
         // `to`: an Address naming a place, and one a place declares.
         const to = entry.to;
@@ -407,7 +326,7 @@ function checkRelation(note, { field, index }) {
         let toAddress;
         const read = parseAddress(to, here);
         if (to === undefined || to === null || to === "") {
-            error(i, undefined, `${label(i)} must name the other place in \`to\``);
+            toIsValid = false;
         } else if (
             read.reason === "no-content-index" ||
             (!read.reason && here.noIndexPackages?.has(read.package))
@@ -468,8 +387,8 @@ function checkRelation(note, { field, index }) {
         // `bearing`.
         const bearing = entry.bearing;
         let bearingIsValid = false;
-        if (bearing === undefined || bearing === null || bearing === "") {
-            error(i, undefined, `${label(i)} must state a \`bearing\` — ${oneOf(BEARINGS)}`);
+        if (unread(bearing)) {
+            bearingIsValid = false;
         } else if (!BEARINGS.includes(String(bearing))) {
             error(
                 i,
@@ -485,8 +404,8 @@ function checkRelation(note, { field, index }) {
         let mode;
         let days;
         if (isRoute) {
-            if (entry.mode === undefined || entry.mode === null || entry.mode === "") {
-                error(i, undefined, `${label(i)} must state a \`mode\` — ${oneOf(ROUTE_MODES)}`);
+            if (unread(entry.mode)) {
+                mode = undefined;
             } else if (!ROUTE_MODES.includes(String(entry.mode))) {
                 error(
                     i,
@@ -498,9 +417,7 @@ function checkRelation(note, { field, index }) {
                 mode = String(entry.mode);
             }
 
-            if (entry.days === undefined || entry.days === null || entry.days === "") {
-                error(i, undefined, `${label(i)} must state \`days\` — ${oneOf(TRAVEL_DAYS)}`);
-            } else {
+            if (!unread(entry.days)) {
                 const n = daysOf(entry.days);
                 if (n === undefined || !TRAVEL_DAYS.includes(n)) {
                     error(
@@ -515,44 +432,39 @@ function checkRelation(note, { field, index }) {
                 }
             }
 
-            if (entry.terrain !== undefined && entry.terrain !== null) {
-                if (!Array.isArray(entry.terrain)) {
-                    error(
-                        i,
-                        "terrain",
-                        `${label(i, "terrain")} must be a list of terrains in travel order, ` +
-                            `but reads ${JSON.stringify(entry.terrain)}`,
-                    );
-                } else {
-                    entry.terrain.forEach((terrain, j) => {
-                        const name = String(terrain);
-                        const modes = TERRAIN_MODES[name];
-                        if (!modes) {
-                            findings.push({
-                                file: note.file,
-                                ...positionOfFrontmatterPath(raw, ["data", field, i, "terrain", j]),
-                                severity: "error",
-                                message:
-                                    `${label(i, "terrain")} names "${name}", which is not a ` +
-                                    `terrain; the registry is ${oneOf(TERRAINS)}`,
-                            });
-                        } else if (mode && !modes.includes(mode)) {
-                            findings.push({
-                                file: note.file,
-                                ...positionOfFrontmatterPath(raw, ["data", field, i, "terrain", j]),
-                                severity: "error",
-                                message:
-                                    `${label(i, "terrain")} names "${name}", which is crossed ` +
-                                    `by ${oneOf(modes)}, but the route is by ${mode}`,
-                            });
-                        }
-                    });
-                }
+            // A `terrain` that is not a list is the inner-key check's finding.
+            if (Array.isArray(entry.terrain)) {
+                entry.terrain.forEach((terrain, j) => {
+                    if (unread(terrain)) return;
+                    const name = String(terrain);
+                    const modes = TERRAIN_MODES[name];
+                    if (!modes) {
+                        findings.push({
+                            file: note.file,
+                            ...positionOfFrontmatterPath(raw, ["data", field, i, "terrain", j]),
+                            severity: "error",
+                            message:
+                                `${label(i, "terrain")} names "${name}", which is not a ` +
+                                `terrain; the registry is ${oneOf(TERRAINS)}`,
+                        });
+                    } else if (mode && !modes.includes(mode)) {
+                        findings.push({
+                            file: note.file,
+                            ...positionOfFrontmatterPath(raw, ["data", field, i, "terrain", j]),
+                            severity: "error",
+                            message:
+                                `${label(i, "terrain")} names "${name}", which is crossed ` +
+                                `by ${oneOf(modes)}, but the route is by ${mode}`,
+                        });
+                    }
+                });
             }
 
-            if (entry.leagues !== undefined && entry.leagues !== null) {
+            // Not a number at all is the inner-key check's finding; a number
+            // that is no distance is this one's.
+            if (!unread(entry.leagues)) {
                 const n = daysOf(entry.leagues);
-                if (n === undefined || n <= 0) {
+                if (n !== undefined && n <= 0) {
                     error(
                         i,
                         "leagues",

package/engine/rank-ladder.mjs

@@ -30,25 +30,22 @@
  * nothing, and one missing its `description` ships a rung that says nothing on
  * a sheet or a page.
  *
- * Two things are deliberately **not** checked here, because something else
- * already does and a finding reported twice is a finding read once and fixed
- * neither time:
- *
- * - **that `ranks` is a list at all** — the field declares `kind: "list"`, and
- *   the shape check names it;
- * - **that `lore` resolves** — the reference checker reads every Address in the
- *   note, this one included.
+ * What a rung *holds* is declared in {@link RUNG_FIELDS} and checked by the
+ * inner-key check: that `ranks` is a list of maps, that a rung carries no key
+ * beyond the four, that `level`, `title` and `description` are stated, and that
+ * each is the kind it is declared — a `level` a whole number. What is checked
+ * here is what only a ladder can say — that a level is held by one rung — and nothing is
+ * reported twice, because a finding reported twice is a finding read once and
+ * fixed neither time. That `lore` resolves is the reference checker's.
  *
  * @module
  */
 
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 
-/** The keys a rung may carry. */
-const RUNG_KEYS = Object.freeze(["level", "title", "description", "lore"]);
+import { RUNG_FIELDS } from "./standing-terms.mjs";
 
-/** The keys a rung must carry a value for. */
-const REQUIRED_TEXT = Object.freeze(["title", "description"]);
+export { RUNG_FIELDS };
 
 /** Every affiliation has an ordinary standing that a being can name as rank 1. */
 export function checkAffiliationRankFloor(note) {
@@ -176,27 +173,12 @@ export function checkRankLadder(note) {
         const which =
             integer(rung?.level) ? `rank ${rung.level}` : `rank ${index + 1} of the ladder`;
 
-        if (!mapping(rung)) {
-            at([rungPath, base], `${which} must be a map of level, title and description`);
-            return;
-        }
-
-        for (const key of Object.keys(rung)) {
-            if (RUNG_KEYS.includes(key)) continue;
-            at(
-                [[...rungPath, key], rungPath],
-                `${which} has unknown key ${key}; a rung takes ${RUNG_KEYS.join(", ")}`,
-            );
-        }
+        // Not a map, an undeclared key, and an absent or mistyped `level`,
+        // `title` or `description` are the inner-key check's findings.
+        if (!mapping(rung)) return;
 
-        if (!integer(rung.level)) {
-            at(
-                [[...rungPath, "level"], rungPath],
-                rung.level === undefined || rung.level === null ?
-                    `${which} needs a level — the rung's position on this body's own ladder`
-                :   `${which} has a level that is not a whole number`,
-            );
-        } else {
+        // A level that is not a whole number is the inner-key check's finding.
+        if (integer(rung.level)) {
             // A level belongs to one rung. Two rungs claiming it leave a
             // member's `rank` answering to the one written first, so the
             // ladder's own order decides what the standing is called and
@@ -215,15 +197,6 @@ export function checkRankLadder(note) {
                         `each rung states its own`,
                 );
         }
-
-        for (const key of REQUIRED_TEXT) {
-            if (stated(rung[key])) continue;
-            at(
-                [[...rungPath, key], rungPath],
-                `${which} needs a ${key}: ` +
-                    (key === "title" ? "what the standing is called" : "what the standing is"),
-            );
-        }
     });
 
     return findings;

package/engine/reckoning-markers.mjs

@@ -131,6 +131,8 @@ export function resolveReckoningMarkers(index, daysPerYear) {
             );
         const byStart = new Map();
         for (const row of declared) {
+            // A fractional start is the inner-key check's one finding.
+            if (typeof row.start === "number" && !Number.isInteger(row.start)) continue;
             if (row.start !== null && (!Number.isSafeInteger(row.start) || row.start < 1)) {
                 error(
                     note,

package/engine/region-events.mjs

@@ -15,19 +15,13 @@
  * The curated Foundry region-event vocabulary, as plain data.
  *
  * Deliberately **plain ESM** — no TypeScript, no `@src` aliases, no Foundry —
- * for the same reason `../sohl/default-item-art.mjs` is: the map-note pack
- * compiler runs under bare `node`, outside the bundler that resolves `@src` and
- * strips types, and it must reject an authored region event that the runtime
- * would silently drop. One list here is what keeps the build-time lint and the
- * runtime bridge from drifting apart.
+ * so the Foundry runtime and any build-time consumer read one list, and the
+ * events a region trigger forwards cannot drift between them.
  *
- * It sits in this package rather than in the system's `src/` tree because the
- * map-note compiler that reads it is installed as a dependency, and a
- * relative path out of the package would resolve to garbage from
- * `node_modules`. The runtime reaches it back through the package's
- * `./engine/region-events` entry point. It is engine-side, not
- * SoHL-side, because any content module that authors a scene region — an
- * adventure module included — needs this vocabulary.
+ * The runtime reaches it through the package's `./engine/region-events` entry
+ * point. It is engine-side, not SoHL-side, because a Scene region exported
+ * from any content module — an adventure module included — names its events
+ * from this vocabulary.
  *
  * The prose explaining *why* each event is curated or excluded lives with the
  * typed re-exports in `src/entity/event/region-triggers.ts`, which is the