@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,191 +0,0 @@
-// 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>`.
- *
- * From streamed or captured text, 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. The structured raw log names every test by its
- * manifest id, so a raw log whose starts name none of the requested files
- * ran something else: a `--jobs` instance that read another instance's test
- * list once passed on that instance's file.
- */
-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
- * @param authoritative - The markers come from the raw log, so a run whose
- *   starts name no requested file is counted (as none started) instead of
- *   being left uncounted
- */
-export function countStartedFiles(evidence, requestedPaths, authoritative = false) {
-    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, unless it is the raw log.
-    if (!authoritative && !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, useTracked && tracked.source === 'raw');
-    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,213 +0,0 @@
-import type { BaselineRecorder, 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. */
-    stale: boolean;
-    /**
-     * Engine-relative paths that would have been packaged but appear to have
-     * changed since the baseline. Sorted and deduplicated. Truncated at
-     * {@link STALE_PATHS_LIMIT} entries for rendering. Consult
-     * {@link StaleBuildResult.truncated} to know when to append a `(+N more)`
-     * tail to the warning.
-     */
-    changedPaths: string[];
-    /**
-     * How many paths were dropped from `changedPaths` due to the render cap.
-     * Callers render this as `(+N more)` in the warning body.
-     */
-    truncated: number;
-    /**
-     * The baseline that anchored the diff, or undefined when no previous
-     * successful build exists. A missing baseline is treated as "not stale":
-     * 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
- * `fireforge build`. Returns a summary the `fireforge test` handler renders
- * as an up-front warning when `--build` was not passed. The probe never
- * refuses a malformed persisted baseline. Git failures and a missing baseline
- * degrade to `stale: false` because they provide no comparison anchor.
- *
- * @param projectRoot Root directory of the project.
- * @param engineDir Path to the engine directory.
- */
-export declare function checkStaleBuildForTest(projectRoot: string, engineDir: string): Promise<StaleBuildResult>;
-/**
- * Formats a human-readable warning body from a {@link StaleBuildResult}.
- * Kept separate from the probe so test code can assert on the structured
- * result without matching the rendered copy.
- */
-export declare function formatStaleBuildWarning(result: StaleBuildResult): string;
-/** Result of {@link findCompiledSourcesNewerThanBinary}. */
-export interface StaleCompiledResult {
-    /** Engine-relative compiled sources modified after the binary was linked. Sorted. */
-    paths: string[];
-    /** Engine-relative file that anchored the comparison (the binary or its libxul). */
-    linkedPath: string;
-    /** When that file was last written. */
-    linkedAt: Date;
-}
-/**
- * Changed compiled sources (C++, Rust, IDL, WebIDL, IPDL, StaticPrefList
- * YAML, …) whose mtime is newer than the launchable build's last link.
- * `mach build faster` compiles none of them, so such a run tests the
- * binary from before the edit, which reads as a failed fix rather than a
- * stale build. Candidates are the engine paths changed since the baseline
- * plus every workdir edit; a fork's persistent patch diff is older than any
- * build that followed it, so only genuine post-build edits remain.
- * Returns undefined when there is nothing to compare against (no
- * launchable binary).
- *
- * @param engineDir - Absolute engine directory
- * @param baseline - Last-build baseline, when one exists
- * @param launchablePath - Engine-relative launchable binary path
- */
-export declare function findCompiledSourcesNewerThanBinary(engineDir: string, baseline: BuildBaseline | undefined, launchablePath: string | undefined): Promise<StaleCompiledResult | undefined>;
-/**
- * The `stale-compiled` refusal (or, under `--allow-stale-build`, warning).
- *
- * @param result - A non-empty {@link StaleCompiledResult}
- */
-export declare function formatStaleCompiledRefusal(result: StaleCompiledResult): string;
-/**
- * The notice that explains why a `test --build` pre-test build escalated
- * to a full `mach build` for stale compiled sources.
- *
- * @param result - A non-empty {@link StaleCompiledResult}
- */
-export declare function formatStaleCompiledBuildNotice(result: StaleCompiledResult): string;
-/**
- * Sentinel returned by {@link findUncoveredRequestPaths} when a full-suite
- * request (no paths) is checked against a scoped coverage record.
- */
-export declare const FULL_SUITE_REQUEST = "(entire suite)";
-/**
- * Compares the requested test paths against the packaged runtime's coverage
- * claim recorded in the baseline. Returns the requested paths the recorded
- * packaging does not cover: the runs that would dispatch against missing
- * `_tests/` support fixtures and hang rather than fail.
- *
- * Coverage semantics: an absent claim and `'full'` cover everything. A
- * scoped list covers a request path when the request equals a covered entry
- * or sits beneath it. A file claim never widens to its containing directory:
- * sibling files can belong to different manifests or harnesses, and a dot in
- * a directory name does not make it a file. 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, so the
- * {@link FULL_SUITE_REQUEST} sentinel is returned and the refusal can name
- * it.
- */
-export declare function findUncoveredRequestPaths(coverage: TestPackagingCoverage | undefined, requestedPaths: readonly string[]): string[];
-/**
- * Test manifests changed since the recorded build that sit in (or above)
- * the directory of an uncovered request path, i.e. the manifests that
- * explain why this run needs coverage the build never claimed.
- *
- * Best-effort: a probe failure returns an empty list, so the refusal
- * degrades to exactly its previous text rather than failing differently.
- *
- * @param engineDir - Absolute engine directory
- * @param baseline - Last successful build's baseline
- * @param uncovered - Uncovered request paths from
- *   {@link findUncoveredRequestPaths}
- * @returns Engine-relative manifest paths, capped at
- *   {@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;
-    /**
-     * Who wrote the record and when, so a run whose coverage a peer's scoped
-     * build replaced can tell whose build that was.
-     */
-    recordedBy?: string | undefined;
-    builtAt?: string | undefined;
-    recorder?: BaselineRecorder | undefined;
-    /** Whether the recorder's process is still running (it may still be using the packaging). */
-    recorderAlive?: boolean | undefined;
-}
-/**
- * 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[], 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. */
-    stale: boolean;
-    /**
-     * Engine-relative `components.conf` paths changed since the last full
-     * build. Sorted, and not capped. {@link formatStaticComponentsRefusal}
-     * applies the render cap.
-     */
-    changedManifests: string[];
-}
-/**
- * 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.
- *
- * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * 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 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>;
-/**
- * Formats the refusal shown when a run would dispatch against a stale
- * compiled StaticComponents table. Same probe/copy split as
- * {@link formatStaleBuildWarning} so tests can pin structure and wording
- * independently.
- */
-export declare function formatStaticComponentsRefusal(changedManifests: string[]): string;
-/**
- * Formats the post-mutation advisory printed by `fireforge reset` /
- * `fireforge import` when `components.conf` diverged from the last full
- * build. Same probe as {@link formatStaticComponentsRefusal},
- * different moment: this fires at mutation time so the operator learns a
- * full build is needed before the next gate run refuses.
- */
-export declare function formatPostMutationStaticComponentsWarning(changedManifests: string[]): string;
-/**
- * Post-mutation advisory used by `fireforge reset` / `fireforge import`:
- * warns (never throws, never blocks) when `components.conf` now differs
- * from the last full-build anchor. Silently skipped when no baseline or
- * anchor exists, or when any probe fails.
- */
-export declare function warnIfStaticComponentsStale(projectRoot: string, engineDir: string): Promise<void>;