@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,251 +0,0 @@
-/**
- * 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
- * test results:
- *
- *  - startup crashes from the mozlog resource monitor on macOS
- *    (`AttributeError: 'SystemResourceMonitor' object has no attribute
- *    '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.
- *
- * Classification therefore keys on `TEST-START` presence, so 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).
- */
-export type { HarnessCrashSignature } from './test-harness-signature.js';
-import { type HarnessCrashSignature, type IncompleteRunEvidence } from './test-harness-signature.js';
-export { buildHarnessCrashMessage } from './test-harness-infra.js';
-export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
-/** How a completed harness run should be interpreted. */
-export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'harness-arguments' | 'no-tests';
-/** Numeric counts parsed from the harness's embedded result summary. */
-export interface HarnessSummaryCounts {
-    /** Total checks the suite ran (`Ran N checks`), when the summary prints one. */
-    checks?: number;
-    /** Unexpected-result count (`Unexpected results: N`), when the summary prints one. */
-    unexpected?: number;
-}
-/** Result of {@link classifyHarnessRun}. */
-export interface HarnessRunVerdict extends HarnessSummaryCounts {
-    kind: HarnessRunClassification;
-    signature?: HarnessCrashSignature;
-    /** First concrete test-failure evidence line, when available. */
-    realFailureLine?: string;
-    /**
-     * First N `TEST-UNEXPECTED-*` lines verbatim, each with its trailing
-     * assertion/diff context lines (`Got …` / `Expected …` / Assert diff /
-     * stack head). Lets the failure summary echo the actual assertion so a
-     * one-off failure that does not reproduce is still diagnosable after the
-     * fact. Only set on `test-failures` verdicts when such lines exist.
-     */
-    realFailureBlocks?: string[];
-    /** Harness noise seen in the same output as a real test failure. */
-    secondaryHarnessSignature?: HarnessCrashSignature;
-    /**
-     * Set when a non-zero mach exit code was overridden because the output
-     * embeds a completed green summary, so the exit code followed harness
-     * noise, not a test result. Callers should surface a note.
-     */
-    greenSummaryOverride?: boolean;
-    /**
-     * Set when the output embeds a green-looking summary that was rejected:
-     * crash or truncation evidence proves the suite never completed, so the
-     * "green" counts only cover the files that ran before the run died. A
-     * SIGSEGV at the second of eight files leaves a `Passed: 2 / Failed: 0`
-     * summary that reads as a pass. Callers must fail the run and surface the
-     * evidence.
-     */
-    greenSummaryRejected?: GreenSummaryRejection;
-    /**
-     * Short parenthetical appended to the `FIREFORGE-VERDICT:` line when the
-     * bare status would under-describe the run: currently "harness teardown
-     * noise ignored" and the headed display-asleep stall. Advisory text
-     * only. The status and reason keys are unaffected.
-     */
-    note?: string;
-    /**
-     * Set when a mach-exit-0 run was refused its pass because it is
-     * incomplete or reported unexpected results. See
-     * `test-run-completeness.ts`.
-     */
-    incomplete?: IncompleteRunEvidence;
-}
-/** Why a green-looking embedded summary was not trusted. */
-export interface GreenSummaryRejection {
-    /** Crash-marker evidence line (mozcrash / signal kill), if any. */
-    crashLine?: string;
-    /** Requested test files with no `TEST_START`/`TEST-START` line at all. */
-    neverStarted: string[];
-    /** Files whose `TEST_START` has no matching end marker. */
-    neverEnded: string[];
-}
-export declare const SHUTDOWN_REENTRY_PATTERN: RegExp;
-/**
- * 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;
-/**
- * Finds the first crash-marker line in the RAW output (see
- * {@link CRASH_MARKER_PATTERNS}), or undefined when the run shows no
- * crash evidence. Exported for direct unit testing.
- */
-export declare function findCrashMarkerLine(output: string): string | undefined;
-/**
- * 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 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 declare function hasCompletedGreenSummary(output: string): boolean;
-/** Basename shape of a mozbuild-manifest test implementation file. */
-export declare const TEST_FILE_BASENAME_PATTERN: RegExp;
-/**
- * Start/end execution markers, both log dialects: the structured mozlog
- * `TEST_START`/`TEST_END` pair and the human browser-chrome
- * `TEST-START`/`TEST-OK` pair. `TEST-UNEXPECTED-*` end shapes are
- * irrelevant here, since any such line already fails the green-summary check
- * before completeness is consulted.
- */
-export declare const START_MARKER_PATTERN: RegExp;
-/**
- * Cross-checks run completeness against the requested test files: every
- * requested file must produce a start marker, and every started test must
- * produce an end marker (the harness emits both even for failing files).
- *
- * Ends are paired with starts positionally (last open start is closed by
- * the next end), not by filename: the xpcshell dialect's `TEST_END: Test
- * PASS` lines do not name the file. Requested paths that are not
- * test-file-shaped (directories, manifests) are skipped for the
- * never-started check. The start/end pairing scan covers them regardless.
- * Exported for direct unit testing.
- */
-export declare function analyzeTestCompleteness(output: string, requestedPaths: readonly string[]): {
-    neverStarted: string[];
-    neverEnded: string[];
-};
-/**
- * Collects the first `limit` TEST-UNEXPECTED-* lines with their trailing
- * assertion/diff context, one string per block. The shutdown-reentry
- * artifact is excluded (it is harness noise, not a test result). When more
- * than `limit` blocks exist, a final `…(+N more …)` note is appended so the
- * operator knows the echo was truncated. Pure. Exported for unit tests.
- */
-export declare function collectUnexpectedFailureBlocks(output: string, limit?: number): string[];
-/**
- * Detects the known harness-crash shapes in captured mach output.
- * Returns undefined for anything that looks like a genuine test result.
- */
-export declare function detectHarnessCrashSignature(output: string): HarnessCrashSignature | undefined;
-/**
- * Classifies a completed harness run. The decision tree, in order:
- *
- * 1. A recognized crash signature wins regardless of exit code (the
- *    shutdown re-entry shape exits non-zero on an otherwise green run,
- *    and the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No execution signal with explicit paths requested means no test ran.
- *    A mochitest server that failed to start explains that, and is a
- *    retriable infrastructure failure (`harness-crash` with
- *    `reason=server-startup` on the verdict line). Otherwise it is
- *    `no-tests`, even when the exit code is zero. The execution signal is
- *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
- *    or the suite-specific xpcshell result-summary block (the xpcshell
- *    dispatch prints no `TEST-START`). Bare `Passed:`/`Failed:` summary
- *    lines are still not trusted as evidence of execution.
- * 3. Exit code zero with tests started is a pass. Anything else is a
- *    test failure for the regular diagnosis chain, except a non-zero
- *    exit whose embedded summary completed green and shows no crash
- *    marker and no truncated/never-started requested file, which is a
- *    pass with a `greenSummaryOverride` note (harness noise owns the
- *    exit code). A green-shaped summary with such evidence is rejected
- *    (`greenSummaryRejected`) and fails.
- */
-export declare function classifyHarnessRun(exitCode: number, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
-/**
- * Parses the numeric counts from the harness's embedded result summary
- * (`Ran N checks` / `Unexpected results: N`). The last occurrence of each
- * wins: a multi-suite run prints one summary per suite and the final one
- * covers the aggregate the operator sees. Absent counts are omitted (the
- * `FIREFORGE-VERDICT:` contract: an absent key means "summary did not
- * print it", never zero).
- */
-export declare function extractSummaryCounts(output: string): HarnessSummaryCounts;
-/**
- * Formats the machine-readable `FIREFORGE-VERDICT:` line: the stable,
- * greppable last line every `fireforge test` run prints so harness-verdict
- * consumers stop regexing mach internals. The status follows this
- * classifier, never the raw exit code: a crash-classified run says
- * `FAIL reason=crash` even at exit 0, and a green-summary-override pass
- * says `PASS` despite a non-zero mach exit. Count keys are omitted when
- * the embedded summary did not print them. Sharded aggregate lines carry
- * a trailing `shards=<passed>/<total>` instead of counts (counts belong
- * to a single embedded suite summary).
- */
-export declare function formatFireforgeVerdictLine(verdict: HarnessRunVerdict, shards?: {
-    passed: number;
-    total: number;
-    failed?: readonly string[];
-}): string;
-/**
- * Builds the operator-facing failure message for a green-looking summary
- * that was rejected on crash or truncation evidence (never trusted as a
- * pass, regardless of how green the embedded counts look).
- */
-export declare function buildGreenSummaryRejectedMessage(rejection: GreenSummaryRejection, exitCode: number): string;
-/**
- * True when a harness run died on SIGSEGV having produced no test evidence
- * whatsoever.
- *
- * `xpcshell return code: -11` with zero output is the signature of an
- * `.sys.mjs` that a packaged module imports but whose `EXTRA_JS_MODULES`
- * registration never landed: the module loader faults before any logging
- * exists, so there is no import error, no stack, no test output, just a
- * dead process. It is indistinguishable from a genuine product crash
- * unless someone names the cause.
- *
- * "Produced no evidence" is semantic rather than a byte
- * budget: no execution signal, no real failure line, and no mozcrash
- * marker. A run that got far enough to start a test, report a failure, or
- * leave a crash dump has evidence of its own, and the regular diagnosis
- * chain reads it. This branch is only for the case where there is
- * nothing else to say.
- *
- * Pure. Exported for direct unit testing.
- *
- * @param exitCode - The harness process exit code
- * @param output - Combined stdout/stderr from the run
- */
-export declare function isSilentSegfault(exitCode: number, output: string): boolean;
-/**
- * Names the known cause of a silent SIGSEGV so the operator checks
- * moz.build registration FIRST instead of paying a full rebuild cycle to
- * rediscover it.
- *
- * @param exitCode - The harness process exit code
- * @param requestedPaths - Test paths the run requested
- */
-export declare function buildSilentSegfaultMessage(exitCode: number, requestedPaths: readonly string[]): string;
-/**
- * Builds the message for a run that produced no `TEST-START` despite
- * requesting paths, including exit-code-zero runs whose `Passed: 0`
- * summary would otherwise read as a silent false green.
- */
-export declare function buildNoTestsRanMessage(exitCode: number, requestedPaths: readonly string[]): string;