@hominis/fireforge 0.44.4 → 0.46.0

package/dist/src/core/patch-export-update.d.ts

@@ -13,6 +13,22 @@ export interface UpdatePatchPolicyGate {
     command: string;
     forceUnsafe?: boolean;
 }
+export interface UpdatePatchAndMetadataOptions {
+    /** Patch directory holding the body and `patches.json`. */
+    patchesDir: string;
+    /** Patch file to rewrite. */
+    filename: string;
+    /** New patch body; an identical body skips the write. */
+    newContent: string;
+    /** Manifest-row fields to merge into the patch's metadata. */
+    updates: Partial<PatchMetadata>;
+    /** Hook run under the lock after the mutation succeeds. */
+    onCommitted?: UpdatePatchCommittedHook | undefined;
+    /** Policy gate run against the under-lock projected manifest. */
+    policyGate?: UpdatePatchPolicyGate | undefined;
+    /** Wait budget and command name for the patch directory lock. */
+    lockOptions?: PatchDirectoryLockOptions | undefined;
+}
 /**
  * Updates a patch file body and its manifest row under the same patch
  * directory lock. Intended for commands like `re-export --files` where the
@@ -26,7 +42,8 @@ export interface UpdatePatchPolicyGate {
  * unexpected rewrite in `git status`. Metadata still moves either way — only
  * the redundant byte-for-byte write is elided.
  *
+ * @param options - See {@link UpdatePatchAndMetadataOptions}
  * @returns True when the patch body on disk changed, false when it was
  *   already byte-identical to the new content.
  */
-export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook, policyGate?: UpdatePatchPolicyGate, lockOptions?: PatchDirectoryLockOptions): Promise<boolean>;
+export declare function updatePatchAndMetadata(options: UpdatePatchAndMetadataOptions): Promise<boolean>;

package/dist/src/core/patch-export-update.js

@@ -5,7 +5,6 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { withPatchDirectoryLock } from './patch-apply.js';
-import { normalizePatchArtifact } from './patch-artifact-normalize.js';
 import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from './patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
 /**
@@ -21,10 +20,12 @@ import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
  * unexpected rewrite in `git status`. Metadata still moves either way — only
  * the redundant byte-for-byte write is elided.
  *
+ * @param options - See {@link UpdatePatchAndMetadataOptions}
  * @returns True when the patch body on disk changed, false when it was
  *   already byte-identical to the new content.
  */
-export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted, policyGate, lockOptions = {}) {
+export async function updatePatchAndMetadata(options) {
+    const { patchesDir, filename, newContent, updates, onCommitted, policyGate, lockOptions = {}, } = options;
     return withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifestForWrite(patchesDir);
         if (!manifest) {
@@ -49,7 +50,7 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
                 forceUnsafe: policyGate.forceUnsafe === true,
             });
         }
-        const normalized = normalizePatchArtifact(newContent);
+        const normalized = newContent;
         const bodyChanged = normalized !== originalContent;
         let patchWritten = false;
         try {

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

@@ -2,9 +2,19 @@ import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '.
 import type { FireForgeConfig } from '../types/config.js';
 import { type SupersedeCoverageDetail } from './patch-export-coverage.js';
 import type { PatchDirectoryLockOptions } from './patch-lock.js';
-export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, type SupersedeCoverageDetail, } from './patch-export-coverage.js';
+export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
 export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
 export { updatePatchAndMetadata } from './patch-export-update.js';
+/**
+ * Projects the planning subset out of a wider export input (commit input,
+ * dry-run preview input) — the fields `planExport` /
+ * `computeExportPlanUnderLock` read. Optional fields are copied only when
+ * present so the plan input never carries explicit `undefined` keys, which
+ * would otherwise leak into the written metadata via spread. The commit
+ * path and the dry-run preview both go through this one projection so
+ * they cannot drift field by field.
+ */
+export declare function buildPlanExportInput(input: PlanExportInput): PlanExportInput;
 /**
  * Gets the next patch number for a new patch.
  * @param patchesDir - Path to the patches directory
@@ -91,26 +101,6 @@ export interface CommitExportedPatchResult {
  * to filename allocation or supersede detection lands in both automatically.
  */
 export declare function commitExportedPatch(input: CommitExportedPatchInput): Promise<CommitExportedPatchResult>;
-/**
- * Parses a patch filename to extract order, category, and name.
- * Supports both new format (001-category-name.patch) and legacy (001-name.patch).
- */
-export declare function parseFilename(filename: string): {
-    order: number;
-    category: PatchCategory | null;
-    name: string;
-};
-/**
- * Finds an existing patch that contains the specified file.
- * Returns the most recent (highest order) patch if multiple exist.
- * @param patchesDir - Path to the patches directory
- * @param filePath - File path to search for
- * @returns The patch info and metadata, or null if not found
- */
-export declare function findExistingPatchForFile(patchesDir: string, filePath: string): Promise<{
-    patch: PatchInfo;
-    metadata: PatchMetadata;
-} | null>;
 /**
  * Updates the content of a patch file.
  * @param patchPath - Path to the patch file

package/dist/src/core/patch-export.js

@@ -3,17 +3,39 @@ import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
-import { PATCH_CATEGORIES } from '../utils/validation.js';
 import { discoverPatches, withPatchDirectoryLock } from './patch-apply.js';
-import { normalizePatchArtifact } from './patch-artifact-normalize.js';
 import { findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
-import { addPatchToManifest, findPatchesAffectingFile, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
-import { requirePatchOrder } from './patch-parse.js';
+import { addPatchToManifest, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
+import { formatPatchOrder, requirePatchOrder } from './patch-parse.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
-export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
+export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
 import { escapeRegex } from '../utils/regex.js';
 export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
 export { updatePatchAndMetadata } from './patch-export-update.js';
+/**
+ * Projects the planning subset out of a wider export input (commit input,
+ * dry-run preview input) — the fields `planExport` /
+ * `computeExportPlanUnderLock` read. Optional fields are copied only when
+ * present so the plan input never carries explicit `undefined` keys, which
+ * would otherwise leak into the written metadata via spread. The commit
+ * path and the dry-run preview both go through this one projection so
+ * they cannot drift field by field.
+ */
+export function buildPlanExportInput(input) {
+    return {
+        patchesDir: input.patchesDir,
+        category: input.category,
+        name: input.name,
+        description: input.description,
+        filesAffected: input.filesAffected,
+        sourceEsrVersion: input.sourceEsrVersion,
+        ...(input.sourceProduct !== undefined ? { sourceProduct: input.sourceProduct } : {}),
+        ...(input.sourceVersion !== undefined ? { sourceVersion: input.sourceVersion } : {}),
+        ...(input.tier !== undefined ? { tier: input.tier } : {}),
+        ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
+        ...(input.config !== undefined ? { config: input.config } : {}),
+    };
+}
 /**
  * Gets the next patch number for a new patch.
  * @param patchesDir - Path to the patches directory
@@ -110,19 +132,7 @@ export async function getNextPatchFilename(patchesDir, category, name) {
  */
 export async function commitExportedPatch(input) {
     return withPatchDirectoryLock(input.patchesDir, async () => {
-        const plan = await computeExportPlanUnderLock({
-            patchesDir: input.patchesDir,
-            category: input.category,
-            name: input.name,
-            description: input.description,
-            filesAffected: input.filesAffected,
-            sourceEsrVersion: input.sourceEsrVersion,
-            ...(input.sourceProduct !== undefined ? { sourceProduct: input.sourceProduct } : {}),
-            ...(input.sourceVersion !== undefined ? { sourceVersion: input.sourceVersion } : {}),
-            ...(input.tier !== undefined ? { tier: input.tier } : {}),
-            ...(input.lintIgnore !== undefined ? { lintIgnore: input.lintIgnore } : {}),
-            ...(input.config !== undefined ? { config: input.config } : {}),
-        });
+        const plan = await computeExportPlanUnderLock(buildPlanExportInput(input));
         if (input.config !== undefined) {
             enforcePatchPolicy({
                 config: input.config,
@@ -140,7 +150,20 @@ export async function commitExportedPatch(input) {
             }
         }
         try {
-            await writeText(patchPath, normalizePatchArtifact(input.diff));
+            // Patch bodies are written byte-for-byte as git produced them, including the
+            // single-space rendering of a blank context line.
+            //
+            // Do NOT add a whitespace-trimming pass here or at any other write site.
+            // Stripping marker lines whose payload is pure whitespace (`/^[ +-]\s+$/` →
+            // bare marker) corrupts real content: Firefox sources contain whitespace-only
+            // lines, so a ` `/`-` line whose payload was two spaces no longer matches the
+            // pristine tree and the freshly exported patch fails `git apply --check`,
+            // while a `+` line silently changes what the patch produces. The repository
+            // whitespace check already exempts `patches/*.patch`
+            // (scripts/check-worktree-whitespace.mjs), and the byte-fidelity contract is
+            // pinned end-to-end by `git-diff-latin1-roundtrip.test.ts` and
+            // `re-export.integration.test.ts`.
+            await writeText(patchPath, input.diff);
             await addPatchToManifest(input.patchesDir, plan.metadata, plan.supersededPatches.map((p) => p.filename));
             for (const oldPatch of plan.supersededPatches) {
                 await removeFile(oldPatch.path);
@@ -188,58 +211,13 @@ export async function commitExportedPatch(input) {
         };
     }, input.lockOptions ?? {});
 }
-/**
- * Parses a patch filename to extract order, category, and name.
- * Supports both new format (001-category-name.patch) and legacy (001-name.patch).
- */
-export function parseFilename(filename) {
-    // New format: 001-ui-sidebar.patch
-    const newMatch = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(filename);
-    if (newMatch?.[1] && newMatch[2] && newMatch[3]) {
-        const orderStr = newMatch[1];
-        const category = newMatch[2];
-        const name = newMatch[3];
-        if (PATCH_CATEGORIES.includes(category)) {
-            return {
-                order: parseInt(orderStr, 10),
-                category,
-                name,
-            };
-        }
-    }
-    // Legacy format: 001-name.patch
-    const legacyMatch = /^(\d+)-(.+)\.patch$/.exec(filename);
-    if (legacyMatch?.[1] && legacyMatch[2]) {
-        return {
-            order: parseInt(legacyMatch[1], 10),
-            category: null,
-            name: legacyMatch[2],
-        };
-    }
-    return { order: Infinity, category: null, name: filename };
-}
-/**
- * Finds an existing patch that contains the specified file.
- * Returns the most recent (highest order) patch if multiple exist.
- * @param patchesDir - Path to the patches directory
- * @param filePath - File path to search for
- * @returns The patch info and metadata, or null if not found
- */
-export async function findExistingPatchForFile(patchesDir, filePath) {
-    const affectingPatches = await findPatchesAffectingFile(patchesDir, filePath);
-    if (affectingPatches.length === 0) {
-        return null;
-    }
-    // Return the most recent (highest order) patch
-    return affectingPatches[affectingPatches.length - 1] ?? null;
-}
 /**
  * Updates the content of a patch file.
  * @param patchPath - Path to the patch file
  * @param newContent - New patch content
  */
 export async function updatePatch(patchPath, newContent) {
-    await writeText(patchPath, normalizePatchArtifact(newContent));
+    await writeText(patchPath, newContent);
 }
 /**
  * Internal planning helper. Does NOT take the patch directory lock — the
@@ -259,7 +237,7 @@ async function computeExportPlanUnderLock(input) {
         ? allocatePolicyOrder(input.config, manifestBefore?.patches ?? [], input.category)
         : null;
     const patchFilename = policyOrder !== null
-        ? `${String(policyOrder).padStart(3, '0')}-${input.category}-${patchNameSlug(input.name, input.category)}.patch`
+        ? `${formatPatchOrder(policyOrder)}-${input.category}-${patchNameSlug(input.name, input.category)}.patch`
         : await getNextPatchFilename(input.patchesDir, input.category, input.name);
     const patchPath = join(input.patchesDir, patchFilename);
     const metadata = {

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

@@ -3,10 +3,6 @@ import type { PatchInfo } from '../types/commands/index.js';
 export declare function discoverPatches(patchesDir: string): Promise<PatchInfo[]>;
 /** Counts the patch files currently present in a patch directory. */
 export declare function countPatches(patchesDir: string): Promise<number>;
-/** Checks whether a patch creates a new file rather than modifying an existing one. */
-export declare function isNewFilePatch(patchPath: string): Promise<boolean>;
-/** Returns the first target file path referenced by a patch, if any. */
-export declare function getTargetFileFromPatch(patchPath: string): Promise<string | null>;
 /**
  * Returns all target file paths referenced by a multi-file patch.
  *

package/dist/src/core/patch-files.js

@@ -24,17 +24,6 @@ export async function countPatches(patchesDir) {
     const patches = await discoverPatches(patchesDir);
     return patches.length;
 }
-/** Checks whether a patch creates a new file rather than modifying an existing one. */
-export async function isNewFilePatch(patchPath) {
-    const content = await readText(patchPath);
-    return content.includes('new file mode') && content.includes('--- /dev/null');
-}
-/** Returns the first target file path referenced by a patch, if any. */
-export async function getTargetFileFromPatch(patchPath) {
-    const content = await readText(patchPath);
-    const match = /^\+\+\+ b\/(.+)$/m.exec(content);
-    return match?.[1] ?? null;
-}
 /**
  * Returns all target file paths referenced by a multi-file patch.
  *

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

@@ -21,20 +21,14 @@
  * cross-patch lint graph.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
+import type { PatchQueueBodyEntry, PatchQueueView } from './patch-lint-queue-types.js';
 /**
- * The slice of a queue entry this rule reads. Declared structurally rather
- * than importing `PatchQueueEntry` from `patch-lint-cross.ts`, which imports
- * this module back — the local shape keeps the dependency edge one-way and
- * `dpdm` clean, matching `patch-lint-module-registration.ts`.
+ * Queue view accepted by {@link lintPatchQueueBinaryBodies}. Described
+ * structurally rather than by importing `PatchQueueContext` from
+ * `patch-lint-cross.ts`, which imports this module back — the shared leaf
+ * type keeps the dependency edge one-way and `dpdm` clean.
  */
-interface BinaryBodyQueueEntry {
-    filename: string;
-    diff: string;
-}
-/** Queue view accepted by {@link lintPatchQueueBinaryBodies}. */
-interface BinaryBodyQueueContext {
-    entries: readonly BinaryBodyQueueEntry[];
-}
+type BinaryBodyQueueContext = PatchQueueView<PatchQueueBodyEntry>;
 /** Lint check identifier emitted by {@link lintPatchQueueBinaryBodies}. */
 export declare const BINARY_BODY_CHECK = "binary-body-not-reconstructable";
 /**

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

@@ -58,5 +58,21 @@ export interface CachedPerPatchLint {
  * is compared explicitly rather than trusted to the key.
  */
 export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, lintIgnore?: Iterable<string>): CachedPerPatchLint | undefined;
+export interface SetCachedPerPatchLintIssuesInput {
+    /** Cache file to mutate in place. */
+    cache: PerPatchLintCacheFile;
+    /** Patch the payload belongs to; also the cache entry key. */
+    patchFilename: string;
+    /** Fingerprint the payload is valid for. */
+    key: string;
+    /** Reported issues, stored as copies. */
+    issues: PatchLintIssue[];
+    /** Issues suppressed by `lintIgnore`, stored as copies. */
+    suppressed: PatchLintIssue[];
+    /** Line count the run measured. */
+    lineCount: number;
+    /** Suppression ids in force for the run, normalized on store. */
+    lintIgnore?: Iterable<string> | undefined;
+}
 /** Stores the per-patch lint payload after a successful lint calculation. */
-export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[], suppressed: PatchLintIssue[], lineCount: number, lintIgnore?: Iterable<string>): void;
+export declare function setCachedPerPatchLintIssues(input: SetCachedPerPatchLintIssuesInput): void;

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

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { getPackageVersion } from '../utils/package-root.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { git } from './git-base.js';
@@ -42,10 +42,6 @@ function stableJson(value) {
         .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
         .join(',')}}`;
 }
-/** Computes a SHA-256 hex digest for text or binary content. */
-function sha256Hex(content) {
-    return createHash('sha256').update(content).digest('hex');
-}
 /** Computes a stable SHA-256 digest for JSON-compatible data. */
 function stableHash(value) {
     return sha256Hex(stableJson(value));
@@ -223,7 +219,8 @@ export function getCachedPerPatchLintIssues(cache, patchFilename, key, lintIgnor
     };
 }
 /** Stores the per-patch lint payload after a successful lint calculation. */
-export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues, suppressed, lineCount, lintIgnore) {
+export function setCachedPerPatchLintIssues(input) {
+    const { cache, patchFilename, key, issues, suppressed, lineCount, lintIgnore } = input;
     cache.entries[patchFilename] = {
         key,
         patchFilename,

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

@@ -46,6 +46,37 @@ export interface GroupedCheckJsResult {
     byFile: Map<string, PatchLintIssue[]>;
     global: PatchLintIssue[];
 }
+/** Inputs for {@link runCheckJsGrouped}. */
+export interface RunCheckJsGroupedInput {
+    /** Absolute engine (repository) directory. */
+    repoDir: string;
+    /**
+     * Patch-owned `.sys.mjs` paths (relative to `repoDir`) the program should
+     * see and resolve against.
+     */
+    resolutionOwned: Set<string>;
+    /**
+     * Optional project-relative extra `.d.ts` appended to the built-in
+     * Firefox-globals shim (from `patchLint.checkJsExtraShim`).
+     */
+    extraShimPath?: string;
+    /** Absolute project root for resolving `extraShimPath`. */
+    projectRoot?: string;
+    /** Strictness preset plus allowlisted compiler-option overrides. */
+    mode?: CheckJsMode;
+    /** Optional shim text appended AFTER the consumer shim. */
+    builtinShimSuffix?: string;
+    /**
+     * 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.
+     */
+    rootScope?: ReadonlySet<string>;
+}
 /**
  * Builds the checkJs program **once** over `resolutionOwned` and returns its
  * diagnostics grouped by originating file. Callers slice the result by their
@@ -54,24 +85,10 @@ export interface GroupedCheckJsResult {
  * every file in `resolutionOwned`, so cross-patch `resource:///`/`chrome://`
  * imports resolve to real sources.
  *
- * @param repoDir - Absolute engine (repository) directory
- * @param resolutionOwned - Patch-owned `.sys.mjs` paths (relative to repoDir)
- *   the program should see and resolve against
- * @param extraShimPath - Optional project-relative extra `.d.ts` appended to
- *   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.
+ * @param input - Program inputs; see {@link RunCheckJsGroupedInput}
  * @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, builtinShimSuffix?: string, rootScope?: ReadonlySet<string>): Promise<GroupedCheckJsResult>;
+export declare function runCheckJsGrouped(input: RunCheckJsGroupedInput): Promise<GroupedCheckJsResult>;
 /**
  * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
  * `reportScope` is supplied, only diagnostics from files in that set are

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

@@ -30,6 +30,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
+import { collectUnmanagedCompanions, retargetUnmanagedCompanionHints, } from './patch-lint-unmanaged-companion.js';
 import { composeShimSource, SHIM_FILENAME, SUPPRESSED_DIAGNOSTIC_CODES, TEST_HARNESS_SHIM, UNDEFINED_IDENTIFIER_CODES, UNDEFINED_IDENTIFIER_HINT, } from './typecheck-shim.js';
 // ---------------------------------------------------------------------------
 // Public API
@@ -161,24 +162,11 @@ function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
  * every file in `resolutionOwned`, so cross-patch `resource:///`/`chrome://`
  * imports resolve to real sources.
  *
- * @param repoDir - Absolute engine (repository) directory
- * @param resolutionOwned - Patch-owned `.sys.mjs` paths (relative to repoDir)
- *   the program should see and resolve against
- * @param extraShimPath - Optional project-relative extra `.d.ts` appended to
- *   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.
+ * @param input - Program inputs; see {@link RunCheckJsGroupedInput}
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode, builtinShimSuffix, rootScope) {
+export async function runCheckJsGrouped(input) {
+    const { repoDir, resolutionOwned, extraShimPath, rootScope } = input;
     const empty = { byFile: new Map(), global: [] };
     if (resolutionOwned.size === 0)
         return empty;
@@ -226,12 +214,14 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     // also undefined, so the resolution target is irrelevant.
     let shimSource;
     try {
-        const composed = await composeShimSource(projectRoot ?? repoDir, extraShimPath);
+        const composed = await composeShimSource(input.projectRoot ?? repoDir, extraShimPath);
         // The suffix (e.g. the loose test-harness baseline) 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;
+        shimSource = input.builtinShimSuffix
+            ? `${composed.source}\n${input.builtinShimSuffix}`
+            : composed.source;
         if (composed.extraShimAppended) {
             verbose(`checkJs: extra shim ${extraShimPath ?? ''} appended to Firefox globals shim`);
         }
@@ -251,7 +241,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     }
     const shimPath = toTsPath(resolve(repoDir, SHIM_FILENAME));
     rootFiles.push(shimPath);
-    const strict = mode?.strict === true;
+    const strict = input.mode?.strict === true;
     const strictness = strict
         ? { strict: true, noImplicitAny: true }
         : {
@@ -265,7 +255,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
     // sources without a hand-generated ambient stub shim.
     const overrides = {};
     let pathsMapping;
-    const co = mode?.compilerOptions;
+    const co = input.mode?.compilerOptions;
     if (co) {
         for (const key of Object.keys(co)) {
             const v = co[key];
@@ -350,7 +340,7 @@ export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath,
         },
     };
     const program = ts.createProgram(rootFiles, options, host);
-    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute, mode?.undefinedIdentifiers ?? 'warning');
+    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute, input.mode?.undefinedIdentifiers ?? 'warning');
     verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s) across ${byFile.size} owning file(s)`);
     return { byFile, global: [] };
 }
@@ -416,7 +406,13 @@ function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute, undefinedIdentifi
  * @returns Array of lint issues from TS diagnostics
  */
 export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode, reportScope) {
-    const { byFile, global } = await runCheckJsGrouped(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode);
+    const { byFile, global } = await runCheckJsGrouped({
+        repoDir,
+        resolutionOwned: patchOwnedFiles,
+        ...(extraShimPath !== undefined ? { extraShimPath } : {}),
+        ...(projectRoot !== undefined ? { projectRoot } : {}),
+        ...(mode !== undefined ? { mode } : {}),
+    });
     const issues = [...global];
     for (const [rel, list] of byFile) {
         if (reportScope && !reportScope.has(rel))
@@ -464,6 +460,7 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
     const mode = modeFromPatchLintConfig(patchLint);
     const seenGlobal = new Set();
     const files = [...testFiles].sort((a, b) => a.localeCompare(b));
+    const companions = await collectUnmanagedCompanions(repoDir, files, testFiles);
     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
@@ -480,10 +477,22 @@ export async function runCheckJsTestFilesGrouped(repoDir, testFiles, patchLint,
                 roots.add(candidate);
             }
         }
-        const result = await runCheckJsGrouped(repoDir, roots, patchLint.checkJsTestShim, projectRoot, mode, TEST_HARNESS_SHIM);
+        const result = await runCheckJsGrouped({
+            repoDir,
+            resolutionOwned: roots,
+            ...(patchLint.checkJsTestShim !== undefined
+                ? { extraShimPath: patchLint.checkJsTestShim }
+                : {}),
+            projectRoot,
+            mode,
+            builtinShimSuffix: TEST_HARNESS_SHIM,
+        });
         const own = result.byFile.get(file);
         if (own && own.length > 0) {
-            merged.byFile.set(file, [...(merged.byFile.get(file) ?? []), ...own]);
+            merged.byFile.set(file, [
+                ...(merged.byFile.get(file) ?? []),
+                ...retargetUnmanagedCompanionHints(own, companions),
+            ]);
         }
         for (const globalIssue of result.global) {
             if (seenGlobal.has(globalIssue.message))
@@ -522,7 +531,16 @@ function modeFromPatchLintConfig(patchLint) {
  * (`--patches`); resolution still spans the whole queue
  */
 export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot, rootScope) {
-    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, modeFromPatchLintConfig(patchLint), undefined, rootScope);
+    return runCheckJsGrouped({
+        repoDir,
+        resolutionOwned: patchOwnedFiles,
+        ...(patchLint.checkJsExtraShim !== undefined
+            ? { extraShimPath: patchLint.checkJsExtraShim }
+            : {}),
+        projectRoot,
+        mode: modeFromPatchLintConfig(patchLint),
+        ...(rootScope !== undefined ? { rootScope } : {}),
+    });
 }
 /**
  * Cheap probe reproducing the only run-level ("global") checkJs findings the

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

@@ -10,13 +10,9 @@
  * so a discarded context frees its map; a caller that mutates a context
  * entry in place must call {@link invalidateNewFileCreatorsCache}.
  */
+import type { PatchQueueBodyEntry, PatchQueueView } from './patch-lint-queue-types.js';
 /** The slice of a queue context the creators map is derived from. */
-interface CreatorsContext {
-    entries: {
-        filename: string;
-        diff: string;
-    }[];
-}
+type CreatorsContext = PatchQueueView<PatchQueueBodyEntry>;
 /** Drops the memoised creators map after an in-place context entry update. */
 export declare function invalidateNewFileCreatorsCache(ctx: CreatorsContext): void;
 /**

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

@@ -34,6 +34,17 @@ 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
@@ -109,13 +120,10 @@ export declare function isForwardImportableFile(path: string): boolean;
  * 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[];
 /**