@hominis/fireforge 0.11.2 → 0.13.0

package/dist/src/commands/patch/reorder.js

@@ -13,21 +13,13 @@ import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive, } from '../../core/destructive.js';
 import { buildPatchQueueContext, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, renumberPatchesInManifest, } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
-function resolvePatchIdentifier(identifier, patches) {
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 function padOrder(value, width) {
     return String(value).padStart(width, '0');
 }

package/dist/src/commands/re-export.js

@@ -6,7 +6,7 @@ import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatch, updatePatchMetadata } from '../core/patch-export.js';
-import { getClaimedFiles, loadPatchesManifest } from '../core/patch-manifest.js';
+import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -14,22 +14,6 @@ import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '..
 import { pickDefined } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { reExportFilesInPlace } from './re-export-files.js';
-/**
- * Resolves patch identifiers (numbers or filenames) to manifest entries.
- * @param identifier - Patch number (e.g. "005") or filename (e.g. "005-ui-storage-modules.patch")
- * @param patches - All patches from the manifest
- * @returns Matching patch metadata
- */
-function resolvePatchIdentifier(identifier, patches) {
-    // If all digits, match by order number
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    // Match by filename (with or without .patch suffix)
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 async function scanPatchFiles(currentFilesAffected, engineDir, manifest, patchFilename, isDryRun) {
     const parentDirs = [...new Set(currentFilesAffected.map((f) => dirname(f)))];
     const claimedByOthers = getClaimedFiles(manifest, patchFilename);

package/dist/src/commands/verify.js

@@ -89,11 +89,11 @@ export async function verifyCommand(projectRoot) {
     if (lintIssues.length > 0) {
         warn(`Cross-patch lint issues (${lintIssues.length}):`);
         for (const issue of lintIssues) {
-            const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
+            const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
             warn(`  ${label} [${issue.check}] ${issue.file}: ${issue.message}`);
             if (issue.severity === 'error')
                 errorCount += 1;
-            else
+            else if (issue.severity === 'warning')
                 warningCount += 1;
         }
     }

package/dist/src/core/ast-utils.d.ts

@@ -1,3 +1,4 @@
+import * as acorn from 'acorn';
 import type * as estree from 'estree';
 import { walk } from 'estree-walker';
 /**
@@ -16,6 +17,15 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
  */
 export declare function parseScript(content: string): AcornESTreeNode<estree.Program>;
+/**
+ * Parse JavaScript source as an **ES module**.
+ * Used for `.sys.mjs` files which use static import/export syntax.
+ *
+ * @param content - Source text to parse
+ * @param onComment - Optional array that acorn fills with comment nodes
+ * @returns Parsed program AST with character-offset positions
+ */
+export declare function parseModule(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
 /**
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.

package/dist/src/core/ast-utils.js

@@ -12,6 +12,24 @@ export function parseScript(content) {
         ecmaVersion: 'latest',
     });
 }
+/**
+ * Parse JavaScript source as an **ES module**.
+ * Used for `.sys.mjs` files which use static import/export syntax.
+ *
+ * @param content - Source text to parse
+ * @param onComment - Optional array that acorn fills with comment nodes
+ * @returns Parsed program AST with character-offset positions
+ */
+export function parseModule(content, onComment) {
+    const opts = {
+        sourceType: 'module',
+        ecmaVersion: 'latest',
+        locations: true,
+    };
+    if (onComment)
+        opts.onComment = onComment;
+    return acorn.parse(content, opts);
+}
 /**
  * Convenience cast from `acorn.Node` (or the generic ESTree union returned
  * by estree-walker callbacks) to a positioned, narrowly-typed node.

package/dist/src/core/config-paths.d.ts

@@ -17,9 +17,9 @@ export declare const CONFIGS_DIR = "configs";
 /** Name of the source directory */
 export declare const SRC_DIR = "src";
 /** Supported top-level fireforge.json keys backed by the current schema. */
-export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire"];
+export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "license", "wire", "patchLint"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "build", "build.jobs", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

package/dist/src/core/config-paths.js

@@ -27,6 +27,7 @@ export const SUPPORTED_CONFIG_ROOT_KEYS = [
     'build',
     'license',
     'wire',
+    'patchLint',
 ];
 /** Supported config paths that can be read or set without --force. */
 export const SUPPORTED_CONFIG_PATHS = [
@@ -42,6 +43,8 @@ export const SUPPORTED_CONFIG_PATHS = [
     'build.jobs',
     'wire',
     'wire.subscriptDir',
+    'patchLint',
+    'patchLint.checkJs',
 ];
 /**
  * Gets all project paths based on a root directory.

package/dist/src/core/config-validate.js

@@ -5,7 +5,7 @@
 import { ConfigError } from '../errors/config.js';
 import { verbose } from '../utils/logger.js';
 import { parseObject } from '../utils/parse.js';
-import { isContainedRelativePath } from '../utils/paths.js';
+import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
 import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 /**
@@ -27,8 +27,14 @@ export function validateConfig(data) {
     const vendor = requireConfigString(rec, 'vendor');
     const appId = requireConfigString(rec, 'appId');
     const binaryName = requireConfigString(rec, 'binaryName');
-    if (binaryName.includes('..') || binaryName.includes('/') || binaryName.includes('\\')) {
-        throw new ConfigError('Config field "binaryName" must not contain path separators or ".."');
+    if (binaryName.includes('..') ||
+        binaryName.includes('/') ||
+        binaryName.includes('\\') ||
+        binaryName.includes('\0')) {
+        throw new ConfigError('Config field "binaryName" must not contain path separators, "..", or null bytes');
+    }
+    if (isExplicitAbsolutePath(binaryName)) {
+        throw new ConfigError('Config field "binaryName" must not be an absolute path');
     }
     if (!isValidAppId(appId)) {
         throw new ConfigError('Config field "appId" must be a valid reverse-domain identifier (e.g., "org.example.browser")');
@@ -101,6 +107,18 @@ export function validateConfig(data) {
         }
         config.license = licenseRaw;
     }
+    // PatchLint
+    const patchLintRec = optionalConfigObject(rec, 'patchLint');
+    if (patchLintRec) {
+        config.patchLint = {};
+        const checkJs = patchLintRec.raw('checkJs');
+        if (checkJs !== undefined) {
+            if (typeof checkJs !== 'boolean') {
+                throw new ConfigError('Config field "patchLint.checkJs" must be a boolean');
+            }
+            config.patchLint.checkJs = checkJs;
+        }
+    }
     // Warn on unknown root keys
     const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
     for (const key of rec.keys()) {

package/dist/src/core/file-lock.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { mkdir, rm, stat } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { ensureDir } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
@@ -25,6 +25,20 @@ function getNodeErrorCode(error) {
 export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
     return `${filePath}${suffix}`;
 }
+const LOCK_PID_FILE = 'pid';
+/**
+ * Checks whether a process with the given PID is still running.
+ * Uses `kill(pid, 0)` which sends no signal but checks existence.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
     try {
         const lockStat = await stat(lockPath);
@@ -32,6 +46,21 @@ async function removeIfStaleLock(lockPath, staleMs, onStaleLockMessage) {
         if (ageMs <= staleMs) {
             return false;
         }
+        // If the lock directory contains a PID file, check whether the owning
+        // process is still running before removing. This prevents premature
+        // removal when a slow operation (e.g. mach build) legitimately holds
+        // the lock past the stale threshold.
+        try {
+            const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
+            const pid = parseInt(pidContent.trim(), 10);
+            if (Number.isFinite(pid) && isProcessAlive(pid)) {
+                verbose(`Lock at ${lockPath} is ${Math.round(ageMs / 1000)}s old but PID ${pid} is still running — not removing`);
+                return false;
+            }
+        }
+        catch {
+            // No PID file or unreadable — fall through to stale removal
+        }
         const staleMessage = onStaleLockMessage?.(ageMs);
         if (staleMessage) {
             warn(staleMessage);
@@ -84,6 +113,14 @@ export async function withFileLock(lockPath, operation, options = {}) {
             await sleep(pollMs);
         }
     }
+    // Write PID into the lock directory so stale-lock recovery can check
+    // whether the owning process is still alive before removing.
+    try {
+        await writeFile(join(lockPath, LOCK_PID_FILE), String(process.pid), 'utf-8');
+    }
+    catch {
+        // Non-fatal: stale recovery falls back to age-only heuristic
+    }
     try {
         return await operation();
     }

package/dist/src/core/furnace-apply.js

@@ -349,7 +349,8 @@ export async function applyAllComponents(root, dryRun = false, options) {
                     // Rollback itself failed: the engine is in a partially restored
                     // state. Persist a pending-repair marker so the next `fireforge
                     // doctor --repair-furnace` run knows to reconcile.
-                    await recordFurnaceRollbackFailure(root, 'apply-rollback', toError(rollbackError).message);
+                    const failedComponents = result.errors.map((e) => e.name).join(', ');
+                    await recordFurnaceRollbackFailure(root, 'apply-rollback', `failed component(s): ${failedComponents || '(unknown)'}: ${toError(rollbackError).message}`);
                     throw rollbackError;
                 }
             }

package/dist/src/core/furnace-config.js

@@ -4,6 +4,7 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
+import { isExplicitAbsolutePath } from '../utils/paths.js';
 import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
 import { resolveFtlDir } from './furnace-constants.js';
@@ -99,8 +100,11 @@ function parseCustomConfig(data, name) {
     if (!isString(data['targetPath'])) {
         throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must be a string`);
     }
-    if (data['targetPath'].includes('..')) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." (path traversal)`);
+    if (data['targetPath'].includes('..') || data['targetPath'].includes('\0')) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." or null bytes (path traversal)`);
+    }
+    if (isExplicitAbsolutePath(data['targetPath'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not be an absolute path`);
     }
     if (!isBoolean(data['register'])) {
         throw new FurnaceError(`Furnace config: custom "${name}.register" must be a boolean`);

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

@@ -3,7 +3,8 @@
  * Patch orchestration — coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
-import { join } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
@@ -34,7 +35,7 @@ async function applySinglePatch(patch, engineDir) {
     try {
         patchContent = await readText(patch.path);
         affectedFiles = extractAffectedFiles(patchContent);
-        validatePatchTargets(patch, affectedFiles);
+        await validatePatchTargets(patch, affectedFiles, engineDir);
         await applyPatchIdempotent(patch.path, engineDir);
         return { patch, success: true };
     }
@@ -143,7 +144,7 @@ export async function validatePatches(patchesDir, engineDir) {
     for (const patch of patches) {
         try {
             const patchContent = await readText(patch.path);
-            validatePatchTargets(patch, extractAffectedFiles(patchContent));
+            await validatePatchTargets(patch, extractAffectedFiles(patchContent), engineDir);
         }
         catch (error) {
             errors.push(`${patch.filename}: ${toError(error).message}`);
@@ -157,11 +158,32 @@ export async function validatePatches(patchesDir, engineDir) {
     }
     return { valid: errors.length === 0, errors };
 }
-function validatePatchTargets(patch, affectedFiles) {
+async function validatePatchTargets(patch, affectedFiles, engineDir) {
     for (const file of affectedFiles) {
         if (!isContainedRelativePath(file)) {
             throw new PatchError(`Patch targets a path outside engine/: ${file}`, patch.filename);
         }
+        // When the engine directory is known, verify that existing target paths
+        // are not symlinks pointing outside the engine tree. A crafted patch
+        // could otherwise write through a symlink to an arbitrary location.
+        if (engineDir) {
+            const targetPath = join(engineDir, file);
+            try {
+                const stats = await lstat(targetPath);
+                if (stats.isSymbolicLink()) {
+                    const realPath = resolve(engineDir, file);
+                    const resolvedEngine = resolve(engineDir);
+                    if (!realPath.startsWith(resolvedEngine + '/') && realPath !== resolvedEngine) {
+                        throw new PatchError(`Patch targets a symlink that resolves outside engine/: ${file}`, patch.filename);
+                    }
+                }
+            }
+            catch (error) {
+                // File doesn't exist yet (new file) or stat fails — skip check
+                if (error instanceof PatchError)
+                    throw error;
+            }
+        }
     }
 }
 /**

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

@@ -0,0 +1,21 @@
+/**
+ * Optional TypeScript `checkJs` pass for patch-owned `.sys.mjs` files.
+ *
+ * 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
+ * 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.
+ */
+import type { PatchLintIssue } from '../types/commands/index.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)
+ * @returns Array of lint issues from TS diagnostics
+ */
+export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>): Promise<PatchLintIssue[]>;

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

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Optional TypeScript `checkJs` pass for patch-owned `.sys.mjs` files.
+ *
+ * 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
+ * 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.
+ */
+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}'.
+]);
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * 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)
+ * @returns Array of lint issues from TS diagnostics
+ */
+export async function runCheckJs(repoDir, patchOwnedFiles) {
+    if (patchOwnedFiles.size === 0)
+        return [];
+    // Dynamic import — typescript stays as a dev dependency
+    let ts;
+    try {
+        ts = await import('typescript');
+    }
+    catch {
+        return [
+            {
+                file: '(checkJs)',
+                check: 'checkjs-type-error',
+                message: 'patchLint.checkJs is enabled but the "typescript" package is not installed. ' +
+                    'Run "npm install typescript" to enable type checking.',
+                severity: 'error',
+            },
+        ];
+    }
+    // Resolve absolute paths for root files, filtering to files that exist
+    const rootFiles = [];
+    const ownedAbsolute = new Set();
+    for (const rel of patchOwnedFiles) {
+        const abs = resolve(repoDir, rel);
+        if (await pathExists(abs)) {
+            rootFiles.push(abs);
+            ownedAbsolute.add(abs);
+        }
+    }
+    if (rootFiles.length === 0)
+        return [];
+    const shimPath = resolve(repoDir, SHIM_FILENAME);
+    rootFiles.push(shimPath);
+    const options = {
+        allowJs: true,
+        checkJs: true,
+        noEmit: true,
+        strict: false,
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        skipLibCheck: true,
+        // Do not follow import/reference directives into the Firefox tree.
+        // We only want to check the patch-owned files themselves.
+        // Without this, TS would try (and fail) to resolve every
+        // resource:// and chrome:// import, flooding the output with
+        // "Cannot find module" errors for upstream Firefox modules.
+        noResolve: true,
+        // 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,
+    };
+    // Custom compiler host: reads patch-owned files from disk, returns
+    // the shim for the shim path, and returns empty content for
+    // anything else to avoid reading the full Firefox tree.
+    const defaultHost = ts.createCompilerHost(options);
+    const host = {
+        ...defaultHost,
+        getSourceFile(fileName, languageVersion, onError) {
+            if (fileName === shimPath) {
+                return ts.createSourceFile(fileName, FIREFOX_GLOBALS_SHIM, languageVersion, true);
+            }
+            if (ownedAbsolute.has(fileName)) {
+                return defaultHost.getSourceFile(fileName, languageVersion, onError);
+            }
+            // For lib files (lib.es*.d.ts) delegate to the default host
+            // so built-in types like Promise, Array, etc. are available.
+            if (fileName.includes('lib.') && fileName.endsWith('.d.ts')) {
+                return defaultHost.getSourceFile(fileName, languageVersion, onError);
+            }
+            // Return an empty source file for anything else to avoid
+            // reading unrelated Firefox source files.
+            return ts.createSourceFile(fileName, '', languageVersion, true);
+        },
+        fileExists(fileName) {
+            if (fileName === shimPath)
+                return true;
+            if (ownedAbsolute.has(fileName))
+                return true;
+            return defaultHost.fileExists(fileName);
+        },
+        readFile(fileName) {
+            if (fileName === shimPath)
+                return FIREFOX_GLOBALS_SHIM;
+            return defaultHost.readFile(fileName);
+        },
+    };
+    const program = ts.createProgram(rootFiles, options, host);
+    const allDiagnostics = [
+        ...program.getSemanticDiagnostics(),
+        ...program.getSyntacticDiagnostics(),
+    ];
+    // Filter to diagnostics originating in patch-owned files only,
+    // and suppress module-resolution / unknown-name noise that is
+    // inherent to checking Firefox JS outside Mozilla's build system.
+    const issues = [];
+    for (const diag of allDiagnostics) {
+        if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
+            continue;
+        const sourceFile = diag.file;
+        if (!sourceFile)
+            continue;
+        if (!ownedAbsolute.has(sourceFile.fileName))
+            continue;
+        const lineInfo = sourceFile.getLineAndCharacterOfPosition(diag.start ?? 0);
+        const line = lineInfo.line + 1;
+        const messageText = typeof diag.messageText === 'string'
+            ? diag.messageText
+            : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
+        // Find the relative path for the issue
+        let relPath = sourceFile.fileName;
+        for (const [rel, abs] of [...patchOwnedFiles].map((r) => [r, resolve(repoDir, r)])) {
+            if (abs === sourceFile.fileName) {
+                relPath = rel;
+                break;
+            }
+        }
+        const severity = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
+        issues.push({
+            file: relPath,
+            check: 'checkjs-type-error',
+            message: `Line ${line}: ${messageText}`,
+            severity,
+        });
+    }
+    verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s), found ${issues.length} issue(s)`);
+    return issues;
+}
+//# sourceMappingURL=patch-lint-checkjs.js.map

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

@@ -113,6 +113,7 @@ export declare function isForwardImportableFile(path: string): boolean;
  * - `import "specifier"`            (side-effect imports — the `from`
  *                                   clause is optional in the regex)
  * - `import("specifier")`           (dynamic imports)
+ * - ChromeUtils.importESModule("specifier")
  * - ChromeUtils.defineESModuleGetters(obj, { Name: "specifier", ... })
  *
  * Returns the raw specifier strings — callers should take the leaf basename

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

@@ -156,6 +156,7 @@ export function isForwardImportableFile(path) {
  * - `import "specifier"`            (side-effect imports — the `from`
  *                                   clause is optional in the regex)
  * - `import("specifier")`           (dynamic imports)
+ * - ChromeUtils.importESModule("specifier")
  * - ChromeUtils.defineESModuleGetters(obj, { Name: "specifier", ... })
  *
  * Returns the raw specifier strings — callers should take the leaf basename
@@ -282,6 +283,12 @@ export function extractImportSpecifiersWithLines(source) {
         if (match[1])
             results.push({ specifier: match[1], line: offsetToLine(match.index) });
     }
+    // ChromeUtils.importESModule("resource://...") — Firefox single-module import
+    const chromeUtilsPattern = /ChromeUtils\.importESModule\s*\(\s*["']([^"']+)["']/g;
+    while ((match = chromeUtilsPattern.exec(stripped)) !== null) {
+        if (match[1])
+            results.push({ specifier: match[1], line: offsetToLine(match.index) });
+    }
     collectGetterSpecifiers(stripped, results, offsetToLine);
     return results;
 }

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

@@ -0,0 +1,21 @@
+/**
+ * AST-based JSDoc validation for exported declarations in `.sys.mjs`
+ * modules. Uses Acorn (already a runtime dependency) to parse the
+ * module and inspects JSDoc comments via the `onComment` callback.
+ *
+ * Separated from `patch-lint.ts` to keep both files within the
+ * project's per-file line budget.
+ */
+export type JsDocCheck = 'missing-jsdoc' | 'jsdoc-param-mismatch' | 'jsdoc-missing-returns';
+export interface JsDocIssue {
+    line: number;
+    check: JsDocCheck;
+    message: string;
+}
+/**
+ * Validates JSDoc on exported declarations in a `.sys.mjs` source file.
+ *
+ * @param source - File content
+ * @returns Array of JSDoc issues found
+ */
+export declare function validateExportJsDoc(source: string): JsDocIssue[];