@hominis/fireforge 0.39.0 → 0.40.0

package/dist/src/commands/status-check.js

@@ -0,0 +1,88 @@
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+const ALL_CLASSIFICATIONS = [
+    'patch-backed',
+    'patch-owned-drift',
+    'unmanaged',
+    'branding',
+    'furnace',
+    'conflict',
+];
+/** Default `--check` policy: everything outside {patch-backed, branding, furnace} fails. */
+const DEFAULT_FAIL_CLASSIFICATIONS = [
+    'unmanaged',
+    'patch-owned-drift',
+    'conflict',
+];
+/**
+ * Resolves the enforcement policy from the raw flags: `--fail-on` implies
+ * `--check` and replaces the default set; both are refused alongside the
+ * modes that skip (or elide) classification.
+ */
+export function resolveStatusCheckPolicy(options) {
+    const failOnList = parseFailOnClassifications(options.failOn);
+    const checkEnabled = options.check === true || failOnList !== undefined;
+    if (checkEnabled &&
+        (options.raw === true ||
+            options.unmanaged === true ||
+            options.ownership === true ||
+            options.testCoverage === true)) {
+        throw new InvalidArgumentError('--check cannot be combined with --raw, --unmanaged, --ownership, or --test-coverage. Use the default view or --json.', '--check');
+    }
+    return { checkEnabled, failOn: failOnList ?? DEFAULT_FAIL_CLASSIFICATIONS };
+}
+function isClassification(value) {
+    return ALL_CLASSIFICATIONS.includes(value);
+}
+/**
+ * Parses a comma-separated `--fail-on` value into a classification list.
+ * Returns undefined when the flag was not given (the caller then applies
+ * the default policy only under `--check`).
+ */
+function parseFailOnClassifications(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parts = raw
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        throw new InvalidArgumentError(`--fail-on requires at least one classification. Valid: ${ALL_CLASSIFICATIONS.join(', ')}.`, '--fail-on');
+    }
+    const classifications = [];
+    for (const part of parts) {
+        if (!isClassification(part)) {
+            throw new InvalidArgumentError(`Unknown --fail-on classification "${part}". Valid: ${ALL_CLASSIFICATIONS.join(', ')}.`, '--fail-on');
+        }
+        if (!classifications.includes(part))
+            classifications.push(part);
+    }
+    return classifications;
+}
+const CHECK_FILE_PREVIEW_MAX = 3;
+/**
+ * Throws a GeneralError (exit 1) when the policy is enabled and any of
+ * its classifications is non-empty, naming each offending classification
+ * with its first few files. A disabled policy or a fully tool-covered
+ * tree passes silently.
+ */
+export function runStatusCheck(classified, policy) {
+    if (!policy.checkEnabled)
+        return;
+    const offending = [];
+    for (const classification of policy.failOn) {
+        const files = classified
+            .filter((entry) => entry.classification === classification)
+            .map((entry) => entry.file);
+        if (files.length === 0)
+            continue;
+        const preview = files.slice(0, CHECK_FILE_PREVIEW_MAX).join(', ');
+        const more = files.length > CHECK_FILE_PREVIEW_MAX
+            ? `, +${String(files.length - CHECK_FILE_PREVIEW_MAX)} more`
+            : '';
+        offending.push(`${String(files.length)} ${classification} (${preview}${more})`);
+    }
+    if (offending.length === 0)
+        return;
+    throw new GeneralError(`status --check failed: ${offending.join(', ')}. Export or adopt unmanaged files, ` +
+        `re-export drifted patches, and run "fireforge verify" for conflict details.`);
+}

package/dist/src/commands/status.js

@@ -13,6 +13,7 @@ import { CommandError, GeneralError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
+import { resolveStatusCheckPolicy, runStatusCheck } from './status-check.js';
 import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
 /**
  * Renders raw worktree status as machine-parseable porcelain-style output.
@@ -86,14 +87,17 @@ function filterFireForgeTempFiles(files) {
 /**
  * Renders classified file status as machine-readable JSON to stdout.
  */
-async function renderJsonStatus(files, paths, projectRoot, binaryName) {
+async function classifyStatusFiles(files, paths, projectRoot, binaryName) {
     const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    const classified = await classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
+    return classifyFiles(files, paths.engine, paths.patches, binaryName, furnacePrefixes);
+}
+function renderJsonStatus(classified) {
     const outputFiles = classified.map((f) => {
         const entry = {
             file: f.file,
             status: f.status.trim(),
             classification: f.classification,
+            patch: f.owner ?? null,
         };
         if (f.classification === 'conflict' && f.claimedBy && f.claimedBy.length > 0) {
             entry.claimedBy = [...f.claimedBy];
@@ -181,6 +185,9 @@ export async function statusCommand(projectRoot, options = {}) {
         if (modeCount > 1) {
             throw new GeneralError('Cannot use --raw, --unmanaged, --ownership, --test-coverage, and --json together. Pick at most one.');
         }
+        // --check / --fail-on enforcement policy (FORGE G1). Applies only
+        // where classification runs (the default view and --json).
+        const checkPolicy = resolveStatusCheckPolicy(options);
         if (!options.raw && !options.json) {
             intro('FireForge Status');
         }
@@ -270,7 +277,9 @@ export async function statusCommand(projectRoot, options = {}) {
         // the output through a JSON parser broke precisely when there was
         // nothing to report. Emit `[]` here and return before the human fallback.
         if (options.json) {
-            await renderJsonStatus(files, paths, projectRoot, config.binaryName);
+            const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
+            renderJsonStatus(classified);
+            runStatusCheck(classified, checkPolicy);
             return;
         }
         // `--raw` consumers parse the native `git status --porcelain` output
@@ -291,8 +300,7 @@ export async function statusCommand(projectRoot, options = {}) {
             return;
         }
         // Patch-aware classification
-        const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-        const classified = await classifyFiles(files, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
+        const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
         const buckets = {
             conflict: classified.filter((f) => f.classification === 'conflict'),
             unmanaged: classified.filter((f) => f.classification === 'unmanaged'),
@@ -307,6 +315,7 @@ export async function statusCommand(projectRoot, options = {}) {
             return;
         }
         await renderDefaultStatus(files.length, buckets, projectRoot, config.binaryName);
+        runStatusCheck(classified, checkPolicy);
     }
     finally {
         if (isMachineOutputMode() !== previousMachineOutputMode) {
@@ -324,6 +333,8 @@ export function registerStatus(program, { getProjectRoot, withErrorHandling }) {
         .option('--ownership', 'Show a flat path → owning patch table (flags files claimed by multiple patches)')
         .option('--test-coverage', 'Show what the last recorded build covers for test packaging (full or scoped paths)')
         .option('--json', 'Output classified file status as JSON')
+        .option('--check', 'Exit non-zero when any unmanaged, patch-owned-drift, or conflict file exists (composes with --json; combine with --fail-on for finer policy)')
+        .option('--fail-on <classifications>', 'Comma-separated classification list that fails --check, replacing the default set (implies --check). Valid: patch-backed, patch-owned-drift, unmanaged, branding, furnace, conflict')
         .action(withErrorHandling(async (options) => {
         await statusCommand(getProjectRoot(), options);
     }));

package/dist/src/commands/test-run.js

@@ -14,6 +14,7 @@
 import { mochitestWithOutput, testWithOutput, xpcshellTestWithOutput, } from '../core/mach.js';
 import { buildHarnessCrashMessage, classifyHarnessRun, headedNoOutputTimeoutHint, } from '../core/test-harness-crash.js';
 import { retryAfterXpcshellSymlinkRepair } from '../core/test-xpcshell-retry.js';
+import { withXpcshellProfileDir } from '../core/xpcshell-profile-dir.js';
 import { BuildError } from '../errors/build.js';
 import { info, note, warn } from '../utils/logger.js';
 import { getPlatform } from '../utils/platform.js';
@@ -34,6 +35,20 @@ function dispatchForSuite(suite) {
  * stale-xpcshell-symlink repair path the single-run flow already used.
  */
 export async function runTestsWithRetries(ctx, paths) {
+    // Pure mochitest dispatches keep their env byte-identical — the profile
+    // variable is xpcshell-harness-specific (FORGE G15b). Generic `mach
+    // test` runs may include xpcshell paths, so they get the isolation too.
+    if (ctx.suite === 'mochitest') {
+        return runTestsWithRetriesInner(ctx, paths, ctx.env);
+    }
+    // Fresh profile dir per harness invocation: shards isolate from each
+    // other and from concurrent `fireforge test` processes; the crash /
+    // symlink-repair retries inside one invocation deliberately REUSE the
+    // same directory (they are the same logical run and the harness
+    // re-initialises the profile contents itself).
+    return withXpcshellProfileDir(ctx.env, (env) => runTestsWithRetriesInner(ctx, paths, env));
+}
+async function runTestsWithRetriesInner(ctx, paths, env) {
     const extraArgs = [...ctx.baseExtraArgs];
     const appdirInjectionAttempted = await maybeInjectAppdirArg(ctx.engineDir, paths, ctx.objDir, extraArgs);
     const dispatch = dispatchForSuite(ctx.suite);
@@ -43,10 +58,10 @@ export async function runTestsWithRetries(ctx, paths) {
     let verdict;
     for (;;) {
         attempts += 1;
-        result = ctx.env
-            ? await dispatch(ctx.engineDir, paths, extraArgs, ctx.env)
+        result = env
+            ? await dispatch(ctx.engineDir, paths, extraArgs, env)
             : await dispatch(ctx.engineDir, paths, extraArgs);
-        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, ctx.env, dispatch);
+        result = await retryAfterXpcshellSymlinkRepair(ctx.engineDir, ctx.objDir, result, ctx.classification, paths, extraArgs, env, dispatch);
         const combined = `${result.stdout}\n${result.stderr}`;
         verdict = classifyHarnessRun(result.exitCode, combined, paths);
         if (verdict.kind !== 'harness-crash' || attempts >= maxAttempts)

package/dist/src/commands/token.js

@@ -105,7 +105,10 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
         ...(options.variant !== undefined ? { variant: options.variant } : {}),
     });
     if (result.skipped) {
-        info(`Token ${tokenName} already exists (skipped)`);
+        const where = result.skippedExisting
+            ? ` in category "${result.skippedExisting.category ?? options.category}" (line ${String(result.skippedExisting.line)})`
+            : '';
+        info(`Token ${tokenName} already exists${where} (skipped)`);
     }
     else {
         const forgeConfig = await loadConfig(projectRoot);

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

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/** Creates a verification tree under `.fireforge/trees/<name>`. */
+export declare function treeCreateCommand(projectRoot: string, name: string, options?: {
+    forceCopy?: boolean;
+}): Promise<void>;
+/** Prints the tree list with staleness against the current primary state. */
+export declare function treeListCommand(projectRoot: string, options?: {
+    json?: boolean;
+}): Promise<void>;
+/** Removes one tree (or all of them with `--all`). */
+export declare function treeRemoveCommand(projectRoot: string, name: string | undefined, options?: {
+    all?: boolean;
+}): Promise<void>;
+/** Registers the tree command group on the CLI program. */
+export declare function registerTree(program: Command, context: CommandContext): void;

package/dist/src/commands/tree.js

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge tree` — copy-on-write verification clones (FORGE G15).
+ *
+ * Trees enable concurrent READ-MOSTLY verification (lint, typecheck,
+ * status, verify, doctor, export dry-runs) beside a busy primary tree.
+ * Exports and every other mutation stay strictly serial in the primary —
+ * a tree's patches/components are snapshots with no merge model, and the
+ * tree guard (cli.ts preAction + core/tree-guard.ts) refuses mutating
+ * commands inside a tree. In-tree `test` and objdir cloning are deferred:
+ * mach objdirs embed absolute source paths, so a cloned objdir would
+ * silently operate against the primary tree.
+ */
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { detectCowSupport } from '../core/tree-cow.js';
+import { cloneTree, listTrees, removeTree } from '../core/tree-store.js';
+import { assertValidTreeName, computePrimaryFingerprint, getTreesDir, readTreeMarker, withTreeLifecycleLock, } from '../core/tree-store.js';
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { info, intro, outro, success, warn } from '../utils/logger.js';
+function assertPosix() {
+    if (process.platform === 'win32') {
+        throw new GeneralError('fireforge tree is POSIX-only; copy-on-write cloning relies on clonefile/reflink, which are not available on Windows.');
+    }
+}
+/** Creates a verification tree under `.fireforge/trees/<name>`. */
+export async function treeCreateCommand(projectRoot, name, options = {}) {
+    assertPosix();
+    intro('FireForge Tree Create');
+    assertValidTreeName(name);
+    if (await readTreeMarker(projectRoot)) {
+        throw new GeneralError('Verification trees cannot be nested: run tree create in the primary tree.');
+    }
+    const treesDir = getTreesDir(projectRoot);
+    const treeRoot = join(treesDir, name);
+    await withTreeLifecycleLock(projectRoot, async () => {
+        if (await pathExists(treeRoot)) {
+            throw new GeneralError(`A tree named "${name}" already exists. Remove it first (fireforge tree remove ${name}) — refresh is remove + create.`);
+        }
+        const { mkdir } = await import('node:fs/promises');
+        await mkdir(treesDir, { recursive: true });
+        const capability = await detectCowSupport(treesDir);
+        if (capability === 'none' && options.forceCopy !== true) {
+            throw new GeneralError('This filesystem cannot copy-on-write (APFS clonefile or btrfs/XFS reflink required), so a tree ' +
+                'would be a full physical copy of the applied engine tree — potentially tens of gigabytes. ' +
+                'Re-run with --force-copy to accept that explicitly.');
+        }
+        if (capability === 'none') {
+            warn('No copy-on-write support detected — performing a full physical copy (--force-copy).');
+        }
+        // Snapshot under the PRIMARY engine-session lock so a mid-mutation
+        // state (half-applied export, furnace deploy) is never captured.
+        const marker = await withEngineSessionLock(projectRoot, 'tree create', () => cloneTree({
+            primaryRoot: projectRoot,
+            treeRoot,
+            name,
+            capability,
+            createdAt: new Date().toISOString(),
+        }));
+        success(`Created verification tree "${name}" at ${treeRoot}`);
+        info(`  Engine HEAD: ${marker.engineHead ?? '(no engine)'}`);
+        info('  Read-only: status, lint, typecheck, verify, doctor, and export --dry-run run inside it; mutation commands are refused.');
+    });
+    outro('Tree created');
+}
+/** Prints the tree list with staleness against the current primary state. */
+export async function treeListCommand(projectRoot, options = {}) {
+    const trees = await listTrees(projectRoot);
+    if (options.json === true) {
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, trees }, null, 2)}\n`);
+        return;
+    }
+    intro('FireForge Trees');
+    if (trees.length === 0) {
+        info('No verification trees. Create one with: fireforge tree create <name>');
+        outro('Done');
+        return;
+    }
+    for (const tree of trees) {
+        info(`${tree.name.padEnd(20)} ${tree.staleness.padEnd(24)} created ${tree.createdAt}`);
+    }
+    outro(`${trees.length} tree(s)`);
+}
+/** Removes one tree (or all of them with `--all`). */
+export async function treeRemoveCommand(projectRoot, name, options = {}) {
+    assertPosix();
+    intro('FireForge Tree Remove');
+    if (options.all !== true && name === undefined) {
+        throw new GeneralError('Pass a tree name, or --all to remove every tree.');
+    }
+    await withTreeLifecycleLock(projectRoot, async () => {
+        const targets = options.all === true ? (await listTrees(projectRoot)).map((t) => t.name) : [name ?? ''];
+        if (targets.length === 0) {
+            info('No verification trees to remove.');
+            return;
+        }
+        for (const target of targets) {
+            await removeTree(projectRoot, target);
+            success(`Removed verification tree "${target}"`);
+        }
+    });
+    outro('Tree removal complete');
+}
+/** Spawns `fireforge <args>` with the tree as its working directory. */
+async function treeExecCommand(projectRoot, name, args) {
+    assertPosix();
+    assertValidTreeName(name);
+    const treeRoot = join(getTreesDir(projectRoot), name);
+    const marker = await readTreeMarker(treeRoot);
+    if (!marker) {
+        throw new GeneralError(`No verification tree named "${name}". List trees with: fireforge tree list`);
+    }
+    const current = await computePrimaryFingerprint(projectRoot);
+    if (marker.engineHead !== current.engineHead) {
+        warn(`Tree "${name}" is stale (primary engine advanced since the snapshot).`);
+    }
+    else if (marker.patchesFingerprint !== current.patchesFingerprint) {
+        warn(`Tree "${name}" is stale (primary patches changed since the snapshot).`);
+    }
+    const cliEntry = process.argv[1];
+    if (cliEntry === undefined) {
+        throw new GeneralError('Cannot resolve the fireforge CLI entry point for tree exec.');
+    }
+    const exitCode = await new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(process.execPath, [cliEntry, ...args], {
+            cwd: treeRoot,
+            stdio: 'inherit',
+        });
+        child.on('error', rejectPromise);
+        child.on('exit', (code) => {
+            resolvePromise(code ?? 1);
+        });
+    });
+    if (exitCode !== 0) {
+        throw new GeneralError(`tree exec: fireforge ${args.join(' ')} exited with code ${String(exitCode)}.`);
+    }
+}
+/** Registers the tree command group on the CLI program. */
+export function registerTree(program, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const tree = program
+        .command('tree')
+        .description('Manage copy-on-write verification clones of this project for concurrent read-mostly work (lint, typecheck, status, verify, export --dry-run). Mutation commands are refused inside a tree.');
+    tree
+        .command('create <name>')
+        .description('Clone the project (engine included, obj-* excluded) into .fireforge/trees/<name> using filesystem copy-on-write (APFS clonefile / btrfs-XFS reflink). Refuses on filesystems without CoW support unless --force-copy explicitly accepts a full physical copy.')
+        .option('--force-copy', 'Allow a full physical copy when the filesystem cannot copy-on-write. This can copy tens of GB; never implied.')
+        .action(withErrorHandling(async (name, options) => {
+        await treeCreateCommand(getProjectRoot(), name, options);
+    }));
+    tree
+        .command('list')
+        .description('List verification trees with creation time and staleness vs the primary tree (engine HEAD and patches.json fingerprint).')
+        .option('--json', 'Output the tree list as JSON')
+        .action(withErrorHandling(async (options) => {
+        await treeListCommand(getProjectRoot(), options);
+    }));
+    tree
+        .command('remove [name]')
+        .description("Delete a verification tree. Refuses while a live process holds the tree's build or engine-session lock.")
+        .option('--all', 'Remove every verification tree')
+        .action(withErrorHandling(async (name, options) => {
+        await treeRemoveCommand(getProjectRoot(), name, options);
+    }));
+    tree
+        .command('exec <name> [args...]')
+        .description('Run a fireforge command inside the named tree (equivalent to cd-ing into it). Example: fireforge tree exec shard-a -- lint --per-patch')
+        .action(withErrorHandling(async (name, args) => {
+        await treeExecCommand(getProjectRoot(), name, args);
+    }));
+}

package/dist/src/core/config-validate.js

@@ -328,6 +328,17 @@ function parsePatchLintBlock(rec) {
     if (checkJsExtraShim !== undefined) {
         out.checkJsExtraShim = parseShimPath(checkJsExtraShim, 'patchLint.checkJsExtraShim');
     }
+    const checkJsTestFiles = rec.raw('checkJsTestFiles');
+    if (checkJsTestFiles !== undefined) {
+        if (typeof checkJsTestFiles !== 'boolean') {
+            throw new ConfigError('Config field "patchLint.checkJsTestFiles" must be a boolean');
+        }
+        out.checkJsTestFiles = checkJsTestFiles;
+    }
+    const checkJsTestShim = rec.raw('checkJsTestShim');
+    if (checkJsTestShim !== undefined) {
+        out.checkJsTestShim = parseShimPath(checkJsTestShim, 'patchLint.checkJsTestShim');
+    }
     const rawColorAllowlist = rec.raw('rawColorAllowlist');
     if (rawColorAllowlist !== undefined) {
         if (!Array.isArray(rawColorAllowlist) ||
@@ -358,6 +369,12 @@ function parsePatchLintBlock(rec) {
     if (out.checkJsCompilerOptions !== undefined && out.checkJsStrict !== true) {
         throw new ConfigError('Config field "patchLint.checkJsCompilerOptions" requires "patchLint.checkJsStrict": true');
     }
+    if (out.checkJsTestFiles === true && out.checkJs !== true) {
+        throw new ConfigError('Config field "patchLint.checkJsTestFiles" requires "patchLint.checkJs": true');
+    }
+    if (out.checkJsTestShim !== undefined && out.checkJsTestFiles !== true) {
+        throw new ConfigError('Config field "patchLint.checkJsTestShim" requires "patchLint.checkJsTestFiles": true');
+    }
     return out;
 }
 /**

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

@@ -1,11 +1,15 @@
 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_CACHE_SCHEMA_VERSION = 2;
 export interface PerPatchLintCacheEntry {
     key: string;
     patchFilename: string;
     issues: PatchLintIssue[];
+    /** Issues dropped by the patch's lintIgnore waivers (FORGE G10). */
+    suppressed: PatchLintIssue[];
+    /** Non-binary diff line count measured by the cached lint run. */
+    lineCount: number;
     updatedAt: string;
 }
 export interface PerPatchLintCacheFile {
@@ -36,7 +40,13 @@ export declare function loadPerPatchLintCache(projectRoot: string): Promise<PerP
 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;
+/** Cached per-patch lint payload returned on a key match. */
+export interface CachedPerPatchLint {
+    issues: PatchLintIssue[];
+    suppressed: PatchLintIssue[];
+    lineCount: number;
+}
+/** Returns the cached lint payload for a patch when the stored key still matches. */
+export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string): CachedPerPatchLint | 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): void;

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

@@ -7,7 +7,11 @@ 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';
-export const LINT_CACHE_SCHEMA_VERSION = 1;
+// Schema 2 (FORGE G10): 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 (the F5-class hazard:
+// a cache hit must never surface LESS than a fresh lint).
+export const LINT_CACHE_SCHEMA_VERSION = 2;
 const LINT_IMPLEMENTATION_VERSION = 1;
 const LINT_CACHE_DIRNAME = 'lint-cache';
 const PER_PATCH_CACHE_FILENAME = 'per-patch-v1.json';
@@ -118,6 +122,8 @@ function isCacheEntry(value) {
     return (typeof entry.key === 'string' &&
         typeof entry.patchFilename === 'string' &&
         Array.isArray(entry.issues) &&
+        Array.isArray(entry.suppressed) &&
+        typeof entry.lineCount === 'number' &&
         typeof entry.updatedAt === 'string');
 }
 /** Loads the per-patch lint cache, treating missing or invalid files as empty. */
@@ -158,19 +164,25 @@ export async function savePerPatchLintCache(projectRoot, cache) {
 export async function clearPerPatchLintCache(projectRoot) {
     await writeJson(getPerPatchLintCachePath(projectRoot), createEmptyPerPatchLintCache());
 }
-/** Returns cached issues for a patch when the stored key still matches. */
+/** Returns the cached lint payload 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 }));
+    return {
+        issues: entry.issues.map((issue) => ({ ...issue })),
+        suppressed: entry.suppressed.map((issue) => ({ ...issue })),
+        lineCount: entry.lineCount,
+    };
 }
-/** Stores per-patch lint issues after a successful lint calculation. */
-export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues) {
+/** Stores the per-patch lint payload after a successful lint calculation. */
+export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues, suppressed, lineCount) {
     cache.entries[patchFilename] = {
         key,
         patchFilename,
         issues: issues.map((issue) => ({ ...issue })),
+        suppressed: suppressed.map((issue) => ({ ...issue })),
+        lineCount,
         updatedAt: new Date().toISOString(),
     };
 }

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

@@ -1,8 +1,8 @@
 import type { PatchCategory, PatchesManifest, PatchInfo, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type SupersedeCoverageDetail } from './patch-export-coverage.js';
-export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, type PatchCoverage, type SupersedeCoverageDetail, } from './patch-export-coverage.js';
-export { type ClearablePatchMetadataField, mutatePatchMetadata, type PatchMetadataMutation, type PatchMetadataMutationResult, updatePatchMetadata, } from './patch-export-metadata.js';
+export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, type SupersedeCoverageDetail, } from './patch-export-coverage.js';
+export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
 export { updatePatchAndMetadata } from './patch-export-update.js';
 /**
  * Gets the next patch number for a new patch.

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

@@ -10,7 +10,7 @@ import { findAllPatchesForFilesWithDetails, } from './patch-export-coverage.js';
 import { addPatchToManifest, loadPatchesManifestForWrite, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
 import { allocatePolicyOrder, enforcePatchPolicy } from './patch-policy.js';
 export { findAllPatchesForFiles, findAllPatchesForFilesWithDetails, findSupersededPatches, isPatchFullyCovered, } from './patch-export-coverage.js';
-export { mutatePatchMetadata, updatePatchMetadata, } from './patch-export-metadata.js';
+export { mutatePatchMetadata, updatePatchMetadata } from './patch-export-metadata.js';
 export { updatePatchAndMetadata } from './patch-export-update.js';
 /**
  * Gets the next patch number for a new patch.

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

@@ -63,7 +63,7 @@ export interface GroupedCheckJsResult {
  * @param mode - Strictness preset plus allowlisted compiler-option overrides
  * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode): Promise<GroupedCheckJsResult>;
+export declare function runCheckJsGrouped(repoDir: string, resolutionOwned: Set<string>, extraShimPath?: string, projectRoot?: string, mode?: CheckJsMode, builtinShimSuffix?: string): Promise<GroupedCheckJsResult>;
 /**
  * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
  * `reportScope` is supplied, only diagnostics from files in that set are
@@ -93,6 +93,24 @@ export declare function runCheckJs(repoDir: string, patchOwnedFiles: Set<string>
  *   not surface other patches' diagnostics)
  */
 export declare function invokePatchLintCheckJs(repoDir: string, patchOwnedFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string, reportScope?: ReadonlySet<string>): Promise<PatchLintIssue[]>;
+/**
+ * Runs the checkJs pass over patch-owned test `.js` files (FORGE G5,
+ * `patchLint.checkJsTestFiles`). Each test file gets its OWN small
+ * program — mochitest scripts share top-level scope only with their
+ * directory's `head*.js` helpers, so one multi-script program would emit
+ * false cross-file redeclaration errors — with roots = the test file plus
+ * any same-directory patch-owned `head*.js`, checked against the built-in
+ * Firefox shim + {@link TEST_HARNESS_SHIM} + the optional consumer
+ * `checkJsTestShim`. Only the target file's diagnostics are reported per
+ * program (head helpers report from their own program), and run-level
+ * errors are de-duplicated across programs.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param testFiles - Patch-owned test-script paths (repo-relative)
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
+ */
+export declare function runCheckJsTestFilesGrouped(repoDir: string, testFiles: Set<string>, patchLint: PatchLintConfig, projectRoot: string): Promise<GroupedCheckJsResult>;
 /**
  * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
  * checkJs program over `patchOwnedFiles` and returns its findings grouped by