@hominis/fireforge 0.15.4 → 0.15.6

package/CHANGELOG.md

@@ -38,7 +38,14 @@
 
 ### Build audit
 
-- `fireforge build` now runs a warn-only post-build dist-tree audit after a successful mach build. The audit diffs engine-relative paths touched since the last successful build (stored as `.fireforge/last-build.json`) against the dist bundle, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact, or whose dist mtime is older than the source. Surfaces the class of bug where a new pref file or widget is edited but never registered in `moz.build` / `jar.mn` / `package-manifest.in` — the 2026-04-18 `hominis.js` pref-file incident is the motivating case. The audit is warn-only and never fails a successful build.
+- `fireforge build` now runs a warn-only post-build dist-tree audit after a successful mach build. The audit diffs engine-relative paths touched since the last successful build (stored as `.fireforge/last-build.json`) against the dist bundle, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact, or whose dist mtime is older than the source. Surfaces the class of bug where a new pref file or widget is edited but never registered in `moz.build` / `jar.mn` / `package-manifest.in`.
+- Build-system inputs (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`) are now excluded from the audit's "must appear in dist/" check. They are consumed by the build to produce chrome registrations / make targets but never themselves ship, so every edit produced a guaranteed false positive — and worse, when an unrelated upstream `moz.build` coincidentally existed elsewhere in the bundle (e.g. `<App>.app/Contents/moz.build`) the audit reported "source is newer than packaged artifact" against two completely unrelated files. The exclusion list lives next to `PACKAGEABLE_EXTENSIONS` in `src/core/build-audit.ts`.
+- Same-basename collisions in `dist/` are now disambiguated by trailing-segment overlap: a branding override at `engine/browser/branding/<name>/content/aboutDialog.css` (which ships at `chrome/<area>/content/branding/aboutDialog.css`) no longer gets matched against the unrelated upstream `chrome/<area>/content/browser/aboutDialog.css`. The scorer rewards candidates whose path contains meaningful intermediate segments from the source (e.g. the `branding` segment) so re-rooted artifacts win over coincidentally-named ones. Generic segments like `content` / `chrome` / `bin` do not count toward the bonus to avoid breaking ties on noise.
+- Test sources (anything under `/test(s)/`, plus `browser_*.js` / `test_*.js` / `xpcshell.toml` / `browser.ini`) are now resolved against the `_tests/` tree under the active `obj-*` directory instead of `dist/`. Mochitest and xpcshell harnesses copy registered tests under `_tests/testing/...`, never into the packaged bundle, so the previous dist-only walk false-flagged every registered test as "missing packaged artifact". Misses still warn — but they now point at `_tests/`, directing the operator to `BROWSER_CHROME_MANIFESTS` / `XPCSHELL_TESTS_MANIFESTS` instead of `package-manifest.in`.
+- Files inside an `if CONFIG[…]:` block in their owning `moz.build` are now skipped on hosts where the gate evaluates off (Windows-only stubinstaller CSS on a macOS build, Darwin-only artwork on Linux, etc.). The detection walks up from the source file to the closest `moz.build`, scans for the basename inside a Python-style indented `if CONFIG[…]:` block, and matches the gate against the host platform via `getPlatform()`. Negation expressions (`!= "WINNT"`, `not CONFIG[…]`) are conservatively NOT treated as single-OS gates, so we never wrongly suppress a warning for a file that should ship on the current host. Lives in the new `src/core/build-audit-platform.ts`.
+- Platform-gate detection now also covers subtrees packaged through platform-specific `Makefile.in` recipes that live outside the `moz.build` graph. Paths under `/stubinstaller/` (Windows NSIS stub installer), `browser/installer/windows/`, `browser/installer/macosx/`, and `browser/installer/linux/` count as host-gated by path convention on hosts where the target platform does not match. Previously the audit warned on every touched branding stubinstaller CSS on every non-Windows build because no ancestor `moz.build` wrapped those files in an `if CONFIG[…]:` block — the packaging trigger is `browser/installer/windows/Makefile.in` / `nsis/stub.nsh`, which the scanner does not parse. An explicit moz.build gate still wins if one is present, so fork-specific overrides behave as before. Surfaced as two warnings per macOS build before the fix.
+- Test-path audits are now gated on the `_tests/all-tests.json` marker file that `mach package-tests` writes. Plain `mach build` populates a partial `_tests/` subtree and stops, so every correctly-registered mochitest / xpcshell source was false-flagged as "missing packaged artifact" on the common build-only path. The audit now checks for the marker and silently skips test-path sources when the marker is absent — operators who want green-checked test registrations run `cd engine && ./mach package-tests` or a scoped `fireforge test <name>` after the build. Surfaced as 24 warnings per build (one per registered mochitest / xpcshell source) before the fix.
+- Stale-artifact warnings now require the matched candidate to be structurally related to the source: either the immediate parent directory trail-matches, or a non-generic source segment (`branding`, the fork's own directory name) appears mid-candidate. Same-basename hits in unrelated subtrees — the motivating case: `engine/browser/modules/<name>/test/head.js` matching the upstream `_tests/xpcshell/dom/quota/test/xpcshell/common/head.js` — are now classified as `missing` with a warning that names the unrelated candidate, rather than a `stale` warning that reads as "your build dropped this file" when in fact the match is spurious. The confidence check only kicks in when staleness would otherwise fire, so `updated` classifications keep their current loose matching. Generic directory segments (`test`, `tests`, `unit`, `common`, `xpcshell`, `mochitest` plus the existing list) no longer contribute to the structural-match bonus so trailing-segment spoofs (a shared `test` / `xpcshell` segment on an unrelated file) are rejected.
 - Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary so operators can distinguish a fast-because-incremental build from a fast-because-silently-skipped one without a post-build `find`.
 - `fireforge build` auto-runs `mach configure` before the mach build step when any `moz.build`, `moz.configure`, or `Makefile.in` changed since the last successful build. Prevents the stale-backend trap where an incremental build skips work against a recursive-make backend that no longer matches the source tree. Emits a `Backend config changed; running mach configure first...` banner so the extra step is visible, and continues the build even if configure exits non-zero.
 - Mach build failures with known-cryptic mozbuild errors now print actionable hints. First entry in the table: `mozbuild.preprocessor.Preprocessor.Error: no preprocessor directives found` prints `Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.` The hint table lives in `src/core/mach-error-hints.ts` and is extensible — new cryptic errors we diagnose get one-line hints added without touching the build wrapper.
@@ -70,7 +77,9 @@
 - New `src/core/marionette-preflight.ts` owns the `--doctor` probe and its teardown semantics.
 - Test mocks for `furnace-registration.js` now cover the new `addLocaleFtlJarMnEntry` / `removeLocaleFtlJarMnEntry` exports; `config.js` mocks in apply-batch tests now cover `loadConfig` because the apply path reads `markerComment` from fireforge.json.
 - Repo-wide scrub of fork-example mentions (`hominis.xhtml`, `HOMINIS` marker-comment examples, fixture tag names) in favour of a generic `mybrowser` / `MYBROWSER` placeholder. FireForge reads as fork-agnostic in docs and fixtures; the npm identity (`@hominis/fireforge`) is unchanged. Closes a v0.15.0 slip-through (one `@hominis/fireforge` reference remained in `src/core/furnace-operation.ts` as a generic example alongside the npm-identity occurrences; the code example is now fork-neutral).
-- New modules landed under coverage-gate protection: `src/core/mach-error-hints.ts`, `src/core/build-audit.ts`, `src/core/build-baseline.ts`, `src/core/patch-lint-diff-tag.ts`, `src/commands/furnace/chrome-doc.ts`, `src/commands/furnace/chrome-doc-templates.ts`, `src/commands/furnace/create-mochikit.ts`. Per-module thresholds added to `scripts/check-coverage-thresholds.mjs`.
+- Second pass on the same scrub: residual `hominis.xhtml` test fixtures in `wire.test.ts`, `browser-wire.test.ts`, and `doctor.test.ts` are now `mybrowser-shell.xhtml`; the `hominis.js` reference in the build-audit changelog motivating-case description is now generic. Tests retain a distinct override-target (`mybrowser.xhtml`) to preserve the configured-vs-overridden semantic of the wire `--target` precedence test.
+- New modules landed under coverage-gate protection: `src/core/mach-error-hints.ts`, `src/core/build-audit.ts`, `src/core/build-audit-resolve.ts`, `src/core/build-audit-platform.ts`, `src/core/build-baseline.ts`, `src/core/patch-lint-diff-tag.ts`, `src/commands/furnace/chrome-doc.ts`, `src/commands/furnace/chrome-doc-templates.ts`, `src/commands/furnace/create-mochikit.ts`. Per-module thresholds added to `scripts/check-coverage-thresholds.mjs`.
+- Path resolution and Python-style moz.build gate detection extracted from `build-audit.ts` into the new `build-audit-resolve.ts` (basename collisions, `_tests/` routing, trailing-segment scoring) and `build-audit-platform.ts` (`if CONFIG[…]:` gate parser keyed on host platform). Keeps the orchestrator under the per-file LOC budget after the false-positive fixes landed.
 
 ## 0.14.0
 

package/README.md

@@ -398,6 +398,15 @@ The summary line splits counts — e.g. `Lint: 2 introduced error(s), 0 introduc
 
 `fireforge build` is a transactional step: after a successful mach build it audits the dist bundle against engine-relative paths touched since the last successful build, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact or whose dist mtime is older than the source. Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary. The audit is warn-only — it never fails a build that mach reported green.
 
+The audit applies six routing rules to suppress false positives that previously trained operators to ignore its warnings:
+
+- **Build inputs are excluded.** `jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, and `mozbuild.in` are consumed by the build to produce chrome registrations / make targets but never themselves ship. They are skipped before the dist lookup, so editing them no longer fires a "missing packaged artifact" warning.
+- **Same-basename collisions in `dist/` are disambiguated by trailing-segment overlap.** A branding override at `engine/browser/branding/<name>/content/aboutDialog.css` ships at `chrome/<area>/content/branding/aboutDialog.css`. A naive basename match would tie that against the unrelated upstream `chrome/<area>/content/browser/aboutDialog.css`; the audit now scores candidates by trailing path-segment match plus a small bonus for non-generic source segments (`branding`, the branding directory name) appearing in the candidate path, so re-rooted artifacts win over coincidentally-named ones.
+- **Unrelated same-basename hits never surface as "stale".** When the best-scoring candidate shares only the basename with the source and no meaningful intermediate segment (common on sparsely-populated `_tests/` trees where an upstream helper like `head.js` is the only same-basename file left from a prior build), the audit classifies the file as `missing` rather than emitting a misleading stale-comparison warning against the unrelated candidate. The warning names the unrelated file so the operator can confirm the mismatch at a glance.
+- **Test sources are looked up under `_tests/`, not `dist/`.** Anything under `/test(s)/` directories, plus `browser_*.js` / `test_*.js` / `xpcshell.toml` / `browser.ini`, is resolved against the `_tests/` tree under the active `obj-*` directory. Mochitest and xpcshell harnesses copy registered tests there, never into the packaged bundle. Misses still warn — but they point at `_tests/`, directing the operator to `BROWSER_CHROME_MANIFESTS` / `XPCSHELL_TESTS_MANIFESTS` instead of `package-manifest.in`.
+- **Test-path audits are gated on `_tests/all-tests.json`.** Plain `mach build` populates a partial `_tests/` subtree and stops — full test packaging only runs under `mach package-tests` / `mach test <target>` (or `fireforge test <name>`). The audit now checks for the `all-tests.json` marker written by the packaged-tests make target and silently skips test-path sources when the marker is absent, so every registered mochitest / xpcshell source no longer false-flags as "missing" on the common build-only path. Run `cd engine && ./mach package-tests` (or a scoped `fireforge test`) after a build to green-check test registrations.
+- **Files inside an `if CONFIG[…]:` block in their owning `moz.build` are skipped on hosts where the gate is off.** Windows-only stubinstaller CSS on a macOS build, Darwin-only artwork on Linux, etc. The detection walks up to the closest `moz.build`, scans for the basename inside a Python-style indented `if CONFIG[…]:` block, and matches the gate against the host platform. Negation expressions are conservatively NOT treated as single-OS gates so a warning is never wrongly suppressed for a file that should ship on the current host. Subtrees packaged through platform-specific `Makefile.in` recipes that live outside the `moz.build` graph — `/stubinstaller/` (NSIS), `browser/installer/windows/`, `browser/installer/macosx/`, `browser/installer/linux/` — are also gated by path convention so branding stubinstaller CSS no longer warns on every non-Windows build.
+
 The build also auto-runs `mach configure` before the mach build step when any `moz.build`, `moz.configure`, or `Makefile.in` changed since the last successful build. Prevents incremental builds from silently skipping work against a stale recursive-make backend. Emits a `Backend config changed; running mach configure first...` banner when it fires.
 
 Mach build failures with known-cryptic mozbuild errors now print actionable hints. Example: a `JS_PREFERENCE_PP_FILES` entry with no `#filter` / `#expand` directives now prints `Hint: ...use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.` alongside the raw mach traceback.

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

@@ -0,0 +1,38 @@
+/** Outcome of a moz.build platform-gate lookup for a single source file. */
+export interface PlatformGateResult {
+    /** True when the file is gated off on the current host. */
+    gatedOff: boolean;
+    /**
+     * The gate expression that excluded the file, if any. Surfaced in
+     * verbose output so an operator can confirm the audit's reasoning.
+     */
+    gateExpression?: string;
+}
+/**
+ * Scans a moz.build file for a basename match inside a conditional
+ * block, returning the gate expression when one encloses the match.
+ *
+ * The scanner uses indentation to track block scope (Python-style):
+ * an `if CONFIG[…]:` line opens a scope at indent N+1, and dedenting
+ * back to indent N closes it. A basename match inside that scope
+ * inherits the gate expression.
+ *
+ * @param content moz.build file content
+ * @param basename Basename of the source file we are auditing
+ * @returns The enclosing gate expression, or undefined if none
+ */
+export declare function findEnclosingGate(content: string, basename: string): string | undefined;
+/**
+ * Determines whether the given source file is gated off on the current
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build,
+ * OR by a path-convention rule for installer-tree subdirectories that
+ * are packaged via Makefile.in recipes the audit does not parse.
+ * Returns `gatedOff: false` and no expression when no gate is found —
+ * the file is not platform-restricted, so the caller should audit it
+ * normally.
+ *
+ * @param engineDir Absolute path to the engine root
+ * @param sourcePath Engine-relative POSIX path of the source file
+ * @returns Detection result
+ */
+export declare function detectPlatformGate(engineDir: string, sourcePath: string): Promise<PlatformGateResult>;

package/dist/src/core/build-audit-platform.js

@@ -0,0 +1,237 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Platform-gate detection for the post-build dist-tree audit.
+ *
+ * `moz.build` files commonly wrap entries in conditional blocks like
+ * `if CONFIG["MAKENSISU"]:` (Windows-only stubinstaller) or
+ * `if CONFIG["OS_TARGET"] == "Darwin":` (macOS-only artwork). On a host
+ * that does not match the gate, the wrapped files are never processed
+ * by the build, so they cannot appear under `dist/`. Without this
+ * detection, the audit fires a "missing packaged artifact" warning for
+ * every gated file on every off-platform build — pure noise.
+ *
+ * Two gate sources are consulted, in order:
+ *   1. Python-style `if CONFIG[...]:` blocks in the owning `moz.build`.
+ *   2. Path-convention gates — certain directory fragments are packaged
+ *      by platform-specific Makefile.in / NSIS recipes that FireForge
+ *      does not parse, so a file living under `browser/installer/windows/`
+ *      or any `/stubinstaller/` subtree is Windows-only regardless of
+ *      what its nearest moz.build says. (The branding stubinstaller CSS
+ *      is the motivating case: referenced from
+ *      `browser/installer/windows/Makefile.in` / `nsis/stub.nsh` with no
+ *      `if CONFIG[…]:` in any moz.build ancestor.)
+ *
+ * The detection is intentionally lightweight: we walk up from the
+ * source file looking for the closest `moz.build`, scan it for an
+ * occurrence of the source basename inside an `if CONFIG[...]:` block,
+ * and check whether the gate expression matches the host platform.
+ * The path-convention pass kicks in only when no moz.build gate is
+ * found, so an explicit moz.build gate always wins.
+ *
+ * This is best-effort. False negatives (we miss a gate and warn anyway)
+ * are tolerable — the audit is warn-only. False positives (we wrongly
+ * skip a gated file that should ship on this host) are not, so the
+ * detection errs toward NOT skipping when uncertain.
+ */
+import { dirname, join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { getPlatform } from '../utils/platform.js';
+/**
+ * Tokens that uniquely identify a Windows-only `if CONFIG[...]:` block.
+ * `MAKENSISU` is the Windows stubinstaller compiler; `OS_TARGET ==
+ * "WINNT"` and `MOZ_WIDGET_TOOLKIT == "windows"` are the conventional
+ * platform discriminators.
+ */
+const WINDOWS_ONLY_GATE_TOKENS = ['MAKENSISU', '"WINNT"', "'WINNT'", '"windows"', "'windows'"];
+/** Tokens that mark a macOS-only `if CONFIG[...]:` block. */
+const DARWIN_ONLY_GATE_TOKENS = ['"Darwin"', "'Darwin'", '"cocoa"', "'cocoa'"];
+/** Tokens that mark a Linux-only `if CONFIG[...]:` block. */
+const LINUX_ONLY_GATE_TOKENS = ['"Linux"', "'Linux'", '"gtk"', "'gtk'"];
+/**
+ * Returns true when the platform-gate expression includes one of the
+ * tokens characteristic of a single OS that is not the current host.
+ */
+function isGateOffHost(expression, host) {
+    const matchesWindows = WINDOWS_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
+    const matchesDarwin = DARWIN_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
+    const matchesLinux = LINUX_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
+    // Negation gates (`!= "WINNT"`, `not CONFIG["MAKENSISU"]`) flip the
+    // semantics. Keep this conservative — if we cannot confidently parse
+    // a negation, return false so we don't wrongly suppress a warning.
+    const negated = /\bnot\b|!=/.test(expression);
+    if (negated)
+        return false;
+    if (matchesWindows && host !== 'win32')
+        return true;
+    if (matchesDarwin && host !== 'darwin')
+        return true;
+    if (matchesLinux && host !== 'linux')
+        return true;
+    return false;
+}
+/**
+ * Walks from a starting directory up to (but not above) the engine root,
+ * yielding the first `moz.build` encountered. Returns undefined when no
+ * ancestor has one — typically only for files that live above any
+ * moz.build entry point, which would not be packageable anyway.
+ */
+async function findOwningMozBuild(engineDir, sourceDir) {
+    let current = sourceDir;
+    const root = engineDir.replace(/\/+$/, '');
+    while (current.startsWith(root)) {
+        const candidate = join(current, 'moz.build');
+        if (await pathExists(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * Matches a `basename` appearing at the tail of a quoted path literal
+ * on a single moz.build line. Catches both the bare entry
+ * `"installing_page.css"` and the path-prefixed entry
+ * `"stubinstaller/installing_page.css"`.
+ */
+function matchesQuotedBasename(line, basename) {
+    const escaped = basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`["'](?:[^"']*\\/)?${escaped}["']`).test(line);
+}
+/**
+ * Scans a moz.build file for a basename match inside a conditional
+ * block, returning the gate expression when one encloses the match.
+ *
+ * The scanner uses indentation to track block scope (Python-style):
+ * an `if CONFIG[…]:` line opens a scope at indent N+1, and dedenting
+ * back to indent N closes it. A basename match inside that scope
+ * inherits the gate expression.
+ *
+ * @param content moz.build file content
+ * @param basename Basename of the source file we are auditing
+ * @returns The enclosing gate expression, or undefined if none
+ */
+export function findEnclosingGate(content, basename) {
+    const lines = content.split('\n');
+    const stack = [];
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        const indent = (/^(\s*)/.exec(line)?.[1] ?? '').length;
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            if (top && indent <= top.indent) {
+                stack.pop();
+                continue;
+            }
+            break;
+        }
+        const ifMatch = /^\s*if\s+(.+?):\s*(?:#.*)?$/.exec(line);
+        if (ifMatch?.[1]) {
+            stack.push({ indent, expression: ifMatch[1] });
+            continue;
+        }
+        if (matchesQuotedBasename(line, basename)) {
+            const top = stack[stack.length - 1];
+            if (top)
+                return top.expression;
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Path-convention gates: directories whose files are packaged by
+ * platform-specific build recipes (NSIS stub installer, DMG creation,
+ * Linux installer scripts) that live outside the moz.build graph. A
+ * file under any of these fragments is platform-restricted regardless
+ * of what its nearest `moz.build` says.
+ *
+ * `stubinstaller/` is the Windows NSIS stub installer asset tree. It
+ * is referenced from `browser/installer/windows/Makefile.in` (via
+ * `FILES` / `_WIDGET_FILES` lists) and `nsis/stub.nsh`, never through
+ * an `if CONFIG[…]:` block an ancestor moz.build exposes. Without
+ * this path-level gate, the audit warns on every touched branding
+ * stubinstaller CSS on every non-Windows build.
+ */
+const PATH_GATES = [
+    { fragment: '/stubinstaller/', platform: 'win32', label: 'path convention: /stubinstaller/' },
+    {
+        fragment: '/browser/installer/windows/',
+        platform: 'win32',
+        label: 'path convention: browser/installer/windows/',
+    },
+    {
+        fragment: '/browser/installer/macosx/',
+        platform: 'darwin',
+        label: 'path convention: browser/installer/macosx/',
+    },
+    {
+        fragment: '/browser/installer/linux/',
+        platform: 'linux',
+        label: 'path convention: browser/installer/linux/',
+    },
+];
+/**
+ * Returns a path-convention gate for `sourcePath` when one applies.
+ * Leading slash added so `startsWith`-style prefix traps
+ * (`browser/installer/windows/…`) match whether or not the input
+ * starts with a separator.
+ */
+function findPathConventionGate(sourcePath) {
+    const normalised = `/${sourcePath}`.replace(/\/+/g, '/');
+    for (const entry of PATH_GATES) {
+        if (normalised.includes(entry.fragment)) {
+            return { platform: entry.platform, label: entry.label };
+        }
+    }
+    return undefined;
+}
+/**
+ * Determines whether the given source file is gated off on the current
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build,
+ * OR by a path-convention rule for installer-tree subdirectories that
+ * are packaged via Makefile.in recipes the audit does not parse.
+ * Returns `gatedOff: false` and no expression when no gate is found —
+ * the file is not platform-restricted, so the caller should audit it
+ * normally.
+ *
+ * @param engineDir Absolute path to the engine root
+ * @param sourcePath Engine-relative POSIX path of the source file
+ * @returns Detection result
+ */
+export async function detectPlatformGate(engineDir, sourcePath) {
+    let host;
+    try {
+        host = getPlatform();
+    }
+    catch {
+        host = undefined;
+    }
+    const sourceDir = dirname(join(engineDir, sourcePath));
+    const mozBuild = await findOwningMozBuild(engineDir, sourceDir);
+    if (mozBuild) {
+        let content;
+        try {
+            content = await readText(mozBuild);
+        }
+        catch {
+            content = '';
+        }
+        const sourceBasename = sourcePath.split('/').pop() ?? '';
+        const expression = findEnclosingGate(content, sourceBasename);
+        if (expression) {
+            if (host && isGateOffHost(expression, host)) {
+                return { gatedOff: true, gateExpression: expression };
+            }
+            return { gatedOff: false, gateExpression: expression };
+        }
+    }
+    const pathGate = findPathConventionGate(sourcePath);
+    if (pathGate && host && host !== pathGate.platform) {
+        return { gatedOff: true, gateExpression: pathGate.label };
+    }
+    return { gatedOff: false };
+}
+//# sourceMappingURL=build-audit-platform.js.map

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

@@ -0,0 +1,66 @@
+/**
+ * Heuristic test for "this looks like a packaged-test source file" — the
+ * audit routes such paths to `_tests/` instead of `dist/`. Matches
+ * mochitest / xpcshell / browser-chrome conventions: any source under a
+ * `/test/` or `/tests/` directory, or with a `browser_` / `test_` prefix
+ * on a `.js`/`.toml` basename. Test manifests (`*.toml`, `*.list`,
+ * `*.ini`) under those directories also qualify.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @returns True when the file belongs to the test tree, not the bundle
+ */
+export declare function isTestPath(sourcePath: string): boolean;
+/**
+ * Counts how many trailing segments two paths share. Used to score
+ * candidate dist artifacts against a source path so that
+ * `branding/<name>/content/aboutDialog.css` prefers a candidate at
+ * `…/content/branding/aboutDialog.css` over one at
+ * `…/content/browser/aboutDialog.css`.
+ *
+ * @param a First path
+ * @param b Second path
+ * @returns Count of matching trailing segments (basename always counts as 1)
+ */
+export declare function countTrailingSegmentMatches(a: string, b: string): number;
+/**
+ * Computes a score for `candidatePath` relative to `sourcePath`. Higher
+ * scores win. Score = trailing-segment match count, with a bonus when
+ * the candidate's path contains a meaningful intermediate segment from
+ * the source (e.g. `branding`, the branding dir name itself, etc.).
+ *
+ * The bonus exists because Firefox packaging often re-roots files: a
+ * source `branding/<name>/content/aboutDialog.css` lands at
+ * `chrome/browser/content/branding/aboutDialog.css` — only the basename
+ * trails-match, but the `branding` segment moved into the middle of
+ * the candidate path. Without the bonus, that candidate would tie with
+ * the unrelated `chrome/browser/content/browser/aboutDialog.css` and
+ * the audit would pick whichever the directory walk hit first.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @param candidatePath Absolute path under the dist tree
+ * @returns Numeric score; higher means better match
+ */
+export declare function scoreCandidate(sourcePath: string, candidatePath: string): number;
+/**
+ * Walks a tree under `root` and returns every file whose basename equals
+ * `name`. Skips dotfile / hidden directories so the symlinked
+ * `.mozbuild` cache (a full upstream copy) does not dominate the scan
+ * on macOS.
+ *
+ * @param root Tree root to search
+ * @param name Basename to match
+ * @param maxDepth Optional traversal cap (default 12)
+ * @returns All matching absolute paths
+ */
+export declare function findAllByBasename(root: string, name: string, maxDepth?: number): Promise<string[]>;
+/**
+ * Resolves the best-matching artifact for a source path under one or
+ * more search roots. Returns the highest-scoring candidate by trailing
+ * segment overlap; ties go to the first-found path (deterministic via
+ * the directory-walk order). Returns undefined when no candidate exists.
+ *
+ * @param sourcePath Engine-relative POSIX source path
+ * @param searchRoots Absolute roots to scan (e.g. dist/, _tests/)
+ * @returns Best-matching artifact path, or undefined
+ */
+export declare function resolveBestArtifact(sourcePath: string, searchRoots: readonly string[]): Promise<string | undefined>;

package/dist/src/core/build-audit-resolve.js

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Path-resolution helpers for the post-build dist-tree audit.
+ *
+ * Resolves the expected on-disk artifact location for a given engine
+ * source path. The previous implementation matched purely by basename and
+ * suffered three classes of false positive:
+ *
+ *   1. A branding override (e.g. `engine/browser/branding/<name>/content/aboutDialog.css`)
+ *      shipped at `chrome/browser/content/branding/aboutDialog.css` would
+ *      get matched against the unrelated upstream
+ *      `chrome/browser/content/browser/aboutDialog.css`.
+ *   2. Test files (`browser_*.js`, `test_*.js`) live under `_tests/`, not
+ *      `dist/`, so every registered test was reported as missing.
+ *   3. Build inputs (`jar.mn`, `moz.build`, `Makefile.in`, `moz.configure`)
+ *      never appear under `dist/` — they are consumed, not packaged.
+ *
+ * The helpers below address (1) by ranking same-basename candidates by
+ * how many trailing path segments they share with the source, and (2) by
+ * routing test paths to a separate `_tests/`-aware resolver.
+ *
+ * (3) is handled in `build-audit.ts` via `isPackageablePath`.
+ */
+import { readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+/** Maximum directory depth to traverse when scanning a tree root. */
+const MAX_SCAN_DEPTH = 12;
+/**
+ * Heuristic test for "this looks like a packaged-test source file" — the
+ * audit routes such paths to `_tests/` instead of `dist/`. Matches
+ * mochitest / xpcshell / browser-chrome conventions: any source under a
+ * `/test/` or `/tests/` directory, or with a `browser_` / `test_` prefix
+ * on a `.js`/`.toml` basename. Test manifests (`*.toml`, `*.list`,
+ * `*.ini`) under those directories also qualify.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @returns True when the file belongs to the test tree, not the bundle
+ */
+export function isTestPath(sourcePath) {
+    if (sourcePath.includes('/test/') || sourcePath.includes('/tests/')) {
+        return true;
+    }
+    const name = basename(sourcePath);
+    if (/^browser_.+\.(js|toml|ini)$/.test(name))
+        return true;
+    if (/^test_.+\.(js|toml|ini)$/.test(name))
+        return true;
+    return false;
+}
+/**
+ * Splits a POSIX path into segments, dropping empties.
+ * @param path POSIX-separated path
+ */
+function pathSegments(path) {
+    return path.split('/').filter(Boolean);
+}
+/**
+ * Counts how many trailing segments two paths share. Used to score
+ * candidate dist artifacts against a source path so that
+ * `branding/<name>/content/aboutDialog.css` prefers a candidate at
+ * `…/content/branding/aboutDialog.css` over one at
+ * `…/content/browser/aboutDialog.css`.
+ *
+ * @param a First path
+ * @param b Second path
+ * @returns Count of matching trailing segments (basename always counts as 1)
+ */
+export function countTrailingSegmentMatches(a, b) {
+    const aSegs = pathSegments(a);
+    const bSegs = pathSegments(b);
+    let matches = 0;
+    while (matches < aSegs.length &&
+        matches < bSegs.length &&
+        aSegs[aSegs.length - 1 - matches] === bSegs[bSegs.length - 1 - matches]) {
+        matches += 1;
+    }
+    return matches;
+}
+/**
+ * Computes a score for `candidatePath` relative to `sourcePath`. Higher
+ * scores win. Score = trailing-segment match count, with a bonus when
+ * the candidate's path contains a meaningful intermediate segment from
+ * the source (e.g. `branding`, the branding dir name itself, etc.).
+ *
+ * The bonus exists because Firefox packaging often re-roots files: a
+ * source `branding/<name>/content/aboutDialog.css` lands at
+ * `chrome/browser/content/branding/aboutDialog.css` — only the basename
+ * trails-match, but the `branding` segment moved into the middle of
+ * the candidate path. Without the bonus, that candidate would tie with
+ * the unrelated `chrome/browser/content/browser/aboutDialog.css` and
+ * the audit would pick whichever the directory walk hit first.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @param candidatePath Absolute path under the dist tree
+ * @returns Numeric score; higher means better match
+ */
+export function scoreCandidate(sourcePath, candidatePath) {
+    const trailing = countTrailingSegmentMatches(sourcePath, candidatePath);
+    const sourceSegs = pathSegments(sourcePath);
+    const candSegs = pathSegments(candidatePath);
+    // Look for source segments that appear anywhere in the candidate path
+    // but are not part of the trailing match. Each unique mid-path hit on
+    // a meaningful (>2-char, not generic like 'content'/'chrome'/'bin')
+    // segment adds 1 to the score.
+    const generic = new Set([
+        'content',
+        'chrome',
+        'bin',
+        'browser',
+        'toolkit',
+        'modules',
+        'base',
+        'app',
+        'profile',
+        'shared',
+        'themes',
+    ]);
+    const trailingSet = new Set(sourceSegs.slice(sourceSegs.length - trailing));
+    let bonus = 0;
+    for (const seg of sourceSegs) {
+        if (seg.length <= 2)
+            continue;
+        if (generic.has(seg))
+            continue;
+        if (trailingSet.has(seg))
+            continue;
+        if (candSegs.includes(seg))
+            bonus += 1;
+    }
+    return trailing * 10 + bonus;
+}
+/**
+ * Walks a tree under `root` and returns every file whose basename equals
+ * `name`. Skips dotfile / hidden directories so the symlinked
+ * `.mozbuild` cache (a full upstream copy) does not dominate the scan
+ * on macOS.
+ *
+ * @param root Tree root to search
+ * @param name Basename to match
+ * @param maxDepth Optional traversal cap (default 12)
+ * @returns All matching absolute paths
+ */
+export async function findAllByBasename(root, name, maxDepth = MAX_SCAN_DEPTH) {
+    const results = [];
+    if (!(await pathExists(root)))
+        return results;
+    const stack = [{ dir: root, depth: 0 }];
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (!entry)
+            break;
+        if (entry.depth > maxDepth)
+            continue;
+        let children;
+        try {
+            children = await readdir(entry.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            const fullPath = join(entry.dir, child.name);
+            if (child.isDirectory()) {
+                if (child.name.startsWith('.'))
+                    continue;
+                stack.push({ dir: fullPath, depth: entry.depth + 1 });
+                continue;
+            }
+            if (child.name === name) {
+                results.push(fullPath);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Resolves the best-matching artifact for a source path under one or
+ * more search roots. Returns the highest-scoring candidate by trailing
+ * segment overlap; ties go to the first-found path (deterministic via
+ * the directory-walk order). Returns undefined when no candidate exists.
+ *
+ * @param sourcePath Engine-relative POSIX source path
+ * @param searchRoots Absolute roots to scan (e.g. dist/, _tests/)
+ * @returns Best-matching artifact path, or undefined
+ */
+export async function resolveBestArtifact(sourcePath, searchRoots) {
+    const name = basename(sourcePath);
+    const allCandidates = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        allCandidates.push(...found);
+    }
+    if (allCandidates.length === 0)
+        return undefined;
+    if (allCandidates.length === 1)
+        return allCandidates[0];
+    let bestScore = -1;
+    let best;
+    for (const candidate of allCandidates) {
+        const score = scoreCandidate(sourcePath, candidate);
+        if (score > bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=build-audit-resolve.js.map

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

@@ -28,7 +28,10 @@ export interface AuditSummary {
 }
 /**
  * Decides whether a source path should be packaged. Returns true for paths
- * whose extension or directory fragment matches a known-packaged pattern.
+ * whose extension or directory fragment matches a known-packaged pattern,
+ * after excluding build inputs (`jar.mn`, `moz.build`, etc.) which are
+ * consumed by the build but never themselves packaged.
+ *
  * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
  * @returns True when the path implies packaging.
  */

package/dist/src/core/build-audit.js

@@ -19,12 +19,27 @@
  *   - False positives are acceptable at this stage: fork-specific packaging
  *     tricks FireForge doesn't know about will surface as warnings an
  *     operator can investigate. The audit never fails the build.
+ *
+ * Routing rules:
+ *   - Build inputs (jar.mn, moz.build, Makefile.in, moz.configure) are
+ *     skipped; they are consumed, not packaged.
+ *   - Test sources (anything under /test(s)/, browser_*.js, test_*.js)
+ *     are looked up under _tests/, not dist/ — that's where mach copies
+ *     them.
+ *   - Files inside an `if CONFIG[...]:` block in moz.build that gates
+ *     off on the current host are skipped (Windows stubinstaller CSS on
+ *     a macOS build, etc.).
+ *   - Same-basename collisions in dist/ are disambiguated by trailing-
+ *     segment overlap so a branding override does not get matched
+ *     against an unrelated upstream file with the same basename.
  */
 import { stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
+import { detectPlatformGate } from './build-audit-platform.js';
+import { countTrailingSegmentMatches, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
 import { hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
@@ -44,48 +59,29 @@ const PACKAGEABLE_EXTENSIONS = [
 const PACKAGEABLE_PATH_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
 /** Directories that are build artifacts, not source — never audited. */
 const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
-/*
- * Finds the first file with the given basename anywhere under the dist
- * bundle. Scans the darwin Contents/Resources layout and the linux/win
- * top-level layout with a depth-limited traversal so deeply-nested
- * node_modules in the dist copy do not dominate the audit wall clock.
+/**
+ * Basenames that are build-system inputs, not packaged artifacts.
+ * `jar.mn` is consumed to produce chrome registrations; `moz.build` /
+ * `moz.configure` / `Makefile.in` feed the build backend; none of them
+ * ship in the bundle. Auditing them produced a guaranteed false
+ * positive on every edit (nothing under dist/ ever has these names),
+ * and a worse failure mode when an unrelated upstream `moz.build`
+ * coincidentally exists at e.g. `MyBrowser.app/Contents/moz.build` and
+ * gets matched as a "stale artifact" of an entirely different file.
  */
-async function findArtifactByBasename(distRoot, name, maxDepth = 10) {
-    const { readdir } = await import('node:fs/promises');
-    const stack = [{ dir: distRoot, depth: 0 }];
-    while (stack.length > 0) {
-        const entry = stack.pop();
-        if (!entry)
-            break;
-        if (entry.depth > maxDepth)
-            continue;
-        let children;
-        try {
-            children = await readdir(entry.dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const child of children) {
-            const fullPath = join(entry.dir, child.name);
-            if (child.isDirectory()) {
-                // Skip the symlinked mozbuild cache tree which contains full copies
-                // and would dominate the scan on macOS.
-                if (child.name.startsWith('.'))
-                    continue;
-                stack.push({ dir: fullPath, depth: entry.depth + 1 });
-                continue;
-            }
-            if (child.name === name) {
-                return fullPath;
-            }
-        }
-    }
-    return undefined;
-}
+const BUILD_INPUT_BASENAMES = new Set([
+    'jar.mn',
+    'moz.build',
+    'moz.configure',
+    'Makefile.in',
+    'mozbuild.in',
+]);
 /**
  * Decides whether a source path should be packaged. Returns true for paths
- * whose extension or directory fragment matches a known-packaged pattern.
+ * whose extension or directory fragment matches a known-packaged pattern,
+ * after excluding build inputs (`jar.mn`, `moz.build`, etc.) which are
+ * consumed by the build but never themselves packaged.
+ *
  * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
  * @returns True when the path implies packaging.
  */
@@ -94,6 +90,8 @@ export function isPackageablePath(sourcePath) {
         if (sourcePath.includes(fragment))
             return false;
     }
+    if (BUILD_INPUT_BASENAMES.has(basename(sourcePath)))
+        return false;
     for (const ext of PACKAGEABLE_EXTENSIONS) {
         if (sourcePath.endsWith(ext))
             return true;
@@ -169,6 +167,203 @@ async function resolveDistRoot(engineDir) {
     }
     return undefined;
 }
+/**
+ * Resolves the `_tests/` tree under the active obj-* directory, used as
+ * a secondary search root for sources that look like packaged tests.
+ * Returns undefined when no obj dir exists yet.
+ */
+async function resolveTestsRoot(engineDir) {
+    const { readdir } = await import('node:fs/promises');
+    let entries;
+    try {
+        entries = await readdir(engineDir);
+    }
+    catch {
+        return undefined;
+    }
+    const objDirs = entries.filter((e) => e.startsWith('obj-'));
+    for (const objDir of objDirs) {
+        const testsPath = join(engineDir, objDir, '_tests');
+        if (await pathExists(testsPath)) {
+            return testsPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Marker file the `package-tests` make target writes after copying the
+ * full test-source tree under `_tests/`. Its presence is the most reliable
+ * signal that test packaging has actually run for the current obj-dir —
+ * plain `mach build` populates a partial `_tests/` subtree and then stops,
+ * so registered tests are absent even when registration is correct.
+ */
+const PACKAGED_TESTS_MARKER = 'all-tests.json';
+/**
+ * Returns true when the full test-package step has actually run for the
+ * active obj-dir. Without this marker the `_tests/` walk produces false
+ * positives for every correctly-registered mochitest / xpcshell source
+ * on the common "built but tests not packaged" path.
+ *
+ * @param testsRoot Absolute path to the obj-*`/_tests/` tree, or undefined.
+ */
+async function hasPackagedTestsMarker(testsRoot) {
+    if (!testsRoot)
+        return false;
+    return pathExists(join(testsRoot, PACKAGED_TESTS_MARKER));
+}
+/**
+ * Resolves the search roots an individual source path should be looked
+ * up under. Test-shaped paths get `_tests/`; everything else gets `dist/`.
+ */
+function searchRootsFor(source, distRoot, testsRoot) {
+    if (isTestPath(source)) {
+        return testsRoot ? [testsRoot] : [];
+    }
+    return [distRoot];
+}
+/**
+ * Minimum trailing-segment overlap required for a same-basename dist/
+ * candidate to count as "the packaged artifact" of a source. The
+ * basename always trail-matches (count 1), so a threshold of 2 requires
+ * the immediate parent directory to also agree. Candidates that only
+ * share the basename are classified as missing — warning the operator
+ * to check registration — rather than emitting a misleading stale
+ * comparison against an unrelated file of the same name.
+ *
+ * Cross-tree re-rooting cases (e.g. `branding/<name>/content/foo.css`
+ * landing at `chrome/<area>/content/branding/foo.css`) bypass this
+ * floor because `scoreCandidate` awards a non-generic-segment bonus
+ * that lifts the confidence regardless of trailing overlap; those are
+ * detected below in `isConfidentMatch`.
+ */
+const MIN_TRAILING_SEGMENT_OVERLAP = 2;
+/**
+ * Returns true when the chosen artifact is structurally related to the
+ * source path — either its immediate parent directory trail-matches, or
+ * a non-generic intermediate source segment appears in the candidate
+ * path (the branding-re-root signal already used by the scorer).
+ *
+ * Used to avoid emitting `stale` warnings that point at an unrelated
+ * same-basename file picked up by the basename walker — a class of
+ * warning that is worse than `missing` because it reads as "your build
+ * dropped this file" when in fact the match is spurious.
+ */
+function isConfidentMatch(source, candidate) {
+    if (countTrailingSegmentMatches(source, candidate) >= MIN_TRAILING_SEGMENT_OVERLAP) {
+        return true;
+    }
+    const sourceSegs = source.split('/').filter(Boolean);
+    const candSegs = candidate.split('/').filter(Boolean);
+    const generic = new Set([
+        'content',
+        'chrome',
+        'bin',
+        'browser',
+        'toolkit',
+        'modules',
+        'base',
+        'app',
+        'profile',
+        'shared',
+        'themes',
+        'test',
+        'tests',
+        'unit',
+        'common',
+        'xpcshell',
+        'mochitest',
+    ]);
+    // Skip the basename itself (which trail-matches by definition).
+    for (let i = 0; i < sourceSegs.length - 1; i += 1) {
+        const seg = sourceSegs[i];
+        if (!seg || seg.length <= 2 || generic.has(seg))
+            continue;
+        if (candSegs.includes(seg))
+            return true;
+    }
+    return false;
+}
+/**
+ * Audits one engine source path and returns its entry. Pure orchestration
+ * helper kept separate so `auditBuildArtifacts` stays under the per-function
+ * line budget.
+ */
+async function auditSinglePath(source, ctx) {
+    if (!isPackageablePath(source)) {
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    const gate = await detectPlatformGate(ctx.engineDir, source);
+    if (gate.gatedOff) {
+        verbose(`Audit: skipping engine/${source} — gated off by "${gate.gateExpression ?? '?'}".`);
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    // Tests only end up under `_tests/` after `mach package-tests` (or a
+    // test-run that invokes the target) has executed. A plain `mach build`
+    // populates a partial subtree and stops, so every correctly-registered
+    // mochitest / xpcshell source appears "missing" on that common path.
+    // Skip audit for test sources when no packaged-tests marker is present.
+    if (isTestPath(source) && !ctx.testsPackaged) {
+        verbose(`Audit: skipping engine/${source} — _tests/${PACKAGED_TESTS_MARKER} not present; full test packaging has not run for this build.`);
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    const sourcePath = join(ctx.engineDir, source);
+    let sourceMtime;
+    try {
+        const sourceStat = await stat(sourcePath);
+        sourceMtime = sourceStat.mtimeMs;
+    }
+    catch {
+        // Deletion that didn't propagate — distinct class of bug, not audited yet.
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
+    const artifact = await resolveBestArtifact(source, roots);
+    if (!artifact) {
+        const where = isTestPath(source) ? '_tests/' : 'dist/';
+        return {
+            source,
+            artifact: undefined,
+            status: 'missing',
+            warning: `Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${where}. Missing moz.build / jar.mn / package-manifest.in registration?`,
+        };
+    }
+    let artifactMtime;
+    try {
+        const artifactStat = await stat(artifact);
+        artifactMtime = artifactStat.mtimeMs;
+    }
+    catch {
+        return {
+            source,
+            artifact,
+            status: 'missing',
+            warning: `Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`,
+        };
+    }
+    if (artifactMtime + 1 < sourceMtime) {
+        // Before claiming "stale", verify the match is structurally related.
+        // A same-basename hit in an unrelated subtree (e.g. `head.js` in a
+        // completely different upstream test helper) should be reported as
+        // missing — the operator needs to check registration, not puzzle
+        // over why an unrelated file appears "older than the source".
+        if (!isConfidentMatch(source, artifact)) {
+            const where = isTestPath(source) ? '_tests/' : 'dist/';
+            return {
+                source,
+                artifact: undefined,
+                status: 'missing',
+                warning: `Audit: engine/${source} was touched but no related packaged artifact with basename "${basename(source)}" was found under ${where} (nearest same-basename file ${artifact} lives in an unrelated subtree). Missing moz.build / jar.mn / package-manifest.in registration?`,
+            };
+        }
+        return {
+            source,
+            artifact,
+            status: 'stale',
+            warning: `Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`,
+        };
+    }
+    return { source, artifact, status: 'updated' };
+}
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
@@ -193,57 +388,23 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
         verbose('Audit skipped: no dist tree found under obj-*/dist/.');
         return summary;
     }
+    const testsRoot = await resolveTestsRoot(engineDir);
+    const testsPackaged = await hasPackagedTestsMarker(testsRoot);
     const changed = await collectChangedFiles(engineDir, baseline);
     if (changed.length === 0) {
         return summary;
     }
+    const ctx = { engineDir, distRoot, testsRoot, testsPackaged };
     for (const source of changed) {
-        if (!isPackageablePath(source)) {
-            summary.skipped += 1;
-            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
-            continue;
-        }
-        const sourcePath = join(engineDir, source);
-        let sourceMtime;
-        try {
-            const sourceStat = await stat(sourcePath);
-            sourceMtime = sourceStat.mtimeMs;
-        }
-        catch {
-            // File was deleted since the diff was computed. Skip — a deletion
-            // that didn't propagate to the dist tree is a distinct class of bug
-            // we don't audit yet.
-            summary.skipped += 1;
-            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
-            continue;
-        }
-        const artifact = await findArtifactByBasename(distRoot, basename(source));
-        if (!artifact) {
-            summary.missing += 1;
-            summary.entries.push({ source, artifact: undefined, status: 'missing' });
-            warn(`Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${distRoot}. Missing moz.build / jar.mn / package-manifest.in registration?`);
-            continue;
-        }
-        let artifactMtime;
-        try {
-            const artifactStat = await stat(artifact);
-            artifactMtime = artifactStat.mtimeMs;
-        }
-        catch {
-            // Disappeared after the directory scan; treat as missing.
-            summary.missing += 1;
-            summary.entries.push({ source, artifact, status: 'missing' });
-            warn(`Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`);
-            continue;
-        }
-        if (artifactMtime + 1 < sourceMtime) {
-            summary.stale += 1;
-            summary.entries.push({ source, artifact, status: 'stale' });
-            warn(`Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`);
-            continue;
-        }
-        summary.updated += 1;
-        summary.entries.push({ source, artifact, status: 'updated' });
+        const result = await auditSinglePath(source, ctx);
+        summary[result.status] += 1;
+        summary.entries.push({
+            source: result.source,
+            artifact: result.artifact,
+            status: result.status,
+        });
+        if (result.warning)
+            warn(result.warning);
     }
     info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
     return summary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",