@hominis/fireforge 0.50.0 → 0.51.0

package/dist/src/commands/re-export.js

@@ -19,7 +19,7 @@ import { applyReExportFilesPositionalFolding, validateReExportOptionCombinations
 import { validateExpectedRemovals } from './re-export-removed.js';
 import { normalizeEngineRelativeInput, normalizeScanFiles } from './re-export-scan.js';
 import { assignScanFileOwners, scanOptionsForPatch } from './re-export-scan-owner.js';
-import { reExportSinglePatchWithIndexLockRetry } from './re-export-single.js';
+import { reExportSinglePatchWithIndexLockRetry, } from './re-export-single.js';
 import { formatReExportRunSummary } from './re-export-summary.js';
 async function resolveSelectedPatches(patches, options, manifest) {
     if (options.all) {
@@ -59,6 +59,27 @@ async function resolveSelectedPatches(patches, options, manifest) {
     const selectedFilenames = selected;
     return manifest.patches.filter((p) => selectedFilenames.includes(p.filename));
 }
+/** Refreshes each selected patch in turn, collecting which wrote and which failed. */
+async function reExportEach(args) {
+    const { selectedPatches, options, scanAssignments, progress, startedAt, shared } = args;
+    const written = [];
+    const failed = [];
+    for (const [index, patch] of selectedPatches.entries()) {
+        const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
+        progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
+        try {
+            if (await reExportSinglePatchWithIndexLockRetry({ ...shared, patch, options: patchOptions })) {
+                written.push(patch.filename);
+            }
+        }
+        catch (error) {
+            failed.push(patch.filename);
+            warn(`Failed to re-export ${patch.filename}`);
+            warn(toError(error).message);
+        }
+    }
+    return { written, failed };
+}
 /**
  * Runs the re-export command to regenerate existing patches from current engine state.
  * @param projectRoot - Root directory of the project
@@ -105,7 +126,7 @@ export async function reExportCommand(projectRoot, patches, options) {
         outro('Nothing to re-export');
         return;
     }
-    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options);
+    const expectedRemovals = await validateExpectedRemovals(paths, selectedPatches, options, manifest.patches);
     if (expectedRemovals.length > 0)
         options = { ...options, expectRemoved: expectedRemovals };
     if (scanFilesByPatch !== undefined) {
@@ -125,7 +146,7 @@ export async function reExportCommand(projectRoot, patches, options) {
     // we write anything.
     if (options.files !== undefined) {
         const filesConfig = await loadConfig(projectRoot);
-        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig)));
+        await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportFilesInPlace(paths, selectedPatches, options, filesConfig), { patches: selectedPatches }));
         return;
     }
     const config = await loadConfig(projectRoot);
@@ -139,38 +160,18 @@ export async function reExportCommand(projectRoot, patches, options) {
     // reports includes it.
     const startedAt = Date.now();
     const lintCtx = await buildReExportLintContext(projectRoot, paths, config, options.noCache === true, new Set(selectedPatches.map((patch) => patch.filename)));
-    let reExported = 0;
-    const reExportedFilenames = [];
-    const failedFilenames = [];
     const progress = spinner('Preparing re-export...');
-    await withDryRunReExportLock(paths.fireforgeDir, isDryRun, async () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, async () => {
-        for (const [index, patch] of selectedPatches.entries()) {
-            const patchOptions = scanOptionsForPatch(options, patch.filename, scanAssignments);
-            progress.message(`Re-exporting ${index + 1}/${selectedPatches.length}: ${patch.filename} (${patch.filesAffected.length} file(s), ${elapsedSince(startedAt)} elapsed)...`);
-            try {
-                const exported = await reExportSinglePatchWithIndexLockRetry({
-                    patch,
-                    paths,
-                    manifest,
-                    options: patchOptions,
-                    isDryRun,
-                    config,
-                    adjacentCtx,
-                    driftCtx,
-                    lintCtx,
-                });
-                if (exported) {
-                    reExported++;
-                    reExportedFilenames.push(patch.filename);
-                }
-            }
-            catch (error) {
-                failedFilenames.push(patch.filename);
-                warn(`Failed to re-export ${patch.filename}`);
-                warn(toError(error).message);
-            }
-        }
-    }));
+    const outcome = await withDryRunReExportLock(paths.fireforgeDir, isDryRun, () => withDryRunPurityGuard(paths.engine, paths.patches, isDryRun, () => reExportEach({
+        selectedPatches,
+        options,
+        scanAssignments,
+        progress,
+        startedAt,
+        shared: { paths, manifest, isDryRun, config, adjacentCtx, driftCtx, lintCtx },
+    }), { patches: selectedPatches }));
+    const reExportedFilenames = outcome.written;
+    const failedFilenames = outcome.failed;
+    const reExported = reExportedFilenames.length;
     await finishReExportLint(lintCtx);
     warnUnseenExpectedDrift(driftCtx);
     warnUnseenApprovedUnmanaged(adjacentCtx);

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

@@ -16,6 +16,7 @@ import type { BuildPreparation } from '../core/build-prepare.js';
  *
  * @param projectRoot - Root directory of the project
  * @param preparation - Result of `prepareBuildEnvironment`
- * @param skipped - True under `--no-furnace-apply`
+ * @param skipped - True under `--no-furnace-apply` / `--furnace-apply none`
+ * @param unreached - Components `--furnace-apply reached` left out
  */
-export declare function reportPreTestFurnace(projectRoot: string, preparation: BuildPreparation, skipped: boolean): Promise<void>;
+export declare function reportPreTestFurnace(projectRoot: string, preparation: BuildPreparation, skipped: boolean, unreached?: readonly string[]): Promise<void>;

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

@@ -20,9 +20,10 @@ import { setVerdictRunAttribute } from './test-verdict.js';
  *
  * @param projectRoot - Root directory of the project
  * @param preparation - Result of `prepareBuildEnvironment`
- * @param skipped - True under `--no-furnace-apply`
+ * @param skipped - True under `--no-furnace-apply` / `--furnace-apply none`
+ * @param unreached - Components `--furnace-apply reached` left out
  */
-export async function reportPreTestFurnace(projectRoot, preparation, skipped) {
+export async function reportPreTestFurnace(projectRoot, preparation, skipped, unreached) {
     if (skipped) {
         setVerdictRunAttribute('furnace-apply', 'skipped');
         let pending = [];
@@ -37,6 +38,11 @@ export async function reportPreTestFurnace(projectRoot, preparation, skipped) {
             : 'Furnace apply skipped (--no-furnace-apply): engine/ is packaged as it stands.');
         return;
     }
+    if (unreached !== undefined && unreached.length > 0) {
+        setVerdictRunAttribute('furnace-skipped', unreached.join(','));
+        notice(`--furnace-apply reached: ${unreached.length} component(s) with undeployed components/ ` +
+            `edits that no requested test reaches are NOT in this build: ${unreached.join(', ')}.`);
+    }
     const applied = preparation.furnaceAppliedNames ?? [];
     if (applied.length === 0)
         return;

package/dist/src/commands/test-build-phase.js

@@ -16,6 +16,7 @@ import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, spinner, verbose } from '../utils/logger.js';
 import { reportPreTestFurnace } from './test-build-furnace.js';
+import { partitionReachedComponents, resolveFurnaceApplyMode } from './test-furnace-reach.js';
 import { reportBuildOnlyCompletion } from './test-modes.js';
 import { enforceStaleBuildGate, enforceStaticComponentsGate } from './test-stale-gate.js';
 import { emitPassVerdict } from './test-verdict.js';
@@ -26,7 +27,7 @@ import { emitPassVerdict } from './test-verdict.js';
  * @param options - See {@link RunPreTestBuildOptions}
  */
 async function runPreTestBuild(options) {
-    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, skipFurnaceApply, } = options;
+    const { projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage, refuseUnexportedDrift, extend, furnace, } = options;
     await withBuildLock(projectRoot, async () => {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
@@ -46,9 +47,10 @@ async function runPreTestBuild(options) {
         const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
             previousBaseline,
             refuseUnexportedDrift,
-            skipFurnaceApply,
+            skipFurnaceApply: furnace.skip,
+            furnaceComponents: furnace.only,
         });
-        await reportPreTestFurnace(projectRoot, preparation, skipFurnaceApply);
+        await reportPreTestFurnace(projectRoot, preparation, furnace.skip, furnace.unreached);
         // Which earlier claims this scoped build keeps, per staged path. The
         // mozconfig half can only be checked once prepareBuildEnvironment has
         // regenerated engine/mozconfig (the file this build will configure
@@ -161,13 +163,28 @@ function assertRefuseUnexportedDriftUsage(options) {
         return;
     throw new InvalidArgumentError('--refuse-unexported-drift requires --build or --build-only: it guards the pre-test build, and this run dispatches none.', '--refuse-unexported-drift');
 }
-/** Refuses `--no-furnace-apply` on a run that dispatches no build, for the same reason. */
+/** Refuses `--no-furnace-apply`/`--furnace-apply` on a run that dispatches no build, for the same reason. */
 function assertNoFurnaceApplyUsage(options) {
-    if (options.furnaceApply !== false)
+    if (options.furnaceApply === undefined || options.furnaceApply === true)
         return;
     if (options.build === true || options.buildOnly === true)
         return;
-    throw new InvalidArgumentError("--no-furnace-apply requires --build or --build-only: it skips the pre-test build's Furnace apply, and this run dispatches no build.", '--no-furnace-apply');
+    const flag = options.furnaceApply === false ? '--no-furnace-apply' : '--furnace-apply';
+    throw new InvalidArgumentError(`${flag} requires --build or --build-only: it shapes the pre-test build's Furnace apply, and this run dispatches no build.`, flag);
+}
+/**
+ * The Furnace part of a pre-test build: skip the apply, apply everything,
+ * or apply only the components the request reaches (and name the rest).
+ */
+async function planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths) {
+    const mode = resolveFurnaceApplyMode(options, projectConfig);
+    if (mode === 'none')
+        return { skip: true };
+    // A path-less build packages the whole suite, which reaches everything.
+    if (mode === 'all' || normalizedPaths.length === 0)
+        return { skip: false };
+    const { reached, skipped } = await partitionReachedComponents(projectRoot, paths.engine, normalizedPaths);
+    return { skip: false, only: reached, unreached: skipped };
 }
 /** Renders the `recordedBy` invocation string surfaced by `status --test-coverage`. */
 function describeBuildInvocation(extending, coverage) {
@@ -218,7 +235,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             testPackagingCoverage: coverage,
             refuseUnexportedDrift: options.refuseUnexportedDrift === true,
             extend: extending ? { requestedPaths: normalizedPaths } : undefined,
-            skipFurnaceApply: options.furnaceApply === false,
+            furnace: await planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths),
         });
         info('');
         if (options.buildOnly) {

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

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { findUnownedSupportHeads, formatUnownedSupportHeadNotice, } from '../core/checkjs-support-heads.js';
+import { buildPatchQueueContext } from '../core/patch-lint.js';
 import { runCheckJsTestFilesGrouped } from '../core/patch-lint-checkjs.js';
-import { isTestScriptFile } from '../core/patch-lint-ownership.js';
+import { isTestScriptFile, resolvableModulesForTests } from '../core/patch-lint-ownership.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { analyzeTestPathScopes } from '../core/test-path-scope.js';
 import { GeneralError } from '../errors/base.js';
@@ -24,7 +25,7 @@ export async function checkRequestedTestTypes(paths, config, requested) {
         owned.add(head.file);
         notice(`Pre-build checkJs: ${formatUnownedSupportHeadNotice(head)}`);
     }
-    const result = await runCheckJsTestFilesGrouped(paths.engine, owned, config.patchLint, paths.root, selected);
+    const result = await runCheckJsTestFilesGrouped(paths.engine, owned, config.patchLint, paths.root, selected, resolvableModulesForTests(await buildPatchQueueContext(paths.patches)));
     const issues = [...result.global, ...[...result.byFile.values()].flat()];
     for (const issue of issues)
         notice(`Pre-build checkJs: ${issue.file}: ${issue.message}`);

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

@@ -0,0 +1,39 @@
+/**
+ * The dispatch half of one `fireforge test` run, split out of `test.ts`:
+ * the engine-generation guard around the harness, and the choice between
+ * one combined invocation, per-argument shards, `--shard-size` chunks and
+ * `--jobs` parallel harness instances.
+ */
+import type { PostRebuildFailureContext } from '../core/test-harness-output.js';
+import type { TestOptions } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type TestRunContext } from './test-run.js';
+import { type ShardGroup } from './test-shards.js';
+/** Everything the dispatch half needs from the run body. */
+export interface TestDispatchInputs {
+    engineDir: string;
+    runCtx: TestRunContext;
+    dispatchGroups: ShardGroup[];
+    options: TestOptions;
+    projectConfig: FireForgeConfig;
+    canaryPath: string | undefined;
+    shuffleSeed: number | undefined;
+    normalizedPaths: string[];
+    xpcshellOnly: boolean;
+    postRebuildContext: PostRebuildFailureContext | undefined;
+}
+/**
+ * Refuses `--jobs`/`--shard-size` shapes that cannot work, before any lock
+ * or build: both need explicit paths and a real dispatch, and parallel
+ * instances cannot share one operator-pinned Marionette port.
+ *
+ * @param testPaths - Requested paths
+ * @param options - Parsed options
+ */
+export declare function assertParallelTestUsage(testPaths: readonly string[], options: TestOptions): void;
+/**
+ * Runs the planned dispatch and finalizes its verdict.
+ *
+ * @param inputs - See {@link TestDispatchInputs}
+ */
+export declare function dispatchTests(inputs: TestDispatchInputs): Promise<void>;

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

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The dispatch half of one `fireforge test` run, split out of `test.ts`:
+ * the engine-generation guard around the harness, and the choice between
+ * one combined invocation, per-argument shards, `--shard-size` chunks and
+ * `--jobs` parallel harness instances.
+ */
+import { createServer } from 'node:net';
+import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
+import { autoPortsRequested } from '../core/harness-port-fallback.js';
+import { extractForwardedMarionettePort } from '../core/marionette-port.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { notice } from '../utils/logger.js';
+import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
+import { shuffleTestGroups } from './test-harness-env.js';
+import { reportCanaryOutcome } from './test-modes.js';
+import { perfGenerationTolerance, runGenerationTolerance } from './test-perf-scope.js';
+import { runTestsWithRetries } from './test-run.js';
+import { chunkShardGroups, finalizeShardedOutcome, runShardedTests, splitContiguous, } from './test-shards.js';
+import { emitFailVerdict, setVerdictRunAttribute } from './test-verdict.js';
+/**
+ * Refuses `--jobs`/`--shard-size` shapes that cannot work, before any lock
+ * or build: both need explicit paths and a real dispatch, and parallel
+ * instances cannot share one operator-pinned Marionette port.
+ *
+ * @param testPaths - Requested paths
+ * @param options - Parsed options
+ */
+export function assertParallelTestUsage(testPaths, options) {
+    const parallel = (options.jobs ?? 1) > 1;
+    const flags = [
+        ...(parallel ? ['--jobs'] : []),
+        ...(options.shardSize !== undefined ? ['--shard-size'] : []),
+    ];
+    if (flags.length === 0)
+        return;
+    const flag = flags.join('/');
+    if (testPaths.length === 0 || options.canary !== undefined || options.auto === true) {
+        throw new InvalidArgumentError(`${flag} splits explicit test paths, so it needs paths and cannot be combined with --canary or --auto.`, flags[0]);
+    }
+    if (options.buildOnly === true) {
+        throw new InvalidArgumentError(`${flag} shapes a dispatch; --build-only runs none.`, flags[0]);
+    }
+    if (parallel &&
+        (options.marionettePort !== undefined ||
+            extractForwardedMarionettePort(options.machArg ?? []) !== undefined)) {
+        throw new InvalidArgumentError('--jobs gives every harness instance its own Marionette port, so it cannot be combined with a pinned --marionette-port (or a forwarded one).', '--jobs');
+    }
+}
+/**
+ * Verifies `engine/` did not change under the run in a way the run could
+ * see 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, inputs) {
+    try {
+        await assertEngineGenerationUnchanged(engineDir, before, inputs.perfSamples === undefined
+            ? runGenerationTolerance(engineDir, inputs.requested, (count) => {
+                setVerdictRunAttribute('drift-tolerated', String(count));
+            })
+            : perfGenerationTolerance(engineDir));
+        if (inputs.powerChanged === true)
+            throw new GeneralError('Perf power source changed during the run; repeat this sitting on a stable power source.');
+    }
+    catch (error) {
+        emitFailVerdict('inconclusive');
+        throw error;
+    }
+}
+/** A free TCP port on the loopback interface, for one harness instance. */
+async function allocateLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            server.close(() => {
+                resolve(port);
+            });
+        });
+    });
+}
+/**
+ * The context for `--jobs` instance `index` (0-based): its own output
+ * prefix, and from the second instance on its own Marionette port, so
+ * browsers started at the same moment never race for 2828. The mochitest
+ * server ports are left to the engine harness's busy-port fallback, which
+ * `--jobs` requires (auto ports).
+ */
+async function instanceContext(base, index, xpcshellOnly) {
+    const ctx = { ...base, outputPrefix: `[job ${index + 1}] ` };
+    if (index === 0 || xpcshellOnly)
+        return ctx;
+    const port = await allocateLoopbackPort();
+    return {
+        ...ctx,
+        baseExtraArgs: [
+            ...base.baseExtraArgs,
+            `--setpref=marionette.port=${port}`,
+            `--marionette=127.0.0.1:${port}`,
+        ],
+    };
+}
+/** The shards to run, or undefined for one combined invocation. */
+function planShards(inputs) {
+    const { dispatchGroups, options, canaryPath, shuffleSeed } = inputs;
+    if (canaryPath !== undefined)
+        return undefined;
+    const ordered = shuffleSeed === undefined ? dispatchGroups : shuffleTestGroups(dispatchGroups, shuffleSeed);
+    if (options.shardSize !== undefined)
+        return chunkShardGroups(ordered, options.shardSize);
+    const jobs = options.jobs ?? 1;
+    if (jobs > 1 && (options.shard === false || ordered.length === 1)) {
+        return splitContiguous(ordered.flatMap((group) => group.paths), jobs);
+    }
+    if (ordered.length > 1 && options.shard !== false)
+        return ordered;
+    return undefined;
+}
+/**
+ * Runs the planned dispatch and finalizes its verdict.
+ *
+ * @param inputs - See {@link TestDispatchInputs}
+ */
+export async function dispatchTests(inputs) {
+    const { engineDir, runCtx, options, projectConfig, normalizedPaths } = inputs;
+    const jobs = options.jobs ?? 1;
+    if (jobs > 1 && !inputs.xpcshellOnly && !autoPortsRequested(options, projectConfig)) {
+        throw new InvalidArgumentError('--jobs runs several browsers at once, which needs auto ports (--auto-ports or ' +
+            'test.mochitestPorts: "auto") so the harness can move each instance to free server ports.', '--jobs');
+    }
+    const guard = {
+        perfSamples: options.perfSamples,
+        requested: normalizedPaths,
+    };
+    const shards = planShards(inputs);
+    if (shards !== undefined) {
+        notice(describeSharding(shards.length, options, jobs));
+        const base = jobs > 1 ? await instanceContext(runCtx, 0, inputs.xpcshellOnly) : runCtx;
+        if (jobs > 1)
+            setVerdictRunAttribute('jobs', String(jobs));
+        const generationBefore = await snapshotEngineGeneration(engineDir);
+        let summary;
+        try {
+            summary = await runShardedTests(base, shards, (outcome, label) => diagnoseShardOutcome(outcome, label, projectConfig.binaryName, inputs.postRebuildContext), {
+                jobs,
+                contextFor: (index) => instanceContext(runCtx, index, inputs.xpcshellOnly),
+                perFile: options.shardSize !== undefined,
+            });
+        }
+        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(engineDir, generationBefore, {
+                ...guard,
+                ...(base.powerChanged === true || runCtx.powerChanged === true
+                    ? { powerChanged: true }
+                    : {}),
+            });
+        }
+        finalizeShardedOutcome(summary);
+        return;
+    }
+    const combinedDispatchPaths = inputs.dispatchGroups.flatMap((group) => group.paths);
+    let outcome;
+    const generationBefore = await snapshotEngineGeneration(engineDir);
+    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(engineDir, generationBefore, {
+            ...guard,
+            ...(runCtx.powerChanged === true ? { powerChanged: true } : {}),
+        });
+    }
+    if (inputs.canaryPath !== undefined) {
+        reportCanaryOutcome(outcome);
+        return;
+    }
+    finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, inputs.postRebuildContext, options.headless === true);
+}
+/**
+ * The sharding notice. 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.
+ */
+function describeSharding(count, options, jobs) {
+    const instances = jobs > 1 ? ` on ${jobs} harness instances at once (each with its own ports and profile)` : '';
+    if (options.shardSize !== undefined) {
+        return (`Sharding: running ${count} chunk(s) of up to ${options.shardSize} file(s)${instances}, ` +
+            'each chunk one mach invocation with a browser restart between files; results are judged ' +
+            'per file from the structured log.');
+    }
+    if (jobs > 1 && options.shard === false) {
+        return (`Sharding: --jobs splits the combined request into ${count} contiguous chunk(s) in order` +
+            `${instances}. Cross-chunk state is NOT exercised.`);
+    }
+    return (`Sharding: running ${count} test path arguments in isolated browser instances${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.');
+}

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