@hominis/fireforge 0.49.2 → 0.50.0

package/dist/src/core/coverage-records.js

@@ -0,0 +1,350 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-path packaging-coverage anchors for scoped `fireforge test --build`.
+ *
+ * A scoped build used to carry one claim anchored to the whole engine, so
+ * any edit outside the new scope (a peer's, on a shared engine, nearly
+ * always) replaced it. Each staged request path now carries its own anchor
+ * restricted to its own staging inputs, and a claim is dropped only when
+ * one of those inputs changed.
+ *
+ * The staging inputs of a request path are its manifest directory (the
+ * nearest directory at or above it that holds a test manifest) plus every
+ * path a manifest there names outside that directory (`support-files`,
+ * `head`, `!/`-rooted shared fixtures). Without the full mozbuild graph
+ * that is the closest sound boundary: an edit outside it cannot change
+ * what the harness stages for that path.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join, posix } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { sha256Hex } from '../utils/hash.js';
+import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
+import { getHead, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/**
+ * Basenames of the test manifests whose entries decide what a packaged test
+ * runtime stages.
+ */
+const TEST_MANIFEST_BASENAMES = new Set([
+    'xpcshell.toml',
+    'xpcshell.ini',
+    'browser.toml',
+    'browser.ini',
+    'mochitest.toml',
+    'mochitest.ini',
+    'chrome.toml',
+    'chrome.ini',
+    'a11y.toml',
+    'a11y.ini',
+]);
+/** Directory entries a directory request's manifest walk visits at most. */
+const MAX_WALK_ENTRIES = 5000;
+/**
+ * Hex-encoded SHA-256 of an engine-relative file, matching the digest the
+ * baseline writer produces. A missing file hashes to
+ * {@link DELETED_FILE_FINGERPRINT}. `undefined` on any other IO error,
+ * which every caller treats as "cannot prove unchanged".
+ * @param engineDir - Path to the engine directory
+ * @param relPath - Engine-relative POSIX path
+ */
+export async function hashEngineFile(engineDir, relPath) {
+    try {
+        return sha256Hex(await readFile(join(engineDir, relPath)));
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return DELETED_FILE_FINGERPRINT;
+        verbose(`Coverage anchor: could not hash ${relPath} — ${toError(error).message}`);
+        return undefined;
+    }
+}
+/** True for a test manifest path (by basename). */
+export function isTestManifestPath(path) {
+    return TEST_MANIFEST_BASENAMES.has(posix.basename(path));
+}
+/** Normalizes a request path: forward slashes, no `./`, no trailing slash. */
+export function normalizeRequestPath(path) {
+    const normalized = posix.normalize(normalizePathSlashes(path.trim())).replace(/\/+$/, '');
+    return normalized === '.' ? '' : normalized;
+}
+/** True when `file` is `prefix` or sits beneath it. The empty prefix is the whole tree. */
+export function isUnderPath(file, prefix) {
+    return prefix === '' || file === prefix || file.startsWith(`${prefix}/`);
+}
+/**
+ * Reads HEAD and the dirty set. Throws on a git failure other than an
+ * unborn HEAD: callers treat that as "nothing can be proven unchanged".
+ * @param engineDir - Path to the engine directory
+ */
+export async function readEngineContentState(engineDir) {
+    let head;
+    try {
+        head = await getHead(engineDir);
+    }
+    catch (error) {
+        if (!isMissingHeadError(error))
+            throw error;
+    }
+    const dirty = new Set();
+    if (head !== undefined) {
+        for (const line of (await git(['diff', '--name-only', 'HEAD'], engineDir)).split('\n')) {
+            if (line.trim())
+                dirty.add(line.trim());
+        }
+    }
+    for (const file of await getUntrackedFiles(engineDir))
+        dirty.add(file);
+    return { engineDir, head, dirty, hashes: new Map(), diffs: new Map() };
+}
+function liveHash(state, path) {
+    let pending = state.hashes.get(path);
+    if (pending === undefined) {
+        pending = hashEngineFile(state.engineDir, path);
+        state.hashes.set(path, pending);
+    }
+    return pending;
+}
+/** Paths committed between `from` and HEAD, or undefined when `from` cannot be diffed. */
+function committedSince(state, from) {
+    let pending = state.diffs.get(from);
+    if (pending === undefined) {
+        pending = git(['diff', '--name-only', `${from}..HEAD`], state.engineDir).then((output) => new Set(output
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)), (error) => {
+            verbose(`Coverage anchor: cannot diff ${from}..HEAD — ${toError(error).message}`);
+            return undefined;
+        });
+        state.diffs.set(from, pending);
+    }
+    return pending;
+}
+/**
+ * Paths whose content may differ from the anchor, restricted to `inputs`
+ * (undefined: the whole tree) and excluding `rebuilt` paths. Undefined when
+ * the anchor cannot be compared at all (no usable HEAD on either side).
+ */
+async function candidatePaths(state, anchor, inputs, rebuilt) {
+    if (state.head === undefined || anchor.engineHeadSha === '')
+        return undefined;
+    const inScope = (file) => (inputs === undefined || inputs.some((input) => isUnderPath(file, input))) &&
+        !rebuilt.some((path) => isUnderPath(file, path));
+    const candidates = new Set();
+    if (state.head !== anchor.engineHeadSha) {
+        const committed = await committedSince(state, anchor.engineHeadSha);
+        if (committed === undefined)
+            return undefined;
+        for (const file of committed)
+            if (inScope(file))
+                candidates.add(file);
+    }
+    for (const file of state.dirty)
+        if (inScope(file))
+            candidates.add(file);
+    for (const file of Object.keys(anchor.fingerprints))
+        if (inScope(file))
+            candidates.add(file);
+    return candidates;
+}
+/**
+ * Inputs whose live content differs from what the anchor staged, sorted.
+ * Undefined when the anchor cannot be compared, which every caller treats as
+ * "changed".
+ *
+ * @param state - Engine state from {@link readEngineContentState}
+ * @param anchor - The claim's anchor
+ * @param inputs - Staging inputs to compare, or undefined for the whole tree
+ * @param rebuilt - Request paths the current build stages afresh
+ */
+export async function findChangedInputs(state, anchor, inputs, rebuilt = []) {
+    const candidates = await candidatePaths(state, anchor, inputs, rebuilt);
+    if (candidates === undefined)
+        return undefined;
+    const changed = [];
+    for (const file of candidates) {
+        const recorded = anchor.fingerprints[file];
+        // Not recorded: the staged copy is the anchor HEAD's, and the file is
+        // a candidate only because it was committed or dirtied since.
+        if (recorded === undefined || (await liveHash(state, file)) !== recorded)
+            changed.push(file);
+    }
+    return changed.sort();
+}
+/**
+ * The anchor after the current build restaged `rebuilt`: recorded content
+ * for those paths becomes their live content. Undefined when that content
+ * cannot be read or the anchor cannot be compared.
+ */
+export async function refreshAnchor(state, anchor, rebuilt) {
+    const everything = await candidatePaths(state, anchor, undefined, []);
+    if (everything === undefined)
+        return undefined;
+    const restaged = (file) => rebuilt.some((path) => isUnderPath(file, path));
+    const fingerprints = {};
+    for (const [file, hash] of Object.entries(anchor.fingerprints)) {
+        if (!restaged(file))
+            fingerprints[file] = hash;
+    }
+    for (const file of everything) {
+        // A restaged file equal to the anchor HEAD's content needs no entry.
+        if (!restaged(file) || (state.head === anchor.engineHeadSha && !state.dirty.has(file))) {
+            continue;
+        }
+        const live = await liveHash(state, file);
+        if (live === undefined)
+            return undefined;
+        fingerprints[file] = live;
+    }
+    return { ...anchor, fingerprints };
+}
+/** Nearest directory at or above `dir` that holds a test manifest, or undefined. */
+async function findManifestDirectory(engineDir, dir) {
+    for (let current = dir;; current = posix.dirname(current)) {
+        const base = current === '.' ? '' : current;
+        try {
+            const entries = await readdir(join(engineDir, base));
+            if (entries.some((entry) => TEST_MANIFEST_BASENAMES.has(entry)))
+                return base;
+        }
+        catch {
+            // A missing directory has no manifest. Keep walking up.
+        }
+        if (base === '')
+            return undefined;
+    }
+}
+/** Test manifests at or beneath `dir`, bounded by {@link MAX_WALK_ENTRIES}. */
+async function findManifestsBeneath(engineDir, dir) {
+    const manifests = [];
+    const pending = [dir];
+    let visited = 0;
+    while (pending.length > 0 && visited < MAX_WALK_ENTRIES) {
+        const current = pending.pop() ?? '';
+        let entries;
+        try {
+            entries = await readdir(join(engineDir, current), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            visited += 1;
+            const path = current ? `${current}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                pending.push(path);
+            else if (TEST_MANIFEST_BASENAMES.has(entry.name))
+                manifests.push(path);
+        }
+    }
+    return manifests;
+}
+/**
+ * Engine-relative paths a manifest names outside its own directory. Bare
+ * names stay inside it. `!/` and `/` prefixes are engine-root relative, as
+ * in mozbuild manifests. A glob keeps the directory part before its first
+ * wildcard segment.
+ */
+export function manifestExternalReferences(manifestPath, text) {
+    const dir = posix.dirname(manifestPath);
+    const refs = [];
+    for (const token of text.match(/[\w.!~@+\-/*?{}]+/g) ?? []) {
+        if (!token.includes('/') || token.includes('//'))
+            continue;
+        const rooted = token.startsWith('!/')
+            ? token.slice(2)
+            : token.startsWith('/')
+                ? token.slice(1)
+                : undefined;
+        const resolved = rooted === undefined ? posix.join(dir, token) : posix.normalize(rooted);
+        const segments = resolved.split('/');
+        const wildcard = segments.findIndex((segment) => /[*?{}]/.test(segment));
+        const path = normalizeRequestPath(wildcard >= 0 ? segments.slice(0, wildcard).join('/') : resolved);
+        if (path === '' || path.startsWith('..') || isUnderPath(path, dir))
+            continue;
+        refs.push(path);
+    }
+    return refs;
+}
+/** Drops entries that sit beneath another entry, then sorts. */
+function collapsePaths(paths) {
+    const unique = [...new Set(paths)].sort();
+    return unique.filter((path) => !unique.some((other) => other !== path && isUnderPath(path, other)));
+}
+/**
+ * Staging inputs of one request path. See the module comment.
+ * @param engineDir - Path to the engine directory
+ * @param requestPath - Engine-relative request path (file or directory)
+ */
+export async function collectStagingInputs(engineDir, requestPath) {
+    const path = normalizeRequestPath(requestPath);
+    let isDirectory = false;
+    try {
+        isDirectory = (await stat(join(engineDir, path))).isDirectory();
+    }
+    catch {
+        // A missing request path is staged by nothing. Its directory still decides.
+    }
+    const start = isDirectory ? path : posix.dirname(path);
+    const base = await findManifestDirectory(engineDir, start === '.' ? '' : start);
+    const fallback = start === '.' || start === '' ? path : start;
+    const root = base === undefined || base === '' ? fallback : base;
+    const manifests = new Set();
+    for (const entry of await readdir(join(engineDir, root)).catch(() => [])) {
+        if (TEST_MANIFEST_BASENAMES.has(entry))
+            manifests.add(`${root}/${entry}`);
+    }
+    if (isDirectory) {
+        for (const manifest of await findManifestsBeneath(engineDir, path))
+            manifests.add(manifest);
+    }
+    const inputs = [root, path];
+    for (const manifest of manifests) {
+        try {
+            const text = await readFile(join(engineDir, manifest), 'utf8');
+            inputs.push(...manifestExternalReferences(manifest, text));
+        }
+        catch (error) {
+            verbose(`Coverage anchor: cannot read ${manifest} — ${toError(error).message}`);
+        }
+    }
+    return collapsePaths(inputs);
+}
+/**
+ * Records the anchor of a request path this build staged. Undefined when
+ * HEAD is unborn or an input's content cannot be read: the path is still
+ * claimed, and later retention falls back to the baseline-wide anchor.
+ *
+ * @param state - Engine state after the build
+ * @param requestPath - Engine-relative request path
+ * @param mozconfigHash - Hash of the mozconfig the build configured with
+ */
+export async function createCoverageRecord(state, requestPath, mozconfigHash) {
+    if (state.head === undefined)
+        return undefined;
+    const inputs = await collectStagingInputs(state.engineDir, requestPath);
+    return narrowAnchor(state, { engineHeadSha: state.head, mozconfigHash, fingerprints: {} }, inputs, [...state.dirty]);
+}
+/**
+ * Restricts an anchor to `inputs`. `extraDirty` adds paths whose live content
+ * becomes the recorded one (the dirty set of a record being created).
+ */
+export async function narrowAnchor(state, anchor, inputs, extraDirty = []) {
+    const fingerprints = {};
+    for (const [file, hash] of Object.entries(anchor.fingerprints)) {
+        if (inputs.some((input) => isUnderPath(file, input)))
+            fingerprints[file] = hash;
+    }
+    for (const file of extraDirty) {
+        if (!inputs.some((input) => isUnderPath(file, input)))
+            continue;
+        const live = await liveHash(state, file);
+        if (live === undefined)
+            return undefined;
+        fingerprints[file] = live;
+    }
+    return { ...anchor, fingerprints, inputs };
+}

package/dist/src/core/destructive.d.ts

@@ -11,8 +11,6 @@
  * forward-import that later-patch lint would then block). Without a single
  * helper, every new destructive command would re-implement this and drift.
  */
-/** Filename of the audit log, relative to the patches directory. */
-export declare const HISTORY_LOG_FILENAME = ".fireforge-history.jsonl";
 /**
  * A structural conflict that must block the operation even under `--force`.
  *
@@ -128,12 +126,17 @@ export declare function assertConfirmationAvailable(operation: string, options:
  */
 export declare function confirmDestructive(input: DestructiveOpInput): Promise<DestructiveOpResult>;
 /**
- * Appends a single JSONL record to `patches/.fireforge-history.jsonl`.
+ * Appends a single JSONL record to the project's patch history log
+ * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
+ * otherwise; a log at the pre-0.50 `patches/.fireforge-history.jsonl` is
+ * moved there first).
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
  * is append-only and advisory: no code path reads it back. It exists so
- * operators have a post-hoc audit trail when something goes wrong.
+ * operators have a post-hoc audit trail when something goes wrong. Every
+ * record carries the writing invocation's id (and `FIREFORGE_SESSION_ID`
+ * when set), so a session sharing the checkout can pick out its own lines.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record

package/dist/src/core/destructive.js

@@ -12,14 +12,10 @@
  * forward-import that later-patch lint would then block). Without a single
  * helper, every new destructive command would re-implement this and drift.
  */
-import { appendFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { CancellationError, InvalidArgumentError } from '../errors/base.js';
-import { ensureDir } from '../utils/fs.js';
 import { info, isCancel, warn } from '../utils/logger.js';
-/** Filename of the audit log, relative to the patches directory. */
-export const HISTORY_LOG_FILENAME = '.fireforge-history.jsonl';
+import { appendHistoryLine, historyRecordIdentity } from './history-log-file.js';
 /**
  * Prints the change summary lines at warn-severity so the prompt stands out.
  */
@@ -161,22 +157,26 @@ export async function confirmDestructive(input) {
     return 'proceed';
 }
 /**
- * Appends a single JSONL record to `patches/.fireforge-history.jsonl`.
+ * Appends a single JSONL record to the project's patch history log
+ * (`.fireforge/history.jsonl` unless `fireforge.json#history.path` says
+ * otherwise; a log at the pre-0.50 `patches/.fireforge-history.jsonl` is
+ * moved there first).
  *
  * Call order matters: append only after the mutation succeeds, never
  * pre-emptively, so rolled-back failures do not leave ghost entries. The log
  * is append-only and advisory: no code path reads it back. It exists so
- * operators have a post-hoc audit trail when something goes wrong.
+ * operators have a post-hoc audit trail when something goes wrong. Every
+ * record carries the writing invocation's id (and `FIREFORGE_SESSION_ID`
+ * when set), so a session sharing the checkout can pick out its own lines.
  *
  * @param patchesDir - Path to the patches directory
  * @param entry - Serializable history record
  */
 export async function appendHistory(patchesDir, entry) {
-    await ensureDir(patchesDir);
     const record = {
         ts: new Date().toISOString(),
+        ...historyRecordIdentity(),
         ...entry,
     };
-    const line = `${JSON.stringify(record)}\n`;
-    await appendFile(join(patchesDir, HISTORY_LOG_FILENAME), line, 'utf-8');
+    await appendHistoryLine(patchesDir, JSON.stringify(record));
 }

package/dist/src/core/engine-session-lock.d.ts

@@ -59,6 +59,15 @@ export declare function isIndexLockError(error: unknown): boolean;
 export declare function isUnavailableGenerationToken(token: string): boolean;
 /** Strips the marker prefix off an unavailable token for display. */
 export declare function unavailableGenerationReason(token: string): string;
+/**
+ * Engine-relative paths whose working-tree status differs between two
+ * generation tokens (both sides of a rename), and whether HEAD moved. An
+ * untracked directory keeps git's trailing `/`.
+ */
+export declare function generationDeltaPaths(before: string, after: string): {
+    headMoved: boolean;
+    paths: string[];
+};
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
@@ -101,4 +110,4 @@ export declare function describeEngineGenerationDelta(before: string, after: str
  * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
-export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;
+export declare function assertEngineGenerationUnchanged(engineDir: string, before: string, tolerateDelta?: (before: string, after: string) => Promise<boolean>): Promise<void>;

package/dist/src/core/engine-session-lock.js

@@ -4,7 +4,7 @@ import { InconclusiveVerdictError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { info, warn } from '../utils/logger.js';
 import { sleep } from '../utils/sleep.js';
-import { readLockStatus, withFileLock } from './file-lock.js';
+import { formatLockQueuePosition, readLockStatus, withFileLock, } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
 /**
@@ -24,12 +24,9 @@ const MAX_WAIT_LOCK_MS = 3600 * 1000;
 function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
     const progress = `${Math.round(waitedMs / 1000)}s of up to ${Math.round(timeoutMs / 1000)}s`;
     // Queue position: under several concurrent sessions the wait
-    // line alone left operators inferring their place from `ps`.
-    const position = queue === undefined || queue.depth === 0
-        ? ''
-        : queue.ahead === 0
-            ? ` You are next in a queue of ${queue.depth}.`
-            : ` ${queue.ahead} ahead of you (queue of ${queue.depth}).`;
+    // line alone left operators inferring their place from `ps`. It names the
+    // ordering rule, because the count is only useful if the grant honours it.
+    const position = formatLockQueuePosition(queue);
     if (holder === undefined) {
         return `Waiting for the FireForge engine lock — ${progress}.${position}`;
     }
@@ -254,6 +251,25 @@ function parsePorcelainRecords(body) {
     }
     return records;
 }
+/**
+ * Engine-relative paths whose working-tree status differs between two
+ * generation tokens (both sides of a rename), and whether HEAD moved. An
+ * untracked directory keeps git's trailing `/`.
+ */
+export function generationDeltaPaths(before, after) {
+    const from = splitGenerationToken(before);
+    const to = splitGenerationToken(after);
+    const beforeRecords = new Set(parsePorcelainRecords(from.body));
+    const afterRecords = new Set(parsePorcelainRecords(to.body));
+    const paths = new Set();
+    for (const record of [...afterRecords, ...beforeRecords]) {
+        if (beforeRecords.has(record) && afterRecords.has(record))
+            continue;
+        for (const path of record.slice(3).split(' -> '))
+            paths.add(path);
+    }
+    return { headMoved: from.head !== to.head, paths: [...paths].sort() };
+}
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
@@ -317,7 +333,7 @@ export function describeEngineGenerationDelta(before, after) {
  * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
-export async function assertEngineGenerationUnchanged(engineDir, before) {
+export async function assertEngineGenerationUnchanged(engineDir, before, tolerateDelta) {
     const after = await snapshotEngineGeneration(engineDir);
     const beforeUnavailable = isUnavailableGenerationToken(before);
     const afterUnavailable = isUnavailableGenerationToken(after);
@@ -339,6 +355,10 @@ export async function assertEngineGenerationUnchanged(engineDir, before) {
     }
     if (after === before)
         return;
+    // A caller that can prove the delta never reached the runtime under test
+    // (a perf sample, see `test-perf-scope.ts`) keeps its verdict.
+    if (tolerateDelta !== undefined && (await tolerateDelta(before, after)))
+        return;
     const delta = describeEngineGenerationDelta(before, after);
     throw new InconclusiveVerdictError('engine/ changed while `fireforge test` was running, so this test verdict is invalid/inconclusive.\n\n' +
         (delta.length > 0 ? `What moved:\n${delta.map((line) => `  ${line}`).join('\n')}\n\n` : '') +

package/dist/src/core/export-moved-code-shape.d.ts

@@ -21,14 +21,25 @@
  * carry), so the refusal can name the sequence instead of leaving the
  * operator to derive it.
  */
+/** One run of consecutive lines a new file shares with an existing patch. */
+export interface MovedCodeBlock {
+    /** New-file path in the pending diff. */
+    file: string;
+    /** File in the source patch that carries the same run. */
+    sourceFile: string;
+    /** The matched substantive lines, trimmed, in order. */
+    lines: string[];
+}
 /** One existing patch that already carries lines the new files would add. */
 export interface MovedCodeOverlap {
     /** Filename of the patch that still contains the moved lines. */
     sourcePatch: string;
     /** New-file paths in the pending diff whose lines it overlaps. */
     files: string[];
-    /** Count of distinct non-trivial lines shared. */
+    /** Count of substantive lines inside the matched blocks. */
     sharedLines: number;
+    /** The matched blocks, so the claim can be checked line by line. */
+    blocks: MovedCodeBlock[];
 }
 /** Minimal queue view this detector needs. */
 export interface MovedCodeQueueEntry {
@@ -36,9 +47,9 @@ export interface MovedCodeQueueEntry {
     diff: string;
 }
 /**
- * Finds existing patches that still carry substantive lines the pending
- * diff's new files would add, the fingerprint of code moved out of an
- * existing patch into a new file.
+ * Finds existing patches that still carry a block of substantive lines the
+ * pending diff's new files would add, the fingerprint of code moved out of
+ * an existing patch into a new file.
  *
  * Pure. Overlaps are returned strongest-first so the message names the
  * most likely source patch.
@@ -48,13 +59,40 @@ export interface MovedCodeQueueEntry {
  * @returns Overlaps, or an empty list when the shape is not present
  */
 export declare function detectMovedCodeOverlaps(pendingDiff: string, entries: readonly MovedCodeQueueEntry[]): MovedCodeOverlap[];
+/** What the placement projection learned about the pending export. */
+export interface MovedCodeAdviceInput {
+    /** Result of {@link detectMovedCodeOverlaps}. */
+    overlaps: readonly MovedCodeOverlap[];
+    /** The filename the pending export would take. */
+    newPatchName: string;
+    /** The order the pending export would take. */
+    insertionOrder: number;
+    /**
+     * New system modules in the pending diff that no patch registers
+     * (`unregistered-system-module` findings on the new patch).
+     */
+    unregisteredModules?: readonly string[];
+    /**
+     * True when every error in the exported content is a missing
+     * registration: registering is then the whole fix, and adopt-then-split
+     * is not offered at all.
+     */
+    registrationResolvesAll?: boolean;
+    /**
+     * Why adopting the new files into the strongest overlap's source patch
+     * would itself be refused (forward imports, size limit). Empty when the
+     * adopt is clean.
+     */
+    adoptBlockers?: readonly string[];
+}
 /**
- * Renders the adopt-then-split remedy for the strongest overlap, as lines
- * appended to the refusal's detail list.
+ * Renders the remedy lines appended to a placement refusal: "register
+ * first" when new modules lack their moz.build registration, then the
+ * adopt-then-split sequence for a real moved-code block, but only when the
+ * adopt itself would pass. Each claim names its evidence (the matched
+ * lines, the blocking findings) so it can be checked.
  *
- * @param overlaps - Result of {@link detectMovedCodeOverlaps}
- * @param newPatchName - The filename the pending export would take
- * @param insertionOrder - The order the pending export would take
- * @returns Detail lines, or an empty list when the shape is not present
+ * @param input - See {@link MovedCodeAdviceInput}
+ * @returns Detail lines, or an empty list when neither shape is present
  */
-export declare function formatAdoptThenSplitRemedy(overlaps: readonly MovedCodeOverlap[], newPatchName: string, insertionOrder: number): string[];
+export declare function formatMovedCodeAdvice(input: MovedCodeAdviceInput): string[];