@heroiclands/package-build 20.0.0 → 20.2.0

package/content-config.mjs

@@ -1370,6 +1370,52 @@ function normalizeCompatibility(value, where, requireMinimum = true) {
  * @param {unknown} value - The declared `systems:` mapping.
  * @returns {Readonly<Record<string, Readonly<object>>>} Frozen; `{}` when absent.
  */
+/**
+ * The **package-wide** system, or `null` where the configuration names none
+ * (#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.
+ *
+ * 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 `systems:` 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 that split
+ * exists to remove. Several entries have no single answer and get none.
+ *
+ * **Written once and read twice**, which is why it is a function rather than the
+ * expression it used to be: the value stamped into `stats.systemId` and the
+ * value a pack's `system:` is validated against are the same fact, and two
+ * spellings of it would be free to disagree about exactly the case that has no
+ * answer.
+ *
+ * @param {object} parts - The resolved pieces of the configuration.
+ * @param {string} parts.packageKind - `systems` or `modules`.
+ * @param {unknown} parts.foundryPackage - The package id.
+ * @param {string|null} parts.requiresSystem - The declared gate, if any.
+ * @param {Readonly<Record<string, object>>} parts.systems - The `systems:` block.
+ * @param {readonly {id?: string}[]} parts.relationshipSystems - System
+ *   relationships.
+ * @returns {string|null} The system id, or `null` where there is no single one.
+ */
+function packageWideSystemId({
+    packageKind,
+    foundryPackage,
+    requiresSystem,
+    systems,
+    relationshipSystems,
+}) {
+    if (packageKind === "systems") return /** @type {string} */ (foundryPackage);
+    if (requiresSystem) return requiresSystem;
+    const declared = Object.keys(systems);
+    if (declared.length === 1) return declared[0];
+    if (relationshipSystems.length === 1) return relationshipSystems[0]?.id ?? null;
+    return null;
+}
+
 function normalizeSystems(value) {
     if (value === undefined || value === null) return Object.freeze({});
     if (!isPlainObject(value)) fail("systems", "must be a mapping of id to spec");
@@ -1875,6 +1921,15 @@ export function defineConfig(config) {
     const relationshipSystems = /** @type {{id?: string}[]} */ (
         (isPlainObject(input.relationships) ? input.relationships.systems : null) ?? []
     );
+    // Read here as well as stamped below, so the check that a pack's `system:`
+    // resolves to something and the value it resolves to are one statement.
+    const packageWide = packageWideSystemId({
+        packageKind,
+        foundryPackage: input.foundryPackage,
+        requiresSystem,
+        systems,
+        relationshipSystems,
+    });
 
     // 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
@@ -1891,11 +1946,35 @@ export function defineConfig(config) {
     }
     for (const pack of packs.flatMap((p) => [p, ...p.companions])) {
         if (!pack.system) continue;
-        if (declaredSystems.size && !declaredSystems.has(pack.system)) {
+        // **A pack's `system:` must resolve to a stamp**, and there are exactly
+        // two things it can resolve to: a `systems:` entry, which carries the
+        // verified version `statsForPack` reads, or this package's own
+        // package-wide system, whose stats answer for every pack of it.
+        //
+        // This used to be skipped entirely when `systems:` was empty or absent
+        // — `declaredSystems.size &&` guarded it — which left the case the
+        // comment above was written about wide open. `harn-ensemble` declares
+        // `system: sohl` and `system: hm3` on its packs, no `systems:` block,
+        // and no package-wide system, so every pack fell through to a
+        // package-wide stat that is null: 2,513 compiled actors stamped
+        // `_stats.systemId: null` in a pack that says `system: sohl` on the
+        // line above. That is the plausible lie #43 was about, reached by the
+        // one path this check did not cover, and the `requiresSystem` check ten
+        // lines up already refuses its own version of it in as many words.
+        if (!declaredSystems.has(pack.system) && pack.system !== packageWide) {
             fail(
                 `packs.${pack.name}.system`,
-                `names \`${pack.system}\`, which \`systems:\` does not ` +
-                    `declare. Declared: ${[...declaredSystems].join(", ")}`,
+                `names \`${pack.system}\`, which \`systems:\` does not declare` +
+                    (declaredSystems.size ?
+                        ` (declared: ${[...declaredSystems].join(", ")})`
+                    :   ` — the \`systems:\` block is empty or absent`) +
+                    (packageWide ?
+                        `, and which is not this package's own system \`${packageWide}\``
+                    :   `, and this package has no package-wide system either`) +
+                    `. Every document in the pack is stamped \`_stats.systemId\` ` +
+                    `and \`systemVersion\` from one of those two, so with ` +
+                    `neither it would be stamped null. Add \`systems:\` naming ` +
+                    `\`${pack.system}\` with a \`compatibility.verified\` version`,
             );
         }
         // With a gate set, a pack for any other system could never be seen:
@@ -1979,21 +2058,13 @@ export function defineConfig(config) {
         // 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,
+            systemId: packageWideSystemId({
+                packageKind,
+                foundryPackage,
+                requiresSystem,
+                systems,
+                relationshipSystems,
+            }),
             // 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

package/e2e.mjs

@@ -40,6 +40,7 @@
  */
 
 import crypto from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -557,6 +558,253 @@ function captureContainerLog(container) {
     return `${result.stdout ?? ""}${result.stderr ?? ""}`;
 }
 
+/**
+ * Programs a package runner is only a way of *naming*.
+ *
+ * `npx cypress run` does not fail when Cypress is gone. `npx` is a way of
+ * saying "find `cypress`", and what it does when it cannot find one is fetch
+ * some other copy from the registry — so the executable the harness checks has
+ * to be the tool, not the runner, or the only thing it ever verifies is the one
+ * program that is never missing.
+ *
+ * @type {readonly string[]}
+ */
+const DIRECT_RUNNERS = Object.freeze(["npx", "pnpx", "bunx"]);
+
+/**
+ * The same idea spelled as a subcommand: `pnpm dlx cypress`, `npm exec
+ * cypress`. The subcommand matters — `npm run e2e` names a *script*, not a
+ * program, and there is nothing there for the harness to resolve.
+ *
+ * @type {Readonly<Record<string, readonly string[]>>}
+ */
+const SUBCOMMAND_RUNNERS = Object.freeze({
+    npm: ["exec"],
+    pnpm: ["dlx", "exec"],
+    yarn: ["dlx"],
+    bun: ["x"],
+});
+
+/**
+ * Runner flags that name the package themselves instead of taking it from the
+ * first bare word. Meeting one means the harness cannot read this command, and
+ * a guess would put the wrong name in the diagnostic — which is worse than
+ * checking the runner alone.
+ *
+ * @type {readonly string[]}
+ */
+const OPAQUE_RUNNER_FLAGS = Object.freeze(["-p", "--package", "-c", "--call"]);
+
+/**
+ * A program's lookup name: its basename, minus a Windows executable extension,
+ * lower-cased. `C:\\…\\npx.cmd` and `npx` are the same question.
+ *
+ * @param {string} program - The program as the command line spells it.
+ * @returns {string} The name to compare against the runner tables.
+ */
+function executableName(program) {
+    return path
+        .basename(program)
+        .replace(/\.(cmd|exe|bat|ps1)$/i, "")
+        .toLowerCase();
+}
+
+/**
+ * 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) {
+    const [program, ...rest] = command;
+    if (!program) return [];
+    const name = executableName(program);
+
+    let args = rest;
+    const subcommands = SUBCOMMAND_RUNNERS[name];
+    if (subcommands) {
+        if (args.length === 0 || !subcommands.includes(args[0])) return [program];
+        args = args.slice(1);
+    } else if (!DIRECT_RUNNERS.includes(name)) return [program];
+
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--") return args[i + 1] ? [program, args[i + 1]] : [program];
+        if (OPAQUE_RUNNER_FLAGS.includes(arg)) return [program];
+        if (arg.startsWith("--package=") || arg.startsWith("--call=")) return [program];
+        if (arg.startsWith("-")) continue;
+        return [program, arg];
+    }
+    return [program];
+}
+
+/**
+ * @param {string} candidate - An absolute path.
+ * @returns {boolean} Whether it is there and is a file.
+ */
+function isExecutableFile(candidate) {
+    return statSync(candidate, { throwIfNoEntry: false })?.isFile() ?? false;
+}
+
+/**
+ * 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, { cwd, env = process.env } = {}) {
+    if (name.includes("/") || name.includes(path.sep)) {
+        const candidate = path.resolve(cwd ?? process.cwd(), name);
+        return isExecutableFile(candidate) ? candidate : null;
+    }
+    const directories = cwd ? [path.join(cwd, "node_modules", ".bin")] : [];
+    directories.push(...(env.PATH ?? "").split(path.delimiter).filter(Boolean));
+    const extensions =
+        process.platform === "win32" ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+    for (const directory of directories) {
+        for (const extension of extensions) {
+            const candidate = path.join(directory, `${name}${extension}`);
+            if (isExecutableFile(candidate)) return candidate;
+        }
+    }
+    return 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 = process.env }) {
+    return suiteExecutables(command).filter((name) => findExecutable(name, { cwd, env }) === null);
+}
+
+/**
+ * Names, quoted, for a diagnostic.
+ *
+ * @param {readonly string[]} names - What to list.
+ * @returns {string} A comma-separated list, back-quoted.
+ */
+function quotedList(names) {
+    return names.map((name) => `\`${name}\``).join(", ");
+}
+
+/**
+ * Filesystem timestamps are not all millisecond-precise, and a suite can write
+ * its first result in the same tick the harness spawned it. A second of slack
+ * costs nothing: a *stale* result is one from a previous run, minutes or days
+ * old, not one written a moment early.
+ */
+const RESULT_MTIME_SLACK_MS = 1000;
+
+/**
+ * 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 }) {
+    const floor = since - RESULT_MTIME_SLACK_MS;
+
+    /**
+     * @param {string} candidate - An absolute path.
+     * @returns {boolean} Whether it, or anything under it, is newer than the floor.
+     */
+    const touched = (candidate) => {
+        const stats = statSync(candidate, { throwIfNoEntry: false });
+        if (!stats) return false;
+        if (stats.isFile()) return stats.mtimeMs >= floor;
+        if (!stats.isDirectory()) return false;
+        return readdirSync(candidate, { withFileTypes: true }).some((entry) =>
+            touched(path.join(candidate, entry.name)),
+        );
+    };
+
+    return paths.filter((declared) => touched(path.resolve(cwd ?? process.cwd(), declared)));
+}
+
+/**
+ * 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 = [] }) {
+    if (vanished.length > 0) {
+        return {
+            status: status || 1,
+            message:
+                `✗ ${quotedList(vanished)} disappeared while the suite was ` +
+                `running, so it cannot have finished. Something reinstalled ` +
+                `\`node_modules\` underneath it — \`npm ci\` removes the tree ` +
+                `before it rebuilds it. Reporting the run as failed: whatever ` +
+                `status it exited with, it ran nothing to completion.`,
+        };
+    }
+    if (declared.length > 0 && fresh.length === 0) {
+        return {
+            status: status || 1,
+            message:
+                `✗ The suite exited ${status} but wrote nothing to ` +
+                `${quotedList(declared)} while it ran, so there is no evidence ` +
+                `it executed anything. Reporting the run as failed: a run that ` +
+                `produced no results is not a pass.`,
+        };
+    }
+    return { status, message: null };
+}
+
 /**
  * Run the repository's suite.
  *
@@ -565,19 +813,51 @@ function captureContainerLog(container) {
  * 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 = process.env, log = () => {} }) {
+export function runSuite({
+    command,
+    args = [],
+    cwd,
+    results = [],
+    env = process.env,
+    log = () => {},
+}) {
+    const missing = missingExecutables({ command, cwd, env });
+    if (missing.length > 0) {
+        throw new Error(
+            `The end-to-end suite cannot start: ${quotedList(missing)} ` +
+                `${missing.length === 1 ? "is" : "are"} not installed — ` +
+                `nothing of that name is in \`node_modules/.bin\` or on ` +
+                `\`PATH\`. The declared command is \`${command.join(" ")}\`. ` +
+                `Install the repository's dependencies and run again.`,
+        );
+    }
+
     const [program, ...rest] = command;
     const childEnv = { ...env };
     delete childEnv.ELECTRON_RUN_AS_NODE;
     log(`▸ ${[...command, ...args].join(" ")}`);
+    const startedAt = Date.now();
     const result = spawnSync(/** @type {string} */ (program), [...rest, ...args], {
         stdio: "inherit",
         cwd,
@@ -585,7 +865,15 @@ export function runSuite({ command, args = [], cwd, env = process.env, log = ()
         shell: process.platform === "win32",
     });
     if (result.error) throw result.error;
-    return result.status ?? 1;
+
+    const verdict = suiteVerdict({
+        status: result.status ?? 1,
+        vanished: missingExecutables({ command, cwd, env }),
+        declared: results,
+        fresh: freshResults({ paths: results, since: startedAt, cwd }),
+    });
+    if (verdict.message) log(verdict.message);
+    return verdict.status;
 }
 
 /**
@@ -696,6 +984,11 @@ export async function e2eRun({
             command,
             args: suiteArgs,
             cwd: config.rootDir,
+            // Only a headless run makes a claim worth checking. `open` hands
+            // the runner to a person, who decides what to execute and when to
+            // close it; "it wrote no results" is a description of that session,
+            // not a fault in it.
+            results: mode === "run" ? config.e2eResults : [],
             env: runEnv,
             log,
         });
@@ -781,6 +1074,7 @@ export async function e2eFast({ config, argv = [], env = process.env, log = () =
         command,
         args: suiteArgs,
         cwd: config.rootDir,
+        results: config.e2eResults,
         env,
         log,
     });