@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,147 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * 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` 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 already rejects non-existent paths up front, so raw
- * prefix-widening was never something an operator could invoke on purpose.
- * It only ever happened by accident.
- */
-import { readdir, stat } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
-/** Test implementation files as mozbuild manifests name them. */
-const TEST_FILE_PATTERN = /^(?:browser|test)_.*\.(?:m?js|x?html)$/;
-/**
- * Recursively enumerates test-implementation files under a directory,
- * returned engine-relative and sorted for deterministic dispatch order.
- * Returns [] when the directory cannot be read. The caller then falls
- * back to the directory form and mach owns the failure.
- */
-async function collectTestFiles(dir, relPrefix) {
-    const files = [];
-    let entries;
-    try {
-        entries = await readdir(dir, { withFileTypes: true });
-    }
-    catch {
-        // An unreadable directory contributes no test files to the scope.
-        return [];
-    }
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            files.push(...(await collectTestFiles(join(dir, entry.name), `${relPrefix}${entry.name}/`)));
-        }
-        else if (entry.isFile() && TEST_FILE_PATTERN.test(entry.name)) {
-            files.push(`${relPrefix}${entry.name}`);
-        }
-    }
-    return files.sort();
-}
-/** Probes whether `path` is a directory, without throwing. */
-async function isDirectorySafe(path) {
-    try {
-        return (await stat(path)).isDirectory();
-    }
-    catch {
-        // A path that cannot be stat'd is not a directory for scoping purposes.
-        return false;
-    }
-}
-/**
- * Analyzes one engine-relative test path argument. See the module doc
- * comment for the semantics.
- */
-async function analyzeTestPathScope(engineDir, requestedPath) {
-    const stripped = requestedPath.replace(/\/+$/, '');
-    const absolute = join(engineDir, stripped);
-    if (!(await isDirectorySafe(absolute))) {
-        return {
-            requestedPath,
-            dispatchPaths: [requestedPath],
-            isDirectory: false,
-            testFileCount: 0,
-            siblingPrefixMatches: [],
-        };
-    }
-    const siblingPrefixMatches = [];
-    const base = basename(stripped);
-    const parentRel = dirname(stripped);
-    try {
-        const siblings = await readdir(dirname(absolute), { withFileTypes: true });
-        for (const entry of siblings) {
-            if (!entry.isDirectory())
-                continue;
-            if (entry.name === base || !entry.name.startsWith(base))
-                continue;
-            const siblingRel = parentRel === '.' ? entry.name : `${parentRel}/${entry.name}`;
-            const testFileCount = (await collectTestFiles(join(dirname(absolute), entry.name), `${siblingRel}/`)).length;
-            // A prefix-matching sibling with no test files never surfaces in a
-            // mach run, so listing it would only add noise.
-            if (testFileCount > 0) {
-                siblingPrefixMatches.push({ path: siblingRel, testFileCount });
-            }
-        }
-    }
-    catch {
-        // Unreadable parent: skip the sibling probe. Exactness via the
-        // explicit file list is preserved regardless.
-    }
-    const testFiles = await collectTestFiles(absolute, `${stripped}/`);
-    return {
-        requestedPath,
-        // The explicit file list is what makes the selection exact. An empty
-        // enumeration falls back to the directory form.
-        dispatchPaths: testFiles.length > 0 ? testFiles : [`${stripped}/`],
-        isDirectory: true,
-        testFileCount: testFiles.length,
-        siblingPrefixMatches,
-    };
-}
-/**
- * Analyzes every test path argument of a run.
- *
- * @param engineDir - Path to the engine directory
- * @param requestedPaths - Engine-relative test path arguments
- */
-export async function analyzeTestPathScopes(engineDir, requestedPaths) {
-    const scopes = [];
-    for (const requestedPath of requestedPaths) {
-        scopes.push(await analyzeTestPathScope(engineDir, requestedPath));
-    }
-    return scopes;
-}
-/**
- * Formats the sibling-exclusion notice for one scope, or undefined when
- * nothing needs saying (file arg, or no prefix-matching siblings).
- */
-export function formatScopeNotice(scope) {
-    if (!scope.isDirectory || scope.siblingPrefixMatches.length === 0)
-        return undefined;
-    const requestedDir = scope.requestedPath.replace(/\/+$/, '');
-    const siblings = scope.siblingPrefixMatches
-        .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 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}.`);
-    }
-    return (`Selected exactly ${requestedDir}/ by passing its ${scope.testFileCount} test file${scope.testFileCount === 1 ? '' : 's'} ` +
-        'explicitly to mach (an explicit file list cannot prefix-match a sibling). ' +
-        `Excluded ${scope.siblingPrefixMatches.length} prefix-named sibling director${scope.siblingPrefixMatches.length === 1 ? 'y' : 'ies'}: ${siblings}. ` +
-        'Pass them as separate paths to include them.');
-}

package/dist/src/core/test-profile-files.d.ts

@@ -1,17 +0,0 @@
-/** Stages explicit profile overlays with relative destinations; cleanup belongs to the caller. */
-export interface StagedProfileFiles {
-    root: string;
-    args: string[];
-    env: Record<string, string>;
-}
-/** Prepares profile overlays and browser/port ownership preconditions. */
-export declare function stageProfileFiles(projectRoot: string, files: readonly string[]): Promise<StagedProfileFiles>;
-/** Python startup overlay: allow merging ONLY the explicitly staged profile directories. */
-export declare const PROFILE_MERGE_PYTHON = "\nimport os\nimport shutil\n_fireforge_profile_root = os.environ.get(\"FIREFORGE_PROFILE_MERGE_ROOT\")\nif _fireforge_profile_root and not getattr(shutil.copytree, \"_fireforge_profile_merge\", False):\n    _fireforge_copytree = shutil.copytree\n    def _fireforge_merge_copytree(src, dst, *args, **kwargs):\n        if os.path.realpath(src).startswith(os.path.realpath(_fireforge_profile_root) + os.sep):\n            # Python's recursive calls may supply dirs_exist_ok positionally.\n            if len(args) >= 5:\n                args = args[:4] + (True,) + args[5:]\n            else:\n                kwargs[\"dirs_exist_ok\"] = True\n        return _fireforge_copytree(src, dst, *args, **kwargs)\n    _fireforge_merge_copytree._fireforge_profile_merge = True\n    shutil.copytree = _fireforge_merge_copytree\n";
-/** Classifies the profile setup traceback separately from stale packaging. */
-export declare function classifyProfileArgumentFailure(output: string): {
-    kind: 'harness-arguments';
-    note: string;
-} | undefined;
-/** Cleanup is independent of the harness verdict and cannot hide its primary error. */
-export declare function cleanupProfileFiles(root: string): Promise<void>;

package/dist/src/core/test-profile-files.js

@@ -1,75 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { InvalidArgumentError } from '../errors/base.js';
-import { toError } from '../utils/errors.js';
-import { warn } from '../utils/logger.js';
-/** Prepares profile overlays and browser/port ownership preconditions. */
-export async function stageProfileFiles(projectRoot, files) {
-    const root = await mkdtemp(join(tmpdir(), 'fireforge-profile-overlay-'));
-    const top = new Set();
-    try {
-        for (const file of files) {
-            const separator = file.indexOf('=');
-            const source = file.slice(0, separator);
-            const dest = file.slice(separator + 1).replaceAll('\\', '/');
-            if (separator <= 0 ||
-                !dest ||
-                dest.startsWith('/') ||
-                dest.includes(':') ||
-                dest.split('/').some((part) => !part || part === '.' || part === '..')) {
-                throw new InvalidArgumentError('--profile-file requires source=relative/destination with no traversal.', '--profile-file');
-            }
-            const target = join(root, dest);
-            await mkdir(dirname(target), { recursive: true });
-            await copyFile(resolve(projectRoot, source), target);
-            top.add(dest.split('/')[0] ?? dest);
-        }
-        return {
-            root,
-            args: [...top].map((path) => `--extra-profile-file=${join(root, path)}`),
-            env: { FIREFORGE_PROFILE_MERGE_ROOT: root },
-        };
-    }
-    catch (error) {
-        await cleanupProfileFiles(root);
-        throw error;
-    }
-}
-/** Python startup overlay: allow merging ONLY the explicitly staged profile directories. */
-export const PROFILE_MERGE_PYTHON = `
-import os
-import shutil
-_fireforge_profile_root = os.environ.get("FIREFORGE_PROFILE_MERGE_ROOT")
-if _fireforge_profile_root and not getattr(shutil.copytree, "_fireforge_profile_merge", False):
-    _fireforge_copytree = shutil.copytree
-    def _fireforge_merge_copytree(src, dst, *args, **kwargs):
-        if os.path.realpath(src).startswith(os.path.realpath(_fireforge_profile_root) + os.sep):
-            # Python's recursive calls may supply dirs_exist_ok positionally.
-            if len(args) >= 5:
-                args = args[:4] + (True,) + args[5:]
-            else:
-                kwargs["dirs_exist_ok"] = True
-        return _fireforge_copytree(src, dst, *args, **kwargs)
-    _fireforge_merge_copytree._fireforge_profile_merge = True
-    shutil.copytree = _fireforge_merge_copytree
-`;
-/** Classifies the profile setup traceback separately from stale packaging. */
-export function classifyProfileArgumentFailure(output) {
-    if (!/copyExtraFilesToProfile/.test(output) || !/FileExistsError/.test(output))
-        return undefined;
-    return {
-        kind: 'harness-arguments',
-        note: 'profile directory collision; use --profile-file source=chrome/userChrome.css to merge into the existing profile',
-    };
-}
-/** Cleanup is independent of the harness verdict and cannot hide its primary error. */
-export async function cleanupProfileFiles(root) {
-    try {
-        await rm(root, { recursive: true, force: true });
-    }
-    catch (error) {
-        warn(`Could not remove staged profile files ${root}: ${toError(error).message}`);
-    }
-}

package/dist/src/core/test-raw-log.d.ts

@@ -1,66 +0,0 @@
-/**
- * The mozlog structured ("raw") log of one mach test dispatch.
- *
- * Everything else FireForge reads from a run is human text: the
- * `TEST_START`/`TEST_END` lines and the `Unexpected results:` summary, in two
- * dialects, out of a capture that keeps only its last 2 MB. A gate that
- * wants to name the files a run failed had to regex that text, and agent-
- * quiet mozbuild drops `TEST_START` from it altogether. The raw log is the
- * record the summary itself is computed from: one JSON object per line,
- * with `test_start`, `test_status` and `test_end` actions naming each test
- * by its manifest id.
- *
- * It is requested per dispatch with mozlog's `--log-raw=<path>`, which
- * `mach test`, `mach mochitest` and `mach xpcshell-test` all accept, only
- * when a run asks for per-file results (`--results`, `--shard-size`).
- */
-import type { StartMarkers } from './test-run-completeness.js';
-/** One test file's outcome, from its `test_end` and failing `test_status` records. */
-export interface RawTestResult {
-    /** The test id mozlog reports (a manifest-relative path). */
-    test: string;
-    /** `test_end` status (`OK`, `PASS`, `FAIL`, `ERROR`, `TIMEOUT`, `CRASH`, `SKIP`). */
-    status: string;
-    /** Expected status; equal to `status` when mozlog omitted it. */
-    expected: string;
-    /** True when the file ended unexpectedly or any subtest did. */
-    unexpected: boolean;
-    /** Subtests that reported an unexpected status. */
-    unexpectedSubtests: number;
-    /** Wall time between `test_start` and `test_end`, when both carried a time. */
-    durationMs?: number;
-}
-/** Everything one raw log says about the run. */
-export interface RawTestLog {
-    /** Files in `test_end` order. A started file with no end is not listed. */
-    results: RawTestResult[];
-    /** Start markers for the completeness veto: every `test_start` id. */
-    markers: StartMarkers;
-    /** Started tests that never ended (a crash or a cut-off run). */
-    unfinished: string[];
-}
-/**
- * Parses a mozlog raw log. Unknown actions and malformed lines are skipped,
- * so a log truncated by a crash still yields the files that finished.
- *
- * @param text - The raw log's contents
- */
-export declare function parseRawTestLog(text: string): RawTestLog;
-/**
- * Reads and parses a raw log. Returns undefined when the file is missing or
- * unreadable (the harness never started, or the engine's mach ignored the
- * flag), so callers fall back to the streamed text.
- *
- * @param path - The `--log-raw` destination
- */
-export declare function readRawTestLog(path: string): Promise<RawTestLog | undefined>;
-/**
- * The `--log-raw` destination the operator already forwarded with
- * `--mach-arg`, when it names a file. FireForge then reads that file instead
- * of adding its own flag, so the operator's log is not replaced.
- *
- * @param args - The dispatch's extra mach arguments
- */
-export declare function forwardedRawLogPath(args: readonly string[]): string | undefined;
-/** True when the dispatch arguments already carry any `--log-raw`. */
-export declare function hasForwardedRawLog(args: readonly string[]): boolean;

package/dist/src/core/test-raw-log.js

@@ -1,122 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * The mozlog structured ("raw") log of one mach test dispatch.
- *
- * Everything else FireForge reads from a run is human text: the
- * `TEST_START`/`TEST_END` lines and the `Unexpected results:` summary, in two
- * dialects, out of a capture that keeps only its last 2 MB. A gate that
- * wants to name the files a run failed had to regex that text, and agent-
- * quiet mozbuild drops `TEST_START` from it altogether. The raw log is the
- * record the summary itself is computed from: one JSON object per line,
- * with `test_start`, `test_status` and `test_end` actions naming each test
- * by its manifest id.
- *
- * It is requested per dispatch with mozlog's `--log-raw=<path>`, which
- * `mach test`, `mach mochitest` and `mach xpcshell-test` all accept, only
- * when a run asks for per-file results (`--results`, `--shard-size`).
- */
-import { readFile } from 'node:fs/promises';
-function parseRecord(line) {
-    if (!line.startsWith('{'))
-        return undefined;
-    try {
-        const parsed = JSON.parse(line);
-        return typeof parsed === 'object' && parsed !== null ? parsed : undefined;
-    }
-    catch {
-        // A line cut off by a killed harness is not a record.
-        return undefined;
-    }
-}
-/**
- * Parses a mozlog raw log. Unknown actions and malformed lines are skipped,
- * so a log truncated by a crash still yields the files that finished.
- *
- * @param text - The raw log's contents
- */
-export function parseRawTestLog(text) {
-    const results = [];
-    const started = [];
-    const startTimes = new Map();
-    const subtestFailures = new Map();
-    for (const line of text.split(/\r?\n/)) {
-        const record = parseRecord(line.trim());
-        if (record === undefined || typeof record.test !== 'string')
-            continue;
-        const test = record.test;
-        if (record.action === 'test_start') {
-            started.push(test);
-            if (typeof record.time === 'number')
-                startTimes.set(test, record.time);
-            continue;
-        }
-        if (record.action === 'test_status' && typeof record.expected === 'string') {
-            // mozlog sets `expected` on a status record only when it differs.
-            subtestFailures.set(test, (subtestFailures.get(test) ?? 0) + 1);
-            continue;
-        }
-        if (record.action !== 'test_end' || typeof record.status !== 'string')
-            continue;
-        const expected = typeof record.expected === 'string' ? record.expected : record.status;
-        const unexpectedSubtests = subtestFailures.get(test) ?? 0;
-        const start = startTimes.get(test);
-        results.push({
-            test,
-            status: record.status,
-            expected,
-            unexpected: expected !== record.status || unexpectedSubtests > 0,
-            unexpectedSubtests,
-            ...(start !== undefined && typeof record.time === 'number'
-                ? { durationMs: record.time - start }
-                : {}),
-        });
-    }
-    const ended = new Set(results.map((result) => result.test));
-    return {
-        results,
-        markers: {
-            started,
-            skipped: results.filter((r) => r.status === 'SKIP').map((r) => r.test),
-        },
-        unfinished: started.filter((test) => !ended.has(test)),
-    };
-}
-/**
- * Reads and parses a raw log. Returns undefined when the file is missing or
- * unreadable (the harness never started, or the engine's mach ignored the
- * flag), so callers fall back to the streamed text.
- *
- * @param path - The `--log-raw` destination
- */
-export async function readRawTestLog(path) {
-    try {
-        return parseRawTestLog(await readFile(path, 'utf8'));
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * The `--log-raw` destination the operator already forwarded with
- * `--mach-arg`, when it names a file. FireForge then reads that file instead
- * of adding its own flag, so the operator's log is not replaced.
- *
- * @param args - The dispatch's extra mach arguments
- */
-export function forwardedRawLogPath(args) {
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index] ?? '';
-        const value = arg.startsWith('--log-raw=')
-            ? arg.slice('--log-raw='.length)
-            : arg === '--log-raw'
-                ? args[index + 1]
-                : undefined;
-        if (value !== undefined)
-            return value === '-' ? undefined : value;
-    }
-    return undefined;
-}
-/** True when the dispatch arguments already carry any `--log-raw`. */
-export function hasForwardedRawLog(args) {
-    return args.some((arg) => arg === '--log-raw' || arg.startsWith('--log-raw='));
-}

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

@@ -1,97 +0,0 @@
-/**
- * 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 { 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
- * @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 declare function countStartedFiles(evidence: string | StartMarkers, requestedPaths: readonly string[], authoritative?: boolean): {
-    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;