@heroiclands/package-build 22.22.0 → 22.23.0

package/engine/art-fields.mjs

@@ -44,6 +44,8 @@
  * @module
  */
 
+import path from "node:path";
+
 import { encodeAddresses } from "./address-values.mjs";
 import { ASSET_SYSTEM, isAssetType } from "./asset-types.mjs";
 import { ASSETS_SEGMENT } from "./pathnames.mjs";
@@ -129,9 +131,49 @@ export function assetAddressIndex(records = [], { config, foreign, types = [] }
                 .filter(([key]) => key),
         ),
         foreign: foreign?.index ?? new Map(),
+        // Foreign first, local last: a renderer sizing a picture looks it up
+        // by the pathname the record resolved to, never by address, and a
+        // local record is entered after a foreign one so it wins the lookup on
+        // the collision neither should ever cause.
+        byPath: assetImageInfoByPathname([
+            ...(foreign?.index?.values() ?? []),
+            ...records.filter(isAssetRecord),
+        ]),
     };
 }
 
+/**
+ * What a renderer needs to size one picture, keyed by the pathname its
+ * address resolves to.
+ *
+ * An image reaches a renderer as the resolved pathname an embed or an authored
+ * body image already carries — see {@link readAssetAddress} — never as the
+ * address that produced it, so the lookup a renderer wants is by pathname, not
+ * by {@link assetAddressIndex}'s own `assets` map.
+ *
+ * @param {readonly object[]} records - Asset records, local or foreign.
+ * @returns {Map<string, {type: string, role?: string, width: number|"", height: number|""}>}
+ *   One entry per addressable file, carrying only what a renderer sizes a
+ *   picture from. `role` is omitted when the record states none; `width` and
+ *   `height` are always present, blank (`""`) for a vector — the record's own
+ *   convention, carried through rather than collapsed into an absence a
+ *   renderer could not tell apart from "no asset resolved at all".
+ */
+export function assetImageInfoByPathname(records = []) {
+    const map = new Map();
+    for (const record of records) {
+        if (!record?.asset?.path || !record.package) continue;
+        const key = `${record.package}/${ASSETS_SEGMENT}/${record.asset.path}`;
+        map.set(key, {
+            type: record.type,
+            role: record.asset.role || undefined,
+            width: typeof record.asset.width === "number" ? record.asset.width : "",
+            height: typeof record.asset.height === "number" ? record.asset.height : "",
+        });
+    }
+    return map;
+}
+
 /**
  * The asset one authored value names, or why it names none.
  *
@@ -200,6 +242,82 @@ export function resolveArtRecord(index, value, defaultType, accepts) {
     return readAssetAddress(index, value, defaultType, accepts).record;
 }
 
+/**
+ * Every asset's role, keyed by the pathname it resolves to — the form a body
+ * carries once an embed's address has been rewritten into the ordinary image
+ * every surface renders ({@link module:engine/content-embeds.resolveEmbeds}).
+ *
+ * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` —
+ * for a caller that reads a body after that rewrite: a Foundry journal, an
+ * item or actor's documentation, and the book.
+ *
+ * @param {object} index - From {@link module:engine/wikilinks.buildWikilinkIndex},
+ *   or the equivalent the site and the book build.
+ * @returns {Map<string, string>} Pathname → role, one entry per asset that
+ *   declares one.
+ */
+export function pathnameRoles(index) {
+    const roles = new Map();
+    for (const record of [
+        ...(index?.assets?.values() ?? []),
+        ...(index?.foreign?.values() ?? []),
+    ]) {
+        const role = record?.asset?.role;
+        if (!role || !record.asset?.path || !record.package) continue;
+        roles.set(`${record.package}/${ASSETS_SEGMENT}/${record.asset.path}`, role);
+    }
+    return roles;
+}
+
+/**
+ * Flag a note whose art slot names a picture that is not the size that slot
+ * is cut to.
+ *
+ * The size is stated by the slot itself, in
+ * {@link module:engine/art-slots.ART_SLOTS}, so it is written once and a slot
+ * that states none asks nothing of the picture it names. Today the hero image
+ * is the one slot with a fixed strip to fill; a picture written in prose is
+ * fitted to the room it has and is never measured here.
+ *
+ * A vector carries no pixel size to compare, and neither does a raster whose
+ * header cannot be read; neither is flagged.
+ *
+ * @param {readonly object[]} records - The corpus, notes and assets together.
+ * @param {object} [opts]
+ * @param {object} [opts.config] - The resolved build configuration.
+ * @param {string} [opts.assetsBase] - Where the asset roots sit, so a finding
+ *   names the file from the working directory as every other finding does.
+ * @returns {object[]} A finding per picture off its slot's size,
+ *   `severity: "error"`.
+ */
+export function checkArtSlotSizes(records = [], { config, assetsBase = "" } = {}) {
+    const sized = ART_SLOTS.filter((slot) => slot.size);
+    if (!sized.length) return [];
+    const index = assetAddressIndex(records, { config });
+    const findings = [];
+    for (const record of records) {
+        const data = record?.data;
+        if (!data) continue;
+        for (const slot of sized) {
+            const value = data[slot.key];
+            if (!value) continue;
+            const asset = resolveArtRecord(index, value, slot.type, slot.accepts);
+            const { path: file, width, height } = asset?.asset ?? {};
+            if (!file || !width || !height) continue;
+            if (Number(width) === slot.size.width && Number(height) === slot.size.height) continue;
+            findings.push({
+                file: path.join(assetsBase, file),
+                severity: "error",
+                message:
+                    `${width}×${height} is not the ${slot.size.width}×${slot.size.height} ` +
+                    `a \`${slot.key}\` is cut to`,
+            });
+        }
+    }
+    return findings;
+}
+
 /**
  * The pathname an art value names, in the form an authored one takes.
  *

package/engine/art-slots.mjs

@@ -76,6 +76,12 @@ export const ART_SLOTS = Object.freeze([
         type: "image",
         accepts: ART_TYPES,
         document: false,
-        describe: "The page's hero image. Reaches no compiled document.",
+        // A hero image fills one fixed strip wherever it is drawn, so every
+        // banner is cut to one size and a picture of another size is resized
+        // to it. A picture written in prose fills no fixed strip and is
+        // fitted to whatever room it has, so no slot but this one states a
+        // size.
+        size: Object.freeze({ width: 1792, height: 768 }),
+        describe: "The page's hero image, cut to 1792×768. Reaches no compiled document.",
     }),
 ]);

package/engine/asset-index.mjs

@@ -50,6 +50,13 @@
  * drop: `licence` beside `license` is otherwise an attribution record that looks
  * complete and carries nothing.
  *
+ * **`role` names what the picture is for**, from a closed set, and belongs to
+ * the `image` type only — an `icon` address carries one nominal size per medium
+ * whatever the file holds, so a `role` declared there is a finding and is
+ * dropped rather than carried through. **`width` and `height` come from the
+ * walk itself**, read from the file's own header rather than declared, and are
+ * blank for an SVG, which has no pixel dimensions to state.
+ *
  * @module
  */
 
@@ -60,7 +67,18 @@ import YAML from "yaml";
 
 import { canonicalKey } from "./content-address.mjs";
 import { positionOfYamlPath } from "./diagnostics.mjs";
-import { ASSET_SYSTEM, ASSET_TYPES, isAssetShortcode } from "./asset-types.mjs";
+import { ASSET_SYSTEM, ASSET_TYPES, imageDimensions, isAssetShortcode } from "./asset-types.mjs";
+
+/**
+ * The closed set of roles a picture may declare.
+ *
+ * Shared with the field declaration below and with every medium that sizes a
+ * picture by its role, so the vocabulary cannot drift between the record that
+ * carries it and the renderer that reads it.
+ *
+ * @type {readonly string[]}
+ */
+export const ASSET_ROLES = Object.freeze(["portrait", "emblem", "banner", "plate", "map"]);
 
 /**
  * The file a directory records provenance for its subtree in.
@@ -92,6 +110,18 @@ export const PROVENANCE_SIDECAR_SUFFIX = ".yaml";
  *   state this key. Omitting one is a finding rather than a blank, because a
  *   record resolves wholesale: the nearest one is the whole answer, so a key it
  *   leaves out is not inherited from above but simply absent.
+ * @property {"boolean"|"integer"} [type] - The value's own type, for a field
+ *   whose answer is not a string. Omitted for every string field; `ai` carries
+ *   the YAML boolean itself rather than a stringified copy, and `width` and
+ *   `height` carry the pixel count the walk measured. Each is refused rather
+ *   than coerced when the value does not match.
+ * @property {readonly string[]} [values] - The closed set a provenance
+ *   declaration must choose one of; a value outside it is a finding and the
+ *   key is left blank, the same treatment an `ai` value of the wrong shape
+ *   gets. `role` is the one field that carries it.
+ * @property {string} [onlyType] - The one asset type this field may be
+ *   declared for. A provenance record stating it for another type is a
+ *   finding, and the value is dropped rather than carried through.
  * @property {string} describe - One line, for the author-facing reference.
  */
 
@@ -134,7 +164,10 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "ai",
         from: "provenance",
-        describe: "Whether the file is machine-generated — `true` or `false`.",
+        type: "boolean",
+        describe:
+            "Whether the file is machine-generated — the YAML boolean `true` " +
+            "or `false`, never a string.",
     }),
     Object.freeze({
         name: "license",
@@ -147,6 +180,32 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
         from: "provenance",
         describe: "Anything else a person reading the attribution needs.",
     }),
+    Object.freeze({
+        name: "role",
+        from: "provenance",
+        onlyType: "image",
+        values: ASSET_ROLES,
+        describe:
+            "What the picture is for — portrait, emblem, banner, plate or map. " +
+            "Absent for an ordinary picture, and refused outside that set. " +
+            "The `image` type only; a value on an `icon` address is a finding.",
+    }),
+    Object.freeze({
+        name: "width",
+        from: "walk",
+        type: "integer",
+        describe:
+            "The file's pixel width, read from its own header during the " +
+            "asset walk. Blank for an SVG, which has no pixel dimensions.",
+    }),
+    Object.freeze({
+        name: "height",
+        from: "walk",
+        type: "integer",
+        describe:
+            "The file's pixel height, read from its own header during the " +
+            "asset walk. Blank for an SVG, which has no pixel dimensions.",
+    }),
 ]);
 
 /**
@@ -181,12 +240,30 @@ export const REQUIRED_PROVENANCE_KEYS = Object.freeze(
     ),
 );
 
+/**
+ * The provenance field declaring each key, by name.
+ *
+ * Read in the parsing loop below to ask whether a key has its own `type`
+ * rather than the ordinary string one — derived from {@link ASSET_RECORD_FIELDS}
+ * for the same reason {@link PROVENANCE_KEYS} is, so the field declaration
+ * stays the one place a key's shape is stated.
+ *
+ * @type {ReadonlyMap<string, AssetRecordField>}
+ */
+const PROVENANCE_FIELD_BY_KEY = new Map(
+    ASSET_RECORD_FIELDS.filter((field) => field.from === "provenance").map((field) => [
+        field.name,
+        field,
+    ]),
+);
+
 /**
  * Read one provenance file, reporting every key that is not a provenance key.
  *
  * @param {string} file - The provenance file.
  * @param {object[]} findings - Collects a diagnostic per unknown key.
- * @returns {Record<string, string>} The recognised keys, as strings.
+ * @returns {Record<string, string|boolean>} The recognised keys — a string for
+ *   every field but `ai`, which carries the YAML boolean itself.
  */
 function readProvenanceFile(file, findings) {
     let text;
@@ -238,6 +315,44 @@ function readProvenanceFile(file, findings) {
             });
             continue;
         }
+        const field = PROVENANCE_FIELD_BY_KEY.get(key);
+        if (field?.type === "boolean") {
+            if (typeof value === "boolean") {
+                out[key] = value;
+            } else {
+                // Distinct from the unknown-key finding above: this key is
+                // recognised, and the problem is the shape of its value — a
+                // quoted `"false"` or a YAML `yes`/`1` would otherwise be
+                // stringified and read as truthy regardless of which it was.
+                findings.push({
+                    file,
+                    ...positionOfYamlPath(text, [key], { key: true }),
+                    severity: "error",
+                    message:
+                        `\`${key}\` must be the YAML boolean \`true\` or \`false\`, ` +
+                        `not ${JSON.stringify(value)}`,
+                });
+            }
+            continue;
+        }
+        if (field?.values) {
+            if (field.values.includes(value)) {
+                out[key] = value;
+            } else {
+                // Distinct from the unknown-key finding above: this key is
+                // recognised, and the problem is that its value is not one of
+                // the closed set it accepts.
+                findings.push({
+                    file,
+                    ...positionOfYamlPath(text, [key], { key: true }),
+                    severity: "error",
+                    message:
+                        `\`${key}\` must be one of ${field.values.join(", ")}, ` +
+                        `not ${JSON.stringify(value)}`,
+                });
+            }
+            continue;
+        }
         out[key] = value == null ? "" : String(value);
     }
 
@@ -299,15 +414,30 @@ function inheritedProvenance(dir, root, cache, findings) {
 /**
  * The `asset` block for one file.
  *
- * @param {string} relPath - The file's path below the package's asset directory.
- * @param {Record<string, string>|null} provenance - The resolved record.
- * @returns {Record<string, string>} The block, every field present.
+ * @param {Record<string, unknown>} walkValues - Every `from: "walk"` field's
+ *   value, keyed by field name.
+ * @param {Record<string, string|boolean>|null} provenance - The resolved record.
+ * @param {string} type - The asset type this file was walked as, so a field
+ *   declaring `onlyType` can be dropped for every other type.
+ * @returns {Record<string, string|boolean|number>} The block, every field
+ *   present — blank (`""`) for a string or integer field nothing states,
+ *   `false` for `ai`.
  */
-function assetBlock(relPath, provenance) {
+function assetBlock(walkValues, provenance, type) {
     const block = {};
     for (const field of ASSET_RECORD_FIELDS) {
-        const value = field.from === "walk" ? relPath : provenance?.[field.name];
-        block[field.name] = typeof value === "string" ? value : "";
+        if (field.onlyType && field.onlyType !== type) {
+            block[field.name] = field.type === "boolean" ? false : "";
+            continue;
+        }
+        const value = field.from === "walk" ? walkValues[field.name] : provenance?.[field.name];
+        if (field.type === "boolean") {
+            block[field.name] = typeof value === "boolean" ? value : false;
+        } else if (field.type === "integer") {
+            block[field.name] = typeof value === "number" ? value : "";
+        } else {
+            block[field.name] = typeof value === "string" ? value : "";
+        }
     }
     return block;
 }
@@ -418,6 +548,18 @@ export function collectAssetRecords(assetsBase, { contentPackage, problems }) {
                     // ancestor walk is not consulted when one is present.
                 :   inheritedProvenance(path.dirname(absPath), rootDir, cache, findings);
 
+            for (const field of ASSET_RECORD_FIELDS) {
+                if (field.onlyType && field.onlyType !== type && provenance?.[field.name]) {
+                    report(
+                        absPath,
+                        `\`${field.name}\` only applies to the \`${field.onlyType}\` type, ` +
+                            `and this address is \`${type}\` — the declaration is dropped`,
+                    );
+                }
+            }
+
+            const dimensions = imageDimensions(absPath, path.extname(absPath).toLowerCase());
+
             records.push({
                 package: contentPackage,
                 type,
@@ -427,7 +569,15 @@ export function collectAssetRecords(assetsBase, { contentPackage, problems }) {
                 address: {
                     canonical: canonicalKey(contentPackage, ASSET_SYSTEM, type, shortcode),
                 },
-                asset: assetBlock(`${root}/${relPath}`, provenance),
+                asset: assetBlock(
+                    {
+                        path: `${root}/${relPath}`,
+                        width: dimensions?.width,
+                        height: dimensions?.height,
+                    },
+                    provenance,
+                    type,
+                ),
             });
         }
     }

package/engine/asset-replacement.mjs

@@ -0,0 +1,93 @@
+/*
+ * 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 declared replacement package's asset record, picked over the local one,
+ * by address.
+ *
+ * A package may declare, on a `relationships.<kind>[]` entry, that a
+ * dependency's asset tree answers its own asset addresses —
+ * `assetReplacement: true` in `package-build.config.yaml`:
+ *
+ * ```yaml
+ * relationships:
+ *     requires:
+ *         - id: thalornaaltart
+ *           manifest: https://…/releases/latest/download/module.json
+ *           assetReplacement: true
+ *           contentIndex: true
+ * ```
+ *
+ * `assetReplacement: true` opts that relationship in. `resolveAssetReplacement`
+ * is what turns the declaration into an answer, one address at a time, against
+ * four rules:
+ *
+ * 1. **Scoped to asset types.** A non-asset address, or one whose package
+ *    segment is not the compiling package's own, resolves to `null` at once —
+ *    tested with {@link module:engine/asset-types.isAssetType} rather than
+ *    reimplemented. A being, an item or a lore note is never replaced this
+ *    way.
+ * 2. **Ordered, single pass.** Replacements are tried in declaration order —
+ *    the order their relationships appear in `package-build.config.yaml` —
+ *    and the first one carrying the address wins.
+ * 3. **Never recursive.** A replacement's own output address is not itself
+ *    looked up against another replacement: resolving
+ *    `thalornaaltart-none-image-thorn` never asks whether something replaces
+ *    `thalornaaltart`. This forecloses a cycle by construction — there is
+ *    nothing to loop.
+ * 4. **A miss falls through.** `null` means no declared replacement carries
+ *    the address, and the caller falls back to the local address exactly as
+ *    it does today. This function never decides that a missing replacement is
+ *    an error; a caller that wants that is free to build it on the answer.
+ *
+ * This resolver answers a different question from
+ * {@link module:engine/asset-bindings.checkForeignAssetBindings}: that check
+ * validates an art module's own staged files against another package's
+ * addresses, at that module's own build time. This one runs at the *replaced*
+ * package's build, consulted by its book, and asks whether a declared
+ * replacement carries an address this package would otherwise answer itself.
+ *
+ * @module
+ */
+
+import { isAssetType } from "./asset-types.mjs";
+import { canonicalKey, readCanonicalKey } from "./content-address.mjs";
+
+/**
+ * The replacement record for one asset address, or `null`.
+ *
+ * @param {string} address - A canonical asset address.
+ * @param {object} opts
+ * @param {string} opts.localPackage - The compiling package's own segment.
+ * @param {readonly string[]} opts.replacements - The package segments of
+ *   every relationship declaring `assetReplacement: true`, in declaration
+ *   order.
+ * @param {Map<string, object>} opts.index - The merged content index, keyed
+ *   by canonical address.
+ * @returns {{record: object, package: string}|null} The first replacement
+ *   carrying the address, or `null` when none does.
+ */
+export function resolveAssetReplacement(address, { localPackage, replacements, index }) {
+    const parts = readCanonicalKey(address);
+    if (!parts) return null;
+    if (!isAssetType(parts.type)) return null;
+    if (parts.package !== localPackage) return null;
+    for (const replacementPackage of replacements ?? []) {
+        const key = canonicalKey(replacementPackage, parts.system, parts.type, parts.shortcode);
+        const record = index?.get(key);
+        if (record?.asset?.path && record.package) {
+            return { record, package: replacementPackage };
+        }
+    }
+    return null;
+}