design-constraint-validator 2.0.1 → 2.2.0

package/cli/commands/set.js

@@ -1,9 +1,8 @@
-import { join } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
 import { loadConfig } from '../config.js';
 import { Engine } from '../../core/engine.js';
 import { flattenTokens } from '../../core/flatten.js';
-import { loadTokens, outputResult } from './utils.js';
+import { mergeTokens } from '../../core/breakpoints.js';
+import { loadThemeTokens, loadTokens, outputResult } from './utils.js';
 import { setupConstraints } from '../constraint-registry.js';
 // Lightweight suggestion helpers (kept local – why command uses core formatter instead)
 function levenshtein(a, b) {
@@ -81,7 +80,10 @@ export async function setCommand(options) {
         process.exit(2);
     }
     const config = cfgRes.value;
-    const tokens = loadTokens(tokensPath);
+    let tokens = loadTokens(tokensPath);
+    if (options.theme) {
+        tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
+    }
     // Create engine with flattened tokens
     const { flat, edges } = flattenTokens(tokens);
     const init = {};
@@ -103,18 +105,6 @@ export async function setCommand(options) {
             process.exit(1);
         }
     }
-    if (options.theme) {
-        const themePath = join('tokens/themes', `${options.theme}.json`);
-        if (existsSync(themePath)) {
-            const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-            for (const [id, value] of Object.entries(themeTokens)) {
-                engine.commit(id, value);
-            }
-        }
-        else {
-            console.warn(`Theme file not found: ${themePath}`);
-        }
-    }
     let finalResult = {};
     function setDeep(obj, parts, v) {
         let cur = obj;
@@ -210,7 +200,7 @@ export async function setCommand(options) {
             for (const e of entries)
                 console.log(' ', e);
         }
-        const dryRun = process.argv.includes('--dry-run');
+        const dryRun = !!(options['dry-run'] ?? options.dryRun);
         for (const { id, value, unset } of entries) {
             if (unset) {
                 if (!options.quiet)
@@ -227,7 +217,8 @@ export async function setCommand(options) {
             }
         }
         const format = options.format || 'json';
-        outputResult(finalResult, format, options.output);
+        // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+        outputResult(finalResult, format, dryRun ? undefined : options.output);
         if (options.write && !dryRun) {
             const path = 'tokens/overrides/local.json';
             let local = {};
@@ -264,9 +255,17 @@ export async function setCommand(options) {
         }
         Object.assign(finalResult, result.patch);
     }
+    const dryRun = !!(options['dry-run'] ?? options.dryRun);
     const format = options.format || 'json';
-    outputResult(finalResult, format, options.output);
+    // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+    outputResult(finalResult, format, dryRun ? undefined : options.output);
     if (options.write || (options.unset && options.unset.length)) {
+        // --dry-run must not touch the filesystem (it previously persisted the
+        // override file on the positional path; the batch path already guarded it).
+        if (dryRun) {
+            console.log('Dry-run: changes not written');
+            return;
+        }
         const fs = await import('node:fs');
         const path = 'tokens/overrides/local.json';
         let local = {};

package/cli/commands/set.ts

@@ -1,10 +1,9 @@
-import { join } from 'node:path';
-import { readFileSync, existsSync } from 'node:fs';
 import { loadConfig } from '../config.js';
 import { Engine } from '../../core/engine.js';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
+import { mergeTokens } from '../../core/breakpoints.js';
 import type { OverridesTree, SetOptions, ValuesPatch } from '../types.js';
-import { loadTokens, outputResult } from './utils.js';
+import { loadThemeTokens, loadTokens, outputResult } from './utils.js';
 import { setupConstraints } from '../constraint-registry.js';
 
 // Lightweight suggestion helpers (kept local – why command uses core formatter instead)
@@ -76,7 +75,11 @@ export async function setCommand(options: SetOptions): Promise<void> {
   const cfgRes = loadConfig(options.config);
   if (!cfgRes.ok) { console.error(cfgRes.error); process.exit(2); }
   const config = cfgRes.value;
-  const tokens = loadTokens(tokensPath);
+  let tokens = loadTokens(tokensPath);
+
+  if (options.theme) {
+    tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
+  }
 
   // Create engine with flattened tokens
   const { flat, edges } = flattenTokens(tokens);
@@ -105,18 +108,6 @@ export async function setCommand(options: SetOptions): Promise<void> {
     }
   }
 
-  if (options.theme) {
-    const themePath = join('tokens/themes', `${options.theme}.json`);
-    if (existsSync(themePath)) {
-      const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-      for (const [id, value] of Object.entries(themeTokens)) {
-        engine.commit(id, value as string | number);
-      }
-    } else {
-      console.warn(`Theme file not found: ${themePath}`);
-    }
-  }
-
   let finalResult: ValuesPatch = {};
 
   function setDeep(obj: OverridesTree, parts: string[], v: unknown) {
@@ -183,7 +174,7 @@ export async function setCommand(options: SetOptions): Promise<void> {
     for (const ent of entries) ensureKnownOrSuggest(ent.id);
     const debug = process.argv.includes('--debug-set') || process.env.DCV_DEBUG_SET === '1';
     if (debug) { console.log('[set:batch] parsed entries:'); for (const e of entries) console.log(' ', e); }
-    const dryRun = process.argv.includes('--dry-run');
+    const dryRun = !!(options['dry-run'] ?? options.dryRun);
     for (const { id, value, unset } of entries) {
       if (unset) { if (!options.quiet) console.log(`preview: unset ${id}`); }
       else {
@@ -193,7 +184,8 @@ export async function setCommand(options: SetOptions): Promise<void> {
       }
     }
     const format = options.format || 'json';
-    outputResult(finalResult, format, options.output);
+    // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+    outputResult(finalResult, format, dryRun ? undefined : options.output);
     if (options.write && !dryRun) {
       const path = 'tokens/overrides/local.json';
       let local: OverridesTree = {} as OverridesTree;
@@ -218,9 +210,17 @@ export async function setCommand(options: SetOptions): Promise<void> {
     }
     Object.assign(finalResult, result.patch);
   }
+  const dryRun = !!(options['dry-run'] ?? options.dryRun);
   const format = options.format || 'json';
-  outputResult(finalResult, format, options.output);
+  // Dry-run prints the patch to stdout instead of writing --output (no file writes).
+  outputResult(finalResult, format, dryRun ? undefined : options.output);
   if (options.write || (options.unset && options.unset.length)) {
+    // --dry-run must not touch the filesystem (it previously persisted the
+    // override file on the positional path; the batch path already guarded it).
+    if (dryRun) {
+      console.log('Dry-run: changes not written');
+      return;
+    }
     const fs = await import('node:fs');
     const path = 'tokens/overrides/local.json';
     let local: OverridesTree = {} as OverridesTree;

package/cli/commands/utils.d.ts

@@ -1,4 +1,5 @@
 import type { TokenNode } from '../../core/flatten.js';
 export declare function loadTokens(tokensPath: string): TokenNode;
+export declare function loadThemeTokens(theme: string): TokenNode;
 export declare function outputResult(data: unknown, format: string, outputPath?: string): void;
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,uBAAuB,CAAC;AAInE,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAUxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CA8BrF"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,uBAAuB,CAAC;AAInE,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAUxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAoBxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CA8BrF"}

package/cli/commands/utils.js

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { valuesToCss } from '../../adapters/css.js';
 // Shared helpers for command modules
 export function loadTokens(tokensPath) {
@@ -13,6 +13,25 @@ export function loadTokens(tokensPath) {
     }
     return data;
 }
+export function loadThemeTokens(theme) {
+    const themePath = join('tokens/themes', `${theme}.json`);
+    if (!existsSync(themePath)) {
+        throw new Error(`Theme file not found: ${themePath}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(readFileSync(themePath, 'utf8'));
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`Theme file is not valid JSON: ${themePath} (${detail})`);
+    }
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        const got = data === null ? 'null' : Array.isArray(data) ? 'array' : typeof data;
+        throw new Error(`Theme file must contain a JSON object: ${themePath} (got ${got})`);
+    }
+    return data;
+}
 export function outputResult(data, format, outputPath) {
     let content;
     switch (format) {

package/cli/commands/utils.ts

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, join } from 'node:path';
 import { valuesToCss } from '../../adapters/css.js';
 import type { TokenNode, TokenValue } from '../../core/flatten.js';
 
@@ -17,6 +17,28 @@ export function loadTokens(tokensPath: string): TokenNode {
   return data as TokenNode;
 }
 
+export function loadThemeTokens(theme: string): TokenNode {
+  const themePath = join('tokens/themes', `${theme}.json`);
+  if (!existsSync(themePath)) {
+    throw new Error(`Theme file not found: ${themePath}`);
+  }
+
+  let data: unknown;
+  try {
+    data = JSON.parse(readFileSync(themePath, 'utf8'));
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    throw new Error(`Theme file is not valid JSON: ${themePath} (${detail})`);
+  }
+
+  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+    const got = data === null ? 'null' : Array.isArray(data) ? 'array' : typeof data;
+    throw new Error(`Theme file must contain a JSON object: ${themePath} (got ${got})`);
+  }
+
+  return data as TokenNode;
+}
+
 export function outputResult(data: unknown, format: string, outputPath?: string): void {
   let content: string;
   switch (format) {

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

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

package/cli/commands/validate.js

@@ -3,10 +3,10 @@ import { Engine } from '../../core/engine.js';
 import { loadConfig } from '../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 { readFileSync } from 'node:fs';
+import { setupConstraints, collectReferencedIds } from '../constraint-registry.js';
 import { printVersionBanner } from '../version-banner.js';
+import { loadThemeTokens } from './utils.js';
 export async function validateCommand(_options) {
     // Show version banner (subtle, dimmed)
     printVersionBanner({ quiet: _options.format === 'json' });
@@ -17,11 +17,22 @@ export async function validateCommand(_options) {
         let anyErrors = false;
         let totalErrors = 0;
         let totalWarnings = 0;
-        const argv = process.argv.slice(2);
-        const failOnIdx = argv.indexOf('--fail-on');
-        const failOn = _options.failOn ?? (failOnIdx >= 0 ? argv[failOnIdx + 1] : 'error');
-        const sumIdx = argv.indexOf('--summary');
-        const summaryFmt = _options.summary ?? (sumIdx >= 0 ? argv[sumIdx + 1] : 'none');
+        // Coverage tracking for the no-match note (never silently "pass" a file whose
+        // tokens are referenced by no active constraint).
+        let anyConstraintMatched = false;
+        let coverageKnownAll = true;
+        let tokenCount = 0;
+        // Reconcile the tokens path: the positional `[tokens-path]` is an alias for
+        // --tokens. The flag wins; warn on a genuine mismatch. undefined => loader default.
+        const flagTokens = _options.tokens;
+        const posTokens = _options['tokens-path'];
+        if (flagTokens && posTokens && flagTokens !== posTokens) {
+            console.error(`warning: both --tokens (${flagTokens}) and positional tokens path (${posTokens}) provided; using --tokens`);
+        }
+        const tokensPath = flagTokens ?? posTokens;
+        const constraintsDir = _options['constraints-dir'] ?? 'themes';
+        const failOn = (_options['fail-on'] ?? _options.failOn) ?? 'error';
+        const summaryFmt = _options.summary ?? 'none';
         const outputFormat = _options.format ?? 'text';
         // Collect all issues for JSON output
         const allErrors = [];
@@ -55,19 +66,10 @@ export async function validateCommand(_options) {
         const tStartTotal = globalThis.performance.now();
         for (const bp of plan) {
             const tStart = globalThis.performance.now();
-            let tokens = loadTokensWithBreakpoint(bp);
+            let tokens = loadTokensWithBreakpoint(bp, tokensPath);
             // 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
-                    }
-                }
+                tokens = mergeTokens(tokens, loadThemeTokens(_options.theme));
             }
             // Create engine with flattened tokens
             const { flat, edges } = flattenTokens(tokens);
@@ -78,7 +80,20 @@ export async function validateCommand(_options) {
             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 sources = setupConstraints(engine, { config, bp, constraintsDir }, { knownIds, crossAxisDebug });
+            // Track whether any active constraint actually references a token in this file.
+            const coverage = collectReferencedIds(sources);
+            if (!coverage.coverageKnown)
+                coverageKnownAll = false;
+            tokenCount = Math.max(tokenCount, knownIds.size);
+            if (!anyConstraintMatched) {
+                for (const id of coverage.ids) {
+                    if (knownIds.has(id)) {
+                        anyConstraintMatched = true;
+                        break;
+                    }
+                }
+            }
             const allIds = new Set(Object.keys(init));
             const issues = engine.evaluate(allIds);
             const errs = issues.filter((i) => i.level === 'error');
@@ -104,6 +119,14 @@ export async function validateCommand(_options) {
             }
         }
         const totalMs = globalThis.performance.now() - tStartTotal;
+        // No-match note: tokens were validated but no active constraint referenced any
+        // of them. Surfaced loudly (stderr + JSON `note`) so a foreign file can never
+        // silently report "0 errors" when nothing was actually checked.
+        const noMatchNote = (tokenCount > 0 && coverageKnownAll && !anyConstraintMatched)
+            ? `No active constraint references any of the ${tokenCount} validated token(s) — nothing was checked. Define constraints in dcv.config.json (constraints.wcag / constraints.thresholds) or point --constraints-dir at your order/cross-axis files.`
+            : undefined;
+        if (noMatchNote)
+            console.error(`note: ${noMatchNote}`);
         // 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 });
@@ -122,11 +145,10 @@ export async function validateCommand(_options) {
         }
         // Handle JSON output mode
         if (outputFormat === 'json') {
-            const result = createValidationResult(allErrors, allWarnings, totalMs, engineVersion);
+            const result = createValidationResult(allErrors, allWarnings, totalMs, engineVersion, noMatchNote);
             // If receipt requested, generate full receipt
             if (_options.receipt) {
-                const tokensFile = _options.tokens ?? 'tokens/tokens.example.json';
-                const constraintsDir = 'themes';
+                const tokensFile = tokensPath ?? 'tokens/tokens.example.json';
                 const receipt = createValidationReceipt(result, tokensFile, constraintsDir, bps[0], failOn);
                 writeJsonOutput(receipt, _options.receipt);
             }

package/cli/commands/validate.ts

@@ -5,10 +5,10 @@ import { parseBreakpoints, loadTokensWithBreakpoint, mergeTokens, type Breakpoin
 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 { readFileSync } from 'node:fs';
+import { setupConstraints, collectReferencedIds } from '../constraint-registry.js';
 import { printVersionBanner } from '../version-banner.js';
+import { loadThemeTokens } from './utils.js';
 
 export async function validateCommand(_options: ValidateOptions): Promise<void> {
   // Show version banner (subtle, dimmed)
@@ -19,13 +19,26 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
     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');
+    // Coverage tracking for the no-match note (never silently "pass" a file whose
+    // tokens are referenced by no active constraint).
+    let anyConstraintMatched = false; let coverageKnownAll = true; let tokenCount = 0;
+
+    // Reconcile the tokens path: the positional `[tokens-path]` is an alias for
+    // --tokens. The flag wins; warn on a genuine mismatch. undefined => loader default.
+    const flagTokens = _options.tokens;
+    const posTokens = _options['tokens-path'];
+    if (flagTokens && posTokens && flagTokens !== posTokens) {
+      console.error(`warning: both --tokens (${flagTokens}) and positional tokens path (${posTokens}) provided; using --tokens`);
+    }
+    const tokensPath = flagTokens ?? posTokens;
+    const constraintsDir = _options['constraints-dir'] ?? 'themes';
+    // Read both the kebab key (CLI; camel-case-expansion is off, and yargs sets the
+    // default there) and the camelCase key (programmatic callers). The old argv-scan
+    // workaround is no longer needed.
     type FailOn = 'off' | 'warn' | 'error';
-    const failOn: FailOn = _options.failOn ?? (failOnIdx >= 0 ? (argv[failOnIdx + 1] as FailOn) : 'error');
-    const sumIdx = argv.indexOf('--summary');
+    const failOn: FailOn = ((_options['fail-on'] ?? _options.failOn) as FailOn) ?? 'error';
     type SummaryFmt = 'table' | 'json' | 'none';
-    const summaryFmt: SummaryFmt = _options.summary ?? (sumIdx >= 0 ? (argv[sumIdx + 1] as SummaryFmt) : 'none');
+    const summaryFmt: SummaryFmt = (_options.summary as SummaryFmt) ?? 'none';
     const outputFormat = _options.format ?? 'text';
     
     // Collect all issues for JSON output
@@ -56,18 +69,10 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
     const tStartTotal = globalThis.performance.now();
     for (const bp of plan) {
       const tStart = globalThis.performance.now();
-      let tokens: TokenNode = loadTokensWithBreakpoint(bp);
+      let tokens: TokenNode = loadTokensWithBreakpoint(bp, tokensPath);
       // 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
-          }
-        }
+        tokens = mergeTokens(tokens, loadThemeTokens(_options.theme));
       }
       // Create engine with flattened tokens
       const { flat, edges } = flattenTokens(tokens);
@@ -79,12 +84,22 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
       const knownIds = new Set(Object.keys(init));
 
       // Discover and attach all constraints via centralized registry
-      setupConstraints(
+      const sources = setupConstraints(
         engine,
-        { config, bp, constraintsDir: 'themes' },
+        { config, bp, constraintsDir },
         { knownIds, crossAxisDebug },
       );
 
+      // Track whether any active constraint actually references a token in this file.
+      const coverage = collectReferencedIds(sources);
+      if (!coverage.coverageKnown) coverageKnownAll = false;
+      tokenCount = Math.max(tokenCount, knownIds.size);
+      if (!anyConstraintMatched) {
+        for (const id of coverage.ids) {
+          if (knownIds.has(id)) { anyConstraintMatched = true; break; }
+        }
+      }
+
       const allIds = new Set(Object.keys(init));
       const issues = engine.evaluate(allIds);
       const errs = issues.filter((i: ConstraintIssue) => i.level === 'error');
@@ -107,6 +122,13 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
       }
     }
     const totalMs = globalThis.performance.now() - tStartTotal;
+    // No-match note: tokens were validated but no active constraint referenced any
+    // of them. Surfaced loudly (stderr + JSON `note`) so a foreign file can never
+    // silently report "0 errors" when nothing was actually checked.
+    const noMatchNote = (tokenCount > 0 && coverageKnownAll && !anyConstraintMatched)
+      ? `No active constraint references any of the ${tokenCount} validated token(s) — nothing was checked. Define constraints in dcv.config.json (constraints.wcag / constraints.thresholds) or point --constraints-dir at your order/cross-axis files.`
+      : undefined;
+    if (noMatchNote) console.error(`note: ${noMatchNote}`);
     // 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 });
@@ -125,12 +147,11 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
     
     // Handle JSON output mode
     if (outputFormat === 'json') {
-      const result = createValidationResult(allErrors, allWarnings, totalMs, engineVersion);
-      
+      const result = createValidationResult(allErrors, allWarnings, totalMs, engineVersion, noMatchNote);
+
       // If receipt requested, generate full receipt
       if (_options.receipt) {
-        const tokensFile = _options.tokens ?? 'tokens/tokens.example.json';
-        const constraintsDir = 'themes';
+        const tokensFile = tokensPath ?? 'tokens/tokens.example.json';
         const receipt = createValidationReceipt(result, tokensFile, constraintsDir, bps[0], failOn);
         writeJsonOutput(receipt, _options.receipt);
       } else {
@@ -154,8 +175,8 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
     }
     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;
+    const budgetTotal = _options['budget-total-ms'] ?? _options.budgetTotalMs;
+    const budgetPerBp = _options['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`);

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;AAO9C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJnE"}
+{"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,CA8JnE"}

package/cli/commands/why.js

@@ -38,17 +38,28 @@ export async function whyCommand(options) {
             return {};
         }
     }
+    // Local overrides (written by `dcv set --write`) inform provenance labelling.
+    // The legacy `themes/theme.json` hint was dropped: `themes/` now holds constraint
+    // policy files, not visual themes (the overlay convention is tokens/themes/<name>.json),
+    // so reading it as a theme layer was a wrong-convention silent fallback.
     const overrides = safeLoad('tokens/overrides/local.json');
-    const theme = safeLoad('themes/theme.json');
     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) {
+    // An explicitly requested --config that fails to load is a hard error (parity
+    // with validate); a config discovered from the cwd just enables the best-effort
+    // constraint summary when present.
+    const cfgRes = loadConfig(options.config);
+    if (!cfgRes.ok) {
+        if (options.config) {
+            console.error(cfgRes.error);
+            process.exit(2);
+        }
+    }
+    else {
+        try {
             const config = cfgRes.value;
             // Create engine with flattened tokens
             const init = {};
@@ -57,8 +68,9 @@ export async function whyCommand(options) {
             }
             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 });
+            // Discover and attach all constraints via centralized registry.
+            // Honor --constraints-dir, matching `validate` (default: themes).
+            setupConstraints(engine, { config, constraintsDir: options['constraints-dir'] ?? 'themes' }, { knownIds });
             const candidates = new Set([target]);
             const allIssues = engine.evaluate(candidates);
             if (allIssues.length) {
@@ -76,9 +88,9 @@ export async function whyCommand(options) {
                 }
             }
         }
-    }
-    catch {
-        // If constraint analysis fails, fall back to provenance-only report.
+        catch {
+            // If constraint analysis fails, fall back to provenance-only report.
+        }
     }
     const report = constraintsSummary ? { ...baseReport, constraints: constraintsSummary } : baseReport;
     const format = options.format || 'json';

package/cli/commands/why.ts

@@ -42,12 +42,14 @@ export async function whyCommand(options: WhyOptions): Promise<void> {
     }
   }
 
+  // Local overrides (written by `dcv set --write`) inform provenance labelling.
+  // The legacy `themes/theme.json` hint was dropped: `themes/` now holds constraint
+  // policy files, not visual themes (the overlay convention is tokens/themes/<name>.json),
+  // so reading it as a theme layer was a wrong-convention silent fallback.
   const overrides = safeLoad('tokens/overrides/local.json');
-  const theme = safeLoad('themes/theme.json');
 
   const baseReport = explain(target, flat, edges, {
     overrides: (overrides as any)?.overrides ?? overrides,
-    theme,
   });
 
   // Best-effort constraint summary: which rules currently implicate this token
@@ -60,9 +62,17 @@ export async function whyCommand(options: WhyOptions): Promise<void> {
       }[]
     | undefined;
 
-  try {
-    const cfgRes = loadConfig(options.config);
-    if (cfgRes.ok) {
+  // An explicitly requested --config that fails to load is a hard error (parity
+  // with validate); a config discovered from the cwd just enables the best-effort
+  // constraint summary when present.
+  const cfgRes = loadConfig(options.config);
+  if (!cfgRes.ok) {
+    if (options.config) {
+      console.error(cfgRes.error);
+      process.exit(2);
+    }
+  } else {
+    try {
       const config = cfgRes.value;
 
       // Create engine with flattened tokens
@@ -73,10 +83,11 @@ export async function whyCommand(options: WhyOptions): Promise<void> {
       const engine = new Engine(init, edges);
       const knownIds = new Set(Object.keys(init));
 
-      // Discover and attach all constraints via centralized registry
+      // Discover and attach all constraints via centralized registry.
+      // Honor --constraints-dir, matching `validate` (default: themes).
       setupConstraints(
         engine,
-        { config, constraintsDir: 'themes' },
+        { config, constraintsDir: options['constraints-dir'] ?? 'themes' },
         { knownIds },
       );
 
@@ -96,9 +107,9 @@ export async function whyCommand(options: WhyOptions): Promise<void> {
           }));
         }
       }
+    } catch {
+      // If constraint analysis fails, fall back to provenance-only report.
     }
-  } catch {
-    // If constraint analysis fails, fall back to provenance-only report.
   }
 
   const report: any = constraintsSummary ? { ...baseReport, constraints: constraintsSummary } : baseReport;