@hominis/fireforge 0.43.0 → 0.44.0

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

@@ -34,30 +34,29 @@ export interface ValidateExportJsDocOptions {
  * @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;
+export declare function validateFunctionDecl(fn: AcornESTreeNode<FunctionDeclaration>, comments: acorn.Comment[], source: string, lookupStart?: number): JsDocIssue[];
 /**
  * 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;
+export declare function validateClassDecl(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, lookupStart?: number): JsDocIssue[];
 /**
- * Walks an exported class body and emits class-method JSDoc issues per
- * the configured severity. Skip rules (in evaluation order):
+ * 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.
+ * A pure-override skip (`super.method(...args)`-only bodies bypassing the
+ * return-tag check) is deliberately not implemented; the rule stays simple.
  */
-export declare function validateClassMethods(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, issues: JsDocIssue[], severity: 'warning' | 'error'): void;
+export declare function validateClassMethods(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, severity: 'warning' | 'error'): JsDocIssue[];
 /**
  * Validates JSDoc on exported declarations in a `.sys.mjs` source file.
  *

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

@@ -238,12 +238,12 @@ function validateParamsAndReturns(fnNode, jsDoc, issues, ctx) {
  * @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) {
+export function validateFunctionDecl(fn, comments, source, lookupStart) {
+    const issues = [];
     const name = fn.id.name;
     const start = lookupStart !== undefined ? lookupStart : fn.start;
     const line = lineAt(source, start);
@@ -254,7 +254,7 @@ export function validateFunctionDecl(fn, comments, source, issues, lookupStart)
             check: 'missing-jsdoc',
             message: `Exported function "${name}" at line ${line} is missing a JSDoc comment.`,
         });
-        return;
+        return issues;
     }
     validateParamsAndReturns(fn, jsDoc, issues, {
         label: `function "${name}"`,
@@ -262,6 +262,7 @@ export function validateFunctionDecl(fn, comments, source, issues, lookupStart)
         paramCheck: 'jsdoc-param-mismatch',
         returnsCheck: 'jsdoc-missing-returns',
     });
+    return issues;
 }
 /**
  * Validates a top-level class declaration: requires an attached JSDoc
@@ -269,7 +270,8 @@ export function validateFunctionDecl(fn, comments, source, issues, lookupStart)
  * {@link validateClassMethods}. Exported for reuse in the chrome-subscript
  * validator.
  */
-export function validateClassDecl(cls, comments, source, issues, lookupStart) {
+export function validateClassDecl(cls, comments, source, lookupStart) {
+    const issues = [];
     const name = cls.id.name;
     const start = lookupStart !== undefined ? lookupStart : cls.start;
     const line = lineAt(source, start);
@@ -281,12 +283,14 @@ export function validateClassDecl(cls, comments, source, issues, lookupStart) {
             message: `Exported class "${name}" at line ${line} is missing a JSDoc comment.`,
         });
     }
+    return issues;
 }
-function validateVariableDecl(varDecl, comments, source, issues, lookupStart) {
+function validateVariableDecl(varDecl, comments, source, lookupStart) {
+    const issues = [];
     const start = lookupStart !== undefined ? lookupStart : varDecl.start;
     const jsDoc = findAttachedJsDoc(comments, start, source);
     if (jsDoc)
-        return; // has a JSDoc block — sufficient for constants
+        return issues; // has a JSDoc block — sufficient for constants
     for (const decl of varDecl.declarations) {
         const name = decl.id.type === 'Identifier' ? decl.id.name : '<destructured>';
         const line = lineAt(source, start);
@@ -296,6 +300,7 @@ function validateVariableDecl(varDecl, comments, source, issues, lookupStart) {
             message: `Exported constant "${name}" at line ${line} is missing a JSDoc comment.`,
         });
     }
+    return issues;
 }
 // ---------------------------------------------------------------------------
 // Class-method validation (opt-in via classMethodMode)
@@ -328,16 +333,17 @@ function classMethodLabel(className, method, 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):
+ * 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.
+ * A pure-override skip (`super.method(...args)`-only bodies bypassing the
+ * return-tag check) is deliberately not implemented; the rule stays simple.
  */
-export function validateClassMethods(cls, comments, source, issues, severity) {
+export function validateClassMethods(cls, comments, source, severity) {
+    const issues = [];
     const className = cls.id.name;
     for (const member of cls.body.body) {
         if (member.type !== 'MethodDefinition')
@@ -381,6 +387,7 @@ export function validateClassMethods(cls, comments, source, issues, severity) {
             skipReturns,
         });
     }
+    return issues;
 }
 // ---------------------------------------------------------------------------
 // Public API
@@ -422,16 +429,16 @@ export function validateExportJsDoc(source, options) {
             const decl = exportNode.declaration;
             const exportStart = exportNode.start;
             if (decl.type === 'FunctionDeclaration') {
-                validateFunctionDecl(decl, comments, source, issues, exportStart);
+                issues.push(...validateFunctionDecl(decl, comments, source, exportStart));
             }
             else if (decl.type === 'ClassDeclaration') {
-                validateClassDecl(decl, comments, source, issues, exportStart);
+                issues.push(...validateClassDecl(decl, comments, source, exportStart));
                 if (classMethodMode !== 'off') {
-                    validateClassMethods(decl, comments, source, issues, classMethodMode);
+                    issues.push(...validateClassMethods(decl, comments, source, classMethodMode));
                 }
             }
             else if (decl.type === 'VariableDeclaration') {
-                validateVariableDecl(decl, comments, source, issues, exportStart);
+                issues.push(...validateVariableDecl(decl, comments, source, exportStart));
             }
             continue;
         }
@@ -446,16 +453,16 @@ export function validateExportJsDoc(source, options) {
                 if (!localDecl)
                     continue;
                 if (localDecl.type === 'FunctionDeclaration') {
-                    validateFunctionDecl(localDecl, comments, source, issues);
+                    issues.push(...validateFunctionDecl(localDecl, comments, source));
                 }
                 else if (localDecl.type === 'ClassDeclaration') {
-                    validateClassDecl(localDecl, comments, source, issues);
+                    issues.push(...validateClassDecl(localDecl, comments, source));
                     if (classMethodMode !== 'off') {
-                        validateClassMethods(localDecl, comments, source, issues, classMethodMode);
+                        issues.push(...validateClassMethods(localDecl, comments, source, classMethodMode));
                     }
                 }
                 else {
-                    validateVariableDecl(localDecl, comments, source, issues);
+                    issues.push(...validateVariableDecl(localDecl, comments, source));
                 }
             }
         }

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

@@ -12,7 +12,7 @@
  */
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { mozbuildSortCompare } from './manifest-helpers.js';
+import { mozbuildSortCompare } from './moz-manifest-helpers.js';
 /**
  * moz.build list variables mozbuild declares as `StrictOrderingOnAppendList`
  * (python/mozbuild/mozbuild/frontend/context.py). configure raises
@@ -81,30 +81,30 @@ function stripMozBuildComment(line) {
     return line;
 }
 /**
- * Extracts every strict-ordered list (with items in file order) from moz.build
- * content.
+ * Extracts every strict-ordered list (with items in file order) from
+ * moz.build content.
  *
- * Comments are stripped before both the item scan and the close-bracket test.
- * moz.build is Python, and before 0.41.0 neither step knew that:
+ * Comments are stripped before both the item scan and the close-bracket
+ * test, because moz.build is Python:
  *
- * - a quoted string in a trailing comment was scraped in as a phantom list
- *   item (`"Zeta.cpp",  # replaces "Beta.cpp"` yielded a `Beta.cpp` entry), so
- *   the sort check reported an unsorted list naming a file that is not in it —
- *   with a fingerprint that could never stabilise, because the item does not
- *   exist to be moved;
- * - a `]` anywhere in a comment (`# see foo[0]`) closed the list early and
- *   silently truncated the item set.
+ * - a quoted string in a trailing comment would otherwise be scraped in as a
+ *   phantom list item (`"Zeta.cpp",  # replaces "Beta.cpp"` yielding a
+ *   `Beta.cpp` entry), so the sort check reports an unsorted list naming a
+ *   file that is not in it — with a fingerprint that can never stabilise,
+ *   because the item does not exist to be moved;
+ * - a `]` anywhere in a comment (`# see foo[0]`) would close the list early
+ *   and silently truncate the item set.
  *
- * The scan also no longer advances the caller's loop counter: an unterminated
- * list used to consume the rest of the file, so every *later* list in it was
- * skipped entirely.
+ * The scan also does not advance the caller's loop counter: an unterminated
+ * list would otherwise consume the rest of the file and skip every later
+ * list in it.
  *
  * Nor does an unterminated list borrow the NEXT list's bracket. The forward
- * scan stops at the next list opener rather than reading through it: without
- * that, an unclosed `EXTRA_COMPONENTS` swallowed the following
- * `EXTRA_JS_MODULES` — its items merged into the first list's item set and its
- * `]` accepted as the first list's close — reporting a sorting error against a
- * variable that never contained those items, and skipping the second list.
+ * scan stops at the next list opener rather than reading through it —
+ * otherwise an unclosed `EXTRA_COMPONENTS` swallows the following
+ * `EXTRA_JS_MODULES`, merging its items into the first list and accepting
+ * its `]` as the first list's close, reporting a sorting error against a
+ * variable that never contained those items.
  */
 function collectStrictOrderedLists(content) {
     const lines = content.split('\n');

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

@@ -1,13 +1,13 @@
 /**
  * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
  *
- * The historical implementation captured the first string literal after
- * the call's opening paren on a single line. That mis-attributed string
- * literals in complex subject arguments and silently skipped multi-line
- * call sites. This version scans the balanced argument list (across
- * newlines, string-aware), takes the *topic* argument by position, and
- * allowlists well-known Firefox-owned topics so tests that simulate
- * upstream notifications are not pushed toward renaming real topics.
+ * Capturing the first string literal after the call's opening paren on a
+ * single line mis-attributes string literals in complex subject arguments
+ * and silently skips multi-line call sites. This scans the balanced argument
+ * list (across newlines, string-aware), takes the *topic* argument by
+ * position, and allowlists well-known Firefox-owned topics so tests that
+ * simulate upstream notifications are not pushed toward renaming real
+ * topics.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 /**

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

@@ -2,13 +2,13 @@
 /**
  * `observer-topic-naming` rule body, extracted from `patch-lint.ts`.
  *
- * The historical implementation captured the first string literal after
- * the call's opening paren on a single line. That mis-attributed string
- * literals in complex subject arguments and silently skipped multi-line
- * call sites. This version scans the balanced argument list (across
- * newlines, string-aware), takes the *topic* argument by position, and
- * allowlists well-known Firefox-owned topics so tests that simulate
- * upstream notifications are not pushed toward renaming real topics.
+ * Capturing the first string literal after the call's opening paren on a
+ * single line mis-attributes string literals in complex subject arguments
+ * and silently skips multi-line call sites. This scans the balanced argument
+ * list (across newlines, string-aware), takes the *topic* argument by
+ * position, and allowlists well-known Firefox-owned topics so tests that
+ * simulate upstream notifications are not pushed toward renaming real
+ * topics.
  */
 /**
  * Firefox-owned observer topics a fork legitimately observes or simulates.

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

@@ -46,22 +46,18 @@ export declare function commentStyleForFile(file: string): CommentStyle | null;
  * Accepted shapes, in order:
  *  - the project's own header for the file's comment style;
  *  - under `browser/branding/`, ANY recognised license header in the
- *    matching style: the setup-generated branding directory is copied
- *    from Firefox's `unofficial` template and arrives with Mozilla
- *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
- *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
- *    GPL-2.0-or-later;
+ *    matching style: the setup-generated branding directory is copied from
+ *    Firefox's `unofficial` template and arrives with Mozilla MPL-2.0
+ *    headers — legitimate for copyright purposes (the assets are Mozilla's)
+ *    even when the fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later;
  *  - on an MPL-2.0 project, any recognised header in the matching style;
  *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
- *    behind a leading editor-directive comment) REGARDLESS of the
- *    project license, on any file whose comment syntax is the block form
- *    (JS and CSS): a file copied from the Firefox tree legitimately
- *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
- *    too. 0.35.0 accepted this on JS only; field verification showed a
- *    derived CSS file carrying the identical three-line block header
- *    still needed a patch-level lintIgnore. Only the block form is
- *    accepted — the `// `-style MPL header is FireForge-generated, not
- *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    behind a leading editor-directive comment) REGARDLESS of the project
+ *    license, on any file whose comment syntax is the block form (JS and
+ *    CSS): a file copied from the Firefox tree legitimately keeps Mozilla's
+ *    header for provenance in an EUPL/GPL/0BSD project too. Only the block
+ *    form is accepted — the `// `-style MPL header is FireForge-generated,
+ *    not upstream provenance — and `hash`-style files (FTL) stay excluded
  *    because `/* … *\/` is not a comment there.
  *
  * @param file - Engine-relative path of the new file
@@ -178,6 +174,29 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
  * Optional behaviour switches for {@link lintExportedPatch}.
  */
 export interface LintExportedPatchOptions {
+    /**
+     * Cross-patch context for ownership resolution. Present whenever the
+     * caller has a loaded patch queue; absent for the ad-hoc single-diff
+     * paths that have no queue to resolve against.
+     */
+    patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext;
+    /**
+     * Per-patch `check` IDs to drop from the returned issues. Threaded from
+     * `PatchMetadata.lintIgnore` so a patch that is advisory-noisy by nature
+     * (a cohesive branding bundle, auto-generated manifest, etc.) can opt out
+     * of a specific rule without reaching for the blunt `--skip-lint` hammer.
+     * Not mutated.
+     */
+    ignoreChecks?: ReadonlySet<string>;
+    /**
+     * Explicit tier override, threaded from `PatchMetadata.tier`. When
+     * `"branding"` forces the branding thresholds on the
+     * `large-patch-lines` rule. Callers with a per-patch manifest context
+     * (re-export, per-patch lint) should pass this; aggregate-mode callers
+     * without a specific patch context omit it and fall through to
+     * auto-detection.
+     */
+    patchTier?: 'branding';
     /**
      * Skip the patch-size rules (`large-patch-files` / `large-patch-lines`).
      * The ad-hoc `fireforge lint <files>` path passes a cross-patch file
@@ -218,20 +237,10 @@ export interface LintExportedPatchOptions {
  * @param affectedFiles - File paths (relative to repoDir) affected by the patch
  * @param diffContent - Raw unified diff string
  * @param config - Project configuration
- * @param patchQueueCtx - Optional cross-patch context for ownership resolution
- * @param ignoreChecks - Optional set of per-patch `check` IDs to drop from the
- *   returned issues. Threaded from `PatchMetadata.lintIgnore` so a patch that
- *   is advisory-noisy by nature (a cohesive branding bundle, auto-generated
- *   manifest, etc.) can opt out of a specific rule without reaching for the
- *   blunt `--skip-lint` hammer. Not mutated by this function.
- * @param patchTier - Optional explicit tier override, threaded from
- *   `PatchMetadata.tier`. When `"branding"` forces the branding
- *   thresholds on the `large-patch-lines` rule. Callers with a
- *   per-patch manifest context (re-export, per-patch lint) should
- *   pass this; aggregate-mode callers without a specific patch
- *   context skip it and fall through to auto-detection.
- * @param options - Optional behaviour switches; see
- *   {@link LintExportedPatchOptions}.
+ * @param options - Optional context and behaviour switches; see
+ *   {@link LintExportedPatchOptions}. Every optional input lives here
+ *   rather than in a positional tail: four of the five call sites had to
+ *   pass `undefined` placeholders to reach the one member they wanted.
  * @returns Array of all lint issues found
  */
-export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding', options?: LintExportedPatchOptions): Promise<PatchLintIssue[]>;
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, options?: LintExportedPatchOptions): Promise<PatchLintIssue[]>;