@heroiclands/package-build 0.6.1 → 3.0.1

package/sohl/being-info.mjs

@@ -0,0 +1,173 @@
+/*
+ * 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 being's info-block fields**, derived from the items it embeds.
+ *
+ * A `being` note carries its embedded documents as `sohl.items` — a flat list
+ * of `{ shortcode, type, system? }` — but the shared theme's sidebar reads
+ * *resolved* shapes: a `skills` map, `gear` grouped by kind, and `spells` /
+ * `talents` split out of the mystical abilities. This is the translation
+ * between the two, and it is SoHL data-model knowledge: which item type is a
+ * skill, where a mastery level lives, what distinguishes a spell from a talent.
+ *
+ * **It lives here because it was living in two places.** Both
+ * `Song-of-Heroic-Lands-FoundryVTT` and `sohl-thalorna` carried a copy, and the
+ * copies drifted: SoHL's caller still gated the derivation on `character` and
+ * `creature`, the two types #1580 merged into `being`, so it had matched
+ * nothing since the merge and all 95 of its being pages published with empty
+ * sidebar sections (SoHL#1696). thalorna's copy checked `being` and was right.
+ * Nothing failed in either repository; the pages built and shipped.
+ *
+ * {@link isBeing} exists for that reason. The bug was not in the derivation —
+ * it was in each caller's idea of what a being *is*, written out per repository
+ * where it could rot independently. One definition, imported.
+ *
+ * @module
+ */
+
+/**
+ * The note `type` whose pages carry a being info block.
+ *
+ * One name, since #1580 merged `character` and `creature` into the `being` they
+ * had always compiled into. The retired names are deliberately **not** accepted
+ * as aliases: they throw elsewhere in the system, and tolerating them here
+ * would hide the next drift of this kind rather than surface it.
+ */
+export const BEING_TYPE = "being";
+
+/**
+ * Whether a note's frontmatter describes a being.
+ *
+ * @param {{type?: unknown}|null|undefined} fm - A note's frontmatter.
+ * @returns {boolean} `true` when the note is a being.
+ */
+export function isBeing(fm) {
+    return Boolean(fm) && fm.type === BEING_TYPE;
+}
+
+/**
+ * The sidebar group each gear item type is displayed under.
+ *
+ * Presentation naming, not data-model naming: the model says `weapongear`, the
+ * sidebar heading says "weapons". Kept as one table so a new gear type is added
+ * in a single place rather than in each consumer's site build.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const GEAR_TYPE_TO_KEY = Object.freeze({
+    weapongear: "weapons",
+    armorgear: "armor",
+    projectilegear: "projectiles",
+    miscgear: "misc",
+    containergear: "containers",
+    concoctiongear: "concoctions",
+});
+
+/** Whether a value is a plain mapping. */
+const isMap = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
+
+/** Whether a value is a non-empty array. */
+const nonEmpty = (v) => Array.isArray(v) && v.length > 0;
+
+/**
+ * Derive a being's info-block fields from its raw `sohl.items[]`.
+ *
+ * Each item's `shortcode` is resolved against `index` — keyed
+ * `"<type>:<shortcode>"` — for a display name and a link to the item's own
+ * page. `attributes` already match the sidebar shape and pass through
+ * untouched.
+ *
+ * **Authored values win.** Only fields the author did not supply are derived,
+ * so a note that hand-writes `sohl.skills` keeps exactly what it wrote. An
+ * item's inline `name` beats the index, and an unresolved shortcode falls back
+ * to *itself* rather than being dropped — a page that names an item the index
+ * has not heard of is better than a page silently missing a row.
+ *
+ * Returns a new object; the input is not mutated.
+ *
+ * @param {object|null|undefined} sohl - The note's `sohl` frontmatter block.
+ * @param {Map<string, {name?: string, url?: string}>} index - Content index,
+ *   `"<type>:<shortcode>"` → the item's page.
+ * @returns {object|null|undefined} The block with its info-block fields filled
+ *   in, or the input unchanged when there is nothing to derive from.
+ */
+export function deriveBeingInfo(sohl, index) {
+    if (!isMap(sohl)) return sohl;
+    const out = { ...sohl };
+    const items = Array.isArray(out.items) ? out.items : [];
+    if (items.length === 0) return out;
+
+    const lookup = (type, shortcode) =>
+        shortcode ? index.get(`${type}:${shortcode}`) : undefined;
+
+    /** An item's display name: its own, then the index's, then its shortcode. */
+    const displayName = (it, ref, shortcode) =>
+        (typeof it.name === "string" && it.name) || ref?.name || shortcode;
+
+    // Skills: { shortcode: masteryLevelBase }.
+    if (!(isMap(out.skills) && Object.keys(out.skills).length > 0)) {
+        const skills = {};
+        for (const it of items) {
+            if (!isMap(it) || it.type !== "skill") continue;
+            const level = it.system?.masteryLevelBase;
+            if (typeof it.shortcode === "string" && typeof level === "number") {
+                skills[it.shortcode] = level;
+            }
+        }
+        if (Object.keys(skills).length > 0) out.skills = skills;
+    }
+
+    // Gear: { weapons: [{ name, shortcode?, url? }], armor: [...], … }.
+    if (!isMap(out.gear)) {
+        const gear = {};
+        for (const it of items) {
+            if (!isMap(it)) continue;
+            const key = GEAR_TYPE_TO_KEY[it.type];
+            if (!key) continue;
+            const shortcode =
+                typeof it.shortcode === "string" ? it.shortcode : undefined;
+            const ref = lookup(it.type, shortcode);
+            const name = displayName(it, ref, shortcode);
+            if (!name) continue;
+            const entry = { name };
+            if (shortcode) entry.shortcode = shortcode;
+            if (ref?.url) entry.url = ref.url;
+            (gear[key] ??= []).push(entry);
+        }
+        if (Object.keys(gear).length > 0) out.gear = gear;
+    }
+
+    // Mystical abilities, split by subType into spells / talents.
+    const spells = [];
+    const talents = [];
+    for (const it of items) {
+        if (!isMap(it) || it.type !== "mysticalability") continue;
+        const shortcode =
+            typeof it.shortcode === "string" ? it.shortcode : undefined;
+        const ref = lookup("mysticalability", shortcode);
+        // No shortcode fallback here: an ability with neither an inline name
+        // nor an index entry has nothing to show, and a row reading like a
+        // shortcode is worse than no row.
+        const name = (typeof it.name === "string" && it.name) || ref?.name;
+        if (!name) continue;
+        const entry = { name };
+        if (ref?.url) entry.url = ref.url;
+        if (it.subType === "arcaneincantation") spells.push(entry);
+        else if (it.subType === "arcanetalent") talents.push(entry);
+    }
+    if (spells.length > 0 && !nonEmpty(out.spells)) out.spells = spells;
+    if (talents.length > 0 && !nonEmpty(out.talents)) out.talents = talents;
+
+    return out;
+}

package/sohl/default-item-art.mjs

@@ -0,0 +1,82 @@
+/*
+ * 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
+ */
+
+/**
+ * Default item artwork, keyed by item `type` — the single source of truth for
+ * both the compendium builder (the items pack compiler, at build time) and the
+ * runtime `SohlItem.getDefaultArtwork` override (fresh, ad-hoc-created items).
+ *
+ * Foundry's `Item.DEFAULT_ICON` is the white `icons/svg/item-bag.svg`, which is
+ * invisible on the light Manuscript sheet and does not adapt to theme; every
+ * SoHL item type instead defaults to a themed `systems/sohl/assets/icons/**`
+ * SVG here (dark ink in light mode, cream in dark, via the build-time
+ * adaptive-fill injection in `utils/svg-theme.mjs`).
+ *
+ * This module is deliberately **plain ESM** — no TypeScript, no `@src` aliases,
+ * no Foundry — precisely so the plain-`node` pack scripts *and* the bundled TS
+ * runtime can both import it. A `.ts` module could not be required by the build
+ * scripts (they run under bare `node`, without the bundler that resolves the
+ * `@src` alias and strips types). Keeping one map here is what prevents the
+ * build-time and runtime defaults from drifting apart (issue #932 was exactly
+ * that drift: the builder had a default, runtime did not).
+ *
+ * It lives in this package rather than in the system's `src/` tree because the
+ * pack pipeline is installed as a dependency (#1501): a relative path out of
+ * the package would resolve to garbage once the pipeline runs from
+ * `node_modules`. The runtime imports it back through the package's
+ * `./sohl/default-item-art` entry point, so there is still exactly one map
+ * (#1510). Injecting the map through configuration instead would re-open #932,
+ * because the two sides would once more be free to disagree.
+ *
+ * Paths are fully resolved (`systems/sohl/...`) — the served path both layers
+ * need. If a new item type is added, add its default here.
+ */
+export const DEFAULT_ITEM_ART = {
+    affiliation: "systems/sohl/assets/icons/noun/shield.svg",
+    affliction: "systems/sohl/assets/icons/other/sick.svg",
+    armorgear: "systems/sohl/assets/icons/game-icons/lorc/breastplate.svg",
+    attribute: "systems/sohl/assets/icons/other/charm.svg",
+    concoctiongear: "systems/sohl/assets/icons/game-icons/badges/flask.svg",
+    containergear: "systems/sohl/assets/icons/other/sack.svg",
+    miscgear: "systems/sohl/assets/icons/other/question-mark.svg",
+    mystery: "systems/sohl/assets/icons/other/sparkles.svg",
+    mysticalability: "systems/sohl/assets/icons/other/hand-sparkles.svg",
+    projectilegear: "systems/sohl/assets/icons/noun/arrow.svg",
+    skill: "systems/sohl/assets/icons/other/head-gear.svg",
+    trauma: "systems/sohl/assets/icons/other/injury.svg",
+    weapongear: "systems/sohl/assets/icons/other/sword.svg",
+};
+
+/**
+ * The default art path for an item `type`, or throw when the type is unknown —
+ * the build's fail-fast contract, so an unrecognized type is never silently
+ * defaulted (aborting the pack build rather than shipping a mismatched icon).
+ *
+ * Runtime callers that must tolerate unknown or `base`-typed items should read
+ * {@link DEFAULT_ITEM_ART} directly and fall back to Foundry's default instead
+ * of calling this — see `SohlItem.getDefaultArtwork`.
+ *
+ * @param {string} type - the item type.
+ * @returns {string} the default image path for that type.
+ */
+export function defaultItemArt(type) {
+    if (!(type in DEFAULT_ITEM_ART)) {
+        throw new Error(
+            `No default art for item type "${type}" — add one to @heroiclands/package-build/sohl/default-item-art`,
+        );
+    }
+    // The map's inferred type has no index signature — deliberately, so callers
+    // reading it directly get the precise key set. The `in` guard above has
+    // already proved this key is present.
+    return /** @type {Record<string, string>} */ (DEFAULT_ITEM_ART)[type];
+}

package/sohl/index.mjs

@@ -0,0 +1,55 @@
+/*
+ * 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
+ */
+
+/**
+ * The SoHL-specific half of the toolchain: the knowledge of the Song of Heroic
+ * Lands data model that a generic content module must never receive.
+ *
+ * The item-type registry and its builders, the items and actors compilers, the
+ * default-art map, and the affiliation standings live here (#1512). Nothing in
+ * `@heroiclands/package-build/engine` exports any of it, so an adventure module
+ * that builds journals, macros, and scenes never receives `buildWeaponGear`.
+ *
+ * A consuming repository hands its own registry to the engine as configuration
+ * — `itemBuilders` in `package-build.config.yaml` — which is how the engine
+ * composes the one doc-carrying-type set without holding any package's data
+ * model.
+ *
+ * Namespaced rather than flattened, for the reason the engine barrel gives.
+ *
+ * @module
+ */
+
+/** The item-type registry: every type that compiles into an Item, and its builder. */
+export * as itemBuilders from "./item-builders.mjs";
+
+/** The Item compiler. */
+export * as items from "./items.mjs";
+
+/** The Actor compiler. */
+export * as actors from "./actors.mjs";
+
+/** This package's own knowledgebase body passes, named from `site.pass`. */
+export * as kbPasses from "./kb-passes.mjs";
+
+// Flat as well as namespaced: the Foundry runtime imports these by name through
+// their own entry points, and they were this barrel's surface before the
+// compilers arrived (#1510).
+export { DEFAULT_ITEM_ART, defaultItemArt } from "./default-item-art.mjs";
+export { AFFILIATION_STANDINGS } from "./affiliation-standings.mjs";
+export {
+    BEING_TYPE,
+    GEAR_TYPE_TO_KEY,
+    deriveBeingInfo,
+    isBeing,
+} from "./being-info.mjs";

package/sohl/item-builders.mjs

@@ -0,0 +1,114 @@
+/*
+ * 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
+ */
+
+/**
+ * **The item-type registry** — every content type that compiles into a Foundry
+ * Item, keyed to the builder that produces its `system` block.
+ *
+ * There is one list, not two. This repository hands {@link ITEM_BUILDERS} to
+ * the build as `itemBuilders` in `package-build.config.yaml`, and `itemTypes()`
+ * — the whitelist — is derived from that table's own keys, so a type cannot be
+ * whitelisted for compilation without a builder to compile it. Previously the
+ * whitelist and the builder table were maintained by hand and had already
+ * drifted: `trait` — an item type **retired in #651**, absent from
+ * `documentTypes.Item` and reported by world migration as unrecognized — was
+ * still advertised as compilable, so a `type: trait` note passed the gate and
+ * then died on `BUILDERS[type] is not a function`, swallowed as a per-file
+ * error (#1504).
+ *
+ * **The builders are generated, not written.** Each type's `system` builder
+ * comes from its field declaration in `item-fields.mjs` by way of
+ * {@link buildFromFields}, so the vocabulary a note may write is readable data
+ * rather than statements buried in a function body — which is what lets the
+ * authoring reference be generated and a note be linted against its type
+ * (#22). One consequence worth naming: the registry's keys are now
+ * {@link ITEM_FIELDS}'s keys, so adding an item type is one edit *there* (plus
+ * its `documentTypes.Item` declaration and its default art), and removing one
+ * is likewise a single deletion.
+ *
+ * **A leaf module, and the reason the seam works.** It imports only the pure
+ * declaration primitives and the field table — never `helpers.mjs`, and never
+ * the resolved configuration. The config file imports *this* module, so a read
+ * back out of the configuration here would close a cycle around the config's
+ * own evaluation. The table travels into configuration; the engine's
+ * `item-registry.mjs` reads it back out and the Item compiler dispatches
+ * through that, which is how a consumer's own table is the one its notes
+ * compile with (#1563).
+ */
+
+import { defaultItemArt } from "./default-item-art.mjs";
+import { buildFromFields, readField } from "../engine/field-spec.mjs";
+import { COMBAT_TECHNIQUE_STRIKE_MODE, ITEM_FIELDS } from "./item-fields.mjs";
+
+/**
+ * The conditionals a flat field list cannot state, keyed by item type.
+ *
+ * A finalizer runs after the declaration has produced the `system` block, and
+ * exists only for a field whose *presence* depends on another field's value.
+ * There is exactly one: a combat technique is authored as a `skill` of subtype
+ * `combattechnique`, and carries a strike mode that no other skill has.
+ *
+ * Keeping this list short is the point. Anything expressible as a field
+ * declaration is said there, where a generator and a linter can read it; a
+ * finalizer is opaque again, so it earns its place one conditional at a time.
+ *
+ * @type {Readonly<Record<string, (fm: object, out: object) => object>>}
+ */
+const FINALIZERS = Object.freeze({
+    skill(fm, out) {
+        if (out.subType === "combattechnique") {
+            out.strikeMode = readField(COMBAT_TECHNIQUE_STRIKE_MODE, fm);
+        }
+        return out;
+    },
+});
+
+/**
+ * Build one registry entry: the declared fields, the builder they generate, and
+ * the default art for the type.
+ *
+ * Reading {@link defaultItemArt} here is what makes the two lists one: this
+ * module cannot name a type the art map does not cover, because that function
+ * throws and this module evaluates at import. A drift that a test used to catch
+ * is unrepresentable.
+ *
+ * Importing the art map keeps this module a leaf — it is plain data, not the
+ * resolved configuration, and the cycle the module note above warns about is
+ * only ever closed by reading configuration back out.
+ *
+ * @param {string} type - The item type, and the art map's key.
+ * @returns {Readonly<{system: (fm: object) => object, img: string, fields: readonly object[]}>}
+ *   The registry entry.
+ */
+function entryFor(type) {
+    const fields = ITEM_FIELDS[type];
+    const build = buildFromFields(fields);
+    const finalize = FINALIZERS[type];
+    return Object.freeze({
+        system: finalize ? (fm) => finalize(fm, build(fm)) : build,
+        img: defaultItemArt(type),
+        fields,
+    });
+}
+
+/**
+ * Every item type, paired with the builder for its `system` block, the default
+ * art for the type, and the frontmatter fields it declares.
+ *
+ * @type {Readonly<Record<string, Readonly<{system: (fm: object) => object, img: string, fields: readonly object[]}>>>}
+ */
+export const ITEM_BUILDERS = Object.freeze(
+    Object.fromEntries(
+        Object.keys(ITEM_FIELDS).map((type) => [type, entryFor(type)]),
+    ),
+);