@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/commands/furnace/validate.js

@@ -1,309 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { getProjectPaths } from '../../core/config.js';
-import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
-import { assertFurnaceReady } from '../../core/furnace-precondition.js';
-import { addCustomElementRegistration, addJarMnEntries, pruneStaleJarMnEntries, } from '../../core/furnace-registration.js';
-import { validateAllComponents, validateComponent } from '../../core/furnace-validate.js';
-import { applyValidationExceptions, } from '../../core/furnace-validate-exceptions.js';
-import { createIssue } from '../../core/furnace-validate-helpers.js';
-import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
-import { pathExists } from '../../utils/fs.js';
-import { info, intro, isMachineOutputMode, note, outro, setMachineOutputMode, warn, } from '../../utils/logger.js';
-import { judgeValidateReport, renderValidateHuman, renderValidateJson } from './validate-report.js';
-/** Checks that auto-fix can correct. */
-const FIXABLE_CHECKS = new Set([
-    'missing-jar-mn-mjs',
-    'missing-jar-mn-css',
-    'wrong-registration-pattern',
-    'stale-jar-registration',
-    'missing-custom-element-registration',
-]);
-/**
- * Auto-fixes registration issues that have deterministic solutions.
- * @returns Number of issues fixed
- */
-async function autoFixIssues(projectRoot, issues) {
-    const { engine: engineDir } = getProjectPaths(projectRoot);
-    const config = await loadFurnaceConfig(projectRoot);
-    const furnacePaths = getFurnacePaths(projectRoot);
-    let fixed = 0;
-    // Group jar.mn fixes per component to batch them
-    const jarMnFixesByComponent = new Map();
-    for (const issue of issues) {
-        if (!FIXABLE_CHECKS.has(issue.check))
-            continue;
-        const customConfig = config.custom[issue.component];
-        if (!customConfig)
-            continue;
-        if (issue.check === 'missing-jar-mn-mjs' || issue.check === 'missing-jar-mn-css') {
-            const ext = issue.check === 'missing-jar-mn-mjs' ? '.mjs' : '.css';
-            const fileName = `${issue.component}${ext}`;
-            const existing = jarMnFixesByComponent.get(issue.component) ?? [];
-            existing.push(fileName);
-            jarMnFixesByComponent.set(issue.component, existing);
-        }
-    }
-    // Prune stale jar.mn registrations (lines pointing at removed or renamed
-    // component files). These break packaging, and validate --fix must not
-    // report success without touching them.
-    if (issues.some((issue) => issue.check === 'stale-jar-registration')) {
-        try {
-            const pruned = await pruneStaleJarMnEntries(engineDir, furnacePaths.customDir, Object.keys(config.custom));
-            fixed += pruned.length;
-            for (const entry of pruned) {
-                info(`Fixed: pruned stale jar.mn line for ${entry.tagName}/${entry.fileName}`);
-            }
-        }
-        catch (err) {
-            warn(`Could not prune stale jar.mn lines: ${toError(err).message}`);
-        }
-    }
-    // Fix jar.mn entries
-    for (const [componentName, files] of jarMnFixesByComponent) {
-        try {
-            // addJarMnEntries is idempotent and reports how many entries it
-            // actually wrote. Only count + log the files that were added so the
-            // reported "fixed" number matches the on-disk change.
-            const added = await addJarMnEntries(engineDir, componentName, files);
-            fixed += added;
-            if (added > 0) {
-                info(`Fixed: added ${files.join(', ')} to jar.mn for ${componentName}`);
-            }
-            else {
-                info(`No-op: jar.mn entries for ${componentName} were already present`);
-            }
-        }
-        catch (err) {
-            warn(`Could not fix jar.mn for ${componentName}: ${toError(err).message}`);
-        }
-    }
-    // `wrong-registration-pattern` is not auto-fixed: the component is
-    // registered but in the wrong block, and moving code between blocks is too
-    // risky to do unattended. Only missing registrations are repaired, below.
-    // Repair components missing from customElements.js entirely (reported by
-    // validate as `missing-custom-element-registration`).
-    //
-    // Scoped to the components named in `issues`: iterating every entry in
-    // `config.custom` makes `furnace validate <one-component> --fix` write
-    // customElements.js registrations for every custom component, outside the
-    // issue list it was handed and invisibly, since `fixed` is never
-    // incremented here.
-    const componentsWithIssues = new Set(issues.map((issue) => issue.component));
-    for (const componentName of componentsWithIssues) {
-        const customConfig = config.custom[componentName];
-        if (!customConfig?.register)
-            continue;
-        const componentDir = join(furnacePaths.customDir, componentName);
-        if (!(await pathExists(componentDir)))
-            continue;
-        const entries = await readdir(componentDir, { withFileTypes: true });
-        const hasMjs = entries.some((e) => e.isFile() && e.name === `${componentName}.mjs`);
-        if (!hasMjs)
-            continue;
-        const modulePath = `chrome://global/content/elements/${componentName}.mjs`;
-        try {
-            // Idempotent: returns without error when already registered, so this
-            // stays a no-op for components whose registration is already correct.
-            await addCustomElementRegistration(engineDir, componentName, modulePath);
-        }
-        catch {
-            // Best-effort repair. The re-validation pass at the call site reports
-            // whatever is still outstanding.
-        }
-    }
-    return fixed;
-}
-/**
- * Resolves the named component's type and directory.
- * @returns undefined for a stock component (nothing local to validate)
- */
-function resolveNamedComponent(name, config, furnacePaths) {
-    if (name in config.overrides) {
-        return { type: 'override', componentDir: join(furnacePaths.overridesDir, name) };
-    }
-    if (name in config.custom) {
-        return { type: 'custom', componentDir: join(furnacePaths.customDir, name) };
-    }
-    if (config.stock.includes(name))
-        return undefined;
-    throw new FurnaceError(`Component "${name}" not found in furnace.json.`, name);
-}
-/**
- * Runs the first validation pass: one named component, or every override
- * and custom component. Returns undefined when there is nothing local to
- * validate (a stock component, or no components at all), after saying so.
- */
-async function runValidationPass(projectRoot, name, config, furnacePaths) {
-    if (name) {
-        const target = resolveNamedComponent(name, config, furnacePaths);
-        if (target === undefined) {
-            info(`"${name}" is a stock component. Stock components are not validated locally.`);
-            return undefined;
-        }
-        if (!(await pathExists(target.componentDir))) {
-            throw new FurnaceError(`Component directory not found for "${name}".`, name);
-        }
-        const issues = await validateComponent(target.componentDir, name, target.type, config, projectRoot);
-        return { results: new Map([[name, issues]]), judged: (component) => component === name };
-    }
-    if (Object.keys(config.overrides).length === 0 && Object.keys(config.custom).length === 0) {
-        info('No components to validate.');
-        return undefined;
-    }
-    if (config.stock.length > 0) {
-        info(`Skipping ${config.stock.length} stock component(s) (no local files to validate).`);
-    }
-    return { results: await validateAllComponents(projectRoot), judged: () => true };
-}
-/**
- * Runs `--fix` over the fixable findings, then re-validates the affected
- * components and swaps their findings in, so the summary and the JSON
- * report what auto-fix actually accomplished. The counter `autoFixIssues`
- * returns only counts calls that did not throw, so a write that succeeded
- * but did not resolve the finding would otherwise still be reported fixed.
- */
-async function applyAutoFix(projectRoot, config, furnacePaths, run, countedIssues) {
-    const fixableIssues = countedIssues.filter((issue) => FIXABLE_CHECKS.has(issue.check));
-    if (fixableIssues.length === 0) {
-        info('\nNo auto-fixable issues found. Remaining issues require manual resolution.');
-        return;
-    }
-    await autoFixIssues(projectRoot, fixableIssues);
-    const reValidated = await reValidateComponents(projectRoot, config, furnacePaths, new Set(fixableIssues.map((issue) => issue.component)));
-    for (const [component, issues] of reValidated)
-        run.results.set(component, issues);
-    const fixableAfter = [...reValidated.values()]
-        .flat()
-        .filter((issue) => FIXABLE_CHECKS.has(issue.check)).length;
-    const actuallyFixed = Math.max(0, fixableIssues.length - fixableAfter);
-    if (actuallyFixed > 0) {
-        info(`\nAuto-fixed ${actuallyFixed} issue(s).`);
-    }
-    if (fixableAfter > 0) {
-        warn(`${fixableAfter} fixable issue(s) remain after auto-fix — investigate manually.`);
-    }
-}
-/** Applies `validationExceptions` to every finding of the run. */
-function exceptRun(run, config) {
-    return applyValidationExceptions([...run.results.values()].flat(), config.validationExceptions, run.judged);
-}
-/**
- * The `furnace.json#minComponents` floor of a full run: an error when it
- * judged fewer components, so a run over an emptied or moved components
- * tree cannot pass by validating nothing. A run naming one component is
- * not judged against it.
- */
-function componentFloorIssue(config, name, judged) {
-    if (name !== undefined || config.minComponents === undefined)
-        return undefined;
-    if (judged >= config.minComponents)
-        return undefined;
-    return createIssue('furnace.json', 'error', 'component-floor', `Validated ${judged} component(s), under furnace.json minComponents ${config.minComponents}. ` +
-        'Check that the components tree is where furnace.json says, or lower the floor.');
-}
-/**
- * Runs the furnace validate command to perform static analysis on components.
- * @param projectRoot - Root directory of the project
- * @param name - Optional component name to validate (validates all if omitted)
- * @param options - Optional command options (`--fix`, `--json`, `--max-warnings`)
- */
-export async function furnaceValidateCommand(projectRoot, name, options = {}) {
-    const previousMachineOutputMode = isMachineOutputMode();
-    // `--json` owns stdout: every diagnostic routes to stderr from here on.
-    // On a throw the mode stays engaged and withErrorHandling resets it, so
-    // the refusal cannot land on stdout after the payload.
-    if (options.json === true)
-        setMachineOutputMode(true);
-    await runFurnaceValidate(projectRoot, name, options);
-    if (isMachineOutputMode() !== previousMachineOutputMode) {
-        setMachineOutputMode(previousMachineOutputMode);
-    }
-}
-async function runFurnaceValidate(projectRoot, name, options) {
-    intro('Furnace Validate');
-    // Gains the engine rung here: this was the one site in the family that
-    // checked furnace.json alone, so a validate against a missing engine
-    // produced downstream noise instead of the shared precondition refusal.
-    const { config } = await assertFurnaceReady(projectRoot);
-    const furnacePaths = getFurnacePaths(projectRoot);
-    const run = await runValidationPass(projectRoot, name, config, furnacePaths);
-    if (run === undefined) {
-        const floor = componentFloorIssue(config, name, 0);
-        if (options.json === true) {
-            renderValidateJson({
-                components: [],
-                outcome: { issues: floor ? [floor] : [], excepted: [], stale: [] },
-                maxWarnings: options.maxWarnings,
-            });
-        }
-        if (floor !== undefined) {
-            renderValidateHuman([], [floor]);
-            throw new FurnaceError('Validation failed with 1 error(s).');
-        }
-        outro(name ? 'Validation complete' : 'Done');
-        return;
-    }
-    const floor = componentFloorIssue(config, name, run.results.size);
-    const firstPass = exceptRun(run, config);
-    if (floor !== undefined)
-        firstPass.issues.push(floor);
-    renderValidateHuman([...run.results.keys()], firstPass.issues);
-    let outcome = firstPass;
-    if (options.fix && firstPass.issues.length > 0) {
-        await applyAutoFix(projectRoot, config, furnacePaths, run, firstPass.issues);
-        outcome = exceptRun(run, config);
-        if (floor !== undefined)
-            outcome.issues.push(floor);
-    }
-    const report = {
-        components: [...run.results.keys()],
-        outcome,
-        maxWarnings: options.maxWarnings,
-    };
-    const verdict = judgeValidateReport(report);
-    const excepted = outcome.excepted.length > 0 ? `, ${outcome.excepted.length} excepted` : '';
-    note(`${verdict.errors} error(s), ${verdict.warnings} warning(s)${excepted} across ${report.components.length} component(s)`, 'Validation Summary');
-    if (options.json === true)
-        renderValidateJson(report);
-    if (verdict.errors > 0) {
-        const fixHint = options.fix ? '' : ' Use --fix to auto-correct registration issues.';
-        info(`Fix the errors above and run "fireforge furnace validate" again.${fixHint}`);
-        throw new FurnaceError(`Validation failed with ${verdict.errors} error(s).`);
-    }
-    if (verdict.warningBudgetExceeded) {
-        throw new FurnaceError(`Validation failed: ${verdict.warnings} warning(s) exceed --max-warnings ${String(options.maxWarnings)}. ` +
-            'Fix them, or record a reviewed finding in furnace.json validationExceptions.');
-    }
-    outro('Validation passed');
-}
-/**
- * Re-validates a specific set of components after an auto-fix pass and
- * returns each one's post-fix findings. Used by the `--fix` path to
- * honestly report what auto-fix actually accomplished.
- */
-async function reValidateComponents(projectRoot, config, furnacePaths, componentNames) {
-    const results = new Map();
-    for (const componentName of componentNames) {
-        let type;
-        let componentDir;
-        if (componentName in config.overrides) {
-            type = 'override';
-            componentDir = join(furnacePaths.overridesDir, componentName);
-        }
-        else if (componentName in config.custom) {
-            type = 'custom';
-            componentDir = join(furnacePaths.customDir, componentName);
-        }
-        else {
-            // Stock or removed components are not local-validated, so skip silently.
-            continue;
-        }
-        if (!(await pathExists(componentDir)))
-            continue;
-        results.set(componentName, await validateComponent(componentDir, componentName, type, config, projectRoot));
-    }
-    return results;
-}

package/dist/src/commands/furnace/validation-output.d.ts

@@ -1,47 +0,0 @@
-import type { FurnacePaths } from '../../core/furnace-config.js';
-import type { DryRunAction, FurnaceConfig, ValidationIssue } from '../../types/furnace.js';
-import { type SpinnerHandle } from '../../utils/logger.js';
-/**
- * Displays validation issues and returns aggregated error and warning counts.
- * @param issues - Validation issues to render
- * @returns Tuple of [errorCount, warningCount]
- */
-export declare function displayValidationIssues(issues: ValidationIssue[]): [number, number];
-export type ValidationResult = {
-    done: true;
-} | {
-    done: false;
-    totalErrors: number;
-    totalWarnings: number;
-    componentCount: number;
-    skippedValidationCount: number;
-};
-export interface RunDeployValidationOptions {
-    /** Active spinner handle for progress display. */
-    validateSpinner: SpinnerHandle;
-    /** Optional component name (validates all if omitted). */
-    name: string | undefined;
-    /** Loaded Furnace configuration. */
-    config: FurnaceConfig;
-    /** Resolved Furnace workspace paths. */
-    furnacePaths: FurnacePaths;
-    /** Names of components whose apply step failed. */
-    failedComponents: Set<string>;
-    /** Whether deploy is running in dry-run mode. */
-    isDryRun: boolean;
-    /** Root directory of the project. */
-    projectRoot: string;
-    /** Projected actions of a dry run, used to filter projected issues. */
-    dryRunActions?: DryRunAction[] | undefined;
-    /**
-     * Extra components a named deploy also touched (fragment includers it
-     * refreshed). Validated alongside `name`; ignored when `name` is unset.
-     */
-    alsoValidate?: string[] | undefined;
-}
-/**
- * Runs the validation phase of a furnace deploy, checking all or a single component.
- * @param options - See {@link RunDeployValidationOptions}
- * @returns Validation counts, or `done: true` if the caller should early-return
- */
-export declare function runDeployValidation(options: RunDeployValidationOptions): Promise<ValidationResult>;

package/dist/src/commands/furnace/validation-output.js

@@ -1,161 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { join } from 'node:path';
-import { validateAllComponents, validateComponent } from '../../core/furnace-validate.js';
-import { applyValidationExceptions } from '../../core/furnace-validate-exceptions.js';
-import { FurnaceError } from '../../errors/furnace.js';
-import { pathExists } from '../../utils/fs.js';
-import { error, info, outro, success, warn } from '../../utils/logger.js';
-/**
- * Displays validation issues and returns aggregated error and warning counts.
- * @param issues - Validation issues to render
- * @returns Tuple of [errorCount, warningCount]
- */
-export function displayValidationIssues(issues) {
-    let errors = 0;
-    let warnings = 0;
-    for (const issue of issues) {
-        if (issue.severity === 'error') {
-            error(`${issue.component}: [${issue.check}] ${issue.message}`);
-            errors++;
-        }
-        else {
-            warn(`${issue.component}: [${issue.check}] ${issue.message}`);
-            warnings++;
-        }
-    }
-    return [errors, warnings];
-}
-function filterProjectedDryRunIssues(issues, actions) {
-    if (!actions || actions.length === 0)
-        return issues;
-    const plannedJarRegistrations = new Set(actions.filter((action) => action.action === 'register-jar').map((action) => action.component));
-    return issues.filter((issue) => {
-        if (plannedJarRegistrations.has(issue.component) &&
-            (issue.check === 'missing-jar-mn-mjs' || issue.check === 'missing-jar-mn-css')) {
-            return false;
-        }
-        return true;
-    });
-}
-/**
- * Drops the findings `furnace.json#validationExceptions` records as
- * reviewed, so a deploy does not fail on a finding `furnace validate`
- * accepts. Staleness is `furnace validate`'s report, not a deploy's.
- */
-function withoutExceptedIssues(issues, config) {
-    return applyValidationExceptions(issues, config.validationExceptions, () => false).issues;
-}
-function resolveNamedValidationTarget(name, config, furnacePaths) {
-    if (name in config.overrides) {
-        return {
-            type: 'override',
-            componentDir: join(furnacePaths.overridesDir, name),
-        };
-    }
-    if (name in config.custom) {
-        return {
-            type: 'custom',
-            componentDir: join(furnacePaths.customDir, name),
-        };
-    }
-    if (config.stock.includes(name)) {
-        return 'stock';
-    }
-    throw new FurnaceError(`Component "${name}" not found in furnace.json.`, name);
-}
-/**
- * Validates one named target and prints its outcome.
- * @returns `[errors, warnings]` for the target
- */
-async function validateNamedTarget(args) {
-    const { name, config, furnacePaths, isDryRun, projectRoot, dryRunActions } = args;
-    const target = resolveNamedValidationTarget(name, config, furnacePaths);
-    if (target === 'stock')
-        return [0, 0];
-    if (!(await pathExists(target.componentDir))) {
-        throw new FurnaceError(`Component directory not found for "${name}".`, name);
-    }
-    const rawIssues = await validateComponent(target.componentDir, name, target.type, config, projectRoot);
-    const counted = withoutExceptedIssues(rawIssues, config);
-    const issues = isDryRun ? filterProjectedDryRunIssues(counted, dryRunActions) : counted;
-    if (issues.length === 0) {
-        success(`${name} — all checks passed`);
-        return [0, 0];
-    }
-    return displayValidationIssues(issues);
-}
-/**
- * Runs the validation phase of a furnace deploy, checking all or a single component.
- * @param options - See {@link RunDeployValidationOptions}
- * @returns Validation counts, or `done: true` if the caller should early-return
- */
-export async function runDeployValidation(options) {
-    const { validateSpinner, name, config, furnacePaths, failedComponents, isDryRun, projectRoot, dryRunActions, alsoValidate, } = options;
-    let totalErrors = 0;
-    let totalWarnings = 0;
-    let componentCount = 0;
-    let skippedValidationCount = 0;
-    if (name && failedComponents.has(name)) {
-        skippedValidationCount = 1;
-        validateSpinner.stop('Validation skipped');
-        warn(`Skipping validation for ${name} because apply failed.`);
-    }
-    else if (name) {
-        const target = resolveNamedValidationTarget(name, config, furnacePaths);
-        if (target === 'stock') {
-            validateSpinner.stop('Validation skipped');
-            info(`"${name}" is a stock component. Stock components are not validated locally.`);
-            outro(isDryRun ? 'Dry run complete' : 'Deploy complete');
-            return { done: true };
-        }
-        if (!(await pathExists(target.componentDir))) {
-            validateSpinner.stop('Validation failed');
-            throw new FurnaceError(`Component directory not found for "${name}".`, name);
-        }
-        validateSpinner.stop('Validation complete');
-        // The named target first, then every includer the deploy refreshed on
-        // its behalf: those engine files changed in this deploy too, so this
-        // deploy's validation covers them.
-        const extra = (alsoValidate ?? []).filter((t) => t !== name && !failedComponents.has(t));
-        for (const tag of [name, ...extra]) {
-            const [errors, warnings] = await validateNamedTarget({
-                name: tag,
-                config,
-                furnacePaths,
-                isDryRun,
-                projectRoot,
-                dryRunActions,
-            });
-            componentCount++;
-            totalErrors += errors;
-            totalWarnings += warnings;
-        }
-    }
-    else {
-        const results = await validateAllComponents(projectRoot);
-        validateSpinner.stop('Validation complete');
-        for (const [componentName, issues] of results) {
-            if (failedComponents.has(componentName)) {
-                skippedValidationCount++;
-                continue;
-            }
-            componentCount++;
-            const counted = withoutExceptedIssues(issues, config);
-            const projectedIssues = isDryRun
-                ? filterProjectedDryRunIssues(counted, dryRunActions)
-                : counted;
-            if (projectedIssues.length === 0) {
-                success(`${componentName} — all checks passed`);
-            }
-            else {
-                const [errors, warnings] = displayValidationIssues(projectedIssues);
-                totalErrors += errors;
-                totalWarnings += warnings;
-            }
-        }
-        if (skippedValidationCount > 0) {
-            warn(`Skipped validation for ${skippedValidationCount} component(s) because their apply step failed.`);
-        }
-    }
-    return { done: false, totalErrors, totalWarnings, componentCount, skippedValidationCount };
-}

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

@@ -1,11 +0,0 @@
-import { Command } from 'commander';
-import type { CommandContext } from '../types/cli.js';
-import type { ImportOptions } from '../types/commands/index.js';
-/**
- * Runs the import command to apply patches.
- * @param projectRoot - Root directory of the project
- * @param options - Import options
- */
-export declare function importCommand(projectRoot: string, options?: ImportOptions): Promise<void>;
-/** Registers the import command on the CLI program. */
-export declare function registerImport(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/lint-per-patch.d.ts

@@ -1,10 +0,0 @@
-import type { LintCommandOptions } from '../types/commands/index.js';
-import type { ProjectPaths } from '../types/config.js';
-/**
- * Lints each patch in the queue as its own isolated diff, honouring
- * per-patch `lintIgnore` entries. Cross-patch rules still run once over
- * the whole queue so queue-level findings are not lost by the rescoping.
- * With `options.patches` set, only the named subset is linted (and the
- * queue-level findings are scoped to files those patches touch).
- */
-export declare function lintPerPatch(projectRoot: string, paths: ProjectPaths, options?: LintCommandOptions): Promise<void>;