@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/re-export-register.js

@@ -8,9 +8,12 @@
  * the orchestrator would go the wrong way.
  */
 import { Command, Option } from 'commander';
+import { getProjectPaths } from '../core/config.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { withPrivateGitIndex } from '../core/git-readonly-index.js';
 import { addWaitLockOption, pickDefined, resolveWaitLockSeconds, stringListOption, } from '../utils/options.js';
 import { reExportCommand } from './re-export.js';
+import { preflightReExportArguments, readPathListFile } from './re-export-preflight.js';
 /** Registers the re-export command on the CLI program. */
 export function registerReExport(program, { getProjectRoot, withErrorHandling }) {
     const reExport = program
@@ -20,41 +23,77 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         'rebase for source metadata stamping.')
         .option('-a, --all', 'Re-export all patches')
         .option('-s, --scan', 'Scan directories for new/removed files and update filesAffected')
-        .option('--scan-file <path>', 'With --scan, add this explicit engine-relative file to one target patch without collecting adjacent files. Repeatable.', ...stringListOption())
+        .option('--scan-file <path>', 'With --scan, add this explicit engine-relative file without collecting adjacent files. Prefix the owning patch (<patch>:<path>, required with several target patches) to adopt into one of them; selected patches without a --scan-file refresh scan-less. Repeatable.', ...stringListOption())
         .option('--scan-files <manifest>', 'With --scan, bulk-assign generated files from a JSON manifest: {"assignments":[{"patch":"002-name.patch","files":["path"]}]}. Selects patches from the manifest.')
         .option('--files <paths>', 'Restrict the re-exported filesAffected to this comma-separated list (single target patch only)', (value) => value
         .split(',')
         .map((v) => v.trim())
         .filter((v) => v.length > 0))
-        .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Mutually exclusive with --scan and --files.')
-        .option('--refuse-foreign-drift', "Refuse a scan-less re-export (non-zero exit, patch not written) when the refreshed body would absorb engine lines not present in the old patch body — protects multi-session checkouts from silently capturing another session's uncommitted edits. Mutually exclusive with --scan and --files.")
+        .option('--refuse-adjacent-unmanaged', 'Refuse a re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Adjacent means the same directory as an owned file (not a sibling or nested directory), or named by a registration line the patch adds. Beside --scan it judges the files the scan did not adopt. Mutually exclusive with --files.')
+        .option('--refuse-foreign-drift', "Refuse a re-export (non-zero exit, patch not written) when the refreshed body would add or drop lines, in a file the patch already owns, that the old patch body did not carry — protects multi-session checkouts from silently capturing another session's uncommitted edits. Beside --scan it guards each patch's existing files (adopted files count as expected). Mutually exclusive with --files.")
         .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable, and the whitelist applies across EVERY patch in this invocation, not per patch — so pass all the patches and all their --expect paths in one call rather than looping one patch at a time.", ...stringListOption())
         .option('--expect-unmanaged <path>', 'With --refuse-adjacent-unmanaged, name an engine-relative file that is a REVIEWED, recorded exception to the adjacency refusal: an approved unmanaged path is still listed, but no longer refuses. Repeatable, and the carve-out applies across EVERY patch in this invocation, not per patch. Use it to keep the belt armed for everything else instead of dropping --refuse-adjacent-unmanaged entirely.', ...stringListOption())
-        .option('--expect-removed <path>', 'Retire an absent file created by the selected patch while keeping scan-less refusals armed. Repeatable.', ...stringListOption())
+        .option('--expect-from <file>', 'Read --expect paths from a file, one engine-relative path per line (blank lines and # comments ignored). Adds to any --expect flags.')
+        .option('--expect-new <path>', 'With --refuse-adjacent-unmanaged, name a file this session created and will adopt with its next export (or --scan-file): it passes the belt and is reported, while every other adjacent file still refuses. Must be changed in engine/ and owned by no patch. Repeatable.', ...stringListOption())
+        .option('--adjacent-ignore <path|glob>', 'With --refuse-adjacent-unmanaged, a reviewed ignore-list entry: an engine-relative path, or a glob whose * stays within one path segment (** is refused). Matches are reported, never refused. Repeatable.', ...stringListOption())
+        .option('--expect-removed <path>', 'Retire a file from the selected patch while keeping scan-less refusals armed: an absent file the patch created, or a patch-modified upstream file whose engine copy is back at HEAD. Repeatable.', ...stringListOption())
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')
         .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-shrink', 'Allow --files to remove paths currently owned by the patch. Required before --yes can bypass the shrink confirmation.')
+        .option('--declarations-out <path>', 'Where a refused --scan adoption writes its one --from-ready staged-declaration report (default: .fireforge/declarations/<timestamp>.json).')
+        .option('--hunks-from <diff>', "Export each file the diff names as the patch's current body plus only the diff's hunks, so another session's edits in the same file stay out. One explicit patch; not with --scan, --files or --all.")
+        .option('--exclude-hunks <diff>', "Export each file the diff names as the working tree minus the diff's hunks. One explicit patch; not with --scan, --files or --all.")
         .option('-y, --yes', 'Skip confirmation prompts (required for non-TTY destructive writes)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')
         .option('--stamp', "After every selected patch refreshes cleanly, stamp each re-exported patch's sourceVersion/sourceProduct in patches.json to firefox.version/firefox.product from fireforge.json. No effect on a partial run.")
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
         .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', ...stringListOption());
     addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
-        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, expectUnmanaged, ...rest } = options;
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
-            ...pickDefined(rest),
-            ...(scanFile !== undefined && scanFile.length > 0 ? { scanFiles: scanFile } : {}),
-            ...(scanFiles !== undefined ? { scanFilesManifest: scanFiles } : {}),
-            ...(tier !== undefined ? { tier: tier } : {}),
-            ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
-            ...(expect !== undefined && expect.length > 0 ? { expect } : {}),
-            ...(expectUnmanaged !== undefined && expectUnmanaged.length > 0
-                ? { expectUnmanaged }
-                : {}),
-            ...(cache === false ? { noCache: true } : {}),
-        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+        const reExportOptions = await toReExportOptions(options);
+        // Refuse what the locked run would refuse before queueing for the
+        // lock, which can be a long wait under contention.
+        await preflightReExportArguments(projectRoot, patches, reExportOptions);
+        // A dry run writes nothing, so it does not queue behind peers' builds
+        // and test runs for the engine lock. Its git plumbing runs on a
+        // private index, so not even git's stat-cache refresh reaches the
+        // shared `.git/index`; dry runs still serialize among themselves.
+        if (reExportOptions.dryRun === true) {
+            const engineDir = getProjectPaths(projectRoot).engine;
+            await withPrivateGitIndex(engineDir, () => reExportCommand(projectRoot, patches, reExportOptions));
+            return;
+        }
+        await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, reExportOptions), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }
+/**
+ * Maps commander's option names onto {@link ReExportOptions}, reading the
+ * `--expect-from` list into `expect` and dropping empty repeatables.
+ */
+async function toReExportOptions(options) {
+    const { tier, lintIgnore, scanFile, scanFiles, cache, expect: expectFlags, expectFrom, expectUnmanaged, expectNew, adjacentIgnore, ...rest } = options;
+    const expect = [
+        ...(expectFlags ?? []),
+        ...(expectFrom !== undefined ? await readPathListFile(expectFrom, '--expect-from') : []),
+    ];
+    return {
+        ...pickDefined({
+            ...rest,
+            scanFiles: nonEmpty(scanFile),
+            scanFilesManifest: scanFiles,
+            tier: tier,
+            lintIgnore: nonEmpty(lintIgnore),
+            expect: nonEmpty(expect),
+            expectUnmanaged: nonEmpty(expectUnmanaged),
+            expectNew: nonEmpty(expectNew),
+            adjacentIgnore: nonEmpty(adjacentIgnore),
+        }),
+        ...(cache === false ? { noCache: true } : {}),
+    };
+}
+/** The list when it has entries, else undefined (which `pickDefined` drops). */
+function nonEmpty(values) {
+    return values !== undefined && values.length > 0 ? values : undefined;
+}

package/dist/src/commands/re-export-removed.d.ts

@@ -1,4 +1,15 @@
 import type { PatchMetadata, ReExportOptions } from '../types/commands/index.js';
 import type { ProjectPaths } from '../types/config.js';
-/** Validates every retirement before any patch is written; typos never silently grant a carve-out. */
-export declare function validateExpectedRemovals(paths: ProjectPaths, patches: PatchMetadata[], options: ReExportOptions): Promise<string[]>;
+/**
+ * Validates every retirement before any patch is written; typos never
+ * silently grant a carve-out. Two shapes retire a file from its one
+ * selected owner:
+ *
+ *  - a file the patch created (`new file mode` section), now absent from
+ *    disk and untracked in engine HEAD;
+ *  - an upstream file the patch modified or deleted, whose engine copy is
+ *    back at HEAD (present, tracked, no diff). A scan-less re-export keeps
+ *    `filesAffected` as it is, so without this the stale entry would stay
+ *    in the manifest and in the reserved-range policy check.
+ */
+export declare function validateExpectedRemovals(paths: ProjectPaths, patches: PatchMetadata[], options: ReExportOptions, queue?: readonly PatchMetadata[]): Promise<string[]>;

package/dist/src/commands/re-export-removed.js

@@ -2,32 +2,45 @@
 import { lstat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { listTrackedInHead } from '../core/git-file-ops.js';
+import { getDirtyFiles } from '../core/git-status.js';
 import { parseDiffSections } from '../core/patch-parse.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { getNodeErrorCode } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { normalizeEngineRelativeInput } from './re-export-scan.js';
-/** Validates every retirement before any patch is written; typos never silently grant a carve-out. */
-export async function validateExpectedRemovals(paths, patches, options) {
+/**
+ * Validates every retirement before any patch is written; typos never
+ * silently grant a carve-out. Two shapes retire a file from its one
+ * selected owner:
+ *
+ *  - a file the patch created (`new file mode` section), now absent from
+ *    disk and untracked in engine HEAD;
+ *  - an upstream file the patch modified or deleted, whose engine copy is
+ *    back at HEAD (present, tracked, no diff). A scan-less re-export keeps
+ *    `filesAffected` as it is, so without this the stale entry would stay
+ *    in the manifest and in the reserved-range policy check.
+ */
+export async function validateExpectedRemovals(paths, patches, options, queue = patches) {
     const removed = [
         ...new Set((options.expectRemoved ?? []).map((file) => normalizeEngineRelativeInput(file, '--expect-removed'))),
     ];
     if (removed.length === 0)
         return removed;
     const tracked = await listTrackedInHead(paths.engine, removed);
+    const dirty = new Set(await getDirtyFiles(paths.engine, [...tracked]));
     for (const file of removed) {
         const owners = patches.filter((patch) => patch.filesAffected.includes(file));
-        if (owners.length !== 1 ||
-            tracked.has(file) ||
-            (await removalPathPresent(join(paths.engine, file)))) {
-            throw new InvalidArgumentError(`--expect-removed ${file} must be absent, untracked in engine HEAD, and owned by exactly one selected patch.`, '--expect-removed');
-        }
         const owner = owners[0];
-        if (!owner)
-            throw new InvalidArgumentError(`No selected owner for ${file}`, '--expect-removed');
-        const body = await readText(join(paths.patches, owner.filename));
-        if (!parseDiffSections(body).some((section) => section.targetPath === file && section.isNewFile)) {
-            throw new InvalidArgumentError(`--expect-removed ${file} was not created by its selected patch.`, '--expect-removed');
+        if (owners.length !== 1 || owner === undefined) {
+            throw new InvalidArgumentError(`--expect-removed ${file} must be owned by exactly one selected patch.` +
+                unselectedOwnerHint(file, patches, queue), '--expect-removed');
+        }
+        const section = parseDiffSections(await readText(join(paths.patches, owner.filename))).find((candidate) => candidate.targetPath === file);
+        if (tracked.has(file)) {
+            assertUpstreamFileBackAtHead(file, owner, section !== undefined && !section.isNewFile, dirty);
+        }
+        else {
+            await assertCreatedFileAbsent(paths, file, owner, section?.isNewFile === true);
         }
         if (owner.filesAffected.every((path) => removed.includes(path))) {
             throw new InvalidArgumentError('Retiring every file would empty the patch; use patch delete instead.', '--expect-removed');
@@ -35,6 +48,38 @@ export async function validateExpectedRemovals(paths, patches, options) {
     }
     return removed;
 }
+/**
+ * Each path retires from its own owner, so one run may retire paths from
+ * several selected patches. A path whose owner was left out of the
+ * selection names that owner, since adding it is the usual fix.
+ */
+function unselectedOwnerHint(file, selected, queue) {
+    const selectedNames = new Set(selected.map((patch) => patch.filename));
+    const outside = queue
+        .filter((patch) => !selectedNames.has(patch.filename) && patch.filesAffected.includes(file))
+        .map((patch) => patch.filename);
+    if (outside.length === 0)
+        return '';
+    return ` It is owned by ${outside.join(', ')}, which this run did not select; add it to the selection to retire both in one run.`;
+}
+async function assertCreatedFileAbsent(paths, file, owner, createdByOwner) {
+    if (await removalPathPresent(join(paths.engine, file))) {
+        throw new InvalidArgumentError(`--expect-removed ${file} is untracked in engine HEAD and still present on disk; ` +
+            'a patch-created file can be retired only once it is deleted.', '--expect-removed');
+    }
+    if (!createdByOwner) {
+        throw new InvalidArgumentError(`--expect-removed ${file} was not created by its selected patch ${owner.filename}.`, '--expect-removed');
+    }
+}
+function assertUpstreamFileBackAtHead(file, owner, changedByOwner, dirty) {
+    if (dirty.has(file)) {
+        throw new InvalidArgumentError(`--expect-removed ${file} is tracked in engine HEAD, but its engine copy still differs ` +
+            'from HEAD. Restore the HEAD copy first, then retire it.', '--expect-removed');
+    }
+    if (!changedByOwner) {
+        throw new InvalidArgumentError(`--expect-removed ${file} is not changed by its selected patch ${owner.filename}.`, '--expect-removed');
+    }
+}
 /** A dangling symlink is still an existing owned path, not an approved absence. */
 async function removalPathPresent(path) {
     try {

package/dist/src/commands/re-export-scan-owner.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Per-file owners for `re-export --scan --scan-file <patch>:<path>`.
+ *
+ * One change often spans a patch that creates files and a patch that
+ * registers or imports them. With `--scan-file` bound to a single target
+ * patch, that change took two invocations, and the adopting one could not
+ * carry the belts the other did. Naming the owner per file lets one call
+ * adopt each file into its patch while every other selected patch
+ * refreshes scan-less, all under the same `--refuse-foreign-drift` belt
+ * and in a single engine-lock hold.
+ */
+import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
+/** A `--scan-file` value split into its optional owner and its path. */
+export interface ScanFileOwnerSpec {
+    owner: string | undefined;
+    path: string;
+}
+/**
+ * Splits `<patch>:<path>` into owner and path. The owner is everything
+ * before the first `:`, and only when that part holds no path separator, so
+ * a plain path (even one with a later `:`) stays a path. A one-letter
+ * prefix before `:/` or `:\` reads as a Windows drive, not a patch.
+ */
+export declare function splitScanFileOwner(raw: string): ScanFileOwnerSpec;
+/** Rejoins a split value, so normalization can rewrite the path half only. */
+export declare function joinScanFileOwner(spec: ScanFileOwnerSpec): string;
+/**
+ * Argument-shape check, before any manifest is read: a multi-patch call has
+ * to say which patch each file joins.
+ */
+export declare function validateScanFileOwners(patches: readonly string[], scanFiles: readonly string[]): void;
+/**
+ * Resolves each `--scan-file` value to its owning selected patch. Returns
+ * `undefined` when no `--scan-file` was given. An unprefixed path belongs
+ * to the single selected patch (the historical form).
+ */
+export declare function assignScanFileOwners(scanFiles: readonly string[] | undefined, selectedPatches: readonly PatchMetadata[], manifest: PatchesManifest): Map<string, string[]> | undefined;
+/**
+ * The options one patch of the loop runs with. A patch with assigned files
+ * adopts exactly those; a selected patch without any refreshes scan-less,
+ * because `--scan` beside per-file owners scopes adoption to the named
+ * files rather than arming a broad directory scan for every other patch.
+ */
+export declare function scanOptionsForPatch(options: ReExportOptions, patchFilename: string, assignments: ReadonlyMap<string, string[]> | undefined): ReExportOptions;

package/dist/src/commands/re-export-scan-owner.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-file owners for `re-export --scan --scan-file <patch>:<path>`.
+ *
+ * One change often spans a patch that creates files and a patch that
+ * registers or imports them. With `--scan-file` bound to a single target
+ * patch, that change took two invocations, and the adopting one could not
+ * carry the belts the other did. Naming the owner per file lets one call
+ * adopt each file into its patch while every other selected patch
+ * refreshes scan-less, all under the same `--refuse-foreign-drift` belt
+ * and in a single engine-lock hold.
+ */
+import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
+import { resolvePatchIdentifier } from '../core/patch-manifest.js';
+import { InvalidArgumentError } from '../errors/base.js';
+/**
+ * Splits `<patch>:<path>` into owner and path. The owner is everything
+ * before the first `:`, and only when that part holds no path separator, so
+ * a plain path (even one with a later `:`) stays a path. A one-letter
+ * prefix before `:/` or `:\` reads as a Windows drive, not a patch.
+ */
+export function splitScanFileOwner(raw) {
+    const colon = raw.indexOf(':');
+    if (colon <= 0)
+        return { owner: undefined, path: raw };
+    const owner = raw.slice(0, colon).trim();
+    const path = raw.slice(colon + 1);
+    if (owner.length === 0 || /[/\\]/.test(owner))
+        return { owner: undefined, path: raw };
+    if (/^[A-Za-z]$/.test(owner) && /^[/\\]/.test(path))
+        return { owner: undefined, path: raw };
+    return { owner, path };
+}
+/** Rejoins a split value, so normalization can rewrite the path half only. */
+export function joinScanFileOwner(spec) {
+    return spec.owner === undefined ? spec.path : `${spec.owner}:${spec.path}`;
+}
+/**
+ * Argument-shape check, before any manifest is read: a multi-patch call has
+ * to say which patch each file joins.
+ */
+export function validateScanFileOwners(patches, scanFiles) {
+    if (patches.length === 0) {
+        throw new InvalidArgumentError('--scan-file needs explicit target patch identifiers.', '--scan-file');
+    }
+    if (patches.length === 1)
+        return;
+    const unowned = scanFiles.filter((file) => splitScanFileOwner(file).owner === undefined);
+    if (unowned.length > 0) {
+        throw new InvalidArgumentError(`--scan-file in a call with ${patches.length} patches must name each file's owning patch ` +
+            `as <patch>:<path> (for example --scan-file ${patches[0] ?? '201'}:${unowned[0] ?? '<path>'}). ` +
+            `Missing an owner: ${unowned.join(', ')}.`, '--scan-file');
+    }
+}
+/**
+ * Resolves each `--scan-file` value to its owning selected patch. Returns
+ * `undefined` when no `--scan-file` was given. An unprefixed path belongs
+ * to the single selected patch (the historical form).
+ */
+export function assignScanFileOwners(scanFiles, selectedPatches, manifest) {
+    if (scanFiles === undefined)
+        return undefined;
+    const selected = new Set(selectedPatches.map((patch) => patch.filename));
+    const byPatch = new Map();
+    const ownerByFile = new Map();
+    for (const raw of scanFiles) {
+        const { owner, path } = splitScanFileOwner(raw);
+        const filename = resolveOwner(owner, selectedPatches, manifest);
+        if (!selected.has(filename)) {
+            throw new InvalidArgumentError(`--scan-file ${raw}: ${filename} is not among the selected patches. ` +
+                'Pass it as a positional patch too.', '--scan-file');
+        }
+        const previous = ownerByFile.get(path);
+        if (previous !== undefined && previous !== filename) {
+            throw new InvalidArgumentError(`--scan-file path is assigned to more than one patch: ${path} (${previous}, ${filename})`, '--scan-file');
+        }
+        ownerByFile.set(path, filename);
+        const files = byPatch.get(filename) ?? [];
+        if (!files.includes(path))
+            files.push(path);
+        byPatch.set(filename, files);
+    }
+    for (const files of byPatch.values())
+        files.sort();
+    return byPatch;
+}
+function resolveOwner(owner, selectedPatches, manifest) {
+    if (owner === undefined) {
+        const only = selectedPatches.length === 1 ? selectedPatches[0] : undefined;
+        if (only === undefined) {
+            throw new InvalidArgumentError('--scan-file in a multi-patch call must name its owning patch as <patch>:<path>.', '--scan-file');
+        }
+        return only.filename;
+    }
+    const match = resolvePatchIdentifier(owner, manifest.patches);
+    if (!match) {
+        throw new InvalidArgumentError(`--scan-file: ${formatPatchNotFoundError(owner, manifest.patches)}`, '--scan-file');
+    }
+    return match.filename;
+}
+/**
+ * The options one patch of the loop runs with. A patch with assigned files
+ * adopts exactly those; a selected patch without any refreshes scan-less,
+ * because `--scan` beside per-file owners scopes adoption to the named
+ * files rather than arming a broad directory scan for every other patch.
+ */
+export function scanOptionsForPatch(options, patchFilename, assignments) {
+    if (assignments === undefined)
+        return options;
+    const assigned = assignments.get(patchFilename);
+    if (assigned !== undefined)
+        return { ...options, scanFiles: assigned };
+    const scanLess = { ...options, scan: false };
+    delete scanLess.scanFiles;
+    return scanLess;
+}

package/dist/src/commands/re-export-scan.d.ts

@@ -1,10 +1,15 @@
+import { type PatchQueueContext } from '../core/patch-lint.js';
 import type { PatchesManifest } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
 export interface ScanResult {
     updated: string[];
     added: string[];
     removed: string[];
 }
-/** Normalizes repeatable `--scan-file` inputs into safe engine-relative paths. */
+/**
+ * Normalizes repeatable `--scan-file` inputs into safe engine-relative
+ * paths, keeping an optional `<patch>:` owner prefix intact.
+ */
 export declare function normalizeScanFiles(scanFiles: readonly string[] | undefined): string[] | undefined;
 /** Normalizes one CLI-provided path into a safe engine-relative path. */
 export declare function normalizeEngineRelativeInput(rawPath: string, flagName: string): string;
@@ -44,15 +49,20 @@ export declare function assertScanAdoptionsHaveNoForwardImports(args: {
     engineDir: string;
     patchFilename: string;
     added: readonly string[];
+    /**
+     * Threads `patchLint.forwardRegistration` so jar.mn registrations are judged
+     * too, and `patchPolicy`, so the remedy names a legal order.
+     */
+    config?: FireForgeConfig;
+    /** `--declarations-out`: where the one `--from`-ready report goes. */
+    declarationsOut?: string | undefined;
 }): Promise<void>;
-/**
- * The one remedy sentence for a forward import a patch body cannot carry.
- * Shared by the `--scan` adoption gate and the plain re-export projection
- * gate so both refusals point at the same commands.
- *
- * @param reRunHint - What to do after the fix ("re-running the scan")
- */
-export declare function formatForwardImportRemedy(reRunHint: string): string;
+/** The manifest rows a queue context carries, for remedy computations. */
+export declare function manifestFromQueue(ctx: PatchQueueContext): PatchesManifest;
+/** `{ category }` of the named queue entry, or `{}` when it has no metadata. */
+export declare function categoryOf(ctx: PatchQueueContext, filename: string): {
+    category?: string;
+};
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export declare function assertScanFileAdditionsHaveDiffHunks(args: {
     diffContent: string;

package/dist/src/commands/re-export-scan.js

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
@@ -15,15 +15,27 @@ import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
 import { isContainedRelativePath, normalizePathSlashes, stripEnginePrefix, } from '../utils/paths.js';
+import { formatDeclarationsReport, writeDeclarationsReport } from './declarations-report.js';
+import { formatForwardImportRemedy } from './forward-import-remedy.js';
+import { joinScanFileOwner, splitScanFileOwner } from './re-export-scan-owner.js';
 const SCAN_ADD_COUNT_THRESHOLD = 3;
 /** Concurrency bound for existence probes (matches the classify/lint pools). */
 const PATH_PROBE_CONCURRENCY = 8;
 const SCAN_DIR_COUNT_THRESHOLD = 2;
-/** Normalizes repeatable `--scan-file` inputs into safe engine-relative paths. */
+/**
+ * Normalizes repeatable `--scan-file` inputs into safe engine-relative
+ * paths, keeping an optional `<patch>:` owner prefix intact.
+ */
 export function normalizeScanFiles(scanFiles) {
-    const normalized = [...new Set(scanFiles ?? [])]
-        .map((file) => normalizeEngineRelativeInput(file, '--scan-file'))
-        .sort();
+    const normalized = [
+        ...new Set((scanFiles ?? []).map((file) => {
+            const spec = splitScanFileOwner(file);
+            return joinScanFileOwner({
+                owner: spec.owner,
+                path: normalizeEngineRelativeInput(spec.path, '--scan-file'),
+            });
+        })),
+    ].sort();
     return normalized.length > 0 ? normalized : undefined;
 }
 /** Normalizes one CLI-provided path into a safe engine-relative path. */
@@ -171,7 +183,7 @@ function scanAdditionsNeedConfirmation(added) {
  * (all adopt through the same scan result), including dry-run.
  */
 export async function assertScanAdoptionsHaveNoForwardImports(args) {
-    const { patchesDir, engineDir, patchFilename, added } = args;
+    const { patchesDir, engineDir, patchFilename, added, config } = args;
     if (added.length === 0)
         return;
     const candidateDiff = await getDiffForFilesAgainstHead(engineDir, [...added]);
@@ -180,7 +192,7 @@ export async function assertScanAdoptionsHaveNoForwardImports(args) {
     const candidateNewFiles = buildNewFileTextProjection(candidateDiff);
     const candidateCreations = detectNewFilesInDiff(candidateDiff);
     const candidateAdditions = buildModifiedFileAdditionsFromDiff(candidateDiff);
-    const baseCtx = await buildPatchQueueContext(patchesDir);
+    const baseCtx = await buildPatchQueueContext(patchesDir, config);
     const projectedEntries = baseCtx.entries.map((entry) => {
         if (entry.filename !== patchFilename)
             return entry;
@@ -193,27 +205,51 @@ export async function assertScanAdoptionsHaveNoForwardImports(args) {
         };
     });
     const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
-    const projectedIssues = lintPatchQueue({ entries: projectedEntries }).filter((i) => i.severity === 'error');
+    const projectedIssues = lintPatchQueue({ ...baseCtx, entries: projectedEntries }).filter((i) => i.severity === 'error');
     const addedSet = new Set(added);
-    const offending = computeProjectedLintRegressions(baselineIssues, projectedIssues).filter((issue) => issue.check === 'forward-import' && addedSet.has(issue.file));
-    if (offending.length === 0)
+    const regressions = computeProjectedLintRegressions(baselineIssues, projectedIssues);
+    const offending = regressions.filter((issue) => issue.check === 'forward-import' && addedSet.has(issue.file));
+    // A forward registration (jar.mn packaging, a test manifest, ...) only
+    // regresses here because the candidates moved the registered file's
+    // creation to this patch, or because a candidate registers it: either way
+    // the adoption caused it, and the operator should declare it in the same
+    // pass as the import instead of meeting it later in the queue audit.
+    const registrations = regressions.filter((issue) => issue.check === 'forward-registration');
+    if (offending.length === 0 && registrations.length === 0)
         return;
     const details = offending.map((issue) => `  - ${issue.file}: ${issue.message}`).join('\n');
-    throw new GeneralError(`Refusing to adopt ${offending.length} scanned file${offending.length === 1 ? '' : 's'} into ${patchFilename} ` +
-        `because they import modules created by later patches:\n${details}\n` +
-        formatForwardImportRemedy('re-running the scan'));
+    const registrationDetails = registrations
+        .map((issue) => `  - ${issue.file}: ${issue.message}`)
+        .join('\n');
+    const parts = [];
+    if (offending.length > 0) {
+        parts.push(`${offending.length} scanned file${offending.length === 1 ? '' : 's'} import modules created by later patches:\n${details}`);
+    }
+    if (registrations.length > 0) {
+        parts.push(`${registrations.length} forward registration${registrations.length === 1 ? '' : 's'} the adoption would leave dangling:\n${registrationDetails}`);
+    }
+    const report = await writeDeclarationsReport(dirname(resolve(patchesDir)), [...offending, ...registrations], args.declarationsOut);
+    throw new GeneralError(`Refusing to adopt scanned files into ${patchFilename}: ${parts.join('\n')}\n` +
+        (report !== undefined ? `${formatDeclarationsReport(report).join('\n')}\n` : '') +
+        formatForwardImportRemedy({
+            reRunHint: 're-running the scan',
+            issues: [...offending, ...registrations],
+            manifest: manifestFromQueue(baseCtx),
+            ...(args.config !== undefined ? { config: args.config } : {}),
+            ...categoryOf(baseCtx, patchFilename),
+        }));
 }
-/**
- * The one remedy sentence for a forward import a patch body cannot carry.
- * Shared by the `--scan` adoption gate and the plain re-export projection
- * gate so both refusals point at the same commands.
- *
- * @param reRunHint - What to do after the fix ("re-running the scan")
- */
-export function formatForwardImportRemedy(reRunHint) {
-    return ('Export those files as their own later patch ("fireforge export --order <n>" / ' +
-        '"fireforge patch split --order <n>") or declare the intentional dependency with ' +
-        `"fireforge patch staged-dependency --add" before ${reRunHint}.`);
+/** The manifest rows a queue context carries, for remedy computations. */
+export function manifestFromQueue(ctx) {
+    return {
+        version: 1,
+        patches: ctx.entries.flatMap((entry) => (entry.metadata ? [entry.metadata] : [])),
+    };
+}
+/** `{ category }` of the named queue entry, or `{}` when it has no metadata. */
+export function categoryOf(ctx, filename) {
+    const category = ctx.entries.find((entry) => entry.filename === filename)?.metadata?.category;
+    return category !== undefined ? { category } : {};
 }
 /** Refuses explicit `--scan-file` additions that did not produce patch hunks. */
 export function assertScanFileAdditionsHaveDiffHunks(args) {