@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -3,17 +3,17 @@
  *
  * Loads the TypeScript compiler API via dynamic import so it is only
  * required when `patchLint.checkJs` is enabled in `fireforge.json`.
- * TypeScript remains a dev-dependency — if a user enables checkJs
+ * TypeScript remains a dev-dependency. If a user enables checkJs
  * without installing it, the pass emits a clear error explaining
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
  * diagnostic code list now live in `typecheck-shim.ts` and are shared
- * with the whole-project `fireforge typecheck` command — keeping a
+ * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
- * and optional allowlisted `checkJsCompilerOptions`; it does not change
+ * 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
@@ -26,57 +26,74 @@
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintCheckJsCompilerOptions, PatchLintConfig, PatchLintSeverityGate } from '../types/config.js';
-/** How a checkJs run controls reporting and resolution; see module docs. */
+/** How a checkJs run controls reporting and resolution. See module docs. */
 export interface CheckJsMode {
     strict: boolean;
     compilerOptions?: PatchLintCheckJsCompilerOptions;
     /**
      * How to report undefined free identifiers (TS2304/TS2552). Default
-     * 'warning' — see `patchLint.undefinedIdentifiers`.
+     * 'warning'. See `patchLint.undefinedIdentifiers`.
      */
     undefinedIdentifiers?: PatchLintSeverityGate;
 }
 /**
  * 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.
+ * 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[];
 }
+/** Inputs for {@link runCheckJsGrouped}. */
+export interface RunCheckJsGroupedInput {
+    /** Absolute engine (repository) directory. */
+    repoDir: string;
+    /**
+     * Patch-owned `.sys.mjs` paths (relative to `repoDir`) the program should
+     * see and resolve against.
+     */
+    resolutionOwned: Set<string>;
+    /**
+     * Optional project-relative extra `.d.ts` appended to the built-in
+     * Firefox-globals shim (from `patchLint.checkJsExtraShim`).
+     */
+    extraShimPath?: string;
+    /** Absolute project root for resolving `extraShimPath`. */
+    projectRoot?: string;
+    /** Strictness preset plus allowlisted compiler-option overrides. */
+    mode?: CheckJsMode;
+    /** Optional shim text appended after the consumer shim. */
+    builtinShimSuffix?: string;
+    /**
+     * When set, only these repo-relative files become program roots.
+     * Resolution (and the host allowlist) still spans all of
+     * `resolutionOwned`, so a subset root's cross-patch imports type-check
+     * against the real owning sources while unrelated owned files are never
+     * parsed. `.mjs` files are module-scoped, so a root's diagnostics are
+     * identical whether other owned files are roots or mere resolution
+     * targets.
+     */
+    rootScope?: ReadonlySet<string>;
+}
 /**
- * Builds the checkJs program **once** over `resolutionOwned` and returns its
+ * 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,
+ * 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
- * @param builtinShimSuffix - Optional shim text appended AFTER the consumer
- *   shim
- * @param rootScope - When set, only these repo-relative files become program
- *   ROOTS; resolution (and the host allowlist) still spans all of
- *   `resolutionOwned`, so a subset root's cross-patch imports type-check
- *   against the real owning sources while unrelated owned files are never
- *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
- *   identical whether other owned files are roots or mere resolution targets.
+ * @param input - Program inputs. See {@link RunCheckJsGroupedInput}
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, builtinShimSuffix?: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
+export declare function runCheckJsGrouped(input: RunCheckJsGroupedInput): Promise<GroupedCheckJsResult>;
 /**
  * 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.
+ * 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
@@ -103,15 +120,15 @@ export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>
 export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
 /**
  * Runs the checkJs pass over patch-owned test `.js` files (
- * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
- * program — mochitest scripts share top-level scope only with their
- * directory's `head*.js` helpers, so one multi-script program would emit
- * false cross-file redeclaration errors — with roots = the test file plus
- * any same-directory patch-owned `head*.js`, checked against the built-in
- * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
- * `checkJsTestShim`. Only the target file's diagnostics are reported per
- * program (head helpers report from their own program), and run-level
- * errors are de-duplicated across programs.
+ * `patchLint.checkJsTestFiles`). Each test file gets its own small
+ * program, with roots = the test file plus any same-directory patch-owned
+ * `head*.js`, checked against the built-in Firefox shim +
+ * {@link TEST_HARNESS_SHIM} + the optional consumer `checkJsTestShim`.
+ * Mochitest scripts share top-level scope only with their directory's
+ * `head*.js` helpers, so one multi-script program would emit false
+ * cross-file redeclaration errors. Only the target file's diagnostics are
+ * reported per program (head helpers report from their own program), and
+ * run-level errors are de-duplicated across programs.
  *
  * @param repoDir - Absolute engine (repository) directory
  * @param testFiles - Patch-owned test-script paths (repo-relative)
@@ -122,7 +139,7 @@ export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: S
 /**
  * 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**
+ * 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.
  *
@@ -131,12 +148,12 @@ export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: S
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  * @param rootScope - Optional subset of files to use as program roots
- * (`--patches`); resolution still spans the whole queue
+ * (`--patches`). Resolution still spans the whole queue
  */
 export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
  * Cheap probe reproducing the only run-level ("global") checkJs findings the
- * build path can produce — a missing `typescript` package and an unreadable
+ * build path can produce: a missing `typescript` package and an unreadable
  * consumer shim (`checkJsExtraShim`, and `checkJsTestShim` when
  * `checkJsTestFiles` is on). The built program itself never contributes
  * globals (see {@link runCheckJsGrouped}), so a warm all-cache-hit run can

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

@@ -4,17 +4,17 @@
  *
  * Loads the TypeScript compiler API via dynamic import so it is only
  * required when `patchLint.checkJs` is enabled in `fireforge.json`.
- * TypeScript remains a dev-dependency — if a user enables checkJs
+ * TypeScript remains a dev-dependency. If a user enables checkJs
  * without installing it, the pass emits a clear error explaining
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget. The shim itself and the suppressed
  * diagnostic code list now live in `typecheck-shim.ts` and are shared
- * with the whole-project `fireforge typecheck` command — keeping a
+ * with the whole-project `fireforge typecheck` command, keeping a
  * single source of truth for the Firefox-globals coverage.
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
- * and optional allowlisted `checkJsCompilerOptions`; it does not change
+ * 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
@@ -39,11 +39,12 @@ import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HAR
  * Converts a native path into the form TypeScript uses for `fileName`.
  *
  * TypeScript normalizes every path it hands a `CompilerHost` to forward
- * slashes on ALL platforms, while `resolve()` here yields the platform
+ * slashes on all platforms, while `resolve()` here yields the platform
  * separator. On Windows that mismatch made every `ownedAbsolute.has(fileName)`
  * and `relByAbsolute.get(fileName)` lookup miss, so the host served an empty
- * source file for each owned file and the whole pass reported zero findings —
- * silently, because "no diagnostics" is indistinguishable from "clean code".
+ * source file for each owned file and the whole pass reported zero findings.
+ * It did so silently, because "no diagnostics" is indistinguishable from
+ * "clean code".
  * Every path that crosses the TS boundary goes through here.
  */
 function toTsPath(path) {
@@ -55,8 +56,8 @@ function toTsPath(path) {
  * 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
+ * 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) {
@@ -105,8 +106,8 @@ function extensionForFile(ts, file) {
 }
 /**
  * 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
+ * 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
@@ -134,7 +135,7 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
             }
             for (const target of targets) {
                 // A `paths` target carries at most one `*`, and TypeScript substitutes
-                // that one wildcard — spelled as index arithmetic (mirroring the
+                // that one wildcard. It is spelled as index arithmetic (mirroring the
                 // prefix/suffix split on the pattern side above) rather than
                 // `replace('*', …)`, whose first-occurrence-only behaviour reads as an
                 // incomplete rewrite (CodeQL `js/incomplete-sanitization`).
@@ -155,35 +156,22 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
     };
 }
 /**
- * Builds the checkJs program **once** over `resolutionOwned` and returns its
+ * 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,
+ * 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
- * @param builtinShimSuffix - Optional shim text appended AFTER the consumer
- *   shim
- * @param rootScope - When set, only these repo-relative files become program
- *   ROOTS; resolution (and the host allowlist) still spans all of
- *   `resolutionOwned`, so a subset root's cross-patch imports type-check
- *   against the real owning sources while unrelated owned files are never
- *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
- *   identical whether other owned files are roots or mere resolution targets.
+ * @param input - Program inputs. See {@link RunCheckJsGroupedInput}
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode, builtinShimSuffix, rootScope) {
+export async function runCheckJsGrouped(input) {
+    const { repoDir, resolutionOwned, extraShimPath, rootScope } = input;
     const empty = { byFile: new Map(), global: [] };
     if (resolutionOwned.size === 0)
         return empty;
-    // Dynamic import — typescript stays as a dev dependency
+    // Dynamic import: typescript stays as a dev dependency
     let ts;
     try {
         ts = await import('typescript');
@@ -204,7 +192,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     }
     // Resolve absolute paths for root files, filtering to files that exist.
     // Under a rootScope, non-scoped owned files stay resolvable (host
-    // allowlist + relByAbsolute) but are not program roots — they are only
+    // allowlist + relByAbsolute) but are not program roots. They are only
     // parsed if a scoped root's import closure reaches them.
     const rootFiles = [];
     const ownedAbsolute = new Set();
@@ -221,18 +209,20 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     if (rootFiles.length === 0)
         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
+    // by config-validate). Resolve it against `projectRoot`. When the
+    // caller passes neither, fall back to `repoDir`. The only way the
     // shim path is ever read in that case is when extraShimPath is
     // also undefined, so the resolution target is irrelevant.
     let shimSource;
     try {
-        const composed = await composeShimSource(projectRoot ?? repoDir, extraShimPath);
+        const composed = await composeShimSource(input.projectRoot ?? repoDir, extraShimPath);
         // The suffix (e.g. the loose test-harness baseline) goes
-        // AFTER the consumer's extra shim: TypeScript resolves conflicting
-        // `declare var` redeclarations to the FIRST declaration, so a typed
+        // after the consumer's extra shim: TypeScript resolves conflicting
+        // `declare var` redeclarations to the first declaration, so a typed
         // consumer declaration must precede the loose fallback to win.
-        shimSource = builtinShimSuffix ? `${composed.source}\n${builtinShimSuffix}` : composed.source;
+        shimSource = input.builtinShimSuffix
+            ? `${composed.source}\n${input.builtinShimSuffix}`
+            : composed.source;
         if (composed.extraShimAppended) {
             verbose(`checkJs: extra shim ${extraShimPath ?? ''} appended to Firefox globals shim`);
         }
@@ -252,21 +242,21 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     }
     const shimPath = toTsPath(resolve(repoDir, SHIM_FILENAME));
     rootFiles.push(shimPath);
-    const strict = mode?.strict === true;
+    const strict = input.mode?.strict === true;
     const strictness = strict
         ? { strict: true, noImplicitAny: true }
         : {
-            // Loose default — implicit `any` is allowed unless `patchLint.checkJsStrict`.
+            // Loose default: implicit `any` is allowed unless `patchLint.checkJsStrict`.
             strict: false,
             noImplicitAny: false,
         };
-    // Allowlisted overrides. Booleans merge directly; a reviewed `paths`
-    // mapping is applied to the compiler options AND wired into the host
+    // 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;
+    const co = input.mode?.compilerOptions;
     if (co) {
         for (const key of Object.keys(co)) {
             const v = co[key];
@@ -292,10 +282,10 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
         // 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
+        // survive the module boundary. Everything else is left to fail
         // 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
+        // host resolver is authoritative: TS never crawls the Firefox
         // tree looking for upstream modules.
         ...strictness,
         ...overrides,
@@ -305,7 +295,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     // 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
+    // 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
@@ -351,7 +341,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
         },
     };
     const program = ts.createProgram(rootFiles, options, host);
-    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute, mode?.undefinedIdentifiers ?? 'warning');
+    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute, input.mode?.undefinedIdentifiers ?? 'warning');
     verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s) across ${byFile.size} owning file(s)`);
     return { byFile, global: [] };
 }
@@ -359,7 +349,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
  * 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
+ * or shim files are dropped. Only owned files (in `relByAbsolute`) carry
  * findings.
  */
 function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifiers = 'warning') {
@@ -404,8 +394,8 @@ function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifi
 /**
  * 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.
+ * 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
@@ -417,7 +407,13 @@ function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifi
  * @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 { byFile, global } = await runCheckJsGrouped({
+        repoDir,
+        resolutionOwned: patchOwnedFiles,
+        ...(extraShimPath !== undefined ? { extraShimPath } : {}),
+        ...(projectRoot !== undefined ? { projectRoot } : {}),
+        ...(mode !== undefined ? { mode } : {}),
+    });
     const issues = [...global];
     for (const [rel, list] of byFile) {
         if (reportScope && !reportScope.has(rel))
@@ -443,15 +439,15 @@ export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint
 }
 /**
  * Runs the checkJs pass over patch-owned test `.js` files (
- * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
- * program — mochitest scripts share top-level scope only with their
- * directory's `head*.js` helpers, so one multi-script program would emit
- * false cross-file redeclaration errors — with roots = the test file plus
- * any same-directory patch-owned `head*.js`, checked against the built-in
- * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
- * `checkJsTestShim`. Only the target file's diagnostics are reported per
- * program (head helpers report from their own program), and run-level
- * errors are de-duplicated across programs.
+ * `patchLint.checkJsTestFiles`). Each test file gets its own small
+ * program, with roots = the test file plus any same-directory patch-owned
+ * `head*.js`, checked against the built-in Firefox shim +
+ * {@link TEST_HARNESS_SHIM} + the optional consumer `checkJsTestShim`.
+ * Mochitest scripts share top-level scope only with their directory's
+ * `head*.js` helpers, so one multi-script program would emit false
+ * cross-file redeclaration errors. Only the target file's diagnostics are
+ * reported per program (head helpers report from their own program), and
+ * run-level errors are de-duplicated across programs.
  *
  * @param repoDir - Absolute engine (repository) directory
  * @param testFiles - Patch-owned test-script paths (repo-relative)
@@ -482,7 +478,16 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
                 roots.add(candidate);
             }
         }
-        const result = await runCheckJsGrouped(repoDir, roots, patchLint.checkJsTestShim, projectRoot, mode, TEST_HARNESS_SHIM);
+        const result = await runCheckJsGrouped({
+            repoDir,
+            resolutionOwned: roots,
+            ...(patchLint.checkJsTestShim !== undefined
+                ? { extraShimPath: patchLint.checkJsTestShim }
+                : {}),
+            projectRoot,
+            mode,
+            builtinShimSuffix: TEST_HARNESS_SHIM,
+        });
         const own = result.byFile.get(file);
         if (own && own.length > 0) {
             merged.byFile.set(file, [
@@ -515,7 +520,7 @@ function modeFromPatchLintConfig(patchLint) {
 /**
  * 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**
+ * 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.
  *
@@ -524,14 +529,23 @@ function modeFromPatchLintConfig(patchLint) {
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
  * @param rootScope - Optional subset of files to use as program roots
- * (`--patches`); resolution still spans the whole queue
+ * (`--patches`). Resolution still spans the whole queue
  */
 export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot, rootScope) {
-    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), undefined, rootScope);
+    return runCheckJsGrouped({
+        repoDir,
+        resolutionOwned: patchOwnedFiles,
+        ...(patchLint.checkJsExtraShim !== undefined
+            ? { extraShimPath: patchLint.checkJsExtraShim }
+            : {}),
+        projectRoot,
+        mode: modeFromPatchLintConfig(patchLint),
+        ...(rootScope !== undefined ? { rootScope } : {}),
+    });
 }
 /**
  * Cheap probe reproducing the only run-level ("global") checkJs findings the
- * build path can produce — a missing `typescript` package and an unreadable
+ * build path can produce: a missing `typescript` package and an unreadable
  * consumer shim (`checkJsExtraShim`, and `checkJsTestShim` when
  * `checkJsTestFiles` is on). The built program itself never contributes
  * globals (see {@link runCheckJsGrouped}), so a warm all-cache-hit run can

package/dist/src/core/patch-lint-chrome-jsdoc.d.ts

@@ -4,30 +4,29 @@
  * `.js` files loaded via `Services.scriptloader.loadSubScript`).
  *
  * Why a separate module from {@link ./patch-lint-jsdoc.ts}: chrome
- * subscripts are NOT ES modules. They are parsed as scripts (no static
+ * subscripts are not ES modules. They are parsed as scripts (no static
  * `export`) and their top-level `class`/`function` declarations are
  * exposed to the loading window as globals rather than declared exports.
  * The export-walker in `patch-lint-jsdoc.ts` would never visit them.
  *
- * The rule shape — "every top-level class needs a JSDoc, every method
- * needs one when `chromeScriptJsDoc` is at `warning`/`error`, every
- * top-level function needs a matching @param/@returns block" — is
- * identical to the `.sys.mjs` rule once you remove the `export` framing,
- * so the per-declaration validators are reused verbatim from the export
- * module.
+ * The rule shape is identical to the `.sys.mjs` rule once you remove the
+ * `export` framing: every top-level class needs a JSDoc, every method
+ * needs one when `chromeScriptJsDoc` is at `warning`/`error`, and every
+ * top-level function needs a matching @param/@returns block. So the
+ * per-declaration validators are reused verbatim from the export module.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintSeverityGate } from '../types/config.js';
 import type { JsDocIssue, ValidateExportJsDocOptions } from './patch-lint-jsdoc.js';
 /**
  * Validates JSDoc on top-level declarations in a chrome-subscript `.js`
- * source file. A parse failure returns an empty issue list — chrome
+ * source file. A parse failure returns an empty issue list. Chrome
  * subscripts that use module-only syntax (rare) silently disable the
  * rule rather than emitting confusing parse-error issues.
  *
  * @param source - File content
  * @param options - Optional gates (e.g. class-method JSDoc severity).
- *   `classMethodMode` defaults to `'off'` — the orchestrator passes the
+ *   `classMethodMode` defaults to `'off'`. The orchestrator passes the
  *   `chromeScriptJsDoc` severity here so a single knob controls both
  *   class-level and method-level enforcement.
  * @returns Array of JSDoc issues found

package/dist/src/core/patch-lint-chrome-jsdoc.js

@@ -5,29 +5,28 @@
  * `.js` files loaded via `Services.scriptloader.loadSubScript`).
  *
  * Why a separate module from {@link ./patch-lint-jsdoc.ts}: chrome
- * subscripts are NOT ES modules. They are parsed as scripts (no static
+ * subscripts are not ES modules. They are parsed as scripts (no static
  * `export`) and their top-level `class`/`function` declarations are
  * exposed to the loading window as globals rather than declared exports.
  * The export-walker in `patch-lint-jsdoc.ts` would never visit them.
  *
- * The rule shape — "every top-level class needs a JSDoc, every method
- * needs one when `chromeScriptJsDoc` is at `warning`/`error`, every
- * top-level function needs a matching @param/@returns block" — is
- * identical to the `.sys.mjs` rule once you remove the `export` framing,
- * so the per-declaration validators are reused verbatim from the export
- * module.
+ * The rule shape is identical to the `.sys.mjs` rule once you remove the
+ * `export` framing: every top-level class needs a JSDoc, every method
+ * needs one when `chromeScriptJsDoc` is at `warning`/`error`, and every
+ * top-level function needs a matching @param/@returns block. So the
+ * per-declaration validators are reused verbatim from the export module.
  */
 import { parseScript } from './ast-utils.js';
 import { validateClassDecl, validateClassMethods, validateFunctionDecl, } from './patch-lint-jsdoc.js';
 /**
  * Validates JSDoc on top-level declarations in a chrome-subscript `.js`
- * source file. A parse failure returns an empty issue list — chrome
+ * source file. A parse failure returns an empty issue list. Chrome
  * subscripts that use module-only syntax (rare) silently disable the
  * rule rather than emitting confusing parse-error issues.
  *
  * @param source - File content
  * @param options - Optional gates (e.g. class-method JSDoc severity).
- *   `classMethodMode` defaults to `'off'` — the orchestrator passes the
+ *   `classMethodMode` defaults to `'off'`. The orchestrator passes the
  *   `chromeScriptJsDoc` severity here so a single knob controls both
  *   class-level and method-level enforcement.
  * @returns Array of JSDoc issues found
@@ -43,7 +42,7 @@ export function validateChromeScriptJsDoc(source, options) {
         // Deliberate carve-out, unlike the `.sys.mjs` walker in
         // `patch-lint-jsdoc.ts` (which reports a parse failure as an issue).
         // `parseScript` rejects `import`/`export`, so a chrome subscript that was
-        // misclassified as a `.js` file — or that mistakenly uses module syntax —
+        // misclassified as a `.js` file (or that mistakenly uses module syntax)
         // would emit a pseudo-issue for every rule here. The orchestrator already
         // runs the export walker on `.sys.mjs` separately, so silently declining
         // to lint an unparseable script is the correct degradation for this file
@@ -63,7 +62,7 @@ export function validateChromeScriptJsDoc(source, options) {
             }
         }
         // Top-level `var Foo = class {...}` / `let Foo = function() {...}`
-        // patterns are intentionally out of scope for V1 — chrome subscripts
+        // patterns are out of scope for V1: chrome subscripts
         // overwhelmingly use bare `class`/`function` declarations and the
         // variable-init form would require unwrapping the initializer. Add
         // it later if a real chrome subscript uses that shape.

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

@@ -6,17 +6,13 @@
  *
  * Memoised per context object: ownership resolution and cache-key
  * fingerprints call this 2-3× per linted patch, and each call otherwise
- * re-runs `detectNewFilesInDiff` over EVERY queue entry's diff. Keyed weakly
- * so a discarded context frees its map; a caller that mutates a context
+ * re-runs `detectNewFilesInDiff` over every queue entry's diff. Keyed weakly
+ * so a discarded context frees its map. A caller that mutates a context
  * entry in place must call {@link invalidateNewFileCreatorsCache}.
  */
+import type { PatchQueueBodyEntry, PatchQueueView } from './patch-lint-queue-types.js';
 /** The slice of a queue context the creators map is derived from. */
-interface CreatorsContext {
-    entries: {
-        filename: string;
-        diff: string;
-    }[];
-}
+type CreatorsContext = PatchQueueView<PatchQueueBodyEntry>;
 /** Drops the memoised creators map after an in-place context entry update. */
 export declare function invalidateNewFileCreatorsCache(ctx: CreatorsContext): void;
 /**
@@ -24,7 +20,7 @@ export declare function invalidateNewFileCreatorsCache(ctx: CreatorsContext): vo
  * mode` by at least one patch in the queue. Paths created by only one
  * patch are also included so callers can distinguish "no creator" from
  * "exactly one creator" without re-scanning the diffs. The returned map
- * is memoised and shared — treat it as read-only.
+ * is memoised and shared, so treat it as read-only.
  */
 export declare function collectNewFileCreatorsByPath(ctx: CreatorsContext): Map<string, string[]>;
 export {};

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

@@ -7,8 +7,8 @@
  *
  * Memoised per context object: ownership resolution and cache-key
  * fingerprints call this 2-3× per linted patch, and each call otherwise
- * re-runs `detectNewFilesInDiff` over EVERY queue entry's diff. Keyed weakly
- * so a discarded context frees its map; a caller that mutates a context
+ * re-runs `detectNewFilesInDiff` over every queue entry's diff. Keyed weakly
+ * so a discarded context frees its map. A caller that mutates a context
  * entry in place must call {@link invalidateNewFileCreatorsCache}.
  */
 import { detectNewFilesInDiff } from './patch-lint-diff.js';
@@ -22,7 +22,7 @@ export function invalidateNewFileCreatorsCache(ctx) {
  * mode` by at least one patch in the queue. Paths created by only one
  * patch are also included so callers can distinguish "no creator" from
  * "exactly one creator" without re-scanning the diffs. The returned map
- * is memoised and shared — treat it as read-only.
+ * is memoised and shared, so treat it as read-only.
  */
 export function collectNewFileCreatorsByPath(ctx) {
     const memoised = newFileCreatorsMemo.get(ctx);