@heroiclands/package-build 0.6.0 → 3.0.0

package/engine/frontmatter.mjs

@@ -0,0 +1,258 @@
+/*
+ * 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
+ */
+
+/**
+ * **Frontmatter readers** — the pure functions that read a content note's
+ * `sohl:` block and normalize what they find.
+ *
+ * Split out of `helpers.mjs` as a **leaf module**: its only import is a frozen
+ * list of constants, so the
+ * item-type registry (`item-builders.mjs`) can build on it without dragging in
+ * `helpers.mjs`, which reaches wikilinks — and through them back to
+ * `item-docs.mjs`, the very module that derives `itemTypes()` from the registry
+ * (#1504). Keeping these readers dependency-free is what makes that one-way.
+ *
+ * `helpers.mjs` re-exports everything here, so existing importers are
+ * unaffected: there is still one name for each reader.
+ */
+
+// The affiliation standings an authored `relation` map may use. Read from the
+// build package rather than restated here, so the pipeline and the runtime
+// enum cannot drift apart (#1510) — a value absent from the list is a build
+// error, never a silent ship.
+import { AFFILIATION_STANDINGS } from "../sohl/affiliation-standings.mjs";
+
+/**
+ * Resolves a dotted frontmatter key (e.g., "name.full") into the nested
+ * value. Returns `defaultValue` if any path segment is missing.
+ */
+export function getFrontmatter(fm, key, defaultValue = undefined) {
+    if (fm == null || typeof fm !== "object") return defaultValue;
+    if (key in fm) return fm[key];
+    const parts = key.split(".");
+    let current = fm;
+    for (const part of parts) {
+        if (current == null || typeof current !== "object") return defaultValue;
+        current = current[part];
+    }
+    return current !== undefined ? current : defaultValue;
+}
+
+/**
+ * Reads a key from `fm.sohl` (the vault's nested system-fields block).
+ * Supports dotted notation, e.g. sohlField(fm, "charges.value", 0).
+ * Falls back to top-level `fm[key]` if `sohl` doesn't carry the key.
+ */
+export function sohlField(fm, key, defaultValue = undefined) {
+    if (fm == null || typeof fm !== "object") return defaultValue;
+    const sohl = fm.sohl;
+    if (sohl && typeof sohl === "object") {
+        if (key in sohl) return sohl[key] ?? defaultValue;
+        const fromNested = getFrontmatter(sohl, key, undefined);
+        if (fromNested !== undefined) return fromNested;
+    }
+    return getFrontmatter(fm, key, defaultValue);
+}
+
+/**
+ * Read a frontmatter property that is authored as a **map**, returning its
+ * entries — or `null` when the note authors none.
+ *
+ * Obsidian's property editor serializes an **emptied map as an empty list**, so
+ * a note whose map property was ever touched and cleared in the editor arrives
+ * as `[]`, not `{}`. The two spellings mean the same thing — this note authors
+ * no entries — and a build that accepted only one of them failed on notes the
+ * editor itself had produced (#8; 44 affiliation notes in `sohl-thalorna`).
+ * Normalizing the notes would fix only today's tree: the next editor touch puts
+ * the empty list back.
+ *
+ * A **populated** array is still malformed, and stays the caller's error to
+ * raise: a list of entries is not a map, and quietly dropping them is the
+ * silent data loss these readers exist to prevent.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} key - The property name, read via {@link sohlField}.
+ * @returns {[string, unknown][] | null} The property's entries — empty when the
+ *   note authors none — or `null` when the value is not a map.
+ */
+function readMapEntries(fm, key) {
+    const raw = sohlField(fm, key, undefined);
+    if (raw == null) return [];
+    if (Array.isArray(raw)) return raw.length === 0 ? [] : null;
+    if (typeof raw !== "object") return null;
+    return Object.entries(raw);
+}
+
+/**
+ * Resolve the `charges` block shared by Mystery and Mystical Ability items.
+ *
+ * Charge usage is carried by the **maximum** alone (#1129): a `null` max means
+ * the item does not use charges at all, `0` means it is counted but uncapped,
+ * and a positive number is a real cap. `value` is the current count, with
+ * `null` meaning "infinite remaining". Both persist as nullable NumberFields,
+ * so absent frontmatter must resolve to `null` — coercing it to `0` would ship
+ * every item as an uncapped charge-user.
+ *
+ * A legacy `usesCharges` flag in authored frontmatter is ignored: it was inert
+ * and has been dropped from the schema.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @returns {{value: number|null, max: number|null}} The persisted charges block.
+ */
+export function resolveCharges(fm) {
+    const toCount = (raw) => {
+        if (raw == null || raw === "") return null;
+        const num = Number(raw);
+        return Number.isFinite(num) ? Math.trunc(num) : null;
+    };
+    const max = toCount(sohlField(fm, "charges.max", null));
+    // A blank maximum means "does not use charges" — a stray current count
+    // cannot outlive it, since the logic layer disables both modifiers.
+    return {
+        value:
+            max === null ? null : toCount(sohlField(fm, "charges.value", null)),
+        max,
+    };
+}
+
+/**
+ * Resolve an item's `skillAptitudes` map — selector → mastery-level modifier,
+ * where a selector is a skill shortcode or `subType:<value>`.
+ *
+ * Authored values must be whole numbers: the persisted field is an integer
+ * `NumberField`, and a fractional or non-numeric entry would be silently
+ * coerced at load, shipping an aptitude nobody authored. A malformed entry is a
+ * build error rather than a rounded surprise. A `0` is legitimate and must be
+ * kept — an element a sign leaves untouched still beats one another sign
+ * hinders, so it carries real weight when maps merge.
+ *
+ * An absent property, an empty map, and the empty **list** Obsidian's property
+ * editor writes for a cleared map all mean the same thing — see
+ * {@link readMapEntries}.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} [ctx] - Label for the error (defaults to "item").
+ * @returns {Record<string, number>} The persisted aptitude map (empty when
+ *   the item authors none).
+ * @throws {Error} When the value is not a map, or a value is not an integer.
+ */
+export function resolveSkillAptitudes(fm, ctx = "item") {
+    const entries = readMapEntries(fm, "skillAptitudes");
+    if (entries === null) {
+        throw new Error(
+            `${ctx}: skillAptitudes must be a map of selector → number`,
+        );
+    }
+    const out = {};
+    for (const [selector, value] of entries) {
+        const num = Number(value);
+        if (!Number.isInteger(num)) {
+            throw new Error(
+                `${ctx}: skillAptitudes["${selector}"] must be a whole number, got "${value}"`,
+            );
+        }
+        out[selector] = num;
+    }
+    return out;
+}
+
+/**
+ * Resolve an affiliation's `relation` map — the shortcode of another
+ * affiliation → this one's standing toward it (#1404).
+ *
+ * An unrecognized standing would fail the schema's `choices` validation at load
+ * and be dropped silently, shipping an affiliation whose authored hostility had
+ * quietly become neutrality — so it is a build error instead.
+ *
+ * An absent property, an empty map, and the empty **list** Obsidian's property
+ * editor writes for a cleared map all mean the same thing — neutral toward
+ * everyone. See {@link readMapEntries}.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} [ctx] - Label for the error (defaults to "item").
+ * @returns {Record<string, string>} The persisted relation map (empty when the
+ *   affiliation authors none — neutral toward everyone).
+ * @throws {Error} When the map is malformed or names an unknown standing.
+ */
+export function resolveRelation(fm, ctx = "item") {
+    const entries = readMapEntries(fm, "relation");
+    if (entries === null) {
+        throw new Error(
+            `${ctx}: relation must be a map of shortcode → standing`,
+        );
+    }
+    const out = {};
+    for (const [code, value] of entries) {
+        const standing = String(value);
+        if (!AFFILIATION_STANDINGS.includes(standing)) {
+            throw new Error(
+                `${ctx}: relation["${code}"] must be one of ${AFFILIATION_STANDINGS.join(", ")}, got "${value}"`,
+            );
+        }
+        out[code] = standing;
+    }
+    return out;
+}
+
+/**
+ * Read the mandatory `subType` from an item's frontmatter, throwing when it is
+ * absent or blank.
+ *
+ * Every subType-bearing item type declares `subType` as `required` with **no**
+ * default in its DataModel — a subtype must always be specified, and it is an
+ * error to omit it. The builder therefore substitutes no fallback: a content
+ * file missing `subType` is a build error, surfaced here rather than shipped as
+ * an invalid (typeless-fallback) item.
+ *
+ * @param {object} fm - The item frontmatter.
+ * @param {string} [ctx] - Optional label for the error (defaults to the item's
+ *   title/name, else "item").
+ * @returns {string} The declared subType.
+ * @throws {Error} When `subType` is missing or blank.
+ */
+export function requireSubType(fm, ctx) {
+    const subType = sohlField(fm, "subType", undefined);
+    if (subType == null || subType === "") {
+        const label = ctx || fm?.title || fm?.name || "item";
+        throw new Error(
+            `${label}: missing required 'subType' — every subType-bearing item must declare its kind (the builder substitutes no default).`,
+        );
+    }
+    return String(subType);
+}
+
+/**
+ * Parses the valueDesc / threshold array format. Accepts either:
+ *   - Array of "Label:MaxValue" strings, e.g. ["Ugly:4", "Plain:12"]
+ *   - Array of objects, e.g. [{ label, maxValue }]
+ * Returns a normalized array of `{ label, maxValue: number }`.
+ */
+export function parseValueDesc(raw) {
+    if (!raw || !Array.isArray(raw)) return [];
+    return raw.map((entry) => {
+        if (typeof entry === "string") {
+            const [label, maxStr] = entry.split(":");
+            return {
+                label: (label ?? "").trim(),
+                maxValue: parseInt(maxStr, 10) || 0,
+            };
+        }
+        if (typeof entry === "object" && entry?.label !== undefined) {
+            return {
+                label: String(entry.label),
+                maxValue: Number(entry.maxValue) || 0,
+            };
+        }
+        return { label: String(entry), maxValue: 0 };
+    });
+}

package/engine/generate.mjs

@@ -0,0 +1,305 @@
+/*
+ * 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
+ */
+
+/**
+ * Pack JSON generation — in-repo Markdown → per-entry JSON (build-only).
+ *
+ * Reads the authoritative content tree at the configured content root and
+ * compiles each pack's entries to per-entry JSON under its build directory
+ * (`build/packs-json/<pack>/` in this repository). The JSON is
+ * a disposable build intermediate consumed by `build:compiledb` (which turns it
+ * into the shipped LevelDB packs) — it is never committed.
+ *
+ * Each `*` compiler walks the whole content tree and selects its own entries by
+ * frontmatter (a `package:` matching the configured `contentPackage` + `type`),
+ * so routing is directory-agnostic: a file lands in a pack because of its
+ * `type`, not its location. Which packs exist, in what order, and which folder
+ * hierarchy each one loads are all declared in `package-build.config.yaml`;
+ * folder files live under the content root and are referenced from entry
+ * frontmatter via `sohl.folder: <id>`.
+ *
+ * This replaces the retired `packs:export` (vault → committed `_source/`); the
+ * HeroicLands vault is no longer a build input for SoHL content.
+ */
+
+import fs from "fs";
+import path from "path";
+import log from "loglevel";
+
+import { foreignItemCatalogDirs } from "./foreign-catalog.mjs";
+
+import { Items } from "../sohl/items.mjs";
+import { Journals } from "./journals.mjs";
+import { Actors } from "../sohl/actors.mjs";
+import { Macros } from "./macros.mjs";
+import { Scenes } from "./scenes.mjs";
+import {
+    buildStats,
+    loadFolders,
+    buildFolderResolver,
+    writeFolderDocs,
+} from "./helpers.mjs";
+import { countContentNotes } from "./content-tree.mjs";
+import { loadPackConfig } from "./pack-config.mjs";
+import { routerFor } from "./pack-router.mjs";
+
+/**
+ * The compiler class for each Foundry document type a pack may hold.
+ *
+ * The pack list is data (`package-build.config.yaml`), so the one thing it
+ * cannot carry is the code that compiles it — a document type maps to its
+ * compiler here. Unknown types fail the build rather than defaulting, so a pack
+ * declaring a type nothing can compile is loud at the first pass instead of
+ * shipping empty.
+ */
+const COMPILERS = {
+    Item: Items,
+    JournalEntry: Journals,
+    Actor: Actors,
+    Macro: Macros,
+    Scene: Scenes,
+};
+
+/**
+ * Root of the build-only JSON tree for one pack.
+ *
+ * @param {string} name - The pack name.
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @returns {string} The pack's JSON directory.
+ */
+export const packJsonDir = (name, config = loadPackConfig()) =>
+    path.join(config.paths.packJson, name);
+
+/**
+ * The generated JSON of **every** configured Item pack — what the actors pass
+ * reads its predefined items from.
+ *
+ * All of them, not the first: a repository may ship several Item packs (#1566),
+ * and an actor's embedded items may be sourced from any of them. Finding one
+ * pack and stopping is how embedded-item resolution would silently miss every
+ * item that landed in another. Returned in configured order, which is also the
+ * order they compile in, so a pack later in the list cannot be read before it
+ * is written.
+ *
+ * @param {object} [config] - The resolved build configuration. Defaults to this
+ *   repository's.
+ * @returns {string[]} Each Item pack's JSON directory. Empty when the
+ *   repository ships no items at all — the actors pass, which is the only
+ *   caller that needs one, refuses that itself.
+ */
+export function itemPackJsonDirs(config = loadPackConfig()) {
+    return config.packs
+        .filter((pack) => pack.type === "Item")
+        .map((pack) => packJsonDir(pack.name, config));
+}
+
+/**
+ * Generate the per-entry JSON for one pack into `build/packs-json/<name>/`.
+ *
+ * @param {object} pack - One entry of the configured pack list.
+ * @param {object} config - The resolved build configuration.
+ * @param {object} router - The pack router, which decides which pack of this
+ *     pass's document type each claimed note belongs in.
+ * @param {boolean} routingReporter - Whether this pass reports a note of its
+ *     document type that routes nowhere. True for the first configured pack of
+ *     the type, so one unroutable note yields one error rather than one per
+ *     pack.
+ * @returns {Promise<{errors: number, compiled: number}>} The compiler's error
+ *     count (0 on success) and the number of entries it wrote.
+ */
+async function generatePack(
+    { name, type, folders, companions },
+    config,
+    router,
+    routingReporter,
+) {
+    const contentBase = config.paths.content;
+    const dest = packJsonDir(name, config);
+
+    const packClass = COMPILERS[type];
+    if (!packClass) {
+        log.error(
+            `Pack ${name}: no compiler for document type "${type}" — the ` +
+                `configured pack list names a type this toolchain cannot compile.`,
+        );
+        return { errors: 1, compiled: 0 };
+    }
+
+    log.info(`Pack ${name}: ${contentBase} → ${dest}`);
+
+    let folderList;
+    let resolver;
+    try {
+        folderList =
+            folders ? loadFolders(path.join(contentBase, folders)) : [];
+        ({ resolver } = buildFolderResolver(folderList));
+    } catch (err) {
+        log.error(`${name} ${folders} validation failed: ${err.message}`);
+        return { errors: 1, compiled: 0 };
+    }
+
+    // Wipe and recreate so removed content notes leave no stale JSON.
+    fs.rmSync(dest, { recursive: true, force: true });
+    fs.mkdirSync(dest, { recursive: true });
+
+    // A companion pack is written by the same pass — the scenes pass also emits
+    // the adventures that bundle them — so it is wiped on the same schedule.
+    const companionDests = {};
+    for (const companion of companions) {
+        const companionDest = packJsonDir(companion.name, config);
+        fs.rmSync(companionDest, { recursive: true, force: true });
+        fs.mkdirSync(companionDest, { recursive: true });
+        companionDests[companion.name] = companionDest;
+    }
+
+    writeFolderDocs(folderList, buildStats(undefined, config), dest, type);
+
+    const pack = new packClass({
+        contentBase,
+        dest,
+        companionDests,
+        // The actors pass resolves each being's embedded items against the items
+        // passes' output. That used to be an unwritten sibling-directory contract
+        // (`path.resolve(dest, "..", "items")`); the configured pack list names
+        // the Item packs, so the dependency is stated rather than assumed
+        // (#1508) — and it is every Item pack, since a repository may ship more
+        // than one (#1566).
+        itemsSourceDirs: itemPackJsonDirs(config),
+        // The catalogue of a package this repository depends on but does
+        // not contain, for a repository that authors beings without
+        // holding the items they are assembled from. Cache-only: a cold
+        // cache throws naming `content-build deps fetch` rather than
+        // downloading inside a compile.
+        foreignSourceDirs: foreignItemCatalogDirs(config),
+        folderResolver: resolver,
+        packName: name,
+        docType: type,
+        router,
+        routingReporter,
+    });
+    await pack.compile();
+    return { errors: pack.errorCount, compiled: pack.compiledCount };
+}
+
+/**
+ * The passes that compiled nothing when they were expected to compile
+ * something — a build failure, not a quiet no-op.
+ *
+ * A pack compiler selects its entries by the configured content package, so a
+ * single wrong package id rejects every note in a perfectly good tree and every
+ * pack ships blank while the build exits 0 (#1502). The empty-tree guard in
+ * {@link generatePacksJson} cannot see that: the tree is full, it is the
+ * *output* that is empty.
+ *
+ * @param {Array<{name: string, compiled: number, mayBeEmpty?: boolean}>} passes -
+ *     One entry per generated pack.
+ * @returns {string[]} One message per pass that must not have been empty.
+ */
+export function emptyPassErrors(passes) {
+    return passes
+        .filter((pass) => !pass.mayBeEmpty && pass.compiled === 0)
+        .map(
+            (pass) =>
+                `Pack "${pass.name}" compiled 0 entries from a non-empty ` +
+                `content tree. Every note was rejected — check that the notes ` +
+                `declare the package this build compiles (\`contentPackage\` in ` +
+                `package-build.config.yaml), or declare the pack ` +
+                `\`mayBeEmpty\` if it genuinely ships nothing.`,
+        );
+}
+
+/**
+ * Generate the build-only JSON for every pack (or one, when `only` is given).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.only] - Restrict to a single pack name.
+ * @param {object} [opts.config] - The resolved build configuration. Defaults to
+ *   this repository's. Supplying one is how a caller compiles a *different*
+ *   package's tree — and how the guard-order test below induces id drift, now
+ *   that the manifest is located by configuration rather than by the working
+ *   directory.
+ * @returns {Promise<number>} Total error count across the generated packs.
+ * @throws {Error} If the configured Foundry package id has drifted from the
+ *   shipped manifest's `id` (see `package-manifest.mjs`).
+ */
+export async function generatePacksJson({
+    only,
+    config = loadPackConfig(),
+} = {}) {
+    // Before anything is generated: every UUID written below is addressed to
+    // the configured `foundryPackage`, so a value that has drifted from the shipped
+    // manifest's `id` produces a whole pack of links that resolve nowhere.
+    // Throws rather than counting an error — there is nothing worth compiling.
+    //
+    const contentBase = config.paths.content;
+    if (!fs.existsSync(contentBase)) {
+        log.error(`Content tree not found at ${contentBase}.`);
+        return 1;
+    }
+    // A tree that is present but empty compiles zero documents *without an
+    // error*, and ships blank compendiums. Refuse instead: this only happens
+    // when the generated tree was never exported, or exported from the wrong
+    // place, and neither is something to build on.
+    const noteCount = countContentNotes(contentBase);
+    if (noteCount === 0) {
+        log.error(
+            `Content tree at ${contentBase} holds no notes, so every pack would ` +
+                `compile empty. The configured content root is ` +
+                `this repository's own source — check out the tree.`,
+        );
+        return 1;
+    }
+    log.info(`Content tree: ${noteCount} note(s) at ${contentBase}`);
+    fs.mkdirSync(config.paths.packJson, { recursive: true });
+
+    // A companion pack has no pass of its own — naming it selects the pass that
+    // writes it, so `compile adventures` is not a silent no-op.
+    const packs = config.packs.filter(
+        (pack) =>
+            !only ||
+            pack.name === only ||
+            pack.companions.some((companion) => companion.name === only),
+    );
+    // One router per configuration, so every pass agrees about where a note
+    // goes, and the first pack of each document type owns the error message for
+    // a note of that type that goes nowhere.
+    const router = routerFor(config);
+    const firstOfType = new Map();
+    for (const pack of config.packs) {
+        if (!firstOfType.has(pack.type)) firstOfType.set(pack.type, pack.name);
+    }
+
+    let totalErrors = 0;
+    const passes = [];
+    for (const pack of packs) {
+        const { errors, compiled } = await generatePack(
+            pack,
+            config,
+            router,
+            firstOfType.get(pack.type) === pack.name,
+        );
+        totalErrors += errors;
+        passes.push({
+            name: pack.name,
+            compiled,
+            mayBeEmpty: pack.mayBeEmpty,
+        });
+    }
+
+    for (const message of emptyPassErrors(passes)) {
+        log.error(message);
+        totalErrors++;
+    }
+    return totalErrors;
+}