@heroiclands/package-build 22.21.0 → 22.23.0

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;
+}

package/engine/asset-types.mjs

@@ -46,6 +46,8 @@
  * @module
  */
 
+import fs from "node:fs";
+
 import { ADDRESS_SEGMENT_PATTERN } from "./address-charset.mjs";
 
 /**
@@ -190,3 +192,241 @@ export function assetTypeOfRoot(root) {
 export function isAssetShortcode(shortcode) {
     return typeof shortcode === "string" && ADDRESS_SEGMENT_PATTERN.test(shortcode);
 }
+
+/**
+ * The PNG (and APNG, which shares the signature) header.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function pngDimensions(bytes) {
+    if (bytes.length < 24) return undefined;
+    if (bytes.toString("hex", 0, 8) !== "89504e470d0a1a0a") return undefined;
+    return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+/**
+ * The GIF header's logical screen size.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function gifDimensions(bytes) {
+    if (bytes.length < 10) return undefined;
+    const signature = bytes.toString("ascii", 0, 6);
+    if (signature !== "GIF87a" && signature !== "GIF89a") return undefined;
+    return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+}
+
+/**
+ * The BMP header's size, carried as a signed value so a bottom-up bitmap's
+ * negative height still reads as a pixel count.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function bmpDimensions(bytes) {
+    if (bytes.length < 26) return undefined;
+    if (bytes.toString("ascii", 0, 2) !== "BM") return undefined;
+    return {
+        width: Math.abs(bytes.readInt32LE(18)),
+        height: Math.abs(bytes.readInt32LE(22)),
+    };
+}
+
+/**
+ * The size a JPEG's first SOF (start-of-frame) segment states, found by
+ * walking its markers rather than assuming a fixed offset — a JPEG carries an
+ * arbitrary run of metadata segments before the frame header.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function jpegDimensions(bytes) {
+    if (bytes.length < 4 || bytes.readUInt16BE(0) !== 0xffd8) return undefined;
+    let pos = 2;
+    while (pos + 1 < bytes.length) {
+        if (bytes[pos] !== 0xff) return undefined;
+        const marker = bytes[pos + 1];
+        pos += 2;
+        // TEM and the restart markers carry no segment length; EOI ends the
+        // stream with no frame header found.
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+        if (marker === 0xd9) return undefined;
+        if (pos + 2 > bytes.length) return undefined;
+        const length = bytes.readUInt16BE(pos);
+        const isStartOfFrame =
+            marker >= 0xc0 &&
+            marker <= 0xcf &&
+            marker !== 0xc4 &&
+            marker !== 0xc8 &&
+            marker !== 0xcc;
+        if (isStartOfFrame) {
+            if (pos + 7 > bytes.length) return undefined;
+            return { height: bytes.readUInt16BE(pos + 3), width: bytes.readUInt16BE(pos + 5) };
+        }
+        pos += length;
+    }
+    return undefined;
+}
+
+/**
+ * A WebP file's size, read from whichever of the three chunk layouts the
+ * format defines — the plain lossy frame, the lossless bitstream, or the
+ * extended header a file with alpha, animation or metadata carries instead.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function webpDimensions(bytes) {
+    if (bytes.length < 30) return undefined;
+    if (bytes.toString("ascii", 0, 4) !== "RIFF" || bytes.toString("ascii", 8, 12) !== "WEBP") {
+        return undefined;
+    }
+    const chunk = bytes.toString("ascii", 12, 16);
+    if (chunk === "VP8 ") {
+        return {
+            width: bytes.readUInt16LE(26) & 0x3fff,
+            height: bytes.readUInt16LE(28) & 0x3fff,
+        };
+    }
+    if (chunk === "VP8L") {
+        const bits = bytes.readUInt32LE(21);
+        return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+    }
+    if (chunk === "VP8X") {
+        return {
+            width: (bytes[24] | (bytes[25] << 8) | (bytes[26] << 16)) + 1,
+            height: (bytes[27] | (bytes[28] << 8) | (bytes[29] << 16)) + 1,
+        };
+    }
+    return undefined;
+}
+
+/**
+ * A TIFF's `ImageWidth`/`ImageLength` tags, read from its first IFD in
+ * whichever byte order the file's own header declares.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function tiffDimensions(bytes) {
+    if (bytes.length < 8) return undefined;
+    const order = bytes.toString("ascii", 0, 2);
+    let little;
+    if (order === "II") little = true;
+    else if (order === "MM") little = false;
+    else return undefined;
+    const u16 = (offset) => (little ? bytes.readUInt16LE(offset) : bytes.readUInt16BE(offset));
+    const u32 = (offset) => (little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset));
+    if (u16(2) !== 42) return undefined;
+    const ifd = u32(4);
+    if (ifd + 2 > bytes.length) return undefined;
+    const entryCount = u16(ifd);
+    let width;
+    let height;
+    for (let i = 0; i < entryCount && (width === undefined || height === undefined); i++) {
+        const entry = ifd + 2 + i * 12;
+        if (entry + 12 > bytes.length) break;
+        const tag = u16(entry);
+        if (tag !== 256 && tag !== 257) continue;
+        // SHORT (type 3) values sit in the first two bytes of the value
+        // field; LONG (type 4) occupies all four, so only the width in that
+        // field differs by type.
+        const type = u16(entry + 2);
+        const value = type === 3 ? u16(entry + 8) : u32(entry + 8);
+        if (tag === 256) width = value;
+        else height = value;
+    }
+    return width !== undefined && height !== undefined ? { width, height } : undefined;
+}
+
+/**
+ * An AVIF's declared size, read from the first `ispe` (Image Spatial
+ * Extents) property its ISOBMFF container carries, by walking box headers
+ * down through `meta` → `iprp` → `ipco` rather than assuming a fixed layout.
+ *
+ * @param {Buffer} bytes
+ * @returns {{width: number, height: number}|undefined}
+ */
+function avifDimensions(bytes) {
+    /** @type {{width: number, height: number}|undefined} */
+    let found;
+    const walk = (start, end) => {
+        let pos = start;
+        while (!found && pos + 8 <= end) {
+            const size = bytes.readUInt32BE(pos);
+            if (size < 8) return;
+            const type = bytes.toString("ascii", pos + 4, pos + 8);
+            const dataStart = pos + 8;
+            const dataEnd = Math.min(pos + size, end);
+            if (type === "meta") {
+                // `meta` is a full box: four bytes of version and flags
+                // precede its own nested boxes.
+                walk(dataStart + 4, dataEnd);
+            } else if (type === "iprp" || type === "ipco") {
+                walk(dataStart, dataEnd);
+            } else if (type === "ispe" && dataEnd - dataStart >= 12) {
+                found = {
+                    width: bytes.readUInt32BE(dataStart + 4),
+                    height: bytes.readUInt32BE(dataStart + 8),
+                };
+            }
+            pos += size;
+        }
+    };
+    walk(0, bytes.length);
+    return found;
+}
+
+/**
+ * The pixel dimensions a raster image's own header states.
+ *
+ * Read from the file's bytes directly rather than through a decoder, so a
+ * corrupt or partial file fails closed — the same `undefined` answer as a
+ * format this carries no reader for — instead of throwing out of the asset
+ * walk. An SVG has no pixel dimensions to read; stating one would be a
+ * fabricated viewBox reading rather than a fact about the file.
+ *
+ * @param {string} absPath - The file's absolute path.
+ * @param {string} ext - Its extension, lowercase and dot-led.
+ * @returns {{width: number, height: number}|undefined} The declared size, or
+ *   `undefined` when the format carries none, or the header cannot be read.
+ */
+export function imageDimensions(absPath, ext) {
+    if (ext === ".svg") return undefined;
+    const reader = IMAGE_DIMENSION_READERS[ext];
+    if (!reader) return undefined;
+    let bytes;
+    try {
+        bytes = fs.readFileSync(absPath);
+    } catch {
+        return undefined;
+    }
+    try {
+        return reader(bytes);
+    } catch {
+        // A header this short or this malformed to parse is the same answer
+        // as one this reads no format for: the dimensions stay blank.
+        return undefined;
+    }
+}
+
+/**
+ * The dimension reader for each raster extension {@link IMAGE_EXTENSIONS}
+ * declares, `.svg` excepted — it has no pixel dimensions, handled above
+ * rather than entered here.
+ *
+ * @type {Readonly<Record<string, (bytes: Buffer) => ({width: number, height: number}|undefined)>>}
+ */
+const IMAGE_DIMENSION_READERS = Object.freeze({
+    ".png": pngDimensions,
+    ".apng": pngDimensions,
+    ".gif": gifDimensions,
+    ".bmp": bmpDimensions,
+    ".jpg": jpegDimensions,
+    ".jpeg": jpegDimensions,
+    ".webp": webpDimensions,
+    ".tiff": tiffDimensions,
+    ".avif": avifDimensions,
+});