@heroiclands/package-build 9.0.0 → 10.0.0

package/engine/pack-config.mjs

@@ -431,9 +431,10 @@ export function locateConfigError(err, configPath) {
  * - **`rootDir`** is the configuration's own directory, always. A data file
  *   cannot write `import.meta.dirname`, and any absolute path it wrote instead
  *   would be one machine's — so authoring it is rejected rather than honoured.
- * - **`itemBuilders`** is a *name* (`sohl`), resolved against the built-in
- *   registries. A registry of a consumer's own is code, and code goes in an
- *   `.mjs` configuration.
+ * - **`itemBuilders`** is a *name* (`sohl`) — or a list of names, for a tree
+ *   feeding more than one system (#58) — resolved against the built-in
+ *   registries. A registry's name is the system it belongs to. A registry of a
+ *   consumer's own is code, and code goes in an `.mjs` configuration.
  * - **`stats.systemVersion`** is derived from the adjacent `package.json` when
  *   the configuration does not state it. Stating it is still allowed: a
  *   repository shipping content *for* another package (a module declaring
@@ -482,26 +483,42 @@ export function configFromData(data, configPath) {
     input.foundryPackage = foundryPackageId(rootDir);
 
     if (input.itemBuilders !== undefined) {
-        const named = input.itemBuilders;
+        const declared = input.itemBuilders;
         const known = Object.keys(ITEM_BUILDER_REGISTRIES).join(", ");
-        if (typeof named !== "string") {
-            throw new Error(
-                `package-build: ${configPath} must name its \`itemBuilders\` ` +
-                    `registry as a string — the registry is code, and data ` +
-                    `cannot carry it. Known registries: ${known}; a registry ` +
-                    `of your own goes in ${CONFIG_BASENAME}.mjs.`,
-            );
-        }
-        const load = ITEM_BUILDER_REGISTRIES[named];
-        if (!load) {
-            throw new Error(
-                `package-build: ${configPath} names the \`itemBuilders\` ` +
-                    `registry "${named}", which this package does not ship. ` +
-                    `Known registries: ${known}. To supply your own, declare ` +
-                    `it in ${CONFIG_BASENAME}.mjs.`,
-            );
-        }
-        input.itemBuilders = load();
+        // One name or several. A repository feeding two systems needs both
+        // vocabularies, and one registry can only carry one (#58); the scalar
+        // form every existing configuration uses is the one-element case and
+        // means exactly what it always did.
+        const names = Array.isArray(declared) ? declared : [declared];
+        const resolved = names.map((named, index) => {
+            const where = Array.isArray(declared) ? `itemBuilders[${index}]` : "itemBuilders";
+            if (typeof named !== "string") {
+                throw new Error(
+                    `package-build: ${configPath} must name its \`${where}\` ` +
+                        `registry as a string — the registry is code, and data ` +
+                        `cannot carry it. Known registries: ${known}; a registry ` +
+                        `of your own goes in ${CONFIG_BASENAME}.mjs.`,
+                );
+            }
+            const load = ITEM_BUILDER_REGISTRIES[named];
+            if (!load) {
+                throw new Error(
+                    `package-build: ${configPath} names the \`${where}\` ` +
+                        `registry "${named}", which this package does not ship. ` +
+                        `Known registries: ${known}. To supply your own, declare ` +
+                        `it in ${CONFIG_BASENAME}.mjs.`,
+                );
+            }
+            // A shipped registry's *name* is the system it belongs to, which is
+            // what lets a data configuration declare a set without carrying the
+            // system id a second time.
+            return { system: named, builders: load() };
+        });
+        // The scalar form stays the flat, system-less registry it has always
+        // resolved to. Wrapping it as a one-entry set would be tidier and would
+        // change what every existing configuration means — `itemBuildersBySystem`
+        // would gain an entry the consumer never declared.
+        input.itemBuilders = Array.isArray(declared) ? resolved : resolved[0].builders;
     }
 
     const stats = input.stats;

package/engine/pack-router.mjs

@@ -47,12 +47,18 @@
  * - A note's **derived** documents are routed by the default of *their* type,
  *   not by the note's declaration: an item note's prose compiles into a
  *   JournalEntry, and `pack:` names where the *item* goes.
+ * - A note feeding **more than one system** declares `pack:` inside the block
+ *   that differs (#58). `pack` needed no new mechanism for that: it is an
+ *   ordinary shared property, so `<system>.pack` overrides the top-level one
+ *   for that system's document and leaves it standing for every other. A note
+ *   wanting one pack for both says it once at the top.
  *
  * @module
  */
 
 import { packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { blockProperty } from "./system-block.mjs";
 
 /**
  * A note that cannot be routed to a pack. Thrown rather than returned so no
@@ -84,8 +90,8 @@ export const PACK_FIELD = "pack";
  *
  * @param {readonly object[]} packs - The resolved `packs` list from
  *   `defineConfig`.
- * @returns {{resolve: (fm: object, docType: string) => string,
- *   resolveOrNull: (fm: object, docType: string) => string|undefined,
+ * @returns {{resolve: (fm: object, docType: string, system?: string) => string,
+ *   resolveOrNull: (fm: object, docType: string, system?: string) => string|undefined,
  *   packsOfType: (docType: string) => string[],
  *   defaultOf: (docType: string) => string|undefined}} The router.
  */
@@ -124,11 +130,15 @@ export function createPackRouter(packs) {
      *
      * @param {object} fm - The note's frontmatter.
      * @param {string} docType - The document type the calling pass writes.
+     * @param {string} [system] - The system whose document is being routed. Its
+     *   block's `pack:` wins over the shared one; without it only the shared
+     *   declaration is read, which is every single-system build.
      * @returns {string} The pack name.
      * @throws {PackRoutingError} When the note routes nowhere.
      */
-    function resolve(fm, docType) {
-        const declared = fm?.[PACK_FIELD];
+    function resolve(fm, docType, system) {
+        const declared =
+            system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
         // The declaration names where the note's *own* document goes. A pass
         // writing a document derived from it — an item's prose becoming a
         // JournalEntry — is not what the author was addressing.
@@ -189,11 +199,12 @@ export function createPackRouter(packs) {
          *
          * @param {object} fm - The note's frontmatter.
          * @param {string} docType - The document type being addressed.
+         * @param {string} [system] - The system whose document is addressed.
          * @returns {string|undefined} The pack name, or `undefined`.
          */
-        resolveOrNull(fm, docType) {
+        resolveOrNull(fm, docType, system) {
             try {
-                return resolve(fm, docType);
+                return resolve(fm, docType, system);
             } catch {
                 return undefined;
             }

package/engine/prose-lint.mjs

@@ -61,6 +61,23 @@ const NEVER_WALK = Object.freeze(new Set([".git", "node_modules"]));
  */
 const IGNORE_FILES = Object.freeze([".gitignore", ".prettierignore"]);
 
+/**
+ * How many times `--write` will format one file looking for a fixpoint.
+ *
+ * `format` is *assumed* idempotent and is not guaranteed to be: a single pass
+ * can leave text the next pass would still change, and a `--write` run that
+ * takes one pass then reports success has called such a file formatted while
+ * `prettier --check` still rejects it (#125). Formatting to a fixpoint removes
+ * the assumption — the file lands on the value repeated formatting converges
+ * to, whatever it took to get there.
+ *
+ * Three, not "until it stops": a file that oscillates would loop forever, and
+ * the cap turns that into a report. Three is enough for the case this is for
+ * (one pass short) with a pass to spare, and costs nothing on a tree that is
+ * already formatted, where the first pass converges immediately.
+ */
+const MAX_FORMAT_PASSES = 3;
+
 /**
  * Every file under a root, minus the directories nothing should walk.
  *
@@ -106,11 +123,15 @@ function walkFiles(root) {
  * @param {readonly string[]} [opts.paths] - Files or directories to check
  *   instead of the whole root.
  * @param {boolean} [opts.write=false] - Rewrite unformatted files in place
- *   rather than reporting them.
+ *   rather than reporting them. Each file is formatted to a fixpoint (up to
+ *   {@link MAX_FORMAT_PASSES} passes), so a written tree is one a second run
+ *   leaves alone; a file that will not converge is reported and left unchanged
+ *   (#125).
  * @param {object} [opts.prettier] - The Prettier module, for tests.
  * @returns {Promise<{findings: Array<{file: string, severity: string,
  *   message: string}>, checked: number, written: string[]}>} The findings, how
- *   many files were considered, and what was rewritten.
+ *   many files were considered, and what was rewritten. `--write` reports
+ *   findings too — a file it cannot parse, or cannot format to a fixpoint.
  */
 export async function checkFormatting(root, opts = {}) {
     const { paths, write = false } = opts;
@@ -155,7 +176,38 @@ export async function checkFormatting(root, opts = {}) {
         // every other one.
         try {
             if (write) {
-                const formatted = await prettier.format(source, options);
+                // Format to a fixpoint rather than once, so what lands on disk
+                // is what a second run would have produced (#125).
+                let formatted = source;
+                let converged = false;
+                for (let pass = 0; pass < MAX_FORMAT_PASSES; pass += 1) {
+                    const next = await prettier.format(formatted, options);
+                    if (next === formatted) {
+                        converged = true;
+                        break;
+                    }
+                    formatted = next;
+                }
+
+                if (!converged) {
+                    // Nothing is written. A formatting the command cannot
+                    // reproduce is not one to commit to disk — writing it
+                    // would make `--write` churn the file on every run — and a
+                    // file that never settles is a defect somewhere that has
+                    // to be named rather than absorbed.
+                    findings.push({
+                        file,
+                        severity: "error",
+                        // No line or column: the verdict is about the whole
+                        // file, and #17's rule is to drop a field rather than
+                        // invent one.
+                        message:
+                            `did not converge after ${MAX_FORMAT_PASSES} formatting passes; ` +
+                            "left unchanged",
+                    });
+                    continue;
+                }
+
                 if (formatted !== source) {
                     fs.writeFileSync(file, formatted);
                     written.push(file);

package/engine/retired-fields.mjs

@@ -34,12 +34,24 @@
  * *unresolvable*, silently — and it also suppressed real build failures, since
  * a note the compilers never reached could not fail on the defects it carried.
  *
+ * **A field retired in favour of another is a third case (#142).** `draft:` and
+ * `package:` were retired outright: nothing replaced them, so no value made
+ * writing one right and refusal was the only honest answer. A *renamed* field
+ * has a replacement, and the two spellings mean the same thing — so the note
+ * still compiles, correctly, and refusing it would fail a build over a document
+ * that is not wrong. Those retire in the three steps `package:` took (#56), and
+ * this module carries the **first**: both spellings are read, the current one
+ * wins, and the retired one is *reported* rather than refused. The sweep and
+ * the refusal come later, once no tree writes it. See
+ * {@link RETIRED_FIELD_ALIASES}.
+ *
  * @module
  */
 
 import fs from "node:fs";
 
 import { positionInFrontmatter } from "./diagnostics.mjs";
+import { sohlField } from "./frontmatter.mjs";
 
 /**
  * What a note declaring `draft:` is told, in one place.
@@ -105,12 +117,15 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
  * both refusals need it and a second copy is a second thing to keep correct.
  *
  * @param {string|undefined} absPath - The note's file.
- * @param {string} key - The top-level frontmatter key.
+ * @param {string} key - The frontmatter key.
+ * @param {string} [value] - When given, prefer the occurrence whose line also
+ *   carries this text — so a finding about one entry of a block opens on that
+ *   entry rather than on the key that introduces it.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath, key) {
+export function locateFrontmatterKey(absPath, key, value = undefined) {
     if (!absPath) return undefined;
     let raw;
     try {
@@ -118,6 +133,105 @@ export function locateFrontmatterKey(absPath, key) {
     } catch {
         return undefined;
     }
-    const at = positionInFrontmatter(raw, key);
+    const at = positionInFrontmatter(raw, key, value);
     return at.line === undefined ? undefined : at;
 }
+
+/* -------------------------------------------------------------------- */
+/*  Retired *in favour of another field*                                 */
+/* -------------------------------------------------------------------- */
+
+/**
+ * The current field name a retired spelling was renamed to.
+ *
+ * Keyed by the **current** name, because that is what a type's schema declares
+ * and what every reader asks for; the value is the spelling still honoured.
+ * The table is therefore scoped by the schema without saying so twice: an alias
+ * applies to a note only where that note's type declares the current field, so
+ * `image` is retired on a map — which declares `img` — and remains an unknown
+ * key anywhere else.
+ *
+ * **`img` (#142).** Every note type names its artwork `img`, at the note's top
+ * level, and resolves it the same way. A map alone named its background art
+ * `image` and read it out of the `sohl:` block — two spellings for one idea,
+ * with nothing to reconcile them, and a specification that had to hedge rather
+ * than state a rule. Art is not system-specific: a Scene is a core Foundry
+ * document and HM3 would want the identical one, so the field belongs beside
+ * every other note's `img`, not inside a system block.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const RETIRED_FIELD_ALIASES = Object.freeze({ img: "image" });
+
+/**
+ * What a note writing a renamed field is told, in one place.
+ *
+ * Shared by the compile-time report and the frontmatter lint, because an author
+ * meets whichever runs first and they should read the same. It names the key to
+ * write rather than a value to correct — no value makes the retired spelling
+ * right — and it says the note compiles either way, so a reader knows this is a
+ * rename to schedule rather than a build to unbreak.
+ *
+ * @param {string} retired - The spelling the note used.
+ * @param {string} current - What to write instead.
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function retiredAliasMessage(retired, current, file) {
+    return (
+        `\`${retired}:\` is a retired frontmatter field — write \`${current}:\` ` +
+        `instead` +
+        (file ? ` — ${file}` : "") +
+        `. Both are read and \`${current}\` wins, so the note compiles ` +
+        `identically either way; \`${retired}\` is removed in a later release`
+    );
+}
+
+/**
+ * Whether a note writes the retired spelling of a field, wherever it put it.
+ *
+ * Both regions are searched, because {@link sohlField} reads both: a note that
+ * moved the key to the top level without renaming it has done half the
+ * migration, and should be told so rather than passing in silence.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} current - The field's current name.
+ * @returns {boolean} Whether the retired spelling is declared.
+ */
+export function declaresRetiredAlias(fm, current) {
+    const retired = RETIRED_FIELD_ALIASES[current];
+    if (!retired || !fm || typeof fm !== "object") return false;
+    const block = fm.sohl;
+    const inBlock =
+        block &&
+        typeof block === "object" &&
+        !Array.isArray(block) &&
+        Object.hasOwn(block, retired);
+    return Boolean(inBlock) || Object.hasOwn(fm, retired);
+}
+
+/**
+ * Read a field that has a retired spelling, the current name winning.
+ *
+ * This is the whole of the retirement window's behaviour, in one function, so
+ * the compiler and the linter cannot disagree about which value a note carries.
+ * Resolution within each spelling is {@link sohlField}'s — the `sohl:` block
+ * first, then the note's top level — so a renamed field keeps working wherever
+ * it was already written while the canonical home is the top level.
+ *
+ * A blank value counts as absent: `img:` cleared in an editor means the note
+ * names no art there, and falling through to the retired spelling is what an
+ * author part-way through the rename means by it.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} current - The field's current name.
+ * @returns {any} The value, or `undefined` when neither spelling carries one.
+ */
+export function readAliasedField(fm, current) {
+    const value = sohlField(fm, current, undefined);
+    if (value !== undefined && value !== null && value !== "") return value;
+    const retired = RETIRED_FIELD_ALIASES[current];
+    return retired ? sohlField(fm, retired, undefined) : undefined;
+}

package/engine/scenes.mjs

@@ -59,6 +59,13 @@ import { packRouter } from "./pack-router.mjs";
 import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
 import { behaviorDocId, buildScene, isMapType, regionDocId } from "./map-notes.mjs";
+import {
+    RETIRED_FIELD_ALIASES,
+    declaresRetiredAlias,
+    locateFrontmatterKey,
+    readAliasedField,
+    retiredAliasMessage,
+} from "./retired-fields.mjs";
 
 /**
  * Every SoHL action name this build knows about, for the `action:` warning on a
@@ -378,6 +385,17 @@ export class Scenes extends BasePackCompiler {
         // pass has to read the other's output.
         const entryId = hasBody ? itemDocEntryId(fm.id) : undefined;
         const folder = this.folderResolver(sohlField(fm, "folder", null));
+        // The retired spelling of the background art, reported where an author
+        // meets it soonest — every consumer runs the compile, and not every
+        // one runs the lint (#142). Located by reading the note back, which is
+        // what the other retired-field reports do: this is the one path that
+        // needs the position, so it is paid for only here.
+        if (declaresRetiredAlias(fm, "img")) {
+            this.noteWarn(
+                retiredAliasMessage(RETIRED_FIELD_ALIASES.img, "img"),
+                locateFrontmatterKey(this.currentNote?.absPath, RETIRED_FIELD_ALIASES.img),
+            );
+        }
         const warnings = [];
         const scene = buildScene(fm, {
             packageId: foundryPackageId(),
@@ -423,7 +441,7 @@ export class Scenes extends BasePackCompiler {
             this.places.set(placeKey, {
                 key: placeKey,
                 name: sohlField(fm, "placeName", null) || name,
-                img: sohlField(fm, "image", null),
+                img: readAliasedField(fm, "img") ?? null,
                 pinned: false,
                 scenes: [],
                 journal: [],