@heroiclands/package-build 19.0.0 → 20.2.0

package/sohl/actors.mjs

@@ -63,6 +63,14 @@ import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
 // verbatim, and `sohl.img` / `sohl.effects` / `sohl.flags` overriding their
 // shared top-level forms for this system alone (#58).
 import { blockProperty, mergeSystemData } from "../engine/system-block.mjs";
+import { readField, retiredTopLevelKey } from "../engine/field-spec.mjs";
+// The retirement window's reports, shared with the frontmatter lint so the two
+// cannot say different things about the same key (#305, #332).
+import {
+    legacyKeyMessage,
+    locateFrontmatterKey,
+    retiredTopLevelMessage,
+} from "../engine/retired-fields.mjs";
 
 /**
  * The system this pass compiles for — the block its notes write.
@@ -81,6 +89,38 @@ const DEFAULT_IMG = {
     being: "systems/sohl/assets/icons/game-icons/delapouite/person.svg",
 };
 
+/**
+ * The being's sheet portrait — the one row of the content format's actor
+ * mapping table that is authored rather than derived.
+ *
+ * **Declared, because the position is not a spelling anyone can guess.** This
+ * was read with `blockProperty(fm, SYSTEM, "portrait")`, which knows the block
+ * and the note's top level and nothing else — so `data.portrait`, the position
+ * the specification names and `sohl-thalorna` writes on 646 beings, was
+ * invisible, and `?? defaultImg` on the next line turned every miss into the
+ * generic person icon rather than into a complaint (#332). Going through
+ * {@link module:engine/field-spec.readField} is what makes the mapping table
+ * executable here as it already is for HM3's `data.species`.
+ *
+ * `img` is deliberately **not** declared beside it: the mapping table keeps a
+ * note's token art at the top level, so `blockProperty` is the whole of its
+ * resolution and there is no `data.img` to reach for.
+ *
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+const PORTRAIT_FIELD = Object.freeze({
+    name: "data.portrait",
+    legacyKey: "portrait",
+    to: "portrait",
+    shape: "path",
+    // The two empties survive, because the caller's `?? defaultImg` is what
+    // tells them apart: `null` and an absent key mean "no art named, default
+    // me", `""` means "ship blank on purpose" (#218).
+    read: (raw) => resolveImg(raw),
+    default: null,
+    describe: "Path to the portrait image.",
+});
+
 /**
  * The default art for an actor subtype.
  *
@@ -206,21 +246,48 @@ export class Actors extends SystemActorCompiler {
                     this.errorCount++;
                     return;
                 }
-                const { shortcode, type, ...rest } = entry;
-                if (!type) {
-                    this.noteError(`${ctx}: sohl.items[${index}] missing type`);
+                const { model, shortcode, type, ...rest } = entry;
+                if (shortcode !== undefined) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] carries a top-level ` +
+                            `\`shortcode\` — that key is retired. Name the item ` +
+                            `this entry copies with \`model:\` (an address, e.g. ` +
+                            `\`${type ?? "skill"}-${shortcode}\`), and use ` +
+                            `\`system.shortcode\` for this item's own identity.`,
+                    );
+                    this.errorCount++;
+                    return;
+                }
+                const read = model === undefined ? null : this.readModel(model, index, ctx);
+                if (model !== undefined && !read) return;
+                if (read && type !== undefined) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] states both \`model\` and ` +
+                            `\`type\` — the model's address already names the ` +
+                            `type, so the second is a place to be wrong. Drop \`type\`.`,
+                    );
+                    this.errorCount++;
+                    return;
+                }
+                const effectiveType = read ? read.type : type;
+                if (!effectiveType) {
+                    this.noteError(
+                        `${ctx}: sohl.items[${index}] names no \`model\` and no ` +
+                            `\`type\` — an entry that copies nothing must state ` +
+                            `\`name\`, \`type\` and \`system.shortcode\`.`,
+                    );
                     this.errorCount++;
                     return;
                 }
                 const embedded = this.resolveEmbedded(
                     itemsMap,
                     actorId,
-                    type,
-                    shortcode || null,
+                    effectiveType,
+                    read ? read.shortcode : null,
                     rest,
                     `items:${index}`,
                     ctx,
-                    { fmKey: "items" },
+                    { fmKey: "items", modelPackage: read?.package ?? null },
                 );
                 if (embedded) items.push(embedded);
             });
@@ -298,6 +365,36 @@ export class Actors extends SystemActorCompiler {
         const { value: authoredFolder, isAddress } = folderField(fm);
         const folder = this.folderResolver(authoredFolder, { isAddress });
 
+        // The two retiring positions a declared field may be read from (#305,
+        // #332). **Warnings**, on the pattern every retirement in this package
+        // follows: the note compiles to the correct document either way, so
+        // reddening a tree over one would refuse before the sweep rather than
+        // after it. What they buy is a count — the whole reason #332 was
+        // invisible for so long is that nothing said which position a value
+        // had come from, and a default is indistinguishable from a miss.
+        const portraitReports = {
+            block: SYSTEM,
+            onLegacyKey: (field) =>
+                this.noteWarn(
+                    legacyKeyMessage(SYSTEM, field),
+                    locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
+                ),
+            // Anchored at column 1: the two positions share a spelling here —
+            // `sohl.portrait` and `portrait` — so a locator that took the first
+            // match would point at the block key while the message named the
+            // top-level one.
+            onRetiredTopLevel: (field) =>
+                this.noteWarn(
+                    retiredTopLevelMessage(field),
+                    locateFrontmatterKey(
+                        this.currentNote?.absPath,
+                        retiredTopLevelKey(field),
+                        undefined,
+                        { topLevel: true },
+                    ),
+                ),
+        };
+
         const system = {
             // The frontmatter shortcode is the actor's stable `(type, shortcode)`
             // key — and, for a being that is an archetype, its archetype
@@ -311,7 +408,9 @@ export class Actors extends SystemActorCompiler {
             templatePriority: systemTemplatePriority(fm, ctx),
             // Nullish, not `||` (#218): a note that names no portrait gets the
             // subtype's default, one that writes `""` ships blank on purpose.
-            portrait: resolveImg(blockProperty(fm, SYSTEM, "portrait")) ?? defaultImg,
+            // Resolved through the declaration so `data.portrait` is reached at
+            // all — see {@link PORTRAIT_FIELD} (#332).
+            portrait: readField(PORTRAIT_FIELD, fm, portraitReports) ?? defaultImg,
             appearance: renderSection(body || "", "appearance"),
             dossier: renderSection(body || "", "dossier"),
         };

package/sohl/item-fields.mjs

@@ -103,6 +103,40 @@ function noteContext(fm, type) {
     return `${type} "${fm?.name?.full ?? fm?.shortcode ?? "?"}"`;
 }
 
+/**
+ * A timed phase's duration **formula** — what is rolled to seed the interval.
+ *
+ * SoHL's own field is a nullable, non-blank `StringField`, and the interval it
+ * yields is in **seconds** (`"432000"` is the five days the world setting
+ * defaults to). A bare number is as valid as a dice expression, and both are
+ * stringified here so a note may write either — which is also why no `kind` is
+ * declared: a lint claiming this must be a string would report `86400` as an
+ * authoring mistake when it is the commonest thing to write.
+ *
+ * Blank reads as unset rather than as `""`, matching the field's `blank: false`
+ * — but a field declaring {@link FieldSpec.omitWhenAbsent} skips before this
+ * runs when the note carries nothing, so the `null` is only ever reached by a
+ * note that cleared the key on purpose.
+ */
+const DURATION_FORMULA = Object.freeze({
+    shape: "roll formula, or a whole number of seconds",
+    read: (raw) => (raw == null || raw === "" ? null : String(raw)),
+});
+
+/**
+ * A timed phase's rolled duration, in **seconds** — the fact, where the formula
+ * above is the definition.
+ *
+ * Authoring it states the interval outright instead of leaving it to a roll,
+ * which is what a fixed-cadence phase wants. Non-numeric reads `0` rather than
+ * `NaN`, as every other count in this vocabulary does.
+ */
+const DURATION_BASE = Object.freeze({
+    shape: "whole number of seconds",
+    kind: "number",
+    read: (raw) => (raw == null || raw === "" ? null : Number(raw) || 0),
+});
+
 /** Aptitude weights per skill selector, validated as whole numbers. */
 const SKILL_APTITUDES = Object.freeze({
     shape: "map of skill selector → whole number",
@@ -414,6 +448,104 @@ export const ITEM_FIELDS = Object.freeze({
             describe:
                 "What running the course to the end does to the host: `death`, or the benign default `cured`.",
         },
+        // The two **authored** thirds of each timed-phase triplet (#329). Every
+        // one omits its key when the note does not carry it, because the value
+        // that stands otherwise is the DataModel's `initial: null` — writing a
+        // compile-time `null` over it would say "this phase takes no time",
+        // which is a different claim from "this note does not set the phase",
+        // and `AfflictionLogic.rollDuration()` opens `if (!formula) return 0`.
+        //
+        // Until they were declared here the only way to author one was the raw
+        // `system:` passthrough — undocumented, uncoerced, and absent from the
+        // field list every author-facing surface is built from — so no note in
+        // any tree wrote one and every shipped affliction had zero-length
+        // phases.
+        // Spelled out, one entry per field, for the reason the dates below are:
+        // a name assembled from a phase argument is not in the source, so it
+        // cannot be grepped, and each phase's prose differs anyway — which is
+        // the whole content of the declaration.
+        {
+            name: "onsetDurationFormula",
+            to: "onsetDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval from contracting the affliction to the start of onset. Omitted when unset, leaving no incubation.",
+        },
+        {
+            name: "onsetDurationBase",
+            to: "onsetDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The onset interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        {
+            name: "healingCheckDurationFormula",
+            to: "healingCheckDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between healing checks, once the affliction is symptomatic. Omitted when unset.",
+        },
+        {
+            name: "healingCheckDurationBase",
+            to: "healingCheckDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        {
+            name: "resolutionDurationFormula",
+            to: "resolutionDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval from onset to the affliction running its course. Omitted when unset.",
+        },
+        {
+            name: "resolutionDurationBase",
+            to: "resolutionDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The resolution interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        // The `…Date` third of every timed-phase triplet, declared as **runtime
+        // state** (#330). A phase is authored as its `…DurationFormula`; the
+        // `…DurationBase` records what that rolled to; the date records *when
+        // it happened*, and only play can know that. All four are
+        // `worldTimeDateField()`s in SoHL's schema — nullable rather than
+        // sentinelled precisely because `0` is itself a valid world time — so
+        // there is no blank an author could honestly write either.
+        //
+        // Declaring them does two things at once: the key is left out of the
+        // compiled document, so SoHL's own `initial: null` stands, and a note
+        // authoring one is refused with a message naming the field and its
+        // reason. Written out rather than generated from a phase name, as the
+        // schema they mirror now is: a field name assembled from an argument is
+        // not in the source, and cannot be grepped, read or reported on.
+        {
+            to: "contractDate",
+            runtimeOnly: "the world time the host contracted the affliction",
+            describe: "When the host contracted it. Play state, never authored.",
+        },
+        {
+            to: "onsetDate",
+            runtimeOnly: "the world time onset fired at",
+            describe: "When onset fired. Play state, never authored.",
+        },
+        {
+            to: "treatmentDate",
+            runtimeOnly: "the world time the affliction was last treated",
+            describe: "When it was last treated. Play state, never authored.",
+        },
+        {
+            to: "resolutionDate",
+            runtimeOnly: "the world time the affliction ran its course",
+            describe: "When it resolved. Play state, never authored.",
+        },
     ]),
 
     armorgear: Object.freeze([
@@ -817,6 +949,77 @@ export const ITEM_FIELDS = Object.freeze({
             default: null,
             describe: "Shortcode of the body location injured. Unset on a descriptive condition.",
         },
+        // A trauma's three timed phases (#329). Its healing check and course
+        // both fall back to a **world setting** when the trauma sets neither
+        // half, which is the sharper reason these omit rather than default: a
+        // compile-time `null` written here is still a value, and the seeding in
+        // `TraumaDataModel._preCreate` reads `data.courseDurationFormula == null`
+        // to decide whether the GM's configured interval applies. A default
+        // would answer that question for every trauma in every world.
+        //
+        // `bloodLossAdvance*` is the one an author reaches for most: a trauma
+        // that sets it bleeds, and one that leaves it unset does not.
+        {
+            name: "healingCheckDurationFormula",
+            to: "healingCheckDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between healing checks. Omitted when unset, leaving the world's configured interval to apply.",
+        },
+        {
+            name: "healingCheckDurationBase",
+            to: "healingCheckDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The healing-check interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        {
+            name: "bloodLossAdvanceDurationFormula",
+            to: "bloodLossAdvanceDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between blood-loss advances. Omitted when unset, leaving the world's configured interval to apply.",
+        },
+        {
+            name: "bloodLossAdvanceDurationBase",
+            to: "bloodLossAdvanceDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The blood-loss interval in seconds. Setting it is what makes the wound bleed; omitted when unset, and the wound does not.",
+        },
+        {
+            name: "courseDurationFormula",
+            to: "courseDurationFormula",
+            ...DURATION_FORMULA,
+            omitWhenAbsent: true,
+            describe:
+                "Interval between course tests, for a condition that runs one — shock, coma, infection. Omitted when unset.",
+        },
+        {
+            name: "courseDurationBase",
+            to: "courseDurationBase",
+            ...DURATION_BASE,
+            omitWhenAbsent: true,
+            describe:
+                "The course-test interval in seconds, standing in for a roll of the formula. Omitted when unset.",
+        },
+        // Runtime state, for the reason `affliction`'s four are (#330): a
+        // trauma's dates are crystallized when the phase fires, and world time
+        // does not exist while content is compiled.
+        {
+            to: "contractDate",
+            runtimeOnly: "the world time the injury was taken",
+            describe: "When the injury was taken. Play state, never authored.",
+        },
+        {
+            to: "treatmentDate",
+            runtimeOnly: "the world time the injury was last treated",
+            describe: "When it was last treated. Play state, never authored.",
+        },
     ]),
 
     weapongear: Object.freeze([

package/sohl/note-schemas.mjs

@@ -148,8 +148,8 @@ const BEING_FIELDS = Object.freeze([
  *
  * `img` is the one required field — the compiler refuses a map note without it,
  * since a scene with no background is not a map. It was spelled `image` and
- * read from the `sohl:` block until #142; both spellings still compile, and the
- * retired one is reported rather than refused.
+ * read from the `sohl:` block until #142, which read both while the trees were
+ * swept; that retirement has since completed and `image` is gone (#149).
  *
  * @type {readonly import("../engine/field-spec.mjs").FieldSpec[]}
  */
@@ -161,7 +161,10 @@ const MAP_FIELDS = Object.freeze([
         // Art is not system-specific — a Scene is a core Foundry document, and
         // every other note type carries its `img` at the note's top level.
         shared: true,
-        describe: "The scene's background image.",
+        describe:
+            "The scene's background image. Owned by whichever package its first segment " +
+            "names — `systems/…` and `modules/…` are emitted unchanged, anything else is " +
+            "this package's own and is rooted under its assets.",
     },
     {
         name: "dimensions",

package/types/config.d.mts

@@ -55,6 +55,8 @@
  * @property {string} e2eStage       Which stage the suite runs against.
  * @property {Readonly<{run: readonly string[], open: readonly string[]|null}>|null} e2eSuite
  *   What to run against the served world; `null` when the repository has none.
+ * @property {readonly string[]} e2eResults  Where the suite writes its results,
+ *   so a run that wrote none is not mistaken for one that passed.
  * @property {Readonly<Record<string, Readonly<{script: string, recreate: boolean}>>>} e2eBuild
  *   Build targets the fast loop can produce, in declaration order.
  * @property {Readonly<Record<string, string>>} e2eWorld  Declared world identity.
@@ -260,6 +262,11 @@ export type PackageBuildConfig = {
         run: readonly string[];
         open: readonly string[] | null;
     }> | null;
+    /**
+     * Where the suite writes its results,
+     * so a run that wrote none is not mistaken for one that passed.
+     */
+    e2eResults: readonly string[];
     /**
      *   Build targets the fast loop can produce, in declaration order.
      */

package/types/e2e.d.mts

@@ -188,6 +188,106 @@ export function waitForWorld({ url, container, stage, timeoutMs, log }: {
     timeoutMs?: number | undefined;
     log?: ((message: string) => void) | undefined;
 }): Promise<void>;
+/**
+ * Every executable that must exist for a suite command to run at all.
+ *
+ * One name for a plain command, two when a package runner is standing in for a
+ * tool. This is deliberately a *reading* of the command rather than a guess:
+ * anything it cannot read reduces to the program alone, because naming the
+ * wrong missing thing would send someone after a dependency they already have.
+ *
+ * @param {readonly string[]} command - The program and its arguments.
+ * @returns {string[]} The executables to resolve, in the order to report them.
+ */
+export function suiteExecutables(command: readonly string[]): string[];
+/**
+ * Find an executable the way the child process will: a path is a path, and a
+ * bare name is looked for in the repository's `node_modules/.bin` first, then
+ * along `PATH`.
+ *
+ * @param {string} name - The program, as the command line spells it.
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - The repository root, for `node_modules/.bin`.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read `PATH` from.
+ * @returns {string|null} Where it is, or `null` if it is nowhere.
+ */
+export function findExecutable(name: string, { cwd, env }?: {
+    cwd?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+}): string | null;
+/**
+ * Which of a suite command's executables are not there.
+ *
+ * Asked twice per run, and the second asking is the point: an install running
+ * alongside the suite can take the runner out from under it mid-flight, which
+ * is precisely the failure that reported itself as green (#153).
+ *
+ * @param {object} opts
+ * @param {readonly string[]} opts.command - The program and its arguments.
+ * @param {string} [opts.cwd] - The repository root.
+ * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
+ * @returns {string[]} The names that resolve to nothing.
+ */
+export function missingExecutables({ command, cwd, env }: {
+    command: readonly string[];
+    cwd?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+}): string[];
+/**
+ * Which declared result paths the suite actually wrote to during this run.
+ *
+ * Existence is not the test. A results directory left behind by the previous
+ * run exists, and reading that as evidence would make the check agree with
+ * exactly the thing it was built to catch. What counts is a file modified since
+ * the spawn.
+ *
+ * @param {object} opts
+ * @param {readonly string[]} opts.paths - Declared result paths, repo-relative.
+ * @param {number} opts.since - Milliseconds since the epoch, at spawn time.
+ * @param {string} [opts.cwd] - The repository root.
+ * @returns {string[]} The declared paths carrying something new.
+ */
+export function freshResults({ paths, since, cwd }: {
+    paths: readonly string[];
+    since: number;
+    cwd?: string | undefined;
+}): string[];
+/**
+ * What the harness reports for a finished suite.
+ *
+ * @typedef {object} SuiteVerdict
+ * @property {number} status        The exit status to hand back.
+ * @property {string|null} message  What to say about it, if anything.
+ */
+/**
+ * Decide what a finished suite is worth, given what it exited with and what it
+ * left behind.
+ *
+ * The point of the e2e suite is to be *evidence*: `compatibility.verified`
+ * moves on a green run, and a sweep exists to produce a citable result. So an
+ * exit status on its own cannot call a run green, because every way of stopping
+ * a runner before it starts — a corrupt install, a missing browser, a killed
+ * process, the concurrent `npm ci` that surfaced this — produces a run that
+ * executed nothing, and nothing is not a pass (#153).
+ *
+ * This can only ever make a verdict worse. A suite that failed keeps its own
+ * status; a suite that passed on no evidence loses the claim. Never the other
+ * way round — a harness that could *upgrade* a result would be a second way to
+ * report a green that did not happen.
+ *
+ * @param {object} opts
+ * @param {number} opts.status - What the suite process exited with.
+ * @param {readonly string[]} [opts.vanished] - Executables gone since it started.
+ * @param {readonly string[]} [opts.declared] - Result paths the repository declares.
+ * @param {readonly string[]} [opts.fresh] - Those of them it wrote to.
+ * @returns {SuiteVerdict} The status to report, and why.
+ */
+export function suiteVerdict({ status, vanished, declared, fresh }: {
+    status: number;
+    vanished?: readonly string[] | undefined;
+    declared?: readonly string[] | undefined;
+    fresh?: readonly string[] | undefined;
+}): SuiteVerdict;
 /**
  * Run the repository's suite.
  *
@@ -196,18 +296,32 @@ export function waitForWorld({ url, container, stage, timeoutMs, log }: {
  * runner launches as plain Node, rejects its own flags, and dies with a
  * `MODULE_NOT_FOUND` naming nothing relevant.
  *
+ * The suite is bracketed by checks rather than trusted on its exit status,
+ * because a run that never started used to report as green (#153):
+ *
+ * - **Before.** Every executable the command needs is resolved, and a missing
+ *   one is an error naming it — rather than a container stood up, a world
+ *   seeded, and a failure three minutes later that names nothing.
+ * - **After.** The same question again, because the reported failure was an
+ *   install pulling the runner out from under a run already in progress; and,
+ *   where the repository declares where its results land, whether anything was
+ *   written there while the suite ran.
+ *
  * @param {object} opts
- * @param {string[]} opts.command - The program and its arguments.
+ * @param {readonly string[]} opts.command - The program and its arguments.
  * @param {string[]} [opts.args] - Extra arguments, appended verbatim.
  * @param {string} opts.cwd - The repository root.
+ * @param {readonly string[]} [opts.results] - Declared result paths to check.
  * @param {NodeJS.ProcessEnv} [opts.env] - Environment for the child.
  * @param {(message: string) => void} [opts.log] - Progress reporting.
  * @returns {number} The suite's exit status.
+ * @throws {Error} When the command names an executable that is not installed.
  */
-export function runSuite({ command, args, cwd, env, log }: {
-    command: string[];
+export function runSuite({ command, args, cwd, results, env, log, }: {
+    command: readonly string[];
     args?: string[] | undefined;
     cwd: string;
+    results?: readonly string[] | undefined;
     env?: NodeJS.ProcessEnv | undefined;
     log?: ((message: string) => void) | undefined;
 }): number;
@@ -349,3 +463,16 @@ export type FastArgs = {
      */
     suiteArgs: string[];
 };
+/**
+ * What the harness reports for a finished suite.
+ */
+export type SuiteVerdict = {
+    /**
+     * The exit status to hand back.
+     */
+    status: number;
+    /**
+     * What to say about it, if anything.
+     */
+    message: string | null;
+};