@heroiclands/package-build 8.1.0 → 10.0.0

package/e2e.mjs

@@ -93,9 +93,7 @@ const EXACT_BUILD = /^\d+\.\d+$/;
  * @returns {string} The hex hash.
  */
 export function hashPassword(password, salt) {
-    return crypto
-        .pbkdf2Sync(password, salt, 1000, 64, "sha512")
-        .toString("hex");
+    return crypto.pbkdf2Sync(password, salt, 1000, 64, "sha512").toString("hex");
 }
 
 /**
@@ -127,23 +125,13 @@ export function resolveE2EWorld(config, env = process.env) {
     const world = config.e2eWorld ?? {};
     const gm = config.e2eGm ?? {};
     return {
-        worldId:
-            env[`${prefix}WORLD_ID`]?.trim() ||
-            world.id ||
-            `${config.packageId}-e2e`,
-        worldTitle:
-            env[`${prefix}WORLD_TITLE`]?.trim() ||
-            world.title ||
-            `${config.packageId} E2E`,
+        worldId: env[`${prefix}WORLD_ID`]?.trim() || world.id || `${config.packageId}-e2e`,
+        worldTitle: env[`${prefix}WORLD_TITLE`]?.trim() || world.title || `${config.packageId} E2E`,
         worldDescription:
-            world.description ||
-            `Disposable world for ${config.packageId} end-to-end tests.`,
+            world.description || `Disposable world for ${config.packageId} end-to-end tests.`,
         gmId: E2E_GM_ID,
         gmName: env[`${prefix}GM_NAME`]?.trim() || gm.name || "Gamemaster",
-        gmPassword:
-            env[`${prefix}GM_PASSWORD`]?.trim() ||
-            gm.password ||
-            `${config.packageId}-e2e`,
+        gmPassword: env[`${prefix}GM_PASSWORD`]?.trim() || gm.password || `${config.packageId}-e2e`,
     };
 }
 
@@ -330,8 +318,7 @@ export function parseFastArgs(argv, build) {
 
     for (let i = 0; i < own.length; i += 1) {
         const arg = /** @type {string} */ (own[i]);
-        if (arg.startsWith("--build="))
-            requested = arg.slice("--build=".length);
+        if (arg.startsWith("--build=")) requested = arg.slice("--build=".length);
         else if (arg === "--recreate") recreate = true;
         else if (arg === "--no-run") runSuite = false;
         else if (arg === "--spec") {
@@ -387,12 +374,7 @@ export function parseFastArgs(argv, build) {
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {Promise<{worldDir: string, world: E2EWorld}>} Where it landed.
  */
-export async function seedTestWorld({
-    config,
-    packageJson,
-    env = process.env,
-    log = () => {},
-}) {
+export async function seedTestWorld({ config, packageJson, env = process.env, log = () => {} }) {
     const stage = config.e2eStage;
     const dataRoot = requireIsolatedDataRoot(stage, env);
     const world = resolveE2EWorld(config, env);
@@ -530,13 +512,7 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * @returns {Promise<void>} Resolves once the world is active.
  * @throws {Error} On a licence failure or a timeout.
  */
-export async function waitForWorld({
-    url,
-    container,
-    stage,
-    timeoutMs = 180_000,
-    log = () => {},
-}) {
+export async function waitForWorld({ url, container, stage, timeoutMs = 180_000, log = () => {} }) {
     const join = `${url}/join`;
     const deadline = Date.now() + timeoutMs;
     log(`Waiting for the world at ${join} …`);
@@ -597,27 +573,17 @@ function captureContainerLog(container) {
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {number} The suite's exit status.
  */
-export function runSuite({
-    command,
-    args = [],
-    cwd,
-    env = process.env,
-    log = () => {},
-}) {
+export function runSuite({ command, args = [], cwd, env = process.env, log = () => {} }) {
     const [program, ...rest] = command;
     const childEnv = { ...env };
     delete childEnv.ELECTRON_RUN_AS_NODE;
     log(`▸ ${[...command, ...args].join(" ")}`);
-    const result = spawnSync(
-        /** @type {string} */ (program),
-        [...rest, ...args],
-        {
-            stdio: "inherit",
-            cwd,
-            env: childEnv,
-            shell: process.platform === "win32",
-        },
-    );
+    const result = spawnSync(/** @type {string} */ (program), [...rest, ...args], {
+        stdio: "inherit",
+        cwd,
+        env: childEnv,
+        shell: process.platform === "win32",
+    });
     if (result.error) throw result.error;
     return result.status ?? 1;
 }
@@ -756,12 +722,7 @@ export async function e2eRun({
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {Promise<number>} The suite's exit status.
  */
-export async function e2eFast({
-    config,
-    argv = [],
-    env = process.env,
-    log = () => {},
-}) {
+export async function e2eFast({ config, argv = [], env = process.env, log = () => {} }) {
     const {
         targets,
         recreate,

package/engine/address-charset.mjs

@@ -0,0 +1,62 @@
+/*
+ * 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 one charset every segment of a canonical address is held to (#59).
+ *
+ * An address is a hyphen-joined tuple — `sohl-skill-clmb` — and it is read back
+ * by **counting segments**, with a fixed meaning per position. That is sound
+ * for exactly one reason: the hyphen is *purely* a separator, because no
+ * segment may contain one. Take that away and reading an address needs a
+ * vocabulary to match against, a longest-match rule, and an answer for every
+ * name that is a prefix of another — none of which exist.
+ *
+ * So the charset is not a tidiness rule. It is the premise the address grammar
+ * rests on, and the issue's word for how it should be held is **enforced rather
+ * than assumed**: a value that breaks it is refused where it is written, not
+ * discovered later as addresses that fail to parse and report nothing about
+ * why. `harn-adventures` was that case — its keys read as four segments and
+ * failed as a `null` return.
+ *
+ * This module is a **leaf with no local imports**, so the validator a
+ * consumer's `package-build.config.mjs` reaches (`content-config.mjs`) can name
+ * it without closing a cycle around that file.
+ *
+ * @module
+ */
+
+/**
+ * The shape every address segment must match: ASCII letters and digits only.
+ *
+ * Case is deliberately **not** constrained. Hundreds of authored shortcodes are
+ * mixed-case and collide with nothing, and case has no bearing on the
+ * separator, which is the whole of what this pattern is protecting.
+ *
+ * @type {RegExp}
+ */
+export const ADDRESS_SEGMENT_PATTERN = /^[A-Za-z0-9]+$/;
+
+/**
+ * Whether a value is a well-formed address segment.
+ *
+ * A blank value is **not** valid: this answers "is this an acceptable segment",
+ * never "is a segment present". Presence is a separate question, asked
+ * wherever the value is required, and conflating the two would report a missing
+ * key as a charset violation.
+ *
+ * @param {unknown} value - The candidate segment.
+ * @returns {boolean} `true` when it matches {@link ADDRESS_SEGMENT_PATTERN}.
+ */
+export function isAddressSegment(value) {
+    return typeof value === "string" && ADDRESS_SEGMENT_PATTERN.test(value);
+}

package/engine/address-diff.mjs

@@ -198,10 +198,7 @@ export function diffItemAddresses(baseline, current, { baseline: label }) {
 export function noteFilesById(contentBase, { skipDirectories } = {}) {
     const byId = new Map();
     const walkOpts = skipDirectories ? { skipDirectories } : undefined;
-    for (const { frontmatter: fm, absPath } of walkMarkdownTree(
-        contentBase,
-        walkOpts,
-    )) {
+    for (const { frontmatter: fm, absPath } of walkMarkdownTree(contentBase, walkOpts)) {
         if (fm?.id && !byId.has(fm.id)) byId.set(fm.id, absPath);
     }
     return byId;

package/engine/alias-index.mjs

@@ -0,0 +1,153 @@
+/*
+ * 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 **alias** namespace: what a note can be called, and who may claim a name.
+ *
+ * A wikilink resolves through one of two namespaces, and the pipe chooses
+ * which (#131): `[[x|…]]` is an *address*, parsed by the address grammar;
+ * `[[x]]` is an *alias*, looked up here. This module owns the second half —
+ * what goes into the index, how a key is spelled, and what happens when two
+ * notes claim one name.
+ *
+ * **An alias is scoped to the claiming note's own type.** The key is
+ * `(type, alias)`, so `Shock` may be a `skill` in one place and a `trauma` in
+ * another without the two ever meeting. A link resolves against the *source*
+ * note's type, which is why a bare name reaches a sibling and never a
+ * cross-type target — that one is written as an address.
+ *
+ * **Three sources, all authored.** `aliases`, `name.aliases`, and `name.full`.
+ * Each is something a person wrote down as a name for the note, which is
+ * exactly what a bare `[[…]]` cites.
+ *
+ * **The filename is deliberately not one of them**, and it used to be — every
+ * one of the three copies of this index added `basename(file, ".md")` with
+ * underscores turned to spaces. That admitted keys no author could ever cite
+ * and no author had ever written:
+ *
+ * - `_Introduction.md` yields the alias `" introduction"`, *with a leading
+ *   space*. A wikilink target is trimmed, so nothing can ever match it. In one
+ *   repository thirteen notes — one per documentation section — claimed that
+ *   key, making it the largest alias collision in the corpus and every one of
+ *   its claimants blameless.
+ * - `README.md` yields `readme`, claimed once per section for the same reason.
+ *
+ * Since a collision is now a build failure rather than a silent deletion, an
+ * index entry that cannot be cited can only ever *cause* one. Removing the
+ * source was measured first, across all five content trees: not one link that
+ * resolves today resolves through the filename alone, so nothing loses a
+ * target — while the collision count falls without a note being edited.
+ *
+ * @module
+ */
+
+/**
+ * Every alias a note claims, in the order the sources are consulted.
+ *
+ * @param {object} fm - Parsed frontmatter.
+ * @returns {string[]} The claimed aliases, each a non-empty string.
+ */
+export function aliasesOf(fm) {
+    return [
+        ...(Array.isArray(fm?.aliases) ? fm.aliases : []),
+        ...(Array.isArray(fm?.name?.aliases) ? fm.name.aliases : []),
+        fm?.name?.full,
+    ].filter((a) => typeof a === "string" && a);
+}
+
+/**
+ * The index key one note's claim on one alias is filed under.
+ *
+ * Stated here so the three indexes — the pack build's, the site build's and
+ * the link checker's — cannot spell it differently. All three already used
+ * `type|alias`, lowercased; the risk was never that they disagreed today.
+ *
+ * @param {string} type - The claiming note's content type.
+ * @param {string} alias - The alias, as authored.
+ * @returns {string} The key.
+ */
+export function aliasKey(type, alias) {
+    return `${String(type).trim()}|${String(alias).trim()}`.toLowerCase();
+}
+
+/**
+ * One alias claimed by more than one note of a single type.
+ *
+ * @typedef {object} AliasCollision
+ * @property {string} key - The index key, `type|alias`.
+ * @property {string} type - The type both claimants share.
+ * @property {string} alias - The alias, as the first claimant wrote it.
+ * @property {unknown[]} claimants - Every note claiming it, in walk order.
+ */
+
+/**
+ * Build the type-scoped alias index, and report every collision in it.
+ *
+ * **A collision resolves to nothing, and is reported naming every claimant.**
+ * Both halves matter. Resolving to whichever note happened to be walked first
+ * makes a link silently point at the wrong document, and which one it is
+ * depends on directory order. Reporting it at the *citing* note blames a file
+ * whose author did nothing wrong — whoever added the second claimant broke
+ * every existing citation (#13) — so the claimants are kept rather than
+ * discarded along with the entry.
+ *
+ * @template T
+ * @param {Iterable<{type: string, aliases: Iterable<string>, value: T}>} entries
+ *   One per note: the type that scopes its claims, the aliases it claims, and
+ *   whatever the caller wants an alias to resolve to.
+ * @param {object} [opts]
+ * @param {(a: T, b: T) => boolean} [opts.same] - Whether two values are the
+ *   same note. Defaults to identity; a caller whose values are freshly built
+ *   records supplies its own.
+ * @returns {{byKey: Map<string, T>, claims: Map<string, T[]>,
+ *   collisions: AliasCollision[]}} `byKey` omits every colliding key, so a
+ *   lookup in it can never resolve an ambiguous alias.
+ */
+export function indexAliases(entries, { same = Object.is } = {}) {
+    const claims = new Map();
+    /** The alias as first written, per key, for a message that reads. */
+    const written = new Map();
+    const typeOf = new Map();
+
+    for (const { type, aliases, value } of entries) {
+        for (const alias of aliases ?? []) {
+            if (typeof alias !== "string" || !alias) continue;
+            const key = aliasKey(type, alias);
+            const claimants = claims.get(key);
+            if (!claimants) {
+                claims.set(key, [value]);
+                written.set(key, alias);
+                typeOf.set(key, String(type).toLowerCase());
+            } else if (!claimants.some((c) => same(c, value))) {
+                claimants.push(value);
+            }
+        }
+    }
+
+    const byKey = new Map();
+    const collisions = [];
+    for (const [key, claimants] of claims) {
+        if (claimants.length === 1) {
+            byKey.set(key, claimants[0]);
+        } else {
+            collisions.push({
+                key,
+                type: typeOf.get(key),
+                alias: written.get(key),
+                claimants,
+            });
+        }
+    }
+
+    return { byKey, claims, collisions };
+}