design-constraint-validator 1.0.0 → 2.0.1

package/core/engine.ts

@@ -1,65 +1,167 @@
-import type { TokenId, TokenValue } from "./flatten.js";
-
-export type ConstraintIssue = {
-  id: TokenId | string;
-  rule: string;            // e.g., "wcag-contrast"
-  level: "error" | "warn";
-  message: string;
-  where?: string;          // optional hint (e.g., "body text on surface")
-};
-
-export type ConstraintPlugin = {
-  id: string;
-  // Called with the set of candidate IDs (changed + affected).
-  evaluate(engine: Engine, candidates: Set<TokenId>): ConstraintIssue[];
-};
-
-export type Graph = Map<TokenId, Set<TokenId>>; // id -> dependents
-
-export class Engine {
-  private values = new Map<TokenId, TokenValue>();
-  private graph: Graph = new Map();
-  private plugins: ConstraintPlugin[] = [];
-
-  constructor(initValues: Record<TokenId, TokenValue>, edges: Array<[TokenId, TokenId]>) {
-    for (const [k, v] of Object.entries(initValues)) this.values.set(k, v);
-    for (const [from, to] of edges) {
-      if (!this.graph.has(from)) this.graph.set(from, new Set());
-      this.graph.get(from)!.add(to);
-      if (!this.graph.has(to)) this.graph.set(to, new Set());
-    }
-  }
-
-  use(plugin: ConstraintPlugin) { this.plugins.push(plugin); return this; }
-
-  get(id: TokenId): TokenValue | undefined { return this.values.get(id); }
-  set(id: TokenId, value: TokenValue) { this.values.set(id, value); }
-
-  /** All nodes that depend (directly/indirectly) on start. */
-  affected(start: TokenId): Set<TokenId> {
-    const seen = new Set<TokenId>();
-    const stack = [start];
-    while (stack.length) {
-      const n = stack.pop()!;
-      if (seen.has(n)) continue;
-      seen.add(n);
-      for (const d of this.graph.get(n) ?? []) stack.push(d);
-    }
-    seen.delete(start);
-    return seen;
-  }
-
-  evaluate(candidates: Set<TokenId>) {
-    return this.plugins.flatMap(p => p.evaluate(this, candidates));
-  }
-
-  /** Single change -> returns affected set, issues, and a patch you can feed to adapters. */
-  commit(id: TokenId, value: TokenValue) {
-    this.set(id, value);
-    const A = this.affected(id);
-    const candidates = new Set<TokenId>([id, ...A]);
-    const issues = this.evaluate(candidates);
-    const patch: Record<TokenId, TokenValue> = { [id]: value };
-    return { affected: [...A], issues, patch };
-  }
-}
+import type { TokenId, TokenValue } from "./flatten.js";
+
+/**
+ * Represents a constraint violation.
+ *
+ * Phase 3C: Enhanced with metadata for tooling and visualization.
+ */
+export type ConstraintIssue = {
+  id: TokenId | string;
+  rule: string;            // e.g., "wcag-contrast"
+  level: "error" | "warn";
+  message: string;
+  where?: string;          // optional hint (e.g., "body text on surface")
+
+  /**
+   * Token IDs involved in this violation.
+   * Useful for filtering, highlighting, and incremental validation.
+   *
+   * Example: For a WCAG contrast violation between fg and bg tokens,
+   * this would be [fgTokenId, bgTokenId].
+   */
+  involvedTokens?: TokenId[];
+
+  /**
+   * Graph edges (reference relationships) involved in this violation.
+   * Useful for visualization and "why" explanations.
+   *
+   * Example: If a token references another that violates a constraint,
+   * this captures that reference edge.
+   */
+  involvedEdges?: Array<[TokenId, TokenId]>;
+};
+
+/**
+ * Constraint plugin interface.
+ *
+ * Phase 3C: Documented contract for candidate-based evaluation.
+ *
+ * ## Candidate Contract
+ *
+ * Plugins MUST honor the `candidates` set for incremental validation:
+ * - Only evaluate constraints that involve at least one candidate token
+ * - Return violations where at least one involved token is in candidates
+ * - This enables efficient re-validation when tokens change
+ *
+ * ## Metadata Contract
+ *
+ * Plugins SHOULD populate `involvedTokens` in returned issues:
+ * - List all token IDs that participate in the constraint
+ * - This enables filtering, highlighting, and graph visualization
+ * - Optional but recommended for better tooling support
+ *
+ * ## Example Implementation
+ *
+ * ```ts
+ * export function MyPlugin(rules: Rule[]): ConstraintPlugin {
+ *   return {
+ *     id: "my-plugin",
+ *     evaluate(engine, candidates) {
+ *       const issues: ConstraintIssue[] = [];
+ *       for (const rule of rules) {
+ *         // Honor candidates: skip if no involved tokens are candidates
+ *         if (!candidates.has(rule.tokenA) && !candidates.has(rule.tokenB)) {
+ *           continue;
+ *         }
+ *         // Check constraint...
+ *         if (violated) {
+ *           issues.push({
+ *             id: `${rule.tokenA}|${rule.tokenB}`,
+ *             rule: "my-plugin",
+ *             level: "error",
+ *             message: "...",
+ *             involvedTokens: [rule.tokenA, rule.tokenB], // Metadata
+ *           });
+ *         }
+ *       }
+ *       return issues;
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export type ConstraintPlugin = {
+  id: string;
+  /**
+   * Evaluate constraints for a set of candidate tokens.
+   *
+   * @param engine Engine instance providing token values and graph
+   * @param candidates Set of token IDs to evaluate (changed + affected)
+   * @returns Array of constraint violations
+   */
+  evaluate(engine: Engine, candidates: Set<TokenId>): ConstraintIssue[];
+};
+
+export type Graph = Map<TokenId, Set<TokenId>>; // id -> dependents
+
+export class Engine {
+  private values = new Map<TokenId, TokenValue>();
+  private graph: Graph = new Map();
+  private plugins: ConstraintPlugin[] = [];
+
+  constructor(initValues: Record<TokenId, TokenValue>, edges: Array<[TokenId, TokenId]>) {
+    for (const [k, v] of Object.entries(initValues)) this.values.set(k, v);
+    for (const [from, to] of edges) {
+      if (!this.graph.has(from)) this.graph.set(from, new Set());
+      this.graph.get(from)!.add(to);
+      if (!this.graph.has(to)) this.graph.set(to, new Set());
+    }
+  }
+
+  use(plugin: ConstraintPlugin) { this.plugins.push(plugin); return this; }
+
+  get(id: TokenId): TokenValue | undefined { return this.values.get(id); }
+  set(id: TokenId, value: TokenValue) { this.values.set(id, value); }
+
+  /**
+   * Get all token IDs in the engine.
+   *
+   * Phase 3C: Exposed for plugins and adapters.
+   * Useful for iterating all tokens or creating a full candidate set.
+   *
+   * @returns Array of all token IDs
+   */
+  getAllIds(): TokenId[] {
+    return Array.from(this.values.keys());
+  }
+
+  /**
+   * Get flat token map (ID → value).
+   *
+   * Phase 3C: Exposed to avoid duplicate flattening in CLI/adapters.
+   * Returns a plain object suitable for serialization or adapter use.
+   *
+   * @returns Record mapping token IDs to their current values
+   */
+  getFlatTokens(): Record<TokenId, TokenValue> {
+    return Object.fromEntries(this.values);
+  }
+
+  /** All nodes that depend (directly/indirectly) on start. */
+  affected(start: TokenId): Set<TokenId> {
+    const seen = new Set<TokenId>();
+    const stack = [start];
+    while (stack.length) {
+      const n = stack.pop()!;
+      if (seen.has(n)) continue;
+      seen.add(n);
+      for (const d of this.graph.get(n) ?? []) stack.push(d);
+    }
+    seen.delete(start);
+    return seen;
+  }
+
+  evaluate(candidates: Set<TokenId>) {
+    return this.plugins.flatMap(p => p.evaluate(this, candidates));
+  }
+
+  /** Single change -> returns affected set, issues, and a patch you can feed to adapters. */
+  commit(id: TokenId, value: TokenValue) {
+    this.set(id, value);
+    const A = this.affected(id);
+    const candidates = new Set<TokenId>([id, ...A]);
+    const issues = this.evaluate(candidates);
+    const patch: Record<TokenId, TokenValue> = { [id]: value };
+    return { affected: [...A], issues, patch };
+  }
+}

package/core/flatten.ts

@@ -1,116 +1,116 @@
-export type TokenId = string; // e.g. "color.palette.brand.600"
-export type TokenValue = string | number;
-export type TokenNode = { 
-  $type?: string; 
-  $value?: TokenValue; 
-  [k: string]: TokenNode | string | number | undefined;
-};
-
-export type FlatToken = {
-  id: TokenId;
-  type: string;
-  value: TokenValue;       // resolved (if ref)
-  raw: TokenValue;         // original $value
-  refs: TokenId[];         // referenced token IDs found in raw
-};
-
-export type FlattenResult = {
-  flat: Record<TokenId, FlatToken>;
-  edges: Array<[from: TokenId, to: TokenId]>; // from ref -> to dependent
-};
-
-const REF_RE = /\{([a-z0-9.-]+)\}/gi;
-
-export function flattenTokens(root: TokenNode): FlattenResult {
-  const flat: Record<TokenId, FlatToken> = {};
-  const edges: Array<[TokenId, TokenId]> = [];
-
-  // First pass: collect all tokens
-  function walk(node: TokenNode, path: string[] = []) {
-    if (!node || typeof node !== 'object') return;
-    
-    if (Object.prototype.hasOwnProperty.call(node, '$value')) {
-      const id = path.join('.');
-      const raw = node.$value;
-      if (raw === undefined) return; // Skip tokens without values
-      
-      const refs: TokenId[] = [];
-      
-      // Find all references in the value
-      if (typeof raw === 'string') {
-        const matches = raw.matchAll(REF_RE);
-        for (const match of matches) {
-          refs.push(match[1]);
-        }
-      }
-      
-      flat[id] = { 
-        id, 
-        type: String(node.$type ?? 'unknown'), 
-        value: raw,
-        raw, 
-        refs 
-      };
-      
-      // Add edges for dependencies
-      refs.forEach(refId => edges.push([refId, id]));
-      return;
-    }
-    
-    // Recursively walk children
-    for (const key of Object.keys(node)) {
-      if (key.startsWith('$')) continue;
-      const child = node[key];
-      if (typeof child === 'object' && child !== null) {
-        walk(child as TokenNode, path.concat(key));
-      }
-    }
-  }
-
-  walk(root);
-
-  // Second pass: resolve references iteratively
-  let changed = true;
-  let iterations = 0;
-  const maxIterations = Object.keys(flat).length * 2; // Safety limit
-  
-  while (changed && iterations < maxIterations) {
-    changed = false;
-    iterations++;
-    
-    for (const token of Object.values(flat)) {
-      if (typeof token.value === 'string' && token.value.includes('{')) {
-        let newValue = token.value;
-        let fullyResolved = true;
-        
-        for (const refId of token.refs) {
-          const refToken = flat[refId];
-          if (!refToken) {
-            throw new Error(`Could not resolve token ${refId}`);
-          }
-          
-          // If the referenced token still has unresolved refs, skip this iteration
-          if (typeof refToken.value === 'string' && refToken.value.includes('{')) {
-            fullyResolved = false;
-            break;
-          }
-          
-          // Replace the reference with the resolved value
-          const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
-          newValue = newValue.replace(refPattern, String(refToken.value));
-        }
-        
-        if (fullyResolved && newValue !== token.value) {
-          token.value = newValue;
-          changed = true;
-        }
-      }
-    }
-  }
-  
-  if (iterations >= maxIterations) {
-    throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
-  }
-
-  return { flat, edges };
-}
+export type TokenId = string; // e.g. "color.palette.brand.600"
+export type TokenValue = string | number;
+export type TokenNode = { 
+  $type?: string; 
+  $value?: TokenValue; 
+  [k: string]: TokenNode | string | number | undefined;
+};
+
+export type FlatToken = {
+  id: TokenId;
+  type: string;
+  value: TokenValue;       // resolved (if ref)
+  raw: TokenValue;         // original $value
+  refs: TokenId[];         // referenced token IDs found in raw
+};
+
+export type FlattenResult = {
+  flat: Record<TokenId, FlatToken>;
+  edges: Array<[from: TokenId, to: TokenId]>; // from ref -> to dependent
+};
+
+const REF_RE = /\{([a-z0-9.-]+)\}/gi;
+
+export function flattenTokens(root: TokenNode): FlattenResult {
+  const flat: Record<TokenId, FlatToken> = {};
+  const edges: Array<[TokenId, TokenId]> = [];
+
+  // First pass: collect all tokens
+  function walk(node: TokenNode, path: string[] = []) {
+    if (!node || typeof node !== 'object') return;
+    
+    if (Object.prototype.hasOwnProperty.call(node, '$value')) {
+      const id = path.join('.');
+      const raw = node.$value;
+      if (raw === undefined) return; // Skip tokens without values
+      
+      const refs: TokenId[] = [];
+      
+      // Find all references in the value
+      if (typeof raw === 'string') {
+        const matches = raw.matchAll(REF_RE);
+        for (const match of matches) {
+          refs.push(match[1]);
+        }
+      }
+      
+      flat[id] = { 
+        id, 
+        type: String(node.$type ?? 'unknown'), 
+        value: raw,
+        raw, 
+        refs 
+      };
+      
+      // Add edges for dependencies
+      refs.forEach(refId => edges.push([refId, id]));
+      return;
+    }
+    
+    // Recursively walk children
+    for (const key of Object.keys(node)) {
+      if (key.startsWith('$')) continue;
+      const child = node[key];
+      if (typeof child === 'object' && child !== null) {
+        walk(child as TokenNode, path.concat(key));
+      }
+    }
+  }
+
+  walk(root);
+
+  // Second pass: resolve references iteratively
+  let changed = true;
+  let iterations = 0;
+  const maxIterations = Object.keys(flat).length * 2; // Safety limit
+  
+  while (changed && iterations < maxIterations) {
+    changed = false;
+    iterations++;
+    
+    for (const token of Object.values(flat)) {
+      if (typeof token.value === 'string' && token.value.includes('{')) {
+        let newValue = token.value;
+        let fullyResolved = true;
+        
+        for (const refId of token.refs) {
+          const refToken = flat[refId];
+          if (!refToken) {
+            throw new Error(`Could not resolve token ${refId}`);
+          }
+          
+          // If the referenced token still has unresolved refs, skip this iteration
+          if (typeof refToken.value === 'string' && refToken.value.includes('{')) {
+            fullyResolved = false;
+            break;
+          }
+          
+          // Replace the reference with the resolved value
+          const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
+          newValue = newValue.replace(refPattern, String(refToken.value));
+        }
+        
+        if (fullyResolved && newValue !== token.value) {
+          token.value = newValue;
+          changed = true;
+        }
+      }
+    }
+  }
+  
+  if (iterations >= maxIterations) {
+    throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
+  }
+
+  return { flat, edges };
+}

package/core/image-export.ts

@@ -1,48 +1,48 @@
-// core/image-export.ts
-import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-
-function which(cmd: string): string | null {
-  const paths = (process.env.PATH || "").split(path.delimiter);
-  for (const p of paths) {
-    const full = path.join(p, cmd + (process.platform === "win32" ? ".cmd" : ""));
-    try { 
-      fs.accessSync(full, fs.constants.X_OK); 
-      return full; 
-    } catch {
-      // File not accessible, continue to next path
-    }
-  }
-  return null;
-}
-
-export type ImageFmt = "svg" | "png";
-export type Renderer = "mermaid" | "dot";
-
-export function exportGraphImage(
-  inputPath: string,              // .mmd or .dot we just wrote
-  outPath: string,                // .svg or .png to write
-  fmt: ImageFmt,                  // "svg" | "png"
-  renderer: Renderer              // "mermaid" | "dot"
-): { ok: boolean; hint?: string } {
-  if (renderer === "mermaid") {
-    const mmdc = which("mmdc");
-    if (!mmdc) {
-      return { ok: false, hint: "Install @mermaid-js/mermaid-cli (mmdc) to render images. Fallback written: .mmd" };
-    }
-    const args = ["-i", inputPath, "-o", outPath, "-t", "default", "-b", "transparent"];
-    if (fmt === "png") args.push("-p", "puppeteer-config.json"); // optional, if you keep one
-    const res = spawnSync(mmdc, args, { stdio: "inherit" });
-    return { ok: res.status === 0, hint: res.status !== 0 ? "mmdc failed; see logs." : undefined };
-  }
-
-  // renderer === "dot"
-  const dot = which("dot");
-  if (!dot) {
-    return { ok: false, hint: "Install Graphviz (dot) to render images. Fallback written: .dot" };
-  }
-  const argFmt = fmt === "svg" ? "-Tsvg" : "-Tpng";
-  const res = spawnSync(dot, [argFmt, inputPath, "-o", outPath], { stdio: "inherit" });
-  return { ok: res.status === 0, hint: res.status !== 0 ? "dot failed; see logs." : undefined };
-}
+// core/image-export.ts
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+function which(cmd: string): string | null {
+  const paths = (process.env.PATH || "").split(path.delimiter);
+  for (const p of paths) {
+    const full = path.join(p, cmd + (process.platform === "win32" ? ".cmd" : ""));
+    try { 
+      fs.accessSync(full, fs.constants.X_OK); 
+      return full; 
+    } catch {
+      // File not accessible, continue to next path
+    }
+  }
+  return null;
+}
+
+export type ImageFmt = "svg" | "png";
+export type Renderer = "mermaid" | "dot";
+
+export function exportGraphImage(
+  inputPath: string,              // .mmd or .dot we just wrote
+  outPath: string,                // .svg or .png to write
+  fmt: ImageFmt,                  // "svg" | "png"
+  renderer: Renderer              // "mermaid" | "dot"
+): { ok: boolean; hint?: string } {
+  if (renderer === "mermaid") {
+    const mmdc = which("mmdc");
+    if (!mmdc) {
+      return { ok: false, hint: "Install @mermaid-js/mermaid-cli (mmdc) to render images. Fallback written: .mmd" };
+    }
+    const args = ["-i", inputPath, "-o", outPath, "-t", "default", "-b", "transparent"];
+    if (fmt === "png") args.push("-p", "puppeteer-config.json"); // optional, if you keep one
+    const res = spawnSync(mmdc, args, { stdio: "inherit" });
+    return { ok: res.status === 0, hint: res.status !== 0 ? "mmdc failed; see logs." : undefined };
+  }
+
+  // renderer === "dot"
+  const dot = which("dot");
+  if (!dot) {
+    return { ok: false, hint: "Install Graphviz (dot) to render images. Fallback written: .dot" };
+  }
+  const argFmt = fmt === "svg" ? "-Tsvg" : "-Tpng";
+  const res = spawnSync(dot, [argFmt, inputPath, "-o", outPath], { stdio: "inherit" });
+  return { ok: res.status === 0, hint: res.status !== 0 ? "dot failed; see logs." : undefined };
+}

package/core/index.d.ts

@@ -1,31 +1,10 @@
-export type TokenId = string;
-export type TokenValue = string | number;
-export type Graph = Map<TokenId, Set<TokenId>>;
-export type ConstraintIssue = {
-    id: TokenId;
-    rule: string;
-    level: "error" | "warn";
-    message: string;
-};
-export type ConstraintPlugin = {
-    id: string;
-    evaluate(engine: Engine, candidates: Set<TokenId>): ConstraintIssue[];
-};
-export declare class Engine {
-    private values;
-    private graph;
-    private plugins;
-    constructor(initValues: Record<TokenId, TokenValue>, edges: Array<[TokenId, TokenId]>);
-    set(id: TokenId, value: TokenValue): void;
-    get(id: TokenId): TokenValue | undefined;
-    use(plugin: ConstraintPlugin): this;
-    affected(start: TokenId): Set<TokenId>;
-    evaluate(ids: Iterable<TokenId>): ConstraintIssue[];
-    /** Apply a single change and return a batch: affected set + issues + patch */
-    commit(id: TokenId, value: TokenValue): {
-        affected: string[];
-        issues: ConstraintIssue[];
-        patch: Record<string, TokenValue>;
-    };
-}
+/**
+ * Public API exports for Design Constraint Validator core.
+ *
+ * This file re-exports the main types and classes from the core engine.
+ * See engine.ts for full implementation with Phase 3C enhancements.
+ */
+export type { TokenId, TokenValue } from "./flatten.js";
+export type { ConstraintIssue, ConstraintPlugin, Graph } from "./engine.js";
+export { Engine } from "./engine.js";
 //# sourceMappingURL=index.d.ts.map

package/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAClC,GAAG,CAAC,EAAE,EAAE,OAAO;IAEf,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAKnC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAYtC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE;IAYnD,8EAA8E;IAC9E,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}