@hominis/fireforge 0.39.0 → 0.41.0

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

@@ -61,9 +61,17 @@ export interface GroupedCheckJsResult {
  *   the built-in Firefox-globals shim (from `patchLint.checkJsExtraShim`)
  * @param projectRoot - Absolute project root for resolving `extraShimPath`
  * @param mode - Strictness preset plus allowlisted compiler-option overrides
+ * @param builtinShimSuffix - Optional shim text appended AFTER the consumer shim
+ * @param rootScope - When set, only these repo-relative files become program
+ *   ROOTS; resolution (and the host allowlist) still spans all of
+ *   `resolutionOwned`, so a subset root's cross-patch imports type-check
+ *   against the real owning sources while unrelated owned files are never
+ *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
+ *   identical whether other owned files are roots or mere resolution
+ *   targets (pinned by the rootScope parity test — FORGE J1c).
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode): Promise<GroupedCheckJsResult>;
+export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, builtinShimSuffix?: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
  * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
  * `reportScope` is supplied, only diagnostics from files in that set are
@@ -93,6 +101,24 @@ export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>
  *   not surface other patches' diagnostics)
  */
 export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
+/**
+ * Runs the checkJs pass over patch-owned test `.js` files (FORGE G5,
+ * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
+ * program — mochitest scripts share top-level scope only with their
+ * directory's `head*.js` helpers, so one multi-script program would emit
+ * false cross-file redeclaration errors — with roots = the test file plus
+ * any same-directory patch-owned `head*.js`, checked against the built-in
+ * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
+ * `checkJsTestShim`. Only the target file's diagnostics are reported per
+ * program (head helpers report from their own program), and run-level
+ * errors are de-duplicated across programs.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param testFiles - Patch-owned test-script paths (repo-relative)
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
+ */
+export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
 /**
  * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
  * checkJs program over `patchOwnedFiles` and returns its findings grouped by
@@ -104,5 +130,19 @@ export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles:
  * @param patchOwnedFiles - Every patch-owned `.sys.mjs` in the queue
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
+ * @param rootScope - Optional subset of files to use as program roots
+ *   (`--patches`); resolution still spans the whole queue (FORGE J1c)
+ */
+export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
+/**
+ * Cheap probe reproducing the only run-level ("global") checkJs findings
+ * the build path can produce — a missing `typescript` package and an
+ * unreadable consumer shim (`checkJsExtraShim`, and `checkJsTestShim`
+ * when `checkJsTestFiles` is on). The built program itself never
+ * contributes globals (see {@link runCheckJsGrouped}), so a warm
+ * all-cache-hit run can satisfy the "warm never reports less than cold"
+ * invariant (FORGE F5) with this probe instead of building the whole
+ * TypeScript program. Issue objects are byte-identical to the build
+ * path's, deduplicated by message like {@link runCheckJsTestFilesGrouped}.
  */
-export declare function invokePatchLintCheckJsGrouped(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<GroupedCheckJsResult>;
+export declare function probeCheckJsGlobalIssues(patchLint: PatchLintConfig, projectRoot: string): Promise<PatchLintIssue[]>;

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

@@ -26,9 +26,10 @@
  * while reporting only the patch under export.
  */
 import { basename, resolve } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
+import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -146,9 +147,17 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
  *   the built-in Firefox-globals shim (from `patchLint.checkJsExtraShim`)
  * @param projectRoot - Absolute project root for resolving `extraShimPath`
  * @param mode - Strictness preset plus allowlisted compiler-option overrides
+ * @param builtinShimSuffix - Optional shim text appended AFTER the consumer shim
+ * @param rootScope - When set, only these repo-relative files become program
+ *   ROOTS; resolution (and the host allowlist) still spans all of
+ *   `resolutionOwned`, so a subset root's cross-patch imports type-check
+ *   against the real owning sources while unrelated owned files are never
+ *   parsed. `.mjs` files are module-scoped, so a root's diagnostics are
+ *   identical whether other owned files are roots or mere resolution
+ *   targets (pinned by the rootScope parity test — FORGE J1c).
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode) {
+export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode, builtinShimSuffix, rootScope) {
     const empty = { byFile: new Map(), global: [] };
     if (resolutionOwned.size === 0)
         return empty;
@@ -171,14 +180,18 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
             ],
         };
     }
-    // Resolve absolute paths for root files, filtering to files that exist
+    // Resolve absolute paths for root files, filtering to files that exist.
+    // Under a rootScope, non-scoped owned files stay resolvable (host
+    // allowlist + relByAbsolute) but are not program roots — they are only
+    // parsed if a scoped root's import closure reaches them.
     const rootFiles = [];
     const ownedAbsolute = new Set();
     const relByAbsolute = new Map();
     for (const rel of resolutionOwned) {
         const abs = resolve(repoDir, rel);
         if (await pathExists(abs)) {
-            rootFiles.push(abs);
+            if (rootScope === undefined || rootScope.has(rel))
+                rootFiles.push(abs);
             ownedAbsolute.add(abs);
             relByAbsolute.set(abs, rel);
         }
@@ -193,7 +206,11 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     let shimSource;
     try {
         const composed = await composeShimSource(projectRoot ?? repoDir, extraShimPath);
-        shimSource = composed.source;
+        // The suffix (e.g. the loose test-harness baseline, FORGE G5) goes
+        // AFTER the consumer's extra shim: TypeScript resolves conflicting
+        // `declare var` redeclarations to the FIRST declaration, so a typed
+        // consumer declaration must precede the loose fallback to win.
+        shimSource = builtinShimSuffix ? `${composed.source}\n${builtinShimSuffix}` : composed.source;
         if (composed.extraShimAppended) {
             verbose(`checkJs: extra shim ${extraShimPath ?? ''} appended to Firefox globals shim`);
         }
@@ -205,7 +222,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
                 {
                     file: extraShimPath ?? '(checkJs)',
                     check: 'checkjs-type-error',
-                    message: err instanceof Error ? err.message : String(err),
+                    message: toError(err).message,
                     severity: 'error',
                 },
             ],
@@ -402,6 +419,60 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
 export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint, projectRoot, reportScope) {
     return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), reportScope);
 }
+/**
+ * Runs the checkJs pass over patch-owned test `.js` files (FORGE G5,
+ * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
+ * program — mochitest scripts share top-level scope only with their
+ * directory's `head*.js` helpers, so one multi-script program would emit
+ * false cross-file redeclaration errors — with roots = the test file plus
+ * any same-directory patch-owned `head*.js`, checked against the built-in
+ * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
+ * `checkJsTestShim`. Only the target file's diagnostics are reported per
+ * program (head helpers report from their own program), and run-level
+ * errors are de-duplicated across programs.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param testFiles - Patch-owned test-script paths (repo-relative)
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
+ */
+export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint, projectRoot, rootScope) {
+    const merged = { byFile: new Map(), global: [] };
+    if (testFiles.size === 0)
+        return merged;
+    const mode = modeFromPatchLintConfig(patchLint);
+    const seenGlobal = new Set();
+    const files = [...testFiles].sort((a, b) => a.localeCompare(b));
+    for (const file of files) {
+        // Under a rootScope only the scoped files get their own program, but
+        // head.js helper discovery still spans the full owned set so a scoped
+        // test keeps its cross-patch harness globals (FORGE J1c).
+        if (rootScope !== undefined && !rootScope.has(file))
+            continue;
+        const dir = file.slice(0, file.lastIndexOf('/') + 1);
+        const roots = new Set([file]);
+        for (const candidate of files) {
+            if (candidate === file)
+                continue;
+            const base = candidate.split('/').pop() ?? '';
+            if (candidate.startsWith(dir) && /^head(?:_.*)?\.js$/.test(base)) {
+                roots.add(candidate);
+            }
+        }
+        const result = await runCheckJsGrouped(repoDir, roots, patchLint.checkJsTestShim, projectRoot, mode, TEST_HARNESS_SHIM);
+        const own = result.byFile.get(file);
+        if (own && own.length > 0) {
+            merged.byFile.set(file, [...(merged.byFile.get(file) ?? []), ...own]);
+        }
+        for (const globalIssue of result.global) {
+            if (seenGlobal.has(globalIssue.message))
+                continue;
+            seenGlobal.add(globalIssue.message);
+            merged.global.push(globalIssue);
+        }
+    }
+    return merged;
+}
 /** Derives the {@link CheckJsMode} from a `patchLint` config block. */
 function modeFromPatchLintConfig(patchLint) {
     const strict = patchLint.checkJsStrict === true;
@@ -426,7 +497,60 @@ function modeFromPatchLintConfig(patchLint) {
  * @param patchOwnedFiles - Every patch-owned `.sys.mjs` in the queue
  * @param patchLint - The resolved `patchLint` config block
  * @param projectRoot - FireForge project root for shim resolution
+ * @param rootScope - Optional subset of files to use as program roots
+ *   (`--patches`); resolution still spans the whole queue (FORGE J1c)
+ */
+export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot, rootScope) {
+    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), undefined, rootScope);
+}
+/**
+ * Cheap probe reproducing the only run-level ("global") checkJs findings
+ * the build path can produce — a missing `typescript` package and an
+ * unreadable consumer shim (`checkJsExtraShim`, and `checkJsTestShim`
+ * when `checkJsTestFiles` is on). The built program itself never
+ * contributes globals (see {@link runCheckJsGrouped}), so a warm
+ * all-cache-hit run can satisfy the "warm never reports less than cold"
+ * invariant (FORGE F5) with this probe instead of building the whole
+ * TypeScript program. Issue objects are byte-identical to the build
+ * path's, deduplicated by message like {@link runCheckJsTestFilesGrouped}.
  */
-export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot) {
-    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint));
+export async function probeCheckJsGlobalIssues(patchLint, projectRoot) {
+    try {
+        await import('typescript');
+    }
+    catch {
+        return [
+            {
+                file: '(checkJs)',
+                check: 'checkjs-type-error',
+                message: 'patchLint.checkJs is enabled but the "typescript" package is not installed. ' +
+                    'Run "npm install typescript" to enable type checking.',
+                severity: 'error',
+            },
+        ];
+    }
+    const issues = [];
+    const seen = new Set();
+    const probeShim = async (shimPath) => {
+        try {
+            await composeShimSource(projectRoot, shimPath);
+        }
+        catch (err) {
+            const message = toError(err).message;
+            if (seen.has(message))
+                return;
+            seen.add(message);
+            issues.push({
+                file: shimPath ?? '(checkJs)',
+                check: 'checkjs-type-error',
+                message,
+                severity: 'error',
+            });
+        }
+    };
+    await probeShim(patchLint.checkJsExtraShim);
+    if (patchLint.checkJsTestFiles === true) {
+        await probeShim(patchLint.checkJsTestShim);
+    }
+    return issues;
 }

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

@@ -40,6 +40,15 @@ export function validateChromeScriptJsDoc(source, options) {
         ast = parseScript(source, comments);
     }
     catch {
+        // Deliberate carve-out, unlike the `.sys.mjs` walker in
+        // `patch-lint-jsdoc.ts` (which reports a parse failure as an issue).
+        // `parseScript` rejects `import`/`export`, so a chrome subscript that was
+        // misclassified as a `.js` file — or that mistakenly uses module syntax —
+        // would emit a pseudo-issue for every rule here. The orchestrator already
+        // runs the export walker on `.sys.mjs` separately, so silently declining
+        // to lint an unparseable script is the correct degradation for this file
+        // and only this file. Pinned by "returns no issues when the source uses
+        // module-only syntax" in patch-lint-chrome-jsdoc.test.ts.
         return [];
     }
     const issues = [];

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

@@ -0,0 +1,30 @@
+/**
+ * New-file creators map for the patch queue, split out of
+ * `patch-lint-cross.ts` (at the per-file line budget). Re-exported from
+ * there so callers keep importing from `patch-lint.ts` unchanged.
+ *
+ * Memoised per context object (FORGE J1): ownership resolution and
+ * cache-key fingerprints call this 2-3× per linted patch, and each call
+ * used to re-run `detectNewFilesInDiff` over EVERY queue entry's diff.
+ * Keyed weakly so a discarded context frees its map; a caller that
+ * mutates a context entry in place must call
+ * {@link invalidateNewFileCreatorsCache}.
+ */
+/** The slice of a queue context the creators map is derived from. */
+interface CreatorsContext {
+    entries: {
+        filename: string;
+        diff: string;
+    }[];
+}
+/** Drops the memoised creators map after an in-place context entry update. */
+export declare function invalidateNewFileCreatorsCache(ctx: CreatorsContext): void;
+/**
+ * Returns the raw `path → patches[]` map of files created in `new file
+ * mode` by at least one patch in the queue. Paths created by only one
+ * patch are also included so callers can distinguish "no creator" from
+ * "exactly one creator" without re-scanning the diffs. The returned map
+ * is memoised and shared — treat it as read-only.
+ */
+export declare function collectNewFileCreatorsByPath(ctx: CreatorsContext): Map<string, string[]>;
+export {};

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

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * New-file creators map for the patch queue, split out of
+ * `patch-lint-cross.ts` (at the per-file line budget). Re-exported from
+ * there so callers keep importing from `patch-lint.ts` unchanged.
+ *
+ * Memoised per context object (FORGE J1): ownership resolution and
+ * cache-key fingerprints call this 2-3× per linted patch, and each call
+ * used to re-run `detectNewFilesInDiff` over EVERY queue entry's diff.
+ * Keyed weakly so a discarded context frees its map; a caller that
+ * mutates a context entry in place must call
+ * {@link invalidateNewFileCreatorsCache}.
+ */
+import { detectNewFilesInDiff } from './patch-lint-diff.js';
+const newFileCreatorsMemo = new WeakMap();
+/** Drops the memoised creators map after an in-place context entry update. */
+export function invalidateNewFileCreatorsCache(ctx) {
+    newFileCreatorsMemo.delete(ctx);
+}
+/**
+ * Returns the raw `path → patches[]` map of files created in `new file
+ * mode` by at least one patch in the queue. Paths created by only one
+ * patch are also included so callers can distinguish "no creator" from
+ * "exactly one creator" without re-scanning the diffs. The returned map
+ * is memoised and shared — treat it as read-only.
+ */
+export function collectNewFileCreatorsByPath(ctx) {
+    const memoised = newFileCreatorsMemo.get(ctx);
+    if (memoised)
+        return memoised;
+    const creators = new Map();
+    for (const entry of ctx.entries) {
+        const newFiles = detectNewFilesInDiff(entry.diff);
+        for (const file of newFiles) {
+            let owners = creators.get(file);
+            if (!owners) {
+                owners = [];
+                creators.set(file, owners);
+            }
+            owners.push(entry.filename);
+        }
+    }
+    newFileCreatorsMemo.set(ctx, creators);
+    return creators;
+}

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

@@ -79,23 +79,7 @@ export interface PatchQueueContext {
  * @param patchesDir - Path to the patches directory
  */
 export declare function buildPatchQueueContext(patchesDir: string, config?: FireForgeConfig): Promise<PatchQueueContext>;
-/**
- * Returns the raw `path → patches[]` map of files created in `new file
- * mode` by at least one patch in the queue. Paths created by only one
- * patch are also included so callers can distinguish "no creator" from
- * "exactly one creator" without re-scanning the diffs.
- *
- * Split out from {@link lintPatchQueueDuplicateCreations} so
- * `status --ownership` (and any future caller that wants ownership
- * without a rendered PatchLintIssue) can consume the same structured
- * data the rule itself relies on. Previously status had to parse the
- * rule's human-readable message to recover the patch list, which was
- * both fragile and made the lint message format part of an implicit
- * contract.
- *
- * @param ctx - Pre-built queue context
- */
-export declare function collectNewFileCreatorsByPath(ctx: PatchQueueContext): Map<string, string[]>;
+export { collectNewFileCreatorsByPath, invalidateNewFileCreatorsCache, } from './patch-lint-creators.js';
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that

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

@@ -16,7 +16,9 @@ import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { stripJsComments } from '../utils/regex.js';
 import { discoverPatches } from './patch-files.js';
+import { collectNewFileCreatorsByPath } from './patch-lint-creators.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
+import { lintPatchQueueModuleRegistrations } from './patch-lint-module-registration.js';
 import { loadPatchesManifest } from './patch-manifest-io.js';
 import { categoryRangeForOrder, categoryRangeLabel } from './patch-policy.js';
 import { extractNewFileContent } from './patch-transform.js';
@@ -81,37 +83,11 @@ export async function buildPatchQueueContext(patchesDir, config) {
     entries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
     return { entries, ...(config?.patchPolicy ? { patchPolicy: config.patchPolicy } : {}) };
 }
-/**
- * Returns the raw `path → patches[]` map of files created in `new file
- * mode` by at least one patch in the queue. Paths created by only one
- * patch are also included so callers can distinguish "no creator" from
- * "exactly one creator" without re-scanning the diffs.
- *
- * Split out from {@link lintPatchQueueDuplicateCreations} so
- * `status --ownership` (and any future caller that wants ownership
- * without a rendered PatchLintIssue) can consume the same structured
- * data the rule itself relies on. Previously status had to parse the
- * rule's human-readable message to recover the patch list, which was
- * both fragile and made the lint message format part of an implicit
- * contract.
- *
- * @param ctx - Pre-built queue context
- */
-export function collectNewFileCreatorsByPath(ctx) {
-    const creators = new Map();
-    for (const entry of ctx.entries) {
-        const newFiles = detectNewFilesInDiff(entry.diff);
-        for (const file of newFiles) {
-            let owners = creators.get(file);
-            if (!owners) {
-                owners = [];
-                creators.set(file, owners);
-            }
-            owners.push(entry.filename);
-        }
-    }
-    return creators;
-}
+// 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 (FORGE J1);
+// re-exported here so callers keep importing from `patch-lint.ts`.
+export { collectNewFileCreatorsByPath, invalidateNewFileCreatorsCache, } from './patch-lint-creators.js';
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
@@ -131,6 +107,7 @@ export function lintPatchQueueDuplicateCreations(ctx) {
             issues.push({
                 file,
                 check: 'duplicate-new-file-creation',
+                patches: [...owners].sort((a, b) => a.localeCompare(b)),
                 fingerprint: `duplicate-new-file-creation|${file}|${[...owners].sort((a, b) => a.localeCompare(b)).join(',')}`,
                 message: `File "${file}" is created (new file mode) by multiple patches: ${owners.join(', ')}. ` +
                     'Only one patch may create a given path. Use "patch delete" or ' +
@@ -519,6 +496,7 @@ export function lintPatchQueueForwardImports(ctx) {
         issues.push({
             file: sitePath,
             check: 'forward-import',
+            patches: [entry.filename],
             fingerprint: `forward-import|${sitePath}|${cleaned}|${fingerprintOwners}`,
             message: `${sitePath} in ${entry.filename} imports "${specifier}", ` +
                 `but the matching new file is created by a later patch: ${ownersSummary}. ` +
@@ -537,6 +515,7 @@ export function lintPatchQueueForwardImports(ctx) {
             issues.push({
                 file: dependency.file,
                 check: 'staged-dependency-unused',
+                patches: [entry.filename],
                 fingerprint: `staged-dependency-unused|${entry.filename}|${dependency.file}|${dependency.specifier}|${dependency.creates}|${dependency.owner ?? ''}`,
                 message: `${entry.filename} declares a staged forward import from ${dependency.file} ` +
                     `to "${dependency.specifier}" / ${dependency.creates}, but that exact forward dependency was not found. ` +
@@ -559,6 +538,7 @@ export function lintPatchQueueForwardImports(ctx) {
             issues.push({
                 file: registration.file,
                 check: 'staged-dependency-unused',
+                patches: [entry.filename],
                 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)} ` +
@@ -631,5 +611,9 @@ function isRegistrationLinePresent(entry, registration) {
  *   manually for projected/hypothetical states)
  */
 export function lintPatchQueue(ctx) {
-    return [...lintPatchQueueDuplicateCreations(ctx), ...lintPatchQueueForwardImports(ctx)];
+    return [
+        ...lintPatchQueueDuplicateCreations(ctx),
+        ...lintPatchQueueForwardImports(ctx),
+        ...lintPatchQueueModuleRegistrations(ctx),
+    ];
 }

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

@@ -15,7 +15,7 @@ import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { hasRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
-import { extractAddedLinesPerFile } from './patch-lint-diff.js';
+import { extractAddedLineNumbersPerFile, extractAddedLinesPerFile } from './patch-lint-diff.js';
 /**
  * Loads the furnace token-prefix lint inputs gracefully — returns
  * undefined (skipping the token-prefix check) when furnace.json cannot
@@ -38,11 +38,48 @@ async function loadCssTokenContext(repoDir) {
     }
     return undefined;
 }
+/**
+ * Masks CSS block comments with spaces, preserving newlines so line
+ * numbers stay stable. An unclosed trailing `/*` is masked to EOF —
+ * matching how a CSS parser treats it (FORGE G4).
+ */
+function maskCssComments(source) {
+    const masked = source.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+    const openerIndex = masked.indexOf('/*');
+    if (openerIndex === -1)
+        return masked;
+    return (masked.slice(0, openerIndex) +
+        masked
+            .slice(openerIndex)
+            .split('\n')
+            .map((line) => ' '.repeat(line.length))
+            .join('\n'));
+}
+const RAW_COLOR_IGNORE_MARKER = 'fireforge-ignore: raw-color-value';
+/**
+ * Builds the scan source for the diff branch with full-file comment
+ * awareness: comments are masked across the whole post-patch file so a
+ * 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
+ * joined-added-lines scan rather than misattributing lines.
+ */
+function buildAddedLinesScanSource(rawCss, addedNumbers) {
+    const rawLines = rawCss.split('\n');
+    if (!addedNumbers.every((n) => n >= 1 && n <= rawLines.length))
+        return undefined;
+    const maskedLines = maskCssComments(rawCss).split('\n');
+    return addedNumbers
+        .filter((n) => !(rawLines[n - 1] ?? '').includes(RAW_COLOR_IGNORE_MARKER))
+        .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, config, issues) {
+function checkRawColorValues(file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues) {
     // 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
@@ -55,25 +92,33 @@ function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
     const allowlist = config?.patchLint?.rawColorAllowlist;
     const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
     const isBranding = file.startsWith('browser/branding/');
-    if (!isAllowlisted && !isBranding) {
-        // Strip lines with inline fireforge-ignore: raw-color-value suppression.
-        // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
+    if (isAllowlisted || isBranding)
+        return;
+    let suppressedContent;
+    const addedNumbers = addedLineNumbersByFile?.get(file);
+    if (addedNumbers !== undefined) {
+        suppressedContent = buildAddedLinesScanSource(rawCss, addedNumbers);
+    }
+    if (suppressedContent === undefined) {
+        // Legacy scan: full file (no diff), or the joined added lines when
+        // the diff and on-disk file disagree. Waiver lines are filtered
+        // against the pre-strip text so the CSS comment marker is present.
         const sourceForSuppression = addedLinesByFile
             ? (addedLinesByFile.get(file) ?? []).join('\n')
             : rawCss;
-        const suppressedContent = sourceForSuppression
+        suppressedContent = sourceForSuppression
             .split('\n')
-            .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
+            .filter((line) => !line.includes(RAW_COLOR_IGNORE_MARKER))
             .join('\n')
             .replace(/\/\*[\s\S]*?\*\//g, '');
-        if (hasRawCssColors(suppressedContent)) {
-            issues.push({
-                file,
-                check: 'raw-color-value',
-                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
-                severity: 'error',
-            });
-        }
+    }
+    if (hasRawCssColors(suppressedContent)) {
+        issues.push({
+            file,
+            check: 'raw-color-value',
+            message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
+            severity: 'error',
+        });
     }
 }
 /**
@@ -157,6 +202,9 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     const tokenContext = await loadCssTokenContext(repoDir);
     const issues = [];
     const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
+    const addedLineNumbersByFile = diffContent
+        ? extractAddedLineNumbersPerFile(diffContent)
+        : undefined;
     for (const file of cssFiles) {
         const filePath = join(repoDir, file);
         if (!(await pathExists(filePath)))
@@ -164,7 +212,7 @@ 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, config, issues);
+        checkRawColorValues(file, rawCss, addedLinesByFile, addedLineNumbersByFile, config, issues);
         checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
     }
     return issues;

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

@@ -18,6 +18,14 @@ export declare function detectNewFilesInDiff(diffContent: string): Set<string>;
  * Returns a map of file path → array of added line contents (without the leading `+`).
  */
 export declare function extractAddedLinesPerFile(diffContent: string): Map<string, string[]>;
+/**
+ * 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 (FORGE G4) — map the patch's additions onto the applied file.
+ */
+export declare function extractAddedLineNumbersPerFile(diffContent: string): Map<string, number[]>;
 /**
  * Builds the `modifiedFileAdditions` map the cross-patch lint expects for
  * a given unified diff. Exposed so callers that construct synthetic /

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

@@ -45,6 +45,37 @@ export function extractAddedLinesPerFile(diffContent) {
     }
     return result;
 }
+/**
+ * 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 (FORGE G4) — map the patch's additions onto the applied file.
+ */
+export function extractAddedLineNumbersPerFile(diffContent) {
+    const result = new Map();
+    for (const section of parseDiffSections(diffContent)) {
+        for (const hunk of section.hunks) {
+            let newLine = hunk.newStart;
+            for (const line of hunk.lines) {
+                if (line.startsWith('\\'))
+                    continue; // ""
+                if (line.startsWith('-'))
+                    continue;
+                if (line.startsWith('+')) {
+                    let arr = result.get(section.targetPath);
+                    if (!arr) {
+                        arr = [];
+                        result.set(section.targetPath, arr);
+                    }
+                    arr.push(newLine);
+                }
+                newLine++;
+            }
+        }
+    }
+    return result;
+}
 /**
  * Builds the `modifiedFileAdditions` map the cross-patch lint expects for
  * a given unified diff. Exposed so callers that construct synthetic /