@hominis/fireforge 0.18.10 → 0.19.0

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

@@ -8,14 +8,42 @@
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
- * project's per-file line budget.
+ * 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
+ * single source of truth for the Firefox-globals coverage.
+ * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
+ * and optional allowlisted `checkJsCompilerOptions`; it does not change
+ * shim composition or suppressed diagnostic codes.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
+import type { PatchLintCheckJsCompilerOptions, PatchLintConfig } from '../types/config.js';
 /**
  * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
  *
  * @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
  */
-export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>): Promise<PatchLintIssue[]>;
+export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: {
+    strict: boolean;
+    compilerOptions?: PatchLintCheckJsCompilerOptions;
+}): Promise<PatchLintIssue[]>;
+/**
+ * Invokes {@link runCheckJs} for a `patchLint` block with `checkJs: true`.
+ * `projectRoot` is the FireForge project root (`dirname(engine)`).
+ */
+export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<PatchLintIssue[]>;

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

@@ -9,80 +9,18 @@
  * how to fix it.
  *
  * Separated from `patch-lint.ts` to keep both files within the
- * project's per-file line budget.
+ * 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
+ * single source of truth for the Firefox-globals coverage.
+ * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
+ * and optional allowlisted `checkJsCompilerOptions`; it does not change
+ * shim composition or suppressed diagnostic codes.
  */
 import { resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-// ---------------------------------------------------------------------------
-// Firefox globals shim
-// ---------------------------------------------------------------------------
-const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
-/**
- * Minimal `.d.ts` shim for Firefox privileged-scope globals.
- *
- * Firefox source is plain JS — no TypeScript allowed. The shim lets
- * `checkJs` run without reporting "cannot find name" for the most
- * common Mozilla APIs. Types are intentionally loose (`any`) because
- * full Firefox type coverage is out of scope.
- *
- * Notable patterns that require shimming:
- * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
- *   populates `lazy` at runtime; we declare it as `Record<string, any>`.
- * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
- * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
- * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
- *   content scripts wired via `browser.js`.
- */
-const FIREFOX_GLOBALS_SHIM = `
-declare var Services: any;
-declare var ChromeUtils: {
-  defineESModuleGetters(target: any, modules: Record<string, string>): void;
-  importESModule(specifier: string): any;
-  import(specifier: string): any;
-  defineModuleGetter(target: any, name: string, specifier: string): void;
-  generateQI(interfaces: any[]): Function;
-  isClassInfo(obj: any): boolean;
-};
-declare var Cu: any;
-declare var Ci: any;
-declare var Cc: any;
-declare var Cr: any;
-declare var Components: any;
-declare var XPCOMUtils: any;
-declare var lazy: Record<string, any>;
-declare var PathUtils: any;
-declare var IOUtils: any;
-declare var FileUtils: any;
-declare var gBrowser: any;
-declare var gURLBar: any;
-declare var gNavigatorBundle: any;
-declare var AppConstants: any;
-`;
-// ---------------------------------------------------------------------------
-// Diagnostic filtering
-// ---------------------------------------------------------------------------
-/**
- * TS diagnostic codes to suppress because they are inherent to
- * checking Firefox JS files outside of Mozilla's own build system.
- *
- * Firefox uses `resource://` and `chrome://` URL schemes for module
- * imports. TypeScript's module resolver cannot follow these, so every
- * import from an upstream Firefox module produces a spurious
- * "Cannot find module" error. Filtering these out is essential to
- * keep the checkJs pass usable — otherwise every file with an import
- * would be buried in false positives.
- */
-const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
-    2307, // Cannot find module '{0}' or its corresponding type declarations.
-    2306, // File '{0}' is not a module.
-    2305, // Module '{0}' has no exported member '{1}'.
-    2792, // Cannot find module '{0}'. Did you mean to set the 'moduleResolution' option...
-    2304, // Cannot find name '{0}'. (for globals we missed in the shim)
-    2552, // Cannot find name '{0}'. Did you mean '{1}'?
-    2580, // Cannot find name '{0}'. Do you need to install type definitions...
-    7016, // Could not find a declaration file for module '{0}'.
-]);
+import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -91,9 +29,22 @@ const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
  *
  * @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
  */
-export async function runCheckJs(repoDir, patchOwnedFiles) {
+export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode) {
     if (patchOwnedFiles.size === 0)
         return [];
     // Dynamic import — typescript stays as a dev dependency
@@ -124,13 +75,53 @@ export async function runCheckJs(repoDir, patchOwnedFiles) {
     }
     if (rootFiles.length === 0)
         return [];
+    // 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
+    // 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);
+        shimSource = composed.source;
+        if (composed.extraShimAppended) {
+            verbose(`checkJs: extra shim ${extraShimPath ?? ''} appended to Firefox globals shim`);
+        }
+    }
+    catch (err) {
+        return [
+            {
+                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);
+    const strict = mode?.strict === true;
+    const strictness = strict
+        ? { strict: true, noImplicitAny: true }
+        : {
+            // Loose default — implicit `any` is allowed unless `patchLint.checkJsStrict`.
+            strict: false,
+            noImplicitAny: false,
+        };
+    const overrides = {};
+    const co = mode?.compilerOptions;
+    if (co) {
+        for (const key of Object.keys(co)) {
+            const v = co[key];
+            if (v !== undefined) {
+                overrides[key] = v;
+            }
+        }
+    }
     const options = {
         allowJs: true,
         checkJs: true,
         noEmit: true,
-        strict: false,
         target: ts.ScriptTarget.ESNext,
         module: ts.ModuleKind.ESNext,
         moduleResolution: ts.ModuleResolutionKind.Bundler,
@@ -141,10 +132,8 @@ export async function runCheckJs(repoDir, patchOwnedFiles) {
         // resource:// and chrome:// import, flooding the output with
         // "Cannot find module" errors for upstream Firefox modules.
         noResolve: true,
-        // Suppress implicit-any noise — Firefox code rarely has full type
-        // annotations and drowning users in thousands of implicit-any
-        // errors defeats the purpose of a focused check.
-        noImplicitAny: false,
+        ...strictness,
+        ...overrides,
     };
     // Custom compiler host: reads patch-owned files from disk, returns
     // the shim for the shim path, and returns empty content for
@@ -154,7 +143,7 @@ export async function runCheckJs(repoDir, patchOwnedFiles) {
         ...defaultHost,
         getSourceFile(fileName, languageVersion, onError) {
             if (fileName === shimPath) {
-                return ts.createSourceFile(fileName, FIREFOX_GLOBALS_SHIM, languageVersion, true);
+                return ts.createSourceFile(fileName, shimSource, languageVersion, true);
             }
             if (ownedAbsolute.has(fileName)) {
                 return defaultHost.getSourceFile(fileName, languageVersion, onError);
@@ -177,7 +166,7 @@ export async function runCheckJs(repoDir, patchOwnedFiles) {
         },
         readFile(fileName) {
             if (fileName === shimPath)
-                return FIREFOX_GLOBALS_SHIM;
+                return shimSource;
             return defaultHost.readFile(fileName);
         },
     };
@@ -222,4 +211,15 @@ export async function runCheckJs(repoDir, patchOwnedFiles) {
     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)`).
+ */
+export async function invokePatchLintCheckJs(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);
+}
 //# sourceMappingURL=patch-lint-checkjs.js.map

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

@@ -0,0 +1,9 @@
+/**
+ * Public re-exports for {@link ./patch-lint.ts}. Split out so the
+ * orchestrator stays within the ESLint `max-lines` budget.
+ */
+export { runCheckJs } from './patch-lint-checkjs.js';
+export { buildPatchQueueContext, collectNewFileCreatorsByPath, type ExtractedSpecifier, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
+export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
+export { type JsDocCheck, type JsDocIssue, validateExportJsDoc } from './patch-lint-jsdoc.js';
+export { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';

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

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Public re-exports for {@link ./patch-lint.ts}. Split out so the
+ * orchestrator stays within the ESLint `max-lines` budget.
+ */
+export { runCheckJs } from './patch-lint-checkjs.js';
+export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
+export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
+export { validateExportJsDoc } from './patch-lint-jsdoc.js';
+export { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+//# sourceMappingURL=patch-lint-reexports.js.map

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

@@ -1,11 +1,7 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
-export { runCheckJs } from './patch-lint-checkjs.js';
-export { buildPatchQueueContext, collectNewFileCreatorsByPath, type ExtractedSpecifier, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
-export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
-export { type JsDocCheck, type JsDocIssue, validateExportJsDoc } from './patch-lint-jsdoc.js';
-export { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+export * from './patch-lint-reexports.js';
 /**
  * Counts the total lines in a unified diff and the number of non-binary
  * text lines, so binary hunks do not inflate patch size checks.

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

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { hasRawCssColors, stripJsComments } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
-import { runCheckJs } from './patch-lint-checkjs.js';
+import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
@@ -20,12 +20,9 @@ import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch
 // creation and forward-import rules, ignore marker) lives in
 // `patch-lint-cross.ts` so the per-patch and cross-patch rule bodies can
 // each stay within the project's per-file line budget. Re-export the
-// public surface so callers continue to import from a single module.
-export { runCheckJs } from './patch-lint-checkjs.js';
-export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
-export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
-export { validateExportJsDoc } from './patch-lint-jsdoc.js';
-export { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+// public surface from `patch-lint-reexports.ts` so callers continue to
+// import from a single module.
+export * from './patch-lint-reexports.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -737,10 +734,8 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...jsIssues,
         ...modCommentIssues,
     ];
-    // Optional checkJs pass — only when explicitly enabled in config
     if (config.patchLint?.checkJs) {
-        const checkJsIssues = await runCheckJs(repoDir, patchOwnedFiles);
-        issues.push(...checkJsIssues);
+        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir))));
     }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not

package/dist/src/core/typecheck-shim.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared TypeScript-checking constants used by both the patch-lint
+ * `checkJs` pass (`patch-lint-checkjs.ts`) and the whole-project
+ * `fireforge typecheck` command (`typecheck.ts`).
+ *
+ * Centralised so both flows agree on the same Firefox-globals shim
+ * and the same set of suppressed diagnostic codes — drift between the
+ * two would mean a patch could lint clean under `fireforge lint` but
+ * still fail `fireforge typecheck`, or vice versa, for reasons the
+ * operator could not infer from the rule names.
+ */
+/** Filename used for the synthetic Firefox-globals shim source file. */
+export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
+/**
+ * Minimal `.d.ts` shim for Firefox privileged-scope globals.
+ *
+ * Firefox source is plain JS — no TypeScript allowed. The shim lets
+ * TS-driven type checking run without reporting "cannot find name"
+ * for the most common Mozilla APIs. Types are intentionally loose
+ * (`any`) because full Firefox type coverage is out of scope.
+ *
+ * Notable patterns that require shimming:
+ * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
+ *   populates `lazy` at runtime; we declare it as `Record<string, any>`.
+ * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
+ * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
+ * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
+ *   content scripts wired via `browser.js`.
+ */
+export declare const FIREFOX_GLOBALS_SHIM = "\ndeclare var Services: any;\ndeclare var ChromeUtils: {\n  defineESModuleGetters(target: any, modules: Record<string, string>): void;\n  importESModule(specifier: string): any;\n  import(specifier: string): any;\n  defineModuleGetter(target: any, name: string, specifier: string): void;\n  generateQI(interfaces: any[]): Function;\n  isClassInfo(obj: any): boolean;\n};\ndeclare var Cu: any;\ndeclare var Ci: any;\ndeclare var Cc: any;\ndeclare var Cr: any;\ndeclare var Components: any;\ndeclare var XPCOMUtils: any;\ndeclare var lazy: Record<string, any>;\ndeclare var PathUtils: any;\ndeclare var IOUtils: any;\ndeclare var FileUtils: any;\ndeclare var gBrowser: any;\ndeclare var gURLBar: any;\ndeclare var gNavigatorBundle: any;\ndeclare var AppConstants: any;\n";
+/**
+ * TS diagnostic codes suppressed by both the patch-lint checkJs pass
+ * and the whole-project typecheck command. Each is a known false
+ * positive that arises from checking Firefox JS outside Mozilla's own
+ * build system: the resolver can't follow `resource://`/`chrome://`
+ * URLs and the global shim is intentionally narrow.
+ *
+ * Widening this set should be deliberate and per-code — silently
+ * suppressing more codes hides real type errors. The same set is used
+ * by both flows so a patch can't pass one and fail the other for a
+ * reason the operator couldn't infer from the docs.
+ */
+export declare const SUPPRESSED_DIAGNOSTIC_CODES: ReadonlySet<number>;
+/**
+ * Result of {@link composeShimSource}: the source body to feed into
+ * the TS host plus a flag indicating whether the user-supplied extra
+ * shim was actually appended (used for verbose logging).
+ */
+export interface ComposedShim {
+    source: string;
+    extraShimAppended: boolean;
+}
+/**
+ * Composes the synthetic shim source by concatenating the built-in
+ * Firefox globals shim with the contents of an optional user-supplied
+ * `.d.ts` file. The user file is appended verbatim — the augment
+ * direction is intentional (declarations later in concat order
+ * augment earlier ones), so a project that wants to refine `Services`
+ * with a more specific type can do so by declaring it in the extra
+ * shim.
+ *
+ * Missing extra-shim files raise a clear error rather than failing
+ * silently with a confusing "type not found" downstream — this is the
+ * one config-driven path where a user typo in `fireforge.json`
+ * produces a runtime error, so it needs to be unmistakable.
+ *
+ * @param projectRoot - Absolute project root, used to resolve the relative shim path
+ * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
+ */
+export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined): Promise<ComposedShim>;

package/dist/src/core/typecheck-shim.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared TypeScript-checking constants used by both the patch-lint
+ * `checkJs` pass (`patch-lint-checkjs.ts`) and the whole-project
+ * `fireforge typecheck` command (`typecheck.ts`).
+ *
+ * Centralised so both flows agree on the same Firefox-globals shim
+ * and the same set of suppressed diagnostic codes — drift between the
+ * two would mean a patch could lint clean under `fireforge lint` but
+ * still fail `fireforge typecheck`, or vice versa, for reasons the
+ * operator could not infer from the rule names.
+ */
+import { resolve } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+/** Filename used for the synthetic Firefox-globals shim source file. */
+export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
+/**
+ * Minimal `.d.ts` shim for Firefox privileged-scope globals.
+ *
+ * Firefox source is plain JS — no TypeScript allowed. The shim lets
+ * TS-driven type checking run without reporting "cannot find name"
+ * for the most common Mozilla APIs. Types are intentionally loose
+ * (`any`) because full Firefox type coverage is out of scope.
+ *
+ * Notable patterns that require shimming:
+ * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
+ *   populates `lazy` at runtime; we declare it as `Record<string, any>`.
+ * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
+ * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
+ * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
+ *   content scripts wired via `browser.js`.
+ */
+export const FIREFOX_GLOBALS_SHIM = `
+declare var Services: any;
+declare var ChromeUtils: {
+  defineESModuleGetters(target: any, modules: Record<string, string>): void;
+  importESModule(specifier: string): any;
+  import(specifier: string): any;
+  defineModuleGetter(target: any, name: string, specifier: string): void;
+  generateQI(interfaces: any[]): Function;
+  isClassInfo(obj: any): boolean;
+};
+declare var Cu: any;
+declare var Ci: any;
+declare var Cc: any;
+declare var Cr: any;
+declare var Components: any;
+declare var XPCOMUtils: any;
+declare var lazy: Record<string, any>;
+declare var PathUtils: any;
+declare var IOUtils: any;
+declare var FileUtils: any;
+declare var gBrowser: any;
+declare var gURLBar: any;
+declare var gNavigatorBundle: any;
+declare var AppConstants: any;
+`;
+/**
+ * TS diagnostic codes suppressed by both the patch-lint checkJs pass
+ * and the whole-project typecheck command. Each is a known false
+ * positive that arises from checking Firefox JS outside Mozilla's own
+ * build system: the resolver can't follow `resource://`/`chrome://`
+ * URLs and the global shim is intentionally narrow.
+ *
+ * Widening this set should be deliberate and per-code — silently
+ * suppressing more codes hides real type errors. The same set is used
+ * by both flows so a patch can't pass one and fail the other for a
+ * reason the operator couldn't infer from the docs.
+ */
+export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
+    2307, // Cannot find module '{0}' or its corresponding type declarations.
+    2306, // File '{0}' is not a module.
+    2305, // Module '{0}' has no exported member '{1}'.
+    2792, // Cannot find module '{0}'. Did you mean to set the 'moduleResolution' option...
+    2304, // Cannot find name '{0}'. (for globals we missed in the shim)
+    2552, // Cannot find name '{0}'. Did you mean '{1}'?
+    2580, // Cannot find name '{0}'. Do you need to install type definitions...
+    7016, // Could not find a declaration file for module '{0}'.
+]);
+/**
+ * Composes the synthetic shim source by concatenating the built-in
+ * Firefox globals shim with the contents of an optional user-supplied
+ * `.d.ts` file. The user file is appended verbatim — the augment
+ * direction is intentional (declarations later in concat order
+ * augment earlier ones), so a project that wants to refine `Services`
+ * with a more specific type can do so by declaring it in the extra
+ * shim.
+ *
+ * Missing extra-shim files raise a clear error rather than failing
+ * silently with a confusing "type not found" downstream — this is the
+ * one config-driven path where a user typo in `fireforge.json`
+ * produces a runtime error, so it needs to be unmistakable.
+ *
+ * @param projectRoot - Absolute project root, used to resolve the relative shim path
+ * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
+ */
+export async function composeShimSource(projectRoot, extraShimPath) {
+    if (!extraShimPath) {
+        return { source: FIREFOX_GLOBALS_SHIM, extraShimAppended: false };
+    }
+    const absoluteShim = resolve(projectRoot, extraShimPath);
+    if (!(await pathExists(absoluteShim))) {
+        throw new Error(`Extra TypeScript shim not found: ${extraShimPath} (resolved to ${absoluteShim}). ` +
+            'Check the path in fireforge.json or create the file.');
+    }
+    const extra = await readText(absoluteShim);
+    return {
+        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${extra}`,
+        extraShimAppended: true,
+    };
+}
+//# sourceMappingURL=typecheck-shim.js.map

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

@@ -0,0 +1,65 @@
+/**
+ * Whole-project TypeScript type checking driven by user-supplied
+ * `jsconfig.json` paths. The engine behind the `fireforge typecheck`
+ * command.
+ *
+ * Distinct from `patch-lint-checkjs.ts` (patch-hygiene): patchLint is
+ * scoped, fireforge-controlled, and runs as part of `fireforge lint`;
+ * this command runs whole projects with user-controlled compiler
+ * options and is intended as a CI gate. The two share the Firefox
+ * globals shim and suppressed-code list (via `typecheck-shim.ts`) so
+ * a file that lints clean cannot fail typecheck for a reason the
+ * operator could not have inferred from the docs.
+ *
+ * Loads the TypeScript compiler API via dynamic import so it is only
+ * required when `typecheck.projects` is configured. TypeScript
+ * remains a dev-dependency — if a user invokes `fireforge typecheck`
+ * without installing it, the function returns a clear error pointing
+ * at `npm install typescript`.
+ */
+import type { TypecheckConfig } from '../types/config.js';
+import type { TypecheckProjectResult } from '../types/typecheck.js';
+/**
+ * Sentinel string surfaced as a `TypecheckIssue.message` when the
+ * project's jsconfig sets `checkJs: false`. Exported so tests can
+ * pin the contract — operators rely on it to spot opted-out projects
+ * in CI logs.
+ */
+export declare const CHECK_JS_DISABLED_NOTICE = "Project sets \"checkJs: false\" \u2014 skipping (override the jsconfig to enable typecheck).";
+/**
+ * Runs `fireforge typecheck` against every project listed in `cfg.projects`.
+ *
+ * Per-project flow:
+ *   1. Read the jsconfig via the TS API. JSON parse / config-spec
+ *      errors are surfaced as issues, not thrown — a single broken
+ *      project must not abort the rest of the run.
+ *   2. Compute final compiler options from the user's options. We
+ *      only force `noEmit: true` (this is a typecheck, not a build);
+ *      we honour `strict`, `target`, `lib`, `module`, `paths`,
+ *      `include`, `exclude`. `allowJs` and `checkJs` default to
+ *      `true` only when the user has not set them — if the user set
+ *      `checkJs: false` we treat that as an explicit opt-out and
+ *      skip the project with a single notice (see {@link CHECK_JS_DISABLED_NOTICE}).
+ *   3. Inject the synthetic shim (built-in + optional extraShim) as
+ *      a virtual root file that the custom CompilerHost serves.
+ *   4. Build the program; collect semantic, syntactic, options, and
+ *      global diagnostics. The patchLint flow only reads semantic +
+ *      syntactic — fine for hygiene, but a CI gate needs the full
+ *      set so misconfigured `lib`/`paths` entries fail loudly.
+ *   5. Drop diagnostics whose code is in `SUPPRESSED_DIAGNOSTIC_CODES`
+ *      and any diagnostic originating in the synthetic shim itself.
+ *
+ * @param projectRoot - Absolute project root. All paths in `cfg` are resolved against it.
+ * @param cfg - Validated `typecheck` block from `fireforge.json`.
+ * @returns One {@link TypecheckProjectResult} per entry in `cfg.projects`,
+ *   in declared order. The CLI is responsible for printing the issues
+ *   and computing the exit code.
+ */
+export declare function runTypecheck(projectRoot: string, cfg: TypecheckConfig): Promise<TypecheckProjectResult[]>;
+/**
+ * Converts an absolute path to a path relative to the project root,
+ * for display in CLI output. Falls back to the absolute path when
+ * the path lies outside the root (e.g. a `node_modules` symlinked
+ * from elsewhere). Exposed for tests and the CLI.
+ */
+export declare function relativeForDisplay(projectRoot: string, absoluteFile: string): string;