@hominis/fireforge 0.50.0 → 0.52.0

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

@@ -0,0 +1,255 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Sharded `fireforge test` runs: one harness invocation per shard, run in
+ * order on one harness instance, or on a pool of `--jobs <n>` instances.
+ *
+ * Each finished shard prints a `FIREFORGE-SHARD:` line, and the aggregate
+ * verdict names the shards that did not pass as `failed-shards=`. Before,
+ * the failing shards were named only in the prose of the aggregate error
+ * and the human summary box, so a wrapper that reruns failed shards had to
+ * parse a sentence that a reworded message would silently break.
+ *
+ * Under `--shard-size <n>` a shard is a chunk of n files, and the run is
+ * judged per file from each dispatch's raw log: `shards=` then counts files
+ * and `failed-shards=` names the files that failed.
+ */
+import { getActiveRunLogPath, writeToActiveRunLog } from '../core/run-log.js';
+import { buildHarnessCrashMessage, formatFireforgeVerdictLine, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
+import { TestFailureError } from '../errors/build.js';
+import { info, note, warn } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
+import { runTestsWithRetries } from './test-run.js';
+import { emitHarnessVerdict } from './test-verdict.js';
+const SHARD_STATUS_LABEL = {
+    'tests-ran-ok': 'PASS',
+    'test-failures': 'FAIL',
+    'harness-crash': 'CRASH',
+    'no-tests': 'NO-TESTS',
+    'harness-arguments': 'ARGUMENTS',
+};
+/**
+ * Derives the aggregate classification for a sharded run: all-green is
+ * `tests-ran-ok`. Otherwise the most structural failure wins. A crashed
+ * shard makes the whole run `harness-crash`, then `no-tests`, then plain
+ * `test-failures`, so the aggregate `reason=` keeps the classifier-driven
+ * contract instead of collapsing every failure to `test-failures`.
+ */
+export function deriveAggregateShardVerdict(shards) {
+    const kinds = new Set(shards.map(({ outcome }) => outcome.verdict.kind));
+    if (kinds.has('harness-arguments'))
+        return { kind: 'harness-arguments' };
+    if (kinds.has('harness-crash'))
+        return { kind: 'harness-crash' };
+    if (kinds.has('no-tests'))
+        return { kind: 'no-tests' };
+    if (kinds.has('test-failures'))
+        return { kind: 'test-failures' };
+    return { kind: 'tests-ran-ok' };
+}
+/**
+ * The `FIREFORGE-SHARD:` line for one finished shard: the verdict it would
+ * have printed alone, plus `shard=<i>/<n>` and `path=<label>`. Never a
+ * `FIREFORGE-VERDICT:` line, so the run keeps exactly one.
+ */
+export function formatShardLine(shard, index, total, failedFiles) {
+    const body = formatFireforgeVerdictLine(shard.outcome.verdict).slice('FIREFORGE-VERDICT: '.length);
+    const files = failedFiles !== undefined && failedFiles.length > 0
+        ? ` failed-files=${failedFiles.join(',')}`
+        : '';
+    return `FIREFORGE-SHARD: ${body} shard=${index + 1}/${total} path=${shard.label.replace(/\s+/g, '_')}${files}`;
+}
+function writeShardLine(line) {
+    process.stdout.write(`${line}\n`);
+    writeToActiveRunLog(`${line}\n`);
+}
+/** True when a raw-log test id names the dispatched path. */
+function namesPath(test, path) {
+    return test === path || test.endsWith(`/${path}`) || path.endsWith(`/${test}`);
+}
+/**
+ * The files of one shard that did not pass, judged from its raw log. A file
+ * with no `test_end` failed (it never started, or never finished). Returns
+ * undefined when the shard wrote no raw log, so the caller judges the
+ * shard as a whole.
+ */
+export function failedFilesOf(shard) {
+    const results = shard.outcome.fileResults;
+    if (results === undefined || shard.paths === undefined)
+        return undefined;
+    return shard.paths.filter((path) => {
+        const result = results.find((entry) => namesPath(entry.test, path));
+        return result === undefined || result.unexpected;
+    });
+}
+function reportShardFailure(ctx, outcome, label, diagnoseShardFailure) {
+    if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
+        const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
+        const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
+            headless: ctx.headless,
+            platform: getPlatform(),
+            ...(outcome.displayState !== undefined ? { displayState: outcome.displayState } : {}),
+        });
+        warn(hint ? `${base}\n\n${hint}` : base);
+    }
+    else if (outcome.verdict.kind !== 'tests-ran-ok') {
+        const diagnosis = diagnoseShardFailure(outcome, label);
+        if (diagnosis)
+            warn(diagnosis);
+    }
+}
+/**
+ * Runs `count` items on up to `jobs` workers at once. Worker `w` handles
+ * the items it takes in order, and results keep item order.
+ */
+async function runPool(count, jobs, worker) {
+    const results = new Array(count);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(jobs, count)) }, async (_, w) => {
+        while (next < count) {
+            const item = next;
+            next += 1;
+            results[item] = await worker(item, w);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Runs each shard as its own harness invocation and prints an aggregate
+ * report. Per-shard failures are diagnosed via `diagnoseShardFailure`
+ * (which receives the throwing diagnosis chain from the command layer)
+ * but downgraded to warnings so every shard runs. The aggregate verdict
+ * line and the aggregate error are not produced here: the caller runs
+ * the engine-generation integrity check first and then calls
+ * {@link finalizeShardedOutcome}, so a run invalidated by a concurrent
+ * `engine/` mutation can never print `PASS` before the check fails.
+ */
+export async function runShardedTests(ctx, groups, diagnoseShardFailure, options = {}) {
+    const jobs = options.jobs ?? 1;
+    const contexts = new Map([[0, ctx]]);
+    const contextFor = async (index) => {
+        const known = contexts.get(index);
+        if (known !== undefined)
+            return known;
+        const made = options.contextFor === undefined ? ctx : await options.contextFor(index);
+        contexts.set(index, made);
+        return made;
+    };
+    let finished = 0;
+    const shards = await runPool(groups.length, jobs, async (index, workerIndex) => {
+        const group = groups[index];
+        const instance = await contextFor(workerIndex);
+        info(`— Shard ${index + 1}/${groups.length}${jobs > 1 ? ` [job ${workerIndex + 1}]` : ''}: ${group.label}`);
+        const outcome = await runTestsWithRetries(instance, group.paths, group.label);
+        // Perf power-source changes are recorded on the instance's context.
+        if (instance.powerChanged === true)
+            ctx.powerChanged = true;
+        const shard = { label: group.label, outcome, paths: group.paths };
+        reportShardFailure(instance, outcome, group.label, diagnoseShardFailure);
+        finished += 1;
+        writeShardLine(formatShardLine(shard, index, groups.length, options.perFile === true ? failedFilesOf(shard) : undefined));
+        reportProgress(finished, groups.length, jobs);
+        return shard;
+    });
+    return summarizeShards(shards, options.perFile === true);
+}
+function reportProgress(finished, total, jobs) {
+    if (jobs > 1)
+        info(`${finished}/${total} shard(s) finished.`);
+}
+/**
+ * Builds the summary box and the counts. Per-file judging counts every
+ * dispatched file of a shard that wrote a raw log; a shard without one
+ * counts as a whole.
+ */
+function summarizeShards(shards, perFile) {
+    const lines = shards.map(({ label, outcome }) => `${SHARD_STATUS_LABEL[outcome.verdict.kind].padEnd(8)} ${label}` +
+        (outcome.attempts > 1 ? `  (${outcome.attempts} attempts)` : ''));
+    const failingShards = shards.filter(({ outcome }) => outcome.verdict.kind !== 'tests-ran-ok');
+    let passed = shards.length - failingShards.length;
+    let total = shards.length;
+    let failed = failingShards.map(({ label }) => label);
+    if (perFile) {
+        passed = 0;
+        total = 0;
+        failed = [];
+        for (const shard of shards) {
+            const files = failedFilesOf(shard);
+            const ok = shard.outcome.verdict.kind === 'tests-ran-ok';
+            if (files === undefined) {
+                total += 1;
+                if (ok)
+                    passed += 1;
+                else
+                    failed.push(shard.label);
+                continue;
+            }
+            const dispatched = shard.paths ?? [];
+            total += dispatched.length;
+            // A red shard whose log names no failing file still failed: count
+            // every file of it, so a crash cannot read as all-green.
+            const red = files.length === 0 && !ok ? dispatched : files;
+            passed += dispatched.length - red.length;
+            failed.push(...red);
+        }
+    }
+    note(`${lines.join('\n')}\n\n${passed}/${total} ${perFile ? 'file(s)' : 'shard(s)'} passed`, 'Sharded Test Summary');
+    return { shards, passed, total, failed, aggregate: deriveAggregateShardVerdict(shards) };
+}
+/**
+ * Emits the aggregate FIREFORGE-VERDICT line for a sharded run, then
+ * throws the aggregate error when any shard did not pass, the same
+ * emit-then-throw shape as `finalizeSingleRunOutcome`. Called only after
+ * the engine-generation check succeeded.
+ */
+export function finalizeShardedOutcome(summary) {
+    emitHarnessVerdict(summary.aggregate, {
+        passed: summary.passed,
+        total: summary.total,
+        failed: summary.failed.map((label) => label.replace(/\s+/g, '_')),
+    });
+    if (summary.passed < summary.total) {
+        throw new TestFailureError(`${summary.failed.length} of ${summary.total} sharded test run(s) did not pass: ` +
+            `${summary.failed.join(', ')}. ` +
+            'See the per-shard diagnosis above. Use --no-shard to reproduce the combined single-invocation behaviour.', 'mach test', undefined, getActiveRunLogPath());
+    }
+}
+/**
+ * Splits the dispatch paths of every group into consecutive chunks of at
+ * most `size` files (`--shard-size`). Order is kept, and a chunk never
+ * mixes groups' order: it is the flattened request, cut every `size`
+ * files.
+ */
+export function chunkShardGroups(groups, size) {
+    const paths = groups.flatMap((group) => group.paths);
+    const chunks = [];
+    for (let start = 0; start < paths.length; start += size) {
+        const chunk = paths.slice(start, start + size);
+        const first = chunk[0] ?? '';
+        chunks.push({
+            label: chunk.length === 1 ? first : `${first}+${chunk.length - 1}`,
+            paths: chunk,
+        });
+    }
+    return chunks;
+}
+/**
+ * Splits one combined request into `parts` contiguous chunks of near-equal
+ * size, in order (`--jobs` with `--no-shard`).
+ */
+export function splitContiguous(paths, parts) {
+    const count = Math.max(1, Math.min(parts, paths.length));
+    const groups = [];
+    let start = 0;
+    for (let index = 0; index < count; index += 1) {
+        const size = Math.ceil((paths.length - start) / (count - index));
+        const chunk = paths.slice(start, start + size);
+        start += size;
+        const first = chunk[0] ?? '';
+        groups.push({
+            label: chunk.length === 1 ? first : `${first}+${chunk.length - 1}`,
+            paths: chunk,
+        });
+    }
+    return groups;
+}

package/dist/src/commands/test-stale-gate.d.ts

@@ -28,7 +28,11 @@ import type { TestOptions } from '../types/commands/index.js';
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
-export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[]): Promise<void>;
+export declare function enforceStaleBuildGate(projectRoot: string, engineDir: string, options: TestOptions, normalizedPaths: readonly string[], 
+/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+gate?: {
+    quiet?: boolean;
+}): Promise<void>;
 /**
  * Compiled-StaticComponents gate: refuses runs whose child process would
  * resolve a stale compiled component table. `components.conf` entries bake

package/dist/src/commands/test-stale-gate.js

@@ -11,6 +11,7 @@ import { filterByCarriedFullCoverage } from '../core/coverage-dispatch.js';
 import { checkStaleBuildForTest, checkStaticComponentsStale, findChangedTestManifestsForPaths, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, FULL_SUITE_REQUEST, } from '../core/test-stale-check.js';
 import { formatStaleExemptions } from '../core/test-stale-exempt.js';
 import { PreflightRefusalError } from '../errors/base.js';
+import { isProcessAlive } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
 import { describePerfStaleImpact } from './test-perf-scope.js';
 /**
@@ -33,7 +34,9 @@ import { describePerfStaleImpact } from './test-perf-scope.js';
  * a full-suite request would refuse a probe that touches no fixtures. The
  * stale-content refusal still applies to it unchanged.
  */
-export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths) {
+export async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths, 
+/** `quiet`: refuse only, without the exemption note (the pre-lock pass). */
+gate = {}) {
     const stale = await checkStaleBuildForTest(projectRoot, engineDir);
     const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
     if (!dispatchesNoTests) {
@@ -41,7 +44,7 @@ export async function enforceStaleBuildGate(projectRoot, engineDir, options, nor
     }
     await enforceStaticComponentsGate(engineDir, stale.baseline, options);
     const exempt = stale.exempt ?? [];
-    if (!stale.stale && exempt.length > 0) {
+    if (!stale.stale && exempt.length > 0 && gate.quiet !== true) {
         info(`Stale-build preflight: ${exempt.length} edit(s) since the last build need no rebuild: ${formatStaleExemptions(exempt)}.`);
     }
     if (!stale.stale)
@@ -91,6 +94,12 @@ async function enforceCoverageGate(engineDir, baseline, normalizedPaths) {
     throw new PreflightRefusalError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : [], changedManifests, {
         changedInputs: Object.fromEntries(remaining.map((request) => [request.path, request.changed])),
         carriesFullAnchor: baseline?.fullCoverageAnchor !== undefined,
+        recordedBy: baseline?.recordedBy,
+        builtAt: baseline?.builtAt,
+        recorder: baseline?.recorder,
+        recorderAlive: baseline?.recorder !== undefined &&
+            baseline.recorder.pid !== process.pid &&
+            isProcessAlive(baseline.recorder.pid),
     }), 'coverage-replaced');
 }
 /**

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

@@ -13,7 +13,7 @@ import type { HarnessRunVerdict } from '../core/test-harness-crash.js';
  */
 export type FireforgeVerdictReason = 'crash' | 'harness-arguments' | 'no-tests' | 'test-failures' | 'preflight' | 'inconclusive' | 'lock-timeout' | 'killed';
 /** Additive keys a run can stamp on its verdict line. */
-export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply';
+export type VerdictRunAttributeKey = 'shuffle' | 'orphans-reaped' | 'host-load' | 'host-cpu-warning' | 'power-source' | 'power-changed' | 'furnace-applied' | 'furnace-apply' | 'furnace-skipped' | 'control-build' | 'drift-tolerated' | 'lock' | 'jobs' | 'results';
 /** Records an additive attribute for this run's verdict line. */
 export declare function setVerdictRunAttribute(key: VerdictRunAttributeKey, value: string): void;
 /**
@@ -46,6 +46,7 @@ export declare function emitAggregateVerdict(body: string): void;
 export declare function emitHarnessVerdict(verdict: HarnessRunVerdict, shards?: {
     passed: number;
     total: number;
+    failed?: readonly string[];
 }): void;
 /** Emits the pathless `--doctor` PASS verdict. */
 export declare function emitPassVerdict(): void;

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

@@ -19,4 +19,4 @@ import type { TestOptions } from '../types/commands/index.js';
  * @param options - Test options
  * @param underLock - Runs the rest of the command under the engine session lock
  */
-export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions, underLock?: (body: () => Promise<void>) => Promise<void>): Promise<void>;
+export declare function testCommand(projectRoot: string, testPaths: string[], options?: TestOptions, underLock?: (body: () => Promise<void>, mode?: 'exclusive' | 'shared') => Promise<void>): Promise<void>;

package/dist/src/commands/test.js

@@ -1,8 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
-import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
 import { hasBuildArtifacts } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
@@ -13,23 +12,22 @@ import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-sco
 import { cleanupProfileFiles, stageProfileFiles, } from '../core/test-profile-files.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
 import { FireForgeError, GeneralError, LockContentionError, PreflightRefusalError, } from '../errors/base.js';
-import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, notice, warn } from '../utils/logger.js';
+import { info, intro, warn } from '../utils/logger.js';
 import { resolveWaitLockSeconds } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { appendMarionetteForwardingArgs, ensureTestBrowserEnvironment, runDoctorPreflight, } from './test-browser-preflight.js';
 import { runTestBuildPhase } from './test-build-phase.js';
-import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
-import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed, shuffleTestGroups, } from './test-harness-env.js';
+import { assertParallelTestUsage, dispatchTests } from './test-dispatch.js';
+import { buildPerfSampleEnv, mergeHarnessEnv, resolveShuffleSeed } from './test-harness-env.js';
 import { removePgidFile, setActivePgidFile } from './test-harness-teardown.js';
-import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, reportCanaryOutcome, resolveCanaryPath, restartBetweenTestsArgs, } from './test-modes.js';
+import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, classifyBeforeDispatch, resolveCanaryPath, restartBetweenTestsArgs, } from './test-modes.js';
 import { orchestrateTestRuns } from './test-orchestrate.js';
-import { perfGenerationTolerance } from './test-perf-scope.js';
 import { resolveLaunchablePathForTests, runTestPreLockPreflight, TEST_BUILD_PREFLIGHT, } from './test-prelock.js';
-import { DEFAULT_HARNESS_RETRIES, finalizeShardedOutcome, runShardedTests, runTestsWithRetries, } from './test-run.js';
-import { emitFailVerdict, resetVerdictEmission, verdictEmitted } from './test-verdict.js';
+import { resetTestResults, withRawLogDir, writeTestResults } from './test-results.js';
+import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
+import { emitFailVerdict, resetVerdictEmission, setVerdictRunAttribute, verdictEmitted, } from './test-verdict.js';
 async function assertTestPathsExist(engineDir, testPaths) {
     const missingPaths = [];
     for (const testPath of testPaths) {
@@ -126,12 +124,35 @@ export async function testCommand(projectRoot, testPaths, options = {}, underLoc
             staged = await stageProfileFiles(projectRoot, options.profileFile);
             options = { ...options, machArg: [...(options.machArg ?? []), ...staged.args] };
         }
+        assertParallelTestUsage(testPaths, options);
         const lockedOptions = await runTestPreLockPreflight(projectRoot, testPaths, options);
         const profileEnv = staged?.env;
-        await underLock(() => orchestrateTestRuns(projectRoot, testPaths, lockedOptions, (paths, runOptions, hooks) => runTestCommandBody(projectRoot, paths, runOptions, profileEnv, hooks), (error) => {
+        // The pre-lock pass resolved `sharedLock` against config and the run's shape.
+        const lockMode = lockedOptions.sharedLock === true ? 'shared' : 'exclusive';
+        if (lockMode === 'shared')
+            setVerdictRunAttribute('lock', 'shared');
+        resetTestResults();
+        if (options.results !== undefined) {
+            setVerdictRunAttribute('results', resolve(projectRoot, options.results));
+        }
+        const orchestrate = (rawLogDir) => orchestrateTestRuns(projectRoot, testPaths, lockedOptions, (paths, runOptions, hooks) => runTestCommandBody(projectRoot, paths, runOptions, profileEnv, {
+            ...hooks,
+            ...(rawLogDir === undefined ? {} : { rawLogDir }),
+        }), (error) => {
             renderPreflightRefusal(error);
             emitFailVerdict('preflight', refusalNote(error));
-        }));
+        });
+        // `--jobs` always reads each dispatch's raw log, so a shard that ran
+        // files other than its own fails instead of passing on their results.
+        const collectsResults = options.results !== undefined || options.shardSize !== undefined || (options.jobs ?? 1) > 1;
+        try {
+            await underLock(() => (collectsResults ? withRawLogDir((dir) => orchestrate(dir)) : orchestrate()), lockMode);
+        }
+        finally {
+            if (options.results !== undefined) {
+                await writeResultsFile(resolve(projectRoot, options.results));
+            }
+        }
     }
     catch (error) {
         if (!verdictEmitted()) {
@@ -164,6 +185,15 @@ export async function testCommand(projectRoot, testPaths, options = {}, underLoc
         }
     }
 }
+/** Writes `--results`; a failure warns, since the run's verdict is already out. */
+async function writeResultsFile(path) {
+    try {
+        await writeTestResults(path);
+    }
+    catch (error) {
+        warn(`Could not write --results ${path}: ${toError(error).message}`);
+    }
+}
 /** The refusal class a preflight gate named, when it named one. */
 function refusalNote(error) {
     return error instanceof PreflightRefusalError ? error.note : undefined;
@@ -198,26 +228,6 @@ function renderPreflightRefusal(error) {
     process.stdout.write(block);
     writeToActiveRunLog(block);
 }
-/**
- * Verifies `engine/` did not change under the run before any PASS verdict
- * may print. On failure the run's verdict is `FAIL reason=inconclusive`,
- * because the harness result exists but cannot be trusted (`preflight` would
- * misdescribe a run whose harness already executed). It is emitted here so the
- * guard's throw can never leave a stale or missing verdict line behind.
- */
-async function verifyEngineGenerationOrEmitInconclusive(engineDir, before, powerChanged = false, perfSamples) {
-    try {
-        await (perfSamples === undefined
-            ? assertEngineGenerationUnchanged(engineDir, before)
-            : assertEngineGenerationUnchanged(engineDir, before, perfGenerationTolerance(engineDir)));
-        if (powerChanged)
-            throw new GeneralError('Perf power source changed during the run; repeat this sitting on a stable power source.');
-    }
-    catch (error) {
-        emitFailVerdict('inconclusive');
-        throw error;
-    }
-}
 async function guardBuildBrowser(engineDir, launchablePath, options) {
     if ((options.build || options.buildOnly) && launchablePath) {
         await waitForPreflight(() => ensureLaunchableBrowserNotRunning(join(engineDir, launchablePath), {
@@ -254,7 +264,12 @@ function prepareDispatchArguments(classification, options, canaryPath, projectCo
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
         : [];
     const extraArgs = prepareExtraMachArgs(options, shuffleSeed, canaryPath, projectConfig, forwardedMachArgs);
-    extraArgs.push(...restartBetweenTestsArgs(options, suite, forwardedMachArgs));
+    // A `--shard-size` chunk runs several files in one browser; mochitest
+    // restarts it between them so a chunk judges each file as a shard would.
+    const restart = options.shardSize !== undefined && suite === 'mochitest'
+        ? { ...options, restartBetweenTests: true }
+        : options;
+    extraArgs.push(...restartBetweenTestsArgs(restart, suite, forwardedMachArgs));
     return { suite, shuffleSeed, extraArgs };
 }
 /**
@@ -327,9 +342,13 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     // documented `--mach-arg --marionette-port=NNNN` route still hits the
     // wrapper preflight refusing on 2828 before the forwarded arg reaches
     // mach.
+    // A negative control on compiled source goes in here, so the build
+    // compiles it (see negative-control-compiled.ts).
+    await hooks.beforeBuild?.();
     if (await runTestBuildPhase(projectRoot, paths, projectConfig, harnessRetries, options, {
         classification,
         normalizedPaths: hooks.coveragePaths ?? normalizedPaths,
+        ...(hooks.fullBuildReason === undefined ? {} : { fullBuildReason: hooks.fullBuildReason }),
     })) {
         return;
     }
@@ -364,6 +383,8 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
         ...(options.fullOutput === true ? { fullOutput: true } : {}),
         ...(harnessEnv ? { env: harnessEnv } : {}),
         pgidFile: options.pgidFile,
+        ...(hooks.rawLogDir === undefined ? {} : { rawLogDir: hooks.rawLogDir }),
+        ...(hooks.repetition === undefined ? {} : { repetition: hooks.repetition }),
     };
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
@@ -376,46 +397,18 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}, profileE
     // into later files. Sharding is per path argument: a directory argument
     // keeps its enumerated files together in one invocation, preserving the
     // one-browser-instance semantics of a directory run. `--no-shard` restores
-    // the combined invocation. The default must not be silent: a cross-file
-    // pollution repro otherwise "passes" because the comparison run was
-    // sharded without saying so, misattributing a suite-context bug upstream.
-    // Hence the one-line notice stating what sharding does and does not
-    // exercise.
-    if (canaryPath === undefined && dispatchGroups.length > 1 && options.shard !== false) {
-        notice(`Sharding: running ${dispatchGroups.length} test path arguments in isolated browser instances ` +
-            '(one mach invocation per argument; a directory argument keeps its files in one instance). ' +
-            'Cross-argument state is NOT exercised — pass --no-shard for a combined single-instance run.');
-        const generationBefore = await snapshotEngineGeneration(paths.engine);
-        let summary;
-        try {
-            const orderedGroups = shuffleSeed === undefined ? dispatchGroups : shuffleTestGroups(dispatchGroups, shuffleSeed);
-            summary = await runShardedTests(runCtx, orderedGroups, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, postRebuildContext));
-        }
-        finally {
-            // Runs before the aggregate verdict below: a mutated engine/ emits
-            // `FAIL reason=inconclusive` and throws, so an invalidated run can
-            // never print `PASS shards=N/N` first. (A throw here masks an
-            // in-flight shard error, as the plain assert always did.)
-            await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged, options.perfSamples);
-        }
-        finalizeShardedOutcome(summary);
-        return;
-    }
-    const combinedDispatchPaths = dispatchGroups.flatMap((group) => group.paths);
-    let outcome;
-    const generationBefore = await snapshotEngineGeneration(paths.engine);
-    try {
-        outcome = await runTestsWithRetries(runCtx, combinedDispatchPaths);
-    }
-    catch (error) {
-        throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
-    }
-    finally {
-        await verifyEngineGenerationOrEmitInconclusive(paths.engine, generationBefore, runCtx.powerChanged, options.perfSamples);
-    }
-    if (canaryPath !== undefined) {
-        reportCanaryOutcome(outcome);
-        return;
-    }
-    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext, options.headless === true);
+    // the combined invocation; `--shard-size` and `--jobs` reshape it (see
+    // test-dispatch.ts).
+    await dispatchTests({
+        engineDir: paths.engine,
+        runCtx,
+        dispatchGroups,
+        options,
+        projectConfig,
+        canaryPath,
+        shuffleSeed,
+        normalizedPaths,
+        xpcshellOnly,
+        postRebuildContext,
+    });
 }

package/dist/src/commands/token-lint.js

@@ -8,15 +8,18 @@
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
+import { buildPatchQueueContext } from '../core/patch-lint.js';
+import { buildJarTargetIndex } from '../core/patch-lint-forward-registration-extended.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { collectDeclaredTokenNames, lintTokenLockstep, lintUndeclaredTokenReferences, } from '../core/token-lint.js';
 import { getTokensCssPath } from '../core/token-manager.js';
+import { buildSiblingSheetMap } from '../core/token-sibling-sheets.js';
 import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { info, intro, outro, setMachineOutputMode, setStdoutSealed, success, warn, } from '../utils/logger.js';
 import { emitMachineError, MACHINE_OUTPUT_SCHEMA_VERSION } from '../utils/machine-output.js';
-/** Token prefix and exempt names from furnace.json, with the init default. */
+/** Token prefix, exempt names and sibling sheets from furnace.json, with the init default. */
 async function loadTokenSettings(projectRoot, binaryName) {
     const fallback = { tokenPrefix: `--${binaryName}-`, exempt: new Set() };
     if (!(await furnaceConfigExists(projectRoot)))
@@ -26,6 +29,7 @@ async function loadTokenSettings(projectRoot, binaryName) {
         return {
             tokenPrefix: furnace.tokenPrefix ?? fallback.tokenPrefix,
             exempt: new Set([...(furnace.tokenAllowlist ?? []), ...(furnace.runtimeVariables ?? [])]),
+            siblingSheets: furnace.tokenSiblingSheets,
         };
     }
     catch (error) {
@@ -41,7 +45,7 @@ async function collectTokenLint(projectRoot) {
     if (!(await pathExists(tokensFile))) {
         throw new GeneralError(`Token CSS file not found: ${tokensCssPath}. Run "fireforge furnace init" to seed it.`);
     }
-    const { tokenPrefix, exempt } = await loadTokenSettings(projectRoot, config.binaryName);
+    const { tokenPrefix, exempt, siblingSheets } = await loadTokenSettings(projectRoot, config.binaryName);
     const tokensCss = await readText(tokensFile);
     const lines = tokensCss.split('\n');
     const declared = collectDeclaredTokenNames(lines);
@@ -52,19 +56,55 @@ async function collectTokenLint(projectRoot) {
     // Every CSS file the patch queue touches: the fork's own stylesheets and
     // the upstream ones it edits.
     const manifest = await loadPatchesManifest(paths.patches);
-    const cssFiles = [
-        ...new Set((manifest?.patches ?? []).flatMap((patch) => patch.filesAffected.filter((file) => file.endsWith('.css') && file !== tokensCssPath))),
-    ].sort();
+    const touched = [...new Set((manifest?.patches ?? []).flatMap((patch) => patch.filesAffected))];
+    const cssFiles = touched.filter((file) => file.endsWith('.css') && file !== tokensCssPath).sort();
+    const contents = await readEngineFiles(paths.engine, touched.filter((file) => LINKING_FILE.test(file)));
+    const siblings = buildSiblingSheetMap({
+        documents: contents,
+        jarTargets: buildJarTargetIndex((await buildPatchQueueContext(paths.patches)).entries),
+        sheets: cssFiles,
+        explicit: siblingSheets,
+    });
     let filesScanned = 1;
     for (const file of cssFiles) {
-        const absolute = join(paths.engine, file);
-        if (!(await pathExists(absolute)))
+        const css = contents.get(file);
+        if (css === undefined)
             continue;
         filesScanned++;
-        findings.push(...lintUndeclaredTokenReferences(file, await readText(absolute), tokenPrefix, declared, exempt));
+        findings.push(...lintUndeclaredTokenReferences(file, css, tokenPrefix, await withSiblingDeclarations(paths.engine, declared, siblings.get(file), contents), exempt));
     }
     return { tokensCssPath, tokenPrefix, filesScanned, findings };
 }
+/** Files whose content can link a stylesheet: markup, scripts, and sheets (`@import`). */
+const LINKING_FILE = /\.(?:css|xhtml|html|xml|mjs|js)$/;
+/** Reads the engine files that exist, keyed by engine-relative path. */
+async function readEngineFiles(engineDir, files) {
+    const contents = new Map();
+    for (const file of files) {
+        const absolute = join(engineDir, file);
+        if (await pathExists(absolute))
+            contents.set(file, await readText(absolute));
+    }
+    return contents;
+}
+/** The tokens CSS declarations plus every declaration of a sheet's siblings. */
+async function withSiblingDeclarations(engineDir, declared, siblings, contents) {
+    if (siblings === undefined || siblings.size === 0)
+        return declared;
+    const merged = new Set(declared);
+    for (const sibling of siblings) {
+        if (!contents.has(sibling)) {
+            const absolute = join(engineDir, sibling);
+            if (!(await pathExists(absolute)))
+                continue;
+            contents.set(sibling, await readText(absolute));
+        }
+        const css = contents.get(sibling) ?? '';
+        for (const name of collectDeclaredTokenNames(css.split('\n')))
+            merged.add(name);
+    }
+    return merged;
+}
 function failureMessage(count) {
     return `token lint found ${String(count)} finding(s).`;
 }