design-constraint-validator 2.0.1 → 2.2.0

package/cli/dcv.js

@@ -2,31 +2,22 @@
 // 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);
-    }
-})();
+import { getVersionInfo } from './version-banner.js';
 const cli = yargs(hideBin(process.argv))
     .scriptName('dcv')
+    // camel-case-expansion is intentionally OFF, so the CLI delivers flags only
+    // under their kebab key (e.g. argv['dry-run'], never argv.dryRun). Commands
+    // read BOTH forms — `options['dry-run'] ?? options.dryRun` — so the same handler
+    // works whether invoked by the CLI (kebab) or programmatically/tests (camelCase).
+    // Reading only one form silently no-ops for the other caller (TASK-024).
     .parserConfiguration({ 'camel-case-expansion': false })
-    .option('quiet', { type: 'boolean' });
-cli.command('set <expressions..>', 'Set token values', y => y
+    .option('quiet', { type: 'boolean' })
+    .option('config', { type: 'string', describe: 'Path to JSON config file' });
+// `[expressions..]` is OPTIONAL: batch mode (--json / `-` stdin) and unset-only
+// mode (--unset) take no positional, and a mandatory positional made yargs abort
+// before the handler (TASK-032).
+cli.command('set [expressions..]', 'Set token values', y => y
     .positional('expressions', { type: 'string', array: true })
     .option('dry-run', { type: 'boolean', default: false })
     .option('write', { type: 'boolean' })
@@ -35,6 +26,7 @@ cli.command('set <expressions..>', 'Set token values', y => y
     .option('format', { type: 'string', choices: ['json', 'css', 'js'], default: 'json' })
     .option('output', { type: 'string' })
     .option('theme', { type: 'string' })
+    .option('debug-set', { type: 'boolean', hidden: true }) // hidden debug aid (also DCV_DEBUG_SET=1)
     .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => setCommand(a));
 cli.command('build', 'Build token outputs', y => y
     .option('format', { type: 'string', choices: ['css', 'json', 'js'], default: 'css' })
@@ -43,17 +35,20 @@ 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' })
+    .option('cross-axis-debug', { type: 'boolean', hidden: true }) // hidden debug aid
     .option('perf', { type: 'boolean', describe: 'Print timing info' })
     .option('budget-total-ms', { type: 'number', describe: 'Fail if total validation exceeds this (ms)' })
     .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }), a => validateCommand(a));
@@ -61,6 +56,10 @@ cli.command('graph', 'Generate dependency / constraint graph', y => y
     .option('format', { type: 'string', choices: ['json', 'mermaid', 'dot', 'svg', 'png'], default: 'json' })
     .option('bundle', { type: 'boolean', describe: 'When used with --hasse export mermaid+dot (+image if svg/png requested)' })
     .option('hasse', { type: 'string' })
+    .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files (default: themes). Used with --hasse.' })
+    .option('filter', { type: 'string', describe: 'Filter dependency-graph edges by regex (matches either endpoint)' })
+    .option('breakpoint', { type: 'string', choices: ['sm', 'md', 'lg'] })
+    .option('all-breakpoints', { type: 'boolean' })
     .option('filter-prefix', { type: 'string' })
     .option('exclude-prefix', { type: 'string' })
     .option('only-violations', { type: 'boolean' })
@@ -68,12 +67,15 @@ cli.command('graph', 'Generate dependency / constraint graph', y => y
     .option('label-violations', { type: 'boolean' })
     .option('label-truncate', { type: 'number', default: 0 })
     .option('min-severity', { type: 'string', choices: ['warn', 'error'], default: 'warn' })
+    .option('violation-color', { type: 'string', describe: 'Hex color for highlighted violations (default: #ff2d55)' })
+    .option('image-from', { type: 'string', choices: ['mermaid', 'dot'], describe: 'Source format for svg/png export (default: mermaid)' })
     .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' })
+    .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files for the constraint summary (default: themes)' })
     .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }), a => whyCommand(a));
 cli.command('patch', 'Export patch (diff) from overrides', y => y
     .option('overrides', { type: 'string', describe: 'Path or inline JSON of flat overrides' })
@@ -85,6 +87,10 @@ cli.command('patch:apply <patch>', 'Apply patch document to tokens', y => y
     .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
     .option('output', { type: 'string', describe: 'Write updated tokens to this file' })
     .option('dry-run', { type: 'boolean', default: false }), a => patchApplyCommand(a));
+// Wire `--version` to the real package version (same source as the banner).
+// Without this, yargs can't locate package.json from the installed bin and
+// prints "unknown" (TASK-021 release smoke-test finding).
+cli.version(getVersionInfo().version);
 cli.help().alias('h', 'help').strict().wrap(cli.terminalWidth());
 cli.parse();
 // EOF

package/cli/dcv.ts

@@ -2,30 +2,25 @@
 // 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);
-  }
-})();
+import { getVersionInfo } from './version-banner.js';
 
 const cli = yargs(hideBin(process.argv))
   .scriptName('dcv')
+  // camel-case-expansion is intentionally OFF, so the CLI delivers flags only
+  // under their kebab key (e.g. argv['dry-run'], never argv.dryRun). Commands
+  // read BOTH forms — `options['dry-run'] ?? options.dryRun` — so the same handler
+  // works whether invoked by the CLI (kebab) or programmatically/tests (camelCase).
+  // Reading only one form silently no-ops for the other caller (TASK-024).
   .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
+// `[expressions..]` is OPTIONAL: batch mode (--json / `-` stdin) and unset-only
+// mode (--unset) take no positional, and a mandatory positional made yargs abort
+// before the handler (TASK-032).
+cli.command<SetOptions>('set [expressions..]', 'Set token values', y => y
   .positional('expressions', { type: 'string', array: true })
   .option('dry-run', { type: 'boolean', default: false })
   .option('write', { type: 'boolean' })
@@ -34,6 +29,7 @@ cli.command<SetOptions>('set <expressions..>', 'Set token values', y => y
   .option('format', { type: 'string', choices: ['json','css','js'], default: 'json' })
   .option('output', { type: 'string' })
   .option('theme', { type: 'string' })
+  .option('debug-set', { type: 'boolean', hidden: true }) // hidden debug aid (also DCV_DEBUG_SET=1)
   .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
   a => setCommand(a)
 );
@@ -45,20 +41,23 @@ 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' })
+  .option('cross-axis-debug', { type: 'boolean', hidden: true }) // hidden debug aid
   .option('perf', { type: 'boolean', describe: 'Print timing info' })
   .option('budget-total-ms', { type: 'number', describe: 'Fail if total validation exceeds this (ms)' })
   .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }),
@@ -69,6 +68,10 @@ cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y =
   .option('format', { type: 'string', choices: ['json','mermaid','dot','svg','png'], default: 'json' })
   .option('bundle', { type: 'boolean', describe: 'When used with --hasse export mermaid+dot (+image if svg/png requested)' })
   .option('hasse', { type: 'string' })
+  .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files (default: themes). Used with --hasse.' })
+  .option('filter', { type: 'string', describe: 'Filter dependency-graph edges by regex (matches either endpoint)' })
+  .option('breakpoint', { type: 'string', choices: ['sm','md','lg'] })
+  .option('all-breakpoints', { type: 'boolean' })
   .option('filter-prefix', { type: 'string' })
   .option('exclude-prefix', { type: 'string' })
   .option('only-violations', { type: 'boolean' })
@@ -76,15 +79,18 @@ cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y =
   .option('label-violations', { type: 'boolean' })
   .option('label-truncate', { type: 'number', default: 0 })
   .option('min-severity', { type: 'string', choices: ['warn','error'], default: 'warn' })
+  .option('violation-color', { type: 'string', describe: 'Hex color for highlighted violations (default: #ff2d55)' })
+  .option('image-from', { type: 'string', choices: ['mermaid','dot'], describe: 'Source format for svg/png export (default: mermaid)' })
   .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)
 );
 
 cli.command<WhyOptions>('why <tokenId>', 'Explain token provenance', y => y
   .positional('tokenId', { type: 'string', demandOption: true })
   .option('format', { type: 'string', choices: ['json','table'], default: 'json' })
+  .option('constraints-dir', { type: 'string', describe: 'Directory holding order / cross-axis constraint files for the constraint summary (default: themes)' })
   .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
   a => whyCommand(a)
 );
@@ -105,6 +111,10 @@ cli.command<PatchApplyOptions>('patch:apply <patch>', 'Apply patch document to t
   a => patchApplyCommand(a)
 );
 
+// Wire `--version` to the real package version (same source as the banner).
+// Without this, yargs can't locate package.json from the installed bin and
+// prints "unknown" (TASK-021 release smoke-test finding).
+cli.version(getVersionInfo().version);
 cli.help().alias('h','help').strict().wrap(cli.terminalWidth());
 cli.parse();
 

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

@@ -32,6 +32,8 @@ export interface SetOptions extends GlobalOptions {
     write?: boolean;
     json?: string;
     unset?: string[];
+    dryRun?: boolean;
+    'dry-run'?: boolean;
 }
 export interface BuildOptions extends GlobalOptions {
     output?: string;
@@ -40,40 +42,49 @@ export interface BuildOptions extends GlobalOptions {
     theme?: string;
     mapper?: string;
     dryRun?: boolean;
+    'dry-run'?: boolean;
     allFormats?: boolean;
+    'all-formats'?: boolean;
 }
 export interface ValidateOptions extends GlobalOptions {
     strict?: boolean;
     constraints?: string[];
+    'tokens-path'?: string;
+    'constraints-dir'?: string;
     perf?: boolean;
     budgetTotalMs?: number;
+    'budget-total-ms'?: number;
     budgetPerBpMs?: number;
+    'budget-per-bp-ms'?: number;
     format?: 'text' | 'json';
     output?: string;
     receipt?: string;
     failOn?: 'off' | 'warn' | 'error';
+    'fail-on'?: 'off' | 'warn' | 'error';
     summary?: 'none' | 'table' | 'json';
 }
 export interface GraphOptions extends GlobalOptions {
     output?: string;
+    'constraints-dir'?: string;
     format?: 'dot' | 'mermaid' | 'json' | 'svg' | 'png';
-    imageFrom?: 'mermaid' | 'dot';
     filter?: string;
     hasse?: string;
-    filterPrefix?: string;
-    excludePrefix?: string;
-    onlyViolations?: boolean;
-    highlightViolations?: boolean;
-    violationColor?: string;
-    labelViolations?: boolean;
-    labelTruncate?: number;
-    minSeverity?: 'warn' | 'error';
+    'image-from'?: 'mermaid' | 'dot';
+    'filter-prefix'?: string;
+    'exclude-prefix'?: string;
+    'only-violations'?: boolean;
+    'highlight-violations'?: boolean;
+    'violation-color'?: string;
+    'label-violations'?: boolean;
+    'label-truncate'?: number;
+    'min-severity'?: 'warn' | 'error';
     focus?: string;
     radius?: number;
     tokens?: string;
 }
 export interface WhyOptions extends GlobalOptions {
     tokenId: string;
+    'constraints-dir'?: string;
     format?: 'json' | 'table';
 }
 export interface PatchOptions extends GlobalOptions {
@@ -87,6 +98,7 @@ export interface PatchApplyOptions extends GlobalOptions {
     output?: string;
     tokens?: string;
     dryRun?: boolean;
+    'dry-run'?: boolean;
 }
 export type { Breakpoint };
 //# sourceMappingURL=types.d.ts.map

package/cli/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"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"}

package/cli/types.ts

@@ -25,6 +25,10 @@ export interface SetOptions extends GlobalOptions {
   write?: boolean;
   json?: string;
   unset?: string[];
+  // CLI delivers the kebab key (camel-case-expansion off); programmatic callers
+  // pass camelCase. Commands read both (TASK-024).
+  dryRun?: boolean;
+  'dry-run'?: boolean;
 }
 export interface BuildOptions extends GlobalOptions {
   output?: string;
@@ -33,40 +37,50 @@ export interface BuildOptions extends GlobalOptions {
   theme?: string;
   mapper?: string;
   dryRun?: boolean;
+  'dry-run'?: boolean;
   allFormats?: boolean;
+  'all-formats'?: boolean;
 }
 export interface ValidateOptions extends GlobalOptions {
   strict?: boolean;
   constraints?: string[];
+  'tokens-path'?: string;
+  'constraints-dir'?: string;
   perf?: boolean;
   budgetTotalMs?: number;
+  'budget-total-ms'?: number;
   budgetPerBpMs?: number;
+  'budget-per-bp-ms'?: number;
   format?: 'text' | 'json';
   output?: string;
   receipt?: string;
   failOn?: 'off' | 'warn' | 'error';
+  'fail-on'?: 'off' | 'warn' | 'error';
   summary?: 'none' | 'table' | 'json';
 }
 export interface GraphOptions extends GlobalOptions {
   output?: string;
+  'constraints-dir'?: string;
   format?: 'dot' | 'mermaid' | 'json' | 'svg' | 'png';
-  imageFrom?: 'mermaid' | 'dot';
   filter?: string;
   hasse?: string;
-  filterPrefix?: string;
-  excludePrefix?: string;
-  onlyViolations?: boolean;
-  highlightViolations?: boolean;
-  violationColor?: string;
-  labelViolations?: boolean;
-  labelTruncate?: number;
-  minSeverity?: 'warn' | 'error';
+  // Kebab keys: the CLI parser runs with camel-case-expansion off.
+  'image-from'?: 'mermaid' | 'dot';
+  'filter-prefix'?: string;
+  'exclude-prefix'?: string;
+  'only-violations'?: boolean;
+  'highlight-violations'?: boolean;
+  'violation-color'?: string;
+  'label-violations'?: boolean;
+  'label-truncate'?: number;
+  'min-severity'?: 'warn' | 'error';
   focus?: string;
   radius?: number;
   tokens?: string;
 }
 export interface WhyOptions extends GlobalOptions {
   tokenId: string;
+  'constraints-dir'?: string;
   format?: 'json' | 'table';
 }
 export interface PatchOptions extends GlobalOptions {
@@ -79,6 +93,7 @@ export interface PatchApplyOptions extends GlobalOptions {
   patch: string; // path or inline patch JSON
   output?: string; // where to write updated tokens (if omitted, prints result)
   tokens?: string; // source tokens file (baseline)
-  dryRun?: boolean; // if true do not write
+  dryRun?: boolean; // if true do not write (programmatic callers)
+  'dry-run'?: boolean; // CLI key (camel-case-expansion off)
 }
 export type { Breakpoint };

package/cli/validate-api.d.ts

@@ -0,0 +1,40 @@
+import { type TokenNode } from '../core/flatten.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import { type ConstraintViolation } from './json-output.js';
+import type { DcvConfig } from './types.js';
+export interface ValidateInput {
+    /** Inline tokens object (DTCG-style `$value`/`$type`). Takes precedence over `tokensPath`. */
+    tokens?: TokenNode;
+    /** Path to a tokens file. Used when `tokens` is not provided. */
+    tokensPath?: string;
+    /** Inline constraints config (the `constraints` block of dcv.config.json). Takes precedence over `configPath`. */
+    constraints?: DcvConfig['constraints'];
+    /** Path to a config file. When neither `constraints` nor `configPath` is given, a dcv.config.* in cwd is discovered. */
+    configPath?: string;
+    /** Directory holding order / cross-axis constraint files. Defaults to `themes`. */
+    constraintsDir?: string;
+    /** Optional breakpoint, selecting `<axis>.<bp>.order.json` / cross-axis variants. */
+    breakpoint?: Breakpoint;
+}
+export interface ValidateResult {
+    /** True when there are no error-level violations. */
+    ok: boolean;
+    counts: {
+        checked: number;
+        violations: number;
+        warnings: number;
+    };
+    violations: ConstraintViolation[];
+    warnings: ConstraintViolation[];
+    /** Set when tokens were validated but no active constraint referenced any of them. */
+    note?: string;
+}
+/**
+ * Validate a token set against constraints and return structured results.
+ *
+ * Unlike the CLI, this treats `tokens` / `tokensPath` as the complete token set
+ * (no implicit cwd token overrides), so it is safe to call from a server that
+ * cannot share a filesystem with the caller.
+ */
+export declare function validate(input?: ValidateInput): ValidateResult;
+//# sourceMappingURL=validate-api.d.ts.map

package/cli/validate-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-api.d.ts","sourceRoot":"","sources":["validate-api.ts"],"names":[],"mappings":"AAYA,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,oBAAoB,CAAC;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAIzD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kHAAkH;IAClH,WAAW,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACvC,wHAAwH;IACxH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA6BD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,GAAE,aAAkB,GAAG,cAAc,CAkDlE"}