@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -6,7 +6,7 @@
  * Factored out of `patch-lint.ts` so the per-patch lint body and
  * cross-patch lint body (in `patch-lint-cross.ts`) can both depend on
  * the same diff walkers without inducing a circular import. Callers
- * should keep importing these through `patch-lint.ts` — this file is
+ * should keep importing these through `patch-lint.ts`. This file is
  * an implementation detail. The actual line-walking lives in
  * `parseDiffSections` (patch-parse.ts), the codebase's single diff walker.
  */
@@ -49,8 +49,8 @@ export function extractAddedLinesPerFile(diffContent) {
  * Extracts 1-based post-patch line numbers of added lines per file from a
  * unified diff. Walking each hunk with a new-file line counter (`+` and
  * context lines advance it, `-` lines do not) lets rules that need
- * full-file context — e.g. comment masking across the context/added
- * boundary — map the patch's additions onto the applied file.
+ * full-file context (e.g. comment masking across the context/added
+ * boundary) map the patch's additions onto the applied file.
  */
 export function extractAddedLineNumbersPerFile(diffContent) {
     const result = new Map();
@@ -84,7 +84,7 @@ export function extractAddedLineNumbersPerFile(diffContent) {
  * `buildPatchQueueContext`.
  *
  * Matches buildPatchQueueContext's algorithm exactly: skip paths that are
- * created by the diff — those are already covered by the `newFiles` map,
+ * created by the diff, since those are already covered by the `newFiles` map,
  * which carries full content rather than only the added lines.
  *
  * @param diff - Unified diff content

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

@@ -1,7 +1,7 @@
 /**
  * The `file-too-large` thresholds and their rendered message.
  *
- * Its own module for two reasons: the config validator needs the DEFAULTS
+ * Its own module for two reasons: the config validator needs the defaults
  * to validate an override triple against the merged result, and importing
  * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
  * import edge (and a cycle) between the rule bodies and config parsing.
@@ -9,9 +9,9 @@
  * On the vocabulary: the bands were `notice` / `warning` / `error` with the
  * middle one described as a "soft limit". That description is false under
  * the posture FireForge itself recommends for a release gate,
- * `--max-warnings 0`, where a warning is a hard failure — so a file at 751
+ * `--max-warnings 0`, where a warning is a hard failure, so a file at 751
  * lines failed a gate with a message calling 750 soft. The message below
- * says what the band IS (a warning) and what a zero-warning gate does with
+ * says what the band is (a warning) and what a zero-warning gate does with
  * it, and the thresholds are now tunable, so a project whose file-size
  * policy differs has a dial instead of an argument.
  */

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

@@ -2,7 +2,7 @@
 /**
  * The `file-too-large` thresholds and their rendered message.
  *
- * Its own module for two reasons: the config validator needs the DEFAULTS
+ * Its own module for two reasons: the config validator needs the defaults
  * to validate an override triple against the merged result, and importing
  * `patch-lint.ts` from `config-validate.ts` for a constant would draw an
  * import edge (and a cycle) between the rule bodies and config parsing.
@@ -10,9 +10,9 @@
  * On the vocabulary: the bands were `notice` / `warning` / `error` with the
  * middle one described as a "soft limit". That description is false under
  * the posture FireForge itself recommends for a release gate,
- * `--max-warnings 0`, where a warning is a hard failure — so a file at 751
+ * `--max-warnings 0`, where a warning is a hard failure, so a file at 751
  * lines failed a gate with a message calling 750 soft. The message below
- * says what the band IS (a warning) and what a zero-warning gate does with
+ * says what the band is (a warning) and what a zero-warning gate does with
  * it, and the thresholds are now tunable, so a project whose file-size
  * policy differs has a dial instead of an argument.
  */
@@ -44,10 +44,10 @@ export function resolveFileSizeThresholds(overrides, isTest) {
 export function formatFileTooLargeMessage(args) {
     const { label, lineCount, thresholds, band, verb } = args;
     if (band === 'error') {
-        return `${label} has ${String(lineCount)} lines (error threshold: ${String(thresholds.error)}). Consider ${verb}.`;
+        return `${label} has ${lineCount} lines (error threshold: ${thresholds.error}). Consider ${verb}.`;
     }
-    return (`${label} has ${String(lineCount)} lines (warning threshold: ${String(thresholds.warning)}, ` +
-        `error threshold: ${String(thresholds.error)}). Consider ${verb}. ` +
+    return (`${label} has ${lineCount} lines (warning threshold: ${thresholds.warning}, ` +
+        `error threshold: ${thresholds.error}). Consider ${verb}. ` +
         `Reported as a ${band}, which a gate running --max-warnings 0 treats as a failure; ` +
         `tune "patchLint.fileSizeThresholds" if these limits are wrong for this project.`);
 }

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

@@ -0,0 +1,58 @@
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { PatchQueueForwardRegistrationEntry, PatchQueueView } from './patch-lint-queue-types.js';
+/**
+ * One `support-files` entry, with the line the patch actually adds it on.
+ *
+ * The entry alone is not enough for the discharge command the rule prints:
+ * `--line` is compared, whitespace-trimmed, against the lines the patch
+ * adds, and a synthesised `support-files = ["<entry>"]` only ever matches a
+ * manifest whose array is single-line and single-entry. Carrying the source
+ * line keeps the remedy and the validation talking about the same text.
+ */
+export interface SupportFileEntry {
+    /** The entry as written inside the manifest (e.g. `fixtures/*.sqlite`). */
+    entry: string;
+    /** The first added line, whitespace-trimmed, that spells the entry out. */
+    line: string;
+    /**
+     * How many distinct added lines spell it out. Above one, the printed
+     * command quotes the first and says so: one declaration covers the file
+     * either way, because the declared check keys on file + creates.
+     */
+    occurrences: number;
+}
+/**
+ * Extracts the `support-files` entries declared in `content`, each paired
+ * with the manifest line it is written on.
+ *
+ * Handles the TOML array on one line and spread over several, and the
+ * whitespace-separated `.ini` spelling. Anything else (a computed value, a
+ * shape this does not recognise) yields nothing, because a rule that
+ * guesses at a manifest it cannot parse refuses correct queues.
+ *
+ * Quoted tokens are matched per physical line rather than over the whole
+ * accumulated array body, so a multi-line array attributes each element to
+ * its own line. Entries are deduplicated: a manifest that lists the same
+ * file under two per-test sections needs one declaration, not two.
+ */
+export declare function extractSupportFileEntries(content: string): SupportFileEntry[];
+/**
+ * Resolves one `support-files` entry, relative to its manifest's directory,
+ * into a matcher over engine-relative paths.
+ *
+ * Only a `*` inside a single path segment is expanded, the shape the
+ * downstream report uses (`fixtures/*.sqlite`). `**`, `!` exclusions and
+ * absolute `/`-rooted entries return undefined: they either cross directory
+ * boundaries or subtract, and a matcher that guessed at them would attribute
+ * a creation to the wrong manifest.
+ */
+export declare function buildSupportFileMatcher(manifestPath: string, entry: string): ((candidate: string) => boolean) | undefined;
+/**
+ * Flags every `support-files` registration a patch introduces that names a
+ * file only a later-ordered patch creates, unless the staged dependency is
+ * declared.
+ *
+ * @param ctx - Projected queue in application order
+ * @returns One issue per undeclared forward registration
+ */
+export declare function lintPatchQueueForwardRegistrations(ctx: PatchQueueView<PatchQueueForwardRegistrationEntry>): PatchLintIssue[];

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

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Cross-patch lint rule: a test manifest that registers a file a
+ * later-ordered patch creates, without declaring the staged dependency.
+ *
+ * The import kind has had this arm since forward-import shipped. The
+ * registration kind never did. `--kind registration` metadata was only ever
+ * checked for staleness once declared, so a patch whose `xpcshell.toml`
+ * carried `support-files = ["fixtures/*.sqlite"]` for a fixture the next
+ * patch creates passed lint in both arms. Declaring the dependency and
+ * removing the declaration produced identical silence, so the gap was
+ * invisible rather than merely absent.
+ *
+ * Scope is narrow on purpose: test-manifest `support-files` only. A
+ * jar.mn packaging line or an actor/customElements registration names its
+ * target through indirection the linter cannot resolve without the build
+ * system, and a rule that guesses there would refuse correct queues on a
+ * Firefox-sized tree. The staged-registration declaration remains the
+ * documented escape hatch for a deliberate stage.
+ */
+import { basename, dirname, posix } from 'node:path';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { escapeRegex } from '../utils/regex.js';
+import { isLaterOwner, quoteRegistrationLine } from './patch-lint-staged-registration.js';
+/**
+ * Manifest basenames whose `support-files` key registers auxiliary files
+ * for a test suite. Closed and documented on purpose: a pattern like
+ * "anything .toml" would sweep in Cargo and taskcluster manifests, whose
+ * `support-files`-shaped keys mean something else entirely.
+ */
+const TEST_MANIFEST_BASENAMES = new Set([
+    'xpcshell.toml',
+    'xpcshell.ini',
+    'mochitest.toml',
+    'mochitest.ini',
+    'browser.toml',
+    'browser.ini',
+    'chrome.toml',
+    'chrome.ini',
+    'a11y.toml',
+    'a11y.ini',
+]);
+/** True for a path whose basename is a recognised test manifest. */
+function isTestManifestPath(path) {
+    return TEST_MANIFEST_BASENAMES.has(basename(normalizePathSlashes(path)));
+}
+/** Matches the start of a `support-files` assignment. */
+const SUPPORT_FILES_PATTERN = /^\s*support-files\s*=\s*(.*)$/;
+/**
+ * Extracts the `support-files` entries declared in `content`, each paired
+ * with the manifest line it is written on.
+ *
+ * Handles the TOML array on one line and spread over several, and the
+ * whitespace-separated `.ini` spelling. Anything else (a computed value, a
+ * shape this does not recognise) yields nothing, because a rule that
+ * guesses at a manifest it cannot parse refuses correct queues.
+ *
+ * Quoted tokens are matched per physical line rather than over the whole
+ * accumulated array body, so a multi-line array attributes each element to
+ * its own line. Entries are deduplicated: a manifest that lists the same
+ * file under two per-test sections needs one declaration, not two.
+ */
+export function extractSupportFileEntries(content) {
+    const lines = content.split('\n');
+    const order = [];
+    const sourceLines = new Map();
+    const record = (entry, source) => {
+        let seen = sourceLines.get(entry);
+        if (seen === undefined) {
+            seen = [];
+            sourceLines.set(entry, seen);
+            order.push(entry);
+        }
+        const trimmed = source.trim();
+        if (!seen.includes(trimmed))
+            seen.push(trimmed);
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        const match = SUPPORT_FILES_PATTERN.exec(raw);
+        if (!match)
+            continue;
+        const head = match[1] ?? '';
+        if (!head.trimStart().startsWith('[')) {
+            // `.ini` spelling: whitespace-separated bare paths on one line.
+            for (const token of head.split(/\s+/).filter((t) => t.length > 0))
+                record(token, raw);
+            continue;
+        }
+        // TOML array: walk the physical lines until the closing bracket,
+        // bounded so an unterminated array in a malformed manifest cannot walk
+        // the file.
+        let body = head;
+        let scanned = 0;
+        let current = raw;
+        for (;;) {
+            for (const quoted of current.matchAll(/["']([^"']+)["']/g)) {
+                if (quoted[1] !== undefined)
+                    record(quoted[1], current);
+            }
+            if (body.includes(']') || i + 1 >= lines.length || scanned >= 200)
+                break;
+            i += 1;
+            scanned += 1;
+            current = lines[i] ?? '';
+            body += `\n${current}`;
+        }
+    }
+    return order.map((entry) => {
+        const seen = sourceLines.get(entry) ?? [];
+        return { entry, line: seen[0] ?? '', occurrences: seen.length };
+    });
+}
+/**
+ * Resolves one `support-files` entry, relative to its manifest's directory,
+ * into a matcher over engine-relative paths.
+ *
+ * Only a `*` inside a single path segment is expanded, the shape the
+ * downstream report uses (`fixtures/*.sqlite`). `**`, `!` exclusions and
+ * absolute `/`-rooted entries return undefined: they either cross directory
+ * boundaries or subtract, and a matcher that guessed at them would attribute
+ * a creation to the wrong manifest.
+ */
+export function buildSupportFileMatcher(manifestPath, entry) {
+    if (entry.startsWith('!') || entry.includes('**') || entry.startsWith('/'))
+        return undefined;
+    const resolved = posix.normalize(posix.join(normalizePathSlashes(dirname(manifestPath)), normalizePathSlashes(entry)));
+    if (resolved.startsWith('..'))
+        return undefined;
+    if (!resolved.includes('*')) {
+        return (candidate) => normalizePathSlashes(candidate) === resolved;
+    }
+    const pattern = new RegExp(`^${resolved
+        .split('*')
+        .map((part) => escapeRegex(part))
+        .join('[^/]*')}$`);
+    return (candidate) => pattern.test(normalizePathSlashes(candidate));
+}
+/** True when this patch already declares the staged registration. */
+function isDeclared(entry, manifestPath, createdPath) {
+    return (entry.metadata?.stagedDependencies?.registrations ?? []).some((registration) => normalizePathSlashes(registration.file) === normalizePathSlashes(manifestPath) &&
+        normalizePathSlashes(registration.creates) === normalizePathSlashes(createdPath));
+}
+/**
+ * Flags every `support-files` registration a patch introduces that names a
+ * file only a later-ordered patch creates, unless the staged dependency is
+ * declared.
+ *
+ * @param ctx - Projected queue in application order
+ * @returns One issue per undeclared forward registration
+ */
+export function lintPatchQueueForwardRegistrations(ctx) {
+    const issues = [];
+    for (const entry of ctx.entries) {
+        // Both arms: a manifest this patch creates and one it modifies can each
+        // introduce a registration line.
+        const manifests = [
+            ...entry.newFiles,
+            ...entry.modifiedFileAdditions,
+        ].filter(([path]) => isTestManifestPath(path));
+        for (const [manifestPath, content] of manifests) {
+            for (const { entry: raw, line: addedLine, occurrences } of extractSupportFileEntries(content)) {
+                const matches = buildSupportFileMatcher(manifestPath, raw);
+                if (matches === undefined)
+                    continue;
+                // `--line` is the line as the patch adds it, which is what the
+                // declared arm compares and what `--remove` matches on. Synthesising
+                // `support-files = ["<entry>"]` instead only ever matched a
+                // single-line single-entry array, so the pasted command left the
+                // declaring patch red with staged-dependency-unused.
+                const declaredLine = quoteRegistrationLine(addedLine);
+                const ambiguity = occurrences > 1
+                    ? ` (the entry is spelled out on ${occurrences} added lines here; ` +
+                        'the first is quoted, and one declaration covers the file either way ' +
+                        'because the declared check keys on --file and --creates.)'
+                    : '';
+                for (const later of ctx.entries) {
+                    // Same predicate the declared-registration arm validates against,
+                    // tiebreak included: two spellings of "later" would let one rule
+                    // flag a pair the other considers already satisfied.
+                    if (!isLaterOwner(later, entry))
+                        continue;
+                    for (const created of later.createdFiles) {
+                        if (!matches(created))
+                            continue;
+                        if (isDeclared(entry, manifestPath, created))
+                            continue;
+                        issues.push({
+                            file: manifestPath,
+                            check: 'forward-registration',
+                            patches: [entry.filename],
+                            fingerprint: `forward-registration|${entry.filename}|${manifestPath}|${raw}|${created}|${later.filename}`,
+                            message: `${manifestPath} in ${entry.filename} registers "${raw}" as a support file, ` +
+                                `but ${created} is created by the later patch ${later.filename}. ` +
+                                'Applying the queue up to this patch leaves the registration dangling. ' +
+                                'Reorder the patches so the file is created first, move the registration into ' +
+                                'the later patch, or declare the intentional staged dependency with: ' +
+                                `fireforge patch staged-dependency ${entry.filename} --add --kind registration ` +
+                                `--file ${manifestPath} --line "${declaredLine}" ` +
+                                `--creates ${created} --owner ${later.filename}` +
+                                ambiguity,
+                            severity: 'error',
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}

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

@@ -28,7 +28,7 @@ export interface ValidateExportJsDocOptions {
  * 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
+ * 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
@@ -54,7 +54,7 @@ export declare function validateClassDecl(cls: AcornESTreeNode<ClassDeclaration>
  *   3. methods whose JSDoc carries `@private` or `@internal`
  *
  * A pure-override skip (`super.method(...args)`-only bodies bypassing the
- * return-tag check) is deliberately not implemented; the rule stays simple.
+ * return-tag check) is deliberately not implemented. The rule stays simple.
  */
 export declare function validateClassMethods(cls: AcornESTreeNode<ClassDeclaration>, comments: acorn.Comment[], source: string, severity: 'warning' | 'error'): JsDocIssue[];
 /**

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

@@ -46,8 +46,8 @@ function findAttachedJsDoc(comments, declStart, source) {
  * loses the param name. String literal types may contain braces too, so
  * quoted runs are skipped verbatim.
  *
- * @returns Index just past the matching close brace, or -1 when the type
- *   expression never closes (malformed doc — caller skips the tag).
+ * @returns Index just past the matching close brace, or undefined when the
+ *   type expression never closes (malformed doc, caller skips the tag).
  */
 function skipBalancedTypeBraces(jsDoc, start) {
     let depth = 0;
@@ -73,7 +73,7 @@ function skipBalancedTypeBraces(jsDoc, start) {
                 return i + 1;
         }
     }
-    return -1;
+    return undefined;
 }
 function extractParamNames(jsDoc) {
     const names = [];
@@ -83,11 +83,11 @@ function extractParamNames(jsDoc) {
         let i = m.index + m[0].length;
         while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
             i++;
-        // Optional `{type}` expression — depth-aware so nested braces inside
+        // Optional `{type}` expression, depth-aware so nested braces inside
         // inline object types or Record<…> generics don't truncate the scan.
         if (jsDoc[i] === '{') {
             const afterType = skipBalancedTypeBraces(jsDoc, i);
-            if (afterType === -1)
+            if (afterType === undefined)
                 continue;
             i = afterType;
             while (i < jsDoc.length && /\s/.test(jsDoc[i] ?? ''))
@@ -124,6 +124,17 @@ function hasPrivateOrInternalTag(jsDoc) {
 function functionReturnsValue(node) {
     return walkForReturn(node.body);
 }
+/**
+ * Narrows an arbitrary child value reached by walking a node's own
+ * properties to an ESTree node. Acorn's AST holds nodes, arrays of nodes,
+ * and plain scalars in the same property positions, so the discriminating
+ * `type` string is the only structural signal available.
+ */
+function isEstreeNode(value) {
+    if (typeof value !== 'object' || value === null || !('type' in value))
+        return false;
+    return typeof value.type === 'string';
+}
 function walkForReturn(node) {
     if (node.type === 'ReturnStatement') {
         return node.argument != null;
@@ -133,26 +144,22 @@ function walkForReturn(node) {
         node.type === 'ArrowFunctionExpression') {
         return false;
     }
-    // `entries` erases the node's static shape without asserting a new one;
-    // the `any` from `Object.entries`' fallback overload widens to `unknown`.
+    // `entries` erases the node's static shape without asserting a new one.
+    // The `any` from `Object.entries`' fallback overload widens to `unknown`.
     const entries = Object.entries(node);
     for (const [key, val] of entries) {
         if (key === 'type')
             continue;
-        if (val && typeof val === 'object') {
-            if (Array.isArray(val)) {
-                for (const child of val) {
-                    if (child && typeof child === 'object' && 'type' in child) {
-                        if (walkForReturn(child))
-                            return true;
-                    }
-                }
-            }
-            else if ('type' in val) {
-                if (walkForReturn(val))
+        if (Array.isArray(val)) {
+            const children = val;
+            for (const child of children) {
+                if (isEstreeNode(child) && walkForReturn(child))
                     return true;
             }
         }
+        else if (isEstreeNode(val) && walkForReturn(val)) {
+            return true;
+        }
     }
     return false;
 }
@@ -183,12 +190,7 @@ function findLocalDeclaration(body, name) {
 // Line number helpers
 // ---------------------------------------------------------------------------
 function lineAt(source, offset) {
-    let line = 1;
-    for (let i = 0; i < offset && i < source.length; i++) {
-        if (source[i] === '\n')
-            line++;
-    }
-    return line;
+    return source.slice(0, offset).split('\n').length;
 }
 /**
  * Validates @param name matching and @returns presence on a function-like
@@ -198,21 +200,19 @@ function lineAt(source, offset) {
  */
 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 } : {}),
-                    });
-                }
+    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 } : {}),
+                });
             }
         }
     }
@@ -232,7 +232,7 @@ function validateParamsAndReturns(fnNode, jsDoc, issues, ctx) {
  * 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
+ * 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
@@ -290,7 +290,7 @@ function validateVariableDecl(varDecl, comments, source, lookupStart) {
     const start = lookupStart !== undefined ? lookupStart : varDecl.start;
     const jsDoc = findAttachedJsDoc(comments, start, source);
     if (jsDoc)
-        return issues; // 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);
@@ -340,7 +340,7 @@ function classMethodLabel(className, method, name) {
  *   3. methods whose JSDoc carries `@private` or `@internal`
  *
  * A pure-override skip (`super.method(...args)`-only bodies bypassing the
- * return-tag check) is deliberately not implemented; the rule stays simple.
+ * return-tag check) is deliberately not implemented. The rule stays simple.
  */
 export function validateClassMethods(cls, comments, source, severity) {
     const issues = [];
@@ -374,7 +374,7 @@ export function validateClassMethods(cls, comments, source, severity) {
             continue;
         }
         if (method.kind === 'get') {
-            // Presence already verified; getter expression is the contract.
+            // Presence already verified. The getter expression is the contract.
             continue;
         }
         const skipReturns = method.kind === 'constructor' || method.kind === 'set';
@@ -407,7 +407,7 @@ export function validateExportJsDoc(source, options) {
         ast = parseModule(source, comments);
     }
     catch (error) {
-        // An unparseable source is NOT a clean file. Returning `[]` here was the
+        // An unparseable source is not a clean file. Returning `[]` here was the
         // same value as "fully documented", so a syntax error silently cleared
         // every rule this module enforces. Report it instead.
         return [
@@ -424,7 +424,7 @@ export function validateExportJsDoc(source, options) {
         if (node.type !== 'ExportNamedDeclaration')
             continue;
         const exportNode = node;
-        // Case 1: inline export declaration — JSDoc attaches to `export`
+        // Case 1: inline export declaration, JSDoc attaches to `export`
         if (exportNode.declaration) {
             const decl = exportNode.declaration;
             const exportStart = exportNode.start;
@@ -442,7 +442,7 @@ export function validateExportJsDoc(source, options) {
             }
             continue;
         }
-        // Case 2: `export { foo, Bar }` — resolve back to local declarations
+        // Case 2: `export { foo, Bar }`, resolve back to local declarations
         if (exportNode.specifiers.length > 0 && !exportNode.source) {
             for (const spec of exportNode.specifiers) {
                 const local = spec.local;

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

@@ -1,12 +1,6 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
-interface ModuleRegistrationQueueEntry {
-    filename: string;
-    newFiles: ReadonlyMap<string, string>;
-    modifiedFileAdditions: ReadonlyMap<string, string>;
-}
-interface ModuleRegistrationQueueContext {
-    entries: readonly ModuleRegistrationQueueEntry[];
-}
+import type { PatchQueueRegistrationEntry, PatchQueueView } from './patch-lint-queue-types.js';
+type ModuleRegistrationQueueContext = PatchQueueView<PatchQueueRegistrationEntry>;
 /**
  * Maps Firefox's common system-module resource URLs to their source
  * suffix. Exported alongside {@link extractResourceModuleSpecifiers} so
@@ -16,7 +10,7 @@ export declare function moduleSourceSuffix(specifier: string): string | undefine
 /**
  * Resource-module strings in actual code (comments removed), de-duplicated.
  * Exported for the engine-aware resolution preflight, which must recognise
- * exactly the same specifier shapes this queue-level rule does — two
+ * exactly the same specifier shapes this queue-level rule does. Two
  * extractors would drift.
  */
 export declare function extractResourceModuleSpecifiers(content: string): string[];

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

@@ -21,7 +21,7 @@ export function moduleSourceSuffix(specifier) {
 /**
  * Resource-module strings in actual code (comments removed), de-duplicated.
  * Exported for the engine-aware resolution preflight, which must recognise
- * exactly the same specifier shapes this queue-level rule does — two
+ * exactly the same specifier shapes this queue-level rule does. Two
  * extractors would drift.
  */
 export function extractResourceModuleSpecifiers(content) {

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

@@ -3,7 +3,7 @@
  *
  * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
  * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got
- * "Y"` — but only at CONFIGURE time, i.e. minutes into a `fireforge build`
+ * "Y"`, but only at configure time, i.e. minutes into a `fireforge build`
  * or `fireforge test --build` dispatch. This check reads the patched
  * `moz.build` files from the engine tree (the working tree carries the
  * applied patch state, same as every other per-patch rule) and reports the