@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/commands/tree.js

@@ -0,0 +1,320 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge tree` — copy-on-write verification clones (FORGE G15).
+ *
+ * Trees enable concurrent READ-MOSTLY verification (lint, typecheck,
+ * status, verify, doctor, export dry-runs) beside a busy primary tree.
+ * Exports and every other mutation stay strictly serial in the primary —
+ * a tree's patches/components are snapshots with no merge model, and the
+ * tree guard (cli.ts preAction + core/tree-guard.ts) refuses mutating
+ * commands inside a tree. `create --with-objdir` additionally clones the
+ * primary's built obj-* directory, rewrites its mozinfo.json to the
+ * tree, and runs `mach configure` inside the tree so the remaining
+ * configure output (config.status, backend.mk, Makefile,
+ * config/autoconf.mk — the verified set) stops naming the primary
+ * (fail-closed — mach objdirs embed absolute source paths, and an
+ * unrelocated clone would silently operate against the primary), which
+ * is what admits build-less `fireforge test` inside that tree.
+ */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { hasBuildArtifacts, runMach, withBuildLock } from '../core/mach.js';
+import { assertBuildArtifacts, findObjdirRelocationViolation, } from '../core/mach-build-artifacts.js';
+import { detectCowSupport } from '../core/tree-cow.js';
+import { cloneTree, listTrees, removeTree } from '../core/tree-store.js';
+import { assertValidTreeName, computePrimaryFingerprint, getTreeMarkerPath, getTreesDir, readTreeMarkerState, withTreeLifecycleLock, } from '../core/tree-store.js';
+import { GeneralError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, setMachineOutputMode, setStdoutSealed, success, warn, } from '../utils/logger.js';
+import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
+function assertPosix() {
+    if (process.platform === 'win32') {
+        throw new GeneralError('fireforge tree is POSIX-only; copy-on-write cloning relies on clonefile/reflink, which are not available on Windows.');
+    }
+}
+/**
+ * Resolves the primary objdir a `--with-objdir` clone will keep,
+ * refusing missing, incomplete, ambiguous, or already-mismatched builds
+ * before any copying starts.
+ */
+async function resolveObjdirForClone(projectRoot) {
+    const engineDir = join(projectRoot, 'engine');
+    const buildCheck = await hasBuildArtifacts(engineDir);
+    assertBuildArtifacts(engineDir, buildCheck, {
+        label: 'tree create --with-objdir',
+        requirement: 'tree create --with-objdir requires a completed primary build.',
+        remediation: 'Run "fireforge build" first, or create the tree without --with-objdir.',
+        requireExisting: true,
+    });
+    if (buildCheck.objDir === undefined) {
+        throw new GeneralError('tree create --with-objdir could not determine the primary obj-* directory.');
+    }
+    return buildCheck.objDir;
+}
+/**
+ * Runs `mach configure` inside the tree's engine so the configure-generated
+ * root files (config.status, backend.mk, Makefile, config/autoconf.mk) are
+ * regenerated against the tree's paths — the mozinfo rewrite alone leaves
+ * those naming the primary, and a build-less in-tree `test` must never
+ * consult primary state. Exit code 0 is not trusted on its own: configure
+ * obeys MOZCONFIG / MOZ_OBJDIR, so the postcondition is verified afterwards
+ * via `findObjdirRelocationViolation` — the intended objdir was configured,
+ * its mozinfo points into the tree, and none of those root files still
+ * names the primary engine (nested Makefiles are products of the verified
+ * config.status; `.deps` build products are out of scope — see the
+ * checker's doc). A failure throws before `cloneTree` writes the marker,
+ * so the tree is removed and `clonedObjdir` is never recorded (fail-closed).
+ */
+async function reconfigureClonedObjdir(treeEngineDir, objDir, primaryEngineDir) {
+    info('  Running mach configure in the tree so no build metadata retains primary paths...');
+    let exitCode;
+    try {
+        exitCode = await runMach(['configure'], treeEngineDir);
+    }
+    catch (error) {
+        throw new BuildError('mach configure failed in the cloned tree; the tree was removed. ' +
+            'Re-run tree create, or create the tree without --with-objdir.', 'mach configure', error instanceof Error ? error : undefined);
+    }
+    if (exitCode !== 0) {
+        throw new BuildError(`mach configure exited non-zero (${exitCode}) in the cloned tree; the tree was removed. ` +
+            'Re-run tree create, or create the tree without --with-objdir.', 'mach configure');
+    }
+    const violation = await findObjdirRelocationViolation({
+        engineDir: treeEngineDir,
+        objDir,
+        forbiddenDir: primaryEngineDir,
+    });
+    if (violation !== undefined) {
+        throw new BuildError(`mach configure exited 0 in the cloned tree but did not relocate the objdir: ${violation}. ` +
+            'The tree was removed. Re-run tree create, or create the tree without --with-objdir.', 'mach configure');
+    }
+}
+/** Creates a verification tree under `.fireforge/trees/<name>`. */
+export async function treeCreateCommand(projectRoot, name, options = {}) {
+    assertPosix();
+    intro('FireForge Tree Create');
+    assertValidTreeName(name);
+    // A marker we cannot parse still means "something claims this is a tree", so
+    // it must block nesting too — otherwise a corrupt marker is a licence to
+    // clone a snapshot into itself.
+    const markerState = await readTreeMarkerState(projectRoot);
+    if (markerState.kind !== 'absent') {
+        throw new GeneralError(markerState.kind === 'valid'
+            ? 'Verification trees cannot be nested: run tree create in the primary tree.'
+            : `${getTreeMarkerPath(projectRoot)} claims this directory is a verification tree, but ` +
+                `${markerState.reason}. Repair or delete the marker before creating a tree here.`);
+    }
+    const treesDir = getTreesDir(projectRoot);
+    const treeRoot = join(treesDir, name);
+    await withTreeLifecycleLock(projectRoot, async () => {
+        if (await pathExists(treeRoot)) {
+            throw new GeneralError(`A tree named "${name}" already exists. Remove it first (fireforge tree remove ${name}) — refresh is remove + create.`);
+        }
+        const { mkdir } = await import('node:fs/promises');
+        await mkdir(treesDir, { recursive: true });
+        const capability = await detectCowSupport(treesDir);
+        if (capability === 'none' && options.forceCopy !== true) {
+            throw new GeneralError('This filesystem cannot copy-on-write (APFS clonefile or btrfs/XFS reflink required), so a tree ' +
+                'would be a full physical copy of the applied engine tree — potentially tens of gigabytes. ' +
+                'Re-run with --force-copy to accept that explicitly.');
+        }
+        if (capability === 'none') {
+            warn('No copy-on-write support detected — performing a full physical copy (--force-copy).');
+        }
+        // Courtesy fast-fail: refuse obvious no-build cases before waiting on
+        // locks. The result is DISCARDED — a build can still start before the
+        // locks below are held, so only the re-resolution under the build lock
+        // is authoritative for what actually gets cloned.
+        if (options.withObjdir === true) {
+            await resolveObjdirForClone(projectRoot);
+        }
+        // Snapshot under the PRIMARY engine-session lock so a mid-mutation
+        // state (half-applied export, furnace deploy) is never captured; an
+        // objdir snapshot additionally holds the primary BUILD lock, under
+        // which the objdir is re-validated immediately before cloning so a
+        // concurrent `fireforge build` can neither tear the obj-* mid-write
+        // nor swap it after preflight. A failed clone (including the
+        // fail-closed mozinfo-rewrite refusal and a failed in-tree
+        // reconfigure) removes the partial tree so the name is immediately
+        // reusable.
+        const marker = await withEngineSessionLock(projectRoot, 'tree create', async () => {
+            const clone = (objDir) => cloneTree({
+                primaryRoot: projectRoot,
+                treeRoot,
+                name,
+                capability,
+                createdAt: new Date().toISOString(),
+                ...(objDir === undefined
+                    ? {}
+                    : {
+                        withObjdir: {
+                            objDir,
+                            reconfigure: (treeEngineDir) => reconfigureClonedObjdir(treeEngineDir, objDir, join(projectRoot, 'engine')),
+                        },
+                    }),
+            });
+            try {
+                return options.withObjdir === true
+                    ? await withBuildLock(projectRoot, async () => clone(await resolveObjdirForClone(projectRoot)))
+                    : await clone();
+            }
+            catch (error) {
+                const { rm } = await import('node:fs/promises');
+                await rm(treeRoot, { recursive: true, force: true });
+                throw error;
+            }
+        }, { waitLockSeconds: options.waitLockSeconds });
+        success(`Created verification tree "${name}" at ${treeRoot}`);
+        info(`  Engine HEAD: ${marker.engineHead ?? '(no engine)'}`);
+        info('  Read-only: status, lint, typecheck, verify, doctor, and export/re-export --dry-run run inside it; mutation commands are refused.');
+        if (marker.clonedObjdir !== undefined) {
+            info(`  Build cloned: ${marker.clonedObjdir} was kept and rewritten to this tree — build-less "fireforge test" runs inside it.`);
+            info('  Browser tests share Marionette port 2828 with the primary; pass --marionette-port for concurrent runs.');
+        }
+    });
+    outro('Tree created');
+}
+/** Prints the tree list with staleness against the current primary state. */
+export async function treeListCommand(projectRoot, options = {}) {
+    if (options.json === true) {
+        // stdout belongs exclusively to the JSON payload: engage machine mode so
+        // any diagnostic — including a listTrees failure rendered later by
+        // withErrorHandling, which also resets the mode — routes to stderr.
+        setMachineOutputMode(true);
+        const trees = await listTrees(projectRoot);
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, trees }, null, 2)}\n`);
+        setMachineOutputMode(false);
+        return;
+    }
+    const trees = await listTrees(projectRoot);
+    intro('FireForge Trees');
+    if (trees.length === 0) {
+        info('No verification trees. Create one with: fireforge tree create <name>');
+        outro('Done');
+        return;
+    }
+    for (const tree of trees) {
+        info(`${tree.name.padEnd(20)} ${tree.staleness.padEnd(24)} created ${tree.createdAt}`);
+    }
+    outro(`${trees.length} tree(s)`);
+}
+/** Removes one tree (or all of them with `--all`). */
+export async function treeRemoveCommand(projectRoot, name, options = {}) {
+    assertPosix();
+    intro('FireForge Tree Remove');
+    if (options.all !== true && name === undefined) {
+        throw new GeneralError('Pass a tree name, or --all to remove every tree.');
+    }
+    await withTreeLifecycleLock(projectRoot, async () => {
+        const targets = options.all === true ? (await listTrees(projectRoot)).map((t) => t.name) : [name ?? ''];
+        if (targets.length === 0) {
+            info('No verification trees to remove.');
+            return;
+        }
+        for (const target of targets) {
+            await removeTree(projectRoot, target, { force: options.force === true });
+            success(`Removed verification tree "${target}"`);
+        }
+    });
+    outro('Tree removal complete');
+}
+/** Spawns `fireforge <args>` with the tree as its working directory. */
+async function treeExecCommand(projectRoot, name, args) {
+    assertPosix();
+    assertValidTreeName(name);
+    const treeRoot = join(getTreesDir(projectRoot), name);
+    const state = await readTreeMarkerState(treeRoot);
+    if (state.kind === 'corrupt') {
+        // Collapsing corrupt into "no such tree" misdiagnoses: the directory IS
+        // there, claiming to be a tree, and "no tree named X" points the operator
+        // at the wrong remediation.
+        throw new GeneralError(`Tree "${name}" exists but its marker could not be read: ${state.reason}. ` +
+            'Recreate it (fireforge tree remove <name> && fireforge tree create <name>).');
+    }
+    if (state.kind === 'absent') {
+        throw new GeneralError(`No verification tree named "${name}". List trees with: fireforge tree list`);
+    }
+    const marker = state.marker;
+    const current = await computePrimaryFingerprint(projectRoot);
+    if (marker.engineHead !== current.engineHead) {
+        warn(`Tree "${name}" is stale (primary engine advanced since the snapshot).`);
+    }
+    else if (marker.engineFingerprint !== undefined &&
+        marker.engineFingerprint !== current.engineFingerprint) {
+        warn(`Tree "${name}" is stale (primary engine worktree changed since the snapshot).`);
+    }
+    else if (marker.patchesFingerprint !== current.patchesFingerprint) {
+        warn(`Tree "${name}" is stale (primary patches changed since the snapshot).`);
+    }
+    const cliEntry = process.argv[1];
+    if (cliEntry === undefined) {
+        throw new GeneralError('Cannot resolve the fireforge CLI entry point for tree exec.');
+    }
+    const exitCode = await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [cliEntry, ...args], {
+            cwd: treeRoot,
+            stdio: 'inherit',
+        });
+        child.on('error', rejectPromise);
+        child.on('exit', (code) => {
+            resolvePromise(code ?? 1);
+        });
+    }).finally(() => {
+        // FORGE L2: with `stdio: 'inherit'` the child owned stdout — including
+        // any FIREFORGE-VERDICT line it emitted as its LAST stdout write. From
+        // here on the parent must not write stdout again, or its own refusal
+        // text (the GeneralError below rendered by withErrorHandling) would
+        // print AFTER the child's verdict and break the "verdict is the run's
+        // last stdout line" contract at the tree-exec boundary. Sealing routes
+        // the parent's remaining output to stderr; withErrorHandling's finally
+        // clears the seal.
+        setStdoutSealed(true);
+    });
+    if (exitCode !== 0) {
+        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${String(exitCode)}.`);
+    }
+}
+/** Registers the tree command group on the CLI program. */
+export function registerTree(program, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const tree = program
+        .command('tree')
+        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export/re-export --dry-run; build-less test with create --with-objdir). Mutation commands are refused inside a tree.');
+    addWaitLockOption(tree
+        .command('create <name>')
+        .description('Clone the project (engine included, obj-* excluded) into .fireforge/trees/<name> using filesystem copy-on-write (APFS clonefile / btrfs-XFS reflink). Refuses on filesystems without CoW support unless --force-copy explicitly accepts a full physical copy.')
+        .option('--force-copy', 'Allow a full physical copy when the filesystem cannot copy-on-write. This can copy tens of GB; never implied.')
+        .option('--with-objdir', 'Also clone the primary obj-* build and rewrite its mozinfo.json to the tree (fail-closed), enabling build-less "fireforge test" inside the tree. Requires a completed, unambiguous primary build.')).action(withErrorHandling(async (name, options) => {
+        // The flag is a CLI-layer concern: the command takes the resolved
+        // wait budget, matching how furnace routes its subcommand locks.
+        const { waitLock, ...rest } = options;
+        await treeCreateCommand(getProjectRoot(), name, {
+            ...rest,
+            waitLockSeconds: resolveWaitLockSeconds(waitLock),
+        });
+    }));
+    tree
+        .command('list')
+        .description('List verification trees with creation time and staleness vs the primary tree (engine HEAD and patches.json fingerprint).')
+        .option('--json', 'Output the tree list as JSON')
+        .action(withErrorHandling(async (options) => {
+        await treeListCommand(getProjectRoot(), options);
+    }));
+    tree
+        .command('remove [name]')
+        .description("Delete a verification tree. Refuses while a live process holds the tree's build or engine-session lock, and when a lock exists whose owning process cannot be identified.")
+        .option('--all', 'Remove every verification tree')
+        .option('--force', "Delete even when a lock directory's owner cannot be identified. Only safe once you have confirmed no build or test is running against the tree.")
+        .action(withErrorHandling(async (name, options) => {
+        await treeRemoveCommand(getProjectRoot(), name, options);
+    }));
+    tree
+        .command('exec <name> [args...]')
+        .description('Run a fireforge command inside the named tree (equivalent to cd-ing into it). Example: fireforge tree exec shard-a -- lint --per-patch')
+        .action(withErrorHandling(async (name, args) => {
+        await treeExecCommand(getProjectRoot(), name, args);
+    }));
+}

package/dist/src/commands/verify.js

@@ -20,7 +20,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { isGitRepository } from '../core/git.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
-import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
+import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
 import { loadPatchesManifest, validatePatchesManifestConsistency } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
 import { collectPatchRegistrationReferences } from '../core/patch-registration-refs.js';
@@ -187,7 +187,7 @@ export async function collectPatchQueueHealth(projectRoot) {
             title: `Cross-patch lint issues (${lintIssues.length})`,
             issues: lintIssues.map((issue) => {
                 const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
-                return `${label} [${issue.check}] ${issue.file}: ${issue.message}`;
+                return `${label} ${formatPatchLintIssue(issue)}`;
             }),
             errorCount: lintErrors,
             warningCount: lintWarnings,

package/dist/src/commands/watch.js

@@ -3,9 +3,10 @@ import { delimiter, dirname } from 'node:path';
 import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
+import { generateMozconfig, hasBuildArtifacts, hasRunnableBundle, watchWithOutput, } from '../core/mach.js';
+import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { GeneralError } from '../errors/base.js';
-import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose } from '../utils/logger.js';
@@ -123,24 +124,16 @@ export async function watchCommand(projectRoot) {
     // instead of an actionable preflight error.
     await probeWatchman();
     // Check for build artifacts before starting watch
+    // The mismatch rung rejects copied or relocated obj-* dirs whose mozinfo
+    // metadata (topsrcdir, topobjdir, mozconfig) still points at a different
+    // source tree; mach watch against stale metadata produces confusing errors.
     const buildCheck = await hasBuildArtifacts(paths.engine);
-    if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
-        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs);
-    }
-    // Reject copied or relocated obj-* dirs whose mozinfo metadata (topsrcdir,
-    // topobjdir, mozconfig) still points at a different source tree. Running mach
-    // watch against stale metadata produces confusing build errors.
-    const mismatchMessage = buildArtifactMismatchMessage(paths.engine, buildCheck, 'Watch mode');
-    if (mismatchMessage) {
-        throw new GeneralError(mismatchMessage);
-    }
-    if (!buildCheck.exists) {
-        const detail = buildCheck.objDir
-            ? `Build artifacts incomplete in ${buildCheck.objDir}/`
-            : 'No build artifacts found (obj-*/ directory missing)';
-        throw new GeneralError(`Watch mode requires a completed build. ${detail}\n\n` +
-            "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.");
-    }
+    assertBuildArtifacts(paths.engine, buildCheck, {
+        label: 'Watch mode',
+        requirement: 'Watch mode requires a completed build.',
+        remediation: "Run 'fireforge build' first to create the initial build, then run 'fireforge watch'.",
+        requireExisting: true,
+    });
     // Report bundle state alongside the "Using build artifacts..." banner
     // so an operator watching a mid-build tree can see why `fireforge run`
     // would refuse right now while watch is still going. Watch remains
@@ -182,10 +175,18 @@ export async function watchCommand(projectRoot) {
     const watchmanDir = dirname(watchmanPath);
     const existingPath = process.env['PATH'] ?? '';
     const pathSegments = existingPath.split(delimiter).filter((segment) => segment.length > 0);
+    // Both arms filter identically; the cast this replaced laundered
+    // `string | undefined` on one arm while the other built the annotated shape
+    // honestly.
+    const baseEnv = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined)
+            baseEnv[key] = value;
+    }
     const watchmanEnv = pathSegments.includes(watchmanDir)
-        ? { ...process.env }
+        ? baseEnv
         : {
-            ...process.env,
+            ...baseEnv,
             PATH: [watchmanDir, ...pathSegments].join(delimiter),
         };
     verbose(`watch: resolved watchman at ${watchmanPath}; forwarding directory in subprocess PATH.`);

package/dist/src/commands/wire.js

@@ -105,7 +105,7 @@ async function assertDomTargetIsWireable(projectRoot, domFilePath, domTargetPath
         await probeDomFragmentInsertionPoint(paths.engine, domFilePath, domTargetPath);
     }
     catch (probeError) {
-        throw new InvalidArgumentError(`${probeError instanceof Error ? probeError.message : String(probeError)}\n` +
+        throw new InvalidArgumentError(`${toError(probeError).message}\n` +
             `The resolved chrome document ${domTargetPath} does not expose an insertion anchor ` +
             'that `fireforge wire` recognises (`#include browser-sets.inc` or `<html:body>`). ' +
             'Add one of those anchors to the chrome doc, or target a document that has them via ' +

package/dist/src/core/ast-utils.d.ts

@@ -33,6 +33,17 @@ export declare function parseModule(content: string, onComment?: acorn.Comment[]
 /**
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.
+ *
+ * **Caller obligation: you must already have discriminated on `node.type`.**
+ * This performs no runtime check — it exists to attach acorn's `start`/`end`
+ * offsets to a node the caller has *already* narrowed, typically inside a
+ * `if (node.type === 'CallExpression')` branch or an equivalent walker guard.
+ * Calling it on an undiscriminated node produces a value whose type is a lie.
+ *
+ * A runtime `type` assertion was considered and rejected: every call site sits
+ * in the hot loop of a lint or registration walker, and all of them are
+ * already post-narrowing, so the check would cost traversal time on every node
+ * to re-prove something the enclosing branch established.
  */
 export declare function asEstree<T extends estree.Node>(node: estree.Node): AcornESTreeNode<T>;
 /**

package/dist/src/core/ast-utils.js

@@ -40,6 +40,17 @@ export function parseModule(content, onComment) {
 /**
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.
+ *
+ * **Caller obligation: you must already have discriminated on `node.type`.**
+ * This performs no runtime check — it exists to attach acorn's `start`/`end`
+ * offsets to a node the caller has *already* narrowed, typically inside a
+ * `if (node.type === 'CallExpression')` branch or an equivalent walker guard.
+ * Calling it on an undiscriminated node produces a value whose type is a lie.
+ *
+ * A runtime `type` assertion was considered and rejected: every call site sits
+ * in the hot loop of a lint or registration walker, and all of them are
+ * already post-narrowing, so the check would cost traversal time on every node
+ * to re-prove something the enclosing branch established.
  */
 export function asEstree(node) {
     return node;

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

@@ -36,6 +36,7 @@
 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 ==
@@ -96,7 +97,7 @@ async function findOwningMozBuild(engineDir, sourceDir) {
  * `"stubinstaller/installing_page.css"`.
  */
 function matchesQuotedBasename(line, basename) {
-    const escaped = basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const escaped = escapeRegex(basename);
     return new RegExp(`["'](?:[^"']*\\/)?${escaped}["']`).test(line);
 }
 /**
@@ -207,6 +208,8 @@ export async function detectPlatformGate(engineDir, sourcePath) {
         host = getPlatform();
     }
     catch {
+        // Unrecognised host platform. The platform gates below are advisory, so an
+        // unknown host disables them rather than failing a warn-only audit.
         host = undefined;
     }
     const sourceDir = dirname(join(engineDir, sourcePath));
@@ -217,6 +220,8 @@ export async function detectPlatformGate(engineDir, sourcePath) {
             content = await readText(mozBuild);
         }
         catch {
+            // An unreadable moz.build contributes no platform gates. The audit is
+            // warn-only, so a missing input degrades to 'no gate found', not an error.
             content = '';
         }
         const sourceBasename = sourcePath.split('/').pop() ?? '';

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

@@ -105,6 +105,8 @@ export async function findRegisteredTarget(engineDir, source) {
                 content = await readText(jarMn);
             }
             catch {
+                // An unreadable jar.mn contributes no registration hints; the resolver falls
+                // through to its other strategies.
                 content = '';
             }
             const rel = relative(current, sourceAbs).split(sep).join('/');

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

@@ -24,6 +24,19 @@ export declare function isTestPath(sourcePath: string): boolean;
  * @returns Count of matching trailing segments (basename always counts as 1)
  */
 export declare function countTrailingSegmentMatches(a: string, b: string): number;
+/**
+ * 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.
+ */
+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

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

@@ -86,6 +86,37 @@ export function countTrailingSegmentMatches(a, b) {
     }
     return matches;
 }
+/**
+ * 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.
+ */
+export const GENERIC_PATH_SEGMENTS = new Set([
+    'content',
+    'chrome',
+    'bin',
+    'browser',
+    'toolkit',
+    'modules',
+    'base',
+    'app',
+    'profile',
+    'shared',
+    'themes',
+    'test',
+    'tests',
+    'unit',
+    'common',
+    'xpcshell',
+    'mochitest',
+]);
 /**
  * Computes a score for `candidatePath` relative to `sourcePath`. Higher
  * scores win. Score = trailing-segment match count, with a bonus when
@@ -112,19 +143,7 @@ export function scoreCandidate(sourcePath, candidatePath) {
     // 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 generic = GENERIC_PATH_SEGMENTS;
     const trailingSet = new Set(sourceSegs.slice(sourceSegs.length - trailing));
     let bonus = 0;
     for (const seg of sourceSegs) {
@@ -166,6 +185,8 @@ export async function findAllByBasename(root, name, maxDepth = MAX_SCAN_DEPTH) {
             children = await readdir(entry.dir, { withFileTypes: true });
         }
         catch {
+            // An unreadable subdirectory yields no candidates. Skip it and keep
+            // scoring the rest rather than abandoning the whole resolution.
             continue;
         }
         for (const child of children) {

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

@@ -39,7 +39,7 @@ import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
 import { detectPlatformGate } from './build-audit-platform.js';
 import { collectSameBasenameCandidates, findRegisteredTarget, resolveArtifactByRegistration, } from './build-audit-registration.js';
-import { countTrailingSegmentMatches, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
+import { countTrailingSegmentMatches, GENERIC_PATH_SEGMENTS, isTestPath, resolveBestArtifact, } from './build-audit-resolve.js';
 import { resolveArtifactByKnownTransform } from './build-audit-transforms.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
 /** Path extensions that are conventionally packaged into the Firefox bundle. */
@@ -138,6 +138,7 @@ async function resolveDistRoot(engineDir) {
         entries = await readdir(engineDir);
     }
     catch {
+        // No readable engine directory means no objdir can be identified.
         return undefined;
     }
     const objDirs = entries.filter((e) => e.startsWith('obj-'));
@@ -161,6 +162,7 @@ async function resolveTestsRoot(engineDir) {
         entries = await readdir(engineDir);
     }
     catch {
+        // No readable engine directory means no objdir can be identified.
         return undefined;
     }
     const objDirs = entries.filter((e) => e.startsWith('obj-'));
@@ -236,25 +238,7 @@ function isConfidentMatch(source, candidate) {
     }
     const sourceSegs = source.split('/').filter(Boolean);
     const candSegs = candidate.split('/').filter(Boolean);
-    const generic = new Set([
-        'content',
-        'chrome',
-        'bin',
-        'browser',
-        'toolkit',
-        'modules',
-        'base',
-        'app',
-        'profile',
-        'shared',
-        'themes',
-        'test',
-        'tests',
-        'unit',
-        'common',
-        'xpcshell',
-        'mochitest',
-    ]);
+    const generic = GENERIC_PATH_SEGMENTS;
     // Skip the basename itself (which trail-matches by definition).
     for (let i = 0; i < sourceSegs.length - 1; i += 1) {
         const seg = sourceSegs[i];