@hominis/fireforge 0.49.2 → 0.50.0

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

@@ -10,6 +10,9 @@ 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 { validateStagedDependencyAdd } from './staged-dependency-validate.js';
 /** Joins the names of the missing flags for error attribution. */
 function missingFlagList(pairs) {
@@ -146,41 +149,6 @@ function resolveRegistrationRemovalTarget(options, staged) {
     }
     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.
  */
@@ -202,9 +170,6 @@ function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, tar
         ? `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);
-}
 /**
  * Runs the metadata-only staged-dependency mutation command.
  *
@@ -216,6 +181,10 @@ 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
@@ -281,12 +250,13 @@ export async function patchStagedDependencyCommand(projectRoot, identifier, opti
     info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, target)}.`);
     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',
@@ -313,7 +283,10 @@ export function registerPatchStagedDependency(parent, context) {
         .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('--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));
+}

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

@@ -1,4 +1,4 @@
-import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+import type { PatchesManifest, PatchMetadata, ReExportOptions } from '../types/commands/index.js';
 import type { ProjectPaths } from '../types/config.js';
 /**
  * Shared per-run context for the adjacency advisory: the classification
@@ -18,6 +18,23 @@ export interface AdjacentUnmanagedContext {
     approvedUnmanaged: ReadonlySet<string>;
     /** Approved paths actually met this run, so unused ones can be surfaced. */
     approvedSeen: Set<string>;
+    /**
+     * Engine-relative paths named by `--expect-new`: files this session
+     * created and will adopt with its next export (or `--scan-file`). They
+     * pass the belt and are reported, while every other adjacent file still
+     * refuses, so a peer's neighbour is not admitted with them.
+     */
+    expectedNew: ReadonlySet<string>;
+    /** `--expect-new` paths actually met this run. */
+    expectedNewSeen: Set<string>;
+    /**
+     * Reviewed `--adjacent-ignore` entries: an engine-relative path, or a
+     * glob whose `*` stays within one path segment. Matches are reported in
+     * one line and never refuse.
+     */
+    adjacentIgnore: readonly string[];
+    /** `--adjacent-ignore` entries that matched a file this run. */
+    adjacentIgnoreSeen: Set<string>;
     /**
      * Offenders collected across the loop. `files` stays the bare paths that
      * downstream consumers already read. `anchored` carries the same entries
@@ -30,6 +47,16 @@ export interface AdjacentUnmanagedContext {
         anchored: string[];
     }[];
 }
+/**
+ * Builds the run's adjacency context. The path flags are normalized once
+ * here, so the per-file comparison matches git's engine-relative output.
+ */
+export declare function buildAdjacentUnmanagedContext(options: ReExportOptions, binaryName: string, furnacePrefixes: ReadonlySet<string>): AdjacentUnmanagedContext;
+/**
+ * The one definition of "adjacent", shared by the per-patch notice and the
+ * run-level refusal so the two cannot drift apart.
+ */
+export declare const ADJACENT_MEANS: string;
 /** Returns the subset of `files` that no longer exist under `engineDir`. */
 export declare function findMissingFiles(engineDir: string, files: readonly string[]): Promise<string[]>;
 /**
@@ -44,8 +71,13 @@ export declare function findMissingFiles(engineDir: string, files: readonly stri
 export interface AdjacentUnmanagedFile {
     /** Engine-relative path of the unmanaged file. */
     file: string;
-    /** Directory holding at least one file this patch owns. */
+    /**
+     * Directory holding at least one file this patch owns, or for a
+     * registration-named file, the directory of the carrier naming it.
+     */
     anchorDir: string;
+    /** The owned carrier whose added registration line names the file. */
+    registeredBy?: string;
 }
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
@@ -62,3 +94,14 @@ export declare function reportAdjacentUnmanagedFiles(args: {
     currentFilesAffected: readonly string[];
     ctx: AdjacentUnmanagedContext;
 }): Promise<boolean>;
+/**
+ * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.
+ *
+ * An `--expect-new` path is a promise that the next export adopts it, so a
+ * met one is repeated as the export still owed, and an unmet one is a
+ * warning: a typo there leaves the refusal armed for the file it meant to
+ * admit. An unmatched `--adjacent-ignore` entry is only noted, because a
+ * reviewed ignore list is reused across runs and patches, and "not met"
+ * is its normal case.
+ */
+export declare function reportAdjacentCarveOutUsage(ctx: AdjacentUnmanagedContext): void;

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

@@ -21,6 +21,34 @@ import { isGeneratedBrandingPath } from '../core/status-classify.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { escapeRegex } from '../utils/regex.js';
+import { findRegisteredChangedFiles } from './re-export-adjacent-registrations.js';
+import { normalizeEngineRelativeInput } from './re-export-scan.js';
+/**
+ * Builds the run's adjacency context. The path flags are normalized once
+ * here, so the per-file comparison matches git's engine-relative output.
+ */
+export function buildAdjacentUnmanagedContext(options, binaryName, furnacePrefixes) {
+    const normalized = (flag, values) => (values ?? []).map((value) => normalizeEngineRelativeInput(value, flag));
+    return {
+        binaryName,
+        furnacePrefixes,
+        refuseAdjacentUnmanaged: options.refuseAdjacentUnmanaged === true,
+        approvedUnmanaged: new Set(normalized('--expect-unmanaged', options.expectUnmanaged)),
+        approvedSeen: new Set(),
+        expectedNew: new Set(normalized('--expect-new', options.expectNew)),
+        expectedNewSeen: new Set(),
+        adjacentIgnore: normalized('--adjacent-ignore', options.adjacentIgnore),
+        adjacentIgnoreSeen: new Set(),
+        refusals: [],
+    };
+}
+/**
+ * The one definition of "adjacent", shared by the per-patch notice and the
+ * run-level refusal so the two cannot drift apart.
+ */
+export const ADJACENT_MEANS = 'Adjacent means the file sits in the same directory as a file this patch owns, ' +
+    'or a registration line this patch adds (jar.mn, moz.build, test manifest) names it.';
 /** Concurrency bound for existence probes (matches the classify/lint pools). */
 const PATH_PROBE_CONCURRENCY = 8;
 /** Returns the subset of `files` that no longer exist under `engineDir`. */
@@ -42,14 +70,41 @@ function isToolManagedPath(file, isNewFile, ctx) {
     }
     return false;
 }
+/**
+ * Matches an `--adjacent-ignore` entry. A `*` stays inside one path
+ * segment, the same narrowness as `buildAudit.unpackaged`: a carve-out that
+ * silently spans subtrees is how a reviewed exception becomes a blanket one.
+ */
+function matchesIgnoreEntry(entry, file) {
+    if (!entry.includes('*'))
+        return entry === file;
+    const pattern = entry
+        .split('*')
+        .map((part) => escapeRegex(part))
+        .join('[^/]*');
+    return new RegExp(`^${pattern}$`).test(file);
+}
+/**
+ * Lists the unmanaged files a re-export of this patch would plausibly have
+ * to capture: changed files directly in a directory the patch owns a file
+ * in, and changed files a registration line the patch adds names. A file in
+ * a sibling or nested directory is not adjacent. The directory listing
+ * recurses (pathspecs do), so it is filtered back to the exact directories,
+ * the same footprint the broad `--scan` adopts from.
+ */
 async function findAdjacentUnmanagedFiles(args) {
     const { currentFilesAffected, engineDir, manifest, patchFilename, ctx } = args;
     const parentDirs = [...new Set(currentFilesAffected.map((file) => dirname(file)))];
+    const parentDirSet = new Set(parentDirs);
     const currentSet = new Set(currentFilesAffected);
     const claimedByOthers = getClaimedFiles(manifest, patchFilename);
-    // First anchor wins: the dirs are scanned in ownership order and a file
-    // lives in exactly one of them, so the map is a dedupe, not a choice.
+    // First anchor wins: a file lives in exactly one directory, and a
+    // directory anchor is the stronger statement than a registration one.
     const candidates = new Map();
+    const isCandidate = (file, isNewFile) => !currentSet.has(file) &&
+        !claimedByOthers.has(file) &&
+        !candidates.has(file) &&
+        !isToolManagedPath(file, isNewFile, ctx);
     for (const dir of parentDirs) {
         const [modifiedFiles, untrackedFiles] = await Promise.all([
             getModifiedFilesInDir(engineDir, dir),
@@ -57,41 +112,80 @@ async function findAdjacentUnmanagedFiles(args) {
         ]);
         const untrackedSet = new Set(untrackedFiles);
         for (const file of [...modifiedFiles, ...untrackedFiles]) {
-            if (currentSet.has(file) || claimedByOthers.has(file))
+            if (!parentDirSet.has(dirname(file)))
                 continue;
-            if (isToolManagedPath(file, untrackedSet.has(file), ctx))
-                continue;
-            if (!candidates.has(file))
-                candidates.set(file, dir);
+            if (isCandidate(file, untrackedSet.has(file))) {
+                candidates.set(file, { file, anchorDir: dirname(file) });
+            }
+        }
+    }
+    const registered = await findRegisteredChangedFiles(engineDir, currentFilesAffected);
+    for (const { file, carrier } of registered) {
+        // A registered path is a patch candidate whatever its tracking state,
+        // so it is classified as new: only a generated path is tool-managed.
+        if (isCandidate(file, true)) {
+            candidates.set(file, { file, anchorDir: dirname(carrier), registeredBy: carrier });
         }
     }
-    return [...candidates.entries()]
-        .map(([file, anchorDir]) => ({ file, anchorDir }))
-        .sort((a, b) => a.file.localeCompare(b.file));
+    return [...candidates.values()].sort((a, b) => a.file.localeCompare(b.file));
+}
+function dispositionOf(file, ctx) {
+    if (ctx.approvedUnmanaged.has(file)) {
+        ctx.approvedSeen.add(file);
+        return 'approved';
+    }
+    if (ctx.expectedNew.has(file)) {
+        ctx.expectedNewSeen.add(file);
+        return 'expected-new';
+    }
+    const ignore = ctx.adjacentIgnore.find((entry) => matchesIgnoreEntry(entry, file));
+    if (ignore !== undefined) {
+        ctx.adjacentIgnoreSeen.add(ignore);
+        return 'ignored';
+    }
+    return 'refusing';
 }
 /**
- * Splits the candidates into the ones that refuse and the ones a
- * `--expect-unmanaged` carve-out admits. Approved paths are recorded as seen
- * so an unused carve-out can be reported, and are returned rather than
- * dropped, so the exception stays visible instead of quietly widening.
+ * Splits the candidates into the ones that refuse and the ones a carve-out
+ * (`--expect-unmanaged`, `--expect-new`, `--adjacent-ignore`) admits. Met
+ * carve-outs are recorded so an unused one can be reported, and admitted
+ * files are returned rather than dropped, so the exception stays visible
+ * instead of quietly widening.
  */
 function partitionApproved(files, ctx) {
-    const refusing = [];
-    const approved = [];
-    for (const entry of files) {
-        if (ctx.approvedUnmanaged.has(entry.file)) {
-            ctx.approvedSeen.add(entry.file);
-            approved.push(entry);
-        }
-        else {
-            refusing.push(entry);
-        }
-    }
-    return { refusing, approved };
+    const groups = {
+        refusing: [],
+        approved: [],
+        'expected-new': [],
+        ignored: [],
+    };
+    for (const entry of files)
+        groups[dispositionOf(entry.file, ctx)].push(entry);
+    return groups;
 }
-/** Renders `<file> (beside engine/<dir>)` for a notice line. */
+/** How a notice names one file's anchor. */
+function describeAnchor(entry) {
+    return entry.registeredBy !== undefined
+        ? `registered by engine/${entry.registeredBy}`
+        : `beside engine/${entry.anchorDir}`;
+}
+/** Renders `<file> (beside engine/<dir>)` or `<file> (registered by engine/<carrier>)`. */
 function describeAnchored(entry) {
-    return `${entry.file} (beside engine/${entry.anchorDir})`;
+    return `${entry.file} (${describeAnchor(entry)})`;
+}
+/** The admitted-file notice lines, one per carve-out that admitted anything. */
+function reportAdmitted(patchFilename, groups) {
+    const notices = [
+        [groups.approved, 'admitted by --expect-unmanaged'],
+        [groups['expected-new'], 'expected by --expect-new'],
+        [groups.ignored, 'ignored by --adjacent-ignore'],
+    ];
+    for (const [entries, how] of notices) {
+        if (entries.length === 0)
+            continue;
+        info(`${patchFilename}: ${entries.length} adjacent unmanaged file(s) ${how} ` +
+            `(${entries.map(describeAnchored).join(', ')}) — reported, not refused.`);
+    }
 }
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
@@ -119,20 +213,19 @@ export async function reportAdjacentUnmanagedFiles(args) {
         patchFilename: patch.filename,
         ctx,
     });
-    const { refusing: unmanagedFiles, approved } = partitionApproved(allUnmanaged, ctx);
-    if (approved.length > 0) {
-        info(`${patch.filename}: ${approved.length} adjacent unmanaged file(s) admitted by ` +
-            `--expect-unmanaged (${approved.map(describeAnchored).join(', ')}) — reported, not refused.`);
-    }
+    const groups = partitionApproved(allUnmanaged, ctx);
+    reportAdmitted(patch.filename, groups);
+    const unmanagedFiles = groups.refusing;
     if (unmanagedFiles.length === 0)
         return false;
     const firstFew = unmanagedFiles.slice(0, 3).map(describeAnchored).join(', ');
     const more = unmanagedFiles.length > 3 ? `, +${unmanagedFiles.length - 3} more` : '';
-    warn(`${patch.filename}: found ${unmanagedFiles.length} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}); ` +
-        `adjacent means the file sits in a directory this patch already owns a file in. ` +
-        `Plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files.`);
+    warn(`${patch.filename}: found ${unmanagedFiles.length} unmanaged file(s) adjacent to this patch's ownership (${firstFew}${more}). ` +
+        `${ADJACENT_MEANS} ` +
+        `Plain re-export keeps filesAffected unchanged — use --scan-file to include reviewed files, ` +
+        `or --expect-new for a file your next export adopts.`);
     for (const entry of unmanagedFiles) {
-        info(`  ${entry.file} — beside engine/${entry.anchorDir} — ` +
+        info(`  ${entry.file} — ${describeAnchor(entry)} — ` +
             `fireforge re-export ${patch.filename} --scan --scan-file ${entry.file}`);
     }
     if (ctx.refuseAdjacentUnmanaged) {
@@ -145,3 +238,29 @@ export async function reportAdjacentUnmanagedFiles(args) {
     }
     return false;
 }
+/**
+ * End-of-run accounting for `--expect-new` and `--adjacent-ignore`.
+ *
+ * An `--expect-new` path is a promise that the next export adopts it, so a
+ * met one is repeated as the export still owed, and an unmet one is a
+ * warning: a typo there leaves the refusal armed for the file it meant to
+ * admit. An unmatched `--adjacent-ignore` entry is only noted, because a
+ * reviewed ignore list is reused across runs and patches, and "not met"
+ * is its normal case.
+ */
+export function reportAdjacentCarveOutUsage(ctx) {
+    const unseenNew = [...ctx.expectedNew].filter((file) => !ctx.expectedNewSeen.has(file));
+    if (unseenNew.length > 0) {
+        warn(`--expect-new path(s) were not met as adjacent unmanaged files this run: ` +
+            `${unseenNew.join(', ')}. Check the path for a typo, and that a selected patch owns a ` +
+            'file in its directory or registers it. The refusal stayed armed for everything else.');
+    }
+    if (ctx.expectedNewSeen.size > 0) {
+        info(`--expect-new admitted ${[...ctx.expectedNewSeen].sort().join(', ')}, which no patch owns ` +
+            'yet. Export them next so the queue does not register files it does not ship.');
+    }
+    const unseenIgnore = ctx.adjacentIgnore.filter((entry) => !ctx.adjacentIgnoreSeen.has(entry));
+    if (unseenIgnore.length > 0) {
+        info(`--adjacent-ignore entries matched no adjacent file this run: ${unseenIgnore.join(', ')}.`);
+    }
+}

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

@@ -8,7 +8,7 @@
  * (`re-export-adjacent.ts`) warns about unmanaged neighbour files but is
  * structurally blind to drift inside owned files. This module compares
  * the old body against the refreshed body per file and reports the
- * payload lines that are about to enter the body. Under
+ * payload lines that are about to enter or leave the body. Under
  * `--refuse-foreign-drift` the patch is skipped and the run exits
  * non-zero, mirroring `--refuse-adjacent-unmanaged`.
  *
@@ -41,23 +41,39 @@ export interface ForeignDriftContext {
         reason: ForeignDriftRefusalReason;
     }[];
 }
-/** One owned file's foreign drift between the old and refreshed body. */
+/**
+ * One owned file's foreign drift between the old and refreshed body,
+ * counted as edits to the engine file rather than as body payload, so a
+ * deletion-only change is drift like any other.
+ */
 export interface FileForeignDrift {
     file: string;
-    /** `+` payload lines in the new body not present in the old body. */
+    /**
+     * Lines the engine file gained since the old body: `+` payload the new
+     * body carries that the old did not, plus `-` payload the old body carried
+     * that the new one dropped (an upstream line restored).
+     */
     addedLines: number;
-    /** `-` payload lines in the new body not present in the old body. */
+    /**
+     * Lines the engine file lost since the old body: `-` payload the new body
+     * carries that the old did not, plus `+` payload the old body carried that
+     * the new one dropped (a line the patch added, now deleted).
+     */
     removedLines: number;
-    /** `@@` headers of new-body hunks carrying foreign lines (capped). */
+    /** `@@` headers of the hunks carrying those lines (capped). */
     hunkSummaries: string[];
     /** True when a binary section's recorded new-side blob hash changed. */
     binaryChanged: boolean;
 }
 /**
  * Pure comparison: per owned file, which `+`/`-` payload lines the
- * refreshed body carries that the old body did not. Files not in
- * `previousFilesAffected` are skipped, since those are intentional
- * adoptions (`--scan`) rather than drift.
+ * refreshed body carries that the old body did not, and which the old body
+ * carried that the refreshed one dropped. Both directions are drift: a
+ * concurrent session deleting a line the patch added changes the patch as
+ * surely as one adding a line, and a belt that only saw absorbed lines let
+ * such a deletion through silently. Files not in `previousFilesAffected`
+ * are skipped, since those are intentional adoptions (`--scan`) or
+ * retirements (`--expect-removed`) rather than drift.
  */
 export declare function computeForeignDrift(oldBody: string, newBody: string, previousFilesAffected: readonly string[]): FileForeignDrift[];
 /**
@@ -71,6 +87,18 @@ export declare function reportForeignDrift(args: {
     engineDir: string;
     newDiffContent: string;
     ctx: ForeignDriftContext;
+    /**
+     * The patch's files that the comparison covers. Defaults to its
+     * `filesAffected`; the caller narrows it by the `--expect-removed`
+     * retirements, which leave the body on purpose.
+     */
+    ownedFiles?: readonly string[];
+    /**
+     * Files a `--scan`/`--scan-file` adoption brings in this run. They sit
+     * outside the comparison (nothing to compare against) and count as
+     * expected, so naming one in `--expect` is not reported as unseen.
+     */
+    adoptedFiles?: readonly string[];
 }): Promise<boolean>;
 /**
  * Names `--expect` paths that never drifted this run. A typo'd