@hominis/fireforge 0.51.0 → 0.53.0

package/dist/src/commands/patch/reorder-shift.js

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch reorder --shift <n> --from <order> [--through <order>]`
+ * renumbers a run of patches up by `n` in one gap-checked transaction, so
+ * an insert has room.
+ *
+ * Opening room for four inserts after 103 meant moving 104 to 128 up by
+ * four. `patch rename --order` moves one patch, and under
+ * `patchPolicy.allowGaps: false` every single step refused on the gap it
+ * left, so the only way through was one `patch split --after` per insert.
+ * The shift moves the whole run at once (the retired and reserved slots
+ * inside it move with it), and under `allowGaps: false` records the orders
+ * it opens as `patches.json#reserved` slots, so the queue stays valid and
+ * the inserts that follow fill them.
+ *
+ * Same contract as `patch compact`: a projected policy check, a projected
+ * cross-patch lint (reporting only what the shift itself adds), a
+ * confirmation, and a commit under the patch-directory lock that refuses
+ * if the plan changed while it waited.
+ */
+import { loadConfig } from '../../core/config.js';
+import { confirmDestructive } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
+import { computeProjectedLintRegressions } from '../../core/patch-lint-projection.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifest, loadPatchesManifestForWrite, renumberPatchesInManifest, savePatchesManifest, } from '../../core/patch-manifest.js';
+import { formatPatchOrder } from '../../core/patch-parse.js';
+import { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { info, intro, outro, warn } from '../../utils/logger.js';
+import { resolveWaitLockSeconds } from '../../utils/options.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
+import { getSortedRenameEntries, renameMapsEqual, writeRenameMapFile, } from '../patch-rename-map.js';
+import { requirePatchQueue } from './patch-context.js';
+import { projectReorder, rebuildFilenameForOrder } from './reorder-projection.js';
+/** Owner label recorded on the reservations a shift opens. */
+const SHIFT_RESERVATION_OWNER = 'patch reorder --shift';
+/** What occupies an order: a patch, a retired slot or a reservation. */
+function occupantAt(manifest, order) {
+    const patch = manifest.patches.find((entry) => entry.order === order);
+    if (patch !== undefined)
+        return patch.filename;
+    const retired = manifest.retired?.find((slot) => slot.order === order);
+    if (retired !== undefined)
+        return `the retired slot of ${retired.filename}`;
+    const reserved = manifest.reserved?.find((slot) => slot.order === order);
+    if (reserved !== undefined)
+        return `the reservation held by ${reserved.owner}`;
+    return undefined;
+}
+/** The category of whatever occupies `order`. */
+function categoryAt(manifest, order) {
+    return (manifest.patches.find((entry) => entry.order === order)?.category ??
+        manifest.retired?.find((slot) => slot.order === order)?.category ??
+        manifest.reserved?.find((slot) => slot.order === order)?.category);
+}
+/**
+ * The last order of the run that starts at `from`: consecutive occupied
+ * orders (patches and slots) of the first occupant's category.
+ */
+function defaultThrough(manifest, from) {
+    const category = categoryAt(manifest, from);
+    let through = from;
+    while (occupantAt(manifest, through + 1) !== undefined &&
+        categoryAt(manifest, through + 1) === category) {
+        through++;
+    }
+    return through;
+}
+/**
+ * Plans a shift against `manifest`, refusing a run with no patch, a
+ * `--through` before `--from`, and a shift that lands on an occupied order
+ * past the run.
+ *
+ * @param manifest - The queue
+ * @param config - Project configuration (`patchPolicy.allowGaps`)
+ * @param options - `shift`, `from` and optional `through`
+ */
+function planShift(manifest, config, options) {
+    const { shift, from } = options;
+    if (occupantAt(manifest, from) === undefined) {
+        throw new InvalidArgumentError(`No patch or slot holds order ${formatPatchOrder(from)}; --from names the first order of the run to shift.`, '--from');
+    }
+    const through = options.through ?? defaultThrough(manifest, from);
+    if (through < from) {
+        throw new InvalidArgumentError(`--through ${through} is before --from ${from}.`, '--through');
+    }
+    const inRun = (order) => order >= from && order <= through;
+    const members = manifest.patches.filter((patch) => inRun(patch.order));
+    if (members.length === 0) {
+        throw new InvalidArgumentError(`No patch sits between orders ${formatPatchOrder(from)} and ${formatPatchOrder(through)}; nothing to shift.`, '--from');
+    }
+    for (let order = through + 1; order <= through + shift; order++) {
+        const occupant = occupantAt(manifest, order);
+        if (occupant !== undefined) {
+            throw new InvalidArgumentError(`--shift ${shift} would move the run ${formatPatchOrder(from)}-${formatPatchOrder(through)} ` +
+                `onto order ${formatPatchOrder(order)}, which ${occupant} holds. Extend the run with ` +
+                '--through, or shift by fewer orders.', '--shift');
+        }
+    }
+    const renameMap = new Map();
+    for (const patch of members) {
+        const newOrder = patch.order + shift;
+        renameMap.set(patch.filename, {
+            newOrder,
+            newFilename: rebuildFilenameForOrder(patch, newOrder),
+        });
+    }
+    const moveSlot = (slot) => inRun(slot.order) ? { ...slot, order: slot.order + shift } : slot;
+    const retired = (manifest.retired ?? []).map(moveSlot);
+    const reserved = (manifest.reserved ?? []).map(moveSlot);
+    // Every order below the shifted run's new start is free after the shift
+    // (the collision check above saw to the ones past the old run), so under
+    // `allowGaps: false` each one is held until an insert fills it.
+    const opened = [];
+    const category = categoryAt(manifest, from);
+    if (config.patchPolicy?.allowGaps === false && category !== undefined) {
+        const reservedAt = new Date().toISOString();
+        for (let order = from; order < from + shift; order++) {
+            opened.push(order);
+            reserved.push({
+                order,
+                category,
+                owner: SHIFT_RESERVATION_OWNER,
+                reservedAt,
+                reason: `opened by patch reorder --shift ${shift} --from ${from}`,
+            });
+        }
+    }
+    const byOrder = (a, b) => a.order - b.order;
+    return {
+        shift,
+        from,
+        through,
+        renameMap,
+        retired: retired.sort(byOrder),
+        reserved: reserved.sort(byOrder),
+        opened,
+    };
+}
+/** The manifest a shift leaves: renamed rows with the plan's slot lists. */
+function projectShiftManifest(manifest, plan) {
+    const renamed = applyRenameMapToManifest(manifest, plan.renameMap);
+    return {
+        version: renamed.version,
+        patches: renamed.patches,
+        ...(plan.retired.length > 0 ? { retired: plan.retired } : {}),
+        ...(plan.reserved.length > 0 ? { reserved: plan.reserved } : {}),
+    };
+}
+/** True when two plans make the same renames and leave the same slot orders. */
+function shiftPlansEqual(left, right) {
+    const orders = (slots) => slots.map((slot) => slot.order).join(',');
+    return (renameMapsEqual(left.renameMap, right.renameMap) &&
+        orders(left.retired) === orders(right.retired) &&
+        orders(left.reserved) === orders(right.reserved));
+}
+/** Cross-patch lint errors the shift itself introduces. */
+async function projectShiftLint(patchesDir, config, renameMap) {
+    const baseCtx = await buildPatchQueueContext(patchesDir, config);
+    const isError = (issue) => issue.severity === 'error';
+    const regressions = computeProjectedLintRegressions(lintPatchQueue(baseCtx).filter(isError), 
+    // The projection keeps the baseline's queue-wide lint settings, so the
+    // two sides compare symmetric rule sets.
+    lintPatchQueue({ ...baseCtx, ...projectReorder(baseCtx, renameMap) }).filter(isError));
+    return regressions.length === 0
+        ? null
+        : {
+            reason: `shift would introduce ${regressions.length} cross-patch lint error(s)`,
+            details: regressions.map(formatPatchLintIssue),
+        };
+}
+/** Lines describing a plan, for the dry run and the confirmation prompt. */
+function describeShift(manifest, plan) {
+    const lines = [
+        `shift orders ${formatPatchOrder(plan.from)}-${formatPatchOrder(plan.through)} up by ${plan.shift}`,
+        `${plan.renameMap.size} patch(es) would be renamed:`,
+        ...getSortedRenameEntries(plan.renameMap).map(([from, entry]) => `  ${from}  →  ${entry.newFilename}  (order ${entry.newOrder})`),
+    ];
+    const inRun = (order) => order >= plan.from && order <= plan.through;
+    for (const slot of manifest.retired ?? []) {
+        if (inRun(slot.order)) {
+            lines.push(`retired slot ${formatPatchOrder(slot.order)} (${slot.filename}) moves to ${formatPatchOrder(slot.order + plan.shift)}`);
+        }
+    }
+    for (const slot of manifest.reserved ?? []) {
+        if (inRun(slot.order)) {
+            lines.push(`reservation ${formatPatchOrder(slot.order)} (held by ${slot.owner}) moves to ` +
+                `${formatPatchOrder(slot.order + plan.shift)}; tell its holder the new order`);
+        }
+    }
+    if (plan.opened.length > 0) {
+        lines.push(`opened orders ${plan.opened.map((order) => formatPatchOrder(order)).join(', ')} are ` +
+            'reserved (patchPolicy.allowGaps: false); "fireforge export --order <n>" or ' +
+            '"patch split --order <n>" fills them, "patch reserve <n> --release" drops one');
+    }
+    return lines;
+}
+/**
+ * Commits a confirmed shift under the patch-directory lock: re-plans
+ * against the current manifest (refusing a changed plan), renumbers, then
+ * writes the plan's slot lists. A failed slot write inverts the renumber.
+ */
+async function commitShift(patchesDir, config, plan, options) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const current = await loadPatchesManifest(patchesDir);
+        if (!current)
+            throw new GeneralError('Manifest disappeared while waiting for lock.');
+        const currentPlan = planShift(current, config, {
+            shift: plan.shift,
+            from: plan.from,
+            through: plan.through,
+        });
+        if (!shiftPlansEqual(plan, currentPlan)) {
+            throw new GeneralError('Patch queue changed while waiting for confirmation. Re-run reorder --shift to recompute the plan.');
+        }
+        enforcePatchPolicy({
+            config,
+            manifest: projectShiftManifest(current, plan),
+            command: 'patch reorder --shift',
+            forceUnsafe: options.forceUnsafe === true,
+        });
+        await renumberPatchesInManifest(patchesDir, plan.renameMap);
+        try {
+            const renumbered = await loadPatchesManifestForWrite(patchesDir);
+            if (!renumbered)
+                throw new GeneralError('Manifest disappeared during reorder --shift.');
+            delete renumbered.retired;
+            delete renumbered.reserved;
+            await savePatchesManifest(patchesDir, {
+                ...renumbered,
+                ...(plan.retired.length > 0 ? { retired: plan.retired } : {}),
+                ...(plan.reserved.length > 0 ? { reserved: plan.reserved } : {}),
+            });
+        }
+        catch (error) {
+            const inverse = new Map([...plan.renameMap].map(([oldFilename, entry]) => [
+                entry.newFilename,
+                { newFilename: oldFilename, newOrder: entry.newOrder - plan.shift },
+            ]));
+            try {
+                await renumberPatchesInManifest(patchesDir, inverse);
+                await savePatchesManifest(patchesDir, current);
+            }
+            catch (rollbackError) {
+                warn(`Rollback warning: could not invert the shift: ${toError(rollbackError).message}`);
+            }
+            throw error;
+        }
+        await appendHistoryBestEffort(patchesDir, {
+            operation: 'patch-reorder-shift',
+            args: {
+                shift: plan.shift,
+                from: plan.from,
+                through: plan.through,
+                renames: getSortedRenameEntries(plan.renameMap).map(([from, entry]) => ({
+                    from,
+                    to: entry.newFilename,
+                    order: entry.newOrder,
+                })),
+                ...(plan.opened.length > 0 ? { reservedOpened: plan.opened } : {}),
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
+            result: 'ok',
+        }, 'patch reorder --shift committed');
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch reorder' });
+}
+/**
+ * Runs `patch reorder --shift <n> --from <order> [--through <order>]`.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Reorder options with `shift` and `from` set
+ */
+export async function patchReorderShiftCommand(projectRoot, options) {
+    intro(options.dryRun ? 'FireForge patch reorder --shift (dry run)' : 'FireForge patch reorder --shift');
+    const config = await loadConfig(projectRoot);
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const plan = planShift(manifest, config, options);
+    enforcePatchPolicy({
+        config,
+        manifest: projectShiftManifest(manifest, plan),
+        command: 'patch reorder --shift',
+        forceUnsafe: options.forceUnsafe === true,
+    });
+    const conflicts = await projectShiftLint(paths.patches, config, plan.renameMap);
+    const decision = await confirmDestructive({
+        operation: 'patch-reorder-shift',
+        title: `Shift ${plan.renameMap.size} patch(es) from order ${formatPatchOrder(plan.from)} up by ${plan.shift}`,
+        summary: describeShift(manifest, plan),
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
+        conflicts,
+    });
+    if (!proceedAfterDecision(decision, 'Reorder cancelled'))
+        return;
+    await commitShift(paths.patches, config, plan, options);
+    if (options.mapOut !== undefined) {
+        const written = await writeRenameMapFile(options.mapOut, plan.renameMap);
+        info(`Wrote the old-to-new filename map (${plan.renameMap.size} rename(s)) to ${written}`);
+    }
+    info(`Shifted ${plan.renameMap.size} patch(es) up by ${plan.shift}.`);
+    outro('Reorder complete');
+}

package/dist/src/commands/patch/reorder.d.ts

@@ -6,31 +6,25 @@
  * renumbered to make room. Pre-flights the projected order through
  * `lintPatchQueue` so reorders that would introduce a forward-import fail
  * before any bytes move.
+ *
+ * `fireforge patch reorder --shift <n> --from <order> [--through <order>]`
+ * renumbers a whole run instead (see reorder-shift.ts). Every mode takes
+ * `--map-out <file>` for the committed old-to-new filename map.
  */
 import { Command } from 'commander';
-import { type PatchQueueContext } from '../../core/patch-lint.js';
-import { type PatchRenameEntry } from '../../core/patch-manifest.js';
 import type { CommandContext } from '../../types/cli.js';
-import type { PatchMetadata, PatchReorderOptions } from '../../types/commands/index.js';
-/** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
-export declare function rebuildFilenameForOrder(existing: PatchMetadata, newOrder: number): string;
-/**
- * Applies a rename map to a {@link PatchQueueContext} so cross-patch lint
- * can run against the projected state without touching disk. Exported for
- * `patch rename --order`, which projects the same single-row move shape.
- */
-export declare function projectReorder(base: PatchQueueContext, renameMap: Map<string, PatchRenameEntry>): PatchQueueContext;
+import type { PatchReorderOptions } from '../../types/commands/index.js';
 /**
  * Runs the `patch reorder` command: computes a rename map moving the
  * target patch to the requested slot, projects the new order through
  * cross-patch lint, confirms, and then renames under the patch directory
- * lock.
+ * lock. With `--shift` it renumbers a run instead (see reorder-shift.ts).
  *
  * @param projectRoot - Project root directory
- * @param identifier - Patch filename or ordinal number to move
- * @param options - Command options (mutually exclusive --to/--before/--after)
+ * @param identifier - Patch filename or ordinal number to move (none with `--shift`)
+ * @param options - Command options (mutually exclusive --to/--before/--after/--shift)
  */
-export declare function patchReorderCommand(projectRoot: string, identifier: string, options?: PatchReorderOptions): Promise<void>;
+export declare function patchReorderCommand(projectRoot: string, identifier: string | undefined, options?: PatchReorderOptions): Promise<void>;
 /**
  * Registers the `patch reorder` subcommand on the `patch` parent.
  *

package/dist/src/commands/patch/reorder.js

@@ -7,6 +7,10 @@
  * renumbered to make room. Pre-flights the projected order through
  * `lintPatchQueue` so reorders that would introduce a forward-import fail
  * before any bytes move.
+ *
+ * `fireforge patch reorder --shift <n> --from <order> [--through <order>]`
+ * renumbers a whole run instead (see reorder-shift.ts). Every mode takes
+ * `--map-out <file>` for the committed old-to-new filename map.
  */
 import { Command, Option } from 'commander';
 import { loadConfig } from '../../core/config.js';
@@ -14,27 +18,17 @@ import { confirmDestructive, } from '../../core/destructive.js';
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, rewriteStagedDependencyOwners, } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, enforcePatchPolicy } from '../../core/patch-policy.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
-import { getSortedRenameEntries, renameMapsEqual } from '../patch-rename-map.js';
+import { getSortedRenameEntries, renameMapsEqual, writeRenameMapFile, } from '../patch-rename-map.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
-/** Zero-pads an ordinal number to the given width. */
-function padOrder(value, width) {
-    return String(value).padStart(width, '0');
-}
-/** Builds a new patch filename by replacing the numeric prefix with `newOrder`. */
-export function rebuildFilenameForOrder(existing, newOrder) {
-    const currentPrefixMatch = /^(\d+)-/.exec(existing.filename);
-    const currentPrefix = currentPrefixMatch?.[1] ?? '001';
-    const width = Math.max(3, currentPrefix.length, String(newOrder).length);
-    const rest = existing.filename.replace(/^\d+-/, '');
-    return `${padOrder(newOrder, width)}-${rest}`;
-}
+import { projectReorder, rebuildFilenameForOrder } from './reorder-projection.js';
+import { patchReorderShiftCommand } from './reorder-shift.js';
 /**
  * Computes a rename map that moves `target` to `destinationOrder` with a
  * minimal shift: only the contiguous run of patches whose current order
@@ -100,35 +94,6 @@ function computeRenameMap(manifestPatches, target, destinationOrder) {
     });
     return renames;
 }
-/**
- * Applies a rename map to a {@link PatchQueueContext} so cross-patch lint
- * can run against the projected state without touching disk. Exported for
- * `patch rename --order`, which projects the same single-row move shape.
- */
-export function projectReorder(base, renameMap) {
-    const ownerLookup = (oldFilename) => renameMap.get(oldFilename)?.newFilename;
-    const projectedEntries = base.entries.map((entry) => {
-        // Project staged-dependency owner references through the rename map on
-        // every entry. Owners point at other patches' filenames, so a
-        // projection that skips non-renamed entries would lint against stale
-        // owners and report false forward-import regressions.
-        const metadata = entry.metadata
-            ? rewriteStagedDependencyOwners(entry.metadata, ownerLookup)
-            : entry.metadata;
-        const rename = renameMap.get(entry.filename);
-        if (!rename) {
-            return metadata === entry.metadata ? entry : { ...entry, metadata };
-        }
-        return {
-            ...entry,
-            metadata,
-            filename: rename.newFilename,
-            order: rename.newOrder,
-        };
-    });
-    projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    return { entries: projectedEntries };
-}
 /**
  * Resolves `--to <N>`, `--before <anchor>`, and `--after <anchor>` into a
  * concrete destination order and, for the anchor variants, the anchor
@@ -186,7 +151,7 @@ function resolveDestination(target, manifestPatches, options) {
  */
 async function commitReorderPlan(commitOptions) {
     const { patchesDir, target, renameMap, anchorFilename, options, config, buildHistoryEntry } = commitOptions;
-    await withPatchDirectoryLock(patchesDir, async () => {
+    return withPatchDirectoryLock(patchesDir, async () => {
         const currentManifest = await loadPatchesManifest(patchesDir);
         if (!currentManifest || currentManifest.patches.length === 0) {
             throw new GeneralError('Patch queue changed while waiting for confirmation. Re-run reorder.');
@@ -239,19 +204,45 @@ async function commitReorderPlan(commitOptions) {
         // succeeded and is not reversible, so surfacing it as a command
         // failure would mislead.
         await appendHistoryBestEffort(patchesDir, buildHistoryEntry(currentRenameMap), `patch reorder committed`);
+        return currentRenameMap;
     }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch reorder' });
 }
+/**
+ * Validates the `--shift` flag set and runs the shift, or returns false
+ * when no shift flag was given.
+ */
+async function runShiftMode(projectRoot, identifier, options) {
+    const { shift, from } = options;
+    if (shift === undefined && from === undefined && options.through === undefined)
+        return false;
+    if (shift === undefined || from === undefined) {
+        throw new InvalidArgumentError('--shift <n> and --from <order> go together (--through <order> is optional).', shift === undefined ? '--shift' : '--from');
+    }
+    if (identifier !== undefined ||
+        options.to !== undefined ||
+        options.before !== undefined ||
+        options.after !== undefined) {
+        throw new InvalidArgumentError('--shift renumbers a run of orders and takes no patch name, --to, --before or --after.', '--shift');
+    }
+    await patchReorderShiftCommand(projectRoot, { ...options, shift, from });
+    return true;
+}
 /**
  * Runs the `patch reorder` command: computes a rename map moving the
  * target patch to the requested slot, projects the new order through
  * cross-patch lint, confirms, and then renames under the patch directory
- * lock.
+ * lock. With `--shift` it renumbers a run instead (see reorder-shift.ts).
  *
  * @param projectRoot - Project root directory
- * @param identifier - Patch filename or ordinal number to move
- * @param options - Command options (mutually exclusive --to/--before/--after)
+ * @param identifier - Patch filename or ordinal number to move (none with `--shift`)
+ * @param options - Command options (mutually exclusive --to/--before/--after/--shift)
  */
 export async function patchReorderCommand(projectRoot, identifier, options = {}) {
+    if (await runShiftMode(projectRoot, identifier, options))
+        return;
+    if (identifier === undefined) {
+        throw new InvalidArgumentError('Name the patch to move, or renumber a run with --shift <n> --from <order>.', 'patch reorder');
+    }
     intro(options.dryRun ? 'FireForge patch reorder (dry run)' : 'FireForge patch reorder');
     const specifiedTargets = [
         options.to !== undefined,
@@ -338,7 +329,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
             result: 'ok',
         };
     };
-    await commitReorderPlan({
+    const committed = await commitReorderPlan({
         patchesDir: paths.patches,
         target,
         renameMap,
@@ -347,6 +338,10 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
         config,
         buildHistoryEntry,
     });
+    if (options.mapOut !== undefined) {
+        const written = await writeRenameMapFile(options.mapOut, committed);
+        info(`Wrote the old-to-new filename map (${committed.size} rename(s)) to ${written}`);
+    }
     info(`Reordered ${renameMap.size} patch(es).`);
     outro('Reorder complete');
 }
@@ -359,11 +354,18 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
 export function registerPatchReorder(parent, context) {
     const { getProjectRoot, withErrorHandling } = context;
     const command = parent
-        .command('reorder <name>')
-        .description('Move a patch to a different position in the queue (destructive)')
+        .command('reorder [name]')
+        .description('Move a patch to a different position in the queue, or shift a run of patches up with ' +
+        '--shift <n> --from <order> (destructive)')
         .addOption(new Option('--to <order>', 'Destination ordinal').argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--to', v))))
         .option('--before <anchor>', 'Place the patch immediately before <anchor>')
         .option('--after <anchor>', 'Place the patch immediately after <anchor>')
+        .addOption(new Option('--shift <n>', 'Renumber the run starting at --from up by <n> orders (no patch name); under ' +
+        'patchPolicy.allowGaps: false the opened orders are reserved').argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--shift', v))))
+        .addOption(new Option('--from <order>', 'First order of the run --shift moves').argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--from', v))))
+        .addOption(new Option('--through <order>', 'Last order of the run --shift moves (default: the end of the run of consecutive ' +
+        "orders of --from's category)").argParser(commanderArgParser((v) => parsePositiveIntegerFlag('--through', v))))
+        .option('--map-out <file>', 'Write the committed old-to-new filename map as JSON')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass the refusal when the projected order introduces a lint error');

package/dist/src/commands/patch/split-plan.d.ts

@@ -45,7 +45,33 @@ export interface SplitPlan {
      * unused. Populated by {@link runProjectedSplitLint}.
      */
     stagedMaintenance: SplitStagedMaintenance;
+    /**
+     * The command running the plan, named in the `reason` of every
+     * declaration it writes. Absent: `patch split`.
+     */
+    operation?: MoveOperation;
+    /**
+     * New engine files no patch owned that `move-files --scan-file` adopts
+     * into the new patch in the same transaction. Already part of
+     * `movedFiles`; listed apart only for the summary and the commit's
+     * still-unowned check.
+     */
+    adoptedFiles?: string[];
 }
+/** The commands that move files between patches and declare the edges they open. */
+export type MoveOperation = 'patch split' | 'patch move-files';
+/**
+ * The `reason` a move records on a forward declaration it writes, so the
+ * declaration explains itself in `patches.json` and `staged-dependency
+ * --add --from` accepts it without a hand-written `--reason`.
+ *
+ * @param source - Patch the files left
+ * @param destination - Patch the files moved into
+ * @param operation - The command that moved them
+ */
+export declare function moveDeclarationReason(source: string, destination: string, operation: MoveOperation): string;
+/** The {@link moveDeclarationReason} of a split plan. */
+export declare function splitDeclarationReason(plan: SplitPlan): string;
 /**
  * Refuses the split unless the source patch currently owns every requested
  * file. Splitting out a file the source does not own would produce a new patch
@@ -90,8 +116,10 @@ export declare function buildNewPatchMetadata(plan: SplitPlan, config: FireForge
 export declare function buildSplitSummary(plan: SplitPlan): string[];
 /**
  * Maps a declaration the split projection proposes back onto the queue as
- * it stands: renumbered patches take their current names, and an owner
- * that is the patch the split would create is dropped (it does not exist
- * until the split runs).
+ * it stands: renumbered patches take their current names. An owner that is
+ * the patch the split would create keeps the planned filename, so the
+ * report declares the owner the rerun creates (`staged-dependency --add`
+ * accepts an owner the queue does not hold yet, and the move then lands
+ * with the declaration already right).
  */
 export declare function splitDeclarationRenamer(plan: SplitPlan): DeclarationRenamer;