@hominis/fireforge 0.15.6 → 0.15.8

package/dist/src/core/smoke-patterns.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared regex library for `fireforge run --smoke-exit`. Used by the smoke
+ * runner to decide whether a console line from the real chrome counts as a
+ * runtime error. Kept separate from the runner so the patterns can be
+ * exercised in isolation and amended without touching process-group logic.
+ *
+ * Matching is anchored at the start of the line (`^`) on purpose: a runtime
+ * error leaves a canonical prefix that Firefox's logging layer prints at
+ * column zero. Embedded mentions of the same string inside an unrelated
+ * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
+ * the prefix and should not trip the scanner.
+ */
+/**
+ * Line prefixes that signal an actual runtime error in a Firefox chrome
+ * process. A hit on any of these patterns is a smoke failure unless the
+ * line also matches the caller-supplied allowlist.
+ *
+ * Additions here should be conservative — false positives turn every
+ * smoke run into noise for operators and every CI run into flake.
+ */
+export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
+/**
+ * Returns `true` when `line` matches any pattern in
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * allowlisted hits separately from raw error matches for its summary.
+ */
+export declare function matchesSmokeError(line: string): boolean;
+/**
+ * Returns `true` when `line` matches any regex in `allow`. Safe to call
+ * with an empty allowlist (always returns `false`).
+ */
+export declare function matchesAllowlist(line: string, allow: readonly RegExp[]): boolean;
+/**
+ * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * lines and `#`-prefixed comments are skipped. Each remaining line is
+ * compiled as a RegExp. A bad pattern throws immediately — better to fail
+ * fast at CLI parse time than to silently let a typo match nothing.
+ */
+export declare function compileAllowlistFromFile(body: string, sourcePath: string): RegExp[];
+/**
+ * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
+ * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.
+ */
+export declare function compileAllowlistFromStrings(sources: readonly string[]): RegExp[];

package/dist/src/core/smoke-patterns.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared regex library for `fireforge run --smoke-exit`. Used by the smoke
+ * runner to decide whether a console line from the real chrome counts as a
+ * runtime error. Kept separate from the runner so the patterns can be
+ * exercised in isolation and amended without touching process-group logic.
+ *
+ * Matching is anchored at the start of the line (`^`) on purpose: a runtime
+ * error leaves a canonical prefix that Firefox's logging layer prints at
+ * column zero. Embedded mentions of the same string inside an unrelated
+ * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
+ * the prefix and should not trip the scanner.
+ */
+/**
+ * Line prefixes that signal an actual runtime error in a Firefox chrome
+ * process. A hit on any of these patterns is a smoke failure unless the
+ * line also matches the caller-supplied allowlist.
+ *
+ * Additions here should be conservative — false positives turn every
+ * smoke run into noise for operators and every CI run into flake.
+ */
+export const SMOKE_ERROR_PATTERNS = [
+    // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
+    /^\s*JavaScript error:/i,
+    // Some log paths prefix browser-console `console.error(...)` with the literal label below.
+    /^\s*console\.error:/i,
+    // Older bracketed-prefix variant still seen in some chrome logs / test runs.
+    /^\s*\[JavaScript (Error|Warning)\]/i,
+    // IPC-layer fatal assertions — Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
+    /^\s*###!!! \[Parent\]/,
+];
+/**
+ * Returns `true` when `line` matches any pattern in
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * allowlisted hits separately from raw error matches for its summary.
+ */
+export function matchesSmokeError(line) {
+    for (const pattern of SMOKE_ERROR_PATTERNS) {
+        if (pattern.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Returns `true` when `line` matches any regex in `allow`. Safe to call
+ * with an empty allowlist (always returns `false`).
+ */
+export function matchesAllowlist(line, allow) {
+    for (const pattern of allow) {
+        if (pattern.test(line)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * lines and `#`-prefixed comments are skipped. Each remaining line is
+ * compiled as a RegExp. A bad pattern throws immediately — better to fail
+ * fast at CLI parse time than to silently let a typo match nothing.
+ */
+export function compileAllowlistFromFile(body, sourcePath) {
+    const lines = body.split(/\r?\n/);
+    const compiled = [];
+    lines.forEach((raw, index) => {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            return;
+        try {
+            compiled.push(new RegExp(line));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
+                cause: error,
+            });
+        }
+    });
+    return compiled;
+}
+/**
+ * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
+ * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.
+ */
+export function compileAllowlistFromStrings(sources) {
+    const compiled = [];
+    sources.forEach((source, index) => {
+        try {
+            compiled.push(new RegExp(source));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
+        }
+    });
+    return compiled;
+}
+//# sourceMappingURL=smoke-patterns.js.map

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

@@ -0,0 +1,42 @@
+import type { BuildBaseline } from './build-baseline.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;
+}
+/**
+ * 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
+ * throws; git failures and a missing baseline both degrade to `stale: false`
+ * so a broken probe cannot block a test run.
+ *
+ * @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;

package/dist/src/core/test-stale-check.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Stale-build preflight for `fireforge test`.
+ *
+ * Without this preflight, an operator who edits engine chrome / packaged
+ * resources (`jar.mn` entries, `.xhtml`/`.mjs`/`.css` under chrome trees,
+ * pref files) and then runs `fireforge test <path>` only discovers the
+ * build is stale AFTER xpcshell / mach test starts and errors out with
+ * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI
+ * — which reads as a test bug, not a rebuild prompt. The motivating case
+ * was scaffolding a new top-level chrome document + BrowserGlue-style
+ * xpcshell test: the test file existed, the manifests were registered,
+ * but `dist/` still held the pre-edit bundle and chrome URIs resolved
+ * to nothing.
+ *
+ * This preflight diffs engine HEAD (or workdir) against the last-build
+ * baseline (`.fireforge/last-build.json`), filters to paths that imply
+ * packaging, and returns a compact summary. `fireforge test` prints a
+ * warning up-front so the operator sees "you edited X, Y, Z since the
+ * last build — rerun with `--build` to refresh" BEFORE mach test
+ * launches. Detection stays advisory (warn-only) because a fork that
+ * rebuilds out-of-band (a separate `./mach build` invocation, an IDE
+ * plugin, etc.) can legitimately have a fresh `dist/` with no
+ * FireForge-recorded baseline update.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { isPackageablePath } from './build-audit.js';
+import { readBuildBaseline } from './build-baseline.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/** Cap on the number of changed paths rendered inline. */
+const STALE_PATHS_LIMIT = 10;
+/**
+ * Collects engine paths that changed since the baseline SHA plus any
+ * workdir modifications. Mirrors the helper inside `build-prepare.ts` but
+ * is kept separate so the test-side preflight does not need to pull in
+ * the full build-prepare dependency graph (mozconfig generation, furnace
+ * apply hooks, …).
+ */
+async function collectChangedEnginePaths(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline.engineHeadSha) {
+        try {
+            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of diff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Stale-build preflight: could not diff engine against baseline — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            for (const untracked of await getUntrackedFiles(engineDir)) {
+                collected.add(untracked);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Stale-build preflight: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected];
+}
+/**
+ * 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
+ * throws; git failures and a missing baseline both degrade to `stale: false`
+ * so a broken probe cannot block a test run.
+ *
+ * @param projectRoot Root directory of the project.
+ * @param engineDir Path to the engine directory.
+ */
+export async function checkStaleBuildForTest(projectRoot, engineDir) {
+    const baseline = await readBuildBaseline(projectRoot);
+    if (!baseline) {
+        return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
+    }
+    const changed = await collectChangedEnginePaths(engineDir, baseline);
+    const packageable = changed.filter((path) => isPackageablePath(path)).sort();
+    if (packageable.length === 0) {
+        return { stale: false, changedPaths: [], truncated: 0, baseline };
+    }
+    const head = packageable.slice(0, STALE_PATHS_LIMIT);
+    const truncated = Math.max(0, packageable.length - head.length);
+    return { stale: true, changedPaths: head, truncated, baseline };
+}
+/**
+ * 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 function formatStaleBuildWarning(result) {
+    const tail = result.truncated > 0 ? `, … (+${result.truncated} more)` : '';
+    const list = result.changedPaths.join(', ') + tail;
+    return (`Engine tree has changed since the last successful fireforge build (${list}).\n` +
+        'The current obj-*/dist/ bundle may not reflect those edits. If your test reads ' +
+        'packaged chrome / jar.mn resources, rerun with "fireforge test --build" (or ' +
+        '"fireforge build --ui") first. Passing --build skips this check.');
+}
+//# sourceMappingURL=test-stale-check.js.map

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

@@ -0,0 +1,143 @@
+/**
+ * Auto-injects `--app-path=<abs>` into `mach test` invocations whose nearest
+ * xpcshell.toml sets `firefox-appdir = "browser"` (or `<appname>-appdir = …`)
+ * but whose `appname` is not `firefox`.
+ *
+ * ## Why this exists
+ *
+ * The upstream xpcshell harness computes the manifest key for the appdir
+ * override as `mozInfo["appname"] + "-appdir"`. On a stock Firefox build the
+ * key is `firefox-appdir`, so the very common `firefox-appdir = "browser"`
+ * directive is honoured. On a rebranded fork (appname=`hominis`,
+ * `mybrowser`, …) the harness looks for `hominis-appdir` / `mybrowser-appdir`
+ * — the literal `firefox-appdir` line is silently ignored, `appPath` falls
+ * back to `xrePath`, and every `resource:///modules/…` import throws
+ * `Failed to load resource:///modules/<name>.sys.mjs` because xpcshell now
+ * resolves the `resource:///` prefix one level above the real app root.
+ *
+ * ## Strategy
+ *
+ * 1. For each test path the operator handed us, find the nearest
+ *    `xpcshell.toml`. If none exists, the test is not an xpcshell test and
+ *    nothing to inject.
+ * 2. Read the manifest's `[DEFAULT]` section. Look for `<appname>-appdir`
+ *    first — if present, the harness already finds it and there's nothing to
+ *    do. Fall back to `firefox-appdir`. This ordering matches upstream
+ *    precedence and avoids overriding an operator who already migrated.
+ * 3. If only `firefox-appdir` is present and `appname != "firefox"`, compute
+ *    the absolute app dir path against the active `obj-X/dist` tree
+ *    (probing `dist/bin/<value>` first, then any `dist/<bundle>.app/Contents/
+ *    Resources/<value>` for the macOS packaged layout) and return it as
+ *    the value to pass to `--app-path`.
+ * 4. If multiple test paths disagree on the resolved value (e.g. one
+ *    manifest sets `browser`, another sets `xulrunner`), refuse injection
+ *    and return null — the operator can drop down to `--mach-arg`.
+ *
+ * Operator escape hatches: `--mach-arg=--app-path=…` always wins (handled in
+ * test.ts; we skip injection when `--app-path=` already appears in the
+ * forwarded args).
+ */
+/**
+ * Result of attempting to resolve the auto-injected `--app-path` value.
+ * Carries enough context for the caller to log a useful info line and for
+ * the diagnostic hint to know whether an injection was attempted.
+ */
+export interface AppdirResolveResult {
+    /** Absolute path to the app dir. Pass as `--app-path=<value>`. */
+    appPath: string;
+    /** Manifest the value was sourced from. Used for the info log. */
+    manifestPath: string;
+    /** Manifest key (e.g. `firefox-appdir`) that triggered the injection. */
+    key: string;
+    /** Relative appdir from the manifest (e.g. `browser`). */
+    relativeAppdir: string;
+}
+/**
+ * `[DEFAULT]` section parser shaped to the narrow case we need: pull a
+ * single key/value out without depending on a real TOML parser. Avoids
+ * pulling a TOML dep into the test path for a one-shot lookup.
+ *
+ * Accepts:
+ *  - Single- or double-quoted values
+ *  - Whitespace either side of `=`
+ *  - Continuation comments (`#` or `;`) at the end of the line
+ *  - Bare unquoted bareword values (e.g. `firefox-appdir = browser`) — some
+ *    operators omit the quotes and the harness honours either form.
+ *
+ * Returns `undefined` when the key is absent or sits outside `[DEFAULT]`.
+ */
+export declare function parseAppdirFromToml(tomlText: string, key: string): {
+    value: string;
+    lineIndex: number;
+} | undefined;
+/**
+ * Walks up from `startPath` (a file or directory under `engineDir`) and
+ * returns the absolute path of the first sibling `xpcshell.toml` found.
+ * Stops at `engineDir` (inclusive) and returns null on miss.
+ *
+ * Special-cases `startPath` itself when it already ends with
+ * `xpcshell.toml` — operators sometimes pass a manifest path directly.
+ */
+export declare function findNearestXpcshellManifest(engineDir: string, startPath: string): Promise<string | null>;
+/**
+ * Reads `<objDir>/mozinfo.json` for the active app name. Returns
+ * `"firefox"` when mozinfo cannot be read or the field is missing — that
+ * is the safe default because it matches stock Firefox behaviour and
+ * means the resolver will not inject anything (the manifest's
+ * `firefox-appdir` value WILL be honoured by the upstream harness when
+ * appname is firefox).
+ */
+export declare function readMozinfoAppname(objDirPath: string): Promise<string>;
+/**
+ * Probes the obj-dir's `dist/` subtree for the absolute path that the
+ * harness would have computed if the manifest key had been honoured.
+ * Returns null when no candidate exists — better to skip injection
+ * silently than to point the harness at a path that doesn't exist
+ * (which fails with a different error than the original `firefox-appdir`
+ * symptom and confuses triage).
+ *
+ * Probe order matches the on-disk layouts FireForge supports today:
+ *  1. `<objDir>/dist/bin/<value>` — Linux primary, also macOS via the
+ *     `dist/bin -> dist/<App>.app/Contents/MacOS/` symlink.
+ *  2. `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` — macOS
+ *     packaged layout, where `dist/bin/` may not exist as a directory.
+ */
+export declare function resolveAbsoluteAppPath(objDirAbs: string, relativeAppdir: string): Promise<string | null>;
+/**
+ * Outcome carrier for {@link resolveXpcshellAppdirArg}. Distinguishes the
+ * three "did nothing" cases so callers can shape diagnostics:
+ *  - `none`: no manifest under any test path needs injection.
+ *  - `mismatch`: at least two manifests resolved to different values; we
+ *    refuse to guess which one the operator meant.
+ *  - `unresolved`: the manifest asks for `firefox-appdir = "<value>"` but
+ *    no `dist/` candidate exists for that value.
+ *  - `injected`: the absolute path to pass via `--app-path=`.
+ */
+export type XpcshellAppdirOutcome = {
+    kind: 'none';
+} | {
+    kind: 'mismatch';
+    values: string[];
+} | {
+    kind: 'unresolved';
+    relativeAppdir: string;
+    manifestPath: string;
+} | {
+    kind: 'injected';
+    result: AppdirResolveResult;
+};
+/**
+ * Top-level resolver. Walks every test path, reads the nearest
+ * xpcshell.toml, and returns the single absolute path to inject (or a
+ * structured "no injection" outcome). Never throws — every fs / parse
+ * error is folded into a `none` outcome so the test command always falls
+ * through to the diagnostic hint instead of dying inside a helper.
+ */
+export declare function resolveXpcshellAppdirArg(engineDir: string, testPaths: readonly string[], objDirName: string): Promise<XpcshellAppdirOutcome>;
+/**
+ * Returns true when the operator already passed `--app-path=` (or its
+ * `--app-path <value>` two-token form) through `--mach-arg`. Used by the
+ * test command to skip auto-injection so the operator override always
+ * wins.
+ */
+export declare function operatorAlreadySetAppPath(extraArgs: readonly string[]): boolean;