@hominis/fireforge 0.18.5 → 0.18.8

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/config.js

@@ -66,10 +66,15 @@ function formatValue(value) {
     if (value === undefined) {
         return '(not set)';
     }
-    if (value === null || typeof value === 'object' || typeof value === 'function') {
-        return JSON.stringify(value, null, 2);
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'symbol') {
+        return value.toString();
     }
-    return String(value);
+    return JSON.stringify(value, null, 2);
 }
 /**
  * Runs the config command to get or set configuration values.

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", "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,8 @@ export const SUPPORTED_CONFIG_PATHS = [
     'patchLint',
     'patchLint.checkJs',
     'patchLint.rawColorAllowlist',
+    'patchLint.jsdocClassMethods',
+    'patchLint.testAssertionFloor',
     '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,40 @@ 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;
+    }
+    return out;
+}
 //# sourceMappingURL=config-validate.js.map

package/dist/src/core/furnace-registration-ast.js

@@ -70,9 +70,7 @@ function isInsideDOMContentLoaded(ancestors, content) {
             call.callee.property.type === 'Identifier' &&
             call.callee.property.name === 'addEventListener') {
             const firstArg = call.arguments[0];
-            if (firstArg &&
-                firstArg.type === 'Literal' &&
-                firstArg.value === 'DOMContentLoaded') {
+            if (firstArg && firstArg.type === 'Literal' && firstArg.value === 'DOMContentLoaded') {
                 return true;
             }
             // Check if "DOMContentLoaded" appears in the call's source (handles edge cases)

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

@@ -6,16 +6,24 @@
  * 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';
+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 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,8 +128,43 @@ 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) {
     const name = fn.id.name;
@@ -141,29 +179,12 @@ 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) {
     const name = cls.id.name;
@@ -194,15 +215,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.
+ */
+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 +334,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 +358,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.js

@@ -178,6 +178,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.
  */
@@ -450,13 +465,28 @@ 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',
+                });
+            }
+        }
+        // 3b. Assertion floor for patch-introduced browser-chrome tests
+        const assertionFloor = config.patchLint?.testAssertionFloor;
+        if (assertionFloor && assertionFloor !== 'off' && isNew && 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,
                 });
             }
         }

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,10 @@ 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 patch-introduced browser_*.js test files. Default: 'off'. */
+    testAssertionFloor?: PatchLintSeverityGate;
 }
 /**
  * Build mode for mach.

package/package.json

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