@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/core/test-harness-crash.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Harness-crash classification for `fireforge test` (field reports C1/C2).
+ * Harness-crash classification for `fireforge test`.
  *
  * The wrapped mach harness exhibits flaky non-test failures that an exit
  * code (or a "did it print a summary" grep) cannot distinguish from real
@@ -11,18 +11,22 @@
  *    'poll_interval'`, `host_statistics64(HOST_VM_INFO64) syscall failed`,
  *    `(ipc/mig) array not large enough` — a psutil/macOS mismatch) which
  *    abort the run before any test executes;
- *  - hangs after browser startup that die at the no-output timeout yet
- *    still emit a `Passed: 0` summary;
- *  - post-green shutdown re-entry, where a fully green run stalls on
- *    "must wait for focus" and records "Application shut down (without
- *    crashing) in the middle of a test!" as the only unexpected failure.
+ *  - hangs after browser startup that die at the no-output timeout yet still
+ *    emit a `Passed: 0` summary;
+ *  - post-green shutdown re-entry, where a fully green run stalls on "must
+ *    wait for focus" and records "Application shut down (without crashing)
+ *    in the middle of a test!" as the only unexpected failure.
  *
  * Classification therefore keys on `TEST-START` presence — summary lines
  * never count as proof that tests ran — and recognizes the crash shapes
- * above so the command layer can retry them with a bounded budget instead
- * of reporting phantom test failures (or phantom passes).
+ * above so the command layer can retry them with a bounded budget instead of
+ * reporting phantom test failures (or phantom passes).
  */
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
+// The no-output-stall triage text lives in `test-stall-triage.ts` (it is
+// operator advice, not classification) and is re-exported here so the
+// command layer keeps importing its harness diagnostics from one module.
+export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
 const TEST_START_PATTERN = /\bTEST-START\b/;
 /**
  * Structured-log execution marker (`mach xpcshell-test` mozlog output uses
@@ -40,28 +44,47 @@ const NONZERO_UNEXPECTED_SUMMARY_PATTERN = /\bUnexpected results:\s*[1-9]/;
  * single-file xpcshell run prints a result-summary block instead
  * (`TEST_END: Test PASS`, `Ran 16 checks`, `Unexpected results: 0`), so
  * keying execution purely on `TEST-START` mis-reads a green xpcshell run as
- * "no tests started" (field report: a single-file xpcshell pass exited 1).
+ * "no tests started".
  *
- * These markers are xpcshell-specific on purpose: the bare
- * `Passed: 0` / `Failed: 0` summary that the no-output hang shape prints is
- * deliberately NOT matched here — that case must still read as `no-tests`.
+ * These markers are xpcshell-specific on purpose: the bare `Passed: 0` /
+ * `Failed: 0` summary that the no-output hang shape prints is deliberately
+ * NOT matched here — that case must still read as `no-tests`.
  */
 const XPCSHELL_RESULT_SUMMARY_PATTERN = /\bTEST_END\b|\bRan \d+ checks?\b|\bResult summary:/i;
 const UNEXPECTED_LINE_PATTERN = /^.*\bTEST-UNEXPECTED-[A-Z-]+\b.*$/gm;
-const FAIL_LINE_PATTERN = /^.*\bFAIL\b.*$/gm;
-const ASSERTION_LINE_PATTERN = /^.*\b(?:Assertion failure|MOZ_ASSERT|ASSERTION)\b.*$/gim;
+/**
+ * A `FAIL` token that is HARNESS-SHAPED. Deliberately not a bare `\bFAIL\b`
+ * word match: that matched any output line containing the ordinary English
+ * word, so a test's own passing diagnostic could manufacture a red run (see
+ * {@link realUnexpectedFailureLines}). It also matched `TEST-KNOWN-FAIL` —
+ * an EXPECTED failure — and counted it as a real one.
+ *
+ * The `TEST-` prefix is what makes the token the harness's rather than
+ * prose, and the negative lookahead is what keeps a known-fail annotation
+ * out of the evidence set.
+ */
+const FAIL_LINE_PATTERN = /^.*\bTEST-(?!KNOWN-FAIL\b)[A-Z-]*FAIL\b.*$/gm;
+/**
+ * The three concrete shapes Gecko prints for a real assertion failure.
+ * Case-SENSITIVE and punctuation-anchored on purpose: the previous
+ * `/\b(?:Assertion failure|MOZ_ASSERT|ASSERTION)\b/gim` was
+ * case-insensitive, so the ordinary English word "assertion" in a passing
+ * diagnostic ("If an assertion below times out, this is why") was read as
+ * a failure — and the verdict then named that diagnostic as the first real
+ * test failure, pointing the reader at the wrong line.
+ */
+const ASSERTION_LINE_PATTERN = /^.*(?:Assertion failure:|MOZ_ASSERT\(|###!!! ASSERTION).*$/gm;
 const SHUTDOWN_REENTRY_PATTERN = /Application shut down \(without crashing\) in the middle of a test/i;
 const FOCUS_STALL_PATTERN = /must wait for focus/i;
 const TRACEBACK_PATTERN = /Traceback \(most recent call last\)/;
 const NO_OUTPUT_TIMEOUT_PATTERN = /timed out after \d+ seconds with no output/i;
 /**
- * Crash-marker lines mozcrash / the mochitest harness print when the
- * browser process itself died. Matched against the RAW output (never
- * noise-stripped): any of these proves the run was truncated by a crash,
- * so an embedded green summary is under-reporting, not a result (field
- * report: `Main app process: killed by SIGSEGV` at the second of eight
- * files, summary `Passed: 2 / Failed: 0`, mach exit 1 — 0.35.0 accepted
- * it as passed and masked a real regression for a whole drill).
+ * Crash-marker lines mozcrash / the mochitest harness print when the browser
+ * process itself died. Matched against the RAW output (never noise-stripped):
+ * any of these proves the run was truncated by a crash, so an embedded green
+ * summary is under-reporting, not a result. `Main app process: killed by
+ * SIGSEGV` at the second of eight files with a `Passed: 2 / Failed: 0`
+ * summary is the shape this exists to catch.
  */
 const CRASH_MARKER_PATTERNS = [
     /Main app process: killed by SIG\w+/,
@@ -77,13 +100,13 @@ const CRASH_MARKER_PATTERNS = [
  * on macOS. Each is matched per-line so the evidence line in the report is
  * the concrete failure, not the whole traceback.
  */
-// Downstream report (0.34.0 cycle): a pre-fix _DegradedReading fallback that
-// wasn't a real namedtuple duck type crashed mozsystemmonitor on the fallback
-// itself (`_build_meta` subscripts the reading; `_collect` unpacks it); a
-// startup abort with zero TEST-START lines from this family is a crash, not
-// a test failure. The `_collect failed` variant is caught-and-logged, so it
-// carries no Traceback header — it gets its own zero-TEST-START check in
-// `detectHarnessCrashSignature` besides joining the traceback cluster.
+// A `_DegradedReading` fallback that is not a real namedtuple duck type
+// crashes mozsystemmonitor on the fallback itself (`_build_meta` subscripts
+// the reading; `_collect` unpacks it); a startup abort with zero TEST-START
+// lines from this family is a crash, not a test failure. The `_collect
+// failed` variant is caught-and-logged, so it carries no Traceback header —
+// it gets its own zero-TEST-START check in `detectHarnessCrashSignature`
+// besides joining the traceback cluster.
 const DEGRADED_READING_CRASH_SIGNALS = [
     /'_DegradedReading' object is not subscriptable/,
     /'_DegradedReading' object is not iterable/,
@@ -96,12 +119,12 @@ const STARTUP_TRACEBACK_SIGNALS = [
     /HOST_VM_INFO64/,
     /\(ipc\/mig\) array not large enough/,
     /psutil\.[A-Za-z]*Error/,
-    // Field report (0.34.1): on a degraded host every collector sample is
-    // rejected, aggregation has nothing, and mozbuild's log_resource_usage
-    // dies on usage["io"].read_bytes AFTER a fully successful compile
-    // ("Error running mach" with complete artifacts). Environmental, not a
-    // build regression — the protected build retries it (incremental retry
-    // is cheap and the guard keeps the retry green).
+    // On a degraded host every collector sample is rejected, aggregation has
+    // nothing, and mozbuild's log_resource_usage dies on
+    // usage["io"].read_bytes AFTER a fully successful compile ("Error running
+    // mach" with complete artifacts). Environmental, not a build regression —
+    // the protected build retries it, since an incremental retry is cheap and
+    // the guard keeps the retry green.
     /AttributeError: 'NoneType' object has no attribute 'read_bytes'/,
     ...DEGRADED_READING_CRASH_SIGNALS,
 ];
@@ -113,12 +136,11 @@ function findLine(output, patterns) {
     return undefined;
 }
 /**
- * Non-signal noise lines: the resource-monitor degrade path (FireForge's
- * own guard plus mozlog's `_collect failed`) prints warnings on runs that
- * then complete green. Field report (0.34.0 cycle): every multi-file suite
- * was reported CRASH because these lines matched the startup-traceback
- * signals even though the embedded summary was fully green. They are
- * excluded from crash evidence entirely.
+ * Non-signal noise lines: the resource-monitor degrade path (FireForge's own
+ * guard plus mozlog's `_collect failed`) prints warnings on runs that then
+ * complete green. Without excluding them, every multi-file suite reports
+ * CRASH because these lines match the startup-traceback signals even though
+ * the embedded summary is fully green.
  */
 const NOISE_LINE_PATTERNS = [
     /\bUserWarning\b/,
@@ -130,10 +152,10 @@ const NOISE_LINE_PATTERNS = [
     /_collect failed(?!.*_DegradedReading)/i,
     /FireForge: host resource monitor degraded/i,
     /warnings\.warn\(/,
-    // mozsystemmonitor's parent-side drain loop rejecting a malformed sample
-    // (field report 0.34.1); mach sometimes reprints the warning text without
-    // the `UserWarning:` token, and a run that completes despite the stream
-    // must never classify as crash on it.
+    // mozsystemmonitor's parent-side drain loop rejecting a malformed sample.
+    // mach sometimes reprints the warning text without the `UserWarning:`
+    // token, and a run that completes despite the stream must never classify
+    // as crash on it.
     /failed to read the received data/i,
 ];
 /** Matches the caught/telemetry context that marks a traceback as benign. */
@@ -209,16 +231,16 @@ function hasGreenShapedSummary(output) {
         realUnexpectedFailureLines(output).length === 0);
 }
 /**
- * True when the output embeds a COMPLETED, GREEN suite summary: an
- * execution signal, `Unexpected results: 0` (and no non-zero unexpected
- * count), a `SUITE_END` marker, no real `TEST-UNEXPECTED-*` lines — and
- * NO crash marker. Such a run finished its suite; any startup-traceback-
- * shaped noise in the same output is by definition non-fatal, so this
- * vetoes signature-based crash classification (field report: fully green
- * sharded runs reported `CRASH (N attempts)` because degradation warnings
- * matched the psutil signals). A summary printed after a crash marker is
- * NOT "completed" — it only covers the files that ran before the crash
- * (0.35.0 green-wash field report). Exported for direct unit testing.
+ * True when the output embeds a COMPLETED, GREEN suite summary: an execution
+ * signal, `Unexpected results: 0` (and no non-zero unexpected count), a
+ * `SUITE_END` marker, no real `TEST-UNEXPECTED-*` lines — and NO crash
+ * marker. Such a run finished its suite, so any startup-traceback-shaped
+ * noise in the same output is by definition non-fatal and this vetoes
+ * signature-based crash classification; without the veto, fully green
+ * sharded runs report `CRASH (N attempts)` because degradation warnings
+ * match the psutil signals. A summary printed after a crash marker is NOT
+ * "completed" — it only covers the files that ran before the crash.
+ * Exported for direct unit testing.
  */
 export function hasCompletedGreenSummary(output) {
     return hasGreenShapedSummary(output) && findCrashMarkerLine(output) === undefined;
@@ -453,18 +475,18 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     const firstRealFailure = realFailures[0];
     const failureBlocks = collectUnexpectedFailureBlocks(output);
     const secondaryHarnessSignature = firstRealFailure !== undefined ? detectSecondaryHarnessNoise(output) : undefined;
-    // Checked BEFORE signature detection: a suite that ran clean
-    // and then died in KNOWN upstream teardown noise is a PASS, not a crash.
-    // The teardown traceback matches the startup-traceback cluster, and the
-    // existing green-summary veto over that cluster requires a `SUITE_END`
-    // marker — which this very traceback is what prevents from printing. So
-    // a substantively green suite (`Ran N checks` / `Unexpected results: 0`,
-    // no unexpected lines) was reported CRASH, indistinguishable at the
-    // summary level from a red run. Every hard-evidence veto still applies:
-    // a crash marker, a non-zero unexpected count, any real TEST-UNEXPECTED
-    // line, the shutdown-re-entry shape, or a requested file that never
-    // started keeps the run failing. Only the missing shutdown marker is
-    // forgiven, and only when the recognized teardown traceback explains it.
+    // Checked BEFORE signature detection: a suite that ran clean and then died
+    // in KNOWN upstream teardown noise is a PASS, not a crash. The teardown
+    // traceback matches the startup-traceback cluster, and the green-summary
+    // veto over that cluster requires a `SUITE_END` marker — which this very
+    // traceback is what prevents from printing. Without this check a
+    // substantively green suite (`Ran N checks` / `Unexpected results: 0`, no
+    // unexpected lines) reports CRASH, indistinguishable at the summary level
+    // from a red run. Every hard-evidence veto still applies: a crash marker,
+    // a non-zero unexpected count, any real TEST-UNEXPECTED line, the
+    // shutdown-re-entry shape, or a requested file that never started keeps
+    // the run failing. Only the missing shutdown marker is forgiven, and only
+    // when the recognized teardown traceback explains it.
     if (isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths)) {
         return { kind: 'tests-ran-ok', note: 'harness teardown noise ignored', ...counts };
     }
@@ -480,16 +502,14 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
         return { kind: 'tests-ran-ok', ...counts };
     }
     // Exit codes follow the corrected verdict: a run whose embedded summary
-    // completed green is a pass even when the wrapper exit code went
-    // non-zero on harness noise (field report: a fully green --no-shard run
-    // exited 1). Real failures always carry a non-zero unexpected count or
-    // TEST-UNEXPECTED lines, both of which fail the green-summary check.
+    // completed green is a pass even when the wrapper exit code went non-zero
+    // on harness noise. Real failures always carry a non-zero unexpected count
+    // or TEST-UNEXPECTED lines, both of which fail the green-summary check.
     //
-    // The override must never win over crash or truncation evidence
-    // (0.35.0 green-wash field report: a SIGSEGV at the second of eight
-    // files produced a "green" `Passed: 2 / Failed: 0` summary and mach
-    // exit 1 — the summary was green only because the crash prevented the
-    // other six files from producing any results). A crash marker or an
+    // The override must never win over crash or truncation evidence: a SIGSEGV
+    // at the second of eight files produces a "green" `Passed: 2 / Failed: 0`
+    // summary and mach exit 1, green only because the crash prevented the
+    // other six files from producing any results. A crash marker or an
     // unpaired/never-started requested file rejects the override with the
     // evidence attached, so the caller can say why.
     if (hasGreenShapedSummary(output)) {
@@ -513,14 +533,40 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
         }
         return { kind: 'tests-ran-ok', greenSummaryOverride: true, ...counts };
     }
+    const wordMatchNote = unmarkedFailureEvidenceNote(counts, realFailures);
     return {
         kind: 'test-failures',
         ...counts,
         ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
         ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
         ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
+        ...(wordMatchNote !== undefined ? { note: wordMatchNote } : {}),
     };
 }
+/**
+ * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
+ * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
+ * `Unexpected results: 0`, yet the run is still classified `test-failures`
+ * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
+ *
+ * `unexpected=0` printed beside `reason=test-failures` is the tell that the
+ * verdict rests on pattern matching rather than on a harness result, and a
+ * reader who cannot see that spends hours attributing a red run to the
+ * change under test. The note says so on the verdict line itself.
+ *
+ * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * green-shaped summary is still a failing run, and inventing a new `reason`
+ * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
+ */
+function unmarkedFailureEvidenceNote(counts, realFailures) {
+    if (counts.unexpected !== 0)
+        return undefined;
+    if (realFailures.length === 0)
+        return undefined;
+    if (realFailures.some((line) => UNEXPECTED_LINE_SINGLE.test(line)))
+        return undefined;
+    return 'summary reported 0 unexpected; no TEST-UNEXPECTED marker in the matched evidence';
+}
 /**
  * True when the capture shows a substantively GREEN suite whose only
  * unexplained residue is the recognized mozsystemmonitor teardown
@@ -643,73 +689,6 @@ export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'ma
         'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
         'patching it manually does not stick).');
 }
-/**
- * The three recorded causes of the `timed out … with no output` / `Ran 0
- * checks` signature, ordered so one stall points at the discriminating
- * next step. Printed verbatim under the hint.
- */
-const NO_OUTPUT_STALL_TRIAGE = [
-    '  1. A sleeping or locked display on an unattended HEADED run (macOS). The browser never ' +
-        'paints and never reaches its first test.',
-    '  2. A headless SWGL compositor failure — re-run with --headless to separate this from (1): ' +
-        'if --headless passes, the stall was display/compositor-side, not product-side.',
-    '  3. A broken `chrome://` image on the startup page, which stalls first paint. Run a ' +
-        'known-good control test first; if the control stalls too, the cause is not the test ' +
-        'under investigation.',
-];
-/**
- * Optional hint appended to the harness-crash message when a HEADED run on
- * macOS died at the no-output timeout.
- *
- * When `displayState` names a MEASURED display state, the hint states it
- * as fact rather than as one of three possibilities — that is the whole
- * point of probing: an operator staring at a bare test failure should not
- * have to rediscover that their machine dimmed. `caffeinate` is described
- * accurately (it prevents sleep; it cannot wake an already-sleeping
- * display), because the previous wording sent operators to a command that
- * could not have helped them.
- *
- * Pure — the platform and the probed state are injected so unit tests need
- * no mocking.
- *
- * @param signature - The recognized crash shape
- * @param context - Run mode, platform, and the probed display state
- * @returns The hint text, or undefined when the shape does not apply
- */
-export function headedNoOutputTimeoutHint(signature, context) {
-    if (context.platform !== 'darwin' || context.headless)
-        return undefined;
-    if (!signature.reason.includes('no-output timeout'))
-        return undefined;
-    const lead = context.displayState === 'asleep'
-        ? 'Hint: this was a HEADED run on macOS and the display was MEASURED ASLEEP ' +
-            '(IODisplayWrangler below its awake power state). A headed browser on a sleeping ' +
-            'display never paints and never starts a test, so this stall is environmental — not a ' +
-            'product or test failure.'
-        : context.displayState === 'awake'
-            ? 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
-                'was measured AWAKE, so the sleeping-display cause below is ruled out for this run.'
-            : 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
-                'state could not be measured, so all three causes below remain open.';
-    const remedy = 'Note that `caffeinate -disu` PREVENTS sleep; it cannot WAKE a display that is already ' +
-        'asleep. Wake the display (or run on an attended machine), or pass --headless.';
-    return `${lead}\n\nKnown causes of this exact signature:\n${NO_OUTPUT_STALL_TRIAGE.join('\n')}\n\n${remedy}`;
-}
-/**
- * Verdict-line note for a headed no-output stall whose display was
- * measured asleep. Returned as the parenthetical the verdict line carries,
- * so the one greppable line an automated consumer reads already names the
- * environmental cause instead of a bare `FAIL reason=crash`.
- */
-export function headedDisplayAsleepVerdictNote(signature, context) {
-    if (context.platform !== 'darwin' || context.headless)
-        return undefined;
-    if (context.displayState !== 'asleep')
-        return undefined;
-    if (!signature.reason.includes('no-output timeout'))
-        return undefined;
-    return 'headed run stalled with the display asleep';
-}
 /**
  * Exit codes that mean "the child died on SIGSEGV": Node reports a
  * signal-killed child as the negated signal number, while a shell layer

package/dist/src/core/test-harness-signature.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The recognized-harness-crash shape, in a module of its own.
+ *
+ * It lives apart from both of its users to break an import cycle:
+ * `test-harness-crash.ts` re-exports the operator advice in
+ * `test-stall-triage.ts`, and the triage text is keyed on this signature. A
+ * type-only edge is erased at runtime, but the cycle gate reads the import
+ * graph rather than the emitted code, and a shared leaf is a truer
+ * description of the relationship than either direction of the cycle was:
+ * neither module owns this type more than the other.
+ */
+/** A recognized harness-crash shape with its evidence line. */
+export interface HarnessCrashSignature {
+    /** Stable reason id for the recognized shape. */
+    reason: string;
+    /** The concrete output line the recognition was based on. */
+    line: string;
+}

package/dist/src/core/test-harness-signature.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The recognized-harness-crash shape, in a module of its own.
+ *
+ * It lives apart from both of its users to break an import cycle:
+ * `test-harness-crash.ts` re-exports the operator advice in
+ * `test-stall-triage.ts`, and the triage text is keyed on this signature. A
+ * type-only edge is erased at runtime, but the cycle gate reads the import
+ * graph rather than the emitted code, and a shared leaf is a truer
+ * description of the relationship than either direction of the cycle was:
+ * neither module owns this type more than the other.
+ */
+export {};

package/dist/src/core/test-path-scope.d.ts

@@ -1,22 +1,19 @@
 /**
  * Directory-argument scope analysis for `fireforge test`.
  *
- * mozbuild's test resolver matches command-line paths by STRING PREFIX,
- * so `fireforge test browser/base/content/test/hominis` silently also
- * ran the sibling directory `browser/base/content/test/hominis-tiles`
- * (152.0b7 → 153.0b8 source-refresh drill: 1224 tests instead of ~200,
- * with no indication the scope widened).
+ * mozbuild's test resolver matches command-line paths by STRING PREFIX, so
+ * `fireforge test browser/base/content/test/hominis` also runs the sibling
+ * directory `browser/base/content/test/hominis-tiles` — silently, and with
+ * no indication the scope widened.
+ *
+ * FireForge therefore treats a directory argument as meaning EXACTLY that
+ * directory: {@link analyzeTestPathScopes} enumerates the test files of
+ * exactly that directory and dispatches THAT explicit file list to mach,
+ * because a file list cannot prefix-match anything. Normalizing the
+ * directory with a trailing `/` does NOT work — mach still sweeps in the
+ * prefix-named sibling. The prefix-matching sibling directories are still
+ * reported so the command layer can tell the operator what was excluded.
  *
- * FireForge therefore treats a directory argument as meaning EXACTLY
- * that directory: {@link analyzeTestPathScopes} enumerates the test
- * files of exactly that directory and dispatches THAT explicit file
- * list to mach — a file list cannot prefix-match anything. (0.35.0
- * instead normalized the directory with a trailing `/`, assuming the
- * separator makes the prefix match exact; field verification on Firefox
- * 153 showed mach still swept in the prefix-named sibling, so the
- * trailing-slash mechanism was cosmetic and its exclusion echo was
- * wrong.) The prefix-matching sibling directories are still reported so
- * the command layer can tell the operator what was excluded. Note
  * FireForge already rejects non-existent paths up front, so raw
  * prefix-widening was never something an operator could invoke
  * deliberately — it only ever happened by accident.

package/dist/src/core/test-path-scope.js

@@ -2,22 +2,19 @@
 /**
  * Directory-argument scope analysis for `fireforge test`.
  *
- * mozbuild's test resolver matches command-line paths by STRING PREFIX,
- * so `fireforge test browser/base/content/test/hominis` silently also
- * ran the sibling directory `browser/base/content/test/hominis-tiles`
- * (152.0b7 → 153.0b8 source-refresh drill: 1224 tests instead of ~200,
- * with no indication the scope widened).
+ * mozbuild's test resolver matches command-line paths by STRING PREFIX, so
+ * `fireforge test browser/base/content/test/hominis` also runs the sibling
+ * directory `browser/base/content/test/hominis-tiles` — silently, and with
+ * no indication the scope widened.
+ *
+ * FireForge therefore treats a directory argument as meaning EXACTLY that
+ * directory: {@link analyzeTestPathScopes} enumerates the test files of
+ * exactly that directory and dispatches THAT explicit file list to mach,
+ * because a file list cannot prefix-match anything. Normalizing the
+ * directory with a trailing `/` does NOT work — mach still sweeps in the
+ * prefix-named sibling. The prefix-matching sibling directories are still
+ * reported so the command layer can tell the operator what was excluded.
  *
- * FireForge therefore treats a directory argument as meaning EXACTLY
- * that directory: {@link analyzeTestPathScopes} enumerates the test
- * files of exactly that directory and dispatches THAT explicit file
- * list to mach — a file list cannot prefix-match anything. (0.35.0
- * instead normalized the directory with a trailing `/`, assuming the
- * separator makes the prefix match exact; field verification on Firefox
- * 153 showed mach still swept in the prefix-named sibling, so the
- * trailing-slash mechanism was cosmetic and its exclusion echo was
- * wrong.) The prefix-matching sibling directories are still reported so
- * the command layer can tell the operator what was excluded. Note
  * FireForge already rejects non-existent paths up front, so raw
  * prefix-widening was never something an operator could invoke
  * deliberately — it only ever happened by accident.
@@ -137,9 +134,9 @@ export function formatScopeNotice(scope) {
         .map((s) => `${s.path}/ (${s.testFileCount} test file${s.testFileCount === 1 ? '' : 's'})`)
         .join(', ');
     if (scope.testFileCount === 0) {
-        // Fallback dispatch: with nothing to enumerate, the raw directory
-        // form goes to mach, whose prefix matching CAN sweep the siblings in.
-        // Claiming exclusion here would repeat the 0.35.0 mistake.
+        // Fallback dispatch: with nothing to enumerate, the raw directory form
+        // goes to mach, whose prefix matching CAN sweep the siblings in.
+        // Claiming exclusion here would be a lie.
         return (`${requestedDir}/ contains no enumerable test files, so the directory is passed to mach ` +
             `as-is — mach resolves paths by string prefix, which may also select: ${siblings}.`);
     }

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

@@ -53,16 +53,16 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
  * packaging does NOT cover — the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
- * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
- * everything. A scoped list covers a request path when the request equals a
- * covered entry, sits beneath a covered directory entry, or shares a
- * manifest granule with a covered entry ({@link toManifestGranule} — a
- * scoped `test --build` packages the whole manifest directory, so a
- * same-manifest sibling of a covered file is packaged too). Both sides are
- * normalized to forward slashes so Windows-style CLI input cannot defeat
- * the prefix rule (baseline paths are POSIX by convention). A request with
- * no paths is a full-suite run and is never covered by a scoped list — the
- * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ * Coverage semantics: an absent claim and `'full'` cover everything. A
+ * scoped list covers a request path when the request equals a covered entry,
+ * sits beneath a covered directory entry, or shares a manifest granule with
+ * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * packages the whole manifest directory, so a same-manifest sibling of a
+ * covered file is packaged too). Both sides are normalized to forward
+ * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
+ * paths are POSIX by convention). A request with no paths is a full-suite
+ * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
+ * sentinel is returned so the refusal can name it.
  */
 export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
 /**
@@ -88,17 +88,17 @@ export interface StaticComponentsStaleResult {
  * Probes whether any `components.conf` changed since the last FULL
  * `fireforge build` — i.e. since the compiled StaticComponents table was
  * last regenerated. `components.conf` entries bake into compiled code; a
- * scoped `test --build` packages the file but the child process resolves
- * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
- * test bug.
+ * scoped `test --build` packages the file but the child process resolves the
+ * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
- * throws — the probes it composes degrade to verbose lines and empty
- * results on git failure, matching {@link checkStaleBuildForTest}.
+ * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * composes degrade to verbose lines and empty results on git failure,
+ * matching {@link checkStaleBuildForTest}.
  */
 export declare function checkStaticComponentsStale(engineDir: string, baseline: BuildBaseline | undefined): Promise<StaticComponentsStaleResult>;
 /**