@hominis/fireforge 0.33.0 → 0.34.1

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

@@ -32,7 +32,32 @@ export interface HarnessCrashSignature {
 export interface HarnessRunVerdict {
     kind: HarnessRunClassification;
     signature?: HarnessCrashSignature;
+    /**
+     * Set when a non-zero mach exit code was overridden because the output
+     * embeds a completed green summary — the exit code followed harness
+     * noise, not a test result. Callers should surface a note.
+     */
+    greenSummaryOverride?: boolean;
 }
+/**
+ * Strips non-signal noise from captured output before crash-signature
+ * matching: resource-monitor degradation warnings, and traceback blocks
+ * that mach caught itself (telemetry submission tracebacks are printed but
+ * never abort the run). The stripped text is used ONLY as crash evidence —
+ * classification of test results still reads the full output.
+ */
+export declare function stripNonSignalNoise(output: string): string;
+/**
+ * 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, and no real `TEST-UNEXPECTED-*` lines.
+ * 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). Exported for direct unit testing.
+ */
+export declare function hasCompletedGreenSummary(output: string): boolean;
 /**
  * Detects the known harness-crash shapes in captured mach output.
  * Returns undefined for anything that looks like a genuine test result.
@@ -55,7 +80,7 @@ export declare function detectHarnessCrashSignature(output: string): HarnessCras
  */
 export declare function classifyHarnessRun(exitCode: number, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
 /** Builds the operator-facing failure message after retries are exhausted. */
-export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number): string;
+export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`

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

@@ -23,6 +23,15 @@
  * of reporting phantom test failures (or phantom passes).
  */
 const TEST_START_PATTERN = /\bTEST-START\b/;
+/**
+ * Structured-log execution marker (`mach xpcshell-test` mozlog output uses
+ * `TEST_START`/`SUITE_END` with underscores, not the hyphenated
+ * `TEST-START` the browser-chrome dispatch prints).
+ */
+const STRUCTURED_TEST_START_PATTERN = /\bTEST_START\b/;
+const SUITE_END_PATTERN = /\bSUITE_END\b/;
+const GREEN_UNEXPECTED_SUMMARY_PATTERN = /\bUnexpected results:\s*0\b/;
+const NONZERO_UNEXPECTED_SUMMARY_PATTERN = /\bUnexpected results:\s*[1-9]/;
 /**
  * Execution signals emitted by the suite-specific xpcshell dispatch
  * (`mach xpcshell-test`), which does NOT print `TEST-START` lines the way
@@ -47,6 +56,17 @@ const NO_OUTPUT_TIMEOUT_PATTERN = /timed out after \d+ seconds with no output/i;
  * 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.
+const DEGRADED_READING_CRASH_SIGNALS = [
+    /'_DegradedReading' object is not subscriptable/,
+    /'_DegradedReading' object is not iterable/,
+];
 const STARTUP_TRACEBACK_SIGNALS = [
     /AttributeError:.*SystemResourceMonitor/,
     /'SystemResourceMonitor' object has no attribute/,
@@ -55,6 +75,7 @@ const STARTUP_TRACEBACK_SIGNALS = [
     /HOST_VM_INFO64/,
     /\(ipc\/mig\) array not large enough/,
     /psutil\.[A-Za-z]*Error/,
+    ...DEGRADED_READING_CRASH_SIGNALS,
 ];
 function findLine(output, patterns) {
     for (const line of output.split(/\r?\n/)) {
@@ -63,6 +84,91 @@ 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.
+ */
+const NOISE_LINE_PATTERNS = [
+    /\bUserWarning\b/,
+    /psutil failed to run/i,
+    // `_collect failed` chatter is noise on green runs, EXCEPT the
+    // `_DegradedReading` variant: that is the crash evidence for the
+    // "object is not iterable" startup-abort signature above and must
+    // survive stripNonSignalNoise.
+    /_collect failed(?!.*_DegradedReading)/i,
+    /FireForge: host resource monitor degraded/i,
+    /warnings\.warn\(/,
+];
+/** Matches the caught/telemetry context that marks a traceback as benign. */
+const BENIGN_TRACEBACK_CONTEXT = /telemetry|glean/i;
+/**
+ * Strips non-signal noise from captured output before crash-signature
+ * matching: resource-monitor degradation warnings, and traceback blocks
+ * that mach caught itself (telemetry submission tracebacks are printed but
+ * never abort the run). The stripped text is used ONLY as crash evidence —
+ * classification of test results still reads the full output.
+ */
+export function stripNonSignalNoise(output) {
+    const lines = output.split(/\r?\n/);
+    const kept = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (NOISE_LINE_PATTERNS.some((p) => p.test(line)))
+            continue;
+        if (TRACEBACK_PATTERN.test(line)) {
+            // Collect the whole traceback block: the header, indented frame/code
+            // lines, and the trailing unindented exception line.
+            const block = [line];
+            let j = i + 1;
+            for (; j < lines.length; j += 1) {
+                const blockLine = lines[j] ?? '';
+                block.push(blockLine);
+                const isIndented = /^\s/.test(blockLine) || blockLine.trim().length === 0;
+                if (!isIndented)
+                    break; // unindented exception line terminates the block
+            }
+            if (BENIGN_TRACEBACK_CONTEXT.test(block.join('\n'))) {
+                i = j; // drop the whole caught-telemetry traceback block
+                continue;
+            }
+            // A real traceback stays in evidence line-by-line (minus noise lines
+            // already filtered above).
+        }
+        kept.push(line);
+    }
+    return kept.join('\n');
+}
+/**
+ * True when the output carries any execution signal: the browser-chrome
+ * `TEST-START` marker, the structured-log `TEST_START` marker, or the
+ * suite-specific xpcshell result-summary block.
+ */
+function hasExecutionSignal(output) {
+    return (TEST_START_PATTERN.test(output) ||
+        STRUCTURED_TEST_START_PATTERN.test(output) ||
+        hasXpcshellResultSummary(output));
+}
+/**
+ * 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, and no real `TEST-UNEXPECTED-*` lines.
+ * 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). Exported for direct unit testing.
+ */
+export function hasCompletedGreenSummary(output) {
+    return (hasExecutionSignal(output) &&
+        SUITE_END_PATTERN.test(output) &&
+        GREEN_UNEXPECTED_SUMMARY_PATTERN.test(output) &&
+        !NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output) &&
+        realUnexpectedFailureLines(output).length === 0);
+}
 /**
  * True when the captured output carries the suite-specific xpcshell
  * result-summary block, which proves tests executed even though the
@@ -83,13 +189,22 @@ function realUnexpectedFailureLines(output) {
  * Returns undefined for anything that looks like a genuine test result.
  */
 export function detectHarnessCrashSignature(output) {
-    const hasTestStart = TEST_START_PATTERN.test(output);
+    const hasTestStart = hasExecutionSignal(output);
     const realFailures = realUnexpectedFailureLines(output);
-    // Startup traceback cluster (resource monitor / psutil). Real test
-    // failures take precedence: a traceback printed during teardown of a
-    // genuinely failing run must not get the whole run retried.
-    if (TRACEBACK_PATTERN.test(output) && realFailures.length === 0) {
-        const signalLine = findLine(output, STARTUP_TRACEBACK_SIGNALS);
+    // A completed green embedded summary vetoes signature-based crash
+    // classification outright: the suite finished, so any startup-shaped
+    // noise in the same output was non-fatal. (The post-green shutdown
+    // re-entry shape below is exempt — it is deliberately a crash verdict on
+    // an otherwise-green log, keyed on its own explicit markers.)
+    const greenSummaryVeto = hasCompletedGreenSummary(output);
+    // Startup traceback cluster (resource monitor / psutil), scanned over
+    // noise-stripped evidence so degradation warnings and caught telemetry
+    // tracebacks never count. Real test failures take precedence: a
+    // traceback printed during teardown of a genuinely failing run must not
+    // get the whole run retried.
+    const evidence = stripNonSignalNoise(output);
+    if (!greenSummaryVeto && TRACEBACK_PATTERN.test(evidence) && realFailures.length === 0) {
+        const signalLine = findLine(evidence, STARTUP_TRACEBACK_SIGNALS);
         if (signalLine) {
             return { reason: 'harness startup traceback (resource monitor/psutil)', line: signalLine };
         }
@@ -98,7 +213,19 @@ export function detectHarnessCrashSignature(output) {
     // the no-output timeout. A trailing "Passed: 0" summary is part of this
     // shape and must not be read as a result.
     if (!hasTestStart) {
-        const timeoutLine = findLine(output, [NO_OUTPUT_TIMEOUT_PATTERN]);
+        // Startup abort on the degraded-reading fallback family: the `_collect
+        // failed: '_DegradedReading' ...` variant is caught-and-logged (no
+        // Traceback header), so the traceback cluster above never sees it.
+        if (realFailures.length === 0) {
+            const degradedLine = findLine(evidence, DEGRADED_READING_CRASH_SIGNALS);
+            if (degradedLine) {
+                return {
+                    reason: 'degraded resource reading crashed the harness fallback (_DegradedReading)',
+                    line: degradedLine,
+                };
+            }
+        }
+        const timeoutLine = findLine(evidence, [NO_OUTPUT_TIMEOUT_PATTERN]);
         if (timeoutLine) {
             return { reason: 'no-output timeout before any test started', line: timeoutLine };
         }
@@ -133,15 +260,26 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     if (signature) {
         return { kind: 'harness-crash', signature };
     }
-    const ranTests = TEST_START_PATTERN.test(output) || hasXpcshellResultSummary(output);
+    const ranTests = hasExecutionSignal(output);
     if (!ranTests && requestedPaths.length > 0) {
         return { kind: 'no-tests' };
     }
-    return exitCode === 0 ? { kind: 'tests-ran-ok' } : { kind: 'test-failures' };
+    if (exitCode === 0) {
+        return { kind: 'tests-ran-ok' };
+    }
+    // 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.
+    if (hasCompletedGreenSummary(output)) {
+        return { kind: 'tests-ran-ok', greenSummaryOverride: true };
+    }
+    return { kind: 'test-failures' };
 }
 /** Builds the operator-facing failure message after retries are exhausted. */
-export function buildHarnessCrashMessage(signature, attempts) {
-    return (`mach test crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
+export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'mach test') {
+    return (`${commandLabel} crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
         `Detected shape: ${signature.reason}\n` +
         `Evidence line: ${signature.line}\n\n` +
         'This failure mode is environmental (mozlog resource monitor / psutil on macOS, focus-stall ' +

package/dist/src/core/xpcshell-appdir.d.ts

@@ -77,6 +77,13 @@ export declare function parseAppdirFromToml(tomlText: string, key: string): {
  *
  * Special-cases `startPath` itself when it already ends with
  * `xpcshell.toml` — operators sometimes pass a manifest path directly.
+ *
+ * When `startPath` is a DIRECTORY, the walk starts at the directory itself
+ * (checking `<dir>/xpcshell.toml` first) rather than at its parent. Field
+ * report (0.34.0 cycle): a directory whose own manifest is an
+ * `xpcshell.toml` was classified non-xpcshell — the walk began at the
+ * parent, missed the manifest, and `fireforge test <dir>` dispatched to
+ * the mochitest runner, which found no mochitests.
  */
 export declare function findNearestXpcshellManifest(engineDir: string, startPath: string): Promise<string | null>;
 /**

package/dist/src/core/xpcshell-appdir.js

@@ -38,7 +38,7 @@
  * test.ts; we skip injection when `--app-path=` already appears in the
  * forwarded args).
  */
-import { readdir } from 'node:fs/promises';
+import { readdir, stat } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 import { pathExists, readJson, readText } from '../utils/fs.js';
 import { isObject, isString } from '../utils/validation.js';
@@ -110,19 +110,28 @@ function stripQuotes(raw) {
  *
  * Special-cases `startPath` itself when it already ends with
  * `xpcshell.toml` — operators sometimes pass a manifest path directly.
+ *
+ * When `startPath` is a DIRECTORY, the walk starts at the directory itself
+ * (checking `<dir>/xpcshell.toml` first) rather than at its parent. Field
+ * report (0.34.0 cycle): a directory whose own manifest is an
+ * `xpcshell.toml` was classified non-xpcshell — the walk began at the
+ * parent, missed the manifest, and `fireforge test <dir>` dispatched to
+ * the mochitest runner, which found no mochitests.
  */
 export async function findNearestXpcshellManifest(engineDir, startPath) {
     const absStart = resolve(engineDir, startPath);
     if (absStart.toLowerCase().endsWith(`${sep}xpcshell.toml`)) {
         return (await pathExists(absStart)) ? absStart : null;
     }
+    const startIsDirectory = await stat(absStart).then((stats) => stats.isDirectory(), () => false);
     const engineAbs = resolve(engineDir);
     let current = absStart;
-    // First iteration walks down to a directory; subsequent ones walk up.
+    // First iteration resolves the starting directory (the path itself for a
+    // directory argument, its parent for a file); subsequent ones walk up.
     // Cap iterations defensively — a pathological symlink loop would
     // otherwise spin until the call stack overflows.
     for (let i = 0; i < 64; i += 1) {
-        const dir = i === 0 ? dirname(absStart) : dirname(current);
+        const dir = i === 0 ? (startIsDirectory ? absStart : dirname(absStart)) : dirname(current);
         const candidate = join(dir, 'xpcshell.toml');
         if (await pathExists(candidate))
             return candidate;

package/dist/src/types/commands/options.d.ts

@@ -530,6 +530,16 @@ export interface FurnaceRemoveOptions {
 export interface FurnaceCreateOptions {
     /** Component description */
     description?: string;
+    /**
+     * Engine-relative directory the test scaffold writes into, instead of
+     * the default `browser/base/content/test/<binaryName>/` (browser-chrome)
+     * or `browser/base/content/test/<binaryName>-xpcshell/<component>/`
+     * (xpcshell). Must stay under `browser/base/content/test/` so the
+     * manifest registration keeps working. Not supported for
+     * `--test-style=mochikit` (that harness lives in the upstream
+     * toolkit/content/tests/widgets tree).
+     */
+    testDir?: string;
     /** Include Fluent l10n support */
     localized?: boolean;
     /** Register in customElements.js (default: true) */
@@ -614,6 +624,8 @@ export interface WireOptions {
 export interface RegisterOptions {
     dryRun?: boolean;
     after?: string;
+    /** Scaffold a missing manifest (moz.build / xpcshell.toml) and wire the parent chain. */
+    createManifest?: boolean;
 }
 /**
  * Options for the patch delete command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -72,9 +72,9 @@
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.17.1",
+    "knip": "6.23.0",
     "lint-staged": "^17.0.4",
-    "prettier": "^3.7.4",
+    "prettier": "3.9.4",
     "tsx": "^4.7.0",
     "typescript": "~6.0.0",
     "typescript-eslint": "^8.0.0",