@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,83 +0,0 @@
-// 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 refuses with one
- * `forward-registration` error per manifest line, and each line would need
- * its own `patch staged-dependency --add` call. `patch move-files`,
- * `patch split` and `re-export --scan` 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
- * @param reason - Rationale stamped on every declaration that carries none
- *   (`patch move-files` and `patch split` name the move that needs it)
- */
-export async function writeDeclarationsReport(projectRoot, issues, out, rename = (declaration) => declaration, reason) {
-    const withReason = (declaration) => reason === undefined || declaration.reason !== undefined
-        ? declaration
-        : { ...declaration, reason };
-    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((declaration) => withReason(rename(declaration))),
-    }))
-        .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();
-    // A report whose every entry carries its reason needs no `--reason`.
-    const reasonFlag = declarations.every((declaration) => declaration.reason !== undefined)
-        ? ''
-        : ` ${STAGED_DEPENDENCY_REASON_PLACEHOLDER}`;
-    return {
-        path,
-        count: declarations.length,
-        commands: holders.map((holder) => `fireforge patch staged-dependency ${holder} --add --from ${path}${reasonFlag}`),
-    };
-}
-/** 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, args.reason);
-    if (report === undefined)
-        return conflicts;
-    return { ...conflicts, details: [...conflicts.details, ...formatDeclarationsReport(report)] };
-}

package/dist/src/commands/destructive-decision.d.ts

@@ -1,19 +0,0 @@
-import type { DestructiveOpResult } from '../core/destructive.js';
-/**
- * Closes out a {@link DestructiveOpResult} and says whether to run the
- * mutation.
- *
- * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
- * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
- * The dry-run wording is a user-facing contract that must not drift between
- * commands, so it lives here. The declined wording is per-command and stays
- * a parameter.
- *
- * `confirmDestructive` never mutates on its own, so a caller that forgets this
- * check silently performs a "dry run" for real. That is why this returns a
- * boolean the caller must act on instead of being a helper that returns void.
- * @param decision - The result from `confirmDestructive`.
- * @param declinedOutro - Outro to print when the operator answered "no".
- * @returns True when the caller should proceed with the mutation.
- */
-export declare function proceedAfterDecision(decision: DestructiveOpResult, declinedOutro: string): boolean;

package/dist/src/commands/destructive-decision.js

@@ -1,31 +0,0 @@
-import { outro } from '../utils/logger.js';
-/** The dry-run outro every command prints, spelled once. */
-const DRY_RUN_OUTRO = 'Dry run complete — no changes made';
-/**
- * Closes out a {@link DestructiveOpResult} and says whether to run the
- * mutation.
- *
- * Eleven commands had copied the same tail: `if (decision === 'dry-run') {
- * outro(…); return; } if (decision === 'declined') { outro(…); return; }`.
- * The dry-run wording is a user-facing contract that must not drift between
- * commands, so it lives here. The declined wording is per-command and stays
- * a parameter.
- *
- * `confirmDestructive` never mutates on its own, so a caller that forgets this
- * check silently performs a "dry run" for real. That is why this returns a
- * boolean the caller must act on instead of being a helper that returns void.
- * @param decision - The result from `confirmDestructive`.
- * @param declinedOutro - Outro to print when the operator answered "no".
- * @returns True when the caller should proceed with the mutation.
- */
-export function proceedAfterDecision(decision, declinedOutro) {
-    if (decision === 'dry-run') {
-        outro(DRY_RUN_OUTRO);
-        return false;
-    }
-    if (decision === 'declined') {
-        outro(declinedOutro);
-        return false;
-    }
-    return true;
-}

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

@@ -1,12 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import type { DiscardOptions } from '../types/commands/index.js';
-/**
- * Runs the discard command to revert changes to a specific file.
- * @param projectRoot - Root directory of the project
- * @param file - File path to discard (relative to engine/)
- * @param options - Discard options
- */
-export declare function discardCommand(projectRoot: string, file: string, options?: DiscardOptions): Promise<void>;
-/** Registers the discard command on the CLI program. */
-export declare function registerDiscard(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/doctor-check-core.d.ts

@@ -1,110 +0,0 @@
-/**
- * Doctor check types and lightweight result builders shared between
- * `doctor.ts` and sibling check modules. Kept separate so registries can import
- * these symbols without creating cycles through `doctor.ts`.
- */
-import type { DoctorCheck, DoctorOptions } from '../types/commands/index.js';
-import type { FireForgeConfig, FireForgeState, ProjectPaths } from '../types/config.js';
-import type { FurnaceConfig } from '../types/furnace.js';
-/**
- * Shared state available to every doctor check during a single run.
- *
- * The context is populated lazily by the doctor runner. Individual checks
- * can record side-observations (e.g. the parsed `fireforge.json`) into the
- * context for later checks to consume without re-parsing.
- */
-export interface DoctorCheckContext {
-    projectRoot: string;
-    paths: ProjectPaths;
-    state: FireForgeState;
-    options: DoctorOptions;
-    /**
-     * Whether the engine/ directory exists on disk. Populated before checks
-     * run so downstream checks can skip git/mach inspections cheaply.
-     */
-    engineExists: boolean;
-    /**
-     * The loaded project config, set by the "fireforge.json is valid" check
-     * when it succeeds. Undefined before that check runs and whenever loading
-     * failed.
-     */
-    config: FireForgeConfig | undefined;
-    /**
-     * Whether `furnace.json` exists on disk. Populated before checks run so
-     * the furnace group can skipIf cheaply when the subsystem is not in use.
-     */
-    furnaceConfigExists: boolean;
-    /**
-     * The parsed furnace config, set by the "Furnace configuration" check
-     * when it succeeds. Later furnace checks read from this so they do not
-     * re-parse the file. Undefined when the config could not be loaded.
-     */
-    furnaceConfig: FurnaceConfig | undefined;
-    /**
-     * State this run actually mutated, one human-readable line per write.
-     * Repairs run inside the check loop while the exit code is computed only
-     * after every check, so a repair can land and the run still exit non-zero
-     * on an unrelated check, and a non-zero exit reads as "nothing happened".
-     * The runner prints these before the summary in every branch so a write is
-     * never invisible.
-     */
-    mutations: string[];
-}
-/**
- * Result a check may return. A single object is the common case. An array
- * lets a single check emit multiple related rows (e.g. the engine branch
- * check which may report on branch + detached state together).
- */
-export type CheckResult = DoctorCheck | DoctorCheck[];
-/**
- * Declarative definition of a single doctor check.
- *
- * Every check opts into the shared execution/reporting pipeline by
- * implementing only its inspection logic in `run`. Cross-cutting concerns
- * (result aggregation, summary, exit codes) live in the runner instead of
- * being duplicated at each call site.
- */
-export interface DoctorCheckDefinition {
-    /**
-     * Human-readable name surfaced in the check report (e.g. "Git installed").
-     * Not required to be unique, but tests assert on it.
-     */
-    name: string;
-    /**
-     * When `true`, the check is silently skipped. Used for checks that only
-     * apply when the engine is present, or only when specific state flags
-     * are set. Skipped checks contribute nothing to the final report.
-     */
-    skipIf?: (ctx: DoctorCheckContext) => boolean;
-    /**
-     * Names of checks that must appear earlier in the registry and run before
-     * this check. Enforced at startup via validateCheckDependencies so
-     * accidental reorders surface immediately instead of producing subtle
-     * context-population bugs at runtime.
-     */
-    dependsOn?: readonly string[];
-    /**
-     * Runs the inspection. Throwing is shorthand for "this check failed with
-     * severity 'error'": the runner converts the exception message into a
-     * DoctorCheck. Returning a DoctorCheck (or array) lets the check control
-     * severity, warnings, and fix hints directly.
-     */
-    run: (ctx: DoctorCheckContext) => CheckResult | Promise<CheckResult>;
-    /**
-     * Optional recovery hint attached to the auto-generated failure result
-     * when `run` throws. Ignored when `run` returns a DoctorCheck explicitly.
-     */
-    fix?: string;
-}
-/**
- * Builds a DoctorCheck object representing a successful "OK" check.
- */
-export declare function ok(name: string, message?: string): DoctorCheck;
-/**
- * Builds a DoctorCheck object representing a warning result.
- */
-export declare function warning(name: string, message: string, fix?: string): DoctorCheck;
-/**
- * Builds a DoctorCheck object representing a failure result.
- */
-export declare function failure(name: string, message: string, fix?: string): DoctorCheck;

package/dist/src/commands/doctor-check-core.js

@@ -1,24 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Doctor check types and lightweight result builders shared between
- * `doctor.ts` and sibling check modules. Kept separate so registries can import
- * these symbols without creating cycles through `doctor.ts`.
- */
-/**
- * Builds a DoctorCheck object representing a successful "OK" check.
- */
-export function ok(name, message = 'OK') {
-    return { name, severity: 'ok', message };
-}
-/**
- * Builds a DoctorCheck object representing a warning result.
- */
-export function warning(name, message, fix) {
-    return { name, severity: 'warning', message, ...(fix ? { fix } : {}) };
-}
-/**
- * Builds a DoctorCheck object representing a failure result.
- */
-export function failure(name, message, fix) {
-    return { name, severity: 'error', message, ...(fix ? { fix } : {}) };
-}

package/dist/src/commands/doctor-engine-eslint.d.ts

@@ -1,3 +0,0 @@
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-/** Surfaces the source-refresh ESLint precondition before an expensive gate/build. */
-export declare const ENGINE_ESLINT_DOCTOR_CHECK: DoctorCheckDefinition;

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

@@ -1,17 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { pathExists } from '../utils/fs.js';
-import { ok, warning } from './doctor-check-core.js';
-/** Surfaces the source-refresh ESLint precondition before an expensive gate/build. */
-export const ENGINE_ESLINT_DOCTOR_CHECK = {
-    name: 'Engine ESLint installed',
-    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.', 
-        // `./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-external-toolchains.d.ts

@@ -1,3 +0,0 @@
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-/** Doctor check for opt-in project-declared external asset/toolchain requirements. */
-export declare const EXTERNAL_TOOLCHAIN_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-external-toolchains.js

@@ -1,56 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { isAbsolute, resolve } from 'node:path';
-import { pathExists } from '../utils/fs.js';
-import { exec, findExecutable } from '../utils/process.js';
-import { failure, ok, warning } from './doctor-check-core.js';
-async function resolveDeclaredTool(projectRoot, tool) {
-    if (tool.path !== undefined) {
-        const candidate = isAbsolute(tool.path) ? tool.path : resolve(projectRoot, tool.path);
-        return (await pathExists(candidate)) ? candidate : undefined;
-    }
-    if (tool.xcrun === true) {
-        try {
-            const found = await exec('xcrun', ['-find', tool.name], { timeout: 5000 });
-            const line = found.stdout.split(/\r?\n/).find((entry) => entry.trim().length > 0);
-            return found.exitCode === 0 ? line?.trim() : undefined;
-        }
-        catch {
-            // `xcrun -find` is absent or the tool is unknown. Either way the tool
-            // has no resolvable path, which is what `undefined` means to the caller.
-            return undefined;
-        }
-    }
-    return findExecutable(tool.name);
-}
-async function runExternalToolchainChecks(ctx) {
-    const toolchains = ctx.config?.externalToolchains;
-    if (!toolchains || toolchains.length === 0)
-        return [];
-    const rows = [];
-    for (const toolchain of toolchains) {
-        for (const tool of toolchain.tools) {
-            const label = `External toolchain: ${toolchain.name}/${tool.name}`;
-            const found = await resolveDeclaredTool(ctx.projectRoot, tool);
-            if (found !== undefined) {
-                rows.push(ok(label, `OK (${found})`));
-                continue;
-            }
-            const required = tool.required !== false;
-            const location = tool.path
-                ? `at ${tool.path}`
-                : tool.xcrun
-                    ? `via xcrun -find ${tool.name}`
-                    : 'on PATH';
-            const message = `${tool.name} was not found ${location}.`;
-            const fix = `Install ${tool.name} or update fireforge.json externalToolchains for ${toolchain.name}.`;
-            rows.push(required ? failure(label, message, fix) : warning(label, message, fix));
-        }
-    }
-    return rows;
-}
-/** Doctor check for opt-in project-declared external asset/toolchain requirements. */
-export const EXTERNAL_TOOLCHAIN_DOCTOR_CHECK = {
-    name: 'External toolchains',
-    dependsOn: ['fireforge.json is valid'],
-    run: runExternalToolchainChecks,
-};

package/dist/src/commands/doctor-furnace-config-sync.d.ts

@@ -1,18 +0,0 @@
-/**
- * "Furnace config sync" doctor check.
- *
- * Surfaces orphaned component directories on disk whose names are missing
- * from `furnace.json`, typically the concurrent-override race, where two
- * parallel `furnace override` commands both leave their directory on disk
- * but only the second reaches `writeFurnaceConfig`. Under
- * `--repair-furnace`, override orphans are re-registered from the
- * `override.json` sidecar the command wrote during the copy phase. Custom
- * orphans are listed for the operator to either re-run `furnace create`
- * against or delete manually, because custom components have no similar
- * persisted metadata.
- *
- * Lives in a sibling module to keep `doctor-furnace.ts` under the per-file
- * LOC budget.
- */
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-export declare const furnaceConfigSyncCheck: DoctorCheckDefinition;