@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch retire <name>`: removes a patch from the queue and keeps
+ * its order number spent as a retired slot in `patches.json#retired`.
+ *
+ * The case it exists for: a rename leaves a patch owning only files that no
+ * longer exist. `patch delete` opens a numeric gap that
+ * `patchPolicy.allowGaps: false` refuses, and `patch compact` renumbers
+ * every later patch, including ones a peer session has in flight. Retiring
+ * removes the patch file and row like a delete, and records the order as a
+ * placeholder the gap check counts as occupied. Nothing else reads the
+ * placeholder (see `core/patch-retired.ts`), and a later
+ * `export --order <n>` that takes the number fills it.
+ *
+ * Shares the delete's dependency refusal, dry-run, confirmation and history
+ * contract, so the two differ only in what happens to the order number.
+ */
+import { Command } from 'commander';
+import { loadConfig } from '../../core/config.js';
+import { confirmDestructive } from '../../core/destructive.js';
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { buildPatchQueueContext } from '../../core/patch-lint.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { removePatchFileAndManifest } from '../../core/patch-manifest.js';
+import { formatPatchOrder } from '../../core/patch-parse.js';
+import { GeneralError } from '../../errors/base.js';
+import { info, intro, outro } from '../../utils/logger.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { proceedAfterDecision } from '../destructive-decision.js';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { deleteCreatedFiles, planClaimedFiles, withCreatedFileLock, } from './removal-created-files.js';
+import { collectRemovalDependents, queueSnapshot, removalConflict, warnDanglingStagedOwners, } from './removal-dependents.js';
+/**
+ * Runs the `patch retire` command.
+ *
+ * @param projectRoot - Project root directory
+ * @param identifier - Patch filename, ordinal, or manifest name to retire
+ * @param options - Command options
+ */
+export async function patchRetireCommand(projectRoot, identifier, options = {}) {
+    intro(options.dryRun ? 'FireForge patch retire (dry run)' : 'FireForge patch retire');
+    const { paths, manifest } = await requirePatchQueue(projectRoot, {
+        missingDirMessage: 'Patches directory not found. No patches to retire.',
+    });
+    const target = requirePatchTarget(identifier, manifest.patches);
+    const baseCtx = await buildPatchQueueContext(paths.patches);
+    const dependents = collectRemovalDependents(baseCtx, target, {
+        noun: 'retirement',
+        verb: 'retire',
+    });
+    warnDanglingStagedOwners(baseCtx, target, 'retire');
+    const order = formatPatchOrder(target.order);
+    const claimed = await planClaimedFiles(baseCtx, target, paths.engine, options.deleteCreated === true);
+    const summary = [
+        `retire ${target.filename}  (category: ${target.category}, order: ${order})`,
+        `description: ${target.description || '(none)'}`,
+        `order ${order} stays spent as a retired slot in patches.json; ` +
+            `"fireforge export --order ${order}" can fill it later`,
+        ...claimed.summary,
+    ];
+    const decision = await confirmDestructive({
+        operation: 'patch-retire',
+        title: `Retire ${target.filename}`,
+        summary,
+        yes: options.yes === true,
+        dryRun: options.dryRun === true,
+        unsafeOverride: options.forceUnsafe === true,
+        conflicts: removalConflict(dependents, target),
+    });
+    if (!proceedAfterDecision(decision, 'Retire cancelled'))
+        return;
+    const slot = {
+        order: target.order,
+        category: target.category,
+        filename: target.filename,
+        retiredAt: new Date().toISOString(),
+        ...(options.reason !== undefined ? { reason: options.reason } : {}),
+    };
+    // Same locking and history contract as `patch delete`: the dependency
+    // scan approved before the prompt is re-checked under the lock, and the
+    // history record is appended inside it.
+    const waitLockSeconds = resolveWaitLockSeconds(options.waitLock);
+    await withCreatedFileLock(projectRoot, 'patch retire', claimed, waitLockSeconds, () => withPatchDirectoryLock(paths.patches, async () => {
+        const current = await buildPatchQueueContext(paths.patches);
+        if (queueSnapshot(current) !== queueSnapshot(baseCtx)) {
+            throw new GeneralError('Patch queue changed while waiting for confirmation or the lock. Re-run patch retire to review the current dependencies.');
+        }
+        await removePatchFileAndManifest(paths.patches, target.filename, slot);
+        await deleteCreatedFiles(paths.engine, claimed.deleteOnCommit);
+        await appendHistoryBestEffort(paths.patches, {
+            operation: 'patch-retire',
+            args: {
+                filename: target.filename,
+                order: target.order,
+                filesAffected: target.filesAffected,
+                ...(claimed.deleteOnCommit.length > 0
+                    ? { deletedCreatedFiles: claimed.deleteOnCommit }
+                    : {}),
+                ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            },
+            ...(options.yes === true ? { yes: true } : {}),
+            ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),
+            result: 'ok',
+        }, `patch retire committed (${target.filename})`);
+    }, { waitLockSeconds, command: 'patch retire' }));
+    info(`Retired ${target.filename}; order ${order} is kept as a retired slot.`);
+    if ((await loadConfig(projectRoot)).patchPolicy?.allowGaps !== false) {
+        info('patchPolicy.allowGaps is not false, so no check reads the retired slot; ' +
+            '"patch delete" would have had the same effect on this queue.');
+    }
+    outro('Retire complete');
+}
+/**
+ * Registers the `patch retire` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchRetire(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const command = parent
+        .command('retire <name>')
+        .description('Remove a patch from the queue but keep its order number as a retired slot, ' +
+        'so patchPolicy.allowGaps: false sees no gap and no later patch is renumbered (destructive)')
+        .option('--reason <text>', 'Rationale recorded on the retired slot')
+        .option('--dry-run', 'Show what would happen without writing')
+        .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--delete-created', 'Also delete the engine files this patch creates that are still on disk, instead of leaving them unmanaged')
+        .option('--force-unsafe', 'Bypass the refusal when a later patch depends on this patch (last resort)');
+    addWaitLockOption(command).action(withErrorHandling(async (name, options) => {
+        await patchRetireCommand(getProjectRoot(), name, pickDefined(options));
+    }));
+}

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

@@ -7,10 +7,12 @@
  */
 import { type ConflictReport } from '../../core/destructive.js';
 import type { PatchQueueContext } from '../../core/patch-lint-cross.js';
-import type { PatchStagedForwardImport } from '../../types/commands/index.js';
+import type { PatchLintIssue, PatchStagedForwardImport } from '../../types/commands/index.js';
 import type { PatchCategory, PatchesManifest, PatchMetadata } from '../../types/commands/index.js';
 import type { FireForgeConfig } from '../../types/config.js';
+import type { DeclarationRenamer } from '../declarations-report.js';
 import { type PlacementPlan } from '../export-flow.js';
+import { type SplitStagedMaintenance } from './split-staged.js';
 /** Everything the commit step needs, computed and confirmed up front. */
 export interface SplitPlan {
     source: PatchMetadata;
@@ -38,6 +40,11 @@ export interface SplitPlan {
      * and persisted on commit so the real per-patch gate stays clean.
      */
     stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+    /**
+     * Declarations the move re-homes on the new patch or drops as made
+     * unused. Populated by {@link runProjectedSplitLint}.
+     */
+    stagedMaintenance: SplitStagedMaintenance;
 }
 /**
  * Refuses the split unless the source patch currently owns every requested
@@ -51,13 +58,6 @@ export declare function assertSourceOwnsFiles(source: PatchMetadata, files: read
  * source patch so hunk context is correct for the new file set.
  */
 export declare function buildSplitDiff(engineDir: string, files: readonly string[], label: string, sourceFilename: string): Promise<string>;
-/**
- * Finds patches declaring a staged-dependency forward-import whose `owner`
- * is the source patch and whose `creates` path moves to the new patch.
- */
-export declare function findOwnerRewriteHolders(patches: readonly PatchMetadata[], sourceFilename: string, movedSet: ReadonlySet<string>): string[];
-/** Rewrites split-affected owners on one manifest row. */
-export declare function rewriteSplitOwners(patch: PatchMetadata, sourceFilename: string, movedSet: ReadonlySet<string>, newFilename: string): PatchMetadata;
 /** Merges `decls` into a patch's `stagedDependencies.forwardImports` (no duplicates). */
 export declare function mergeStagedForwardImports(patch: PatchMetadata, decls: readonly PatchStagedForwardImport[]): PatchMetadata;
 /**
@@ -69,7 +69,9 @@ export declare function mergeStagedForwardImports(patch: PatchMetadata, decls: r
  */
 export declare function runProjectedSplitLint(plan: SplitPlan, baseCtx: PatchQueueContext): {
     conflicts: ConflictReport | null;
+    regressions: PatchLintIssue[];
     stagedDependencyAdditions: Map<string, PatchStagedForwardImport[]>;
+    stagedMaintenance: SplitStagedMaintenance;
 };
 /** Builds the projected manifest for policy enforcement. */
 export declare function projectSplitManifest(manifest: {
@@ -86,3 +88,10 @@ export declare function buildNewPatchMetadata(plan: SplitPlan, config: FireForge
  * shown by `--dry-run` and by the destructive-operation confirmation prompt.
  */
 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).
+ */
+export declare function splitDeclarationRenamer(plan: SplitPlan): DeclarationRenamer;

package/dist/src/commands/patch/split-plan.js

@@ -20,6 +20,7 @@ import { pathExists } from '../../utils/fs.js';
 import { warn } from '../../utils/logger.js';
 import {} from '../export-flow.js';
 import { projectEntryBody } from './entry-projection.js';
+import { describeStagedMaintenance, findDeclarationsMadeUnused, keptRelocatedDeclarations, relocatedSourceDeclarations, rewriteSplitOwners, withoutRelocatedDeclarations, } from './split-staged.js';
 /**
  * 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
@@ -58,29 +59,6 @@ export async function buildSplitDiff(engineDir, files, label, sourceFilename) {
     }
     return diff;
 }
-/**
- * Finds patches declaring a staged-dependency forward-import whose `owner`
- * is the source patch and whose `creates` path moves to the new patch.
- */
-export function findOwnerRewriteHolders(patches, sourceFilename, movedSet) {
-    return patches
-        .filter((patch) => (patch.stagedDependencies?.forwardImports ?? []).some((fi) => fi.owner === sourceFilename && movedSet.has(fi.creates)))
-        .map((patch) => patch.filename);
-}
-/** Rewrites split-affected owners on one manifest row. */
-export function rewriteSplitOwners(patch, sourceFilename, movedSet, newFilename) {
-    const forwardImports = patch.stagedDependencies?.forwardImports;
-    if (!forwardImports?.some((fi) => fi.owner === sourceFilename && movedSet.has(fi.creates))) {
-        return patch;
-    }
-    return {
-        ...patch,
-        stagedDependencies: {
-            ...patch.stagedDependencies,
-            forwardImports: forwardImports.map((fi) => fi.owner === sourceFilename && movedSet.has(fi.creates) ? { ...fi, owner: newFilename } : fi),
-        },
-    };
-}
 /** Builds the projected post-split queue entries (renumber + shrunken source + new patch). */
 function buildProjectedSplitEntries(baseCtx, plan) {
     const movedSet = new Set(plan.movedFiles);
@@ -90,6 +68,9 @@ function buildProjectedSplitEntries(baseCtx, plan) {
         if (metadata) {
             metadata = rewriteStagedDependencyOwners(metadata, ownerLookup);
             metadata = rewriteSplitOwners(metadata, plan.source.filename, movedSet, plan.placement.newFilename);
+            if (entry.filename === plan.source.filename) {
+                metadata = withoutRelocatedDeclarations(metadata, movedSet);
+            }
         }
         const rename = plan.placement.renameMap.get(entry.filename);
         const base = rename
@@ -99,10 +80,26 @@ function buildProjectedSplitEntries(baseCtx, plan) {
             return base;
         return { ...base, ...projectEntryBody(plan.remainingDiff) };
     });
+    // Declarations whose declaring file moved travel with it, so the new
+    // patch's projected entry carries them (and only then needs metadata).
+    const relocated = relocatedSourceDeclarations(plan.source, movedSet, ownerLookup);
+    const hasRelocated = (relocated.forwardImports?.length ?? 0) + (relocated.registrations?.length ?? 0) > 0;
     entries.push({
         filename: plan.placement.newFilename,
         order: plan.placement.insertionOrder,
-        metadata: null,
+        metadata: hasRelocated
+            ? {
+                filename: plan.placement.newFilename,
+                order: plan.placement.insertionOrder,
+                category: plan.category,
+                name: plan.name,
+                description: plan.description,
+                createdAt: '',
+                sourceEsrVersion: plan.source.sourceEsrVersion,
+                filesAffected: plan.movedFiles,
+                stagedDependencies: relocated,
+            }
+            : null,
         ...projectEntryBody(plan.movedDiff),
     });
     entries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
@@ -184,13 +181,29 @@ export function runProjectedSplitLint(plan, baseCtx) {
     // the new patch, then inject them before linting so they resolve.
     const stagedDependencyAdditions = computeSplitStagedDependencyAdditions(projectedEntries, plan.placement.newFilename);
     injectStagedDependencyAdditions(projectedEntries, stagedDependencyAdditions);
-    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({
+    const baselineAll = lintPatchQueue(baseCtx);
+    const projectedAll = lintPatchQueue({
         entries: projectedEntries,
         // Keep the projection patch-policy-aware whenever the baseline is, so
         // computeProjectedLintRegressions compares symmetric rule sets.
         ...(baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {}),
-    }).filter((i) => i.severity === 'error');
+    });
+    const baselineIssues = baselineAll.filter((i) => i.severity === 'error');
+    const projectedIssues = projectedAll.filter((i) => i.severity === 'error');
+    const oldNameByNew = new Map([...plan.placement.renameMap].map(([oldName, entry]) => [entry.newFilename, oldName]));
+    const stagedMaintenance = {
+        relocated: relocatedSourceDeclarations(plan.source, new Set(plan.movedFiles), (old) => plan.placement.renameMap.get(old)?.newFilename),
+        dropped: findDeclarationsMadeUnused({
+            baselineEntries: baseCtx.entries,
+            projectedEntries,
+            baselineIssues: baselineAll,
+            projectedIssues: projectedAll,
+            sourceFilename: plan.source.filename,
+            newFilename: plan.placement.newFilename,
+            mapBack: (name) => oldNameByNew.get(name) ?? name,
+            movedSet: new Set(plan.movedFiles),
+        }),
+    };
     const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
     if (baselineIssues.length > 0 && regressions.length === 0) {
         warn(`Note: projected queue still has ${baselineIssues.length} pre-existing cross-patch ` +
@@ -202,7 +215,7 @@ export function runProjectedSplitLint(plan, baseCtx) {
             reason: `split would introduce ${regressions.length} cross-patch lint error(s)`,
             details: regressions.map(formatPatchLintIssue),
         };
-    return { conflicts, stagedDependencyAdditions };
+    return { conflicts, regressions, stagedDependencyAdditions, stagedMaintenance };
 }
 /** Builds the projected manifest for policy enforcement. */
 export function projectSplitManifest(manifest, plan, newMetadata) {
@@ -222,6 +235,8 @@ export function projectSplitManifest(manifest, plan, newMetadata) {
  * source's provenance (product, version, category) onto the new patch.
  */
 export function buildNewPatchMetadata(plan, config) {
+    const staged = keptRelocatedDeclarations(plan.stagedMaintenance, plan.placement.newFilename);
+    const hasStaged = (staged.forwardImports?.length ?? 0) + (staged.registrations?.length ?? 0) > 0;
     return {
         filename: plan.placement.newFilename,
         order: plan.placement.insertionOrder,
@@ -231,6 +246,7 @@ export function buildNewPatchMetadata(plan, config) {
         createdAt: new Date().toISOString(),
         ...buildPatchSourceMetadata(config.firefox),
         filesAffected: plan.movedFiles,
+        ...(hasStaged ? { stagedDependencies: staged } : {}),
     };
 }
 /**
@@ -253,5 +269,21 @@ export function buildSplitSummary(plan) {
     if (plan.ownerRewrites.length > 0) {
         summary.push(`staged-dependency owners re-pointed to the new patch in: ${plan.ownerRewrites.join(', ')}`);
     }
+    summary.push(...describeStagedMaintenance(plan.stagedMaintenance, plan.source.filename, plan.placement.newFilename));
     return summary;
 }
+/**
+ * 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).
+ */
+export function splitDeclarationRenamer(plan) {
+    const oldNameByNew = new Map([...plan.placement.renameMap].map(([oldName, entry]) => [entry.newFilename, oldName]));
+    const current = (name) => oldNameByNew.get(name) ?? name;
+    return ({ owner, ...declaration }) => ({
+        ...declaration,
+        patch: current(declaration.patch),
+        ...(owner !== plan.placement.newFilename ? { owner: current(owner) } : {}),
+    });
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Staged-dependency upkeep for `patch split` and `patch move-files
+ * --create`: the declarations a file move invalidates.
+ *
+ * Moving files into a new patch changes three kinds of declaration:
+ *
+ *  - an `owner` that named the source for a `creates` path that moved now
+ *    names the new patch (both kinds, see {@link rewriteSplitOwners});
+ *  - a declaration the source holds for a site in a moved file belongs to
+ *    the new patch, because the importing or registering line moved with
+ *    the file ({@link relocatedSourceDeclarations});
+ *  - a declaration that was in use before the move and is not after it
+ *    (the new patch now applies before the importer, or the importer and
+ *    the imported file landed in one patch) is dropped
+ *    ({@link findDeclarationsMadeUnused}).
+ *
+ * Without this the move wrote the bodies and left the queue audit and the
+ * per-patch lint to report `queue-dependency-creates-unowned` and
+ * `staged-dependency-unused` afterwards, one `--remove`/`--add` pair per
+ * entry to repair by hand.
+ */
+import type { PatchQueueEntry } from '../../core/patch-lint.js';
+import type { PatchLintIssue, PatchMetadata, PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../../types/commands/index.js';
+/** One declaration of either kind. */
+export type StagedDeclaration = PatchStagedForwardImport | PatchStagedRegistration;
+/** A declaration the move made unused, named by its post-move holder. */
+export interface DroppedStagedDeclaration {
+    /** Holder patch filename after the move (and any renumber). */
+    holder: string;
+    /** The declaration as the projected queue holds it. */
+    declaration: StagedDeclaration;
+}
+/** Declaration changes a split or `move-files --create` commits. */
+export interface SplitStagedMaintenance {
+    /** Source declarations whose declaring file moved, re-homed on the new patch. */
+    relocated: PatchStagedDependencies;
+    /** Declarations in use before the move and unused after it. */
+    dropped: DroppedStagedDeclaration[];
+}
+/** An empty maintenance plan. */
+export declare function emptyStagedMaintenance(): SplitStagedMaintenance;
+/**
+ * The source's declarations whose declaring file moves, with owners passed
+ * through `ownerLookup` (the renumber the placement implies).
+ *
+ * @param source - The source patch's current manifest row
+ * @param movedSet - Files moving to the new patch
+ * @param ownerLookup - Old → new filename for renumbered patches
+ */
+export declare function relocatedSourceDeclarations(source: PatchMetadata, movedSet: ReadonlySet<string>, ownerLookup: (oldFilename: string) => string | undefined): PatchStagedDependencies;
+/**
+ * Removes from the source row the declarations whose declaring file moved
+ * (they are re-homed on the new patch).
+ */
+export declare function withoutRelocatedDeclarations(source: PatchMetadata, movedSet: ReadonlySet<string>): PatchMetadata;
+/**
+ * Re-points `owner` from the source to the new patch on every declaration
+ * (forward-import and registration alike) whose `creates` path moved.
+ */
+export declare function rewriteSplitOwners(patch: PatchMetadata, sourceFilename: string, movedSet: ReadonlySet<string>, newFilename: string): PatchMetadata;
+/**
+ * Finds patches holding a declaration (either kind) whose `owner` is the
+ * source patch and whose `creates` path moves to the new patch.
+ */
+export declare function findOwnerRewriteHolders(patches: readonly PatchMetadata[], sourceFilename: string, movedSet: ReadonlySet<string>): string[];
+/** Inputs to {@link findDeclarationsMadeUnused}. */
+export interface MadeUnusedInput {
+    /** Queue entries before the move. */
+    baselineEntries: readonly PatchQueueEntry[];
+    /** Queue entries after the move, relocations and owner rewrites applied. */
+    projectedEntries: readonly PatchQueueEntry[];
+    /** Every finding of the baseline queue lint (all severities). */
+    baselineIssues: readonly PatchLintIssue[];
+    /** Every finding of the projected queue lint (all severities). */
+    projectedIssues: readonly PatchLintIssue[];
+    /** Source patch filename before the move. */
+    sourceFilename: string;
+    /** The new patch's filename. */
+    newFilename: string;
+    /** Projected → pre-move filename for renumbered patches. */
+    mapBack: (projectedFilename: string) => string;
+    /** Files moving to the new patch. */
+    movedSet: ReadonlySet<string>;
+}
+/**
+ * Declarations the projected queue reports `staged-dependency-unused` for
+ * that the baseline queue did not: the ones the move itself made unused.
+ * Only declarations the move touches are candidates (their `creates` path
+ * moved, or they were re-homed on the new patch), so pre-existing stale
+ * declarations elsewhere are left for the operator.
+ */
+export declare function findDeclarationsMadeUnused(input: MadeUnusedInput): DroppedStagedDeclaration[];
+/**
+ * Removes the dropped declarations held by `patch` (matched by its
+ * post-move filename and the declaration's projected identity).
+ */
+export declare function withoutDroppedDeclarations(patch: PatchMetadata, dropped: readonly DroppedStagedDeclaration[]): PatchMetadata;
+/** The relocated declarations the new patch keeps (relocated minus dropped). */
+export declare function keptRelocatedDeclarations(maintenance: SplitStagedMaintenance, newFilename: string): PatchStagedDependencies;
+/**
+ * Operator-facing lines naming every declaration the move re-homes or
+ * drops. Empty when the move touches no declaration.
+ *
+ * @param maintenance - The planned changes
+ * @param sourceFilename - Source patch filename
+ * @param newFilename - The new patch's filename
+ */
+export declare function describeStagedMaintenance(maintenance: SplitStagedMaintenance, sourceFilename: string, newFilename: string): string[];

package/dist/src/commands/patch/split-staged.js

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Staged-dependency upkeep for `patch split` and `patch move-files
+ * --create`: the declarations a file move invalidates.
+ *
+ * Moving files into a new patch changes three kinds of declaration:
+ *
+ *  - an `owner` that named the source for a `creates` path that moved now
+ *    names the new patch (both kinds, see {@link rewriteSplitOwners});
+ *  - a declaration the source holds for a site in a moved file belongs to
+ *    the new patch, because the importing or registering line moved with
+ *    the file ({@link relocatedSourceDeclarations});
+ *  - a declaration that was in use before the move and is not after it
+ *    (the new patch now applies before the importer, or the importer and
+ *    the imported file landed in one patch) is dropped
+ *    ({@link findDeclarationsMadeUnused}).
+ *
+ * Without this the move wrote the bodies and left the queue audit and the
+ * per-patch lint to report `queue-dependency-creates-unowned` and
+ * `staged-dependency-unused` afterwards, one `--remove`/`--add` pair per
+ * entry to repair by hand.
+ */
+import { stagedDependencyUnusedFingerprint } from '../../core/patch-lint-staged-registration.js';
+/** An empty maintenance plan. */
+export function emptyStagedMaintenance() {
+    return { relocated: {}, dropped: [] };
+}
+function declarationsOf(staged) {
+    return [...(staged?.forwardImports ?? []), ...(staged?.registrations ?? [])];
+}
+function matcherOf(declaration) {
+    return 'specifier' in declaration ? `i:${declaration.specifier}` : `r:${declaration.line}`;
+}
+/** Identity of a declaration, owner included. */
+function declarationKey(declaration) {
+    return [
+        declaration.file,
+        matcherOf(declaration),
+        declaration.creates,
+        declaration.owner ?? '',
+    ].join('\0');
+}
+/** Identity without the owner, which a renumber or split may rewrite. */
+function declarationSiteKey(declaration) {
+    return [declaration.file, matcherOf(declaration), declaration.creates].join('\0');
+}
+function rebuildStaged(staged, keep, rewrite = (declaration) => declaration) {
+    const forwardImports = (staged?.forwardImports ?? [])
+        .filter(keep)
+        .map((entry) => rewrite(entry));
+    const registrations = (staged?.registrations ?? [])
+        .filter(keep)
+        .map((entry) => rewrite(entry));
+    return {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(registrations.length > 0 ? { registrations } : {}),
+    };
+}
+function hasDeclarations(staged) {
+    return declarationsOf(staged).length > 0;
+}
+/** Writes `staged` onto `patch`, dropping the field when it is empty. */
+function withStaged(patch, staged) {
+    if (hasDeclarations(staged))
+        return { ...patch, stagedDependencies: staged };
+    if (patch.stagedDependencies === undefined)
+        return patch;
+    const rest = { ...patch };
+    delete rest.stagedDependencies;
+    return rest;
+}
+/**
+ * The source's declarations whose declaring file moves, with owners passed
+ * through `ownerLookup` (the renumber the placement implies).
+ *
+ * @param source - The source patch's current manifest row
+ * @param movedSet - Files moving to the new patch
+ * @param ownerLookup - Old → new filename for renumbered patches
+ */
+export function relocatedSourceDeclarations(source, movedSet, ownerLookup) {
+    return rebuildStaged(source.stagedDependencies, (declaration) => movedSet.has(declaration.file), (declaration) => {
+        const owner = declaration.owner === undefined ? undefined : ownerLookup(declaration.owner);
+        return owner === undefined ? { ...declaration } : { ...declaration, owner };
+    });
+}
+/**
+ * Removes from the source row the declarations whose declaring file moved
+ * (they are re-homed on the new patch).
+ */
+export function withoutRelocatedDeclarations(source, movedSet) {
+    if (!declarationsOf(source.stagedDependencies).some((d) => movedSet.has(d.file)))
+        return source;
+    return withStaged(source, rebuildStaged(source.stagedDependencies, (declaration) => !movedSet.has(declaration.file)));
+}
+/**
+ * Re-points `owner` from the source to the new patch on every declaration
+ * (forward-import and registration alike) whose `creates` path moved.
+ */
+export function rewriteSplitOwners(patch, sourceFilename, movedSet, newFilename) {
+    const matches = (declaration) => declaration.owner === sourceFilename && movedSet.has(declaration.creates);
+    if (!declarationsOf(patch.stagedDependencies).some(matches))
+        return patch;
+    return {
+        ...patch,
+        stagedDependencies: {
+            ...patch.stagedDependencies,
+            ...rebuildStaged(patch.stagedDependencies, () => true, (declaration) => matches(declaration) ? { ...declaration, owner: newFilename } : declaration),
+        },
+    };
+}
+/**
+ * Finds patches holding a declaration (either kind) whose `owner` is the
+ * source patch and whose `creates` path moves to the new patch.
+ */
+export function findOwnerRewriteHolders(patches, sourceFilename, movedSet) {
+    return patches
+        .filter((patch) => declarationsOf(patch.stagedDependencies).some((declaration) => declaration.owner === sourceFilename && movedSet.has(declaration.creates)))
+        .map((patch) => patch.filename);
+}
+/**
+ * Declarations the projected queue reports `staged-dependency-unused` for
+ * that the baseline queue did not: the ones the move itself made unused.
+ * Only declarations the move touches are candidates (their `creates` path
+ * moved, or they were re-homed on the new patch), so pre-existing stale
+ * declarations elsewhere are left for the operator.
+ */
+export function findDeclarationsMadeUnused(input) {
+    const unusedFingerprints = (issues) => new Set(issues
+        .filter((issue) => issue.check === 'staged-dependency-unused')
+        .map((issue) => issue.fingerprint ?? ''));
+    const baselineUnused = unusedFingerprints(input.baselineIssues);
+    const projectedUnused = unusedFingerprints(input.projectedIssues);
+    const baselineByHolder = new Map(input.baselineEntries.map((entry) => [entry.filename, entry.metadata]));
+    const dropped = [];
+    for (const entry of input.projectedEntries) {
+        const isNewPatch = entry.filename === input.newFilename;
+        for (const declaration of declarationsOf(entry.metadata?.stagedDependencies)) {
+            if (!isNewPatch && !input.movedSet.has(declaration.creates))
+                continue;
+            if (!projectedUnused.has(stagedDependencyUnusedFingerprint(entry.filename, declaration))) {
+                continue;
+            }
+            const originalHolder = isNewPatch ? input.sourceFilename : input.mapBack(entry.filename);
+            const original = declarationsOf(baselineByHolder.get(originalHolder)?.stagedDependencies).find((candidate) => declarationSiteKey(candidate) === declarationSiteKey(declaration));
+            if (original !== undefined &&
+                baselineUnused.has(stagedDependencyUnusedFingerprint(originalHolder, original))) {
+                continue;
+            }
+            dropped.push({ holder: entry.filename, declaration });
+        }
+    }
+    return dropped;
+}
+/**
+ * Removes the dropped declarations held by `patch` (matched by its
+ * post-move filename and the declaration's projected identity).
+ */
+export function withoutDroppedDeclarations(patch, dropped) {
+    const keys = new Set(dropped
+        .filter((entry) => entry.holder === patch.filename)
+        .map((entry) => declarationKey(entry.declaration)));
+    if (keys.size === 0)
+        return patch;
+    return withStaged(patch, rebuildStaged(patch.stagedDependencies, (declaration) => !keys.has(declarationKey(declaration))));
+}
+/** The relocated declarations the new patch keeps (relocated minus dropped). */
+export function keptRelocatedDeclarations(maintenance, newFilename) {
+    const keys = new Set(maintenance.dropped
+        .filter((entry) => entry.holder === newFilename)
+        .map((entry) => declarationKey(entry.declaration)));
+    return rebuildStaged(maintenance.relocated, (declaration) => !keys.has(declarationKey(declaration)));
+}
+function describeDeclaration(declaration) {
+    return 'specifier' in declaration
+        ? `${declaration.file} imports "${declaration.specifier}" (${declaration.creates})`
+        : `${declaration.file} registers "${declaration.line}" (${declaration.creates})`;
+}
+/**
+ * Operator-facing lines naming every declaration the move re-homes or
+ * drops. Empty when the move touches no declaration.
+ *
+ * @param maintenance - The planned changes
+ * @param sourceFilename - Source patch filename
+ * @param newFilename - The new patch's filename
+ */
+export function describeStagedMaintenance(maintenance, sourceFilename, newFilename) {
+    const lines = [];
+    const kept = declarationsOf(keptRelocatedDeclarations(maintenance, newFilename));
+    if (kept.length > 0) {
+        lines.push(`staged-dependency declarations moved from ${sourceFilename} to ${newFilename} (${kept.length}):`);
+        for (const declaration of kept)
+            lines.push(`  ${describeDeclaration(declaration)}`);
+    }
+    if (maintenance.dropped.length > 0) {
+        lines.push(`staged-dependency declarations dropped because the move made them unused (${maintenance.dropped.length}):`);
+        for (const { holder, declaration } of maintenance.dropped) {
+            const shownHolder = holder === newFilename ? `${sourceFilename} → ${newFilename}` : holder;
+            lines.push(`  ${shownHolder}: ${describeDeclaration(declaration)}`);
+        }
+    }
+    return lines;
+}

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

@@ -19,6 +19,11 @@ import type { CommandContext } from '../../types/cli.js';
 import type { PatchMetadata, PatchSplitOptions } from '../../types/commands/index.js';
 import type { FireForgeConfig } from '../../types/config.js';
 import { type SplitPlan } from './split-plan.js';
+/**
+ * Prints the owner rewrites and the declarations the move re-homed or
+ * dropped, after a committed split or `move-files --create`.
+ */
+export declare function reportSplitStagedChanges(plan: SplitPlan): void;
 /**
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest