@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/core/test-run-completeness.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The exit-0 completeness veto for `fireforge test`.
+ *
+ * `classifyHarnessRun` trusts a mach exit code of 0 once any test started.
+ * That is wrong for one shape a downstream fork hit: the browser shut down
+ * cleanly inside the 105th of 314 files ("Application shut down (without
+ * crashing) in the middle of a test!"), nothing after it ran, mach still
+ * exited 0, and the verdict read `PASS checks=7919 unexpected=1`. The
+ * truncation checks the classifier already applies to a non-zero exit with
+ * a green-looking summary never ran, because the exit code short-circuited
+ * them.
+ *
+ * So a would-be pass is re-examined here against three facts the captured
+ * output carries: a non-zero `Unexpected results:` count, the harness's
+ * mid-test shutdown line, and requested test files that never produced a
+ * start marker. Any one of them turns the run into
+ * `FAIL reason=test-failures`, and a short start count is stamped on the
+ * verdict line as `started=<n>/<m> first-unstarted=<path>`.
+ *
+ * The start-count check only runs when at least one start marker names a
+ * requested file. The suite-specific xpcshell dispatch can prove execution
+ * with a result-summary block alone and print no `TEST_START` line, and a
+ * run that never names its files cannot be counted against them.
+ */
+import { type HarnessRunVerdict } from './test-harness-crash.js';
+import type { IncompleteRunEvidence } from './test-harness-signature.js';
+/** Start and skip marker names seen in a run's output. */
+export interface StartMarkers {
+    started: string[];
+    skipped: string[];
+}
+/**
+ * Collects start and skip markers from a dispatch's output as it streams.
+ *
+ * The capture `runMachCapture` hands back keeps only the last 2 MB of each
+ * stream, so a suite that prints more than that (a large browser directory,
+ * or any run under `--full-output`) loses its first files' start lines from
+ * the capture, and counting from that tail named files that ran and passed
+ * as never started. The tracker sees every chunk, splits it into whole lines
+ * per stream, and keeps only the marker names, so it grows with the file
+ * count, not the output size.
+ */
+export interface StartMarkerTracker {
+    /** Feeds one output chunk; wire it to `MachOptions.onOutputChunk`. */
+    onChunk(stream: 'stdout' | 'stderr', chunk: string): void;
+    /** The markers seen so far, including any unterminated last line. */
+    markers(): StartMarkers;
+}
+/** Markers collected outside the capped capture, and where they came from. */
+export interface TrackedStartMarkers {
+    markers: StartMarkers;
+    /** `stream`: every output chunk; `raw`: the mozlog structured log. */
+    source: 'stream' | 'raw';
+}
+/** Creates a {@link StartMarkerTracker}. */
+export declare function createStartMarkerTracker(): StartMarkerTracker;
+/**
+ * Counts the requested test files that produced a start or skip marker.
+ * Returns undefined when nothing can be counted: no test-file-shaped
+ * request, or no start line that names any requested file.
+ *
+ * @param evidence - Captured mach stdout and stderr, or the markers
+ *   collected from the complete stream
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ */
+export declare function countStartedFiles(evidence: string | StartMarkers, requestedPaths: readonly string[]): {
+    started: number;
+    requested: number;
+    firstUnstarted?: string;
+} | undefined;
+/**
+ * Re-examines a passing verdict for a mach exit-0 run and fails it when
+ * the run is incomplete or reported unexpected results. Any other verdict
+ * is returned unchanged.
+ *
+ * @param verdict - The classifier's verdict
+ * @param output - Captured mach stdout and stderr
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ * @param tracked - Start markers collected from the complete stream (or
+ *   the structured raw log); without them the capped capture is scanned
+ */
+export declare function vetoIncompletePass(verdict: HarnessRunVerdict, output: string, requestedPaths: readonly string[], tracked?: TrackedStartMarkers): HarnessRunVerdict;
+/**
+ * Operator-facing explanation for a pass {@link vetoIncompletePass}
+ * refused. Names the first file that never started, because that is
+ * where a re-run has to pick up.
+ *
+ * @param evidence - The veto's evidence
+ */
+export declare function buildIncompleteRunMessage(evidence: IncompleteRunEvidence): string;

package/dist/src/core/test-run-completeness.js

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The exit-0 completeness veto for `fireforge test`.
+ *
+ * `classifyHarnessRun` trusts a mach exit code of 0 once any test started.
+ * That is wrong for one shape a downstream fork hit: the browser shut down
+ * cleanly inside the 105th of 314 files ("Application shut down (without
+ * crashing) in the middle of a test!"), nothing after it ran, mach still
+ * exited 0, and the verdict read `PASS checks=7919 unexpected=1`. The
+ * truncation checks the classifier already applies to a non-zero exit with
+ * a green-looking summary never ran, because the exit code short-circuited
+ * them.
+ *
+ * So a would-be pass is re-examined here against three facts the captured
+ * output carries: a non-zero `Unexpected results:` count, the harness's
+ * mid-test shutdown line, and requested test files that never produced a
+ * start marker. Any one of them turns the run into
+ * `FAIL reason=test-failures`, and a short start count is stamped on the
+ * verdict line as `started=<n>/<m> first-unstarted=<path>`.
+ *
+ * The start-count check only runs when at least one start marker names a
+ * requested file. The suite-specific xpcshell dispatch can prove execution
+ * with a result-summary block alone and print no `TEST_START` line, and a
+ * run that never names its files cannot be counted against them.
+ */
+import { SHUTDOWN_REENTRY_PATTERN, START_MARKER_PATTERN, TEST_FILE_BASENAME_PATTERN, } from './test-harness-crash.js';
+/**
+ * A skip marker naming a test (`TEST-SKIP | path`, `TEST_SKIP: path`). A
+ * manifest-skipped file is accounted for, not missing.
+ */
+const SKIP_MARKER_PATTERN = /\bTEST[-_]SKIP(?:PED)?\b[:| ]*\s*(\S+)?/;
+/** Basename of a `/`-separated path. */
+function basenameOf(path) {
+    return path.slice(path.lastIndexOf('/') + 1);
+}
+/** Collects the start and skip marker names in `output`, line by line. */
+function scanStartMarkers(output) {
+    const markers = { started: [], skipped: [] };
+    for (const line of output.split(/\r?\n/))
+        recordMarkerLine(line, markers);
+    return markers;
+}
+function recordMarkerLine(line, markers) {
+    const start = START_MARKER_PATTERN.exec(line)?.[1];
+    if (start !== undefined) {
+        markers.started.push(start);
+        return;
+    }
+    const skip = SKIP_MARKER_PATTERN.exec(line)?.[1];
+    if (skip !== undefined)
+        markers.skipped.push(skip);
+}
+/** Creates a {@link StartMarkerTracker}. */
+export function createStartMarkerTracker() {
+    const collected = { started: [], skipped: [] };
+    const pending = { stdout: '', stderr: '' };
+    return {
+        onChunk(stream, chunk) {
+            const lines = `${pending[stream]}${chunk}`.split(/\r?\n/);
+            pending[stream] = lines.pop() ?? '';
+            for (const line of lines)
+                recordMarkerLine(line, collected);
+        },
+        markers() {
+            const tail = { started: [], skipped: [] };
+            recordMarkerLine(pending.stdout, tail);
+            recordMarkerLine(pending.stderr, tail);
+            return {
+                started: [...collected.started, ...tail.started],
+                skipped: [...collected.skipped, ...tail.skipped],
+            };
+        },
+    };
+}
+/**
+ * Counts the requested test files that produced a start or skip marker.
+ * Returns undefined when nothing can be counted: no test-file-shaped
+ * request, or no start line that names any requested file.
+ *
+ * @param evidence - Captured mach stdout and stderr, or the markers
+ *   collected from the complete stream
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ */
+export function countStartedFiles(evidence, requestedPaths) {
+    const requested = requestedPaths.filter((path) => TEST_FILE_BASENAME_PATTERN.test(basenameOf(path)));
+    if (requested.length === 0)
+        return undefined;
+    const { started, skipped } = typeof evidence === 'string' ? scanStartMarkers(evidence) : evidence;
+    const names = (path, list) => {
+        const base = basenameOf(path);
+        return list.some((name) => name.includes(base));
+    };
+    // Counting needs a dialect that names the requested files on its start
+    // lines. When no start line names any of them, the output cannot be
+    // counted against the request at all.
+    if (!requested.some((path) => names(path, started)))
+        return undefined;
+    const unstarted = requested.filter((path) => !names(path, started) && !names(path, skipped));
+    const firstUnstarted = unstarted[0];
+    return {
+        started: requested.length - unstarted.length,
+        requested: requested.length,
+        ...(firstUnstarted !== undefined ? { firstUnstarted } : {}),
+    };
+}
+/**
+ * Re-examines a passing verdict for a mach exit-0 run and fails it when
+ * the run is incomplete or reported unexpected results. Any other verdict
+ * is returned unchanged.
+ *
+ * @param verdict - The classifier's verdict
+ * @param output - Captured mach stdout and stderr
+ * @param requestedPaths - Dispatched paths, in dispatch order
+ * @param tracked - Start markers collected from the complete stream (or
+ *   the structured raw log); without them the capped capture is scanned
+ */
+export function vetoIncompletePass(verdict, output, requestedPaths, tracked) {
+    if (verdict.kind !== 'tests-ran-ok')
+        return verdict;
+    const shutdownLine = output
+        .split(/\r?\n/)
+        .find((line) => SHUTDOWN_REENTRY_PATTERN.test(line))
+        ?.trim();
+    // Tracked markers win whenever they saw a start line at all. An empty
+    // tracker means nothing was streamed through it, and the capture is then
+    // the only evidence there is.
+    const useTracked = tracked !== undefined && tracked.markers.started.length > 0;
+    const counted = countStartedFiles(useTracked ? tracked.markers : output, requestedPaths);
+    const unexpected = verdict.unexpected ?? 0;
+    const truncated = counted?.firstUnstarted !== undefined;
+    if (unexpected === 0 && shutdownLine === undefined && !truncated)
+        return verdict;
+    const evidence = {
+        started: counted?.started ?? 0,
+        requested: counted?.requested ?? 0,
+        ...(counted?.firstUnstarted !== undefined
+            ? {
+                firstUnstarted: counted.firstUnstarted,
+                startedSource: useTracked ? tracked.source : 'capture',
+            }
+            : {}),
+        ...(shutdownLine !== undefined ? { shutdownLine } : {}),
+        ...(unexpected > 0 ? { unexpected } : {}),
+    };
+    // The pass-only annotations would misdescribe a failed run: "harness
+    // teardown noise ignored" and the green-summary override both say the
+    // run was trusted.
+    const rest = { ...verdict };
+    delete rest.greenSummaryOverride;
+    delete rest.note;
+    return {
+        ...rest,
+        kind: 'test-failures',
+        incomplete: evidence,
+        ...(shutdownLine !== undefined ? { realFailureLine: shutdownLine } : {}),
+    };
+}
+/**
+ * Operator-facing explanation for a pass {@link vetoIncompletePass}
+ * refused. Names the first file that never started, because that is
+ * where a re-run has to pick up.
+ *
+ * @param evidence - The veto's evidence
+ */
+export function buildIncompleteRunMessage(evidence) {
+    const lines = [];
+    if (evidence.firstUnstarted !== undefined) {
+        lines.push(`  - only ${evidence.started} of ${evidence.requested} requested test files started; ` +
+            `the first that never started is ${evidence.firstUnstarted}`);
+    }
+    if (evidence.shutdownLine !== undefined) {
+        lines.push(`  - the browser shut down in the middle of a test: ${evidence.shutdownLine}`);
+    }
+    if (evidence.unexpected !== undefined) {
+        lines.push(`  - the suite summary reported ${evidence.unexpected} unexpected result(s)`);
+    }
+    const rerun = evidence.firstUnstarted !== undefined
+        ? `Re-run from ${evidence.firstUnstarted} onward, or the whole selection once the engine is quiet.`
+        : 'Read the unexpected results in the output above.';
+    return ('mach exited 0, but FireForge did NOT treat the run as passed:\n\n' +
+        `${lines.join('\n')}\n\n` +
+        'A browser that quits cleanly mid-suite exits 0, and its summary then covers only the ' +
+        `files that ran. ${rerun}`);
+}

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,5 @@
 import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
+import { type StaleExemption } from './test-stale-exempt.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */
@@ -22,6 +23,13 @@ export interface StaleBuildResult {
      * we have nothing to compare against and a warning would mislead.
      */
     baseline: BuildBaseline | undefined;
+    /**
+     * Changed packageable paths the packaged runtime already serves (objdir
+     * symlinks to the edited source, test files restaged at dispatch), which
+     * therefore do not make the build stale. Named in the refusal and in a
+     * notice so the exemption is visible.
+     */
+    exempt?: StaleExemption[];
 }
 /**
  * Probes the engine tree for packageable changes since the last successful
@@ -79,15 +87,33 @@ export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverag
  *   {@link STALE_PATHS_LIMIT}
  */
 export declare function findChangedTestManifestsForPaths(engineDir: string, baseline: BuildBaseline | undefined, uncovered: readonly string[]): Promise<string[]>;
+/** Extra evidence for {@link formatTestCoverageRefusal}. */
+export interface CoverageRefusalDetail {
+    /**
+     * Per uncovered path, the staging inputs that changed since the full
+     * build the recorded claim carries forward (what the replaced coverage
+     * affects).
+     */
+    changedInputs?: Readonly<Record<string, readonly string[]>>;
+    /** The record carries a full build's anchor forward for unchanged paths. */
+    carriesFullAnchor?: boolean;
+}
 /**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include. It is
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ *
  * @param uncovered - Request paths the recorded packaging does not cover
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
  *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
+ * @param detail - See {@link CoverageRefusalDetail}
  */
-export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[]): string;
+export declare function formatTestCoverageRefusal(uncovered: string[], coverage: string[], changedManifests?: readonly string[], detail?: CoverageRefusalDetail): string;
 /** Result of the compiled-StaticComponents staleness probe. */
 export interface StaticComponentsStaleResult {
     /** True when at least one `components.conf` genuinely diverged from the anchor. */

package/dist/src/core/test-stale-check.js

@@ -28,7 +28,9 @@ import { normalizePathSlashes } from '../utils/paths.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
+import { isTestManifestPath } from './coverage-records.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
+import { formatStaleExemptions, partitionStaleCandidates, } from './test-stale-exempt.js';
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
@@ -61,12 +63,15 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     // fingerprints capture "these files had this content when the build ran".
     // A path stays stale only when its live hash diverges.
     packageable = await dropPathsMatchingFingerprints(engineDir, packageable, baseline.packageableFingerprints);
-    if (packageable.length === 0) {
-        return { stale: false, changedPaths: [], truncated: 0, baseline };
+    // Edits the runtime already serves (symlinked into the objdir, or test
+    // files `mach test` restages at dispatch) cannot make the packaging stale.
+    const { stale, exempt } = await partitionStaleCandidates(engineDir, packageable);
+    if (stale.length === 0) {
+        return { stale: false, changedPaths: [], truncated: 0, baseline, exempt };
     }
-    const head = packageable.slice(0, STALE_PATHS_LIMIT);
-    const truncated = Math.max(0, packageable.length - head.length);
-    return { stale: true, changedPaths: head, truncated, baseline };
+    const head = stale.slice(0, STALE_PATHS_LIMIT);
+    const truncated = Math.max(0, stale.length - head.length);
+    return { stale: true, changedPaths: head, truncated, baseline, exempt };
 }
 /**
  * Formats a human-readable warning body from a {@link StaleBuildResult}.
@@ -76,10 +81,15 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
 export function formatStaleBuildWarning(result) {
     const tail = result.truncated > 0 ? `, … (+${result.truncated} more)` : '';
     const list = result.changedPaths.join(', ') + tail;
+    const exempt = result.exempt ?? [];
+    const exemptLine = exempt.length > 0
+        ? `\nNot counted as stale, because the runtime already serves them: ${formatStaleExemptions(exempt)}.`
+        : '';
     return (`Engine tree has changed since the last successful fireforge build (${list}).\n` +
         'The current obj-*/dist/ bundle may not reflect those edits. If your test reads ' +
         'packaged chrome / jar.mn resources, rerun with "fireforge test --build" (or ' +
-        '"fireforge build --ui") first. Passing --build skips this check.');
+        '"fireforge build --ui") first. Passing --build skips this check.' +
+        exemptLine);
 }
 /**
  * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
@@ -120,37 +130,6 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
 function normalizeCoveragePath(path) {
     return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
 }
-/**
- * Formats the refusal shown when a non-`--build` run requests paths the
- * packaged runtime's scoped `test --build` coverage does not include. It is
- * enforced on every such run, with or without `--allow-stale-build`. Kept
- * separate from the matcher so tests can pin structure and copy
- * independently (same split as {@link formatStaleBuildWarning}).
- */
-/**
- * Basenames of the test manifests whose entries decide what a packaged test
- * runtime stages. A manifest that gained an entry is the single most common
- * reason a run needs coverage the last build never claimed, and it is a
- * fact FireForge already holds but never said, leaving the operator to
- * rediscover it after a correct refusal.
- */
-const TEST_MANIFEST_BASENAMES = new Set([
-    'xpcshell.toml',
-    'xpcshell.ini',
-    'browser.toml',
-    'browser.ini',
-    'mochitest.toml',
-    'mochitest.ini',
-    'chrome.toml',
-    'chrome.ini',
-    'a11y.toml',
-    'a11y.ini',
-]);
-/** True for a test manifest path (by basename). */
-function isTestManifestPath(path) {
-    const base = path.slice(path.lastIndexOf('/') + 1);
-    return TEST_MANIFEST_BASENAMES.has(base);
-}
 /**
  * Test manifests changed since the recorded build that sit in (or above)
  * the directory of an uncovered request path, i.e. the manifests that
@@ -185,31 +164,35 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
     return hits.slice(0, STALE_PATHS_LIMIT);
 }
 /**
+ * Formats the refusal shown when a non-`--build` run requests paths the
+ * packaged runtime's scoped `test --build` coverage does not include. It is
+ * enforced on every such run, with or without `--allow-stale-build`. Kept
+ * separate from the matcher so tests can pin structure and copy
+ * independently (same split as {@link formatStaleBuildWarning}).
+ *
  * @param uncovered - Request paths the recorded packaging does not cover
  * @param coverage - The recorded scoped coverage claim
  * @param changedManifests - Test manifests changed since the recorded
  *   build that explain an uncovered path (from
  *   {@link findChangedTestManifestsForPaths}). Omitted or empty renders
  *   nothing
+ * @param detail - See {@link CoverageRefusalDetail}
  */
-export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = []) {
+export function formatTestCoverageRefusal(uncovered, coverage, changedManifests = [], detail = {}) {
     const cap = (paths) => {
         const head = paths.slice(0, STALE_PATHS_LIMIT);
         const truncated = paths.length - head.length;
         return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
-    // Name --extend-coverage here or it is undiscoverable: a scoped build
-    // replaces the claim, so under several concurrent sessions a peer's build
-    // for an unrelated path erases coverage you legitimately still hold, and
-    // the union that fixes it is a flag the operator has no reason to know
-    // exists at the moment they need it. The anchor conditions are stated
-    // because they are what decides whether it will work.
-    const extendHint = rebuildTargets.length > 0
-        ? ` Add --extend-coverage to that rebuild to UNION the new paths onto the recorded claim instead of replacing it — it holds while engine HEAD and engine/mozconfig are unchanged since the recorded build.`
+    // Per-path retention is the default, so rebuilding only the uncovered
+    // paths no longer costs anyone else's claim. Saying so is what keeps a
+    // peer from rebuilding everything "to be safe".
+    const keepHint = rebuildTargets.length > 0
+        ? ' That scoped build keeps every other recorded path whose own staging inputs (manifest directory and the fixtures its manifest names) and engine/mozconfig are unchanged.'
         : '';
     const rebuildHint = rebuildTargets.length > 0
-        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them (or "fireforge test --build-only ..." to package without running), or run "fireforge build" for full coverage.${keepHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
     // Why this run needs new coverage, when a changed manifest explains it: a
     // manifest that gained an entry is not covered by a build claim recorded
@@ -217,10 +200,17 @@ export function formatTestCoverageRefusal(uncovered, coverage, changedManifests
     const manifestLine = changedManifests.length > 0
         ? ` This run needs coverage the recorded build never claimed because a test manifest changed since it: ${changedManifests.map((m) => `engine/${m}`).join(', ')} — a manifest that gained an entry stages new support fixtures, and a claim recorded for other paths (or another harness) does not cover them.`
         : '';
-    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
+    const affected = Object.entries(detail.changedInputs ?? {}).filter(([, files]) => files.length > 0);
+    const affectedLine = affected.length > 0
+        ? ` Staging inputs changed since the full build this record carries forward: ${affected.map(([path, files]) => `${path} (${cap(files)})`).join('; ')}.`
+        : '';
+    const scope = detail.carriesFullAnchor
+        ? `${cap(coverage)}, plus earlier full coverage for paths whose own staging inputs are unchanged`
+        : cap(coverage);
+    return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${scope}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
         'fixtures for those manifests may be missing from obj-*/_tests/, and the run can hang ' +
-        `rather than fail.${manifestLine} ${rebuildHint} ` +
+        `rather than fail.${affectedLine}${manifestLine} ${rebuildHint} ` +
         '(--allow-stale-build does not bypass this check — it accepts stale content, not missing coverage.)');
 }
 /**

package/dist/src/core/test-stale-exempt.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Edits the stale-build preflight must not count. A test file the build
+ * never packages is restaged by `mach test` at dispatch, and a file whose
+ * every objdir copy is a symlink back to the edited source is already what
+ * the runtime reads. Refusing on either made every iteration on a test (or
+ * on symlinked chrome) pay a packaging pass or reach for
+ * `--allow-stale-build`, the flag whose refusal text says not to.
+ */
+import { type InstallManifestIndex } from './objdir-install-manifests.js';
+/** A changed path the preflight does not count as stale, and why. */
+export interface StaleExemption {
+    path: string;
+    /**
+     * `symlinked`: every objdir copy is a symlink to the edited source.
+     * `test-only`: a test file the build does not package, restaged at dispatch.
+     */
+    why: 'symlinked' | 'test-only';
+}
+/** The single `obj-*` directory under the engine, or undefined when zero or several exist. */
+export declare function findSingleObjDir(engineDir: string): Promise<string | undefined>;
+/**
+ * The objdir's install-manifest index, or undefined when there is no single
+ * objdir or nothing in it is readable.
+ * @param engineDir - Absolute engine directory
+ */
+export declare function loadEngineInstallIndex(engineDir: string): Promise<InstallManifestIndex | undefined>;
+/**
+ * Splits changed packageable paths into the ones that make the packaged
+ * runtime stale and the ones it already serves. Without a readable objdir
+ * index every path stays stale, the behaviour before the exemption existed.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param paths - Changed engine-relative paths, already fingerprint-filtered
+ */
+export declare function partitionStaleCandidates(engineDir: string, paths: readonly string[]): Promise<{
+    stale: string[];
+    exempt: StaleExemption[];
+}>;
+/** Renders exemptions for a notice or refusal: `a (symlinked), b (test file)`. */
+export declare function formatStaleExemptions(exempt: readonly StaleExemption[], limit?: number): string;

package/dist/src/core/test-stale-exempt.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Edits the stale-build preflight must not count. A test file the build
+ * never packages is restaged by `mach test` at dispatch, and a file whose
+ * every objdir copy is a symlink back to the edited source is already what
+ * the runtime reads. Refusing on either made every iteration on a test (or
+ * on symlinked chrome) pay a packaging pass or reach for
+ * `--allow-stale-build`, the flag whose refusal text says not to.
+ */
+import { readdir } from 'node:fs/promises';
+import { isTestPath } from './build-audit-resolve.js';
+import { classifyRuntimeDelivery, loadInstallManifestIndex, } from './objdir-install-manifests.js';
+/** The single `obj-*` directory under the engine, or undefined when zero or several exist. */
+export async function findSingleObjDir(engineDir) {
+    try {
+        const entries = await readdir(engineDir, { withFileTypes: true });
+        const objDirs = entries.filter((entry) => entry.isDirectory() && entry.name.startsWith('obj-'));
+        return objDirs.length === 1 ? objDirs[0]?.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The objdir's install-manifest index, or undefined when there is no single
+ * objdir or nothing in it is readable.
+ * @param engineDir - Absolute engine directory
+ */
+export async function loadEngineInstallIndex(engineDir) {
+    const objDir = await findSingleObjDir(engineDir);
+    return objDir === undefined ? undefined : loadInstallManifestIndex(engineDir, objDir);
+}
+/**
+ * Splits changed packageable paths into the ones that make the packaged
+ * runtime stale and the ones it already serves. Without a readable objdir
+ * index every path stays stale, the behaviour before the exemption existed.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param paths - Changed engine-relative paths, already fingerprint-filtered
+ */
+export async function partitionStaleCandidates(engineDir, paths) {
+    if (paths.length === 0)
+        return { stale: [], exempt: [] };
+    const index = await loadEngineInstallIndex(engineDir);
+    if (index === undefined)
+        return { stale: [...paths], exempt: [] };
+    const stale = [];
+    const exempt = [];
+    for (const path of paths) {
+        const delivery = await classifyRuntimeDelivery(index, engineDir, path);
+        if (delivery === 'live')
+            exempt.push({ path, why: 'symlinked' });
+        else if (delivery === 'at-dispatch' || (delivery === 'unlisted' && isTestPath(path))) {
+            exempt.push({ path, why: 'test-only' });
+        }
+        else
+            stale.push(path);
+    }
+    return { stale, exempt };
+}
+/** Renders exemptions for a notice or refusal: `a (symlinked), b (test file)`. */
+export function formatStaleExemptions(exempt, limit = 10) {
+    const head = exempt
+        .slice(0, limit)
+        .map(({ path, why }) => why === 'symlinked'
+        ? `${path} (objdir symlink to the source)`
+        : `${path} (test file, restaged at dispatch)`);
+    const extra = exempt.length - head.length;
+    return head.join(', ') + (extra > 0 ? `, … (+${extra} more)` : '');
+}

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -22,6 +22,8 @@ export interface XpcshellRetryOptions {
     kind?: MachTestSuiteKind | undefined;
     /** Whether the run was started with full harness output. */
     fullOutput?: boolean | undefined;
+    /** Per-chunk feed for the retried run's output (start-marker tracking). */
+    onOutputChunk?: ((stream: 'stdout' | 'stderr', chunk: string) => void) | undefined;
 }
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test

package/dist/src/core/test-xpcshell-retry.js

@@ -9,7 +9,7 @@ import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
  * generic command.
  */
 export async function retryAfterXpcshellSymlinkRepair(options) {
-    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, } = options;
+    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, onOutputChunk, } = options;
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
@@ -23,6 +23,7 @@ export async function retryAfterXpcshellSymlinkRepair(options) {
                 args: extraArgs,
                 env,
                 fullOutput,
+                ...(onOutputChunk === undefined ? {} : { teardown: { onOutputChunk } }),
             });
         }
     }