@hominis/fireforge 0.37.0 → 0.39.0

package/dist/src/commands/source.js

@@ -4,7 +4,7 @@ import { configExists, loadRawConfigDocument, validateConfig, withConfigFileLock
 import { resolveArchive } from '../core/firefox-archive.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { info, intro, outro, success } from '../utils/logger.js';
-import { isValidFirefoxProduct } from '../utils/validation.js';
+import { isValidFirefoxCandidate, isValidFirefoxProduct } from '../utils/validation.js';
 const SOURCE_PRODUCTS = [
     'firefox',
     'firefox-esr',
@@ -27,6 +27,12 @@ function parseSourceProduct(product) {
     }
     throw new InvalidArgumentError(`--product must be one of: ${SOURCE_PRODUCTS.join(', ')}`, '--product');
 }
+function parseSourceCandidate(candidate) {
+    if (isValidFirefoxCandidate(candidate)) {
+        return candidate;
+    }
+    throw new InvalidArgumentError(`--candidate must look like "buildN" (e.g. "build2"), got "${candidate}"`, '--candidate');
+}
 /**
  * Atomically updates the Firefox source tuple in fireforge.json.
  */
@@ -38,6 +44,9 @@ export async function sourceSetCommand(projectRoot, options) {
     if (options.sha256 !== undefined && options.clearSha256 === true) {
         throw new InvalidArgumentError('--sha256 cannot be combined with --clear-sha256', '--sha256');
     }
+    if (options.candidate !== undefined && options.clearCandidate === true) {
+        throw new InvalidArgumentError('--candidate cannot be combined with --clear-candidate', '--candidate');
+    }
     const written = await withConfigFileLock(projectRoot, async () => {
         const raw = await loadRawConfigDocument(projectRoot);
         const updated = cloneRawConfig(raw);
@@ -50,6 +59,12 @@ export async function sourceSetCommand(projectRoot, options) {
         else if (options.sha256 !== undefined) {
             firefox['sha256'] = options.sha256;
         }
+        if (options.clearCandidate === true) {
+            delete firefox['candidate'];
+        }
+        else if (options.candidate !== undefined) {
+            firefox['candidate'] = options.candidate;
+        }
         updated['firefox'] = firefox;
         const validated = validateConfig(updated);
         if (validated.firefox.sha256 !== undefined) {
@@ -58,7 +73,7 @@ export async function sourceSetCommand(projectRoot, options) {
         await writeConfigDocument(projectRoot, updated);
         return validated.firefox;
     });
-    const archive = resolveArchive(written.version, written.product);
+    const archive = resolveArchive(written.version, written.product, written.candidate);
     success(`Set firefox.version = ${written.version}`);
     success(`Set firefox.product = ${written.product}`);
     success(`Resolved source URL: ${archive.url}`);
@@ -68,6 +83,12 @@ export async function sourceSetCommand(projectRoot, options) {
     else if (options.clearSha256 === true) {
         info('Cleared firefox.sha256');
     }
+    if (written.candidate !== undefined) {
+        success(`Set firefox.candidate = ${written.candidate}`);
+    }
+    else if (options.clearCandidate === true) {
+        info('Cleared firefox.candidate');
+    }
     outro('');
 }
 /** Registers the source command on the CLI program. */
@@ -82,13 +103,17 @@ export function registerSource(program, { getProjectRoot, withErrorHandling }) {
         .makeOptionMandatory())
         .option('--sha256 <hash>', 'Pinned SHA-256 for the resolved source archive')
         .option('--clear-sha256', 'Clear any existing pinned SHA-256')
+        .option('--candidate <buildN>', 'Release-candidate build directory (e.g. "build2")', parseSourceCandidate)
+        .option('--clear-candidate', 'Clear any existing release-candidate build directory')
         .action(withErrorHandling(async (options) => {
-        const { product, version, sha256, clearSha256 } = options;
+        const { product, version, sha256, clearSha256, candidate, clearCandidate } = options;
         await sourceSetCommand(getProjectRoot(), {
             version,
             product: parseSourceProduct(product),
             ...(sha256 !== undefined ? { sha256 } : {}),
             ...(clearSha256 !== undefined ? { clearSha256 } : {}),
+            ...(candidate !== undefined ? { candidate } : {}),
+            ...(clearCandidate !== undefined ? { clearCandidate } : {}),
         });
     }));
 }

package/dist/src/commands/status-output.d.ts

@@ -1,3 +1,4 @@
+import type { BuildBaseline } from '../core/build-baseline-types.js';
 import type { ClassifiedFile } from '../core/status-classify.js';
 export interface ClassifiedBuckets {
     conflict: ClassifiedFile[];
@@ -11,3 +12,11 @@ export interface ClassifiedBuckets {
 export declare function renderUnmanagedOnly(unmanagedFiles: ClassifiedFile[], totalModified: number, projectRoot: string, binaryName: string): Promise<void>;
 /** Renders the default classified status buckets. */
 export declare function renderDefaultStatus(totalModified: number, buckets: ClassifiedBuckets, projectRoot: string, binaryName: string): Promise<void>;
+/**
+ * Renders `fireforge status --test-coverage` (FORGE F11): a READ-ONLY view
+ * of the last build baseline's test-packaging coverage. Before this
+ * existed, the only way to learn the recorded coverage scope — which
+ * concurrent sessions sharing one engine tree overwrite constantly — was
+ * to trip the out-of-coverage refusal on a real test run.
+ */
+export declare function renderTestCoverageStatus(baseline: BuildBaseline | undefined): void;

package/dist/src/commands/status-output.js

@@ -1,4 +1,3 @@
-// SPDX-License-Identifier: EUPL-1.2
 import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
 import { getPrimaryStatusCode } from '../core/status-classify.js';
 import { GeneralError } from '../errors/base.js';
@@ -182,3 +181,36 @@ export async function renderDefaultStatus(totalModified, buckets, projectRoot, b
         .map((section) => `${section.files.length} ${section.label}`);
     outro(parts.join(', '));
 }
+/**
+ * Renders `fireforge status --test-coverage` (FORGE F11): a READ-ONLY view
+ * of the last build baseline's test-packaging coverage. Before this
+ * existed, the only way to learn the recorded coverage scope — which
+ * concurrent sessions sharing one engine tree overwrite constantly — was
+ * to trip the out-of-coverage refusal on a real test run.
+ */
+export function renderTestCoverageStatus(baseline) {
+    if (baseline === undefined) {
+        info('No build baseline recorded (.fireforge/last-build.json missing or unreadable).\n' +
+            'Run "fireforge build" to record one.');
+        outro('No test-packaging coverage recorded');
+        return;
+    }
+    info(`Last build: ${baseline.builtAt}  (binary: ${baseline.binaryName}, ` +
+        `engine HEAD: ${baseline.engineHeadSha || '(unborn)'})`);
+    info(`Recorded by: ${baseline.recordedBy ?? 'unknown'}`);
+    const coverage = baseline.testPackagingCoverage;
+    if (coverage === undefined) {
+        info('Test packaging coverage: full (implicit — baseline predates coverage recording)');
+        outro('Coverage: full');
+        return;
+    }
+    if (coverage === 'full') {
+        info('Test packaging coverage: full');
+        outro('Coverage: full');
+        return;
+    }
+    const list = coverage.map((path) => `  - ${path}`).join('\n');
+    info(`Test packaging coverage: scoped to ${String(coverage.length)} path(s):\n${list}\n` +
+        'A "fireforge test" over paths outside this list will be refused as uncovered.');
+    outro(`Coverage: scoped (${String(coverage.length)} paths)`);
+}

package/dist/src/commands/status.js

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { Command } from 'commander';
+import { readBuildBaseline } from '../core/build-baseline.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
@@ -12,7 +13,7 @@ import { CommandError, GeneralError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
-import { renderDefaultStatus, renderUnmanagedOnly, } from './status-output.js';
+import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
  * Each line is: STATUS<tab>FILE
@@ -170,13 +171,25 @@ export async function statusCommand(projectRoot, options = {}) {
         setMachineOutputMode(true);
     }
     try {
-        const modeCount = [options.raw, options.unmanaged, options.ownership, options.json].filter((v) => v === true).length;
+        const modeCount = [
+            options.raw,
+            options.unmanaged,
+            options.ownership,
+            options.testCoverage,
+            options.json,
+        ].filter((v) => v === true).length;
         if (modeCount > 1) {
-            throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, and --json together. Pick at most one.');
+            throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, and --json together. Pick at most one.');
         }
         if (!options.raw && !options.json) {
             intro('FireForge Status');
         }
+        // Test-coverage mode needs only the project root (the baseline lives
+        // in .fireforge/), so it short-circuits before any engine/git guards.
+        if (options.testCoverage) {
+            renderTestCoverageStatus(await readBuildBaseline(projectRoot));
+            return;
+        }
         const paths = getProjectPaths(projectRoot);
         const config = await loadConfig(projectRoot);
         const emitJsonError = (code, message) => {
@@ -309,6 +322,7 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--raw', 'Show raw worktree status without patch classification')
         .option('--unmanaged', 'Show only unmanaged changes (not covered by patches or tools)')
         .option('--ownership', 'Show a flat path → owning patch table (flags files claimed by multiple patches)')
+        .option('--test-coverage', 'Show what the last recorded build covers for test packaging (full or scoped paths)')
         .option('--json', 'Output classified file status as JSON')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);

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

@@ -14,7 +14,7 @@ import type { TestRunOutcome } from './test-run.js';
  * harness problems with their own messages; everything else flows into
  * the regular non-zero-exit diagnosis chain.
  */
-export declare function finalizeSingleRunOutcome(outcome: TestRunOutcome, normalizedPaths: string[], binaryName: string, postRebuildContext: PostRebuildFailureContext | undefined): void;
+export declare function finalizeSingleRunOutcome(outcome: TestRunOutcome, normalizedPaths: string[], binaryName: string, postRebuildContext: PostRebuildFailureContext | undefined, headless?: boolean): void;
 /**
  * Shard-mode adapter over {@link handleNonZeroTestExit}: produces the
  * diagnosis text as a string (to warn per shard) instead of throwing, so

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

@@ -7,11 +7,12 @@
  * `test-harness-crash.ts` for single and sharded invocations. Split out of
  * `test.ts` to keep both files within the per-file line budget.
  */
-import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, } from '../core/test-harness-crash.js';
+import { buildGreenSummaryRejectedMessage, buildHarnessCrashMessage, buildNoTestsRanMessage, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { info } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
 function buildUnknownTestMessage(testPaths) {
     return (`mach could not discover the requested test path${testPaths.length === 1 ? '' : 's'}: ${testPaths.join(', ')}\n\n` +
         'The file may exist, but Firefox does not currently resolve it as a runnable test.\n\n' +
@@ -179,9 +180,14 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
  * harness problems with their own messages; everything else flows into
  * the regular non-zero-exit diagnosis chain.
  */
-export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext) {
+export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, postRebuildContext, headless = false) {
     if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
-        throw new GeneralError(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
+        const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
+        const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
+            headless,
+            platform: getPlatform(),
+        });
+        throw new GeneralError(hint ? `${base}\n\n${hint}` : base);
     }
     if (outcome.verdict.kind === 'tests-ran-ok') {
         // The verdict is authoritative over the raw exit code: a completed

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

@@ -12,4 +12,25 @@ export declare function resolveCanaryPath(options: TestOptions, projectConfig: P
 export declare function canaryTimeoutSeconds(projectConfig: ProjectConfig): number;
 /** Emits or throws the one-word canary verdict. */
 export declare function reportCanaryOutcome(outcome: TestRunOutcome): void;
+/** Per-harness bucketing of the requested test paths. */
+export interface HarnessClassification {
+    xpcshell: string[];
+    nonXpcshell: string[];
+}
+/**
+ * Harness classification is a pure path→manifest lookup and must precede
+ * the build dispatch: a mixed xpcshell+mochitest request can never
+ * dispatch, so refusing it before spending minutes in a pre-test build
+ * is strictly better (FORGE F7). A nonexistent path classifies as
+ * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
+ * before assertTestPathsExist is harmless — existence is still asserted
+ * after the stale/coverage gates, preserving their precedence over
+ * missing-path errors. `xpcshellOnly` (non-empty request, zero
+ * nonXpcshell paths) gates the Marionette preflight and the mochitest
+ * client flags (FORGE F10); pathless runs keep the full-suite behavior.
+ */
+export declare function classifyBeforeDispatch(engineDir: string, normalizedPaths: string[]): Promise<{
+    classification: HarnessClassification;
+    xpcshellOnly: boolean;
+}>;
 export {};

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

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { loadConfig } from '../core/config.js';
+import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { success } from '../utils/logger.js';
 /** Rejects pathless `fireforge test` unless the operator selected a pathless mode. */
@@ -59,3 +60,44 @@ function buildPathlessTestMessage() {
         '  - `fireforge test --doctor` to run the Marionette preflight only\n' +
         '  - `fireforge test --canary` to run the configured short harness canary');
 }
+async function classifyTestHarnesses(engineDir, normalizedPaths) {
+    const result = { xpcshell: [], nonXpcshell: [] };
+    for (const testPath of normalizedPaths) {
+        const manifest = await findNearestXpcshellManifest(engineDir, testPath);
+        if (manifest) {
+            result.xpcshell.push(testPath);
+        }
+        else {
+            result.nonXpcshell.push(testPath);
+        }
+    }
+    return result;
+}
+function buildMixedHarnessMessage(classification) {
+    return ('FireForge cannot run xpcshell and browser/mochitest paths in the same mach invocation.\n\n' +
+        'Split this into separate `fireforge test` commands so each manifest selects its own harness:\n' +
+        `  - xpcshell: ${classification.xpcshell.join(', ')}\n` +
+        `  - browser/mochitest: ${classification.nonXpcshell.join(', ')}`);
+}
+/**
+ * Harness classification is a pure path→manifest lookup and must precede
+ * the build dispatch: a mixed xpcshell+mochitest request can never
+ * dispatch, so refusing it before spending minutes in a pre-test build
+ * is strictly better (FORGE F7). A nonexistent path classifies as
+ * nonXpcshell (findNearestXpcshellManifest returns null), so classifying
+ * before assertTestPathsExist is harmless — existence is still asserted
+ * after the stale/coverage gates, preserving their precedence over
+ * missing-path errors. `xpcshellOnly` (non-empty request, zero
+ * nonXpcshell paths) gates the Marionette preflight and the mochitest
+ * client flags (FORGE F10); pathless runs keep the full-suite behavior.
+ */
+export async function classifyBeforeDispatch(engineDir, normalizedPaths) {
+    const classification = await classifyTestHarnesses(engineDir, normalizedPaths);
+    if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {
+        throw new GeneralError(buildMixedHarnessMessage(classification));
+    }
+    return {
+        classification,
+        xpcshellOnly: normalizedPaths.length > 0 && classification.nonXpcshell.length === 0,
+    };
+}

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

@@ -2,18 +2,19 @@
 import { Command } from 'commander';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { GeneralError } from '../errors/base.js';
-import { commanderArgParser, pickDefined } from '../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { testCommand } from './test.js';
 import { DEFAULT_HARNESS_RETRIES } from './test-run.js';
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const test = program
         .command('test [paths...]')
         .description('Run tests via mach test')
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
         .option('--auto', 'Forward mach test --auto. Valid only when no explicit paths are provided.')
         .option('--allow-stale-build', 'Allow tests to run even when packageable engine files changed since the last successful FireForge build')
+        .option('--allow-stale-components', 'Run tests despite components.conf changes that only a full "fireforge build" compiles in (the packaged child process will resolve the OLD StaticComponents table)')
         .option('--kill-stale-marionette', 'Terminate a recognized stale browser process holding the Marionette port before running tests')
         .option('--canary [path]', 'Run one short browser-chrome harness canary. Uses test.canaryPath from fireforge.json when no path is supplied.')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
@@ -56,9 +57,9 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         'runs (one browser instance per argument) by default, which does',
         'not exercise cross-argument state; --no-shard restores the',
         'combined single-instance invocation.',
-    ].join('\n'))
-        .action(withErrorHandling(async (paths, options) => {
+    ].join('\n'));
+    addWaitLockOption(test).action(withErrorHandling(async (paths, options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)));
+        await withEngineSessionLock(projectRoot, 'test', () => testCommand(projectRoot, paths, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

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

@@ -36,6 +36,8 @@ export interface TestRunContext {
     baseExtraArgs: readonly string[];
     /** Bounded harness-crash retry budget (0 disables retries). */
     harnessRetries: number;
+    /** Whether --headless was requested (crash-hint copy only). */
+    headless: boolean;
     /** Extra environment variables for the mach process. */
     env?: Record<string, string>;
 }

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

@@ -12,10 +12,11 @@
  * combined invocation stays available via `--no-shard`.
  */
 import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
-import { buildHarnessCrashMessage, classifyHarnessRun, } from '../core/test-harness-crash.js';
+import { buildHarnessCrashMessage, classifyHarnessRun, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { BuildError } from '../errors/build.js';
 import { info, note, warn } from '../utils/logger.js';
+import { getPlatform } from '../utils/platform.js';
 import { maybeInjectAppdirArg } from './test-appdir.js';
 /** Default bounded retry budget for recognized harness crashes. */
 export const DEFAULT_HARNESS_RETRIES = 2;
@@ -78,7 +79,12 @@ export async function runShardedTests(ctx, groups, diagnoseShardFailure) {
         const outcome = await runTestsWithRetries(ctx, group.paths);
         shards.push({ label: group.label, outcome });
         if (outcome.verdict.kind === 'harness-crash' && outcome.verdict.signature) {
-            warn(buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts));
+            const base = buildHarnessCrashMessage(outcome.verdict.signature, outcome.attempts);
+            const hint = headedNoOutputTimeoutHint(outcome.verdict.signature, {
+                headless: ctx.headless,
+                platform: getPlatform(),
+            });
+            warn(hint ? `${base}\n\n${hint}` : base);
         }
         else if (outcome.verdict.kind !== 'tests-ran-ok') {
             const diagnosis = diagnoseShardFailure(outcome, group.label);

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

@@ -0,0 +1,44 @@
+/**
+ * Pre-dispatch gates for `fireforge test` that stand between the request
+ * and a run against a stale or under-packaged runtime: the packaging
+ * coverage refusal, the stale-content refusal, and the compiled
+ * StaticComponents refusal. Split out of `test.ts` so the command module
+ * stays wiring; the probes and refusal copy live in
+ * `src/core/test-stale-check.ts`.
+ */
+import type { BuildBaseline } from '../core/build-baseline-types.js';
+import type { TestOptions } from '../types/commands/index.js';
+/**
+ * Stale-build preflight — when `--build` was NOT requested, detect
+ * packageable engine edits since the last successful build and fail
+ * UP-FRONT unless the operator explicitly accepts the stale package risk.
+ *
+ * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * regardless of staleness or `--allow-stale-build`: a runtime packaged by
+ * a file-scoped `test --build` can lack support fixtures for OTHER
+ * manifests even when nothing changed since — dispatching such a run
+ * hangs on missing fixtures rather than failing, so the flag (which only
+ * accepts stale CONTENT) must not be the trigger. Field incident: a
+ * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
+ * later run over different files timed out twice at 45s waiting on
+ * `DOMAudioPlaybackStarted`.
+ *
+ * Exception: a path-less `test --doctor` stops at the Marionette health
+ * check (`runDoctorPreflight` returns 'stop' when no test paths were
+ * given) and never dispatches a test, so it needs no packaging coverage —
+ * treating it as 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>;
+/**
+ * Compiled-StaticComponents gate — refuses runs whose child process would
+ * resolve a stale compiled component table. `components.conf` entries bake
+ * into compiled code that only a FULL build regenerates; a scoped
+ * `test --build` repackages the file but the failure surfaces as
+ * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
+ * (after the coverage refusal) AND to scoped `test --build` runs (before
+ * the pre-test build — that build cannot fix the table). A path-less
+ * `test --build` is exempt: its full build refreshes the anchor itself.
+ * `--allow-stale-components` downgrades the refusal to a warning.
+ */
+export declare function enforceStaticComponentsGate(engineDir: string, baseline: BuildBaseline | undefined, options: TestOptions): Promise<void>;

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

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pre-dispatch gates for `fireforge test` that stand between the request
+ * and a run against a stale or under-packaged runtime: the packaging
+ * coverage refusal, the stale-content refusal, and the compiled
+ * StaticComponents refusal. Split out of `test.ts` so the command module
+ * stays wiring; the probes and refusal copy live in
+ * `src/core/test-stale-check.ts`.
+ */
+import { checkStaleBuildForTest, checkStaticComponentsStale, findUncoveredRequestPaths, formatStaleBuildWarning, formatStaticComponentsRefusal, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
+import { GeneralError } from '../errors/base.js';
+import { warn } from '../utils/logger.js';
+/**
+ * Stale-build preflight — when `--build` was NOT requested, detect
+ * packageable engine edits since the last successful build and fail
+ * UP-FRONT unless the operator explicitly accepts the stale package risk.
+ *
+ * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * regardless of staleness or `--allow-stale-build`: a runtime packaged by
+ * a file-scoped `test --build` can lack support fixtures for OTHER
+ * manifests even when nothing changed since — dispatching such a run
+ * hangs on missing fixtures rather than failing, so the flag (which only
+ * accepts stale CONTENT) must not be the trigger. Field incident: a
+ * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
+ * later run over different files timed out twice at 45s waiting on
+ * `DOMAudioPlaybackStarted`.
+ *
+ * Exception: a path-less `test --doctor` stops at the Marionette health
+ * check (`runDoctorPreflight` returns 'stop' when no test paths were
+ * given) and never dispatches a test, so it needs no packaging coverage —
+ * treating it as 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) {
+    const stale = await checkStaleBuildForTest(projectRoot, engineDir);
+    const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
+    if (!dispatchesNoTests) {
+        const recordedCoverage = stale.baseline?.testPackagingCoverage;
+        const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
+        if (uncovered.length > 0) {
+            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : []));
+        }
+    }
+    await enforceStaticComponentsGate(engineDir, stale.baseline, options);
+    const staleMessage = stale.stale
+        ? `${formatStaleBuildWarning(stale)}\n\n` +
+            'Run `fireforge test --build` to refresh the packaged runtime first, or pass ' +
+            '`--allow-stale-build` if you intentionally rebuilt out-of-band and accept the risk.'
+        : undefined;
+    if (staleMessage !== undefined) {
+        if (options.allowStaleBuild === true) {
+            warn(staleMessage);
+        }
+        else {
+            throw new GeneralError(staleMessage);
+        }
+    }
+}
+/**
+ * Compiled-StaticComponents gate — refuses runs whose child process would
+ * resolve a stale compiled component table. `components.conf` entries bake
+ * into compiled code that only a FULL build regenerates; a scoped
+ * `test --build` repackages the file but the failure surfaces as
+ * `NS_ERROR_MALFORMED_URI` inside the test. Applies to build-less runs
+ * (after the coverage refusal) AND to scoped `test --build` runs (before
+ * the pre-test build — that build cannot fix the table). A path-less
+ * `test --build` is exempt: its full build refreshes the anchor itself.
+ * `--allow-stale-components` downgrades the refusal to a warning.
+ */
+export async function enforceStaticComponentsGate(engineDir, baseline, options) {
+    const result = await checkStaticComponentsStale(engineDir, baseline);
+    if (!result.stale) {
+        return;
+    }
+    const message = formatStaticComponentsRefusal(result.changedManifests);
+    if (options.allowStaleComponents === true) {
+        warn(message);
+        return;
+    }
+    throw new GeneralError(message);
+}