@hominis/fireforge 0.30.1 → 0.32.0

package/dist/src/core/mach.js

@@ -312,8 +312,33 @@ export async function test(engineDir, testPaths = [], args = []) {
 }
 /**
  * Runs mach test while capturing streamed output for better diagnostics.
+ *
+ * @param env - Optional extra environment variables for the mach process
+ *   (merged over `process.env` by the exec layer). Used by
+ *   `fireforge test --perf-samples` to publish the artifact-path contract.
+ */
+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 testWithOutput(engineDir, testPaths = [], args = []) {
-    return runMachCapture(['test', ...testPaths, ...args], engineDir);
+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-register.d.ts

@@ -1,22 +1,11 @@
 /**
  * Manifest registration barrel — re-exports all registration targets
- * and provides the shared RegisterResult interface.
+ * and the shared RegisterResult interface (which lives in
+ * `register-result.ts` so the leaf modules can import it without
+ * creating a cycle through this barrel).
  */
-/**
- * Result of a manifest registration operation.
- */
-export interface RegisterResult {
-    /** The manifest file that was modified */
-    manifest: string;
-    /** The entry that was inserted */
-    entry: string;
-    /** The entry after which the new entry was inserted (for user display) */
-    previousEntry?: string | undefined;
-    /** Whether the entry already existed (skipped) */
-    skipped: boolean;
-    /** Whether --after target was not found and fell back to alphabetical */
-    afterFallback?: boolean | undefined;
-}
+import type { RegisterResult } from './register-result.js';
+export type { RegisterResult } from './register-result.js';
 export { registerBrowserContent } from './register-browser-content.js';
 export { registerFireForgeModule } from './register-module.js';
 export { registerSharedCSS } from './register-shared-css.js';

package/dist/src/core/manifest-register.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Manifest registration barrel — re-exports all registration targets
- * and provides the shared RegisterResult interface.
+ * and the shared RegisterResult interface (which lives in
+ * `register-result.ts` so the leaf modules can import it without
+ * creating a cycle through this barrel).
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';

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,8 +16,16 @@
  * `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 { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from './typecheck-shim.js';
@@ -25,56 +33,158 @@ import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from '.
 // Public API
 // ---------------------------------------------------------------------------
 /**
- * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
+ * Builds the host-side module resolver for the checkJs pass: maps an import
+ * specifier to a patch-owned absolute path when the specifier's final
+ * segment uniquely matches an owned file. URL specifiers
+ * (chrome://browser/content/Foo.sys.mjs, resource:///modules/Foo.sys.mjs)
+ * are matched by basename, with a `.mjs` → `.sys.mjs` fallback for deployed
+ * widget URLs. Ambiguous or unknown basenames stay unresolved — loose
+ * wildcard typing beats guessing the wrong module — and relative specifiers
+ * are left to fail resolution (the relative-import lint rule bans them).
+ */
+function createOwnedSpecifierResolver(ts, ownedAbsolute) {
+    const ownedByBasename = new Map();
+    for (const abs of ownedAbsolute) {
+        const base = basename(abs);
+        const list = ownedByBasename.get(base) ?? [];
+        list.push(abs);
+        ownedByBasename.set(base, list);
+    }
+    return (specifier) => {
+        if (specifier.startsWith('.'))
+            return undefined;
+        const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
+        const segment = cleaned.slice(cleaned.lastIndexOf('/') + 1);
+        if (!segment)
+            return undefined;
+        const candidates = [...(ownedByBasename.get(segment) ?? [])];
+        if (segment.endsWith('.mjs') && !segment.endsWith('.sys.mjs')) {
+            candidates.push(...(ownedByBasename.get(segment.replace(/\.mjs$/, '.sys.mjs')) ?? []));
+        }
+        if (candidates.length !== 1)
+            return undefined;
+        return {
+            resolvedFileName: candidates[0],
+            extension: ts.Extension.Mjs,
+            isExternalLibraryImport: false,
+        };
+    };
+}
+/** 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;
+}
+/**
+ * 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
@@ -89,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);
@@ -108,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;
             }
         }
@@ -126,26 +250,35 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
         module: ts.ModuleKind.ESNext,
         moduleResolution: ts.ModuleResolutionKind.Bundler,
         skipLibCheck: true,
-        // Do not follow import/reference directives into the Firefox tree.
-        // We only want to check the patch-owned files themselves.
-        // Without this, TS would try (and fail) to resolve every
-        // resource:// and chrome:// import, flooding the output with
-        // "Cannot find module" errors for upstream Firefox modules.
-        noResolve: true,
+        // Module resolution is host-controlled (see resolveOwnedSpecifier
+        // below): imports that match a patch-owned file resolve to the real
+        // source so JSDoc type-guard predicates and @template generics
+        // survive the module boundary; everything else deliberately fails
+        // resolution, falling back to the chrome:*/resource:* ambient
+        // wildcards plus the suppressed "cannot find module" codes. The
+        // host resolver is authoritative — TS never crawls the Firefox
+        // tree looking for upstream modules.
         ...strictness,
         ...overrides,
     };
+    const resolveOwnedSpecifier = createOwnedSpecifierResolver(ts, ownedAbsolute);
     // Custom compiler host: reads patch-owned files from disk, returns
     // 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
@@ -160,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);
         },
@@ -169,57 +302,116 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
                 return shimSource;
             return defaultHost.readFile(fileName);
         },
+        resolveModuleNameLiterals(moduleLiterals) {
+            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