@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,37 +0,0 @@
-/**
- * `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

@@ -1,132 +0,0 @@
-// 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-harness-env.d.ts

@@ -1,23 +0,0 @@
-import type { TestSuite } from './test-run.js';
-/**
- * Builds the perf-sample env contract for the harness run:
- * `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON` naming the
- * artifact file a budget checker consumes after the run.
- */
-export declare function buildPerfSampleEnv(projectRoot: string, binaryName: string, perfSamples: string | undefined): Record<string, string> | undefined;
-/**
- * Merges the per-feature harness env contracts into one map, or `undefined`
- * when no feature exported anything (so `TestRunContext.env` stays absent).
- */
-export declare function mergeHarnessEnv(...parts: (Record<string, string> | undefined)[]): Record<string, string> | undefined;
-/**
- * Resolves the seed for FireForge's isolated shard order and exports it for
- * custom in-file task code. Native mach file shuffling remains unseeded;
- * replaying this seed guarantees only the FireForge shard permutation.
- *
- * Mochitest-only: the xpcshell harness has no shuffle, and generic `mach
- * test` dispatch would forward the flag to every suite it fans out to.
- */
-export declare function resolveShuffleSeed(shuffle: number | boolean | undefined, suite: TestSuite): number | undefined;
-/** Returns a deterministic Fisher–Yates permutation without mutating the selection. */
-export declare function shuffleTestGroups<T>(groups: readonly T[], seed: number): T[];

package/dist/src/commands/test-harness-env.js

@@ -1,81 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Per-feature environment and argument contracts `fireforge test` exports to
- * the harness process: the perf-sample artifact path and the seeded
- * test-order shuffle. Split out of `test.ts` to keep the command body inside
- * its file budget.
- */
-import { randomInt } from 'node:crypto';
-import { resolve } from 'node:path';
-import { GeneralError } from '../errors/base.js';
-import { info } from '../utils/logger.js';
-import { setVerdictRunAttribute } from './test-verdict.js';
-/**
- * Builds the perf-sample env contract for the harness run:
- * `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON` naming the
- * artifact file a budget checker consumes after the run.
- */
-export function buildPerfSampleEnv(projectRoot, binaryName, perfSamples) {
-    if (!perfSamples)
-        return undefined;
-    const envName = `${binaryName.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_PERF_SAMPLE_JSON`;
-    const artifactPath = resolve(projectRoot, perfSamples);
-    info(`Perf sample contract: ${envName}=${artifactPath}`);
-    return { [envName]: artifactPath };
-}
-/**
- * Merges the per-feature harness env contracts into one map, or `undefined`
- * when no feature exported anything (so `TestRunContext.env` stays absent).
- */
-export function mergeHarnessEnv(...parts) {
-    const merged = {};
-    for (const part of parts) {
-        if (part)
-            Object.assign(merged, part);
-    }
-    return Object.keys(merged).length > 0 ? merged : undefined;
-}
-/**
- * Resolves the seed for FireForge's isolated shard order and exports it for
- * custom in-file task code. Native mach file shuffling remains unseeded;
- * replaying this seed guarantees only the FireForge shard permutation.
- *
- * Mochitest-only: the xpcshell harness has no shuffle, and generic `mach
- * test` dispatch would forward the flag to every suite it fans out to.
- */
-export function resolveShuffleSeed(shuffle, suite) {
-    if (shuffle === undefined || shuffle === false)
-        return undefined;
-    if (suite !== 'mochitest') {
-        throw new GeneralError("--shuffle forwards the mochitest harness's file-order shuffle; 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).');
-    }
-    const seed = shuffle === true ? randomInt(1, 2 ** 31 - 1) : shuffle;
-    setVerdictRunAttribute('shuffle', String(seed));
-    info(`Test shard order: seed=${seed} (replay with "fireforge test --shuffle=${seed}"). ` +
-        'Native harness file shuffle remains unseeded.');
-    return seed;
-}
-/** Returns a deterministic Fisher–Yates permutation without mutating the selection. */
-export function shuffleTestGroups(groups, seed) {
-    const shuffled = [...groups];
-    // Hash the decimal seed so every accepted safe integer contributes, rather
-    // than silently discarding its high bits in the 32-bit PRNG.
-    let state = 2166136261;
-    for (const character of String(seed))
-        state = Math.imul(state ^ character.charCodeAt(0), 16777619);
-    state = state >>> 0 || 1;
-    for (let index = shuffled.length - 1; index > 0; index--) {
-        state ^= state << 13;
-        state ^= state >>> 17;
-        state ^= state << 5;
-        const destination = Math.floor(((state >>> 0) / 2 ** 32) * (index + 1));
-        // Both indexes are bounded by the array length, including under
-        // noUncheckedIndexedAccess; T may itself contain undefined.
-        const selected = shuffled[index];
-        shuffled[index] = shuffled[destination];
-        shuffled[destination] = selected;
-    }
-    return shuffled;
-}

package/dist/src/commands/test-harness-teardown.d.ts

@@ -1,62 +0,0 @@
-/**
- * Owns the kill path of one mach test dispatch for `fireforge test`.
- *
- * Three things the run must do around every `runMachTestSuite` call, kept
- * together because each one exists for the same incident (a supervisor
- * killed the process above FireForge at its bound and the harness httpd it
- * had launched spun for hours):
- *
- *  1. Track the helper pids the harness announces, and after mach has
- *     exited terminate any that outlived it (`harness-helper-pids.ts`).
- *  2. Publish the harness process group (`--pgid-file`), so a supervisor
- *     that can only SIGKILL FireForge can still take the whole tree with
- *     one `kill -- -<pgid>` afterwards.
- *  3. Watch FireForge's own parent (`parent-exit-watchdog.ts`). When it
- *     vanishes mid-run, write the killed verdict, reap the group, and let
- *     the dispatch loop end the run instead of retrying.
- *
- * Every reap adds to the `orphans-reaped=` verdict attribute.
- */
-import type { MachTestSuiteOptions } from '../core/mach.js';
-/** Inputs for {@link createHarnessTeardown}. */
-export interface HarnessTeardownInputs {
-    /** Absolute objdir of this project, when known: the anchor for every kill. */
-    objDir: string | undefined;
-    /** `--pgid-file`: where to publish the harness process group id. */
-    pgidFile: string | undefined;
-}
-/** One dispatch's teardown: the hooks to spread into `runMachTestSuite`, and its lifecycle. */
-export interface HarnessTeardown {
-    /** Hooks for {@link MachTestSuiteOptions.teardown}. */
-    hooks: NonNullable<MachTestSuiteOptions['teardown']>;
-    /**
-     * Records the same-objdir helpers alive right now, before the dispatch
-     * spawns anything, so the post-close reap can tell this dispatch's
-     * unannounced helpers from an earlier run's survivors. Await it before
-     * `runMachTestSuite`.
-     */
-    prepare(): Promise<void>;
-    /** Stops the parent watchdog. Call after the dispatch resolved or threw. */
-    dispose(): void;
-}
-/**
- * Builds the teardown for one dispatch (one retry attempt of one shard).
- * The pid tracker and the group id are per dispatch; the parent watchdog
- * runs only while that dispatch is in flight.
- */
-export declare function createHarnessTeardown(inputs: HarnessTeardownInputs): HarnessTeardown;
-/** Records the run's pgid file so {@link removeActivePgidFile} can find it from the signal handler. */
-export declare function setActivePgidFile(path: string | undefined): void;
-/**
- * Removes the pgid file at the end of a run that ended under FireForge's
- * control. A file left behind after a normal exit would name a group id
- * the kernel may have reused; the file must only outlive FireForge when
- * FireForge itself was killed without notice, which is what it is for.
- */
-export declare function removePgidFile(path: string | undefined): Promise<void>;
-/**
- * Signal-pipeline variant of {@link removePgidFile}: removes the run's pgid
- * file, if one is registered. Called by the bin entry point after the child
- * shutdown wait, so the group the file names has already been signalled.
- */
-export declare function removeActivePgidFile(): Promise<void>;

package/dist/src/commands/test-harness-teardown.js

@@ -1,128 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Owns the kill path of one mach test dispatch for `fireforge test`.
- *
- * Three things the run must do around every `runMachTestSuite` call, kept
- * together because each one exists for the same incident (a supervisor
- * killed the process above FireForge at its bound and the harness httpd it
- * had launched spun for hours):
- *
- *  1. Track the helper pids the harness announces, and after mach has
- *     exited terminate any that outlived it (`harness-helper-pids.ts`).
- *  2. Publish the harness process group (`--pgid-file`), so a supervisor
- *     that can only SIGKILL FireForge can still take the whole tree with
- *     one `kill -- -<pgid>` afterwards.
- *  3. Watch FireForge's own parent (`parent-exit-watchdog.ts`). When it
- *     vanishes mid-run, write the killed verdict, reap the group, and let
- *     the dispatch loop end the run instead of retrying.
- *
- * Every reap adds to the `orphans-reaped=` verdict attribute.
- */
-import { unlink, writeFile } from 'node:fs/promises';
-import { createHelperPidTracker, reapTrackedHarnessPids, snapshotObjdirHelpers, } from '../core/harness-helper-pids.js';
-import { startParentExitWatchdog } from '../core/parent-exit-watchdog.js';
-import { toError } from '../utils/errors.js';
-import { verbose, warn } from '../utils/logger.js';
-import { sweepProcessGroup } from '../utils/process-group.js';
-import { addVerdictRunCount, emitKilledVerdict } from './test-verdict.js';
-/**
- * Builds the teardown for one dispatch (one retry attempt of one shard).
- * The pid tracker and the group id are per dispatch; the parent watchdog
- * runs only while that dispatch is in flight.
- */
-export function createHarnessTeardown(inputs) {
-    const tracker = createHelperPidTracker();
-    let pgid;
-    let baseline;
-    const watchdog = startParentExitWatchdog({
-        onParentExit: ({ originalPpid, currentPpid }) => {
-            // Verdict first, before anything that can stall: the parent that would
-            // have read it is gone, but the run log and any tee of stdout are not.
-            emitKilledVerdict('parent-exit');
-            warn(`Parent process ${originalPpid} exited while the harness was running (this process now ` +
-                `reports parent ${currentPpid}); ending the run and terminating the harness tree so it ` +
-                'cannot run on unsupervised.');
-            if (pgid !== undefined) {
-                void sweepProcessGroup(pgid, undefined, 'after the parent process exited').catch((error) => {
-                    warn(`Reaping harness group ${pgid} after parent exit failed: ${toError(error).message}`);
-                });
-            }
-        },
-    });
-    return {
-        hooks: {
-            onOutputChunk: (stream, chunk) => {
-                tracker.feed(stream, chunk);
-            },
-            onProcessGroup: (id) => {
-                pgid = id;
-                verbose(`Harness process group: ${id} (mach is the group leader).`);
-                if (inputs.pgidFile !== undefined)
-                    void publishPgid(inputs.pgidFile, id);
-            },
-            postCloseSweep: async () => {
-                const reaped = await reapTrackedHarnessPids(tracker.tracked(), inputs.objDir, baseline);
-                addVerdictRunCount('orphans-reaped', reaped);
-            },
-        },
-        prepare: async () => {
-            baseline = await snapshotObjdirHelpers(inputs.objDir);
-        },
-        dispose: () => {
-            watchdog.stop();
-        },
-    };
-}
-/**
- * Writes `<pgid>\n` to the pgid file. Best-effort: a supervisor that asked
- * for the file and cannot get it is warned, and the run proceeds, because
- * the file is a courtesy to the supervisor and not a precondition of the
- * tests.
- */
-async function publishPgid(path, pgid) {
-    try {
-        await writeFile(path, `${pgid}\n`, 'utf8');
-    }
-    catch (error) {
-        warn(`Could not write --pgid-file ${path}: ${toError(error).message}`);
-    }
-}
-/**
- * The pgid file of the run in flight, for the signal pipeline. `testCommand`'s
- * own `finally` removes the file on every path it controls, but on SIGTERM
- * that `finally` races the bin handler's `process.exit` and loses, and a
- * SIGTERM is notice: the file must not outlive a run FireForge itself
- * ended. Set when the run starts, cleared by {@link removePgidFile}.
- */
-let activePgidFile;
-/** Records the run's pgid file so {@link removeActivePgidFile} can find it from the signal handler. */
-export function setActivePgidFile(path) {
-    activePgidFile = path;
-}
-/**
- * Removes the pgid file at the end of a run that ended under FireForge's
- * control. A file left behind after a normal exit would name a group id
- * the kernel may have reused; the file must only outlive FireForge when
- * FireForge itself was killed without notice, which is what it is for.
- */
-export async function removePgidFile(path) {
-    if (path === undefined)
-        return;
-    if (activePgidFile === path)
-        activePgidFile = undefined;
-    try {
-        await unlink(path);
-    }
-    catch (error) {
-        // ENOENT is the usual case when no dispatch ever spawned.
-        verbose(`--pgid-file ${path} not removed: ${toError(error).message}`);
-    }
-}
-/**
- * Signal-pipeline variant of {@link removePgidFile}: removes the run's pgid
- * file, if one is registered. Called by the bin entry point after the child
- * shutdown wait, so the group the file names has already been signalled.
- */
-export async function removeActivePgidFile() {
-    await removePgidFile(activePgidFile);
-}

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

@@ -1,57 +0,0 @@
-import type { TestOptions } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.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. */
-export declare function assertTestModeCombinations(testPaths: readonly string[], options: TestOptions, canaryPath: string | undefined): void;
-/** Resolves the canary path from CLI or config. */
-export declare function resolveCanaryPath(options: TestOptions, projectConfig: FireForgeConfig): string | undefined;
-/** Returns the configured canary no-output budget, defaulting to 60 seconds. */
-export declare function canaryTimeoutSeconds(projectConfig: FireForgeConfig): number;
-/** Emits or throws the one-word canary verdict. */
-export declare function reportCanaryOutcome(outcome: TestRunOutcome): void;
-/** Per-harness bucketing of the requested test paths. */
-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
- * dispatch, so refusing it before spending minutes in a pre-test build
- * is strictly better. A nonexistent path classifies as
- * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
- * before assertTestPathsExist is harmless: existence is still asserted
- * after the stale/coverage gates, preserving their precedence over
- * missing-path errors. `xpcshellOnly` (non-empty request, zero
- * nonXpcshell paths) gates the Marionette preflight and the mochitest
- * client flags. Pathless runs keep the full-suite behavior.
- */
-export declare function classifyBeforeDispatch(engineDir: string, normalizedPaths: string[], options?: {
-    allowMixed?: boolean;
-}): Promise<{
-    classification: HarnessClassification;
-    xpcshellOnly: boolean;
-}>;
-/**
- * Prints the `--build-only` completion guidance: the union build is
- * recorded as the packaging-coverage claim, so each harness half can now
- * 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[];