@hominis/fireforge 0.28.5 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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.
+
 ## 0.28.0
 
 - Restored mach lint compatibility for FireForge-managed Git-backed Firefox checkouts by materializing a `.hgignore` copy of `.gitignore` when Firefox's ignorefile linter config is present.

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/commands/test.js

@@ -5,9 +5,9 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, testWithOutput, withBuildLock, } from '../core/mach.js';
 import { assertMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
-import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, } from '../core/test-harness-output.js';
+import { buildHarnessEarlyExitMessage, classifyHarnessEarlyExit, completePostRebuildFailureContext, createPostRebuildFailureContext, prependPostRebuildFailureContext, } from '../core/test-harness-output.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
-import { tryRepairStaleXpcshellTestSymlink } from '../core/test-stale-symlink.js';
+import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
@@ -34,7 +34,12 @@ function buildUnknownTestMessage(testPaths) {
         'The file may exist, but Firefox does not currently resolve it as a runnable test.\n\n' +
         'Check the nearest test manifest (for example browser.toml or xpcshell.toml), confirm the file is listed under the correct test type, and make sure each parent moz.build registers that manifest before retrying.');
 }
-function buildStaleBuildMessage() {
+function buildStaleBuildMessage(postRebuild) {
+    if (postRebuild) {
+        return ('Firefox test runtime still reported stale-artifact-shaped resource failures after the rebuild completed.\n\n' +
+            'FireForge already ran the requested rebuild before this focused test, so treat the remaining failure as a real runtime, registration, routing, or test-contract regression rather than another stale deployed-artifact-only blocker.\n\n' +
+            'Check the first post-rebuild failure above and the raw mach output for the concrete path or module that still fails.');
+    }
     return ('Firefox test runtime appears to be using stale build artifacts.\n\n' +
         'The failing output referenced missing branding or distribution resources, which usually means the current obj-* build does not match recent engine or branding changes.\n\n' +
         'Re-run "fireforge build --ui" or "fireforge test --build" and then retry.');
@@ -171,6 +176,15 @@ async function runPreTestBuild(projectRoot, paths, projectConfig) {
         s.stop('Build complete');
     });
 }
+function logTestSelection(normalizedPaths) {
+    if (normalizedPaths.length > 0) {
+        info(`Running tests: ${normalizedPaths.join(', ')}`);
+    }
+    else {
+        info('Running all tests...');
+    }
+    info('');
+}
 // Detects the `AttributeError: 'MochitestDesktop' object has no attribute
 // 'http3Server'` teardown crash. The attribute is lazy-initialized inside
 // harness code paths that presume chrome://branding resolves correctly; a
@@ -188,16 +202,23 @@ function buildMochitestHttp3ServerMessage() {
         "  - The `BROWSER_CHROME_MANIFESTS` entry for your fork's chrome.manifest is registered.\n\n" +
         'This is an upstream Firefox harness interaction; FireForge can only diagnose it.');
 }
-function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName) {
+function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted, binaryName, postRebuildContext) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
+    const failureContext = postRebuildContext
+        ? completePostRebuildFailureContext(postRebuildContext, combinedOutput)
+        : undefined;
+    const withContext = (message) => prependPostRebuildFailureContext(message, failureContext);
+    const throwGeneral = (message) => {
+        throw new GeneralError(withContext(message));
+    };
     if (/UNKNOWN TEST\b/i.test(combinedOutput)) {
-        throw new GeneralError(buildUnknownTestMessage(normalizedPaths));
+        throwGeneral(buildUnknownTestMessage(normalizedPaths));
     }
     const earlyExit = classifyHarnessEarlyExit(combinedOutput, normalizedPaths);
     if (earlyExit) {
-        throw new GeneralError(buildHarnessEarlyExitMessage(earlyExit, normalizedPaths));
+        throwGeneral(buildHarnessEarlyExitMessage(earlyExit, normalizedPaths));
     }
     // Fork-owned module load failures must beat the branding stale-build
     // branch: 2026-04-21 eval (Finding #14) saw a fork's test fail with
@@ -206,7 +227,7 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     // stale-build pattern matched, so the operator was told to rebuild
     // when the real fix is to register the missing module.
     if (hasForkModuleSignal(combinedOutput, binaryName)) {
-        throw new GeneralError(buildForkModuleMessage(binaryName));
+        throwGeneral(buildForkModuleMessage(binaryName));
     }
     // Branding-specific stale-build signals keep priority over the broader
     // xpcshell-appdir hint: when `chrome://branding/locale/brand.properties`
@@ -219,24 +240,24 @@ function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted
     // which is the more useful diagnosis in practice for `Failed to load
     // resource:///modules/…`.
     if (hasStaleBuildArtifactsSignal(combinedOutput)) {
-        throw new GeneralError(buildStaleBuildMessage());
+        throwGeneral(buildStaleBuildMessage(Boolean(failureContext)));
     }
     if (hasXpcshellAppdirSignal(combinedOutput)) {
-        throw new GeneralError(buildXpcshellAppdirMessage(appdirInjectionAttempted));
+        throwGeneral(buildXpcshellAppdirMessage(appdirInjectionAttempted));
     }
     if (hasMochitestHttp3ServerSignal(combinedOutput)) {
-        throw new GeneralError(buildMochitestHttp3ServerMessage());
+        throwGeneral(buildMochitestHttp3ServerMessage());
     }
     if (/FileExistsError/i.test(combinedOutput) &&
         /(mochitest|xpcshell|_tests)/i.test(combinedOutput)) {
-        throw new GeneralError(buildHarnessSymlinkMessage());
+        throwGeneral(buildHarnessSymlinkMessage());
     }
     if (/invalid filename/i.test(combinedOutput) ||
         /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');
         info('Run "fireforge register <test-path>" to register it.');
     }
-    throw new BuildError(`Tests failed with exit code ${result.exitCode}. Check the output above for details.`, 'mach test');
+    throw new BuildError(withContext(`Tests failed with exit code ${result.exitCode}. Check the output above for details.`), 'mach test');
 }
 /**
  * Runs the test command to execute mach tests.
@@ -362,10 +383,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
             throw new GeneralError('Marionette preflight reported FAIL — see output above. Aborting before mach test runs.');
         }
     }
-    // Normalize test paths (strip engine/ prefix if present). Uses the
-    // shared `stripEnginePrefix` helper so `test`, `register`, `lint`, and
-    // `export` all accept the same prefix forms. Also trim to match the
-    // previous case-insensitive + leading-whitespace-tolerant contract.
     const normalizedPaths = testPaths.map((p) => stripEnginePrefix(p).trim());
     await assertTestPathsExist(paths.engine, normalizedPaths);
     const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
@@ -375,7 +392,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     const forwardedMachArgs = options.machArg && options.machArg.length > 0
         ? filterRedundantXpcshellFlavorArgs(options.machArg, classification)
         : [];
-    // Build extra args
     const extraArgs = [];
     if (options.headless) {
         extraArgs.push('--headless');
@@ -430,14 +446,7 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // overrides via `--mach-arg=--app-path=…` always win — we skip injection
     // when the operator already passed one.
     const appdirInjection = await maybeInjectAppdirArg(paths.engine, normalizedPaths, buildCheck.objDir, extraArgs);
-    // Log what we're doing
-    if (normalizedPaths.length > 0) {
-        info(`Running tests: ${normalizedPaths.join(', ')}`);
-    }
-    else {
-        info('Running all tests...');
-    }
-    info('');
+    logTestSelection(normalizedPaths);
     let result;
     try {
         result = await testWithOutput(paths.engine, normalizedPaths, extraArgs);
@@ -445,15 +454,10 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
-    if (result.exitCode !== 0 &&
-        classification.xpcshell.length > 0 &&
-        classification.nonXpcshell.length === 0) {
-        const repaired = await tryRepairStaleXpcshellTestSymlink(paths.engine, buildCheck.objDir, `${result.stdout}\n${result.stderr}`);
-        if (repaired) {
-            result = await testWithOutput(paths.engine, normalizedPaths, extraArgs);
-        }
-    }
-    handleNonZeroTestExit(result, normalizedPaths, appdirInjection, projectConfig.binaryName);
+    result = await retryAfterXpcshellSymlinkRepair(paths.engine, buildCheck.objDir, result, classification, normalizedPaths, extraArgs);
+    handleNonZeroTestExit(result, normalizedPaths, appdirInjection, projectConfig.binaryName, options.build
+        ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
+        : undefined);
 }
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {

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/dist/src/core/test-harness-output.d.ts

@@ -3,6 +3,19 @@ export interface HarnessEarlyExit {
     kind: HarnessEarlyExitKind;
     line: string;
 }
+export interface PostRebuildFailureContext {
+    rebuildCommand: string;
+    requestedPaths: readonly string[];
+    firstFailureLine?: string;
+}
+/** Finds the first high-signal failure line from captured mach test output. */
+export declare function findFirstUsefulFailureLine(output: string): string | undefined;
+/** Starts a post-rebuild context block for a focused test failure. */
+export declare function createPostRebuildFailureContext(rebuildCommand: string, requestedPaths: readonly string[]): PostRebuildFailureContext;
+/** Adds the first useful failure line from captured output to an existing context block. */
+export declare function completePostRebuildFailureContext(context: PostRebuildFailureContext, output: string): PostRebuildFailureContext;
+/** Prepends post-rebuild context when the test failure happened after a successful rebuild. */
+export declare function prependPostRebuildFailureContext(message: string, context: PostRebuildFailureContext | undefined): string;
 /** Classifies mach output where no requested test actually began running. */
 export declare function classifyHarnessEarlyExit(output: string, normalizedPaths: readonly string[]): HarnessEarlyExit | undefined;
 /** Builds the user-facing message for a harness startup or zero-run failure. */

package/dist/src/core/test-harness-output.js

@@ -8,6 +8,45 @@ function getNonEmptyOutputLines(output) {
 function findFirstMatchingLine(lines, patterns) {
     return lines.find((line) => patterns.some((pattern) => pattern.test(line)));
 }
+/** Finds the first high-signal failure line from captured mach test output. */
+export function findFirstUsefulFailureLine(output) {
+    const lines = getNonEmptyOutputLines(output);
+    const matched = findFirstMatchingLine(lines, [
+        /\bTEST-UNEXPECTED-[A-Z-]+\b/,
+        /\bPROCESS-CRASH\b/i,
+        /\bTIMEOUT\b/i,
+        /timed out/i,
+        /HominisBrowserUnavailableError/i,
+        /Marionette.*(?:session|startup|start).*fail/i,
+        /(?:failed|unable) to (?:start|create|open).*Marionette/i,
+        /SessionNotCreatedException/i,
+        /Browser process exited during spawn/i,
+        /Failed to load (?:resource|chrome):\/\//i,
+        /\b(?:Error|Exception|TypeError|ReferenceError|SyntaxError):\s+/,
+        /AttributeError:\s+/,
+    ]);
+    return matched ?? lines[0];
+}
+/** Starts a post-rebuild context block for a focused test failure. */
+export function createPostRebuildFailureContext(rebuildCommand, requestedPaths) {
+    return { rebuildCommand, requestedPaths };
+}
+/** Adds the first useful failure line from captured output to an existing context block. */
+export function completePostRebuildFailureContext(context, output) {
+    const firstFailureLine = findFirstUsefulFailureLine(output);
+    return firstFailureLine ? { ...context, firstFailureLine } : context;
+}
+/** Prepends post-rebuild context when the test failure happened after a successful rebuild. */
+export function prependPostRebuildFailureContext(message, context) {
+    if (!context)
+        return message;
+    const requestedPaths = context.requestedPaths.length > 0 ? context.requestedPaths.join(', ') : '(all tests)';
+    return ('Post-rebuild test failure:\n\n' +
+        `Rebuild command: ${context.rebuildCommand}\n` +
+        `Requested paths: ${requestedPaths}\n` +
+        `First post-rebuild failure: ${context.firstFailureLine ?? '(no captured output)'}\n\n` +
+        message);
+}
 /** Classifies mach output where no requested test actually began running. */
 export function classifyHarnessEarlyExit(output, normalizedPaths) {
     const lines = getNonEmptyOutputLines(output);

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -0,0 +1,7 @@
+import { type MachCommandResult } from './mach.js';
+export interface XpcshellRetryClassification {
+    xpcshell: readonly string[];
+    nonXpcshell: readonly string[];
+}
+/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
+export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[]): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { testWithOutput } from './mach.js';
+import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
+/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
+export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs) {
+    if (result.exitCode !== 0 &&
+        classification.xpcshell.length > 0 &&
+        classification.nonXpcshell.length === 0) {
+        const repaired = await tryRepairStaleXpcshellTestSymlink(engineDir, objDir, `${result.stdout}\n${result.stderr}`);
+        if (repaired) {
+            return testWithOutput(engineDir, normalizedPaths, extraArgs);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=test-xpcshell-retry.js.map

package/package.json

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