@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/commands/check-steps.js

@@ -0,0 +1,175 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The step plan of `fireforge check`: which commands run, with which
+ * arguments, in which order constraints, and how each one's output is
+ * condensed into its table row.
+ *
+ * Every built-in step is the real command run as a child `fireforge`
+ * process, not an in-process call. That is what keeps the gate's output
+ * sane (each command owns its stdout, its machine mode and its error
+ * boundary) and what avoids double locking: `check` itself takes no lock,
+ * so each child takes exactly the locks its command takes standalone.
+ * None of the built-in steps takes the engine session lock, which is why
+ * they can run side by side.
+ */
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+/**
+ * How to re-run this CLI as a child: the same Node, the same loader flags
+ * (minus debugger flags, whose port the parent already holds), the same
+ * entry script.
+ */
+function fireforgeInvocation() {
+    const entry = process.argv[1];
+    if (entry === undefined) {
+        throw new GeneralError('Cannot resolve the fireforge CLI entry point for check steps.');
+    }
+    const loaderFlags = process.execArgv.filter((flag) => !flag.startsWith('--inspect'));
+    return { command: process.execPath, prefix: [...loaderFlags, entry] };
+}
+/** Strips clack's gutter glyphs so a captured line reads as plain text. */
+function plainLine(line) {
+    return line.replace(/^[\s│■●◆◇▲└┌|]+/u, '').trim();
+}
+/**
+ * The generic detail: nothing on success, and on failure the last line
+ * the step printed (its refusal, usually), cut to fit a table cell.
+ */
+export function lastOutputLine(combined, exitCode) {
+    if (exitCode === 0)
+        return '';
+    const lines = combined
+        .split(/\r?\n/)
+        .map(plainLine)
+        .filter((line) => line.length > 0);
+    const last = lines.at(-1) ?? '';
+    return last.length > 120 ? `${last.slice(0, 117)}...` : last;
+}
+function parseJsonDocument(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return typeof parsed === 'object' && parsed !== null
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Status detail from its `--json --summary` document: the failing classes. */
+export function summarizeStatus(output) {
+    const doc = parseJsonDocument(output.stdout);
+    if (doc?.summary === undefined)
+        return lastOutputLine(output.combined, output.exitCode);
+    const offenders = doc.check?.offenders ?? [];
+    if (offenders.length > 0) {
+        return offenders.map((entry) => `${entry.count} ${entry.classification}`).join(', ');
+    }
+    return `${doc.summary.total ?? 0} changed file(s), none failing`;
+}
+/** Furnace detail from its `--json` document: counts after exceptions. */
+export function summarizeFurnace(output) {
+    const doc = parseJsonDocument(output.stdout);
+    if (doc?.summary === undefined)
+        return lastOutputLine(output.combined, output.exitCode);
+    const { errors, warnings, excepted, staleExceptions } = doc.summary;
+    const extra = [
+        excepted > 0 ? `${excepted} excepted` : '',
+        staleExceptions > 0 ? `${staleExceptions} stale exception(s)` : '',
+    ].filter((part) => part.length > 0);
+    return [`${errors} error(s), ${warnings} warning(s)`, ...extra].join(', ');
+}
+/** Token-coverage detail: the coverage percentage it reports. */
+export function summarizeTokenCoverage(output) {
+    const match = /Token coverage: (\d+)%/.exec(output.combined);
+    if (match?.[1] !== undefined)
+        return `coverage ${match[1]}%`;
+    if (output.combined.includes('No modified CSS files'))
+        return 'no modified CSS';
+    return lastOutputLine(output.combined, output.exitCode);
+}
+function generic(output) {
+    return lastOutputLine(output.combined, output.exitCode);
+}
+/** The status step's `--check` flags from `check.status`. */
+export function statusPolicyArgs(policy) {
+    const args = [];
+    if (policy?.failOn !== undefined)
+        args.push('--fail-on', policy.failOn.join(','));
+    if (policy?.allow !== undefined)
+        args.push('--allow', policy.allow.join(','));
+    if (policy?.failOnUnknown === true)
+        args.push('--fail-on-unknown');
+    return args;
+}
+function builtinStep(invocation, projectRoot, name, args, summarize, extra = {}) {
+    return {
+        name,
+        kind: 'builtin',
+        command: invocation.command,
+        args: [...invocation.prefix, ...args],
+        display: `fireforge ${args.join(' ')}`,
+        cwd: projectRoot,
+        after: extra.after ?? [],
+        skipReason: extra.skipReason,
+        summarize,
+    };
+}
+/** Runs a project command line through the platform shell. */
+function shellInvocation(commandLine) {
+    return process.platform === 'win32'
+        ? { command: 'cmd.exe', args: ['/d', '/s', '/c', commandLine] }
+        : { command: '/bin/sh', args: ['-c', commandLine] };
+}
+/**
+ * Builds the full plan: the six built-in steps (with the ones this project
+ * cannot run marked skipped) followed by `check.extraSteps[]`.
+ *
+ * `furnace-validate` waits for `typecheck`, the one built-in step that
+ * writes: it regenerates a stale Furnace jsconfig, whose drift
+ * `furnace validate` reports. Run side by side, the two would race on that
+ * file and the verdict would depend on which won.
+ */
+export function buildCheckPlan(input) {
+    const { projectRoot, config } = input;
+    const invocation = fireforgeInvocation();
+    const check = config.check ?? {};
+    const patchArgs = input.patches !== undefined ? ['--patches', input.patches.join(',')] : [];
+    const lintWarnings = check.maxWarnings?.lint !== undefined ? ['--max-warnings', String(check.maxWarnings.lint)] : [];
+    const furnaceWarnings = check.maxWarnings?.furnace !== undefined
+        ? ['--max-warnings', String(check.maxWarnings.furnace)]
+        : [];
+    const plan = [
+        builtinStep(invocation, projectRoot, 'status', ['status', '--json', '--summary', '--check', ...statusPolicyArgs(check.status), ...patchArgs], summarizeStatus),
+        builtinStep(invocation, projectRoot, 'verify', ['verify', ...patchArgs], generic),
+        builtinStep(invocation, projectRoot, 'lint', ['lint', '--per-patch', '--notices', 'summary', ...lintWarnings, ...patchArgs], generic),
+        builtinStep(invocation, projectRoot, 'typecheck', ['typecheck'], generic, {
+            skipReason: config.typecheck === undefined ? 'no "typecheck" block in fireforge.json' : undefined,
+        }),
+        builtinStep(invocation, projectRoot, 'furnace-validate', ['furnace', 'validate', '--json', ...furnaceWarnings], summarizeFurnace, {
+            after: ['typecheck'],
+            skipReason: input.furnaceConfigured ? undefined : 'no furnace.json',
+        }),
+        builtinStep(invocation, projectRoot, 'token-coverage', ['token', 'coverage'], summarizeTokenCoverage),
+    ];
+    for (const step of check.extraSteps ?? []) {
+        const shell = shellInvocation(step.command);
+        plan.push({
+            name: step.name,
+            kind: 'extra',
+            command: shell.command,
+            args: shell.args,
+            display: step.command,
+            cwd: step.cwd !== undefined ? join(projectRoot, step.cwd) : projectRoot,
+            timeoutMs: step.timeout !== undefined ? step.timeout * 1000 : undefined,
+            after: [],
+            summarize: generic,
+        });
+    }
+    for (const name of check.skip ?? []) {
+        const step = plan.find((entry) => entry.name === name);
+        if (step !== undefined)
+            step.skipReason = 'skipped by check.skip in fireforge.json';
+    }
+    return plan;
+}

package/dist/src/commands/check.d.ts

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+import type { CommandContext } from '../types/cli.js';
+import { type CheckStepPlan } from './check-steps.js';
+/** Options Commander forwards from `fireforge check`. */
+export interface CheckCommandOptions {
+    json?: boolean;
+    /** Judge only these patches in status, verify and lint. */
+    patches?: string[];
+    /** Comma-separated step names to leave out. */
+    skip?: string;
+    /** Comma-separated step names to run, leaving out the rest. */
+    only?: string;
+    /** Raw `--jobs` value. */
+    jobs?: string;
+}
+/**
+ * Applies `--only` and `--skip` to the plan. A step left out this way is
+ * dropped from the table rather than shown as skipped: the caller asked
+ * for a narrower gate, not a report of what it chose not to run.
+ */
+export declare function selectCheckSteps(plan: CheckStepPlan[], options: Pick<CheckCommandOptions, 'only' | 'skip'>): CheckStepPlan[];
+/** Parses `--jobs`: a positive integer. Defaults to one slot per CPU. */
+export declare function parseCheckJobs(raw: string | undefined): number;
+/**
+ * Runs the composed gate.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - See {@link CheckCommandOptions}
+ */
+export declare function checkCommand(projectRoot: string, options?: CheckCommandOptions): Promise<void>;
+/** Registers the `check` command on the CLI program. */
+export declare function registerCheck(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/check.js

@@ -0,0 +1,160 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge check`: the composed static gate. Runs status, verify,
+ * per-patch lint, typecheck, Furnace validation and token coverage, plus
+ * the project's `check.extraSteps[]`, in parallel, and ends with one
+ * `FIREFORGE-VERDICT:` line over a per-step table (or one JSON document
+ * under `--json`).
+ *
+ * Each step is the real command in a child process (see check-steps.ts for
+ * why), so a step behaves exactly as it does when run on its own.
+ */
+import { availableParallelism } from 'node:os';
+import { Command } from 'commander';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists } from '../core/furnace-config.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { selectPatchSubset } from '../core/patch-subset.js';
+import { GeneralError, InvalidArgumentError, LockContentionError } from '../errors/base.js';
+import { ConfigError } from '../errors/config.js';
+import { toError } from '../utils/errors.js';
+import { info, intro, isMachineOutputMode, note, outro, setMachineOutputMode, } from '../utils/logger.js';
+import { formatCheckTable, judgeCheck, writeCheckJson, writeCheckVerdictLine, } from './check-report.js';
+import { runCheckSteps } from './check-run.js';
+import { buildCheckPlan } from './check-steps.js';
+import { resolveStatusCheckPolicy } from './status-check.js';
+function parseNameList(raw) {
+    if (raw === undefined)
+        return undefined;
+    return raw
+        .split(',')
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+}
+/**
+ * Applies `--only` and `--skip` to the plan. A step left out this way is
+ * dropped from the table rather than shown as skipped: the caller asked
+ * for a narrower gate, not a report of what it chose not to run.
+ */
+export function selectCheckSteps(plan, options) {
+    const known = plan.map((step) => step.name);
+    const only = parseNameList(options.only);
+    const skip = parseNameList(options.skip);
+    for (const [flag, names] of [
+        ['--only', only],
+        ['--skip', skip],
+    ]) {
+        const unknown = (names ?? []).filter((name) => !known.includes(name));
+        if (unknown.length > 0) {
+            throw new InvalidArgumentError(`Unknown ${flag} step "${unknown.join('", "')}". Steps: ${known.join(', ')}.`, flag);
+        }
+    }
+    return plan.filter((step) => (only === undefined || only.includes(step.name)) && skip?.includes(step.name) !== true);
+}
+/** Parses `--jobs`: a positive integer. Defaults to one slot per CPU. */
+export function parseCheckJobs(raw) {
+    if (raw === undefined)
+        return availableParallelism();
+    const jobs = Number(raw);
+    if (!Number.isInteger(jobs) || jobs < 1) {
+        throw new InvalidArgumentError('--jobs must be a positive integer.', '--jobs');
+    }
+    return jobs;
+}
+/**
+ * Refuses a `check.status` policy the status step would refuse, before any
+ * step runs, as the config error it is.
+ */
+function assertStatusPolicy(config) {
+    const policy = config.check?.status;
+    if (policy === undefined)
+        return;
+    try {
+        resolveStatusCheckPolicy({
+            check: true,
+            ...(policy.failOn !== undefined ? { failOn: policy.failOn.join(',') } : {}),
+            ...(policy.allow !== undefined ? { allow: policy.allow.join(',') } : {}),
+            ...(policy.failOnUnknown === true ? { failOnUnknown: true } : {}),
+        });
+    }
+    catch (error) {
+        throw new ConfigError(`Config field "check.status" is invalid: ${toError(error).message}`);
+    }
+}
+/** Resolves `--patches` once, so a typo fails here rather than in three steps. */
+async function resolvePatchScope(patchesDir, requested) {
+    if (requested === undefined || requested.length === 0)
+        return undefined;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0) {
+        throw new GeneralError('--patches needs a patch queue, but patches.json lists no patches.');
+    }
+    return selectPatchSubset(manifest, requested, '--patches selects patches (filename, stem, order number, manifest name, or slug).').map((patch) => patch.filename);
+}
+/**
+ * Runs the composed gate.
+ *
+ * @param projectRoot - Project root directory
+ * @param options - See {@link CheckCommandOptions}
+ */
+export async function checkCommand(projectRoot, options = {}) {
+    const previousMachineOutputMode = isMachineOutputMode();
+    // `--json` owns stdout from the first byte. On a throw the mode stays
+    // engaged and withErrorHandling resets it after routing the refusal.
+    if (options.json === true)
+        setMachineOutputMode(true);
+    await runCheck(projectRoot, options);
+    if (isMachineOutputMode() !== previousMachineOutputMode) {
+        setMachineOutputMode(previousMachineOutputMode);
+    }
+}
+async function runCheck(projectRoot, options) {
+    intro('FireForge Check');
+    const jobs = parseCheckJobs(options.jobs);
+    const config = await loadConfig(projectRoot);
+    assertStatusPolicy(config);
+    const patches = await resolvePatchScope(getProjectPaths(projectRoot).patches, options.patches);
+    const plan = selectCheckSteps(buildCheckPlan({
+        projectRoot,
+        config,
+        furnaceConfigured: await furnaceConfigExists(projectRoot),
+        patches,
+    }), options);
+    const runnable = plan.filter((step) => step.skipReason === undefined).length;
+    info(`Running ${runnable} step(s), up to ${Math.min(jobs, Math.max(1, runnable))} at once${patches ? `, judging ${patches.join(', ')}` : ''}.`);
+    const results = await runCheckSteps(plan, jobs);
+    const verdict = judgeCheck(results);
+    if (options.json === true) {
+        writeCheckJson(results, verdict);
+    }
+    else {
+        note(formatCheckTable(results), 'Steps');
+        for (const result of results) {
+            if (result.status === 'fail' && result.outputTail) {
+                note(result.outputTail, `${result.name}: ${result.command}`);
+            }
+        }
+        outro(verdict.passed ? 'Check passed' : `Check failed: ${verdict.failed.join(', ')}`);
+        writeCheckVerdictLine(verdict);
+    }
+    if (verdict.reason === 'lock-timeout') {
+        throw new LockContentionError(`fireforge check: ${verdict.failed.join(', ')} could not take their locks in time. Re-run when the holder is done.`);
+    }
+    if (!verdict.passed) {
+        throw new GeneralError(`fireforge check failed: ${verdict.failed.join(', ')}. Run a failing step on its own for its full output.`);
+    }
+}
+/** Registers the `check` command on the CLI program. */
+export function registerCheck(program, { getProjectRoot, withErrorHandling }) {
+    program
+        .command('check')
+        .description('Composed static gate: status, verify, per-patch lint, typecheck, Furnace validation, token coverage and fireforge.json check.extraSteps in parallel, with one FIREFORGE-VERDICT line')
+        .option('--json', 'Write one JSON document (verdict plus a result per step) instead of the table')
+        .option('--patches <names...>', 'Judge only these patches in the status, verify and lint steps (filename, stem, order number, manifest name, or slug)')
+        .option('--only <steps>', 'Comma-separated steps to run, leaving out the rest')
+        .option('--skip <steps>', 'Comma-separated steps to leave out')
+        .option('--jobs <n>', 'Steps to run at once (default: one per CPU)')
+        .action(withErrorHandling(async (options) => {
+        await checkCommand(getProjectRoot(), options);
+    }));
+}

package/dist/src/commands/config.js

@@ -35,6 +35,7 @@ const STRING_TYPED_KEYS = new Set([
     'firefox.candidate',
     'license',
     'wire.subscriptDir',
+    'history.path',
 ]);
 /**
  * Parses a string value into the appropriate type.
@@ -131,12 +132,10 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             // Readers stay lock-free (see `withConfigFileLock`).
             unchanged = await withConfigFileLock(projectRoot, async () => {
                 // Short-circuit when the new value matches the current on-disk
-                // value. Running every set through `mutateConfig` + `writeConfig`
-                // round-trips through `JSON.stringify` and rewrites the file even
-                // when nothing changed semantically, reordering top-level keys
-                // (`license`, `markerComment`, …) on every harmless re-set. The
-                // check uses the raw on-disk document so forced keys round-trip the
-                // same as known keys.
+                // value, so a harmless re-set neither rewrites the file nor bumps
+                // its mtime. The check uses the raw on-disk document so forced keys
+                // round-trip the same as known keys. A real change is written by
+                // `writeConfigDocument`, which edits only the changed value in place.
                 const rawConfig = await loadRawConfigDocument(projectRoot);
                 const currentValue = getNestedValue(rawConfig, key);
                 if (deepEqual(currentValue, parsedValue)) {

package/dist/src/commands/doctor-engine-eslint.js

@@ -8,5 +8,10 @@ export const ENGINE_ESLINT_DOCTOR_CHECK = {
     skipIf: (ctx) => !ctx.engineExists,
     run: async (ctx) => (await pathExists(join(ctx.paths.engine, 'node_modules/eslint/bin/eslint.js')))
         ? ok('Engine ESLint installed')
-        : warning('Engine ESLint installed', 'Engine-local ESLint is missing after source extraction; an engine-eslint ratchet cannot run.', 'Run "cd engine && ./mach eslint --setup" after each source refresh, before building or running the gate.'),
+        : warning('Engine ESLint installed', 'Engine-local ESLint is missing after source extraction; an engine-eslint ratchet cannot run.', 
+        // `./mach npm ci` installs only the node dependencies the ratchet
+        // runs. `./mach eslint --setup` also builds mach's Python `lint`
+        // virtualenv, whose pinned requirements can stop resolving on PyPI
+        // and fail the whole step with node_modules still missing.
+        'Run "cd engine && ./mach npm ci --no-audit --no-fund" after each source refresh, before building or running the gate. It installs engine/node_modules without the Python lint virtualenv "./mach eslint --setup" also builds.'),
 };

package/dist/src/commands/doctor-source-pin.js

@@ -58,7 +58,10 @@ async function runSourcePinCheck(ctx) {
     }
     const downloaded = ctx.state.downloadedVersion;
     const mismatches = [];
-    if (actual !== undefined && actual !== pinned) {
+    // Firefox's version.txt never carries the `esr` suffix (an ESR 153.4.0esr
+    // tree reads 153.4.0), so the engine comparison drops it from the pin. The
+    // last download recorded the full pin, so that comparison keeps it.
+    if (actual !== undefined && actual !== pinned && actual !== pinned.replace(/esr$/, '')) {
         mismatches.push(`engine baseline browser/config/version.txt reads ${actual}`);
     }
     if (downloaded !== undefined && downloaded !== pinned) {

package/dist/src/commands/export-adopt-check.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The advice an export placement refusal appends for new files: "register
+ * first" when a new system module only lacks its moz.build line, and
+ * adopt-then-split for a real moved-code block, but only after checking
+ * that the adopt itself would pass.
+ *
+ * The advice used to be offered on the moved-code heuristic alone. On one
+ * queue it told the operator to adopt six new modules into an existing
+ * patch when the only error was the missing registration; the adopt then
+ * refused one module for importing later patches, and without it breached
+ * the source patch's hard size limit. Split out of export-flow.ts for the
+ * line budget.
+ */
+import { type PatchQueueContext } from '../core/patch-lint.js';
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Why adopting `diff` into `sourceFilename` would itself be refused: the
+ * forward imports the adopted files would give the source patch, and the
+ * source patch's hard size limit. Empty when the adopt is clean.
+ *
+ * @param baseCtx - The current queue
+ * @param sourceFilename - The patch the adopt would grow
+ * @param diff - The pending export's diff
+ */
+export declare function findAdoptBlockers(baseCtx: PatchQueueContext, sourceFilename: string, diff: string): string[];
+/**
+ * Detail lines for a placement refusal: register-first and moved-code
+ * advice, each only when the projection supports it.
+ *
+ * @param baseCtx - The current queue
+ * @param diff - The pending export's diff
+ * @param projectedIssues - Error findings of the placement projection
+ * @param plan - The placement's new filename and order
+ */
+export declare function describePlacementAdvice(baseCtx: PatchQueueContext, diff: string, projectedIssues: readonly PatchLintIssue[], plan: {
+    newFilename: string;
+    insertionOrder: number;
+}): string[];

package/dist/src/commands/export-adopt-check.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The advice an export placement refusal appends for new files: "register
+ * first" when a new system module only lacks its moz.build line, and
+ * adopt-then-split for a real moved-code block, but only after checking
+ * that the adopt itself would pass.
+ *
+ * The advice used to be offered on the moved-code heuristic alone. On one
+ * queue it told the operator to adopt six new modules into an existing
+ * patch when the only error was the missing registration; the adopt then
+ * refused one module for importing later patches, and without it breached
+ * the source patch's hard size limit. Split out of export-flow.ts for the
+ * line budget.
+ */
+import { detectMovedCodeOverlaps, formatMovedCodeAdvice } from '../core/export-moved-code-shape.js';
+import { countNonBinaryDiffLines, getPatchSizeThresholds, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
+import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
+import { projectEntryBody } from './patch/entry-projection.js';
+/**
+ * Why adopting `diff` into `sourceFilename` would itself be refused: the
+ * forward imports the adopted files would give the source patch, and the
+ * source patch's hard size limit. Empty when the adopt is clean.
+ *
+ * @param baseCtx - The current queue
+ * @param sourceFilename - The patch the adopt would grow
+ * @param diff - The pending export's diff
+ */
+export function findAdoptBlockers(baseCtx, sourceFilename, diff) {
+    const source = baseCtx.entries.find((entry) => entry.filename === sourceFilename);
+    if (source === undefined)
+        return [];
+    const blockers = [];
+    const pending = projectEntryBody(diff);
+    const adopted = {
+        ...source,
+        diff: `${source.diff}\n${diff}`,
+        newFiles: new Map([...source.newFiles, ...pending.newFiles]),
+        createdFiles: new Set([...source.createdFiles, ...pending.createdFiles]),
+        modifiedFileAdditions: new Map([
+            ...source.modifiedFileAdditions,
+            ...pending.modifiedFileAdditions,
+        ]),
+    };
+    const isError = (issue) => issue.severity === 'error';
+    const baseline = lintPatchQueue(baseCtx).filter(isError);
+    const projected = lintPatchQueue({
+        ...baseCtx,
+        entries: baseCtx.entries.map((entry) => (entry.filename === sourceFilename ? adopted : entry)),
+    }).filter(isError);
+    for (const issue of computeProjectedLintRegressions(baseline, projected)) {
+        if (issue.check !== 'forward-import' || !issue.patches?.includes(sourceFilename))
+            continue;
+        for (const declaration of issue.stagedDeclarations ?? []) {
+            blockers.push(`${declaration.file} imports "${declaration.specifier ?? ''}", created by ` +
+                `${declaration.owner}, which applies after ${sourceFilename} (forward-import)`);
+        }
+    }
+    if (!(source.metadata?.lintIgnore ?? []).includes('large-patch-lines')) {
+        const tier = resolvePatchSizeTier([...(source.metadata?.filesAffected ?? []), ...pending.newFiles.keys()], source.metadata?.tier);
+        const limit = getPatchSizeThresholds(tier.tier).lines.error;
+        const lines = countNonBinaryDiffLines(source.diff).textLines + countNonBinaryDiffLines(diff).textLines;
+        if (lines > limit) {
+            blockers.push(`${sourceFilename} would grow to about ${lines} lines, over its ${tier.tier} hard limit ` +
+                `of ${limit} (large-patch-lines)`);
+        }
+    }
+    return blockers;
+}
+/**
+ * Detail lines for a placement refusal: register-first and moved-code
+ * advice, each only when the projection supports it.
+ *
+ * @param baseCtx - The current queue
+ * @param diff - The pending export's diff
+ * @param projectedIssues - Error findings of the placement projection
+ * @param plan - The placement's new filename and order
+ */
+export function describePlacementAdvice(baseCtx, diff, projectedIssues, plan) {
+    const newFiles = projectEntryBody(diff).newFiles;
+    const exported = projectedIssues.filter((issue) => issue.patches?.includes(plan.newFilename) ?? issue.message.includes(plan.newFilename));
+    const unregisteredModules = [
+        ...new Set(exported
+            .filter((issue) => issue.check === 'unregistered-system-module' && newFiles.has(issue.file))
+            .map((issue) => issue.file)),
+    ];
+    const registrationResolvesAll = unregisteredModules.length > 0 &&
+        exported.every((issue) => issue.check === 'unregistered-system-module');
+    const overlaps = registrationResolvesAll ? [] : detectMovedCodeOverlaps(diff, baseCtx.entries);
+    const strongest = overlaps[0];
+    return formatMovedCodeAdvice({
+        overlaps,
+        newPatchName: plan.newFilename,
+        insertionOrder: plan.insertionOrder,
+        unregisteredModules,
+        registrationResolvesAll,
+        adoptBlockers: strongest !== undefined ? findAdoptBlockers(baseCtx, strongest.sourcePatch, diff) : [],
+    });
+}

package/dist/src/commands/export-flow.js

@@ -7,11 +7,11 @@
  * per-file / per-function line budgets and makes each step individually
  * testable without dragging the whole command harness along for the ride.
  */
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import {} from '../core/destructive.js';
-import { detectMovedCodeOverlaps, formatAdoptThenSplitRemedy, } from '../core/export-moved-code-shape.js';
 import { buildPlanExportInput, findAllPatchesForFilesWithDetails, patchNameSlug, planExport, } from '../core/patch-export.js';
 import { buildPatchQueueContext, lintPatchQueue } from '../core/patch-lint.js';
+import { formatLintIgnoreList } from '../core/patch-lint-ignore.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
 import { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
 import { formatPatchOrder, requirePatchOrder } from '../core/patch-parse.js';
@@ -20,9 +20,11 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
+import { describePlacementAdvice } from './export-adopt-check.js';
 import { groupProjectedPlacementErrors } from './export-placement-conflicts.js';
 import { assertPlacementAvoidsReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
+import { acceptTreeRegisteredModules } from './export-staged-registration.js';
 import { projectEntryBody } from './patch/entry-projection.js';
 import { getSortedRenameEntries, renameMapsEqual } from './patch-rename-map.js';
 function buildFilenameForPlacement(category, name, order, width) {
@@ -170,18 +172,31 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
     // whether they live in a brand-new file or are added to an existing one.
     // Leaving either map empty lets a patch land before one of its own
     // dependencies and still pass the gate.
+    const pendingBody = projectEntryBody(diff);
     projectedEntries.push({
         filename: plan.newFilename,
         order: plan.insertionOrder,
         metadata: null,
-        ...projectEntryBody(diff),
+        ...pendingBody,
     });
     projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
     const policyRest = baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {};
-    const projectedIssues = lintPatchQueue({
-        entries: projectedEntries,
-        ...policyRest,
-    }).filter((i) => i.severity === 'error');
+    // A new module whose moz.build line is declared (staged registration)
+    // and present in the working tree, but not yet exported by its owner, is
+    // accepted with a "re-export the owner next" note instead of refused.
+    const registration = await acceptTreeRegisteredModules({
+        engineDir: join(dirname(patchesDir), 'engine'),
+        baseCtx,
+        newFilename: plan.newFilename,
+        pendingNewFiles: new Set(pendingBody.newFiles.keys()),
+        projectedIssues: lintPatchQueue({
+            entries: projectedEntries,
+            ...policyRest,
+        }).filter((i) => i.severity === 'error'),
+    });
+    for (const note of registration.accepted)
+        warn(note);
+    const projectedIssues = registration.remaining;
     if (projectedIssues.length === 0)
         return null;
     // Baseline lint over the un-renumbered queue: an error present here is
@@ -192,16 +207,16 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         entries: baseCtx.entries,
         ...policyRest,
     }).filter((i) => i.severity === 'error');
-    // New-file + moved-code slice: when the refusal is caused by
-    // the source patch still carrying lines the new patch would gain, name
-    // the adopt-then-split sequence instead of leaving the operator to
-    // derive it from two individually-correct guards that together dead-end.
-    const movedCode = detectMovedCodeOverlaps(diff, baseCtx.entries);
+    // Register-first and new-file + moved-code advice: name the working
+    // sequence instead of leaving the operator to derive it from two
+    // individually-correct guards that together dead-end, but only offer
+    // adopt-then-split for a real moved block whose adopt would itself pass.
     return {
         reason: `placement would introduce ${projectedIssues.length} cross-patch lint error(s)`,
         details: [
             ...groupProjectedPlacementErrors(projectedIssues, baselineIssues, plan),
-            ...formatAdoptThenSplitRemedy(movedCode, plan.newFilename, plan.insertionOrder),
+            ...registration.advice,
+            ...describePlacementAdvice(baseCtx, diff, projectedIssues, plan),
         ],
     };
 }
@@ -380,7 +395,7 @@ export async function renderDryRunPreview(input) {
         info(`  tier: ${plan.metadata.tier}`);
     }
     if (plan.metadata.lintIgnore !== undefined && plan.metadata.lintIgnore.length > 0) {
-        info(`  lintIgnore: ${plan.metadata.lintIgnore.join(', ')}`);
+        info(`  lintIgnore: ${formatLintIgnoreList(plan.metadata.lintIgnore)}`);
     }
     if (supersedeDetails.length > 0) {
         info(`\n[dry-run] Would supersede ${supersedeDetails.length} existing patch(es):`);