@hominis/fireforge 0.18.9 → 0.18.11

package/dist/src/core/license-headers.js

@@ -53,6 +53,39 @@ export function getLicenseHeader(license, style) {
             return lines.map((l) => `# ${l}`).join('\n');
     }
 }
+/**
+ * Single-line `/* ... *\/` block comments containing either an Emacs
+ * file-mode marker (`-*-`) or a vim modeline (`vim:`) — Mozilla's
+ * canonical first-line editor directives that legitimately precede the
+ * license header in many Firefox source files.
+ *
+ * Restricted to single-line blocks so a multi-line license header never
+ * gets accidentally consumed.
+ */
+const EDITOR_DIRECTIVE_BLOCK_COMMENT = /^[ \t]*\/\*[^\r\n]*?(?:-\*-|\bvim:)[^\r\n]*?\*\/[ \t]*\r?\n?/;
+/**
+ * Strips any leading run of editor-directive block comments and blank
+ * lines, returning the remaining content.
+ *
+ * Mozilla's coding convention places editor directives like
+ * `/* -*- Mode: javascript; ... -*- *\/` and `/* vim: set ... *\/` on
+ * lines 1–2, with the canonical license header following on lines 3+.
+ * The raw `content.startsWith(...)` check used by {@link hasAnyLicenseHeader}
+ * never matches in that shape; this helper lets the caller test the
+ * post-directive prefix as a fallback.
+ *
+ * @param content - File content to strip
+ */
+function stripLeadingEditorDirectives(content) {
+    let result = content;
+    let prev;
+    do {
+        prev = result;
+        result = result.replace(/^[ \t]*\r?\n/, '');
+        result = result.replace(EDITOR_DIRECTIVE_BLOCK_COMMENT, '');
+    } while (result !== prev);
+    return result;
+}
 /**
  * Returns true if `content` starts with any known license header for the
  * given comment style.
@@ -65,16 +98,24 @@ export function getLicenseHeader(license, style) {
  * standard MPL header — operators were forced to `--skip-lint` over a real
  * false positive.
  *
+ * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
+ * leading the file are tolerated — Mozilla's canonical layout puts those
+ * on lines 1–2 with the MPL header on lines 3+, which the raw
+ * `startsWith` check would otherwise miss.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
 export function hasAnyLicenseHeader(content, style) {
+    const candidates = [content, stripLeadingEditorDirectives(content)];
     const licenses = Object.keys(HEADER_LINES);
-    if (licenses.some((license) => content.startsWith(getLicenseHeader(license, style)))) {
-        return true;
-    }
-    if (style === 'js' && content.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
-        return true;
+    for (const candidate of candidates) {
+        if (licenses.some((license) => candidate.startsWith(getLicenseHeader(license, style)))) {
+            return true;
+        }
+        if (style === 'js' && candidate.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
+            return true;
+        }
     }
     return false;
 }

package/dist/src/core/mach-build-artifacts.d.ts

@@ -50,8 +50,8 @@ export interface RunnableBundleCheck {
  *
  * Platform layout:
  * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName` — e.g. `Hominis.app` for
- *   binary `hominis`, so we enumerate the `*.app` bundles rather than
+ *   display casing can differ from `binaryName` — e.g. `MyBrowser.app` for
+ *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
  *   compute the name.
  * - Linux: `<objDir>/dist/bin/<binaryName>`.
  * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.

package/dist/src/core/mach-build-artifacts.js

@@ -108,8 +108,8 @@ export async function hasBuildArtifacts(engineDir) {
  *
  * Platform layout:
  * - macOS: `<objDir>/dist/*.app/Contents/MacOS/<binaryName>` (the `.app`
- *   display casing can differ from `binaryName` — e.g. `Hominis.app` for
- *   binary `hominis`, so we enumerate the `*.app` bundles rather than
+ *   display casing can differ from `binaryName` — e.g. `MyBrowser.app` for
+ *   binary `mybrowser`, so we enumerate the `*.app` bundles rather than
  *   compute the name.
  * - Linux: `<objDir>/dist/bin/<binaryName>`.
  * - Windows: `<objDir>/dist/bin/<binaryName>.exe`.

package/dist/src/core/mach-error-hints.js

@@ -40,19 +40,18 @@ export const MACH_ERROR_HINTS = [
         // inside gecko-profiler's generated `bindings.rs`, but `_CharT` is
         // not in scope where the alias lands — so the Rust compile fails
         // with "cannot find type `_CharT`". The symptom is obscure and the
-        // fix is external: Hominis ships
-        // `990-infra-bindgen-basic-string-workaround.patch` in its patch
-        // queue, which strips the offending alias line post-generation.
-        // This hint surfaces the workaround pointer alongside the raw
-        // bindgen output so operators don't have to reverse-engineer the
-        // failure.
+        // fix is external: a downstream consumer's patch queue may ship
+        // `990-infra-bindgen-basic-string-workaround.patch`, which strips
+        // the offending alias line post-generation. This hint surfaces the
+        // workaround pointer alongside the raw bindgen output so operators
+        // don't have to reverse-engineer the failure.
         pattern: /cannot find type `_CharT` in this scope[\s\S]*?gecko-profiler-|gecko-profiler-[\s\S]*?cannot find type `_CharT` in this scope/,
         hint: 'The Rust compile failed on a bindgen-generated `basic_string___self_view` alias in ' +
             'gecko-profiler/bindings.rs. This is an upstream bindgen output bug against some ' +
             'macOS libc++ SDK versions and needs a post-generation patch to strip the alias. ' +
             'The known-working workaround is the `990-infra-bindgen-basic-string-workaround.patch` ' +
-            "Hominis ships in its patch queue — import the equivalent into your fork's patches/, " +
-            'then re-run "fireforge import" + "fireforge build". If you do not use Hominis\' queue, ' +
+            "shipped by some downstream patch queues — import the equivalent into your fork's patches/, " +
+            'then re-run "fireforge import" + "fireforge build". If your fork does not carry such a patch, ' +
             'apply the following post-process to the generated file before the Rust compile: ' +
             'remove any `pub type basic_string___self_view = …<_CharT>;` line from ' +
             '`<objdir>/release/build/gecko-profiler-*/out/gecko/bindings.rs`.',

package/dist/src/core/marionette-port.js

@@ -3,7 +3,7 @@
  * Marionette port probe.
  *
  * Gecko's Marionette control channel binds `127.0.0.1:2828` when a
- * Firefox / ForgeFresh / Hominis instance is launched with
+ * Firefox / ForgeFresh / fork instance is launched with
  * `-marionette`. The `fireforge test` harness spawns the browser with
  * that flag, so any test run needs the port to be free at start.
  *
@@ -42,7 +42,7 @@ const BROWSER_BASENAMES = new Set([
     'firefox-bin',
     'firefox-esr',
     'forgefresh',
-    'hominis',
+    'mybrowser',
     'thunderbird',
 ]);
 /**
@@ -53,8 +53,8 @@ const BROWSER_BASENAMES = new Set([
  * warning.
  *
  * Includes the operator-provided `binaryName` from `fireforge.json`
- * so a fork that ships under a custom name (e.g. Hominis'
- * `hominis-nightly`) is still recognised as a browser.
+ * so a fork that ships under a custom name (e.g.
+ * `mybrowser-nightly`) is still recognised as a browser.
  */
 function isBrowserHolder(holder, binaryName) {
     if (/\s-marionette(?:\s|$)/.test(holder.commandLine)) {

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

@@ -5,6 +5,16 @@ import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '.
  * @returns Next patch number (e.g., "005" for 4 existing patches)
  */
 export declare function getNextPatchNumber(patchesDir: string): Promise<string>;
+/**
+ * Sanitizes a human-readable name into a filename slug.
+ *
+ * Exported so `patch rename` can produce a filename slug from its
+ * `--to <new-name>` argument using the exact same convention `export`
+ * uses, without duplicating the lowercase + non-alnum collapse + length
+ * cap rules. Drift between the two would let an operator rename a patch
+ * to a slug `export` could never reach.
+ */
+export declare function sanitizeName(name: string): string;
 /**
  * Generates the next patch filename with category.
  * @param patchesDir - Path to the patches directory

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

@@ -25,9 +25,15 @@ export async function getNextPatchNumber(patchesDir) {
     return String(nextNumber).padStart(Math.max(3, String(nextNumber).length), '0');
 }
 /**
- * Sanitizes a string for use in a filename.
+ * Sanitizes a human-readable name into a filename slug.
+ *
+ * Exported so `patch rename` can produce a filename slug from its
+ * `--to <new-name>` argument using the exact same convention `export`
+ * uses, without duplicating the lowercase + non-alnum collapse + length
+ * cap rules. Drift between the two would let an operator rename a patch
+ * to a slug `export` could never reach.
  */
-function sanitizeName(name) {
+export function sanitizeName(name) {
     return name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')

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

@@ -8,7 +8,10 @@
  * 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.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 /**
@@ -16,6 +19,15 @@ import type { PatchLintIssue } from '../types/commands/index.js';
  *
  * @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).
  * @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): Promise<PatchLintIssue[]>;

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

@@ -9,80 +9,15 @@
  * 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.
  */
 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 +26,18 @@ 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).
  * @returns Array of lint issues from TS diagnostics
  */
-export async function runCheckJs(repoDir, patchOwnedFiles) {
+export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot) {
     if (patchOwnedFiles.size === 0)
         return [];
     // Dynamic import — typescript stays as a dev dependency
@@ -124,6 +68,29 @@ 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 options = {
@@ -154,7 +121,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 +144,7 @@ export async function runCheckJs(repoDir, patchOwnedFiles) {
         },
         readFile(fileName) {
             if (fileName === shimPath)
-                return FIREFOX_GLOBALS_SHIM;
+                return shimSource;
             return defaultHost.readFile(fileName);
         },
     };

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

@@ -396,6 +396,10 @@ export function lintPatchQueueForwardImports(ctx) {
                 .map((o) => `${o.filename}:${o.fullPath}`)
                 .sort((a, b) => a.localeCompare(b))
                 .join(',');
+            // Lowest ordinal that lands AFTER every later-ordered creator —
+            // turns the operator's "guess and re-run" loop into a single shot
+            // when the only fix is reordering.
+            const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
             issues.push({
                 file: sitePath,
                 check: 'forward-import',
@@ -404,7 +408,8 @@ export function lintPatchQueueForwardImports(ctx) {
                     `but the matching new file is created by a later patch: ${ownersSummary}. ` +
                     'Reorder the patches so the dependency is created first, move the import ' +
                     'into the later patch, or mark the import with ' +
-                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive.`,
+                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
+                    `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
                 severity: 'error',
             });
         }

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

@@ -1,5 +1,5 @@
 // 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';
@@ -737,10 +737,12 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...jsIssues,
         ...modCommentIssues,
     ];
-    // Optional checkJs pass — only when explicitly enabled in config
+    // Optional checkJs pass — only when explicitly enabled in config.
+    // `checkJsExtraShim` is project-relative; resolve against the
+    // project root (dirname(engine) by getProjectPaths convention).
     if (config.patchLint?.checkJs) {
-        const checkJsIssues = await runCheckJs(repoDir, patchOwnedFiles);
-        issues.push(...checkJsIssues);
+        const extraShim = config.patchLint.checkJsExtraShim;
+        issues.push(...(await runCheckJs(repoDir, patchOwnedFiles, extraShim, 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