@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/commands/furnace/rename-registrations.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Engine registration edits for `furnace rename`: the customElements.js
+ * entry (rewritten in place, keeping its marker comments), the
+ * toolkit/content/jar.mn widget lines, the deployed `.ftl`, and the locale
+ * jar.mn line (re-pointed only when one existed, never for `sharedFtl`).
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loadConfig } from '../../core/config.js';
+import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath, } from '../../core/furnace-constants.js';
+import { resolveFurnaceMarkerComment } from '../../core/furnace-marker.js';
+import { addCustomElementRegistration, addJarMnEntries, addLocaleFtlJarMnEntry, removeCustomElementRegistration, removeLocaleFtlJarMnEntry, renameCustomElementRegistration, } from '../../core/furnace-registration.js';
+import { renameJarMnEntriesInPlace } from '../../core/furnace-registration-jar-inplace.js';
+import { snapshotFile } from '../../core/furnace-rollback.js';
+import { pathExists, readText, removeFile, writeText } from '../../utils/fs.js';
+import { renameComponentFileName } from './rename-helpers.js';
+/**
+ * The project marker (`// <MARKER>:`) a registration line written by the
+ * rename carries, resolved exactly as `furnace apply` resolves it. An
+ * unreadable fireforge.json degrades to no marker rather than failing the
+ * rename.
+ */
+export async function loadMarkerComment(projectRoot) {
+    try {
+        return resolveFurnaceMarkerComment(await loadConfig(projectRoot));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Re-points the engine-side registrations (customElements.js, jar.mn, and
+ * the localized `.ftl` entries) from the old tag name to the new one.
+ *
+ * @param options - See {@link UpdateEngineRegistrationsOptions}
+ */
+export async function updateEngineRegistrations(options) {
+    const { engineDir, oldName, newName, newDir, ftlDir, componentConfig, markerComment, journal } = options;
+    const customElementsPath = join(engineDir, 'toolkit/content/customElements.js');
+    const jarMnPath = join(engineDir, 'toolkit/content/jar.mn');
+    if (await pathExists(customElementsPath)) {
+        await snapshotFile(journal, customElementsPath);
+        // Rewrite the existing entry in place: it keeps its position, layout and
+        // trailing `// <MARKER>:` comments. Only when there is no entry to
+        // rewrite is a fresh one added, carrying the project marker like every
+        // line `furnace apply` writes.
+        if (!(await renameCustomElementRegistration(engineDir, oldName, newName))) {
+            await removeCustomElementRegistration(engineDir, oldName);
+            await addCustomElementRegistration(engineDir, newName, `chrome://global/content/elements/${newName}.mjs`, markerComment !== undefined ? { markerComment } : {});
+        }
+    }
+    if (await pathExists(jarMnPath)) {
+        await snapshotFile(journal, jarMnPath);
+        const files = (await readdir(newDir, { withFileTypes: true }))
+            .filter((e) => e.isFile() && (e.name.endsWith('.mjs') || e.name.endsWith('.css')))
+            .map((e) => e.name);
+        // Rewrite the old lines where they stand, like the customElements.js
+        // entry above, so the rename moves no other line of the block; only a
+        // file with no line yet is inserted.
+        await renameJarMnEntriesInPlace(engineDir, oldName, newName, files, (file) => renameComponentFileName(file, oldName, newName));
+        if (files.length > 0) {
+            await addJarMnEntries(engineDir, newName, files);
+        }
+    }
+    // Rename FTL localization files in the engine locale directory
+    const ftlDirPath = join(engineDir, ftlDir);
+    const oldFtlPath = join(ftlDirPath, `${oldName}.ftl`);
+    const newFtlPath = join(ftlDirPath, `${newName}.ftl`);
+    if (await pathExists(oldFtlPath)) {
+        await snapshotFile(journal, oldFtlPath);
+        await snapshotFile(journal, newFtlPath);
+        const ftlContent = await readText(oldFtlPath);
+        await writeText(newFtlPath, ftlContent);
+        await removeFile(oldFtlPath);
+    }
+    // Re-point the locale jar.mn chrome registration when the component is
+    // localized. Renaming the .ftl file on disk alone leaves the locale
+    // jar.mn pointing at `locale/.../${oldName}.ftl`, so `furnace validate`
+    // passes while the engine still carries a stale registration for the
+    // now-missing file. Only an existing line is re-pointed: a `sharedFtl`
+    // component has no per-component .ftl, and adding a line for one names a
+    // file that does not exist (an unmanaged edit `mach build` trips over).
+    if (componentConfig.localized) {
+        const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+        const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+        if (chromeSubPath !== undefined && localeJarRel !== undefined) {
+            const localeJarAbs = join(engineDir, localeJarRel);
+            if (await pathExists(localeJarAbs)) {
+                await snapshotFile(journal, localeJarAbs);
+                const removed = await removeLocaleFtlJarMnEntry(engineDir, localeJarRel, oldName, chromeSubPath);
+                if (removed && componentConfig.sharedFtl === undefined) {
+                    await addLocaleFtlJarMnEntry(engineDir, localeJarRel, newName, chromeSubPath);
+                }
+            }
+        }
+    }
+}

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

@@ -1,5 +1,6 @@
+import type { FurnaceRenameOptions } from '../../types/commands/index.js';
 /**
  * Renames a custom or override component atomically: updates directory name,
  * file names, file contents, furnace.json, and engine registrations.
  */
-export declare function furnaceRenameCommand(projectRoot: string, oldName: string, newName: string): Promise<void>;
+export declare function furnaceRenameCommand(projectRoot: string, oldName: string, newName: string, options?: FurnaceRenameOptions): Promise<void>;

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

@@ -3,9 +3,8 @@ import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { isComponentSourceFile, resolveFtlChromeSubPath, resolveFtlDir, resolveFtlLocaleJarMnPath, tagNameToClassName, } from '../../core/furnace-constants.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
-import { addCustomElementRegistration, addJarMnEntries, addLocaleFtlJarMnEntry, removeCustomElementRegistration, removeJarMnEntries, removeLocaleFtlJarMnEntry, } from '../../core/furnace-registration.js';
+import { isComponentSourceFile, resolveFtlDir, tagNameToClassName, } from '../../core/furnace-constants.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { CUSTOM_ELEMENT_TAG_PATTERN, CUSTOM_ELEMENT_TAG_RULES, } from '../../core/furnace-registration-validate.js';
 import { createRollbackJournal, recordCreatedDir, snapshotDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getStoriesDir } from '../../core/furnace-stories.js';
@@ -16,7 +15,9 @@ import { copyFile, ensureDir, pathExists, readText, removeDir, removeFile, write
 import { info, intro, note, outro, warn } from '../../utils/logger.js';
 import { escapeRegex } from '../../utils/regex.js';
 import { updateBrowserChromeTestContent } from './rename-browser-test.js';
+import { renderRenamePlan } from './rename-dry-run.js';
 import { rekeyStateChecksums, renameComponentFileName, updateConfigForCustomRename, updateConfigForOverrideRename, } from './rename-helpers.js';
+import { loadMarkerComment, updateEngineRegistrations } from './rename-registrations.js';
 import { renameXpcshellTestFiles } from './rename-xpcshell.js';
 import { browserTestFileName } from './test-file-name.js';
 /**
@@ -165,7 +166,7 @@ async function performRenameMutations(args) {
     const { projectRoot, oldName, newName } = args;
     const oldClassName = tagNameToClassName(oldName);
     const newClassName = tagNameToClassName(newName);
-    await runFurnaceMutation(projectRoot, 'rename-rollback', async (ctx) => {
+    const mutate = async (ctx) => {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
         let newDir = args.newDir;
@@ -245,16 +246,16 @@ async function performRenameMutations(args) {
             }
             await writeFurnaceConfig(projectRoot, config);
             // 3. Update engine registrations (custom components only)
-            if (isCustom && config.custom[newName]?.register && (await pathExists(args.engineDir))) {
-                const ftlDir = resolveFtlDir(config.ftlBasePath);
-                const isLocalized = config.custom[newName].localized;
+            const newConfig = config.custom[newName];
+            if (isCustom && newConfig?.register && (await pathExists(args.engineDir))) {
                 await updateEngineRegistrations({
                     engineDir: args.engineDir,
                     oldName,
                     newName,
                     newDir,
-                    ftlDir,
-                    isLocalized,
+                    ftlDir: resolveFtlDir(config.ftlBasePath),
+                    componentConfig: newConfig,
+                    markerComment: await loadMarkerComment(projectRoot),
                     journal,
                 });
             }
@@ -318,68 +319,15 @@ async function performRenameMutations(args) {
                 subject: `rename "${oldName}" → "${newName}"`,
             });
         }
-    });
-}
-/**
- * Re-points the engine-side registrations (customElements.js, jar.mn, and
- * the localized `.ftl` entries) from the old tag name to the new one.
- *
- * @param options - See {@link UpdateEngineRegistrationsOptions}
- */
-async function updateEngineRegistrations(options) {
-    const { engineDir, oldName, newName, newDir, ftlDir, isLocalized, journal } = options;
-    const customElementsPath = join(engineDir, 'toolkit/content/customElements.js');
-    const jarMnPath = join(engineDir, 'toolkit/content/jar.mn');
-    if (await pathExists(customElementsPath)) {
-        await snapshotFile(journal, customElementsPath);
-        await removeCustomElementRegistration(engineDir, oldName);
-        await addCustomElementRegistration(engineDir, newName, `chrome://global/content/elements/${newName}.mjs`);
-    }
-    if (await pathExists(jarMnPath)) {
-        await snapshotFile(journal, jarMnPath);
-        await removeJarMnEntries(engineDir, oldName);
-        const files = (await readdir(newDir, { withFileTypes: true }))
-            .filter((e) => e.isFile() && (e.name.endsWith('.mjs') || e.name.endsWith('.css')))
-            .map((e) => e.name);
-        if (files.length > 0) {
-            await addJarMnEntries(engineDir, newName, files);
-        }
-    }
-    // Rename FTL localization files in the engine locale directory
-    const ftlDirPath = join(engineDir, ftlDir);
-    const oldFtlPath = join(ftlDirPath, `${oldName}.ftl`);
-    const newFtlPath = join(ftlDirPath, `${newName}.ftl`);
-    if (await pathExists(oldFtlPath)) {
-        await snapshotFile(journal, oldFtlPath);
-        await snapshotFile(journal, newFtlPath);
-        const ftlContent = await readText(oldFtlPath);
-        await writeText(newFtlPath, ftlContent);
-        await removeFile(oldFtlPath);
-    }
-    // Re-wire the locale jar.mn chrome registration when the component is
-    // localized. `updateEngineRegistrations` renames the .ftl file on disk but
-    // leaves the locale jar.mn pointing at `locale/.../${oldName}.ftl`, so
-    // `furnace validate` passes while the engine still carries a stale
-    // registration for the now-missing file.
-    if (isLocalized) {
-        const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
-        const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
-        if (chromeSubPath !== undefined && localeJarRel !== undefined) {
-            const localeJarAbs = join(engineDir, localeJarRel);
-            if (await pathExists(localeJarAbs)) {
-                await snapshotFile(journal, localeJarAbs);
-                await removeLocaleFtlJarMnEntry(engineDir, localeJarRel, oldName, chromeSubPath);
-                await addLocaleFtlJarMnEntry(engineDir, localeJarRel, newName, chromeSubPath);
-            }
-        }
-    }
+    };
+    await runFurnaceMutation(projectRoot, 'rename-rollback', mutate, waitLockMutationOptions(args.waitLockSeconds));
 }
 /**
  * Renames a custom or override component atomically: updates directory name,
  * file names, file contents, furnace.json, and engine registrations.
  */
-export async function furnaceRenameCommand(projectRoot, oldName, newName) {
-    intro('Furnace Rename');
+export async function furnaceRenameCommand(projectRoot, oldName, newName, options = {}) {
+    intro(options.dryRun ? 'Furnace Rename (dry run)' : 'Furnace Rename');
     if (!CUSTOM_ELEMENT_TAG_PATTERN.test(oldName)) {
         throw new InvalidArgumentError(`Invalid source name "${oldName}": ${CUSTOM_ELEMENT_TAG_RULES}`, 'old-name');
     }
@@ -419,6 +367,19 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
     if (await pathExists(newDir)) {
         throw new FurnaceError(`Target directory already exists: components/${componentDirLabel}/${newName}`, newName);
     }
+    if (options.dryRun) {
+        note(await renderRenamePlan({
+            config,
+            oldName,
+            newName,
+            oldDir,
+            componentDirLabel,
+            engineDir: paths.engine,
+            markerComment: await loadMarkerComment(projectRoot),
+        }), `${oldName} → ${newName}`);
+        outro('Dry run complete (no files modified)');
+        return;
+    }
     await performRenameMutations({
         projectRoot,
         oldName,
@@ -427,6 +388,7 @@ export async function furnaceRenameCommand(projectRoot, oldName, newName) {
         furnaceConfigPath: furnacePaths.furnaceConfig,
         furnacePaths,
         engineDir: paths.engine,
+        waitLockSeconds: options.waitLockSeconds,
     });
     note(`Component renamed: ${oldName} → ${newName}\n\n` +
         `Directory: components/${componentDirLabel}/${newName}/\n\n` +

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

@@ -1,9 +1,14 @@
+import type { FurnaceLockWaitable } from '../../types/commands/index.js';
+/** Options for `furnace scan`. */
+export interface FurnaceScanOptions extends FurnaceLockWaitable {
+    /** Search additional Firefox directories beyond the default widgets path. */
+    deep?: boolean;
+    /** Persist every untracked component into furnace.json's stock section. */
+    track?: boolean;
+}
 /**
  * Runs the furnace scan command to discover MozLitElement components.
  * @param projectRoot - Root directory of the project
  * @param options - Scan options
  */
-export declare function furnaceScanCommand(projectRoot: string, options?: {
-    deep?: boolean;
-    track?: boolean;
-}): Promise<void>;
+export declare function furnaceScanCommand(projectRoot: string, options?: FurnaceScanOptions): Promise<void>;

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

@@ -2,7 +2,7 @@
 import { confirm, multiselect, select } from '@clack/prompts';
 import { stdioIsInteractive } from '../../core/destructive.js';
 import { ensureFurnaceConfig, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
-import { completeJournalRollback, runFurnaceMutation } from '../../core/furnace-operation.js';
+import { completeJournalRollback, runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
 import { createRollbackJournal, snapshotFile } from '../../core/furnace-rollback.js';
 import { DEEP_SCAN_PATHS, scanWidgetsDirectory } from '../../core/furnace-scanner.js';
@@ -13,8 +13,9 @@ import { furnaceOverrideCommand } from './override.js';
  * @param components - Components discovered in the engine scan
  * @param tracked - Existing Furnace tracking map keyed by tag name
  * @param projectRoot - Root directory of the project
+ * @param waitLockSeconds - Resolved `--wait-lock` budget for the furnace lock
  */
-async function promptAddComponents(components, tracked, projectRoot) {
+async function promptAddComponents(components, tracked, projectRoot, waitLockSeconds) {
     const untrackedComponents = components.filter((c) => !tracked.has(c.tagName));
     const shouldAdd = await confirm({ message: 'Add components to furnace.json?' });
     if (isCancel(shouldAdd) || !shouldAdd) {
@@ -36,7 +37,7 @@ async function promptAddComponents(components, tracked, projectRoot) {
         outro('Scan complete');
         return;
     }
-    await persistStockComponents(projectRoot, selected);
+    await persistStockComponents(projectRoot, selected, waitLockSeconds);
     const addedNames = selected;
     success(`Added ${addedNames.length} component${addedNames.length === 1 ? '' : 's'} to furnace.json`);
     // Offer to immediately override one of the just-added stock components.
@@ -54,7 +55,7 @@ async function promptAddComponents(components, tracked, projectRoot) {
         cancel('Cancelled');
         return;
     }
-    await furnaceOverrideCommand(projectRoot, overrideTarget);
+    await furnaceOverrideCommand(projectRoot, overrideTarget, waitLockSeconds !== undefined ? { waitLockSeconds } : {});
 }
 /**
  * Persists discovered component tag names into the `stock` section of
@@ -69,8 +70,8 @@ async function promptAddComponents(components, tracked, projectRoot) {
  * auto-created cleans up after itself instead of leaving an unwanted default
  * config behind.
  */
-async function persistStockComponents(projectRoot, names) {
-    await runFurnaceMutation(projectRoot, 'scan-rollback', async (ctx) => {
+async function persistStockComponents(projectRoot, names, waitLockSeconds) {
+    const mutate = async (ctx) => {
         const journal = createRollbackJournal();
         ctx.registerJournal(journal);
         const furnacePaths = getFurnacePaths(projectRoot);
@@ -96,7 +97,8 @@ async function persistStockComponents(projectRoot, names) {
                 subject: `furnace.json update during scan`,
             });
         }
-    });
+    };
+    await runFurnaceMutation(projectRoot, 'scan-rollback', mutate, waitLockMutationOptions(waitLockSeconds));
 }
 /**
  * Renders a component's discovered capabilities as a display suffix. Shared
@@ -172,14 +174,14 @@ export async function furnaceScanCommand(projectRoot, options = {}) {
             return;
         }
         const untrackedNames = untrackedComponentList.map((c) => c.tagName);
-        await persistStockComponents(projectRoot, untrackedNames);
+        await persistStockComponents(projectRoot, untrackedNames, options.waitLockSeconds);
         success(`Tracked ${untrackedNames.length} component${untrackedNames.length === 1 ? '' : 's'} in the stock section of furnace.json`);
         outro('Scan complete');
         return;
     }
     const isInteractive = stdioIsInteractive();
     if (isInteractive && untrackedCount > 0) {
-        await promptAddComponents(components, tracked, projectRoot);
+        await promptAddComponents(components, tracked, projectRoot, options.waitLockSeconds);
         return;
     }
     if (untrackedCount > 0) {

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

@@ -3,7 +3,7 @@ import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
 import { applyAllComponents } from '../../core/furnace-apply.js';
-import { logApplyResult } from '../../core/furnace-apply-output.js';
+import { formatSkipBreakdown, logApplyResult } from '../../core/furnace-apply-output.js';
 import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
 import { runFurnaceMutation, waitLockMutationOptions } from '../../core/furnace-operation.js';
@@ -136,7 +136,8 @@ export async function furnaceSyncCommand(projectRoot, options = {}) {
             throw new FurnaceError(`${totalFailures} component${totalFailures === 1 ? '' : 's'} failed to apply cleanly`);
         }
         await reportJsconfigPathsSync(projectRoot, config, false);
-        outro(`Sync complete — ${result.applied.length} applied, ${result.skipped.length} skipped`);
+        outro(`Sync complete — ${result.applied.length} applied, ${result.skipped.length} skipped` +
+            formatSkipBreakdown(result.skipped));
     }
     else {
         outro('Dry run complete');

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>;