@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -22,19 +22,47 @@ import { assertConfirmationAvailable, confirmDestructive } from '../../core/dest
 import { appendHistoryBestEffort } from '../../core/history-log.js';
 import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext } from '../../core/patch-lint.js';
+import { buildLintIgnoreChecks } from '../../core/patch-lint-ignore.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
 import { enforcePatchPolicy } from '../../core/patch-policy.js';
+import { manifestWithRetiredSlots } from '../../core/patch-retired.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { readText, removeFile, writeText } from '../../utils/fs.js';
 import { info, intro, outro, success, warn } from '../../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../../utils/options.js';
 import { normalizePatchDisplayName, parsePositiveIntegerFlag } from '../../utils/validation.js';
+import { withDeclarationsReport } from '../declarations-report.js';
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { placementPlansEqual, resolvePlacementPlan } from '../export-flow.js';
 import { runPatchLint } from '../export-shared.js';
-import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, findOwnerRewriteHolders, mergeStagedForwardImports, projectSplitManifest, rewriteSplitOwners, runProjectedSplitLint, } from './split-plan.js';
+import { assertSourceOwnsFiles, buildNewPatchMetadata, buildSplitDiff, buildSplitSummary, mergeStagedForwardImports, projectSplitManifest, runProjectedSplitLint, splitDeclarationRenamer, } from './split-plan.js';
+import { describeStagedMaintenance, emptyStagedMaintenance, findOwnerRewriteHolders, rewriteSplitOwners, withoutDroppedDeclarations, withoutRelocatedDeclarations, } from './split-staged.js';
+/**
+ * History payload for the declarations a split re-homed or dropped, omitted
+ * when it touched none so unaffected records keep their old shape.
+ */
+function stagedMaintenanceHistory(plan) {
+    const { relocated, dropped } = plan.stagedMaintenance;
+    const relocatedCount = (relocated.forwardImports?.length ?? 0) + (relocated.registrations?.length ?? 0);
+    return {
+        ...(relocatedCount > 0 ? { relocatedDeclarations: relocated } : {}),
+        ...(dropped.length > 0 ? { droppedDeclarations: dropped } : {}),
+    };
+}
+/**
+ * Prints the owner rewrites and the declarations the move re-homed or
+ * dropped, after a committed split or `move-files --create`.
+ */
+export function reportSplitStagedChanges(plan) {
+    if (plan.ownerRewrites.length > 0) {
+        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
+    }
+    for (const line of describeStagedMaintenance(plan.stagedMaintenance, plan.source.filename, plan.placement.newFilename)) {
+        info(line);
+    }
+}
 /**
  * Commits a confirmed split under the patch directory lock: renumber →
  * write new patch body → write shrunken source body → single manifest
@@ -84,13 +112,17 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
                 if (decls?.length) {
                     withOwners = mergeStagedForwardImports(withOwners, decls);
                 }
+                withOwners = withoutDroppedDeclarations(withOwners, plan.stagedMaintenance.dropped);
                 if (patch.filename !== effectiveSourceFilename)
                     return withOwners;
-                return { ...withOwners, filesAffected: plan.remainingFiles };
+                return {
+                    ...withoutRelocatedDeclarations(withOwners, movedSet),
+                    filesAffected: plan.remainingFiles,
+                };
             });
             updatedPatches.push(newMetadata);
             updatedPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-            const updated = validatePatchesManifest({ ...fresh, patches: updatedPatches });
+            const updated = validatePatchesManifest(manifestWithRetiredSlots(fresh, updatedPatches));
             await savePatchesManifest(patchesDir, updated);
             await appendHistoryBestEffort(patchesDir, {
                 operation: 'patch-split',
@@ -100,6 +132,7 @@ export async function commitPatchSplit(patchesDir, plan, newMetadata, options, c
                     order: plan.placement.insertionOrder,
                     files: plan.movedFiles,
                     ownerRewrites: plan.ownerRewrites,
+                    ...stagedMaintenanceHistory(plan),
                     renames: [...plan.placement.renameMap.entries()].map(([from, entry]) => ({
                         from,
                         to: entry.newFilename,
@@ -212,16 +245,27 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         name: displayName,
         description: options.description ?? '',
         ownerRewrites: findOwnerRewriteHolders(manifest.patches, source.filename, movedSet),
-        // Populated by runProjectedSplitLint below (forward edges into the new patch).
+        // Populated by runProjectedSplitLint below (forward edges into the new
+        // patch, and the declarations the move re-homes or makes unused).
         stagedDependencyAdditions: new Map(),
+        stagedMaintenance: emptyStagedMaintenance(),
     };
+    // Policy first: the projected manifest (orders, ranges, the gap rule)
+    // does not depend on the lint below, so a refused --order fails before
+    // the per-patch and projected lint passes instead of after them.
+    enforcePatchPolicy({
+        config,
+        manifest: projectSplitManifest(manifest, plan, buildNewPatchMetadata(plan, config)),
+        command: 'patch split',
+        forceUnsafe: options.forceUnsafe === true,
+    });
     // Per-patch lint both projected bodies, threading the source patch's
     // tier/lintIgnore so an intentional-advisory patch can still split.
     // The whole-queue context (built once, with the config for committed-gate
     // parity) resolves cross-patch imports and sibling head.js harness roots
     // instead of linting each projected body blind.
     const patchQueueCtx = await buildPatchQueueContext(paths.patches, config);
-    const ignoreChecks = source.lintIgnore ? new Set(source.lintIgnore) : undefined;
+    const ignoreChecks = buildLintIgnoreChecks(source.lintIgnore);
     await runPatchLint({
         engineDir: paths.engine,
         filesAffected: remainingFiles,
@@ -242,15 +286,16 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         ignoreChecks,
         patchTier: source.tier,
     });
-    const { conflicts, stagedDependencyAdditions } = runProjectedSplitLint(plan, patchQueueCtx);
-    plan.stagedDependencyAdditions = stagedDependencyAdditions;
-    const newMetadata = buildNewPatchMetadata(plan, config);
-    enforcePatchPolicy({
-        config,
-        manifest: projectSplitManifest(manifest, plan, newMetadata),
-        command: 'patch split',
-        forceUnsafe: options.forceUnsafe === true,
+    const projected = runProjectedSplitLint(plan, patchQueueCtx);
+    plan.stagedDependencyAdditions = projected.stagedDependencyAdditions;
+    plan.stagedMaintenance = projected.stagedMaintenance;
+    const conflicts = await withDeclarationsReport(projected.conflicts, {
+        projectRoot,
+        regressions: projected.regressions,
+        out: options.declarationsOut,
+        rename: splitDeclarationRenamer(plan),
     });
+    const newMetadata = buildNewPatchMetadata(plan, config);
     const decision = await confirmDestructive({
         operation: 'patch-split',
         title: `Split ${plan.movedFiles.length} file(s) out of ${source.filename} into ${placement.newFilename}`,
@@ -264,9 +309,7 @@ export async function patchSplitCommand(projectRoot, sourceId, options) {
         return;
     await commitPatchSplit(paths.patches, plan, newMetadata, options, config);
     success(`Split ${source.filename}: ${placement.newFilename} now owns ${plan.movedFiles.length} file(s)`);
-    if (plan.ownerRewrites.length > 0) {
-        info(`Re-pointed staged-dependency owners in: ${plan.ownerRewrites.join(', ')}`);
-    }
+    reportSplitStagedChanges(plan);
     outro('Split complete');
 }
 /**
@@ -287,7 +330,8 @@ export function registerPatchSplit(parent, context) {
         .option('--dry-run', 'Show what would happen without writing')
         .option('-y, --yes', 'Skip confirmation prompt (required for non-TTY)')
         .option('--force-unsafe', 'Bypass projected-lint refusals')
-        .option('--skip-lint', 'Skip per-patch lint of the projected bodies');
+        .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)');
     addWaitLockOption(command).action(withErrorHandling(async (sourceId, options) => {
         await patchSplitCommand(getProjectRoot(), sourceId, {
             files: options.files,
@@ -302,6 +346,7 @@ export function registerPatchSplit(parent, context) {
                 yes: options.yes,
                 forceUnsafe: options.forceUnsafe,
                 skipLint: options.skipLint,
+                declarationsOut: options.declarationsOut,
                 waitLock: options.waitLock,
             }),
         });

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

@@ -0,0 +1,34 @@
+/**
+ * `fireforge patch stage <name>...`: stages the named patches' `.patch`
+ * files and only their rows of `patches/patches.json` in the project
+ * repository's git index.
+ *
+ * The case it exists for: several sessions edit one checkout's queue, and
+ * each must commit only its own patches. Staging the whole manifest takes
+ * every session's rows; staging one owner's hunks of it with
+ * `git apply --cached --unidiff-zero` placed a kept insertion at its
+ * new-side line number once a dropped hunk above had shifted the file, and
+ * an invalid manifest was committed. This command builds the staged
+ * manifest from HEAD's rows plus the named working rows (see
+ * `core/patch-manifest-stage.ts`), validates it, and writes it straight to
+ * the index with `git hash-object` + `git update-index`. The working copy
+ * is never touched, and nothing is committed.
+ */
+import { Command } from 'commander';
+import type { CommandContext } from '../../types/cli.js';
+import type { PatchStageOptions } from '../../types/commands/index.js';
+/**
+ * Runs the `patch stage` command.
+ *
+ * @param projectRoot - Project root directory (a git working tree)
+ * @param identifiers - Patch filenames, ordinals or names to stage
+ * @param options - Command options
+ */
+export declare function patchStageCommand(projectRoot: string, identifiers: readonly string[], options?: PatchStageOptions): Promise<void>;
+/**
+ * Registers the `patch stage` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export declare function registerPatchStage(parent: Command, context: CommandContext): void;

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

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge patch stage <name>...`: stages the named patches' `.patch`
+ * files and only their rows of `patches/patches.json` in the project
+ * repository's git index.
+ *
+ * The case it exists for: several sessions edit one checkout's queue, and
+ * each must commit only its own patches. Staging the whole manifest takes
+ * every session's rows; staging one owner's hunks of it with
+ * `git apply --cached --unidiff-zero` placed a kept insertion at its
+ * new-side line number once a dropped hunk above had shifted the file, and
+ * an invalid manifest was committed. This command builds the staged
+ * manifest from HEAD's rows plus the named working rows (see
+ * `core/patch-manifest-stage.ts`), validates it, and writes it straight to
+ * the index with `git hash-object` + `git update-index`. The working copy
+ * is never touched, and nothing is committed.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { Command } from 'commander';
+import { getProjectPaths } from '../../core/config.js';
+import { git } from '../../core/git-base.js';
+import { withPatchDirectoryLock } from '../../core/patch-lock.js';
+import { loadPatchesManifestForWrite, resolvePatchIdentifier, validatePatchesManifest, } from '../../core/patch-manifest.js';
+import { mergeStagedManifest, serializeStagedManifest, } from '../../core/patch-manifest-stage.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { pathExists } from '../../utils/fs.js';
+import { info, intro, outro } from '../../utils/logger.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../utils/options.js';
+import { exec } from '../../utils/process.js';
+/** A project-relative path in git's separator. */
+function gitPath(projectRoot, path) {
+    return relative(projectRoot, path).split(sep).join('/');
+}
+/** HEAD's manifest, or null when HEAD has none (or there is no HEAD yet). */
+async function readHeadManifest(projectRoot, manifestPath) {
+    const shown = await exec('git', ['show', `HEAD:./${manifestPath}`], { cwd: projectRoot });
+    if (shown.exitCode !== 0)
+        return null;
+    try {
+        return validatePatchesManifest(JSON.parse(shown.stdout));
+    }
+    catch (error) {
+        throw new GeneralError(`HEAD's ${manifestPath} is not a valid manifest (${toError(error).message}); stage it by hand.`);
+    }
+}
+/** Resolves each identifier to a filename, against the working rows then HEAD's. */
+function resolveFilenames(identifiers, working, head) {
+    const filenames = new Set();
+    for (const identifier of identifiers) {
+        const live = resolvePatchIdentifier(identifier, working.patches);
+        // A patch deleted (or renamed away) in the working copy is named by its
+        // HEAD filename, so its row can be staged as removed.
+        const gone = (head?.patches ?? []).find((row) => row.filename === identifier || row.filename === `${identifier}.patch`);
+        const filename = live?.filename ?? gone?.filename;
+        if (filename === undefined) {
+            throw new InvalidArgumentError(`No patch "${identifier}" in the working manifest or at HEAD.`, identifier);
+        }
+        filenames.add(filename);
+    }
+    return filenames;
+}
+/** Stages one `.patch` file: its content, or its removal when it is gone. */
+async function stagePatchFile(projectRoot, patchPath) {
+    if (await pathExists(join(projectRoot, patchPath))) {
+        await git(['add', '--', patchPath], projectRoot);
+        return;
+    }
+    const tracked = await exec('git', ['ls-files', '--error-unmatch', '--', patchPath], {
+        cwd: projectRoot,
+    });
+    if (tracked.exitCode === 0) {
+        await git(['rm', '--cached', '--quiet', '--', patchPath], projectRoot);
+    }
+}
+/** Writes `content` as a blob and points the index entry at it. */
+async function stageBlob(projectRoot, path, content) {
+    const scratch = await mkdtemp(join(tmpdir(), 'fireforge-stage-'));
+    try {
+        const file = join(scratch, 'patches.json');
+        await writeFile(file, content);
+        const sha = (await git(['hash-object', '-w', '--no-filters', file], projectRoot)).trim();
+        await git(['update-index', '--add', '--cacheinfo', `100644,${sha},${path}`], projectRoot);
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/**
+ * Runs the `patch stage` command.
+ *
+ * @param projectRoot - Project root directory (a git working tree)
+ * @param identifiers - Patch filenames, ordinals or names to stage
+ * @param options - Command options
+ */
+export async function patchStageCommand(projectRoot, identifiers, options = {}) {
+    intro(options.dryRun ? 'FireForge patch stage (dry run)' : 'FireForge patch stage');
+    const probe = await exec('git', ['rev-parse', '--is-inside-work-tree'], { cwd: projectRoot });
+    if (probe.exitCode !== 0 || probe.stdout.trim() !== 'true') {
+        throw new GeneralError('patch stage needs the project to be a git working tree.');
+    }
+    const { patches: patchesDir } = getProjectPaths(projectRoot);
+    const manifestPath = gitPath(projectRoot, join(patchesDir, 'patches.json'));
+    // Under the patch lock, so the rows and `.patch` files staged are one
+    // consistent snapshot rather than a peer's half-finished write.
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const working = await loadPatchesManifestForWrite(patchesDir);
+        if (working === null) {
+            throw new GeneralError(`No ${manifestPath} to stage.`);
+        }
+        const head = await readHeadManifest(projectRoot, manifestPath);
+        const filenames = resolveFilenames(identifiers, working, head);
+        let staged;
+        try {
+            staged = mergeStagedManifest(head, working, filenames);
+        }
+        catch (error) {
+            throw new GeneralError(`Refusing to stage: ${toError(error).message}.`);
+        }
+        const prefix = options.dryRun === true ? '[dry-run] ' : '';
+        for (const { filename, change } of staged.changes) {
+            info(`${prefix}${filename}: row ${change}; .patch file staged`);
+        }
+        if (options.dryRun === true)
+            return;
+        await stageBlob(projectRoot, manifestPath, serializeStagedManifest(staged.manifest));
+        for (const filename of filenames) {
+            await stagePatchFile(projectRoot, gitPath(projectRoot, join(patchesDir, filename)));
+        }
+        info(`Staged ${filenames.size} patch(es) and their ${manifestPath} rows. Other rows stay as at HEAD; ` +
+            'nothing was committed.');
+    }, { waitLockSeconds: resolveWaitLockSeconds(options.waitLock), command: 'patch stage' });
+    outro(options.dryRun ? 'Dry run complete — nothing staged' : 'Patch stage complete');
+}
+/**
+ * Registers the `patch stage` subcommand on the `patch` parent.
+ *
+ * @param parent - Parent Commander command
+ * @param context - Shared CLI registration context
+ */
+export function registerPatchStage(parent, context) {
+    const { getProjectRoot, withErrorHandling } = context;
+    const command = parent
+        .command('stage <names...>')
+        .description("Stage the named patches' .patch files and only their patches.json rows in the git index " +
+        "(HEAD's rows for every other patch); validates the staged manifest, commits nothing")
+        .option('--dry-run', 'Show which rows would be staged without touching the index');
+    addWaitLockOption(command).action(withErrorHandling(async (names, options) => {
+        await patchStageCommand(getProjectRoot(), names, pickDefined(options));
+    }));
+}

package/dist/src/commands/patch/staged-dependency-batch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Batch input and history delta for `patch staged-dependency`.
+ *
+ * `--from <json-file>` lets one `--add` call declare many edges under one
+ * lock hold. Turning on `patchLint.forwardRegistration: "extended"` on a real
+ * queue surfaced hundreds of undeclared registrations, each printed with its
+ * own command, and one call per edge was the only way to declare them. The
+ * file is either a `lint --per-patch --report` JSON (its findings carry the
+ * `stagedDeclarations` that discharge them) or a plain array of
+ * declarations.
+ *
+ * The history record of every call holds only the delta (`added` /
+ * `removed`). Recording the patch's whole list before and after grew the
+ * log quadratically with the list: 849 single-edge calls took one consumer's
+ * log from 36 MB to 184 MB.
+ */
+import type { PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../../types/commands/index.js';
+/** Declarations read from a `--from` file for one target patch. */
+export interface StagedDependencyBatch {
+    forwardImports: PatchStagedForwardImport[];
+    registrations: PatchStagedRegistration[];
+    /** Entries naming a different patch, left out. */
+    skippedForOtherPatches: number;
+}
+/**
+ * Reads the declarations a `--from` file supplies for `targetFilename`.
+ *
+ * Every entry takes `file`, `creates`, optional `owner` and `reason`, and
+ * either `specifier` (an import) or `line` (a registration); `kind` may
+ * name the shape explicitly. An entry with a `patch` field naming another
+ * patch is skipped and counted, so one report can be applied patch by
+ * patch. `defaultReason` (the `--reason` flag) fills entries without one.
+ *
+ * @param path - The JSON file
+ * @param targetFilename - Filename of the patch being edited
+ * @param defaultReason - Reason for entries that carry none
+ */
+export declare function readStagedDependencyBatch(path: string, targetFilename: string, defaultReason?: string): Promise<StagedDependencyBatch>;
+/**
+ * The history delta between two committed `stagedDependencies` values:
+ * the declarations the call added and the ones it removed. Each side is
+ * omitted when empty. Older log records carry `before`/`after` instead;
+ * a reader should accept either.
+ */
+export declare function stagedDependencyDelta(before: PatchStagedDependencies | undefined, after: PatchStagedDependencies | undefined): {
+    added?: PatchStagedDependencies;
+    removed?: PatchStagedDependencies;
+};

package/dist/src/commands/patch/staged-dependency-batch.js

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Batch input and history delta for `patch staged-dependency`.
+ *
+ * `--from <json-file>` lets one `--add` call declare many edges under one
+ * lock hold. Turning on `patchLint.forwardRegistration: "extended"` on a real
+ * queue surfaced hundreds of undeclared registrations, each printed with its
+ * own command, and one call per edge was the only way to declare them. The
+ * file is either a `lint --per-patch --report` JSON (its findings carry the
+ * `stagedDeclarations` that discharge them) or a plain array of
+ * declarations.
+ *
+ * The history record of every call holds only the delta (`added` /
+ * `removed`). Recording the patch's whole list before and after grew the
+ * log quadratically with the list: 849 single-edge calls took one consumer's
+ * log from 36 MB to 184 MB.
+ */
+import { InvalidArgumentError } from '../../errors/base.js';
+import { toError } from '../../utils/errors.js';
+import { readJson } from '../../utils/fs.js';
+import { isArray, isObject } from '../../utils/validation.js';
+function optionalString(record, key, label) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new InvalidArgumentError(`${label}.${key} must be a non-empty string.`, '--from');
+    }
+    return value;
+}
+function requiredString(record, key, label) {
+    const value = optionalString(record, key, label);
+    if (value === undefined) {
+        throw new InvalidArgumentError(`${label} is missing "${key}".`, '--from');
+    }
+    return value;
+}
+/**
+ * Collects the declaration records a parsed file holds: a lint report's
+ * `stagedDeclarations` (from `queueIssues` and every patch's `issues`), or
+ * the elements of a plain array.
+ */
+function collectRecords(data) {
+    if (isArray(data)) {
+        return data.map((entry, index) => {
+            if (!isObject(entry)) {
+                throw new InvalidArgumentError(`--from entry [${index}] must be an object.`, '--from');
+            }
+            return { record: entry, label: `--from entry [${index}]` };
+        });
+    }
+    if (!isObject(data)) {
+        throw new InvalidArgumentError('--from must hold a JSON array of declarations or a "lint --per-patch --report" document.', '--from');
+    }
+    const issues = [];
+    if (isArray(data['queueIssues']))
+        issues.push(...data['queueIssues']);
+    if (isArray(data['patches'])) {
+        for (const patch of data['patches']) {
+            if (isObject(patch) && isArray(patch['issues']))
+                issues.push(...patch['issues']);
+        }
+    }
+    const records = [];
+    for (const issue of issues) {
+        if (!isObject(issue) || !isArray(issue['stagedDeclarations']))
+            continue;
+        for (const declaration of issue['stagedDeclarations']) {
+            if (isObject(declaration)) {
+                records.push({
+                    record: declaration,
+                    label: `stagedDeclarations of [${String(issue['check'])}] ${String(issue['file'])}`,
+                });
+            }
+        }
+    }
+    return records;
+}
+/**
+ * Reads the declarations a `--from` file supplies for `targetFilename`.
+ *
+ * Every entry takes `file`, `creates`, optional `owner` and `reason`, and
+ * either `specifier` (an import) or `line` (a registration); `kind` may
+ * name the shape explicitly. An entry with a `patch` field naming another
+ * patch is skipped and counted, so one report can be applied patch by
+ * patch. `defaultReason` (the `--reason` flag) fills entries without one.
+ *
+ * @param path - The JSON file
+ * @param targetFilename - Filename of the patch being edited
+ * @param defaultReason - Reason for entries that carry none
+ */
+export async function readStagedDependencyBatch(path, targetFilename, defaultReason) {
+    let data;
+    try {
+        data = await readJson(path);
+    }
+    catch (error) {
+        throw new InvalidArgumentError(`--from ${path} could not be read as JSON: ${toError(error).message}`, '--from');
+    }
+    const batch = {
+        forwardImports: [],
+        registrations: [],
+        skippedForOtherPatches: 0,
+    };
+    for (const { record, label } of collectRecords(data)) {
+        const patch = optionalString(record, 'patch', label);
+        if (patch !== undefined && patch !== targetFilename) {
+            batch.skippedForOtherPatches += 1;
+            continue;
+        }
+        const specifier = optionalString(record, 'specifier', label);
+        const line = optionalString(record, 'line', label);
+        const kind = record['kind'] ?? (line !== undefined ? 'registration' : 'import');
+        if (kind !== 'import' && kind !== 'registration') {
+            throw new InvalidArgumentError(`${label}.kind must be "import" or "registration".`, '--from');
+        }
+        const file = requiredString(record, 'file', label);
+        const creates = requiredString(record, 'creates', label);
+        const owner = optionalString(record, 'owner', label);
+        const reason = optionalString(record, 'reason', label) ?? defaultReason;
+        const extras = {
+            ...(owner !== undefined ? { owner } : {}),
+            ...(reason !== undefined ? { reason } : {}),
+        };
+        if (kind === 'import') {
+            if (specifier === undefined || line !== undefined) {
+                throw new InvalidArgumentError(`${label} is an import declaration and needs "specifier" (not "line").`, '--from');
+            }
+            batch.forwardImports.push({ file, specifier, creates, ...extras });
+        }
+        else {
+            if (line === undefined || specifier !== undefined) {
+                throw new InvalidArgumentError(`${label} is a registration declaration and needs "line" (not "specifier").`, '--from');
+            }
+            batch.registrations.push({ file, line, creates, ...extras });
+        }
+    }
+    return batch;
+}
+function entryKey(entry) {
+    return JSON.stringify(entry);
+}
+function difference(left, right) {
+    const keys = new Set((right ?? []).map(entryKey));
+    return (left ?? []).filter((entry) => !keys.has(entryKey(entry)));
+}
+function nonEmpty(staged) {
+    const forwardImports = staged.forwardImports ?? [];
+    const registrations = staged.registrations ?? [];
+    if (forwardImports.length === 0 && registrations.length === 0)
+        return undefined;
+    return {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(registrations.length > 0 ? { registrations } : {}),
+    };
+}
+/**
+ * The history delta between two committed `stagedDependencies` values:
+ * the declarations the call added and the ones it removed. Each side is
+ * omitted when empty. Older log records carry `before`/`after` instead;
+ * a reader should accept either.
+ */
+export function stagedDependencyDelta(before, after) {
+    const added = nonEmpty({
+        forwardImports: difference(after?.forwardImports, before?.forwardImports),
+        registrations: difference(after?.registrations, before?.registrations),
+    });
+    const removed = nonEmpty({
+        forwardImports: difference(before?.forwardImports, after?.forwardImports),
+        registrations: difference(before?.registrations, after?.registrations),
+    });
+    return {
+        ...(added !== undefined ? { added } : {}),
+        ...(removed !== undefined ? { removed } : {}),
+    };
+}

package/dist/src/commands/patch/staged-dependency-entries.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Kind-neutral views and list operations over staged-dependency
+ * declarations, shared by `patch staged-dependency` and its `--from` batch
+ * path. Split out of `staged-dependency.ts` for the per-file line budget.
+ */
+import type { PatchStagedDependencies, PatchStagedForwardImport, PatchStagedRegistration } from '../../types/commands/index.js';
+/** The command's mutation mode. */
+export type StagedDependencyMode = 'add' | 'remove' | 'clear';
+/** The declaration shape (`--kind`). */
+export type StagedDependencyKind = 'import' | 'registration';
+/**
+ * One staged-dependency entry of either kind. The `matcher` field is the
+ * kind-specific middle term: the import specifier for import entries, the
+ * registration line for registration entries. Key/removal/label logic is
+ * shared across kinds through this shape.
+ */
+export interface StagedEntryView {
+    file: string;
+    matcher: string;
+    creates: string;
+    owner?: string;
+    reason?: string;
+}
+/** View of an import declaration. */
+export declare function importView(dependency: PatchStagedForwardImport): StagedEntryView;
+/** View of a registration declaration. */
+export declare function registrationView(dependency: PatchStagedRegistration): StagedEntryView;
+/** One-line operator label for a declaration. */
+export declare function dependencyLabel(kind: StagedDependencyKind, view: StagedEntryView): string;
+/**
+ * Applies one add/remove/clear to a declaration list: `add` appends unless
+ * an entry with the same file, matcher, creates and owner exists.
+ */
+export declare function applyMode<T>(existing: readonly T[], mode: StagedDependencyMode, target: StagedEntryView | undefined, toView: (entry: T) => StagedEntryView, addition: T | undefined): T[];
+/** Number of declarations of both kinds. */
+export declare function countStagedEntries(staged: PatchStagedDependencies | undefined): number;

package/dist/src/commands/patch/staged-dependency-entries.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Kind-neutral views and list operations over staged-dependency
+ * declarations, shared by `patch staged-dependency` and its `--from` batch
+ * path. Split out of `staged-dependency.ts` for the per-file line budget.
+ */
+/** View of an import declaration. */
+export function importView(dependency) {
+    return { ...dependency, matcher: dependency.specifier };
+}
+/** View of a registration declaration. */
+export function registrationView(dependency) {
+    return { ...dependency, matcher: dependency.line };
+}
+function dependencyKey(view) {
+    return [view.file, view.matcher, view.creates, view.owner ?? ''].join('\0');
+}
+/** One-line operator label for a declaration. */
+export function dependencyLabel(kind, view) {
+    const owner = view.owner ? ` owner=${view.owner}` : '';
+    const reason = view.reason ? ` reason="${view.reason}"` : '';
+    if (kind === 'import') {
+        return `${view.file} imports "${view.matcher}" from ${view.creates}${owner}${reason}`;
+    }
+    return `${view.file} registers "${view.matcher}" for ${view.creates}${owner}${reason}`;
+}
+function matchesTarget(view, target) {
+    return (view.file === target.file &&
+        view.matcher === target.matcher &&
+        view.creates === target.creates &&
+        (target.owner === undefined || view.owner === target.owner));
+}
+/**
+ * Applies one add/remove/clear to a declaration list: `add` appends unless
+ * an entry with the same file, matcher, creates and owner exists.
+ */
+export function applyMode(existing, mode, target, toView, addition) {
+    if (mode === 'clear')
+        return [];
+    if (!target)
+        return [...existing];
+    if (mode === 'remove')
+        return existing.filter((entry) => !matchesTarget(toView(entry), target));
+    const seen = new Set(existing.map((entry) => dependencyKey(toView(entry))));
+    if (seen.has(dependencyKey(target)) || addition === undefined)
+        return [...existing];
+    return [...existing, addition];
+}
+/** Number of declarations of both kinds. */
+export function countStagedEntries(staged) {
+    return (staged?.forwardImports?.length ?? 0) + (staged?.registrations?.length ?? 0);
+}