@heroiclands/package-build 22.9.2 → 22.11.0

package/engine/actor-compiler.mjs

@@ -50,6 +50,7 @@ import fs from "fs";
 import path from "path";
 import log from "loglevel";
 
+import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
 import { makeId } from "./helpers.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 // The `{#appearance}` / `{#dossier}` convention is the note format's, so the
@@ -96,6 +97,7 @@ export function stripCompendiumFields(item) {
  */
 export function isPlainObject(v) {
     return (
+        !isAddressTuple(v) &&
         v !== null &&
         typeof v === "object" &&
         !Array.isArray(v) &&
@@ -705,7 +707,7 @@ export class SystemActorCompiler extends BasePackCompiler {
         const key = `${this.documentSubtypes.block}.items`;
         const where = () =>
             locateFrontmatterKey(this.currentNote?.absPath, "items", String(model ?? ""));
-        if (typeof model !== "string" || !model.trim()) {
+        if (!isAddressTuple(model) && (typeof model !== "string" || !model.trim())) {
             this.noteError(`${ctx}: ${key}[${index}] \`model\` must be an address`, where());
             this.errorCount++;
             return null;
@@ -715,7 +717,11 @@ export class SystemActorCompiler extends BasePackCompiler {
         // dependency whose item catalogue was loaded.
         const types = new Set(Object.keys(this.documentSubtypes.types));
         const packages = new Set([contentPackage(), ...this.foreignPackages]);
-        const read = readQualifier(model.trim(), types, packages);
+        const read = parseAddress(
+            model,
+            { types, packages, package: contentPackage(), system: this.system },
+            { declared: true, legacyShortcodeCase: true },
+        );
         if (!read || read.reason) {
             const why =
                 read?.reason === "not-lowercase" ?
@@ -728,7 +734,15 @@ export class SystemActorCompiler extends BasePackCompiler {
             this.errorCount++;
             return null;
         }
-        return { type: read.type, shortcode: read.shortcode, package: read.package ?? null };
+        if (read.system !== this.system || !types.has(read.type)) {
+            this.noteError(
+                `${ctx}: ${key}[${index}] model must name a ${this.system} item, but names ${renderAddress(read)}`,
+                where(),
+            );
+            this.errorCount++;
+            return null;
+        }
+        return read;
     }
 
     /**
@@ -789,10 +803,8 @@ export class SystemActorCompiler extends BasePackCompiler {
             this.errorCount++;
             return null;
         }
-        // A `model:` may name the package its template comes from. Where
-        // it does, the packaged address is used and nothing local can shadow
-        // it; where it does not, the unqualified one is, and a local definition
-        // still wins over a dependency's as it always has.
+        // A model names one package. Omitted packages are completed at the
+        // read boundary; native embedded identities use the local catalogue.
         const address = catalogueKey(
             /** @type {string} */ (subType),
             shortcode ?? "",
@@ -854,6 +866,7 @@ export class SystemActorCompiler extends BasePackCompiler {
         const { data: _authored, ...fields } = overlay ?? {};
         const merged = overlay ? deepMerge(base, fields) : base;
         merged.type = subType;
+        if (this.reduceEmittedAddresses(merged.system, itemFields(type, this.system))) return null;
         // The two art rules an item note compiles under, applied to an entry
         // that is one in every respect but where it is written: the address it
         // names wins, the template it copies answers next, and the type's own

package/engine/address-fields.mjs

@@ -0,0 +1,426 @@
+/*
+ * 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
+ */
+
+/**
+ * **An authored Address, an emitted native reference.**
+ *
+ * A declared field may hold an Address where the document it compiles into
+ * holds a **Shortcode** or a published Item UUID. An affiliation's `seat` is a Shortcode case: the note
+ * names a place at whatever length says what it means — `tashal`,
+ * `place-tashal`, `none-place-tashal`, `kethira-none-place-tashal` — and the
+ * compiled Item carries `tashal`, which is what the runtime resolves among the
+ * items one actor holds, where packages do not exist.
+ *
+ * The `emit: "uuid"` declaration resolves an exact native target from the
+ * local or declared dependency index. The target supplies its published UUID.
+ * This module performs both conversions at the Foundry output boundary.
+ * Storing the written form instead would store a value plus a context that does
+ * not travel with it: a four-segment string reaches a runtime that looks up one
+ * segment and returns nothing, silently.
+ *
+ * ## The two questions stay separate
+ *
+ * A position declares both halves, and they are not the same statement:
+ *
+ * - **`type`** is what an omitted `<type>` segment takes — the default
+ *   {@link module:engine/address.parseAddress} fills in.
+ * - **`accepts`** is the set of types the position takes at all, tested by
+ *   {@link module:engine/address.acceptsType} once the value parses.
+ *
+ * They coincide at every position here, and that is the common case rather than
+ * the rule: an art slot defaults to `icon` and accepts `icon` or `image`. So the
+ * set is read as its own input and never derived from the default, and a
+ * position accepting several types is expressible without touching this module.
+ *
+ * The distinction is what a value like `being-foobar` turns on. With the package
+ * and the system supplied from context it parses to a perfectly good Address —
+ * and it is unacceptable to a field that takes a place. The parser does not
+ * refuse it, because it is an Address; the **field** refuses it, with an error
+ * naming what it accepts.
+ *
+ * ## Authored defaults belong to the read boundary
+ *
+ * Parsed Address tuples retain the enclosing block's system. This reduction
+ * projects their Shortcode without changing that identity. Direct callers
+ * supplying strings provide the position's package and type vocabulary.
+ *
+ * ## The reduction is lossy, and the collision it loses is legal
+ *
+ * A shortcode is unique only within one `package-system-type` space, so
+ * `foo-sohl-affiliation-b` and `bar-sohl-affiliation-b` are both valid and are
+ * two different affiliations. Reducing either to `b` throws away the only thing
+ * that told them apart, and the emitted field cannot represent both.
+ *
+ * That is **an error naming both Addresses**, rather than a silent merge:
+ * shipping a standing nobody authored is the worse outcome. It fires on content
+ * that is entirely valid, so the message says so instead of implying a mistake.
+ *
+ * One Address written twice is a different finding, and only where the position
+ * holds a map: two keys reducing to one emitted key claim two values for one
+ * target, and the field carries one. In a **list** the same Address twice is an
+ * ordinary duplicate — nothing is lost, so nothing is reported.
+ *
+ * ## What this module does not do
+ *
+ * Shortcode output needs only the Address grammar. UUID output requires the
+ * exact target in the published index and accepts only Item UUIDs.
+ *
+ * A failure is a **finding**, never a diagnostic: the caller owns the file and
+ * the severity, and locates the finding at the value inside the note.
+ *
+ * @module
+ */
+
+import { acceptsType, parseAddress, renderAddress, isAddressTuple } from "./address.mjs";
+import { AddressEntries } from "./address-values.mjs";
+import { systemOf } from "./document-subtypes.mjs";
+import { getFrontmatter } from "./frontmatter.mjs";
+import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
+import { authoredKey, setPath } from "./system-block.mjs";
+
+/**
+ * How many values a position holds.
+ *
+ * - `value` — the field's value is one Address.
+ * - `items` — every element of a list is one.
+ * - `keys` — every **key** of a map is one, and the values are untouched.
+ *
+ * @type {readonly string[]}
+ */
+export const ADDRESS_FIELD_SHAPES = Object.freeze(["value", "items", "keys"]);
+
+/**
+ * An Address position, as a field declaration states it.
+ *
+ * @typedef {object} AddressPosition
+ * @property {string} type - The type an omitted `<type>` segment takes.
+ * @property {readonly string[]} accepts - Every type the position accepts.
+ * @property {"value"|"items"|"keys"} [holds] - Where the Addresses are.
+ *   Defaults to `value`.
+ * @property {"uuid"} [emit] - Resolve each exact target to its published Item UUID.
+ */
+
+/**
+ * What a reduction could not do, for a caller to report.
+ *
+ * @typedef {object} AddressFinding
+ * @property {string} key - The field, named as an author writes it.
+ * @property {string} written - The authored value, so the caller can locate the
+ *   finding at the line carrying it rather than at the key.
+ * @property {string} message - One sentence, naming the fix.
+ */
+
+/**
+ * The declarations that state an Address position.
+ *
+ * @param {readonly object[]} fields - A field declaration.
+ * @returns {object[]} Only the fields carrying an `address` statement.
+ */
+export function addressFields(fields) {
+    return (fields ?? []).filter((field) => Boolean(field?.address));
+}
+
+/**
+ * Reduce every Address a compiled block holds to the Shortcode it names.
+ *
+ * The block is edited in place, as {@link
+ * module:engine/system-block.mergeSystemData} edits it: what the caller holds is
+ * the document being assembled, and a field the reduction cannot read is left
+ * exactly as authored — the findings stop the build, so nothing ships either
+ * way, and an untouched value is what a reader of the failing note sees.
+ *
+ * @param {object} emitted - The `system` block, already built.
+ * @param {readonly object[]} fields - The type's field declaration.
+ * @param {import("./address.mjs").AddressVocabulary & {package?: string}}
+ *   vocabulary - The tree's vocabularies and the package the values are written
+ *   in.
+ * @returns {AddressFinding[]} Every value that could not be reduced.
+ */
+export function reduceAddressFields(emitted, fields, vocabulary = {}) {
+    const findings = [];
+    for (const field of addressFields(fields)) {
+        const value = getFrontmatter(emitted, field.to, undefined);
+        const reduced = reduceOne(value, field, vocabulary, findings);
+        if (reduced !== undefined) setPath(emitted, field.to, reduced);
+    }
+    return findings;
+}
+
+/**
+ * Reduce one field's value, by the shape its position holds.
+ *
+ * @param {unknown} value - The emitted value.
+ * @param {object} field - The declaration.
+ * @param {object} vocabulary - As {@link reduceAddressFields} takes it.
+ * @param {AddressFinding[]} findings - Collected, in the order they are found.
+ * @returns {unknown} The reduced value, or `undefined` to leave it alone.
+ */
+function reduceOne(value, field, vocabulary, findings) {
+    const position = field.address;
+    const defaults = positionDefaults(position, vocabulary);
+    const shape = position.holds ?? "value";
+    // Two keys, or two list entries, reducing to one emitted shortcode: the
+    // Address each of them named, by the shortcode all of them land on.
+    const seen = new Map();
+    const read = (written) => readOne(written, field, defaults, seen, findings, shape, vocabulary);
+
+    if (shape === "keys") {
+        if (!isMapping(value)) return undefined;
+        const out = {};
+        for (const [written, standing] of value instanceof AddressEntries ?
+            value.entries.map((e) => [e.target, e.value])
+        :   Object.entries(value)) {
+            const code = read(written);
+            // The first standing stands, so the emitted map does not depend on
+            // which key the reduction reached first.
+            if (code !== undefined && !Object.hasOwn(out, code)) out[code] = standing;
+        }
+        return out;
+    }
+
+    if (shape === "items") {
+        if (!Array.isArray(value)) return undefined;
+        return value.map((written) => read(written) ?? written);
+    }
+
+    // One Address, and the two empties of a scalar field: `null` and an absent
+    // key mean *names nothing*, and `""` is the same statement a property editor
+    // writes. Neither is an Address, and neither is a mistake.
+    if (value == null || value === "") return undefined;
+    return read(value);
+}
+
+/**
+ * Read one written Address, reporting what stops it.
+ *
+ * @param {unknown} written - The value as authored.
+ * @param {object} field - The declaration.
+ * @param {object} defaults - What {@link positionDefaults} returns.
+ * @param {Map<string, {address: string, written: string}>} seen - The Addresses
+ *   already reduced at this position, by emitted shortcode.
+ * @param {AddressFinding[]} findings - Collected.
+ * @param {string} shape - What the position holds.
+ * @returns {string|undefined} The shortcode, or `undefined` when nothing is
+ *   emitted for this value.
+ */
+function readOne(written, field, defaults, seen, findings, shape, vocabulary) {
+    const key = findingKey(field);
+    // An embedded Item may inherit an already compiled reference from its model.
+    if (
+        field.address.emit === "uuid" &&
+        typeof written === "string" &&
+        /^Compendium\.[^.]+\.[^.]+\.Item\.[^.]+$/.test(written)
+    )
+        return written;
+    const value =
+        isAddressTuple(written) ? renderAddress(written)
+        : typeof written === "string" ? written
+        : String(written ?? "");
+    const report = (message) => void findings.push({ key, written: value, message });
+
+    const tuple = parseAddress(written, defaults);
+    if (tuple.reason) {
+        report(unreadableMessage(key, value, tuple, defaults));
+        return undefined;
+    }
+    if (!acceptsType(tuple, defaults.accepts)) {
+        report(unacceptedMessage(key, value, defaults.accepts));
+        return undefined;
+    }
+
+    const address = renderAddress(tuple);
+    if (field.address.emit === "uuid") {
+        const target =
+            tuple.package === vocabulary.package ?
+                vocabulary.referenceTargets?.get(address)
+            :   vocabulary.foreignReferences?.get(address);
+        const uuid = target?.uuid;
+        if (!uuid || !/^Compendium\.[^.]+\.[^.]+\.Item\.[^.]+$/.test(uuid)) {
+            report(
+                `\`${key}\` names \`${address}\`, but its exact native Item has no published Item UUID`,
+            );
+            return undefined;
+        }
+        return uuid;
+    }
+    const code = tuple.shortcode;
+    const first = seen.get(code);
+    if (first && first.address !== address) {
+        report(collidingMessage(key, first.address, address, code));
+        return undefined;
+    }
+    if (first && shape === "keys") {
+        report(repeatedMessage(key, address, first.written, value));
+        return undefined;
+    }
+    if (!first) seen.set(code, { address, written: value });
+    return code;
+}
+
+/**
+ * The defaults and vocabularies a position reads its values against.
+ *
+ * **The position's own types belong in the vocabulary.** A position declares
+ * what it names, so a tree that happens to carry no note of that type still
+ * reads the value: without this, an affiliation naming a `seat` in a tree whose
+ * places are all in a dependency stops parsing, and the refusal describes the
+ * tree rather than the value.
+ *
+ * @param {AddressPosition} position - The declaration's `address` statement.
+ * @param {object} vocabulary - As {@link reduceAddressFields} takes it.
+ * @returns {object} The defaults {@link parseAddress} takes, plus the accepted
+ *   set the acceptability step reads.
+ */
+function positionDefaults(position, vocabulary) {
+    const accepts = position.accepts ?? [position.type];
+    return {
+        ...vocabulary,
+        types: new Set([...(vocabulary.types ?? []), position.type, ...accepts]),
+        // Derived from the type rather than taken from the block the value sits
+        // in: an affiliation address names a SoHL Item, a place address names a
+        // core document, and both are written inside the same `sohl:` block.
+        system: systemOf(position.type, KNOWN_DOCUMENT_SUBTYPE_MAPS),
+        type: position.type,
+        accepts,
+    };
+}
+
+/** Whether a value is an authored map rather than a list or a scalar. */
+function isMapping(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * The key a finding names, as the note's own line spells it.
+ *
+ * A declaration's shared source is a path into the `data:` container —
+ * `data.seat` — and the note writes `seat:` one level inside it. The finding
+ * names that key for two reasons at once: it is the word on the line the
+ * diagnostic opens, and it is what {@link
+ * module:engine/retired-fields.locateFrontmatterKey} matches when the authored
+ * value cannot be found in the fence, which a dotted path never would.
+ *
+ * @param {object} field - The declaration.
+ * @returns {string} The key, without the container holding it.
+ */
+function findingKey(field) {
+    return authoredKey(field.name ?? field.to);
+}
+
+/**
+ * Format a closed set for a message: `a, b or c`.
+ *
+ * @param {readonly unknown[]} values - The set.
+ * @returns {string} The values, joined.
+ */
+function oneOf(values) {
+    const all = [...values].map((value) => `\`${String(value)}\``);
+    return all.length < 2 ?
+            all.join("")
+        :   `${all.slice(0, -1).join(", ")} or ${all[all.length - 1]}`;
+}
+
+/**
+ * What a value the grammar cannot read is reported as.
+ *
+ * @param {string} key - The field, as an author writes it.
+ * @param {string} written - The authored value.
+ * @param {import("./address.mjs").AddressProblem} problem - Why it does not
+ *   parse.
+ * @param {object} defaults - What {@link positionDefaults} returns.
+ * @returns {string} The message.
+ */
+function unreadableMessage(key, written, problem, defaults) {
+    if (problem.reason === "no-content-index") {
+        return (
+            `\`${key}\` names package "${problem.package}", which is declared ` +
+            `\`contentIndex: false\` — a Foundry dependency only, with no content index ` +
+            `fetched for it, so nothing it publishes can be named here`
+        );
+    }
+    if (problem.reason === "not-lowercase") {
+        return (
+            `\`${key}\` names \`${written}\`, whose package, system or type segment ` +
+            `carries a capital — those segments are lowercase, an address having one ` +
+            `spelling`
+        );
+    }
+    return (
+        `\`${key}\` must name ${oneOf(defaults.accepts)} — its \`shortcode\`, or that ` +
+        `address qualified by type, by system and type, or by package, system and ` +
+        `type — but reads \`${written}\``
+    );
+}
+
+/**
+ * What a value naming a type the position does not take is reported as.
+ *
+ * An **error**: the value is a real Address, so no default repairs it, and the
+ * position cannot do anything with what it names.
+ *
+ * **The value states its own type, and the message leaves it there.** A value
+ * omitting the `<type>` segment takes the position's default and is therefore
+ * acceptable, so this fires only where the author wrote a type — and naming the
+ * parsed one instead would name the `doc<type>` a system-bearing type is
+ * redirected to under `none`, sending a reader to look for a segment nobody
+ * wrote.
+ *
+ * @param {string} key - The field, as an author writes it.
+ * @param {string} written - The authored value.
+ * @param {readonly string[]} accepts - The types the position accepts.
+ * @returns {string} The message.
+ */
+function unacceptedMessage(key, written, accepts) {
+    return (
+        `\`${key}\` names \`${written}\`, whose type this field does not accept — it ` +
+        `accepts ${oneOf(accepts)}`
+    );
+}
+
+/**
+ * What two Addresses reducing to one shortcode are reported as.
+ *
+ * The message states that both values are valid, because they are: a shortcode
+ * is unique within one package's address space and these are two packages'. The
+ * fault is in what the emitted field can hold, which is why the finding names
+ * both Addresses rather than one of them.
+ *
+ * @param {string} key - The field, as an author writes it.
+ * @param {string} first - The Address already reduced.
+ * @param {string} second - The Address colliding with it.
+ * @param {string} code - The shortcode they share.
+ * @returns {string} The message.
+ */
+function collidingMessage(key, first, second, code) {
+    return (
+        `\`${key}\` names both \`${first}\` and \`${second}\`, which share the shortcode ` +
+        `"${code}" — both addresses are valid, and the compiled field is keyed by the ` +
+        `shortcode alone, so it carries one of the two and the other is lost`
+    );
+}
+
+/**
+ * What one Address written twice at a keyed position is reported as.
+ *
+ * @param {string} key - The field, as an author writes it.
+ * @param {string} address - The Address both keys name.
+ * @param {string} first - How the first key was written.
+ * @param {string} second - How the second was written.
+ * @returns {string} The message.
+ */
+function repeatedMessage(key, address, first, second) {
+    return (
+        `\`${key}\` names \`${address}\` twice, as \`${first}\` and as \`${second}\` — the ` +
+        `compiled field carries one value per target, so the second is lost`
+    );
+}

package/engine/address-values.mjs

@@ -0,0 +1,80 @@
+/*
+ * 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>
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { isAddressTuple, renderAddress } from "./address.mjs";
+
+/** Address-keyed properties hold typed entries rather than string object keys. */
+export class AddressEntries {
+    /** @param {Array<{target: object, value: unknown, sourceKey: string}>} entries - Typed entries and diagnostic source keys. */
+    constructor(entries) {
+        if (!entries.every((entry) => isAddressTuple(entry.target)))
+            throw new TypeError("Address map keys must be complete tuples");
+        this.entries = entries;
+    }
+}
+
+/** An Address and the section within its document. */
+export class AddressLink {
+    /** @param {object} target - Complete tuple. @param {string} anchor - Section slug. */
+    constructor(target, anchor) {
+        if (!isAddressTuple(target)) throw new TypeError("An Address link needs a complete tuple");
+        this.target = target;
+        this.anchor = anchor;
+        Object.freeze(this);
+    }
+}
+
+/**
+ * Render typed properties at a generated-output boundary.
+ * @param {any} value - A tuple-bearing tree.
+ * @param {WeakMap<object, object>} [seen] - Shared containers in this output.
+ * @returns {any} A serializable tree containing full Addresses.
+ */
+export function encodeAddresses(value, seen = new WeakMap()) {
+    if (value && typeof value === "object" && seen.has(value)) return seen.get(value);
+    if (isAddressTuple(value)) return renderAddress(value);
+    if (value instanceof AddressLink) return `${renderAddress(value.target)}#${value.anchor}`;
+    if (value instanceof AddressEntries) {
+        const out = {};
+        seen.set(value, out);
+        for (const { target, value: entry } of value.entries) {
+            const key = renderAddress(target);
+            if (Object.hasOwn(out, key)) throw new Error(`Repeated Address map key: ${key}`);
+            out[key] = encodeAddresses(entry, seen);
+        }
+        return out;
+    }
+    if (Array.isArray(value)) {
+        const out = [];
+        seen.set(value, out);
+        for (const entry of value) out.push(encodeAddresses(entry, seen));
+        return out;
+    }
+    if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype)
+        return value;
+    const out = {};
+    seen.set(value, out);
+    for (const [key, entry] of Object.entries(value)) out[key] = encodeAddresses(entry, seen);
+    return out;
+}
+
+/**
+ * Clone mutable note state while retaining immutable Address identities.
+ * @param {any} value - Typed note state.
+ * @returns {any} An independent mutable container tree.
+ */
+export function cloneAddressState(value) {
+    if (isAddressTuple(value)) return value;
+    if (value instanceof AddressEntries)
+        return new AddressEntries(
+            value.entries.map((entry) => ({ ...entry, value: cloneAddressState(entry.value) })),
+        );
+    if (Array.isArray(value)) return value.map(cloneAddressState);
+    if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, v]) => [key, cloneAddressState(v)]));
+}