@hominis/fireforge 0.15.6 → 0.15.8

package/dist/src/commands/run.js

@@ -1,14 +1,36 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, run } from '../core/mach.js';
-import { GeneralError } from '../errors/base.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, run, runMachSmoke, } from '../core/mach.js';
+import { compileAllowlistFromFile, compileAllowlistFromStrings, matchesAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { ExitCode } from '../errors/codes.js';
+import { SmokeRunError } from '../errors/run.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, removeDir, removeFile } from '../utils/fs.js';
-import { info, intro, verbose } from '../utils/logger.js';
+import { info, intro, verbose, warn } from '../utils/logger.js';
+import { pickDefined } from '../utils/options.js';
+/**
+ * Exit code returned by smoke-run mode when the captured console stream
+ * produced one or more error lines that did NOT match the operator's
+ * allowlist.
+ */
+export const SMOKE_EXIT_FAILURE = ExitCode.SMOKE_EXIT_FAILURE;
+/**
+ * Exit code returned by smoke-run mode when the browser itself exited
+ * with a non-clean status before the smoke window elapsed — i.e. a
+ * launch-side failure we could NOT observe as a console error line
+ * (crash before console wiring, missing profile, etc.).
+ */
+export const SMOKE_LAUNCH_FAILURE = ExitCode.SMOKE_LAUNCH_FAILURE;
+/** Recommendation surfaced when the smoke window is shorter than a typical cold start. */
+const SMOKE_COLD_START_THRESHOLD_MS = 30_000;
+/** Maximum number of unallowed error lines to surface in the terminal summary. */
+const SMOKE_UNALLOWED_PREVIEW_MAX = 10;
 /**
  * Cleans the dev profile to prevent stale-state startup failures.
  *
@@ -50,7 +72,7 @@ async function cleanDevProfile(engineDir) {
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
  */
-export async function runCommand(projectRoot) {
+export async function runCommand(projectRoot, options = {}) {
     intro('FireForge Run');
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
@@ -76,6 +98,10 @@ export async function runCommand(projectRoot) {
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures
     await cleanDevProfile(paths.engine);
+    if (options.smokeExit !== undefined) {
+        await runSmokeExit(paths.engine, options);
+        return;
+    }
     info('Launching browser...\n');
     const exitCode = await run(paths.engine);
     // Exit-code whitelist:
@@ -89,13 +115,182 @@ export async function runCommand(projectRoot) {
         throw new BuildError(`Browser exited with code ${exitCode}`, 'mach run');
     }
 }
+/**
+ * Drives the `--smoke-exit` launch path. Runs the browser under
+ * {@link runMachSmoke}, scans the merged console stream for error-class
+ * lines against the operator-supplied allowlist, and applies the smoke
+ * exit contract. The deadline-fires-SIGTERM path is treated as a clean
+ * window iff no unallowed errors were observed.
+ */
+async function runSmokeExit(engineDir, options) {
+    // Windows lacks the POSIX process-group primitives --smoke-exit leans on to
+    // SIGTERM the whole mach → python → firefox tree. Running through anyway
+    // would only kill the top-level wrapper and orphan Firefox content
+    // processes, so reject the flag up front to match the documented contract
+    // in CHANGELOG.md / README.md.
+    if (process.platform === 'win32') {
+        throw new InvalidArgumentError('--smoke-exit is POSIX-only; process-group semantics do not map cleanly onto Windows.', 'smokeExit');
+    }
+    const smokeExit = options.smokeExit;
+    // The runCommand caller has already gated on `options.smokeExit !== undefined`,
+    // but commander can hand us `0` or negative values through the action
+    // layer if the parser in `registerRun` was bypassed (e.g. programmatic
+    // use in a test that skips the parser). Guard explicitly so the deadline
+    // timer cannot be scheduled at 0 ms and immediately kill the process.
+    if (smokeExit === undefined || smokeExit < 1 || !Number.isFinite(smokeExit)) {
+        throw new InvalidArgumentError('--smoke-exit expects a positive integer number of seconds.', 'smokeExit');
+    }
+    const smokeTimeoutMs = smokeExit * 1000;
+    if (smokeTimeoutMs < SMOKE_COLD_START_THRESHOLD_MS) {
+        // Not an error — cold starts just tend to exceed the window. Surfacing
+        // the hint here instead of failing lets agents run shorter windows
+        // intentionally (e.g. warm-cache smoke checks).
+        verbose(`Smoke window is ${String(smokeExit)}s; cold starts on slow machines often exceed 30s.`);
+    }
+    const allowlist = await buildAllowlist(options);
+    const captureStream = options.captureConsole
+        ? createWriteStream(options.captureConsole)
+        : undefined;
+    // createWriteStream opens the fd asynchronously, so ENOENT / EACCES /
+    // EISDIR / EROFS surface as an 'error' event *after* the constructor
+    // returns. Without a listener Node re-throws as uncaughtException and
+    // kills the CLI mid-smoke-run — orphaning the mach → python → firefox
+    // tree because the deadline timer never fires. Swallow the event into a
+    // warning so the smoke run still terminates cleanly; subsequent mirror
+    // writes on the errored stream are silent no-ops.
+    captureStream?.on('error', (err) => {
+        warn(`--capture-console stream error: ${err.message}`);
+    });
+    const findings = [];
+    let allowlistedHits = 0;
+    const handleLine = (stream, line) => {
+        // Mirror raw output to the terminal so operators watching the smoke
+        // run still see what the browser is printing. Stream selection on the
+        // mirror preserves stdout/stderr separation for downstream piping.
+        const sink = stream === 'stdout' ? process.stdout : process.stderr;
+        sink.write(`${line}\n`);
+        if (!matchesSmokeError(line))
+            return;
+        if (matchesAllowlist(line, allowlist)) {
+            allowlistedHits += 1;
+            return;
+        }
+        findings.push({ stream, line });
+    };
+    info(`Launching browser (smoke-exit after ${String(smokeExit)}s)...\n`);
+    const startedAt = Date.now();
+    let result;
+    try {
+        result = await runMachSmoke(['run'], engineDir, {
+            smokeTimeoutMs,
+            onStdoutLine: (line) => {
+                handleLine('stdout', line);
+            },
+            onStderrLine: (line) => {
+                handleLine('stderr', line);
+            },
+            ...(captureStream ? { mirror: { stdout: captureStream, stderr: captureStream } } : {}),
+        });
+    }
+    finally {
+        captureStream?.end();
+    }
+    const elapsedMs = Date.now() - startedAt;
+    reportSmokeSummary({
+        smokeTimeoutMs,
+        elapsedMs,
+        timedOut: result.timedOut,
+        allowlistedHits,
+        findings,
+        exitCode: result.exitCode,
+    });
+    // Exit contract (precedence: unallowed errors dominate timed-out).
+    if (findings.length > 0) {
+        throw new SmokeRunError(`Smoke run observed ${String(findings.length)} unallowed console error(s).`, SMOKE_EXIT_FAILURE);
+    }
+    if (result.timedOut) {
+        // Clean window — SIGTERM from us. Treat as success.
+        return;
+    }
+    if (result.exitCode === 0 || result.exitCode === 130 || result.exitCode === 143) {
+        return;
+    }
+    throw new SmokeRunError(`Browser exited with code ${String(result.exitCode)} before smoke-exit window elapsed.`, SMOKE_LAUNCH_FAILURE);
+}
+/**
+ * Compiles the active allowlist from `--console-allow` CLI values and
+ * the optional `--console-allow-file`. Fails fast on a bad regex —
+ * better to surface the typo at parse time than to silently let it
+ * match nothing and turn every allowed hit into a smoke failure.
+ */
+async function buildAllowlist(options) {
+    const allow = [];
+    if (options.consoleAllow && options.consoleAllow.length > 0) {
+        try {
+            allow.push(...compileAllowlistFromStrings(options.consoleAllow));
+        }
+        catch (error) {
+            throw new InvalidArgumentError(toError(error).message, 'consoleAllow');
+        }
+    }
+    if (options.consoleAllowFile) {
+        try {
+            const body = await readFile(options.consoleAllowFile, 'utf8');
+            allow.push(...compileAllowlistFromFile(body, options.consoleAllowFile));
+        }
+        catch (error) {
+            throw new InvalidArgumentError(`Failed to read --console-allow-file: ${toError(error).message}`, 'consoleAllowFile');
+        }
+    }
+    return allow;
+}
+/**
+ * Prints the human-readable summary block that follows every smoke run.
+ * Called once, right before the exit-code decision. Keeps the reporting
+ * path separate from exit-contract logic so a test can render summaries
+ * without mocking the BuildError construction.
+ */
+function reportSmokeSummary(args) {
+    const seconds = (args.elapsedMs / 1000).toFixed(1);
+    const windowSeconds = (args.smokeTimeoutMs / 1000).toFixed(0);
+    const suffix = args.timedOut ? ' (deadline fired — SIGTERM sent to process group)' : '';
+    info('');
+    info(`Smoke run complete: ${seconds}s elapsed of ${windowSeconds}s window${suffix}`);
+    info(`  Unallowed errors: ${String(args.findings.length)}`);
+    info(`  Allowlisted hits: ${String(args.allowlistedHits)}`);
+    info(`  Child exit code:  ${String(args.exitCode)}`);
+    if (args.findings.length === 0)
+        return;
+    warn('');
+    warn(`Unallowed console errors (first ${String(SMOKE_UNALLOWED_PREVIEW_MAX)}):`);
+    args.findings.slice(0, SMOKE_UNALLOWED_PREVIEW_MAX).forEach((finding, index) => {
+        warn(`  ${String(index + 1)}. [${finding.stream}] ${finding.line}`);
+    });
+    if (args.findings.length > SMOKE_UNALLOWED_PREVIEW_MAX) {
+        const remaining = args.findings.length - SMOKE_UNALLOWED_PREVIEW_MAX;
+        warn(`  …and ${String(remaining)} more.`);
+    }
+}
 /** Registers the run command on the CLI program. */
 export function registerRun(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('run')
         .description('Launch the built browser')
-        .action(withErrorHandling(async () => {
-        await runCommand(getProjectRoot());
+        .option('--smoke-exit <seconds>', 'Smoke-run mode (POSIX only): launch, capture console, SIGTERM the process group after <seconds>. Exit 0 on a clean window, 12 on unallowed errors, 13 on launch failure.', (value) => {
+        const parsed = Number.parseInt(value, 10);
+        if (!Number.isFinite(parsed) || parsed < 1 || String(parsed) !== value.trim()) {
+            throw new Error(`--smoke-exit expects a positive integer number of seconds (got "${value}").`);
+        }
+        return parsed;
+    })
+        .option('--console-allow <regex>', 'Allowlist regex (repeatable). Lines that match any entry do not count toward the smoke exit code.', (value, acc) => {
+        acc.push(value);
+        return acc;
+    }, [])
+        .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored.')
+        .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
+        .action(withErrorHandling(async (options) => {
+        await runCommand(getProjectRoot(), pickDefined(options));
     }));
 }
 //# sourceMappingURL=run.js.map

package/dist/src/commands/test.js

@@ -4,10 +4,12 @@ import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
 import { reportMarionettePreflight, runMarionettePreflight } from '../core/marionette-preflight.js';
+import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
+import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, spinner } from '../utils/logger.js';
+import { info, intro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 /**
  * Strips a leading "engine/" or "engine\\" prefix from a path if present.
@@ -59,7 +61,47 @@ function hasStaleBuildArtifactsSignal(output) {
         /resource:\/\/\/modules\/distribution\.sys\.mjs/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
 }
-function handleNonZeroTestExit(result, normalizedPaths) {
+// Detects the broader xpcshell symptom where every `resource:///modules/...`
+// import fails — the signature of xpcshell running with the wrong app-dir on
+// a manifest that sets `firefox-appdir = "browser"`. Checked AFTER the
+// stale-build signal (which matches the narrower `distribution.sys.mjs`
+// path) so the more specific diagnosis wins when both patterns apply.
+function hasXpcshellAppdirSignal(output) {
+    return /Failed to load resource:\/\/\/modules\//i.test(output);
+}
+function buildXpcshellAppdirMessage(injectionAttempted) {
+    const triggerLines = injectionAttempted
+        ? 'FireForge auto-injected `--app-path=<absolute>` against the resolved obj-dir before mach test ran, but the failure persists. The injected path either does not match the appdir layout your harness expects, or the harness was built against a layout FireForge cannot probe (omni.ja-packed tree, alternate `dist/` shape).\n\n'
+        : 'Likely triggers:\n' +
+            '  - The nearest xpcshell.toml sets `firefox-appdir = "browser"` but the harness reads `<appname>-appdir` instead — the literal `firefox-appdir` directive is silently ignored on rebranded forks (appname != "firefox").\n' +
+            '  - FireForge could not find an xpcshell.toml above the test path, so the auto-injection never ran.\n\n';
+    return ('xpcshell failed to load core resource:///modules/*.sys.mjs imports.\n\n' +
+        'This is the canonical symptom of xpcshell running with the wrong app directory: the runtime resolves `resource:///modules/` against the parent of the expected app root, so every `ChromeUtils.importESModule("resource:///modules/…")` throws.\n\n' +
+        triggerLines +
+        'Options:\n' +
+        '  - Add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the xpcshell.toml [DEFAULT] so the harness reads the appname-keyed value directly.\n' +
+        '  - Pass overrides through `fireforge test <path> --mach-arg="--app-path=<absolute>"` to inject the path verbatim (operator overrides always win over auto-injection).\n' +
+        '  - Remove `firefox-appdir = "browser"` from the xpcshell.toml [DEFAULT] and move browser-chrome dependencies into a browser-chrome mochitest (see `fireforge furnace create --test-style=browser-chrome`).\n' +
+        '  - If the test only touches toolkit chrome (chrome://global/*), drop the `firefox-appdir` setting entirely — toolkit chrome is registered without it.');
+}
+// Detects the `AttributeError: 'MochitestDesktop' object has no attribute
+// 'http3Server'` teardown crash. The attribute is lazy-initialized inside
+// harness code paths that presume chrome://branding resolves correctly; a
+// missing or miswired branding registration short-circuits the setup and
+// leaves the cleanup path looking up an attribute that was never assigned.
+function hasMochitestHttp3ServerSignal(output) {
+    return /'MochitestDesktop' object has no attribute 'http3Server'/.test(output);
+}
+function buildMochitestHttp3ServerMessage() {
+    return ("Mochitest raised `AttributeError: 'MochitestDesktop' object has no attribute 'http3Server'`.\n\n" +
+        'This is almost always a symptom of `chrome://branding` not registering correctly in your fork — the mochitest harness lazy-initializes `http3Server` only after branding resolves, and a missing branding registration short-circuits setup. The cleanup path then trips the AttributeError, masking the real error.\n\n' +
+        'Check that:\n' +
+        "  - Your fork's branding directory is listed in `browser/branding/moz.build` (or equivalent) and ships a `brand.properties` / `brand.ftl`.\n" +
+        '  - `chrome://branding/locale/brand.properties` resolves at runtime (try `fireforge run` and inspect the Browser Console).\n' +
+        "  - The `BROWSER_CHROME_MANIFESTS` entry for your fork's chrome.manifest is registered.\n\n" +
+        'This is an upstream Firefox harness interaction; FireForge can only diagnose it.');
+}
+function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
@@ -69,6 +111,12 @@ function handleNonZeroTestExit(result, normalizedPaths) {
     if (hasStaleBuildArtifactsSignal(combinedOutput)) {
         throw new GeneralError(buildStaleBuildMessage());
     }
+    if (hasMochitestHttp3ServerSignal(combinedOutput)) {
+        throw new GeneralError(buildMochitestHttp3ServerMessage());
+    }
+    if (hasXpcshellAppdirSignal(combinedOutput)) {
+        throw new GeneralError(buildXpcshellAppdirMessage(appdirInjectionAttempted));
+    }
     if (/invalid filename/i.test(combinedOutput) ||
         /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');
@@ -118,6 +166,20 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         s.stop('Build complete');
         info('');
     }
+    else {
+        // Stale-build preflight — when --build was NOT requested, detect
+        // packageable engine edits since the last successful `fireforge build`
+        // and warn UP-FRONT. Without this, edits to chrome / packaged resources
+        // surface only as a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell
+        // after mach test has already launched (see motivating case in
+        // `core/test-stale-check.ts`). The check is warn-only so a fork that
+        // rebuilt out-of-band (no FireForge-recorded baseline update) is not
+        // blocked from running tests.
+        const stale = await checkStaleBuildForTest(projectRoot, paths.engine);
+        if (stale.stale) {
+            warn(formatStaleBuildWarning(stale));
+        }
+    }
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When
     // no paths are supplied this is the only step — it's the fastest way to tell
@@ -144,6 +206,23 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (options.headless) {
         extraArgs.push('--headless');
     }
+    // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
+    // flags FireForge does not model directly (see the xpcshell appdir hint
+    // above for the motivating case). Appended AFTER --headless so mach sees
+    // the FireForge-managed flags first and the escape-valve ones last, which
+    // keeps the override precedence predictable.
+    if (options.machArg && options.machArg.length > 0) {
+        extraArgs.push(...options.machArg);
+    }
+    // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
+    // full motivation. On rebranded forks (appname != "firefox") the upstream
+    // harness silently ignores `firefox-appdir = "browser"` directives in the
+    // xpcshell.toml, so every `resource:///modules/…` import throws. We probe
+    // the nearest manifest, compute the absolute appdir under obj-*/dist/, and
+    // inject `--app-path=<abs>` so the harness uses the right root. Operator
+    // overrides via `--mach-arg=--app-path=…` always win — we skip injection
+    // when the operator already passed one.
+    const appdirInjection = await maybeInjectAppdirArg(paths.engine, normalizedPaths, buildCheck.objDir, extraArgs);
     // Log what we're doing
     if (normalizedPaths.length > 0) {
         info(`Running tests: ${normalizedPaths.join(', ')}`);
@@ -159,7 +238,34 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
-    handleNonZeroTestExit(result, normalizedPaths);
+    handleNonZeroTestExit(result, normalizedPaths, appdirInjection);
+}
+/**
+ * Resolves and (when applicable) appends an `--app-path=<abs>` arg to
+ * `extraArgs`. Returns true iff the arg was injected. The logging branches
+ * mirror the {@link XpcshellAppdirOutcome} variants so an operator can tell
+ * from the test output whether FireForge tried to help and what it found.
+ */
+async function maybeInjectAppdirArg(engineDir, normalizedPaths, objDir, extraArgs) {
+    if (!objDir)
+        return false;
+    if (operatorAlreadySetAppPath(extraArgs))
+        return false;
+    const outcome = await resolveXpcshellAppdirArg(engineDir, normalizedPaths, objDir);
+    switch (outcome.kind) {
+        case 'none':
+            return false;
+        case 'mismatch':
+            warn(`xpcshell appdir auto-injection skipped — multiple test paths resolved to different app dirs (${outcome.values.join(', ')}). Pass --mach-arg=--app-path=<abs> to disambiguate.`);
+            return false;
+        case 'unresolved':
+            warn(`xpcshell appdir auto-injection skipped — manifest at ${outcome.manifestPath} requests appdir "${outcome.relativeAppdir}" but no matching directory exists under ${objDir}/dist/. Build artifacts may be stale.`);
+            return false;
+        case 'injected':
+            extraArgs.push(`--app-path=${outcome.result.appPath}`);
+            info(`xpcshell appdir auto-injected: --app-path=${outcome.result.appPath} (from ${outcome.result.manifestPath} firefox-appdir=${outcome.result.relativeAppdir}).`);
+            return true;
+    }
 }
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
@@ -169,6 +275,10 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
+        .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', (value, acc) => {
+        acc.push(value);
+        return acc;
+    }, [])
         .action(withErrorHandling(async (paths, options) => {
         await testCommand(getProjectRoot(), paths, pickDefined(options));
     }));

package/dist/src/core/build-audit-registration.d.ts

@@ -0,0 +1,80 @@
+/** Parsed jar.mn registration anchored to a specific engine source path. */
+export interface RegistrationHit {
+    /** Target path extracted from the entry (POSIX). */
+    target: string;
+    /** Source path from the entry (POSIX, relative to the jar.mn directory). */
+    source: string;
+    /** Absolute path of the jar.mn that owns the registration. */
+    jarManifest: string;
+}
+/** Result of a registration-aware dist probe. */
+export interface RegistrationProbeResult {
+    /** Absolute path of the packaged artifact matching the registration target. */
+    artifact: string;
+    /** The registration entry that anchored the match. */
+    hit: RegistrationHit;
+}
+/**
+ * Parses a single jar.mn line into `{ target, source }` when the line is a
+ * content entry with an explicit `(source)` reference. Returns undefined
+ * for comments, headers (`browser.jar:`), `%` manifest directives, blank
+ * lines, and entries without a source reference.
+ *
+ * Accepted entry shapes:
+ *   `        content/browser/foo.js     (content/foo.js)`   bare
+ *   `*       content/browser/foo.js     (content/foo.js)`   `*` = preprocessed
+ *   `en-US.jar:        content/foo.js  (content/foo.js)`    locale-prefixed
+ */
+export declare function parseJarMnEntry(line: string): {
+    target: string;
+    source: string;
+} | undefined;
+/**
+ * Scans a jar.mn file's contents for an entry whose source reference
+ * matches `relativeSource` (POSIX, relative to the jar.mn directory).
+ * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * practice, so a first-match wins behaviour is adequate.
+ */
+export declare function findJarMnEntryForSource(content: string, relativeSource: string): {
+    target: string;
+    source: string;
+} | undefined;
+/**
+ * Walks from the source's directory upward to the engine root, returning
+ * the first jar.mn entry that registers the given source. Returns undefined
+ * when no ancestor jar.mn claims the source.
+ *
+ * @param engineDir Absolute engine root; walk halts here.
+ * @param source Engine-relative POSIX source path.
+ */
+export declare function findRegisteredTarget(engineDir: string, source: string): Promise<RegistrationHit | undefined>;
+/**
+ * Probes the dist tree for the artifact registered against the given
+ * source. Returns the matched candidate and the registration hit that
+ * anchored it; undefined when the source has no owning jar.mn or when
+ * no same-basename candidate under the search roots ends with the
+ * registered target path.
+ *
+ * Suffix-matching against the target path is intentional: jar.mn targets
+ * are relative to the jar root (`browser.jar:`, `toolkit.jar:`), but the
+ * dist tree prefixes every entry with a jar-specific directory
+ * (`.../chrome/browser/content/browser/…`). The source basename plus the
+ * target suffix are unambiguous across every packaging convention we
+ * care about.
+ *
+ * @param engineDir Absolute engine root.
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to probe (dist/, _tests/).
+ */
+export declare function resolveArtifactByRegistration(engineDir: string, source: string, searchRoots: readonly string[]): Promise<RegistrationProbeResult | undefined>;
+/**
+ * Returns the absolute paths of every same-basename candidate under the
+ * given search roots. Used by the audit to enumerate ALL false-match
+ * candidates when the heuristic fallback downgrades to "missing" — the
+ * operator needs to see the full set, not just the scorer's pick, to
+ * distinguish a registration bug from a genuine packaging drop.
+ *
+ * @param source Engine-relative POSIX source path.
+ * @param searchRoots Absolute roots to scan.
+ */
+export declare function collectSameBasenameCandidates(source: string, searchRoots: readonly string[]): Promise<string[]>;