@heroiclands/package-build 0.6.0 → 3.0.0

package/engine/content-lint.mjs

@@ -0,0 +1,204 @@
+/*
+ * 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
+ */
+
+/**
+ * Linting a content tree's **addresses** — the rules every package's notes are
+ * authored against, wherever those notes live.
+ *
+ * These rules used to live in the SoHL repository's `utils/`, which had two
+ * consequences and no upside (#20). `thalorna` and `kethira` notes were checked
+ * by nothing at all, so the packages most likely to carry authoring mistakes
+ * were the ones nothing inspected. And one rule with two implementations can
+ * disagree without anything detecting it, which the canonical-separator
+ * handling already did once on each side.
+ *
+ * Two rules, both about a note's identity:
+ *
+ * 1. **Shape** — a `shortcode` is strictly ASCII-alphanumeric. It is the
+ *    identity key referenced from saved world data, and it is half of the
+ *    `type-shortcode` address, whose parse depends on the separating hyphen
+ *    being the only hyphen in the string.
+ * 2. **Uniqueness** — `(type, shortcode)` names one note.
+ *
+ * **Nothing here writes.** A check reports and an author fixes.
+ *
+ * **A third rule was retired (#79).** Every note used to be required to repeat
+ * its own `type-shortcode` address in the top-level `aliases:` list. That
+ * served exactly one reader — **Obsidian**, so `[[type-shortcode]]` resolved in
+ * the editor — and nothing else ever read it: both resolvers parse the hyphen
+ * qualifier themselves, and the alias list feeds only the bare-alias fallback
+ * index. The project no longer authors in Obsidian, so the rule required a line
+ * of frontmatter per note for a reader that does not exist. Removing it was
+ * verified output-neutral beforehand: across 1,735 stripped notes,
+ * `package compile` produced byte-identical `build/packs-json` and the site
+ * build byte-identical `site/content`.
+ *
+ * **What is deliberately absent.** Corpus reachability — "every Rules document
+ * is reachable from the book's root" — is a statement about what one package
+ * publishes, not about the note format, and belongs with the publishing it
+ * describes. So do retired hostnames.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { positionInFrontmatter } from "./diagnostics.mjs";
+import { walkMarkdownTree } from "./helpers.mjs";
+
+/**
+ * The shape every `shortcode` must match: ASCII letters and digits only.
+ *
+ * Case is deliberately **not** constrained: hundreds of authored shortcodes are
+ * mixed-case and collide with nothing, so tightening that is a separate
+ * decision from this one.
+ *
+ * A consuming system's *runtime* keeps its own copy of this pattern — it cannot
+ * import a build-time dependency into shipped code — and is expected to pin the
+ * two together with a test rather than trust that they still agree.
+ */
+export const SHORTCODE_PATTERN = /^[A-Za-z0-9]+$/;
+
+/**
+ * Whether a value is a well-formed shortcode.
+ *
+ * A blank value is **not** valid here. Blank is handled separately wherever a
+ * key is derived from a document's name, so this predicate answers only "is
+ * this an acceptable key", never "is this key present".
+ *
+ * @param {unknown} value - The candidate shortcode.
+ * @returns {boolean} `true` when it matches {@link SHORTCODE_PATTERN}.
+ */
+export function isValidShortcode(value) {
+    return typeof value === "string" && SHORTCODE_PATTERN.test(value);
+}
+
+/**
+ * Collect the notes a lint pass reasons about.
+ *
+ * Only notes carrying a `type` are content notes. Vault scaffolding —
+ * `Templates/`, a `README`, a repository's own `CLAUDE.md` — has no type, is
+ * neither addressed nor addressable, and would fail rules it can never satisfy.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Passed to the walk.
+ * @returns {Array<{fm: object, absPath: string, file: string}>} The notes, in
+ *   path order so findings read top to bottom.
+ */
+function collectNotes(contentBase, { skipDirectories } = {}) {
+    const notes = [];
+    const walkOpts = skipDirectories ? { skipDirectories } : undefined;
+    for (const { frontmatter: fm, absPath } of walkMarkdownTree(
+        contentBase,
+        walkOpts,
+    )) {
+        if (!fm || !fm.type) continue;
+        notes.push({
+            fm,
+            absPath,
+            file: path.relative(process.cwd(), absPath),
+        });
+    }
+    notes.sort((a, b) => (a.absPath < b.absPath ? -1 : 1));
+    return notes;
+}
+
+/**
+ * Lint every address in a content tree.
+ *
+ * @param {string} contentBase - Root of the content tree.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.skipDirectories] - Directory names the walk
+ *   ignores. Defaults to the configured list.
+ * @returns {{findings: Array<{file: string, line?: number, column?: number,
+ *   severity: "error"|"warning", message: string}>, notes: number,
+ *   keys: number}} The findings, and what was inspected to produce them.
+ */
+export function lintContentTree(contentBase, { skipDirectories } = {}) {
+    const findings = [];
+    const notes = collectNotes(contentBase, { skipDirectories });
+
+    /** @type {Map<string, Array<{file: string, absPath: string}>>} */
+    const byKey = new Map();
+
+    for (const { fm, absPath, file } of notes) {
+        const shortcode = fm.shortcode;
+        // Folder documents and keyless entries carry no address at all.
+        if (!shortcode) continue;
+
+        // Read only when there is something to say about the note, so a clean
+        // tree costs one pass rather than two.
+        const raw = () => fs.readFileSync(absPath, "utf8");
+
+        const key = `${fm.type}:${shortcode}`;
+        const seen = byKey.get(key);
+        if (seen) seen.push({ file, absPath });
+        else byKey.set(key, [{ file, absPath }]);
+
+        if (!isValidShortcode(shortcode)) {
+            findings.push({
+                file,
+                ...positionInFrontmatter(raw(), "shortcode", String(shortcode)),
+                severity: "error",
+                message:
+                    `shortcode "${shortcode}" is not strictly alphanumeric; it ` +
+                    `is the identity key and half of the ` +
+                    `"${fm.type}-${shortcode}" address, whose parse needs the ` +
+                    `separator to be the only hyphen`,
+            });
+        }
+    }
+
+    // "Every one of nothing is unique" is a vacuous pass, and it is exactly
+    // what a tree that failed to check out produces — so the lint would go
+    // green on the one state it most needs to catch.
+    if (byKey.size === 0) {
+        findings.push({
+            file: path.relative(process.cwd(), contentBase) || contentBase,
+            severity: "error",
+            message:
+                "holds no keyed content, so every rule here is vacuous — " +
+                "check that the content tree is present and that this is its root",
+        });
+        return { findings, notes: notes.length, keys: 0 };
+    }
+
+    for (const [key, files] of byKey) {
+        if (files.length < 2) continue;
+        // Reported once per offending note rather than once per key: each note
+        // is a place an author has to go and edit, and a finding naming only
+        // the key sends them hunting for the other one.
+        for (const { file, absPath } of files) {
+            const others = files
+                .filter((f) => f.file !== file)
+                .map((f) => f.file);
+            findings.push({
+                file,
+                ...positionInFrontmatter(
+                    fs.readFileSync(absPath, "utf8"),
+                    "shortcode",
+                ),
+                severity: "error",
+                message:
+                    `duplicate address "${key}", also declared by ` +
+                    `${others.join(", ")}; a document is addressed by ` +
+                    `(type, shortcode) across every pack of its document type, ` +
+                    `so routing them to different packs does not separate them`,
+            });
+        }
+    }
+
+    return { findings, notes: notes.length, keys: byKey.size };
+}

package/engine/content-package.mjs

@@ -0,0 +1,67 @@
+/*
+ * 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
+ */
+
+/**
+ * Which package's notes this repository compiles, and which Foundry package
+ * ships them — read from the repository's `package-build.config.yaml`.
+ *
+ * Both values are **derived**, not declared: `config.mjs` is the single place
+ * the configuration is resolved (#1508). This module survives as the import
+ * path the link resolver and the compilers have always used, so that the values
+ * can still be mocked in one place and so no consumer has to learn a new
+ * spelling for them.
+ */
+
+import { loadPackConfig } from "./pack-config.mjs";
+
+/**
+ * The **content** package: the distribution unit a note declares in its
+ * `package:` frontmatter. The pack compilers select their entries by it.
+ *
+ * Stable across compilation targets. If this content were ever compiled for a
+ * second game system, its notes would still declare `package: sohl` — only the
+ * Foundry package below would differ.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {string} The configured `contentPackage`.
+ */
+export function contentPackage() {
+    return loadPackConfig().contentPackage;
+}
+
+/**
+ * The **Foundry package** this repository's packs are shipped in — the `id` in
+ * `assets/templates/system.template.json`, and the first segment of every
+ * compendium UUID the compilers emit.
+ *
+ * Distinct from {@link contentPackage}, and equal to it only by coincidence
+ * here: a note says `package: sohl` and its documents are addressed as
+ * `Compendium.sohl.<pack>.<Type>.<id>`. In `sohl-thalorna` the two differ
+ * (`thalorna` vs `sohl-thalorna`), which is why they are separate values rather
+ * than one — treating them as interchangeable is what #1498 was.
+ *
+ * Configured rather than read from the manifest so the link resolver stays
+ * filesystem-free and unit-testable. `assertPackageIdMatchesManifestFile` in
+ * `package-manifest.mjs` — called from `generatePacksJson`, before any entry is
+ * written — fails the build if this value and the manifest's `id` ever drift.
+ *
+ * An accessor rather than a hoisted constant, so that importing this module
+ * needs no configuration (#2).
+ *
+ * @returns {string} The configured `foundryPackage`.
+ */
+export function foundryPackageId() {
+    return loadPackConfig().foundryPackage;
+}

package/engine/content-slug.mjs

@@ -0,0 +1,169 @@
+/*
+ * 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 URL segment of a content note — derived from its name.
+ *
+ * Content notes carry no authored `slug`: it was a hand-maintained second
+ * spelling of something already determined, free to drift from the page it
+ * named. The URL is derived instead.
+ *
+ * It is derived from the **name**, deliberately not from the `shortcode`, even
+ * though `(type, shortcode)` is unique by rule and would be a tempting key. A
+ * shortcode is *identity*: it is referenced from saved world data — actions,
+ * cohorts, expressions, archetypes, pack lookups — so binding the public URL to
+ * it would make a cosmetic URL change into a data migration. A URL is
+ * presentation, and it should read like one (`/creature/nusvorroth/`, not
+ * `/creature/nsvrroth/`). Renames are what a URL must survive, and they do:
+ * every change appends to the legacy-URL map, which emits a redirect.
+ *
+ * **One normalisation, for every slug this build makes.** {@link slugify} is it.
+ * Two things are layered on top of it for **document identity** only, in
+ * {@link contentSlug}:
+ *
+ * - it must produce something, and throws when a name yields no slug;
+ * - it **abbreviates** — see {@link ABBREVIATIONS}.
+ *
+ * Abbreviation stops at the document's own address on purpose. A heading anchor
+ * is not a name the build invents: an author writes the matching key by hand —
+ * a map note pins `locations.stair-foot` at a heading called *Stair Foot* — so a
+ * slug that silently became `stair-ft` would break a reference nobody could
+ * have predicted. The same goes for a pack filename, which is only ever read
+ * back by the unpacker. Shortening either buys nothing and costs the author's
+ * ability to guess the key.
+ *
+ * This header used to claim the opposite — that anchor slugs, filename slugs and
+ * this one were deliberately separate operations. Three of them had drifted into
+ * dropping non-ASCII letters instead of transliterating them, so `Kûrbúl Helm`
+ * addressed a page at `kurbul-helm` while its pack file was `k-rb-l-helm` and a
+ * link to a heading of the same name pointed at `#k-rb-l-helm`. Twenty-two of
+ * this repository's notes were affected. That was not a design; it was three
+ * copies of a regex, and the differences between them were all mistakes.
+ *
+ * What the rule does, and why:
+ *
+ * - **Transliterate, don't discard.** `unidecode` carries every non-ASCII letter
+ *   to its ASCII sense — `æ` → `ae`, `þ` → `th`, `œ` → `oe`, `ß` → `ss`,
+ *   `ö` → `o`, `¾` → `3/4`. A rule that merely strips them turns a name into
+ *   punctuation.
+ * - **An apostrophe elides.** `’` and `'` mark a pronunciation break — a glottal
+ *   stop — inside one word, so `Kenbet’Pat` is `kenbetpat`, not `kenbet-pat`.
+ * - **Everything else non-alphanumeric becomes a hyphen**, collapsed and
+ *   trimmed.
+ *
+ * `slugifyShortcode` in the SoHL runtime is genuinely a different operation and
+ * stays separate: it runs the other way, suggesting a shortcode *from* a name
+ * when an item is created.
+ *
+ * Plain ESM with no Foundry and no filesystem access, so it is unit-testable.
+ */
+
+import unidecode from "unidecode";
+
+import { abbreviateTokens } from "./abbreviations.mjs";
+
+/**
+ * The URL segment for one content note.
+ *
+ * The name is **transliterated** before it is reduced, so an accented character
+ * is carried across rather than dropped — dropping is what turned `Nüsvōrroth`
+ * into `n-sv-rroth` and forced a hand-written slug. Ligatures expand the way a
+ * reader would spell them out: `þ`→`th`, `æ`→`ae`, `œ`→`oe`, `ß`→`ss`, `ij`→`ij`,
+ * `fi`→`fi`, and eth (`ð`) follows the Icelandic convention of a bare `d`.
+ *
+ * Two reductions are ours rather than the transliterator's:
+ *
+ * - **apostrophes are removed**, not treated as separators (`Armorer's Kit` →
+ *   `armorers-kit`), matching the URLs these pages already publish at;
+ * - **a fraction keeps its digits together** — a vulgar fraction expands to
+ *   `3/4`, and the solidus would otherwise split it into `3-4`, so a slash
+ *   *between digits* is closed up (`Kûrbúl ¾-Helm` → `kurbul-34-helm`).
+ *
+ * @param {string | undefined} name - The note's display name (`name.full`),
+ *   which a malformed note may not have at all.
+ * @returns {string} The URL segment (never empty).
+ * @throws {Error} When there is no name, or the name carries no URL-safe
+ *   characters — either way the note cannot be addressed, which is a content
+ *   error rather than something to paper over with a fallback.
+ */
+export function slugify(text) {
+    const raw = typeof text === "string" ? text.trim() : "";
+    if (!raw) return "";
+    const tokens = unidecode(raw)
+        .toLowerCase()
+        // An apostrophe marks a pronunciation break, not a word boundary:
+        // `Kenbet\u2019Pat` is one name said with a catch in it, so it elides
+        // rather than becoming a hyphen.
+        .replace(/['\u2019]/g, "")
+        // A vulgar fraction transliterates to its digits (`\u00be` \u2192 `3/4`); the
+        // solidus between them is not a word boundary either.
+        .replace(/(\d)\/(\d)/g, "$1$2")
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+
+    return tokens.join("-");
+}
+
+/**
+ * The URL segment a content note publishes at.
+ *
+ * {@link slugify} with the rule that a document *must* be addressable: a note
+ * that yields no slug is a content error, not something to paper over with a
+ * fallback, because the alternative is a page nobody can reach.
+ *
+ * @param {string | undefined} name - The note's display name (`name.full`),
+ *   which a malformed note may not have at all.
+ * @returns {string} The URL segment (never empty).
+ * @throws {Error} When there is no name, or the name carries no URL-safe
+ *   characters.
+ */
+export function contentSlug(name) {
+    const raw = typeof name === "string" ? name.trim() : "";
+    if (!raw) {
+        throw new Error("content note has no name, so it has no URL");
+    }
+    const normalised = slugify(raw);
+    const slug = abbreviateTokens(normalised.split("-").filter(Boolean)).join(
+        "-",
+    );
+    if (!slug) {
+        throw new Error(
+            `name "${raw}" has no URL-safe characters, so it cannot address a page`,
+        );
+    }
+    return slug;
+}
+
+/**
+ * Find pages that would publish to the same URL.
+ *
+ * Nothing constrains two notes in one section from sharing a name, and a
+ * collision silently overwrites one page with the other. This turns it into a
+ * build failure that names every claimant, so the fix is a more specific title.
+ * (The content tree has no collisions today.)
+ *
+ * @param {Array<{sec: string, slug: string, src: string}>} pages
+ * @returns {Array<{url: string, sources: string[]}>} One entry per collision, in
+ *   first-claim order; empty when every URL is unique.
+ */
+export function findSlugCollisions(pages) {
+    const byUrl = new Map();
+    for (const { sec, slug, src } of pages) {
+        const url = `/${sec}/${slug}/`;
+        if (!byUrl.has(url)) byUrl.set(url, []);
+        byUrl.get(url).push(src);
+    }
+    return [...byUrl.entries()]
+        .filter(([, sources]) => sources.length > 1)
+        .map(([url, sources]) => ({ url, sources }));
+}