design-constraint-validator 1.0.0 → 1.1.0

package/cli/commands/utils.ts

@@ -1,50 +1,50 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
-import { valuesToCss } from '../../adapters/css.js';
-import type { TokenNode, TokenValue } from '../../core/flatten.js';
-
-// Shared helpers for command modules
-
-export function loadTokens(tokensPath: string): TokenNode {
-  const resolvedPath = resolve(tokensPath);
-  if (!existsSync(resolvedPath)) {
-    throw new Error(`Token file not found: ${resolvedPath}`);
-  }
-  const data = JSON.parse(readFileSync(resolvedPath, 'utf8'));
-  if (typeof data !== 'object' || data === null) {
-    throw new Error(`Invalid token file: expected object, got ${typeof data}`);
-  }
-  return data as TokenNode;
-}
-
-export function outputResult(data: unknown, format: string, outputPath?: string): void {
-  let content: string;
-  switch (format) {
-    case 'json':
-      content = JSON.stringify(data, null, 2);
-      break;
-    case 'css': {
-      if (data && typeof data === 'object' && 'patch' in (data as { patch?: unknown })) {
-        const patch = (data as { patch: Record<string, TokenValue> }).patch;
-        content = valuesToCss(patch);
-      } else if (data && typeof data === 'object') {
-        content = valuesToCss(data as Record<string, TokenValue>);
-      } else {
-        content = valuesToCss({});
-      }
-      break; }
-    case 'js':
-      content = `export default ${JSON.stringify(data, null, 2)};`;
-      break;
-    default:
-      content = JSON.stringify(data, null, 2);
-  }
-  if (outputPath) {
-    const dir = dirname(outputPath);
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(outputPath, content, 'utf8');
-    console.log(`Output written to: ${outputPath}`);
-  } else {
-    console.log(content);
-  }
-}
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { valuesToCss } from '../../adapters/css.js';
+import type { TokenNode, TokenValue } from '../../core/flatten.js';
+
+// Shared helpers for command modules
+
+export function loadTokens(tokensPath: string): TokenNode {
+  const resolvedPath = resolve(tokensPath);
+  if (!existsSync(resolvedPath)) {
+    throw new Error(`Token file not found: ${resolvedPath}`);
+  }
+  const data = JSON.parse(readFileSync(resolvedPath, 'utf8'));
+  if (typeof data !== 'object' || data === null) {
+    throw new Error(`Invalid token file: expected object, got ${typeof data}`);
+  }
+  return data as TokenNode;
+}
+
+export function outputResult(data: unknown, format: string, outputPath?: string): void {
+  let content: string;
+  switch (format) {
+    case 'json':
+      content = JSON.stringify(data, null, 2);
+      break;
+    case 'css': {
+      if (data && typeof data === 'object' && 'patch' in (data as { patch?: unknown })) {
+        const patch = (data as { patch: Record<string, TokenValue> }).patch;
+        content = valuesToCss(patch);
+      } else if (data && typeof data === 'object') {
+        content = valuesToCss(data as Record<string, TokenValue>);
+      } else {
+        content = valuesToCss({});
+      }
+      break; }
+    case 'js':
+      content = `export default ${JSON.stringify(data, null, 2)};`;
+      break;
+    default:
+      content = JSON.stringify(data, null, 2);
+  }
+  if (outputPath) {
+    const dir = dirname(outputPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(outputPath, content, 'utf8');
+    console.log(`Output written to: ${outputPath}`);
+  } else {
+    console.log(content);
+  }
+}

package/cli/commands/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["validate.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA0G9E"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["validate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAMnD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoK9E"}

package/cli/commands/validate.js

@@ -1,8 +1,11 @@
 import { flattenTokens } from '../../core/flatten.js';
-import { createValidationEngine } from '../engine-helpers.js';
+import { Engine } from '../../core/engine.js';
 import { loadConfig } from '../config.js';
-import { parseBreakpoints, loadTokensWithBreakpoint } from '../../core/breakpoints.js';
-import { loadCrossAxisPlugin } from '../../core/cross-axis-config.js';
+import { parseBreakpoints, loadTokensWithBreakpoint, mergeTokens } from '../../core/breakpoints.js';
+import { createValidationResult, createValidationReceipt, writeJsonOutput } from '../json-output.js';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { setupConstraints } from '../constraint-registry.js';
 export async function validateCommand(_options) {
     try {
         const bps = parseBreakpoints(process.argv);
@@ -13,9 +16,13 @@ export async function validateCommand(_options) {
         let totalWarnings = 0;
         const argv = process.argv.slice(2);
         const failOnIdx = argv.indexOf('--fail-on');
-        const failOn = failOnIdx >= 0 ? argv[failOnIdx + 1] : 'error';
+        const failOn = _options.failOn ?? (failOnIdx >= 0 ? argv[failOnIdx + 1] : 'error');
         const sumIdx = argv.indexOf('--summary');
-        const summaryFmt = sumIdx >= 0 ? argv[sumIdx + 1] : 'none';
+        const summaryFmt = _options.summary ?? (sumIdx >= 0 ? argv[sumIdx + 1] : 'none');
+        const outputFormat = _options.format ?? 'text';
+        // Collect all issues for JSON output
+        const allErrors = [];
+        const allWarnings = [];
         const rows = [];
         function pushRow(bpLabel, stats) { rows.push({ bp: bpLabel, ...stats }); }
         function printSummaryTable(rs) {
@@ -45,19 +52,31 @@ export async function validateCommand(_options) {
         const tStartTotal = globalThis.performance.now();
         for (const bp of plan) {
             const tStart = globalThis.performance.now();
-            const tokens = loadTokensWithBreakpoint(bp);
-            const engine = createValidationEngine(tokens, bp, config);
-            const initIds = Object.keys(flattenTokens(tokens).flat).reduce((a, k) => { a[k] = true; return a; }, {});
-            const knownIds = new Set(Object.keys(initIds));
-            // Load global + bp-specific cross-axis rules (bp file optional)
-            engine.use(loadCrossAxisPlugin('themes/cross-axis.rules.json', bp, { debug: crossAxisDebug, knownIds }));
-            if (bp) {
-                const bpRulesPath = `themes/cross-axis.${bp}.rules.json`;
-                engine.use(loadCrossAxisPlugin(bpRulesPath, bp, { debug: crossAxisDebug, knownIds }));
+            let tokens = loadTokensWithBreakpoint(bp);
+            // Optional theme overlay (tokens/themes/<name>.json), mirroring build behavior
+            if (_options.theme) {
+                const themePath = join('tokens/themes', `${_options.theme}.json`);
+                if (existsSync(themePath)) {
+                    try {
+                        const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
+                        tokens = mergeTokens(tokens, themeTokens);
+                    }
+                    catch {
+                        // If theme file is invalid JSON, ignore and proceed with base tokens
+                    }
+                }
+            }
+            // Create engine with flattened tokens
+            const { flat, edges } = flattenTokens(tokens);
+            const init = {};
+            for (const t of Object.values(flat)) {
+                init[t.id] = t.value;
             }
-            const { ThresholdPlugin } = await import('../../core/constraints/threshold.js');
-            engine.use(ThresholdPlugin([{ id: 'control.size.min', op: '>=', valuePx: 44, where: 'Touch target (WCAG / Apple HIG)' }]));
-            const allIds = new Set(Object.keys(initIds));
+            const engine = new Engine(init, edges);
+            const knownIds = new Set(Object.keys(init));
+            // Discover and attach all constraints via centralized registry
+            setupConstraints(engine, { config, bp, constraintsDir: 'themes' }, { knownIds, crossAxisDebug });
+            const allIds = new Set(Object.keys(init));
             const issues = engine.evaluate(allIds);
             const errs = issues.filter((i) => i.level === 'error');
             const warns = issues.filter((i) => i.level !== 'error');
@@ -65,14 +84,20 @@ export async function validateCommand(_options) {
                 anyErrors = true;
             totalErrors += errs.length;
             totalWarnings += warns.length;
+            // Collect for JSON output
+            allErrors.push(...errs);
+            allWarnings.push(...warns);
             const rulesEvaluated = errs.length + warns.length;
             pushRow(bp ?? 'global', { rules: rulesEvaluated, warnings: warns.length, errors: errs.length });
             const dur = globalThis.performance.now() - tStart;
             perBpTimings.push({ bp: bp ?? 'global', ms: dur });
-            console.log(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
-            for (const it of issues) {
-                const tag = it.level === 'error' ? 'ERROR' : 'WARN ';
-                console.log(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`);
+            // Only print text output if not in JSON mode
+            if (outputFormat !== 'json') {
+                console.log(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
+                for (const it of issues) {
+                    const tag = it.level === 'error' ? 'ERROR' : 'WARN ';
+                    console.log(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`);
+                }
             }
         }
         const totalMs = globalThis.performance.now() - tStartTotal;
@@ -81,20 +106,48 @@ export async function validateCommand(_options) {
             const agg = rows.reduce((a, b) => ({ rules: a.rules + b.rules, warnings: a.warnings + b.warnings, errors: a.errors + b.errors }), { rules: 0, warnings: 0, errors: 0 });
             rows.push({ bp: 'TOTAL', ...agg });
         }
-        if (_options.perf) {
-            console.log('[perf] per-breakpoint timings:');
-            for (const t of perBpTimings)
-                console.log(`  ${t.bp}: ${t.ms.toFixed(2)}ms`);
-            console.log(`[perf] total: ${totalMs.toFixed(2)}ms`);
+        // Get package version for stats
+        let engineVersion = '1.0.0';
+        try {
+            // eslint-disable-next-line no-undef
+            const pkgPath = new URL('../../package.json', import.meta.url);
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            engineVersion = pkg.version;
         }
-        if (summaryFmt === 'json') {
-            // Provide machine-readable aggregate separate from rows if TOTAL present
-            const totalRow = rows.find(r => r.bp === 'TOTAL');
-            const json = totalRow ? { rows, total: { rules: totalRow.rules, warnings: totalRow.warnings, errors: totalRow.errors } } : { rows };
-            console.log(JSON.stringify(json, null, 2));
+        catch {
+            // Ignore package.json read errors, use default version
         }
-        else if (summaryFmt === 'table') {
-            printSummaryTable(rows);
+        // Handle JSON output mode
+        if (outputFormat === 'json') {
+            const result = createValidationResult(allErrors, allWarnings, totalMs, engineVersion);
+            // If receipt requested, generate full receipt
+            if (_options.receipt) {
+                const tokensFile = _options.tokens ?? 'tokens/tokens.example.json';
+                const constraintsDir = 'themes';
+                const receipt = createValidationReceipt(result, tokensFile, constraintsDir, bps[0], failOn);
+                writeJsonOutput(receipt, _options.receipt);
+            }
+            else {
+                writeJsonOutput(result, _options.output);
+            }
+        }
+        else {
+            // Text output mode
+            if (_options.perf) {
+                console.log('[perf] per-breakpoint timings:');
+                for (const t of perBpTimings)
+                    console.log(`  ${t.bp}: ${t.ms.toFixed(2)}ms`);
+                console.log(`[perf] total: ${totalMs.toFixed(2)}ms`);
+            }
+            if (summaryFmt === 'json') {
+                // Provide machine-readable aggregate separate from rows if TOTAL present
+                const totalRow = rows.find(r => r.bp === 'TOTAL');
+                const json = totalRow ? { rows, total: { rules: totalRow.rules, warnings: totalRow.warnings, errors: totalRow.errors } } : { rows };
+                console.log(JSON.stringify(json, null, 2));
+            }
+            else if (summaryFmt === 'table') {
+                printSummaryTable(rows);
+            }
         }
         let code = anyErrors ? 1 : 0;
         // Budget checks (do not override fail-on semantics unless budgets add failures)

package/cli/commands/validate.ts

@@ -1,115 +1,176 @@
-import { flattenTokens } from '../../core/flatten.js';
-import { createValidationEngine } from '../engine-helpers.js';
-import { loadConfig } from '../config.js';
-import { parseBreakpoints, loadTokensWithBreakpoint, type Breakpoint } from '../../core/breakpoints.js';
-import { loadCrossAxisPlugin } from '../../core/cross-axis-config.js';
-import type { ConstraintIssue } from '../../core/engine.js';
-import type { ValidateOptions } from '../types.js';
-
-export async function validateCommand(_options: ValidateOptions): Promise<void> {
-  try {
-    const bps = parseBreakpoints(process.argv);
-    const crossAxisDebug = process.argv.includes('--cross-axis-debug');
-    const plan: (Breakpoint | undefined)[] = bps.length ? bps : [undefined];
-    let anyErrors = false; let totalErrors = 0; let totalWarnings = 0;
-    const argv = process.argv.slice(2);
-    const failOnIdx = argv.indexOf('--fail-on');
-    type FailOn = 'off' | 'warn' | 'error';
-    const failOn: FailOn = failOnIdx >= 0 ? (argv[failOnIdx + 1] as FailOn) : 'error';
-    const sumIdx = argv.indexOf('--summary');
-    type SummaryFmt = 'table' | 'json' | 'none';
-    const summaryFmt: SummaryFmt = sumIdx >= 0 ? (argv[sumIdx + 1] as SummaryFmt) : 'none';
-    type VRow = { bp: string; rules: number; warnings: number; errors: number };
-    const rows: VRow[] = [];
-    function pushRow(bpLabel: string, stats: { rules: number; warnings: number; errors: number }) { rows.push({ bp: bpLabel, ...stats }); }
-    function printSummaryTable(rs: VRow[]) {
-      if (!rs.length) return;
-      const showTotalLine = !rs.some(r => r.bp === 'TOTAL');
-      const cols = ['scope','rules','warnings','errors'] as const;
-      const data = rs.map(r => ({ scope: r.bp, rules: String(r.rules), warnings: String(r.warnings), errors: String(r.errors) }));
-      const widths = cols.map(c => Math.max(c.length, ...data.map(d => d[c].length)));
-      const line = (vals: string[]) => vals.map((v,i)=>v.padEnd(widths[i])).join('  ');
-      console.log(line(cols as unknown as string[]));
-      console.log(line(widths.map(w => '-'.repeat(w))));
-      for (const d of data) console.log(line(cols.map(c => d[c])));
-      if (showTotalLine && rs.length > 1) {
-        const tot = rs.reduce((a,b)=>({ rules:a.rules+b.rules, warnings:a.warnings+b.warnings, errors:a.errors+b.errors }), { rules:0,warnings:0,errors:0 });
-        console.log(line(['TOTAL', String(tot.rules), String(tot.warnings), String(tot.errors)]));
-      }
-    }
-    const cfgRes = loadConfig(_options.config);
-    if (!cfgRes.ok) { console.error(cfgRes.error); process.exit(2); }
-    const config = cfgRes.value;
-    const perBpTimings: Array<{ bp: string; ms: number }> = [];
-    const tStartTotal = globalThis.performance.now();
-    for (const bp of plan) {
-      const tStart = globalThis.performance.now();
-      const tokens = loadTokensWithBreakpoint(bp);
-      const engine = createValidationEngine(tokens, bp, config);
-      const initIds = Object.keys(flattenTokens(tokens).flat).reduce<Record<string, true>>((a,k)=>{a[k]=true;return a;},{});
-      const knownIds = new Set(Object.keys(initIds));
-      // Load global + bp-specific cross-axis rules (bp file optional)
-      engine.use(loadCrossAxisPlugin('themes/cross-axis.rules.json', bp, { debug: crossAxisDebug, knownIds }));
-      if (bp) {
-        const bpRulesPath = `themes/cross-axis.${bp}.rules.json`;
-        engine.use(loadCrossAxisPlugin(bpRulesPath, bp, { debug: crossAxisDebug, knownIds }));
-      }
-      const { ThresholdPlugin } = await import('../../core/constraints/threshold.js');
-      engine.use(ThresholdPlugin([{ id: 'control.size.min', op: '>=', valuePx: 44, where: 'Touch target (WCAG / Apple HIG)' }]));
-      const allIds = new Set(Object.keys(initIds));
-      const issues = engine.evaluate(allIds);
-      const errs = issues.filter((i: ConstraintIssue) => i.level === 'error');
-      const warns = issues.filter((i: ConstraintIssue) => i.level !== 'error');
-      if (errs.length) anyErrors = true;
-      totalErrors += errs.length; totalWarnings += warns.length;
-      const rulesEvaluated = errs.length + warns.length; pushRow(bp ?? 'global', { rules: rulesEvaluated, warnings: warns.length, errors: errs.length });
-      const dur = globalThis.performance.now() - tStart;
-      perBpTimings.push({ bp: bp ?? 'global', ms: dur });
-      console.log(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
-      for (const it of issues) { const tag = it.level === 'error' ? 'ERROR' : 'WARN '; console.log(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`); }
-    }
-    const totalMs = globalThis.performance.now() - tStartTotal;
-    // Append aggregate total row if multiple scopes and not already added
-    if (rows.length > 1) {
-      const agg = rows.reduce((a,b)=>({ rules:a.rules+b.rules, warnings:a.warnings+b.warnings, errors:a.errors+b.errors }), { rules:0,warnings:0,errors:0 });
-      rows.push({ bp: 'TOTAL', ...agg });
-    }
-    if (_options.perf) {
-      console.log('[perf] per-breakpoint timings:');
-      for (const t of perBpTimings) console.log(`  ${t.bp}: ${t.ms.toFixed(2)}ms`);
-      console.log(`[perf] total: ${totalMs.toFixed(2)}ms`);
-    }
-    if (summaryFmt === 'json') {
-      // Provide machine-readable aggregate separate from rows if TOTAL present
-      const totalRow = rows.find(r => r.bp === 'TOTAL');
-      const json = totalRow ? { rows, total: { rules: totalRow.rules, warnings: totalRow.warnings, errors: totalRow.errors } } : { rows };
-      console.log(JSON.stringify(json, null, 2));
-    } else if (summaryFmt === 'table') {
-      printSummaryTable(rows);
-    }
-    let code = anyErrors ? 1 : 0;
-    // Budget checks (do not override fail-on semantics unless budgets add failures)
-    const budgetTotal = (_options as any)['budget-total-ms'] ?? _options.budgetTotalMs;
-    const budgetPerBp = (_options as any)['budget-per-bp-ms'] ?? _options.budgetPerBpMs;
-    let budgetFailed = false;
-    if (budgetTotal != null && totalMs > budgetTotal) {
-      console.error(`[perf] total time ${totalMs.toFixed(2)}ms exceeded budget ${budgetTotal}ms`);
-      budgetFailed = true;
-    }
-    if (budgetPerBp != null) {
-      for (const t of perBpTimings) {
-        if (t.ms > budgetPerBp) {
-          console.error(`[perf] ${t.bp} time ${t.ms.toFixed(2)}ms exceeded per-breakpoint budget ${budgetPerBp}ms`);
-          budgetFailed = true;
-        }
-      }
-    }
-    if (failOn === 'off') code = 0; else if (failOn === 'warn') code = (totalErrors + totalWarnings) > 0 ? 1 : 0; else code = totalErrors > 0 ? 1 : 0;
-    if (budgetFailed) code = Math.max(code, 1);
-    process.exit(code);
-  } catch (e) {
-    const msg = e instanceof Error ? e.message : String(e);
-    console.error('validate: failed:', msg);
-    process.exit(2);
-  }
-}
+import { flattenTokens, type TokenNode, type FlatToken } from '../../core/flatten.js';
+import { Engine } from '../../core/engine.js';
+import { loadConfig } from '../config.js';
+import { parseBreakpoints, loadTokensWithBreakpoint, mergeTokens, type Breakpoint } from '../../core/breakpoints.js';
+import type { ConstraintIssue } from '../../core/engine.js';
+import type { ValidateOptions } from '../types.js';
+import { createValidationResult, createValidationReceipt, writeJsonOutput } from '../json-output.js';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { setupConstraints } from '../constraint-registry.js';
+
+export async function validateCommand(_options: ValidateOptions): Promise<void> {
+  try {
+    const bps = parseBreakpoints(process.argv);
+    const crossAxisDebug = process.argv.includes('--cross-axis-debug');
+    const plan: (Breakpoint | undefined)[] = bps.length ? bps : [undefined];
+    let anyErrors = false; let totalErrors = 0; let totalWarnings = 0;
+    const argv = process.argv.slice(2);
+    const failOnIdx = argv.indexOf('--fail-on');
+    type FailOn = 'off' | 'warn' | 'error';
+    const failOn: FailOn = _options.failOn ?? (failOnIdx >= 0 ? (argv[failOnIdx + 1] as FailOn) : 'error');
+    const sumIdx = argv.indexOf('--summary');
+    type SummaryFmt = 'table' | 'json' | 'none';
+    const summaryFmt: SummaryFmt = _options.summary ?? (sumIdx >= 0 ? (argv[sumIdx + 1] as SummaryFmt) : 'none');
+    const outputFormat = _options.format ?? 'text';
+    
+    // Collect all issues for JSON output
+    const allErrors: ConstraintIssue[] = [];
+    const allWarnings: ConstraintIssue[] = [];
+    type VRow = { bp: string; rules: number; warnings: number; errors: number };
+    const rows: VRow[] = [];
+    function pushRow(bpLabel: string, stats: { rules: number; warnings: number; errors: number }) { rows.push({ bp: bpLabel, ...stats }); }
+    function printSummaryTable(rs: VRow[]) {
+      if (!rs.length) return;
+      const showTotalLine = !rs.some(r => r.bp === 'TOTAL');
+      const cols = ['scope','rules','warnings','errors'] as const;
+      const data = rs.map(r => ({ scope: r.bp, rules: String(r.rules), warnings: String(r.warnings), errors: String(r.errors) }));
+      const widths = cols.map(c => Math.max(c.length, ...data.map(d => d[c].length)));
+      const line = (vals: string[]) => vals.map((v,i)=>v.padEnd(widths[i])).join('  ');
+      console.log(line(cols as unknown as string[]));
+      console.log(line(widths.map(w => '-'.repeat(w))));
+      for (const d of data) console.log(line(cols.map(c => d[c])));
+      if (showTotalLine && rs.length > 1) {
+        const tot = rs.reduce((a,b)=>({ rules:a.rules+b.rules, warnings:a.warnings+b.warnings, errors:a.errors+b.errors }), { rules:0,warnings:0,errors:0 });
+        console.log(line(['TOTAL', String(tot.rules), String(tot.warnings), String(tot.errors)]));
+      }
+    }
+    const cfgRes = loadConfig(_options.config);
+    if (!cfgRes.ok) { console.error(cfgRes.error); process.exit(2); }
+    const config = cfgRes.value;
+    const perBpTimings: Array<{ bp: string; ms: number }> = [];
+    const tStartTotal = globalThis.performance.now();
+    for (const bp of plan) {
+      const tStart = globalThis.performance.now();
+      let tokens: TokenNode = loadTokensWithBreakpoint(bp);
+      // Optional theme overlay (tokens/themes/<name>.json), mirroring build behavior
+      if (_options.theme) {
+        const themePath = join('tokens/themes', `${_options.theme}.json`);
+        if (existsSync(themePath)) {
+          try {
+            const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
+            tokens = mergeTokens(tokens, themeTokens);
+          } catch {
+            // If theme file is invalid JSON, ignore and proceed with base tokens
+          }
+        }
+      }
+      // Create engine with flattened tokens
+      const { flat, edges } = flattenTokens(tokens);
+      const init: Record<string, string | number> = {};
+      for (const t of Object.values(flat)) {
+        init[(t as FlatToken).id] = (t as FlatToken).value;
+      }
+      const engine = new Engine(init, edges);
+      const knownIds = new Set(Object.keys(init));
+
+      // Discover and attach all constraints via centralized registry
+      setupConstraints(
+        engine,
+        { config, bp, constraintsDir: 'themes' },
+        { knownIds, crossAxisDebug },
+      );
+
+      const allIds = new Set(Object.keys(init));
+      const issues = engine.evaluate(allIds);
+      const errs = issues.filter((i: ConstraintIssue) => i.level === 'error');
+      const warns = issues.filter((i: ConstraintIssue) => i.level !== 'error');
+      if (errs.length) anyErrors = true;
+      totalErrors += errs.length; totalWarnings += warns.length;
+      
+      // Collect for JSON output
+      allErrors.push(...errs);
+      allWarnings.push(...warns);
+      
+      const rulesEvaluated = errs.length + warns.length; pushRow(bp ?? 'global', { rules: rulesEvaluated, warnings: warns.length, errors: errs.length });
+      const dur = globalThis.performance.now() - tStart;
+      perBpTimings.push({ bp: bp ?? 'global', ms: dur });
+      
+      // Only print text output if not in JSON mode
+      if (outputFormat !== 'json') {
+        console.log(`validate${bp ? ` [bp=${bp}]` : ''}: ${errs.length} error(s), ${warns.length} warning(s)${_options.perf ? ` (${dur.toFixed(2)}ms)` : ''}`);
+        for (const it of issues) { const tag = it.level === 'error' ? 'ERROR' : 'WARN '; console.log(`${tag} ${it.rule}  ${it.id}${it.where ? ' @ ' + it.where : ''}${bp ? ` [${bp}]` : ''} — ${it.message}`); }
+      }
+    }
+    const totalMs = globalThis.performance.now() - tStartTotal;
+    // Append aggregate total row if multiple scopes and not already added
+    if (rows.length > 1) {
+      const agg = rows.reduce((a,b)=>({ rules:a.rules+b.rules, warnings:a.warnings+b.warnings, errors:a.errors+b.errors }), { rules:0,warnings:0,errors:0 });
+      rows.push({ bp: 'TOTAL', ...agg });
+    }
+    // Get package version for stats
+    let engineVersion = '1.0.0';
+    try {
+      // eslint-disable-next-line no-undef
+      const pkgPath = new URL('../../package.json', import.meta.url);
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      engineVersion = pkg.version;
+    } catch {
+      // Ignore package.json read errors, use default version
+    }
+    
+    // Handle JSON output mode
+    if (outputFormat === 'json') {
+      const result = createValidationResult(allErrors, allWarnings, totalMs, engineVersion);
+      
+      // If receipt requested, generate full receipt
+      if (_options.receipt) {
+        const tokensFile = _options.tokens ?? 'tokens/tokens.example.json';
+        const constraintsDir = 'themes';
+        const receipt = createValidationReceipt(result, tokensFile, constraintsDir, bps[0], failOn);
+        writeJsonOutput(receipt, _options.receipt);
+      } else {
+        writeJsonOutput(result, _options.output);
+      }
+    } else {
+      // Text output mode
+      if (_options.perf) {
+        console.log('[perf] per-breakpoint timings:');
+        for (const t of perBpTimings) console.log(`  ${t.bp}: ${t.ms.toFixed(2)}ms`);
+        console.log(`[perf] total: ${totalMs.toFixed(2)}ms`);
+      }
+      if (summaryFmt === 'json') {
+        // Provide machine-readable aggregate separate from rows if TOTAL present
+        const totalRow = rows.find(r => r.bp === 'TOTAL');
+        const json = totalRow ? { rows, total: { rules: totalRow.rules, warnings: totalRow.warnings, errors: totalRow.errors } } : { rows };
+        console.log(JSON.stringify(json, null, 2));
+      } else if (summaryFmt === 'table') {
+        printSummaryTable(rows);
+      }
+    }
+    let code = anyErrors ? 1 : 0;
+    // Budget checks (do not override fail-on semantics unless budgets add failures)
+    const budgetTotal = (_options as any)['budget-total-ms'] ?? _options.budgetTotalMs;
+    const budgetPerBp = (_options as any)['budget-per-bp-ms'] ?? _options.budgetPerBpMs;
+    let budgetFailed = false;
+    if (budgetTotal != null && totalMs > budgetTotal) {
+      console.error(`[perf] total time ${totalMs.toFixed(2)}ms exceeded budget ${budgetTotal}ms`);
+      budgetFailed = true;
+    }
+    if (budgetPerBp != null) {
+      for (const t of perBpTimings) {
+        if (t.ms > budgetPerBp) {
+          console.error(`[perf] ${t.bp} time ${t.ms.toFixed(2)}ms exceeded per-breakpoint budget ${budgetPerBp}ms`);
+          budgetFailed = true;
+        }
+      }
+    }
+    if (failOn === 'off') code = 0; else if (failOn === 'warn') code = (totalErrors + totalWarnings) > 0 ? 1 : 0; else code = totalErrors > 0 ? 1 : 0;
+    if (budgetFailed) code = Math.max(code, 1);
+    process.exit(code);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error('validate: failed:', msg);
+    process.exit(2);
+  }
+}

package/cli/commands/why.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCnE"}
+{"version":3,"file":"why.d.ts","sourceRoot":"","sources":["why.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJnE"}