@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/rank-ladder.mjs

@@ -0,0 +1,198 @@
+/*
+ * 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
+ */
+
+/**
+ * What a **rung** of an affiliation's rank ladder has to state.
+ *
+ * A rung is a map of `level`, `title` and `description`, all three required,
+ * plus an optional `lore` Address for a standing that needs more said about it
+ * than a description can hold. Those three keys together are a complete
+ * statement of a rung; nothing further is needed for a ladder to be correct.
+ *
+ * **A level belongs to one rung.** The ladder is read by level, so two rungs
+ * claiming one level leave a member's `rank` answering to whichever is written
+ * first — a standing whose name changes when two lines swap places. A body that
+ * confers two titles at one standing writes them as one rung, or gives each its
+ * own level.
+ *
+ * **The severity is error**, because the ladder is what a being's `rank`
+ * indexes into: a rung missing its `title` makes a standing that resolves to
+ * 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.
+ *
+ * @module
+ */
+
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/** The keys a rung may carry. */
+const RUNG_KEYS = Object.freeze(["level", "title", "description", "lore"]);
+
+/** The keys a rung must carry a value for. */
+const REQUIRED_TEXT = Object.freeze(["title", "description"]);
+
+/**
+ * Whether a value is a YAML mapping rather than a list or a scalar.
+ *
+ * @param {unknown} value - What was authored.
+ * @returns {boolean} True for a mapping.
+ */
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Whether a value states a whole number.
+ *
+ * A quoted `"3"` counts, because YAML hands a quoted scalar back as a string
+ * and the ladder reads it as a number either way — `3.5` does not, because a
+ * rung sits on a rung and there is nothing between two of them.
+ *
+ * @param {unknown} value - The authored `level`.
+ * @returns {boolean} True when it is an integer.
+ */
+function integer(value) {
+    if (typeof value === "number") return Number.isInteger(value);
+    if (typeof value !== "string" || value.trim() === "") return false;
+    return Number.isInteger(Number(value));
+}
+
+/**
+ * Whether a value states something rather than nothing.
+ *
+ * @param {unknown} value - The authored `title` or `description`.
+ * @returns {boolean} True for a non-empty string.
+ */
+function stated(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * Check one affiliation's `data.governance.ranks` against the rung contract.
+ *
+ * Each problem is its own finding, so a rung missing all three of its required
+ * keys reports three rather than the first: a reader fixing a ladder wants the
+ * whole of it in one pass.
+ *
+ * **A finding is located by the node it is about**, through the frontmatter's
+ * own YAML tree — a present-but-wrong value points at that value, and an absent
+ * key points at the rung that should have carried it, since a key that was
+ * never written has no position of its own. Where even the rung cannot be
+ * located the position is dropped rather than guessed, and the finding names
+ * the file alone.
+ *
+ * @param {object} note - The note being checked.
+ * @param {string} note.file - Its path, as a diagnostic spells it.
+ * @param {string} [note.raw] - Its source, for the position.
+ * @param {object} [note.fm] - Its parsed frontmatter.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: string, message: string}>} The findings, in authored order.
+ */
+export function checkRankLadder(note) {
+    const ranks = note.fm?.data?.governance?.ranks;
+    // Absent is the ordinary case: most bodies confer no ranks at all. A value
+    // that is not a list is the shape check's finding, not this one's.
+    if (!Array.isArray(ranks)) return [];
+
+    const findings = [];
+    const base = ["data", "governance", "ranks"];
+
+    /**
+     * One finding, located at the first of the given paths that resolves.
+     *
+     * @param {Array<Array<string|number>>} paths - Candidates, most specific
+     *   first.
+     * @param {string} message - What is wrong.
+     * @returns {void}
+     */
+    const at = (paths, message) => {
+        let position = {};
+        for (const path of paths) {
+            position = positionOfFrontmatterPath(note.raw ?? "", path);
+            if (position.line !== undefined) break;
+        }
+        findings.push({ file: note.file, ...position, severity: "error", message });
+    };
+
+    // Level → how the rung holding it is named, so a repeat can say which rung
+    // already holds the level rather than only that something does.
+    const held = new Map();
+
+    ranks.forEach((rung, index) => {
+        const rungPath = [...base, index];
+        // Named by its level where it states one, because a reader scanning a
+        // ladder of fifteen rungs knows them by level and not by position.
+        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(", ")}`,
+            );
+        }
+
+        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 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
+            // moving two lines renames it. Reported on the second rung,
+            // naming the first, because the first is the one a reader has to
+            // find to tell the two apart.
+            const level = Number(rung.level);
+            const named = stated(rung.title) ? JSON.stringify(rung.title) : which;
+            const first = held.get(level);
+            if (first === undefined) held.set(level, named);
+            else
+                at(
+                    [[...rungPath, "level"], rungPath],
+                    `rank ${level} is declared twice, as ${first} and ${named}; a level ` +
+                        `is a rung's identity and a member's rank indexes into it, so ` +
+                        `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

@@ -54,7 +54,7 @@ export function resolveReckoningMarkers(index, daysPerYear) {
             1,
             daysPerYear,
         );
-        const pkg = fm.package ?? note.package ?? index?.contentPackage;
+        const pkg = note.package ?? index?.contentPackage;
         const declared = [];
         for (const [position, era] of rows.entries()) {
             if (!era || typeof era.shortcode !== "string" || !era.shortcode || !fm.shortcode)

package/engine/retired-fields.mjs

@@ -58,11 +58,9 @@
  * one of them in. Every note that carried one has been moved, across four
  * repositories, and this is the third step of that retirement.
  *
- * Refusing it matters more than refusing an ordinary dead key, because top
- * level is *deliberately open*: an unrecognised key there is passed through to
- * Hugo, so a stray `traits:` would not be ignored loudly but would arrive on
- * the page as a theme parameter, checked by nothing. The whole argument for
- * `data:` being closed is the argument for refusing this.
+ * Refusing it by name rather than as an unknown key is what names the home the
+ * facts have: the finding says which `data:` key each one becomes, which an
+ * author cannot read off a list of the keys the region declares.
  *
  * `sohl.traits` is a different field that shares the name — `projectilegear`
  * declares one, and the theme's gear sidebar reads it — so the refusal is
@@ -350,8 +348,7 @@ export function traitsRetiredMessage(file) {
         (file ? ` — ${file}` : "") +
         ". A being's own description belongs in the closed container the " +
         "content format declares, where `being` declares every one of its " +
-        "keys; at the top level it was passed through to the page unchecked, " +
-        "so a misspelling became a theme parameter rather than a finding. " +
+        "keys. " +
         "`gender`, `species`, `age` and `appearance.*` move unchanged; " +
         "`traits.birthday` becomes `data.born`; three reshape — " +
         "`traits.height.m` becomes `data.height` " +
@@ -526,12 +523,10 @@ export function legacyKeyMessage(block, field, file) {
  * What a note writing a field at the **top-level key `data:` gathered it off**
  * is told.
  *
- * {@link legacyKeyMessage}'s counterpart for the other retiring position. The
- * sweep
- * did not invent the facts `data:` holds — it collected them out of the note's
- * open top level — so `portrait:` beside `img:` is the *pre-`data:`* spelling
- * of `data.portrait`, and both are read for the same reason both in-block
- * spellings are: a package moves its corpus when it is ready, not on a flag day.
+ * {@link legacyKeyMessage}'s counterpart for the other retiring position.
+ * `portrait:` beside `img:` is the bare spelling of `data.portrait`, and both
+ * are read for the same reason both in-block spellings are: a package moves its
+ * corpus when it is ready, not on a flag day.
  *
  * It says nothing about which value is emitted, because that is not what an
  * author needs from it. The value is the same either way; what the finding

package/engine/scenes.mjs

@@ -50,6 +50,10 @@ import fs from "fs";
 import path from "path";
 import log from "loglevel";
 
+// The one reader of a system block's own properties, so a scene's effect
+// references resolve from the same position the item compiler emits from.
+import { blockProperty } from "./system-block.mjs";
+
 import {
     parseMarkdownFile,
     sohlField,
@@ -76,7 +80,7 @@ import { behaviorDocId, buildScene, isMapType, regionDocId } from "./map-notes.m
 import { buildItineraryScenes } from "./itinerary-scenes.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { rasterizeMapSvg } from "./map-raster.mjs";
-import { artPathname, artSlot } from "./art-fields.mjs";
+import { artPathname, artSlot, pathnameRoles } from "./art-fields.mjs";
 import { buildExportedScene } from "./exported-scene.mjs";
 
 /**
@@ -235,7 +239,11 @@ export class Scenes extends BasePackCompiler {
             // `resolveNoteId(fm)` with no package, which falls back to the
             // ambient one. What remains unset is a file with no address.
             if (!fm || !fm.id) continue;
-            if (fm.shortcode && Array.isArray(fm.effects) && fm.effects.length) {
+            // The Active Effects a region behaviour may point at, read from
+            // the block that carries them onto the document — the one position
+            // the format accepts for them.
+            const effects = blockProperty(fm, "sohl", "effects");
+            if (fm.shortcode && Array.isArray(effects) && effects.length) {
                 effectsByAddress.set(`${fm.type}-${fm.shortcode}`, {
                     id: fm.id,
                     type: fm.type,
@@ -246,7 +254,7 @@ export class Scenes extends BasePackCompiler {
                     // second router is a second answer to where the document
                     // landed, resolved from the working directory.
                     pack: this.#packRouter.resolveOrNull(fm, packForType(fm.type).docType),
-                    effects: fm.effects,
+                    effects,
                 });
             }
             if (!isMapType(fm.type)) continue;
@@ -387,11 +395,15 @@ export class Scenes extends BasePackCompiler {
      * @param {string} markdown - The converted body.
      * @param {string} entryId - The JournalEntry's id.
      * @param {string} name - The map's name (its lead page).
+     * @param {(address: string) => string|undefined} resolveRole - See
+     *   {@link module:engine/journals.splitPages}; threaded through so an
+     *   unanchored map figure's page key agrees with the journal this pass
+     *   derives it against.
      * @returns {Map<string, string>} heading key → page id.
      */
-    #pageIds(markdown, entryId, name) {
+    #pageIds(markdown, entryId, name, resolveRole) {
         const pageIds = new Map();
-        splitPages(markdown, name).forEach((page) => {
+        splitPages(markdown, name, resolveRole).forEach((page) => {
             const id = journalPageId(entryId, page);
             if (page.anchorSlug) pageIds.set(page.anchorSlug, id);
             const slug = slugify(page.name);
@@ -431,6 +443,12 @@ export class Scenes extends BasePackCompiler {
     compileNote(fm, markdown) {
         const name = resolveName(fm);
         const hasBody = Boolean(String(markdown).trim());
+        // The markdown this pass reads has already had its embeds rewritten
+        // into ordinary images, each `src` the pathname `pathnameRoles` keys
+        // its roles by — see {@link module:engine/journals.Journals#buildEntry},
+        // which derives this same journal's pages the same way.
+        const roles = pathnameRoles(this.linkIndex);
+        const resolveRole = (pathname) => roles.get(pathname);
         // The same doc-entry id the journals pass derives, from the
         // shared `docEntryTypes` arrangement — so neither
         // pass has to read the other's output.
@@ -503,7 +521,8 @@ export class Scenes extends BasePackCompiler {
                         hasBody ?
                             this.#packRouter.resolve(fm, "JournalEntry")
                         :   this.#packRouter.defaultOf("JournalEntry"),
-                    pageIds: hasBody ? this.#pageIds(markdown, entryId, name) : new Map(),
+                    pageIds:
+                        hasBody ? this.#pageIds(markdown, entryId, name, resolveRole) : new Map(),
                     knownActions: this.knownActions,
                     warnings,
                     ...this.#resolvers(this.index, this.effectsByAddress, fm.shortcode),
@@ -527,12 +546,12 @@ export class Scenes extends BasePackCompiler {
                     name,
                     markdown,
                     leadName: name,
+                    resolveRole,
                     // As in the journals pass: an address resolves in the
                     // pack that emits it, which is what makes the folder
                     // materialise there too. The id spelling that used
                     // to cross packs verbatim is retired.
                     folder: this.folderResolver(authoredFolder, { isAddress: true }),
-                    flags: fm.flags,
                 })
             :   null;