@hominis/fireforge 0.49.2 → 0.50.0

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

@@ -9,7 +9,7 @@
  * (`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
+ * payload lines that are about to enter or leave the body. Under
  * `--refuse-foreign-drift` the patch is skipped and the run exits
  * non-zero, mirroring `--refuse-adjacent-unmanaged`.
  *
@@ -74,8 +74,15 @@ function multisetExcess(next, previous) {
     }
     return excess;
 }
-function summarizeForeignHunks(payload, foreignAdded, foreignRemoved) {
+/**
+ * Summarizes the hunks of `payload` that carry the budgeted `+`/`-` lines.
+ * `describe` renders the per-hunk counts, so the old body's dropped lines
+ * read in the same engine-edit direction as the new body's absorbed ones.
+ */
+function summarizeForeignHunks(payload, foreignAdded, foreignRemoved, describe) {
     const summaries = [];
+    if (payload === undefined)
+        return summaries;
     const addedBudget = new Map(foreignAdded);
     const removedBudget = new Map(foreignRemoved);
     for (const section of payload.sections) {
@@ -101,7 +108,7 @@ function summarizeForeignHunks(payload, foreignAdded, foreignRemoved) {
                 }
             }
             if (added > 0 || removed > 0) {
-                summaries.push(`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@ (+${added}/-${removed})`);
+                summaries.push(`@@ -${hunk.oldStart},${hunk.oldCount} +${hunk.newStart},${hunk.newCount} @@ ${describe(added, removed)}`);
             }
         }
     }
@@ -113,47 +120,71 @@ function countExcess(excess) {
         total += count;
     return total;
 }
+const EMPTY_PAYLOAD_LINES = new Map();
 /**
  * Pure comparison: per owned file, which `+`/`-` payload lines the
- * refreshed body carries that the old body did not. Files not in
- * `previousFilesAffected` are skipped, since those are intentional
- * adoptions (`--scan`) rather than drift.
+ * refreshed body carries that the old body did not, and which the old body
+ * carried that the refreshed one dropped. Both directions are drift: a
+ * concurrent session deleting a line the patch added changes the patch as
+ * surely as one adding a line, and a belt that only saw absorbed lines let
+ * such a deletion through silently. Files not in `previousFilesAffected`
+ * are skipped, since those are intentional adoptions (`--scan`) or
+ * retirements (`--expect-removed`) rather than 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) {
+    // New-body order first, then files only the old body carried.
+    const files = new Set([...newByFile.keys(), ...oldByFile.keys()]);
+    for (const file of files) {
         if (!owned.has(file))
             continue;
+        const next = newByFile.get(file);
         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 });
+        if (next?.isBinary === true || previous?.isBinary === true) {
+            if (binaryContentChanged(next, previous)) {
+                drift.push({
+                    file,
+                    addedLines: 0,
+                    removedLines: 0,
+                    hunkSummaries: [],
+                    binaryChanged: true,
+                });
             }
             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);
+        const absorbedAdded = multisetExcess(next?.added ?? EMPTY_PAYLOAD_LINES, previous?.added ?? EMPTY_PAYLOAD_LINES);
+        const absorbedRemoved = multisetExcess(next?.removed ?? EMPTY_PAYLOAD_LINES, previous?.removed ?? EMPTY_PAYLOAD_LINES);
+        const droppedAdded = multisetExcess(previous?.added ?? EMPTY_PAYLOAD_LINES, next?.added ?? EMPTY_PAYLOAD_LINES);
+        const droppedRemoved = multisetExcess(previous?.removed ?? EMPTY_PAYLOAD_LINES, next?.removed ?? EMPTY_PAYLOAD_LINES);
+        const addedLines = countExcess(absorbedAdded) + countExcess(droppedRemoved);
+        const removedLines = countExcess(absorbedRemoved) + countExcess(droppedAdded);
         if (addedLines === 0 && removedLines === 0)
             continue;
         drift.push({
             file,
             addedLines,
             removedLines,
-            hunkSummaries: summarizeForeignHunks(next, foreignAdded, foreignRemoved).slice(0, MAX_HUNK_SUMMARIES_PER_FILE),
+            hunkSummaries: [
+                ...summarizeForeignHunks(next, absorbedAdded, absorbedRemoved, (plus, minus) => `(+${plus}/-${minus})`),
+                // A dropped `+` line is one the engine lost; a dropped `-` line is an
+                // upstream line the engine has back.
+                ...summarizeForeignHunks(previous, droppedAdded, droppedRemoved, (plus, minus) => `in the old body, dropped (+${minus}/-${plus})`),
+            ].slice(0, MAX_HUNK_SUMMARIES_PER_FILE),
             binaryChanged: false,
         });
     }
     return drift;
 }
+/** True when a binary section appeared, vanished, or its new-side blob hash moved. */
+function binaryContentChanged(next, previous) {
+    if (next?.binaryNewHash === undefined || previous?.binaryNewHash === undefined)
+        return true;
+    return !(next.binaryNewHash.startsWith(previous.binaryNewHash) ||
+        previous.binaryNewHash.startsWith(next.binaryNewHash));
+}
 /**
  * Reads the old body, prints the always-on drift preview (including under
  * dry-run and `--scan`), and, when `ctx.refuseForeignDrift` is set,
@@ -161,6 +192,10 @@ export function computeForeignDrift(oldBody, newBody, previousFilesAffected) {
  */
 export async function reportForeignDrift(args) {
     const { patch, patchesDir, engineDir, newDiffContent, ctx } = args;
+    for (const file of args.adoptedFiles ?? []) {
+        if (ctx.expectedDriftFiles.has(file))
+            ctx.expectedSeen.add(file);
+    }
     const oldPath = join(patchesDir, patch.filename);
     let oldBody;
     try {
@@ -172,7 +207,7 @@ export async function reportForeignDrift(args) {
     catch (error) {
         return refuseUnreadableBaseline(ctx, patch.filename, `old body unreadable (${toError(error).message})`);
     }
-    const drift = computeForeignDrift(oldBody, newDiffContent, patch.filesAffected);
+    const drift = computeForeignDrift(oldBody, newDiffContent, args.ownedFiles ?? patch.filesAffected);
     ctx.evaluationRuns += 1;
     if (drift.length === 0)
         return false;
@@ -184,7 +219,7 @@ export async function reportForeignDrift(args) {
     const recentlyEdited = await findFilesEditedSinceLastExport(engineDir, oldPath, drift.map((d) => d.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 ${totalLines} ${lineNoun} not present in the old patch body (${drift.length} file(s)):`);
+    warn(`${patch.filename}: refreshed body changes ${totalLines} ${lineNoun} against the old patch body (${drift.length} file(s)):`);
     for (const entry of drift.slice(0, MAX_FILES_REPORTED)) {
         const expectedTag = ctx.expectedDriftFiles.has(entry.file) ? ' (expected via --expect)' : '';
         const authorshipTag = recentlyEdited.has(entry.file)
@@ -194,7 +229,7 @@ export async function reportForeignDrift(args) {
             info(`  ${entry.file}: binary content changed${expectedTag}${authorshipTag}`);
             continue;
         }
-        info(`  ${entry.file}: +${entry.addedLines}/-${entry.removedLines} newly captured line(s)${expectedTag}${authorshipTag}`);
+        info(`  ${entry.file}: +${entry.addedLines} added / -${entry.removedLines} removed line(s)${expectedTag}${authorshipTag}`);
         for (const summary of entry.hunkSummaries) {
             info(`    ${summary}`);
         }
@@ -274,31 +309,24 @@ function refuseUnreadableBaseline(ctx, patchFilename, detail) {
 /**
  * States, verbatim in the notice, what the `--expect` whitelist is compared
  * against and when. This notice is the only feedback an operator gets that
- * the drift belt looked at the files they named, and a downstream report
- * showed the previous copy actively misleading: it warned "showed no drift"
- * over an edit that was captured correctly, and none of the causes it named
- * held, so the operator's only recourse was `grep -c` on the written body.
- *
- * The measurement, stated exactly:
+ * the drift belt looked at the files they named, so it has to describe the
+ * measurement exactly:
  *
  *  - Compared: for each file already in the patch's `filesAffected`, the
  *    `+`/`-` payload lines the refreshed body carries that the old patch
- *    body did not (`computeForeignDrift`). It is a content comparison, and
- *    it is one-directional: excess in the new body only.
+ *    body did not, and the ones the old body carried that the refreshed body
+ *    dropped (`computeForeignDrift`). It is a content comparison in both
+ *    directions, so a deletion-only edit is drift too.
  *  - When: per patch, on the body about to be written, before the write.
  *    Never against post-write state.
  *
- * The one-directional half is what the earlier copy hid, and it is the
- * cause the report's first shape actually hit: deleting a line from an
- * engine file makes the refreshed body drop that file's `+` line. Nothing
- * is absorbed, so there is no drift to see. The belt exists to catch a
- * concurrent session's edits being silently swallowed into a body, not
- * every difference between two bodies. Stating that is the fix. Widening
- * the comparison would turn every ordinary line removal into a refusal.
+ * An earlier copy compared one direction only, so a correctly captured
+ * deletion read as an `--expect` that matched nothing, and a peer's
+ * deletion in a file outside `--expect` passed the belt silently.
  */
 const EXPECT_MEASUREMENT_NOTE = '--expect is evaluated against CONTENT, before the write: for each file already in the ' +
-    "patch's filesAffected, the payload lines the refreshed body carries that the old patch " +
-    'body did not. It never looks at post-write state.';
+    "patch's filesAffected, the payload lines the refreshed body adds or drops against the old " +
+    'patch body. It never looks at post-write state.';
 /**
  * Names `--expect` paths that never drifted this run. A typo'd
  * `--expect` path silently degrades the flag back to refusing the slice it
@@ -318,17 +346,13 @@ export function warnUnseenExpectedDrift(driftCtx) {
         `${unseen.join(', ')}.\n` +
         `${EXPECT_MEASUREMENT_NOTE}\n` +
         'Causes, in rough order of likelihood:\n' +
-        '  1. Your edit only REMOVED lines from the body (you deleted a line from the engine ' +
-        'file). The comparison is one-directional — it reports lines ABSORBED into the body — ' +
-        'so a correctly captured deletion is not drift and never will be. Confirm the capture ' +
-        'with "grep -c" on the written patch body.\n' +
-        "  2. A typo in the path, or a path not in the patch's filesAffected (files adopted " +
-        'this run via --scan/--scan-file are excluded from the comparison by design).\n' +
-        '  3. Adoption already captured it: a "re-export <p> --scan --scan-file <f>" run also ' +
+        "  1. A typo in the path, or a path in none of the selected patches' filesAffected and " +
+        'not adopted by this run.\n' +
+        '  2. Adoption already captured it: a "re-export <p> --scan --scan-file <f>" run also ' +
         "captures that patch's other drifted files, so a scan-less re-export afterwards " +
-        'legitimately sees nothing left to absorb. Informational — a chain that treats this ' +
+        'legitimately sees nothing left to change. Informational — a chain that treats this ' +
         'warning as an error will false-red on it.\n' +
-        '  4. The slice was already captured by an earlier export in this session.\n' +
-        '  5. The engine content already matches the patch body — a concurrent session may have ' +
+        '  3. The slice was already captured by an earlier export in this session.\n' +
+        '  4. The engine content already matches the patch body — a concurrent session may have ' +
         'exported the same change, so the drift converged before this run looked.');
 }

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

@@ -7,6 +7,7 @@ import { listTrackedInHead } from '../core/git-file-ops.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
 import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildLintIgnoreChecks, mergeLintIgnoreIds } from '../core/patch-lint-ignore.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
@@ -25,10 +26,8 @@ import { projectEntryBody } from './patch/entry-projection.js';
  * so the caller can drop the field rather than write an empty array.
  */
 function resolveEffectiveTierAndLintIgnore(target, options) {
-    const existingIgnoreSet = new Set(target.lintIgnore ?? []);
     const flagIgnoreSet = new Set(options.lintIgnore ?? []);
-    const mergedIgnoreSet = new Set([...existingIgnoreSet, ...flagIgnoreSet]);
-    const effectiveLintIgnore = mergedIgnoreSet.size > 0 ? [...mergedIgnoreSet] : undefined;
+    const effectiveLintIgnore = mergeLintIgnoreIds(target.lintIgnore, [...flagIgnoreSet]);
     const effectiveTier = options.tier ?? target.tier;
     return { effectiveTier, effectiveLintIgnore, flagIgnoreSet };
 }
@@ -39,8 +38,10 @@ function resolveEffectiveTierAndLintIgnore(target, options) {
  * shrink. Pre-existing cross-patch errors are surfaced as a non-blocking
  * warning so the user does not walk away thinking the queue is clean.
  */
-async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff) {
-    const baseCtx = await buildPatchQueueContext(patchesDir);
+async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff, config) {
+    // The config threads `patchLint.forwardRegistration` through, so a forward
+    // jar.mn registration is judged the way `lint --per-patch` judges it.
+    const baseCtx = await buildPatchQueueContext(patchesDir, config);
     const projection = projectEntryBody(projectedDiff);
     const projectedEntries = baseCtx.entries.map((entry) => {
         if (entry.filename !== targetFilename)
@@ -48,7 +49,7 @@ async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedD
         return { ...entry, ...projection };
     });
     const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ ...baseCtx, entries: projectedEntries }).filter((i) => i.severity === 'error');
     const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
     if (baselineIssues.length > 0 && regressions.length === 0) {
         warn(`Note: projected queue still has ${baselineIssues.length} pre-existing ` +
@@ -223,7 +224,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     // `--tier` and `--lint-ignore` participate too, with append/union
     // semantics on the lint-ignore list.
     const { effectiveTier, effectiveLintIgnore, flagIgnoreSet } = resolveEffectiveTierAndLintIgnore(target, options);
-    const ignoreChecks = effectiveLintIgnore ? new Set(effectiveLintIgnore) : undefined;
+    const ignoreChecks = buildLintIgnoreChecks(effectiveLintIgnore);
     const patchQueueCtx = (await pathExists(paths.patches))
         ? await buildPatchQueueContext(paths.patches)
         : undefined;
@@ -237,7 +238,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
         ignoreChecks,
         patchTier: effectiveTier,
     });
-    const conflicts = await runProjectedCrossPatchLint(paths.patches, target.filename, projectedDiff);
+    const conflicts = await runProjectedCrossPatchLint(paths.patches, target.filename, projectedDiff, config);
     const filesUpdates = buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveLintIgnore, flagIgnoreSet);
     const manifest = await loadPatchesManifest(paths.patches);
     if (manifest) {
@@ -246,6 +247,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             manifest: buildProjectedManifest(manifest, manifest.patches.map((entry) => entry.filename === target.filename ? { ...entry, ...filesUpdates } : entry)),
             command: 're-export --files',
             forceUnsafe: options.forceUnsafe === true,
+            scope: [target.filename],
         });
     }
     const decision = await confirmFilesModeProjection({
@@ -297,6 +299,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
             config,
             command: 're-export --files',
             forceUnsafe: options.forceUnsafe === true,
+            scope: [target.filename],
         },
     });
     success(`Re-exported ${target.filename}`);

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

@@ -21,6 +21,7 @@
  */
 import { type PatchQueueContext } from '../core/patch-lint.js';
 import { type PerPatchLintCacheFile } from '../core/patch-lint-cache.js';
+import { type LintIgnoreChecks } from '../core/patch-lint-ignore.js';
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
 import { type PerRunCheckJs } from './lint-per-run-checkjs.js';
@@ -92,7 +93,7 @@ export declare function lintReExportedPatch(args: {
     existingFiles: string[];
     diffContent: string;
     skipLint?: boolean;
-    ignoreChecks?: ReadonlySet<string>;
+    ignoreChecks?: LintIgnoreChecks;
     patchTier?: 'branding';
 }): Promise<ReExportLintResult | null>;
 /**

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

@@ -20,18 +20,20 @@
  *   (`refreshQueueCtxEntry`), so later iterations of an `--all` run lint
  *   against the just-refreshed body instead of the stale one.
  */
-import { buildPatchQueueContext, countNonBinaryDiffLines, detectNewFilesInDiff, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintExportedPatch, lintPatchQueue, measurePatchSize, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/patch-lint-cache.js';
 import { invalidateNewFileCreatorsCache } from '../core/patch-lint-cross.js';
+import { lintIgnoreCacheTokens } from '../core/patch-lint-ignore.js';
 import { resolvePatchOwnedSysMjs } from '../core/patch-lint-ownership.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { GeneralError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
 import { reportPatchLintOutcome } from './export-shared.js';
+import { formatForwardImportRemedy } from './forward-import-remedy.js';
 import { buildPerRunCheckJs } from './lint-per-run-checkjs.js';
 import { projectEntryBody } from './patch/entry-projection.js';
-import { formatForwardImportRemedy } from './re-export-scan.js';
+import { categoryOf, manifestFromQueue } from './re-export-scan.js';
 /**
  * Builds the once-per-invocation lint context.
  *
@@ -135,7 +137,7 @@ export async function lintReExportedPatch(args) {
             queueContext: patchQueueCtx,
             ...(lintCtx.engineHeadSha === undefined ? {} : { engineHeadSha: lintCtx.engineHeadSha }),
         });
-        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, args.ignoreChecks);
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey, lintIgnoreCacheTokens(args.ignoreChecks));
         if (cached) {
             lintCtx.reusedCacheEntries++;
             reportPatchLintOutcome([...globalIssues, ...cached.issues], args.skipLint);
@@ -167,8 +169,10 @@ export async function lintReExportedPatch(args) {
     else if (patchQueueCtx) {
         lintOptions.checkJsReportScope = resolvePatchOwnedSysMjs(detectNewFilesInDiff(diffContent));
     }
+    const patchSize = await measurePatchSize(paths.engine, diffContent, existingFiles, config);
     const issues = await lintExportedPatch(paths.engine, existingFiles, diffContent, config, {
         ...lintOptions,
+        patchSizeMeasurement: patchSize,
         ...(patchQueueCtx ? { patchQueueCtx } : {}),
         ...(args.ignoreChecks ? { ignoreChecks: args.ignoreChecks } : {}),
         ...(args.patchTier ? { patchTier: args.patchTier } : {}),
@@ -177,8 +181,8 @@ export async function lintReExportedPatch(args) {
     return {
         issues,
         suppressed: suppressedIssues,
-        lineCount: countNonBinaryDiffLines(diffContent).textLines,
-        lintIgnore: [...(args.ignoreChecks ?? [])],
+        lineCount: patchSize.lines,
+        lintIgnore: lintIgnoreCacheTokens(args.ignoreChecks),
     };
 }
 /**
@@ -236,10 +240,11 @@ export function assertRefreshedBodyHasNoNewQueueErrors(args) {
     const projectedEntries = ctx.entries.map((entry) => entry.filename === patchFilename ? { ...entry, ...projection } : entry);
     const isError = (issue) => issue.severity === 'error';
     const baseline = lintPatchQueue(ctx).filter(isError);
-    const projected = lintPatchQueue({
-        entries: projectedEntries,
-        ...(ctx.patchPolicy ? { patchPolicy: ctx.patchPolicy } : {}),
-    }).filter(isError);
+    // The whole context carries over (patchPolicy and the
+    // `patchLint.forwardRegistration` scope): dropping the scope here let a
+    // forward jar.mn registration pass this gate and surface only in the
+    // later queue audit, separately from the forward import it packages.
+    const projected = lintPatchQueue({ ...ctx, entries: projectedEntries }).filter(isError);
     const regressions = computeProjectedLintRegressions(baseline, projected);
     if (regressions.length === 0) {
         if (baseline.length > 0 && !lintCtx.queueBaselineWarned) {
@@ -253,7 +258,15 @@ export function assertRefreshedBodyHasNoNewQueueErrors(args) {
     const hasForwardImport = regressions.some((issue) => issue.check === 'forward-import');
     const message = `Refusing to re-export ${patchFilename} because the refreshed body introduces ` +
         `${regressions.length} new cross-patch lint error${regressions.length === 1 ? '' : 's'}:\n${details}` +
-        (hasForwardImport ? `\n${formatForwardImportRemedy('re-running the re-export')}` : '');
+        (hasForwardImport
+            ? `\n${formatForwardImportRemedy({
+                reRunHint: 're-running the re-export',
+                issues: regressions,
+                manifest: manifestFromQueue(ctx),
+                config: lintCtx.config,
+                ...categoryOf(ctx, patchFilename),
+            })}`
+            : '');
     if (forceUnsafe) {
         warn(message);
         warn('Proceeding because --force-unsafe was provided.');

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { InvalidArgumentError } from '../errors/base.js';
 import { info } from '../utils/logger.js';
+import { validateScanFileOwners } from './re-export-scan-owner.js';
 /**
  * Heuristic for `--files` positional folding: an extra positional that
  * contains a path separator and is not a `.patch` filename is an engine
@@ -62,6 +63,39 @@ function validateWhitelistFlagDependencies(options) {
         options.refuseAdjacentUnmanaged !== true) {
         throw new InvalidArgumentError('--expect-unmanaged names approved exceptions to --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop --expect-unmanaged.', '--expect-unmanaged');
     }
+    for (const [flag, values] of [
+        ['--expect-new', options.expectNew],
+        ['--adjacent-ignore', options.adjacentIgnore],
+    ]) {
+        if (values !== undefined && values.length > 0 && options.refuseAdjacentUnmanaged !== true) {
+            throw new InvalidArgumentError(`${flag} relaxes --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop ${flag}.`, flag);
+        }
+    }
+    if (options.adjacentIgnore?.some((entry) => entry.includes('**'))) {
+        throw new InvalidArgumentError('--adjacent-ignore takes a path or a glob whose * stays within one path segment; ** is refused, because a subtree carve-out is how a reviewed exception becomes a blanket one.', '--adjacent-ignore');
+    }
+}
+/**
+ * Refuses a path-valued flag whose value starts with `-`. Commander hands a
+ * required option value whatever follows it, so a list that ended early
+ * (`--expect-unmanaged --dry-run`) silently turned the next flag into a path
+ * and the dry run into a write. No engine path starts with a dash.
+ */
+function validatePathFlagValues(options) {
+    for (const [flag, values] of [
+        ['--expect', options.expect],
+        ['--expect-unmanaged', options.expectUnmanaged],
+        ['--expect-new', options.expectNew],
+        ['--expect-removed', options.expectRemoved],
+        ['--adjacent-ignore', options.adjacentIgnore],
+        ['--scan-file', options.scanFiles],
+    ]) {
+        const swallowed = (values ?? []).filter((value) => value.trim().startsWith('-'));
+        if (swallowed.length > 0) {
+            throw new InvalidArgumentError(`${flag} was given ${swallowed.map((value) => `"${value}"`).join(', ')}, which is a flag, not an engine path: ` +
+                `the ${flag} before it had no value, so it took the next argument. Give every ${flag} a path.`, flag);
+        }
+    }
 }
 function validateExpectedRemovalUsage(patches, options) {
     if (options.expectRemoved?.length &&
@@ -71,6 +105,9 @@ function validateExpectedRemovalUsage(patches, options) {
 }
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
+    // First: a swallowed flag would otherwise surface as whichever
+    // combination error it happens to trip, naming the wrong problem.
+    validatePathFlagValues(options);
     validateExpectedRemovalUsage(patches, options);
     if (options.files !== undefined) {
         if (options.all || options.scan) {
@@ -91,9 +128,10 @@ export function validateReExportOptionCombinations(patches, options) {
         if (options.scanFilesManifest !== undefined) {
             throw new InvalidArgumentError('--scan-file cannot be combined with --scan-files.', '--scan-file');
         }
-        if (options.all || patches.length !== 1) {
-            throw new InvalidArgumentError('--scan-file operates on exactly one target patch. Pass a single patch identifier.', '--scan-file');
+        if (options.all) {
+            throw new InvalidArgumentError('--scan-file cannot be combined with --all. Pass the target patch identifiers.', '--scan-file');
         }
+        validateScanFileOwners(patches, options.scanFiles);
     }
     if (options.scanFilesManifest !== undefined) {
         if (!options.scan)
@@ -105,8 +143,11 @@ 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');
+    // Beside --scan the belt covers the files each patch already owns; the
+    // files a scan adopts are the run's stated intent. --files replaces the
+    // file list outright, so there is no owned set left to guard.
+    if (options.refuseForeignDrift === true && options.files !== undefined) {
+        throw new InvalidArgumentError('--refuse-foreign-drift cannot be combined with --files (it sets filesAffected explicitly and captures the current engine state).', '--refuse-foreign-drift');
     }
     validateWhitelistFlagDependencies(options);
     const usingTierFlag = options.tier !== undefined;

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

@@ -0,0 +1,23 @@
+import type { ReExportOptions } from '../types/commands/index.js';
+/**
+ * Reads a path list file: one engine-relative path per line, blank lines
+ * and `#` comment lines ignored. Backs `--expect-from`, which exists because
+ * a list held in one shell variable reaches the CLI as one argument under
+ * zsh, and splitting it by hand left every path after the first as a
+ * positional patch name.
+ *
+ * @param file - The list file, relative to the working directory
+ * @param flag - Flag name for error messages
+ */
+export declare function readPathListFile(file: string, flag: string): Promise<string[]>;
+/**
+ * Runs every lock-free argument check: empty or unknown patch names
+ * (naming an engine file passed by mistake), option combinations, path
+ * flag values that are flags, and path flag values that name no changed
+ * file. Throws the refusal the locked run would have thrown, only sooner.
+ *
+ * @param projectRoot - Project root
+ * @param patches - Positional patch arguments as given
+ * @param options - Options as the command layer builds them
+ */
+export declare function preflightReExportArguments(projectRoot: string, patches: readonly string[], options: ReExportOptions): Promise<void>;