design-constraint-validator 1.1.0 → 2.1.0

package/README.md

@@ -6,6 +6,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/design-constraint-validator.svg)](https://www.npmjs.com/package/design-constraint-validator)
 [![CI](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/ci.yml)
 [![SBOM](https://img.shields.io/badge/SBOM-CycloneDX-brightgreen)](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/sbom.yml)
+[![Supply Chain Security](https://img.shields.io/badge/security-hardened-blue)](SECURITY.md)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.x-339933.svg)](#)
 
@@ -35,28 +36,54 @@ npx dcv --help
 
 ## Quick Start
 
+DCV validates **your** tokens against **your** constraints. From an empty directory:
+
 ```bash
-# Validate tokens with default constraints
-npx dcv validate ./tokens/tokens.json
+# 1. Your design tokens (DTCG-style "$value")
+cat > tokens.json <<'JSON'
+{
+  "color": {
+    "text": { "$value": "#888888" },
+    "bg":   { "$value": "#999999" }
+  }
+}
+JSON
+
+# 2. Your constraints — auto-discovered as dcv.config.json in the cwd
+cat > dcv.config.json <<'JSON'
+{
+  "constraints": {
+    "enableBuiltInWcagDefaults": false,
+    "enableBuiltInThreshold": false,
+    "wcag": [
+      { "foreground": "color.text", "background": "color.bg", "ratio": 4.5, "description": "Body text on background" }
+    ]
+  }
+}
+JSON
+
+# 3. Validate (positional path or --tokens; exits non-zero on violations)
+npx dcv validate tokens.json --summary table
 
-# Explain failures
-npx dcv why --format table
+# Explain one token (the tokenId is required)
+npx dcv why color.text --tokens tokens.json --format table
 
-# Export dependency graph
-npx dcv graph --format mermaid > graph.mmd
+# Export the dependency graph
+npx dcv graph --tokens tokens.json --format mermaid > graph.mmd
 ```
 
-**Example Output:**
+**Example output** (`validate`):
 
-```
-Constraint                    Status   Details
-────────────────────────────  ──────   ─────────────────────────────────────────────
-WCAG Contrast ≥ 4.5:1        FAIL     text.primary(#5A5A5A) on bg.body(#F5F5F5) ⇒ 3.8
-Typography monotonic scale   FAIL     h3(22) < body(18) < h2(21) < h1(34)  ✖ out-of-order: h2<h3
-Cross-axis (weight vs size)  PASS     all headings satisfy min weight for size bucket
-Exit code: 1 (violations found)
+```text
+validate: 1 error(s), 0 warning(s)
+ERROR wcag-contrast  color.text|color.bg @ Body text on background — Contrast 1.24:1 < 4.5:1
+scope   rules  warnings  errors
+------  -----  --------  ------
+global  1      0         1
 ```
 
+Exit code is `1` when violations are found, `0` when clean (use `--fail-on off` to always exit `0`). The built-in WCAG/threshold defaults target the bundled example token ids, so disable them (as above) when validating your own token names.
+
 ---
 
 ## Programmatic API
@@ -64,14 +91,15 @@ Exit code: 1 (violations found)
 ```ts
 import { validate } from 'design-constraint-validator';
 
-const result = await validate({
-  tokensPath: './tokens/tokens.json',
-  policyPath: './themes/policies/aa.json'
+// Synchronous. Point at files, or pass `tokens` / `constraints` inline.
+const result = validate({
+  tokensPath: './tokens.json',
+  configPath: './dcv.config.json', // omit to auto-discover dcv.config.json in the cwd
 });
 
 if (!result.ok) {
   for (const v of result.violations) {
-    console.log(`[${v.kind}] ${v.message}`, v.context);
+    console.log(`[${v.ruleId}] ${v.message}`);
   }
   process.exitCode = 1;
 }
@@ -81,6 +109,31 @@ See **[API Reference](docs/API.md)** for complete programmatic usage.
 
 ---
 
+## Use from AI agents (MCP)
+
+DCV ships a second binary, `dcv-mcp`, that exposes the validator over MCP stdio for agent clients. Add it to a Claude Desktop or generic MCP client config like this:
+
+```json
+{
+  "mcpServers": {
+    "dcv": {
+      "command": "npx",
+      "args": ["-y", "--package", "design-constraint-validator", "dcv-mcp"]
+    }
+  }
+}
+```
+
+The server exposes exactly three JSON-returning tools:
+
+- `validate` - validate inline `tokens` or a `tokensPath` against inline `constraints` or a config file.
+- `why` - explain provenance, aliases, dependencies, dependents, and alias chain for one token id.
+- `graph` - return token dependency `nodes` and `edges`.
+
+Tool failures are returned as structured JSON: `{ "ok": false, "error": { "code": "...", "message": "..." } }`.
+
+---
+
 ## Documentation
 
 ### For Everyone
@@ -103,6 +156,7 @@ See **[API Reference](docs/API.md)** for complete programmatic usage.
 - **[Prior Art / Method](docs/prior-art/)** - Design rationale (Decision Themes, receipts)
 - **[AI Guide](docs/AI-GUIDE.md)** - Using DCV with ChatGPT/Claude/Copilot
 - **[Contributing](CONTRIBUTING.md)** - Contribution guidelines
+- **[Security](SECURITY.md)** - Supply chain security measures
 
 ---
 
@@ -140,12 +194,26 @@ Adapters normalize common ecosystems:
 
 - **Style Dictionary** - See [examples/style-dictionary/](examples/style-dictionary/)
 - **Tokens Studio JSON** - See [examples/tokens-studio/](examples/tokens-studio/)
-- **DTCG** (Design Tokens Community Group) - See [examples/dtcg/](examples/dtcg/)
+- **DTCG** (Design Tokens Community Group) — reads the **2025.10 stable spec** (structured sRGB colors, structured dimensions, `{alias}` references, `$extensions` passthrough; non-sRGB spaces warn rather than mis-calculate; composite types out of scope). See [examples/dtcg/](examples/dtcg/)
 
 Full adapter documentation: **[Adapters](docs/Adapters.md)**
 
 ---
 
+## DCV & DecisionThemes
+
+DCV is the **standalone validation engine** — use it for any token system.
+
+**DecisionThemes** (coming 2026) is a complete design system framework built on DCV:
+- **5-axis decision model** (Tone, Emphasis, Size, Density, Shape)
+- **VT/DT pipeline** (Value Themes + Decision Themes → deterministic CSS configs)
+- **Studio UI** + **Hub marketplace** for sharing Decision Systems
+
+DCV powers DecisionThemes' validation layer — but works perfectly standalone.
+Preview: [www.decisionthemes.com](https://www.decisionthemes.com)
+
+---
+
 ## Method & Prior Art
 
 The Design Constraint Validator engine is based on a theming and validation method published as **defensive prior art**.
@@ -166,7 +234,8 @@ These documents keep the method openly implementable and prevent patent lock-up.
 DCV generates CycloneDX-compliant SBOMs for supply chain transparency:
 
 - **CI Builds:** SBOM artifacts on every CI run (90-day retention)
-- **Releases:** SBOM files (JSON + XML) attached to GitHub releases
+- **Version tags:** SBOM artifacts for release tags
+- **GitHub Releases:** SBOM files (JSON + XML) attached when a GitHub Release is created
 - **Manual:** Run `npx @cyclonedx/cyclonedx-npm` in project root
 
 **Download:**
@@ -180,7 +249,7 @@ DCV generates CycloneDX-compliant SBOMs for supply chain transparency:
 - Plugin API for **custom constraints**
 - **VS Code** diagnostics (inline explain)
 - **Cross-axis packs** (typography × weight × contrast)
-- **Receipts & provenance** (hashes, signable reports)
+- **Signed / attestable receipts** — `dcv validate --receipt` already emits environment + input content hashes today; cryptographic **signing** is the roadmap part
 - UI graph explorer (node inspector, violations focus)
 
 ---

package/adapters/decisionthemes.d.ts

@@ -0,0 +1,44 @@
+/**
+ * DecisionThemes Adapter (Placeholder)
+ *
+ * This adapter will integrate with the DecisionThemes framework (coming 2026).
+ * It transforms VT (Value Themes) + DT (Decision Themes) into flat tokens for DCV validation.
+ *
+ * @see https://www.decisionthemes.com
+ * @see docs/Adapters.md for implementation details
+ *
+ * @example
+ * ```typescript
+ * import { decisionthemesAdapter } from './adapters/decisionthemes.js';
+ *
+ * const { tokens, policy } = decisionthemesAdapter({
+ *   vt: { ... }, // Value Themes (raw values)
+ *   dt: { ... }  // Decision Themes (formulas)
+ * });
+ *
+ * // tokens = flat token object for DCV validation
+ * // policy = auto-generated constraints from 5-axis model
+ * ```
+ */
+export interface VT {
+    [key: string]: any;
+}
+export interface DT {
+    [key: string]: any;
+}
+export interface DecisionThemesInput {
+    vt: VT;
+    dt: DT;
+}
+export interface DecisionThemesOutput {
+    tokens: Record<string, any>;
+    policy?: string;
+}
+/**
+ * Transform DecisionThemes (VT+DT) into DCV-compatible tokens
+ *
+ * @param input - VT (values) + DT (decisions)
+ * @returns Flat tokens + optional policy JSON
+ */
+export declare function decisionthemesAdapter(_input: DecisionThemesInput): DecisionThemesOutput;
+//# sourceMappingURL=decisionthemes.d.ts.map

package/adapters/decisionthemes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisionthemes.d.ts","sourceRoot":"","sources":["decisionthemes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,EAAE;IAEjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,EAAE;IAEjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,EAAE,CAAC;IACP,EAAE,EAAE,EAAE,CAAC;CACR;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,mBAAmB,GAAG,oBAAoB,CASvF"}

package/adapters/decisionthemes.js

@@ -0,0 +1,35 @@
+/**
+ * DecisionThemes Adapter (Placeholder)
+ *
+ * This adapter will integrate with the DecisionThemes framework (coming 2026).
+ * It transforms VT (Value Themes) + DT (Decision Themes) into flat tokens for DCV validation.
+ *
+ * @see https://www.decisionthemes.com
+ * @see docs/Adapters.md for implementation details
+ *
+ * @example
+ * ```typescript
+ * import { decisionthemesAdapter } from './adapters/decisionthemes.js';
+ *
+ * const { tokens, policy } = decisionthemesAdapter({
+ *   vt: { ... }, // Value Themes (raw values)
+ *   dt: { ... }  // Decision Themes (formulas)
+ * });
+ *
+ * // tokens = flat token object for DCV validation
+ * // policy = auto-generated constraints from 5-axis model
+ * ```
+ */
+/**
+ * Transform DecisionThemes (VT+DT) into DCV-compatible tokens
+ *
+ * @param input - VT (values) + DT (decisions)
+ * @returns Flat tokens + optional policy JSON
+ */
+export function decisionthemesAdapter(_input) {
+    // TODO: Implement when DecisionThemes integration is ready
+    // This will call the DecisionThemes resolver/compute engine to process _input
+    throw new Error('DecisionThemes adapter not yet implemented. ' +
+        'This is a placeholder for future integration with the DecisionThemes framework. ' +
+        'See https://www.decisionthemes.com for updates.');
+}

package/adapters/decisionthemes.ts

@@ -0,0 +1,59 @@
+/**
+ * DecisionThemes Adapter (Placeholder)
+ *
+ * This adapter will integrate with the DecisionThemes framework (coming 2026).
+ * It transforms VT (Value Themes) + DT (Decision Themes) into flat tokens for DCV validation.
+ *
+ * @see https://www.decisionthemes.com
+ * @see docs/Adapters.md for implementation details
+ *
+ * @example
+ * ```typescript
+ * import { decisionthemesAdapter } from './adapters/decisionthemes.js';
+ *
+ * const { tokens, policy } = decisionthemesAdapter({
+ *   vt: { ... }, // Value Themes (raw values)
+ *   dt: { ... }  // Decision Themes (formulas)
+ * });
+ *
+ * // tokens = flat token object for DCV validation
+ * // policy = auto-generated constraints from 5-axis model
+ * ```
+ */
+
+export interface VT {
+  // Value Themes - raw design values
+  [key: string]: any;
+}
+
+export interface DT {
+  // Decision Themes - formulas and decision mappings
+  [key: string]: any;
+}
+
+export interface DecisionThemesInput {
+  vt: VT;
+  dt: DT;
+}
+
+export interface DecisionThemesOutput {
+  tokens: Record<string, any>;
+  policy?: string;
+}
+
+/**
+ * Transform DecisionThemes (VT+DT) into DCV-compatible tokens
+ *
+ * @param input - VT (values) + DT (decisions)
+ * @returns Flat tokens + optional policy JSON
+ */
+export function decisionthemesAdapter(_input: DecisionThemesInput): DecisionThemesOutput {
+  // TODO: Implement when DecisionThemes integration is ready
+  // This will call the DecisionThemes resolver/compute engine to process _input
+
+  throw new Error(
+    'DecisionThemes adapter not yet implemented. ' +
+    'This is a placeholder for future integration with the DecisionThemes framework. ' +
+    'See https://www.decisionthemes.com for updates.'
+  );
+}

package/cli/commands/build.js

@@ -6,7 +6,7 @@ import { emitJSON } from '../../adapters/json.js';
 import { emitJS } from '../../adapters/js.js';
 export async function buildCommand(options) {
     const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-    const tokens = loadTokensWithBreakpoint();
+    const tokens = loadTokensWithBreakpoint(undefined, options.tokens);
     const { flat } = flattenTokens(tokens);
     let allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, t.value]));
     if (options.theme) {

package/cli/commands/build.ts

@@ -8,7 +8,7 @@ import type { BuildOptions } from '../types.js';
 
 export async function buildCommand(options: BuildOptions & { [k: string]: any }): Promise<void> {
   const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-  const tokens = loadTokensWithBreakpoint();
+  const tokens = loadTokensWithBreakpoint(undefined, options.tokens);
   const { flat } = flattenTokens(tokens);
   let allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, (t as FlatToken).value]));
   if (options.theme) {

package/cli/commands/graph.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { flattenTokens } from '../../core/flatten.js';
 import { exportGraphImage } from '../../core/image-export.js';
-import { attachRuntimeConstraints } from '../constraints-loader.js';
+import { setupConstraints } from '../constraint-registry.js';
 import { loadConfig } from '../config.js';
 // Local helper for non-poset dependency graphs
 function generateDependencyGraph(edges, format) {
@@ -100,7 +100,7 @@ export async function graphCommand(options) {
                 let edgeLabels;
                 if (onlyViolations || highlightViolations || labelViolations) {
                     const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-                    const tokens = loadTokensWithBreakpoint(breakpoint);
+                    const tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
                     const { flattenTokens } = await import('../../core/flatten.js');
                     const { Engine } = await import('../../core/engine.js');
                     const { MonotonicPlugin, parseSize } = await import('../../core/constraints/monotonic.js');
@@ -127,7 +127,7 @@ export async function graphCommand(options) {
                     if (cfgRes.ok) {
                         const config = cfgRes.value;
                         const knownIds = new Set(Object.keys(flat));
-                        attachRuntimeConstraints(engine, { config, knownIds, bp: breakpoint });
+                        setupConstraints(engine, { config, bp: breakpoint }, { knownIds });
                         const runtimeIssues = engine.evaluate(allIdsInHasse);
                         issues.push(...runtimeIssues);
                     }
@@ -211,7 +211,7 @@ export async function graphCommand(options) {
     }
     for (const breakpoint of plan) {
         const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-        const tokens = loadTokensWithBreakpoint(breakpoint);
+        const tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
         const { edges } = flattenTokens(tokens);
         let filteredEdges = edges;
         if (options.filter) {

package/cli/commands/graph.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import type { GraphOptions } from '../types.js';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
 import { exportGraphImage } from '../../core/image-export.js';
-import { attachRuntimeConstraints } from '../constraints-loader.js';
+import { setupConstraints } from '../constraint-registry.js';
 import { loadConfig } from '../config.js';
 
 // Local helper for non-poset dependency graphs
@@ -69,7 +69,7 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
         let highlight: { nodes: Set<string>; edges: Set<string>; color?: string } | undefined; let edgeLabels: Map<string,string> | undefined;
         if (onlyViolations || highlightViolations || labelViolations) {
           const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-          const tokens = loadTokensWithBreakpoint(breakpoint);
+          const tokens = loadTokensWithBreakpoint(breakpoint, options.tokens);
           const { flattenTokens } = await import('../../core/flatten.js');
           const { Engine } = await import('../../core/engine.js');
           const { MonotonicPlugin, parseSize } = await import('../../core/constraints/monotonic.js');
@@ -98,7 +98,7 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
           if (cfgRes.ok) {
             const config = cfgRes.value;
             const knownIds = new Set(Object.keys(flat as Record<string, FlatToken>));
-            attachRuntimeConstraints(engine, { config, knownIds, bp: breakpoint });
+            setupConstraints(engine, { config, bp: breakpoint }, { knownIds });
             const runtimeIssues = engine.evaluate(allIdsInHasse);
             issues.push(...runtimeIssues);
           }
@@ -170,7 +170,7 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
     return; }
   for (const breakpoint of plan) {
     const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-    const tokens = loadTokensWithBreakpoint(breakpoint); const { edges } = flattenTokens(tokens);
+    const tokens = loadTokensWithBreakpoint(breakpoint, options.tokens); const { edges } = flattenTokens(tokens);
     let filteredEdges = edges;
     if (options.filter) { const filterRegex = new RegExp(options.filter); filteredEdges = edges.filter(([from,to]) => filterRegex.test(from) || filterRegex.test(to)); }
     const format = options.format || 'json'; const graph = generateDependencyGraph(filteredEdges, 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;AAMnD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAoK9E"}
+{"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"}

package/cli/commands/validate.js

@@ -5,8 +5,11 @@ import { parseBreakpoints, loadTokensWithBreakpoint, mergeTokens } from '../../c
 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 { setupConstraints, collectReferencedIds } from '../constraint-registry.js';
+import { printVersionBanner } from '../version-banner.js';
 export async function validateCommand(_options) {
+    // Show version banner (subtle, dimmed)
+    printVersionBanner({ quiet: _options.format === 'json' });
     try {
         const bps = parseBreakpoints(process.argv);
         const crossAxisDebug = process.argv.includes('--cross-axis-debug');
@@ -14,6 +17,20 @@ export async function validateCommand(_options) {
         let anyErrors = false;
         let totalErrors = 0;
         let totalWarnings = 0;
+        // 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 argv = process.argv.slice(2);
         const failOnIdx = argv.indexOf('--fail-on');
         const failOn = _options.failOn ?? (failOnIdx >= 0 ? argv[failOnIdx + 1] : 'error');
@@ -52,7 +69,7 @@ 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`);
@@ -75,7 +92,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');
@@ -101,6 +131,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 });
@@ -119,11 +157,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

@@ -7,14 +7,31 @@ 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 { setupConstraints, collectReferencedIds } from '../constraint-registry.js';
+import { printVersionBanner } from '../version-banner.js';
 
 export async function validateCommand(_options: ValidateOptions): Promise<void> {
+  // Show version banner (subtle, dimmed)
+  printVersionBanner({ quiet: _options.format === 'json' });
+
   try {
     const bps = parseBreakpoints(process.argv);
     const crossAxisDebug = process.argv.includes('--cross-axis-debug');
     const plan: (Breakpoint | undefined)[] = bps.length ? bps : [undefined];
     let anyErrors = false; let totalErrors = 0; let totalWarnings = 0;
+    // 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 argv = process.argv.slice(2);
     const failOnIdx = argv.indexOf('--fail-on');
     type FailOn = 'off' | 'warn' | 'error';
@@ -52,7 +69,7 @@ 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`);
@@ -75,12 +92,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');
@@ -103,6 +130,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 });
@@ -121,12 +155,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 {