@heroiclands/package-build 9.0.0 → 10.0.0

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/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 };
+}

package/engine/base-compiler.mjs

@@ -79,6 +79,9 @@ import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { assertNoDraftField } from "./retired-fields.mjs";
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
+import { carriesSystemBlock } from "./system-block.mjs";
+import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
+import { locateFrontmatterKey } from "./retired-fields.mjs";
 
 /**
  * The tallies one pass accumulates while walking the tree.
@@ -93,8 +96,9 @@ import { assertTypeNotRetired, packForType } from "./ids.mjs";
  * @property {number} compiled - Notes that became a document.
  * @property {number} skippedNoId - Notes with no `id`, where that is tolerated.
  * @property {number} skippedOther - Notes this pass does not claim.
- * @property {number} declined - Notes refused because they declare a retired
- *   frontmatter field. Counted as errors, never as skips.
+ * @property {number} declined - Notes this pack **refused** — one declaring a
+ *   retired frontmatter field, or one routed to a system pack whose system it
+ *   says nothing about (#58). Counted as errors, never as skips.
  */
 
 /**
@@ -167,6 +171,26 @@ export class BasePackCompiler {
      */
     static readsPackOutputOf = Object.freeze([]);
 
+    /**
+     * Whether this pass's document **is** a system's data, and therefore takes
+     * only notes that carry that system's block (#58).
+     *
+     * A pack may declare a `system:` — `harn-ensemble` ships an `actors-hm3`
+     * and an `actors-sohl` from one tree — and the note-side half of that is
+     * the block named after the system. A note carrying no such block has
+     * nothing to say about it, so compiling it there would emit a **hollow
+     * document**: a subtype, and none of the fields the subtype exists for.
+     *
+     * False by default, because most passes write documents that are not
+     * system data at all. A JournalEntry of prose is the same document under
+     * either system, and a journals pack that declared one must not turn every
+     * doc note in the tree into a finding. The Item and Actor passes say so;
+     * anything else that genuinely writes a system's data says so too.
+     *
+     * @type {boolean}
+     */
+    static requiresSystemBlock = false;
+
     /** @type {string} */
     contentBase;
     /** @type {string} */
@@ -176,6 +200,19 @@ export class BasePackCompiler {
     /** @type {number} */
     errorCount = 0;
 
+    /**
+     * Emitted-`system` findings, one per `documentType|subtype|field` (#155).
+     *
+     * A key the compiler writes is on **every** document of a subtype, so
+     * reporting it where it is found would print the same sentence 3,126 times
+     * and bury the one that is not systemic. Collected here instead and flushed
+     * once at the end of the pass, keyed so the class of defect is reported
+     * once and the first document carrying it names a file a reader can open.
+     *
+     * @type {Map<string, {message: string, file: string|undefined}>}
+     */
+    emittedFindings = new Map();
+
     /**
      * The pack this pass writes, and the Foundry document type it holds.
      *
@@ -300,7 +337,36 @@ export class BasePackCompiler {
      */
     routesHere(fm) {
         if (!this.router || !this.packName || !this.docType) return true;
-        return this.router.resolve(fm, this.docType) === this.packName;
+        return (
+            this.router.resolve(fm, this.docType, this.packSystem ?? undefined) === this.packName
+        );
+    }
+
+    /**
+     * Whether a claimed, routed note may become this pack's document at all.
+     *
+     * The pack-eligibility gate, and it fails rather than skipping: a note that
+     * routed *here* and carries nothing for this pack's system is an authoring
+     * mistake with a hollow document at the end of it, not a note that belongs
+     * to another pass. Skipping it quietly is how a whole tree compiles to
+     * documents nobody can use — the failure mode #1502 and #56 are both
+     * instances of.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @returns {boolean} True when the note may be compiled here.
+     * @throws {Error} When this pack's system is absent from the note. The
+     *   error carries a `position` where the note's own file can be read.
+     */
+    eligibleFor(fm) {
+        if (!this.constructor.requiresSystemBlock || !this.packSystem) return true;
+        if (carriesSystemBlock(fm, this.packSystem)) return true;
+        const label = fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "this note";
+        throw new Error(
+            `${label} carries no \`${this.packSystem}:\` block, so it has no ` +
+                `${this.packSystem} data to compile — but it routes to pack ` +
+                `"${this.packName}", which declares \`system: ${this.packSystem}\`. ` +
+                `Add the block, or route the note to a pack of another system.`,
+        );
     }
 
     /**
@@ -442,6 +508,113 @@ export class BasePackCompiler {
         });
     }
 
+    /**
+     * Report every `<system>.system` key the receiving subtype does not declare
+     * (#58).
+     *
+     * An **error**, not a warning: Foundry drops an unknown `system` key at
+     * construction without a word, so the alternative is a document shipped
+     * with a field the author wrote and nobody will ever see. Each finding is
+     * located at the offending key where the file can be read, so it points at
+     * a line rather than at a note.
+     *
+     * Silent where nothing can answer — no published schema, or a subtype the
+     * artifact does not name. `content-build lint` says that out loud once for
+     * the whole build rather than once per note.
+     *
+     * @param {object} fm - The note's frontmatter.
+     * @param {string} block - The system block to read.
+     * @param {string} documentType - `Item`, `Actor`, …
+     * @param {string} subType - The subtype this note compiles into.
+     * @returns {number} How many findings were reported.
+     */
+    reportUndeclaredSystemData(fm, block, documentType, subType) {
+        const absPath = this.currentNote?.absPath;
+        const findings = checkAuthoredSystemData(fm, { block, documentType, subType });
+        for (const finding of findings) {
+            this.errorCount++;
+            const leaf = finding.path.split(".").pop();
+            this.noteError(finding.message, locateFrontmatterKey(absPath, leaf));
+        }
+        return findings.length;
+    }
+
+    /**
+     * Record every `system` key the *compiled document* carries that the
+     * receiving subtype does not declare (#155).
+     *
+     * The sibling of {@link BasePackCompiler#reportUndeclaredSystemData}, and
+     * the half that sees what no declaration states. A compiler writes keys of
+     * its own alongside the declared fields — `shortcode`, `actionDefs`,
+     * `notes`, `docHtml`, `archetype` — and neither the field-declaration check
+     * nor the authored-`system` check can see them, so until this nothing
+     * compared them at all. Foundry's discard is the same silent one either
+     * way.
+     *
+     * Called with the block **after** the builder, the authored merge and any
+     * conditional fields have all written into it, so what is checked is what
+     * the pack file receives.
+     *
+     * Recorded rather than reported: see {@link BasePackCompiler#emittedFindings}
+     * for why, and {@link BasePackCompiler#reportEmittedFindings} for where they
+     * come out.
+     *
+     * @param {object} system - The `system` block just assembled.
+     * @param {object} opts
+     * @param {object} opts.fm - The note's frontmatter.
+     * @param {string} opts.block - The system block the note writes.
+     * @param {string} opts.documentType - `Item`, `Actor`, …
+     * @param {string} opts.subType - The subtype this note compiles into.
+     * @param {string} opts.type - The note's content type.
+     * @param {readonly {to?: string}[]} [opts.fields] - The type's field
+     *   declaration, which tells a builder emission from a compiler one.
+     * @param {object} [opts.config] - The resolved build configuration.
+     * @returns {number} How many findings were new to this pass.
+     */
+    reportEmittedSystemData(system, { fm, block, documentType, subType, type, fields, config }) {
+        const findings = checkEmittedSystemData(system, {
+            fm,
+            block,
+            documentType,
+            subType,
+            type,
+            fields,
+            ...(config ? { config } : {}),
+        });
+        let added = 0;
+        for (const finding of findings) {
+            const key = `${finding.documentType}|${finding.subtype}|${finding.field}`;
+            if (this.emittedFindings.has(key)) continue;
+            this.emittedFindings.set(key, {
+                message: finding.message,
+                file: this.currentNote?.absPath,
+            });
+            added++;
+        }
+        return added;
+    }
+
+    /**
+     * Emit the collected emitted-`system` findings, once each.
+     *
+     * An **error**, for the reason #60 made its sibling one: the value is gone
+     * at load and the build says nothing, and severity that varied by *which
+     * part of the build wrote the key* would make the less fixable half the
+     * quieter one. What varies is the message, which says whose fix it is —
+     * see {@link module:engine/schema-check.emittedUndeclaredMessage}.
+     *
+     * @returns {number} How many were reported.
+     */
+    reportEmittedFindings() {
+        const found = this.emittedFindings;
+        this.emittedFindings = new Map();
+        for (const finding of found.values()) {
+            this.errorCount++;
+            emitDiagnostic({ file: finding.file, severity: "error", message: finding.message });
+        }
+        return found.size;
+    }
+
     /**
      * One note → one document. **Required.**
      *
@@ -552,7 +725,8 @@ export class BasePackCompiler {
             // them in the skipped tally is the defect (#56). Each one has
             // already been named individually as a diagnostic.
             log.error(
-                `Declined ${stats.declined} note(s) declaring a retired ` + `frontmatter field`,
+                `Declined ${stats.declined} note(s) — each named above, with ` +
+                    `the reason this pack would not compile it`,
             );
         }
         this.reportDetail(stats);
@@ -644,6 +818,18 @@ export class BasePackCompiler {
                 }
                 continue;
             }
+            // Whether this pack's system is one the note speaks for. Checked
+            // after routing — a note bound for another pack is none of this
+            // pass's business — and before `skipNote`, so a pass's own
+            // rejection rules never run on a note it may not compile.
+            try {
+                this.eligibleFor(fm);
+            } catch (err) {
+                stats.declined++;
+                this.errorCount++;
+                this.noteError(err.message, err.position);
+                continue;
+            }
             if (this.skipNote(fm, body)) {
                 stats.skippedOther++;
                 continue;
@@ -668,6 +854,10 @@ export class BasePackCompiler {
 
         this.compiledCount = stats.compiled;
         await this.finish(stats);
+        // After `finish`, because a pass that writes documents there (the
+        // scenes pass bundles an Adventure) has emitted them by now; before
+        // `report`, so the pass's summary counts them.
+        this.reportEmittedFindings();
         this.report(stats);
     }
 }

package/engine/content-address.mjs

@@ -38,14 +38,14 @@ export const KB_PREFIX = "kb/";
  * The URL section a note routes to.
  *
  * A `doc` is narrative content whose only identity is its subtype label, so it
- * routes by `category`; every other type names its own section.
+ * routes by `subType`; every other type names its own section.
  *
  * @param {object} fm - Parsed frontmatter.
  * @returns {string|undefined} The section, or `undefined` when the note has
- *   none — a `doc` with no category has no address and is not published.
+ *   none — a `doc` with no subtype has no address and is not published.
  */
 export function sectionOf(fm) {
-    return fm.type === "doc" ? fm.category : fm.type;
+    return fm.type === "doc" ? fm.subType : fm.type;
 }
 
 /**
@@ -85,7 +85,7 @@ function landingOf(fm, isReadme, landing) {
     // `collection`. The section is authored rather than derived: it is the
     // identity of the section being introduced, and the note's own title
     // ("Creatures") is presentation, which would slug to something else.
-    if (fm.type === "doc" && fm.category === "collection") {
+    if (fm.type === "doc" && fm.subType === "collection") {
         return { landing: true, segment: fm.section || fm.slug };
     }
     return { landing: false };