@hominis/fireforge 0.18.8 → 0.18.9

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 } from '../core/marionette-port.js';
+import { assertMarionettePortAvailable, extractForwardedMarionettePort, isMarionetteFlavor, } 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';
@@ -238,6 +238,20 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             warn(formatStaleBuildWarning(stale));
         }
     }
+    // Resolve the effective Marionette port. Operator precedence:
+    //   1. `--marionette-port` (first-class option, parsed at the CLI layer)
+    //   2. forwarded `--mach-arg --marionette-port=NNNN` /
+    //      `--mach-arg --setpref=marionette.port=NNNN`
+    //   3. fall back to `DEFAULT_MARIONETTE_PORT` semantics inside the probes
+    //      (passed as `undefined`).
+    // Without (2), an operator working around a stale listener via the
+    // documented `--mach-arg --marionette-port=NNNN` workaround would still
+    // hit the wrapper preflight refusing on 2828 before the forwarded arg
+    // ever reached mach.
+    const forwardedPort = options.machArg
+        ? extractForwardedMarionettePort(options.machArg)
+        : undefined;
+    const effectivePort = options.marionettePort ?? forwardedPort;
     // Stale-browser probe: an interrupted earlier test run can leave a
     // Firefox/ForgeFresh/Hominis instance listening on the Marionette
     // control port, which breaks the next mach test launch with a
@@ -246,7 +260,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // generic bind failure. 2026-04-21 eval (Finding #20): a stale
     // `-marionette` process from `fresh/` poisoned a later test run in
     // the sibling `hominis/` workspace.
-    await assertMarionettePortAvailable(undefined, { binaryName: projectConfig.binaryName });
+    await assertMarionettePortAvailable(effectivePort, { binaryName: projectConfig.binaryName });
     // `--doctor` runs a short marionette handshake probe. When test paths are
     // supplied the probe gates the mach test invocation (a FAIL bails out). When
     // no paths are supplied this is the only step — it's the fastest way to tell
@@ -259,7 +273,9 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         // clack box-drawing framing.
         process.stdout.write('Running marionette preflight...\n');
         info('Running marionette preflight...');
-        const preflight = await runMarionettePreflight(paths.engine);
+        const preflight = effectivePort !== undefined
+            ? await runMarionettePreflight(paths.engine, { port: effectivePort })
+            : await runMarionettePreflight(paths.engine);
         // 2026-04-24 eval Finding 7: the pre-0.18.1 code used
         // `success()` + `outro()` + a direct `process.stdout.write` as a
         // belt-and-suspenders but still reproducibly dropped the PASS summary
@@ -303,6 +319,30 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (options.machArg && options.machArg.length > 0) {
         extraArgs.push(...options.machArg);
     }
+    // Auto-forward the Marionette port to mach when `--marionette-port` is
+    // set. We use `--setpref=marionette.port=<n>` because the marionette
+    // listener reads that pref before binding (browser-chrome / mochitest
+    // path); xpcshell never reads it, so the pref is a no-op there.
+    //
+    // 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`.
+    if (options.marionettePort !== undefined) {
+        const operatorAlreadyForwarded = forwardedPort !== undefined;
+        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 ?? [])) {
+            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.`);
+        }
+    }
     // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
     // full motivation. On rebranded forks (appname != "firefox") the upstream
     // harness silently ignores `firefox-appdir = "browser"` directives in the
@@ -368,6 +408,13 @@ 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) => {
+        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}")`);
+        }
+        return n;
+    })
         .action(withErrorHandling(async (paths, options) => {
         await testCommand(getProjectRoot(), paths, pickDefined(options));
     }));

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

@@ -15,8 +15,12 @@ export type AcornESTreeNode<T extends estree.Node = estree.Node> = T & {
  * Parse JavaScript source as a **script** (not an ES module).
  * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
+ *
+ * @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 parseScript(content: string): AcornESTreeNode<estree.Program>;
+export declare function parseScript(content: string, onComment?: acorn.Comment[]): AcornESTreeNode<estree.Program>;
 /**
  * Parse JavaScript source as an **ES module**.
  * Used for `.sys.mjs` files which use static import/export syntax.

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

@@ -5,12 +5,19 @@ import { walk } from 'estree-walker';
  * Parse JavaScript source as a **script** (not an ES module).
  * All Mozilla chrome JS files (`browser-main.js`, `browser-init.js`,
  * `customElements.js`, etc.) are scripts that run in a privileged scope.
+ *
+ * @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 parseScript(content) {
-    return acorn.parse(content, {
+export function parseScript(content, onComment) {
+    const opts = {
         sourceType: 'script',
         ecmaVersion: 'latest',
-    });
+    };
+    if (onComment)
+        opts.onComment = onComment;
+    return acorn.parse(content, opts);
 }
 /**
  * Parse JavaScript source as an **ES module**.

package/dist/src/core/build-audit-resolve.d.ts

@@ -2,9 +2,11 @@
  * Heuristic test for "this looks like a packaged-test source file" — the
  * audit routes such paths to `_tests/` instead of `dist/`. Matches
  * mochitest / xpcshell / browser-chrome conventions: any source under a
- * `/test/` or `/tests/` directory, or with a `browser_` / `test_` prefix
- * on a `.js`/`.toml` basename. Test manifests (`*.toml`, `*.list`,
- * `*.ini`) under those directories also qualify.
+ * `/test/` or `/tests/` directory, anywhere under a `testing/` subtree
+ * (which holds mochitest / marionette / xpcshell harness sources), or
+ * with a `browser_` / `test_` prefix on a `.js`/`.toml` basename. Test
+ * manifests (`*.toml`, `*.list`, `*.ini`) under those directories also
+ * qualify.
  *
  * @param sourcePath Engine-relative POSIX path
  * @returns True when the file belongs to the test tree, not the bundle

package/dist/src/core/build-audit-resolve.js

@@ -30,9 +30,11 @@ const MAX_SCAN_DEPTH = 12;
  * Heuristic test for "this looks like a packaged-test source file" — the
  * audit routes such paths to `_tests/` instead of `dist/`. Matches
  * mochitest / xpcshell / browser-chrome conventions: any source under a
- * `/test/` or `/tests/` directory, or with a `browser_` / `test_` prefix
- * on a `.js`/`.toml` basename. Test manifests (`*.toml`, `*.list`,
- * `*.ini`) under those directories also qualify.
+ * `/test/` or `/tests/` directory, anywhere under a `testing/` subtree
+ * (which holds mochitest / marionette / xpcshell harness sources), or
+ * with a `browser_` / `test_` prefix on a `.js`/`.toml` basename. Test
+ * manifests (`*.toml`, `*.list`, `*.ini`) under those directories also
+ * qualify.
  *
  * @param sourcePath Engine-relative POSIX path
  * @returns True when the file belongs to the test tree, not the bundle
@@ -41,6 +43,13 @@ export function isTestPath(sourcePath) {
     if (sourcePath.includes('/test/') || sourcePath.includes('/tests/')) {
         return true;
     }
+    // `testing/{mochitest,marionette,xpcshell,...}` are test-infrastructure
+    // trees that ship under `_tests/`, not `dist/`. Match both as a root
+    // segment (e.g. `testing/mochitest/api.js`) and as an interior segment
+    // (e.g. a vendored harness under `third_party/.../testing/...`).
+    if (sourcePath.startsWith('testing/') || sourcePath.includes('/testing/')) {
+        return true;
+    }
     const name = basename(sourcePath);
     if (/^browser_.+\.(js|toml|ini)$/.test(name))
         return true;

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

@@ -19,7 +19,7 @@ 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", "patchLint", "markerComment"];
 /** 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", "patchLint", "patchLint.checkJs", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "markerComment"];
+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", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

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

@@ -49,6 +49,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'patchLint.rawColorAllowlist',
     'patchLint.jsdocClassMethods',
     'patchLint.testAssertionFloor',
+    'patchLint.chromeScriptJsDoc',
     'markerComment',
 ];
 /**

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

@@ -229,6 +229,10 @@ function parsePatchLintBlock(rec) {
     if (testAssertionFloor !== undefined) {
         out.testAssertionFloor = testAssertionFloor;
     }
+    const chromeScriptJsDoc = parseSeverityGate(rec.raw('chromeScriptJsDoc'), 'patchLint.chromeScriptJsDoc');
+    if (chromeScriptJsDoc !== undefined) {
+        out.chromeScriptJsDoc = chromeScriptJsDoc;
+    }
     return out;
 }
 //# sourceMappingURL=config-validate.js.map

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

@@ -48,3 +48,32 @@ export declare function probeMarionettePort(port?: number): Promise<MarionettePo
 export declare function assertMarionettePortAvailable(port?: number, options?: {
     binaryName?: string;
 }): Promise<void>;
+/**
+ * Extracts a `--marionette-port=N` (or `--marionette-port N`) argument from
+ * a list of forwarded mach args, if present. Used so an operator passing the
+ * port via `--mach-arg --marionette-port=NNNN` gets the same preflight
+ * override they would from a first-class `--marionette-port` option, rather
+ * than the wrapper probing the default port and refusing.
+ *
+ * Also recognises `--setpref=marionette.port=NNNN` since that is the path
+ * the test command auto-forwards to mach.
+ *
+ * @param machArgs - Forwarded mach args as they would appear on the command
+ *   line (one element per token; `--foo=bar` and `--foo bar` both supported).
+ * @returns The integer port if a recognised arg is present and parses; else
+ *   `undefined`.
+ */
+export declare function extractForwardedMarionettePort(machArgs: string[]): number | undefined;
+/**
+ * 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.
+ *
+ * @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 declare function isMarionetteFlavor(testPaths: string[], machArgs: string[]): boolean;

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

@@ -212,4 +212,86 @@ export async function assertMarionettePortAvailable(port = DEFAULT_MARIONETTE_PO
     throw new GeneralError(`Marionette port ${port} is already in use by ${holder.command} (PID ${holder.pid}). ` +
         `This is not a FireForge-launched browser; stop the holder process or free the port before rerunning.`);
 }
+/**
+ * Extracts a `--marionette-port=N` (or `--marionette-port N`) argument from
+ * a list of forwarded mach args, if present. Used so an operator passing the
+ * port via `--mach-arg --marionette-port=NNNN` gets the same preflight
+ * override they would from a first-class `--marionette-port` option, rather
+ * than the wrapper probing the default port and refusing.
+ *
+ * Also recognises `--setpref=marionette.port=NNNN` since that is the path
+ * the test command auto-forwards to mach.
+ *
+ * @param machArgs - Forwarded mach args as they would appear on the command
+ *   line (one element per token; `--foo=bar` and `--foo bar` both supported).
+ * @returns The integer port if a recognised arg is present and parses; else
+ *   `undefined`.
+ */
+export function extractForwardedMarionettePort(machArgs) {
+    for (let i = 0; i < machArgs.length; i++) {
+        const arg = machArgs[i];
+        if (arg === undefined)
+            continue;
+        // `--marionette-port=NNNN`
+        let match = /^--marionette-port=(\d+)$/.exec(arg);
+        if (match?.[1]) {
+            const n = Number.parseInt(match[1], 10);
+            if (Number.isFinite(n))
+                return n;
+        }
+        // `--marionette-port NNNN` (two tokens)
+        if (arg === '--marionette-port') {
+            const next = machArgs[i + 1];
+            if (next !== undefined) {
+                const n = Number.parseInt(next, 10);
+                if (Number.isFinite(n))
+                    return n;
+            }
+        }
+        // `--setpref=marionette.port=NNNN` — the auto-forward shape; recognised
+        // here so a duplicate check at the call site can spot operator-supplied
+        // setprefs without re-implementing the parse.
+        match = /^--setpref=marionette\.port=(\d+)$/.exec(arg);
+        if (match?.[1]) {
+            const n = Number.parseInt(match[1], 10);
+            if (Number.isFinite(n))
+                return n;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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.
+ *
+ * @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;
+    }
+    for (const arg of machArgs) {
+        if (/^--flavor=(browser-chrome|mochitest|chrome|a11y)\b/.test(arg))
+            return true;
+    }
+    if (testPaths.length === 0)
+        return true;
+    for (const path of testPaths) {
+        const base = path.split('/').pop() ?? path;
+        if (/^browser_.+\.(js|ini|toml)$/.test(base))
+            return true;
+        if (path.includes('/mochitest/') || path.startsWith('mochitest/'))
+            return true;
+        if (path.includes('/browser-chrome/') || path.startsWith('browser-chrome/'))
+            return true;
+    }
+    return false;
+}
 //# sourceMappingURL=marionette-port.js.map

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

@@ -0,0 +1,47 @@
+/**
+ * AST-based JSDoc validation for top-level declarations in patch-owned
+ * chrome subscripts (`browser/base/content/<binaryName>*.js` and similar
+ * `.js` files loaded via `Services.scriptloader.loadSubScript`).
+ *
+ * Why a separate module from {@link ./patch-lint-jsdoc.ts}: chrome
+ * subscripts are NOT ES modules. They are parsed as scripts (no static
+ * `export`) and their top-level `class`/`function` declarations are
+ * exposed to the loading window as globals rather than declared exports.
+ * The export-walker in `patch-lint-jsdoc.ts` would never visit them.
+ *
+ * The rule shape — "every top-level class needs a JSDoc, every method
+ * needs one when `chromeScriptJsDoc` is at `warning`/`error`, every
+ * top-level function needs a matching @param/@returns block" — is
+ * identical to the `.sys.mjs` rule once you remove the `export` framing,
+ * so the per-declaration validators are reused verbatim from the export
+ * module.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { PatchLintSeverityGate } from '../types/config.js';
+import type { JsDocIssue, ValidateExportJsDocOptions } from './patch-lint-jsdoc.js';
+/**
+ * Validates JSDoc on top-level declarations in a chrome-subscript `.js`
+ * source file. A parse failure returns an empty issue list — chrome
+ * subscripts that use module-only syntax (rare) silently disable the
+ * rule rather than emitting confusing parse-error issues.
+ *
+ * @param source - File content
+ * @param options - Optional gates (e.g. class-method JSDoc severity).
+ *   `classMethodMode` defaults to `'off'` — the orchestrator passes the
+ *   `chromeScriptJsDoc` severity here so a single knob controls both
+ *   class-level and method-level enforcement.
+ * @returns Array of JSDoc issues found
+ */
+export declare function validateChromeScriptJsDoc(source: string, options?: ValidateExportJsDocOptions): JsDocIssue[];
+/**
+ * Per-file dispatch: applies the chrome-subscript JSDoc rule to one file
+ * if it qualifies, mapping {@link JsDocIssue} into {@link PatchLintIssue}.
+ * Extracted so the orchestrator in `patch-lint.ts` stays under the
+ * project's per-file line budget — `patch-lint.ts` invokes this helper
+ * inline once per affected JS/MJS file. Returns an empty array when the
+ * file does not qualify (not a chrome subscript, not patch-owned, or the
+ * mode is `'off'` / unset). The orchestrator pre-computes `isChromeOwned`
+ * (true iff the file is a patch-owned `.js` non-`.sys.mjs`) so the call
+ * site fits on a single line.
+ */
+export declare function lintChromeScriptJsDocForFile(file: string, content: string, isChromeOwned: boolean, mode: PatchLintSeverityGate | undefined): PatchLintIssue[];

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

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * AST-based JSDoc validation for top-level declarations in patch-owned
+ * chrome subscripts (`browser/base/content/<binaryName>*.js` and similar
+ * `.js` files loaded via `Services.scriptloader.loadSubScript`).
+ *
+ * Why a separate module from {@link ./patch-lint-jsdoc.ts}: chrome
+ * subscripts are NOT ES modules. They are parsed as scripts (no static
+ * `export`) and their top-level `class`/`function` declarations are
+ * exposed to the loading window as globals rather than declared exports.
+ * The export-walker in `patch-lint-jsdoc.ts` would never visit them.
+ *
+ * The rule shape — "every top-level class needs a JSDoc, every method
+ * needs one when `chromeScriptJsDoc` is at `warning`/`error`, every
+ * top-level function needs a matching @param/@returns block" — is
+ * identical to the `.sys.mjs` rule once you remove the `export` framing,
+ * so the per-declaration validators are reused verbatim from the export
+ * module.
+ */
+import { parseScript } from './ast-utils.js';
+import { validateClassDecl, validateClassMethods, validateFunctionDecl, } from './patch-lint-jsdoc.js';
+/**
+ * Validates JSDoc on top-level declarations in a chrome-subscript `.js`
+ * source file. A parse failure returns an empty issue list — chrome
+ * subscripts that use module-only syntax (rare) silently disable the
+ * rule rather than emitting confusing parse-error issues.
+ *
+ * @param source - File content
+ * @param options - Optional gates (e.g. class-method JSDoc severity).
+ *   `classMethodMode` defaults to `'off'` — the orchestrator passes the
+ *   `chromeScriptJsDoc` severity here so a single knob controls both
+ *   class-level and method-level enforcement.
+ * @returns Array of JSDoc issues found
+ */
+export function validateChromeScriptJsDoc(source, options) {
+    const classMethodMode = options?.classMethodMode ?? 'off';
+    const comments = [];
+    let ast;
+    try {
+        ast = parseScript(source, comments);
+    }
+    catch {
+        return [];
+    }
+    const issues = [];
+    const body = ast.body;
+    for (const node of body) {
+        if (node.type === 'FunctionDeclaration') {
+            validateFunctionDecl(node, comments, source, issues);
+        }
+        else if (node.type === 'ClassDeclaration') {
+            validateClassDecl(node, comments, source, issues);
+            if (classMethodMode !== 'off') {
+                validateClassMethods(node, comments, source, issues, classMethodMode);
+            }
+        }
+        // Top-level `var Foo = class {...}` / `let Foo = function() {...}`
+        // patterns are intentionally out of scope for V1 — chrome subscripts
+        // overwhelmingly use bare `class`/`function` declarations and the
+        // variable-init form would require unwrapping the initializer. Add
+        // it later if a real chrome subscript uses that shape.
+    }
+    return issues;
+}
+/**
+ * Per-file dispatch: applies the chrome-subscript JSDoc rule to one file
+ * if it qualifies, mapping {@link JsDocIssue} into {@link PatchLintIssue}.
+ * Extracted so the orchestrator in `patch-lint.ts` stays under the
+ * project's per-file line budget — `patch-lint.ts` invokes this helper
+ * inline once per affected JS/MJS file. Returns an empty array when the
+ * file does not qualify (not a chrome subscript, not patch-owned, or the
+ * mode is `'off'` / unset). The orchestrator pre-computes `isChromeOwned`
+ * (true iff the file is a patch-owned `.js` non-`.sys.mjs`) so the call
+ * site fits on a single line.
+ */
+export function lintChromeScriptJsDocForFile(file, content, isChromeOwned, mode) {
+    if (!isChromeOwned || !mode || mode === 'off')
+        return [];
+    const jsdocIssues = validateChromeScriptJsDoc(content, { classMethodMode: mode });
+    return jsdocIssues.map((issue) => ({
+        file,
+        check: issue.check,
+        message: issue.message,
+        severity: issue.severity ?? mode,
+    }));
+}
+//# sourceMappingURL=patch-lint-chrome-jsdoc.js.map

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

@@ -6,6 +6,9 @@
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget.
  */
+import type * as acorn from 'acorn';
+import type { ClassDeclaration, FunctionDeclaration } from 'estree';
+import type { AcornESTreeNode } from './ast-utils.js';
 export type JsDocCheck = 'missing-jsdoc' | 'jsdoc-param-mismatch' | 'jsdoc-missing-returns' | 'missing-jsdoc-class-method' | 'jsdoc-class-method-param-mismatch' | 'jsdoc-class-method-missing-returns';
 export interface JsDocIssue {
     line: number;
@@ -19,6 +22,40 @@ export interface ValidateExportJsDocOptions {
     /** Gate for class-method JSDoc enforcement. Default 'off' (no walking). */
     classMethodMode?: ClassMethodMode;
 }
+/**
+ * Validates a top-level function declaration: requires an attached JSDoc
+ * comment, then checks @param name matching and @returns presence. Exported
+ * so the chrome-subscript validator (`patch-lint-chrome-jsdoc.ts`) can reuse
+ * it on `parseScript`-produced declarations — the rule shape is identical
+ * between ES-module exports and chrome-subscript top-level declarations.
+ *
+ * @param fn - FunctionDeclaration AST node
+ * @param comments - All Acorn comments collected from the source
+ * @param source - Original source text (for line-number resolution)
+ * @param issues - Output sink for JSDoc issues
+ * @param lookupStart - Optional offset to use when locating the attached
+ *   JSDoc (defaults to `fn.start`). Used by the export-walker so the JSDoc
+ *   is found relative to the `export` keyword rather than the inner decl.
+ */
+export declare function validateFunctionDecl(fn: AcornESTreeNode<FunctionDeclaration>, comments: acorn.Comment[], source: string, issues: JsDocIssue[], lookupStart?: number): void;
+/**
+ * Validates a top-level class declaration: requires an attached JSDoc
+ * comment on the class itself. Method-level checks live in
+ * {@link validateClassMethods}. Exported for reuse in the chrome-subscript
+ * validator.
+ */
+export declare function validateClassDecl(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, issues: JsDocIssue[], lookupStart?: number): void;
+/**
+ * Walks an exported class body and emits class-method JSDoc issues per
+ * the configured severity. Skip rules (in evaluation order):
+ *   1. private syntax (`#foo`) and underscore-prefixed names
+ *   2. zero-parameter constructors
+ *   3. methods whose JSDoc carries `@private` or `@internal`
+ *
+ * Pure-override skip (`super.method(...args)`-only bodies bypassing the
+ * @returns check) is deferred — V1 keeps the rule simple.
+ */
+export declare function validateClassMethods(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, issues: JsDocIssue[], severity: 'warning' | 'error'): void;
 /**
  * Validates JSDoc on exported declarations in a `.sys.mjs` source file.
  *

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

@@ -166,7 +166,22 @@ function validateParamsAndReturns(fnNode, jsDoc, issues, ctx) {
 // ---------------------------------------------------------------------------
 // Top-level export validation
 // ---------------------------------------------------------------------------
-function validateFunctionDecl(fn, comments, source, issues, lookupStart) {
+/**
+ * Validates a top-level function declaration: requires an attached JSDoc
+ * comment, then checks @param name matching and @returns presence. Exported
+ * so the chrome-subscript validator (`patch-lint-chrome-jsdoc.ts`) can reuse
+ * it on `parseScript`-produced declarations — the rule shape is identical
+ * between ES-module exports and chrome-subscript top-level declarations.
+ *
+ * @param fn - FunctionDeclaration AST node
+ * @param comments - All Acorn comments collected from the source
+ * @param source - Original source text (for line-number resolution)
+ * @param issues - Output sink for JSDoc issues
+ * @param lookupStart - Optional offset to use when locating the attached
+ *   JSDoc (defaults to `fn.start`). Used by the export-walker so the JSDoc
+ *   is found relative to the `export` keyword rather than the inner decl.
+ */
+export function validateFunctionDecl(fn, comments, source, issues, lookupStart) {
     const name = fn.id.name;
     const start = lookupStart !== undefined ? lookupStart : fn.start;
     const line = lineAt(source, start);
@@ -186,7 +201,13 @@ function validateFunctionDecl(fn, comments, source, issues, lookupStart) {
         returnsCheck: 'jsdoc-missing-returns',
     });
 }
-function validateClassDecl(cls, comments, source, issues, lookupStart) {
+/**
+ * Validates a top-level class declaration: requires an attached JSDoc
+ * comment on the class itself. Method-level checks live in
+ * {@link validateClassMethods}. Exported for reuse in the chrome-subscript
+ * validator.
+ */
+export function validateClassDecl(cls, comments, source, issues, lookupStart) {
     const name = cls.id.name;
     const start = lookupStart !== undefined ? lookupStart : cls.start;
     const line = lineAt(source, start);
@@ -254,7 +275,7 @@ function classMethodLabel(className, method, name) {
  * Pure-override skip (`super.method(...args)`-only bodies bypassing the
  * @returns check) is deferred — V1 keeps the rule simple.
  */
-function validateClassMethods(cls, comments, source, issues, severity) {
+export function validateClassMethods(cls, comments, source, issues, severity) {
     const className = cls.id.name;
     for (const member of cls.body.body) {
         if (member.type !== 'MethodDefinition')

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

@@ -1,10 +1,17 @@
 /**
- * Patch ownership resolution for `.sys.mjs` files.
+ * Patch ownership resolution for JS-shaped files.
  *
  * A file is "patch-owned" when it was created by the project's patch
  * queue rather than being an upstream Firefox file that happens to be
- * modified. This module computes the set of patch-owned `.sys.mjs`
- * paths so lint rules can scope enforcement to project code only.
+ * modified. This module computes the set of patch-owned paths so lint
+ * rules can scope enforcement to project code only.
+ *
+ * The two resolvers are kept separate (one per extension predicate)
+ * because the downstream rules differ: `.sys.mjs` files go through
+ * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule;
+ * chrome subscripts (`.js` non-`.sys.mjs`) only get the script-walker
+ * JSDoc rule. Mixing them in a single set would silently broaden
+ * `runCheckJs` to chrome subscripts, which it is not designed for.
  */
 import type { PatchQueueContext } from './patch-lint-cross.js';
 /**
@@ -23,3 +30,14 @@ import type { PatchQueueContext } from './patch-lint-cross.js';
  * @returns Set of patch-owned `.sys.mjs` file paths
  */
 export declare function resolvePatchOwnedSysMjs(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;
+/**
+ * Returns the set of file paths that are patch-owned chrome subscripts
+ * (`.js` files that are not `.sys.mjs` modules — typically
+ * `browser/base/content/<binaryName>*.js` and similar). Same ownership
+ * semantics as {@link resolvePatchOwnedSysMjs}.
+ *
+ * @param currentNewFiles - Files newly created in the current diff
+ * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
+ * @returns Set of patch-owned chrome-subscript file paths
+ */
+export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;

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

@@ -1,13 +1,41 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patch ownership resolution for `.sys.mjs` files.
+ * Patch ownership resolution for JS-shaped files.
  *
  * A file is "patch-owned" when it was created by the project's patch
  * queue rather than being an upstream Firefox file that happens to be
- * modified. This module computes the set of patch-owned `.sys.mjs`
- * paths so lint rules can scope enforcement to project code only.
+ * modified. This module computes the set of patch-owned paths so lint
+ * rules can scope enforcement to project code only.
+ *
+ * The two resolvers are kept separate (one per extension predicate)
+ * because the downstream rules differ: `.sys.mjs` files go through
+ * `runCheckJs` (TypeScript checkJs) and the export-walker JSDoc rule;
+ * chrome subscripts (`.js` non-`.sys.mjs`) only get the script-walker
+ * JSDoc rule. Mixing them in a single set would silently broaden
+ * `runCheckJs` to chrome subscripts, which it is not designed for.
  */
 import { collectNewFileCreatorsByPath } from './patch-lint-cross.js';
+/**
+ * Returns the set of patch-owned files matching `predicate`. Internal
+ * helper shared by the per-extension resolvers below.
+ */
+function resolveOwned(currentNewFiles, patchQueueCtx, predicate) {
+    const owned = new Set();
+    for (const file of currentNewFiles) {
+        if (predicate(file)) {
+            owned.add(file);
+        }
+    }
+    if (patchQueueCtx) {
+        const creators = collectNewFileCreatorsByPath(patchQueueCtx);
+        for (const [file, owners] of creators) {
+            if (predicate(file) && owners.length > 0) {
+                owned.add(file);
+            }
+        }
+    }
+    return owned;
+}
 /**
  * Returns the set of file paths that are patch-owned `.sys.mjs` files.
  *
@@ -24,20 +52,19 @@ import { collectNewFileCreatorsByPath } from './patch-lint-cross.js';
  * @returns Set of patch-owned `.sys.mjs` file paths
  */
 export function resolvePatchOwnedSysMjs(currentNewFiles, patchQueueCtx) {
-    const owned = new Set();
-    for (const file of currentNewFiles) {
-        if (file.endsWith('.sys.mjs')) {
-            owned.add(file);
-        }
-    }
-    if (patchQueueCtx) {
-        const creators = collectNewFileCreatorsByPath(patchQueueCtx);
-        for (const [file, owners] of creators) {
-            if (file.endsWith('.sys.mjs') && owners.length > 0) {
-                owned.add(file);
-            }
-        }
-    }
-    return owned;
+    return resolveOwned(currentNewFiles, patchQueueCtx, (file) => file.endsWith('.sys.mjs'));
+}
+/**
+ * Returns the set of file paths that are patch-owned chrome subscripts
+ * (`.js` files that are not `.sys.mjs` modules — typically
+ * `browser/base/content/<binaryName>*.js` and similar). Same ownership
+ * semantics as {@link resolvePatchOwnedSysMjs}.
+ *
+ * @param currentNewFiles - Files newly created in the current diff
+ * @param patchQueueCtx - Optional cross-patch context for queue-wide ownership
+ * @returns Set of patch-owned chrome-subscript file paths
+ */
+export function resolvePatchOwnedChromeScripts(currentNewFiles, patchQueueCtx) {
+    return resolveOwned(currentNewFiles, patchQueueCtx, (file) => file.endsWith('.js') && !file.endsWith('.sys.mjs'));
 }
 //# sourceMappingURL=patch-lint-ownership.js.map

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

@@ -5,7 +5,7 @@ export { runCheckJs } from './patch-lint-checkjs.js';
 export { buildPatchQueueContext, collectNewFileCreatorsByPath, type ExtractedSpecifier, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 export { type JsDocCheck, type JsDocIssue, validateExportJsDoc } from './patch-lint-jsdoc.js';
-export { resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+export { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 /**
  * Counts the total lines in a unified diff and the number of non-binary
  * text lines, so binary hunks do not inflate patch size checks.
@@ -55,9 +55,14 @@ export declare function lintNewFileHeaders(repoDir: string, newFiles: string[],
  * @param newFiles - Set of files that are newly created in this patch
  * @param config - Project configuration
  * @param patchOwnedFiles - Optional set of patch-owned `.sys.mjs` paths for scoped JSDoc enforcement
+ * @param patchOwnedChromeScripts - Optional set of patch-owned chrome
+ *   subscripts (`.js` non-`.sys.mjs`) for scoped chrome-script JSDoc
+ *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}; passed
+ *   separately from `patchOwnedFiles` so the `runCheckJs` consumer (which
+ *   only accepts `.sys.mjs`) is not silently broadened.
  * @returns Array of lint issues
  */
-export declare function lintPatchedJs(repoDir: string, affectedFiles: string[], newFiles: Set<string>, config: FireForgeConfig, patchOwnedFiles?: Set<string>): Promise<PatchLintIssue[]>;
+export declare function lintPatchedJs(repoDir: string, affectedFiles: string[], newFiles: Set<string>, config: FireForgeConfig, patchOwnedFiles?: Set<string>, patchOwnedChromeScripts?: Set<string>): Promise<PatchLintIssue[]>;
 /**
  * Checks that modifications to existing (non-new) JS/MJS files include at
  * least one `// BINARYNAME:` comment in the added lines.

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

@@ -7,10 +7,11 @@ import { hasRawCssColors, stripJsComments } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
 import { runCheckJs } from './patch-lint-checkjs.js';
+import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
-import { resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
@@ -24,7 +25,7 @@ export { runCheckJs } from './patch-lint-checkjs.js';
 export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 export { validateExportJsDoc } from './patch-lint-jsdoc.js';
-export { resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+export { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -403,9 +404,14 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
  * @param newFiles - Set of files that are newly created in this patch
  * @param config - Project configuration
  * @param patchOwnedFiles - Optional set of patch-owned `.sys.mjs` paths for scoped JSDoc enforcement
+ * @param patchOwnedChromeScripts - Optional set of patch-owned chrome
+ *   subscripts (`.js` non-`.sys.mjs`) for scoped chrome-script JSDoc
+ *   enforcement. Built by {@link resolvePatchOwnedChromeScripts}; passed
+ *   separately from `patchOwnedFiles` so the `runCheckJs` consumer (which
+ *   only accepts `.sys.mjs`) is not silently broadened.
  * @returns Array of lint issues
  */
-export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles) {
+export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles, patchOwnedChromeScripts) {
     const jsFiles = affectedFiles.filter(isJsFile);
     if (jsFiles.length === 0)
         return [];
@@ -476,9 +482,20 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
                 });
             }
         }
-        // 3b. Assertion floor for patch-introduced browser-chrome tests
+        // 3a. JSDoc on top-level declarations in patch-owned chrome subscripts.
+        // Dispatched out-of-line to keep this file under the per-file line
+        // budget. See `patch-lint-chrome-jsdoc.ts` for the rule body.
+        const isChromeOwned = file.endsWith('.js') &&
+            !isSysMjs &&
+            (patchOwnedChromeScripts ? patchOwnedChromeScripts.has(file) : isNew);
+        const chromeMode = config.patchLint?.chromeScriptJsDoc;
+        issues.push(...lintChromeScriptJsDocForFile(file, content, isChromeOwned, chromeMode));
+        // 3b. Assertion floor for browser-chrome tests touched by this patch
+        // (covers both newly introduced files and modified upstream tests —
+        // a patch that strips the last `Assert.equal` from an existing
+        // browser_*.js silently passed under the old `isNew` gate).
         const assertionFloor = config.patchLint?.testAssertionFloor;
-        if (assertionFloor && assertionFloor !== 'off' && isNew && isBrowserChromeTestFile(file)) {
+        if (assertionFloor && assertionFloor !== 'off' && isBrowserChromeTestFile(file)) {
             const ASSERTION_TOKENS = ['Assert.', 'ok(', 'is(', 'isnot(', 'isDeeply('];
             const hasAssertion = ASSERTION_TOKENS.some((tok) => strippedContent.includes(tok));
             if (!hasAssertion) {
@@ -703,10 +720,11 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
+    const patchOwnedChromeScripts = resolvePatchOwnedChromeScripts(newFiles, patchQueueCtx);
     const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues] = await Promise.all([
         lintPatchedCss(repoDir, affectedFiles, diffContent, config),
         lintNewFileHeaders(repoDir, [...newFiles], config),
-        lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles),
+        lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles, patchOwnedChromeScripts),
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);

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

@@ -316,6 +316,14 @@ export interface TestOptions {
      * values appear after `--headless` if both are set.
      */
     machArg?: string[];
+    /**
+     * 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.
+     */
+    marionettePort?: number;
 }
 /**
  * Options for the furnace apply command.

package/dist/src/types/config.d.ts

@@ -74,8 +74,19 @@ export interface PatchLintConfig {
     rawColorAllowlist?: string[];
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */
     jsdocClassMethods?: PatchLintSeverityGate;
-    /** Require ≥1 assertion in patch-introduced browser_*.js test files. Default: 'off'. */
+    /** Require ≥1 assertion in any patch-touched browser_*.js test file (new or modified). Default: 'off'. */
     testAssertionFloor?: PatchLintSeverityGate;
+    /**
+     * Enforce JSDoc on top-level classes (and their methods) and functions
+     * in patch-owned chrome subscripts (`.js` files loaded via
+     * `Services.scriptloader.loadSubScript`, e.g.
+     * `browser/base/content/<binaryName>*.js`). Distinct from
+     * `jsdocClassMethods` because chrome subscripts are parsed as scripts,
+     * not ES modules — using one flag for both would silently disable the
+     * rule when a chrome subscript was fed to the module parser. Default:
+     * 'off'.
+     */
+    chromeScriptJsDoc?: PatchLintSeverityGate;
 }
 /**
  * Build mode for mach.

package/package.json

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