@hominis/fireforge 0.18.6 → 0.18.9

package/README.md

@@ -230,29 +230,37 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed — with tool-managed branding paths (`browser/branding/<binaryName>/`) excluded. A fresh-setup workspace carries a large generated branding diff that operators did not author directly, and letting it through tripped the patch-size and license-header rules on content that matches the `branding` bucket in `fireforge status`. When the exclusion fires the command prints a one-line note naming the excluded count so the filter is visible. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further — explicit-path mode does lint branding files (the operator's explicit request wins over the branding exclusion); the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
 
-| Check                          | Scope                                                                                            | Severity                 |
-| ------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------ |
-| `missing-license-header`       | New files (JS/CSS/FTL)                                                                           | error                    |
-| `relative-import`              | JS/MJS files                                                                                     | error                    |
-| `token-prefix-violation`       | CSS files (with furnace)                                                                         | error                    |
-| `raw-color-value`              | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                        | error                    |
-| `duplicate-new-file-creation`  | Same path created by multiple patches                                                            | error                    |
-| `forward-import`               | Patch imports from a later-patch file                                                            | error                    |
-| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                                                | error                    |
-| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                                                | error                    |
-| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                                                | error                    |
-| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                                                  | error                    |
-| `missing-modification-comment` | Modified upstream JS/MJS                                                                         | warning                  |
-| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                                             | warning                  |
-| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                     | notice / warning / error |
-| `observer-topic-naming`        | Observer topics with binaryName                                                                  | warning                  |
-| `large-patch-files`            | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                         | warning                  |
-| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding) | notice / warning / error |
+| Check                                | Scope                                                                                            | Severity                 |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| `missing-license-header`             | New files (JS/CSS/FTL)                                                                           | error                    |
+| `relative-import`                    | JS/MJS files                                                                                     | error                    |
+| `token-prefix-violation`             | CSS files (with furnace)                                                                         | error                    |
+| `raw-color-value`                    | Introduced CSS color values (allowlist via `patchLint.rawColorAllowlist`)                        | error                    |
+| `duplicate-new-file-creation`        | Same path created by multiple patches                                                            | error                    |
+| `forward-import`                     | Patch imports from a later-patch file                                                            | error                    |
+| `missing-jsdoc`                      | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-param-mismatch`               | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `jsdoc-missing-returns`              | Exports in patch-owned `.sys.mjs`                                                                | error                    |
+| `checkjs-type-error`                 | Patch-owned `.sys.mjs` (opt-in)                                                                  | error                    |
+| `missing-jsdoc-class-method`         | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                          | configurable             |
+| `jsdoc-class-method-param-mismatch`  | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                          | configurable             |
+| `jsdoc-class-method-missing-returns` | Class-method exports in patch-owned `.sys.mjs` (opt-in)                                          | configurable             |
+| `test-needs-assertion`               | Patch-introduced `browser_*.js` test files (opt-in)                                              | configurable             |
+| `missing-modification-comment`       | Modified upstream JS/MJS                                                                         | warning                  |
+| `modified-file-missing-header`       | Modified upstream files (JS/CSS/FTL)                                                             | warning                  |
+| `file-too-large`                     | New files (tiered: 500/750/900 general, 1200/1400/1600 test)                                     | notice / warning / error |
+| `observer-topic-naming`              | Observer topics with binaryName                                                                  | warning                  |
+| `large-patch-files`                  | Patches affecting many files (tiered: >5 general, >5 test, >60 branding)                         | warning                  |
+| `large-patch-lines`                  | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test, 8000/18000/30000 branding) | notice / warning / error |
 
 **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. This pass solely focuses on type errors within the patch-owned code itself (mismatched JSDoc types, wrong argument counts, unreachable code, etc.).
 
+**Optional `jsdocClassMethods` enforcement.** Set `"patchLint": { "jsdocClassMethods": "warning" | "error" }` in `fireforge.json` to extend JSDoc validation to class-method exports inside patch-owned `.sys.mjs` files. Every public method (instance and static), parameter-bearing constructor, getter, and setter must carry a leading JSDoc block; `@param` names must match the parameter list, and `@returns` is required when a method returns a value (getters and setters are exempt from `@returns`). Methods whose name starts with `_` or `#`, methods carrying `@private` or `@internal` in their JSDoc, and zero-parameter constructors are exempt. Defaults to `"off"`, so upgrading is a no-op until the knob is set.
+
+**Optional `testAssertionFloor` enforcement.** Set `"patchLint": { "testAssertionFloor": "warning" | "error" }` to require that every `browser_*.js` test file introduced by the current patch contains at least one assertion (`Assert.*`, `ok()`, `is()`, `isnot()`, or `isDeeply()`). Smoke-only tests that load the script and exit without asserting any user-visible behavior are flagged as `test-needs-assertion`. Comment-only assertions do not count — comments are stripped before scanning. `head.js` and `head_*.js` test helpers are exempt; modified upstream tests are out of scope (V1 only flags newly-introduced files). Defaults to `"off"`.
+
 The two cross-patch rules (`duplicate-new-file-creation` and `forward-import`) run over the whole patch queue rather than a single diff, catching ordering issues that only surface during `import`. Forward-import detection compares leaf filenames, so a false positive is theoretically possible when two patches create files with the same basename in different directories. Suppress with an inline `// fireforge-ignore: forward-import` comment on or above the import line. Both `forward-import` and `raw-color-value` support inline suppression comments (`// fireforge-ignore: forward-import` and `/* fireforge-ignore: raw-color-value */` respectively).
 
 </details>

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", "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

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

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

@@ -129,22 +129,7 @@ export function validateConfig(data) {
     // PatchLint
     const patchLintRec = optionalConfigObject(rec, 'patchLint');
     if (patchLintRec) {
-        config.patchLint = {};
-        const checkJs = patchLintRec.raw('checkJs');
-        if (checkJs !== undefined) {
-            if (typeof checkJs !== 'boolean') {
-                throw new ConfigError('Config field "patchLint.checkJs" must be a boolean');
-            }
-            config.patchLint.checkJs = checkJs;
-        }
-        const rawColorAllowlist = patchLintRec.raw('rawColorAllowlist');
-        if (rawColorAllowlist !== undefined) {
-            if (!Array.isArray(rawColorAllowlist) ||
-                rawColorAllowlist.some((v) => typeof v !== 'string')) {
-                throw new ConfigError('Config field "patchLint.rawColorAllowlist" must be an array of strings');
-            }
-            config.patchLint.rawColorAllowlist = rawColorAllowlist;
-        }
+        config.patchLint = parsePatchLintBlock(patchLintRec);
     }
     // Warn on unknown root keys
     const knownRootKeys = new Set(SUPPORTED_CONFIG_ROOT_KEYS);
@@ -210,4 +195,44 @@ function optionalConfigObject(rec, key) {
         throw new ConfigError(`Config field "${key}" must be an object`);
     }
 }
+const SEVERITY_GATE_VALUES = ['off', 'warning', 'error'];
+function parseSeverityGate(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || !SEVERITY_GATE_VALUES.includes(raw)) {
+        throw new ConfigError(`Config field "${label}" must be one of: ${SEVERITY_GATE_VALUES.join(', ')}`);
+    }
+    return raw;
+}
+function parsePatchLintBlock(rec) {
+    const out = {};
+    const checkJs = rec.raw('checkJs');
+    if (checkJs !== undefined) {
+        if (typeof checkJs !== 'boolean') {
+            throw new ConfigError('Config field "patchLint.checkJs" must be a boolean');
+        }
+        out.checkJs = checkJs;
+    }
+    const rawColorAllowlist = rec.raw('rawColorAllowlist');
+    if (rawColorAllowlist !== undefined) {
+        if (!Array.isArray(rawColorAllowlist) ||
+            rawColorAllowlist.some((v) => typeof v !== 'string')) {
+            throw new ConfigError('Config field "patchLint.rawColorAllowlist" must be an array of strings');
+        }
+        out.rawColorAllowlist = rawColorAllowlist;
+    }
+    const jsdocClassMethods = parseSeverityGate(rec.raw('jsdocClassMethods'), 'patchLint.jsdocClassMethods');
+    if (jsdocClassMethods !== undefined) {
+        out.jsdocClassMethods = jsdocClassMethods;
+    }
+    const testAssertionFloor = parseSeverityGate(rec.raw('testAssertionFloor'), 'patchLint.testAssertionFloor');
+    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,16 +6,61 @@
  * Separated from `patch-lint.ts` to keep both files within the
  * project's per-file line budget.
  */
-export type JsDocCheck = 'missing-jsdoc' | 'jsdoc-param-mismatch' | 'jsdoc-missing-returns';
+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;
     check: JsDocCheck;
     message: string;
+    /** Optional severity hint. When undefined, callers default to 'error'. */
+    severity?: 'error' | 'warning';
 }
+export type ClassMethodMode = 'off' | 'warning' | 'error';
+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.
  *
  * @param source - File content
+ * @param options - Optional gates for opt-in checks (e.g. class-method JSDoc)
  * @returns Array of JSDoc issues found
  */
-export declare function validateExportJsDoc(source: string): JsDocIssue[];
+export declare function validateExportJsDoc(source: string, options?: ValidateExportJsDocOptions): JsDocIssue[];

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

@@ -50,6 +50,9 @@ function extractParamNames(jsDoc) {
 function hasReturnsTag(jsDoc) {
     return /@returns?\b/.test(jsDoc);
 }
+function hasPrivateOrInternalTag(jsDoc) {
+    return /@(?:private|internal)\b/.test(jsDoc);
+}
 // ---------------------------------------------------------------------------
 // Return-statement detection
 // ---------------------------------------------------------------------------
@@ -125,10 +128,60 @@ function lineAt(source, offset) {
     }
     return line;
 }
+/**
+ * Validates @param name matching and @returns presence on a function-like
+ * node that already has an attached JSDoc comment. Destructured, default-
+ * valued, and rest params are silently skipped to match historical behavior
+ * of the top-level export check.
+ */
+function validateParamsAndReturns(fnNode, jsDoc, issues, ctx) {
+    const docText = jsDoc.value;
+    if (!ctx.skipParams) {
+        const actualParams = fnNode.params
+            .map((p) => (p.type === 'Identifier' ? p.name : null))
+            .filter((n) => n !== null);
+        if (actualParams.length > 0) {
+            const docParams = extractParamNames(docText);
+            for (const param of actualParams) {
+                if (!docParams.includes(param)) {
+                    issues.push({
+                        line: ctx.line,
+                        check: ctx.paramCheck,
+                        message: `Exported ${ctx.label} at line ${ctx.line}: @param "${param}" is missing or misnamed in JSDoc.`,
+                        ...(ctx.severity ? { severity: ctx.severity } : {}),
+                    });
+                }
+            }
+        }
+    }
+    if (!ctx.skipReturns && functionReturnsValue(fnNode) && !hasReturnsTag(docText)) {
+        issues.push({
+            line: ctx.line,
+            check: ctx.returnsCheck,
+            message: `Exported ${ctx.label} at line ${ctx.line} returns a value but JSDoc is missing @returns.`,
+            ...(ctx.severity ? { severity: ctx.severity } : {}),
+        });
+    }
+}
 // ---------------------------------------------------------------------------
-// Core validation
+// 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);
@@ -141,31 +194,20 @@ function validateFunctionDecl(fn, comments, source, issues, lookupStart) {
         });
         return;
     }
-    const docText = jsDoc.value;
-    const actualParams = fn.params
-        .map((p) => (p.type === 'Identifier' ? p.name : null))
-        .filter((n) => n !== null);
-    if (actualParams.length > 0) {
-        const docParams = extractParamNames(docText);
-        for (const param of actualParams) {
-            if (!docParams.includes(param)) {
-                issues.push({
-                    line,
-                    check: 'jsdoc-param-mismatch',
-                    message: `Exported function "${name}" at line ${line}: @param "${param}" is missing or misnamed in JSDoc.`,
-                });
-            }
-        }
-    }
-    if (functionReturnsValue(fn) && !hasReturnsTag(docText)) {
-        issues.push({
-            line,
-            check: 'jsdoc-missing-returns',
-            message: `Exported function "${name}" at line ${line} returns a value but JSDoc is missing @returns.`,
-        });
-    }
+    validateParamsAndReturns(fn, jsDoc, issues, {
+        label: `function "${name}"`,
+        line,
+        paramCheck: 'jsdoc-param-mismatch',
+        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);
@@ -194,15 +236,102 @@ function validateVariableDecl(varDecl, comments, source, issues, lookupStart) {
     }
 }
 // ---------------------------------------------------------------------------
+// Class-method validation (opt-in via classMethodMode)
+// ---------------------------------------------------------------------------
+/**
+ * Returns the method's identifier name when statically resolvable, or
+ * undefined for computed keys (e.g. `[Symbol.iterator]()`). Private fields
+ * (`#name`) are treated as private-by-syntax and surface as undefined here
+ * so the walker skips them up front.
+ */
+function staticMethodName(method) {
+    if (method.computed)
+        return undefined;
+    const key = method.key;
+    if (key.type !== 'Identifier')
+        return undefined;
+    return key.name;
+}
+function isPrivateMethodKey(method) {
+    return method.key.type === 'PrivateIdentifier';
+}
+function classMethodLabel(className, method, name) {
+    if (method.kind === 'constructor')
+        return `constructor of class "${className}"`;
+    const prefix = method.static ? 'static ' : '';
+    if (method.kind === 'get')
+        return `${prefix}getter "${className}.${name}"`;
+    if (method.kind === 'set')
+        return `${prefix}setter "${className}.${name}"`;
+    return `${prefix}method "${className}.${name}"`;
+}
+/**
+ * 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 function validateClassMethods(cls, comments, source, issues, severity) {
+    const className = cls.id.name;
+    for (const member of cls.body.body) {
+        if (member.type !== 'MethodDefinition')
+            continue;
+        const method = member;
+        if (isPrivateMethodKey(method))
+            continue;
+        const name = staticMethodName(method);
+        if (name === undefined)
+            continue;
+        if (method.kind !== 'constructor' && name.startsWith('_'))
+            continue;
+        if (method.kind === 'constructor' && method.value.params.length === 0)
+            continue;
+        const methodStart = method.start;
+        const line = lineAt(source, methodStart);
+        const jsDoc = findAttachedJsDoc(comments, methodStart, source);
+        if (jsDoc && hasPrivateOrInternalTag(jsDoc.value))
+            continue;
+        const label = classMethodLabel(className, method, name);
+        if (!jsDoc) {
+            issues.push({
+                line,
+                check: 'missing-jsdoc-class-method',
+                message: `Exported ${label} at line ${line} is missing a JSDoc comment.`,
+                severity,
+            });
+            continue;
+        }
+        if (method.kind === 'get') {
+            // Presence already verified; getter expression is the contract.
+            continue;
+        }
+        const skipReturns = method.kind === 'constructor' || method.kind === 'set';
+        validateParamsAndReturns(method.value, jsDoc, issues, {
+            label,
+            line,
+            paramCheck: 'jsdoc-class-method-param-mismatch',
+            returnsCheck: 'jsdoc-class-method-missing-returns',
+            severity,
+            skipReturns,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 /**
  * Validates JSDoc on exported declarations in a `.sys.mjs` source file.
  *
  * @param source - File content
+ * @param options - Optional gates for opt-in checks (e.g. class-method JSDoc)
  * @returns Array of JSDoc issues found
  */
-export function validateExportJsDoc(source) {
+export function validateExportJsDoc(source, options) {
+    const classMethodMode = options?.classMethodMode ?? 'off';
     const comments = [];
     let ast;
     try {
@@ -226,6 +355,9 @@ export function validateExportJsDoc(source) {
             }
             else if (decl.type === 'ClassDeclaration') {
                 validateClassDecl(decl, comments, source, issues, exportStart);
+                if (classMethodMode !== 'off') {
+                    validateClassMethods(decl, comments, source, issues, classMethodMode);
+                }
             }
             else if (decl.type === 'VariableDeclaration') {
                 validateVariableDecl(decl, comments, source, issues, exportStart);
@@ -247,6 +379,9 @@ export function validateExportJsDoc(source) {
                 }
                 else if (localDecl.type === 'ClassDeclaration') {
                     validateClassDecl(localDecl, comments, source, issues);
+                    if (classMethodMode !== 'off') {
+                        validateClassMethods(localDecl, comments, source, issues, classMethodMode);
+                    }
                 }
                 else {
                     validateVariableDecl(localDecl, comments, source, issues);

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
 // ---------------------------------------------------------------------------
@@ -178,6 +179,21 @@ export function isTestFile(file) {
     const basename = file.split('/').pop() ?? '';
     return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
 }
+/**
+ * Narrower scope than `isTestFile` — only browser-chrome test files
+ * (`browser_*.js` under a `/test/` or `/tests/` directory). Excludes
+ * `head.js` and `head_*.js` test helpers.
+ */
+function isBrowserChromeTestFile(file) {
+    if (!file.endsWith('.js'))
+        return false;
+    if (!/\/(?:test|tests)\//.test(file))
+        return false;
+    const basename = file.split('/').pop() ?? '';
+    if (basename === 'head.js' || /^head_.*\.js$/.test(basename))
+        return false;
+    return basename.startsWith('browser_');
+}
 /**
  * Detects comment style from file extension for license header checks.
  */
@@ -388,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 [];
@@ -450,13 +471,39 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         // 3. JSDoc on exports (patch-owned .sys.mjs files)
         const isOwned = patchOwnedFiles ? patchOwnedFiles.has(file) : isNew;
         if (isOwned && isSysMjs) {
-            const jsdocIssues = validateExportJsDoc(content);
+            const classMethodMode = config.patchLint?.jsdocClassMethods;
+            const jsdocIssues = validateExportJsDoc(content, classMethodMode ? { classMethodMode } : undefined);
             for (const jsdocIssue of jsdocIssues) {
                 issues.push({
                     file,
                     check: jsdocIssue.check,
                     message: jsdocIssue.message,
-                    severity: 'error',
+                    severity: jsdocIssue.severity ?? 'error',
+                });
+            }
+        }
+        // 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' && isBrowserChromeTestFile(file)) {
+            const ASSERTION_TOKENS = ['Assert.', 'ok(', 'is(', 'isnot(', 'isDeeply('];
+            const hasAssertion = ASSERTION_TOKENS.some((tok) => strippedContent.includes(tok));
+            if (!hasAssertion) {
+                issues.push({
+                    file,
+                    check: 'test-needs-assertion',
+                    message: `Test file ${file} contains no assertions (Assert.*, ok(), is(), isnot(), isDeeply()). Smoke-only tests do not count as coverage. Add at least one assertion that pins user-visible behavior, or remove the file.`,
+                    severity: assertionFloor,
                 });
             }
         }
@@ -673,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

@@ -59,6 +59,11 @@ export interface WireConfig {
     /** Subscript directory relative to engine/. Default: "browser/base/content" */
     subscriptDir?: string;
 }
+/**
+ * Severity gate for opt-in patch-lint rules. `'off'` disables the rule;
+ * `'warning'` and `'error'` emit issues at the matching severity.
+ */
+export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
 /**
  * Configuration for patch lint rules.
  */
@@ -67,6 +72,21 @@ export interface PatchLintConfig {
     checkJs?: boolean;
     /** File paths exempt from the raw-color-value check (exact or basename match) */
     rawColorAllowlist?: string[];
+    /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */
+    jsdocClassMethods?: PatchLintSeverityGate;
+    /** 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.6",
+  "version": "0.18.9",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",