@heroiclands/package-build 23.4.1 → 23.5.0

package/engine/asset-index.mjs

@@ -27,12 +27,13 @@
  * slug. A reader tells the two shapes apart by the `asset` block, which is what
  * {@link module:engine/index-records.isAssetRecord} asks.
  *
- * **`path` is what makes resolution one step.** The record is emitted by the
- * package holding the bytes, so its path is that package's path — relative to
- * that package's `assets/` directory — and each consumer joins its own root onto
- * it. Foundry prefixes `<kind>/<foundry id>/assets/`, the website its CDN prefix
- * for the package, the book the asset base it was configured with. Nothing has
- * to be looked up a second time.
+ * **`path` is the source path.** The record is emitted by the package holding
+ * the bytes, so its path is that package's path — relative to that package's
+ * `assets/` directory — and names where the file sits in the repository. The
+ * book stages from it. Foundry and the website serve the **deployed** layout
+ * instead, `<icons|images>/<basename>`, which follows from the same path by
+ * dropping the directories between the type root and the file — see
+ * {@link module:engine/asset-shipping}.
  *
  * **Provenance resolves per address**, and the rule is stated rather than
  * inferred from a directory:
@@ -43,8 +44,14 @@
  *    sidecar exists precisely because that answer is wrong for this one file.
  * 2. Otherwise the nearest `provenance.yaml`, searching the file's own directory
  *    and then its ancestors, stopping at the type root.
- * 3. Otherwise nothing, and the record's provenance fields are blank. A package
- *    that records no attribution is a fact to state, not a walk to fail.
+ * 3. Otherwise nothing — and a file no record covers is a **finding** at the
+ *    file. Every asset states who holds its rights, the terms it is used under
+ *    and whether it is machine-generated, because the stage decides from those
+ *    three answers whether the file ships.
+ *
+ * Resolution is **per file**, never per folder. One directory routinely holds
+ * files covered by its own `provenance.yaml` beside files a sidecar answers for,
+ * so nothing reads one file's answer as its neighbour's.
  *
  * An unknown key in a provenance file is a **finding** rather than a silent
  * drop: `licence` beside `license` is otherwise an attribution record that looks
@@ -66,7 +73,7 @@ import path from "node:path";
 import YAML from "yaml";
 
 import { canonicalKey } from "./content-address.mjs";
-import { positionOfYamlPath } from "./diagnostics.mjs";
+import { formatDiagnostic, positionOfYamlPath } from "./diagnostics.mjs";
 import { ASSET_SYSTEM, ASSET_TYPES, imageDimensions, isAssetShortcode } from "./asset-types.mjs";
 
 /**
@@ -164,10 +171,12 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "ai",
         from: "provenance",
+        required: true,
         type: "boolean",
         describe:
             "Whether the file is machine-generated — the YAML boolean `true` " +
-            "or `false`, never a string.",
+            "or `false`, never a string. Required: a record that does not say " +
+            "is a finding, never read as `false`.",
     }),
     Object.freeze({
         name: "license",
@@ -257,6 +266,17 @@ const PROVENANCE_FIELD_BY_KEY = new Map(
     ]),
 );
 
+/**
+ * What a file carries when its record omits a required key, by key.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+const MISSING_KEY_CONSEQUENCE = Object.freeze({
+    attribution: "no attribution",
+    license: "no licence",
+    ai: "no statement of whether it is machine-generated — and an unstated `ai` is never read as `false`, so none of them ships",
+});
+
 /**
  * Read one provenance file, reporting every key that is not a provenance key.
  *
@@ -289,7 +309,9 @@ function readProvenanceFile(file, findings) {
         });
         return {};
     }
-    if (parsed == null) return {};
+    // An empty file is a record that states nothing, and is held to the
+    // required keys below like any other.
+    if (parsed == null) parsed = {};
     if (typeof parsed !== "object" || Array.isArray(parsed)) {
         findings.push({
             file,
@@ -357,21 +379,24 @@ function readProvenanceFile(file, findings) {
     }
 
     // A record resolves wholesale — the nearest one is the whole answer, and no
-    // ancestor fills a key it leaves out. So an omitted `attribution` or
-    // `license` is not a value inherited from above; it is a file with no stated
-    // rights holder and no stated terms, which is the one thing a provenance
-    // record exists to prevent. Reported against the file rather than a line,
-    // because the fault is an absence and has no position.
+    // ancestor fills a key it leaves out. So an omitted `attribution`, `license`
+    // or `ai` is not a value inherited from above; it is a file with no stated
+    // rights holder, no stated terms, or no statement of whether a machine made
+    // it, which is the one thing a provenance record exists to prevent.
+    // Reported against the file rather than a line, because the fault is an
+    // absence and has no position. An `ai` that is present but not a boolean
+    // already has its own finding above.
     for (const key of REQUIRED_PROVENANCE_KEYS) {
-        if (out[key]) continue;
+        const field = PROVENANCE_FIELD_BY_KEY.get(key);
+        const stated = field?.type === "boolean" ? Object.hasOwn(parsed, key) : Boolean(out[key]);
+        if (stated) continue;
         findings.push({
             file,
             severity: "error",
             message:
                 `a provenance record states \`${key}\`, and this one does not. ` +
                 "A record replaces rather than extends the one above it, so every " +
-                "file it covers would carry no " +
-                (key === "license" ? "licence" : key),
+                `file it covers would carry ${MISSING_KEY_CONSEQUENCE[key] ?? `no ${key}`}`,
         });
     }
     return out;
@@ -497,8 +522,9 @@ function* walkAssetRoot(rootDir, extensions) {
  *   asserts that the address does not exist.
  * @returns {Array<Record<string, any>>} One record per addressable file, in walk
  *   order; the caller imposes the index's total order.
- * @throws {Error} When a file cannot be addressed and no `problems` array was
- *   supplied. `file` rides on the error.
+ * @throws {Error} When any finding is made and no `problems` array was
+ *   supplied. Its message is every finding as a located diagnostic line, one
+ *   per line; `file` and `position` name the first.
  */
 export function collectAssetRecords(assetsBase, { contentPackage, problems }) {
     const records = [];
@@ -548,6 +574,17 @@ export function collectAssetRecords(assetsBase, { contentPackage, problems }) {
                     // ancestor walk is not consulted when one is present.
                 :   inheritedProvenance(path.dirname(absPath), rootDir, cache, findings);
 
+            if (provenance === null) {
+                report(
+                    absPath,
+                    `no provenance record covers this file — add \`${path.basename(absPath)}` +
+                        `${PROVENANCE_SIDECAR_SUFFIX}\` beside it, or a \`${PROVENANCE_FILE}\` ` +
+                        `in its directory or one above it up to ${root}/. Every asset states ` +
+                        "its attribution, its licence and whether it is machine-generated, " +
+                        "and the stage ships a file only on those answers",
+                );
+            }
+
             for (const field of ASSET_RECORD_FIELDS) {
                 if (field.onlyType && field.onlyType !== type && provenance?.[field.name]) {
                     report(
@@ -584,10 +621,14 @@ export function collectAssetRecords(assetsBase, { contentPackage, problems }) {
 
     if (findings.length) {
         if (!problems) {
+            // Every finding, each a located diagnostic line, so a tree with a
+            // dozen uncovered files is fixed in one pass rather than one
+            // rebuild per file.
             const first = findings[0];
-            const err = new Error(first.message);
+            const err = new Error(findings.map(formatDiagnostic).join("\n"));
             err.file = first.file;
             if (first.line) err.position = { line: first.line, column: first.column };
+            /** @type {any} */ (err).located = true;
             throw err;
         }
         problems.push(...findings);

package/engine/asset-references.mjs

@@ -0,0 +1,355 @@
+/*
+ * 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
+ */
+
+/**
+ * Every asset reference in a compiled document states the asset's address.
+ *
+ * A compiled document names a picture by its Foundry path. That path says where
+ * the file sits in one install and nothing more, so each reference also carries
+ * the asset's canonical address, which says which file it is wherever a world
+ * keeps it:
+ *
+ * - **HTML.** Each `<img>` whose `src` names an asset carries
+ *   `data-asset="<address>"` beside it.
+ * - **Path fields.** The address goes in `flags.<system>.assets` on the
+ *   document holding the field, as nested objects mirroring the field's path —
+ *   never a dotted key, which Foundry's `expandObject` splits on update.
+ *
+ *   | Document | Flag on | Keys |
+ *   | --- | --- | --- |
+ *   | Actor, Item, ActiveEffect, Macro, RollTable | the document | `img` |
+ *   | Actor token art | `prototypeToken.flags` | `texture.src` |
+ *   | Table result | the result | `img` |
+ *   | Journal image page | the page | `src` |
+ *
+ * `<system>` is the system the document is compiled for — its
+ * `_stats.systemId`.
+ *
+ * **A stand-in replaces an asset the package does not ship.** A reference to
+ * an excluded picture compiles to its package's own
+ * `<package>-none-<icon|image>-missing` and keeps the excluded asset's address,
+ * which is how a world finds the real file once it holds it. An excluded
+ * picture with no shipped stand-in is a finding against the note.
+ *
+ * The pass runs over the finished document, so it answers the same way
+ * whichever compiler built it and whether the path came from an art address,
+ * an authored pathname or a body image.
+ *
+ * @module
+ */
+
+import { isAssetRecord } from "./index-records.mjs";
+import { ASSETS_SEGMENT, resolvePathname } from "./pathnames.mjs";
+import { deployedAssetPath, exclusionReason, standInAddress } from "./asset-shipping.mjs";
+
+/**
+ * The embedded collections each document type holds, and their document type.
+ *
+ * @type {Readonly<Record<string, Readonly<Record<string, string>>>>}
+ */
+const EMBEDDED_COLLECTIONS = Object.freeze({
+    Actor: Object.freeze({ items: "Item", effects: "ActiveEffect" }),
+    Item: Object.freeze({ effects: "ActiveEffect" }),
+    JournalEntry: Object.freeze({ pages: "JournalEntryPage" }),
+    RollTable: Object.freeze({ results: "TableResult" }),
+    Adventure: Object.freeze({
+        actors: "Actor",
+        items: "Item",
+        journal: "JournalEntry",
+        tables: "RollTable",
+        macros: "Macro",
+    }),
+});
+
+/**
+ * One path field: the object whose `flags` record it, and the field's path
+ * inside that object.
+ *
+ * @typedef {object} AssetPathField
+ * @property {readonly string[]} holder - From the document to the object
+ *   carrying the flag; empty for the document itself.
+ * @property {readonly string[]} field - From that object to the value.
+ * @property {(doc: object) => boolean} [when] - Whether the field is a picture
+ *   on this document.
+ */
+
+/**
+ * The path fields naming an asset, by document type.
+ *
+ * @type {Readonly<Record<string, readonly AssetPathField[]>>}
+ */
+export const ASSET_PATH_FIELDS = Object.freeze({
+    Actor: Object.freeze([
+        { holder: [], field: ["img"] },
+        { holder: ["prototypeToken"], field: ["texture", "src"] },
+    ]),
+    Item: Object.freeze([{ holder: [], field: ["img"] }]),
+    ActiveEffect: Object.freeze([{ holder: [], field: ["img"] }]),
+    Macro: Object.freeze([{ holder: [], field: ["img"] }]),
+    RollTable: Object.freeze([{ holder: [], field: ["img"] }]),
+    TableResult: Object.freeze([{ holder: [], field: ["img"] }]),
+    JournalEntryPage: Object.freeze([
+        { holder: [], field: ["src"], when: (doc) => doc?.type === "image" },
+    ]),
+});
+
+/**
+ * One asset a compiled path can name.
+ *
+ * @typedef {object} AssetReferenceEntry
+ * @property {string} address - The canonical address.
+ * @property {string} package - The content package shipping it.
+ * @property {string} type - `icon` or `image`.
+ * @property {string} foundry - Its path in a Foundry install.
+ * @property {boolean} shipped - Whether its package ships it.
+ */
+
+/**
+ * Every picture a compiled document can name, by Foundry path and by address.
+ *
+ * Built from this package's asset records and every fetched dependency's, so a
+ * reference to another package's picture states its address too.
+ *
+ * @param {{assets?: Map<string, object>, foreign?: Map<string, object>}} linkIndex -
+ *   The compile's link index.
+ * @param {object} config - The resolved build configuration.
+ * @returns {{byPath: Map<string, AssetReferenceEntry>, byAddress: Map<string, AssetReferenceEntry>}}
+ */
+export function assetReferenceLookup(linkIndex, config) {
+    const byPath = new Map();
+    const byAddress = new Map();
+    // Keyed by the rendered canonical address in both maps — a local record's
+    // own `address.canonical` is the parsed form, and a fetched dependency's
+    // entry carries none — so the key is the address.
+    const entries = [
+        ...(linkIndex?.foreign?.entries() ?? []),
+        ...(linkIndex?.assets?.entries() ?? []),
+    ];
+    for (const [key, record] of entries) {
+        if (!isAssetRecord(record) || !record.package) continue;
+        if (deployedAssetPath(record) === undefined) continue;
+        let forms;
+        try {
+            forms = resolvePathname(
+                `${record.package}/${ASSETS_SEGMENT}/${record.asset.path}`,
+                config,
+            );
+        } catch {
+            continue;
+        }
+        if (!forms?.foundry) continue;
+        const entry = {
+            address: key,
+            package: record.package,
+            type: record.type,
+            foundry: forms.foundry,
+            // Additions are this package's own: a dependency's list is its own.
+            shipped:
+                exclusionReason(
+                    record,
+                    record.package === config.contentPackage ?
+                        (config.packageBuild?.shippingLicenses ?? [])
+                    :   [],
+                ) === "",
+        };
+        byPath.set(entry.foundry, entry);
+        byAddress.set(entry.address, entry);
+    }
+    return { byPath, byAddress };
+}
+
+/**
+ * What one compiled path becomes: the path to write and the address to state.
+ *
+ * @param {string} value - A compiled path.
+ * @param {{byPath: Map<string, AssetReferenceEntry>, byAddress: Map<string, AssetReferenceEntry>}} lookup
+ * @param {(message: string) => void} report - Called once per excluded asset
+ *   with no stand-in.
+ * @returns {{src: string, address: string}|null} `null` for a path naming no
+ *   asset.
+ */
+function resolveReference(value, lookup, report) {
+    const entry = lookup.byPath.get(value);
+    if (!entry) return null;
+    if (entry.shipped) return { src: value, address: entry.address };
+    const standIn = lookup.byAddress.get(standInAddress(entry.package, entry.type));
+    if (standIn?.shipped) return { src: standIn.foundry, address: entry.address };
+    report(
+        `\`${entry.address}\` is not shipped in the \`${entry.package}\` package, and that ` +
+            `package has no shipped stand-in \`${standInAddress(entry.package, entry.type)}\` ` +
+            "to draw in its place — add a human-made `missing` picture under its " +
+            `${entry.type === "icon" ? "icons" : "images"}/ root, licensed to ship`,
+    );
+    return { src: value, address: entry.address };
+}
+
+/**
+ * Read a nested property.
+ *
+ * @param {any} obj
+ * @param {readonly string[]} keys
+ * @returns {any}
+ */
+function getPath(obj, keys) {
+    let at = obj;
+    for (const key of keys) {
+        if (at == null || typeof at !== "object") return undefined;
+        at = at[key];
+    }
+    return at;
+}
+
+/**
+ * Write a nested property, creating plain objects on the way.
+ *
+ * @param {Record<string, any>} obj
+ * @param {readonly string[]} keys
+ * @param {unknown} value
+ */
+function setPath(obj, keys, value) {
+    let at = obj;
+    for (const key of keys.slice(0, -1)) {
+        if (at[key] == null || typeof at[key] !== "object") at[key] = {};
+        at = at[key];
+    }
+    at[keys[keys.length - 1]] = value;
+}
+
+/**
+ * Record one field's address on the object holding it.
+ *
+ * Copies the `flags` objects it writes into, so a `flags` block the document
+ * shares with an authored note is never changed in place.
+ *
+ * @param {Record<string, any>} holder
+ * @param {string} system
+ * @param {readonly string[]} field
+ * @param {string} address
+ */
+function flagAddress(holder, system, field, address) {
+    const flags = { ...(holder.flags ?? {}) };
+    const scope = { ...(flags[system] ?? {}) };
+    const assets = structuredClone(scope.assets ?? {});
+    setPath(assets, field, address);
+    scope.assets = assets;
+    flags[system] = scope;
+    holder.flags = flags;
+}
+
+/** One `<img …>` tag. */
+const IMG_TAG = /<img\b[^>]*>/gi;
+
+/** The `src` attribute inside a tag. */
+const SRC_ATTRIBUTE = /(\ssrc\s*=\s*)(["'])(.*?)\2/i;
+
+/**
+ * Mark every `<img>` in one HTML string with its asset's address.
+ *
+ * @param {string} html
+ * @param {Parameters<typeof resolveReference>[1]} lookup
+ * @param {(message: string) => void} report
+ * @returns {string} The HTML, every asset `<img>` carrying `data-asset`.
+ */
+export function annotateHtml(html, lookup, report) {
+    if (typeof html !== "string" || !html.includes("<img")) return html;
+    return html.replace(IMG_TAG, (tag) => {
+        if (/\sdata-asset\s*=/i.test(tag)) return tag;
+        const src = tag.match(SRC_ATTRIBUTE);
+        if (!src) return tag;
+        const resolved = resolveReference(src[3], lookup, report);
+        if (!resolved) return tag;
+        const rewritten = tag.replace(SRC_ATTRIBUTE, `$1$2${resolved.src}$2`);
+        const close = rewritten.endsWith("/>") ? "/>" : ">";
+        const body = rewritten.slice(0, -close.length).replace(/\s+$/, "");
+        return `${body} data-asset="${resolved.address}"${close === "/>" ? " />" : ">"}`;
+    });
+}
+
+/**
+ * Mark every HTML string anywhere under a value, in place.
+ *
+ * @param {any} value
+ * @param {Parameters<typeof resolveReference>[1]} lookup
+ * @param {(message: string) => void} report
+ */
+function annotateStrings(value, lookup, report) {
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            if (typeof item !== "string") annotateStrings(item, lookup, report);
+            else {
+                const annotated = annotateHtml(item, lookup, report);
+                if (annotated !== item) value[index] = annotated;
+            }
+        });
+        return;
+    }
+    if (value == null || typeof value !== "object") return;
+    // Written back only where something changed: a document holds frozen
+    // values — a parsed Address among them — that no `<img>` ever sits in.
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== "string") annotateStrings(item, lookup, report);
+        else {
+            const annotated = annotateHtml(item, lookup, report);
+            if (annotated !== item) value[key] = annotated;
+        }
+    }
+}
+
+/**
+ * Annotate one document's path fields, and its embedded documents', in place.
+ *
+ * @param {Record<string, any>} doc
+ * @param {string} documentType
+ * @param {string|null|undefined} system
+ * @param {Parameters<typeof resolveReference>[1]} lookup
+ * @param {(message: string) => void} report
+ */
+function annotateFields(doc, documentType, system, lookup, report) {
+    if (doc == null || typeof doc !== "object") return;
+    for (const { holder: holderPath, field, when } of ASSET_PATH_FIELDS[documentType] ?? []) {
+        if (when && !when(doc)) continue;
+        const holder = holderPath.length ? getPath(doc, holderPath) : doc;
+        if (holder == null || typeof holder !== "object") continue;
+        const value = getPath(holder, field);
+        if (typeof value !== "string" || !value) continue;
+        const resolved = resolveReference(value, lookup, report);
+        if (!resolved) continue;
+        setPath(holder, field, resolved.src);
+        if (system) flagAddress(holder, system, field, resolved.address);
+    }
+    for (const [key, childType] of Object.entries(EMBEDDED_COLLECTIONS[documentType] ?? {})) {
+        const children = doc[key];
+        if (!Array.isArray(children)) continue;
+        for (const child of children) annotateFields(child, childType, system, lookup, report);
+    }
+}
+
+/**
+ * State the address of every asset one compiled document references, and draw
+ * a stand-in for each the package does not ship. Changes `doc` in place.
+ *
+ * @param {Record<string, any>} doc - The compiled document.
+ * @param {string} documentType - Its Foundry document type.
+ * @param {object} opts - Options.
+ * @param {Parameters<typeof resolveReference>[1]} opts.lookup - From
+ *   {@link assetReferenceLookup}.
+ * @param {string|null|undefined} opts.system - The flag scope; no flag is
+ *   written without one.
+ * @param {(message: string) => void} opts.report - Receives each finding.
+ * @returns {Record<string, any>} `doc`.
+ */
+export function annotateAssetReferences(doc, documentType, { lookup, system, report }) {
+    annotateFields(doc, documentType, system, lookup, report);
+    annotateStrings(doc, lookup, report);
+    return doc;
+}