@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/commands/test-furnace-reach.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge test --build --furnace-apply reached`: deploy only the Furnace
+ * components a requested test reaches.
+ *
+ * The pre-test build's Furnace apply runs over the whole `components/`
+ * tree, so on a shared engine a peer's `test --build` deployed every
+ * session's undeployed component edits into the shared objdir, including
+ * edits another session was holding back for a before-capture. `reached`
+ * keeps the apply to the components the run can observe and names the rest.
+ *
+ * "Reaches" is textual, and errs towards applying: a component is reached
+ * when a requested test file, a `head*.js` beside it, or any test file
+ * under a requested directory names the component's tag, or when the test
+ * path itself names it. A component no test names cannot change what the
+ * run observes through its own code, so leaving its undeployed edit out
+ * keeps the run honest about what it packaged.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { listStaleFurnaceComponents } from '../core/furnace-staleness.js';
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+/** Files read per run, so a huge directory request cannot stall the build. */
+const MAX_SCANNED_FILES = 4000;
+const SCANNED_EXTENSIONS = /\.(?:m?js|html|xhtml|toml|ini)$/;
+/**
+ * Resolves the mode from the flag and `test.furnaceApply`. `false`
+ * (`--no-furnace-apply`) is `none`.
+ */
+export function resolveFurnaceApplyMode(options, config) {
+    if (options.furnaceApply === false)
+        return 'none';
+    if (typeof options.furnaceApply === 'string')
+        return options.furnaceApply;
+    return config.test?.furnaceApply ?? 'all';
+}
+async function collectFiles(path, out) {
+    if (out.length >= MAX_SCANNED_FILES)
+        return;
+    let info;
+    try {
+        info = await stat(path);
+    }
+    catch {
+        return;
+    }
+    if (info.isFile()) {
+        if (SCANNED_EXTENSIONS.test(path))
+            out.push(path);
+        return;
+    }
+    if (!info.isDirectory())
+        return;
+    let entries;
+    try {
+        entries = await readdir(path);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries.sort()) {
+        if (out.length >= MAX_SCANNED_FILES)
+            return;
+        await collectFiles(join(path, entry), out);
+    }
+}
+/** The files whose text decides reach: the request plus `head*.js` beside each file. */
+async function reachFiles(engineDir, testPaths) {
+    const files = [];
+    for (const path of testPaths) {
+        const absolute = join(engineDir, path);
+        await collectFiles(absolute, files);
+        try {
+            if ((await stat(absolute)).isFile()) {
+                const dir = dirname(absolute);
+                for (const entry of await readdir(dir)) {
+                    if (/^head.*\.js$/.test(entry))
+                        files.push(join(dir, entry));
+                }
+            }
+        }
+        catch {
+            // A missing path is refused later by the path-existence check.
+        }
+    }
+    return [...new Set(files)];
+}
+/**
+ * The stale components a request reaches, and the stale ones it does not.
+ *
+ * @param projectRoot - Project root
+ * @param engineDir - Absolute engine directory
+ * @param testPaths - Engine-relative requested paths
+ */
+export async function partitionReachedComponents(projectRoot, engineDir, testPaths) {
+    let stale;
+    try {
+        stale = await listStaleFurnaceComponents(projectRoot);
+    }
+    catch (error) {
+        verbose(`Furnace pending-edit probe failed: ${toError(error).message}`);
+        return { reached: [], skipped: [] };
+    }
+    if (stale.length === 0)
+        return { reached: [], skipped: [] };
+    const names = new Set();
+    for (const path of testPaths) {
+        for (const name of stale)
+            if (path.includes(name))
+                names.add(name);
+    }
+    for (const file of await reachFiles(engineDir, testPaths)) {
+        if (names.size === stale.length)
+            break;
+        let text;
+        try {
+            text = await readFile(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const name of stale) {
+            if (text.includes(name) || basename(file).includes(name))
+                names.add(name);
+        }
+    }
+    return {
+        reached: stale.filter((name) => names.has(name)),
+        skipped: stale.filter((name) => !names.has(name)),
+    };
+}

package/dist/src/commands/test-orchestrate.d.ts

@@ -25,6 +25,20 @@ export interface TestRunHooks {
     coveragePaths?: string[];
     /** Runs after every preflight gate and the pre-test build, right before dispatch. */
     beforeDispatch?: () => Promise<void>;
+    /**
+     * Runs right before the pre-test build: a negative control on compiled
+     * source, which only reaches the binary when the build compiles it.
+     */
+    beforeBuild?: () => Promise<void>;
+    /**
+     * Why the pre-test build must be a full `mach build`: `mach build faster`
+     * compiles nothing, so a compiled control's binary needs the full one.
+     */
+    fullBuildReason?: string;
+    /** `--repeat` run this sub-run is (1-based), for `--results`. */
+    repetition?: number;
+    /** Where dispatches write their mozlog raw logs (`--results`, `--shard-size`). */
+    rawLogDir?: string;
 }
 /** The single-run body (`runTestCommandBody`), injected to avoid an import cycle. */
 export type TestRunBody = (paths: string[], options: TestOptions, hooks: TestRunHooks) => Promise<void>;

package/dist/src/commands/test-orchestrate.js

@@ -17,15 +17,16 @@
  */
 import { getProjectPaths } from '../core/config.js';
 import { applyNegativeControl, planNegativeControl, recoverPendingNegativeControl, restoreNegativeControl, } from '../core/negative-control.js';
+import { formatCompiledControlBuildNotice, formatCompiledControlRefusal, } from '../core/negative-control-compiled.js';
 import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { GeneralError, InvalidArgumentError, PreflightRefusalError } from '../errors/base.js';
 import { TestFailureError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, success } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { classifyTestHarnesses } from './test-modes.js';
 import { deriveControlOutcome, describeControlOutcome, formatAggregateBody, formatRunLine, parseCapturedVerdict, worstRun, } from './test-multi-verdict.js';
-import { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, verdictEmitted, } from './test-verdict.js';
+import { emitAggregateVerdict, emitFailVerdict, setVerdictCapture, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
 function assertMultiRunUsage(testPaths, options) {
     const flag = options.negativeControl !== undefined ? '--negative-control' : '--repeat';
     if (testPaths.length === 0) {
@@ -84,7 +85,10 @@ async function planRuns(engineDir, testPaths, options) {
                 ...(group.harness === undefined ? {} : { harness: group.harness }),
                 paths: group.paths,
                 options: first ? options : laterRunOptions(options),
-                hooks: first && union !== undefined ? { coveragePaths: union } : {},
+                hooks: {
+                    repetition,
+                    ...(first && union !== undefined ? { coveragePaths: union } : {}),
+                },
             });
         }
     }
@@ -158,6 +162,16 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
         : await planNegativeControl(projectRoot, projectPaths.engine, options.negativeControl, {
             deferApplyCheck: options.build === true,
         });
+    // A compiled target only reaches the binary through a build, so its
+    // control goes in before the first run's pre-test build.
+    const compiled = plan?.compiled;
+    const compiledControl = compiled !== undefined;
+    if (compiledControl) {
+        if (options.build !== true) {
+            throw new PreflightRefusalError(formatCompiledControlRefusal(compiled), 'negative-control');
+        }
+        setVerdictRunAttribute('control-build', 'compiled');
+    }
     const results = [];
     let restoreError;
     for (const [index, run] of runs.entries()) {
@@ -170,7 +184,14 @@ export async function orchestrateTestRuns(projectRoot, testPaths, options, body,
         try {
             await body(run.paths, run.options, {
                 ...run.hooks,
-                ...(plan === undefined ? {} : { beforeDispatch: controlHook(controlPaths, plan, slot) }),
+                ...(plan === undefined
+                    ? {}
+                    : compiledControl && index === 0
+                        ? {
+                            beforeBuild: controlHook(controlPaths, plan, slot),
+                            fullBuildReason: formatCompiledControlBuildNotice(compiled),
+                        }
+                        : { beforeDispatch: controlHook(controlPaths, plan, slot) }),
             });
         }
         catch (caught) {

package/dist/src/commands/test-perf-scope.d.ts

@@ -27,3 +27,24 @@ export declare function describePerfStaleImpact(engineDir: string, stalePaths: r
  * @param engineDir - Absolute engine directory
  */
 export declare function perfGenerationTolerance(engineDir: string): (before: string, after: string) => Promise<boolean>;
+/**
+ * Tolerance for `assertEngineGenerationUnchanged` on an ordinary run: true
+ * (with a warning, and `drift-tolerated=<n>` on the verdict) when HEAD did
+ * not move and every changed path is one the running browser cannot see.
+ *
+ * A peer deleting an unrelated chrome script used to make a whole run
+ * inconclusive. What a running browser can see mid-run is narrower than
+ * "anything under engine/": a file the objdir links to its source (`live`),
+ * one the harness stages at dispatch (`at-dispatch`), and the run's own
+ * test files and the staging inputs their manifests name. A compiled
+ * source, or a file the build copied into the package, is already fixed in
+ * the running binary or package; the next run's stale-build gate judges it.
+ *
+ * Perf runs keep {@link perfGenerationTolerance}: a sample is also void
+ * when a packaged path changes.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param requested - Normalized request paths of the run
+ * @param onTolerated - Receives the tolerated path count
+ */
+export declare function runGenerationTolerance(engineDir: string, requested: readonly string[], onTolerated: (count: number) => void): (before: string, after: string) => Promise<boolean>;

package/dist/src/commands/test-perf-scope.js

@@ -81,3 +81,58 @@ export function perfGenerationTolerance(engineDir) {
         return true;
     };
 }
+/**
+ * Tolerance for `assertEngineGenerationUnchanged` on an ordinary run: true
+ * (with a warning, and `drift-tolerated=<n>` on the verdict) when HEAD did
+ * not move and every changed path is one the running browser cannot see.
+ *
+ * A peer deleting an unrelated chrome script used to make a whole run
+ * inconclusive. What a running browser can see mid-run is narrower than
+ * "anything under engine/": a file the objdir links to its source (`live`),
+ * one the harness stages at dispatch (`at-dispatch`), and the run's own
+ * test files and the staging inputs their manifests name. A compiled
+ * source, or a file the build copied into the package, is already fixed in
+ * the running binary or package; the next run's stale-build gate judges it.
+ *
+ * Perf runs keep {@link perfGenerationTolerance}: a sample is also void
+ * when a packaged path changes.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param requested - Normalized request paths of the run
+ * @param onTolerated - Receives the tolerated path count
+ */
+export function runGenerationTolerance(engineDir, requested, onTolerated) {
+    return async (before, after) => {
+        const delta = generationDeltaPaths(before, after);
+        if (delta.headMoved || delta.paths.length === 0)
+            return false;
+        const index = await loadEngineInstallIndex(engineDir);
+        if (index === undefined)
+            return false;
+        const inputs = [...requested];
+        for (const path of requested)
+            inputs.push(...(await collectStagingInputs(engineDir, path)));
+        for (const path of delta.paths) {
+            const bare = path.endsWith('/') ? path.slice(0, -1) : path;
+            if (inputs.some((input) => isUnderPath(bare, input) || isUnderPath(input, bare))) {
+                return false;
+            }
+            // A path-less run requests every test, so any test file is its own.
+            if (requested.length === 0 && isTestPath(path))
+                return false;
+            if (path.endsWith('/')) {
+                if (installsFromDirectory(index, path))
+                    return false;
+                continue;
+            }
+            const delivery = await classifyRuntimeDelivery(index, engineDir, path);
+            if (delivery === 'live' || delivery === 'at-dispatch')
+                return false;
+        }
+        warn(`engine/ changed while this run was in flight, but only in files the running browser ` +
+            `cannot see (${capList(delta.paths)}); the verdict stands. The next run's stale-build ` +
+            'gate judges whether they need a rebuild.');
+        onTolerated(delta.paths.length);
+        return true;
+    };
+}

package/dist/src/commands/test-prelock.js

@@ -22,10 +22,13 @@ import { join } from 'node:path';
 import { describeBuildRunState, readBuildRunState } from '../core/build-run-record.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
+import { autoPortsRequested } from '../core/harness-port-fallback.js';
 import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, extractForwardedMarionettePort, } from '../core/marionette-port.js';
 import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { planNegativeControl } from '../core/negative-control.js';
+import { formatCompiledControlRefusal } from '../core/negative-control-compiled.js';
 import { waitBeforeLock } from '../core/preflight-wait.js';
 import { PreflightRefusalError } from '../errors/base.js';
 import { info } from '../utils/logger.js';
@@ -33,6 +36,7 @@ import { resolveWaitLockSeconds } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { checkRequestedTestTypes } from './test-checkjs.js';
 import { assertPathlessTestMode, classifyBeforeDispatch, resolveCanaryPath } from './test-modes.js';
+import { enforceStaleBuildGate } from './test-stale-gate.js';
 /**
  * Resolves the launchable binary a test run needs, or refuses naming why
  * it is missing. The cause comes from the build run record, which any
@@ -95,10 +99,11 @@ async function loadPreLockContext(projectRoot, testPaths, options) {
  * @param options - Parsed test options
  */
 export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
-    const context = await loadPreLockContext(projectRoot, testPaths, options);
-    if (context === undefined)
-        return options;
-    const { paths, config, objDir } = context;
+    const loaded = await loadPreLockContext(projectRoot, testPaths, options);
+    if (loaded === undefined)
+        return withLockMode(options, 'exclusive');
+    const { paths, config, objDir } = loaded;
+    options = withLockMode(options, resolveTestLockMode(options, config));
     let launchablePath;
     try {
         launchablePath = await resolveLaunchablePathForTests(projectRoot, paths.engine, config.binaryName, objDir);
@@ -115,11 +120,102 @@ export async function runTestPreLockPreflight(projectRoot, testPaths, options) {
     if (options.build === true || options.buildOnly === true) {
         await checkRequestedTestTypes(paths, config, normalizedPaths);
     }
+    else {
+        await refuseCompiledControlBeforeLock(projectRoot, paths.engine, options);
+        await refuseStalePackagingBeforeLock(projectRoot, paths.engine, options, normalizedPaths);
+    }
     return waitForResourcesBeforeLock(paths.engine, config, options, {
         launchablePath,
         normalizedPaths,
     });
 }
+/** `options` with `sharedLock` set to the resolved decision. */
+function withLockMode(options, mode) {
+    if (mode === 'exclusive' && options.sharedLock === undefined)
+        return options;
+    const rest = { ...options };
+    delete rest.sharedLock;
+    return mode === 'shared' ? { ...rest, sharedLock: true } : rest;
+}
+/**
+ * How this run holds the engine session lock. Shared only on request
+ * (`--shared-lock` or `test.lockMode: "shared"`), and only for a run that
+ * writes nothing into engine/ or the objdir and can move its ports: no
+ * build, no negative control, auto ports. Every other run stays exclusive,
+ * so a shared holder can never overlap a build or a re-export.
+ */
+function resolveTestLockMode(options, config) {
+    const requested = options.sharedLock === true || config.test?.lockMode === 'shared';
+    if (!requested)
+        return 'exclusive';
+    const writes = options.build === true ||
+        options.buildOnly === true ||
+        options.negativeControl !== undefined ||
+        options.canary !== undefined ||
+        options.doctor === true;
+    if (writes || !autoPortsRequested(options, config)) {
+        info('Shared test lock requested, but this run ' +
+            (writes
+                ? 'builds, applies a negative control, or runs a canary/doctor preflight'
+                : 'does not use auto ports (--auto-ports or test.mochitestPorts: "auto")') +
+            ', so it holds the engine lock exclusively.');
+        return 'exclusive';
+    }
+    return 'shared';
+}
+/**
+ * Refuses a build-less `--negative-control` on compiled source before the
+ * lock: applied after the build it is never compiled, so the run could only
+ * report `control=missed` against the unmutated binary.
+ */
+async function refuseCompiledControlBeforeLock(projectRoot, engineDir, options) {
+    if (options.negativeControl === undefined)
+        return;
+    let plan;
+    try {
+        plan = await planNegativeControl(projectRoot, engineDir, options.negativeControl);
+    }
+    catch {
+        // Any other refusal (including a control a killed run left applied,
+        // which only the in-lock recovery may undo) is the in-lock pass's.
+        return;
+    }
+    if (plan.compiled === undefined)
+        return;
+    throw new PreflightRefusalError(formatCompiledControlRefusal(plan.compiled), 'negative-control');
+}
+/**
+ * Runs the build-less run's packaging gates (coverage, stale content,
+ * StaticComponents) before the lock, so a refusal surfaces before the run
+ * queues instead of after it reached the head of the queue. The same gate
+ * runs again under the lock, where a peer's build may since have changed
+ * the answer; this pass only refuses early what would refuse anyway.
+ *
+ * Skipped while a build runs (it will rewrite the record this reads) and
+ * under `--allow-stale-build`/`--allow-stale-components`, whose warnings
+ * belong to the in-lock pass alone. A `--negative-control` refusal says to
+ * add `--build`: without it the control has nothing current to run on, and
+ * the invocation used to end `control=inconclusive` after a full queue.
+ */
+async function refuseStalePackagingBeforeLock(projectRoot, engineDir, options, normalizedPaths) {
+    if (options.allowStaleBuild === true || options.allowStaleComponents === true)
+        return;
+    if ((await readBuildRunState(projectRoot)).kind === 'running')
+        return;
+    try {
+        await enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, {
+            quiet: true,
+        });
+    }
+    catch (error) {
+        if (options.negativeControl === undefined || !(error instanceof PreflightRefusalError)) {
+            throw error;
+        }
+        throw new PreflightRefusalError(`${error.message}\n\nThis --negative-control run has no --build, so its control would ` +
+            'run on this packaging and end inconclusive. Add --build: the control is then planned ' +
+            'against a fresh build of the requested paths.', error.note);
+    }
+}
 /** `options` without one wait budget, which this pass already spent. */
 function withoutOption(options, key) {
     const rest = { ...options };

package/dist/src/commands/test-register.js

@@ -106,7 +106,21 @@ function registerTestSharingOptions(test) {
 function registerTestBuildOptions(test) {
     return test
         .option('--extend-coverage', 'With --build/--build-only and explicit paths, refuse instead of dropping any earlier packaging claim. Scoped builds keep each earlier path by default while its own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged; this flag turns a drop into a refusal before the build.')
-        .option('--no-furnace-apply', 'With --build/--build-only, skip the Furnace apply so the build packages engine/ as it stands; names the components whose undeployed components/ edits it leaves out');
+        .option('--furnace-apply <mode>', 'With --build/--build-only: all (default; deploy every component with undeployed edits), reached (only components a requested test names; the rest are reported as furnace-skipped=<names>), or none. Same as test.furnaceApply.', commanderArgParser((raw) => {
+        if (raw !== 'all' && raw !== 'reached' && raw !== 'none') {
+            throw new GeneralError(`--furnace-apply must be all, reached or none (got "${raw}")`);
+        }
+        return raw;
+    }))
+        .option('--no-furnace-apply', 'With --build/--build-only, skip the Furnace apply so the build packages engine/ as it stands; names the components whose undeployed components/ edits it leaves out (same as --furnace-apply none)');
+}
+/** Options that run a request on several harness instances, or judge it per file. */
+function registerTestParallelOptions(test) {
+    return test
+        .option('--jobs <n>', 'Run shards on n harness instances at once inside one lock hold, each with its own profile, Marionette port and (via auto ports) server ports. With --no-shard, or one directory argument, the files are split in order into n contiguous chunks. Prints a FIREFORGE-SHARD line per shard and one aggregate verdict. Requires --auto-ports or test.mochitestPorts: "auto".', commanderArgParser((raw) => parsePositiveIntegerFlag('--jobs', raw)))
+        .option('--shard-size <n>', 'Dispatch n files per mach invocation (mochitest restarts the browser between files) and judge each file from the structured log: shards= then counts files and failed-shards= names failed files. Combines with --jobs.', commanderArgParser((raw) => parsePositiveIntegerFlag('--shard-size', raw)))
+        .option('--results <path>', 'Write a JSON record per test file and --repeat run (status, expected, duration, run-log line) from the mozlog structured log, and name it on the verdict as results=<path>')
+        .option('--shared-lock', 'Hold the engine session lock shared when this run is build-less, applies no negative control and uses auto ports, so peers\' build-less runs on this objdir overlap; builds and re-exports still wait. Same as test.lockMode: "shared".');
 }
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
@@ -146,13 +160,14 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         return n;
     }))
         .addHelpText('after', TEST_HELP_TEXT);
-    addWaitLockOption(registerTestBuildOptions(registerTestMultiRunOptions(registerTestSharingOptions(test)))).action(withErrorHandling(async (paths, options) => {
+    addWaitLockOption(registerTestParallelOptions(registerTestBuildOptions(registerTestMultiRunOptions(registerTestSharingOptions(test))))).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
         // Fallback for a verdict testCommand did not emit (it takes the lock).
         resetVerdictEmission();
         try {
-            await testCommand(projectRoot, paths, pickDefined(options), (body) => withEngineSessionLock(projectRoot, 'test', body, {
+            await testCommand(projectRoot, paths, pickDefined(options), (body, mode) => withEngineSessionLock(projectRoot, 'test', body, {
                 waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+                ...(mode === 'shared' ? { mode } : {}),
             }));
         }
         catch (error) {

package/dist/src/commands/test-results.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `fireforge test --results <path>`: one record per test file and per
+ * `--repeat` run, from the mozlog raw log each dispatch writes.
+ *
+ * Gates and retry wrappers downstream named a run's failing files by
+ * reading `TEST_START`/`TEST_END` lines and the prose of the "sharded test
+ * run(s) did not pass" error out of the human log, which nothing promised
+ * to keep stable. The results file is the stable form: JSON with a
+ * `schemaVersion`, written once the invocation has finished, and named on
+ * the verdict line as `results=<path>`.
+ */
+import type { RawTestResult } from '../core/test-raw-log.js';
+/** One file's result in one dispatch. */
+export interface TestFileResult extends RawTestResult {
+    /** `--repeat` run (1-based); 1 for a single run. */
+    run: number;
+    /** The shard (path argument or `--shard-size` chunk) the file ran in. */
+    shard: string;
+    /** Line of the run log where this file's dispatch began (1-based). */
+    logLine: number;
+}
+/** The document `--results` writes. */
+export interface TestResultsDocument {
+    schemaVersion: 1;
+    /** Files in dispatch-completion order. */
+    files: TestFileResult[];
+    /** Started files that never ended, per dispatch. */
+    unfinished: Array<{
+        test: string;
+        run: number;
+        shard: string;
+    }>;
+}
+/** Clears the collector at the start of an invocation. */
+export declare function resetTestResults(): void;
+/**
+ * Adds one dispatch's parsed raw log to the invocation's results.
+ *
+ * @param results - The dispatch's finished files
+ * @param unfinished - Its started-but-unfinished files
+ * @param context - Run, shard and run-log line of the dispatch
+ */
+export declare function recordTestResults(results: readonly RawTestResult[], unfinished: readonly string[], context: {
+    run: number;
+    shard: string;
+    logLine: number;
+}): void;
+/** The results collected so far (for tests and the shard summary). */
+export declare function collectedTestResults(): TestResultsDocument;
+/**
+ * Writes the collected results.
+ *
+ * @param path - Destination of `--results`
+ */
+export declare function writeTestResults(path: string): Promise<void>;
+/**
+ * Creates the scratch directory the dispatches' raw logs go to, runs
+ * `body`, and removes it afterwards.
+ *
+ * @param body - Receives the directory
+ */
+export declare function withRawLogDir<T>(body: (dir: string) => Promise<T>): Promise<T>;

package/dist/src/commands/test-results.js

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge test --results <path>`: one record per test file and per
+ * `--repeat` run, from the mozlog raw log each dispatch writes.
+ *
+ * Gates and retry wrappers downstream named a run's failing files by
+ * reading `TEST_START`/`TEST_END` lines and the prose of the "sharded test
+ * run(s) did not pass" error out of the human log, which nothing promised
+ * to keep stable. The results file is the stable form: JSON with a
+ * `schemaVersion`, written once the invocation has finished, and named on
+ * the verdict line as `results=<path>`.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { writeJson } from '../utils/fs.js';
+let collected = { schemaVersion: 1, files: [], unfinished: [] };
+/** Clears the collector at the start of an invocation. */
+export function resetTestResults() {
+    collected = { schemaVersion: 1, files: [], unfinished: [] };
+}
+/**
+ * Adds one dispatch's parsed raw log to the invocation's results.
+ *
+ * @param results - The dispatch's finished files
+ * @param unfinished - Its started-but-unfinished files
+ * @param context - Run, shard and run-log line of the dispatch
+ */
+export function recordTestResults(results, unfinished, context) {
+    for (const result of results)
+        collected.files.push({ ...result, ...context });
+    for (const test of unfinished) {
+        collected.unfinished.push({ test, run: context.run, shard: context.shard });
+    }
+}
+/** The results collected so far (for tests and the shard summary). */
+export function collectedTestResults() {
+    return collected;
+}
+/**
+ * Writes the collected results.
+ *
+ * @param path - Destination of `--results`
+ */
+export async function writeTestResults(path) {
+    await writeJson(path, collectedTestResults());
+}
+/**
+ * Creates the scratch directory the dispatches' raw logs go to, runs
+ * `body`, and removes it afterwards.
+ *
+ * @param body - Receives the directory
+ */
+export async function withRawLogDir(body) {
+    const dir = await mkdtemp(join(tmpdir(), 'fireforge-raw-log-'));
+    try {
+        return await body(dir);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+}