@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/branding.d.ts

@@ -1,21 +1,14 @@
 import { FireForgeError } from '../errors/base.js';
 import type { ProjectLicense } from '../types/config.js';
-/**
- * Error thrown when branding operations fail.
- */
-export declare class BrandingError extends FireForgeError {
-    readonly code: 6;
-    get userMessage(): string;
-}
 /**
  * Error thrown when the generated `mozconfig` references a `--with-branding`
  * directory that does not match the branding tree FireForge set up. The
- * mismatch is a silent-corruption hazard — `mach configure` picks the value
+ * mismatch is a silent-corruption hazard: `mach configure` picks the value
  * from mozconfig but the scaffolded branding lives elsewhere, so the build
  * fails deep inside moz.build resolution with a confusing "path does not
  * exist" message. Surface it as an actionable preflight instead.
  *
- * Setup renders templates under `configs/` with `${binaryName}` baked in; a
+ * Setup renders templates under `configs/` with `${binaryName}` baked in. A
  * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
  * re-templating) leaves those names stale while `setupBranding` keeps using
  * the current value. Both directions produce the same class of build break.
@@ -44,8 +37,8 @@ export interface BrandingConfig {
      * Project license (from fireforge.json). Used to stamp the generated
      * `configure.sh`, `brand.properties`, and `brand.ftl` files with the
      * matching header so `patch-lint` does not flag them for
-     * `missing-license-header` when the project is not MPL-2.0. Optional;
-     * falls back to {@link DEFAULT_LICENSE}.
+     * `missing-license-header` when the project is not MPL-2.0. Optional.
+     * Falls back to {@link DEFAULT_LICENSE}.
      */
     license?: ProjectLicense;
 }
@@ -54,7 +47,7 @@ export interface BrandingConfig {
  * `toolkit/moz.configure` composes `CFBundleIdentifier` as
  * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
  * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
- * LEAF segment while the generated mozconfig carries the remainder as
+ * leaf segment while the generated mozconfig carries the remainder as
  * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
  * double-prefixes the shipped bundle id. Config validation guarantees a
  * reverse-domain id, so the split always has both halves.

package/dist/src/core/branding.js

@@ -4,11 +4,12 @@ import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { copyDir, pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from './license-headers.js';
 /**
  * Error thrown when branding operations fail.
  */
-export class BrandingError extends FireForgeError {
+class BrandingError extends FireForgeError {
     code = ExitCode.PATCH_ERROR;
     get userMessage() {
         return `Branding Error: ${this.message}\n\nBranding is required to set MOZ_APP_VENDOR, MOZ_MACBUNDLE_ID, and other Firefox identity values.`;
@@ -17,12 +18,12 @@ export class BrandingError extends FireForgeError {
 /**
  * Error thrown when the generated `mozconfig` references a `--with-branding`
  * directory that does not match the branding tree FireForge set up. The
- * mismatch is a silent-corruption hazard — `mach configure` picks the value
+ * mismatch is a silent-corruption hazard: `mach configure` picks the value
  * from mozconfig but the scaffolded branding lives elsewhere, so the build
  * fails deep inside moz.build resolution with a confusing "path does not
  * exist" message. Surface it as an actionable preflight instead.
  *
- * Setup renders templates under `configs/` with `${binaryName}` baked in; a
+ * Setup renders templates under `configs/` with `${binaryName}` baked in. A
  * later edit to `fireforge.json`'s `binaryName` (or a re-setup without
  * re-templating) leaves those names stale while `setupBranding` keeps using
  * the current value. Both directions produce the same class of build break.
@@ -56,7 +57,7 @@ export class BrandingMozconfigMismatchError extends FireForgeError {
  * `toolkit/moz.configure` composes `CFBundleIdentifier` as
  * `<--with-distribution-id>.<MOZ_MACBUNDLE_ID>` (the distribution id
  * defaults to `org.mozilla`), so branding `configure.sh` must carry only the
- * LEAF segment while the generated mozconfig carries the remainder as
+ * leaf segment while the generated mozconfig carries the remainder as
  * `--with-distribution-id`. Writing the full appId into `MOZ_MACBUNDLE_ID`
  * double-prefixes the shipped bundle id. Config validation guarantees a
  * reverse-domain id, so the split always has both halves.
@@ -361,7 +362,7 @@ export async function isBrandingSetup(engineDir, config) {
  * @returns true if the path is managed by branding tooling
  */
 export function isBrandingManagedPath(file, binaryName) {
-    const normalized = file.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(file);
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
         normalized === brandingRoot ||

package/dist/src/core/browser-wire.d.ts

@@ -30,7 +30,7 @@ export interface WireOptions {
      * replacement path here.
      */
     domTargetPath?: string | undefined;
-    /** Dry run — don't write any files */
+    /** Dry run: don't write any files */
     dryRun?: boolean | undefined;
     /** Insert init block after the block containing this name */
     after?: string | undefined;

package/dist/src/core/browser-wire.js

@@ -4,11 +4,14 @@ import { GeneralError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { toRootRelativePath } from '../utils/paths.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { assertSnapshotted, createRollbackJournal, restoreRollbackJournal, snapshotFile, } from './furnace-rollback.js';
 import { registerBrowserContent } from './moz-manifest-register.js';
-import { DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
-import { addDestroyToBrowserInit, addDomFragment, addInitToBrowserInit, addSubscriptToBrowserMain, } from './wire-targets.js';
+import { addDestroyToBrowserInit } from './wire-destroy.js';
+import { addDomFragment, DEFAULT_DOM_TARGET } from './wire-dom-fragment.js';
+import { addInitToBrowserInit } from './wire-init.js';
+import { addSubscriptToBrowserMain } from './wire-subscript.js';
 export const DEFAULT_BROWSER_SUBSCRIPT_DIR = 'browser/base/content';
 const BROWSER_BASE_DIR = 'browser/base';
 /**
@@ -25,7 +28,7 @@ export async function wireSubscript(root, name, options = {}) {
     // Compute jar.mn source path relative to browser/base/
     let jarMnSourcePath;
     if (subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR) {
-        const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
+        const relPath = normalizePathSlashes(relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)));
         jarMnSourcePath = `${relPath}/${name}.js`;
     }
     if (options.dryRun) {
@@ -83,9 +86,9 @@ export async function wireSubscript(root, name, options = {}) {
         let initAdded = false;
         if (options.init) {
             // The snapshot above is taken when init or destroy is `!== undefined`
-            // while these writes fire on truthiness — close, but two separate
-            // conditions over the same file, which is exactly the pairing that
-            // drifts when a third writer is added later.
+            // while these writes fire on truthiness. Close, but two separate
+            // conditions over the same file, and that kind of pairing drifts when
+            // a third writer is added later.
             assertSnapshotted(journal, join(engineDir, 'browser/base/content/browser-init.js'), 'browser wire init');
             initAdded = await addInitToBrowserInit(engineDir, options.init, options.after, marker);
         }
@@ -116,7 +119,7 @@ export async function wireSubscript(root, name, options = {}) {
         // original wire failure and the rollback failure so the operator knows
         // the engine may be in a partially-wired state that needs manual
         // attention. The original error's message is preserved so the user sees
-        // *why* the wire failed (e.g. "Could not find insertion point in chrome
+        // why the wire failed (e.g. "Could not find insertion point in chrome
         // document") alongside any rollback diagnosis.
         const originalMessage = toError(error).message;
         try {

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

@@ -25,10 +25,10 @@ export declare function findEnclosingGate(content: string, basename: string): st
 /**
  * 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
+ * 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
+ * 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
@@ -36,3 +36,32 @@ export declare function findEnclosingGate(content: string, basename: string): st
  * @returns Detection result
  */
 export declare function detectPlatformGate(engineDir: string, sourcePath: string): Promise<PlatformGateResult>;
+/**
+ * Result of an ancestor `DIRS +=` gate lookup.
+ */
+export interface AncestorDirsGateResult {
+    /** True when an ancestor's `DIRS` entry is gated off on this host. */
+    gatedOff: boolean;
+    /** The gate expression that excluded the directory. */
+    gateExpression?: string;
+    /** Engine-relative path of the `moz.build` carrying the gate. */
+    gateFile?: string;
+}
+/**
+ * Determines whether the source file's directory is excluded from this
+ * build by a gate in an ancestor `moz.build`.
+ *
+ * `detectPlatformGate` reads only the file's own nearest `moz.build`, which
+ * misses the common Firefox shape where the whole subtree is reached
+ * through a conditional `DIRS +=` one or more levels up: nothing in
+ * `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet none of
+ * it is built on macOS.
+ *
+ * Errs toward not skipping, like the rest of this module: an unreadable or
+ * oversized ancestor, or a directory no `DIRS` entry names, yields
+ * `gatedOff: false`.
+ *
+ * @param engineDir - Absolute path to the engine root
+ * @param sourcePath - Engine-relative POSIX path of the source file
+ */
+export declare function detectAncestorDirsGate(engineDir: string, sourcePath: string): Promise<AncestorDirsGateResult>;

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

@@ -6,35 +6,36 @@
  * `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
+ * 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
+ *   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: walk up from the source file
+ * The detection is 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.
  *
- * 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.
+ * Best-effort. False negatives (missing a gate and warning anyway) are
+ * tolerable because the audit is warn-only. False positives (skipping a file
+ * that should ship on this host) are not tolerable, so it errs toward not
+ * skipping when uncertain.
  */
+import { stat } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { getPlatform } from '../utils/platform.js';
 import { escapeRegex } from '../utils/regex.js';
 /**
  * Tokens that uniquely identify a Windows-only `if CONFIG[...]:` block.
- * `MAKENSISU` is the Windows stubinstaller compiler; `OS_TARGET ==
+ * `MAKENSISU` is the Windows stubinstaller compiler. `OS_TARGET ==
  * "WINNT"` and `MOZ_WIDGET_TOOLKIT == "windows"` are the conventional
  * platform discriminators.
  */
@@ -52,7 +53,7 @@ function isGateOffHost(expression, host) {
     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
+    // 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)
@@ -68,7 +69,7 @@ function isGateOffHost(expression, host) {
 /**
  * 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
+ * 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) {
@@ -184,10 +185,10 @@ function findPathConventionGate(sourcePath) {
 /**
  * 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
+ * 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
+ * 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
@@ -231,3 +232,142 @@ export async function detectPlatformGate(engineDir, sourcePath) {
     }
     return { gatedOff: false };
 }
+/**
+ * Maximum ancestor levels walked looking for a gating `DIRS` entry, and the
+ * largest `moz.build` read while doing it. The audit runs on every build, so
+ * a pathological tree must not be able to make it slow. Beyond these bounds
+ * the walk gives up and the caller keeps today's behaviour (warn).
+ */
+const MAX_ANCESTOR_DEPTH = 12;
+const MAX_MOZ_BUILD_BYTES = 256 * 1024;
+/** Matches a line that begins a `DIRS` assignment. */
+const DIRS_ASSIGNMENT_PATTERN = /^\s*DIRS\s*\+?=/;
+/**
+ * Collects the full stack of `if CONFIG[…]:` expressions enclosing the
+ * `DIRS` entry whose value equals `relDir`.
+ *
+ * Two differences from {@link findEnclosingGate}, both load-bearing here:
+ * only quoted values inside a `DIRS` assignment are considered (an
+ * unrelated string literal elsewhere in the file must not gate a
+ * directory), and every enclosing expression is returned rather than the
+ * innermost. Firefox nests these: `toolkit/moz.build` reaches
+ * `mozapps/defaultagent` inside `OS_ARCH == "WINNT"`, then a `CC_TYPE`
+ * test, then `MOZ_DEFAULT_BROWSER_AGENT`, and it is the outermost one that
+ * excludes the directory on a macOS host.
+ *
+ * @param content - `moz.build` file content
+ * @param relDir - Directory path relative to the `moz.build`, POSIX-separated
+ * @returns Enclosing gate expressions, outermost first. Empty when ungated
+ *   or when no `DIRS` entry reaches `relDir`
+ */
+function findDirsEntryGates(content, relDir) {
+    const lines = content.split('\n');
+    const stack = [];
+    let inDirs = false;
+    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] });
+            inDirs = false;
+            continue;
+        }
+        if (DIRS_ASSIGNMENT_PATTERN.test(line)) {
+            // A `DIRS += [` list body continues on later lines. A single-line
+            // `DIRS += ["x"]` is fully handled by the match below.
+            inDirs = !line.includes(']');
+            if (dirsLineNames(line, relDir))
+                return stack.map((entry) => entry.expression);
+            continue;
+        }
+        if (inDirs) {
+            if (dirsLineNames(line, relDir))
+                return stack.map((entry) => entry.expression);
+            if (line.includes(']'))
+                inDirs = false;
+        }
+    }
+    return undefined;
+}
+/** True when `line` carries `relDir` as a quoted value. */
+function dirsLineNames(line, relDir) {
+    const escaped = escapeRegex(relDir.replace(/\/+$/, ''));
+    return new RegExp(`["']${escaped}\\/?["']`).test(line);
+}
+/**
+ * Determines whether the source file's directory is excluded from this
+ * build by a gate in an ancestor `moz.build`.
+ *
+ * `detectPlatformGate` reads only the file's own nearest `moz.build`, which
+ * misses the common Firefox shape where the whole subtree is reached
+ * through a conditional `DIRS +=` one or more levels up: nothing in
+ * `toolkit/mozapps/defaultagent/moz.build` says "Windows only", yet none of
+ * it is built on macOS.
+ *
+ * Errs toward not skipping, like the rest of this module: an unreadable or
+ * oversized ancestor, or a directory no `DIRS` entry names, yields
+ * `gatedOff: false`.
+ *
+ * @param engineDir - Absolute path to the engine root
+ * @param sourcePath - Engine-relative POSIX path of the source file
+ */
+export async function detectAncestorDirsGate(engineDir, sourcePath) {
+    let host;
+    try {
+        host = getPlatform();
+    }
+    catch {
+        return { gatedOff: false };
+    }
+    const segments = sourcePath.split('/').filter(Boolean);
+    // Drop the basename: the walk is over directories.
+    segments.pop();
+    const root = engineDir.replace(/[/\\]+$/, '');
+    const depth = Math.min(segments.length, MAX_ANCESTOR_DEPTH);
+    // Start at the immediate parent of the file's directory and walk up, so
+    // the nearest gating ancestor is found first.
+    for (let cut = segments.length - 1; cut >= segments.length - depth; cut -= 1) {
+        const ancestorSegments = segments.slice(0, cut);
+        const relDir = segments.slice(cut).join('/');
+        if (relDir === '')
+            continue;
+        const mozBuild = join(root, ...ancestorSegments, 'moz.build');
+        if (!(await pathExists(mozBuild)))
+            continue;
+        let content;
+        try {
+            const stats = await stat(mozBuild);
+            if (stats.size > MAX_MOZ_BUILD_BYTES)
+                continue;
+            content = await readText(mozBuild);
+        }
+        catch {
+            continue;
+        }
+        const gates = findDirsEntryGates(content, relDir);
+        if (gates === undefined)
+            continue;
+        const offHost = gates.find((expression) => isGateOffHost(expression, host));
+        if (offHost !== undefined) {
+            return {
+                gatedOff: true,
+                gateExpression: offHost,
+                gateFile: [...ancestorSegments, 'moz.build'].join('/'),
+            };
+        }
+        // The directory is reached from here and this host passes every gate.
+        // A further ancestor cannot un-reach it.
+        return { gatedOff: false };
+    }
+    return { gatedOff: false };
+}

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

@@ -32,7 +32,7 @@ export declare function parseJarMnEntry(line: string): {
 /**
  * Scans a jar.mn file's contents for an entry whose source reference
  * matches `relativeSource` (POSIX, relative to the jar.mn directory).
- * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * Returns the first match. jar.mn enforces uniqueness of `(source)` in
  * practice, so a first-match wins behaviour is adequate.
  */
 export declare function findJarMnEntryForSource(content: string, relativeSource: string): {
@@ -44,14 +44,14 @@ export declare function findJarMnEntryForSource(content: string, relativeSource:
  * the first jar.mn entry that registers the given source. Returns undefined
  * when no ancestor jar.mn claims the source.
  *
- * @param engineDir Absolute engine root; walk halts here.
+ * @param engineDir Absolute engine root. The walk halts here.
  * @param source Engine-relative POSIX source path.
  */
 export declare function findRegisteredTarget(engineDir: string, source: string): Promise<RegistrationHit | undefined>;
 /**
  * Probes the dist tree for the artifact registered against the given
  * source. Returns the matched candidate and the registration hit that
- * anchored it; undefined when the source has no owning jar.mn or when
+ * anchored it. Undefined when the source has no owning jar.mn or when
  * no same-basename candidate under the search roots ends with the
  * registered target path.
  *
@@ -69,8 +69,8 @@ export declare function findRegisteredTarget(engineDir: string, source: string):
 export declare function resolveArtifactByRegistration(engineDir: string, source: string, searchRoots: readonly string[]): Promise<RegistrationProbeResult | undefined>;
 /**
  * Returns the absolute paths of every same-basename candidate under the
- * given search roots. Used by the audit to enumerate ALL false-match
- * candidates when the heuristic fallback downgrades to "missing" — the
+ * given search roots. Used by the audit to enumerate all false-match
+ * candidates when the heuristic fallback downgrades to "missing". The
  * operator needs to see the full set, not just the scorer's pick, to
  * distinguish a registration bug from a genuine packaging drop.
  *

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

@@ -18,13 +18,14 @@
  * report an unambiguous "registered but not packaged" miss when none exists.
  *
  * When no jar.mn registration is found, the caller falls back to the
- * similarity heuristic — which covers sources registered through moz.build
+ * 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';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { findAllByBasename } from './build-audit-resolve.js';
 /** Ceiling on ancestor-directory hops when searching for an owning jar.mn. */
 const MAX_JAR_MN_SCAN_DEPTH = 8;
@@ -61,11 +62,11 @@ export function parseJarMnEntry(line) {
 /**
  * Scans a jar.mn file's contents for an entry whose source reference
  * matches `relativeSource` (POSIX, relative to the jar.mn directory).
- * Returns the first match; jar.mn enforces uniqueness of `(source)` in
+ * Returns the first match. jar.mn enforces uniqueness of `(source)` in
  * practice, so a first-match wins behaviour is adequate.
  */
 export function findJarMnEntryForSource(content, relativeSource) {
-    const normalized = relativeSource.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(relativeSource);
     for (const line of content.split('\n')) {
         const parsed = parseJarMnEntry(line);
         if (!parsed)
@@ -80,7 +81,7 @@ export function findJarMnEntryForSource(content, relativeSource) {
  * the first jar.mn entry that registers the given source. Returns undefined
  * when no ancestor jar.mn claims the source.
  *
- * @param engineDir Absolute engine root; walk halts here.
+ * @param engineDir Absolute engine root. The walk halts here.
  * @param source Engine-relative POSIX source path.
  */
 export async function findRegisteredTarget(engineDir, source) {
@@ -97,7 +98,7 @@ export async function findRegisteredTarget(engineDir, source) {
                 content = await readText(jarMn);
             }
             catch {
-                // An unreadable jar.mn contributes no registration hints; the resolver falls
+                // An unreadable jar.mn contributes no registration hints. The resolver falls
                 // through to its other strategies.
                 content = '';
             }
@@ -121,12 +122,12 @@ export async function findRegisteredTarget(engineDir, source) {
  * independent.
  */
 function toPosix(path) {
-    return path.split(sep).join('/');
+    return normalizePathSlashes(path);
 }
 /**
  * Probes the dist tree for the artifact registered against the given
  * source. Returns the matched candidate and the registration hit that
- * anchored it; undefined when the source has no owning jar.mn or when
+ * anchored it. Undefined when the source has no owning jar.mn or when
  * no same-basename candidate under the search roots ends with the
  * registered target path.
  *
@@ -161,8 +162,8 @@ export async function resolveArtifactByRegistration(engineDir, source, searchRoo
 }
 /**
  * Returns the absolute paths of every same-basename candidate under the
- * given search roots. Used by the audit to enumerate ALL false-match
- * candidates when the heuristic fallback downgrades to "missing" — the
+ * given search roots. Used by the audit to enumerate all false-match
+ * candidates when the heuristic fallback downgrades to "missing". The
  * operator needs to see the full set, not just the scorer's pick, to
  * distinguish a registration bug from a genuine packaging drop.
  *

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

@@ -1,5 +1,5 @@
 /**
- * Heuristic test for "this looks like a packaged-test source file" — the
+ * 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, anywhere under a `testing/` subtree
@@ -27,7 +27,7 @@ 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 —
+ * Shared on purpose: 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
@@ -44,14 +44,14 @@ export declare const GENERIC_PATH_SEGMENTS: ReadonlySet<string>;
  *
  * 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
+ * `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 ties with the unrelated
  * `chrome/browser/content/browser/aboutDialog.css`.
  *
  * @param sourcePath Engine-relative POSIX path
  * @param candidatePath Absolute path under the dist tree
- * @returns Numeric score; higher means better match
+ * @returns Numeric score, where higher means better match
  */
 export declare function scoreCandidate(sourcePath: string, candidatePath: string): number;
 /**
@@ -69,7 +69,7 @@ export declare function findAllByBasename(root: string, name: string, maxDepth?:
 /**
  * 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
+ * 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

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

@@ -24,7 +24,7 @@ import { normalizePathSlashes } from '../utils/paths.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
+ * 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, anywhere under a `testing/` subtree
@@ -59,7 +59,7 @@ export function isTestPath(sourcePath) {
  *
  * 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
+ * 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.
@@ -94,7 +94,7 @@ 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 —
+ * Shared on purpose: 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
@@ -129,14 +129,14 @@ export const GENERIC_PATH_SEGMENTS = new Set([
  *
  * 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
+ * `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 ties with the unrelated
  * `chrome/browser/content/browser/aboutDialog.css`.
  *
  * @param sourcePath Engine-relative POSIX path
  * @param candidatePath Absolute path under the dist tree
- * @returns Numeric score; higher means better match
+ * @returns Numeric score, where higher means better match
  */
 export function scoreCandidate(sourcePath, candidatePath) {
     const trailing = countTrailingSegmentMatches(sourcePath, candidatePath);
@@ -210,7 +210,7 @@ export async function findAllByBasename(root, name, maxDepth = MAX_SCAN_DEPTH) {
 /**
  * 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
+ * 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