@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/test-furnace-reach.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `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 type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/** The effective Furnace apply mode for a pre-test build. */
+export type FurnaceApplyMode = 'all' | 'reached' | 'none';
+/**
+ * Resolves the mode from the flag and `test.furnaceApply`. `false`
+ * (`--no-furnace-apply`) is `none`.
+ */
+export declare function resolveFurnaceApplyMode(options: TestOptions, config: FireForgeConfig): FurnaceApplyMode;
+/**
+ * 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 declare function partitionReachedComponents(projectRoot: string, engineDir: string, testPaths: readonly string[]): Promise<{
+    reached: string[];
+    skipped: string[];
+}>;

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-modes.d.ts

@@ -1,6 +1,6 @@
 import type { TestOptions } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
-import type { TestRunOutcome } from './test-run.js';
+import type { TestRunOutcome, TestSuite } from './test-run.js';
 /** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
 export declare function assertPathlessTestMode(testPaths: readonly string[], options: TestOptions): void;
 /** Rejects invalid combinations for mode-like `fireforge test` options. */
@@ -16,6 +16,8 @@ export interface HarnessClassification {
     xpcshell: string[];
     nonXpcshell: string[];
 }
+/** Buckets normalized request paths by the harness their nearest manifest selects. */
+export declare function classifyTestHarnesses(engineDir: string, normalizedPaths: readonly string[]): Promise<HarnessClassification>;
 /**
  * Harness classification is a pure path→manifest lookup and must precede
  * the build dispatch: a mixed xpcshell+mochitest request can never
@@ -40,3 +42,16 @@ export declare function classifyBeforeDispatch(engineDir: string, normalizedPath
  * run build-less without tripping the stale/coverage gate.
  */
 export declare function reportBuildOnlyCompletion(classification: HarnessClassification, normalizedPaths: readonly string[]): void;
+/**
+ * The mach args `--restart-between-tests` forwards: mochitest's own flag,
+ * which restarts the browser between test files (the run shape a
+ * `standalone` manifest key asks for). Mochitest-only, refused otherwise
+ * for the reason `--shuffle` is: xpcshell has no such flag and generic
+ * `mach test` would hand it to every suite. Not duplicated when
+ * `--mach-arg` already forwards it.
+ *
+ * @param options - Parsed test options
+ * @param suite - The resolved dispatch target
+ * @param forwardedMachArgs - `--mach-arg` values after filtering
+ */
+export declare function restartBetweenTestsArgs(options: TestOptions, suite: TestSuite, forwardedMachArgs: readonly string[]): string[];

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

@@ -72,7 +72,8 @@ function buildPathlessTestMessage() {
         '  - `fireforge test --doctor` to run the Marionette preflight only\n' +
         '  - `fireforge test --canary` to run the configured short harness canary');
 }
-async function classifyTestHarnesses(engineDir, normalizedPaths) {
+/** Buckets normalized request paths by the harness their nearest manifest selects. */
+export async function classifyTestHarnesses(engineDir, normalizedPaths) {
     const result = { xpcshell: [], nonXpcshell: [] };
     for (const testPath of normalizedPaths) {
         const manifest = await findNearestXpcshellManifest(engineDir, testPath);
@@ -133,3 +134,25 @@ export function reportBuildOnlyCompletion(classification, normalizedPaths) {
         info(`Run: fireforge test ${normalizedPaths.join(' ')}`);
     }
 }
+/**
+ * The mach args `--restart-between-tests` forwards: mochitest's own flag,
+ * which restarts the browser between test files (the run shape a
+ * `standalone` manifest key asks for). Mochitest-only, refused otherwise
+ * for the reason `--shuffle` is: xpcshell has no such flag and generic
+ * `mach test` would hand it to every suite. Not duplicated when
+ * `--mach-arg` already forwards it.
+ *
+ * @param options - Parsed test options
+ * @param suite - The resolved dispatch target
+ * @param forwardedMachArgs - `--mach-arg` values after filtering
+ */
+export function restartBetweenTestsArgs(options, suite, forwardedMachArgs) {
+    if (options.restartBetweenTests !== true)
+        return [];
+    if (suite !== 'mochitest') {
+        throw new GeneralError("--restart-between-tests forwards the mochitest harness's per-file browser restart; the " +
+            'xpcshell harness has none, and generic `mach test` dispatch would hand it to every ' +
+            'suite. Narrow the paths to browser-chrome/mochitest files (and drop --generic-mach-test).');
+    }
+    return forwardedMachArgs.includes('--restart-between-tests') ? [] : ['--restart-between-tests'];
+}

package/dist/src/commands/test-multi-verdict.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-run lines and the aggregate verdict of a multi-run `fireforge test`
+ * (`--repeat`, mixed harnesses, `--negative-control`). Pure: the
+ * orchestration in `test-orchestrate.ts` feeds it the verdict line each
+ * sub-run would have printed, captured instead of written.
+ */
+/** One finished sub-run. */
+export interface SubRunResult {
+    /** 1-based repetition this run belongs to. */
+    repetition: number;
+    /** The harness half of a mixed invocation. */
+    harness?: 'xpcshell' | 'mochitest';
+    /** The captured verdict, without the `FIREFORGE-VERDICT: ` prefix. */
+    body: string;
+    passed: boolean;
+    /** `reason=` of a failed run. */
+    reason?: string;
+    /** `note=` of a failed run, when it carried one. */
+    note?: string;
+    /** What the sub-run threw, if anything. */
+    error?: unknown;
+}
+/**
+ * How a negative control came out: `caught` when every repetition went red
+ * on test failures, `missed` when a repetition stayed green (the tests did
+ * not detect the mutation), `inconclusive` when any run failed for another
+ * reason or the invocation stopped early.
+ */
+export type ControlOutcome = 'caught' | 'missed' | 'inconclusive';
+/**
+ * Parses a captured verdict line into a sub-run result.
+ *
+ * @param line - The captured line, or undefined when the sub-run wrote none
+ */
+export declare function parseCapturedVerdict(line: string | undefined): Pick<SubRunResult, 'body' | 'passed' | 'reason' | 'note'>;
+/**
+ * The `FIREFORGE-RUN:` line for one sub-run: the verdict it would have
+ * printed alone, plus `run=<i>/<n>` and, for a mixed invocation,
+ * `harness=`. Never `FIREFORGE-VERDICT:`, so the invocation keeps exactly
+ * one verdict line.
+ */
+export declare function formatRunLine(result: SubRunResult, index: number, total: number): string;
+/** The failed run with the most structural reason, or undefined when all passed. */
+export declare function worstRun(results: readonly SubRunResult[]): SubRunResult | undefined;
+/**
+ * Derives a negative control's outcome.
+ *
+ * @param results - Every finished sub-run
+ * @param repetitions - How many repetitions were planned
+ * @param complete - False when the invocation stopped before its last run
+ */
+export declare function deriveControlOutcome(results: readonly SubRunResult[], repetitions: number, complete: boolean): ControlOutcome;
+/**
+ * The aggregate verdict body. A single planned run (a lone control) keeps
+ * its own line, counts included; several aggregate to `PASS runs=<n>/<n>`
+ * or `FAIL reason=<most structural> [note=] runs=<passed>/<planned>`.
+ * A control appends `control=<outcome>`.
+ */
+export declare function formatAggregateBody(results: readonly SubRunResult[], plannedTotal: number, control?: ControlOutcome): string;
+/** One-line human summary of a control's outcome. */
+export declare function describeControlOutcome(outcome: ControlOutcome): string;

package/dist/src/commands/test-multi-verdict.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-run lines and the aggregate verdict of a multi-run `fireforge test`
+ * (`--repeat`, mixed harnesses, `--negative-control`). Pure: the
+ * orchestration in `test-orchestrate.ts` feeds it the verdict line each
+ * sub-run would have printed, captured instead of written.
+ */
+/** The prefix every verdict line starts with. */
+const VERDICT_PREFIX = 'FIREFORGE-VERDICT: ';
+/**
+ * Parses a captured verdict line into a sub-run result.
+ *
+ * @param line - The captured line, or undefined when the sub-run wrote none
+ */
+export function parseCapturedVerdict(line) {
+    const body = (line ?? `${VERDICT_PREFIX}FAIL reason=preflight`).slice(VERDICT_PREFIX.length);
+    const passed = body.startsWith('PASS');
+    const reason = /(?:^| )reason=(\S+)/.exec(body)?.[1];
+    const note = /(?:^| )note=(\S+)/.exec(body)?.[1];
+    return {
+        body,
+        passed,
+        ...(reason === undefined ? {} : { reason }),
+        ...(note === undefined ? {} : { note }),
+    };
+}
+/**
+ * The `FIREFORGE-RUN:` line for one sub-run: the verdict it would have
+ * printed alone, plus `run=<i>/<n>` and, for a mixed invocation,
+ * `harness=`. Never `FIREFORGE-VERDICT:`, so the invocation keeps exactly
+ * one verdict line.
+ */
+export function formatRunLine(result, index, total) {
+    const harness = result.harness === undefined ? '' : ` harness=${result.harness}`;
+    return `FIREFORGE-RUN: ${result.body} run=${index + 1}/${total}${harness}`;
+}
+/** Most structural first: the reason an aggregate failure reports. */
+const REASON_RANK = [
+    'inconclusive',
+    'preflight',
+    'crash',
+    'harness-arguments',
+    'no-tests',
+    'test-failures',
+];
+function rankOf(reason) {
+    const rank = REASON_RANK.indexOf(reason ?? '');
+    return rank === -1 ? REASON_RANK.length : rank;
+}
+/** The failed run with the most structural reason, or undefined when all passed. */
+export function worstRun(results) {
+    let worst;
+    for (const result of results) {
+        if (result.passed)
+            continue;
+        if (worst === undefined || rankOf(result.reason) < rankOf(worst.reason))
+            worst = result;
+    }
+    return worst;
+}
+/**
+ * Derives a negative control's outcome.
+ *
+ * @param results - Every finished sub-run
+ * @param repetitions - How many repetitions were planned
+ * @param complete - False when the invocation stopped before its last run
+ */
+export function deriveControlOutcome(results, repetitions, complete) {
+    if (!complete)
+        return 'inconclusive';
+    if (results.some((result) => !result.passed && result.reason !== 'test-failures')) {
+        return 'inconclusive';
+    }
+    for (let repetition = 1; repetition <= repetitions; repetition += 1) {
+        const red = results.some((result) => result.repetition === repetition && result.reason === 'test-failures');
+        if (!red)
+            return 'missed';
+    }
+    return 'caught';
+}
+/**
+ * The aggregate verdict body. A single planned run (a lone control) keeps
+ * its own line, counts included; several aggregate to `PASS runs=<n>/<n>`
+ * or `FAIL reason=<most structural> [note=] runs=<passed>/<planned>`.
+ * A control appends `control=<outcome>`.
+ */
+export function formatAggregateBody(results, plannedTotal, control) {
+    const controlKey = control === undefined ? '' : ` control=${control}`;
+    const only = results[0];
+    if (plannedTotal === 1 && only !== undefined)
+        return `${only.body}${controlKey}`;
+    const passed = results.filter((result) => result.passed).length;
+    const runs = ` runs=${passed}/${plannedTotal}`;
+    const worst = worstRun(results);
+    if (worst === undefined && results.length === plannedTotal)
+        return `PASS${runs}${controlKey}`;
+    const reason = worst?.reason ?? 'preflight';
+    const note = worst?.note === undefined ? '' : ` note=${worst.note}`;
+    return `FAIL reason=${reason}${note}${runs}${controlKey}`;
+}
+/** One-line human summary of a control's outcome. */
+export function describeControlOutcome(outcome) {
+    switch (outcome) {
+        case 'caught':
+            return 'Negative control: the tests went red on the mutation, as a control should (control=caught).';
+        case 'missed':
+            return 'Negative control: the tests STAYED GREEN with the mutation applied, so they do not detect it (control=missed).';
+        case 'inconclusive':
+            return 'Negative control: inconclusive, a run failed for a reason other than test failures or did not run (control=inconclusive).';
+    }
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Multi-run orchestration for `fireforge test`, all under the one
+ * engine-session lock hold the command already has:
+ *
+ *  - mixed harness paths run as two consecutive mach invocations, xpcshell
+ *    first, with one pre-test build (when `--build`) packaging both halves;
+ *  - `--repeat <n>` runs the same selection n times, building once;
+ *  - `--negative-control <diff>` applies a reviewed mutation after the
+ *    build and right before each dispatch, and restores it after the run.
+ *
+ * Each sub-run is the ordinary single-run body. Its verdict line is
+ * captured rather than printed (see `setVerdictCapture`) and echoed as a
+ * `FIREFORGE-RUN:` line, and the invocation ends with one aggregate
+ * `FIREFORGE-VERDICT:` line. A request that needs none of this runs the
+ * body exactly as before.
+ */
+import type { TestOptions } from '../types/commands/index.js';
+/** What the orchestrator asks of one sub-run beyond its paths and options. */
+export interface TestRunHooks {
+    /**
+     * Paths the pre-test build packages and records as coverage when they
+     * are wider than this run's own: the union of a mixed invocation's
+     * halves, so the second half runs build-less against the same build.
+     */
+    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>;
+    /** `--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>;
+/**
+ * Runs `fireforge test` as one or several sub-runs. Always recovers a
+ * negative control a killed earlier run left applied, first.
+ *
+ * @param projectRoot - Project root
+ * @param testPaths - The positional test paths
+ * @param options - Parsed test options
+ * @param body - The single-run body
+ * @param onRefusal - Renders a sub-run's preflight refusal and emits its
+ *   `FAIL reason=preflight` verdict (captured), as `testCommand` does for a
+ *   single run
+ */
+export declare function orchestrateTestRuns(projectRoot: string, testPaths: string[], options: TestOptions, body: TestRunBody, onRefusal: (error: unknown) => void): Promise<void>;