@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/test-browser-preflight.js

@@ -1,9 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { reportOrphanedHarnessProcesses } from '../core/harness-orphans.js';
-import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
+import { deferBusyPortToHarness, resolveAutoPorts } from '../core/harness-port-fallback.js';
+import { assertMarionettePortAvailable, DEFAULT_MARIONETTE_PORT, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
-import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
+import { DEFAULT_MOCHITEST_SERVER_PORT, ensureMochitestServerPortAvailable, } from '../core/mochitest-server-port.js';
 import { waitForPreflight } from '../core/preflight-wait.js';
 import { GeneralError } from '../errors/base.js';
 import { info, outro, verbose } from '../utils/logger.js';
@@ -153,7 +154,15 @@ export async function ensureTestBrowserEnvironment(engineDir, launchablePath, xp
     // browser connect to a server that cannot serve this run's manifest,
     // which surfaces as a 370s "Ran 0 checks" stall naming nothing. xpcshell
     // does not use the httpd, so an xpcshell-only run is never blocked by it.
-    if (!xpcshellOnly) {
+    // Auto ports (opt-in) step aside for a peer's listener and let the
+    // harness's own busy-port fallback move this run; see
+    // src/core/harness-port-fallback.ts.
+    const autoPorts = xpcshellOnly
+        ? undefined
+        : await resolveAutoPorts(engineDir, options, projectConfig);
+    if (!xpcshellOnly &&
+        !(autoPorts?.serverPorts === true &&
+            (await deferBusyPortToHarness(DEFAULT_MOCHITEST_SERVER_PORT, 'Mochitest server', engineDir)))) {
         await waitForPreflight(() => ensureMochitestServerPortAvailable(undefined, {
             engineDir,
             killStaleServer: options.killStaleMarionette === true,
@@ -173,6 +182,13 @@ export async function ensureTestBrowserEnvironment(engineDir, launchablePath, xp
         ? extractForwardedMarionettePort(options.machArg)
         : undefined;
     const effectivePort = options.marionettePort ?? forwardedPort;
+    // Never under --doctor: its handshake launches a browser on this port
+    // itself and would talk to the peer's browser instead.
+    if (autoPorts?.marionettePort === true &&
+        options.doctor !== true &&
+        (await deferBusyPortToHarness(effectivePort ?? DEFAULT_MARIONETTE_PORT, 'Marionette', engineDir))) {
+        return { forwardedPort, effectivePort };
+    }
     await waitForPreflight(() => ensureTestMarionettePortAvailable(effectivePort, projectConfig.binaryName, options, {
         xpcshellOnly,
         doctor: options.doctor === true,

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

@@ -0,0 +1,22 @@
+/**
+ * What a pre-test build did with Furnace components. `prepareBuildEnvironment`
+ * runs `furnace apply` over the whole `components/` tree, so a
+ * `fireforge test --build` meant to capture the committed behaviour could
+ * silently ship component edits nobody had deployed yet (another session's
+ * included), and nothing in the test output said so. The applied names now
+ * ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
+ * stands, naming the undeployed edits it left out.
+ */
+import type { BuildPreparation } from '../core/build-prepare.js';
+/**
+ * Reports the pre-test build's Furnace step: the components it deployed
+ * (notice plus `furnace-applied=<names>` on the verdict line), or, when the
+ * apply was skipped, the components whose undeployed edits this build
+ * leaves out (`furnace-apply=skipped`).
+ *
+ * @param projectRoot - Root directory of the project
+ * @param preparation - Result of `prepareBuildEnvironment`
+ * @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, unreached?: readonly string[]): Promise<void>;

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

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What a pre-test build did with Furnace components. `prepareBuildEnvironment`
+ * runs `furnace apply` over the whole `components/` tree, so a
+ * `fireforge test --build` meant to capture the committed behaviour could
+ * silently ship component edits nobody had deployed yet (another session's
+ * included), and nothing in the test output said so. The applied names now
+ * ride the verdict line, and `--no-furnace-apply` packages `engine/` as it
+ * stands, naming the undeployed edits it left out.
+ */
+import { listStaleFurnaceComponents } from '../core/furnace-staleness.js';
+import { toError } from '../utils/errors.js';
+import { notice, verbose } from '../utils/logger.js';
+import { setVerdictRunAttribute } from './test-verdict.js';
+/**
+ * Reports the pre-test build's Furnace step: the components it deployed
+ * (notice plus `furnace-applied=<names>` on the verdict line), or, when the
+ * apply was skipped, the components whose undeployed edits this build
+ * leaves out (`furnace-apply=skipped`).
+ *
+ * @param projectRoot - Root directory of the project
+ * @param preparation - Result of `prepareBuildEnvironment`
+ * @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, unreached) {
+    if (skipped) {
+        setVerdictRunAttribute('furnace-apply', 'skipped');
+        let pending = [];
+        try {
+            pending = await listStaleFurnaceComponents(projectRoot);
+        }
+        catch (error) {
+            verbose(`Furnace pending-edit probe failed: ${toError(error).message}`);
+        }
+        notice(pending.length > 0
+            ? `Furnace apply skipped (--no-furnace-apply): engine/ is packaged as it stands. ${pending.length} component(s) with undeployed components/ edits are NOT in this build: ${pending.join(', ')}.`
+            : '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;
+    setVerdictRunAttribute('furnace-applied', applied.join(','));
+    notice(`This pre-test build deployed ${applied.length} Furnace component(s) whose components/ source ` +
+        `changed since their last deploy: ${applied.join(', ')}. Those edits (another session's ` +
+        'undeployed edits included) are in the runtime under test. Pass --no-furnace-apply to ' +
+        'package engine/ as it stands, for example for a before-capture.');
+}

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

@@ -6,7 +6,7 @@
  */
 import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
-import { checkExtendCoverageAnchor, checkExtendMozconfigAnchor, formatExtendCoverageRefusal, unionTestPackagingCoverage, } from '../core/coverage-extend.js';
+import { applyMozconfigAnchor, formatCoverageRetentionNotice, formatExtendCoverageRefusal, planCoverageRetention, recordScopedCoverage, } from '../core/coverage-extend.js';
 import { hasBuildArtifacts } from '../core/mach.js';
 import { runProtectedMachBuild, withBuildLock } from '../core/mach.js';
 import { assertHealthyPartialConfig, pruneDanglingTestLinks } from '../core/objdir-maintenance.js';
@@ -15,7 +15,8 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { info, notice, spinner, verbose } from '../utils/logger.js';
-import { checkRequestedTestTypes } from './test-checkjs.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, } = 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
@@ -41,32 +42,29 @@ async function runPreTestBuild(options) {
             if (pruned > 0)
                 notice(`Pruned ${pruned} dangling _tests symlink(s).`);
         }
-        await checkRequestedTestTypes(paths, projectConfig, testPackagingCoverage === 'full' ? [] : testPackagingCoverage);
+        // The named-file checkJs pass runs before the engine lock is even
+        // requested (test-prelock.ts), so a type error refuses without a wait.
         const preparation = await prepareBuildEnvironment(projectRoot, paths, projectConfig, {
             previousBaseline,
             refuseUnexportedDrift,
+            skipFurnaceApply: furnace.skip,
+            furnaceComponents: furnace.only,
         });
-        // The mozconfig half of the --extend-coverage anchor can
-        // only be checked once prepareBuildEnvironment has regenerated
-        // engine/mozconfig (the file this build will configure with), and must
-        // still be checked before mach, so a refusal costs no build.
-        let retainCoverage = false;
-        if (testPackagingCoverage !== 'full' && previousBaseline) {
-            const anchor = await checkExtendCoverageAnchor(paths.engine, previousBaseline, testPackagingCoverage);
-            const mozconfigAnchor = await checkExtendMozconfigAnchor(paths.engine, previousBaseline);
-            retainCoverage =
-                anchor.ok && mozconfigAnchor.ok && previousBaseline.testInputFingerprints !== undefined;
-            if (extend !== undefined && (!anchor.ok || !mozconfigAnchor.ok)) {
-                throw new GeneralError(formatExtendCoverageRefusal(!anchor.ok ? anchor : mozconfigAnchor));
-            }
-            if (!retainCoverage) {
-                const old = previousBaseline.testPackagingCoverage;
-                const dropped = old === undefined || old === 'full'
-                    ? ['full coverage outside this scope']
-                    : old.filter((file) => !testPackagingCoverage.includes(file));
-                if (dropped.length)
-                    notice(`Scoped build drops previous packaging coverage: ${dropped.join(', ')}. Earlier staging inputs changed or have no complete fingerprint anchor; rebuild those paths together to retain them.`);
+        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
+        // with), and must still be checked before mach, so a refusal costs no
+        // build.
+        let plan;
+        if (testPackagingCoverage !== 'full') {
+            plan = await applyMozconfigAnchor(paths.engine, await planCoverageRetention(paths.engine, previousBaseline, testPackagingCoverage));
+            if (extend !== undefined && plan.dropped.length > 0) {
+                throw new GeneralError(formatExtendCoverageRefusal(plan.dropped));
             }
+            const retentionNotice = formatCoverageRetentionNotice(plan);
+            if (retentionNotice !== undefined)
+                notice(retentionNotice);
         }
         const buildKind = preparation.fullBuildRequired ? 'full' : 'faster';
         if (preparation.fullBuildRequired) {
@@ -103,24 +101,24 @@ async function runPreTestBuild(options) {
             // carries the static-components anchor forward, since `mach build
             // faster` does not rebake components.conf into the compiled table.
             try {
-                // Under --extend-coverage the claim is the union of the previous
-                // record and this build's paths, and the static-components anchor
-                // is always carried forward: that union can evaluate to 'full'
-                // while the build behind it was a scoped `mach build faster` that
+                // A scoped claim records this build's paths plus every earlier path
+                // the plan kept, each with its own staging-input anchor. When it
+                // kept anything the static-components anchor is carried forward
+                // explicitly: a kept full claim is still a `mach build faster` that
                 // did not rebake the compiled table.
-                const recordedCoverage = retainCoverage
-                    ? unionTestPackagingCoverage(previousBaseline?.testPackagingCoverage, testPackagingCoverage === 'full' ? [] : testPackagingCoverage)
-                    : testPackagingCoverage;
+                const recorded = plan === undefined || testPackagingCoverage === 'full'
+                    ? { testPackagingCoverage }
+                    : await recordScopedCoverage(paths.engine, plan, testPackagingCoverage);
                 await writeBuildBaseline({
                     projectRoot,
                     engineDir: paths.engine,
                     binaryName: projectConfig.binaryName,
-                    testPackagingCoverage: recordedCoverage,
+                    ...recorded,
                     previousBaseline,
                     recordedBy: describeBuildInvocation(extend !== undefined, testPackagingCoverage),
                     staticComponentsHandling: preparation.fullBuildRequired
                         ? 'refresh'
-                        : retainCoverage
+                        : plan !== undefined && (plan.keepFull || Object.keys(plan.retained).length > 0)
                             ? 'carry-forward'
                             : 'auto',
                     buildKind,
@@ -138,15 +136,15 @@ async function runPreTestBuild(options) {
     });
 }
 /**
- * `--extend-coverage` only means something for a scoped build: it unions
- * this build's paths onto the recorded claim. Without `--build`/
+ * `--extend-coverage` only means something for a scoped build: it refuses
+ * a build that would drop an earlier claim. Without `--build`/
  * `--build-only` there is no build to extend from, and a path-less build
  * records `'full'`, which already covers everything. Refusing both is more
  * honest than silently ignoring the flag.
  */
 function assertExtendCoverageUsage(options, normalizedPaths) {
     if (options.build !== true && options.buildOnly !== true) {
-        throw new InvalidArgumentError('--extend-coverage requires --build or --build-only: it unions the paths a build packages onto the recorded coverage claim.', '--extend-coverage');
+        throw new InvalidArgumentError('--extend-coverage requires --build or --build-only: it guards the coverage claim a build records.', '--extend-coverage');
     }
     if (normalizedPaths.length === 0) {
         throw new InvalidArgumentError('--extend-coverage requires explicit test paths: a path-less build records full coverage, which already covers every path.', '--extend-coverage');
@@ -165,6 +163,29 @@ 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`/`--furnace-apply` on a run that dispatches no build, for the same reason. */
+function assertNoFurnaceApplyUsage(options) {
+    if (options.furnaceApply === undefined || options.furnaceApply === true)
+        return;
+    if (options.build === true || options.buildOnly === true)
+        return;
+    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) {
     const extendFlag = extending ? ' --extend-coverage' : '';
@@ -186,6 +207,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
         assertExtendCoverageUsage(options, normalizedPaths);
     }
     assertRefuseUnexportedDriftUsage(options);
+    assertNoFurnaceApplyUsage(options);
     if (options.build || options.buildOnly) {
         // A path-less `test --build` runs (and packages for) the full suite.
         // A scoped invocation only vouches for the requested paths. A scoped
@@ -197,11 +219,11 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             const previousBaseline = await readBuildBaseline(projectRoot);
             await enforceStaticComponentsGate(paths.engine, previousBaseline, options);
             if (extending) {
-                // Head/fingerprint half of the anchor, before the build lock: a
-                // refusal here costs neither build time nor the lock.
-                const anchor = await checkExtendCoverageAnchor(paths.engine, previousBaseline, normalizedPaths);
-                if (!anchor.ok) {
-                    throw new GeneralError(formatExtendCoverageRefusal(anchor));
+                // Staging-input half of the plan, before the build lock: a refusal
+                // here costs neither build time nor the lock.
+                const plan = await planCoverageRetention(paths.engine, previousBaseline, normalizedPaths);
+                if (plan.dropped.length > 0) {
+                    throw new GeneralError(formatExtendCoverageRefusal(plan.dropped));
                 }
             }
         }
@@ -213,6 +235,7 @@ export async function runTestBuildPhase(projectRoot, paths, projectConfig, harne
             testPackagingCoverage: coverage,
             refuseUnexportedDrift: options.refuseUnexportedDrift === true,
             extend: extending ? { requestedPaths: normalizedPaths } : undefined,
+            furnace: await planPreTestFurnace(projectRoot, paths, projectConfig, options, normalizedPaths),
         });
         info('');
         if (options.buildOnly) {

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

@@ -1,6 +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';
@@ -17,7 +19,13 @@ export async function checkRequestedTestTypes(paths, config, requested) {
     const selected = new Set(scopes.flatMap((scope) => scope.dispatchPaths.filter(isTestScriptFile)));
     for (const file of selected)
         owned.add(file);
-    const result = await runCheckJsTestFilesGrouped(paths.engine, owned, config.patchLint, paths.root, selected);
+    // A support head a named test brings into scope joins the pass even
+    // before any patch owns it, or every name it declares reads as undefined.
+    for (const head of await findUnownedSupportHeads(paths.engine, selected, owned)) {
+        owned.add(head.file);
+        notice(`Pre-build checkJs: ${formatUnownedSupportHeadNotice(head)}`);
+    }
+    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-diagnose.js

@@ -11,6 +11,7 @@ import { getActiveRunLogPath } from '../core/run-log.js';
 import { describeChangedPrefNoise } from '../core/test-changed-prefs.js';
 import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, buildSilentSegfaultMessage, headedNoOutputTimeoutHint, isSilentSegfault, } from '../core/test-harness-crash.js';
 import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
+import { buildIncompleteRunMessage } from '../core/test-run-completeness.js';
 import { GeneralError } from '../errors/base.js';
 import { TestFailureError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -249,6 +250,9 @@ function applySingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuild
         }
         return;
     }
+    if (outcome.verdict.incomplete !== undefined) {
+        throw new TestFailureError(buildIncompleteRunMessage(outcome.verdict.incomplete), 'mach test', formatFailureBlocks(outcome.verdict.realFailureBlocks), getActiveRunLogPath());
+    }
     if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
         // The silent false green: exit 0 plus a "Passed: 0"-style summary with
         // zero TEST-START lines must fail rather than pass.
@@ -282,6 +286,9 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
     if (outcome.verdict.kind === 'no-tests' && outcome.result.exitCode === 0) {
         return buildNoTestsRanMessage(0, [path]);
     }
+    if (outcome.verdict.incomplete !== undefined) {
+        return buildIncompleteRunMessage(outcome.verdict.incomplete);
+    }
     if (outcome.verdict.greenSummaryRejected) {
         return buildGreenSummaryRejectedMessage(outcome.verdict.greenSummaryRejected, outcome.result.exitCode);
     }

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