@hominis/fireforge 0.52.0 → 0.54.0

package/dist/src/commands/patch/move-files-retire.js

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `patch move-files --retire-empty`: fold every file of a patch into
+ * another and retire the emptied patch's slot in the same transaction.
+ *
+ * Without the flag `move-files` refuses to empty the source, and
+ * `patch retire` on an emptied patch refuses while another patch's
+ * declaration still names it as the owner. With the flag the move re-points
+ * those declarations to the destination first (after the fold the
+ * destination creates every file the source did), carries the source's own declarations over with its files, and then
+ * retires the source the way `patch retire` does: the row and `.patch` file
+ * leave, and the order stays spent as a `patches.json#retired` slot so
+ * `patchPolicy.allowGaps: false` sees no gap.
+ */
+import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.js';
+/**
+ * Concatenates declaration lists without duplicates, dropping every entry
+ * owned by `destination` itself: after the fold the file it waits for
+ * arrives in the same patch, so it is no longer a forward edge.
+ */
+function foldDeclarations(lists, destination) {
+    const keys = new Set();
+    const merged = [];
+    for (const entry of lists.flatMap((list) => list ?? [])) {
+        if (entry.owner === destination)
+            continue;
+        const key = JSON.stringify(entry);
+        if (keys.has(key))
+            continue;
+        keys.add(key);
+        merged.push(entry);
+    }
+    return merged;
+}
+/** The destination row carrying its own and the source's declarations. */
+function foldStaged(destination, source) {
+    const own = destination.stagedDependencies;
+    const forwardImports = foldDeclarations([own?.forwardImports, source?.forwardImports], destination.filename);
+    const registrations = foldDeclarations([own?.registrations, source?.registrations], destination.filename);
+    const folded = { ...destination };
+    delete folded.stagedDependencies;
+    if (forwardImports.length === 0 && registrations.length === 0)
+        return folded;
+    folded.stagedDependencies = {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(registrations.length > 0 ? { registrations } : {}),
+    };
+    return folded;
+}
+/**
+ * Re-points every declaration whose owner is `source` to `destination` and
+ * carries the source's own declarations onto the destination. The source
+ * row is returned unchanged; the caller retires it.
+ *
+ * @param patches - Manifest rows
+ * @param source - Filename of the patch the fold empties
+ * @param destination - Filename of the patch that receives its files
+ */
+export function foldSourceRows(patches, source, destination) {
+    const lookup = (owner) => owner === source ? destination : undefined;
+    const sourceRow = patches.find((patch) => patch.filename === source);
+    const sourceStaged = sourceRow
+        ? rewriteStagedDependencyOwners(sourceRow, lookup).stagedDependencies
+        : undefined;
+    const repointed = [];
+    const rows = patches.map((patch) => {
+        if (patch.filename === source)
+            return patch;
+        const rewritten = rewriteStagedDependencyOwners(patch, lookup);
+        if (rewritten !== patch)
+            repointed.push(patch.filename);
+        return patch.filename === destination ? foldStaged(rewritten, sourceStaged) : rewritten;
+    });
+    return { patches: rows, repointed };
+}
+/**
+ * The retired slot the emptied source leaves, shaped as `patch retire`
+ * writes it.
+ *
+ * @param source - The emptied source row
+ * @param destination - Filename of the patch that took its files
+ */
+export function retiredSlotForFold(source, destination) {
+    return {
+        order: source.order,
+        category: source.category,
+        filename: source.filename,
+        retiredAt: new Date().toISOString(),
+        reason: `folded into ${destination} by patch move-files --retire-empty`,
+    };
+}

package/dist/src/commands/patch/move-files.d.ts

@@ -3,6 +3,9 @@
  * re-export choreography needed to move file ownership between two
  * patches. With `--create --order <n>` the target patch is created and
  * the files move into it as one transaction (see move-files-create.ts).
+ * `--scan-file` adopts new, unowned engine files into the destination in
+ * the same transaction, and `--retire-empty` lets the move empty the
+ * source and retire its slot.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';

package/dist/src/commands/patch/move-files.js

@@ -4,6 +4,9 @@
  * re-export choreography needed to move file ownership between two
  * patches. With `--create --order <n>` the target patch is created and
  * the files move into it as one transaction (see move-files-create.ts).
+ * `--scan-file` adopts new, unowned engine files into the destination in
+ * the same transaction, and `--retire-empty` lets the move empty the
+ * source and retire its slot.
  */
 import { relative } from 'node:path';
 import { Command } from 'commander';
@@ -15,6 +18,7 @@ import { pathExists } from '../../utils/fs.js';
 import { info, intro, note, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, stringListOption, } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { resolveAdoptedFiles } from './move-files-adopt.js';
 import { patchMoveFilesCreateCommand } from './move-files-create.js';
 import { runMoveFilesInto } from './move-files-into.js';
 function normalizeFileList(files) {
@@ -53,13 +57,25 @@ function assertTargetDoesNotAlreadyOwnFiles(target, files) {
         return;
     throw new InvalidArgumentError(`${target.filename} already owns ${duplicates.length} requested file(s):\n${formatFiles(duplicates)}`, 'patch move-files');
 }
-function computeFileMovePlan(source, target, files) {
+function computeFileMovePlan(source, target, files, adoptedFiles) {
     const moved = new Set(files);
     return {
         sourceAfter: source.filesAffected.filter((file) => !moved.has(file)).sort(),
-        targetAfter: [...new Set([...target.filesAffected, ...files])].sort(),
+        targetAfter: [...new Set([...target.filesAffected, ...files, ...adoptedFiles])].sort(),
     };
 }
+/** Refuses a move that empties the source unless `--retire-empty` asks for it, and the flag on a move that does not. */
+function assertEmptySourceIntent(source, sourceAfter, retireEmpty) {
+    if (sourceAfter.length === 0 && !retireEmpty) {
+        throw new InvalidArgumentError(`${source.filename} would have no filesAffected after this move. Pass --retire-empty to ` +
+            'fold it into the destination in one transaction: the declarations it owns re-point to ' +
+            'the destination and its order stays spent as a retired slot.', 'patch move-files');
+    }
+    if (sourceAfter.length > 0 && retireEmpty) {
+        throw new InvalidArgumentError(`--retire-empty applies only to a move that empties the source; ${source.filename} would ` +
+            `keep ${sourceAfter.length} file(s).`, '--retire-empty');
+    }
+}
 /**
  * Builds and prints a safe, no-write file ownership move plan.
  *
@@ -75,6 +91,10 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     if (options.create !== true && options.order !== undefined) {
         throw new InvalidArgumentError('--order is only valid together with --create.', '--order');
     }
+    if (options.create === true && options.retireEmpty === true) {
+        throw new InvalidArgumentError('--retire-empty folds the source into an existing patch. To move a whole patch to a new ' +
+            'name or order, use "fireforge patch rename" or "fireforge patch reorder".', '--retire-empty');
+    }
     if (options.create === true && options.order !== undefined) {
         await patchMoveFilesCreateCommand(projectRoot, fromIdentifier, toIdentifier, {
             ...options,
@@ -111,10 +131,10 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     }
     assertPatchHasFiles(source, files);
     assertTargetDoesNotAlreadyOwnFiles(target, files);
-    const { sourceAfter, targetAfter } = computeFileMovePlan(source, target, files);
-    if (sourceAfter.length === 0) {
-        throw new InvalidArgumentError(`${source.filename} would have no filesAffected after this move. Delete or re-export that patch explicitly instead.`, 'patch move-files');
-    }
+    const adoptedFiles = await resolveAdoptedFiles(options.scanFile, manifest.patches, paths.engine, files);
+    const { sourceAfter, targetAfter } = computeFileMovePlan(source, target, files, adoptedFiles);
+    const retireSource = options.retireEmpty === true;
+    assertEmptySourceIntent(source, sourceAfter, retireSource);
     for (const file of files) {
         if (!(await pathExists(`${paths.engine}/${file}`))) {
             warn(`engine/${file} does not exist in the current worktree; re-export may drop or fail it.`);
@@ -124,19 +144,23 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
     info(`Moving ownership in ${relativePatchesDir}/patches.json.`);
     info(`Move ${files.length} file(s) from ${source.filename} to ${target.filename}:`);
     note(formatFiles(files), 'Files');
-    note(formatFiles(sourceAfter), `${source.filename} files after move`);
+    if (adoptedFiles.length > 0)
+        note(formatFiles(adoptedFiles), 'Adopted new files');
+    note(retireSource ? '(none: retired)' : formatFiles(sourceAfter), `${source.filename} files after move`);
     note(formatFiles(targetAfter), `${target.filename} files after move`);
     // Manual fallback (e.g. when the worktree cannot carry both patches'
     // content right now): the equivalent re-export choreography, in
     // executable order. The shrink must land before the grow, or the
     // projected cross-patch lint refuses the pair with
     // duplicate-new-file-creation.
-    const applySource = formatReExportCommand(source.filename, sourceAfter, [
-        '--allow-shrink',
-        '--yes',
-    ]);
     const applyTarget = formatReExportCommand(target.filename, targetAfter, ['--yes']);
-    note(`1. ${applySource}\n2. ${applyTarget}\n(the shrink must land first)`, 'Equivalent manual commands');
+    if (!retireSource) {
+        const applySource = formatReExportCommand(source.filename, sourceAfter, [
+            '--allow-shrink',
+            '--yes',
+        ]);
+        note(`1. ${applySource}\n2. ${applyTarget}\n(the shrink must land first)`, 'Equivalent manual commands');
+    }
     const config = await loadConfig(projectRoot);
     await runMoveFilesInto({
         enginePath: paths.engine,
@@ -146,6 +170,8 @@ export async function patchMoveFilesCommand(projectRoot, fromIdentifier, toIdent
         files,
         sourceAfter,
         targetAfter,
+        adoptedFiles,
+        retireSource,
         options,
         config,
     });
@@ -171,6 +197,8 @@ export function registerPatchMoveFiles(parent, context) {
         .option('-d, --description <desc>', 'Description for the created patch')
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
+        .option('--scan-file <path>', 'New engine file no patch owns, adopted into <to> in the same transaction (repeatable)', ...stringListOption())
+        .option('--retire-empty', 'Allow the move to empty <from>: re-point the declarations it owns to <to> and retire its slot')
         .option('--force-unsafe', 'Bypass projected-lint refusals')
         .option('--skip-lint', 'Skip per-patch lint of the projected bodies')
         .option('--declarations-out <path>', 'Where a refusal writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json)');
@@ -187,6 +215,8 @@ export function registerPatchMoveFiles(parent, context) {
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
                 declarationsOut: options.declarationsOut,
+                scanFile: options.scanFile,
+                retireEmpty: options.retireEmpty,
                 waitLock: options.waitLock,
             }),
         });

package/dist/src/commands/patch/move-size-tier.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Names a patch-size tier change in a move's lint refusal.
+ *
+ * `large-patch-lines` judges a patch by its tier: a patch of test files
+ * only is held to the test tier, everything else to the general tier
+ * (with test lines split out under `addedCode`). A move that takes a
+ * source's last product file out turns it into a test-only patch, and the
+ * test tier then counts every line against its own ceiling, where a
+ * `share: "test"` waiver no longer applies. A plain size error would hide
+ * that reordering the moves (tests first) fixes it, so the wrapper below appends which tier the patch moves into, its count and the
+ * ceiling that count is held to.
+ */
+import { type RunPatchLintOptions } from '../export-shared.js';
+/** One side of a move, linted on its post-transaction body. */
+export interface MoveSideLintOptions extends RunPatchLintOptions {
+    /** The patch's files before the move; absent for a patch the move creates. */
+    filesBefore?: readonly string[];
+    /** How the refusal names the patch (`source`, `destination`). */
+    role: string;
+}
+/**
+ * Runs {@link runPatchLint} on one side of a move and, when the lint
+ * refuses, appends {@link describeMoveTierChange}'s line to the refusal.
+ *
+ * @param options - The side's lint options, its files before the move and its role
+ */
+export declare function runMoveSideLint(options: MoveSideLintOptions): Promise<void>;

package/dist/src/commands/patch/move-size-tier.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Names a patch-size tier change in a move's lint refusal.
+ *
+ * `large-patch-lines` judges a patch by its tier: a patch of test files
+ * only is held to the test tier, everything else to the general tier
+ * (with test lines split out under `addedCode`). A move that takes a
+ * source's last product file out turns it into a test-only patch, and the
+ * test tier then counts every line against its own ceiling, where a
+ * `share: "test"` waiver no longer applies. A plain size error would hide
+ * that reordering the moves (tests first) fixes it, so the wrapper below appends which tier the patch moves into, its count and the
+ * ceiling that count is held to.
+ */
+import { getPatchSizeThresholds, measurePatchSize, resolvePatchSizeTier, } from '../../core/patch-lint-size.js';
+import { GeneralError } from '../../errors/base.js';
+import { runPatchLint } from '../export-shared.js';
+/**
+ * Describes a tier change that leaves the patch above the new tier's
+ * `large-patch-lines` error ceiling, or returns undefined when the tier
+ * does not change, the rule is waived, or the count fits.
+ *
+ * @param options - The side's lint options and its files before the move
+ */
+async function describeMoveTierChange(options) {
+    const { filesBefore, filesAffected, patchTier, ignoreChecks, config } = options;
+    if (filesBefore === undefined || ignoreChecks?.has('large-patch-lines') === true) {
+        return undefined;
+    }
+    const before = resolvePatchSizeTier(filesBefore, patchTier).tier;
+    const after = resolvePatchSizeTier(filesAffected, patchTier).tier;
+    if (before === after)
+        return undefined;
+    const measurement = await measurePatchSize(options.engineDir, options.diffContent, filesAffected, config);
+    // Under `addedCode` a general-tier patch holds only its non-test lines to
+    // the general ceiling (the test lines meet the test tier's).
+    const count = measurement.metric === 'addedCode' && after === 'general'
+        ? measurement.lines - measurement.testLines
+        : measurement.lines;
+    const limit = getPatchSizeThresholds(after, config).lines.error;
+    if (count <= limit)
+        return undefined;
+    const advice = after === 'test'
+        ? 'Move its test files out before its last product file (or in the same move), ' +
+            'so it never stands as a test-only patch above that ceiling.'
+        : 'Order the moves so it does not change tier while above that ceiling.';
+    return `Tier change: the ${options.role} becomes ${after} tier (it was ${before} tier): ${count} lines against ${limit}. ${advice}`;
+}
+/**
+ * Runs {@link runPatchLint} on one side of a move and, when the lint
+ * refuses, appends {@link describeMoveTierChange}'s line to the refusal.
+ *
+ * @param options - The side's lint options, its files before the move and its role
+ */
+export async function runMoveSideLint(options) {
+    try {
+        await runPatchLint(options);
+    }
+    catch (error) {
+        if (!(error instanceof GeneralError))
+            throw error;
+        const note = await describeMoveTierChange(options);
+        if (note === undefined)
+            throw error;
+        throw new GeneralError(`${error.message}\n${note}`);
+    }
+}

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

@@ -35,7 +35,7 @@ import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeco
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
-import { projectReorder } from './reorder.js';
+import { projectReorder } from './reorder-projection.js';
 /**
  * Pulls the ordinal-string + category prefix out of a patch filename so
  * the rename keeps the existing ordinal padding verbatim. Returning the

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

@@ -0,0 +1,17 @@
+/**
+ * Rename-map helpers shared by `patch reorder` (single-patch moves and
+ * `--shift`), `patch compact` and `patch rename --order`: the filename a
+ * patch takes at a new order, and the queue context projected through a
+ * rename map for cross-patch lint.
+ */
+import type { PatchQueueContext } from '../../core/patch-lint.js';
+import { type PatchRenameEntry } from '../../core/patch-manifest.js';
+import type { PatchMetadata } 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;

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

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Rename-map helpers shared by `patch reorder` (single-patch moves and
+ * `--shift`), `patch compact` and `patch rename --order`: the filename a
+ * patch takes at a new order, and the queue context projected through a
+ * rename map for cross-patch lint.
+ */
+import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.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}`;
+}
+/**
+ * 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 };
+}

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

@@ -0,0 +1,30 @@
+/**
+ * `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 type { PatchReorderOptions } from '../../types/commands/index.js';
+/**
+ * Runs `patch reorder --shift <n> --from <order> [--through <order>]`.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - Reorder options with `shift` and `from` set
+ */
+export declare function patchReorderShiftCommand(projectRoot: string, options: PatchReorderOptions & {
+    shift: number;
+    from: number;
+}): Promise<void>;