@hominis/fireforge 0.43.1 → 0.44.1

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

@@ -4,34 +4,29 @@
  *
  * `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.
+ * `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 warns about every gated file on every off-platform build.
  *
  * 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.)
+ *   2. Path-convention gates — certain directory fragments are packaged by
+ *      platform-specific Makefile.in / NSIS recipes that FireForge does not
+ *      parse, so a file under `browser/installer/windows/` or any
+ *      `/stubinstaller/` subtree is Windows-only regardless of what its
+ *      nearest moz.build says.
  *
- * 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.
+ * The detection is intentionally lightweight: walk up from the source file
+ * to the closest `moz.build`, scan it for the source basename inside an
+ * `if CONFIG[...]:` block, and check whether the gate matches the host. The
+ * path-convention pass runs only when no moz.build gate is found, so an
+ * explicit 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.
+ * Best-effort by design. False negatives (missing a gate and warning anyway)
+ * are tolerable — the audit is warn-only. False positives (skipping a file
+ * that should ship on this host) are not, so it errs toward NOT skipping
+ * when uncertain.
  */
 import { dirname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
@@ -144,17 +139,14 @@ export function findEnclosingGate(content, basename) {
 }
 /**
  * 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.
+ * 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.
+ * `stubinstaller/` is the Windows NSIS stub installer asset tree, referenced
+ * from `browser/installer/windows/Makefile.in` and `nsis/stub.nsh` rather
+ * than through any `if CONFIG[…]:` block an ancestor moz.build exposes.
  */
 const PATH_GATES = [
     { fragment: '/stubinstaller/', platform: 'win32', label: 'path convention: /stubinstaller/' },

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

@@ -3,33 +3,25 @@
  * Registration-aware artifact resolution for the post-build dist-tree audit.
  *
  * The basename-plus-similarity heuristic in `build-audit-resolve.ts` cannot
- * distinguish two unrelated files that share a source basename. Motivating
- * case: one fork registers `content/mybrowser.js` in `browser/base/jar.mn`
- * (packaged under `chrome/browser/content/browser/mybrowser.js`) while an
- * unrelated patch registers a `mybrowser.js` pref file under
- * `browser/defaults/preferences/`. The basename walker surfaces both
- * candidates, `scoreCandidate` awards them an equal trailing-overlap score
- * (basename only, no meaningful mid-path match), and whichever the
- * directory walk hits first wins — frequently the wrong one.
+ * distinguish two unrelated files that share a source basename: one fork
+ * registers `content/mybrowser.js` in `browser/base/jar.mn` (packaged under
+ * `chrome/browser/content/browser/mybrowser.js`) while an unrelated patch
+ * registers a `mybrowser.js` pref file under `browser/defaults/preferences/`.
+ * The basename walker surfaces both, `scoreCandidate` awards them an equal
+ * trailing-overlap score, and whichever the directory walk hits first wins.
  *
- * This module anchors resolution to the `(source)` reference inside
- * `jar.mn`. For a source under audit we walk its ancestor directories for
- * an owning `jar.mn`, find the entry whose `(source)` resolves to our
- * path, and expose both the target path recorded in the entry and the
- * manifest that owns it. Callers in `build-audit.ts` prefer candidates
- * whose absolute dist-tree path ends with the registered target, and
- * report an unambiguous "registered but not packaged" miss when no such
- * candidate exists — rather than falling through to the heuristic which
- * would pick an unrelated same-basename file.
+ * This module anchors resolution to the `(source)` reference inside `jar.mn`.
+ * For a source under audit it walks the ancestor directories for an owning
+ * `jar.mn`, finds the entry whose `(source)` resolves to that path, and
+ * exposes both the registered target and the manifest that owns it. Callers
+ * prefer candidates whose dist-tree path ends with the registered target and
+ * report an unambiguous "registered but not packaged" miss when none exists.
  *
- * Fallback semantics: when no jar.mn registration is found, the caller
- * is expected to use the similarity heuristic. Registration wins when it
- * exists; the heuristic fills the gap for sources registered through
- * moz.build (`FINAL_TARGET_FILES`, `JS_PREFERENCE_FILES`, etc.) or
- * `package-manifest.in` entries, which this module intentionally does
- * not parse — supporting every Firefox registration surface would bloat
- * the audit, and the heuristic's remaining weak case (unrelated same-
- * basename hits) is surfaced to the operator in the warning copy.
+ * When no jar.mn registration is found, the caller falls back to the
+ * similarity heuristic — which covers sources registered through moz.build
+ * (`FINAL_TARGET_FILES`, `JS_PREFERENCE_FILES`) or `package-manifest.in`.
+ * Parsing every Firefox registration surface would bloat the audit, and the
+ * heuristic's weak case is surfaced to the operator in the warning copy.
  */
 import { basename, dirname, join, relative, sep } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';

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

@@ -27,29 +27,27 @@ export declare function countTrailingSegmentMatches(a: string, b: string): numbe
 /**
  * Path segments too common to identify an artifact on their own.
  *
- * Shared deliberately: this set governs two halves of ONE decision, and the
- * halves disagreed before 0.41.0. `scoreCandidate` (selection) used an
- * 11-entry copy while `isConfidentMatch` (confirmation, in `build-audit.ts`)
- * used a 17-entry one, so a source path containing `test`, `tests`, `unit`,
- * `common`, `xpcshell` or `mochitest` earned a +1 selection bonus for a
- * segment that confirmation then rejected as meaningless — the chosen
- * artifact could never be confirmed. The union is authoritative; any addition
- * must apply to both halves, which is now automatic.
+ * Shared deliberately: this set governs two halves of ONE decision —
+ * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
+ * `build-audit.ts`). When the halves kept separate copies they disagreed,
+ * so a source path could earn a selection bonus for a segment that
+ * confirmation then rejected as meaningless, leaving the chosen artifact
+ * unconfirmable. Any addition must apply to both halves, which is now
+ * automatic.
  */
 export declare const GENERIC_PATH_SEGMENTS: ReadonlySet<string>;
 /**
  * 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.).
+ * 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`, or the branding dir name itself).
  *
- * The bonus exists because Firefox packaging often re-roots files: a
- * source `branding/<name>/content/aboutDialog.css` lands at
+ * 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.
+ * trails-match, but the `branding` segment moved into the middle of the
+ * candidate path. Without the bonus that candidate ties with the unrelated
+ * `chrome/browser/content/browser/aboutDialog.css`.
  *
  * @param sourcePath Engine-relative POSIX path
  * @param candidatePath Absolute path under the dist tree

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

@@ -2,28 +2,25 @@
 /*
  * 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:
+ * Resolves the expected on-disk artifact location for a given engine source
+ * path. Matching purely by basename produces three classes of false
+ * positive, each of which these helpers exist to avoid:
  *
- *   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.
+ *   1. A branding override (`engine/browser/branding/<name>/content/
+ *      aboutDialog.css`, shipped at `chrome/browser/content/branding/
+ *      aboutDialog.css`) matching the unrelated upstream
+ *      `chrome/browser/content/browser/aboutDialog.css`. Handled by ranking
+ *      same-basename candidates on shared trailing path segments.
+ *   2. Test files (`browser_*.js`, `test_*.js`) living under `_tests/`, not
+ *      `dist/`. Handled by routing test paths to a separate resolver.
  *   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`.
+ *      that are consumed rather than packaged. 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';
+import { normalizePathSlashes } from '../utils/paths.js';
 /** Maximum directory depth to traverse when scanning a tree root. */
 const MAX_SCAN_DEPTH = 12;
 /**
@@ -58,11 +55,19 @@ export function isTestPath(sourcePath) {
     return false;
 }
 /**
- * Splits a POSIX path into segments, dropping empties.
- * @param path POSIX-separated path
+ * Splits a path into segments, dropping empties.
+ *
+ * Separators are normalized first because the candidates come from `join()`
+ * over a `readdir` walk of the dist tree: on Windows those carry backslashes,
+ * which a `/`-only split collapses into a SINGLE segment. Every candidate then
+ * scores the same, so the trailing-overlap heuristic that disambiguates
+ * same-basename artifacts (`branding/…/aboutDialog.css` versus
+ * `browser/…/aboutDialog.css`) silently picks an arbitrary one.
+ *
+ * @param path Path in either separator style
  */
 function pathSegments(path) {
-    return path.split('/').filter(Boolean);
+    return normalizePathSlashes(path).split('/').filter(Boolean);
 }
 /**
  * Counts how many trailing segments two paths share. Used to score
@@ -89,14 +94,13 @@ export function countTrailingSegmentMatches(a, b) {
 /**
  * Path segments too common to identify an artifact on their own.
  *
- * Shared deliberately: this set governs two halves of ONE decision, and the
- * halves disagreed before 0.41.0. `scoreCandidate` (selection) used an
- * 11-entry copy while `isConfidentMatch` (confirmation, in `build-audit.ts`)
- * used a 17-entry one, so a source path containing `test`, `tests`, `unit`,
- * `common`, `xpcshell` or `mochitest` earned a +1 selection bonus for a
- * segment that confirmation then rejected as meaningless — the chosen
- * artifact could never be confirmed. The union is authoritative; any addition
- * must apply to both halves, which is now automatic.
+ * Shared deliberately: this set governs two halves of ONE decision —
+ * `scoreCandidate` (selection) and `isConfidentMatch` (confirmation, in
+ * `build-audit.ts`). When the halves kept separate copies they disagreed,
+ * so a source path could earn a selection bonus for a segment that
+ * confirmation then rejected as meaningless, leaving the chosen artifact
+ * unconfirmable. Any addition must apply to both halves, which is now
+ * automatic.
  */
 export const GENERIC_PATH_SEGMENTS = new Set([
     'content',
@@ -119,17 +123,16 @@ export const GENERIC_PATH_SEGMENTS = new Set([
 ]);
 /**
  * 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.).
+ * 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`, or the branding dir name itself).
  *
- * The bonus exists because Firefox packaging often re-roots files: a
- * source `branding/<name>/content/aboutDialog.css` lands at
+ * 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.
+ * trails-match, but the `branding` segment moved into the middle of the
+ * candidate path. Without the bonus that candidate ties with the unrelated
+ * `chrome/browser/content/browser/aboutDialog.css`.
  *
  * @param sourcePath Engine-relative POSIX path
  * @param candidatePath Absolute path under the dist tree

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

@@ -2,29 +2,28 @@
 /*
  * Known source→packaging path transforms for the post-build dist-tree audit.
  *
- * Motivating case: a source at `engine/browser/base/content/foo.js` ships
- * under `chrome/browser/content/browser/foo.js`. If an unrelated patch
- * registers a different `foo.js` elsewhere in the tree (e.g. a pref file
- * under `browser/defaults/preferences/foo.js`), the basename walker
- * surfaces both candidates, `scoreCandidate` awards them an identical
- * trailing-overlap score (basename only; every intermediate segment is
- * in the generic list), and whichever the directory walk hits first wins.
- * The heuristic then declares the chosen candidate "not structurally
- * related" and reports the correctly-packaged chrome resource as missing.
+ * A source at `engine/browser/base/content/foo.js` ships under
+ * `chrome/browser/content/browser/foo.js`. If an unrelated patch registers a
+ * different `foo.js` elsewhere (say a pref file under
+ * `browser/defaults/preferences/`), the basename walker surfaces both, and
+ * `scoreCandidate` awards them an identical trailing-overlap score because
+ * every intermediate segment is in the generic list. The heuristic then
+ * declares the winner "not structurally related" and reports the
+ * correctly-packaged chrome resource as missing.
  *
- * The transforms below anchor resolution to the well-known subtree→chrome
- * conventions used by upstream mozilla-central jar.mn. When a source
- * matches one of these prefixes, a candidate whose absolute path ends
- * with the implied chrome suffix is treated as a confident match — the
- * scorer never runs and the structural-relation check is bypassed.
+ * The transforms below anchor resolution to the subtree→chrome conventions
+ * upstream mozilla-central jar.mn uses. A candidate whose path ends with the
+ * implied chrome suffix is a confident match: the scorer never runs and the
+ * structural-relation check is bypassed.
  *
- * Scope is intentionally narrow: only subtrees whose packaging target is
- * stable across every fork we know about. A fork that reroutes a known
- * subtree can still win by adding `(source)` annotations in its own
- * `jar.mn`, which `resolveArtifactByRegistration` consults first.
+ * Scope is intentionally narrow — only subtrees whose packaging target is
+ * stable across forks. A fork that reroutes a known subtree can still win by
+ * adding `(source)` annotations in its own `jar.mn`, which
+ * `resolveArtifactByRegistration` consults first.
  */
 import { basename, sep } from 'node:path';
 import { findAllByBasename } from './build-audit-resolve.js';
+import { WIDGETS_DIR } from './furnace-constants.js';
 /**
  * Table of `prefix → chrome-suffix` transforms. Each rule names an
  * engine-relative subtree prefix and produces the expected dist-tree
@@ -38,7 +37,7 @@ const KNOWN_TRANSFORMS = [
         build: (rest) => `chrome/browser/content/browser/${rest}`,
     },
     {
-        prefix: 'toolkit/content/widgets/',
+        prefix: `${WIDGETS_DIR}/`,
         build: (rest) => `chrome/toolkit/content/global/elements/${rest}`,
     },
     {

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

@@ -6,7 +6,7 @@
  * but never registered in moz.build, jar.mn, or package-manifest.in, so
  * the mach build reports success but the packaged bundle carries stale
  * or missing content. A fork-specific pref file that was never registered
- * for packaging is the motivating case.
+ * for packaging is the canonical case.
  *
  * The audit is best-effort and warn-only:
  *   - It enumerates engine files changed since the previous build baseline
@@ -33,7 +33,7 @@
  *     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 { readdir, stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
@@ -59,13 +59,11 @@ 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/'];
 /**
- * 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
+ * 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 ship in the bundle. Auditing
+ * them guarantees a false positive on every edit, and worse, an unrelated
+ * upstream `moz.build` sitting at e.g. `MyBrowser.app/Contents/moz.build`
  * gets matched as a "stale artifact" of an entirely different file.
  */
 const BUILD_INPUT_BASENAMES = new Set([
@@ -92,13 +90,11 @@ export function isPackageablePath(sourcePath) {
     if (BUILD_INPUT_BASENAMES.has(basename(sourcePath)))
         return false;
     // `.inc.xhtml` fragments are consumed via `#include` from a registered
-    // chrome document and resolved at packaging time — they never ship as
-    // a standalone packaged artifact. 2026-04-21 eval (Finding #11):
-    // `fireforge build --ui` after `wire --dom` flagged the wired
-    // `*.inc.xhtml` as "missing packaged artifact" even though
-    // `register` correctly refuses to register it and the operator
-    // followed the documented workflow. Mirror the same carve-out the
-    // register rules apply.
+    // chrome document and resolved at packaging time — they never ship as a
+    // standalone packaged artifact, so auditing them flags a wired
+    // `*.inc.xhtml` as "missing packaged artifact" even though `register`
+    // correctly refuses to register it. Mirror the carve-out the register
+    // rules apply.
     if (sourcePath.endsWith('.inc.xhtml'))
         return false;
     for (const ext of PACKAGEABLE_EXTENSIONS) {
@@ -132,7 +128,6 @@ export function isXpcomManifestPath(sourcePath) {
  * one-or-none.
  */
 async function resolveDistRoot(engineDir) {
-    const { readdir } = await import('node:fs/promises');
     let entries;
     try {
         entries = await readdir(engineDir);
@@ -156,7 +151,6 @@ async function resolveDistRoot(engineDir) {
  * 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);
@@ -207,18 +201,17 @@ function searchRootsFor(source, distRoot, testsRoot) {
 }
 /**
  * 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.
+ * 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 agree too. Candidates sharing only 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`.
+ * Cross-tree re-rooting (e.g. `branding/<name>/content/foo.css` landing at
+ * `chrome/<area>/content/branding/foo.css`) bypasses this floor:
+ * `scoreCandidate` awards a non-generic-segment bonus that lifts confidence
+ * regardless of trailing overlap. See `isConfidentMatch` below.
  */
 const MIN_TRAILING_SEGMENT_OVERLAP = 2;
 /**
@@ -285,11 +278,8 @@ async function auditSinglePath(source, ctx) {
     const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
     // Registration-aware resolution first: a `jar.mn` entry whose `(source)`
     // references this file is authoritative over the basename-similarity
-    // heuristic. The motivating case is a fork that adds `content/foo.js`
-    // in `browser/base/jar.mn` while an unrelated patch registers a pref
-    // file of the same basename elsewhere — the heuristic cannot
-    // distinguish them, so the audit falsely reports "missing" against the
-    // correctly-packaged file.
+    // heuristic, which cannot distinguish a fork's `content/foo.js` from an
+    // unrelated pref file of the same basename elsewhere in the tree.
     const registered = await resolveArtifactByRegistration(ctx.engineDir, source, roots);
     if (registered) {
         return evaluateArtifactMtime(source, registered.artifact, sourceMtime, { registered: true });
@@ -305,14 +295,10 @@ async function auditSinglePath(source, ctx) {
     // source under `browser/base/content/` (or another prefix whose chrome
     // target is stable across forks) is matched against its expected
     // `chrome/...` suffix rather than whichever same-basename candidate the
-    // directory walk happened to hit first. Motivating case: a source at
-    // `engine/browser/base/content/foo.js` whose correctly-packaged artifact
-    // lives at `chrome/browser/content/browser/foo.js` but which an unrelated
-    // patch also placed under `browser/defaults/preferences/foo.js`; every
-    // intermediate segment of the source is in the scorer's generic list,
-    // so `resolveBestArtifact` picks whichever hit first and `isConfidentMatch`
-    // rejects every candidate, classifying the correctly-packaged file as
-    // "missing" even though packaging had landed it.
+    // directory walk happened to hit first. Every intermediate segment of such
+    // a source is in the scorer's generic list, so `resolveBestArtifact` picks
+    // arbitrarily and `isConfidentMatch` then rejects every candidate,
+    // classifying a correctly-packaged file as "missing".
     const byTransform = await resolveArtifactByKnownTransform(source, roots);
     if (byTransform) {
         return evaluateArtifactMtime(source, byTransform, sourceMtime, { registered: true });

package/dist/src/core/build-baseline-types.d.ts

@@ -23,18 +23,16 @@ export interface BuildBaseline {
      */
     binaryName: string;
     /**
-     * Content hash per packageable engine path that was dirty at build
-     * time (modified-against-HEAD or untracked). Used by
-     * `checkStaleBuildForTest` to distinguish "this file's content was
-     * already in `dist/` when the build completed" from "this file has
-     * been edited since". Missing on baselines written before 0.16.0; the
-     * stale-check falls back to the path-only comparison in that case,
-     * so older baselines retain their existing behavior.
+     * Content hash per packageable engine path that was dirty at build time
+     * (modified-against-HEAD or untracked). Used by `checkStaleBuildForTest`
+     * to distinguish "this file's content was already in `dist/` when the
+     * build completed" from "this file has been edited since". When absent,
+     * the stale-check falls back to a path-only comparison.
      *
-     * Keys are engine-relative POSIX paths. Values are hex-encoded
-     * SHA-256 digests of the file contents at the moment the baseline
-     * was recorded, or {@link DELETED_FILE_FINGERPRINT} when the successful
-     * build observed a tracked deletion.
+     * Keys are engine-relative POSIX paths. Values are hex-encoded SHA-256
+     * digests of the file contents at the moment the baseline was recorded,
+     * or {@link DELETED_FILE_FINGERPRINT} when the successful build observed
+     * a tracked deletion.
      */
     packageableFingerprints?: Record<string, string>;
     /**
@@ -50,9 +48,7 @@ export interface BuildBaseline {
      *   an `--allow-stale-build` run over uncovered paths is refused rather
      *   than dispatched into a hang.
      *
-     * Missing on baselines written before 0.37.0 — only `fireforge build`
-     * wrote baselines then, so "full" is the honest historical value and the
-     * stale-check treats an absent field as full coverage.
+     * An absent field is treated as full coverage.
      *
      * The record is project-scoped, which is also per-obj-dir: multi-objdir
      * checkouts are refused up-front (`AmbiguousBuildArtifactsError`), so at
@@ -62,26 +58,25 @@ export interface BuildBaseline {
      * general — every baseline write refreshes `packageableFingerprints` for
      * ALL dirty packageable paths, so a blind union would whitewash an
      * earlier scope's edited fixtures while `obj-*`/`_tests/` still holds its
-     * stale staging; coverage therefore REPLACES by default.
+     * stale staging. Coverage therefore REPLACES by default.
      *
-     * The one exception is `test --build --extend-coverage`, which
-     * unions only after proving the previous record's anchor still holds:
-     * same engine HEAD, same {@link BuildBaseline.mozconfigHash}, and every
-     * previously fingerprinted path byte-identical — i.e. the wholesale
-     * fingerprint refresh is a no-op for everything the earlier scope's
-     * staging depended on. Any divergence refuses fail-closed. See
-     * `src/core/coverage-extend.ts`, which also documents the one boundary
-     * that guard does not cover (dirty non-packageable fixtures).
+     * The one exception is `test --build --extend-coverage`, which unions only
+     * after proving the previous record's anchor still holds: same engine
+     * HEAD, same {@link BuildBaseline.mozconfigHash}, and every previously
+     * fingerprinted path byte-identical — i.e. the wholesale fingerprint
+     * refresh is a no-op for everything the earlier scope's staging depended
+     * on. Any divergence refuses fail-closed. See `src/core/coverage-extend.ts`
+     * for the one boundary that guard does not cover (dirty non-packageable
+     * fixtures).
      */
     testPackagingCoverage?: TestPackagingCoverage;
     /**
      * Hex-encoded SHA-256 of `engine/mozconfig` as it stood for this build.
      * Recorded because the mozconfig is REGENERATED from project-side
-     * `configs/*.mozconfig` templates plus `fireforge.json` on every build,
-     * so `engineHeadSha` does not cover it: two builds at the same engine SHA
-     * can configure differently. Consumed by the `--extend-coverage` anchor.
-     * Missing on pre-0.41.0 baselines, which `--extend-coverage` refuses
-     * (one plain build re-records it).
+     * `configs/*.mozconfig` templates plus `fireforge.json` on every build, so
+     * `engineHeadSha` does not cover it: two builds at the same engine SHA can
+     * configure differently. Consumed by the `--extend-coverage` anchor, which
+     * refuses when the field is absent (one plain build re-records it).
      */
     mozconfigHash?: string;
     /**
@@ -89,18 +84,17 @@ export interface BuildBaseline {
      * the last FULL-coverage build plus content fingerprints of the
      * `components.conf` manifests that were dirty at that moment. Written
      * fresh only on FULL-coverage baseline writes (`fireforge build`,
-     * `build --ui`, path-less `test --build`); a scoped `test --build`
-     * carries the previous record forward verbatim, because `mach build
-     * faster` does not rebake `components.conf` registrations into the
-     * compiled table. Missing on pre-0.38.0 baselines — the
-     * static-components stale check degrades to "fresh" in that case.
+     * `build --ui`, path-less `test --build`); a scoped `test --build` carries
+     * the previous record forward verbatim, because `mach build faster` does
+     * not rebake `components.conf` registrations into the compiled table. When
+     * absent, the static-components stale check degrades to "fresh".
      */
     staticComponentsBaseline?: StaticComponentsBaseline;
     /**
      * Invocation shape that recorded this baseline (`'fireforge build'`,
      * `'fireforge build --ui'`, `'fireforge test --build [paths]'`).
-     * Informational — surfaced by `fireforge status --test-coverage`.
-     * Missing on pre-0.39.0 baselines; render as "unknown".
+     * Informational — surfaced by `fireforge status --test-coverage`. Render
+     * as "unknown" when absent.
      */
     recordedBy?: string;
 }

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

@@ -36,6 +36,7 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
  * the current binaryName. Caller is responsible for only invoking this
  * after the build exit code was zero.
+ *
  * @param projectRoot - Root directory of the project
  * @param engineDir - Path to the engine directory
  * @param binaryName - Current `binaryName` from fireforge.json
@@ -51,9 +52,9 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  * @param staticComponentsHandling - `'auto'` (default) refreshes the
  *   static-components anchor whenever the coverage claim is `'full'` or
  *   absent. `'refresh'` records it even for a scoped coverage claim whose
- *   implementation escalated to a full build. `'carry-forward'` always keeps the previous anchor: needed by
- * `--extend-coverage`, whose union can EVALUATE to `'full'`
- *   while the build that produced it was still a scoped `mach build
- *   faster` that did not rebake the compiled table.
+ *   implementation escalated to a full build. `'carry-forward'` always
+ *   keeps the previous anchor: needed by `--extend-coverage`, whose union
+ *   can EVALUATE to `'full'` while the build that produced it was still a
+ *   scoped `mach build faster` that did not rebake the compiled table.
  */
 export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string, staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward'): Promise<void>;