@hominis/fireforge 0.49.1 → 0.50.0

package/dist/src/commands/furnace/validate-report.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `furnace validate` result rendering: the human per-component lines and
+ * the `--json` document (schemaVersion 1, docs/machine-output.md), plus
+ * the verdict both share, so the exit code and the `passed` key can never
+ * disagree.
+ */
+import { type ValidationExceptionOutcome } from '../../core/furnace-validate-exceptions.js';
+import type { ValidationIssue } from '../../types/furnace.js';
+/** One finished `furnace validate` run. */
+export interface FurnaceValidateReport {
+    /** Components the run judged, in validation order. */
+    components: string[];
+    /** Findings after `validationExceptions` were applied. */
+    outcome: ValidationExceptionOutcome;
+    /** `--max-warnings`, when given. */
+    maxWarnings?: number | undefined;
+}
+/** The verdict: counts, and whether errors or the warning budget fail it. */
+export interface FurnaceValidateVerdict {
+    errors: number;
+    warnings: number;
+    /** True when `--max-warnings` was given and the warnings exceed it. */
+    warningBudgetExceeded: boolean;
+    passed: boolean;
+}
+/** Computes the verdict both renderings report. */
+export declare function judgeValidateReport(report: FurnaceValidateReport): FurnaceValidateVerdict;
+/**
+ * Prints one line per clean component and every finding of the rest.
+ * Findings on names outside `components` (a stale exception for a removed
+ * component, an orphaned scaffold) print after them.
+ */
+export declare function renderValidateHuman(components: readonly string[], issues: readonly ValidationIssue[]): void;
+/**
+ * Writes the `--json` document and seals stdout. Every finding is listed
+ * once in `issues` (stale-exception warnings included); `excepted` and
+ * `staleExceptions` restate the exception bookkeeping for a consumer that
+ * audits the list itself.
+ */
+export declare function renderValidateJson(report: FurnaceValidateReport): void;
+/**
+ * Parses `--max-warnings <n>`: a non-negative integer, or undefined when
+ * the flag was not given.
+ */
+export declare function parseMaxWarnings(raw: string | undefined): number | undefined;

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

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `furnace validate` result rendering: the human per-component lines and
+ * the `--json` document (schemaVersion 1, docs/machine-output.md), plus
+ * the verdict both share, so the exit code and the `passed` key can never
+ * disagree.
+ */
+import { countValidationSeverities, } from '../../core/furnace-validate-exceptions.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { setStdoutSealed, success } from '../../utils/logger.js';
+import { displayValidationIssues } from './validation-output.js';
+/** Computes the verdict both renderings report. */
+export function judgeValidateReport(report) {
+    const { errors, warnings } = countValidationSeverities(report.outcome.issues);
+    const warningBudgetExceeded = report.maxWarnings !== undefined && warnings > report.maxWarnings;
+    return {
+        errors,
+        warnings,
+        warningBudgetExceeded,
+        passed: errors === 0 && !warningBudgetExceeded,
+    };
+}
+/** Groups findings by component, keeping the report's component order first. */
+function groupByComponent(components, issues) {
+    const grouped = new Map(components.map((name) => [name, []]));
+    for (const issue of issues) {
+        const list = grouped.get(issue.component) ?? [];
+        list.push(issue);
+        grouped.set(issue.component, list);
+    }
+    return grouped;
+}
+/**
+ * Prints one line per clean component and every finding of the rest.
+ * Findings on names outside `components` (a stale exception for a removed
+ * component, an orphaned scaffold) print after them.
+ */
+export function renderValidateHuman(components, issues) {
+    for (const [name, componentIssues] of groupByComponent(components, issues)) {
+        if (componentIssues.length === 0) {
+            success(`${name} — all checks passed`);
+        }
+        else {
+            displayValidationIssues(componentIssues);
+        }
+    }
+}
+/**
+ * Writes the `--json` document and seals stdout. Every finding is listed
+ * once in `issues` (stale-exception warnings included); `excepted` and
+ * `staleExceptions` restate the exception bookkeeping for a consumer that
+ * audits the list itself.
+ */
+export function renderValidateJson(report) {
+    const verdict = judgeValidateReport(report);
+    const grouped = groupByComponent(report.components, report.outcome.issues);
+    const payload = {
+        schemaVersion: 1,
+        passed: verdict.passed,
+        summary: {
+            components: report.components.length,
+            errors: verdict.errors,
+            warnings: verdict.warnings,
+            excepted: report.outcome.excepted.length,
+            staleExceptions: report.outcome.stale.length,
+        },
+        ...(report.maxWarnings !== undefined ? { maxWarnings: report.maxWarnings } : {}),
+        components: report.components.map((name) => ({
+            name,
+            ...countValidationSeverities(grouped.get(name) ?? []),
+        })),
+        issues: report.outcome.issues,
+        excepted: report.outcome.excepted,
+        staleExceptions: report.outcome.stale,
+    };
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    setStdoutSealed(true);
+}
+/**
+ * Parses `--max-warnings <n>`: a non-negative integer, or undefined when
+ * the flag was not given.
+ */
+export function parseMaxWarnings(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new InvalidArgumentError('--max-warnings must be a non-negative integer.', '--max-warnings');
+    }
+    return value;
+}

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

@@ -3,6 +3,6 @@ import type { FurnaceValidateOptions } from '../../types/commands/index.js';
  * 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 (e.g. --fix)
+ * @param options - Optional command options (`--fix`, `--json`, `--max-warnings`)
  */
 export declare function furnaceValidateCommand(projectRoot: string, name?: string, options?: FurnaceValidateOptions): Promise<void>;

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

@@ -6,11 +6,12 @@ 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 { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
-import { info, intro, note, outro, success, warn } from '../../utils/logger.js';
-import { displayValidationIssues } from './validation-output.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',
@@ -114,133 +115,152 @@ async function autoFixIssues(projectRoot, issues) {
     }
     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);
+}
 /**
  * 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 (e.g. --fix)
+ * @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);
-    let totalErrors = 0;
-    let totalWarnings = 0;
-    let componentCount;
-    let allIssues = [];
-    if (name) {
-        // --- Single component validation ---
-        let type;
-        let componentDir;
-        if (name in config.overrides) {
-            type = 'override';
-            componentDir = join(furnacePaths.overridesDir, name);
-        }
-        else if (name in config.custom) {
-            type = 'custom';
-            componentDir = join(furnacePaths.customDir, name);
-        }
-        else if (config.stock.includes(name)) {
-            info(`"${name}" is a stock component. Stock components are not validated locally.`);
-            outro('Validation complete');
-            return;
-        }
-        else {
-            throw new FurnaceError(`Component "${name}" not found in furnace.json.`, name);
-        }
-        if (!(await pathExists(componentDir))) {
-            throw new FurnaceError(`Component directory not found for "${name}".`, name);
-        }
-        const issues = await validateComponent(componentDir, name, type, config, projectRoot);
-        componentCount = 1;
-        allIssues = issues;
-        if (issues.length === 0) {
-            success(`${name} — all checks passed`);
-        }
-        else {
-            const [e, w] = displayValidationIssues(issues);
-            totalErrors += e;
-            totalWarnings += w;
+    const run = await runValidationPass(projectRoot, name, config, furnacePaths);
+    if (run === undefined) {
+        if (options.json === true) {
+            renderValidateJson({
+                components: [],
+                outcome: { issues: [], excepted: [], stale: [] },
+                maxWarnings: options.maxWarnings,
+            });
         }
+        outro(name ? 'Validation complete' : 'Done');
+        return;
     }
-    else {
-        // --- Validate all components ---
-        const overrideCount = Object.keys(config.overrides).length;
-        const customCount = Object.keys(config.custom).length;
-        if (overrideCount === 0 && customCount === 0) {
-            info('No components to validate.');
-            outro('Done');
-            return;
-        }
-        if (config.stock.length > 0) {
-            info(`Skipping ${config.stock.length} stock component(s) (no local files to validate).`);
-        }
-        const results = await validateAllComponents(projectRoot);
-        componentCount = results.size;
-        for (const [componentName, issues] of results) {
-            allIssues.push(...issues);
-            if (issues.length === 0) {
-                success(`${componentName} — all checks passed`);
-            }
-            else {
-                const [e, w] = displayValidationIssues(issues);
-                totalErrors += e;
-                totalWarnings += w;
-            }
-        }
+    const firstPass = exceptRun(run, config);
+    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);
     }
-    // Auto-fix fixable issues when --fix is passed. The counter returned by
-    // `autoFixIssues` only counts function calls that did not throw, so a
-    // write that succeeded but did not actually resolve the issue
-    // (addJarMnEntries appending to a file mach later ignores) would still
-    // bump it. Re-validate the affected components and compute the real drop
-    // in fixable issues so the reported number is honest.
-    if (options.fix && allIssues.length > 0) {
-        const fixableIssues = allIssues.filter((issue) => FIXABLE_CHECKS.has(issue.check));
-        if (fixableIssues.length > 0) {
-            await autoFixIssues(projectRoot, fixableIssues);
-            const reValidated = await reValidateComponents(projectRoot, config, furnacePaths, new Set(fixableIssues.map((issue) => issue.component)));
-            const fixableBefore = fixableIssues.length;
-            const fixableAfter = reValidated.issues.filter((issue) => FIXABLE_CHECKS.has(issue.check)).length;
-            const actuallyFixed = Math.max(0, fixableBefore - fixableAfter);
-            // Replace the pre-fix issue totals with the post-fix view so the
-            // summary reflects current reality. Issues that auto-fix could not
-            // address still count toward totalErrors / totalWarnings.
-            totalErrors = reValidated.totalErrors;
-            totalWarnings = reValidated.totalWarnings;
-            if (actuallyFixed > 0) {
-                info(`\nAuto-fixed ${actuallyFixed} issue(s).`);
-            }
-            if (fixableAfter > 0) {
-                warn(`${fixableAfter} fixable issue(s) remain after auto-fix — investigate manually.`);
-            }
-        }
-        else {
-            info('\nNo auto-fixable issues found. Remaining issues require manual resolution.');
-        }
-    }
-    // Summary
-    note(`${totalErrors} error(s), ${totalWarnings} warning(s) across ${componentCount} component(s)`, 'Validation Summary');
-    if (totalErrors > 0) {
+    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 ${totalErrors} error(s).`);
+        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 the post-fix issue list with the recomputed error / warning
- * totals. Used by the `--fix` path to honestly report what auto-fix
- * actually accomplished.
+ * 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 issues = [];
-    let totalErrors = 0;
-    let totalWarnings = 0;
+    const results = new Map();
     for (const componentName of componentNames) {
         let type;
         let componentDir;
@@ -258,14 +278,7 @@ async function reValidateComponents(projectRoot, config, furnacePaths, component
         }
         if (!(await pathExists(componentDir)))
             continue;
-        const componentIssues = await validateComponent(componentDir, componentName, type, config, projectRoot);
-        issues.push(...componentIssues);
-        for (const issue of componentIssues) {
-            if (issue.severity === 'error')
-                totalErrors += 1;
-            else
-                totalWarnings += 1;
-        }
+        results.set(componentName, await validateComponent(componentDir, componentName, type, config, projectRoot));
     }
-    return { issues, totalErrors, totalWarnings };
+    return results;
 }

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

@@ -1,6 +1,7 @@
 // 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';
@@ -36,6 +37,14 @@ function filterProjectedDryRunIssues(issues, actions) {
         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 {
@@ -67,7 +76,8 @@ async function validateNamedTarget(args) {
         throw new FurnaceError(`Component directory not found for "${name}".`, name);
     }
     const rawIssues = await validateComponent(target.componentDir, name, target.type, config, projectRoot);
-    const issues = isDryRun ? filterProjectedDryRunIssues(rawIssues, dryRunActions) : rawIssues;
+    const counted = withoutExceptedIssues(rawIssues, config);
+    const issues = isDryRun ? filterProjectedDryRunIssues(counted, dryRunActions) : counted;
     if (issues.length === 0) {
         success(`${name} — all checks passed`);
         return [0, 0];
@@ -130,9 +140,10 @@ export async function runDeployValidation(options) {
                 continue;
             }
             componentCount++;
+            const counted = withoutExceptedIssues(issues, config);
             const projectedIssues = isDryRun
-                ? filterProjectedDryRunIssues(issues, dryRunActions)
-                : issues;
+                ? filterProjectedDryRunIssues(counted, dryRunActions)
+                : counted;
             if (projectedIssues.length === 0) {
                 success(`${componentName} — all checks passed`);
             }