@hominis/fireforge 0.40.0 → 0.41.0

package/dist/src/commands/re-export-drift.js

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Foreign-drift preview + `--refuse-foreign-drift` gate for `re-export`
+ * (FORGE J2).
+ *
+ * A scan-less re-export rebuilds each patch body as a whole-file
+ * `git diff HEAD` over the owned files — so a CONCURRENT session's
+ * uncommitted lines inside a file the patch already owns are silently
+ * absorbed into the refreshed body. The adjacency advisory
+ * (`re-export-adjacent.ts`) warns about unmanaged NEIGHBOUR files but is
+ * structurally blind to drift inside owned files. This module compares
+ * the old body against the refreshed body per file and reports the
+ * payload lines that are about to ENTER the body; under
+ * `--refuse-foreign-drift` the patch is skipped and the run exits
+ * non-zero, mirroring `--refuse-adjacent-unmanaged`.
+ *
+ * "Foreign" is decided by content, not authorship: re-export's legitimate
+ * job is capturing intentional engine edits, so the preview always prints
+ * and the hard stop is an explicit opt-in for multi-session checkouts.
+ * The comparison is offset-insensitive — per-file MULTISETS of `+`/`-`
+ * payload lines — because a refresh legitimately shifts hunk offsets and
+ * context without changing what the patch does.
+ */
+import { join } from 'node:path';
+import { parseDiffSections } from '../core/patch-parse.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { info, verbose, warn } from '../utils/logger.js';
+const MAX_HUNK_SUMMARIES_PER_FILE = 3;
+const MAX_FILES_REPORTED = 10;
+function collectPayloadByFile(body) {
+    const byFile = new Map();
+    for (const section of parseDiffSections(body)) {
+        const file = section.targetPath;
+        let payload = byFile.get(file);
+        if (!payload) {
+            payload = {
+                added: new Map(),
+                removed: new Map(),
+                binaryNewHash: undefined,
+                isBinary: false,
+                sections: [],
+            };
+            byFile.set(file, payload);
+        }
+        payload.sections.push(section);
+        if (section.isBinary) {
+            payload.isBinary = true;
+            payload.binaryNewHash = section.indexNewHash;
+            continue;
+        }
+        for (const hunk of section.hunks) {
+            for (const line of hunk.lines) {
+                if (line.startsWith('+')) {
+                    const text = line.slice(1);
+                    payload.added.set(text, (payload.added.get(text) ?? 0) + 1);
+                }
+                else if (line.startsWith('-')) {
+                    const text = line.slice(1);
+                    payload.removed.set(text, (payload.removed.get(text) ?? 0) + 1);
+                }
+            }
+        }
+    }
+    return byFile;
+}
+/** Multiset difference: occurrences of `next` not consumed by `previous`. */
+function multisetExcess(next, previous) {
+    const excess = new Map();
+    for (const [text, count] of next) {
+        const remaining = count - (previous.get(text) ?? 0);
+        if (remaining > 0)
+            excess.set(text, remaining);
+    }
+    return excess;
+}
+function summarizeForeignHunks(payload, foreignAdded, foreignRemoved) {
+    const summaries = [];
+    const addedBudget = new Map(foreignAdded);
+    const removedBudget = new Map(foreignRemoved);
+    for (const section of payload.sections) {
+        for (const hunk of section.hunks) {
+            let added = 0;
+            let removed = 0;
+            for (const line of hunk.lines) {
+                if (line.startsWith('+')) {
+                    const text = line.slice(1);
+                    const budget = addedBudget.get(text) ?? 0;
+                    if (budget > 0) {
+                        addedBudget.set(text, budget - 1);
+                        added++;
+                    }
+                }
+                else if (line.startsWith('-')) {
+                    const text = line.slice(1);
+                    const budget = removedBudget.get(text) ?? 0;
+                    if (budget > 0) {
+                        removedBudget.set(text, budget - 1);
+                        removed++;
+                    }
+                }
+            }
+            if (added > 0 || removed > 0) {
+                summaries.push(`@@ -${String(hunk.oldStart)},${String(hunk.oldCount)} +${String(hunk.newStart)},${String(hunk.newCount)} @@ (+${String(added)}/-${String(removed)})`);
+            }
+        }
+    }
+    return summaries;
+}
+function countExcess(excess) {
+    let total = 0;
+    for (const count of excess.values())
+        total += count;
+    return total;
+}
+/**
+ * Pure comparison: per owned file, which `+`/`-` payload lines the
+ * refreshed body carries that the old body did not. Files NOT in
+ * `previousFilesAffected` are skipped — those are intentional adoptions
+ * (`--scan`), not drift.
+ */
+export function computeForeignDrift(oldBody, newBody, previousFilesAffected) {
+    const owned = new Set(previousFilesAffected);
+    const oldByFile = collectPayloadByFile(oldBody);
+    const newByFile = collectPayloadByFile(newBody);
+    const drift = [];
+    for (const [file, next] of newByFile) {
+        if (!owned.has(file))
+            continue;
+        const previous = oldByFile.get(file);
+        if (next.isBinary || previous?.isBinary === true) {
+            const binaryChanged = next.binaryNewHash === undefined ||
+                previous?.binaryNewHash === undefined ||
+                !(next.binaryNewHash.startsWith(previous.binaryNewHash) ||
+                    previous.binaryNewHash.startsWith(next.binaryNewHash));
+            if (binaryChanged) {
+                drift.push({ file, addedLines: 0, removedLines: 0, hunkSummaries: [], binaryChanged });
+            }
+            continue;
+        }
+        const foreignAdded = multisetExcess(next.added, previous?.added ?? new Map());
+        const foreignRemoved = multisetExcess(next.removed, previous?.removed ?? new Map());
+        const addedLines = countExcess(foreignAdded);
+        const removedLines = countExcess(foreignRemoved);
+        if (addedLines === 0 && removedLines === 0)
+            continue;
+        drift.push({
+            file,
+            addedLines,
+            removedLines,
+            hunkSummaries: summarizeForeignHunks(next, foreignAdded, foreignRemoved).slice(0, MAX_HUNK_SUMMARIES_PER_FILE),
+            binaryChanged: false,
+        });
+    }
+    return drift;
+}
+/**
+ * Reads the old body, prints the always-on drift preview (including under
+ * dry-run and `--scan`), and — when `ctx.refuseForeignDrift` is set —
+ * records a refusal and returns `true` so the caller skips the write.
+ */
+export async function reportForeignDrift(args) {
+    const { patch, patchesDir, newDiffContent, ctx } = args;
+    const oldPath = join(patchesDir, patch.filename);
+    let oldBody;
+    try {
+        if (!(await pathExists(oldPath))) {
+            return refuseUnreadableBaseline(ctx, patch.filename, 'old patch body missing');
+        }
+        oldBody = await readText(oldPath);
+    }
+    catch (error) {
+        return refuseUnreadableBaseline(ctx, patch.filename, `old body unreadable (${toError(error).message})`);
+    }
+    const drift = computeForeignDrift(oldBody, newDiffContent, patch.filesAffected);
+    ctx.evaluationRuns += 1;
+    if (drift.length === 0)
+        return false;
+    const unexpected = drift.filter((d) => !ctx.expectedDriftFiles.has(d.file));
+    for (const entry of drift) {
+        if (ctx.expectedDriftFiles.has(entry.file))
+            ctx.expectedSeen.add(entry.file);
+    }
+    const totalLines = drift.reduce((sum, d) => sum + d.addedLines + d.removedLines, 0);
+    const lineNoun = totalLines === 1 ? 'line' : 'lines';
+    warn(`${patch.filename}: refreshed body absorbs ${String(totalLines)} ${lineNoun} not present in the old patch body (${String(drift.length)} file(s)):`);
+    for (const entry of drift.slice(0, MAX_FILES_REPORTED)) {
+        const expectedTag = ctx.expectedDriftFiles.has(entry.file) ? ' (expected via --expect)' : '';
+        if (entry.binaryChanged) {
+            info(`  ${entry.file}: binary content changed${expectedTag}`);
+            continue;
+        }
+        info(`  ${entry.file}: +${String(entry.addedLines)}/-${String(entry.removedLines)} newly captured line(s)${expectedTag}`);
+        for (const summary of entry.hunkSummaries) {
+            info(`    ${summary}`);
+        }
+    }
+    if (drift.length > MAX_FILES_REPORTED) {
+        info(`  +${String(drift.length - MAX_FILES_REPORTED)} more file(s)`);
+    }
+    if (ctx.refuseForeignDrift) {
+        if (unexpected.length === 0) {
+            info(`${patch.filename}: drift confined to --expect file(s); proceeding under --refuse-foreign-drift.`);
+            return false;
+        }
+        ctx.refusals.push({
+            patchFilename: patch.filename,
+            files: unexpected.map((d) => d.file),
+            reason: 'foreign-drift',
+        });
+        warn(`${patch.filename}: skipped (--refuse-foreign-drift).`);
+        return true;
+    }
+    warn('  If these are intentional engine edits, this is the normal re-export flow. ' +
+        'FireForge cannot infer authorship; if another session owns them, re-run with ' +
+        "--refuse-foreign-drift, or commit/stash that session's edits first.");
+    return false;
+}
+/**
+ * Fail-closed baseline handling (FORGE L6): a missing or unreadable old
+ * patch body means the drift comparison CANNOT run, so under
+ * `--refuse-foreign-drift` the patch is refused rather than written on the
+ * strength of a check that never happened. Without the flag this stays the
+ * historical advisory skip (the preview is best-effort there).
+ */
+function refuseUnreadableBaseline(ctx, patchFilename, detail) {
+    if (!ctx.refuseForeignDrift) {
+        verbose(`Skipping foreign-drift preview for ${patchFilename}: ${detail}`);
+        return false;
+    }
+    ctx.refusals.push({ patchFilename, files: [], reason: 'baseline-unreadable' });
+    warn(`${patchFilename}: skipped (--refuse-foreign-drift) — ${detail}; the drift comparison cannot run, refusing fail-closed.`);
+    return true;
+}

package/dist/src/commands/re-export-files.js

@@ -7,7 +7,7 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
 import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
@@ -73,7 +73,7 @@ async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedD
         return null;
     return {
         reason: `projected --files state introduces ${regressions.length} new cross-patch lint error(s)`,
-        details: regressions.map((i) => `[${i.check}] ${i.file}: ${i.message}`),
+        details: regressions.map(formatPatchLintIssue),
     };
 }
 /**
@@ -117,7 +117,9 @@ async function confirmFilesModeProjection(args) {
         for (const line of summary) {
             info(`  ${line}`);
         }
-        throw new InvalidArgumentError(`Refusing to re-export ${target.filename} with --files because it would remove ${removed.length} existing patch-owned file${removed.length === 1 ? '' : 's'}. Run again with --allow-shrink after reviewing the dry-run output.`, '--allow-shrink');
+        throw new InvalidArgumentError(`Refusing to re-export ${target.filename} with --files because it would remove ${removed.length} existing patch-owned file${removed.length === 1 ? '' : 's'}. Run again with --allow-shrink after reviewing the dry-run output. ` +
+            'If the intent is to move those files into their own patch instead, ' +
+            '"fireforge patch move-files <from> <to> --file <path> --create --order <n>" does the shrink and the new patch in one transaction.', '--allow-shrink');
     }
     return confirmDestructive({
         operation: 're-export-files',

package/dist/src/commands/re-export-lint.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Hoisted + cached lint context for `re-export` (FORGE J1).
+ *
+ * The per-patch loop used to rebuild the whole patch-queue context AND a
+ * fresh queue-wide checkJs TypeScript program for every patch — ~37 s of
+ * fixed setup per patch (measured on a 290-patch consumer queue), so an
+ * N-patch re-export cost N×37 s. This module:
+ *
+ * - builds the queue context and the {@link PerRunCheckJs} program
+ *   controller ONCE per invocation (`buildReExportLintContext`) and slices
+ *   per-patch findings out of it (the FORGE I3 shape `move-files`/`split`
+ *   already use, plus the program-level hoist `lint --per-patch` has);
+ * - reuses the existing per-patch lint RESULT cache
+ *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations —
+ *   re-export lints the identical input `lint --per-patch` does (the
+ *   fresh `git diff HEAD` of the owned files), and the key already
+ *   hashes engine HEAD, per-file content, patch body, config, shims, and
+ *   ownership, so a repeat single re-export is a warm hit (~4 s instead
+ *   of ~41 s). `--no-cache` opts out; run-level checkJs globals are
+ *   never cached (FORGE F5) and are emitted once per invocation;
+ * - keeps the in-memory queue context honest after each write
+ *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
+ *   against the just-refreshed body instead of the stale one.
+ */
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { type PerPatchLintCacheFile } from '../core/lint-cache.js';
+import { type PatchQueueContext } from '../core/patch-lint.js';
+import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type PerRunCheckJs } from './lint-per-run-checkjs.js';
+/** Per-invocation lint context, built once and threaded through the loop. */
+export interface ReExportLintContext {
+    projectRoot: string;
+    paths: ReturnType<typeof getProjectPaths>;
+    config: FireForgeConfig;
+    /** Whole-queue context, built WITH config so the forward-import hints
+     *  match `lint --per-patch` (FORGE F14); undefined when no patches dir. */
+    patchQueueCtx: PatchQueueContext | undefined;
+    /** Queue-wide checkJs controller; undefined when checkJs is off. */
+    checkJs: PerRunCheckJs | undefined;
+    /** Per-patch result cache; undefined under `--no-cache`. */
+    cache: PerPatchLintCacheFile | undefined;
+    engineHeadSha: string | undefined;
+    cacheDirty: boolean;
+    reusedCacheEntries: number;
+    /** Run-level checkJs globals are emitted once per invocation. */
+    globalsEmitted: boolean;
+}
+/** Builds the once-per-invocation lint context (FORGE J1). */
+export declare function buildReExportLintContext(projectRoot: string, paths: ReturnType<typeof getProjectPaths>, config: Awaited<ReturnType<typeof loadConfig>>, noCache: boolean): Promise<ReExportLintContext>;
+/** Fresh lint payload carried to the post-write cache store. */
+export interface ReExportLintResult {
+    issues: PatchLintIssue[];
+    suppressed: PatchLintIssue[];
+    lineCount: number;
+}
+/**
+ * Lints one re-exported patch body using the hoisted context: cache hit →
+ * replay the stored issues through the shared reporter (returns `null`);
+ * miss → lint with the queue-wide program's pre-attributed slices (or a
+ * per-patch build when the fresh diff creates files the hoisted program
+ * never saw — the `--scan` adoption case) and return the payload for
+ * {@link storeReExportLintResult}. Throws exactly like `runPatchLint` on
+ * errors (unless `skipLint`).
+ *
+ * The cache key is built over the PROJECTED metadata (current
+ * filesAffected, merged lintIgnore, effective tier) so `--tier` /
+ * `--lint-ignore` flags change the key. The entry itself is stored AFTER
+ * the body write (the key hashes the on-disk `.patch` file, which this
+ * very run is about to rewrite — a pre-write store could never match a
+ * later run).
+ */
+export declare function lintReExportedPatch(args: {
+    lintCtx: ReExportLintContext;
+    patch: PatchMetadata;
+    projectedMetadata: PatchMetadata;
+    existingFiles: string[];
+    diffContent: string;
+    skipLint?: boolean;
+    ignoreChecks?: ReadonlySet<string>;
+    patchTier?: 'branding';
+}): Promise<ReExportLintResult | null>;
+/**
+ * Stores a fresh lint result AFTER the body write, keying against the
+ * just-written `.patch` file and the refreshed queue context — the state
+ * a later identical invocation will observe (call
+ * {@link refreshQueueCtxEntry} first).
+ */
+export declare function storeReExportLintResult(lintCtx: ReExportLintContext, patchFilename: string, projectedMetadata: PatchMetadata, existingFiles: string[], result: ReExportLintResult): Promise<void>;
+/**
+ * Refreshes the in-memory queue entry for a just-rewritten patch so later
+ * iterations (and later cache keys) lint against the new body instead of
+ * the stale one. The on-disk write is the authority; this mirrors it.
+ */
+export declare function refreshQueueCtxEntry(lintCtx: ReExportLintContext, patchFilename: string, diffContent: string): void;
+/** Persists cache writes and reports reuse, once after the loop. */
+export declare function finishReExportLint(lintCtx: ReExportLintContext): Promise<void>;

package/dist/src/commands/re-export-lint.js

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Hoisted + cached lint context for `re-export` (FORGE J1).
+ *
+ * The per-patch loop used to rebuild the whole patch-queue context AND a
+ * fresh queue-wide checkJs TypeScript program for every patch — ~37 s of
+ * fixed setup per patch (measured on a 290-patch consumer queue), so an
+ * N-patch re-export cost N×37 s. This module:
+ *
+ * - builds the queue context and the {@link PerRunCheckJs} program
+ *   controller ONCE per invocation (`buildReExportLintContext`) and slices
+ *   per-patch findings out of it (the FORGE I3 shape `move-files`/`split`
+ *   already use, plus the program-level hoist `lint --per-patch` has);
+ * - reuses the existing per-patch lint RESULT cache
+ *   (`.fireforge/lint-cache/per-patch-v1.json`) across invocations —
+ *   re-export lints the identical input `lint --per-patch` does (the
+ *   fresh `git diff HEAD` of the owned files), and the key already
+ *   hashes engine HEAD, per-file content, patch body, config, shims, and
+ *   ownership, so a repeat single re-export is a warm hit (~4 s instead
+ *   of ~41 s). `--no-cache` opts out; run-level checkJs globals are
+ *   never cached (FORGE F5) and are emitted once per invocation;
+ * - keeps the in-memory queue context honest after each write
+ *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
+ *   against the just-refreshed body instead of the stale one.
+ */
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
+import { buildPatchQueueContext, countNonBinaryDiffLines, detectNewFilesInDiff, lintExportedPatch, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { invalidateNewFileCreatorsCache } from '../core/patch-lint-cross.js';
+import { extractAddedLinesPerFile } from '../core/patch-lint-diff.js';
+import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
+import { pathExists } from '../utils/fs.js';
+import { info } from '../utils/logger.js';
+import { reportPatchLintOutcome } from './export-shared.js';
+import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
+/** Builds the once-per-invocation lint context (FORGE J1). */
+export async function buildReExportLintContext(projectRoot, paths, config, noCache) {
+    const patchQueueCtx = (await pathExists(paths.patches))
+        ? await buildPatchQueueContext(paths.patches, config)
+        : undefined;
+    const checkJs = patchQueueCtx
+        ? buildPerRunCheckJs(projectRoot, paths, config, patchQueueCtx)
+        : undefined;
+    const cache = noCache ? undefined : await loadPerPatchLintCache(projectRoot);
+    const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
+    return {
+        projectRoot,
+        paths,
+        config,
+        patchQueueCtx,
+        checkJs,
+        cache,
+        engineHeadSha,
+        cacheDirty: false,
+        reusedCacheEntries: 0,
+        globalsEmitted: false,
+    };
+}
+/** The checkJs-relevant files this fresh diff creates. */
+function checkJsFilesInDiff(diffContent, checkJs) {
+    const files = new Set();
+    for (const f of detectNewFilesInDiff(diffContent)) {
+        if (checkJs.isRelevant(f))
+            files.add(f);
+    }
+    return files;
+}
+/**
+ * Lints one re-exported patch body using the hoisted context: cache hit →
+ * replay the stored issues through the shared reporter (returns `null`);
+ * miss → lint with the queue-wide program's pre-attributed slices (or a
+ * per-patch build when the fresh diff creates files the hoisted program
+ * never saw — the `--scan` adoption case) and return the payload for
+ * {@link storeReExportLintResult}. Throws exactly like `runPatchLint` on
+ * errors (unless `skipLint`).
+ *
+ * The cache key is built over the PROJECTED metadata (current
+ * filesAffected, merged lintIgnore, effective tier) so `--tier` /
+ * `--lint-ignore` flags change the key. The entry itself is stored AFTER
+ * the body write (the key hashes the on-disk `.patch` file, which this
+ * very run is about to rewrite — a pre-write store could never match a
+ * later run).
+ */
+export async function lintReExportedPatch(args) {
+    const { lintCtx, patch, projectedMetadata, existingFiles, diffContent } = args;
+    const { paths, config, patchQueueCtx, checkJs, cache } = lintCtx;
+    // Tier notice, identical to runPatchLint's head — surfaced on both the
+    // cached and fresh paths so the governing tier is never silent.
+    const tierDecision = resolvePatchSizeTier(existingFiles, args.patchTier);
+    if (tierDecision.tier === 'branding') {
+        info(tierDecision.source === 'explicit'
+            ? 'Lint: branding threshold tier applied via patches.json `tier: "branding"` opt-in.'
+            : 'Lint: branding threshold tier applied (patch is all under browser/branding/ plus registration siblings).');
+    }
+    // Run-level checkJs globals surface exactly once per invocation, never
+    // from the cache (FORGE F5). On an all-warm run this is a cheap probe,
+    // not a program build.
+    let globalIssues = [];
+    if (checkJs && !lintCtx.globalsEmitted) {
+        lintCtx.globalsEmitted = true;
+        globalIssues = await checkJs.getGlobal();
+    }
+    if (cache && patchQueueCtx) {
+        const cacheKey = await buildPerPatchLintCacheKey({
+            projectRoot: lintCtx.projectRoot,
+            engineDir: paths.engine,
+            patchesDir: paths.patches,
+            patch: projectedMetadata,
+            existingFiles,
+            config,
+            queueContext: patchQueueCtx,
+            ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
+        });
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
+        if (cached) {
+            lintCtx.reusedCacheEntries++;
+            reportPatchLintOutcome([...globalIssues, ...cached.issues], args.skipLint);
+            return null;
+        }
+    }
+    const lintOptions = {};
+    const suppressedIssues = [];
+    lintOptions.onSuppressed = (suppressed) => suppressedIssues.push(...suppressed);
+    if (checkJs) {
+        const created = checkJsFilesInDiff(diffContent, checkJs);
+        const allKnown = [...created].every((f) => checkJs.resolutionSet.has(f));
+        if (allKnown) {
+            // Slice this patch's findings out of the one queue-wide program.
+            lintOptions.precomputedCheckJs = await checkJs.sliceFor(created);
+        }
+        else {
+            // Fresh `--scan` adoption created checkJs-relevant files the hoisted
+            // program has never seen — fall back to a per-patch build with the
+            // usual report scope so nothing is silently unchecked (FORGE F5).
+            lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
+        }
+    }
+    else if (patchQueueCtx) {
+        lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
+    }
+    const issues = await lintExportedPatch(paths.engine, existingFiles, diffContent, config, patchQueueCtx, args.ignoreChecks, args.patchTier, lintOptions);
+    reportPatchLintOutcome([...globalIssues, ...issues], args.skipLint);
+    return {
+        issues,
+        suppressed: suppressedIssues,
+        lineCount: countNonBinaryDiffLines(diffContent).textLines,
+    };
+}
+/**
+ * Stores a fresh lint result AFTER the body write, keying against the
+ * just-written `.patch` file and the refreshed queue context — the state
+ * a later identical invocation will observe (call
+ * {@link refreshQueueCtxEntry} first).
+ */
+export async function storeReExportLintResult(lintCtx, patchFilename, projectedMetadata, existingFiles, result) {
+    const { cache, patchQueueCtx, paths, config } = lintCtx;
+    if (!cache || !patchQueueCtx)
+        return;
+    const cacheKey = await buildPerPatchLintCacheKey({
+        projectRoot: lintCtx.projectRoot,
+        engineDir: paths.engine,
+        patchesDir: paths.patches,
+        patch: projectedMetadata,
+        existingFiles,
+        config,
+        queueContext: patchQueueCtx,
+        ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
+    });
+    setCachedPerPatchLintIssues(cache, patchFilename, cacheKey, result.issues, result.suppressed, result.lineCount);
+    lintCtx.cacheDirty = true;
+}
+/**
+ * Refreshes the in-memory queue entry for a just-rewritten patch so later
+ * iterations (and later cache keys) lint against the new body instead of
+ * the stale one. The on-disk write is the authority; this mirrors it.
+ */
+export function refreshQueueCtxEntry(lintCtx, patchFilename, diffContent) {
+    const ctx = lintCtx.patchQueueCtx;
+    if (!ctx)
+        return;
+    const entry = ctx.entries.find((e) => e.filename === patchFilename);
+    if (!entry)
+        return;
+    entry.diff = diffContent;
+    const newFilePaths = detectNewFilesInDiff(diffContent);
+    const addedLinesByFile = extractAddedLinesPerFile(diffContent);
+    const newFiles = new Map();
+    const modifiedFileAdditions = new Map();
+    for (const [file, lines] of addedLinesByFile) {
+        if (newFilePaths.has(file)) {
+            // A created file's content IS its added lines.
+            newFiles.set(file, lines.join('\n'));
+        }
+        else {
+            modifiedFileAdditions.set(file, lines.join('\n'));
+        }
+    }
+    entry.newFiles = newFiles;
+    entry.modifiedFileAdditions = modifiedFileAdditions;
+    invalidateNewFileCreatorsCache(ctx);
+}
+/** Persists cache writes and reports reuse, once after the loop. */
+export async function finishReExportLint(lintCtx) {
+    if (lintCtx.cache && lintCtx.cacheDirty) {
+        await savePerPatchLintCache(lintCtx.projectRoot, lintCtx.cache);
+    }
+    if (lintCtx.reusedCacheEntries > 0) {
+        info(`Reused lint cache for ${lintCtx.reusedCacheEntries} patch${lintCtx.reusedCacheEntries === 1 ? '' : 'es'}.`);
+    }
+}

package/dist/src/commands/re-export-options.js

@@ -80,6 +80,14 @@ export function validateReExportOptionCombinations(patches, options) {
     if (options.refuseAdjacentUnmanaged === true && (options.scan || options.files !== undefined)) {
         throw new InvalidArgumentError('--refuse-adjacent-unmanaged applies to the scan-less path only and cannot be combined with --scan or --files (those set filesAffected explicitly).', '--refuse-adjacent-unmanaged');
     }
+    if (options.refuseForeignDrift === true && (options.scan || options.files !== undefined)) {
+        throw new InvalidArgumentError('--refuse-foreign-drift applies to the scan-less path only and cannot be combined with --scan or --files (those explicitly capture the current engine state).', '--refuse-foreign-drift');
+    }
+    if (options.expect !== undefined &&
+        options.expect.length > 0 &&
+        options.refuseForeignDrift !== true) {
+        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
+    }
     const usingTierFlag = options.tier !== undefined;
     const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
     if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {

package/dist/src/commands/re-export-register.d.ts

@@ -0,0 +1,18 @@
+/**
+ * CLI registration for `fireforge re-export`.
+ *
+ * Split out of `re-export.ts` in 0.41.0. That file was the only one in `src/`
+ * carrying a file-level `eslint-disable max-lines` — it measured 526 against
+ * the 500 cap with the rule suppressed — and its own suppression comment named
+ * this block as the obvious thing to move ("splitting register plumbing is
+ * unrelated to this fix"). Moving it drops the file under the cap and removes
+ * the suppression.
+ *
+ * §7 of the quality survey forbids folding `re-export-files.ts` back INTO the
+ * orchestrator; this splits in the other direction, matching the existing
+ * `re-export-scan.ts` / `re-export-options.ts` boundary.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+/** Registers the re-export command on the CLI program. */
+export declare function registerReExport(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/re-export-register.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * CLI registration for `fireforge re-export`.
+ *
+ * Split out of `re-export.ts` in 0.41.0. That file was the only one in `src/`
+ * carrying a file-level `eslint-disable max-lines` — it measured 526 against
+ * the 500 cap with the rule suppressed — and its own suppression comment named
+ * this block as the obvious thing to move ("splitting register plumbing is
+ * unrelated to this fix"). Moving it drops the file under the cap and removes
+ * the suppression.
+ *
+ * §7 of the quality survey forbids folding `re-export-files.ts` back INTO the
+ * orchestrator; this splits in the other direction, matching the existing
+ * `re-export-scan.ts` / `re-export-options.ts` boundary.
+ */
+import { Command, Option } from 'commander';
+import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
+import { reExportCommand } from './re-export.js';
+/** Registers the re-export command on the CLI program. */
+export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
+    const reExport = program
+        .command('re-export [patches...]')
+        .description('Refresh existing patch bodies (and filesAffected with --scan) from the current engine ' +
+        'state. Does NOT change sourceVersion/sourceProduct by default — use --stamp or run ' +
+        'rebase for source metadata stamping.')
+        .option('-a, --all', 'Re-export all patches')
+        .option('-s, --scan', 'Scan directories for new/removed files and update filesAffected')
+        .option('--scan-file <path>', 'With --scan, add this explicit engine-relative file to one target patch without collecting adjacent files. Repeatable.', ...stringListOption())
+        .option('--scan-files <manifest>', 'With --scan, bulk-assign generated files from a JSON manifest: {"assignments":[{"patch":"002-name.patch","files":["path"]}]}. Selects patches from the manifest.')
+        .option('--files <paths>', 'Restrict the re-exported filesAffected to this comma-separated list (single target patch only)', (value) => value
+        .split(',')
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0))
+        .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Mutually exclusive with --scan and --files.')
+        .option('--refuse-foreign-drift', "Refuse a scan-less re-export (non-zero exit, patch not written) when the refreshed body would absorb engine lines not present in the old patch body — protects multi-session checkouts from silently capturing another session's uncommitted edits. Mutually exclusive with --scan and --files.")
+        .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable.", ...stringListOption())
+        .option('--dry-run', 'Show what would change without writing')
+        .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
+        .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')
+        .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
+        .option('--allow-shrink', 'Allow --files to remove paths currently owned by the patch. Required before --yes can bypass the shrink confirmation.')
+        .option('-y, --yes', 'Skip confirmation prompts (required for non-TTY destructive writes)')
+        .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
+        .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
+        .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
+        .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', ...stringListOption());
+    addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
+        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, ...rest } = options;
+        const projectRoot = getProjectRoot();
+        await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
+            ...pickDefined(rest),
+            ...(scanFile !== undefined && scanFile.length > 0 ? { scanFiles: scanFile } : {}),
+            ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
+            ...(tier !== undefined ? { tier: tier } : {}),
+            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
+            ...(expect !== undefined && expect.length > 0 ? { expect } : {}),
+            ...(cache === false ? { noCache: true } : {}),
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+    }));
+}