@hominis/fireforge 0.30.1 → 0.32.0

package/dist/src/core/test-harness-crash.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Harness-crash classification for `fireforge test` (field reports C1/C2).
+ *
+ * The wrapped mach harness exhibits flaky non-test failures that an exit
+ * code (or a "did it print a summary" grep) cannot distinguish from real
+ * test results:
+ *
+ *  - startup crashes from the mozlog resource monitor on macOS
+ *    (`AttributeError: 'SystemResourceMonitor' object has no attribute
+ *    'poll_interval'`, `host_statistics64(HOST_VM_INFO64) syscall failed`,
+ *    `(ipc/mig) array not large enough` — a psutil/macOS mismatch) which
+ *    abort the run before any test executes;
+ *  - hangs after browser startup that die at the no-output timeout yet
+ *    still emit a `Passed: 0` summary;
+ *  - post-green shutdown re-entry, where a fully green run stalls on
+ *    "must wait for focus" and records "Application shut down (without
+ *    crashing) in the middle of a test!" as the only unexpected failure.
+ *
+ * Classification therefore keys on `TEST-START` presence — summary lines
+ * never count as proof that tests ran — and recognizes the crash shapes
+ * above so the command layer can retry them with a bounded budget instead
+ * of reporting phantom test failures (or phantom passes).
+ */
+const TEST_START_PATTERN = /\bTEST-START\b/;
+const UNEXPECTED_LINE_PATTERN = /^.*\bTEST-UNEXPECTED-[A-Z-]+\b.*$/gm;
+const SHUTDOWN_REENTRY_PATTERN = /Application shut down \(without crashing\) in the middle of a test/i;
+const FOCUS_STALL_PATTERN = /must wait for focus/i;
+const TRACEBACK_PATTERN = /Traceback \(most recent call last\)/;
+const NO_OUTPUT_TIMEOUT_PATTERN = /timed out after \d+ seconds with no output/i;
+/**
+ * Startup-traceback fingerprints from the mozlog resource monitor / psutil
+ * on macOS. Each is matched per-line so the evidence line in the report is
+ * the concrete failure, not the whole traceback.
+ */
+const STARTUP_TRACEBACK_SIGNALS = [
+    /AttributeError:.*SystemResourceMonitor/,
+    /'SystemResourceMonitor' object has no attribute/,
+    /poll_interval/,
+    /host_statistics64/,
+    /HOST_VM_INFO64/,
+    /\(ipc\/mig\) array not large enough/,
+    /psutil\.[A-Za-z]*Error/,
+];
+function findLine(output, patterns) {
+    for (const line of output.split(/\r?\n/)) {
+        if (patterns.some((p) => p.test(line)))
+            return line.trim();
+    }
+    return undefined;
+}
+/** Unexpected-failure lines that are NOT the shutdown re-entry artifact. */
+function realUnexpectedFailureLines(output) {
+    const matches = output.match(UNEXPECTED_LINE_PATTERN) ?? [];
+    return matches.filter((line) => !SHUTDOWN_REENTRY_PATTERN.test(line));
+}
+/**
+ * Detects the known harness-crash shapes in captured mach output.
+ * Returns undefined for anything that looks like a genuine test result.
+ */
+export function detectHarnessCrashSignature(output) {
+    const hasTestStart = TEST_START_PATTERN.test(output);
+    const realFailures = realUnexpectedFailureLines(output);
+    // Startup traceback cluster (resource monitor / psutil). Real test
+    // failures take precedence: a traceback printed during teardown of a
+    // genuinely failing run must not get the whole run retried.
+    if (TRACEBACK_PATTERN.test(output) && realFailures.length === 0) {
+        const signalLine = findLine(output, STARTUP_TRACEBACK_SIGNALS);
+        if (signalLine) {
+            return { reason: 'harness startup traceback (resource monitor/psutil)', line: signalLine };
+        }
+    }
+    // Post-browser-startup hang: no test ever started, the harness died at
+    // the no-output timeout. A trailing "Passed: 0" summary is part of this
+    // shape and must not be read as a result.
+    if (!hasTestStart) {
+        const timeoutLine = findLine(output, [NO_OUTPUT_TIMEOUT_PATTERN]);
+        if (timeoutLine) {
+            return { reason: 'no-output timeout before any test started', line: timeoutLine };
+        }
+        return undefined;
+    }
+    // Post-green shutdown re-entry: every unexpected line is the
+    // shutdown-mid-test artifact, the run stalled on focus, and at least one
+    // such artifact exists — an otherwise green log.
+    const shutdownLine = findLine(output, [SHUTDOWN_REENTRY_PATTERN]);
+    if (shutdownLine && realFailures.length === 0 && FOCUS_STALL_PATTERN.test(output)) {
+        return { reason: 'post-green shutdown re-entry during harness teardown', line: shutdownLine };
+    }
+    return undefined;
+}
+/**
+ * Classifies a completed harness run. The decision tree, in order:
+ *
+ * 1. A recognized crash signature wins regardless of exit code (the
+ *    shutdown re-entry shape exits non-zero on an otherwise green run;
+ *    the hang shape can even exit zero with a `Passed: 0` summary).
+ * 2. No `TEST-START` with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. Summary lines are not
+ *    trusted as evidence of execution.
+ * 3. Exit code zero with tests started is a pass; anything else is a
+ *    test failure for the regular diagnosis chain.
+ */
+export function classifyHarnessRun(exitCode, output, requestedPaths) {
+    const signature = detectHarnessCrashSignature(output);
+    if (signature) {
+        return { kind: 'harness-crash', signature };
+    }
+    if (!TEST_START_PATTERN.test(output) && requestedPaths.length > 0) {
+        return { kind: 'no-tests' };
+    }
+    return exitCode === 0 ? { kind: 'tests-ran-ok' } : { kind: 'test-failures' };
+}
+/** Builds the operator-facing failure message after retries are exhausted. */
+export function buildHarnessCrashMessage(signature, attempts) {
+    return (`mach test crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
+        `Detected shape: ${signature.reason}\n` +
+        `Evidence line: ${signature.line}\n\n` +
+        'This failure mode is environmental (mozlog resource monitor / psutil on macOS, focus-stall ' +
+        'shutdown re-entry, or a pre-test hang) rather than a test regression. Re-run the command, ' +
+        'raise the retry budget with --harness-retries <n>, or run the file in isolation. ' +
+        'If it persists across many runs, inspect the mach virtualenv (mach resyncs psutil on its own; ' +
+        'patching it manually does not stick).');
+}
+/**
+ * Builds the message for a run that produced no `TEST-START` despite
+ * requesting paths — including exit-code-zero runs whose `Passed: 0`
+ * summary would otherwise read as a silent false green.
+ */
+export function buildNoTestsRanMessage(exitCode, requestedPaths) {
+    const exitNote = exitCode === 0
+        ? 'The harness exited 0 and may have printed a summary line, but a summary without a single TEST-START is not a test result.'
+        : `The harness exited ${exitCode} before any TEST-START line.`;
+    return ('mach test finished without starting any of the requested tests.\n\n' +
+        `${exitNote}\n\n` +
+        `Requested paths: ${requestedPaths.join(', ')}\n\n` +
+        'Check that the paths are registered in their test manifest (browser.toml / xpcshell.toml) ' +
+        'and that the manifest is reachable from moz.build, then retry.');
+}
+//# sourceMappingURL=test-harness-crash.js.map

package/dist/src/core/test-stale-check.d.ts

@@ -1,4 +1,4 @@
-import type { BuildBaseline } from './build-baseline.js';
+import type { BuildBaseline } from './build-baseline-types.js';
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */

package/dist/src/core/test-stale-check.js

@@ -30,53 +30,9 @@ import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { isPackageablePath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
-import { hasChanges, isMissingHeadError } from './git.js';
-import { git } from './git-base.js';
-import { getUntrackedFiles } from './git-status.js';
+import { collectChangedEnginePaths } from './engine-changes.js';
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
-/**
- * Collects engine paths that changed since the baseline SHA plus any
- * workdir modifications. Mirrors the helper inside `build-prepare.ts` but
- * is kept separate so the test-side preflight does not need to pull in
- * the full build-prepare dependency graph (mozconfig generation, furnace
- * apply hooks, …).
- */
-async function collectChangedEnginePaths(engineDir, baseline) {
-    const collected = new Set();
-    if (baseline.engineHeadSha) {
-        try {
-            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
-            for (const line of diff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-        }
-        catch (error) {
-            if (!isMissingHeadError(error)) {
-                verbose(`Stale-build preflight: could not diff engine against baseline — ${toError(error).message}`);
-            }
-        }
-    }
-    try {
-        if (await hasChanges(engineDir)) {
-            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
-            for (const line of worktreeDiff.split('\n')) {
-                const trimmed = line.trim();
-                if (trimmed)
-                    collected.add(trimmed);
-            }
-            for (const untracked of await getUntrackedFiles(engineDir)) {
-                collected.add(untracked);
-            }
-        }
-    }
-    catch (error) {
-        verbose(`Stale-build preflight: could not enumerate workdir changes — ${toError(error).message}`);
-    }
-    return [...collected];
-}
 /**
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
@@ -92,7 +48,7 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     if (!baseline) {
         return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
     }
-    const changed = await collectChangedEnginePaths(engineDir, baseline);
+    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Stale-build preflight');
     let packageable = changed.filter((path) => isPackageablePath(path)).sort();
     // Content-hash comparison: when the baseline carries a fingerprint set,
     // fold each candidate path through a live re-hash and drop paths whose

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -3,5 +3,12 @@ export interface XpcshellRetryClassification {
     xpcshell: readonly string[];
     nonXpcshell: readonly string[];
 }
-/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[]): Promise<MachCommandResult>;
+/** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
+export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>) => Promise<MachCommandResult>;
+/**
+ * Removes a stale xpcshell install symlink and retries the focused mach test
+ * once. The retry uses the same `dispatch` (suite-specific or generic) the
+ * caller is already running on, so an xpcshell-suite run repairs and re-runs
+ * via `mach xpcshell-test` rather than falling back to the generic command.
+ */
+export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -1,14 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { testWithOutput } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
-/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs) {
+/**
+ * Removes a stale xpcshell install symlink and retries the focused mach test
+ * once. The retry uses the same `dispatch` (suite-specific or generic) the
+ * caller is already running on, so an xpcshell-suite run repairs and re-runs
+ * via `mach xpcshell-test` rather than falling back to the generic command.
+ */
+export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput) {
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
         const repaired = await tryRepairStaleXpcshellTestSymlink(engineDir, objDir, `${result.stdout}\n${result.stderr}`);
         if (repaired) {
-            return testWithOutput(engineDir, normalizedPaths, extraArgs);
+            return env
+                ? dispatch(engineDir, normalizedPaths, extraArgs, env)
+                : dispatch(engineDir, normalizedPaths, extraArgs);
         }
     }
     return result;

package/dist/src/core/token-dark-mode.js

@@ -111,13 +111,22 @@ export function findDarkRootInsertionIndex(lines) {
     }
     if (rootOpenLine === -1)
         return -1;
-    // Depth-count starting from the `:root` opener. The first `{`
-    // encountered sets the entry depth to the initial counter value; the
-    // closing brace that returns to that depth terminates the block.
+    // Depth-count starting from the `:root` opener; see findBlockCloseIndex.
+    return findBlockCloseIndex(stripped, rootOpenLine);
+}
+/**
+ * Depth-counts braces from `startLine` (whose lines must already have
+ * block comments stripped), returning the index of the line on which the
+ * block opened there returns to its entry depth — i.e. the line carrying
+ * the block's closing `}` — or -1 when the block never closes. The first
+ * `{` encountered sets the entry depth, so the scan may start on the
+ * selector/at-rule line itself rather than on the opener.
+ */
+function findBlockCloseIndex(stripped, startLine) {
     let depth = 0;
     let entryDepth = 0;
     let enteredBlock = false;
-    for (let i = rootOpenLine; i < stripped.length; i++) {
+    for (let i = startLine; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
         for (const ch of line) {
             if (ch === '{') {
@@ -156,27 +165,6 @@ export function findDarkMediaCloseIndex(lines) {
     }
     if (darkMediaLine === -1)
         return -1;
-    let depth = 0;
-    let entryDepth = 0;
-    let enteredBlock = false;
-    for (let i = darkMediaLine; i < stripped.length; i++) {
-        const line = stripped[i] ?? '';
-        for (const ch of line) {
-            if (ch === '{') {
-                depth++;
-                if (!enteredBlock) {
-                    entryDepth = depth - 1;
-                    enteredBlock = true;
-                }
-            }
-            else if (ch === '}') {
-                depth--;
-            }
-        }
-        if (enteredBlock && depth === entryDepth) {
-            return i;
-        }
-    }
-    return -1;
+    return findBlockCloseIndex(stripped, darkMediaLine);
 }
 //# sourceMappingURL=token-dark-mode.js.map

package/dist/src/core/token-manager.d.ts

@@ -20,6 +20,8 @@ export interface AddTokenOptions {
     darkValue?: string | undefined;
     /** Dry run mode */
     dryRun?: boolean | undefined;
+    /** Declare the category banner in the tokens CSS when it does not exist yet. */
+    createCategory?: boolean | undefined;
 }
 /**
  * Result of adding a token.
@@ -35,6 +37,8 @@ export interface AddTokenResult {
     countUpdated: boolean;
     /** Whether the operation was skipped (already exists) */
     skipped: boolean;
+    /** Whether a new category banner was declared by this add. */
+    categoryCreated?: boolean;
 }
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export declare function getTokensCssPath(binaryName: string): string;

package/dist/src/core/token-manager.js

@@ -69,39 +69,54 @@ function validateDarkValue(options) {
         throw new InvalidArgumentError('Override mode requires --dark-value to be specified.', 'darkValue');
     }
 }
-async function assertTokenCategoryExists(engineDir, tokensCssPath, category) {
-    const filePath = join(engineDir, tokensCssPath);
-    if (!(await pathExists(filePath))) {
-        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
-    }
-    const content = await readText(filePath);
-    const lines = content.split('\n');
+/**
+ * True when `lines` contain a category header (single-line or multi-line
+ * banner shape) naming `category`. Shared by the pre-add assertion and the
+ * in-memory banner creation path so both agree on what "exists" means.
+ */
+function categoryHeaderExists(lines, category) {
     const escapedCategory = escapeRegex(category);
     const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i] ?? '';
         if (singleLinePattern.test(line)) {
-            return;
+            return true;
         }
         if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
             for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
                 const blockLine = lines[j] ?? '';
                 if (new RegExp(escapedCategory).test(blockLine)) {
-                    return;
+                    return true;
                 }
                 if (/\*\//.test(blockLine))
                     break;
             }
         }
     }
+    return false;
+}
+async function assertTokenCategoryExists(engineDir, tokensCssPath, category, createCategory = false) {
+    const filePath = join(engineDir, tokensCssPath);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    if (categoryHeaderExists(lines, category))
+        return;
+    // The write path declares the banner in the same edit as the token
+    // insertion, so a missing category is fine when creation was requested.
+    if (createCategory)
+        return;
     const discoveredCategories = discoverCategoryHeaders(lines);
     const available = discoveredCategories.length > 0
         ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
-        : 'The file currently has no category headers. Add one by hand near the top of the :root { … } block — the format is "/* = My Category = */" — or run "fireforge furnace init --force" to re-scaffold the default seed set.';
+        : 'The file currently has no category headers.';
     throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
         `${available}\n\n` +
         'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
-        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.');
+        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.\n\n' +
+        'Re-run with --create-category to declare the banner and insert the token in one step.');
 }
 /**
  * Scans a tokens CSS file for category header comments and returns the
@@ -156,7 +171,7 @@ export async function validateTokenAdd(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
-    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
 }
 /**
  * Adds a design token to the CSS file and documentation.
@@ -185,7 +200,7 @@ export async function addToken(root, options) {
         };
     }
     // --- CSS file ---
-    const cssAdded = await addTokenToCSS(engineDir, options, tokensCssPath);
+    const { added: cssAdded, categoryCreated } = await addTokenToCSS(engineDir, options, tokensCssPath);
     if (!cssAdded) {
         return {
             cssAdded: false,
@@ -203,8 +218,39 @@ export async function addToken(root, options) {
         unmappedAdded: docsResult.unmappedAdded,
         countUpdated: docsResult.countUpdated,
         skipped: false,
+        categoryCreated,
     };
 }
+/**
+ * Splices a new single-line category banner ("= Name =" comment shape, the
+ * same format `discoverCategoryHeaders` recognises) just before the closing
+ * brace of the `:root` block, making the new category the last section.
+ * Mutates `lines` in place.
+ */
+function declareCategoryBanner(lines, category, tokensCssPath) {
+    let rootOpen = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/:root\s*\{/.test(lines[i] ?? '')) {
+            rootOpen = i;
+            break;
+        }
+    }
+    if (rootOpen === -1) {
+        throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
+            'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
+    }
+    let rootClose = -1;
+    for (let i = rootOpen + 1; i < lines.length; i++) {
+        if (/^\s*\}/.test(lines[i] ?? '')) {
+            rootClose = i;
+            break;
+        }
+    }
+    if (rootClose === -1) {
+        throw new GeneralError(`Cannot create category "${category}": the :root block in ${tokensCssPath} never closes.`);
+    }
+    lines.splice(rootClose, 0, '', `  /* = ${category} = */`);
+}
 function findCategorySection(lines, category, tokensCssPath) {
     const escapedCategory = escapeRegex(category);
     const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
@@ -296,15 +342,23 @@ function insertDarkModeOverride(lines, options) {
  */
 async function addTokenToCSS(engineDir, options, tokensCssPath) {
     const filePath = join(engineDir, tokensCssPath);
-    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
     let content = await readText(filePath);
     // Idempotency check — strip CSS block comments so we don't match inside them
     const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
     if (stripped.includes(options.tokenName + ':')) {
-        return false;
+        return { added: false, categoryCreated: false };
     }
     const lines = content.split('\n');
     const annotation = getModeAnnotation(options.mode, options.value);
+    // Declare a missing category banner in the same in-memory edit as the
+    // token insertion — the file is written exactly once, so a failure
+    // between "banner declared" and "token inserted" cannot occur.
+    let categoryCreated = false;
+    if (options.createCategory === true && !categoryHeaderExists(lines, options.category)) {
+        declareCategoryBanner(lines, options.category, tokensCssPath);
+        categoryCreated = true;
+    }
     const { categoryLine, sectionEnd } = findCategorySection(lines, options.category, tokensCssPath);
     // Build the insertion lines
     const insertLines = [];
@@ -325,7 +379,7 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     insertDarkModeOverride(lines, options);
     content = lines.join('\n');
     await writeText(filePath, content);
-    return true;
+    return { added: true, categoryCreated };
 }
 /**
  * Strips surrounding backticks from a cell, if present. Token cells are

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

@@ -11,27 +11,6 @@
  */
 /** 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`.
- * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
- *   checkJs: the compiler sees empty stubs (`noResolve`); without URL
- *   ambient modules namespaces degrade to unusable typings. Wildcards
- *   keep Firefox URL imports pragmatically loose, same posture as globals.
- */
-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\n// Shorthand ambient modules \u2014 exports from matching URL imports are loosely typed,\n// avoiding noResolve empty-graph namespaces. (Named member access broke when we tried\n// export= Record under moduleResolution Bundler.)\ndeclare module 'resource:*';\ndeclare module 'chrome:*';\n\n";
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
  * and the whole-project typecheck command. Each is a known false
@@ -61,7 +40,9 @@ export interface ComposedShim {
  * 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.
+ * shim. Any triple-slash `/// <reference path="…">` directives inside the
+ * extra shim are inlined (resolved against the extra shim's own directory)
+ * so they are not silently dropped at the synthetic shim path.
  *
  * Missing extra-shim files raise a clear error rather than failing
  * silently with a confusing "type not found" downstream — this is the

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

@@ -10,7 +10,7 @@
  * still fail `fireforge typecheck`, or vice versa, for reasons the
  * operator could not infer from the rule names.
  */
-import { resolve } from 'node:path';
+import { dirname, 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';
@@ -30,18 +30,21 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
  *   content scripts wired via `browser.js`.
  * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
- *   checkJs: the compiler sees empty stubs (`noResolve`); without URL
- *   ambient modules namespaces degrade to unusable typings. Wildcards
- *   keep Firefox URL imports pragmatically loose, same posture as globals.
+ *   checkJs: imports of *patch-owned* modules resolve to their real
+ *   sources (see `patch-lint-checkjs.ts`); everything else fails host
+ *   resolution and lands on these URL ambient wildcards, keeping
+ *   upstream Firefox imports pragmatically loose, same posture as globals.
  */
-export const FIREFOX_GLOBALS_SHIM = `
+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;
+  defineLazyGetter(target: any, name: string, getter: () => any): void;
   generateQI(interfaces: any[]): Function;
+  getClassName(obj: any, unwrap?: boolean): string;
   isClassInfo(obj: any): boolean;
 };
 declare var Cu: any;
@@ -58,6 +61,25 @@ declare var gBrowser: any;
 declare var gURLBar: any;
 declare var gNavigatorBundle: any;
 declare var AppConstants: any;
+// Fluent localization — a stable chrome global. Members stay loose (any),
+// but the constructor shape is declared so "new Localization([...])" and
+// "new Localization([...], true)" typecheck without a local cast.
+declare var Localization: {
+  new (
+    resourceIds: Array<string | { path: string; optional?: boolean }>,
+    sync?: boolean
+  ): {
+    formatValue(id: string, args?: Record<string, unknown>): any;
+    formatValues(keys: any[]): any;
+    formatMessages(keys: any[]): any;
+    formatValueSync(id: string, args?: Record<string, unknown>): any;
+    formatValuesSync(keys: any[]): any;
+    formatMessagesSync(keys: any[]): any;
+    addResourceIds(ids: Array<string | { path: string; optional?: boolean }>): void;
+    removeResourceIds(ids: string[]): number;
+    setAsync(): void;
+  };
+};
 
 // Shorthand ambient modules — exports from matching URL imports are loosely typed,
 // avoiding noResolve empty-graph namespaces. (Named member access broke when we tried
@@ -88,6 +110,43 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
     2580, // Cannot find name '{0}'. Do you need to install type definitions...
     7016, // Could not find a declaration file for module '{0}'.
 ]);
+/** Matches a lone triple-slash `/// <reference path="…" />` directive line. */
+const TRIPLE_SLASH_REFERENCE = /^\s*\/\/\/\s*<reference\s+path\s*=\s*["']([^"']+)["']\s*\/?>\s*$/;
+/**
+ * Inlines triple-slash `/// <reference path="…">` directives in shim source.
+ *
+ * Both shim consumers feed the text to the compiler at a *synthetic* path
+ * (an in-memory source file, not the extra shim's real location), so TS
+ * resolves a relative `/// <reference>` against that synthetic directory and
+ * silently drops it. Inlining the referenced file's contents (recursively,
+ * resolved against the *referencing* file's directory, deduped by absolute
+ * path) makes the directives self-contained so their declarations survive.
+ *
+ * @param source - Shim source possibly containing reference directives
+ * @param baseDir - Directory the directives' relative paths resolve against
+ * @param seen - Absolute paths already inlined (cycle / duplicate guard)
+ */
+async function inlineTripleSlashReferences(source, baseDir, seen) {
+    const out = [];
+    for (const line of source.split('\n')) {
+        const match = TRIPLE_SLASH_REFERENCE.exec(line);
+        if (!match?.[1]) {
+            out.push(line);
+            continue;
+        }
+        const absolute = resolve(baseDir, match[1]);
+        if (seen.has(absolute))
+            continue;
+        seen.add(absolute);
+        if (!(await pathExists(absolute))) {
+            out.push(`// (fireforge: unresolved /// <reference path="${match[1]}">)`);
+            continue;
+        }
+        const referenced = await readText(absolute);
+        out.push(await inlineTripleSlashReferences(referenced, dirname(absolute), seen));
+    }
+    return out.join('\n');
+}
 /**
  * Composes the synthetic shim source by concatenating the built-in
  * Firefox globals shim with the contents of an optional user-supplied
@@ -95,7 +154,9 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
  * 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.
+ * shim. Any triple-slash `/// <reference path="…">` directives inside the
+ * extra shim are inlined (resolved against the extra shim's own directory)
+ * so they are not silently dropped at the synthetic shim path.
  *
  * Missing extra-shim files raise a clear error rather than failing
  * silently with a confusing "type not found" downstream — this is the
@@ -115,8 +176,9 @@ export async function composeShimSource(projectRoot, extraShimPath) {
             'Check the path in fireforge.json or create the file.');
     }
     const extra = await readText(absoluteShim);
+    const inlinedExtra = await inlineTripleSlashReferences(extra, dirname(absoluteShim), new Set([absoluteShim]));
     return {
-        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${extra}`,
+        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
         extraShimAppended: true,
     };
 }