@hominis/fireforge 0.15.4 → 0.15.5

package/CHANGELOG.md

@@ -38,7 +38,11 @@
 
 ### 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`.
 - 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 +74,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,13 @@ 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 four 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.
+- **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`.
+- **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.
+
 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,36 @@
+/** 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.
+ * 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,170 @@
+// 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.
+ *
+ * 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.
+ *
+ * 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;
+}
+/**
+ * Determines whether the given source file is gated off on the current
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build.
+ * 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) {
+    const sourceDir = dirname(join(engineDir, sourcePath));
+    const mozBuild = await findOwningMozBuild(engineDir, sourceDir);
+    if (!mozBuild)
+        return { gatedOff: false };
+    let content;
+    try {
+        content = await readText(mozBuild);
+    }
+    catch {
+        return { gatedOff: false };
+    }
+    const sourceBasename = sourcePath.split('/').pop() ?? '';
+    const expression = findEnclosingGate(content, sourceBasename);
+    if (!expression)
+        return { gatedOff: false };
+    let host;
+    try {
+        host = getPlatform();
+    }
+    catch {
+        return { gatedOff: false };
+    }
+    if (isGateOffHost(expression, host)) {
+        return { gatedOff: true, gateExpression: expression };
+    }
+    return { gatedOff: false, gateExpression: expression };
+}
+//# 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 { 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,97 @@ 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;
+}
+/**
+ * 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];
+}
+/**
+ * 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 moz.build "${gate.gateExpression ?? '?'}".`);
+        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) {
+        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 +282,22 @@ 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 changed = await collectChangedFiles(engineDir, baseline);
     if (changed.length === 0) {
         return summary;
     }
+    const ctx = { engineDir, distRoot, testsRoot };
     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.5",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",