design-constraint-validator 2.0.1 → 2.1.0

package/cli/config-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["config-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;EAKzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAEd,CAAC;AAEjB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAGZ,CAAC;AAEjB,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,CAAC,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAM3F"}
+{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["config-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;EAMzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAEd,CAAC;AAEjB,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAGZ,CAAC;AAEjB,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,KAAK,CAAC,EAAE,eAAe,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAO3F"}

package/cli/config-schema.js

@@ -3,7 +3,8 @@ export const WcagRuleSchema = z.object({
     foreground: z.string(),
     background: z.string(),
     ratio: z.number().positive().optional(),
-    description: z.string().optional()
+    description: z.string().optional(),
+    backdrop: z.string().optional()
 });
 export const ConstraintsSchema = z.object({
     wcag: z.array(WcagRuleSchema).optional()
@@ -15,7 +16,8 @@ export const DcvConfigSchema = z.object({
 export function validateConfig(raw) {
     const res = DcvConfigSchema.safeParse(raw);
     if (!res.success) {
-        return { errors: res.error.errors.map(e => `${e.path.join('.') || '<root>'}: ${e.message}`) };
+        // zod v4 renamed ZodError.errors -> .issues (the .errors getter was removed).
+        return { errors: res.error.issues.map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`) };
     }
     return { value: res.data };
 }

package/cli/config-schema.ts

@@ -4,7 +4,8 @@ export const WcagRuleSchema = z.object({
   foreground: z.string(),
   background: z.string(),
   ratio: z.number().positive().optional(),
-  description: z.string().optional()
+  description: z.string().optional(),
+  backdrop: z.string().optional()
 });
 
 export const ConstraintsSchema = z.object({
@@ -21,7 +22,8 @@ export type DcvConfigParsed = z.infer<typeof DcvConfigSchema>;
 export function validateConfig(raw: unknown): { value?: DcvConfigParsed; errors?: string[] } {
   const res = DcvConfigSchema.safeParse(raw);
   if (!res.success) {
-    return { errors: res.error.errors.map(e => `${e.path.join('.')||'<root>'}: ${e.message}`) };
+    // zod v4 renamed ZodError.errors -> .issues (the .errors getter was removed).
+    return { errors: res.error.issues.map((e) => `${e.path.join('.') || '<root>'}: ${e.message}`) };
   }
   return { value: res.data };
 }

package/cli/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CA6BzE"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAkCzE"}

package/cli/config.js

@@ -1,20 +1,26 @@
 import { readFileSync, existsSync } from 'node:fs';
+import { basename, extname } from 'node:path';
 import { validateConfig } from './config-schema.js';
 import { ok, err } from './result.js';
 export function loadConfig(configPath) {
+    if (configPath && !existsSync(configPath)) {
+        return err(`Config file not found: ${configPath}`);
+    }
     const candidates = configPath ? [configPath] : [
         'dcv.config.json',
-        'dcv.config.js',
         '.dcvrc.json',
         'package.json'
     ];
     for (const p of candidates) {
         if (!existsSync(p))
             continue;
+        if (extname(p) === '.js') {
+            return err(`Unsupported config file ${p}: use JSON config (dcv.config.json, .dcvrc.json, or package.json "dcv").`);
+        }
         try {
             const rawTxt = readFileSync(p, 'utf8');
             let raw = JSON.parse(rawTxt);
-            if (p === 'package.json' && raw && typeof raw === 'object') {
+            if (basename(p) === 'package.json' && raw && typeof raw === 'object') {
                 const pkg = raw;
                 if ('dcv' in pkg) {
                     raw = pkg.dcv;

package/cli/config.ts

@@ -1,21 +1,27 @@
 import { readFileSync, existsSync } from 'node:fs';
+import { basename, extname } from 'node:path';
 import { validateConfig } from './config-schema.js';
 import { ok, err, type Result } from './result.js';
 import type { DcvConfig } from './types.js';
 
 export function loadConfig(configPath?: string): Result<DcvConfig, string> {
+  if (configPath && !existsSync(configPath)) {
+    return err(`Config file not found: ${configPath}`);
+  }
   const candidates = configPath ? [configPath] : [
     'dcv.config.json',
-    'dcv.config.js',
     '.dcvrc.json',
     'package.json'
   ];
   for (const p of candidates) {
     if (!existsSync(p)) continue;
+    if (extname(p) === '.js') {
+      return err(`Unsupported config file ${p}: use JSON config (dcv.config.json, .dcvrc.json, or package.json "dcv").`);
+    }
     try {
       const rawTxt = readFileSync(p, 'utf8');
       let raw: unknown = JSON.parse(rawTxt);
-      if (p === 'package.json' && raw && typeof raw === 'object') {
+      if (basename(p) === 'package.json' && raw && typeof raw === 'object') {
         const pkg = raw as Record<string, unknown>;
         if ('dcv' in pkg) {
           raw = pkg.dcv;

package/cli/constraint-registry.d.ts

@@ -67,6 +67,8 @@ export type AttachOptions = {
     knownIds: Set<string>;
     crossAxisDebug?: boolean;
 };
+export declare const DEFAULT_WCAG_PAIRS: WcagRule[];
+export declare const DEFAULT_THRESHOLDS: ThresholdRule[];
 /**
  * Discover all constraint sources for a given configuration and breakpoint.
  *
@@ -98,4 +100,18 @@ export declare function attachConstraints(engine: Engine, sources: ConstraintSou
  * @param attachOpts Attachment options
  */
 export declare function setupConstraints(engine: Engine, discoveryOpts: DiscoveryOptions, attachOpts: AttachOptions): ConstraintSource[];
+/**
+ * Collect the token ids referenced by the active constraint sources, plus
+ * whether that coverage is fully enumerable.
+ *
+ * Used to detect the silent-pass case: a token file that validates with zero
+ * errors only because no active constraint references any of its tokens. Cross-
+ * axis rule ids are not enumerated here, so when any cross-axis source is present
+ * `coverageKnown` is false and callers must stay conservative (never claim
+ * "nothing was checked" when they cannot be sure).
+ */
+export declare function collectReferencedIds(sources: ConstraintSource[]): {
+    ids: Set<string>;
+    coverageKnown: boolean;
+};
 //# sourceMappingURL=constraint-registry.d.ts.map

package/cli/constraint-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constraint-registry.d.ts","sourceRoot":"","sources":["constraint-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAY5C,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAEtD,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,UAAU,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CA8F9E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAsFxG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,gBAAgB,EAC/B,UAAU,EAAE,aAAa,GACxB,gBAAgB,EAAE,CAIpB"}
+{"version":3,"file":"constraint-registry.d.ts","sourceRoot":"","sources":["constraint-registry.ts"],"names":[],"mappings":"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"}

package/cli/constraint-registry.js

@@ -18,6 +18,16 @@ import { WcagContrastPlugin } from '../core/constraints/wcag.js';
 import { ThresholdPlugin } from '../core/constraints/threshold.js';
 import { CrossAxisPlugin } from '../core/constraints/cross-axis.js';
 import { loadCrossAxisRules } from './cross-axis-loader.js';
+// Built-in default constraint rules. Shared by attachConstraints (to register
+// plugins) and collectReferencedIds (to compute coverage) so the two never drift.
+export const DEFAULT_WCAG_PAIRS = [
+    { fg: 'color.role.text.default', bg: 'color.role.bg.surface', min: 4.5, where: 'Body text on surface' },
+    { fg: 'color.role.accent.default', bg: 'color.role.bg.surface', min: 3.0, where: 'Accent on surface' },
+    { fg: 'color.role.focus.ring', bg: 'color.role.bg.surface', min: 3.0, where: 'Focus ring on surface', backdrop: '#ffffff' },
+];
+export const DEFAULT_THRESHOLDS = [
+    { id: 'control.size.min', op: '>=', valuePx: 44, where: 'Touch target (WCAG / Apple HIG)' },
+];
 // ============================================================================
 // Discovery
 // ============================================================================
@@ -132,42 +142,13 @@ export function attachConstraints(engine, sources, opts) {
             switch (source.type) {
                 case 'builtin-wcag': {
                     if (source.enabled) {
-                        const defaultWcagPairs = [
-                            {
-                                fg: 'color.role.text.default',
-                                bg: 'color.role.bg.surface',
-                                min: 4.5,
-                                where: 'Body text on surface',
-                            },
-                            {
-                                fg: 'color.role.accent.default',
-                                bg: 'color.role.bg.surface',
-                                min: 3.0,
-                                where: 'Accent on surface',
-                            },
-                            {
-                                fg: 'color.role.focus.ring',
-                                bg: 'color.role.bg.surface',
-                                min: 3.0,
-                                where: 'Focus ring on surface',
-                                backdrop: '#ffffff',
-                            },
-                        ];
-                        engine.use(WcagContrastPlugin(defaultWcagPairs));
+                        engine.use(WcagContrastPlugin(DEFAULT_WCAG_PAIRS));
                     }
                     break;
                 }
                 case 'builtin-threshold': {
                     if (source.enabled) {
-                        const defaultThresholds = [
-                            {
-                                id: 'control.size.min',
-                                op: '>=',
-                                valuePx: 44,
-                                where: 'Touch target (WCAG / Apple HIG)',
-                            },
-                        ];
-                        engine.use(ThresholdPlugin(defaultThresholds, 'threshold'));
+                        engine.use(ThresholdPlugin(DEFAULT_THRESHOLDS, 'threshold'));
                     }
                     break;
                 }
@@ -223,3 +204,55 @@ export function setupConstraints(engine, discoveryOpts, attachOpts) {
     attachConstraints(engine, sources, attachOpts);
     return sources;
 }
+/**
+ * Collect the token ids referenced by the active constraint sources, plus
+ * whether that coverage is fully enumerable.
+ *
+ * Used to detect the silent-pass case: a token file that validates with zero
+ * errors only because no active constraint references any of its tokens. Cross-
+ * axis rule ids are not enumerated here, so when any cross-axis source is present
+ * `coverageKnown` is false and callers must stay conservative (never claim
+ * "nothing was checked" when they cannot be sure).
+ */
+export function collectReferencedIds(sources) {
+    const ids = new Set();
+    let coverageKnown = true;
+    const addOrders = (orders) => {
+        for (const [a, , b] of orders) {
+            ids.add(a);
+            ids.add(b);
+        }
+    };
+    for (const source of sources) {
+        switch (source.type) {
+            case 'builtin-wcag':
+                for (const p of DEFAULT_WCAG_PAIRS) {
+                    ids.add(p.fg);
+                    ids.add(p.bg);
+                }
+                break;
+            case 'builtin-threshold':
+                for (const t of DEFAULT_THRESHOLDS)
+                    ids.add(t.id);
+                break;
+            case 'config-wcag':
+                for (const r of source.rules) {
+                    ids.add(r.fg);
+                    ids.add(r.bg);
+                }
+                break;
+            case 'custom-threshold':
+                for (const r of source.rules)
+                    ids.add(r.id);
+                break;
+            case 'order-file':
+            case 'lightness-file':
+                addOrders(source.orders);
+                break;
+            case 'cross-axis-file':
+                coverageKnown = false;
+                break;
+        }
+    }
+    return { ids, coverageKnown };
+}

package/cli/constraint-registry.ts

@@ -69,6 +69,18 @@ export type AttachOptions = {
   crossAxisDebug?: boolean;
 };
 
+// Built-in default constraint rules. Shared by attachConstraints (to register
+// plugins) and collectReferencedIds (to compute coverage) so the two never drift.
+export const DEFAULT_WCAG_PAIRS: WcagRule[] = [
+  { fg: 'color.role.text.default', bg: 'color.role.bg.surface', min: 4.5, where: 'Body text on surface' },
+  { fg: 'color.role.accent.default', bg: 'color.role.bg.surface', min: 3.0, where: 'Accent on surface' },
+  { fg: 'color.role.focus.ring', bg: 'color.role.bg.surface', min: 3.0, where: 'Focus ring on surface', backdrop: '#ffffff' },
+];
+
+export const DEFAULT_THRESHOLDS: ThresholdRule[] = [
+  { id: 'control.size.min', op: '>=', valuePx: 44, where: 'Touch target (WCAG / Apple HIG)' },
+];
+
 // ============================================================================
 // Discovery
 // ============================================================================
@@ -200,43 +212,14 @@ export function attachConstraints(engine: Engine, sources: ConstraintSource[], o
       switch (source.type) {
         case 'builtin-wcag': {
           if (source.enabled) {
-            const defaultWcagPairs: WcagRule[] = [
-              {
-                fg: 'color.role.text.default',
-                bg: 'color.role.bg.surface',
-                min: 4.5,
-                where: 'Body text on surface',
-              },
-              {
-                fg: 'color.role.accent.default',
-                bg: 'color.role.bg.surface',
-                min: 3.0,
-                where: 'Accent on surface',
-              },
-              {
-                fg: 'color.role.focus.ring',
-                bg: 'color.role.bg.surface',
-                min: 3.0,
-                where: 'Focus ring on surface',
-                backdrop: '#ffffff',
-              },
-            ];
-            engine.use(WcagContrastPlugin(defaultWcagPairs));
+            engine.use(WcagContrastPlugin(DEFAULT_WCAG_PAIRS));
           }
           break;
         }
 
         case 'builtin-threshold': {
           if (source.enabled) {
-            const defaultThresholds: ThresholdRule[] = [
-              {
-                id: 'control.size.min',
-                op: '>=',
-                valuePx: 44,
-                where: 'Touch target (WCAG / Apple HIG)',
-              },
-            ];
-            engine.use(ThresholdPlugin(defaultThresholds, 'threshold'));
+            engine.use(ThresholdPlugin(DEFAULT_THRESHOLDS, 'threshold'));
           }
           break;
         }
@@ -302,3 +285,56 @@ export function setupConstraints(
   attachConstraints(engine, sources, attachOpts);
   return sources;
 }
+
+/**
+ * Collect the token ids referenced by the active constraint sources, plus
+ * whether that coverage is fully enumerable.
+ *
+ * Used to detect the silent-pass case: a token file that validates with zero
+ * errors only because no active constraint references any of its tokens. Cross-
+ * axis rule ids are not enumerated here, so when any cross-axis source is present
+ * `coverageKnown` is false and callers must stay conservative (never claim
+ * "nothing was checked" when they cannot be sure).
+ */
+export function collectReferencedIds(sources: ConstraintSource[]): { ids: Set<string>; coverageKnown: boolean } {
+  const ids = new Set<string>();
+  let coverageKnown = true;
+  const addOrders = (orders: OrderRule[]) => {
+    for (const [a, , b] of orders) {
+      ids.add(a);
+      ids.add(b);
+    }
+  };
+
+  for (const source of sources) {
+    switch (source.type) {
+      case 'builtin-wcag':
+        for (const p of DEFAULT_WCAG_PAIRS) {
+          ids.add(p.fg);
+          ids.add(p.bg);
+        }
+        break;
+      case 'builtin-threshold':
+        for (const t of DEFAULT_THRESHOLDS) ids.add(t.id);
+        break;
+      case 'config-wcag':
+        for (const r of source.rules) {
+          ids.add(r.fg);
+          ids.add(r.bg);
+        }
+        break;
+      case 'custom-threshold':
+        for (const r of source.rules) ids.add(r.id);
+        break;
+      case 'order-file':
+      case 'lightness-file':
+        addOrders(source.orders);
+        break;
+      case 'cross-axis-file':
+        coverageKnown = false;
+        break;
+    }
+  }
+
+  return { ids, coverageKnown };
+}

package/cli/dcv.js

@@ -2,30 +2,12 @@
 // Clean minimal DCV CLI entrypoint
 import yargs from 'yargs/yargs';
 import { hideBin } from 'yargs/helpers';
-import { spawnSync } from 'node:child_process';
-import { createRequire } from 'module';
-import path from 'node:path';
 import { setCommand, buildCommand, validateCommand, graphCommand, whyCommand, patchCommand, patchApplyCommand } from './commands/index.js';
-// Early intercept: experimental graph diff helper
-(() => {
-    const args = process.argv.slice(2);
-    if (args[0] === 'graph' && args[1] === 'diff') {
-        const pass = args.slice(2);
-        const require = createRequire(import.meta.url);
-        const tsx = (() => { try {
-            return require.resolve('tsx/dist/cli.mjs');
-        }
-        catch {
-            return path.resolve('node_modules/tsx/dist/cli.mjs');
-        } })();
-        const r = spawnSync(process.execPath, [tsx, path.resolve('scripts/graph-diff.ts'), ...pass], { stdio: 'inherit', env: process.env });
-        process.exit(r.status ?? 0);
-    }
-})();
 const cli = yargs(hideBin(process.argv))
     .scriptName('dcv')
     .parserConfiguration({ 'camel-case-expansion': false })
-    .option('quiet', { type: 'boolean' });
+    .option('quiet', { type: 'boolean' })
+    .option('config', { type: 'string', describe: 'Path to JSON config file' });
 cli.command('set <expressions..>', 'Set token values', y => y
     .positional('expressions', { type: 'string', array: true })
     .option('dry-run', { type: 'boolean', default: false })
@@ -43,14 +25,16 @@ cli.command('build', 'Build token outputs', y => y
     .option('mapper', { type: 'string' })
     .option('theme', { type: 'string' })
     .option('dry-run', { type: 'boolean', default: false })
-    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => buildCommand(a));
-cli.command('validate', 'Validate constraints', y => y
+    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }), a => buildCommand(a));
+cli.command('validate [tokens-path]', 'Validate constraints', y => y
+    .positional('tokens-path', { type: 'string', describe: 'Path to a tokens file (positional alias for --tokens)' })
+    .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files (default: themes)' })
     .option('fail-on', { type: 'string', choices: ['off', 'warn', 'error'], default: 'error' })
     .option('summary', { type: 'string', choices: ['none', 'table', 'json'], default: 'none' })
     .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' })
     .option('output', { type: 'string', describe: 'Write JSON output to file' })
     .option('receipt', { type: 'string', describe: 'Generate validation receipt with audit trail' })
-    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
+    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' })
     .option('theme', { type: 'string', describe: 'Apply named theme tokens before validation' })
     .option('breakpoint', { type: 'string' })
     .option('all-breakpoints', { type: 'boolean' })
@@ -70,7 +54,7 @@ cli.command('graph', 'Generate dependency / constraint graph', y => y
     .option('min-severity', { type: 'string', choices: ['warn', 'error'], default: 'warn' })
     .option('focus', { type: 'string' })
     .option('radius', { type: 'number', default: 1 })
-    .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => graphCommand(a));
+    .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }), a => graphCommand(a));
 cli.command('why <tokenId>', 'Explain token provenance', y => y
     .positional('tokenId', { type: 'string', demandOption: true })
     .option('format', { type: 'string', choices: ['json', 'table'], default: 'json' })

package/cli/dcv.ts

@@ -2,28 +2,14 @@
 // Clean minimal DCV CLI entrypoint
 import yargs from 'yargs/yargs';
 import { hideBin } from 'yargs/helpers';
-import { spawnSync } from 'node:child_process';
-import { createRequire } from 'module';
-import path from 'node:path';
 import { type SetOptions, type BuildOptions, type ValidateOptions, type GraphOptions, type WhyOptions, type PatchOptions, type PatchApplyOptions } from './types.js';
 import { setCommand, buildCommand, validateCommand, graphCommand, whyCommand, patchCommand, patchApplyCommand } from './commands/index.js';
 
-// Early intercept: experimental graph diff helper
-(() => {
-  const args = process.argv.slice(2);
-  if (args[0] === 'graph' && args[1] === 'diff') {
-    const pass = args.slice(2);
-    const require = createRequire(import.meta.url);
-    const tsx = (() => { try { return require.resolve('tsx/dist/cli.mjs'); } catch { return path.resolve('node_modules/tsx/dist/cli.mjs'); }})();
-    const r = spawnSync(process.execPath, [tsx, path.resolve('scripts/graph-diff.ts'), ...pass], { stdio: 'inherit', env: process.env });
-    process.exit(r.status ?? 0);
-  }
-})();
-
 const cli = yargs(hideBin(process.argv))
   .scriptName('dcv')
   .parserConfiguration({ 'camel-case-expansion': false })
-  .option('quiet', { type: 'boolean' });
+  .option('quiet', { type: 'boolean' })
+  .option('config', { type: 'string', describe: 'Path to JSON config file' });
 
 cli.command<SetOptions>('set <expressions..>', 'Set token values', y => y
   .positional('expressions', { type: 'string', array: true })
@@ -45,17 +31,19 @@ cli.command<BuildOptions>('build', 'Build token outputs', y => y
   .option('mapper', { type: 'string' })
   .option('theme', { type: 'string' })
   .option('dry-run', { type: 'boolean', default: false })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }),
   a => buildCommand(a)
 );
 
-cli.command<ValidateOptions>('validate', 'Validate constraints', y => y
+cli.command<ValidateOptions>('validate [tokens-path]', 'Validate constraints', y => y
+  .positional('tokens-path', { type: 'string', describe: 'Path to a tokens file (positional alias for --tokens)' })
+  .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files (default: themes)' })
   .option('fail-on', { type: 'string', choices: ['off','warn','error'], default: 'error' })
   .option('summary', { type: 'string', choices: ['none','table','json'], default: 'none' })
   .option('format', { type: 'string', choices: ['text','json'], default: 'text', describe: 'Output format' })
   .option('output', { type: 'string', describe: 'Write JSON output to file' })
   .option('receipt', { type: 'string', describe: 'Generate validation receipt with audit trail' })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
+  .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' })
   .option('theme', { type: 'string', describe: 'Apply named theme tokens before validation' })
   .option('breakpoint', { type: 'string' })
   .option('all-breakpoints', { type: 'boolean' })
@@ -78,7 +66,7 @@ cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y =
   .option('min-severity', { type: 'string', choices: ['warn','error'], default: 'warn' })
   .option('focus', { type: 'string' })
   .option('radius', { type: 'number', default: 1 })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  .option('tokens', { type: 'string', describe: 'Path to a tokens file (defaults to tokens/tokens.example.json)' }),
   a => graphCommand(a)
 );
 

package/cli/json-output.d.ts

@@ -21,6 +21,8 @@ export interface ValidationResult {
     };
     violations: ConstraintViolation[];
     warnings?: ConstraintViolation[];
+    /** Set when tokens were validated but no active constraint referenced any of them. */
+    note?: string;
     stats: {
         durationMs: number;
         engineVersion: string;
@@ -57,7 +59,7 @@ export declare function formatViolation(issue: ConstraintIssue): ConstraintViola
 /**
  * Generate a ValidationResult from collected issues
  */
-export declare function createValidationResult(errors: ConstraintIssue[], warnings: ConstraintIssue[], durationMs: number, engineVersion: string): ValidationResult;
+export declare function createValidationResult(errors: ConstraintIssue[], warnings: ConstraintIssue[], durationMs: number, engineVersion: string, note?: string): ValidationResult;
 /**
  * Generate a ValidationReceipt with full audit trail
  */

package/cli/json-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-output.d.ts","sourceRoot":"","sources":["json-output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,WAAW,EAAE;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,MAAM,EAAE;QACN,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;QACjC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAiB3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,EAAE,EACzB,QAAQ,EAAE,eAAe,EAAE,EAC3B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,gBAAgB,CAoBlB;AAcD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAC/B,iBAAiB,CAoCnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CASxE"}
+{"version":3,"file":"json-output.d.ts","sourceRoot":"","sources":["json-output.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE;QACR,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QACL,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,GAAG,EAAE;QACH,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED,MAAM,WAAW,iBAAkB,SAAQ,gBAAgB;IACzD,WAAW,EAAE;QACX,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,MAAM,EAAE;QACN,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;QACjC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,GAAG,mBAAmB,CAsB3E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,EAAE,EACzB,QAAQ,EAAE,eAAe,EAAE,EAC3B,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,gBAAgB,CAqBlB;AAcD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAC/B,iBAAiB,CAoCnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CASxE"}

package/cli/json-output.js

@@ -11,19 +11,25 @@ export function formatViolation(issue) {
         level: issue.level === 'error' ? 'error' : 'warn',
         message: issue.message,
     };
-    if (issue.id) {
+    if (issue.involvedTokens?.length) {
+        violation.nodes = issue.involvedTokens;
+    }
+    else if (issue.id) {
         violation.nodes = [issue.id];
     }
     // Add context from where field or other metadata
-    if (issue.where) {
-        violation.context = { where: issue.where };
+    if (issue.where || issue.metadata) {
+        violation.context = {
+            ...(issue.where ? { where: issue.where } : {}),
+            ...(issue.metadata ?? {}),
+        };
     }
     return violation;
 }
 /**
  * Generate a ValidationResult from collected issues
  */
-export function createValidationResult(errors, warnings, durationMs, engineVersion) {
+export function createValidationResult(errors, warnings, durationMs, engineVersion, note) {
     const violations = errors.map(formatViolation);
     const warningViolations = warnings.map(formatViolation);
     return {
@@ -35,6 +41,7 @@ export function createValidationResult(errors, warnings, durationMs, engineVersi
         },
         violations,
         warnings: warningViolations.length > 0 ? warningViolations : undefined,
+        note,
         stats: {
             durationMs: Math.round(durationMs),
             engineVersion,

package/cli/json-output.ts

@@ -27,6 +27,8 @@ export interface ValidationResult {
   };
   violations: ConstraintViolation[];
   warnings?: ConstraintViolation[];
+  /** Set when tokens were validated but no active constraint referenced any of them. */
+  note?: string;
   stats: {
     durationMs: number;
     engineVersion: string;
@@ -68,13 +70,18 @@ export function formatViolation(issue: ConstraintIssue): ConstraintViolation {
     message: issue.message,
   };
 
-  if (issue.id) {
+  if (issue.involvedTokens?.length) {
+    violation.nodes = issue.involvedTokens;
+  } else if (issue.id) {
     violation.nodes = [issue.id];
   }
 
   // Add context from where field or other metadata
-  if (issue.where) {
-    violation.context = { where: issue.where };
+  if (issue.where || issue.metadata) {
+    violation.context = {
+      ...(issue.where ? { where: issue.where } : {}),
+      ...(issue.metadata ?? {}),
+    };
   }
 
   return violation;
@@ -87,7 +94,8 @@ export function createValidationResult(
   errors: ConstraintIssue[],
   warnings: ConstraintIssue[],
   durationMs: number,
-  engineVersion: string
+  engineVersion: string,
+  note?: string
 ): ValidationResult {
   const violations = errors.map(formatViolation);
   const warningViolations = warnings.map(formatViolation);
@@ -101,6 +109,7 @@ export function createValidationResult(
     },
     violations,
     warnings: warningViolations.length > 0 ? warningViolations : undefined,
+    note,
     stats: {
       durationMs: Math.round(durationMs),
       engineVersion,

package/cli/types.d.ts

@@ -45,6 +45,8 @@ export interface BuildOptions extends GlobalOptions {
 export interface ValidateOptions extends GlobalOptions {
     strict?: boolean;
     constraints?: string[];
+    'tokens-path'?: string;
+    'constraints-dir'?: string;
     perf?: boolean;
     budgetTotalMs?: number;
     budgetPerBpMs?: number;