@heroiclands/package-build 23.1.0 → 23.2.0

package/engine/docs-checks.mjs

@@ -1,4 +1,13 @@
 /*
+ * 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
  */
 

package/engine/document-subtypes.mjs

@@ -63,11 +63,10 @@
  * @module
  */
 
-import { assertTypeNotRetired, currentType } from "./ids.mjs";
 import { NO_SYSTEM } from "./systems.mjs";
 
 export { NO_SYSTEM };
-import { locateFrontmatterKey } from "./retired-fields.mjs";
+import { locateFrontmatterKey } from "./diagnostics.mjs";
 
 /**
  * One row of a system's map: what a note of this type becomes.
@@ -201,12 +200,9 @@ function frozenRow(system, noteType, row) {
 /**
  * The row a system declares for a note type, or nothing.
  *
- * The **one** place a map is indexed, so the retirement window for a renamed
- * type is honoured everywhere a row is asked for — {@link documentSubtype},
- * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and
- * {@link systemOf} all arrive here. A note still spelling `armorgear` finds the
- * `armor` row, compiles into the `armorgear` document it always did, and keeps
- * the address it publishes at; only the *report* tells it to move.
+ * The **one** place a map is indexed — {@link documentSubtype},
+ * {@link mapsNoteType}, {@link noteTypesFor}'s consumers and {@link systemOf}
+ * all arrive here.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The note's declared `type`.
@@ -215,7 +211,7 @@ function frozenRow(system, noteType, row) {
  */
 export function subtypeRow(map, noteType) {
     if (!noteType || typeof noteType !== "string") return undefined;
-    return map?.types?.[currentType(noteType)];
+    return map?.types?.[noteType];
 }
 
 /**
@@ -315,6 +311,29 @@ export function documentSubtype(map, noteType, fm, { file, absPath } = {}) {
  * @property {string} [problem] - Why the reference names no document subtype.
  */
 
+/** Every subtype a map's rows produce, per map. @type {WeakMap<object, Set<string>>} */
+const PRODUCED = new WeakMap();
+
+/**
+ * The document subtypes the rows of a map produce.
+ *
+ * @param {DocumentSubtypeMap} map - The system's map.
+ * @returns {Set<string>} Each one-to-one row's subtype and every subtype a
+ *   one-to-many row permits.
+ */
+function producedSubtypes(map) {
+    let produced = PRODUCED.get(map);
+    if (!produced) {
+        produced = new Set();
+        for (const row of Object.values(map?.types ?? {})) {
+            if (row.subType) produced.add(row.subType);
+            for (const subType of row.subTypes ?? []) produced.add(subType);
+        }
+        PRODUCED.set(map, produced);
+    }
+    return produced;
+}
+
 /**
  * The document subtype a `(type, shortcode)` **reference** addresses.
  *
@@ -354,41 +373,35 @@ export function documentSubtype(map, noteType, fm, { file, absPath } = {}) {
  *   only the row has no block to read a discriminator from, so nothing here
  *   can choose, and choosing anyway would be right about half the time.
  *
- * A **retired** spelling is refused by name before any of that. Without it a
- * reference left behind by a merge would take the unmapped fallback and address
- * a document of the old name — resolving silently, which is precisely what a
- * retirement exists to stop.
- *
- * A **renamed** spelling is the opposite case and resolves normally, through
- * the same {@link currentType} every other lookup goes through. It has to
- * be this side as much as the note's own `type:`: the overwhelming majority of
- * the 31,000 occurrences of the old names are `(type, shortcode)` references
- * inside a being's `items:` list, so a window that resolved notes but not
- * references would silently drop 30,000 embedded items rather than compile them
- * unchanged.
+ * A type that no row names, that no row produces as a subtype and that the
+ * consumer does not declare is refused: stamping the authored spelling on it
+ * would address a document that cannot exist.
  *
  * @param {DocumentSubtypeMap} map - The system's map.
  * @param {string|undefined} noteType - The type the reference names.
  * @param {string} document - The Foundry document class the reference must
  *   address — `"Item"` for a being's embedded items.
+ * @param {object} [options] - Options.
+ * @param {ReadonlySet<string>} [options.declared] - The item types the
+ *   consuming repository declares itself, which the map does not name.
  * @returns {ReferencedSubtype} The subtype, or why there is none.
  */
-export function referencedSubtype(map, noteType, document) {
+export function referencedSubtype(map, noteType, document, { declared } = {}) {
     if (!noteType || typeof noteType !== "string") {
         return { problem: "the reference names no type" };
     }
-    try {
-        assertTypeNotRetired(noteType);
-    } catch (err) {
-        return { problem: /** @type {Error} */ (err).message };
-    }
 
     const row = subtypeRow(map, noteType);
-    // No row: the type is the consumer's own, and its document is stamped with
-    // the note type. See the note on the unmapped fallback above. Returned as
-    // *authored*, not normalised — the Item pass stamps an unmapped document
-    // with `fm.type` verbatim, and the two answers have to agree.
-    if (!row) return { subType: noteType };
+    // No row: the type is the consumer's own, or a subtype a row produces, and
+    // its document is stamped with the note type. See the note on the unmapped
+    // fallback above. Returned as *authored* — the Item pass stamps an unmapped
+    // document with `fm.type` verbatim, and the two answers have to agree.
+    if (!row) {
+        if (declared?.has(noteType) || producedSubtypes(map).has(noteType)) {
+            return { subType: noteType };
+        }
+        return { problem: `"${noteType}" is not a type any registry declares` };
+    }
 
     if (row.document !== document) {
         return {
@@ -406,8 +419,8 @@ export function referencedSubtype(map, noteType, document) {
         // reference does by never matching this row's key at all. Only a
         // reference that names the row without naming a subtype is genuinely
         // undecidable.
-        if (permitted.includes(currentType(noteType))) {
-            return { subType: currentType(noteType) };
+        if (permitted.includes(noteType)) {
+            return { subType: noteType };
         }
         return {
             problem:

package/engine/event-views.mjs

@@ -59,11 +59,14 @@ const BY_DATE = "ORDER BY e.whenSort NULLS LAST, e.address";
  * index record, and the `query` it writes for a note — given the note's
  * Address in each form an event may name it by, and the shape of the corpus —
  * or `null` where the corpus states nothing the view could select. A view's
- * `own` query, where it has one, is what decides whether the view has rows.
+ * `own` query, where it has one, is what decides whether the view has rows;
+ * a view with `owners` answers that for many notes in one query, given each
+ * note's Address forms.
  *
  * @type {ReadonlyArray<Readonly<{slug: string, heading: string,
  *   applies: (record: object) => boolean,
- *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null}>>}
+ *   query: (self: string[], shape: CorpusShape) => {fence: string, own?: string}|null,
+ *   owners?: (db: object, selves: string[][], shape: CorpusShape) => Promise<Set<string>>}>>}
  */
 export const EVENT_VIEWS = Object.freeze([
     Object.freeze({
@@ -71,6 +74,7 @@ export const EVENT_VIEWS = Object.freeze([
         heading: "Chronology",
         applies: (record) => record.type === "place",
         query: chronologyQuery,
+        owners: chronologyOwners,
     }),
     Object.freeze({
         slug: "events",
@@ -79,6 +83,8 @@ export const EVENT_VIEWS = Object.freeze([
             record.type === "being" ||
             record.type === "affiliation" ||
             (record.type === "lore" && record.subType === "culture"),
+        owners: (db, selves, shape) =>
+            namedOwners(db, selves, "SELECT unnest(who).ref AS ref FROM events", shape.who),
         query: (self, shape) => {
             if (!shape.who) return null;
             const named = `list_filter(e.who, w -> w.ref IN (${literals(self)}))`;
@@ -102,6 +108,13 @@ export const EVENT_VIEWS = Object.freeze([
             record.type === "affiliation" ||
             record.type === "place" ||
             (record.type === "lore" && record.subType === "culture"),
+        owners: (db, selves, shape) =>
+            namedOwners(
+                db,
+                selves,
+                'SELECT account."by" AS ref FROM (SELECT unnest(accounts) AS account FROM events)',
+                shape.accounts,
+            ),
         query: (self, shape) => {
             if (!shape.accounts) return null;
             return {
@@ -122,6 +135,14 @@ export const EVENT_VIEWS = Object.freeze([
         slug: "followed",
         heading: "What followed",
         applies: (record) => Array.isArray(record.data?.events) && record.data.events.length > 0,
+        owners: (db, selves, shape) =>
+            namedOwners(
+                db,
+                selves,
+                "SELECT split_part(edge.event, '#', 1) AS ref " +
+                    "FROM (SELECT unnest(follows) AS edge FROM events)",
+                shape.follows,
+            ),
         query: (self, shape) => {
             if (!shape.follows) return null;
             const edges =
@@ -153,6 +174,96 @@ export const EVENT_VIEWS = Object.freeze([
  * @property {boolean} depth - Some event states `depth`.
  */
 
+/**
+ * Which notes an event names, asked of every note in one query rather than one
+ * query per note: the references the events state are listed once and joined to
+ * every note's Address forms.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase}.
+ * @param {string[][]} selves - Each note's Address, in each form.
+ * @param {string} refs - A query selecting one `ref` per reference an event
+ *   states.
+ * @param {boolean} stated - Whether the corpus states the field `refs` reads.
+ * @returns {Promise<Set<string>>} The first form of each note some event names.
+ */
+async function namedOwners(db, selves, refs, stated) {
+    if (!stated) return new Set();
+    const values = selves
+        .flatMap((forms) => forms.map((form) => `(${literal(forms[0])}, ${literal(form)})`))
+        .join(", ");
+    const { rows } = await db.query(
+        [
+            `WITH selves(root, form) AS (VALUES ${values}),`,
+            `named AS (${refs})`,
+            "SELECT DISTINCT selves.root AS root",
+            "FROM named JOIN selves ON selves.form = named.ref",
+        ].join("\n"),
+    );
+    return new Set(rows.map((row) => String(row.root)));
+}
+
+/** The `reach` clauses felt in the places `here` holds. */
+function chronologyFelt() {
+    return 'list_filter(e."where".reach, r -> list_contains(here.places, r.place))';
+}
+
+/**
+ * The conditions under which an event is one of a place's own rows: it
+ * happened at the place or below it, or it is felt there.
+ *
+ * @param {CorpusShape} shape - What the corpus states.
+ * @returns {string[]} The alternatives, over `e` and `here.places`.
+ */
+function chronologyOwnRows(shape) {
+    return [
+        ...(shape.locus ?
+            ['len(list_filter(e."where".locus, l -> list_contains(here.places, l))) > 0']
+        :   []),
+        ...(shape.reach ? [`len(${chronologyFelt()}) > 0`] : []),
+    ];
+}
+
+/**
+ * Which places have a chronology of their own rows, asked of every place in one
+ * query rather than one query per place.
+ *
+ * The places below each root are walked together, so the walk over `entries`
+ * is paid once for the whole corpus instead of once per place.
+ *
+ * @param {object} db - From {@link module:engine/sql-tables.openNotesDatabase}.
+ * @param {string[][]} selves - Each place's Address, in each form; the `note`
+ *   system's is the first.
+ * @param {CorpusShape} shape - What the corpus states.
+ * @returns {Promise<Set<string>>} The roots with at least one own row.
+ */
+async function chronologyOwners(db, selves, shape) {
+    const values = [...new Set(selves.map((self) => self[0]))]
+        .map((root) => `(${literal(root)})`)
+        .join(", ");
+    const below =
+        shape.parents ?
+            [
+                "WITH RECURSIVE below(root, place) AS (",
+                `    SELECT r, r FROM (VALUES ${values}) AS t(r)`,
+                "    UNION",
+                "    SELECT b.root, lower(p.package || '-note-place-' || p.shortcode)",
+                "    FROM entries p JOIN below b ON list_contains(p.data.parents, b.place)",
+                "    WHERE p.type = 'place'",
+                "),",
+            ]
+        :   [`WITH RECURSIVE below(root, place) AS (SELECT r, r FROM (VALUES ${values}) AS t(r)),`];
+    const { rows } = await db.query(
+        [
+            ...below,
+            "here AS (SELECT root, list(place) AS places FROM below GROUP BY root)",
+            "SELECT DISTINCT here.root AS root",
+            "FROM events e, here",
+            `WHERE ${chronologyOwnRows(shape).join(" OR ")}`,
+        ].join("\n"),
+    );
+    return new Set(rows.map((row) => String(row.root)));
+}
+
 /**
  * A place's chronology: every event that happened at the place or anywhere
  * below it in `parents`, every event felt there — with the clause saying how —
@@ -181,13 +292,8 @@ function chronologyQuery(self, shape) {
                 "),",
             ]
         :   [`WITH RECURSIVE below(place) AS (SELECT ${literal(self[0])}),`];
-    const felt = 'list_filter(e."where".reach, r -> list_contains(here.places, r.place))';
-    const ownRows = [
-        ...(shape.locus ?
-            ['len(list_filter(e."where".locus, l -> list_contains(here.places, l))) > 0']
-        :   []),
-        ...(shape.reach ? [`len(${felt}) > 0`] : []),
-    ];
+    const felt = chronologyFelt();
+    const ownRows = chronologyOwnRows(shape);
     const head = [
         ...below,
         "here AS (SELECT list(place) AS places FROM below)",
@@ -241,7 +347,7 @@ async function corpusShape(db) {
  * @param {object} record - The note's index record.
  * @returns {string[]} The forms, the `note` one first.
  */
-function selfForms(record) {
+export function selfForms(record) {
     const tuple = {
         package: String(record.package),
         type: String(record.type),
@@ -285,6 +391,21 @@ export async function eventViewSections(db, records, fileOf, only) {
     if (!all.some((record) => Array.isArray(record?.data?.events) && record.data.events.length))
         return out;
     const shape = await corpusShape(db);
+    // A view that can say which notes have rows in one query is asked once, over
+    // every note it will be given, and the per-note count is skipped.
+    const owned = new Map();
+    for (const view of EVENT_VIEWS) {
+        if (!view.owners) continue;
+        const selves = [];
+        for (const record of all) {
+            if (!record?.address || record.documents || !record.shortcode) continue;
+            if (only !== undefined && fileOf(record) !== only) continue;
+            if (!view.applies(record) || authoredSection(record, view.slug)) continue;
+            const self = selfForms(record);
+            if (view.query(self, shape)) selves.push(self);
+        }
+        if (selves.length) owned.set(view.slug, await view.owners(db, selves, shape));
+    }
     for (const record of all) {
         if (!record?.address || record.documents || !record.shortcode) continue;
         if (only !== undefined && fileOf(record) !== only) continue;
@@ -294,10 +415,14 @@ export async function eventViewSections(db, records, fileOf, only) {
             if (!view.applies(record) || authoredSection(record, view.slug)) continue;
             const query = view.query(self, shape);
             if (!query) continue;
-            const { rows } = await db.query(
-                `SELECT count(*) AS n FROM (${query.own ?? query.fence})`,
-            );
-            if (Number(rows[0]?.n ?? 0) > 0) sections.set(view.slug, section(view, query.fence));
+            const has =
+                owned.has(view.slug) ?
+                    owned.get(view.slug).has(self[0])
+                :   Number(
+                        (await db.query(`SELECT count(*) AS n FROM (${query.own ?? query.fence})`))
+                            .rows[0]?.n ?? 0,
+                    ) > 0;
+            if (has) sections.set(view.slug, section(view, query.fence));
         }
         if (sections.size) out.set(fileOf(record), sections);
     }

package/engine/exported-scene.mjs

@@ -1,10 +1,21 @@
 /*
+ * 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
  */
 
 /** Preserve an exported Foundry Scene while binding marked pins to note pages. */
 
 import { journalPageId, splitPages } from "./journals.mjs";
+import { dataFields } from "./note-vocabulary.mjs";
+import { isAddressTuple, renderAddress } from "./address.mjs";
 
 const EMBEDDED = Object.freeze([
     "drawings",
@@ -96,38 +107,90 @@ function fixupTarget(scene, path) {
     return { parent: current, key: last.key };
 }
 
-/** Apply author-declared asset address replacements to an exported Scene. */
-function applyFixups(scene, fixups, resolveAddress) {
-    if (fixups === undefined) return;
-    if (!Array.isArray(fixups)) throw new Error("`data.fixup` must be an array");
-    for (const [index, fixup] of fixups.entries()) {
-        if (
-            !fixup ||
-            typeof fixup !== "object" ||
-            Array.isArray(fixup) ||
-            fixup.type !== "address" ||
-            typeof fixup.value !== "string" ||
-            !fixup.value
-        ) {
+/**
+ * Every fixup a map note states, each with the key it was authored at.
+ *
+ * Two sources, applied by one mechanism. `data.fixup` names its Scene paths
+ * outright. A map field declaring a `sceneProperty` — `thumbnail`, written into
+ * `.thumb` — names the Scene property in the vocabulary instead, so the note
+ * states only the Address and the compile adds the entry. A declared field and
+ * an authored entry writing one property is refused: either would silently
+ * overwrite the other.
+ *
+ * @param {object} fm - The map note's frontmatter.
+ * @returns {Array<{label: string, fixup: unknown}>} The fixups, authored first.
+ * @throws {Error} When `data.fixup` is not a list, or two fixups write one path.
+ */
+function noteFixups(fm) {
+    const authored = fm.data?.fixup;
+    if (authored !== undefined && !Array.isArray(authored)) {
+        throw new Error("`data.fixup` must be an array");
+    }
+    const out = (authored ?? []).map((fixup, index) => ({ label: `data.fixup[${index}]`, fixup }));
+    for (const field of dataFields("map") ?? []) {
+        if (!field.sceneProperty) continue;
+        const value = fm.data?.[field.name];
+        if (value === undefined || value === null || value === "") continue;
+        const label = `data.${field.name}`;
+        const clash = out.find(({ fixup }) => fixup?.path === field.sceneProperty);
+        if (clash) {
             throw new Error(
-                `data.fixup[${index}] needs path, type: address, and an asset address value`,
+                `\`${label}\` and \`${clash.label}\` both write \`${field.sceneProperty}\`; ` +
+                    `keep one of them`,
             );
         }
-        const { parent, key } = fixupTarget(scene, fixup.path);
-        if (typeof parent[key] !== "string" && parent[key] !== null) {
-            throw new Error(`Scene fixup path "${fixup.path}" must name a string asset field`);
-        }
-        if (typeof resolveAddress !== "function") {
-            throw new Error("Scene address fixups need an asset resolver");
-        }
-        const resolved = resolveAddress(fixup.value);
-        if (typeof resolved !== "string" || !resolved) {
-            throw new Error(`Scene fixup address "${fixup.value}" does not resolve to an asset`);
+        out.push({
+            label,
+            fixup: {
+                path: field.sceneProperty,
+                type: "address",
+                value: isAddressTuple(value) ? renderAddress(value) : value,
+            },
+        });
+    }
+    return out;
+}
+
+/** Apply a map note's asset address replacements to its exported Scene. */
+function applyFixups(scene, fixups, resolveAddress) {
+    for (const { label, fixup } of fixups) {
+        try {
+            applyFixup(scene, label, fixup, resolveAddress);
+        } catch (error) {
+            // An entry the compile added says which key the note wrote, since
+            // the path it failed on appears nowhere in the note.
+            if (label.startsWith("data.fixup[")) throw error;
+            throw new Error(`\`${label}\`: ${error.message}`, { cause: error });
         }
-        parent[key] = resolved;
     }
 }
 
+/** Resolve one fixup's Address and write its path into the Scene. */
+function applyFixup(scene, label, fixup, resolveAddress) {
+    if (
+        !fixup ||
+        typeof fixup !== "object" ||
+        Array.isArray(fixup) ||
+        fixup.type !== "address" ||
+        typeof fixup.value !== "string" ||
+        !fixup.value
+    ) {
+        throw new Error(`${label} needs path, type: address, and an asset address value`);
+    }
+    const { parent, key } = fixupTarget(scene, fixup.path);
+    if (typeof parent[key] !== "string" && parent[key] !== null) {
+        throw new Error(`Scene fixup path "${fixup.path}" must name a string asset field`);
+    }
+    if (typeof resolveAddress !== "function") {
+        throw new Error("Scene address fixups need an asset resolver");
+    }
+    const resolved = resolveAddress(fixup.value);
+    if (typeof resolved !== "string" || !resolved) {
+        throw new Error(`Scene fixup address "${fixup.value}" does not resolve to an asset`);
+    }
+    parent[key] = resolved;
+}
+
 /**
  * Add a compendium key to every embedded document that carries an `_id`.
  *
@@ -156,8 +219,9 @@ function keyDocuments(docs, collection, parentIds, sceneId) {
  * Compile a Foundry Scene export into a pack document.
  *
  * The Scene passes through as exported. Only the note-derived Scene ID,
- * compendium metadata, `data.fixup` and pins marked `#anchor` change; nothing
- * else inside the Scene is read or checked.
+ * compendium metadata, the fixups — `data.fixup` and the map fields that
+ * declare a Scene property, such as `data.thumbnail` — and pins marked
+ * `#anchor` change; nothing else inside the Scene is read or checked.
  *
  * @param {object} fm - The map note's frontmatter.
  * @param {string} markdown - Its converted Markdown body.
@@ -175,7 +239,7 @@ export function buildExportedScene(fm, markdown, { journalEntryId, stats, resolv
         throw new Error("a map note needs a derived 16-character Scene ID");
     }
     const scene = structuredClone(source);
-    applyFixups(scene, fm.data?.fixup, resolveAddress);
+    applyFixups(scene, noteFixups(fm), resolveAddress);
     scene._id = fm.id;
     scene._key = `!scenes!${fm.id}`;
     if (stats) scene._stats = stats;

package/engine/extension-attributes.mjs

@@ -1,4 +1,15 @@
-/* SPDX-License-Identifier: GPL-3.0-or-later */
+/*
+ * 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
+ */
 
 /**
  * A name an id, a class or an attribute key may carry.