@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,76 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Machine-readable per-patch lint report (`lint --per-patch --report
- * <path>`). One mechanism serves two observability gaps: consumers get each
- * patch's size metrics against the same thresholds the size rules fire on,
- * instead of mirroring `countNonBinaryDiffLines`, and lintIgnore-suppressed
- * issues stay visible with their measurements rather than vanishing.
- *
- * Helper module consumed by lint-per-patch.ts. No registrar is exported and
- * none is wanted.
- */
-import { getPatchSizeThresholds, resolvePatchSizeTier, } from '../core/patch-lint.js';
-import { evaluateLintIgnoreCeilings, evaluateLintIgnoreWaivers, } from '../core/patch-lint-ignore.js';
-import { writeJson } from '../utils/fs.js';
-import { info } from '../utils/logger.js';
-const LINT_REPORT_SCHEMA_VERSION = 1;
-/**
- * Writes the per-patch lint report JSON. Called after the per-patch
- * results are assembled in patch order. Policy findings are
- * patch-attributed by their `filename` field upstream and are not
- * duplicated here. Cross-patch findings (`forward-import`,
- * `forward-registration`, …) go in `queueIssues`, with the
- * `stagedDeclarations` that discharge them, so the report can be handed to
- * `patch staged-dependency --from` as is.
- */
-export async function writePerPatchLintReport(reportPath, subset, results, config, queueIssues = []) {
-    const metric = config.patchLint?.patchSizeMetric ?? 'diff';
-    const patches = [];
-    let errors = 0;
-    let warnings = 0;
-    let suppressed = 0;
-    let linted = 0;
-    let skipped = 0;
-    for (let i = 0; i < subset.length; i++) {
-        const patch = subset[i];
-        const result = results[i];
-        if (!patch || !result)
-            continue;
-        const tier = resolvePatchSizeTier(result.existingFiles, patch.tier);
-        const findings = [...result.rawIssues, ...result.suppressedIssues];
-        const measurements = { lines: result.lineCount, files: patch.filesAffected.length };
-        patches.push({
-            filename: patch.filename,
-            name: patch.name,
-            status: result.status,
-            metric,
-            lineCount: result.lineCount,
-            filesAffected: patch.filesAffected.length,
-            tier,
-            thresholds: getPatchSizeThresholds(tier.tier, config),
-            issues: result.rawIssues,
-            suppressedIssues: result.suppressedIssues,
-            lintIgnoreCeilings: result.status === 'skipped'
-                ? []
-                : evaluateLintIgnoreCeilings(patch.lintIgnore, findings, measurements),
-            lintIgnoreWaivers: result.status === 'skipped'
-                ? []
-                : evaluateLintIgnoreWaivers(patch.lintIgnore, findings, measurements),
-        });
-        if (result.status === 'skipped')
-            skipped++;
-        else
-            linted++;
-        errors += result.rawIssues.filter((issue) => issue.severity === 'error').length;
-        warnings += result.rawIssues.filter((issue) => issue.severity === 'warning').length;
-        suppressed += result.suppressedIssues.length;
-    }
-    await writeJson(reportPath, {
-        schemaVersion: LINT_REPORT_SCHEMA_VERSION,
-        generatedAt: new Date().toISOString(),
-        patches,
-        queueIssues,
-        totals: { linted, skipped, errors, warnings, suppressed },
-    });
-    info(`Per-patch lint report written to ${reportPath}.`);
-}

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

@@ -1,47 +0,0 @@
-import { Command } from 'commander';
-import { type PatchQueueContext } from '../core/patch-lint.js';
-import type { CommandContext } from '../types/cli.js';
-import type { LintCommandOptions, PatchLintIssue } from '../types/commands/index.js';
-/**
- * Result of {@link applyAggregateLintIgnoreSuppression}.
- */
-export interface AggregateLintIgnoreResult {
-    /** Issues remaining after suppression. */
-    issues: PatchLintIssue[];
-    /** Number of issues dropped because an owning patch listed the check in `lintIgnore`. */
-    dropped: number;
-}
-/**
- * Filters aggregate-mode lint issues against per-patch `lintIgnore` lists
- * drawn from the manifest. An issue is dropped when at least one patch whose
- * `filesAffected` covers `issue.file` lists `issue.check` in its
- * `lintIgnore`.
- *
- * Mirrors the per-patch contract: `--per-patch` mode threads each patch's
- * `lintIgnore` directly into `lintExportedPatch`, so a check the operator
- * explicitly waived in `patches.json` does not surface. Aggregate `--since`
- * mode has no patch-level scope of its own and would otherwise rediscover
- * the suppressed warning every CI run. Attributing each issue's file to its
- * owning patch via `filesAffected` re-establishes the same suppression
- * semantics. Cross-patch findings (forward-import, duplicate-creation) also
- * attribute via `issue.file`, which is the offending site and is owned by
- * some patch.
- *
- * Multiple owners: an issue is dropped if any owning patch waived the
- * rule. This is conservative: it never adds new findings, only drops
- * already-waived ones.
- *
- * @param issues - Issues collected from the aggregate lint run.
- * @param ctx - Patch queue context used to attribute file → patch.
- * @returns Filtered issue list and the count of dropped findings.
- */
-export declare function applyAggregateLintIgnoreSuppression(issues: PatchLintIssue[], ctx: PatchQueueContext): AggregateLintIgnoreResult;
-/**
- * Runs the lint command to check engine changes against patch quality rules.
- * @param projectRoot - Root directory of the project
- * @param files - Optional file/directory paths to lint (relative to engine/)
- * @param options - Additional lint options such as `--since` diff-scoping
- */
-export declare function lintCommand(projectRoot: string, files: string[], options?: LintCommandOptions): Promise<void>;
-/** Registers the lint command on the CLI program. */
-export declare function registerLint(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

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

@@ -1,38 +0,0 @@
-/**
- * Central manifest of every top-level FireForge command.
- *
- * The manifest is iterated from {@link createProgram} in cli.ts so that
- * adding a new command is a one-line change here instead of a three-line
- * edit (import + registration call + ordering) spread across cli.ts. It
- * also gives documentation tooling and tests a single authoritative list
- * of commands to enumerate.
- *
- * The order of entries in {@link COMMAND_MANIFEST} is the order commands
- * appear in `fireforge --help`. The order is chosen rather than
- * alphabetical, and groups related commands together.
- */
-import type { CommandRegistrar } from '../types/cli.js';
-/**
- * A single entry in the command manifest.
- */
-export interface CommandManifestEntry {
-    /**
-     * Human-readable command name, matching the first token of the
-     * command line (e.g. `build`, `furnace`). Informational only, since the
-     * authoritative command string lives inside each registrar's
-     * `.command(...)` call, but useful for documentation, manifest
-     * introspection, and test assertions.
-     */
-    name: string;
-    /**
-     * Group label used by the root CLI help and generated documentation.
-     */
-    group: 'project' | 'workflow' | 'engine' | 'diagnostics' | 'components';
-    /** Registers the command (and any subcommands) on the Commander program. */
-    register: CommandRegistrar;
-}
-/**
- * Ordered list of every top-level FireForge command. cli.ts iterates this
- * array to register commands in a single loop.
- */
-export declare const COMMAND_MANIFEST: readonly CommandManifestEntry[];

package/dist/src/commands/manifest.js

@@ -1,68 +0,0 @@
-import { registerBootstrap } from './bootstrap.js';
-import { registerBuild } from './build.js';
-import { registerCheck } from './check.js';
-import { registerConfig } from './config.js';
-import { registerDiscard } from './discard.js';
-import { registerDoctor } from './doctor.js';
-import { registerDownload } from './download.js';
-import { registerExport } from './export.js';
-import { registerExportAll } from './export-all.js';
-import { registerFurnace } from './furnace/index.js';
-import { registerImport } from './import.js';
-import { registerLint } from './lint.js';
-import { registerPackage } from './package.js';
-import { registerPark } from './park.js';
-import { registerPatch } from './patch/index.js';
-import { registerReExport } from './re-export-register.js';
-import { registerRebase } from './rebase/index.js';
-import { registerRegister } from './register.js';
-import { registerReset } from './reset.js';
-import { registerResolve } from './resolve.js';
-import { registerRun } from './run.js';
-import { registerSetup } from './setup.js';
-import { registerSource } from './source.js';
-import { registerStatus } from './status.js';
-import { registerTest } from './test-register.js';
-import { registerToken } from './token.js';
-import { registerTree } from './tree.js';
-import { registerTypecheck } from './typecheck.js';
-import { registerVerify } from './verify.js';
-import { registerWatch } from './watch.js';
-import { registerWire } from './wire.js';
-/**
- * Ordered list of every top-level FireForge command. cli.ts iterates this
- * array to register commands in a single loop.
- */
-export const COMMAND_MANIFEST = [
-    { name: 'setup', group: 'project', register: registerSetup },
-    { name: 'source', group: 'project', register: registerSource },
-    { name: 'download', group: 'engine', register: registerDownload },
-    { name: 'bootstrap', group: 'engine', register: registerBootstrap },
-    { name: 'import', group: 'workflow', register: registerImport },
-    { name: 'resolve', group: 'workflow', register: registerResolve },
-    { name: 'build', group: 'workflow', register: registerBuild },
-    { name: 'run', group: 'workflow', register: registerRun },
-    { name: 'status', group: 'workflow', register: registerStatus },
-    { name: 'reset', group: 'workflow', register: registerReset },
-    { name: 'discard', group: 'workflow', register: registerDiscard },
-    { name: 'export', group: 'workflow', register: registerExport },
-    { name: 'export-all', group: 'workflow', register: registerExportAll },
-    { name: 're-export', group: 'workflow', register: registerReExport },
-    { name: 'park', group: 'workflow', register: registerPark },
-    { name: 'patch', group: 'workflow', register: registerPatch },
-    { name: 'rebase', group: 'workflow', register: registerRebase },
-    { name: 'package', group: 'workflow', register: registerPackage },
-    { name: 'watch', group: 'workflow', register: registerWatch },
-    { name: 'test', group: 'workflow', register: registerTest },
-    { name: 'tree', group: 'workflow', register: registerTree },
-    { name: 'config', group: 'project', register: registerConfig },
-    { name: 'doctor', group: 'diagnostics', register: registerDoctor },
-    { name: 'register', group: 'workflow', register: registerRegister },
-    { name: 'wire', group: 'workflow', register: registerWire },
-    { name: 'token', group: 'components', register: registerToken },
-    { name: 'lint', group: 'diagnostics', register: registerLint },
-    { name: 'typecheck', group: 'diagnostics', register: registerTypecheck },
-    { name: 'verify', group: 'diagnostics', register: registerVerify },
-    { name: 'check', group: 'diagnostics', register: registerCheck },
-    { name: 'furnace', group: 'components', register: registerFurnace },
-];

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

@@ -1,11 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import type { PackageOptions } from '../types/commands/index.js';
-/**
- * Runs the package command to create a distribution package.
- * @param projectRoot - Root directory of the project
- * @param options - Package options
- */
-export declare function packageCommand(projectRoot: string, options: PackageOptions): Promise<void>;
-/** Registers the package command on the CLI program. */
-export declare function registerPackage(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

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

@@ -1,22 +0,0 @@
-import type { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-/** Options for `fireforge park`. */
-export interface ParkOptions {
-    label?: string;
-    hunks?: string;
-    restore?: string;
-    list?: boolean;
-    drop?: string;
-    dryRun?: boolean;
-    waitLock?: number | boolean;
-}
-/**
- * Runs `fireforge park`.
- *
- * @param projectRoot - Project root
- * @param identifier - The patch to park (omitted for --restore/--list/--drop)
- * @param options - See {@link ParkOptions}
- */
-export declare function parkCommand(projectRoot: string, identifier: string | undefined, options: ParkOptions): Promise<void>;
-/** Registers `fireforge park`. */
-export declare function registerPark(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/park.js

@@ -1,232 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * `fireforge park`: set one session's edits in a patch's files aside and
- * put them back after the owner commits.
- *
- *   park <patch> [--label <l>] [--hunks <diff>]   park and restore baseline
- *   park --restore <label>                         three-way merge them back
- *   park --list | park --drop <label>
- *
- * Without `--hunks` every drifted file of the patch goes back to its
- * queue-applied baseline. With `--hunks` only the named hunks are taken out
- * of the working tree. Either way the park warns when a hunk it takes out
- * removes a Fluent message id, or a whole file, that files outside the
- * patch still reference: a parked string still used by markup another
- * patch owns makes `document.l10n.ready` reject in every new window.
- */
-import { basename, join } from 'node:path';
-import { getProjectPaths } from '../core/config.js';
-import { withEngineSessionLock } from '../core/engine-session-lock.js';
-import { appendHistoryBestEffort } from '../core/history-log.js';
-import { dropPark, fluentIds, listParks, planRestore, readEngineFile, readPark, removedLines, writeEngineFile, writePark, } from '../core/park-store.js';
-import { createPatchedContentContext } from '../core/patch-apply.js';
-import { formatPatchNotFoundError } from '../core/patch-identifier-suggest.js';
-import { loadPatchesManifest, resolvePatchIdentifier } from '../core/patch-manifest.js';
-import { parseDiffSections } from '../core/patch-parse.js';
-import { GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { pathExists, readText } from '../utils/fs.js';
-import { info, intro, outro, success, warn } from '../utils/logger.js';
-import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
-import { applyHunksByContext } from './re-export-hunks.js';
-import { normalizeEngineRelativeInput } from './re-export-scan.js';
-/** The patch-applied baseline of each of `patch`'s files (null = absent). */
-async function baselinesOf(paths, patch) {
-    const { computePatched } = await createPatchedContentContext(paths.patches, paths.engine);
-    const deleted = new Set(parseDiffSections(await readText(join(paths.patches, patch.filename)))
-        .filter((section) => section.isDeletedFile)
-        .map((section) => section.targetPath));
-    const baselines = new Map();
-    for (const file of patch.filesAffected) {
-        baselines.set(file, deleted.has(file) ? null : await computePatched(file));
-    }
-    return baselines;
-}
-/** The files a park would change, with both sides. */
-async function planPark(paths, patch, hunksPath) {
-    if (hunksPath === undefined) {
-        const baselines = await baselinesOf(paths, patch);
-        const files = [];
-        for (const [path, after] of baselines) {
-            const before = await readEngineFile(paths.engine, path);
-            if (before !== after)
-                files.push({ path, before, after });
-        }
-        return files;
-    }
-    if (!(await pathExists(hunksPath))) {
-        throw new InvalidArgumentError(`--hunks ${hunksPath} does not exist.`, '--hunks');
-    }
-    const owned = new Set(patch.filesAffected);
-    const files = [];
-    for (const section of parseDiffSections(await readText(hunksPath))) {
-        const path = normalizeEngineRelativeInput(section.targetPath, '--hunks');
-        if (!owned.has(path)) {
-            throw new InvalidArgumentError(`--hunks names ${path}, which ${patch.filename} does not own.`, '--hunks');
-        }
-        const before = await readEngineFile(paths.engine, path);
-        const after = applyHunksByContext(before ?? '', section.hunks, true, path);
-        if (before !== after)
-            files.push({ path, before, after });
-    }
-    return files;
-}
-/**
- * Referrers outside the patch of what the park takes away: Fluent ids its
- * removed lines declare, and files it removes outright.
- */
-async function findOutsideReferrers(paths, manifest, patch, files) {
-    const needles = new Map();
-    for (const file of files) {
-        if (file.path.endsWith('.ftl')) {
-            for (const id of fluentIds(removedLines(file.before, file.after))) {
-                needles.set(id, `Fluent id "${id}" (${file.path})`);
-            }
-        }
-        if (file.before !== null && file.after === null) {
-            needles.set(basename(file.path), `file ${file.path}`);
-        }
-    }
-    if (needles.size === 0)
-        return [];
-    const own = new Set(patch.filesAffected);
-    const outside = [...new Set(manifest.patches.flatMap((entry) => entry.filesAffected))].filter((file) => !own.has(file));
-    const findings = [];
-    for (const file of outside) {
-        const content = await readEngineFile(paths.engine, file);
-        if (content === null)
-            continue;
-        for (const [needle, label] of needles) {
-            if (content.includes(needle))
-                findings.push(`${label} is still referenced by ${file}`);
-        }
-    }
-    return findings;
-}
-async function runPark(projectRoot, identifier, options) {
-    const paths = getProjectPaths(projectRoot);
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest)
-        throw new GeneralError('No patches/patches.json; nothing to park against.');
-    const patch = resolvePatchIdentifier(identifier, manifest.patches);
-    if (!patch) {
-        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), 'park');
-    }
-    const files = await planPark(paths, patch, options.hunks);
-    if (files.length === 0) {
-        info(`${patch.filename}: nothing to park; its files match ${options.hunks ?? 'the baseline'}.`);
-        return;
-    }
-    for (const finding of await findOutsideReferrers(paths, manifest, patch, files)) {
-        warn(`Parking removes what is still in use: ${finding}. Move it somewhere you own first.`);
-    }
-    const label = options.label ?? `${patch.filename.replace(/\.patch$/, '')}-${Date.now().toString(36)}`;
-    for (const file of files)
-        info(`  ${file.path}`);
-    if (options.dryRun === true) {
-        info(`[dry-run] would park ${files.length} file(s) of ${patch.filename} as "${label}".`);
-        return;
-    }
-    const dir = await writePark(projectRoot, {
-        label,
-        patch: patch.filename,
-        createdAt: new Date().toISOString(),
-        mode: options.hunks === undefined ? 'baseline' : 'hunks',
-        files,
-    });
-    for (const file of files)
-        await writeEngineFile(paths.engine, file.path, file.after);
-    await appendHistoryBestEffort(paths.patches, {
-        operation: 'park',
-        args: { label, patch: patch.filename, files: files.map((file) => file.path) },
-        result: 'ok',
-    }, `park ${label}`);
-    success(`Parked ${files.length} file(s) of ${patch.filename} as "${label}" (${dir}).`);
-    info(`Restore with: fireforge park --restore ${label}`);
-}
-async function runRestore(projectRoot, label, dryRun) {
-    const paths = getProjectPaths(projectRoot);
-    const park = await readPark(projectRoot, label);
-    const conflicts = [];
-    const plans = [];
-    for (const file of park.files) {
-        const now = await readEngineFile(paths.engine, file.path);
-        const plan = await planRestore(file, now);
-        plans.push({ file, ...plan });
-        if (plan.outcome === 'conflict')
-            conflicts.push(file.path);
-    }
-    for (const { file, outcome } of plans)
-        info(`  ${file.path}: ${outcome}`);
-    if (dryRun) {
-        info(`[dry-run] restoring "${label}" would leave ${conflicts.length} conflict(s).`);
-        return;
-    }
-    for (const { file, content, outcome } of plans) {
-        if (outcome !== 'unchanged')
-            await writeEngineFile(paths.engine, file.path, content);
-    }
-    await appendHistoryBestEffort(paths.patches, {
-        operation: 'park-restore',
-        args: { label, patch: park.patch, conflicts },
-        result: conflicts.length === 0 ? 'ok' : 'conflict',
-    }, `park --restore ${label}`);
-    if (conflicts.length > 0) {
-        throw new GeneralError(`Restoring "${label}" left conflict markers in ${conflicts.join(', ')}. Resolve them, ` +
-            `then drop the park with "fireforge park --drop ${label}".`);
-    }
-    await dropPark(projectRoot, label);
-    success(`Restored "${label}" into ${park.files.length} file(s) of ${park.patch}.`);
-}
-/**
- * Runs `fireforge park`.
- *
- * @param projectRoot - Project root
- * @param identifier - The patch to park (omitted for --restore/--list/--drop)
- * @param options - See {@link ParkOptions}
- */
-export async function parkCommand(projectRoot, identifier, options) {
-    intro('FireForge park');
-    const modes = [identifier !== undefined, options.restore, options.list, options.drop].filter((mode) => mode !== undefined && mode !== false);
-    if (modes.length !== 1) {
-        throw new InvalidArgumentError('Pass exactly one of: a patch to park, --restore <label>, --list or --drop <label>.', 'park');
-    }
-    if (options.list === true) {
-        const parks = await listParks(projectRoot);
-        if (parks.length === 0)
-            info('No parks.');
-        for (const park of parks) {
-            info(`${park.label}  ${park.patch}  ${park.files.length} file(s)  ${park.createdAt}`);
-        }
-    }
-    else if (options.drop !== undefined) {
-        await dropPark(projectRoot, options.drop);
-        success(`Dropped park "${options.drop}".`);
-    }
-    else if (options.restore !== undefined) {
-        await runRestore(projectRoot, options.restore, options.dryRun === true);
-    }
-    else if (identifier !== undefined) {
-        await runPark(projectRoot, identifier, options);
-    }
-    outro('Park complete');
-}
-/** Registers `fireforge park`. */
-export function registerPark(program, { getProjectRoot, withErrorHandling }) {
-    const command = program
-        .command('park [patch]')
-        .description("Set a session's edits in a patch's files aside (back to the queue-applied baseline, or minus the hunks a diff names) and three-way merge them back later")
-        .option('--label <label>', 'Name for the park (default: <patch>-<time>)')
-        .option('--hunks <diff>', 'Park only the hunks this diff names, not every drifted line')
-        .option('--restore <label>', 'Three-way merge a park back into the engine, then drop it')
-        .option('--list', 'List the parks')
-        .option('--drop <label>', 'Delete a park without restoring it')
-        .option('--dry-run', 'Show what would be parked or restored');
-    addWaitLockOption(command).action(withErrorHandling(async (patch, options) => {
-        const projectRoot = getProjectRoot();
-        if (options.list === true || options.drop !== undefined || options.dryRun === true) {
-            await parkCommand(projectRoot, patch, options);
-            return;
-        }
-        await withEngineSessionLock(projectRoot, 'park', () => parkCommand(projectRoot, patch, options), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
-    }));
-}

package/dist/src/commands/patch/compact.d.ts

@@ -1,28 +0,0 @@
-/**
- * `fireforge patch compact`: closes ordinal gaps in the patch queue.
- *
- * After deletes or splits, patch ordinals may have gaps (e.g. 1, 3, 7).
- * This command renumbers patches to close those gaps in a single atomic
- * operation, preserving relative order. Without a patch policy the whole
- * queue is renumbered from 1. With `patchPolicy.ranges` configured the
- * compaction is range-aware (each category range compacts independently,
- * reserved ranges and out-of-range strays are left untouched).
- */
-import { Command } from 'commander';
-import type { CommandContext } from '../../types/cli.js';
-import type { PatchCompactOptions } from '../../types/commands/index.js';
-/**
- * Runs the `patch compact` command: renumbers all patches to close ordinal
- * gaps in a single atomic operation.
- *
- * @param projectRoot - Project root directory
- * @param options - Command options
- */
-export declare function patchCompactCommand(projectRoot: string, options?: PatchCompactOptions): Promise<void>;
-/**
- * Registers the `patch compact` subcommand on the `patch` parent.
- *
- * @param parent - Parent Commander command
- * @param context - Shared CLI registration context
- */
-export declare function registerPatchCompact(parent: Command, context: CommandContext): void;