design-constraint-validator 1.0.0 → 2.0.1

package/cli/graph-poset.ts

@@ -1,74 +1,74 @@
-// cli/graph-poset.ts
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
-import { buildPoset, transitiveReduction, toMermaidHasse, toDotHasse, validatePoset, type Order } from "../core/poset.js";
-
-export interface OrderFile {
-  $description?: string;
-  order: Order[];
-}
-
-export function loadOrderFile(path: string): OrderFile {
-  if (!existsSync(path)) {
-    throw new Error(`Order file not found: ${path}`);
-  }
-  return JSON.parse(readFileSync(path, "utf8"));
-}
-
-export function generateHasseDiagram(orderPath: string, outputPath: string, format: 'mermaid' | 'dot' = 'mermaid'): void {
-  const orderData = loadOrderFile(orderPath);
-  const { order, $description } = orderData;
-  
-  // Build and validate poset
-  const poset = buildPoset(order);
-  const validation = validatePoset(poset);
-  
-  if (!validation.valid) {
-    console.error("⚠️  Warning: Poset contains cycles:");
-    for (const cycle of validation.cycles || []) {
-      console.error(`   ${cycle.join(" → ")}`);
-    }
-  }
-  
-  // Generate Hasse diagram (transitive reduction)
-  const hasse = transitiveReduction(poset);
-  
-  const title = $description || "Poset Hierarchy";
-  const diagram = format === 'mermaid' 
-    ? toMermaidHasse(hasse, { title })
-    : toDotHasse(hasse, { title });
-  
-  // Ensure output directory exists
-  mkdirSync(outputPath.split('/').slice(0, -1).join('/'), { recursive: true });
-  
-  writeFileSync(outputPath, diagram);
-  console.log(`✅ Generated ${format.toUpperCase()} Hasse diagram: ${outputPath}`);
-  
-  if (!validation.valid) {
-    console.log(`⚠️  Note: Diagram shows cycles that should be resolved`);
-  }
-}
-
-export function generateAllHasseDiagrams(themesDir: string = "themes", outputDir: string = "dist/graphs"): void {
-  const orderFiles = [
-    { file: "typography.order.json", name: "typography" },
-    { file: "spacing.order.json", name: "spacing" }
-  ];
-  
-  mkdirSync(outputDir, { recursive: true });
-  
-  for (const { file, name } of orderFiles) {
-    const orderPath = `${themesDir}/${file}`;
-    
-    if (existsSync(orderPath)) {
-      try {
-        // Generate both Mermaid and DOT formats
-        generateHasseDiagram(orderPath, `${outputDir}/${name}-hasse.mmd`, 'mermaid');
-        generateHasseDiagram(orderPath, `${outputDir}/${name}-hasse.dot`, 'dot');
-      } catch (error) {
-        console.error(`❌ Failed to generate diagram for ${name}:`, error);
-      }
-    } else {
-      console.log(`⏭️  Skipping ${name} (no order file found)`);
-    }
-  }
-}
+// cli/graph-poset.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { buildPoset, transitiveReduction, toMermaidHasse, toDotHasse, validatePoset, type Order } from "../core/poset.js";
+
+export interface OrderFile {
+  $description?: string;
+  order: Order[];
+}
+
+export function loadOrderFile(path: string): OrderFile {
+  if (!existsSync(path)) {
+    throw new Error(`Order file not found: ${path}`);
+  }
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+export function generateHasseDiagram(orderPath: string, outputPath: string, format: 'mermaid' | 'dot' = 'mermaid'): void {
+  const orderData = loadOrderFile(orderPath);
+  const { order, $description } = orderData;
+  
+  // Build and validate poset
+  const poset = buildPoset(order);
+  const validation = validatePoset(poset);
+  
+  if (!validation.valid) {
+    console.error("⚠️  Warning: Poset contains cycles:");
+    for (const cycle of validation.cycles || []) {
+      console.error(`   ${cycle.join(" → ")}`);
+    }
+  }
+  
+  // Generate Hasse diagram (transitive reduction)
+  const hasse = transitiveReduction(poset);
+  
+  const title = $description || "Poset Hierarchy";
+  const diagram = format === 'mermaid' 
+    ? toMermaidHasse(hasse, { title })
+    : toDotHasse(hasse, { title });
+  
+  // Ensure output directory exists
+  mkdirSync(outputPath.split('/').slice(0, -1).join('/'), { recursive: true });
+  
+  writeFileSync(outputPath, diagram);
+  console.log(`✅ Generated ${format.toUpperCase()} Hasse diagram: ${outputPath}`);
+  
+  if (!validation.valid) {
+    console.log(`⚠️  Note: Diagram shows cycles that should be resolved`);
+  }
+}
+
+export function generateAllHasseDiagrams(themesDir: string = "themes", outputDir: string = "dist/graphs"): void {
+  const orderFiles = [
+    { file: "typography.order.json", name: "typography" },
+    { file: "spacing.order.json", name: "spacing" }
+  ];
+  
+  mkdirSync(outputDir, { recursive: true });
+  
+  for (const { file, name } of orderFiles) {
+    const orderPath = `${themesDir}/${file}`;
+    
+    if (existsSync(orderPath)) {
+      try {
+        // Generate both Mermaid and DOT formats
+        generateHasseDiagram(orderPath, `${outputDir}/${name}-hasse.mmd`, 'mermaid');
+        generateHasseDiagram(orderPath, `${outputDir}/${name}-hasse.dot`, 'dot');
+      } catch (error) {
+        console.error(`❌ Failed to generate diagram for ${name}:`, error);
+      }
+    } else {
+      console.log(`⏭️  Skipping ${name} (no order file found)`);
+    }
+  }
+}

package/cli/json-output.d.ts

@@ -0,0 +1,69 @@
+import type { ConstraintIssue } from '../core/engine.js';
+export interface ConstraintViolation {
+    ruleId: string;
+    level: 'error' | 'warn';
+    message: string;
+    nodes?: string[];
+    edges?: [string, string][];
+    context?: {
+        actual?: unknown;
+        expected?: unknown;
+        threshold?: number;
+        [key: string]: unknown;
+    };
+}
+export interface ValidationResult {
+    ok: boolean;
+    counts: {
+        checked: number;
+        violations: number;
+        warnings: number;
+    };
+    violations: ConstraintViolation[];
+    warnings?: ConstraintViolation[];
+    stats: {
+        durationMs: number;
+        engineVersion: string;
+        timestamp: string;
+    };
+    dcv: {
+        name: string;
+        version: string;
+        repository: string;
+    };
+}
+export interface ValidationReceipt extends ValidationResult {
+    environment: {
+        nodeVersion: string;
+        platform: string;
+        arch: string;
+    };
+    inputs: {
+        tokensFile: string;
+        tokensHash: string;
+        constraintsDir: string;
+        constraintHashes: Record<string, string>;
+        breakpoint?: string;
+    };
+    config: {
+        failOn: 'off' | 'warn' | 'error';
+        overrides?: string[];
+    };
+}
+/**
+ * Convert internal ConstraintIssue to standardized ConstraintViolation format
+ */
+export declare function formatViolation(issue: ConstraintIssue): ConstraintViolation;
+/**
+ * Generate a ValidationResult from collected issues
+ */
+export declare function createValidationResult(errors: ConstraintIssue[], warnings: ConstraintIssue[], durationMs: number, engineVersion: string): ValidationResult;
+/**
+ * Generate a ValidationReceipt with full audit trail
+ */
+export declare function createValidationReceipt(result: ValidationResult, tokensFile: string, constraintsDir: string, breakpoint: string | undefined, failOn: 'off' | 'warn' | 'error'): ValidationReceipt;
+/**
+ * Write JSON output to file or stdout
+ */
+export declare function writeJsonOutput(data: unknown, outputPath?: string): void;
+//# sourceMappingURL=json-output.d.ts.map

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

@@ -0,0 +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"}

package/cli/json-output.js

@@ -0,0 +1,109 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getVersionInfo } from './version-banner.js';
+/**
+ * Convert internal ConstraintIssue to standardized ConstraintViolation format
+ */
+export function formatViolation(issue) {
+    const violation = {
+        ruleId: issue.rule,
+        level: issue.level === 'error' ? 'error' : 'warn',
+        message: issue.message,
+    };
+    if (issue.id) {
+        violation.nodes = [issue.id];
+    }
+    // Add context from where field or other metadata
+    if (issue.where) {
+        violation.context = { where: issue.where };
+    }
+    return violation;
+}
+/**
+ * Generate a ValidationResult from collected issues
+ */
+export function createValidationResult(errors, warnings, durationMs, engineVersion) {
+    const violations = errors.map(formatViolation);
+    const warningViolations = warnings.map(formatViolation);
+    return {
+        ok: errors.length === 0,
+        counts: {
+            checked: errors.length + warnings.length,
+            violations: errors.length,
+            warnings: warnings.length,
+        },
+        violations,
+        warnings: warningViolations.length > 0 ? warningViolations : undefined,
+        stats: {
+            durationMs: Math.round(durationMs),
+            engineVersion,
+            timestamp: new Date().toISOString(),
+        },
+        dcv: getVersionInfo(),
+    };
+}
+/**
+ * Calculate SHA-256 hash of a file
+ */
+function hashFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath);
+        return 'sha256:' + createHash('sha256').update(content).digest('hex').slice(0, 16);
+    }
+    catch {
+        return 'sha256:unknown';
+    }
+}
+/**
+ * Generate a ValidationReceipt with full audit trail
+ */
+export function createValidationReceipt(result, tokensFile, constraintsDir, breakpoint, failOn) {
+    // Hash the tokens file
+    const tokensHash = hashFile(tokensFile);
+    // Hash all constraint files in the directory
+    const constraintHashes = {};
+    try {
+        const files = fs.readdirSync(constraintsDir);
+        for (const file of files) {
+            if (file.endsWith('.json')) {
+                const filePath = path.join(constraintsDir, file);
+                constraintHashes[file] = hashFile(filePath);
+            }
+        }
+    }
+    catch {
+        // If constraintsDir doesn't exist, just use empty hashes
+    }
+    return {
+        ...result,
+        environment: {
+            nodeVersion: process.version,
+            platform: process.platform,
+            arch: process.arch,
+        },
+        inputs: {
+            tokensFile,
+            tokensHash,
+            constraintsDir,
+            constraintHashes,
+            breakpoint,
+        },
+        config: {
+            failOn,
+        },
+    };
+}
+/**
+ * Write JSON output to file or stdout
+ */
+export function writeJsonOutput(data, outputPath) {
+    const json = JSON.stringify(data, null, 2);
+    if (outputPath) {
+        fs.writeFileSync(outputPath, json, 'utf-8');
+        console.error(`✓ Output written to ${outputPath}`);
+    }
+    else {
+        console.log(json);
+    }
+}

package/cli/json-output.ts

@@ -0,0 +1,184 @@
+import type { ConstraintIssue } from '../core/engine.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { getVersionInfo } from './version-banner.js';
+
+export interface ConstraintViolation {
+  ruleId: string;
+  level: 'error' | 'warn';
+  message: string;
+  nodes?: string[];
+  edges?: [string, string][];
+  context?: {
+    actual?: unknown;
+    expected?: unknown;
+    threshold?: number;
+    [key: string]: unknown;
+  };
+}
+
+export interface ValidationResult {
+  ok: boolean;
+  counts: {
+    checked: number;
+    violations: number;
+    warnings: number;
+  };
+  violations: ConstraintViolation[];
+  warnings?: ConstraintViolation[];
+  stats: {
+    durationMs: number;
+    engineVersion: string;
+    timestamp: string;
+  };
+  dcv: {
+    name: string;
+    version: string;
+    repository: string;
+  };
+}
+
+export interface ValidationReceipt extends ValidationResult {
+  environment: {
+    nodeVersion: string;
+    platform: string;
+    arch: string;
+  };
+  inputs: {
+    tokensFile: string;
+    tokensHash: string;
+    constraintsDir: string;
+    constraintHashes: Record<string, string>;
+    breakpoint?: string;
+  };
+  config: {
+    failOn: 'off' | 'warn' | 'error';
+    overrides?: string[];
+  };
+}
+
+/**
+ * Convert internal ConstraintIssue to standardized ConstraintViolation format
+ */
+export function formatViolation(issue: ConstraintIssue): ConstraintViolation {
+  const violation: ConstraintViolation = {
+    ruleId: issue.rule,
+    level: issue.level === 'error' ? 'error' : 'warn',
+    message: issue.message,
+  };
+
+  if (issue.id) {
+    violation.nodes = [issue.id];
+  }
+
+  // Add context from where field or other metadata
+  if (issue.where) {
+    violation.context = { where: issue.where };
+  }
+
+  return violation;
+}
+
+/**
+ * Generate a ValidationResult from collected issues
+ */
+export function createValidationResult(
+  errors: ConstraintIssue[],
+  warnings: ConstraintIssue[],
+  durationMs: number,
+  engineVersion: string
+): ValidationResult {
+  const violations = errors.map(formatViolation);
+  const warningViolations = warnings.map(formatViolation);
+
+  return {
+    ok: errors.length === 0,
+    counts: {
+      checked: errors.length + warnings.length,
+      violations: errors.length,
+      warnings: warnings.length,
+    },
+    violations,
+    warnings: warningViolations.length > 0 ? warningViolations : undefined,
+    stats: {
+      durationMs: Math.round(durationMs),
+      engineVersion,
+      timestamp: new Date().toISOString(),
+    },
+    dcv: getVersionInfo(),
+  };
+}
+
+/**
+ * Calculate SHA-256 hash of a file
+ */
+function hashFile(filePath: string): string {
+  try {
+    const content = fs.readFileSync(filePath);
+    return 'sha256:' + createHash('sha256').update(content).digest('hex').slice(0, 16);
+  } catch {
+    return 'sha256:unknown';
+  }
+}
+
+/**
+ * Generate a ValidationReceipt with full audit trail
+ */
+export function createValidationReceipt(
+  result: ValidationResult,
+  tokensFile: string,
+  constraintsDir: string,
+  breakpoint: string | undefined,
+  failOn: 'off' | 'warn' | 'error'
+): ValidationReceipt {
+  // Hash the tokens file
+  const tokensHash = hashFile(tokensFile);
+
+  // Hash all constraint files in the directory
+  const constraintHashes: Record<string, string> = {};
+  try {
+    const files = fs.readdirSync(constraintsDir);
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        const filePath = path.join(constraintsDir, file);
+        constraintHashes[file] = hashFile(filePath);
+      }
+    }
+  } catch {
+    // If constraintsDir doesn't exist, just use empty hashes
+  }
+
+  return {
+    ...result,
+    environment: {
+      nodeVersion: process.version,
+      platform: process.platform,
+      arch: process.arch,
+    },
+    inputs: {
+      tokensFile,
+      tokensHash,
+      constraintsDir,
+      constraintHashes,
+      breakpoint,
+    },
+    config: {
+      failOn,
+    },
+  };
+}
+
+/**
+ * Write JSON output to file or stdout
+ */
+export function writeJsonOutput(data: unknown, outputPath?: string): void {
+  const json = JSON.stringify(data, null, 2);
+  
+  if (outputPath) {
+    fs.writeFileSync(outputPath, json, 'utf-8');
+    console.error(`✓ Output written to ${outputPath}`);
+  } else {
+    console.log(json);
+  }
+}

package/cli/result.ts

@@ -1,27 +1,27 @@
-export type Ok<T> = { ok: true; value: T };
-export type Err<E> = { ok: false; error: E };
-export type Result<T, E = Error> = Ok<T> | Err<E>;
-
-export function ok<T>(value: T): Ok<T> { return { ok: true, value }; }
-export function err<E>(error: E): Err<E> { return { ok: false, error }; }
-
-export function wrap<T>(fn: () => T): Result<T, unknown> {
-  try { return ok(fn()); } catch (e) { return err(e); }
-}
-
-export async function wrapAsync<T>(fn: () => Promise<T>): Promise<Result<T, unknown>> {
-  try { return ok(await fn()); } catch (e) { return err(e); }
-}
-
-export function map<T, U, E>(r: Result<T, E>, f: (v: T) => U): Result<U, E> {
-  return r.ok ? ok(f(r.value)) : r;
-}
-
-export function chain<T, U, E>(r: Result<T, E>, f: (v: T) => Result<U, E>): Result<U, E> {
-  return r.ok ? f(r.value) : r;
-}
-
-export function getOrThrow<T, E>(r: Result<T, E>): T {
-  if (!r.ok) throw r.error as any; // consumer decides how to handle
-  return r.value;
-}
+export type Ok<T> = { ok: true; value: T };
+export type Err<E> = { ok: false; error: E };
+export type Result<T, E = Error> = Ok<T> | Err<E>;
+
+export function ok<T>(value: T): Ok<T> { return { ok: true, value }; }
+export function err<E>(error: E): Err<E> { return { ok: false, error }; }
+
+export function wrap<T>(fn: () => T): Result<T, unknown> {
+  try { return ok(fn()); } catch (e) { return err(e); }
+}
+
+export async function wrapAsync<T>(fn: () => Promise<T>): Promise<Result<T, unknown>> {
+  try { return ok(await fn()); } catch (e) { return err(e); }
+}
+
+export function map<T, U, E>(r: Result<T, E>, f: (v: T) => U): Result<U, E> {
+  return r.ok ? ok(f(r.value)) : r;
+}
+
+export function chain<T, U, E>(r: Result<T, E>, f: (v: T) => Result<U, E>): Result<U, E> {
+  return r.ok ? f(r.value) : r;
+}
+
+export function getOrThrow<T, E>(r: Result<T, E>): T {
+  if (!r.ok) throw r.error as any; // consumer decides how to handle
+  return r.value;
+}

package/cli/run.ts

@@ -1,54 +1,54 @@
-#!/usr/bin/env ts-node
-import { readFileSync } from "node:fs";
-import { flattenTokens } from "../core/flatten.js";
-import { Engine } from "../core/engine.js";
-import { WcagContrastPlugin } from "../core/constraints/wcag.js";
-
-const tokensRoot = JSON.parse(readFileSync("tokens/tokens.example.json","utf8"));
-const { flat, edges } = flattenTokens(tokensRoot);
-
-// Build init values map
-const init: Record<string, string|number> = {};
-for (const [id, t] of Object.entries(flat)) init[id] = t.value;
-
-// Engine + plugin (example pairs; adjust IDs to your roles)
-const engine = new Engine(init, edges).use(
-  WcagContrastPlugin([
-    { fg: "color.role.text.default", bg: "color.role.surface.default", min: 4.5, where: "Body text" },
-    { fg: "color.role.accent.default", bg: "color.role.surface.default", min: 3.0, where: "Accent on surface" }
-  ])
-);
-
-// Apply overrides if present
-let overrides: Record<string, string|number> = {};
-try {
-  const maybe = JSON.parse(readFileSync("tokens/overrides/local.json","utf8"));
-  overrides = maybe.overrides ?? maybe;
-} catch {
-  // File doesn't exist or invalid JSON, use empty overrides
-}
-
-import { patchToJson } from "../adapters/json.js";
-import yargs from "yargs/yargs";
-import { hideBin } from "yargs/helpers";
-
-const argvPromise = yargs(hideBin(process.argv)).option('json', {
-  alias: 'j',
-  type: 'boolean',
-  description: 'Output result as JSON'
-}).argv;
-
-// ... existing code ...
-
-(async () => {
-  const argv = await argvPromise;
-  for (const [id, val] of Object.entries(overrides)) {
-    const res = engine.commit(id, val);
-    if (argv.json) {
-      const jsonOutput = patchToJson(res);
-      console.log(JSON.stringify(jsonOutput, null, 2));
-    } else {
-      console.log(JSON.stringify(res, null, 2));
-    }
-  }
-})();
+#!/usr/bin/env ts-node
+import { readFileSync } from "node:fs";
+import { flattenTokens } from "../core/flatten.js";
+import { Engine } from "../core/engine.js";
+import { WcagContrastPlugin } from "../core/constraints/wcag.js";
+
+const tokensRoot = JSON.parse(readFileSync("tokens/tokens.example.json","utf8"));
+const { flat, edges } = flattenTokens(tokensRoot);
+
+// Build init values map
+const init: Record<string, string|number> = {};
+for (const [id, t] of Object.entries(flat)) init[id] = t.value;
+
+// Engine + plugin (example pairs; adjust IDs to your roles)
+const engine = new Engine(init, edges).use(
+  WcagContrastPlugin([
+    { fg: "color.role.text.default", bg: "color.role.surface.default", min: 4.5, where: "Body text" },
+    { fg: "color.role.accent.default", bg: "color.role.surface.default", min: 3.0, where: "Accent on surface" }
+  ])
+);
+
+// Apply overrides if present
+let overrides: Record<string, string|number> = {};
+try {
+  const maybe = JSON.parse(readFileSync("tokens/overrides/local.json","utf8"));
+  overrides = maybe.overrides ?? maybe;
+} catch {
+  // File doesn't exist or invalid JSON, use empty overrides
+}
+
+import { patchToJson } from "../adapters/json.js";
+import yargs from "yargs/yargs";
+import { hideBin } from "yargs/helpers";
+
+const argvPromise = yargs(hideBin(process.argv)).option('json', {
+  alias: 'j',
+  type: 'boolean',
+  description: 'Output result as JSON'
+}).argv;
+
+// ... existing code ...
+
+(async () => {
+  const argv = await argvPromise;
+  for (const [id, val] of Object.entries(overrides)) {
+    const res = engine.commit(id, val);
+    if (argv.json) {
+      const jsonOutput = patchToJson(res);
+      console.log(JSON.stringify(jsonOutput, null, 2));
+    } else {
+      console.log(JSON.stringify(res, null, 2));
+    }
+  }
+})();