@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,75 @@
+import type { CheckConfig, FireForgeConfig } from '../types/config.js';
+/** One planned step. */
+export interface CheckStepPlan {
+    name: string;
+    kind: 'builtin' | 'extra';
+    /** Executable to spawn. */
+    command: string;
+    /** Its arguments. */
+    args: string[];
+    /** The command line as the table prints it. */
+    display: string;
+    cwd: string;
+    timeoutMs?: number | undefined;
+    /** Steps that must finish before this one starts (ordering only). */
+    after: string[];
+    /** Set when the step is planned but not run, with the reason. */
+    skipReason?: string | undefined;
+    /**
+     * Why it is skipped: `config` when `check.skip` names it (a decision),
+     * `unavailable` when the project has nothing for it to run (a gap,
+     * which `check.failOnSkipped` fails).
+     */
+    skipKind?: 'config' | 'unavailable' | undefined;
+    /** Extra environment for the child. */
+    env?: Record<string, string> | undefined;
+    /** Condenses a finished run into the table's detail cell. */
+    summarize: (output: {
+        stdout: string;
+        combined: string;
+        exitCode: number;
+    }) => string;
+}
+/** The project facts the plan depends on. */
+export interface CheckPlanInput {
+    projectRoot: string;
+    config: FireForgeConfig;
+    furnaceConfigured: boolean;
+    /** Resolved `--patches` filenames, forwarded to status, verify and lint. */
+    patches?: string[] | undefined;
+}
+/**
+ * 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 declare function lastOutputLine(combined: string, exitCode: number): string;
+/** Status detail from its `--json --summary` document: the failing classes. */
+export declare function summarizeStatus(output: {
+    stdout: string;
+    combined: string;
+    exitCode: number;
+}): string;
+/** Furnace detail from its `--json` document: counts after exceptions. */
+export declare function summarizeFurnace(output: {
+    stdout: string;
+    combined: string;
+    exitCode: number;
+}): string;
+/** Token-coverage detail: the coverage percentage it reports. */
+export declare function summarizeTokenCoverage(output: {
+    stdout: string;
+    combined: string;
+    exitCode: number;
+}): string;
+/** The status step's `--check` flags from `check.status`. */
+export declare function statusPolicyArgs(policy: CheckConfig['status']): string[];
+/**
+ * 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 declare function buildCheckPlan(input: CheckPlanInput): CheckStepPlan[];

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

@@ -0,0 +1,200 @@
+// 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,
+        timeoutMs: extra.timeoutMs,
+        after: extra.after ?? [],
+        skipReason: extra.skipReason,
+        skipKind: extra.skipReason !== undefined ? 'unavailable' : undefined,
+        summarize,
+    };
+}
+/** A built-in step's budget: `check.timeouts.<step>`, else `check.timeout`. */
+function builtinTimeoutMs(check, name) {
+    const seconds = check.timeouts?.[name] ?? check.timeout;
+    return seconds !== undefined ? seconds * 1000 : undefined;
+}
+/** 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 lintReport = check.lintReport !== undefined ? join(projectRoot, check.lintReport) : undefined;
+    const lintReportArgs = lintReport !== undefined ? ['--report', lintReport] : [];
+    const timeoutMs = (name) => builtinTimeoutMs(check, name);
+    const plan = [
+        builtinStep(invocation, projectRoot, 'status', ['status', '--json', '--summary', '--check', ...statusPolicyArgs(check.status), ...patchArgs], summarizeStatus, { timeoutMs: timeoutMs('status') }),
+        builtinStep(invocation, projectRoot, 'verify', ['verify', ...patchArgs], generic, {
+            timeoutMs: timeoutMs('verify'),
+        }),
+        builtinStep(invocation, projectRoot, 'lint', [
+            'lint',
+            '--per-patch',
+            '--notices',
+            'summary',
+            ...lintWarnings,
+            ...lintReportArgs,
+            ...patchArgs,
+        ], generic, { timeoutMs: timeoutMs('lint') }),
+        builtinStep(invocation, projectRoot, 'typecheck', ['typecheck'], generic, {
+            skipReason: config.typecheck === undefined ? 'no "typecheck" block in fireforge.json' : undefined,
+            timeoutMs: timeoutMs('typecheck'),
+        }),
+        builtinStep(invocation, projectRoot, 'furnace-validate', ['furnace', 'validate', '--json', ...furnaceWarnings], summarizeFurnace, {
+            after: ['typecheck'],
+            skipReason: input.furnaceConfigured ? undefined : 'no furnace.json',
+            timeoutMs: timeoutMs('furnace-validate'),
+        }),
+        builtinStep(invocation, projectRoot, 'token-coverage', ['token', 'coverage'], summarizeTokenCoverage, { timeoutMs: timeoutMs('token-coverage') }),
+    ];
+    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: step.after ?? [],
+            env: lintReport !== undefined ? { FIREFORGE_CHECK_LINT_REPORT: lintReport } : undefined,
+            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';
+            step.skipKind = 'config';
+        }
+    }
+    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, { failOnSkipped: config.check?.failOnSkipped });
+    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/declarations-report.d.ts

@@ -0,0 +1,43 @@
+import type { ConflictReport } from '../core/destructive.js';
+import type { PatchLintIssue, PatchLintStagedDeclaration } from '../types/commands/index.js';
+/** A written declaration report and the commands that apply it. */
+export interface DeclarationsReport {
+    /** Absolute path of the JSON report. */
+    path: string;
+    /** Declarations written. */
+    count: number;
+    /** One `patch staged-dependency <holder> --add --from` call per holder. */
+    commands: string[];
+}
+/**
+ * A declaration as the report records it. `owner` is dropped when it names
+ * a patch the refused change would have created, which does not exist yet.
+ */
+export type ReportedDeclaration = Omit<PatchLintStagedDeclaration, 'owner'> & {
+    owner?: string;
+};
+/** Rewrites a projected declaration into the names the current queue uses. */
+export type DeclarationRenamer = (declaration: PatchLintStagedDeclaration) => ReportedDeclaration;
+/**
+ * Writes every declaration `issues` propose into one report, or returns
+ * undefined when they propose none.
+ *
+ * @param projectRoot - Project root (the default report directory lives under it)
+ * @param issues - The refusal's findings
+ * @param out - `--declarations-out`, relative to the working directory
+ * @param rename - Maps projected patch names back to current ones
+ */
+export declare function writeDeclarationsReport(projectRoot: string, issues: readonly PatchLintIssue[], out?: string, rename?: DeclarationRenamer): Promise<DeclarationsReport | undefined>;
+/** The refusal lines that point at a written report. */
+export declare function formatDeclarationsReport(report: DeclarationsReport): string[];
+/**
+ * Appends the report lines to a refusal, writing the report from the
+ * refusal's findings. A refusal that proposes no declaration is returned
+ * unchanged, and so is no refusal at all.
+ */
+export declare function withDeclarationsReport(conflicts: ConflictReport | null, args: {
+    projectRoot: string;
+    regressions: readonly PatchLintIssue[];
+    out?: string | undefined;
+    rename?: DeclarationRenamer;
+}): Promise<ConflictReport | null>;

package/dist/src/commands/declarations-report.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * One `--from`-ready declaration report for a refused queue change.
+ *
+ * Moving a test out of a patch that owns a shared manifest refused with one
+ * `forward-registration` error per manifest line, and each line needed its
+ * own `patch staged-dependency --add` call: a slice that added seven suites
+ * wrote eighteen declarations by hand. `patch move-files`, `patch split`
+ * and `re-export --scan` now write every declaration their refusal proposes
+ * into one lint-report-shaped JSON (`queueIssues[].stagedDeclarations`) and
+ * name the single `patch staged-dependency <holder> --add --from <file>`
+ * call per holding patch that discharges them.
+ */
+import { join, resolve } from 'node:path';
+import { STAGED_DEPENDENCY_REASON_PLACEHOLDER } from '../core/patch-lint-staged-registration.js';
+import { ensureDir, writeJson } from '../utils/fs.js';
+/** Where an unnamed report goes, relative to the project root. */
+const DEFAULT_REPORT_DIR = join('.fireforge', 'declarations');
+/** The checks whose findings carry declarations that discharge them. */
+const DECLARABLE_CHECKS = new Set(['forward-import', 'forward-registration']);
+/**
+ * Writes every declaration `issues` propose into one report, or returns
+ * undefined when they propose none.
+ *
+ * @param projectRoot - Project root (the default report directory lives under it)
+ * @param issues - The refusal's findings
+ * @param out - `--declarations-out`, relative to the working directory
+ * @param rename - Maps projected patch names back to current ones
+ */
+export async function writeDeclarationsReport(projectRoot, issues, out, rename = (declaration) => declaration) {
+    const queueIssues = issues
+        .filter((issue) => DECLARABLE_CHECKS.has(issue.check))
+        .map((issue) => ({
+        check: issue.check,
+        file: issue.file,
+        message: issue.message,
+        stagedDeclarations: (issue.stagedDeclarations ?? []).map(rename),
+    }))
+        .filter((issue) => issue.stagedDeclarations.length > 0);
+    const declarations = queueIssues.flatMap((issue) => issue.stagedDeclarations);
+    if (declarations.length === 0)
+        return undefined;
+    const path = out !== undefined
+        ? resolve(out)
+        : join(projectRoot, DEFAULT_REPORT_DIR, `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}.json`);
+    await ensureDir(resolve(path, '..'));
+    await writeJson(path, { queueIssues });
+    const holders = [...new Set(declarations.map((declaration) => declaration.patch))].sort();
+    return {
+        path,
+        count: declarations.length,
+        commands: holders.map((holder) => `fireforge patch staged-dependency ${holder} --add --from ${path} ` +
+            STAGED_DEPENDENCY_REASON_PLACEHOLDER),
+    };
+}
+/** The refusal lines that point at a written report. */
+export function formatDeclarationsReport(report) {
+    return [
+        `All ${report.count} declaration(s) this refusal proposes are in ${report.path}; ` +
+            'declare them in one call per holding patch:',
+        ...report.commands.map((command) => `  ${command}`),
+    ];
+}
+/**
+ * Appends the report lines to a refusal, writing the report from the
+ * refusal's findings. A refusal that proposes no declaration is returned
+ * unchanged, and so is no refusal at all.
+ */
+export async function withDeclarationsReport(conflicts, args) {
+    if (conflicts === null)
+        return null;
+    const report = await writeDeclarationsReport(args.projectRoot, args.regressions, args.out, args.rename);
+    if (report === undefined)
+        return conflicts;
+    return { ...conflicts, details: [...conflicts.details, ...formatDeclarationsReport(report)] };
+}

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) {