@hominis/fireforge 0.31.0 → 0.33.0

package/dist/src/core/mach.js

@@ -8,6 +8,7 @@ import { createSiblingLockPath, withFileLock } from './file-lock.js';
 import { ensureFirefoxIgnorefileCompatibility } from './firefox-ignorefile.js';
 import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
+import { resolveMachBuildEnv } from './mach-resource-shim.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
 export { attemptMozinfoRewrite, buildArtifactMismatchMessage, hasBuildArtifacts, hasRunnableBundle, } from './mach-build-artifacts.js';
 export { generateMozconfig } from './mach-mozconfig.js';
@@ -156,7 +157,10 @@ export async function build(engineDir, jobs) {
     if (jobs !== undefined) {
         args.push('-j', String(jobs));
     }
-    const result = await runMachInheritCapture(args, engineDir);
+    // Inject the resource-monitor degrade shim so a host psutil failure does
+    // not abort the build regardless of which mach entry FireForge spawns.
+    const env = await resolveMachBuildEnv();
+    const result = await runMachInheritCapture(args, engineDir, { env });
     if (result.exitCode !== 0) {
         surfaceMachErrorHints(result);
     }
@@ -170,7 +174,10 @@ export async function build(engineDir, jobs) {
  * @returns Captured mach result
  */
 export async function buildUI(engineDir) {
-    const result = await runMachInheritCapture(['build', 'faster'], engineDir);
+    // Same resource-monitor degrade shim as the full build: raw
+    // `./mach build faster` aborts on the host psutil monitor without it.
+    const env = await resolveMachBuildEnv();
+    const result = await runMachInheritCapture(['build', 'faster'], engineDir, { env });
     if (result.exitCode !== 0) {
         surfaceMachErrorHints(result);
     }
@@ -320,4 +327,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/manifest-helpers.js

@@ -1,3 +1,28 @@
+/**
+ * Ordering comparator matching mozbuild's `StrictOrderingOnAppendList`
+ * (`mozbuild.util.UnsortedError`): entries are compared **case-insensitively**,
+ * so `HominisAppearanceController` (`appe`) sorts before
+ * `HominisAppMenuIntegration` (`appm`) even though a raw byte comparison
+ * places the uppercase `M` (0x4D) before the lowercase `e` (0x65).
+ *
+ * A naive `a > b` insertion landed the new entry in byte order, which
+ * `mach configure` then rejected with `UnsortedError`, aborting the build.
+ * Ties on the lower-cased key fall back to byte order so the comparison is
+ * total and stable.
+ */
+function mozbuildSortCompare(a, b) {
+    const la = a.toLowerCase();
+    const lb = b.toLowerCase();
+    if (la < lb)
+        return -1;
+    if (la > lb)
+        return 1;
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
 /**
  * Inserts a line into an array of lines in alphabetical order within a
  * specified range. The comparison key is extracted from each line.
@@ -16,7 +41,7 @@ export function findAlphabeticalPosition(lines, startLine, endLine, newKey, extr
             existingKeys.push(key);
         }
     }
-    const isSorted = existingKeys.every((k, idx) => idx === 0 || k.localeCompare(existingKeys[idx - 1] ?? '') >= 0);
+    const isSorted = existingKeys.every((k, idx) => idx === 0 || mozbuildSortCompare(k, existingKeys[idx - 1] ?? '') >= 0);
     if (!isSorted) {
         return { insertIndex: endLine, previousEntry: undefined };
     }
@@ -29,7 +54,7 @@ export function findAlphabeticalPosition(lines, startLine, endLine, newKey, extr
         const key = extractKey(line);
         if (key === undefined)
             continue;
-        if (key > newKey) {
+        if (mozbuildSortCompare(key, newKey) > 0) {
             insertIndex = i;
             break;
         }
@@ -61,7 +86,7 @@ export function findAlphabeticalTokenPosition(tokens, sectionTargetPattern, newK
             continue;
         const match = sectionTargetPattern.exec(entry.parsed.target);
         const key = match?.[1] ?? entry.parsed.target;
-        if (key > newKey) {
+        if (mozbuildSortCompare(key, newKey) > 0) {
             insertLineIndex = entry.lineIndex;
             break;
         }
@@ -84,7 +109,7 @@ export function findAlphabeticalMozBuildPosition(tokens, newKey) {
     let previousEntry;
     for (const item of items) {
         const key = item.parsed?.value ?? '';
-        if (key > newKey) {
+        if (mozbuildSortCompare(key, newKey) > 0) {
             insertLineIndex = item.lineIndex;
             break;
         }

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>;

package/dist/src/core/patch-lint-checkjs.js

@@ -16,6 +16,14 @@
  * `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 { basename, resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
@@ -62,57 +70,121 @@ function createOwnedSpecifierResolver(ts, ownedAbsolute) {
         };
     };
 }
+/** Maps a resolved file path to the TS extension enum the host must report. */
+function extensionForFile(ts, file) {
+    if (file.endsWith('.d.ts'))
+        return ts.Extension.Dts;
+    if (file.endsWith('.ts'))
+        return ts.Extension.Ts;
+    if (file.endsWith('.tsx'))
+        return ts.Extension.Tsx;
+    if (file.endsWith('.cjs'))
+        return ts.Extension.Cjs;
+    if (file.endsWith('.jsx'))
+        return ts.Extension.Jsx;
+    if (file.endsWith('.json'))
+        return ts.Extension.Json;
+    return ts.Extension.Mjs;
+}
 /**
- * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
+ * Builds a resolver for a reviewed `paths` mapping (route 2 of the
+ * cross-patch resolution work). Each pattern may contain a single `*`;
+ * matching targets are resolved relative to `baseDir` (the engine dir, like
+ * the rest of `patchLint` which is engine-relative). Resolved files are
+ * recorded via `onResolved` so the compiler host knows to read them from
+ * disk rather than returning empty content. No `baseUrl` is set, so this is
+ * TS5090-safe: `paths` resolution is host-driven here, not config-driven.
+ */
+function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
+    const entries = Object.entries(paths);
+    return (specifier) => {
+        for (const [pattern, targets] of entries) {
+            const star = pattern.indexOf('*');
+            let captured;
+            if (star === -1) {
+                if (specifier !== pattern)
+                    continue;
+                captured = '';
+            }
+            else {
+                const prefix = pattern.slice(0, star);
+                const suffix = pattern.slice(star + 1);
+                if (specifier.length < prefix.length + suffix.length)
+                    continue;
+                if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+                    continue;
+                captured = specifier.slice(prefix.length, specifier.length - suffix.length);
+            }
+            for (const target of targets) {
+                const rel = target.includes('*') ? target.replace('*', captured) : target;
+                const abs = resolve(baseDir, rel);
+                if (!fileExists(abs))
+                    continue;
+                onResolved(abs);
+                return {
+                    resolvedFileName: abs,
+                    extension: extensionForFile(ts, abs),
+                    isExternalLibraryImport: false,
+                };
+            }
+        }
+        return undefined;
+    };
+}
+/**
+ * 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 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.
- * @returns Array of lint issues from TS diagnostics
+ * @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 async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode) {
-    if (patchOwnedFiles.size === 0)
-        return [];
+export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode) {
+    const empty = { byFile: new Map(), global: [] };
+    if (resolutionOwned.size === 0)
+        return empty;
     // Dynamic import — typescript stays as a dev dependency
     let ts;
     try {
         ts = await import('typescript');
     }
     catch {
-        return [
-            {
-                file: '(checkJs)',
-                check: 'checkjs-type-error',
-                message: 'patchLint.checkJs is enabled but the "typescript" package is not installed. ' +
-                    'Run "npm install typescript" to enable type checking.',
-                severity: 'error',
-            },
-        ];
+        return {
+            byFile: new Map(),
+            global: [
+                {
+                    file: '(checkJs)',
+                    check: 'checkjs-type-error',
+                    message: 'patchLint.checkJs is enabled but the "typescript" package is not installed. ' +
+                        'Run "npm install typescript" to enable type checking.',
+                    severity: 'error',
+                },
+            ],
+        };
     }
     // Resolve absolute paths for root files, filtering to files that exist
     const rootFiles = [];
     const ownedAbsolute = new Set();
-    for (const rel of patchOwnedFiles) {
+    const relByAbsolute = new Map();
+    for (const rel of resolutionOwned) {
         const abs = resolve(repoDir, rel);
         if (await pathExists(abs)) {
             rootFiles.push(abs);
             ownedAbsolute.add(abs);
+            relByAbsolute.set(abs, rel);
         }
     }
     if (rootFiles.length === 0)
-        return [];
+        return empty;
     // Compose the shim. `extraShimPath` is project-relative (validated
     // by config-validate); resolve it against `projectRoot`. When the
     // caller passes neither, fall back to `repoDir` — the only way the
@@ -127,14 +199,17 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
         }
     }
     catch (err) {
-        return [
-            {
-                file: extraShimPath ?? '(checkJs)',
-                check: 'checkjs-type-error',
-                message: err instanceof Error ? err.message : String(err),
-                severity: 'error',
-            },
-        ];
+        return {
+            byFile: new Map(),
+            global: [
+                {
+                    file: extraShimPath ?? '(checkJs)',
+                    check: 'checkjs-type-error',
+                    message: err instanceof Error ? err.message : String(err),
+                    severity: 'error',
+                },
+            ],
+        };
     }
     const shimPath = resolve(repoDir, SHIM_FILENAME);
     rootFiles.push(shimPath);
@@ -146,12 +221,23 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
             strict: false,
             noImplicitAny: false,
         };
+    // Allowlisted overrides. Booleans merge directly; a reviewed `paths`
+    // mapping is applied to the compiler options AND wired into the host
+    // resolver below so patch-owned modules can be typed from their real
+    // sources without a hand-generated ambient stub shim.
     const overrides = {};
+    let pathsMapping;
     const co = mode?.compilerOptions;
     if (co) {
         for (const key of Object.keys(co)) {
             const v = co[key];
-            if (v !== undefined) {
+            if (v === undefined)
+                continue;
+            if (key === 'paths') {
+                pathsMapping = v;
+                overrides.paths = pathsMapping;
+            }
+            else {
                 overrides[key] = v;
             }
         }
@@ -180,13 +266,19 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
     // the shim for the shim path, and returns empty content for
     // anything else to avoid reading the full Firefox tree.
     const defaultHost = ts.createCompilerHost(options);
+    // Files pulled in via a reviewed `paths` mapping — outside the owned set
+    // but read from disk so the resolver's targets actually type-check.
+    const pathsResolved = new Set();
+    const resolveViaPaths = pathsMapping
+        ? createPathsResolver(ts, pathsMapping, repoDir, (f) => defaultHost.fileExists(f), (abs) => pathsResolved.add(abs))
+        : undefined;
     const host = {
         ...defaultHost,
         getSourceFile(fileName, languageVersion, onError) {
             if (fileName === shimPath) {
                 return ts.createSourceFile(fileName, shimSource, languageVersion, true);
             }
-            if (ownedAbsolute.has(fileName)) {
+            if (ownedAbsolute.has(fileName) || pathsResolved.has(fileName)) {
                 return defaultHost.getSourceFile(fileName, languageVersion, onError);
             }
             // For lib files (lib.es*.d.ts) delegate to the default host
@@ -201,7 +293,7 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
         fileExists(fileName) {
             if (fileName === shimPath)
                 return true;
-            if (ownedAbsolute.has(fileName))
+            if (ownedAbsolute.has(fileName) || pathsResolved.has(fileName))
                 return true;
             return defaultHost.fileExists(fileName);
         },
@@ -211,61 +303,115 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
             return defaultHost.readFile(fileName);
         },
         resolveModuleNameLiterals(moduleLiterals) {
-            return moduleLiterals.map((literal) => ({
-                resolvedModule: resolveOwnedSpecifier(literal.text),
-            }));
+            return moduleLiterals.map((literal) => {
+                const owned = resolveOwnedSpecifier(literal.text);
+                if (owned)
+                    return { resolvedModule: owned };
+                return { resolvedModule: resolveViaPaths?.(literal.text) };
+            });
         },
     };
     const program = ts.createProgram(rootFiles, options, host);
-    const allDiagnostics = [
-        ...program.getSemanticDiagnostics(),
-        ...program.getSyntacticDiagnostics(),
-    ];
-    // Filter to diagnostics originating in patch-owned files only,
-    // and suppress module-resolution / unknown-name noise that is
-    // inherent to checking Firefox JS outside Mozilla's build system.
-    const issues = [];
-    for (const diag of allDiagnostics) {
+    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute);
+    verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s) across ${byFile.size} owning file(s)`);
+    return { byFile, global: [] };
+}
+/**
+ * Groups TS diagnostics by the patch-owned file they originate in,
+ * suppressing module-resolution / unknown-name noise inherent to checking
+ * Firefox JS outside Mozilla's build system. Diagnostics from `paths`-resolved
+ * or shim files are dropped — only owned files (in `relByAbsolute`) carry
+ * findings.
+ */
+function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute) {
+    const byFile = new Map();
+    for (const diag of diagnostics) {
         if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
             continue;
         const sourceFile = diag.file;
         if (!sourceFile)
             continue;
-        if (!ownedAbsolute.has(sourceFile.fileName))
+        const relPath = relByAbsolute.get(sourceFile.fileName);
+        if (relPath === undefined)
             continue;
         const lineInfo = sourceFile.getLineAndCharacterOfPosition(diag.start ?? 0);
         const line = lineInfo.line + 1;
         const messageText = typeof diag.messageText === 'string'
             ? diag.messageText
             : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
-        // Find the relative path for the issue
-        let relPath = sourceFile.fileName;
-        for (const [rel, abs] of [...patchOwnedFiles].map((r) => [r, resolve(repoDir, r)])) {
-            if (abs === sourceFile.fileName) {
-                relPath = rel;
-                break;
-            }
-        }
         const severity = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
-        issues.push({
+        const bucket = byFile.get(relPath) ?? [];
+        bucket.push({
             file: relPath,
             check: 'checkjs-type-error',
             message: `Line ${line}: ${messageText}`,
             severity,
         });
+        byFile.set(relPath, bucket);
+    }
+    return byFile;
+}
+/**
+ * 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 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 async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode, reportScope) {
+    const { byFile, global } = await runCheckJsGrouped(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode);
+    const issues = [...global];
+    for (const [rel, list] of byFile) {
+        if (reportScope && !reportScope.has(rel))
+            continue;
+        issues.push(...list);
     }
-    verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s), found ${issues.length} issue(s)`);
     return issues;
 }
 /**
  * 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 async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint, projectRoot, reportScope) {
+    const strict = patchLint.checkJsStrict === true;
+    const mode = strict && patchLint.checkJsCompilerOptions
+        ? { strict, compilerOptions: patchLint.checkJsCompilerOptions }
+        : { strict };
+    return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode, reportScope);
+}
+/**
+ * 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 async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint, projectRoot) {
+export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot) {
     const strict = patchLint.checkJsStrict === true;
     const mode = strict && patchLint.checkJsCompilerOptions
         ? { strict, compilerOptions: patchLint.checkJsCompilerOptions }
         : { strict };
-    return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
+    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
 }
 //# sourceMappingURL=patch-lint-checkjs.js.map

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

@@ -180,6 +180,37 @@ export declare function findForwardImportIgnoreLines(source: string): Set<number
  *   engine file — not our concern).
  * - Imports on a line suppressed by the ignore marker.
  */
+/** One discovered forward-import edge: a site importing a later-created file. */
+export interface ForwardImportEdge {
+    /** Importing patch filename. */
+    entry: string;
+    /** Importing file path relative to engine/. */
+    sitePath: string;
+    /** Exact import specifier as it appears in source. */
+    specifier: string;
+    /** Specifier with any query/hash stripped (used for fingerprints). */
+    cleaned: string;
+    /** Later-ordered patch creating the imported file. */
+    owner: string;
+    /** Path of the later-created file (relative to engine/). */
+    creates: string;
+}
+/**
+ * Returns every forward-import edge in the queue, one per (site, later
+ * creator) pair, regardless of any staged-dependency declarations. Used by
+ * `patch split` to discover the forward edges it introduces into the new
+ * patch so it can auto-declare them (and so its projected lint matches the
+ * real per-patch gate).
+ */
+export declare function collectForwardImportEdges(ctx: PatchQueueContext): ForwardImportEdge[];
+/**
+ * Cross-patch lint rule: flag imports of a module a later-ordered patch is
+ * responsible for creating, unless the patch declares an exact staged
+ * forward-import for it. Also warns on staged-dependency declarations that
+ * never matched (stale). Matching is conservative — by basename, not by
+ * resolving `resource://`/`chrome://` URLs — with an inline ignore marker as
+ * an escape hatch for unrelated basename collisions.
+ */
 export declare function lintPatchQueueForwardImports(ctx: PatchQueueContext): PatchLintIssue[];
 /**
  * Cross-patch lint orchestrator. Runs every cross-patch rule against the