design-constraint-validator 1.0.0 → 2.0.1

package/cli/commands/validate.js

@@ -1,9 +1,15 @@
 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';
+import { printVersionBanner } from '../version-banner.js';
 export async function validateCommand(_options) {
+    // Show version banner (subtle, dimmed)
+    printVersionBanner({ quiet: _options.format === 'json' });
     try {
         const bps = parseBreakpoints(process.argv);
         const crossAxisDebug = process.argv.includes('--cross-axis-debug');
@@ -13,9 +19,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 +55,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 +87,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 +109,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,180 @@
-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';
+import { printVersionBanner } from '../version-banner.js';
+
+export async function validateCommand(_options: ValidateOptions): Promise<void> {
+  // Show version banner (subtle, dimmed)
+  printVersionBanner({ quiet: _options.format === 'json' });
+
+  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"}

package/cli/commands/why.js

@@ -2,61 +2,127 @@ import { readFileSync } from 'node:fs';
 import { flattenTokens } from '../../core/flatten.js';
 import { explain } from '../../core/why.js';
 import { loadTokens } from './utils.js';
+import { Engine } from '../../core/engine.js';
+import { loadConfig } from '../config.js';
+import { setupConstraints } from '../constraint-registry.js';
 export async function whyCommand(options) {
     const tokensPath = options.tokens || 'tokens/tokens.json';
     const tokens = loadTokens(tokensPath);
     const { flat, edges } = flattenTokens(tokens);
     const target = options.tokenId;
     if (!flat[target]) {
-        console.error(`❌ Token not found: ${target}`);
+        console.error(`Token not found: ${target}`);
         const { suggestIds } = await import('../../core/cli-format.js');
         const suggestions = suggestIds(target, Object.keys(flat));
         if (suggestions.length > 0) {
-            console.log(`\nDid you mean:`);
-            suggestions.slice(0, 5).forEach(s => console.log(`  ${s.id}`));
+            console.log('\nDid you mean:');
+            suggestions.slice(0, 5).forEach((s) => console.log(`  ${s.id}`));
         }
         else {
-            console.log(`\nAvailable tokens:`);
-            Object.keys(flat).sort().slice(0, 10).forEach(id => console.log(`  ${id}`));
-            if (Object.keys(flat).length > 10)
+            console.log('\nAvailable tokens:');
+            Object.keys(flat)
+                .sort()
+                .slice(0, 10)
+                .forEach((id) => console.log(`  ${id}`));
+            if (Object.keys(flat).length > 10) {
                 console.log(`  ... and ${Object.keys(flat).length - 10} more`);
+            }
         }
         process.exit(1);
     }
-    function safeLoad(p) { try {
-        return JSON.parse(readFileSync(p, 'utf8'));
+    function safeLoad(p) {
+        try {
+            return JSON.parse(readFileSync(p, 'utf8'));
+        }
+        catch {
+            return {};
+        }
     }
-    catch {
-        return {};
-    } }
     const overrides = safeLoad('tokens/overrides/local.json');
     const theme = safeLoad('themes/theme.json');
-    const report = explain(target, flat, edges, { overrides: overrides?.overrides ?? overrides, theme });
+    const baseReport = explain(target, flat, edges, {
+        overrides: overrides?.overrides ?? overrides,
+        theme,
+    });
+    // Best-effort constraint summary: which rules currently implicate this token
+    let constraintsSummary;
+    try {
+        const cfgRes = loadConfig(options.config);
+        if (cfgRes.ok) {
+            const config = cfgRes.value;
+            // Create engine with flattened tokens
+            const init = {};
+            for (const t of Object.values(flat)) {
+                init[t.id] = t.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, constraintsDir: 'themes' }, { knownIds });
+            const candidates = new Set([target]);
+            const allIssues = engine.evaluate(candidates);
+            if (allIssues.length) {
+                const related = allIssues.filter((issue) => {
+                    const parts = String(issue.id).split('|');
+                    return parts.includes(target);
+                });
+                if (related.length) {
+                    constraintsSummary = related.map((issue) => ({
+                        ruleId: issue.rule,
+                        level: issue.level,
+                        message: issue.message,
+                        where: issue.where,
+                    }));
+                }
+            }
+        }
+    }
+    catch {
+        // If constraint analysis fails, fall back to provenance-only report.
+    }
+    const report = constraintsSummary ? { ...baseReport, constraints: constraintsSummary } : baseReport;
     const format = options.format || 'json';
     if (format === 'table') {
         const { pad, trunc } = await import('../../core/cli-format.js');
         console.log(`\n=== Token Analysis: ${target} ===`);
         console.log(`Value: ${report.value}`);
-        console.log(`Raw: ${report.raw || 'N/A'}`);
+        console.log(`Raw: ${report.raw ?? 'N/A'}`);
         console.log(`Provenance: ${report.provenance}`);
         if (report.dependsOn && report.dependsOn.length > 0) {
             console.log(`\nDependencies (${report.dependsOn.length}):`);
             console.log(pad('TOKEN', 30) + pad('VALUE', 20) + 'TYPE');
             console.log('-'.repeat(70));
-            report.dependsOn.forEach((depId) => { const dep = flat[depId]; if (dep)
-                console.log(pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown')); });
+            report.dependsOn.forEach((depId) => {
+                const dep = flat[depId];
+                if (dep) {
+                    console.log(pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown'));
+                }
+            });
         }
         if (report.dependents && report.dependents.length > 0) {
             console.log(`\nDependents (${report.dependents.length}):`);
             console.log(pad('TOKEN', 30) + pad('VALUE', 20) + 'TYPE');
             console.log('-'.repeat(70));
-            report.dependents.forEach((depId) => { const dep = flat[depId]; if (dep)
-                console.log(pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown')); });
+            report.dependents.forEach((depId) => {
+                const dep = flat[depId];
+                if (dep) {
+                    console.log(pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown'));
+                }
+            });
         }
-        if (report.refs && report.refs.length > 0)
+        if (report.refs && report.refs.length > 0) {
             console.log(`\nReferences: ${report.refs.join(', ')}`);
-        if (report.chain && report.chain.length > 0)
-            console.log(`\nReference Chain: ${report.chain.join(' → ')}`);
+        }
+        if (report.chain && report.chain.length > 0) {
+            console.log(`\nReference Chain: ${report.chain.join(' -> ')}`);
+        }
+        if (constraintsSummary && constraintsSummary.length > 0) {
+            console.log('\nConstraints (violations involving this token):');
+            constraintsSummary.forEach((c) => {
+                const where = c.where ? ` @ ${c.where}` : '';
+                console.log(`- [${c.level}] ${c.ruleId}${where}: ${c.message}`);
+            });
+        }
     }
     else {
         console.log(JSON.stringify(report, null, 2));