@hominis/fireforge 0.29.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.30.0
+
+- Added safe repo-local per-patch lint result caching for `lint --per-patch`, plus `--no-cache` and `lint cache clear` escape hatches while preserving release-gate severity accounting and queue-wide checks.
+
 ## 0.29.0
 
 - Improved `fireforge test --build` failure reporting so post-rebuild focused test failures name the rebuild command, requested paths, and first failure line separately from stale-artifact rebuild advice.

package/README.md

@@ -57,6 +57,7 @@ npx fireforge export browser/base/content/browser.js --name custom-toolbar --cat
 npx fireforge re-export custom-toolbar
 npx fireforge re-export --scan --scan-files generated-assets.json --dry-run
 npx fireforge lint --per-patch
+npx fireforge lint --per-patch --max-warnings 0
 npx fireforge verify
 npm run whitespace:check
 npx fireforge build
@@ -65,6 +66,11 @@ npx fireforge test browser/base/content/test/browser/
 
 Use `fireforge --help` for the full set of commands.
 
+`lint --per-patch` reuses safe repo-local results for unchanged patches from
+`.fireforge/lint-cache/`, while still running queue-wide checks every time. Use
+`npx fireforge lint --per-patch --no-cache` to force a fresh run, or
+`npx fireforge lint cache clear` to drop cached per-patch lint results.
+
 For large generated asset batches, `re-export --scan --scan-files <manifest>` assigns files to
 their owner patches without broad directory scanning. The manifest is JSON:
 

package/dist/src/commands/lint-per-patch.d.ts

@@ -0,0 +1,8 @@
+import { getProjectPaths } from '../core/config.js';
+import type { LintCommandOptions } from './lint.js';
+/**
+ * Lints each patch in the queue as its own isolated diff, honouring
+ * per-patch `lintIgnore` entries. Cross-patch rules still run once over
+ * the whole queue so queue-level findings are not lost by the rescoping.
+ */
+export declare function lintPerPatch(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, options?: LintCommandOptions): Promise<void>;

package/dist/src/commands/lint-per-patch.js

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { loadConfig } from '../core/config.js';
+import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
+import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
+import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { evaluatePatchPolicy } from '../core/patch-policy.js';
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { info, outro, success, warn } from '../utils/logger.js';
+function buildPerPatchMaxWarningsMessage(count, maxWarnings, linted) {
+    return (`Patch lint found ${count} warning(s) across ${linted} patch(es), exceeding --max-warnings ${maxWarnings}.` +
+        ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
+}
+/**
+ * Lints each patch in the queue as its own isolated diff, honouring
+ * per-patch `lintIgnore` entries. Cross-patch rules still run once over
+ * the whole queue so queue-level findings are not lost by the rescoping.
+ */
+export async function lintPerPatch(projectRoot, paths, options = {}) {
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        info('No patches in manifest — nothing to lint per-patch.');
+        outro('Nothing to lint');
+        return;
+    }
+    const config = await loadConfig(projectRoot);
+    const ctx = await buildPatchQueueContext(paths.patches);
+    const cache = options.noCache === true ? undefined : await loadPerPatchLintCache(projectRoot);
+    let cacheDirty = false;
+    let reusedCacheEntries = 0;
+    const issues = [];
+    for (const issue of evaluatePatchPolicy(config, manifest)) {
+        issues.push({
+            file: issue.filename,
+            check: `patch-policy/${issue.code}`,
+            message: issue.message,
+            severity: issue.severity,
+        });
+    }
+    let linted = 0;
+    let skipped = 0;
+    for (const patch of manifest.patches) {
+        const existing = [];
+        for (const f of patch.filesAffected) {
+            if (await pathExists(join(paths.engine, f)))
+                existing.push(f);
+        }
+        if (existing.length === 0) {
+            skipped++;
+            continue;
+        }
+        const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
+        if (!diff.trim()) {
+            skipped++;
+            continue;
+        }
+        const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+        const decision = resolvePatchSizeTier(existing, patch.tier);
+        if (decision.tier === 'branding') {
+            info(decision.source === 'explicit'
+                ? `${patch.filename}: branding threshold tier applied via patches.json \`tier: "branding"\` opt-in.`
+                : `${patch.filename}: branding threshold tier applied (all files under browser/branding/ plus registration siblings).`);
+        }
+        let patchIssues;
+        if (cache) {
+            const cacheKey = await buildPerPatchLintCacheKey({
+                projectRoot,
+                engineDir: paths.engine,
+                patchesDir: paths.patches,
+                patch,
+                existingFiles: existing,
+                config,
+                queueContext: ctx,
+            });
+            patchIssues = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
+            if (patchIssues) {
+                reusedCacheEntries++;
+            }
+            else {
+                patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier);
+                setCachedPerPatchLintIssues(cache, patch.filename, cacheKey, patchIssues);
+                cacheDirty = true;
+            }
+        }
+        else {
+            patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier);
+        }
+        for (const issue of patchIssues) {
+            issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
+        }
+        linted++;
+    }
+    issues.push(...lintPatchQueue(ctx));
+    if (cache && cacheDirty)
+        await savePerPatchLintCache(projectRoot, cache);
+    if (reusedCacheEntries > 0) {
+        info(`Reused lint cache for ${reusedCacheEntries} patch${reusedCacheEntries === 1 ? '' : 'es'}.`);
+    }
+    if (issues.length === 0) {
+        if (linted === 0 && skipped > 0) {
+            info(`No patches in the queue have been applied to engine/. Run "fireforge import" first if you want lint findings against the staged hunks; otherwise this is expected.`);
+        }
+        const summary = skipped > 0
+            ? `No lint issues found across ${linted} patch(es) (${skipped} skipped — files not present in engine/).`
+            : `No lint issues found across ${linted} patch(es).`;
+        success(summary);
+        outro('Lint passed');
+        return;
+    }
+    const errors = issues.filter((i) => i.severity === 'error');
+    const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices)
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    for (const issue of warnings)
+        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
+    for (const issue of errors)
+        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
+    info(`\nLint (per-patch over ${linted} patch(es)): ${errors.length} error(s), ${warnings.length} warning(s)`);
+    if (errors.length > 0) {
+        outro('Lint failed');
+        throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
+    }
+    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
+        outro('Lint failed');
+        throw new GeneralError(buildPerPatchMaxWarningsMessage(warnings.length, options.maxWarnings, linted));
+    }
+    if (warnings.length > 0) {
+        outro('Lint passed with warnings');
+    }
+    else if (notices.length > 0) {
+        outro('Lint passed with notices');
+    }
+    else {
+        outro('Lint passed');
+    }
+}
+//# sourceMappingURL=lint-per-patch.js.map

package/dist/src/commands/lint.d.ts

@@ -52,6 +52,11 @@ export interface LintCommandOptions {
      * findings to become blocking without changing default CLI behavior.
      */
     maxWarnings?: number;
+    /**
+     * Bypass per-patch lint cache reads and writes. Accepted in aggregate mode
+     * for CLI consistency, but only `--per-patch` currently uses the cache.
+     */
+    noCache?: boolean;
 }
 /**
  * Result of {@link applyAggregateLintIgnoreSuppression}.

package/dist/src/commands/lint.js

@@ -7,15 +7,15 @@ import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getStatusWithCodes, hasChanges, isGitRepository } from '../core/git.js';
 import { getAllDiff, getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { expandUntrackedDirectoryEntries, getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, getWorkingTreeStatus, } from '../core/git-status.js';
+import { clearPerPatchLintCache } from '../core/lint-cache.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue } from '../core/patch-lint.js';
 import { collectDiffFilePaths, tagLintIssues } from '../core/patch-lint-diff-tag.js';
-import { loadPatchesManifest } from '../core/patch-manifest.js';
-import { evaluatePatchPolicy } from '../core/patch-policy.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
+import { lintPerPatch } from './lint-per-patch.js';
 /**
  * Resolves the diff the lint command should run against. Returns `null` when
  * there is nothing to lint (e.g. no matching files, clean tree, or empty
@@ -399,121 +399,9 @@ export async function lintCommand(projectRoot, files, options = {}) {
         outro('Lint passed');
     }
 }
-/**
- * Lints each patch in the queue as its own isolated diff, honouring
- * per-patch `lintIgnore` entries. Cross-patch rules still run once over
- * the whole queue so queue-level findings (duplicate creations, forward
- * imports) are not lost by the rescoping.
- *
- * Kept separate from {@link lintCommand}'s aggregate path because the
- * two scopes have genuinely different contracts — the aggregate path
- * reports what `git diff HEAD` looks like right now, the per-patch
- * path reports what each patch's own slice of that diff looks like.
- * Sharing a loop would hide the distinction and force the caller to
- * decide semantics mid-function.
- */
-async function lintPerPatch(projectRoot, paths, options = {}) {
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        info('No patches in manifest — nothing to lint per-patch.');
-        outro('Nothing to lint');
-        return;
-    }
-    const config = await loadConfig(projectRoot);
-    const ctx = await buildPatchQueueContext(paths.patches);
-    const issues = [];
-    for (const issue of evaluatePatchPolicy(config, manifest)) {
-        issues.push({
-            file: issue.filename,
-            check: `patch-policy/${issue.code}`,
-            message: issue.message,
-            severity: issue.severity,
-        });
-    }
-    let linted = 0;
-    let skipped = 0;
-    for (const patch of manifest.patches) {
-        const existing = [];
-        for (const f of patch.filesAffected) {
-            if (await pathExists(join(paths.engine, f)))
-                existing.push(f);
-        }
-        if (existing.length === 0) {
-            skipped++;
-            continue;
-        }
-        const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
-        if (!diff.trim()) {
-            skipped++;
-            continue;
-        }
-        const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
-        const decision = resolvePatchSizeTier(existing, patch.tier);
-        if (decision.tier === 'branding') {
-            info(decision.source === 'explicit'
-                ? `${patch.filename}: branding threshold tier applied via patches.json \`tier: "branding"\` opt-in.`
-                : `${patch.filename}: branding threshold tier applied (all files under browser/branding/ plus registration siblings).`);
-        }
-        const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier);
-        for (const issue of patchIssues) {
-            issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
-        }
-        linted++;
-    }
-    // Cross-patch rules over the whole queue — rescoping per-patch would
-    // lose these findings, so they run exactly once against the full
-    // context.
-    issues.push(...lintPatchQueue(ctx));
-    if (issues.length === 0) {
-        // 2026-04-26 eval Finding 7: pre-fix the success line read
-        // `No lint issues found across 0 patch(es).` whenever the queue
-        // had not been applied to the engine — every patch's
-        // `filesAffected` filtered out, so `existing` was empty and the
-        // patch was silently skipped. Operators read that as "the queue
-        // is clean" when in reality nothing was checked. Surface the
-        // skipped count and, when nothing was linted at all, point at
-        // `fireforge import` as the missing prerequisite.
-        if (linted === 0 && skipped > 0) {
-            info(`No patches in the queue have been applied to engine/. Run "fireforge import" first if you want lint findings against the staged hunks; otherwise this is expected.`);
-        }
-        const summary = skipped > 0
-            ? `No lint issues found across ${linted} patch(es) (${skipped} skipped — files not present in engine/).`
-            : `No lint issues found across ${linted} patch(es).`;
-        success(summary);
-        outro('Lint passed');
-        return;
-    }
-    const errors = issues.filter((i) => i.severity === 'error');
-    const warnings = issues.filter((i) => i.severity === 'warning');
-    const notices = issues.filter((i) => i.severity === 'notice');
-    for (const issue of notices)
-        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
-    for (const issue of warnings)
-        warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
-    for (const issue of errors)
-        warn(`ERROR [${issue.check}] ${issue.file}: ${issue.message}`);
-    info(`\nLint (per-patch over ${linted} patch(es)): ${errors.length} error(s), ${warnings.length} warning(s)`);
-    if (errors.length > 0) {
-        outro('Lint failed');
-        throw new GeneralError(`Patch lint found ${errors.length} error(s) across ${linted} patch(es). Fix these before exporting.`);
-    }
-    if (options.maxWarnings !== undefined && warnings.length > options.maxWarnings) {
-        outro('Lint failed');
-        throw new GeneralError(buildMaxWarningsMessage(warnings.length, options.maxWarnings, `across ${linted} patch(es)`));
-    }
-    if (warnings.length > 0) {
-        outro('Lint passed with warnings');
-    }
-    else if (notices.length > 0) {
-        outro('Lint passed with notices');
-    }
-    else {
-        outro('Lint passed');
-    }
-}
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const lint = program
         .command('lint [paths...]')
         .description('Lint engine changes against patch quality rules. Default: aggregate diff against HEAD ' +
         '(every applied patch summed). Use --per-patch for per-patch scope, or pass explicit ' +
@@ -522,6 +410,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
         .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
+        .option('--no-cache', 'Bypass per-patch lint result cache reads and writes.')
         .action(withErrorHandling(async (paths, options) => {
         const lintOptions = {};
         if (options.since !== undefined) {
@@ -540,7 +429,21 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
             }
             lintOptions.maxWarnings = maxWarnings;
         }
+        if (options.cache === false) {
+            lintOptions.noCache = true;
+        }
         await lintCommand(getProjectRoot(), paths, lintOptions);
     }));
+    lint
+        .command('cache')
+        .description('Manage the per-patch lint result cache')
+        .command('clear')
+        .description('Clear cached per-patch lint results')
+        .action(withErrorHandling(async () => {
+        intro('FireForge Lint Cache');
+        await clearPerPatchLintCache(getProjectRoot());
+        success('Cleared per-patch lint cache.');
+        outro('Lint cache cleared');
+    }));
 }
 //# sourceMappingURL=lint.js.map

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

@@ -0,0 +1,52 @@
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type PatchQueueContext } from './patch-lint.js';
+export declare const LINT_CACHE_SCHEMA_VERSION = 1;
+export declare const LINT_IMPLEMENTATION_VERSION = 1;
+export interface PerPatchLintCacheEntry {
+    key: string;
+    patchFilename: string;
+    issues: PatchLintIssue[];
+    updatedAt: string;
+}
+export interface PerPatchLintCacheFile {
+    schemaVersion: typeof LINT_CACHE_SCHEMA_VERSION;
+    entries: Record<string, PerPatchLintCacheEntry>;
+}
+export interface PerPatchLintCacheKeyInput {
+    projectRoot: string;
+    engineDir: string;
+    patchesDir: string;
+    patch: PatchMetadata;
+    existingFiles: string[];
+    config: FireForgeConfig;
+    queueContext: PatchQueueContext;
+    packageVersion?: string;
+}
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue | undefined;
+};
+/** Computes a SHA-256 hex digest for text or binary content. */
+export declare function sha256Hex(content: string | Buffer): string;
+/** Computes a stable SHA-256 digest for JSON-compatible data. */
+export declare function stableHash(value: JsonValue): string;
+/** Returns the repo-local per-patch lint cache file path. */
+export declare function getPerPatchLintCachePath(projectRoot: string): string;
+/**
+ * Builds the complete per-patch lint cache key for one lintable patch.
+ * The key includes source, metadata, config, engine state, and ownership inputs.
+ */
+export declare function buildPerPatchLintCacheKey(input: PerPatchLintCacheKeyInput): Promise<string>;
+/** Creates an empty cache document using the current cache schema. */
+export declare function createEmptyPerPatchLintCache(): PerPatchLintCacheFile;
+/** Loads the per-patch lint cache, treating missing or invalid files as empty. */
+export declare function loadPerPatchLintCache(projectRoot: string): Promise<PerPatchLintCacheFile>;
+/** Persists the per-patch lint cache atomically through the shared JSON writer. */
+export declare function savePerPatchLintCache(projectRoot: string, cache: PerPatchLintCacheFile): Promise<void>;
+/** Clears the per-patch lint cache by replacing it with an empty document. */
+export declare function clearPerPatchLintCache(projectRoot: string): Promise<void>;
+/** Returns cached issues for a patch when the stored key still matches. */
+export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string): PatchLintIssue[] | undefined;
+/** Stores per-patch lint issues after a successful lint calculation. */
+export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[]): void;
+export {};

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

@@ -0,0 +1,171 @@
+// 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 { getPackageVersion } from '../utils/package-root.js';
+import { getFurnacePaths } from './furnace-config.js';
+import { collectNewFileCreatorsByPath } from './patch-lint.js';
+export const LINT_CACHE_SCHEMA_VERSION = 1;
+export const LINT_IMPLEMENTATION_VERSION = 1;
+const LINT_CACHE_DIRNAME = 'lint-cache';
+const PER_PATCH_CACHE_FILENAME = 'per-patch-v1.json';
+function stableJson(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableJson(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries
+        .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+        .join(',')}}`;
+}
+/** Computes a SHA-256 hex digest for text or binary content. */
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/** Computes a stable SHA-256 digest for JSON-compatible data. */
+export function stableHash(value) {
+    return sha256Hex(stableJson(value));
+}
+/** Returns the repo-local per-patch lint cache file path. */
+export function getPerPatchLintCachePath(projectRoot) {
+    return join(projectRoot, '.fireforge', LINT_CACHE_DIRNAME, PER_PATCH_CACHE_FILENAME);
+}
+async function fileHash(path) {
+    if (!(await pathExists(path))) {
+        return { exists: false };
+    }
+    return { exists: true, sha256: sha256Hex(await readFile(path)) };
+}
+function normalizePatchMetadata(patch) {
+    return {
+        filesAffected: patch.filesAffected,
+        lintIgnore: patch.lintIgnore,
+        stagedDependencies: patch.stagedDependencies,
+        tier: patch.tier,
+    };
+}
+function normalizeLintConfig(config) {
+    return {
+        binaryName: config.binaryName,
+        license: config.license,
+        patchLint: config.patchLint,
+    };
+}
+function isOwnershipRelevantFile(file) {
+    return file.endsWith('.js') || file.endsWith('.mjs') || file.endsWith('.jsm');
+}
+function buildOwnershipFingerprint(files, ctx) {
+    const creators = collectNewFileCreatorsByPath(ctx);
+    const entries = {};
+    const relevantFiles = [...files]
+        .filter(isOwnershipRelevantFile)
+        .sort((a, b) => a.localeCompare(b));
+    for (const file of relevantFiles) {
+        entries[file] = [...(creators.get(file) ?? [])].sort((a, b) => a.localeCompare(b));
+    }
+    return entries;
+}
+/**
+ * Builds the complete per-patch lint cache key for one lintable patch.
+ * The key includes source, metadata, config, engine state, and ownership inputs.
+ */
+export async function buildPerPatchLintCacheKey(input) {
+    const engineFiles = {};
+    for (const file of [...input.existingFiles].sort((a, b) => a.localeCompare(b))) {
+        engineFiles[file] = await fileHash(join(input.engineDir, file));
+    }
+    const furnaceConfigPath = getFurnacePaths(input.projectRoot).furnaceConfig;
+    const extraShimPath = input.config.patchLint?.checkJsExtraShim;
+    const extraShim = extraShimPath === undefined
+        ? null
+        : {
+            path: extraShimPath,
+            hash: await fileHash(resolve(input.projectRoot, extraShimPath)),
+        };
+    return stableHash({
+        cacheSchemaVersion: LINT_CACHE_SCHEMA_VERSION,
+        lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
+        packageVersion: input.packageVersion ?? getPackageVersion(),
+        patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
+        patchMetadata: normalizePatchMetadata(input.patch),
+        lintConfig: normalizeLintConfig(input.config),
+        furnaceConfig: await fileHash(furnaceConfigPath),
+        checkJsExtraShim: extraShim,
+        engineFiles,
+        queueOwnership: buildOwnershipFingerprint(input.existingFiles, input.queueContext),
+    });
+}
+/** Creates an empty cache document using the current cache schema. */
+export function createEmptyPerPatchLintCache() {
+    return { schemaVersion: LINT_CACHE_SCHEMA_VERSION, entries: {} };
+}
+function isCacheEntry(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    return (typeof entry.key === 'string' &&
+        typeof entry.patchFilename === 'string' &&
+        Array.isArray(entry.issues) &&
+        typeof entry.updatedAt === 'string');
+}
+/** Loads the per-patch lint cache, treating missing or invalid files as empty. */
+export async function loadPerPatchLintCache(projectRoot) {
+    const cachePath = getPerPatchLintCachePath(projectRoot);
+    if (!(await pathExists(cachePath))) {
+        return createEmptyPerPatchLintCache();
+    }
+    try {
+        const raw = await readJson(cachePath);
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            return createEmptyPerPatchLintCache();
+        }
+        const candidate = raw;
+        if (candidate.schemaVersion !== LINT_CACHE_SCHEMA_VERSION || !candidate.entries) {
+            return createEmptyPerPatchLintCache();
+        }
+        const entries = {};
+        for (const [filename, entry] of Object.entries(candidate.entries)) {
+            if (isCacheEntry(entry)) {
+                entries[filename] = entry;
+            }
+        }
+        return { schemaVersion: LINT_CACHE_SCHEMA_VERSION, entries };
+    }
+    catch {
+        return createEmptyPerPatchLintCache();
+    }
+}
+/** Persists the per-patch lint cache atomically through the shared JSON writer. */
+export async function savePerPatchLintCache(projectRoot, cache) {
+    await writeJson(getPerPatchLintCachePath(projectRoot), {
+        schemaVersion: LINT_CACHE_SCHEMA_VERSION,
+        entries: cache.entries,
+    });
+}
+/** Clears the per-patch lint cache by replacing it with an empty document. */
+export async function clearPerPatchLintCache(projectRoot) {
+    await writeJson(getPerPatchLintCachePath(projectRoot), createEmptyPerPatchLintCache());
+}
+/** Returns cached issues for a patch when the stored key still matches. */
+export function getCachedPerPatchLintIssues(cache, patchFilename, key) {
+    const entry = cache.entries[patchFilename];
+    if (!entry || entry.key !== key)
+        return undefined;
+    return entry.issues.map((issue) => ({ ...issue }));
+}
+/** Stores per-patch lint issues after a successful lint calculation. */
+export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues) {
+    cache.entries[patchFilename] = {
+        key,
+        patchFilename,
+        issues: issues.map((issue) => ({ ...issue })),
+        updatedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=lint-cache.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",