@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,14 @@
+/**
+ * `patch staged-dependency --add --from <json-file>`: adds every
+ * declaration a file supplies for one patch in a single manifest update
+ * under one lock hold. The file format and the history delta live in
+ * `staged-dependency-batch.ts`.
+ */
+import type { PatchStagedDependencyOptions } from '../../types/commands/index.js';
+import { type StagedDependencyMode } from './staged-dependency-entries.js';
+/**
+ * `--add --from <json-file>`: every declaration the file supplies for the
+ * target patch, validated up front and written in one manifest update
+ * under one lock hold, with one delta history record.
+ */
+export declare function runBatchAdd(projectRoot: string, identifier: string, mode: StagedDependencyMode, options: PatchStagedDependencyOptions): Promise<void>;

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

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `patch staged-dependency --add --from <json-file>`: adds every
+ * declaration a file supplies for one patch in a single manifest update
+ * under one lock hold. The file format and the history delta live in
+ * `staged-dependency-batch.ts`.
+ */
+import { appendHistoryBestEffort } from '../../core/history-log.js';
+import { mutatePatchMetadata } from '../../core/patch-export.js';
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { info, outro } from '../../utils/logger.js';
+import { resolveWaitLockSeconds } from '../../utils/options.js';
+import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { readStagedDependencyBatch, stagedDependencyDelta, } from './staged-dependency-batch.js';
+import { applyMode, countStagedEntries, importView, registrationView, } from './staged-dependency-entries.js';
+import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
+/** Flags that describe one declaration and so cannot combine with `--from`. */
+const SINGLE_DECLARATION_FLAGS = [
+    ['--kind', 'kind'],
+    ['--file', 'file'],
+    ['--specifier', 'specifier'],
+    ['--line', 'line'],
+    ['--creates', 'creates'],
+    ['--owner', 'owner'],
+];
+/** Adds every `--from` declaration not already present, keyed like a single `--add`. */
+function mergeBatch(staged, batch) {
+    let forwardImports = [...(staged?.forwardImports ?? [])];
+    for (const entry of batch.forwardImports) {
+        forwardImports = applyMode(forwardImports, 'add', importView(entry), importView, entry);
+    }
+    let registrations = [...(staged?.registrations ?? [])];
+    for (const entry of batch.registrations) {
+        registrations = applyMode(registrations, 'add', registrationView(entry), registrationView, entry);
+    }
+    return {
+        ...(forwardImports.length > 0 ? { forwardImports } : {}),
+        ...(registrations.length > 0 ? { registrations } : {}),
+    };
+}
+/**
+ * `--add --from <json-file>`: every declaration the file supplies for the
+ * target patch, validated up front and written in one manifest update
+ * under one lock hold, with one delta history record.
+ */
+export async function runBatchAdd(projectRoot, identifier, mode, options) {
+    const from = options.from ?? '';
+    if (mode !== 'add') {
+        throw new InvalidArgumentError('--from only applies to --add.', '--from');
+    }
+    const clashing = SINGLE_DECLARATION_FLAGS.filter(([, key]) => options[key] !== undefined);
+    if (clashing.length > 0) {
+        throw new InvalidArgumentError(`--from supplies the declarations itself; drop ${clashing.map(([flag]) => flag).join(', ')}.`, '--from');
+    }
+    const { paths, manifest } = await requirePatchQueue(projectRoot);
+    const targetPatch = requirePatchTarget(identifier, manifest.patches);
+    const batch = await readStagedDependencyBatch(from, targetPatch.filename, options.reason);
+    for (const entry of [...batch.forwardImports, ...batch.registrations]) {
+        validateStagedDependencyAdd(entry, manifest.patches);
+    }
+    const supplied = batch.forwardImports.length + batch.registrations.length;
+    if (batch.skippedForOtherPatches > 0) {
+        info(`Skipped ${batch.skippedForOtherPatches} declaration(s) in ${from} that name another patch.`);
+    }
+    if (supplied === 0) {
+        info(`${from} holds no declarations for ${targetPatch.filename}; nothing to add.`);
+        outro('Patch staged-dependency complete');
+        return;
+    }
+    const existing = targetPatch.stagedDependencies;
+    const projectedCount = countStagedEntries(mergeBatch(existing, batch));
+    const describe = (beforeCount, afterCount) => `added ${afterCount - beforeCount} of ${supplied} staged declaration(s) from ${from}` +
+        (supplied > afterCount - beforeCount
+            ? ` (${supplied - (afterCount - beforeCount)} already present or repeated)`
+            : '');
+    if (options.dryRun === true) {
+        info(`[dry-run] ${targetPatch.filename}: ${describe(countStagedEntries(existing), projectedCount)}.`);
+        outro('Dry run complete — no changes made');
+        return;
+    }
+    const result = await mutatePatchMetadata(paths.patches, targetPatch.filename, (current) => {
+        const after = mergeBatch(current.stagedDependencies, batch);
+        if (countStagedEntries(after) === 0)
+            return { unset: ['stagedDependencies'] };
+        return { set: { stagedDependencies: after } };
+    }, {
+        waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+        command: 'patch staged-dependency',
+    });
+    if (!result) {
+        throw new GeneralError(`Patch ${targetPatch.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+    }
+    const before = result.before.stagedDependencies;
+    const after = result.after.stagedDependencies;
+    info(`${targetPatch.filename}: ${describe(countStagedEntries(before), countStagedEntries(after))}.`);
+    await appendHistoryBestEffort(paths.patches, {
+        operation: 'patch-staged-dependency',
+        args: {
+            filename: targetPatch.filename,
+            mode,
+            from,
+            ...stagedDependencyDelta(before, after),
+        },
+        ...(options.yes === true ? { yes: true } : {}),
+        result: 'ok',
+    }, `patch staged-dependency committed (${targetPatch.filename})`);
+    outro('Patch staged-dependency complete');
+}

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

@@ -0,0 +1,31 @@
+/**
+ * `--remove` target selection for `patch staged-dependency`. Split out of
+ * `staged-dependency.ts` for the per-file line budget.
+ *
+ * A removal names its entries by any of `--file`, `--specifier`/`--line`,
+ * `--creates` and `--owner`, and must give at least `--creates` or the
+ * `--file` + matcher pair. Registration lines compare whitespace-
+ * insensitively (runs of whitespace collapse, ends trimmed), the way the
+ * lint compares them, so a line copied from a patch hunk matches the stored
+ * one whatever its padding. A selection that matches nothing is refused
+ * rather than reported as a no-op.
+ */
+import type { PatchStagedDependencies, PatchStagedDependencyOptions } from '../../types/commands/index.js';
+import { type StagedDependencyKind, type StagedEntryView } from './staged-dependency-entries.js';
+/**
+ * Resolves the staged entries a `--remove` invocation names. The returned
+ * views are the stored entries themselves, so the removal matches them
+ * exactly.
+ *
+ * - `--file` + matcher identifying one entry infers `--creates`.
+ * - `--file` + matcher identifying several entries without `--creates`
+ *   refuses with the candidate list.
+ * - `--creates` alone selects every declaration for that created path.
+ *
+ * @param kind - Declaration kind (`--kind`)
+ * @param options - Command options
+ * @param staged - The target patch's current staged dependencies
+ * @returns The matching stored entries (never empty)
+ * @throws InvalidArgumentError when the selectors are insufficient or match nothing
+ */
+export declare function selectRemovalEntries(kind: StagedDependencyKind, options: PatchStagedDependencyOptions, staged: PatchStagedDependencies | undefined): StagedEntryView[];

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

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `--remove` target selection for `patch staged-dependency`. Split out of
+ * `staged-dependency.ts` for the per-file line budget.
+ *
+ * A removal names its entries by any of `--file`, `--specifier`/`--line`,
+ * `--creates` and `--owner`, and must give at least `--creates` or the
+ * `--file` + matcher pair. Registration lines compare whitespace-
+ * insensitively (runs of whitespace collapse, ends trimmed), the way the
+ * lint compares them, so a line copied from a patch hunk matches the stored
+ * one whatever its padding. A selection that matches nothing is refused
+ * rather than reported as a no-op.
+ */
+import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
+import { info } from '../../utils/logger.js';
+import { dependencyLabel, importView, registrationView, } from './staged-dependency-entries.js';
+/** Collapses whitespace runs and trims, for registration-line comparison. */
+function normalizeRegistrationLine(line) {
+    return line.trim().replace(/\s+/g, ' ');
+}
+function stagedViews(kind, staged) {
+    return kind === 'import'
+        ? (staged?.forwardImports ?? []).map(importView)
+        : (staged?.registrations ?? []).map(registrationView);
+}
+/**
+ * Resolves the staged entries a `--remove` invocation names. The returned
+ * views are the stored entries themselves, so the removal matches them
+ * exactly.
+ *
+ * - `--file` + matcher identifying one entry infers `--creates`.
+ * - `--file` + matcher identifying several entries without `--creates`
+ *   refuses with the candidate list.
+ * - `--creates` alone selects every declaration for that created path.
+ *
+ * @param kind - Declaration kind (`--kind`)
+ * @param options - Command options
+ * @param staged - The target patch's current staged dependencies
+ * @returns The matching stored entries (never empty)
+ * @throws InvalidArgumentError when the selectors are insufficient or match nothing
+ */
+export function selectRemovalEntries(kind, options, staged) {
+    const matcherFlag = kind === 'import' ? '--specifier' : '--line';
+    const matcher = kind === 'import' ? options.specifier : options.line;
+    const hasPair = Boolean(options.file) && Boolean(matcher);
+    if (!options.creates && !hasPair) {
+        throw new InvalidArgumentError(`--remove${kind === 'registration' ? ' --kind registration' : ''} requires --creates, ` +
+            `or --file with ${matcherFlag}; --creates alone removes every declaration for that path.`, matcher && !options.file
+            ? '--file'
+            : options.file && !matcher
+                ? matcherFlag
+                : `--creates or --file + ${matcherFlag}`);
+    }
+    const wanted = matcher === undefined ? undefined : comparableMatcher(kind, matcher);
+    const views = stagedViews(kind, staged);
+    const candidates = views.filter((view) => (!options.file || view.file === options.file) &&
+        (wanted === undefined || comparableMatcher(kind, view.matcher) === wanted) &&
+        (!options.creates || view.creates === options.creates) &&
+        (options.owner === undefined || view.owner === options.owner));
+    if (candidates.length === 0) {
+        const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
+        const existing = views.length === 0
+            ? `This patch has no ${noun}s.`
+            : `This patch's ${noun}s:\n${views.map((view) => `  - ${dependencyLabel(kind, view)}`).join('\n')}`;
+        throw new InvalidArgumentError(`--remove matched no ${noun}. ${existing}`, '--remove');
+    }
+    if (candidates.length > 1 && !options.creates) {
+        const list = candidates.map((view) => `  - ${dependencyLabel(kind, view)}`).join('\n');
+        const noun = kind === 'import' ? 'staged forward-imports' : 'staged registrations';
+        throw new GeneralError(`--remove matches ${candidates.length} ${noun} on this patch; pass --creates to pick one:\n${list}`);
+    }
+    const single = candidates.length === 1 ? candidates[0] : undefined;
+    if (single !== undefined && !options.creates) {
+        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
+    }
+    return candidates;
+}
+function comparableMatcher(kind, matcher) {
+    return kind === 'registration' ? normalizeRegistrationLine(matcher) : matcher;
+}

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

@@ -10,6 +10,10 @@ import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { info, intro, outro } from '../../utils/logger.js';
 import { addWaitLockOption, resolveWaitLockSeconds } from '../../utils/options.js';
 import { requirePatchQueue, requirePatchTarget } from './patch-context.js';
+import { stagedDependencyDelta } from './staged-dependency-batch.js';
+import { applyMode, countStagedEntries, dependencyLabel, importView, registrationView, } from './staged-dependency-entries.js';
+import { runBatchAdd } from './staged-dependency-from.js';
+import { selectRemovalEntries } from './staged-dependency-remove.js';
 import { validateStagedDependencyAdd } from './staged-dependency-validate.js';
 /** Joins the names of the missing flags for error attribution. */
 function missingFlagList(pairs) {
@@ -82,128 +86,27 @@ function requireRegistrationOptions(options) {
         dependency.reason = options.reason;
     return dependency;
 }
-/**
- * Resolves the `--remove` target for forward-imports:
- * `--file` + `--specifier` suffice when they identify at most one staged
- * entry. `--creates` is inferred from a unique match, an ambiguous match
- * refuses with the candidate list, and no match falls through to the
- * honest "no staged forward-import matched" summary.
- */
-function resolveImportRemovalTarget(options, staged) {
-    if (!options.file || !options.specifier) {
-        throw new InvalidArgumentError('--remove requires --file and --specifier; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
-            ['--file', options.file],
-            ['--specifier', options.specifier],
-        ]));
-    }
-    if (options.creates) {
-        return requireForwardImportOptions(options);
-    }
-    const { file, specifier } = options;
-    const candidates = (staged?.forwardImports ?? []).filter((entry) => entry.file === file &&
-        entry.specifier === specifier &&
-        (options.owner === undefined || entry.owner === options.owner));
-    const single = candidates.length === 1 ? candidates[0] : undefined;
-    if (single !== undefined) {
-        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
-        return { ...single };
-    }
-    if (candidates.length > 1) {
-        const list = candidates
-            .map((entry) => `  - ${dependencyLabel('import', importView(entry))}`)
-            .join('\n');
-        throw new GeneralError(`--remove matches ${candidates.length} staged forward-imports on this patch; ` +
-            `pass --creates to pick one:\n${list}`);
-    }
-    return { file, specifier, creates: '(no match)' };
-}
-/** Registration twin of {@link resolveImportRemovalTarget}, keyed on `--line`. */
-function resolveRegistrationRemovalTarget(options, staged) {
-    if (!options.file || !options.line) {
-        throw new InvalidArgumentError('--remove --kind registration requires --file and --line; --creates is only needed to disambiguate when several staged entries share them.', missingFlagList([
-            ['--file', options.file],
-            ['--line', options.line],
-        ]));
-    }
-    if (options.creates) {
-        return requireRegistrationOptions(options);
-    }
-    const { file, line } = options;
-    const candidates = (staged?.registrations ?? []).filter((entry) => entry.file === file &&
-        entry.line === line &&
-        (options.owner === undefined || entry.owner === options.owner));
-    const single = candidates.length === 1 ? candidates[0] : undefined;
-    if (single !== undefined) {
-        info(`Inferred --creates ${single.creates} from the single matching staged entry.`);
-        return { ...single };
-    }
-    if (candidates.length > 1) {
-        const list = candidates
-            .map((entry) => `  - ${dependencyLabel('registration', registrationView(entry))}`)
-            .join('\n');
-        throw new GeneralError(`--remove matches ${candidates.length} staged registrations on this patch; ` +
-            `pass --creates to pick one:\n${list}`);
-    }
-    return { file, line, creates: '(no match)' };
-}
-function importView(dependency) {
-    return { ...dependency, matcher: dependency.specifier };
-}
-function registrationView(dependency) {
-    return { ...dependency, matcher: dependency.line };
-}
-function dependencyKey(view) {
-    return [view.file, view.matcher, view.creates, view.owner ?? ''].join('\0');
-}
-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));
-}
-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];
-}
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, target) {
+function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, targets) {
     const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
     if (mode === 'clear') {
         return beforeCount === 0
             ? 'stagedDependencies was already empty — no change'
             : `cleared ${beforeCount} staged dependency declaration(s)`;
     }
-    if (!target)
+    const label = targets.map((target) => dependencyLabel(kind, target)).join('; ');
+    if (targets.length === 0)
         return 'stagedDependencies unchanged';
     if (mode === 'add') {
         return afterCount === beforeCount
-            ? `${noun} already present: ${dependencyLabel(kind, target)}`
-            : `added ${noun}: ${dependencyLabel(kind, target)}`;
+            ? `${noun} already present: ${label}`
+            : `added ${noun}: ${label}`;
     }
     return afterCount === beforeCount
-        ? `no ${noun} matched: ${dependencyLabel(kind, target)}`
-        : `removed ${beforeCount - afterCount} ${noun} declaration(s): ${dependencyLabel(kind, target)}`;
-}
-function countStagedEntries(staged) {
-    return (staged?.forwardImports?.length ?? 0) + (staged?.registrations?.length ?? 0);
+        ? `no ${noun} matched: ${label}`
+        : `removed ${beforeCount - afterCount} ${noun} declaration(s): ${label}`;
 }
 /**
  * Runs the metadata-only staged-dependency mutation command.
@@ -216,41 +119,44 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
+    if (options.from !== undefined) {
+        await runBatchAdd(projectRoot, identifier, mode, options);
+        return;
+    }
     const kind = kindFromOptions(options);
     // The patch queue loads before the declaration fields resolve so
     // `--remove` can infer `--creates` from the target patch's staged
     // entries.
     const { paths, manifest } = await requirePatchQueue(projectRoot);
     const targetPatch = requirePatchTarget(identifier, manifest.patches);
-    const importDependency = mode === 'clear' || kind !== 'import'
-        ? undefined
-        : mode === 'add'
-            ? requireForwardImportOptions(options)
-            : resolveImportRemovalTarget(options, targetPatch.stagedDependencies);
-    const registrationDependency = mode === 'clear' || kind !== 'registration'
-        ? undefined
-        : mode === 'add'
-            ? requireRegistrationOptions(options)
-            : resolveRegistrationRemovalTarget(options, targetPatch.stagedDependencies);
+    const importDependency = mode === 'add' && kind === 'import' ? requireForwardImportOptions(options) : undefined;
+    const registrationDependency = mode === 'add' && kind === 'registration' ? requireRegistrationOptions(options) : undefined;
     // Shape-check --add declarations against the loaded queue: a
     // patch-name-shaped --creates/--file is refused now instead of surfacing
     // later as an undischargeable staged-dependency-unused.
-    if (mode === 'add') {
-        const added = importDependency ?? registrationDependency;
-        if (added !== undefined) {
-            validateStagedDependencyAdd(added, manifest.patches);
-        }
-    }
-    const target = importDependency !== undefined
-        ? importView(importDependency)
-        : registrationDependency !== undefined
-            ? registrationView(registrationDependency)
-            : undefined;
+    const added = importDependency ?? registrationDependency;
+    if (added !== undefined) {
+        validateStagedDependencyAdd(added, manifest.patches);
+    }
+    const targets = mode === 'remove'
+        ? selectRemovalEntries(kind, options, targetPatch.stagedDependencies)
+        : importDependency !== undefined
+            ? [importView(importDependency)]
+            : registrationDependency !== undefined
+                ? [registrationView(registrationDependency)]
+                : [];
+    const applyKind = (entries, own, toView, addition) => {
+        if (!own)
+            return [...entries];
+        if (mode !== 'remove')
+            return applyMode(entries, mode, targets[0], toView, addition);
+        return targets.reduce((remaining, target) => applyMode(remaining, 'remove', target, toView, undefined), [...entries]);
+    };
     const applyToStaged = (staged) => {
         if (mode === 'clear')
             return {};
-        const forwardImports = applyMode(staged?.forwardImports ?? [], kind === 'import' ? mode : 'add', kind === 'import' ? target : undefined, importView, importDependency);
-        const registrations = applyMode(staged?.registrations ?? [], kind === 'registration' ? mode : 'add', kind === 'registration' ? target : undefined, registrationView, registrationDependency);
+        const forwardImports = applyKind(staged?.forwardImports ?? [], kind === 'import', importView, importDependency);
+        const registrations = applyKind(staged?.registrations ?? [], kind === 'registration', registrationView, registrationDependency);
         return {
             ...(forwardImports.length > 0 ? { forwardImports } : {}),
             ...(registrations.length > 0 ? { registrations } : {}),
@@ -258,7 +164,7 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     };
     const existing = targetPatch.stagedDependencies;
     const projected = applyToStaged(existing);
-    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, target);
+    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, targets);
     if (isDryRun) {
         info(`[dry-run] ${targetPatch.filename}: ${summary}.`);
         outro('Dry run complete — no changes made');
@@ -278,15 +184,21 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     }
     const before = result.before.stagedDependencies;
     const after = result.after.stagedDependencies;
-    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, target)}.`);
+    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, targets)}.`);
+    if (mode === 'remove' && countStagedEntries(after) === countStagedEntries(before)) {
+        // The selection matched when the queue was read; a peer removed the
+        // entries before the locked write. Still a miss, so still a refusal.
+        throw new InvalidArgumentError(`${targetPatch.filename}: the selected staged declaration(s) were already gone when the manifest was written.`, '--remove');
+    }
     await appendHistoryBestEffort(paths.patches, {
         operation: 'patch-staged-dependency',
+        // Only the delta: the whole list on both sides grew the log
+        // quadratically with the list (see staged-dependency-batch.ts).
         args: {
             filename: targetPatch.filename,
             mode,
             kind,
-            before: before ?? {},
-            after: after ?? {},
+            ...stagedDependencyDelta(before, after),
         },
         ...(options.yes === true ? { yes: true } : {}),
         result: 'ok',
@@ -305,15 +217,18 @@ export function registerPatchStagedDependency(parent, context) {
         .command('staged-dependency <name>')
         .description('Edit PatchMetadata.stagedDependencies on a single patch (no .patch body rewrite).')
         .option('--add', 'Add a staged dependency declaration')
-        .option('--remove', 'Remove matching staged dependency declaration(s)')
+        .option('--remove', 'Remove matching staged dependency declaration(s); a selection that matches nothing exits 8')
         .option('--clear', 'Drop the stagedDependencies field entirely')
         .option('--kind <kind>', 'Declaration shape: "import" (forward import, the default) or "registration" (jar.mn packaging line, customElements or actor registration)')
         .option('--file <path>', 'Declaring file path relative to engine/')
         .option('--specifier <specifier>', 'Exact import specifier as it appears in source (--kind import)')
-        .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-trimmed (--kind registration)')
-        .option('--creates <path>', 'Later-created file path relative to engine/')
+        .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-insensitively (--kind registration)')
+        .option('--creates <path>', 'Later-created file path relative to engine/ (with --remove and no --file: removes every declaration for that path)')
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
-        .option('--reason <text>', 'Human-readable rationale stored with the declaration')
+        .option('--reason <text>', 'Human-readable rationale stored with the declaration (with --from: the default for entries without one)')
+        .option('--from <json-file>', 'Add every declaration in a JSON file under one lock hold (--add only): a "lint --per-patch --report" ' +
+        "document (its findings' stagedDeclarations for this patch) or an array of " +
+        '{ file, specifier | line, creates, owner?, reason?, patch? } entries')
         .option('--dry-run', 'Show what would change without writing')
         .option('-y, --yes', 'Record scripted consent in the destructive-operation history log. This command never prompts; the flag exists for workflow uniformity with commands that do.');
     addWaitLockOption(command).action(withErrorHandling(async (name, options) => {

package/dist/src/commands/re-export-adjacent-registrations.d.ts

@@ -0,0 +1,20 @@
+/** One changed engine file a registration line the patch adds names. */
+export interface RegisteredChangedFile {
+    /** Engine-relative path of the named file. */
+    file: string;
+    /** Engine-relative path of the carrier whose added line names it. */
+    carrier: string;
+}
+/**
+ * Lists the changed (modified, deleted or untracked) engine files named by
+ * the registration lines the patch's owned carriers add relative to HEAD.
+ * Only added lines count: an upstream line naming an upstream file is not
+ * the patch's registration. A wildcard token is matched against the changed
+ * files under its carrier's directory, the only place such a token reaches
+ * without the build system.
+ *
+ * @param engineDir - Engine checkout
+ * @param ownedFiles - The patch's current filesAffected
+ * @returns Named changed files, first carrier wins, sorted by path
+ */
+export declare function findRegisteredChangedFiles(engineDir: string, ownedFiles: readonly string[]): Promise<RegisteredChangedFile[]>;

package/dist/src/commands/re-export-adjacent-registrations.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The registration arm of the scan-less re-export adjacency belt.
+ *
+ * A file the patch registers (a jar.mn, moz.build or test-manifest line the
+ * patch adds names it) belongs with the patch even when it lives in another
+ * directory, so an unmanaged one is adjacent in the sense that matters: the
+ * refreshed body would ship a registration for a file it leaves out. This
+ * module answers which changed engine files those lines name. The caller
+ * filters out owned, claimed and tool-managed paths.
+ *
+ * Split out of re-export-adjacent.ts to keep that module about the
+ * classification, not the carrier parsing.
+ */
+import { dirname } from 'node:path';
+import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
+import { getDirtyFiles, getModifiedFilesInDir, getUntrackedFilesInDir, } from '../core/git-status.js';
+import { extractAddedLinesPerFile } from '../core/patch-lint-diff.js';
+import { isRegistrationCarrier, resolveCarrierReferences, } from '../core/patch-lint-forward-registration-extended.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+/**
+ * Lists the changed (modified, deleted or untracked) engine files named by
+ * the registration lines the patch's owned carriers add relative to HEAD.
+ * Only added lines count: an upstream line naming an upstream file is not
+ * the patch's registration. A wildcard token is matched against the changed
+ * files under its carrier's directory, the only place such a token reaches
+ * without the build system.
+ *
+ * @param engineDir - Engine checkout
+ * @param ownedFiles - The patch's current filesAffected
+ * @returns Named changed files, first carrier wins, sorted by path
+ */
+export async function findRegisteredChangedFiles(engineDir, ownedFiles) {
+    const carriers = ownedFiles.filter(isRegistrationCarrier);
+    if (carriers.length === 0)
+        return [];
+    const diff = await getDiffForFilesAgainstHead(engineDir, carriers);
+    const exactToCarrier = new Map();
+    const wildcardsByCarrier = new Map();
+    for (const [carrier, lines] of extractAddedLinesPerFile(diff)) {
+        for (const ref of resolveCarrierReferences(carrier, lines.join('\n'))) {
+            if (ref.exact !== undefined) {
+                if (!exactToCarrier.has(ref.exact))
+                    exactToCarrier.set(ref.exact, carrier);
+            }
+            else {
+                const list = wildcardsByCarrier.get(carrier) ?? [];
+                list.push(ref.matches);
+                wildcardsByCarrier.set(carrier, list);
+            }
+        }
+    }
+    const found = new Map();
+    if (exactToCarrier.size > 0) {
+        for (const file of await getDirtyFiles(engineDir, [...exactToCarrier.keys()])) {
+            const carrier = exactToCarrier.get(file);
+            if (carrier !== undefined)
+                found.set(file, carrier);
+        }
+    }
+    for (const [carrier, matchers] of wildcardsByCarrier) {
+        const scope = normalizePathSlashes(dirname(carrier));
+        const [modified, untracked] = await Promise.all([
+            getModifiedFilesInDir(engineDir, scope),
+            getUntrackedFilesInDir(engineDir, scope),
+        ]);
+        for (const file of [...modified, ...untracked]) {
+            if (!found.has(file) && matchers.some((matches) => matches(file)))
+                found.set(file, carrier);
+        }
+    }
+    return [...found.entries()]
+        .map(([file, carrier]) => ({ file, carrier }))
+        .sort((a, b) => a.file.localeCompare(b.file));
+}