design-constraint-validator 2.0.1 → 2.2.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)](#)
 
@@ -25,38 +26,70 @@ This is **not** a schema linter; it's a **reasoning validator** for values and r
 # Local (recommended)
 npm i -D design-constraint-validator
 
-# One-off run
-npx dcv --help
+# One-off run, no install (the bin name `dcv` belongs to an unrelated package)
+npx design-constraint-validator --help
 ```
 
+After a local install, the shorter `dcv` bin is available (e.g. `npx dcv --help`).
+
 **Requirements:** Node.js ≥ 18.x (ESM)
 
 ---
 
 ## 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
 
-# Explain failures
-npx dcv why --format table
+# 3. Validate (positional path or --tokens; exits non-zero on violations)
+npx design-constraint-validator validate tokens.json --summary table
 
-# Export dependency graph
-npx dcv graph --format mermaid > graph.mmd
+# Explain one token (the tokenId is required)
+npx design-constraint-validator why color.text --tokens tokens.json --format table
+
+# Export the dependency graph
+npx design-constraint-validator graph --tokens tokens.json --format mermaid > graph.mmd
 ```
 
-**Example Output:**
+> These one-offs use the full package name because the bare `dcv` bin name on npm
+> belongs to an unrelated package. After `npm i -D design-constraint-validator`,
+> use the shorter `npx dcv …`.
 
-```
-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)
+**Example output** (`validate`):
+
+```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 +97,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 +115,36 @@ 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 six read-only, 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`.
+- `list-constraints` - enumerate the active constraints (WCAG pairs, thresholds, order/lightness scales, cross-axis) for the given input.
+- `explain` - turn a violation into plain-English text plus machine-readable facts.
+- `suggest-fix` - compute a verified satisfying value for a violation (WCAG color, threshold/monotonic boundary) without writing anything.
+
+The three derivation tools (`list-constraints`, `explain`, `suggest-fix`) stay read-only — they return suggestions; applying them is up to you (`dcv set` / `dcv patch`). See **[AI Guide](docs/AI-GUIDE.md)** for the full agent loop.
+
+Tool failures are returned as structured JSON: `{ "ok": false, "error": { "code": "...", "message": "..." } }`.
+
+---
+
 ## Documentation
 
 ### For Everyone
@@ -103,6 +167,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,7 +205,7 @@ 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)**
 
@@ -180,7 +245,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:**
@@ -194,7 +260,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/cli/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwD9F"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["build.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+D9F"}

package/cli/commands/build.js

@@ -1,21 +1,19 @@
-import { join, dirname, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { flattenTokens } from '../../core/flatten.js';
+import { mergeTokens } from '../../core/breakpoints.js';
 import { valuesToCss } from '../../adapters/css.js';
 import { emitJSON } from '../../adapters/json.js';
 import { emitJS } from '../../adapters/js.js';
+import { loadThemeTokens } from './utils.js';
 export async function buildCommand(options) {
     const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-    const tokens = loadTokensWithBreakpoint();
-    const { flat } = flattenTokens(tokens);
-    let allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, t.value]));
+    let tokens = loadTokensWithBreakpoint(undefined, options.tokens);
     if (options.theme) {
-        const themePath = join('tokens/themes', `${options.theme}.json`);
-        if (existsSync(themePath)) {
-            const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-            Object.assign(allValues, themeTokens);
-        }
+        tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
     }
+    const { flat } = flattenTokens(tokens);
+    const allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, t.value]));
     const format = options.format || 'css';
     const defaultOutput = `dist/tokens.${format}`;
     let manifest;
@@ -34,21 +32,31 @@ export async function buildCommand(options) {
             process.exit(1);
         }
     }
-    const allFormats = options.allFormats ?? options['all-formats'];
+    // Read both the kebab key (CLI, camel-case-expansion is off) and the camelCase
+    // key (programmatic callers, e.g. tests). Reading only one form silently no-ops
+    // for the other caller — that was the TASK-024 bug class.
+    const allFormats = options['all-formats'] ?? options.allFormats;
+    const dryRun = options['dry-run'] ?? options.dryRun;
     if (allFormats) {
+        const css = valuesToCss(allValues, { manifest });
+        const json = emitJSON(allValues, manifest);
+        const js = emitJS(allValues, manifest);
+        if (dryRun) {
+            // Dry run: print every format, write nothing.
+            console.log(css);
+            console.log(json);
+            console.log(js);
+            return;
+        }
         const dir = 'dist';
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        const css = valuesToCss(allValues, { manifest });
         writeFileSync('dist/tokens.css', css, 'utf8');
-        if (options.dryRun)
-            console.log(css);
-        writeFileSync('dist/tokens.json', emitJSON(allValues, manifest), 'utf8');
-        writeFileSync('dist/tokens.js', emitJS(allValues, manifest), 'utf8');
+        writeFileSync('dist/tokens.json', json, 'utf8');
+        writeFileSync('dist/tokens.js', js, 'utf8');
         console.log(`Tokens written (all formats) to dist/ (css/json/js)${manifest ? ' with mapper' : ''}`);
         return;
     }
-    const dryRun = options.dryRun ?? options['dry-run'];
     if (format === 'css') {
         const css = valuesToCss(allValues, { manifest });
         if (dryRun) {
@@ -63,26 +71,26 @@ export async function buildCommand(options) {
         console.log(`CSS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
     }
     else if (format === 'json') {
-        const outPath = options.output || defaultOutput;
-        const dir = dirname(outPath);
-        if (!existsSync(dir))
-            mkdirSync(dir, { recursive: true });
         if (dryRun) {
             console.log(emitJSON(allValues, manifest));
             return;
         }
-        writeFileSync(outPath, emitJSON(allValues, manifest), 'utf8');
-        console.log(`JSON tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
-    }
-    else if (format === 'js') {
         const outPath = options.output || defaultOutput;
         const dir = dirname(outPath);
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
+        writeFileSync(outPath, emitJSON(allValues, manifest), 'utf8');
+        console.log(`JSON tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
+    }
+    else if (format === 'js') {
         if (dryRun) {
             console.log(emitJS(allValues, manifest));
             return;
         }
+        const outPath = options.output || defaultOutput;
+        const dir = dirname(outPath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
         writeFileSync(outPath, emitJS(allValues, manifest), 'utf8');
         console.log(`JS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
     }

package/cli/commands/build.ts

@@ -1,23 +1,21 @@
-import { join, dirname, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { flattenTokens, type FlatToken } from '../../core/flatten.js';
+import { mergeTokens } from '../../core/breakpoints.js';
 import { valuesToCss, type ManifestRow } from '../../adapters/css.js';
 import { emitJSON } from '../../adapters/json.js';
 import { emitJS } from '../../adapters/js.js';
 import type { BuildOptions } from '../types.js';
+import { loadThemeTokens } from './utils.js';
 
 export async function buildCommand(options: BuildOptions & { [k: string]: any }): Promise<void> {
   const { loadTokensWithBreakpoint } = await import('../../core/breakpoints.js');
-  const tokens = loadTokensWithBreakpoint();
-  const { flat } = flattenTokens(tokens);
-  let allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, (t as FlatToken).value]));
+  let tokens = loadTokensWithBreakpoint(undefined, options.tokens);
   if (options.theme) {
-    const themePath = join('tokens/themes', `${options.theme}.json`);
-    if (existsSync(themePath)) {
-      const themeTokens = JSON.parse(readFileSync(themePath, 'utf8'));
-      Object.assign(allValues, themeTokens);
-    }
+    tokens = mergeTokens(tokens, loadThemeTokens(options.theme));
   }
+  const { flat } = flattenTokens(tokens);
+  const allValues = Object.fromEntries(Object.values(flat).map(t => [t.id, (t as FlatToken).value]));
   const format = options.format || 'css';
   const defaultOutput = `dist/tokens.${format}`;
   let manifest: ManifestRow[] | undefined;
@@ -33,18 +31,29 @@ export async function buildCommand(options: BuildOptions & { [k: string]: any })
       process.exit(1);
     }
   }
-  const allFormats = options.allFormats ?? options['all-formats'];
+  // Read both the kebab key (CLI, camel-case-expansion is off) and the camelCase
+  // key (programmatic callers, e.g. tests). Reading only one form silently no-ops
+  // for the other caller — that was the TASK-024 bug class.
+  const allFormats = options['all-formats'] ?? options.allFormats;
+  const dryRun = options['dry-run'] ?? options.dryRun;
   if (allFormats) {
-    const dir = 'dist'; if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const css = valuesToCss(allValues, { manifest });
+    const json = emitJSON(allValues, manifest);
+    const js = emitJS(allValues, manifest);
+    if (dryRun) {
+      // Dry run: print every format, write nothing.
+      console.log(css);
+      console.log(json);
+      console.log(js);
+      return;
+    }
+    const dir = 'dist'; if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync('dist/tokens.css', css, 'utf8');
-    if (options.dryRun) console.log(css);
-    writeFileSync('dist/tokens.json', emitJSON(allValues, manifest), 'utf8');
-    writeFileSync('dist/tokens.js', emitJS(allValues, manifest), 'utf8');
+    writeFileSync('dist/tokens.json', json, 'utf8');
+    writeFileSync('dist/tokens.js', js, 'utf8');
     console.log(`Tokens written (all formats) to dist/ (css/json/js)${manifest ? ' with mapper' : ''}`);
     return;
   }
-  const dryRun = options.dryRun ?? options['dry-run'];
   if (format === 'css') {
     const css = valuesToCss(allValues, { manifest });
   if (dryRun) { console.log(css); return; }
@@ -52,13 +61,13 @@ export async function buildCommand(options: BuildOptions & { [k: string]: any })
     writeFileSync(outPath, css, 'utf8');
     console.log(`CSS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
   } else if (format === 'json') {
+    if (dryRun) { console.log(emitJSON(allValues, manifest)); return; }
     const outPath = options.output || defaultOutput; const dir = dirname(outPath); if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  if (dryRun) { console.log(emitJSON(allValues, manifest)); return; }
     writeFileSync(outPath, emitJSON(allValues, manifest), 'utf8');
     console.log(`JSON tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
   } else if (format === 'js') {
+    if (dryRun) { console.log(emitJS(allValues, manifest)); return; }
     const outPath = options.output || defaultOutput; const dir = dirname(outPath); if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  if (dryRun) { console.log(emitJS(allValues, manifest)); return; }
     writeFileSync(outPath, emitJS(allValues, manifest), 'utf8');
     console.log(`JS tokens written to ${outPath}${manifest ? ' (manifest mapper applied)' : ''}`);
   }

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

@@ -1 +1 @@
-{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAuJvE"}
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA8BhD,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAiKvE"}

package/cli/commands/graph.js

@@ -16,11 +16,14 @@ function generateDependencyGraph(edges, format) {
             return dot + '}\n';
         }
         case 'mermaid': {
+            // Injective id encoding so distinct token ids (e.g. a.b vs a_b) never
+            // collapse to the same Mermaid node (TASK-027).
+            const safe = (s) => s.replace(/[^a-zA-Z0-9]/g, (c) => `_${c.charCodeAt(0)}_`);
             let mermaid = 'graph LR\n';
             const mermaidNodes = new Set();
             edges.forEach(([from, to]) => {
-                const fromId = from.replace(/[^a-zA-Z0-9]/g, '_');
-                const toId = to.replace(/[^a-zA-Z0-9]/g, '_');
+                const fromId = safe(from);
+                const toId = safe(to);
                 if (!mermaidNodes.has(fromId)) {
                     mermaid += `  ${fromId}["${from}"]\n`;
                     mermaidNodes.add(fromId);
@@ -44,16 +47,21 @@ export async function graphCommand(options) {
     if (options.hasse) {
         const name = options.hasse;
         const bundle = options.bundle;
+        const constraintsDir = options['constraints-dir'] ?? 'themes';
         const fmt = (options.format === 'json' ? 'mermaid' : options.format);
-        const imageFrom = options.imageFrom || 'mermaid';
-        const filterPrefixes = options.filterPrefix ? options.filterPrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
-        const excludePrefixes = options.excludePrefix ? options.excludePrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
-        const onlyViolations = options.onlyViolations || false;
-        const highlightViolations = options.highlightViolations || false;
-        const violationColor = options.violationColor || '#ff2d55';
-        const labelViolations = options.labelViolations || false;
-        const labelTruncate = Math.max(0, options.labelTruncate || 0);
-        const minSeverity = options.minSeverity || 'warn';
+        const imageFrom = options['image-from'] || 'mermaid';
+        // The CLI runs with camel-case-expansion off, so kebab flags arrive only under
+        // their kebab keys. Read those (camelCase reads here silently no-op'd before).
+        const filterPrefix = options['filter-prefix'];
+        const excludePrefix = options['exclude-prefix'];
+        const filterPrefixes = filterPrefix ? filterPrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
+        const excludePrefixes = excludePrefix ? excludePrefix.split(',').map(s => s.trim()).filter(Boolean) : [];
+        const onlyViolations = options['only-violations'] || false;
+        const highlightViolations = options['highlight-violations'] || false;
+        const violationColor = options['violation-color'] || '#ff2d55';
+        const labelViolations = options['label-violations'] || false;
+        const labelTruncate = Math.max(0, options['label-truncate'] || 0);
+        const minSeverity = options['min-severity'] || 'warn';
         const focus = options.focus;
         const radius = Math.max(0, options.radius || 1);
         for (const breakpoint of plan) {
@@ -78,7 +86,7 @@ export async function graphCommand(options) {
             const outDir = 'dist/graphs';
             const baseFile = `${outDir}/${name}${suffix}-hasse.${ext}`;
             try {
-                const src = `themes/${name}.order.json`;
+                const src = `${constraintsDir}/${name}.order.json`;
                 if (!existsSync(src)) {
                     console.error(`❌ Order constraint file not found: ${src}`);
                     process.exit(1);
@@ -100,7 +108,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');
@@ -122,12 +130,21 @@ export async function graphCommand(options) {
                         const numericOrders = order;
                         issues = MonotonicPlugin(numericOrders, parseSize, 'monotonic').evaluate(engine, allIdsInHasse);
                     }
-                    // Attach threshold (and any other runtime constraints) respecting config flags
-                    const cfgRes = loadConfig(undefined);
-                    if (cfgRes.ok) {
+                    // Attach threshold (and any other runtime constraints) respecting config flags.
+                    // Honor the global --config and --constraints-dir, matching `validate`.
+                    const cfgRes = loadConfig(options.config);
+                    if (!cfgRes.ok) {
+                        // An explicitly requested config that fails is a hard error (parity with
+                        // validate); otherwise proceed with order-file violations only.
+                        if (options.config) {
+                            console.error(cfgRes.error);
+                            process.exit(2);
+                        }
+                    }
+                    else {
                         const config = cfgRes.value;
                         const knownIds = new Set(Object.keys(flat));
-                        setupConstraints(engine, { config, bp: breakpoint }, { knownIds });
+                        setupConstraints(engine, { config, bp: breakpoint, constraintsDir }, { knownIds });
                         const runtimeIssues = engine.evaluate(allIdsInHasse);
                         issues.push(...runtimeIssues);
                     }
@@ -211,7 +228,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

@@ -15,8 +15,11 @@ function generateDependencyGraph(edges: Array<[string, string]>, format: string)
       dot += '\n'; edges.forEach(([f,t]) => { dot += `  "${f}" -> "${t}";\n`; });
       return dot + '}\n'; }
     case 'mermaid': {
+      // Injective id encoding so distinct token ids (e.g. a.b vs a_b) never
+      // collapse to the same Mermaid node (TASK-027).
+      const safe = (s: string) => s.replace(/[^a-zA-Z0-9]/g, (c) => `_${c.charCodeAt(0)}_`);
       let mermaid = 'graph LR\n'; const mermaidNodes = new Set<string>();
-      edges.forEach(([from,to]) => { const fromId = from.replace(/[^a-zA-Z0-9]/g,'_'); const toId = to.replace(/[^a-zA-Z0-9]/g,'_');
+      edges.forEach(([from,to]) => { const fromId = safe(from); const toId = safe(to);
         if (!mermaidNodes.has(fromId)) { mermaid += `  ${fromId}["${from}"]\n`; mermaidNodes.add(fromId); }
         if (!mermaidNodes.has(toId)) { mermaid += `  ${toId}["${to}"]\n`; mermaidNodes.add(toId); }
         mermaid += `  ${fromId} --> ${toId}\n`; });
@@ -33,16 +36,21 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
   if (options.hasse) {
     const name = options.hasse;
   const bundle = (options as any).bundle;
+  const constraintsDir = options['constraints-dir'] ?? 'themes';
   const fmt = (options.format === 'json' ? 'mermaid' : options.format) as 'mermaid' | 'dot' | 'svg' | 'png';
-    const imageFrom = options.imageFrom || 'mermaid';
-    const filterPrefixes = options.filterPrefix ? options.filterPrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
-    const excludePrefixes = options.excludePrefix ? options.excludePrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
-    const onlyViolations = options.onlyViolations || false;
-    const highlightViolations = options.highlightViolations || false;
-    const violationColor = options.violationColor || '#ff2d55';
-    const labelViolations = options.labelViolations || false;
-    const labelTruncate = Math.max(0, options.labelTruncate || 0);
-    const minSeverity = options.minSeverity || 'warn';
+    const imageFrom = options['image-from'] || 'mermaid';
+    // The CLI runs with camel-case-expansion off, so kebab flags arrive only under
+    // their kebab keys. Read those (camelCase reads here silently no-op'd before).
+    const filterPrefix = options['filter-prefix'];
+    const excludePrefix = options['exclude-prefix'];
+    const filterPrefixes = filterPrefix ? filterPrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
+    const excludePrefixes = excludePrefix ? excludePrefix.split(',').map(s=>s.trim()).filter(Boolean) : [];
+    const onlyViolations = options['only-violations'] || false;
+    const highlightViolations = options['highlight-violations'] || false;
+    const violationColor = options['violation-color'] || '#ff2d55';
+    const labelViolations = options['label-violations'] || false;
+    const labelTruncate = Math.max(0, options['label-truncate'] || 0);
+    const minSeverity = options['min-severity'] || 'warn';
     const focus = options.focus; const radius = Math.max(0, options.radius || 1);
     for (const breakpoint of plan) {
       const suffixParts: string[] = [];
@@ -57,7 +65,7 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
       const ext = baseFmt === 'mermaid' ? 'mmd' : 'dot';
       const outDir = 'dist/graphs'; const baseFile = `${outDir}/${name}${suffix}-hasse.${ext}`;
       try {
-        const src = `themes/${name}.order.json`;
+        const src = `${constraintsDir}/${name}.order.json`;
         if (!existsSync(src)) { console.error(`❌ Order constraint file not found: ${src}`); process.exit(1); }
         const { order } = JSON.parse(readFileSync(src, 'utf8'));
         const { buildPoset, transitiveReduction, toMermaidHasseStyled, toDotHasseStyled, filterByPrefix, filterExcludePrefix, khopSubgraph, pickSeedsByPattern } = await import('../../core/poset.js');
@@ -69,7 +77,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');
@@ -93,12 +101,17 @@ export async function graphCommand(options: GraphOptions): Promise<void> {
             issues = MonotonicPlugin(numericOrders, parseSize, 'monotonic').evaluate(engine, allIdsInHasse);
           }
 
-          // Attach threshold (and any other runtime constraints) respecting config flags
-          const cfgRes = loadConfig(undefined);
-          if (cfgRes.ok) {
+          // Attach threshold (and any other runtime constraints) respecting config flags.
+          // Honor the global --config and --constraints-dir, matching `validate`.
+          const cfgRes = loadConfig(options.config);
+          if (!cfgRes.ok) {
+            // An explicitly requested config that fails is a hard error (parity with
+            // validate); otherwise proceed with order-file violations only.
+            if (options.config) { console.error(cfgRes.error); process.exit(2); }
+          } else {
             const config = cfgRes.value;
             const knownIds = new Set(Object.keys(flat as Record<string, FlatToken>));
-            setupConstraints(engine, { config, bp: breakpoint }, { knownIds });
+            setupConstraints(engine, { config, bp: breakpoint, constraintsDir }, { knownIds });
             const runtimeIssues = engine.evaluate(allIdsInHasse);
             issues.push(...runtimeIssues);
           }
@@ -170,7 +183,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/patch-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patch-apply.d.ts","sourceRoot":"","sources":["patch-apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkCrD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4C9E"}
+{"version":3,"file":"patch-apply.d.ts","sourceRoot":"","sources":["patch-apply.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAkCrD,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+C9E"}

package/cli/commands/patch-apply.js

@@ -60,7 +60,10 @@ export async function patchApplyCommand(opts) {
     for (const c of patchDoc.changes) {
         applyChange(tokens, c.id, c.to, c.type);
     }
-    if (opts.dryRun) {
+    // Read both forms: kebab from the CLI (camel-case-expansion off) and camelCase
+    // from programmatic callers. Reading only opts.dryRun was dead for the CLI, so
+    // `--dry-run --output` silently wrote the file (TASK-024).
+    if (opts['dry-run'] ?? opts.dryRun) {
         outputResult(tokens, 'json');
         return;
     }

package/cli/commands/patch-apply.ts

@@ -66,7 +66,10 @@ export async function patchApplyCommand(opts: PatchApplyOptions): Promise<void>
     applyChange(tokens, c.id, c.to, c.type);
   }
 
-  if (opts.dryRun) {
+  // Read both forms: kebab from the CLI (camel-case-expansion off) and camelCase
+  // from programmatic callers. Reading only opts.dryRun was dead for the CLI, so
+  // `--dry-run --output` silently wrote the file (TASK-024).
+  if (opts['dry-run'] ?? opts.dryRun) {
     outputResult(tokens, 'json');
     return;
   }

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

@@ -1 +1 @@
-{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["set.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,UAAU,EAAe,MAAM,aAAa,CAAC;AAmE1E,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAsKnE"}
+{"version":3,"file":"set.d.ts","sourceRoot":"","sources":["set.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAiB,UAAU,EAAe,MAAM,aAAa,CAAC;AAmE1E,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAuKnE"}