@heroiclands/package-build 6.1.0 → 8.0.0

package/content-config.mjs

@@ -584,9 +584,12 @@ const CONFIG_KEYS = [
     "site",
     "compatibility",
     "relationships",
+    "systems",
+    "requiresSystem",
     "packageBuild",
     "publish",
 ];
+const SYSTEM_KEYS = ["manifest", "compatibility"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
@@ -626,7 +629,24 @@ const PACK_KEYS = [
     "system",
 ];
 const PATH_KEYS = Object.keys(DEFAULT_PATHS);
-const STATS_KEYS = ["systemId", "systemVersion", "lastModifiedBy"];
+const STATS_KEYS = ["lastModifiedBy"];
+
+/**
+ * How the loader hands {@link defineConfig} the system version it resolved.
+ *
+ * A **Symbol**, deliberately. `stats.systemVersion` is refused from an authored
+ * configuration (#48), but the value still has to reach here from the loader —
+ * which is the half that may do I/O, and which reads a system package's version
+ * out of the adjacent `package.json`. A string key would be a second spelling of
+ * the refused one, forgeable from YAML and reachable by `rejectUnknownKeys`; a
+ * symbol key cannot be written in YAML at all and does not appear in
+ * `Object.keys`, so the refusal has no back door.
+ *
+ * @type {symbol}
+ */
+export const DERIVED_SYSTEM_VERSION = Symbol.for(
+    "package-build.derivedSystemVersion",
+);
 const PUBLISH_KEYS = ["site", "manifests", "address"];
 const MANIFEST_KEYS = ["publish", "consume"];
 const ADDRESS_KEYS = ["prefix", "landing"];
@@ -637,12 +657,25 @@ function isPlainObject(value) {
 }
 
 /**
- * @param {string} field
- * @param {string} problem
+ * Reject a configured value, naming the key it was written under.
+ *
+ * The dotted path is carried on the error as `field` as well as spelled into
+ * the message, because the message alone is a good description and a bad
+ * locator: the loader that read the file can resolve that path to a line and
+ * column, and does (`locateConfigError` in `engine/pack-config.mjs`, #95).
+ * Attaching it here rather than formatting here is what keeps this module
+ * free of I/O — it is the leaf an `.mjs` configuration imports, so it may not
+ * reach for the file it is validating.
+ *
+ * @param {string} field - Dotted path of the offending key.
+ * @param {string} problem - What is wrong with it.
  * @returns {never}
  */
 function fail(field, problem) {
-    throw new TypeError(`package-build config: \`${field}\` ${problem}.`);
+    throw Object.assign(
+        new TypeError(`package-build config: \`${field}\` ${problem}.`),
+        { field },
+    );
 }
 
 /**
@@ -869,28 +902,42 @@ function normalizePaths(value, rootDir) {
  * @param {unknown} value
  * @returns {Readonly<StatsSpec>}
  */
-function normalizeStats(value) {
+function normalizeStats(value, derived) {
     if (!isPlainObject(value)) fail("stats", "must be an object");
     const input = /** @type {Record<string, unknown>} */ (value);
+
+    // **`systemId` and `systemVersion` are derived, and authoring a derived
+    // value is an error rather than an override (#48).** `systems:` is the
+    // single source: it says which systems this package stamps against, and
+    // `requiresSystem` — or a lone declared system — says which one the
+    // package-wide block takes. A system package answers for itself.
+    //
+    // Refused rather than ignored, because the two would silently disagree.
+    // That is exactly how `stats.systemVersion` came to sit at `0.6.0` for four
+    // releases: a transcribed copy is free to drift from what it copied, and
+    // nothing reads a stamped `_stats` until something migrates on it.
+    for (const key of ["systemId", "systemVersion"]) {
+        if (input[key] === undefined) continue;
+        fail(
+            `stats.${key}`,
+            `is derived and may not be authored. ` +
+                (key === "systemId" ?
+                    `A system package is its own system; a module takes it ` +
+                    `from \`requiresSystem\`, or from \`systems:\` when it ` +
+                    `declares exactly one. `
+                :   `It is the \`compatibility.verified\` of the system in ` +
+                    `\`systems:\`, or a system package's own \`package.json\` ` +
+                    `version. `) +
+                `Remove the key`,
+        );
+    }
     rejectUnknownKeys(input, STATS_KEYS, "stats.");
 
     return Object.freeze({
-        // Optional: a package whose packs are not all for one system declares
-        // the system per pack instead (`packs[].system`), and a package that
-        // ships only system-agnostic documents declares none at all.
-        systemId:
-            input.systemId === undefined || input.systemId === null ?
-                null
-            :   requireNonEmptyString(input.systemId, "stats.systemId"),
-        // Optional for the same reason as `systemId`: a system-agnostic module
-        // is not built against a system, so it has no version of one to stamp.
-        systemVersion:
-            input.systemVersion === undefined || input.systemVersion === null ?
-                null
-            :   requireNonEmptyString(
-                    input.systemVersion,
-                    "stats.systemVersion",
-                ),
+        // Per pack where the packs differ — see `statsForPack` — and this is
+        // the package-wide answer for everything that has no pack in hand.
+        systemId: derived.systemId,
+        systemVersion: derived.systemVersion,
         lastModifiedBy: requireNonEmptyString(
             input.lastModifiedBy,
             "stats.lastModifiedBy",
@@ -1184,6 +1231,98 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
  * @param {unknown} value - The `relationships` block, or `undefined`.
  * @returns {Readonly<Relationships>} It, frozen; `{}` when absent.
  */
+/**
+ * The systems this package can stamp content against — declaration only (#48).
+ *
+ * **Declaring is not requiring, and that separation is the whole point.** The
+ * only place to state a system version used to be `relationships.systems`, and
+ * that list is a *restriction*: Foundry's `supportsSystem` drops a module from
+ * any world whose system it does not name. So a module shipping content for two
+ * systems — `harn-ensemble` ships an HM3 pack, a SoHL pack and a system-neutral
+ * journals pack — had to choose between naming its systems and remaining
+ * loadable, and choosing the second meant stamping no system version at all on
+ * content that certainly has one.
+ *
+ * Naming a system here restricts nothing. {@link normalizeRequiresSystem} is
+ * what restricts, and it is separate and optional.
+ *
+ * Each entry carries the same `compatibility` shape a relationship does, and
+ * `verified` is what a pack stamps: `_stats.systemVersion` records what the
+ * content was *built against*, not the floor it tolerates.
+ *
+ * @param {unknown} value - The declared `systems:` mapping.
+ * @returns {Readonly<Record<string, Readonly<object>>>} Frozen; `{}` when absent.
+ */
+function normalizeSystems(value) {
+    if (value === undefined || value === null) return Object.freeze({});
+    if (!isPlainObject(value))
+        fail("systems", "must be a mapping of id to spec");
+    const input = /** @type {Record<string, unknown>} */ (value);
+
+    const out = {};
+    for (const [id, entry] of Object.entries(input)) {
+        const at = `systems.${id}`;
+        if (!id) fail("systems", "declares an empty system id");
+        if (!isPlainObject(entry)) fail(at, "must be a mapping");
+        const spec = /** @type {Record<string, unknown>} */ (entry);
+        rejectUnknownKeys(spec, SYSTEM_KEYS, `${at}.`);
+
+        const compatibility = spec.compatibility;
+        if (!isPlainObject(compatibility)) {
+            fail(`${at}.compatibility`, "must be a mapping");
+        }
+        const compat = /** @type {Record<string, unknown>} */ (compatibility);
+        rejectUnknownKeys(compat, COMPATIBILITY_KEYS, `${at}.compatibility.`);
+        // `verified` is required because it is the value a pack stamps. A
+        // declaration that cannot answer "which version was this built
+        // against" is the gap this block exists to close.
+        const verified = requireNonEmptyString(
+            compat.verified,
+            `${at}.compatibility.verified`,
+        );
+
+        out[id] = Object.freeze({
+            manifest:
+                spec.manifest === undefined || spec.manifest === null ?
+                    null
+                :   requireNonEmptyString(spec.manifest, `${at}.manifest`),
+            compatibility: Object.freeze({
+                minimum:
+                    compat.minimum === undefined || compat.minimum === null ?
+                        null
+                    :   requireNonEmptyString(
+                            compat.minimum,
+                            `${at}.compatibility.minimum`,
+                        ),
+                verified,
+            }),
+        });
+    }
+    return Object.freeze(out);
+}
+
+/**
+ * The one system this package refuses to load without, or `null` (#48).
+ *
+ * The gate half of the split. Naming a system here emits
+ * `relationships.systems` for it, which is what Foundry's `supportsSystem`
+ * reads — so the package becomes unavailable under any other system. Omitted,
+ * no relationship is emitted and the package loads anywhere, each pack stamping
+ * whatever its own `system:` names.
+ *
+ * It reuses the {@link normalizeSystems} entry rather than restating the
+ * compatibility: `stats.systemVersion` froze at `0.6.0` for four releases
+ * because a transcription was free to disagree with what it copied, and a
+ * second transcription invites the same.
+ *
+ * @param {unknown} value - The declared `requiresSystem:`.
+ * @returns {string|null} The system id, or `null`.
+ */
+function normalizeRequiresSystem(value) {
+    if (value === undefined || value === null) return null;
+    return requireNonEmptyString(value, "requiresSystem");
+}
+
 function normalizeRelationships(value) {
     if (value === undefined) return Object.freeze({});
     if (!isPlainObject(value)) fail("relationships", "must be a mapping");
@@ -1541,6 +1680,54 @@ export function defineConfig(config) {
         seen.add(name);
     }
 
+    // ── systems: declaring, and requiring, are separate decisions (#48) ──────
+    const systems = normalizeSystems(input.systems);
+    const requiresSystem = normalizeRequiresSystem(input.requiresSystem);
+    const declaredSystems = new Set(Object.keys(systems));
+    /** `relationships.systems`, for the derivations that still consult it. */
+    const relationshipSystems = /** @type {{id?: string}[]} */ (
+        (isPlainObject(input.relationships) ?
+            input.relationships.systems
+        :   null) ?? []
+    );
+
+    // A name that resolves to nothing is a build error rather than a
+    // fall-through, in the spirit the rest of this file already follows: a pack
+    // stamping a system nobody declared would stamp `undefined`, which is the
+    // plausible lie #43 was about.
+    if (requiresSystem !== null && !declaredSystems.has(requiresSystem)) {
+        fail(
+            "requiresSystem",
+            `names \`${requiresSystem}\`, which \`systems:\` does not declare` +
+                (declaredSystems.size ?
+                    `. Declared: ${[...declaredSystems].join(", ")}`
+                :   ` — the \`systems:\` block is empty or absent`),
+        );
+    }
+    for (const pack of packs.flatMap((p) => [p, ...p.companions])) {
+        if (!pack.system) continue;
+        if (declaredSystems.size && !declaredSystems.has(pack.system)) {
+            fail(
+                `packs.${pack.name}.system`,
+                `names \`${pack.system}\`, which \`systems:\` does not ` +
+                    `declare. Declared: ${[...declaredSystems].join(", ")}`,
+            );
+        }
+        // With a gate set, a pack for any other system could never be seen:
+        // Foundry drops the whole package under a system `requiresSystem` does
+        // not name, so the pack would ship and be unreachable.
+        if (requiresSystem !== null && pack.system !== requiresSystem) {
+            fail(
+                `packs.${pack.name}.system`,
+                `names \`${pack.system}\` while \`requiresSystem\` is ` +
+                    `\`${requiresSystem}\`, so this pack could never be seen — ` +
+                    `Foundry hides the whole package from any world whose ` +
+                    `system \`requiresSystem\` does not name. Drop ` +
+                    `\`requiresSystem\`, or correct the pack`,
+            );
+        }
+    }
+
     // Several packs of one document type are allowed — editorial grouping of
     // same-type documents is ordinary Foundry practice, and collapsing such a
     // layout breaks every stored compendium UUID (#1566). What is not allowed
@@ -1592,7 +1779,50 @@ export function defineConfig(config) {
         // one place `systems/sohl` (or `modules/sohl-thalorna`) is spelled.
         assetRoot: `${packageKind}/${foundryPackage}/assets`,
         paths: normalizePaths(input.paths, rootDir),
-        stats: normalizeStats(input.stats),
+        // The package-wide system, derived (#48). A **system** package is its
+        // own system, which is true by construction and needs no declaration. A
+        // **module** takes the one it requires, or the one system it declares
+        // when there is exactly one; with several and no gate there is no
+        // package-wide answer, and each pack carries its own.
+        stats: normalizeStats(input.stats, {
+            systemId:
+                packageKind === "systems" ? foundryPackage
+                : requiresSystem ? requiresSystem
+                : Object.keys(systems).length === 1 ? Object.keys(systems)[0]
+                    // A lone `relationships.systems` entry is a declaration of
+                    // the system as much as a gate, so it still answers. That
+                    // matters because the relationship carries `itemCatalog`
+                    // too — a separate concern the split does not replace — so
+                    // a repository using it would otherwise have to restate its
+                    // compatibility under `systems:` purely to keep stamping,
+                    // which is the duplication this whole change exists to
+                    // remove. Several entries have no single answer and get
+                    // none.
+                : relationshipSystems.length === 1 ?
+                    (relationshipSystems[0]?.id ?? null)
+                :   null,
+            // Derived here where the answer is pure data — the `verified` of
+            // whichever system the package-wide block takes — and supplied by
+            // the loader otherwise. The loader is the half that may do I/O, and
+            // the two cases needing it are a *system* package (its own
+            // `package.json` version) and a module still deriving from
+            // `relationships.systems`.
+            systemVersion:
+                (() => {
+                    const id =
+                        requiresSystem ??
+                        (Object.keys(systems).length === 1 ?
+                            Object.keys(systems)[0]
+                        :   null);
+                    return id ?
+                            (systems[id]?.compatibility?.verified ?? null)
+                        :   null;
+                })() ??
+                (isPlainObject(input.stats) ?
+                    input.stats[DERIVED_SYSTEM_VERSION]
+                :   null) ??
+                null,
+        }),
         itemBuilders,
         itemArt,
         itemFields,
@@ -1616,6 +1846,8 @@ export function defineConfig(config) {
             "compatibility",
         ),
         relationships: normalizeRelationships(input.relationships),
+        systems,
+        requiresSystem,
         packageBuild: normalizePackageBuild(input.packageBuild),
         publish: normalizePublish(input.publish),
     });

package/engine/base-compiler.mjs

@@ -73,6 +73,7 @@ import {
     convertNoteWikilinks,
     collectContentDocs,
     expandNoteTables,
+    statsForPack,
 } from "./helpers.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
@@ -237,6 +238,7 @@ export class BasePackCompiler {
         dest,
         folderResolver = () => null,
         packName,
+        packSystem = null,
         docType,
         router,
         routingReporter = false,
@@ -262,11 +264,34 @@ export class BasePackCompiler {
             writable: false,
         });
         this.packName = packName;
+        this.packSystem = packSystem;
         this.docType = docType;
         this.router = router;
         this.routingReporter = routingReporter;
     }
 
+    /**
+     * The `_stats` block every entry this pass emits is stamped with (#48).
+     *
+     * Per pack rather than per package, because a module may ship the same
+     * content for two systems — `harn-ensemble` has an `actors-hm3` pack and an
+     * `actors-sohl` pack — and those documents were built against different
+     * system versions. A single global block stamped both identically.
+     *
+     * Memoised on the instance: one pass, one pack, one system, so the block is
+     * constant for the life of the compiler. The previous module-level memo
+     * could not be, because it was shared across passes for different packs.
+     *
+     * @returns {object} The block, built once per compiler.
+     */
+    get stats() {
+        this.#stats ??= statsForPack(this.packSystem);
+        return this.#stats;
+    }
+
+    /** @type {object|undefined} */
+    #stats;
+
     /**
      * Whether this pass's pack is the one a claimed note belongs in.
      *

package/engine/content-links.mjs

@@ -58,6 +58,7 @@ import {
     canonicalKey,
     loadForeignManifests,
     manifestsComplete,
+    PACKAGE_BASE,
     readCanonicalKey,
 } from "./kb-manifest.mjs";
 import { frontmatterWikilinks, slugify } from "./web-wikilinks.mjs";
@@ -336,6 +337,74 @@ export function buildLinkIndex(
  */
 const SITE_HOST = /^(?:[a-z0-9-]+\.)*heroiclands\.org$/i;
 
+/**
+ * Every package landing this build can name, as `package` → base (#87).
+ *
+ * **A landing needs no manifest, and that is what makes it work.** The link
+ * manifest indexes content notes, and a homepage is deliberately not one — it
+ * compiles to no document and is entered in no manifest. The reading that
+ * follows from this, and that left a hardcoded URL as the only authored form,
+ * is that a landing therefore cannot be addressed. It does not follow: a
+ * landing's address is not a *note's* address but the **package's**, and
+ * {@link PACKAGE_BASE} already records where each package is served. That is a
+ * frozen constant vendored into every repository, so consulting it walks no
+ * tree, reads no manifest and builds no index — which is precisely why the
+ * mechanism survives `homepage` mode, where the licensing fence means none of
+ * those exist.
+ *
+ * The roster is consulted **for landings only**. Widening the package set the
+ * other rules read would make them offer manifest-based advice about packages
+ * no manifest is vendored for.
+ *
+ * @param {string} ownPackage - The package this build publishes.
+ * @param {Iterable<string>} manifestPackages - Packages a vendored manifest
+ *   names, which are addressable whether or not the roster lists them.
+ * @returns {Map<string, string>} Package to base, each base slash-terminated.
+ */
+function landingBases(ownPackage, manifestPackages) {
+    const bases = new Map();
+    // Convention first, roster second, so a package the roster relocates is
+    // recorded at the relocated base rather than the default one.
+    for (const pkg of [ownPackage, ...manifestPackages]) {
+        if (pkg) bases.set(pkg, `/${pkg}/`);
+    }
+    for (const [pkg, base] of Object.entries(PACKAGE_BASE)) {
+        if (typeof base === "string" && base.endsWith("/")) {
+            bases.set(pkg, base);
+        }
+    }
+    return bases;
+}
+
+/**
+ * The package whose landing an address names, or `null`.
+ *
+ * Matches the whole path, not a prefix: `/sohl/` is the landing, `/sohl/kb/`
+ * is a page inside the package and belongs to the manifest rules instead.
+ *
+ * @param {string} url - The authored address.
+ * @param {Map<string, string>} bases - From {@link landingBases}.
+ * @returns {{pkg: string, base: string}|null} The package and its base.
+ */
+function landingTarget(url, bases) {
+    const value = String(url ?? "").trim();
+    if (!value || !/^[a-z][a-z0-9+.-]*:/i.test(value)) return null;
+    let parsed;
+    try {
+        parsed = new URL(value);
+    } catch {
+        return null;
+    }
+    if (!/^https?:$/.test(parsed.protocol)) return null;
+    if (!SITE_HOST.test(parsed.hostname)) return null;
+    const pathname =
+        parsed.pathname.endsWith("/") ? parsed.pathname : `${parsed.pathname}/`;
+    for (const [pkg, base] of bases) {
+        if (pathname === base) return { pkg, base };
+    }
+    return null;
+}
+
 /**
  * How an authored address resolves, or `null` for one nothing here can judge.
  *
@@ -400,9 +469,17 @@ function readAddress(url, packages) {
  *   and what replaced it, so this is a fact rather than a guess — and it is
  *   exactly the SoHL defect.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   vendored manifest names. Both have a better form to write, which is why they
- *   are reported; a bare `/<package>/` is left alone, because a package
- *   homepage is in no manifest and there is nothing better to write.
+ *   vendored manifest names. Every one of them has a better form to write, which
+ *   is why every one is reported — including a bare `/<package>/`, which names
+ *   another package's landing (#87).
+ *
+ *   That last case was exempt until the better form was identified, on the
+ *   reasoning that a landing is in no link manifest so nothing could resolve it.
+ *   True, and beside the point: it does not need resolving. A landing's address
+ *   *is* its package prefix, so `/<package>/` is the absolute URL with the host
+ *   struck off — host-free, emitted verbatim, and needing no index, which is
+ *   what lets it hold in homepage-only mode where the tree is never walked. The
+ *   form was already accepted here; nothing had ever named it as the one to use.
  * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
  *   time. `href:` means "already resolved, use verbatim", so the same leading
  *   slash is correct there and is not reported.
@@ -424,6 +501,7 @@ function readAddress(url, packages) {
 export function auditHomepageLinks(index) {
     const findings = [];
     const packages = new Set([index.contentPackage, ...index.packages]);
+    const bases = landingBases(index.contentPackage, index.packages);
 
     for (const note of index.notes) {
         if (!isHomepage(note.fm)) continue;
@@ -467,28 +545,43 @@ export function auditHomepageLinks(index) {
             if (!address) continue;
             const { shape, segments, prefix } = address;
 
-            if (shape === "absolute" && prefix) {
-                // A bare `/<package>/` is a package's homepage, which is in no
-                // link manifest and has no relative form from another package.
-                // A finding with no fix is noise.
+            // Landings first, and by the roster rather than by the manifest
+            // package set: a landing is addressable in a repository that
+            // vendors no manifest at all, which is the case the fence creates
+            // and the case this rule exists for (#87).
+            const landing = landingTarget(url, bases);
+            if (landing) {
+                report(
+                    field,
+                    url,
+                    url,
+                    occurrence,
+                    `hardcoded absolute URL to ` +
+                        (landing.pkg === index.contentPackage ?
+                            `this package's own landing`
+                        :   `package "${landing.pkg}"'s landing`) +
+                        ` — write "${landing.base}", which names no host, is ` +
+                        `emitted verbatim, and resolves through the package ` +
+                        `roster rather than through an index, so it holds ` +
+                        `where no content tree is walked`,
+                );
+            } else if (shape === "absolute" && prefix) {
                 const rest = segments.slice(1).join("/");
-                if (rest) {
-                    report(
-                        field,
-                        url,
-                        url,
-                        occurrence,
-                        prefix === index.contentPackage ?
-                            `hardcoded absolute URL into this package's own ` +
-                                `address — write the package-relative ` +
-                                `"${rest}/", which the landing resolves ` +
-                                `against the site so the page follows the mount`
-                        :   `hardcoded absolute URL into package "${prefix}" ` +
-                                `— resolve it through that package's link ` +
-                                `manifest, whose entries carry the address, so a ` +
-                                `relocation does not leave this page behind`,
-                    );
-                }
+                report(
+                    field,
+                    url,
+                    url,
+                    occurrence,
+                    prefix === index.contentPackage ?
+                        `hardcoded absolute URL into this package's own ` +
+                            `address — write the package-relative ` +
+                            `"${rest}/", which the landing resolves ` +
+                            `against the site so the page follows the mount`
+                    :   `hardcoded absolute URL into package "${prefix}" ` +
+                            `— resolve it through that package's link ` +
+                            `manifest, whose entries carry the address, so a ` +
+                            `relocation does not leave this page behind`,
+                );
             } else if (shape === "rooted" && kind === "url") {
                 const rest =
                     prefix ? segments.slice(1).join("/") : segments.join("/");
@@ -497,9 +590,21 @@ export function auditHomepageLinks(index) {
                     url,
                     url,
                     occurrence,
-                    `url "${url}" is root-relative, but a landing's url: is ` +
-                        `resolved against the site — write "${rest}/", or ` +
-                        `href: for an address that is already resolved`,
+                    // A `url:` is package-relative by construction, so it
+                    // cannot address anything outside this package at all —
+                    // there is no relative spelling of another package's root.
+                    // `href:` is the field for an address already resolved.
+                    !rest ?
+                        `url "${url}" addresses ` +
+                            (prefix ?
+                                `package "${prefix}"'s landing`
+                            :   `the site root`) +
+                            `, but a landing's url: is package-relative and ` +
+                            `cannot leave this package — write ` +
+                            `href: "${url}", which is used verbatim`
+                    :   `url "${url}" is root-relative, but a landing's url: ` +
+                            `is resolved against the site — write "${rest}/", ` +
+                            `or href: for an address that is already resolved`,
                 );
             }