@hominis/fireforge 0.31.0 → 0.32.0

package/dist/src/core/git-diff.js

@@ -7,8 +7,8 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
-import { ensureGit, git } from './git-base.js';
-import { fileExistsInHead, isBinaryFile } from './git-file-ops.js';
+import { chunkPathspecs, ensureGit, git } from './git-base.js';
+import { fileExistsInHead, hashObjectBatch, isBinaryFile, listTrackedInHead, } from './git-file-ops.js';
 import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
 async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
     const result = await exec('git', args, { cwd: repoDir });
@@ -28,35 +28,33 @@ export async function getFileDiff(repoDir, filePath) {
     return git(['diff', 'HEAD', '--', filePath], repoDir);
 }
 /**
- * Generates a unified diff for a new (untracked) file.
- * @param repoDir - Repository directory
+ * Abbreviates a full git blob hash to the 10-character form used in the
+ * synthesized `index 0000000000..<hash>` line, falling back to the all-zero
+ * placeholder when no usable hash is available. Mirrors the original per-file
+ * truncation exactly.
+ * @param fullHash - Full blob hash, or undefined when hashing failed
+ * @returns 10-character abbreviated hash or the zero placeholder
+ */
+function abbreviateBlobHash(fullHash) {
+    if (fullHash !== undefined && fullHash.length >= 10) {
+        return fullHash.slice(0, 10);
+    }
+    return '0000000000';
+}
+/**
+ * Pure formatter for a new (untracked) file's unified diff. Extracted from
+ * {@link generateNewFileDiff} so the batched cold-run path in
+ * {@link getDiffForFilesAgainstHead} and the standalone path share one source of
+ * truth — the only thing that differs between them is where `blobHash` comes
+ * from (a single batched `git hash-object` vs a per-file one), never the
+ * formatting. Preserves the empty-file form, the trailing-newline handling, and
+ * the "No newline at end of file" marker byte-for-byte.
  * @param filePath - Path to the file (relative to repo)
+ * @param content - File content
+ * @param blobHash - Abbreviated blob hash for the index line
  * @returns Diff content in unified diff format
  */
-export async function generateNewFileDiff(repoDir, filePath) {
-    const fullPath = join(repoDir, filePath);
-    // Defensive check: a directory here means a caller bypassed the
-    // expansion layers and handed the leaf reader a path it cannot
-    // read. Surface it with an actionable message naming the offending
-    // path rather than the raw `EISDIR` that `readText` would throw —
-    // recurring bug class (see the belt-and-suspenders note in
-    // `getDiffForFilesAgainstHead`).
-    const fileStat = await stat(fullPath);
-    if (fileStat.isDirectory()) {
-        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
-    }
-    const content = await readText(fullPath);
-    // Compute the abbreviated git blob hash for the index line
-    let blobHash = '0000000000';
-    try {
-        const fullHash = (await git(['hash-object', fullPath], repoDir)).trim();
-        if (fullHash.length >= 10) {
-            blobHash = fullHash.slice(0, 10);
-        }
-    }
-    catch (error) {
-        verbose(`git hash-object failed for ${filePath}; falling back to zero blob hash: ${toError(error).message}`);
-    }
+function buildNewFileDiffBody(filePath, content, blobHash) {
     // Handle empty files
     if (content.length === 0) {
         return [
@@ -91,6 +89,36 @@ export async function generateNewFileDiff(repoDir, filePath) {
     }
     return diffLines.join('\n') + '\n';
 }
+/**
+ * Generates a unified diff for a new (untracked) file.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @returns Diff content in unified diff format
+ */
+export async function generateNewFileDiff(repoDir, filePath) {
+    const fullPath = join(repoDir, filePath);
+    // Defensive check: a directory here means a caller bypassed the
+    // expansion layers and handed the leaf reader a path it cannot
+    // read. Surface it with an actionable message naming the offending
+    // path rather than the raw `EISDIR` that `readText` would throw —
+    // recurring bug class (see the belt-and-suspenders note in
+    // `getDiffForFilesAgainstHead`).
+    const fileStat = await stat(fullPath);
+    if (fileStat.isDirectory()) {
+        throw new GitError(`expected a file but found a directory at '${filePath}' — caller must expand directory entries before diffing`, `hash-object ${filePath}`);
+    }
+    const content = await readText(fullPath);
+    // Compute the abbreviated git blob hash for the index line
+    let blobHash = '0000000000';
+    try {
+        const fullHash = (await git(['hash-object', fullPath], repoDir)).trim();
+        blobHash = abbreviateBlobHash(fullHash);
+    }
+    catch (error) {
+        verbose(`git hash-object failed for ${filePath}; falling back to zero blob hash: ${toError(error).message}`);
+    }
+    return buildNewFileDiffBody(filePath, content, blobHash);
+}
 /**
  * Generates a patch for a file.
  * If the file is tracked in HEAD, it generates a standard contextual diff.
@@ -185,10 +213,93 @@ export async function getAllDiff(repoDir) {
     const combined = allDiffs.join('');
     return combined.endsWith('\n') ? combined : combined + '\n';
 }
+/**
+ * Splits a combined `git diff` body into one string per file section,
+ * preserving exact bytes. A section runs from a column-0 `diff --git ` line up
+ * to (but not including) the next such line. Boundary detection is anchored to
+ * column 0 because every diff *body* line is prefixed by a space, `+`, `-`,
+ * `\`, or `@`, so a context or added line that merely contains the text
+ * `diff --git` can never be mistaken for a header. Paths are deliberately NOT
+ * parsed out of the header here — see {@link buildTrackedSections}.
+ * @param combined - Combined `git diff` stdout
+ * @returns File sections in git's emission order
+ */
+function splitDiffSections(combined) {
+    const marker = 'diff --git ';
+    const sections = [];
+    let start = -1;
+    for (let i = 0; i < combined.length; i++) {
+        if ((i === 0 || combined[i - 1] === '\n') && combined.startsWith(marker, i)) {
+            if (start !== -1)
+                sections.push(combined.slice(start, i));
+            start = i;
+        }
+    }
+    if (start !== -1)
+        sections.push(combined.slice(start, combined.length));
+    return sections;
+}
+/**
+ * Runs one `git diff --no-renames HEAD` over the tracked files (chunked under
+ * ARG_MAX) and returns a `Map<path, section>` whose sections are byte-identical
+ * to the per-file `git diff HEAD -- <file>` they replace.
+ *
+ * `--no-renames` is load-bearing: a multi-path diff under a user's
+ * `diff.renames=true`/`=copies` could otherwise emit a single 2-path rename
+ * section (`a/<old> b/<new>`) that a single-path `git diff HEAD -- <file>` can
+ * never produce; `--no-renames` re-splits it into the same delete + add bytes
+ * the per-file loop emitted.
+ *
+ * Sections are attributed to paths by POSITION against a companion
+ * `git diff --no-renames HEAD -z --name-only` (raw, unquoted, NUL-delimited
+ * paths, emitted in the same order as the sections) — never by parsing the
+ * `diff --git` header, which is ambiguous or unparseable under `core.quotePath`
+ * (non-ASCII paths are C-quoted), paths containing spaces, or
+ * `diff.noprefix`/`diff.mnemonicPrefix`. If the section and name counts ever
+ * disagree (an unmodeled config), that chunk falls back to per-file
+ * {@link getFileDiff} so no file's diff is ever silently dropped.
+ * @param repoDir - Repository directory
+ * @param trackedFiles - Repo-relative files known to exist in HEAD
+ * @returns Map from path to its exact diff section (changed files only)
+ */
+async function buildTrackedSections(repoDir, trackedFiles) {
+    const sectionsByPath = new Map();
+    for (const chunk of chunkPathspecs(trackedFiles)) {
+        const combined = await git(['diff', '--no-renames', 'HEAD', '--', ...chunk], repoDir);
+        const namesOutput = await git(['diff', '--no-renames', 'HEAD', '-z', '--name-only', '--', ...chunk], repoDir);
+        const names = namesOutput.split('\0').filter((name) => name.length > 0);
+        const sections = splitDiffSections(combined);
+        if (sections.length === names.length) {
+            for (let i = 0; i < names.length; i++) {
+                // Exact-path keys (raw git bytes, same encoding as the inputs) — never
+                // a substring/startsWith match, so `foo.txt` cannot capture
+                // `foo.txt.bak`'s section.
+                sectionsByPath.set(names[i], sections[i]);
+            }
+            continue;
+        }
+        // Counts disagree — recover the exact pre-batch per-file bytes for this
+        // chunk rather than risk dropping or mis-keying a section.
+        for (const file of chunk) {
+            const diff = await getFileDiff(repoDir, file);
+            if (diff.trim())
+                sectionsByPath.set(file, diff);
+        }
+    }
+    return sectionsByPath;
+}
 /**
  * Builds a combined diff against HEAD for the provided files without touching
  * the real git index. Tracked files use `git diff HEAD`; untracked files use
  * synthesized new-file diffs.
+ *
+ * Performance: the work is batched into a handful of `git` invocations
+ * (one `ls-tree` to classify, one `diff` over all tracked files, one
+ * `hash-object` over all new text files) rather than the ~2 spawns per file the
+ * previous per-file loop issued — that fan-out dominated the cold-run cost on a
+ * Firefox-sized checkout (~700 serial spawns, ~99s). Binary, directory, and
+ * recursion paths stay per-file because they are rare and (for binary) mutate
+ * the index.
  * @param repoDir - Repository directory
  * @param files - File paths to diff (relative to repo root)
  * @returns Combined diff content
@@ -215,15 +326,24 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
         expandedFiles.push(file);
     }
     const uniqueFiles = [...new Set(expandedFiles)].sort();
-    const diffs = [];
+    if (uniqueFiles.length === 0)
+        return '';
+    // Batch 1: classify tracked-vs-new for the whole set in one `ls-tree` pass,
+    // replacing one `fileExistsInHead` spawn per file.
+    const tracked = await listTrackedInHead(repoDir, uniqueFiles);
+    // Batch 2: one diff over every tracked file, split back to exact per-file
+    // sections keyed by path.
+    const trackedSections = await buildTrackedSections(repoDir, uniqueFiles.filter((file) => tracked.has(file)));
+    // Classify the non-tracked files. Directory and binary entries keep their
+    // per-file handling (rare, and binary patches mutate the index so they must
+    // stay serial); plain new text files are collected for a single batched
+    // `git hash-object`. Results land in `sectionByFile`, keyed by path, to be
+    // emitted in sorted order below.
+    const sectionByFile = new Map();
+    const newTextFiles = [];
     for (const file of uniqueFiles) {
-        if (await fileExistsInHead(repoDir, file)) {
-            const diff = await getFileDiff(repoDir, file);
-            if (diff.trim()) {
-                diffs.push(diff);
-            }
+        if (tracked.has(file))
             continue;
-        }
         const fullPath = join(repoDir, file);
         if (!(await pathExists(fullPath))) {
             continue;
@@ -244,17 +364,42 @@ export async function getDiffForFilesAgainstHead(repoDir, files) {
                 throw new GitError(`'${file}' is a directory with no untracked content (submodule or gitignored?) — cannot diff as a file`, `ls-files --others -- ${file}`);
             }
             const innerDiff = await getDiffForFilesAgainstHead(repoDir, innerFiles);
-            if (innerDiff.trim()) {
-                diffs.push(innerDiff);
-            }
+            if (innerDiff.trim())
+                sectionByFile.set(file, innerDiff);
             continue;
         }
-        const diff = (await isBinaryFile(repoDir, file))
-            ? await generateBinaryFilePatch(repoDir, file)
-            : await generateNewFileDiff(repoDir, file);
-        if (diff.trim()) {
-            diffs.push(diff);
+        if (await isBinaryFile(repoDir, file)) {
+            const diff = await generateBinaryFilePatch(repoDir, file);
+            if (diff.trim())
+                sectionByFile.set(file, diff);
+            continue;
+        }
+        newTextFiles.push(file);
+    }
+    // Batch 3: blob hashes for every new text file in one `git hash-object`.
+    // A miss (rare: a path became unreadable after the stat above) falls back to
+    // the zero hash with the same verbose log the per-file path emitted.
+    const blobHashes = await hashObjectBatch(repoDir, newTextFiles.map((file) => join(repoDir, file)));
+    for (const file of newTextFiles) {
+        const fullPath = join(repoDir, file);
+        const fullHash = blobHashes.get(fullPath);
+        if (fullHash === undefined) {
+            verbose(`git hash-object failed for ${file}; falling back to zero blob hash`);
         }
+        const body = buildNewFileDiffBody(file, await readText(fullPath), abbreviateBlobHash(fullHash));
+        if (body.trim())
+            sectionByFile.set(file, body);
+    }
+    // Reassemble in the sorted `uniqueFiles` order — NOT git's section order,
+    // which uses git's own collation and diverges from JS `.sort()` for
+    // non-ASCII paths. Driving emission off `uniqueFiles` (as the previous
+    // per-file loop did) keeps the combined output byte-identical. Do not change
+    // this to push sections in git's emission order.
+    const diffs = [];
+    for (const file of uniqueFiles) {
+        const section = trackedSections.get(file) ?? sectionByFile.get(file);
+        if (section && section.trim())
+            diffs.push(section);
     }
     if (diffs.length === 0) {
         return '';
@@ -275,6 +420,22 @@ export async function getStagedDiffForFiles(repoDir, files) {
     await ensureGit();
     return git(['diff', '--cached', 'HEAD', '--', ...files], repoDir);
 }
+/**
+ * Serializes the index-mutating untracked-binary path. The bounded per-patch
+ * lint pool can call {@link getDiffForFilesAgainstHead} (and thus this) for
+ * several patches at once; two concurrent `git add --intent-to-add` / `git
+ * reset` sequences would collide on `.git/index.lock` (a hard failure) or
+ * interleave one file's stage with another's unstage. This process-level
+ * promise chain runs the staging sequences one at a time. Read-only callers
+ * (`git diff --binary HEAD`) do not need it. Binary patches are rare, so the
+ * serialization cost is negligible.
+ */
+let binaryStagingLock = Promise.resolve();
+function runWithBinaryStagingLock(task) {
+    const result = binaryStagingLock.then(task, task);
+    binaryStagingLock = result.then(() => undefined, () => undefined);
+    return result;
+}
 /**
  * Generates a GIT binary patch for a binary file.
  * For tracked files, uses `git diff --binary HEAD`.
@@ -285,7 +446,7 @@ export async function getStagedDiffForFiles(repoDir, files) {
  */
 export async function generateBinaryFilePatch(repoDir, filePath) {
     await ensureGit();
-    // Try tracked file diff first
+    // Try tracked file diff first (read-only — no index lock needed)
     const result = await execGitWithAllowedExitCodes(repoDir, [
         'diff',
         '--binary',
@@ -295,20 +456,24 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     ]);
     if (result.stdout.trim())
         return result.stdout;
-    // For untracked files, stage temporarily to produce a binary diff
-    try {
-        await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
-        const diffResult = await execGitWithAllowedExitCodes(repoDir, [
-            'diff',
-            '--binary',
-            '--',
-            filePath,
-        ]);
-        return diffResult.stdout;
-    }
-    finally {
-        // Always unstage, even if diff fails
-        await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
-    }
+    // For untracked files, stage temporarily to produce a binary diff. The
+    // stage/unstage pair mutates the index, so it must not interleave with
+    // another concurrent binary patch (see runWithBinaryStagingLock).
+    return runWithBinaryStagingLock(async () => {
+        try {
+            await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
+            const diffResult = await execGitWithAllowedExitCodes(repoDir, [
+                'diff',
+                '--binary',
+                '--',
+                filePath,
+            ]);
+            return diffResult.stdout;
+        }
+        finally {
+            // Always unstage, even if diff fails
+            await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+        }
+    });
 }
 //# sourceMappingURL=git-diff.js.map

package/dist/src/core/git-file-ops.d.ts

@@ -30,6 +30,45 @@ export declare function unstageFiles(repoDir: string, files: string[]): Promise<
  * @returns true if file exists in HEAD
  */
 export declare function fileExistsInHead(repoDir: string, filePath: string): Promise<boolean>;
+/**
+ * Batched equivalent of {@link fileExistsInHead}: returns the subset of `files`
+ * that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX chunk
+ * instead of one spawn per file. This is the cold-run hot path — a Firefox-sized
+ * checkout has hundreds of affected files, and the old per-file fan-out spent
+ * ~99s in serial `git ls-tree`/`git diff` spawns.
+ *
+ * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes the
+ * output a trivial NUL-split with no quoting to undo. Membership in the returned
+ * Set is exactly `await fileExistsInHead(repoDir, file)` for any non-directory
+ * `file`. Throws (via {@link git}) when HEAD itself is unresolvable, matching the
+ * per-file helper's failure mode.
+ * @param repoDir - Repository directory
+ * @param files - Repo-relative paths to classify
+ * @returns The subset of `files` present in HEAD
+ */
+export declare function listTrackedInHead(repoDir: string, files: string[]): Promise<Set<string>>;
+/**
+ * Batched equivalent of the per-file `git hash-object` in
+ * {@link import('./git-diff.js').generateNewFileDiff}: computes the git blob
+ * hash for every path in one spawn per ARG_MAX chunk and returns a
+ * `Map<fullPath, fullHash>`.
+ *
+ * Uses {@link import('../utils/process.js').exec} rather than {@link git}
+ * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
+ * all-or-nothing: it aborts at the first unreadable path and emits nothing for
+ * the rest. To preserve the old per-file contract — where one bad path zeroed
+ * only its own index line — a chunk that does not return exactly one hash per
+ * input falls back to hashing that chunk's paths individually. A path that is
+ * still unhashable is simply left out of the map; the caller applies the
+ * `0000000000` zero-hash fallback (and the same verbose log) for any miss, so
+ * the blob hash is byte-identical to `git hash-object` (filters/.gitattributes
+ * are applied per path) without the risk of in-process hashing, which would
+ * diverge under `core.autocrlf`/`text` attributes.
+ * @param repoDir - Repository directory
+ * @param fullPaths - Absolute file paths to hash
+ * @returns Map from each input path to its full blob hash (misses omitted)
+ */
+export declare function hashObjectBatch(repoDir: string, fullPaths: string[]): Promise<Map<string, string>>;
 /**
  * Gets the content of a file at a specific git ref (HEAD by default).
  * @param repoDir - Repository directory

package/dist/src/core/git-file-ops.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { GitError } from '../errors/git.js';
 import { removeFile } from '../utils/fs.js';
 import { exec } from '../utils/process.js';
-import { ensureGit, git } from './git-base.js';
+import { chunkPathspecs, ensureGit, git } from './git-base.js';
 /**
  * Restores a tracked path from HEAD, including staged changes.
  * @param repoDir - Repository directory
@@ -87,6 +87,87 @@ export async function fileExistsInHead(repoDir, filePath) {
     await ensureGit();
     return (await git(['ls-tree', 'HEAD', '--', filePath], repoDir)).trim().length > 0;
 }
+/**
+ * Batched equivalent of {@link fileExistsInHead}: returns the subset of `files`
+ * that are tracked in HEAD, using a single `git ls-tree` per ARG_MAX chunk
+ * instead of one spawn per file. This is the cold-run hot path — a Firefox-sized
+ * checkout has hundreds of affected files, and the old per-file fan-out spent
+ * ~99s in serial `git ls-tree`/`git diff` spawns.
+ *
+ * `-r` lists nested blobs by full repo-relative path; `--name-only -z` makes the
+ * output a trivial NUL-split with no quoting to undo. Membership in the returned
+ * Set is exactly `await fileExistsInHead(repoDir, file)` for any non-directory
+ * `file`. Throws (via {@link git}) when HEAD itself is unresolvable, matching the
+ * per-file helper's failure mode.
+ * @param repoDir - Repository directory
+ * @param files - Repo-relative paths to classify
+ * @returns The subset of `files` present in HEAD
+ */
+export async function listTrackedInHead(repoDir, files) {
+    const tracked = new Set();
+    if (files.length === 0)
+        return tracked;
+    await ensureGit();
+    const wanted = new Set(files);
+    for (const chunk of chunkPathspecs(files)) {
+        const output = await git(['ls-tree', '-r', 'HEAD', '--name-only', '-z', '--', ...chunk], repoDir);
+        for (const name of output.split('\0')) {
+            // `ls-tree -r` can surface entries beyond the literal inputs only when an
+            // input is itself a directory in HEAD; intersect with `wanted` so the
+            // result is always a subset of the requested files, never a superset.
+            if (name.length > 0 && wanted.has(name))
+                tracked.add(name);
+        }
+    }
+    return tracked;
+}
+/**
+ * Batched equivalent of the per-file `git hash-object` in
+ * {@link import('./git-diff.js').generateNewFileDiff}: computes the git blob
+ * hash for every path in one spawn per ARG_MAX chunk and returns a
+ * `Map<fullPath, fullHash>`.
+ *
+ * Uses {@link import('../utils/process.js').exec} rather than {@link git}
+ * (which throws on a non-zero exit) because `git hash-object f1 f2 …` is
+ * all-or-nothing: it aborts at the first unreadable path and emits nothing for
+ * the rest. To preserve the old per-file contract — where one bad path zeroed
+ * only its own index line — a chunk that does not return exactly one hash per
+ * input falls back to hashing that chunk's paths individually. A path that is
+ * still unhashable is simply left out of the map; the caller applies the
+ * `0000000000` zero-hash fallback (and the same verbose log) for any miss, so
+ * the blob hash is byte-identical to `git hash-object` (filters/.gitattributes
+ * are applied per path) without the risk of in-process hashing, which would
+ * diverge under `core.autocrlf`/`text` attributes.
+ * @param repoDir - Repository directory
+ * @param fullPaths - Absolute file paths to hash
+ * @returns Map from each input path to its full blob hash (misses omitted)
+ */
+export async function hashObjectBatch(repoDir, fullPaths) {
+    const hashes = new Map();
+    if (fullPaths.length === 0)
+        return hashes;
+    await ensureGit();
+    for (const chunk of chunkPathspecs(fullPaths)) {
+        const result = await exec('git', ['hash-object', '--', ...chunk], { cwd: repoDir });
+        const lines = result.stdout.split('\n').filter((line) => line.length > 0);
+        if (result.exitCode === 0 && lines.length === chunk.length) {
+            for (let i = 0; i < chunk.length; i++) {
+                hashes.set(chunk[i], lines[i]);
+            }
+            continue;
+        }
+        // Batch aborted partway (a path became unreadable between the caller's stat
+        // and here, or otherwise failed). Recover per file so one bad path only
+        // loses its own hash, exactly as the pre-batch per-file code behaved.
+        for (const path of chunk) {
+            const single = await exec('git', ['hash-object', '--', path], { cwd: repoDir });
+            const hash = single.stdout.trim();
+            if (single.exitCode === 0 && hash.length > 0)
+                hashes.set(path, hash);
+        }
+    }
+    return hashes;
+}
 /**
  * Gets the content of a file at a specific git ref (HEAD by default).
  * @param repoDir - Repository directory

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

@@ -199,3 +199,20 @@ export declare function test(engineDir: string, testPaths?: string[], args?: str
  *   `fireforge test --perf-samples` to publish the artifact-path contract.
  */
 export declare function testWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+/**
+ * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
+ * capturing output. Unlike the generic `mach test`, the suite-specific
+ * commands degrade a broken mozlog resource monitor to a warning instead of
+ * crashing at startup, so `fireforge test` dispatches single-suite runs here
+ * to stay resilient to the host psutil failure (field report E1).
+ *
+ * Signature mirrors {@link testWithOutput} so the two are interchangeable in
+ * the dispatch path.
+ */
+export declare function xpcshellTestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+/**
+ * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
+ * capturing output. The suite-specific counterpart to {@link testWithOutput}
+ * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
+ */
+export declare function mochitestWithOutput(engineDir: string, testPaths?: string[], args?: string[], env?: Record<string, string>): Promise<MachCommandResult>;

package/dist/src/core/mach.js

@@ -320,4 +320,25 @@ export async function test(engineDir, testPaths = [], args = []) {
 export async function testWithOutput(engineDir, testPaths = [], args = [], env) {
     return runMachCapture(['test', ...testPaths, ...args], engineDir, env ? { env } : {});
 }
+/**
+ * Runs `mach xpcshell-test` (the suite-specific xpcshell command) while
+ * capturing output. Unlike the generic `mach test`, the suite-specific
+ * commands degrade a broken mozlog resource monitor to a warning instead of
+ * crashing at startup, so `fireforge test` dispatches single-suite runs here
+ * to stay resilient to the host psutil failure (field report E1).
+ *
+ * Signature mirrors {@link testWithOutput} so the two are interchangeable in
+ * the dispatch path.
+ */
+export async function xpcshellTestWithOutput(engineDir, testPaths = [], args = [], env) {
+    return runMachCapture(['xpcshell-test', ...testPaths, ...args], engineDir, env ? { env } : {});
+}
+/**
+ * Runs `mach mochitest` (covers browser-chrome / mochitest flavors) while
+ * capturing output. The suite-specific counterpart to {@link testWithOutput}
+ * for non-xpcshell single-suite runs — see {@link xpcshellTestWithOutput}.
+ */
+export async function mochitestWithOutput(engineDir, testPaths = [], args = [], env) {
+    return runMachCapture(['mochitest', ...testPaths, ...args], engineDir, env ? { env } : {});
+}
 //# sourceMappingURL=mach.js.map

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

@@ -15,35 +15,89 @@
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
  * and optional allowlisted `checkJsCompilerOptions`; it does not change
  * shim composition or suppressed diagnostic codes.
+ *
+ * Resolution scope vs reporting scope: the TS program is built over a
+ * *resolution* set (every patch-owned `.sys.mjs` the run cares about, so
+ * cross-patch `resource:///` imports resolve to their real sources), while
+ * diagnostics are emitted only for files in the *report* scope. Splitting
+ * the two lets per-patch lint build one queue-wide program and attribute
+ * findings per patch, and lets export/re-export resolve cross-patch imports
+ * while reporting only the patch under export.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintCheckJsCompilerOptions, PatchLintConfig } from '../types/config.js';
+/** How a checkJs run controls reporting and resolution; see module docs. */
+export interface CheckJsMode {
+    strict: boolean;
+    compilerOptions?: PatchLintCheckJsCompilerOptions;
+}
+/**
+ * Result of {@link runCheckJsGrouped}: diagnostics attributed to the
+ * patch-owned file they originate in (`byFile`, keyed by repo-relative
+ * path), plus run-level errors that have no owning file (`global` — e.g.
+ * TypeScript missing or an unreadable extra shim).
+ */
+export interface GroupedCheckJsResult {
+    byFile: Map<string, PatchLintIssue[]>;
+    global: PatchLintIssue[];
+}
+/**
+ * Builds the checkJs program **once** over `resolutionOwned` and returns its
+ * diagnostics grouped by originating file. Callers slice the result by their
+ * own report scope — per-patch lint attributes each file to its owning
+ * patch, export/re-export keeps only the patch under export. Resolution
+ * always spans every file in `resolutionOwned`, so cross-patch
+ * `resource:///`/`chrome://` imports resolve to real sources.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param resolutionOwned - Patch-owned `.sys.mjs` paths (relative to repoDir)
+ *   the program should see and resolve against
+ * @param extraShimPath - Optional project-relative extra `.d.ts` appended to
+ *   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
+ * @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): Promise<GroupedCheckJsResult>;
 /**
- * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
+ * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
+ * `reportScope` is supplied, only diagnostics from files in that set are
+ * returned (resolution still spans every owned file); omitting it reports
+ * every owned file's diagnostics — the historical whole-set behaviour.
  *
- * @param repoDir - Absolute path to the engine (repository) directory
- * @param patchOwnedFiles - Set of patch-owned `.sys.mjs` file paths (relative to repoDir)
- * @param extraShimPath - Optional project-relative path to an additional
- *   `.d.ts` file whose contents are concatenated to the built-in
- *   Firefox-globals shim. Sourced from `patchLint.checkJsExtraShim`.
- *   Resolved against `projectRoot` (one level up from `repoDir` is the
- *   wrong root — patches sit inside `engine/` while the shim lives at
- *   the project root, so the caller passes both).
- * @param projectRoot - Absolute project root for resolving `extraShimPath`.
- *   Defaults to `repoDir` for back-compat with callers that don't
- *   pass an extra shim (no resolution actually happens in that case).
- * @param mode - When `strict` is true, enables `strict` and `noImplicitAny`
- *   (CI-style). Optional `compilerOptions` merges allowlisted boolean
- *   overrides after that preset (from `patchLint.checkJsCompilerOptions`).
- *   Omitted or `{ strict: false }` preserves the historical loose preset.
+ * @param repoDir - Absolute engine (repository) directory
+ * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
+ * @param extraShimPath - Optional project-relative extra `.d.ts`
+ * @param projectRoot - Absolute project root for resolving `extraShimPath`
+ * @param mode - Strictness preset plus allowlisted compiler-option overrides
+ * @param reportScope - When set, restrict reported diagnostics to these
+ *   repo-relative files
  * @returns Array of lint issues from TS diagnostics
  */
-export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: {
-    strict: boolean;
-    compilerOptions?: PatchLintCheckJsCompilerOptions;
-}): Promise<PatchLintIssue[]>;
+export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
 /**
  * Invokes {@link runCheckJs} for a `patchLint` block with `checkJs: true`.
  * `projectRoot` is the FireForge project root (`dirname(engine)`).
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
+ * @param reportScope - Optional repo-relative files to report on (export /
+ *   re-export passes the patch under export so cross-patch resolution does
+ *   not surface other patches' diagnostics)
+ */
+export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
+/**
+ * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
+ * checkJs program over `patchOwnedFiles` and returns its findings grouped by
+ * owning file. The per-patch lint orchestrator calls this **once per run**
+ * and attributes each file's findings to its owning patch, instead of
+ * rebuilding the same program for every patch in the queue.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @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
  */
-export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<PatchLintIssue[]>;
+export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<GroupedCheckJsResult>;