@hominis/fireforge 0.49.2 → 0.50.0

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

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Argument checks `fireforge re-export` runs before it queues for the
+ * engine session lock.
+ *
+ * Under contention the lock wait runs to many minutes, and an argument the
+ * run was always going to refuse (an empty patch name from an unquoted
+ * `"$@"`, a changed-file path passed as a positional, a path flag that
+ * swallowed the next flag) used to be reported only after that wait. These
+ * checks read the manifest and a path-scoped `git status` without the lock.
+ * The command repeats its own resolution under the lock, so a manifest that
+ * changes in between is still read fresh there.
+ */
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { getProjectPaths } from '../core/config.js';
+import { isGitRepository } from '../core/git.js';
+import { chunkPathspecs } from '../core/git-base.js';
+import { getDirtyFiles } from '../core/git-status.js';
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
+import { loadPatchesManifest, resolvePatchIdentifier } from '../core/patch-manifest.js';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { normalizeReExportFilesPositionals, validateReExportOptionCombinations, } from './re-export-options.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+import { splitScanFileOwner } from './re-export-scan-owner.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 async function readPathListFile(file, flag) {
+    let text;
+    try {
+        text = await readFile(resolve(file), 'utf8');
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`${flag} could not read ${file}: ${toError(error).message}`, flag);
+    }
+    const paths = text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#'));
+    if (paths.length === 0) {
+        throw new InvalidArgumentError(`${flag} file ${file} lists no paths. An empty list is usually a generation step that ` +
+            `failed; write one engine-relative path per line, or drop ${flag}.`, flag);
+    }
+    return paths;
+}
+/** Engine-relative form of a positional, or undefined when it cannot be one. */
+function asEnginePath(value) {
+    try {
+        return normalizeEngineRelativeInput(value, 'patch');
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolvePositionals(engineDir, patches, manifest) {
+    for (const identifier of patches) {
+        if (resolvePatchIdentifier(identifier, manifest.patches))
+            continue;
+        const enginePath = asEnginePath(identifier);
+        if (enginePath !== undefined && (await pathExists(join(engineDir, enginePath)))) {
+            throw new InvalidArgumentError(`"${identifier}" is a file in engine/, not a patch. re-export takes patch identifiers ` +
+                `as positionals. To name a file whose drift this run expects, pass --expect ` +
+                `${enginePath} (one --expect per path), or list the paths one per line in a file ` +
+                'and pass --expect-from <file>.', identifier);
+        }
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
+    }
+}
+/**
+ * Refuses a path flag value that names no changed file in engine/. Every
+ * one of these flags is about a changed file (drift to expect, an unmanaged
+ * file to admit, a file to adopt), so a clean or absent path is a typo or a
+ * swallowed argument, and the run would otherwise treat it as a no-op.
+ */
+async function assertFlagPathsInStatus(engineDir, options, manifest) {
+    const normalize = (flag, values) => [
+        flag,
+        (values ?? []).map((value) => normalizeEngineRelativeInput(value, flag)),
+    ];
+    const expectNew = normalize('--expect-new', options.expectNew);
+    const byFlag = [
+        normalize('--expect', options.expect),
+        normalize('--expect-unmanaged', options.expectUnmanaged),
+        expectNew,
+        normalize('--scan-file', options.scanFiles?.map((value) => splitScanFileOwner(value).path)),
+    ];
+    const all = [...new Set(byFlag.flatMap(([, values]) => values))];
+    if (all.length === 0 || !(await isGitRepository(engineDir)))
+        return;
+    const changed = new Set();
+    try {
+        for (const chunk of chunkPathspecs(all)) {
+            for (const file of await getDirtyFiles(engineDir, chunk))
+                changed.add(file);
+        }
+    }
+    catch {
+        // An engine git cannot answer for (no HEAD yet, a broken checkout) is
+        // the locked run's engine precondition to report, with its own remedy.
+        return;
+    }
+    for (const [flag, values] of byFlag) {
+        const absent = values.filter((value) => !changed.has(value));
+        if (absent.length > 0) {
+            throw new InvalidArgumentError(`${flag} names no changed file in engine/: ${absent.join(', ')}. Each value must be a ` +
+                'path git status lists (modified, deleted or untracked); a clean or missing path is a ' +
+                'typo or a list that ended early, and the run would have ignored it.', flag);
+        }
+    }
+    const owners = new Map();
+    for (const patch of manifest.patches) {
+        for (const file of patch.filesAffected)
+            owners.set(file, patch.filename);
+    }
+    const owned = expectNew[1].filter((file) => owners.has(file));
+    if (owned.length > 0) {
+        throw new InvalidArgumentError(`--expect-new names a file a patch already owns: ` +
+            `${owned.map((file) => `${file} (${owners.get(file) ?? ''})`).join(', ')}. ` +
+            '--expect-new is for files no patch owns yet; drop it for these.', '--expect-new');
+    }
+}
+/**
+ * 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 async function preflightReExportArguments(projectRoot, patches, options) {
+    const empty = patches.filter((patch) => patch.trim().length === 0).length;
+    if (empty > 0) {
+        throw new InvalidArgumentError(`re-export was given ${empty} empty patch argument(s). An empty argument is usually a ` +
+            'shell expansion that produced nothing (an unquoted "$@" in a heredoc, an unset ' +
+            'variable); pass patch identifiers, or --all.', 'patches');
+    }
+    const normalized = normalizeReExportFilesPositionals(patches, options);
+    validateReExportOptionCombinations(normalized.patches, normalized.options);
+    const paths = getProjectPaths(projectRoot);
+    const manifest = await loadPatchesManifest(paths.patches);
+    // No manifest: the locked run reports that with its own remedy.
+    if (!manifest || manifest.patches.length === 0)
+        return;
+    if (options.all !== true && options.scanFilesManifest === undefined) {
+        await resolvePositionals(paths.engine, normalized.patches, manifest);
+    }
+    await assertFlagPathsInStatus(paths.engine, normalized.options, manifest);
+}

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

@@ -11,6 +11,7 @@ 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';
+import { preflightReExportArguments, readPathListFile } from './re-export-preflight.js';
 /** Registers the re-export command on the CLI program. */
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
     const reExport = program
@@ -20,17 +21,20 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         '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-file <path>', 'With --scan, add this explicit engine-relative file without collecting adjacent files. Prefix the owning patch (<patch>:<path>, required with several target patches) to adopt into one of them; selected patches without a --scan-file refresh scan-less. 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('--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. Adjacent means the same directory as an owned file (not a sibling or nested directory), or named by a registration line the patch adds. Mutually exclusive with --scan and --files.')
+        .option('--refuse-foreign-drift', "Refuse a re-export (non-zero exit, patch not written) when the refreshed body would add or drop lines, in a file the patch already owns, that the old patch body did not carry — protects multi-session checkouts from silently capturing another session's uncommitted edits. Beside --scan it guards each patch's existing files (adopted files count as expected). Mutually exclusive with --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, and the whitelist applies across EVERY patch in this invocation, not per patch — so pass all the patches and all their --expect paths in one call rather than looping one patch at a time.", ...stringListOption())
         .option('--expect-unmanaged <path>', 'With --refuse-adjacent-unmanaged, name an engine-relative file that is a REVIEWED, recorded exception to the adjacency refusal: an approved unmanaged path is still listed, but no longer refuses. Repeatable, and the carve-out applies across EVERY patch in this invocation, not per patch. Use it to keep the belt armed for everything else instead of dropping --refuse-adjacent-unmanaged entirely.', ...stringListOption())
-        .option('--expect-removed <path>', 'Retire an absent file created by the selected patch while keeping scan-less refusals armed. Repeatable.', ...stringListOption())
+        .option('--expect-from <file>', 'Read --expect paths from a file, one engine-relative path per line (blank lines and # comments ignored). Adds to any --expect flags.')
+        .option('--expect-new <path>', 'With --refuse-adjacent-unmanaged, name a file this session created and will adopt with its next export (or --scan-file): it passes the belt and is reported, while every other adjacent file still refuses. Must be changed in engine/ and owned by no patch. Repeatable.', ...stringListOption())
+        .option('--adjacent-ignore <path|glob>', 'With --refuse-adjacent-unmanaged, a reviewed ignore-list entry: an engine-relative path, or a glob whose * stays within one path segment (** is refused). Matches are reported, never refused. Repeatable.', ...stringListOption())
+        .option('--expect-removed <path>', 'Retire a file from the selected patch while keeping scan-less refusals armed: an absent file the patch created, or a patch-modified upstream file whose engine copy is back at HEAD. 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')
@@ -42,19 +46,40 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .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, expectUnmanaged, ...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 } : {}),
-            ...(expectUnmanaged !== undefined && expectUnmanaged.length > 0
-                ? { expectUnmanaged }
-                : {}),
-            ...(cache === false ? { noCache: true } : {}),
-        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+        const reExportOptions = await toReExportOptions(options);
+        // Refuse what the locked run would refuse before queueing for the
+        // lock, which can be a long wait under contention.
+        await preflightReExportArguments(projectRoot, patches, reExportOptions);
+        await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, reExportOptions), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }
+/**
+ * Maps commander's option names onto {@link ReExportOptions}, reading the
+ * `--expect-from` list into `expect` and dropping empty repeatables.
+ */
+async function toReExportOptions(options) {
+    const { tier, lintIgnore, scanFile, scanFiles, cache, expect: expectFlags, expectFrom, expectUnmanaged, expectNew, adjacentIgnore, ...rest } = options;
+    const expect = [
+        ...(expectFlags ?? []),
+        ...(expectFrom !== undefined ? await readPathListFile(expectFrom, '--expect-from') : []),
+    ];
+    return {
+        ...pickDefined({
+            ...rest,
+            scanFiles: nonEmpty(scanFile),
+            scanFilesManifest: scanFiles,
+            tier: tier,
+            lintIgnore: nonEmpty(lintIgnore),
+            expect: nonEmpty(expect),
+            expectUnmanaged: nonEmpty(expectUnmanaged),
+            expectNew: nonEmpty(expectNew),
+            adjacentIgnore: nonEmpty(adjacentIgnore),
+        }),
+        ...(cache === false ? { noCache: true } : {}),
+    };
+}
+/** The list when it has entries, else undefined (which `pickDefined` drops). */
+function nonEmpty(values) {
+    return values !== undefined && values.length > 0 ? values : undefined;
+}

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

@@ -1,4 +1,15 @@
 import type { PatchMetadata, ReExportOptions } from '../types/commands/index.js';
 import type { ProjectPaths } from '../types/config.js';
-/** Validates every retirement before any patch is written; typos never silently grant a carve-out. */
+/**
+ * Validates every retirement before any patch is written; typos never
+ * silently grant a carve-out. Two shapes retire a file from its one
+ * selected owner:
+ *
+ *  - a file the patch created (`new file mode` section), now absent from
+ *    disk and untracked in engine HEAD;
+ *  - an upstream file the patch modified or deleted, whose engine copy is
+ *    back at HEAD (present, tracked, no diff). A scan-less re-export keeps
+ *    `filesAffected` as it is, so without this the stale entry would stay
+ *    in the manifest and in the reserved-range policy check.
+ */
 export declare function validateExpectedRemovals(paths: ProjectPaths, patches: PatchMetadata[], options: ReExportOptions): Promise<string[]>;

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

@@ -2,12 +2,24 @@
 import { lstat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { listTrackedInHead } from '../core/git-file-ops.js';
+import { getDirtyFiles } from '../core/git-status.js';
 import { parseDiffSections } from '../core/patch-parse.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { getNodeErrorCode } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { normalizeEngineRelativeInput } from './re-export-scan.js';
-/** Validates every retirement before any patch is written; typos never silently grant a carve-out. */
+/**
+ * Validates every retirement before any patch is written; typos never
+ * silently grant a carve-out. Two shapes retire a file from its one
+ * selected owner:
+ *
+ *  - a file the patch created (`new file mode` section), now absent from
+ *    disk and untracked in engine HEAD;
+ *  - an upstream file the patch modified or deleted, whose engine copy is
+ *    back at HEAD (present, tracked, no diff). A scan-less re-export keeps
+ *    `filesAffected` as it is, so without this the stale entry would stay
+ *    in the manifest and in the reserved-range policy check.
+ */
 export async function validateExpectedRemovals(paths, patches, options) {
     const removed = [
         ...new Set((options.expectRemoved ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-removed'))),
@@ -15,19 +27,19 @@ export async function validateExpectedRemovals(paths, patches, options) {
     if (removed.length === 0)
         return removed;
     const tracked = await listTrackedInHead(paths.engine, removed);
+    const dirty = new Set(await getDirtyFiles(paths.engine, [...tracked]));
     for (const file of removed) {
         const owners = patches.filter((patch) => patch.filesAffected.includes(file));
-        if (owners.length !== 1 ||
-            tracked.has(file) ||
-            (await removalPathPresent(join(paths.engine, file)))) {
-            throw new InvalidArgumentError(`--expect-removed ${file} must be absent, untracked in engine HEAD, and owned by exactly one selected patch.`, '--expect-removed');
-        }
         const owner = owners[0];
-        if (!owner)
-            throw new InvalidArgumentError(`No selected owner for ${file}`, '--expect-removed');
-        const body = await readText(join(paths.patches, owner.filename));
-        if (!parseDiffSections(body).some((section) => section.targetPath === file && section.isNewFile)) {
-            throw new InvalidArgumentError(`--expect-removed ${file} was not created by its selected patch.`, '--expect-removed');
+        if (owners.length !== 1 || owner === undefined) {
+            throw new InvalidArgumentError(`--expect-removed ${file} must be owned by exactly one selected patch.`, '--expect-removed');
+        }
+        const section = parseDiffSections(await readText(join(paths.patches, owner.filename))).find((candidate) => candidate.targetPath === file);
+        if (tracked.has(file)) {
+            assertUpstreamFileBackAtHead(file, owner, section !== undefined && !section.isNewFile, dirty);
+        }
+        else {
+            await assertCreatedFileAbsent(paths, file, owner, section?.isNewFile === true);
         }
         if (owner.filesAffected.every((path) => removed.includes(path))) {
             throw new InvalidArgumentError('Retiring every file would empty the patch; use patch delete instead.', '--expect-removed');
@@ -35,6 +47,24 @@ export async function validateExpectedRemovals(paths, patches, options) {
     }
     return removed;
 }
+async function assertCreatedFileAbsent(paths, file, owner, createdByOwner) {
+    if (await removalPathPresent(join(paths.engine, file))) {
+        throw new InvalidArgumentError(`--expect-removed ${file} is untracked in engine HEAD and still present on disk; ` +
+            'a patch-created file can be retired only once it is deleted.', '--expect-removed');
+    }
+    if (!createdByOwner) {
+        throw new InvalidArgumentError(`--expect-removed ${file} was not created by its selected patch ${owner.filename}.`, '--expect-removed');
+    }
+}
+function assertUpstreamFileBackAtHead(file, owner, changedByOwner, dirty) {
+    if (dirty.has(file)) {
+        throw new InvalidArgumentError(`--expect-removed ${file} is tracked in engine HEAD, but its engine copy still differs ` +
+            'from HEAD. Restore the HEAD copy first, then retire it.', '--expect-removed');
+    }
+    if (!changedByOwner) {
+        throw new InvalidArgumentError(`--expect-removed ${file} is not changed by its selected patch ${owner.filename}.`, '--expect-removed');
+    }
+}
 /** A dangling symlink is still an existing owned path, not an approved absence. */
 async function removalPathPresent(path) {
     try {

package/dist/src/commands/re-export-scan-owner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-file owners for `re-export --scan --scan-file <patch>:<path>`.
+ *
+ * One change often spans a patch that creates files and a patch that
+ * registers or imports them. With `--scan-file` bound to a single target
+ * patch, that change took two invocations, and the adopting one could not
+ * carry the belts the other did. Naming the owner per file lets one call
+ * adopt each file into its patch while every other selected patch
+ * refreshes scan-less, all under the same `--refuse-foreign-drift` belt
+ * and in a single engine-lock hold.
+ */
+import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
+/** A `--scan-file` value split into its optional owner and its path. */
+export interface ScanFileOwnerSpec {
+    owner: string | undefined;
+    path: string;
+}
+/**
+ * Splits `<patch>:<path>` into owner and path. The owner is everything
+ * before the first `:`, and only when that part holds no path separator, so
+ * a plain path (even one with a later `:`) stays a path. A one-letter
+ * prefix before `:/` or `:\` reads as a Windows drive, not a patch.
+ */
+export declare function splitScanFileOwner(raw: string): ScanFileOwnerSpec;
+/** Rejoins a split value, so normalization can rewrite the path half only. */
+export declare function joinScanFileOwner(spec: ScanFileOwnerSpec): string;
+/**
+ * Argument-shape check, before any manifest is read: a multi-patch call has
+ * to say which patch each file joins.
+ */
+export declare function validateScanFileOwners(patches: readonly string[], scanFiles: readonly string[]): void;
+/**
+ * Resolves each `--scan-file` value to its owning selected patch. Returns
+ * `undefined` when no `--scan-file` was given. An unprefixed path belongs
+ * to the single selected patch (the historical form).
+ */
+export declare function assignScanFileOwners(scanFiles: readonly string[] | undefined, selectedPatches: readonly PatchMetadata[], manifest: PatchesManifest): Map<string, string[]> | undefined;
+/**
+ * The options one patch of the loop runs with. A patch with assigned files
+ * adopts exactly those; a selected patch without any refreshes scan-less,
+ * because `--scan` beside per-file owners scopes adoption to the named
+ * files rather than arming a broad directory scan for every other patch.
+ */
+export declare function scanOptionsForPatch(options: ReExportOptions, patchFilename: string, assignments: ReadonlyMap<string, string[]> | undefined): ReExportOptions;

package/dist/src/commands/re-export-scan-owner.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-file owners for `re-export --scan --scan-file <patch>:<path>`.
+ *
+ * One change often spans a patch that creates files and a patch that
+ * registers or imports them. With `--scan-file` bound to a single target
+ * patch, that change took two invocations, and the adopting one could not
+ * carry the belts the other did. Naming the owner per file lets one call
+ * adopt each file into its patch while every other selected patch
+ * refreshes scan-less, all under the same `--refuse-foreign-drift` belt
+ * and in a single engine-lock hold.
+ */
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
+import { resolvePatchIdentifier } from '../core/patch-manifest.js';
+import { InvalidArgumentError } from '../errors/base.js';
+/**
+ * Splits `<patch>:<path>` into owner and path. The owner is everything
+ * before the first `:`, and only when that part holds no path separator, so
+ * a plain path (even one with a later `:`) stays a path. A one-letter
+ * prefix before `:/` or `:\` reads as a Windows drive, not a patch.
+ */
+export function splitScanFileOwner(raw) {
+    const colon = raw.indexOf(':');
+    if (colon <= 0)
+        return { owner: undefined, path: raw };
+    const owner = raw.slice(0, colon).trim();
+    const path = raw.slice(colon + 1);
+    if (owner.length === 0 || /[/\\]/.test(owner))
+        return { owner: undefined, path: raw };
+    if (/^[A-Za-z]$/.test(owner) && /^[/\\]/.test(path))
+        return { owner: undefined, path: raw };
+    return { owner, path };
+}
+/** Rejoins a split value, so normalization can rewrite the path half only. */
+export function joinScanFileOwner(spec) {
+    return spec.owner === undefined ? spec.path : `${spec.owner}:${spec.path}`;
+}
+/**
+ * Argument-shape check, before any manifest is read: a multi-patch call has
+ * to say which patch each file joins.
+ */
+export function validateScanFileOwners(patches, scanFiles) {
+    if (patches.length === 0) {
+        throw new InvalidArgumentError('--scan-file needs explicit target patch identifiers.', '--scan-file');
+    }
+    if (patches.length === 1)
+        return;
+    const unowned = scanFiles.filter((file) => splitScanFileOwner(file).owner === undefined);
+    if (unowned.length > 0) {
+        throw new InvalidArgumentError(`--scan-file in a call with ${patches.length} patches must name each file's owning patch ` +
+            `as <patch>:<path> (for example --scan-file ${patches[0] ?? '201'}:${unowned[0] ?? '<path>'}). ` +
+            `Missing an owner: ${unowned.join(', ')}.`, '--scan-file');
+    }
+}
+/**
+ * Resolves each `--scan-file` value to its owning selected patch. Returns
+ * `undefined` when no `--scan-file` was given. An unprefixed path belongs
+ * to the single selected patch (the historical form).
+ */
+export function assignScanFileOwners(scanFiles, selectedPatches, manifest) {
+    if (scanFiles === undefined)
+        return undefined;
+    const selected = new Set(selectedPatches.map((patch) => patch.filename));
+    const byPatch = new Map();
+    const ownerByFile = new Map();
+    for (const raw of scanFiles) {
+        const { owner, path } = splitScanFileOwner(raw);
+        const filename = resolveOwner(owner, selectedPatches, manifest);
+        if (!selected.has(filename)) {
+            throw new InvalidArgumentError(`--scan-file ${raw}: ${filename} is not among the selected patches. ` +
+                'Pass it as a positional patch too.', '--scan-file');
+        }
+        const previous = ownerByFile.get(path);
+        if (previous !== undefined && previous !== filename) {
+            throw new InvalidArgumentError(`--scan-file path is assigned to more than one patch: ${path} (${previous}, ${filename})`, '--scan-file');
+        }
+        ownerByFile.set(path, filename);
+        const files = byPatch.get(filename) ?? [];
+        if (!files.includes(path))
+            files.push(path);
+        byPatch.set(filename, files);
+    }
+    for (const files of byPatch.values())
+        files.sort();
+    return byPatch;
+}
+function resolveOwner(owner, selectedPatches, manifest) {
+    if (owner === undefined) {
+        const only = selectedPatches.length === 1 ? selectedPatches[0] : undefined;
+        if (only === undefined) {
+            throw new InvalidArgumentError('--scan-file in a multi-patch call must name its owning patch as <patch>:<path>.', '--scan-file');
+        }
+        return only.filename;
+    }
+    const match = resolvePatchIdentifier(owner, manifest.patches);
+    if (!match) {
+        throw new InvalidArgumentError(`--scan-file: ${formatPatchNotFoundError(owner, manifest.patches)}`, '--scan-file');
+    }
+    return match.filename;
+}
+/**
+ * The options one patch of the loop runs with. A patch with assigned files
+ * adopts exactly those; a selected patch without any refreshes scan-less,
+ * because `--scan` beside per-file owners scopes adoption to the named
+ * files rather than arming a broad directory scan for every other patch.
+ */
+export function scanOptionsForPatch(options, patchFilename, assignments) {
+    if (assignments === undefined)
+        return options;
+    const assigned = assignments.get(patchFilename);
+    if (assigned !== undefined)
+        return { ...options, scanFiles: assigned };
+    const scanLess = { ...options, scan: false };
+    delete scanLess.scanFiles;
+    return scanLess;
+}

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

@@ -1,10 +1,15 @@
+import { type PatchQueueContext } from '../core/patch-lint.js';
 import type { PatchesManifest } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
 export interface ScanResult {
     updated: string[];
     added: string[];
     removed: string[];
 }
-/** Normalizes repeatable `--scan-file` inputs into safe engine-relative paths. */
+/**
+ * Normalizes repeatable `--scan-file` inputs into safe engine-relative
+ * paths, keeping an optional `<patch>:` owner prefix intact.
+ */
 export declare function normalizeScanFiles(scanFiles: readonly string[] | undefined): string[] | undefined;
 /** Normalizes one CLI-provided path into a safe engine-relative path. */
 export declare function normalizeEngineRelativeInput(rawPath: string, flagName: string): string;
@@ -44,15 +49,18 @@ export declare function assertScanAdoptionsHaveNoForwardImports(args: {
     engineDir: string;
     patchFilename: string;
     added: readonly string[];
+    /**
+     * Threads `patchLint.forwardRegistration` so jar.mn registrations are judged
+     * too, and `patchPolicy`, so the remedy names a legal order.
+     */
+    config?: FireForgeConfig;
 }): Promise<void>;
-/**
- * The one remedy sentence for a forward import a patch body cannot carry.
- * Shared by the `--scan` adoption gate and the plain re-export projection
- * gate so both refusals point at the same commands.
- *
- * @param reRunHint - What to do after the fix ("re-running the scan")
- */
-export declare function formatForwardImportRemedy(reRunHint: string): string;
+/** The manifest rows a queue context carries, for remedy computations. */
+export declare function manifestFromQueue(ctx: PatchQueueContext): PatchesManifest;
+/** `{ category }` of the named queue entry, or `{}` when it has no metadata. */
+export declare function categoryOf(ctx: PatchQueueContext, filename: string): {
+    category?: string;
+};
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export declare function assertScanFileAdditionsHaveDiffHunks(args: {
     diffContent: string;