@heroiclands/package-build 20.0.0 → 20.2.1

package/engine/pack-config.mjs

@@ -47,14 +47,38 @@
  * actually needed: every accessor in the engine funnels through here, so
  * anything that reads configuration throws with the message below.
  *
- * **Located by walking up from this module, not from the working directory.**
- * The config file sits at the root of the repository that installed the
- * toolchain, so climbing out of
- * `node_modules/@heroiclands/package-build/engine/` lands on it either way.
- * Resolving it against `process.cwd()` instead would make the build read a
- * different tree depending on where it was launched from, which is the very
- * property #1508 removed. `PACKAGE_BUILD_CONFIG` names the file explicitly when
- * a consumer keeps it somewhere else.
+ * **Located by walking up from the working directory, and from this module only
+ * when that finds nothing.** The config file sits at the root of the repository
+ * being built, and a build is run inside that repository — so the walk from
+ * `process.cwd()` finds it from the root, from `packages/`, from anywhere
+ * below. Climbing from this module instead finds the same file too, right up
+ * until the installed package is not the one the caller is standing in: a git
+ * worktree nested under its parent checkout with no `node_modules` of its own
+ * resolves `@heroiclands/package-build` out of the *parent's*, because Node's
+ * resolution walks parent directories. `import.meta.dirname` is then inside the
+ * parent, the walk lands on the parent's configuration, and the build compiles
+ * the parent's content tree into the parent's `build/` and exits 0 — saying so
+ * only in paths that are easy to read past (#364).
+ *
+ * That failure is undetectable on exactly the work most likely to provoke it.
+ * The usual tell is a zero diff where a change was expected; an
+ * output-preserving sweep *expects* zero differences, so the tell is gone and a
+ * wrong-tree build produces confident evidence for a tree nobody touched. Order
+ * of resolution is the fix, because reviewer vigilance cannot be.
+ *
+ * The module walk stays, as the fallback for an invocation from outside any
+ * repository, and is never *preferred*: a configuration found above the
+ * installed package rather than above the working directory is not the one a
+ * caller meant. When both walks find one and they disagree, the ignored one is
+ * named in a warning rather than passed over — that disagreement is also the
+ * only cheap signal that this tree is building on another checkout's
+ * `node_modules`. `PACKAGE_BUILD_CONFIG` names the file explicitly and skips
+ * both walks, which is why it was the workaround.
+ *
+ * What #1508 removed stays removed. The property it bought was not "resolve
+ * from the module"; it was that a build reads one tree however it was launched,
+ * and an upward walk from the working directory keeps that — every directory
+ * inside a repository resolves that repository's single configuration.
  *
  * **Loaded synchronously.** A YAML config is parsed synchronously as a matter
  * of course; an `.mjs` one is loaded with `require` rather than `await import`,
@@ -81,7 +105,12 @@ import { createRequire } from "node:module";
 import YAML from "yaml";
 
 import { defineConfig, DERIVED_SYSTEM_VERSION } from "../content-config.mjs";
-import { formatDiagnostic, positionOfYamlPath, yamlKeyPath } from "./diagnostics.mjs";
+import {
+    emitDiagnostic,
+    formatDiagnostic,
+    positionOfYamlPath,
+    yamlKeyPath,
+} from "./diagnostics.mjs";
 
 /** The stem every consuming repository declares its build under. */
 export const CONFIG_BASENAME = "package-build.config";
@@ -144,6 +173,41 @@ export function findConfigFile(from) {
     }
 }
 
+/**
+ * Which configuration file a build launched here should read, and what each
+ * walk found.
+ *
+ * Kept separate from {@link loadPackConfig} because the *choice* is worth being
+ * able to ask about without loading anything: the two walks disagreeing is the
+ * observable form of #364, and a caller that wants to report it — or a test
+ * that wants to describe it — should not have to reproduce the resolution and
+ * risk disagreeing with the loader about it. It performs I/O, and is named for
+ * it, like the {@link findConfigFile} it calls twice.
+ *
+ * `PACKAGE_BUILD_CONFIG` is deliberately not consulted here. An explicit name
+ * is not a search result: {@link loadPackConfig} short-circuits on it before it
+ * ever asks, so there is no walk to report and nothing to disagree with.
+ *
+ * @param {object} [from] - Where to walk up from; both default to the real
+ *   thing, and are parameters only so a caller can describe a tree it is not
+ *   standing in.
+ * @param {string} [from.cwd] - The directory the build was launched in.
+ * @param {string} [from.moduleDir] - The directory this module sits in.
+ * @returns {{path: string|undefined, fromCwd: string|undefined, fromModule: string|undefined}}
+ *   The file to read, and each walk's own answer — the same file in an ordinary
+ *   build, different ones in a worktree resolving the toolchain out of its
+ *   parent checkout.
+ * @throws {Error} As {@link findConfigFile}, when one directory holds more than
+ *   one configuration.
+ */
+export function resolveConfigFile({ cwd = process.cwd(), moduleDir = import.meta.dirname } = {}) {
+    const fromCwd = findConfigFile(cwd);
+    const fromModule = findConfigFile(moduleDir);
+    // `??`, not `||`: the module walk is a fallback for finding *nothing*, never
+    // a tie-break between two answers.
+    return { path: fromCwd ?? fromModule, fromCwd, fromModule };
+}
+
 const require = createRequire(import.meta.url);
 
 /**
@@ -607,20 +671,46 @@ export function loadPackConfig() {
     if (loaded) return loaded;
 
     const explicit = process.env.PACKAGE_BUILD_CONFIG;
-    const configPath = explicit ? path.resolve(explicit) : findConfigFile(import.meta.dirname);
+    const found = explicit ? undefined : resolveConfigFile();
+    const configPath = explicit ? path.resolve(explicit) : found.path;
 
     if (!configPath || !fs.existsSync(configPath)) {
         throw new Error(
             explicit ?
                 `package-build: PACKAGE_BUILD_CONFIG names ${configPath}, ` +
                     `which does not exist.`
+                // Both origins, because either walk could have found one and
+                // naming only the module's would send a reader looking inside
+                // `node_modules/` for a file that belongs in their own root.
             :   `package-build: no ${CONFIG_FILENAMES.join(" or ")} found at ` +
-                    `or above ${import.meta.dirname}. A consuming repository ` +
-                    `declares its build in one file at its root; set ` +
+                    `or above ${process.cwd()}, nor at or above ` +
+                    `${import.meta.dirname}. A consuming repository declares ` +
+                    `its build in one file at its root; set ` +
                     `PACKAGE_BUILD_CONFIG to name it elsewhere.`,
         );
     }
 
+    // Two different files, one of which is about to be ignored. Said out loud
+    // because the alternative is what #364 was: a build that reads the parent
+    // checkout's configuration, compiles the parent's tree, and reports it only
+    // in absolute paths nobody rereads. A warning rather than an error — the
+    // shape is legitimate, and the working directory's answer is the right one
+    // — but never silence.
+    if (found?.fromCwd && found.fromModule && found.fromCwd !== found.fromModule) {
+        emitDiagnostic({
+            severity: "warning",
+            message:
+                `package-build: reading ${found.fromCwd}, the configuration ` +
+                `above this working directory. The installed ` +
+                `@heroiclands/package-build sits under a different ` +
+                `repository, whose own ${found.fromModule} is being ignored — ` +
+                `usually because this tree has no \`node_modules\` of its own ` +
+                `and resolved the toolchain out of a parent checkout. Run ` +
+                `\`npm ci\` here, or set PACKAGE_BUILD_CONFIG, to say which ` +
+                `tree is meant.`,
+        });
+    }
+
     loaded =
         configPath.endsWith(".mjs") ?
             loadCodeConfig(configPath)

package/engine/prose-config.mjs

@@ -134,6 +134,48 @@ export function sharedPrettierOptionsFor(file) {
     return /\.md$/i.test(file) ? { ...PRETTIER_BASE, ...PRETTIER_MARKDOWN } : { ...PRETTIER_BASE };
 }
 
+/**
+ * Where a resolved Prettier configuration disagrees with the shared one.
+ *
+ * The runner resolves each file's options as *either* the consumer's own config
+ * or {@link sharedPrettierOptionsFor}, never a merge. That is what bare Prettier
+ * does and it is the contract — but it means the conventions this package exists
+ * to publish hold by convention alone, and they lapse in two opposite directions
+ * (#133). A consumer that declares any config of its own gets whatever that
+ * config says: spread {@link PRETTIER_BASE} without the markdown override and
+ * every note reindents at 4, the reindentation the override was added to prevent
+ * (#76); write a partial `.prettierrc` such as `{"tabWidth": 2}` and
+ * `printWidth`, `trailingComma`, `experimentalTernaries` and the rest fall back
+ * to Prettier's own defaults. A consumer that declares *nothing* formats one way
+ * under this command and another under a bare `npx prettier`.
+ *
+ * This is the comparison that makes either absence visible. It is a **report,
+ * not a merge**: what a consumer declared still wins, and a deliberate local
+ * choice stays possible — it stops being silent, and nothing here fails a build
+ * over it.
+ *
+ * Every shared value is a primitive, so `!==` is the whole comparison. An option
+ * holding an object would need a deeper one, and the shared set has none —
+ * `overrides` is not compared, because `resolveConfig` has already applied and
+ * removed it by the time a configuration reaches this.
+ *
+ * @param {object|null|undefined} resolved - What `prettier.resolveConfig`
+ *   returned for `file`, with the consumer's own `overrides` already applied.
+ *   `null` — no configuration at all — reports every shared key as absent.
+ * @param {string} file - Path the options were resolved for. Decides whether
+ *   {@link PRETTIER_MARKDOWN} is part of what is expected.
+ * @returns {Array<{key: string, shared: unknown, local: unknown}>} One entry per
+ *   shared key the resolved configuration does not carry the value of, in the
+ *   order {@link PRETTIER_BASE} declares them. `local` is `undefined` where the
+ *   key is absent entirely, which is not the same finding as a key set to
+ *   something else and is reported differently.
+ */
+export function sharedPrettierDivergence(resolved, file) {
+    return Object.entries(sharedPrettierOptionsFor(file))
+        .filter(([key, shared]) => resolved?.[key] !== shared)
+        .map(([key, shared]) => ({ key, shared, local: resolved?.[key] }));
+}
+
 /**
  * The markdownlint rules — the structural checks Prettier cannot make.
  *

package/engine/prose-lint.mjs

@@ -38,6 +38,7 @@ import {
     MARKDOWNLINT_CONFIG,
     MARKDOWN_GLOBS,
     MARKDOWN_IGNORES,
+    sharedPrettierDivergence,
     sharedPrettierOptionsFor,
 } from "./prose-config.mjs";
 
@@ -78,6 +79,27 @@ const IGNORE_FILES = Object.freeze([".gitignore", ".prettierignore"]);
  */
 const MAX_FORMAT_PASSES = 3;
 
+/**
+ * The two paths whose resolved configuration stands for the repository's.
+ *
+ * Prettier resolves a configuration *per file*, so asking what a repository is
+ * configured to do means asking about a file. These are the two answers that
+ * differ: markdown carries the shared `tabWidth` override and everything else
+ * does not, so a single probe would check half the conventions and miss the one
+ * most worth checking (#133).
+ *
+ * Ordinary names at the repository root, and neither has to exist —
+ * `resolveConfig` reads the path to walk up from it and to match `overrides`
+ * against it, never the file. That is also the limit of what this can say: it
+ * reports the configuration a file *at the root* resolves to, so an override a
+ * consumer scoped to some subtree of its own is outside the question being
+ * asked, and rightly so.
+ */
+const CONVENTION_PROBES = Object.freeze({ code: "index.mjs", markdown: "README.md" });
+
+/** The one line a consumer writes to adopt the shared configuration verbatim. */
+const SHARED_CONFIG_RE_EXPORT = 'export { default } from "@heroiclands/package-build/prettier";';
+
 /**
  * Every file under a root, minus the directories nothing should walk.
  *
@@ -245,6 +267,110 @@ export async function checkFormatting(root, opts = {}) {
     return { findings, checked, written };
 }
 
+/**
+ * One divergence as the sentence a diagnostic carries.
+ *
+ * The two cases read differently on purpose. A key set to something else is a
+ * choice someone made and can defend; a key that is simply absent is the
+ * silent half of #133 — the consumer did not choose Prettier's default, it
+ * arrived because declaring one option discards every option not restated.
+ *
+ * @param {{key: string, shared: unknown, local: unknown}} divergence - From
+ *   {@link sharedPrettierDivergence}.
+ * @param {string} [scope=""] - Which files this is about, when it is not all of
+ *   them. Prefixed to the key, so the line reads `markdown \`tabWidth\` …`.
+ * @returns {string} The message.
+ */
+function divergenceMessage({ key, shared, local }, scope = "") {
+    const here =
+        local === undefined ?
+            "is not set here, so Prettier's own default applies"
+        :   `is ${JSON.stringify(local)} here`;
+    return `${scope}\`${key}\` ${here}; the shared configuration says ${JSON.stringify(shared)}`;
+}
+
+/**
+ * Report where a repository's own Prettier configuration parts from the shared
+ * one — or that it has none at all (#133).
+ *
+ * **Warnings, every one of them.** A consumer's config wins by design and this
+ * does not change that; it only refuses to let the divergence be silent, which
+ * is the whole of what the issue asks for. Turning any of this into an error
+ * would make the shared conventions mandatory, and they are a default.
+ *
+ * The no-configuration case is the sharper one and is reported even though the
+ * command itself behaves correctly there: with no config file the shared
+ * conventions reach `content-build format` and reach *nothing else*, so an
+ * editor's format-on-save and a bare `npx prettier --check .` apply Prettier's
+ * own defaults to the same tree, and the two take turns rewriting the same
+ * lines. That is not hypothetical — it is what the config files in
+ * `sohl-thalorna` and `sohl-kethira-basic` were added to stop.
+ *
+ * @param {string} root - Repository to ask about.
+ * @param {object} [opts]
+ * @param {object} [opts.prettier] - The Prettier module, for tests.
+ * @returns {Promise<{findings: Array<{file?: string, severity: string,
+ *   message: string}>, configFile: string|null}>} The findings and the config
+ *   file they are about, which is `null` when the repository declares none. A
+ *   finding about a missing file carries no `file`: #17's rule is to drop a
+ *   field rather than invent one.
+ */
+export async function checkPrettierConventions(root, opts = {}) {
+    const prettier = opts.prettier ?? (await import("prettier"));
+    const base = path.resolve(root);
+    const probe = (name) => path.join(base, name);
+
+    const configFile = await prettier.resolveConfigFile(probe(CONVENTION_PROBES.code));
+    if (!configFile) {
+        return {
+            findings: [
+                {
+                    severity: "warning",
+                    message:
+                        "this repository declares no Prettier configuration, so `content-build " +
+                        "format` applies the shared conventions while an editor and a bare `npx " +
+                        "prettier` apply Prettier's own to the same tree; declare them in a " +
+                        `prettier.config.mjs — ${SHARED_CONFIG_RE_EXPORT}`,
+                },
+            ],
+            configFile: null,
+        };
+    }
+
+    /** @param {string} name - One of {@link CONVENTION_PROBES}. */
+    const divergenceFor = async (name) =>
+        sharedPrettierDivergence(
+            await prettier.resolveConfig(probe(name), { editorconfig: false }),
+            probe(name),
+        );
+
+    const code = await divergenceFor(CONVENTION_PROBES.code);
+    const markdown = await divergenceFor(CONVENTION_PROBES.markdown);
+
+    const findings = code.map((divergence) => ({
+        file: configFile,
+        severity: "warning",
+        message: divergenceMessage(divergence),
+    }));
+    for (const divergence of markdown) {
+        // A key that resolves the same way everywhere is one finding, not two.
+        // Only what markdown alone gets wrong is worth a line of its own — and
+        // it is the line that matters most, `tabWidth` being the value a note
+        // moving between repositories reindents on.
+        const everywhere = code.some(
+            (other) => other.key === divergence.key && Object.is(other.local, divergence.local),
+        );
+        if (everywhere) continue;
+        findings.push({
+            file: configFile,
+            severity: "warning",
+            message: divergenceMessage(divergence, "markdown "),
+        });
+    }
+
+    return { findings, configFile };
+}
+
 /**
  * One markdownlint result as a diagnostic.
  *

package/engine/schema-extract.mjs

@@ -1,3 +1,16 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
 /**
  * Read a package's DataModel field sets out of its source, as data.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "20.0.0",
+    "version": "20.2.1",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

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