design-constraint-validator 2.1.0 → 2.2.0

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,CAoM9E"}
+{"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 { 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' });
@@ -31,11 +31,8 @@ export async function validateCommand(_options) {
         }
         const tokensPath = flagTokens ?? posTokens;
         const constraintsDir = _options['constraints-dir'] ?? 'themes';
-        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');
+        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 = [];
@@ -72,16 +69,7 @@ export async function validateCommand(_options) {
             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);

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 { 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)
@@ -32,13 +32,13 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
     }
     const tokensPath = flagTokens ?? posTokens;
     const constraintsDir = _options['constraints-dir'] ?? 'themes';
-    const argv = process.argv.slice(2);
-    const failOnIdx = argv.indexOf('--fail-on');
+    // 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
@@ -72,15 +72,7 @@ export async function validateCommand(_options: ValidateOptions): Promise<void>
       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);
@@ -183,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;