@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -34,13 +34,24 @@ export interface PatchQueueEntry {
      * are not indexed here.
      */
     newFiles: Map<string, string>;
+    /**
+     * Every path this patch creates, whatever the body kind: text, a
+     * reconstructable `GIT binary patch`, or a payload-less
+     * `Binary files … differ` stub. `newFiles` is text-only by design (a
+     * binary authors no imports, so the import rules gain nothing from it and
+     * `extractNewFileContent` correctly refuses to decode one), but "does a
+     * later patch create this path" is a question about existence after apply,
+     * not about content, and answering it from `newFiles` made every binary
+     * creation invisible to the staged-registration rules.
+     */
+    createdFiles: Set<string>;
     /**
      * Map from existing-file path → concatenated added lines from the patch's
      * hunks against that file (joined with `\n`). Populated for files the
      * patch *modifies* (i.e. paths that show up in the diff without a
      * `new file mode` marker). The forward-import rule and `patch delete`
      * dependency scan use this to detect imports added into pre-existing
-     * files — a failure mode the newFiles map cannot represent because it
+     * files, a failure mode the newFiles map cannot represent because it
      * only tracks creations.
      */
     modifiedFileAdditions: Map<string, string>;
@@ -49,7 +60,7 @@ export interface PatchQueueEntry {
  * Queue-wide context passed to cross-patch lint rules.
  *
  * "Projected" means rules receive a potentially hypothetical view of the
- * queue — the caller may have already applied a planned delete, reorder, or
+ * queue: the caller may have already applied a planned delete, reorder, or
  * re-export to the entries before calling the rule. This lets
  * `patch reorder`, `patch delete`, `export --order`, and `re-export --files`
  * run the same cross-patch checks they would hit on a real run, without
@@ -73,7 +84,7 @@ export interface PatchQueueContext {
  * Reads manifest metadata best-effort: if the manifest is missing or a patch
  * file has no metadata entry, the context still populates the entry from the
  * filename prefix so cross-patch rules can operate on a drift state. (A
- * separate consistency check — see `patches verify` — is responsible for
+ * separate consistency check, see `patches verify`, is responsible for
  * reporting the drift as its own error.)
  *
  * @param patchesDir - Path to the patches directory
@@ -100,22 +111,19 @@ export declare function isForwardImportableFile(path: string): boolean;
  *
  * Intentionally conservative. Catches:
  * - `import ... from "specifier"`   (ES module static imports)
- * - `import "specifier"`            (side-effect imports — the `from`
+ * - `import "specifier"`            (side-effect imports, where the `from`
  *                                   clause is optional in the regex)
  * - `import("specifier")`           (dynamic imports)
  * - ChromeUtils.importESModule("specifier")
  * - ChromeUtils.defineESModuleGetters(obj, { Name: "specifier", ... })
  *
- * Returns the raw specifier strings — callers should take the leaf basename
+ * Returns the raw specifier strings. Callers should take the leaf basename
  * to match against the newFileIndex, because we do not resolve `resource://`
  * URLs to engine file paths.
- */
-export declare function extractImportSpecifiers(source: string): string[];
-/**
- * Internal form of {@link extractImportSpecifiers} that also returns the
- * (0-indexed) line number where each specifier was found. Used by the
- * forward-import rule so it can correlate specifiers against the
- * ignore-marker line set and skip suppressed matches.
+ *
+ * Also returns the (0-indexed) line number where each specifier was found, so
+ * the forward-import rule can correlate specifiers against the ignore-marker
+ * line set and skip suppressed matches.
  */
 export interface ExtractedSpecifier {
     specifier: string;
@@ -123,7 +131,7 @@ export interface ExtractedSpecifier {
 }
 /**
  * Returns import specifiers plus 0-indexed line numbers, preserving the
- * same matching behavior as {@link extractImportSpecifiers}.
+ * same matching behavior as {@link extractImportSpecifiersWithLines}.
  */
 export declare function extractImportSpecifiersWithLines(source: string): ExtractedSpecifier[];
 /**
@@ -154,19 +162,19 @@ export declare function findForwardImportIgnoreLines(source: string): Set<number
  * Cross-patch lint rule: a patch imports a module that a later patch is
  * responsible for creating.
  *
- * Deliberately conservative — `resource://` URLs are not resolved to engine
+ * Conservative by design: `resource://` URLs are not resolved to engine
  * file paths. Instead a cross-queue index of newly-created files is built,
  * keyed by basename, and imports whose leaf matches an entry owned by a
  * later-ordered patch are flagged. False positives from unrelated basename
- * collisions (two directories both creating `Helper.sys.mjs`) are possible;
- * the README documents the limitation and the inline ignore marker above is
+ * collisions (two directories both creating `Helper.sys.mjs`) are possible.
+ * The README documents the limitation and the inline ignore marker above is
  * the escape hatch.
  *
  * Rules out:
  * - Imports whose leaf matches a newly-created file in the *same* or an
  *   *earlier* patch (legitimate use).
  * - Imports whose leaf is not in the new-file index at all (pre-existing
- *   engine file — not our concern).
+ *   engine file, not our concern).
  * - Imports on a line suppressed by the ignore marker.
  */
 /** One discovered forward-import edge: a site importing a later-created file. */
@@ -196,8 +204,8 @@ export declare function collectForwardImportEdges(ctx: PatchQueueContext): Forwa
  * Cross-patch lint rule: flag imports of a module a later-ordered patch is
  * responsible for creating, unless the patch declares an exact staged
  * forward-import for it. Also warns on staged-dependency declarations that
- * never matched (stale). Matching is conservative — by basename, not by
- * resolving `resource://`/`chrome://` URLs — with an inline ignore marker as
+ * never matched (stale). Matching is conservative: by basename, not by
+ * resolving `resource://`/`chrome://` URLs, with an inline ignore marker as
  * an escape hatch for unrelated basename collisions.
  */
 export declare function lintPatchQueueForwardImports(ctx: PatchQueueContext): PatchLintIssue[];

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

@@ -19,7 +19,9 @@ import { discoverPatches } from './patch-files.js';
 import { lintPatchQueueBinaryBodies } from './patch-lint-binary.js';
 import { collectNewFileCreatorsByPath } from './patch-lint-creators.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
+import { lintPatchQueueForwardRegistrations } from './patch-lint-forward-registration.js';
 import { lintPatchQueueModuleRegistrations } from './patch-lint-module-registration.js';
+import { describeRegistrationFailure, findStagedRegistrationFailure, isLaterOwner, quoteRegistrationLine, } from './patch-lint-staged-registration.js';
 import { loadPatchesManifest } from './patch-manifest-io.js';
 import { categoryRangeForOrder, categoryRangeLabel } from './patch-policy.js';
 import { extractNewFileContent } from './patch-transform.js';
@@ -30,7 +32,7 @@ import { extractNewFileContent } from './patch-transform.js';
  * Reads manifest metadata best-effort: if the manifest is missing or a patch
  * file has no metadata entry, the context still populates the entry from the
  * filename prefix so cross-patch rules can operate on a drift state. (A
- * separate consistency check — see `patches verify` — is responsible for
+ * separate consistency check, see `patches verify`, is responsible for
  * reporting the drift as its own error.)
  *
  * @param patchesDir - Path to the patches directory
@@ -61,7 +63,7 @@ export async function buildPatchQueueContext(patchesDir, config) {
         // Added-line content for every file the patch modifies but does not
         // create. Fed to the forward-import rule so imports introduced into
         // pre-existing files are checked too, not only imports in brand-new
-        // files. We deliberately skip paths in newFilePaths — those are
+        // files. Paths in newFilePaths are skipped on purpose: they are
         // already covered by the newFiles map, which carries full content
         // rather than only the added lines.
         const addedLinesByFile = extractAddedLinesPerFile(diff);
@@ -77,6 +79,9 @@ export async function buildPatchQueueContext(patchesDir, config) {
             metadata: metadataByFilename.get(patch.filename) ?? null,
             diff,
             newFiles,
+            // Straight from the detector, before the text-extraction filter above
+            // drops the bodies it cannot decode.
+            createdFiles: newFilePaths,
             modifiedFileAdditions,
         });
     }
@@ -86,7 +91,7 @@ export async function buildPatchQueueContext(patchesDir, config) {
 }
 // The creators map (split out of `lintPatchQueueDuplicateCreations` so
 // `status --ownership` can consume the structured data) lives in
-// `patch-lint-creators.ts` with its per-context memoisation;
+// `patch-lint-creators.ts` with its per-context memoisation. It is
 // re-exported here so callers keep importing from `patch-lint.ts`.
 export { collectNewFileCreatorsByPath, invalidateNewFileCreatorsCache, } from './patch-lint-creators.js';
 /**
@@ -125,24 +130,6 @@ const FORWARD_IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
 export function isForwardImportableFile(path) {
     return FORWARD_IMPORTABLE_EXTENSIONS.some((ext) => path.endsWith(ext));
 }
-/**
- * Regex-level extractor for module specifiers in ES module / subscript files.
- *
- * Intentionally conservative. Catches:
- * - `import ... from "specifier"`   (ES module static imports)
- * - `import "specifier"`            (side-effect imports — the `from`
- *                                   clause is optional in the regex)
- * - `import("specifier")`           (dynamic imports)
- * - ChromeUtils.importESModule("specifier")
- * - ChromeUtils.defineESModuleGetters(obj, { Name: "specifier", ... })
- *
- * Returns the raw specifier strings — callers should take the leaf basename
- * to match against the newFileIndex, because we do not resolve `resource://`
- * URLs to engine file paths.
- */
-export function extractImportSpecifiers(source) {
-    return extractImportSpecifiersWithLines(source).map((item) => item.specifier);
-}
 function buildLineOffsets(source) {
     const offsets = [0];
     for (let i = 0; i < source.length; i++) {
@@ -181,7 +168,7 @@ function collectGetterSpecifiers(stripped, results, offsetToLine) {
         const openParen = stripped.indexOf('(', match.index);
         if (openParen === -1)
             continue;
-        // Walk to the first top-level `{` inside the call — the start of
+        // Walk to the first top-level `{` inside the call, the start of
         // the getter-map object literal. Bail if we reach the closing `)`
         // first (no object literal argument given).
         let depthParen = 1;
@@ -236,14 +223,14 @@ function collectGetterSpecifiers(stripped, results, offsetToLine) {
 }
 /**
  * Returns import specifiers plus 0-indexed line numbers, preserving the
- * same matching behavior as {@link extractImportSpecifiers}.
+ * same matching behavior as {@link extractImportSpecifiersWithLines}.
  */
 export function extractImportSpecifiersWithLines(source) {
     // stripJsComments replaces comment bodies with space runs of equal
     // length, preserving character offsets. That lets us match against
     // the stripped source (so we do not match `import` tokens inside
     // block comments or string literals) while still reporting line
-    // numbers based on the ORIGINAL source, which is what the
+    // numbers based on the original source, which is what the
     // ignore-marker scan walks.
     const stripped = stripJsComments(source);
     const results = [];
@@ -260,7 +247,7 @@ export function extractImportSpecifiersWithLines(source) {
         if (match[1])
             results.push({ specifier: match[1], line: offsetToLine(match.index) });
     }
-    // ChromeUtils.importESModule("resource://...") — Firefox single-module import
+    // ChromeUtils.importESModule("resource://...") is a Firefox single-module import
     const chromeUtilsPattern = /ChromeUtils\.importESModule\s*\(\s*["']([^"']+)["']/g;
     while ((match = chromeUtilsPattern.exec(stripped)) !== null) {
         if (match[1])
@@ -270,14 +257,14 @@ export function extractImportSpecifiersWithLines(source) {
     return results;
 }
 /**
- * Bare `Name: "url"` property lines added inside a PRE-EXISTING
- * `defineESModuleGetters` (or `XPCOMUtils` lazy-getter) map. Applied ONLY to
+ * Bare `Name: "url"` property lines added inside a pre-existing
+ * `defineESModuleGetters` (or `XPCOMUtils` lazy-getter) map. Applied only to
  * `modifiedFileAdditions`: a patch that inserts one property into an
  * existing getter object never carries the `defineESModuleGetters(` opener
  * in its added lines, so the balanced-brace walk in
  * {@link extractImportSpecifiersWithLines} cannot see it. The
  * URL-scheme restriction keeps ordinary object literals
- * (`label: "Foo.sys.mjs"`) out; the leaf-extension filter downstream does
+ * (`label: "Foo.sys.mjs"`) out. The leaf-extension filter downstream does
  * the rest.
  */
 const BARE_GETTER_PROPERTY_LINE = /^\s*(?:["'])?[A-Za-z_$][\w$]*(?:["'])?\s*:\s*["']((?:resource|chrome|moz-src):\/\/[^"']+)["']\s*,?\s*$/;
@@ -290,8 +277,8 @@ function extractBareGetterSpecifiers(source) {
     const stripped = stripJsComments(source);
     const results = [];
     const lines = stripped.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-        const match = BARE_GETTER_PROPERTY_LINE.exec(lines[i] ?? '');
+    for (const [i, line] of lines.entries()) {
+        const match = BARE_GETTER_PROPERTY_LINE.exec(line);
         if (match?.[1])
             results.push({ specifier: match[1], line: i });
     }
@@ -323,9 +310,8 @@ export const FORWARD_IMPORT_IGNORE_MARKER = 'fireforge-ignore: forward-import';
 export function findForwardImportIgnoreLines(source) {
     const lines = source.split('\n');
     const ignored = new Set();
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line && line.includes(FORWARD_IMPORT_IGNORE_MARKER)) {
+    for (const [i, line] of lines.entries()) {
+        if (line.includes(FORWARD_IMPORT_IGNORE_MARKER)) {
             ignored.add(i);
             ignored.add(i + 1);
         }
@@ -348,36 +334,51 @@ function findMatchingStagedDependency(entry, sitePath, specifier, laterOwners) {
         laterOwners.some((owner) => owner.fullPath === dependency.creates &&
             (dependency.owner === undefined || dependency.owner === owner.filename)));
 }
-/**
- * Later-in-apply-order predicate shared by the forward-import scan and the
- * registration validation: strictly higher ordinal, or same ordinal with a
- * lexicographically later filename (the apply loop's tiebreak).
- */
-function isLaterOwner(owner, entry) {
-    return (owner.order > entry.order || (owner.order === entry.order && owner.filename > entry.filename));
-}
-/** Builds the basename → later-creators index used by the forward-import scan. */
-function buildNewFileIndex(ctx) {
-    const newFileIndex = new Map();
+/** Builds a basename → creators index from one path set per entry. */
+function buildCreatorIndex(ctx, pathsOf) {
+    const index = new Map();
     for (const entry of ctx.entries) {
-        for (const fullPath of entry.newFiles.keys()) {
+        for (const fullPath of pathsOf(entry)) {
             const leaf = basename(fullPath);
-            let owners = newFileIndex.get(leaf);
+            let owners = index.get(leaf);
             if (!owners) {
                 owners = [];
-                newFileIndex.set(leaf, owners);
+                index.set(leaf, owners);
             }
             owners.push({ filename: entry.filename, order: entry.order, fullPath });
         }
     }
-    return newFileIndex;
+    return index;
+}
+/**
+ * Basename → later-creators index for the forward-IMPORT scan.
+ *
+ * Keyed on `newFiles`: this index answers "which patch creates
+ * the module this specifier resolves to", and a binary is not a module.
+ */
+function buildNewFileIndex(ctx) {
+    return buildCreatorIndex(ctx, (entry) => entry.newFiles.keys());
+}
+/**
+ * Basename → creators index for the staged-REGISTRATION rules.
+ *
+ * Keyed on `createdFiles`, which includes binary creations. A registration
+ * (`support-files`, a jar.mn line, an actor entry) points at a file that
+ * must exist after apply. Whether its body was text or a `GIT binary patch`
+ * has nothing to do with it. Resolving this from `newFiles` made a declared
+ * dependency on a binary fixture report `creates-unresolved`, so the
+ * declaration read as stale on every lint run and removing it changed
+ * nothing either. The failure was symmetric and therefore invisible.
+ */
+function buildCreatedFileIndex(ctx) {
+    return buildCreatorIndex(ctx, (entry) => entry.createdFiles);
 }
 /**
  * Visits every forward-import site (an import whose leaf is created by a
  * later-ordered patch). Shared by {@link lintPatchQueueForwardImports} (which
  * resolves/reports each) and {@link collectForwardImportEdges} (which returns
  * them structurally). We scan a created file's full body and a modified
- * file's added lines only — flagging imports *this patch introduces*, not
+ * file's added lines only, so it flags imports *this patch introduces*, not
  * pre-existing HEAD imports that happen to collide with a later-created file.
  */
 function eachForwardImportSite(ctx, newFileIndex, visit) {
@@ -388,10 +389,10 @@ function eachForwardImportSite(ctx, newFileIndex, visit) {
         if (includeBareGetterLines) {
             // Dedupe by (specifier, line): a patch that adds the whole getter
             // call carries both the opener (found by the balanced walk) and the
-            // property line (found here) — report each site once.
-            const seen = new Set(sites.map((site) => `${site.specifier}|${String(site.line)}`));
+            // property line (found here), so report each site once.
+            const seen = new Set(sites.map((site) => `${site.specifier}|${site.line}`));
             for (const extra of extractBareGetterSpecifiers(content)) {
-                if (!seen.has(`${extra.specifier}|${String(extra.line)}`))
+                if (!seen.has(`${extra.specifier}|${extra.line}`))
                     sites.push(extra);
             }
         }
@@ -447,12 +448,13 @@ export function collectForwardImportEdges(ctx) {
  * Cross-patch lint rule: flag imports of a module a later-ordered patch is
  * responsible for creating, unless the patch declares an exact staged
  * forward-import for it. Also warns on staged-dependency declarations that
- * never matched (stale). Matching is conservative — by basename, not by
- * resolving `resource://`/`chrome://` URLs — with an inline ignore marker as
+ * never matched (stale). Matching is conservative: by basename, not by
+ * resolving `resource://`/`chrome://` URLs, with an inline ignore marker as
  * an escape hatch for unrelated basename collisions.
  */
 export function lintPatchQueueForwardImports(ctx) {
     const newFileIndex = buildNewFileIndex(ctx);
+    const createdFileIndex = buildCreatedFileIndex(ctx);
     const issues = [];
     const usedStagedDeclarations = new Set();
     eachForwardImportSite(ctx, newFileIndex, (entry, sitePath, specifier, cleaned, laterOwners) => {
@@ -468,11 +470,11 @@ 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 —
+        // Lowest ordinal that lands after every later-ordered creator. It
         // turns the operator's "guess and re-run" loop into a single shot
         // when the only fix is reordering. When patchPolicy is available and
         // that ordinal falls outside the importing patch's category range,
-        // `patch reorder` would refuse it — suppress the hint and point at
+        // `patch reorder` would refuse it, so suppress the hint and point at
         // the staged-dependency remedy instead.
         const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
         const category = entry.metadata?.category ?? /^\d+-([a-z]+)-/.exec(entry.filename)?.[1];
@@ -524,14 +526,14 @@ export function lintPatchQueueForwardImports(ctx) {
         }
         // Registration-kind declarations: a jar.mn packaging line,
         // customElements registration, or actor registration referencing a
-        // later-created file. There is no import specifier to match — the
+        // later-created file. There is no import specifier to match. The
         // declaration is "used" when the declared line (whitespace-trimmed)
-        // appears among the lines this patch adds to the declaring file AND its
+        // appears among the lines this patch adds to the declaring file and its
         // `creates` resolves to a file a later-ordered patch actually creates
-        // (with `owner`, when set, naming that patch) — mirroring
+        // (with `owner`, when set, naming that patch), mirroring
         // findMatchingStagedDependency for the import kind.
         for (const registration of entry.metadata?.stagedDependencies?.registrations ?? []) {
-            const failure = findStagedRegistrationFailure(entry, registration, newFileIndex);
+            const failure = findStagedRegistrationFailure(entry, registration, createdFileIndex);
             if (failure === undefined)
                 continue;
             issues.push({
@@ -541,62 +543,16 @@ export function lintPatchQueueForwardImports(ctx) {
                 fingerprint: `staged-dependency-unused|${entry.filename}|${registration.file}|reg:${registration.line}|${registration.creates}|${registration.owner ?? ''}`,
                 message: `${entry.filename} declares a staged registration in ${registration.file} ` +
                     `("${registration.line}") for ${registration.creates}, but ${describeRegistrationFailure(failure)} ` +
-                    'Remove the stale declaration with "fireforge patch staged-dependency --remove --kind registration" or update it to match the patch and queue.',
+                    'Remove the stale declaration with: ' +
+                    `fireforge patch staged-dependency ${entry.filename} --remove --kind registration ` +
+                    `--file ${registration.file} --line "${quoteRegistrationLine(registration.line)}" ` +
+                    `--creates ${registration.creates}; or update it to match the patch and queue.`,
                 severity: 'warning',
             });
         }
     }
     return issues;
 }
-/**
- * Validates one registration-kind declaration against the patch content
- * and the queue, mirroring {@link findMatchingStagedDependency}: the
- * declared line must be added by this patch, `creates` must exactly match
- * a file a LATER-ordered patch creates (an earlier-only creator means the
- * dependency is already satisfied and the declaration is stale), and
- * `owner`, when set, must name one of those creating patches. Returns
- * undefined when valid.
- */
-function findStagedRegistrationFailure(entry, registration, newFileIndex) {
-    if (!isRegistrationLinePresent(entry, registration))
-        return { kind: 'line-absent' };
-    const creators = (newFileIndex.get(basename(registration.creates)) ?? []).filter((owner) => owner.fullPath === registration.creates && isLaterOwner(owner, entry));
-    if (creators.length === 0)
-        return { kind: 'creates-unresolved' };
-    if (registration.owner !== undefined &&
-        !creators.some((owner) => owner.filename === registration.owner)) {
-        return { kind: 'owner-mismatch', creators };
-    }
-    return undefined;
-}
-/** Message tail for each {@link StagedRegistrationFailure} shape. */
-function describeRegistrationFailure(failure) {
-    switch (failure.kind) {
-        case 'line-absent':
-            return 'the patch does not add that line.';
-        case 'creates-unresolved':
-            return ('no later-ordered patch creates that file — the declaration is stale, ' +
-                'or the queue order no longer stages it.');
-        case 'owner-mismatch':
-            return `that file is created by ${failure.creators.map((o) => o.filename).join(', ')}, not the declared owner.`;
-    }
-}
-/**
- * True when the declared registration/packaging line appears (trimmed)
- * among the lines the patch introduces in the declaring file — either as a
- * newly-created file's content or as added lines to an existing file
- * (where jar.mn / customElements.js / actor-registration edits land).
- */
-function isRegistrationLinePresent(entry, registration) {
-    const declared = registration.line.trim();
-    if (declared.length === 0)
-        return false;
-    const introduced = [
-        entry.newFiles.get(registration.file),
-        entry.modifiedFileAdditions.get(registration.file),
-    ];
-    return introduced.some((content) => content !== undefined && content.split('\n').some((line) => line.trim() === declared));
-}
 /**
  * Cross-patch lint orchestrator. Runs every cross-patch rule against the
  * provided context and returns combined issues.
@@ -614,6 +570,7 @@ export function lintPatchQueue(ctx) {
         ...lintPatchQueueDuplicateCreations(ctx),
         ...lintPatchQueueForwardImports(ctx),
         ...lintPatchQueueModuleRegistrations(ctx),
+        ...lintPatchQueueForwardRegistrations(ctx),
         ...lintPatchQueueBinaryBodies(ctx),
     ];
 }

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

@@ -3,7 +3,7 @@
  * custom-property references.
  *
  * Split out of `patch-lint.ts` so each rule family stays within the
- * per-file line budget; `patch-lint.ts` re-exports `lintPatchedCss` so
+ * per-file line budget. `patch-lint.ts` re-exports `lintPatchedCss` so
  * existing callers keep importing from the single module.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';

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

@@ -4,7 +4,7 @@
  * custom-property references.
  *
  * Split out of `patch-lint.ts` so each rule family stays within the
- * per-file line budget; `patch-lint.ts` re-exports `lintPatchedCss` so
+ * per-file line budget. `patch-lint.ts` re-exports `lintPatchedCss` so
  * existing callers keep importing from the single module.
  */
 import { join } from 'node:path';
@@ -15,7 +15,7 @@ import { hasRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { extractAddedLineNumbersPerFile, extractAddedLinesPerFile } from './patch-lint-diff.js';
 /**
- * Loads the furnace token-prefix lint inputs gracefully — returns
+ * Loads the furnace token-prefix lint inputs gracefully. Returns
  * undefined (skipping the token-prefix check) when furnace.json cannot
  * be loaded or no tokenPrefix is configured.
  */
@@ -38,7 +38,7 @@ async function loadCssTokenContext(repoDir) {
 }
 /**
  * Masks CSS block comments with spaces, preserving newlines so line
- * numbers stay stable. An unclosed trailing `/*` is masked to EOF —
+ * numbers stay stable. An unclosed trailing `/*` is masked to EOF,
  * matching how a CSS parser treats it.
  */
 function maskCssComments(source) {
@@ -60,7 +60,7 @@ const RAW_COLOR_IGNORE_MARKER = 'fireforge-ignore: raw-color-value';
  * comment spanning the context/added boundary suppresses its hex, then
  * only the patch's added line numbers are scanned. Returns undefined
  * when any added line number falls outside the on-disk file (patch not
- * applied / drifted) — the caller then falls back to the legacy
+ * applied / drifted). The caller then falls back to the legacy
  * joined-added-lines scan rather than misattributing lines.
  */
 function buildAddedLinesScanSource(rawCss, addedNumbers) {
@@ -73,14 +73,11 @@ function buildAddedLinesScanSource(rawCss, addedNumbers) {
         .map((n) => maskedLines[n - 1] ?? '')
         .join('\n');
 }
-/**
- * Raw-color check for one patched CSS file, scoped to introduced lines
- * when diff context is available. Pushes onto `issues`.
- */
-function checkRawColorValues(file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues) {
+function checkRawColorValues(input) {
+    const { file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues } = input;
     // Check only introduced raw color values when diff context is available.
     // Skip files on the raw-color allowlist (exact path or basename match) and
-    // auto-exempt files under `browser/branding/` — those are the fork's
+    // auto-exempt files under `browser/branding/`: those are the fork's
     // visual identity assets (app-about dialogs, installer pages, branded CSS
     // copied from Firefox's `unofficial` template) and belong to the
     // design-decision layer the design-token system does not govern. Without
@@ -207,7 +204,14 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
         const rawCss = await readText(filePath);
         // Strip block comments before scanning
         const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        checkRawColorValues(file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues);
+        checkRawColorValues({
+            file,
+            rawCss,
+            addedLinesByFile,
+            addedLineNumbersByFile,
+            config,
+            issues,
+        });
         checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
     }
     return issues;

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

@@ -12,7 +12,7 @@ import type { PatchLintIssue } from '../types/commands/index.js';
 /**
  * Collects engine-relative paths that changed between `rev` and `HEAD`,
  * plus any workdir modifications and untracked files. An empty set means
- * "no diff we can prove" — downstream treats every issue as `cumulative`
+ * "no diff we can prove". Downstream treats every issue as `cumulative`
  * in that case (operator ran `lint --since HEAD` with no pending work).
  * @param engineDir Path to the engine git repository.
  * @param rev Git revision to diff against (e.g. `HEAD`, a branch, a SHA).
@@ -28,10 +28,10 @@ export declare const AGGREGATE_PATCH_FILE = "(patch)";
 /**
  * Annotates a list of lint issues with `introduced` / `cumulative` tags
  * based on whether the issue's file is part of the supplied diff set.
- * Mutates each issue in place AND returns the list for chaining.
+ * Mutates each issue in place and returns the list for chaining.
  *
- * Issues with no file (`issue.file === ''`) — e.g. cross-patch rules that
- * describe queue-wide state — are always `cumulative` under `--since`
+ * Issues with no file (`issue.file === ''`), for example cross-patch rules
+ * that describe queue-wide state, are always `cumulative` under `--since`
  * because they describe drift accumulated across many commits, not a single
  * current-task edit.
  *
@@ -39,7 +39,7 @@ export declare const AGGREGATE_PATCH_FILE = "(patch)";
  * synthetic placeholder that can never appear in a real `diffFiles` set.
  * Without special-casing, `large-patch-files` / `large-patch-lines` are
  * always tagged `[cumulative]` under `--only-introduced` even when the diff
- * IS the aggregate the rules measured, which reads as "this pre-existed" to
+ * is the aggregate the rules measured, which reads as "this pre-existed" to
  * an operator asking "what did this diff introduce?". The aggregate tag is
  * therefore promoted to `introduced` whenever the diff set has any content:
  * a non-empty `diffFiles` means the operator asked about a specific diff

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

@@ -17,7 +17,7 @@ import { getUntrackedFiles } from './git-status.js';
 /**
  * Collects engine-relative paths that changed between `rev` and `HEAD`,
  * plus any workdir modifications and untracked files. An empty set means
- * "no diff we can prove" — downstream treats every issue as `cumulative`
+ * "no diff we can prove". Downstream treats every issue as `cumulative`
  * in that case (operator ran `lint --since HEAD` with no pending work).
  * @param engineDir Path to the engine git repository.
  * @param rev Git revision to diff against (e.g. `HEAD`, a branch, a SHA).
@@ -68,10 +68,10 @@ export const AGGREGATE_PATCH_FILE = '(patch)';
 /**
  * Annotates a list of lint issues with `introduced` / `cumulative` tags
  * based on whether the issue's file is part of the supplied diff set.
- * Mutates each issue in place AND returns the list for chaining.
+ * Mutates each issue in place and returns the list for chaining.
  *
- * Issues with no file (`issue.file === ''`) — e.g. cross-patch rules that
- * describe queue-wide state — are always `cumulative` under `--since`
+ * Issues with no file (`issue.file === ''`), for example cross-patch rules
+ * that describe queue-wide state, are always `cumulative` under `--since`
  * because they describe drift accumulated across many commits, not a single
  * current-task edit.
  *
@@ -79,7 +79,7 @@ export const AGGREGATE_PATCH_FILE = '(patch)';
  * synthetic placeholder that can never appear in a real `diffFiles` set.
  * Without special-casing, `large-patch-files` / `large-patch-lines` are
  * always tagged `[cumulative]` under `--only-introduced` even when the diff
- * IS the aggregate the rules measured, which reads as "this pre-existed" to
+ * is the aggregate the rules measured, which reads as "this pre-existed" to
  * an operator asking "what did this diff introduce?". The aggregate tag is
  * therefore promoted to `introduced` whenever the diff set has any content:
  * a non-empty `diffFiles` means the operator asked about a specific diff

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

@@ -5,7 +5,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.
  */
@@ -22,8 +22,8 @@ export declare function extractAddedLinesPerFile(diffContent: string): Map<strin
  * 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 declare function extractAddedLineNumbersPerFile(diffContent: string): Map<string, number[]>;
 /**
@@ -34,7 +34,7 @@ export declare function extractAddedLineNumbersPerFile(diffContent: string): Map
  * `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