@hominis/fireforge 0.45.0 → 0.46.1

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
@@ -23,7 +33,7 @@ export declare function getNextPatchNumber(patchesDir: string): Promise<string>;
 export declare function sanitizeName(name: string): string;
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
- * Operators frequently pass the DESIRED FILENAME stem to `--name`
+ * Operators frequently pass the desired filename stem to `--name`
  * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
  * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
  * and category themselves, so a matching prefix in the name is always
@@ -35,7 +45,7 @@ export declare function stripRedundantCategoryPrefix(sanitizedName: string, cate
  * Sanitizes a patch name and drops redundant category/full-stem prefixes.
  *
  * A single trailing `.patch` extension is stripped before sanitisation:
- * operators frequently pass a full patch FILENAME where a name is expected
+ * operators frequently pass a full patch filename where a name is expected
  * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
  * and slugging the extension produces double-suffixed `...-patch.patch`
  * files. A name that deliberately ends in a literal `-patch` slug segment
@@ -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
@@ -125,7 +115,7 @@ export declare function updatePatch(patchPath: string, newContent: string): Prom
  * Dry-run and the real write both go through {@link computeExportPlanUnderLock}
  * so their filename allocation, supersede detection, and projected
  * post-write manifest cannot drift. `planExport` exposes the rich coverage
- * form for preview rendering; {@link commitExportedPatch} consumes the bare
+ * form for preview rendering. {@link commitExportedPatch} consumes the bare
  * `PatchInfo[]` form of the same underlying data.
  */
 export interface ExportPlan {
@@ -155,13 +145,13 @@ export interface PlanExportInput {
     /**
      * Optional `PatchMetadata.tier` opt-in carried from the CLI flag.
      * Only `"branding"` is currently recognised. When provided the field
-     * is written into the new patch's metadata; when absent the field
+     * is written into the new patch's metadata. When absent the field
      * stays unset and tier resolution falls back to auto-detection.
      */
     tier?: 'branding';
     /**
      * Optional `PatchMetadata.lintIgnore` carried from the CLI flag.
-     * Empty arrays are treated as "field absent" — the validator only
+     * Empty arrays are treated as "field absent": the validator only
      * preserves the field when it has at least one entry.
      */
     lintIgnore?: string[];
@@ -169,16 +159,16 @@ export interface PlanExportInput {
     config?: FireForgeConfig;
 }
 /**
- * Read-only planning function — computes everything a real export would
+ * Read-only planning function. Computes everything a real export would
  * do without writing anything to disk. Takes the patch directory lock
  * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
  * and returns the plan for preview rendering.
  *
  * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
  * so the dry-run preview cannot drift from the real write. The real write
- * path does NOT reuse a prior plan object (another export may have landed
- * between dry-run and commit, which would stale the filename allocation);
- * it re-runs the same helper under a fresh lock. The guarantee is "same
+ * path does not reuse a prior plan object (another export may have landed
+ * between dry-run and commit, which would stale the filename allocation).
+ * It re-runs the same helper under a fresh lock. The guarantee is "same
  * code, possibly different data," not "same plan object."
  */
 export declare function planExport(input: PlanExportInput): Promise<ExportPlan>;

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
@@ -49,7 +71,7 @@ export function sanitizeName(name) {
 }
 /**
  * Strips a leading `NNN-<category>-` prefix from a sanitized name slug.
- * Operators frequently pass the DESIRED FILENAME stem to `--name`
+ * Operators frequently pass the desired filename stem to `--name`
  * (`--name 203-ui-foo --category ui`), which would otherwise double-prefix
  * into `203-ui-203-ui-foo.patch`. The filename builders prepend the order
  * and category themselves, so a matching prefix in the name is always
@@ -78,7 +100,7 @@ export function stripRedundantCategoryPrefix(sanitizedName, category) {
  * Sanitizes a patch name and drops redundant category/full-stem prefixes.
  *
  * A single trailing `.patch` extension is stripped before sanitisation:
- * operators frequently pass a full patch FILENAME where a name is expected
+ * operators frequently pass a full patch filename where a name is expected
  * (`move-files <from> 348-ui-foo.patch --create`, `rename --to foo.patch`),
  * and slugging the extension produces double-suffixed `...-patch.patch`
  * files. A name that deliberately ends in a literal `-patch` slug segment
@@ -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,70 +211,25 @@ 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
- * caller must already hold it — because the two public entry points
+ * Internal planning helper. It does not take the patch directory lock (the
+ * caller must already hold it), because the two public entry points
  * ({@link planExport} and {@link commitExportedPatch}) each take their own
  * lock for the full operation. Sharing this single pure computation is how
- * dry-run previews and real writes stay in lockstep by construction
- * instead of by parallel implementations that can drift.
+ * dry-run previews and real writes stay in lockstep, instead of relying on
+ * parallel implementations that can drift.
  */
 async function computeExportPlanUnderLock(input) {
     // ForWrite: a corrupt manifest read as null here would produce a
-    // manifestAfter containing ONLY the new patch — committing that plan
+    // manifestAfter containing only the new patch. Committing that plan
     // wipes the queue metadata, and the rollback path would then delete
     // patches.json entirely because manifestBefore looked absent.
     const manifestBefore = await loadPatchesManifestForWrite(input.patchesDir);
@@ -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 = {
@@ -302,16 +280,16 @@ async function computeExportPlanUnderLock(input) {
     };
 }
 /**
- * Read-only planning function — computes everything a real export would
+ * Read-only planning function. Computes everything a real export would
  * do without writing anything to disk. Takes the patch directory lock
  * briefly, runs {@link computeExportPlanUnderLock}, releases the lock,
  * and returns the plan for preview rendering.
  *
  * Shares {@link computeExportPlanUnderLock} with {@link commitExportedPatch}
  * so the dry-run preview cannot drift from the real write. The real write
- * path does NOT reuse a prior plan object (another export may have landed
- * between dry-run and commit, which would stale the filename allocation);
- * it re-runs the same helper under a fresh lock. The guarantee is "same
+ * path does not reuse a prior plan object (another export may have landed
+ * between dry-run and commit, which would stale the filename allocation).
+ * It re-runs the same helper under a fresh lock. The guarantee is "same
  * code, possibly different data," not "same plan object."
  */
 export async function planExport(input) {

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-identifier-suggest.d.ts

@@ -15,6 +15,6 @@ import type { PatchMetadata } from '../types/commands/index.js';
  * Formats the user-facing "patch not found" error message used by
  * `patch delete`, `patch reorder`, `patch tier`, and
  * `patch lint-ignore`. Returns a single string suitable for the
- * `InvalidArgumentError` body — never the full queue enumeration.
+ * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export declare function formatPatchNotFoundError(identifier: string, patches: readonly PatchMetadata[]): string;

package/dist/src/core/patch-identifier-suggest.js

@@ -22,7 +22,7 @@ const MIN_PREFIX_MATCH_LENGTH = 4;
 const SUGGESTION_LIMIT = 3;
 /**
  * Computes the Levenshtein edit distance between two strings. Used by
- * `formatPatchNotFoundError` to rank candidate identifiers; the small
+ * `formatPatchNotFoundError` to rank candidate identifiers. The small
  * upper bound on input lengths (filenames, ordinals, names) makes the
  * O(m*n) implementation trivially fast.
  */
@@ -87,13 +87,13 @@ function rankSuggestions(identifier, candidates) {
     return candidates
         .map((candidate) => {
         const lower = candidate.toLowerCase();
-        // Prefix relation in EITHER direction is a stronger signal than edit
+        // Prefix relation in either direction is a stronger signal than edit
         // distance and is not bounded by it: a partial ordinal or an
         // abbreviated slug ("ui-foo" for "002-ui-foo.patch") is many edits away
         // from the full identifier yet is obviously the intended target.
         // `lower.startsWith(needle)`: the operator typed an abbreviation of a
         // real identifier. The reverse relation is only meaningful when the
-        // candidate is substantial — otherwise the single-character ordinal
+        // candidate is substantial. Otherwise the single-character ordinal
         // "9" would "match" every input starting with a 9.
         const prefixMatch = needle.length >= MIN_PREFIX_MATCH_LENGTH &&
             (lower.startsWith(needle) ||
@@ -115,7 +115,7 @@ function rankSuggestions(identifier, candidates) {
  * Formats the user-facing "patch not found" error message used by
  * `patch delete`, `patch reorder`, `patch tier`, and
  * `patch lint-ignore`. Returns a single string suitable for the
- * `InvalidArgumentError` body — never the full queue enumeration.
+ * `InvalidArgumentError` body, never the full queue enumeration.
  */
 export function formatPatchNotFoundError(identifier, patches) {
     const accepted = collectAcceptedIdentifiers(patches);

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

@@ -2,39 +2,33 @@
  * Queue-wide lint for binary patch bodies that cannot recreate their file.
  *
  * `git diff` has two ways to render a binary change. `git diff --binary`
- * emits a `GIT binary patch` section carrying the literal/delta payload —
- * that body can be replayed by `git apply`. Plain `git diff` emits only the
- * informational `Binary files a/x and b/x differ`, which records THAT the
- * bytes changed and carries none of them.
+ * emits a `GIT binary patch` section carrying the literal/delta payload,
+ * and that body can be replayed by `git apply`. Plain `git diff` emits only
+ * the informational `Binary files a/x and b/x differ`, which records that
+ * the bytes changed and carries none of them.
  *
  * The stub form is dangerous rather than merely lossy because it still
  * carries a correct `index <old>..<new>` line. Every identity-shaped check in
- * the codebase — worktree classification, foreign-drift detection — keys on
+ * the codebase (worktree classification, foreign-drift detection) keys on
  * that hash, matches it against the live file, and concludes the patch is
  * backed. So a queue can hold a patch that provably cannot rebuild its own
  * file while every gate reports green, and the loss surfaces only at the next
  * clean-room apply. This rule is the one check that reads the body itself and
  * fails closed, whichever command wrote it.
  *
- * Body-only by design: it needs no engine checkout, so it runs anywhere the
+ * Body-only: it needs no engine checkout, so it runs anywhere the
  * queue context is available and never pulls an engine dependency into the
  * 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

@@ -53,10 +53,26 @@ export interface CachedPerPatchLint {
 }
 /**
  * Returns the cached lint payload for a patch when the stored key still
- * matches AND the entry was computed under the same lint-ignore waiver set.
+ * matches and the entry was computed under the same lint-ignore waiver set.
  * A waiver change makes a replayed verdict actively wrong, so the waiver set
  * 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, and 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,25 +1,25 @@
 // 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';
 import { collectNewFileCreatorsByPath } from './patch-lint.js';
 // Schema 2: entries additionally carry the lintIgnore-suppressed issues and
 // the measured non-binary line count, so a warm run can report waived size
-// measurements identically to a cold one — a cache hit must never surface
-// LESS than a fresh lint.
+// measurements identically to a cold one. A cache hit must never surface
+// less than a fresh lint.
 // Schema 3: the key additionally content-hashes the
 // `patchLint.checkJsTestShim` file exactly as `checkJsExtraShim`'s already
-// was; without it, editing the test shim in place replays every cached
+// was. Without it, editing the test shim in place replays every cached
 // verdict.
-// Schema 4: each entry RECORDS the lint-ignore waiver set that produced it,
+// Schema 4: each entry records the lint-ignore waiver set that produced it,
 // and a lookup whose effective waiver set differs is refused even when the
 // key matches. The key already hashes `patch.lintIgnore`, so this is
 // belt-and-braces on purpose: a waiver change is the one mutation that makes
-// a replayed verdict actively WRONG (an operator writes a waiver, re-runs,
+// a replayed verdict actively wrong (an operator writes a waiver, re-runs,
 // and is shown the finding they just waived), and the class must not depend
 // on every future key input staying complete. Bumping the schema also
 // discards every pre-4 entry, which is itself the cure for a cache that
@@ -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));
@@ -100,7 +96,7 @@ function buildOwnershipFingerprint(files, ctx) {
 export async function buildPerPatchLintCacheKey(input) {
     // Hash in parallel, then insert in sorted order. The sort is load-bearing:
     // `stableHash` below serialises this record, so insertion order is part of
-    // the cache key — assigning as results land would make the key
+    // the cache key, and assigning as results land would make the key
     // nondeterministic.
     const sortedFiles = [...input.existingFiles].sort((a, b) => a.localeCompare(b));
     const hashes = await Promise.all(sortedFiles.map((file) => fileHash(join(input.engineDir, file))));
@@ -114,8 +110,8 @@ export async function buildPerPatchLintCacheKey(input) {
     const shimHashOf = async (shimPath) => shimPath === undefined
         ? null
         : { path: shimPath, hash: await fileHash(resolve(input.projectRoot, shimPath)) };
-    // Both shims feed compiled checkJs programs, so both are content-hashed —
-    // the config block alone only carries their PATHS, and an in-place edit
+    // Both shims feed compiled checkJs programs, so both are content-hashed.
+    // The config block alone only carries their paths, and an in-place edit
     // must invalidate the programs it feeds.
     const [extraShim, testShim] = await Promise.all([
         shimHashOf(input.config.patchLint?.checkJsExtraShim),
@@ -125,9 +121,9 @@ export async function buildPerPatchLintCacheKey(input) {
         cacheSchemaVersion: LINT_CACHE_SCHEMA_VERSION,
         engineHeadSha: input.engineHeadSha ?? null,
         lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
-        // Deliberately the PLAIN semver, not the +g<sha> build identity:
-        // identity churns every commit at the same version and
-        // would invalidate the cache for no correctness gain.
+        // The plain semver, not the +g<sha> build identity: that identity
+        // churns every commit at the same version and would invalidate the
+        // cache for no correctness gain.
         packageVersion: input.packageVersion ?? getPackageVersion(),
         patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
         patchMetadata: normalizePatchMetadata(input.patch),
@@ -181,7 +177,7 @@ export async function loadPerPatchLintCache(projectRoot) {
     }
     catch {
         // Any unreadable or malformed cache file is treated as a cold cache. The
-        // cache is a pure optimisation, so discarding it is always safe — the
+        // cache is a pure optimisation, so discarding it is always safe. The
         // alternative is failing lint over a corrupt sidecar.
         return createEmptyPerPatchLintCache();
     }
@@ -203,7 +199,7 @@ function normalizeLintIgnoreSet(lintIgnore) {
 }
 /**
  * Returns the cached lint payload for a patch when the stored key still
- * matches AND the entry was computed under the same lint-ignore waiver set.
+ * matches and the entry was computed under the same lint-ignore waiver set.
  * A waiver change makes a replayed verdict actively wrong, so the waiver set
  * is compared explicitly rather than trusted to the key.
  */
@@ -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,