@hominis/fireforge 0.40.0 → 0.42.0

package/dist/src/core/mach-build-artifacts.js

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join, relative, resolve, sep } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { AmbiguousBuildArtifactsError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
-import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { pathExists, readJson, readText, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
 import { isObject, isString } from '../utils/validation.js';
@@ -33,7 +35,11 @@ function validateBuildMozinfo(data) {
 }
 /**
  * Checks if build artifacts exist in the engine directory.
- * Looks for obj-* directories with a dist subdirectory.
+ * Looks for obj-* directories with a dist subdirectory. Detection is
+ * deliberately symlink-agnostic — building/running against a symlinked
+ * objdir in place is the user's own arrangement; the clone path, where a
+ * symlink would route writes into the original build, refuses separately
+ * (`assertCloneSafeObjdir` in tree-store.ts).
  * @param engineDir - Path to the engine directory
  * @returns Build artifact check result
  */
@@ -135,6 +141,8 @@ export async function hasRunnableBundle(engineDir, binaryName, objDir) {
             entries = await readdir(distDir, { withFileTypes: true });
         }
         catch {
+            // No readable dist directory means no runnable bundle, which is exactly
+            // what the caller needs to know.
             return { runnable: false };
         }
         for (const entry of entries) {
@@ -285,3 +293,101 @@ export async function attemptMozinfoRewrite(engineDir, objDir) {
         ...(newMozconfig ? { newMozconfig } : {}),
     };
 }
+/**
+ * Shared build-artifact preflight: rejects ambiguous multi-objdir checkouts,
+ * artifacts whose metadata points at another tree, and (when
+ * `requireExisting`) missing or incomplete builds — each with the actionable
+ * message for that case.
+ *
+ * Takes an already-probed {@link BuildArtifactCheck} rather than probing
+ * itself, so it stays a pure validator: callers keep their own
+ * `hasBuildArtifacts` call (which their suites already stub) and this function
+ * needs no test double of its own.
+ *
+ * Five commands carried a character-identical copy of this ladder, including
+ * the same `ambiguous && objDirs && objDirs.length > 0` expression that
+ * `BuildArtifactCheck`'s boolean-plus-optionals shape forces at every reader.
+ * The shape itself is unchanged — it has several producers and a documented
+ * refusal contract (see the containment predicates below) — but it is now
+ * destructured in exactly one place.
+ */
+export function assertBuildArtifacts(engineDir, buildCheck, options) {
+    if (buildCheck.ambiguous && buildCheck.objDirs && buildCheck.objDirs.length > 0) {
+        throw new AmbiguousBuildArtifactsError(buildCheck.objDirs);
+    }
+    const mismatchMessage = buildArtifactMismatchMessage(engineDir, buildCheck, options.label);
+    if (mismatchMessage) {
+        throw new GeneralError(mismatchMessage);
+    }
+    if (options.requireExisting && !buildCheck.exists) {
+        const detail = buildCheck.objDir
+            ? `Build artifacts incomplete in ${buildCheck.objDir}/`
+            : 'No build artifacts found (obj-*/ directory missing)';
+        throw new GeneralError(`${options.requirement} ${detail}\n\n${options.remediation}`);
+    }
+}
+/**
+ * Post-`mach configure` relocation check for a cloned objdir: confirms
+ * configure actually regenerated `<engineDir>/<objDir>` and that none of
+ * the four configure-generated root files (`config.status`, `backend.mk`,
+ * `Makefile`, `config/autoconf.mk`) still names `forbiddenDir` (the
+ * primary engine a relocated clone must never consult). Exit code 0 alone
+ * proves neither — a stray MOZCONFIG/MOZ_OBJDIR can steer configure at a
+ * different objdir entirely. Nested Makefiles are products of the verified
+ * `config.status` and are not scanned; `.deps` files are build products a
+ * configure cannot regenerate and are explicitly out of scope — any
+ * primary-path strings they retain are read-only staleness corrected by
+ * the first in-tree rebuild. Pure checker: returns a human-readable
+ * violation, or `undefined` when clean; callers own the error type and
+ * remediation copy. Unreadable metadata is itself a violation (fail
+ * closed).
+ */
+export async function findObjdirRelocationViolation(args) {
+    const { engineDir, objDir, forbiddenDir } = args;
+    const objDirPath = join(engineDir, objDir);
+    if (!(await pathExists(join(objDirPath, 'config.status')))) {
+        return (`${objDir}/config.status was not written — mach configure may have targeted a ` +
+            'different objdir (check MOZCONFIG / MOZ_OBJDIR)');
+    }
+    let mozinfo;
+    try {
+        mozinfo = validateBuildMozinfo(await readJson(join(objDirPath, 'mozinfo.json')));
+    }
+    catch (error) {
+        return `${objDir}/mozinfo.json could not be read after configure: ${toError(error).message}`;
+    }
+    const expectedSrcDir = resolve(engineDir);
+    const expectedObjDir = resolve(objDirPath);
+    const actualSrcDir = mozinfo.topsrcdir ? resolve(mozinfo.topsrcdir) : undefined;
+    const actualObjDir = mozinfo.topobjdir ? resolve(mozinfo.topobjdir) : undefined;
+    if (actualSrcDir !== expectedSrcDir) {
+        return `${objDir}/mozinfo.json topsrcdir resolves to ${actualSrcDir ?? '(absent)'}, expected ${expectedSrcDir}`;
+    }
+    if (actualObjDir !== expectedObjDir) {
+        return `${objDir}/mozinfo.json topobjdir resolves to ${actualObjDir ?? '(absent)'}, expected ${expectedObjDir}`;
+    }
+    // The canonical no-primary-paths assertion (mirrors the opt-in real-mach
+    // proof in scripts/run-full-firefox-integration.mjs): substring search on
+    // the resolved primary engine dir is collision-safe against the tree's own
+    // paths — `<primary>/.fireforge/trees/<name>/engine` never contains the
+    // substring `<primary>/engine`. Scans exactly the configure-generated
+    // root files; `config.status` is mandatory (checked above), the rest are
+    // optional-if-absent because not every configure backend writes them.
+    const forbidden = resolve(forbiddenDir);
+    for (const name of ['config.status', 'backend.mk', 'Makefile', 'config/autoconf.mk']) {
+        const filePath = join(objDirPath, ...name.split('/'));
+        if (name !== 'config.status' && !(await pathExists(filePath)))
+            continue;
+        let content;
+        try {
+            content = await readText(filePath);
+        }
+        catch (error) {
+            return `${objDir}/${name} could not be read after configure: ${toError(error).message}`;
+        }
+        if (content.includes(forbidden)) {
+            return `${objDir}/${name} still contains the primary engine path ${forbidden}`;
+        }
+    }
+    return undefined;
+}

package/dist/src/core/mach-mozconfig.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { MozconfigError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { getPlatform } from '../utils/platform.js';
-import { BrandingMozconfigMismatchError } from './branding.js';
+import { BrandingMozconfigMismatchError, splitAppId } from './branding.js';
 /**
  * Replaces template variables in a string.
  * @param content - Content with ${variable} placeholders
@@ -95,6 +95,14 @@ export async function generateMozconfig(configsDir, engineDir, config) {
         binaryName: config.binaryName,
     };
     let content = '';
+    // Bundle identity: branding configure.sh carries only the LEAF of appId
+    // (see splitAppId in branding.ts — upstream composes the mac bundle id as
+    // <distribution-id>.<MOZ_MACBUNDLE_ID>); the prefix travels here so the
+    // two halves can never drift apart.
+    const { distributionId } = splitAppId(config.appId);
+    content +=
+        `# FireForge identity (generated from fireforge.json appId)\n` +
+            `ac_add_options --with-distribution-id=${distributionId}\n\n`;
     // Read common config if it exists
     if (await pathExists(commonPath)) {
         const commonContent = await readText(commonPath);

package/dist/src/core/mach-resource-shim.js

@@ -461,6 +461,7 @@ async function listSubdirs(dir) {
         return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
     }
     catch {
+        // An unreadable directory contributes no subdirectories to the shim scan.
         return [];
     }
 }

package/dist/src/core/marionette-port.d.ts

@@ -27,6 +27,22 @@ export interface MarionettePortProbeResult {
     /** Details about the holder, when the probe recovered them. */
     holder?: MarionettePortHolder;
 }
+/** A Firefox-family process launched from this project's built bundle. */
+export interface RunningBundleProcess {
+    pid: number;
+    commandLine: string;
+}
+/** Pure parser kept exported so platform output handling is regression-testable. */
+export declare function parseProcessList(stdout: string, launchableBinary: string): RunningBundleProcess[];
+/**
+ * Refuses a browser-harness launch when this objdir's app is already alive,
+ * or terminates the parent when the operator explicitly opted into stale
+ * browser cleanup. This closes the no-listening-port variant of the stale
+ * Marionette process failure.
+ */
+export declare function ensureLaunchableBrowserNotRunning(launchableBinary: string, options?: {
+    killStaleBrowser?: boolean;
+}): Promise<void>;
 /**
  * Probes whether the Marionette port is currently bound by a
  * listener. The probe is best-effort: missing tooling returns

package/dist/src/core/marionette-port.js

@@ -45,6 +45,88 @@ const BROWSER_BASENAMES = new Set([
     'mybrowser',
     'thunderbird',
 ]);
+/**
+ * Finds browser processes whose command line names the exact launchable
+ * binary from this project's objdir. Unlike the Marionette-port probe, this
+ * also catches a wedged browser that survived a harness timeout but no longer
+ * owns the control port. Best-effort: unavailable process-list tooling yields
+ * an empty result rather than blocking tests.
+ */
+async function findRunningBundleProcesses(launchableBinary) {
+    try {
+        if (process.platform === 'win32') {
+            const escapedPath = launchableBinary.replaceAll("'", "''");
+            const script = `Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -eq '${escapedPath}' } | ` +
+                'ForEach-Object { Write-Output ("$($_.ProcessId) $($_.CommandLine)") }';
+            const result = await exec('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-Command',
+                script,
+            ]);
+            return parseProcessList(result.stdout, launchableBinary);
+        }
+        const result = await exec('ps', ['-axo', 'pid=,args=']);
+        return parseProcessList(result.stdout, launchableBinary);
+    }
+    catch {
+        return [];
+    }
+}
+/** Pure parser kept exported so platform output handling is regression-testable. */
+export function parseProcessList(stdout, launchableBinary) {
+    const matches = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+        if (!match?.[1] || !match[2]?.includes(launchableBinary))
+            continue;
+        const pid = Number(match[1]);
+        if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid)
+            continue;
+        matches.push({ pid, commandLine: match[2] });
+    }
+    return matches;
+}
+/**
+ * Refuses a browser-harness launch when this objdir's app is already alive,
+ * or terminates the parent when the operator explicitly opted into stale
+ * browser cleanup. This closes the no-listening-port variant of the stale
+ * Marionette process failure.
+ */
+export async function ensureLaunchableBrowserNotRunning(launchableBinary, options = {}) {
+    const processes = await findRunningBundleProcesses(launchableBinary);
+    if (processes.length === 0)
+        return;
+    const parent = processes.find((candidate) => !candidate.commandLine.includes('-contentproc'));
+    const holder = parent ?? processes[0];
+    if (!holder)
+        return;
+    if (options.killStaleBrowser) {
+        try {
+            if (process.platform === 'win32') {
+                await exec('powershell.exe', [
+                    '-NoProfile',
+                    '-NonInteractive',
+                    '-Command',
+                    `Stop-Process -Id ${holder.pid} -Force`,
+                ]);
+            }
+            else {
+                process.kill(holder.pid, 'SIGTERM');
+            }
+            return;
+        }
+        catch (error) {
+            throw new GeneralError(`A browser from this objdir is still running (PID ${holder.pid}), but FireForge could not terminate it: ${toError(error).message}`);
+        }
+    }
+    const killHint = process.platform === 'win32'
+        ? `Stop-Process -Id ${holder.pid} -Force`
+        : `kill ${holder.pid}  # or "kill -9 ${holder.pid}" if it doesn't exit`;
+    throw new GeneralError(`A browser from this project's objdir is already running (PID ${holder.pid}). ` +
+        'It may have survived a previously timed-out or interrupted "fireforge test" run and can wedge the next headed launch. ' +
+        `Stop it with "${killHint}", or retry with "--kill-stale-marionette".`);
+}
 /**
  * Returns `true` when the holder's command basename or command-line
  * flags clearly identify it as a Firefox-family browser with
@@ -110,13 +192,12 @@ async function probeWithLsof(port) {
         }
         return { inUse: true, holder: { pid, command, commandLine } };
     }
-    catch (error) {
-        // `lsof` missing, or stdout parse failed. Treat as "unknown" ⇒
-        // port probe is silently skipped.
-        const message = toError(error).message;
-        if (/ENOENT|not found|command not found/i.test(message)) {
-            return { inUse: false };
-        }
+    catch {
+        // `lsof` missing, or its stdout did not parse. Either way the port state
+        // is unknown, and an unknown port is reported as free so the probe never
+        // blocks a run on its own uncertainty. (The errno test that used to sit
+        // here returned the same value as this fallthrough, so it decided
+        // nothing.)
         return { inUse: false };
     }
 }
@@ -156,6 +237,8 @@ async function probeWithPowerShell(port) {
         return { inUse: true, holder: { pid, command, commandLine } };
     }
     catch {
+        // Unparseable netstat/PowerShell output. The port state is unknown, and an unknown port
+        // is reported free so the probe never blocks a run on its own uncertainty.
         return { inUse: false };
     }
 }
@@ -172,6 +255,8 @@ export async function probeMarionettePort(port = DEFAULT_MARIONETTE_PORT) {
         platform = getPlatform();
     }
     catch {
+        // Unrecognised host platform — no probe strategy applies, so the port is
+        // reported free rather than blocking the run.
         return { inUse: false };
     }
     if (platform === 'darwin' || platform === 'linux') {
@@ -241,7 +326,7 @@ export async function ensureMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
     }
     catch (error) {
         throw new GeneralError(`Marionette port ${port} is held by stale browser ${holder.command} (PID ${holder.pid}), ` +
-            `but FireForge could not terminate it: ${error instanceof Error ? error.message : String(error)}`);
+            `but FireForge could not terminate it: ${toError(error).message}`);
     }
 }
 /**

package/dist/src/core/marionette-preflight.js

@@ -17,6 +17,7 @@ import { mkdtemp, rm } from 'node:fs/promises';
 import net from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
 import { ensureMach } from './mach.js';
@@ -75,7 +76,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         await ensureMach(engineDir);
     }
     catch (error) {
-        return fail('mach-available', `mach not available in engine: ${error.message}`, elapsed());
+        return fail('mach-available', `mach not available in engine: ${toError(error).message}`, elapsed());
     }
     // Layer 3: Python that mach requires is discoverable.
     let python;
@@ -83,7 +84,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         python = await getPython(engineDir);
     }
     catch (error) {
-        return fail('python-available', `Python interpreter required by mach is not available: ${error.message}`, elapsed());
+        return fail('python-available', `Python interpreter required by mach is not available: ${toError(error).message}`, elapsed());
     }
     // Layer 4: throwaway browser profile directory is creatable.
     let profileDir;
@@ -91,7 +92,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
     }
     catch (error) {
-        return fail('profile-creatable', `Could not create a throwaway browser profile in ${tmpdir()}: ${error.message}`, elapsed());
+        return fail('profile-creatable', `Could not create a throwaway browser profile in ${tmpdir()}: ${toError(error).message}`, elapsed());
     }
     let child;
     let stderrTail = '';
@@ -123,7 +124,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
             });
         }
         catch (error) {
-            return fail('browser-spawns', `Could not spawn mach run: ${error.message}`, elapsed());
+            return fail('browser-spawns', `Could not spawn mach run: ${toError(error).message}`, elapsed());
         }
         const spawnedChild = child;
         child.stderr?.on('data', (data) => {
@@ -183,7 +184,7 @@ export async function runMarionettePreflight(engineDir, options = {}) {
             await rm(profileDir, { recursive: true, force: true });
         }
         catch (error) {
-            warn(`Could not clean up marionette preflight profile: ${error.message}`);
+            warn(`Could not clean up marionette preflight profile: ${toError(error).message}`);
         }
     }
 }

package/dist/src/core/patch-apply.d.ts

@@ -2,7 +2,7 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import type { ImportSummary, PatchResult } from '../types/commands/index.js';
+import type { ImportSummary, PatchInfo, PatchMetadata, PatchResult } from '../types/commands/index.js';
 export { PatchError } from '../errors/patch.js';
 export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
@@ -73,18 +73,25 @@ export declare function matchesUntilFilename(patchFilename: string, needle: stri
  */
 export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, optionsOrContinue?: ApplyPatchesOptions | boolean): Promise<ImportSummary>;
 /**
- * Computes the cumulative patched content for a file.
- * @param patchesDir - Path to the patches directory
- * @param engineDir - Path to the engine directory
- * @param filePath - File path to compute content for
- * @returns Content after all patches applied, or null if file doesn't exist
+ * Batched patched-content computation shared by status classification,
+ * import's unmanaged-dirty guard, and discard baseline planning.
  */
-export declare function computePatchedContent(patchesDir: string, engineDir: string, filePath: string): Promise<string | null>;
+export interface PatchedContentContext {
+    /** Manifest rows, so callers don't re-load the manifest per file. */
+    manifestPatches: readonly PatchMetadata[];
+    /** Cumulative patched content for a file (null if absent at HEAD with no creator). */
+    computePatched: (filePath: string) => Promise<string | null>;
+    /** Patches affecting a file, sorted by order (from the shared inverted index). */
+    getAffectingPatches: (filePath: string) => readonly PatchInfo[];
+    /** Patch body text, memoized per patch path across the whole batch. */
+    readPatchBody: (patch: PatchInfo) => Promise<string>;
+}
 /**
- * Builds a batched variant of {@link computePatchedContent} that loads the
- * manifest and discovers patch files ONCE for many lookups. The per-call
- * function re-runs `loadPatchesManifest` + `discoverPatches` for every
- * file — O(dirtyFiles × patches) redundant IO when classifying a broad
- * engine edit session during `import`.
+ * Builds a batched patched-content context that loads the manifest and
+ * discovers patch files ONCE for many lookups, and memoizes each patch
+ * body read across the batch. The old per-call helper re-ran
+ * `loadPatchesManifest` + `discoverPatches` and re-read every affecting
+ * patch body for every file — O(dirtyFiles × patches) redundant IO when
+ * classifying a broad engine edit session during `status` or `import`.
  */
-export declare function createPatchedContentComputer(patchesDir: string, engineDir: string): Promise<(filePath: string) => Promise<string | null>>;
+export declare function createPatchedContentContext(patchesDir: string, engineDir: string): Promise<PatchedContentContext>;

package/dist/src/core/patch-apply.js

@@ -14,9 +14,9 @@ import { exec } from '../utils/process.js';
 import { applyPatchIdempotent, reversePatch } from './git.js';
 import { getFileContentFromHead } from './git-file-ops.js';
 import { discoverPatches } from './patch-files.js';
-import { findPatchesAffectingFile, loadPatchesManifest } from './patch-manifest.js';
+import { loadPatchesManifest } from './patch-manifest.js';
 import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch } from './patch-parse.js';
-import { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+import { applyPatchTextToContent, extractNewFileContent } from './patch-transform.js';
 // Re-export from split modules so existing import sites continue working
 export { PatchError } from '../errors/patch.js';
 export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
@@ -394,33 +394,14 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, optionsOrC
     };
 }
 /**
- * Computes the cumulative patched content for a file.
- * @param patchesDir - Path to the patches directory
- * @param engineDir - Path to the engine directory
- * @param filePath - File path to compute content for
- * @returns Content after all patches applied, or null if file doesn't exist
- */
-export async function computePatchedContent(patchesDir, engineDir, filePath) {
-    let content = await getFileContentFromHead(engineDir, filePath);
-    // Find all patches affecting this file
-    const affectingPatches = await findPatchesAffectingFile(patchesDir, filePath);
-    if (affectingPatches.length === 0) {
-        return content;
-    }
-    // Apply each patch in order
-    for (const { patch } of affectingPatches) {
-        content = await applyPatchToContent(content, patch.path, filePath);
-    }
-    return content;
-}
-/**
- * Builds a batched variant of {@link computePatchedContent} that loads the
- * manifest and discovers patch files ONCE for many lookups. The per-call
- * function re-runs `loadPatchesManifest` + `discoverPatches` for every
- * file — O(dirtyFiles × patches) redundant IO when classifying a broad
- * engine edit session during `import`.
+ * Builds a batched patched-content context that loads the manifest and
+ * discovers patch files ONCE for many lookups, and memoizes each patch
+ * body read across the batch. The old per-call helper re-ran
+ * `loadPatchesManifest` + `discoverPatches` and re-read every affecting
+ * patch body for every file — O(dirtyFiles × patches) redundant IO when
+ * classifying a broad engine edit session during `status` or `import`.
  */
-export async function createPatchedContentComputer(patchesDir, engineDir) {
+export async function createPatchedContentContext(patchesDir, engineDir) {
     const manifest = await loadPatchesManifest(patchesDir);
     const patches = await discoverPatches(patchesDir);
     const patchByFilename = new Map(patches.map((p) => [p.filename, p]));
@@ -438,11 +419,29 @@ export async function createPatchedContentComputer(patchesDir, engineDir) {
     for (const list of affectingByFile.values()) {
         list.sort((a, b) => a.order - b.order);
     }
-    return async (filePath) => {
-        let content = await getFileContentFromHead(engineDir, filePath);
-        for (const patch of affectingByFile.get(filePath) ?? []) {
-            content = await applyPatchToContent(content, patch.path, filePath);
+    // Promise-memoized so concurrent classification workers never read the
+    // same body twice (memoizing the promise, not the value, closes the
+    // window between two workers missing the cache at once).
+    const bodyPromises = new Map();
+    const readPatchBody = (patch) => {
+        let body = bodyPromises.get(patch.path);
+        if (!body) {
+            body = readText(patch.path);
+            bodyPromises.set(patch.path, body);
         }
-        return content;
+        return body;
+    };
+    const getAffectingPatches = (filePath) => affectingByFile.get(filePath) ?? [];
+    return {
+        manifestPatches: manifest?.patches ?? [],
+        getAffectingPatches,
+        readPatchBody,
+        computePatched: async (filePath) => {
+            let content = await getFileContentFromHead(engineDir, filePath);
+            for (const patch of getAffectingPatches(filePath)) {
+                content = applyPatchTextToContent(content, await readPatchBody(patch), filePath);
+            }
+            return content;
+        },
     };
 }

package/dist/src/core/patch-export.js

@@ -10,6 +10,7 @@ import { findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
 import { addPatchToManifest, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
+import { escapeRegex } from '../utils/regex.js';
 export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
 export { updatePatchAndMetadata } from './patch-export-update.js';
 /**
@@ -45,9 +46,6 @@ export function sanitizeName(name) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 50);
 }
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
  * Operators frequently pass the DESIRED FILENAME stem to `--name`
@@ -59,8 +57,8 @@ function escapeRegExp(value) {
  */
 export function stripRedundantCategoryPrefix(sanitizedName, category) {
     const prefixes = [
-        new RegExp(`^\\d+-${escapeRegExp(category)}-`),
-        new RegExp(`^${escapeRegExp(category)}-`),
+        new RegExp(`^\\d+-${escapeRegex(category)}-`),
+        new RegExp(`^${escapeRegex(category)}-`),
     ];
     let stripped = sanitizedName;
     let changed = true;

package/dist/src/core/patch-lint-checkjs.d.ts

@@ -61,9 +61,17 @@ export interface GroupedCheckJsResult {
  *   the built-in Firefox-globals shim (from `patchLint.checkJsExtraShim`)
  * @param projectRoot - Absolute project root for resolving `extraShimPath`
  * @param mode - Strictness preset plus allowlisted compiler-option overrides
+ * @param builtinShimSuffix - Optional shim text appended AFTER the consumer shim
+ * @param rootScope - When set, only these repo-relative files become program
+ *   ROOTS; resolution (and the host allowlist) still spans all of
+ *   `resolutionOwned`, so a subset root's cross-patch imports type-check
+ *   against the real owning sources while unrelated owned files are never
+ *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
+ *   identical whether other owned files are roots or mere resolution
+ *   targets (pinned by the rootScope parity test — FORGE J1c).
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, builtinShimSuffix?: string): Promise<GroupedCheckJsResult>;
+export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, builtinShimSuffix?: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
  * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
  * `reportScope` is supplied, only diagnostics from files in that set are
@@ -110,7 +118,7 @@ export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles:
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  */
-export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<GroupedCheckJsResult>;
+export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
  * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
  * checkJs program over `patchOwnedFiles` and returns its findings grouped by
@@ -122,5 +130,19 @@ export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: S
  * @param patchOwnedFiles - Every patch-owned `.sys.mjs` in the queue
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
+ * @param rootScope - Optional subset of files to use as program roots
+ *   (`--patches`); resolution still spans the whole queue (FORGE J1c)
  */
-export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<GroupedCheckJsResult>;
+export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
+/**
+ * Cheap probe reproducing the only run-level ("global") checkJs findings
+ * the build path can produce — a missing `typescript` package and an
+ * unreadable consumer shim (`checkJsExtraShim`, and `checkJsTestShim`
+ * when `checkJsTestFiles` is on). The built program itself never
+ * contributes globals (see {@link runCheckJsGrouped}), so a warm
+ * all-cache-hit run can satisfy the "warm never reports less than cold"
+ * invariant (FORGE F5) with this probe instead of building the whole
+ * TypeScript program. Issue objects are byte-identical to the build
+ * path's, deduplicated by message like {@link runCheckJsTestFilesGrouped}.
+ */
+export declare function probeCheckJsGlobalIssues(patchLint: PatchLintConfig, projectRoot: string): Promise<PatchLintIssue[]>;