@hominis/fireforge 0.18.8 → 0.18.10

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/license-headers.d.ts

@@ -29,6 +29,11 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * standard MPL header — operators were forced to `--skip-lint` over a real
  * false positive.
  *
+ * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
+ * leading the file are tolerated — Mozilla's canonical layout puts those
+ * on lines 1–2 with the MPL header on lines 3+, which the raw
+ * `startsWith` check would otherwise miss.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */

package/dist/src/core/license-headers.js

@@ -53,6 +53,39 @@ export function getLicenseHeader(license, style) {
             return lines.map((l) => `# ${l}`).join('\n');
     }
 }
+/**
+ * Single-line `/* ... *\/` block comments containing either an Emacs
+ * file-mode marker (`-*-`) or a vim modeline (`vim:`) — Mozilla's
+ * canonical first-line editor directives that legitimately precede the
+ * license header in many Firefox source files.
+ *
+ * Restricted to single-line blocks so a multi-line license header never
+ * gets accidentally consumed.
+ */
+const EDITOR_DIRECTIVE_BLOCK_COMMENT = /^[ \t]*\/\*[^\r\n]*?(?:-\*-|\bvim:)[^\r\n]*?\*\/[ \t]*\r?\n?/;
+/**
+ * Strips any leading run of editor-directive block comments and blank
+ * lines, returning the remaining content.
+ *
+ * Mozilla's coding convention places editor directives like
+ * `/* -*- Mode: javascript; ... -*- *\/` and `/* vim: set ... *\/` on
+ * lines 1–2, with the canonical license header following on lines 3+.
+ * The raw `content.startsWith(...)` check used by {@link hasAnyLicenseHeader}
+ * never matches in that shape; this helper lets the caller test the
+ * post-directive prefix as a fallback.
+ *
+ * @param content - File content to strip
+ */
+function stripLeadingEditorDirectives(content) {
+    let result = content;
+    let prev;
+    do {
+        prev = result;
+        result = result.replace(/^[ \t]*\r?\n/, '');
+        result = result.replace(EDITOR_DIRECTIVE_BLOCK_COMMENT, '');
+    } while (result !== prev);
+    return result;
+}
 /**
  * Returns true if `content` starts with any known license header for the
  * given comment style.
@@ -65,16 +98,24 @@ export function getLicenseHeader(license, style) {
  * standard MPL header — operators were forced to `--skip-lint` over a real
  * false positive.
  *
+ * Editor-directive block comments (`/* -*- ... -*- *\/`, `/* vim: ... *\/`)
+ * leading the file are tolerated — Mozilla's canonical layout puts those
+ * on lines 1–2 with the MPL header on lines 3+, which the raw
+ * `startsWith` check would otherwise miss.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
 export function hasAnyLicenseHeader(content, style) {
+    const candidates = [content, stripLeadingEditorDirectives(content)];
     const licenses = Object.keys(HEADER_LINES);
-    if (licenses.some((license) => content.startsWith(getLicenseHeader(license, style)))) {
-        return true;
-    }
-    if (style === 'js' && content.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
-        return true;
+    for (const candidate of candidates) {
+        if (licenses.some((license) => candidate.startsWith(getLicenseHeader(license, style)))) {
+            return true;
+        }
+        if (style === 'js' && candidate.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
+            return true;
+        }
     }
     return false;
 }

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-export.d.ts

@@ -5,6 +5,16 @@ import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '.
  * @returns Next patch number (e.g., "005" for 4 existing patches)
  */
 export declare function getNextPatchNumber(patchesDir: string): Promise<string>;
+/**
+ * Sanitizes a human-readable name into a filename slug.
+ *
+ * Exported so `patch rename` can produce a filename slug from its
+ * `--to <new-name>` argument using the exact same convention `export`
+ * uses, without duplicating the lowercase + non-alnum collapse + length
+ * cap rules. Drift between the two would let an operator rename a patch
+ * to a slug `export` could never reach.
+ */
+export declare function sanitizeName(name: string): string;
 /**
  * Generates the next patch filename with category.
  * @param patchesDir - Path to the patches directory

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

@@ -25,9 +25,15 @@ export async function getNextPatchNumber(patchesDir) {
     return String(nextNumber).padStart(Math.max(3, String(nextNumber).length), '0');
 }
 /**
- * Sanitizes a string for use in a filename.
+ * Sanitizes a human-readable name into a filename slug.
+ *
+ * Exported so `patch rename` can produce a filename slug from its
+ * `--to <new-name>` argument using the exact same convention `export`
+ * uses, without duplicating the lowercase + non-alnum collapse + length
+ * cap rules. Drift between the two would let an operator rename a patch
+ * to a slug `export` could never reach.
  */
-function sanitizeName(name) {
+export function sanitizeName(name) {
     return name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')

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-cross.js

@@ -396,6 +396,10 @@ export function lintPatchQueueForwardImports(ctx) {
                 .map((o) => `${o.filename}:${o.fullPath}`)
                 .sort((a, b) => a.localeCompare(b))
                 .join(',');
+            // Lowest ordinal that lands AFTER every later-ordered creator —
+            // turns the operator's "guess and re-run" loop into a single shot
+            // when the only fix is reordering.
+            const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
             issues.push({
                 file: sitePath,
                 check: 'forward-import',
@@ -404,7 +408,8 @@ export function lintPatchQueueForwardImports(ctx) {
                     `but the matching new file is created by a later patch: ${ownersSummary}. ` +
                     'Reorder the patches so the dependency is created first, move the import ' +
                     'into the later patch, or mark the import with ' +
-                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive.`,
+                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
+                    `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
                 severity: 'error',
             });
         }

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>;