@hominis/fireforge 0.19.1 → 0.19.3

package/CHANGELOG.md

@@ -5,10 +5,16 @@
 ### Features
 
 - **`patchLint.checkJsStrict` and `patchLint.checkJsCompilerOptions`.** The patch-lint `checkJs` pass now defaults to the historical loose preset (`strict: false`, `noImplicitAny: false`). Set `"patchLint": { "checkJs": true, "checkJsStrict": true }` to enforce `strict` and `noImplicitAny` on patch-owned `.sys.mjs` so implicit-any parameters surface as `checkjs-type-error`, aligning with strict whole-project checkJs without changing module resolution (`noResolve` and `resource://` suppression unchanged). Optional `checkJsCompilerOptions` (requires `checkJsStrict`) merges allowlisted boolean compiler overrides — for example `{ "strictNullChecks": false }` — after the strict preset for gradual adoption. The Firefox globals shim and `SUPPRESSED_DIAGNOSTIC_CODES` remain shared with `fireforge typecheck` via `typecheck-shim.ts`.
+- **`checkJs` — ambient modules for Firefox URL imports.** The shared shim in `typecheck-shim.ts` now includes shorthand `declare module 'resource:*'` and `declare module 'chrome:*'`, matching typical `resource://…` / `chrome://…` specifiers without the broken `Record` + `export=` shape under `moduleResolution` Bundler (which typed dynamic imports as `{ default: … }` and broke `.namedExport` access). Bulk `fireforge re-export` with `patchLint.checkJs` no longer routinely needs `--skip-lint` for `.sys.mjs` queues that lazily URL-import storage and infra helpers.
 
 ### Hardening
 
 - **`modified-file-missing-header` — standard Mozilla MPL-2.0 block headers with wrapped line breaks.** The upstream fallback scan required a contiguous `Mozilla Public License` substring in the first few lines, so files that follow Mozilla’s usual `/* … Mozilla Public` / ` * License, v. 2.0 … */` wrap (including after Emacs/vim directive blocks) were warned despite a valid notice. `containsUpstreamLicenseText` in `src/core/license-headers.ts` now normalizes common block-comment continuation prefixes before matching, so forks need not add SPDX solely to satisfy patch lint.
+- **`fireforge test` — `--marionette-port` auto-forward matches toolkit mochitests and mixed suites.** Auto-forward of `--setpref=marionette.port=<n>` previously keyed off a path heuristic that missed `toolkit/content/tests/**` widget HTML tests (no `/mochitest/` segment), so the preflight could use the operator’s port while mach still defaulted to **2828**. Forwarding now runs whenever `--marionette-port` is set unless `--mach-arg` explicitly includes `--flavor=xpcshell` / `xpcshell-tests` (the pref is unused there). `isMarionetteFlavor` also treats `toolkit/content/tests/` paths as Marionette-relevant unless they sit under `/tests/xpcshell/`, for consistency with other callers of that helper.
+
+### Documentation
+
+- **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation (for example Hominis `AGENT_RULES.md`).
 
 ## 0.18.0
 

package/README.md

@@ -255,7 +255,7 @@ By default, a standalone `fireforge lint` (no arguments) lints the **aggregate**
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
-**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these. By default the pass uses a **loose** compiler preset (`strict: false`, `noImplicitAny: false`) so implicit `any` from untyped parameters does not flood the output. Set `"patchLint": { "checkJsStrict": true }` (requires `checkJs: true`) to enable `strict` and `noImplicitAny` for parity with strict whole-project checkJs — implicit-any parameters then surface as `checkjs-type-error`. Optional `"patchLint": { "checkJsCompilerOptions": { "strictNullChecks": false } }` (requires `checkJsStrict: true`) merges **allowlisted boolean** strict flags after that preset so forks can tighten `noImplicitAny` while relaxing e.g. null checks. The same built-in shim and the same eight suppressed diagnostic codes as `fireforge typecheck` apply; only explicit strictness differs. Projects that need to extend the built-in shim (e.g. for `MozLitElement`, `MozXULElement`, or fork-specific component bases) can point at an additional `.d.ts` via `"patchLint": { "checkJsExtraShim": "tools/types/<fork>-globals.d.ts" }`; the file is concatenated to the built-in shim — augment, don't redeclare.
+**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these; the built-in shim also declares ambient `resource:*` and `chrome:*` modules so lazy `import("resource:-…")` / `import("chrome:-…")` stay loosely typed under `noResolve` instead of degrading into spurious `checkjs-type-error` cascades — refine further with `"patchLint": { "checkJsExtraShim": "..." }`. By default the pass uses a **loose** compiler preset (`strict: false`, `noImplicitAny: false`) so implicit `any` from untyped parameters does not flood the output. Set `"patchLint": { "checkJsStrict": true }` (requires `checkJs: true`) to enable `strict` and `noImplicitAny` for parity with strict whole-project checkJs — implicit-any parameters then surface as `checkjs-type-error`. Optional `"patchLint": { "checkJsCompilerOptions": { "strictNullChecks": false } }` (requires `checkJsStrict: true`) merges **allowlisted boolean** strict flags after that preset so forks can tighten `noImplicitAny` while relaxing e.g. null checks. The same built-in shim and the same eight suppressed diagnostic codes as `fireforge typecheck` apply; only explicit strictness differs. Projects that need to extend the built-in shim (e.g. for `MozLitElement`, `MozXULElement`, or fork-specific component bases) can point at an additional `.d.ts` via `"patchLint": { "checkJsExtraShim": "tools/types/<fork>-globals.d.ts" }`; the file is concatenated to the built-in shim — augment, don't redeclare.
 
 **Whole-project type checking — `fireforge typecheck`.** `patchLint.checkJs` is patch-hygiene: scoped to patch-owned `.sys.mjs`, suppresses module-resolution noise, and runs every time `fireforge lint` runs. With `checkJsStrict`, that pass can match a strict jsconfig's `noImplicitAny` behaviour without replacing full-project resolution. `fireforge typecheck` remains the CI-grade complement: it runs whole projects you point at via `typecheck.projects` in `fireforge.json`, honours each jsconfig's strictness/include/exclude/`paths`, and is intended as a CI gate. The two are complementary; the recommended setup is `fireforge lint` on every patch export and `fireforge typecheck` on CI for the project-level baseline.
 
@@ -638,6 +638,12 @@ xpcshell has a chrome-URI boundary that is worth knowing before writing assertio
 
 The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
 
+### Mochitest stalls and `--marionette-port`
+
+When you pass `--marionette-port <n>`, FireForge uses that port for the stale-listener probe and for `--doctor`, and it forwards `--setpref=marionette.port=<n>` to `mach test` so the harness binds the same port. The only exception is an explicit `--mach-arg --flavor=xpcshell` (or `--flavor=xpcshell-tests`): that harness ignores the pref, so FireForge skips auto-forward and logs a short notice instead. Toolkit widget mochitests under `toolkit/content/tests/` (for example `test_*.html` next to `browser_*.js` suites) therefore stay aligned with the probe without duplicating `--mach-arg=--setpref=marionette.port=…`.
+
+Some forks see mochitests end with **`TEST_END: TIMEOUT`** after on the order of **370 seconds** with **no harness output** — including runs where mozinfo reports `headless: false`, so the failure is not explained by SWGL headless alone. When tests wait on custom chrome (for example a fork tile shell that never sets a `_readyForTesting` gate), the hang is **engine-side**; use your fork’s test docs and `browser.toml` defaults (for Hominis-style trees, see the fork’s `AGENT_RULES.md` for `hominis.testing.*` prefs). Operationally: ensure Marionette port **2828** is free, pass **`--marionette-port`** when you use a non-default port (FireForge keeps preflight and mach consistent as above), and narrow the failure with `--doctor` or by splitting a lighter smoke test that does not depend on full chrome init.
+
 ### Stale-build preflight on `fireforge test`
 
 `fireforge test <path>` (without `--build`) now runs a preflight that diffs engine HEAD and the workdir against the last successful `fireforge build` (recorded at `.fireforge/last-build.json`). When packageable engine files have changed since that baseline, the command prints a single up-front warning naming the paths and pointing at `fireforge test --build`. This catches the class of failure where a newly scaffolded chrome resource or pref file is registered correctly but `obj-*/dist/` still holds the pre-edit bundle, so the test reads stale packaged artifacts and errors out with a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell / mach test. The preflight is warn-only — a fork that rebuilt out-of-band (direct `./mach build`, IDE plugin, separate CI stage) is not blocked. Passing `--build` skips the preflight because the rebuild just refreshed the bundle.

package/dist/src/commands/test.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, } from '../core/mach.js';
-import { assertMarionettePortAvailable, extractForwardedMarionettePort, isMarionetteFlavor, } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, extractForwardedMarionettePort, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
 import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
@@ -326,21 +326,22 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     //
     // Skip forwarding when the operator already supplied an equivalent arg
     // via `--mach-arg` — duplicates would be confusing without changing
-    // semantics. Skip with a notice for clearly-non-marionette flavours
-    // (xpcshell, or paths that don't look browser-chrome/mochitest) so the
-    // operator knows the preflight took the override but mach was not
-    // auto-configured. Same escape valve applies: any mach arg can still
-    // be supplied via `--mach-arg`.
+    // semantics. Skip when mach args explicitly request `--flavor=xpcshell`
+    // (or `xpcshell-tests`): the preflight still honours `--marionette-port`,
+    // but mach does not use the marionette.port pref on that harness. Any
+    // other arg shape still forwards so toolkit widget paths and mixed suites
+    // stay aligned with the probe without duplicate `--mach-arg` flags.
     if (options.marionettePort !== undefined) {
         const operatorAlreadyForwarded = forwardedPort !== undefined;
+        const machArgs = options.machArg ?? [];
         if (operatorAlreadyForwarded) {
             info(`--marionette-port=${options.marionettePort} set, but the same port is already forwarded via --mach-arg; skipping auto-forward.`);
         }
-        else if (isMarionetteFlavor(normalizedPaths, options.machArg ?? [])) {
+        else if (shouldAutoForwardMarionettePortToMach(machArgs)) {
             extraArgs.push(`--setpref=marionette.port=${options.marionettePort}`);
         }
         else {
-            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but the test paths do not look browser-chrome/mochitest — mach is not auto-configured. Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if mach should also use this port.`);
+            info(`--marionette-port=${options.marionettePort} applied to the preflight probe, but --flavor=xpcshell is set — mach is not auto-configured with --setpref=marionette.port (xpcshell ignores that pref). Pass --mach-arg --setpref=marionette.port=${options.marionettePort} explicitly if you still need mach to see the port.`);
         }
     }
     // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
@@ -408,7 +409,7 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         acc.push(value);
         return acc;
     }, [])
-        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and the auto-forwarded --setpref=marionette.port=<n> arg passed to mach. Use this when a stale process holds 2828 or a CI runner reserves a different port.', (raw) => {
+        .option('--marionette-port <port>', 'Override the Marionette control port (default 2828) for the stale-browser probe, the --doctor preflight, and (unless --mach-arg includes --flavor=xpcshell) the auto-forwarded --setpref=marionette.port=<n> passed to mach. Use this when a stale process holds 2828 or a CI runner reserves a different port.', (raw) => {
         const n = Number.parseInt(raw, 10);
         if (!Number.isFinite(n) || n < 1 || n > 65535) {
             throw new GeneralError(`--marionette-port must be an integer in 1..65535 (got "${raw}")`);

package/dist/src/core/marionette-port.d.ts

@@ -64,13 +64,31 @@ export declare function assertMarionettePortAvailable(port?: number, options?: {
  *   `undefined`.
  */
 export declare function extractForwardedMarionettePort(machArgs: string[]): number | undefined;
+/**
+ * True when forwarded mach args explicitly select the xpcshell harness.
+ * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
+ * for runs where the pref is ignored anyway.
+ */
+export declare function hasExplicitXpcshellFlavor(machArgs: string[]): boolean;
+/**
+ * Whether `fireforge test` should append `--setpref=marionette.port=<n>` when
+ * the operator passed `--marionette-port`. Forwards for every harness except
+ * an explicit `--flavor=xpcshell` / `xpcshell-tests` (toolkit widget mochitests
+ * under `toolkit/content/tests/` do not match the older path-only heuristic
+ * but still launch a Marionette-driven browser).
+ */
+export declare function shouldAutoForwardMarionettePortToMach(machArgs: string[]): boolean;
 /**
  * Heuristic: do the test paths or forwarded mach args indicate a flavour
  * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. Used to decide whether to auto-forward
- * `--setpref=marionette.port=<n>` to mach when the operator passed
- * `--marionette-port`. A no-paths invocation (the default "run all tests"
- * shape) is treated as marionette-relevant since it includes browser-chrome.
+ * mochitest do; xpcshell does not. A no-paths invocation (the default "run
+ * all tests" shape) is treated as marionette-relevant since it includes
+ * browser-chrome.
+ *
+ * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
+ * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
+ * than this function alone, so toolkit paths without `/mochitest/` still get
+ * the pref when appropriate.
  *
  * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
  * @param machArgs - Forwarded mach args (post-`--mach-arg`).

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

@@ -260,23 +260,47 @@ export function extractForwardedMarionettePort(machArgs) {
     }
     return undefined;
 }
+/**
+ * True when forwarded mach args explicitly select the xpcshell harness.
+ * Used so `--marionette-port` auto-forward skips `--setpref=marionette.port`
+ * for runs where the pref is ignored anyway.
+ */
+export function hasExplicitXpcshellFlavor(machArgs) {
+    for (const arg of machArgs) {
+        if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `fireforge test` should append `--setpref=marionette.port=<n>` when
+ * the operator passed `--marionette-port`. Forwards for every harness except
+ * an explicit `--flavor=xpcshell` / `xpcshell-tests` (toolkit widget mochitests
+ * under `toolkit/content/tests/` do not match the older path-only heuristic
+ * but still launch a Marionette-driven browser).
+ */
+export function shouldAutoForwardMarionettePortToMach(machArgs) {
+    return !hasExplicitXpcshellFlavor(machArgs);
+}
 /**
  * Heuristic: do the test paths or forwarded mach args indicate a flavour
  * that actually launches a Marionette-driven browser? Browser-chrome and
- * mochitest do; xpcshell does not. Used to decide whether to auto-forward
- * `--setpref=marionette.port=<n>` to mach when the operator passed
- * `--marionette-port`. A no-paths invocation (the default "run all tests"
- * shape) is treated as marionette-relevant since it includes browser-chrome.
+ * mochitest do; xpcshell does not. A no-paths invocation (the default "run
+ * all tests" shape) is treated as marionette-relevant since it includes
+ * browser-chrome.
+ *
+ * Note: `fireforge test` auto-forward of `--marionette-port` to mach uses
+ * {@link shouldAutoForwardMarionettePortToMach} (mach-arg flavor gate) rather
+ * than this function alone, so toolkit paths without `/mochitest/` still get
+ * the pref when appropriate.
  *
  * @param testPaths - Engine-relative paths after `stripEnginePrefix`.
  * @param machArgs - Forwarded mach args (post-`--mach-arg`).
  * @returns `true` when the run is likely to bind a Marionette listener.
  */
 export function isMarionetteFlavor(testPaths, machArgs) {
-    for (const arg of machArgs) {
-        if (/^--flavor=xpcshell\b/.test(arg) || arg === '--flavor=xpcshell-tests')
-            return false;
-    }
+    if (hasExplicitXpcshellFlavor(machArgs))
+        return false;
     for (const arg of machArgs) {
         if (/^--flavor=(browser-chrome|mochitest|chrome|a11y)\b/.test(arg))
             return true;
@@ -291,6 +315,9 @@ export function isMarionetteFlavor(testPaths, machArgs) {
             return true;
         if (path.includes('/browser-chrome/') || path.startsWith('browser-chrome/'))
             return true;
+        if (path.includes('toolkit/content/tests/') && !path.includes('/tests/xpcshell/')) {
+            return true;
+        }
     }
     return false;
 }

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

@@ -26,8 +26,12 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * - `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";
+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

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

@@ -29,6 +29,10 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * - `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 const FIREFOX_GLOBALS_SHIM = `
 declare var Services: any;
@@ -54,6 +58,13 @@ declare var gBrowser: any;
 declare var gURLBar: any;
 declare var gNavigatorBundle: any;
 declare var AppConstants: any;
+
+// Shorthand ambient modules — exports from matching URL imports are loosely typed,
+// avoiding noResolve empty-graph namespaces. (Named member access broke when we tried
+// export= Record under moduleResolution Bundler.)
+declare module 'resource:*';
+declare module 'chrome:*';
+
 `;
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass

package/dist/src/types/commands/options.d.ts

@@ -319,9 +319,10 @@ export interface TestOptions {
     /**
      * Override the Marionette control port (default 2828) used by the
      * stale-browser probe, the `--doctor` preflight, and the auto-forwarded
-     * `--setpref=marionette.port=<n>` arg passed to mach. Set this when a
-     * stale process holds the default port and `kill` is not an option, or
-     * when a CI runner reserves a different port for parallel test runs.
+     * `--setpref=marionette.port=<n>` arg passed to mach (omitted when mach
+     * args explicitly set `--flavor=xpcshell` / `xpcshell-tests`). Set this
+     * when a stale process holds the default port and `kill` is not an option,
+     * or when a CI runner reserves a different port for parallel test runs.
      */
     marionettePort?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",