design-constraint-validator 1.0.0

package/core/index.js

@@ -0,0 +1,54 @@
+export class Engine {
+    values = new Map();
+    graph = new Map();
+    plugins = [];
+    constructor(initValues, edges) {
+        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());
+        }
+    }
+    set(id, value) { this.values.set(id, value); }
+    get(id) { return this.values.get(id); }
+    use(plugin) {
+        this.plugins.push(plugin);
+        return this;
+    }
+    affected(start) {
+        const seen = new Set();
+        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(ids) {
+        const candidates = new Set(ids);
+        const issues = [];
+        // Run all registered constraint plugins
+        for (const plugin of this.plugins) {
+            issues.push(...plugin.evaluate(this, candidates));
+        }
+        return issues;
+    }
+    /** Apply a single change and return a batch: affected set + issues + patch */
+    commit(id, value) {
+        this.set(id, value);
+        const A = this.affected(id);
+        const issues = this.evaluate([id, ...A]);
+        const patch = {};
+        patch[id] = value; // include dependents if you compute derived values
+        return { affected: Array.from(A), issues, patch };
+    }
+}

package/core/index.ts

@@ -0,0 +1,72 @@
+export type TokenId = string; // "dimension.spacing.scale.4"
+export type TokenValue = string | number;
+export type Graph = Map<TokenId, Set<TokenId>>; // edges: id -> dependents
+
+export type ConstraintIssue = {
+  id: TokenId;
+  rule: string;          // "wcag-contrast"
+  level: "error" | "warn";
+  message: string;
+};
+
+export type ConstraintPlugin = {
+  id: string;
+  evaluate(engine: Engine, candidates: Set<TokenId>): ConstraintIssue[];
+};
+
+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());
+    }
+  }
+
+  set(id: TokenId, value: TokenValue) { this.values.set(id, value); }
+  get(id: TokenId) { return this.values.get(id); }
+  
+  use(plugin: ConstraintPlugin): this {
+    this.plugins.push(plugin);
+    return this;
+  }
+
+  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(ids: Iterable<TokenId>): ConstraintIssue[] {
+    const candidates = new Set(ids);
+    const issues: ConstraintIssue[] = [];
+    
+    // Run all registered constraint plugins
+    for (const plugin of this.plugins) {
+      issues.push(...plugin.evaluate(this, candidates));
+    }
+    
+    return issues;
+  }
+
+  /** Apply a single change and return a batch: affected set + issues + patch */
+  commit(id: TokenId, value: TokenValue) {
+    this.set(id, value);
+    const A = this.affected(id);
+    const issues = this.evaluate([id, ...A]);
+    const patch: Record<TokenId, TokenValue> = {};
+    patch[id] = value; // include dependents if you compute derived values
+    return { affected: Array.from(A), issues, patch };
+  }
+}

package/core/patch.d.ts

@@ -0,0 +1,28 @@
+import type { TokenNode, TokenValue } from './flatten.js';
+export interface PatchChange {
+    id: string;
+    from: TokenValue | null | undefined;
+    to: TokenValue | null | undefined;
+    type: 'modify' | 'add' | 'remove';
+}
+export interface PatchDocument {
+    version: 1;
+    generatedAt: string;
+    baseFile?: string;
+    breakpoint?: string;
+    changes: PatchChange[];
+    patch: Record<string, TokenValue | null | undefined>;
+    hash: string;
+    baseTokensHash?: string;
+    meta?: Record<string, any>;
+}
+export interface BuildPatchOptions {
+    tokens: TokenNode;
+    baseFile?: string;
+    overrides?: Record<string, any>;
+    breakpoint?: string;
+    includeUnchanged?: boolean;
+}
+export declare function applyFlatOverrides(tokens: TokenNode, overrides?: Record<string, any>): void;
+export declare function buildPatch(opts: BuildPatchOptions): PatchDocument;
+//# sourceMappingURL=patch.d.ts.map

package/core/patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch.d.ts","sourceRoot":"","sources":["patch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IACpC,EAAE,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAMD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAuB3F;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAyEjE"}

package/core/patch.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { flattenTokens } from './flatten.js';
+function canonicalString(obj) {
+    return JSON.stringify(obj, Object.keys(obj).sort(), 2);
+}
+export function applyFlatOverrides(tokens, overrides) {
+    if (!overrides)
+        return;
+    for (const [id, val] of Object.entries(overrides)) {
+        const parts = id.split('.');
+        let cur = tokens;
+        for (let i = 0; i < parts.length; i++) {
+            const p = parts[i];
+            if (cur == null || typeof cur !== 'object')
+                break;
+            if (!(p in cur))
+                break;
+            if (i === parts.length - 1) {
+                const leaf = cur[p];
+                if (leaf && typeof leaf === 'object' && Object.prototype.hasOwnProperty.call(leaf, '$value')) {
+                    if (val === null) {
+                        // Do not delete here; handled later to keep reference resolution intact.
+                    }
+                    else {
+                        leaf.$value = val;
+                    }
+                }
+            }
+            else {
+                cur = cur[p];
+            }
+        }
+    }
+}
+export function buildPatch(opts) {
+    const cloned = JSON.parse(JSON.stringify(opts.tokens));
+    // Flatten original
+    const baseFlat = flattenTokens(cloned).flat;
+    // Canonical base tokens hash (id -> value) for drift detection when applying patch later
+    const baseFlatValues = {};
+    Object.keys(baseFlat).sort().forEach(id => { baseFlatValues[id] = baseFlat[id]?.value; });
+    const baseTokensHash = createHash('sha256').update(canonicalString(baseFlatValues)).digest('hex');
+    // Apply overrides on a fresh clone for diffing
+    const modified = JSON.parse(JSON.stringify(opts.tokens));
+    const removalIds = new Set();
+    if (opts.overrides) {
+        for (const [id, v] of Object.entries(opts.overrides)) {
+            if (v === null)
+                removalIds.add(id);
+        }
+    }
+    applyFlatOverrides(modified, opts.overrides);
+    const modFlat = flattenTokens(modified).flat;
+    // Post-process removals: remove from modFlat so diff sees them as missing
+    for (const id of removalIds) {
+        delete modFlat[id];
+    }
+    const changes = [];
+    const patch = {};
+    const visited = new Set();
+    for (const id of Object.keys(baseFlat)) {
+        visited.add(id);
+        const before = baseFlat[id]?.value;
+        const after = modFlat[id]?.value;
+        if (removalIds.has(id)) {
+            // Skip here; removal handled later
+            continue;
+        }
+        if (before !== after) {
+            changes.push({ id, from: before, to: after, type: 'modify' });
+            patch[id] = after;
+        }
+        else if (opts.includeUnchanged) {
+            changes.push({ id, from: before, to: after, type: 'modify' });
+        }
+    }
+    // Added ids (override referencing unknown id -> treat as add)
+    if (opts.overrides) {
+        for (const id of Object.keys(opts.overrides)) {
+            if (visited.has(id))
+                continue;
+            patch[id] = opts.overrides[id];
+            changes.push({ id, from: null, to: opts.overrides[id], type: 'add' });
+        }
+    }
+    // Removed ids (present in base, absent after overrides application)
+    for (const id of Object.keys(baseFlat)) {
+        if (!(id in modFlat)) {
+            const before = baseFlat[id]?.value;
+            patch[id] = null;
+            changes.push({ id, from: before, to: null, type: 'remove' });
+        }
+    }
+    // Sort deterministic
+    changes.sort((a, b) => a.id.localeCompare(b.id));
+    const patchSorted = {};
+    Object.keys(patch).sort().forEach(k => { patchSorted[k] = patch[k]; });
+    const hash = createHash('sha256').update(canonicalString(patchSorted)).digest('hex');
+    return {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        baseFile: opts.baseFile,
+        breakpoint: opts.breakpoint,
+        changes,
+        patch: patchSorted,
+        hash,
+        baseTokensHash,
+        meta: { changeCount: changes.length }
+    };
+}

package/core/patch.ts

@@ -0,0 +1,134 @@
+import { createHash } from 'node:crypto';
+import type { TokenNode, TokenValue } from './flatten.js';
+import { flattenTokens } from './flatten.js';
+
+export interface PatchChange {
+  id: string;
+  from: TokenValue | null | undefined;
+  to: TokenValue | null | undefined;
+  type: 'modify' | 'add' | 'remove';
+}
+
+export interface PatchDocument {
+  version: 1;
+  generatedAt: string; // ISO
+  baseFile?: string;
+  breakpoint?: string;
+  changes: PatchChange[];
+  patch: Record<string, TokenValue | null | undefined>; // id -> to value
+  hash: string; // sha256 of canonical patch object (patch + ids)
+  baseTokensHash?: string; // sha256 of canonical flattened base tokens (id -> value)
+  meta?: Record<string, any>;
+}
+
+export interface BuildPatchOptions {
+  tokens: TokenNode;           // raw hierarchical tokens
+  baseFile?: string;           // filename hint
+  overrides?: Record<string, any>; // flat override map id->value
+  breakpoint?: string;         // reserved for future responsive diffing
+  includeUnchanged?: boolean;  // debug flag
+}
+
+function canonicalString(obj: any): string {
+  return JSON.stringify(obj, Object.keys(obj).sort(), 2);
+}
+
+export function applyFlatOverrides(tokens: TokenNode, overrides?: Record<string, any>): void {
+  if (!overrides) return;
+  for (const [id, val] of Object.entries(overrides)) {
+    const parts = id.split('.');
+    let cur: any = tokens;
+    for (let i = 0; i < parts.length; i++) {
+      const p = parts[i];
+      if (cur == null || typeof cur !== 'object') break;
+      if (!(p in cur)) break;
+      if (i === parts.length - 1) {
+        const leaf = cur[p];
+        if (leaf && typeof leaf === 'object' && Object.prototype.hasOwnProperty.call(leaf, '$value')) {
+          if (val === null) {
+            // Do not delete here; handled later to keep reference resolution intact.
+          } else {
+            leaf.$value = val;
+          }
+        }
+      } else {
+        cur = cur[p];
+      }
+    }
+  }
+}
+
+export function buildPatch(opts: BuildPatchOptions): PatchDocument {
+  const cloned = JSON.parse(JSON.stringify(opts.tokens));
+  // Flatten original
+  const baseFlat = flattenTokens(cloned as any).flat as Record<string, any>;
+  // Canonical base tokens hash (id -> value) for drift detection when applying patch later
+  const baseFlatValues: Record<string, any> = {};
+  Object.keys(baseFlat).sort().forEach(id => { baseFlatValues[id] = baseFlat[id]?.value; });
+  const baseTokensHash = createHash('sha256').update(canonicalString(baseFlatValues)).digest('hex');
+  // Apply overrides on a fresh clone for diffing
+  const modified = JSON.parse(JSON.stringify(opts.tokens));
+  const removalIds = new Set<string>();
+  if (opts.overrides) {
+    for (const [id, v] of Object.entries(opts.overrides)) {
+      if (v === null) removalIds.add(id);
+    }
+  }
+  applyFlatOverrides(modified as any, opts.overrides);
+  const modFlat = flattenTokens(modified as any).flat as Record<string, any>;
+  // Post-process removals: remove from modFlat so diff sees them as missing
+  for (const id of removalIds) {
+    delete modFlat[id];
+  }
+
+  const changes: PatchChange[] = [];
+  const patch: Record<string, TokenValue | null | undefined> = {};
+  const visited = new Set<string>();
+  for (const id of Object.keys(baseFlat)) {
+    visited.add(id);
+    const before = baseFlat[id]?.value;
+    const after = modFlat[id]?.value;
+    if (removalIds.has(id)) {
+      // Skip here; removal handled later
+      continue;
+    }
+    if (before !== after) {
+      changes.push({ id, from: before, to: after, type: 'modify' });
+      patch[id] = after;
+    } else if (opts.includeUnchanged) {
+      changes.push({ id, from: before, to: after, type: 'modify' });
+    }
+  }
+  // Added ids (override referencing unknown id -> treat as add)
+  if (opts.overrides) {
+    for (const id of Object.keys(opts.overrides)) {
+      if (visited.has(id)) continue;
+      patch[id] = opts.overrides[id];
+      changes.push({ id, from: null, to: opts.overrides[id], type: 'add' });
+    }
+  }
+  // Removed ids (present in base, absent after overrides application)
+  for (const id of Object.keys(baseFlat)) {
+    if (!(id in modFlat)) {
+      const before = baseFlat[id]?.value;
+      patch[id] = null;
+      changes.push({ id, from: before, to: null, type: 'remove' });
+    }
+  }
+  // Sort deterministic
+  changes.sort((a, b) => a.id.localeCompare(b.id));
+  const patchSorted: Record<string, any> = {};
+  Object.keys(patch).sort().forEach(k => { patchSorted[k] = patch[k]; });
+  const hash = createHash('sha256').update(canonicalString(patchSorted)).digest('hex');
+  return {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    baseFile: opts.baseFile,
+    breakpoint: opts.breakpoint,
+    changes,
+    patch: patchSorted,
+    hash,
+  baseTokensHash,
+    meta: { changeCount: changes.length }
+  };
+}

package/core/poset.d.ts

@@ -0,0 +1,41 @@
+export type Id = string;
+export type Comp = "<=" | ">=";
+export type Order = [Id, Comp, Id];
+export type Digraph = Map<Id, Set<Id>>;
+export type EdgeLabels = Map<string, string>;
+/** Safe ID for Mermaid/DOT node identifiers */
+export declare function sanitizeId(id: string): string;
+export type Highlight = {
+    nodes?: Set<string>;
+    edges?: Set<string>;
+    color?: string;
+};
+export declare function buildPoset(orders: Order[]): Digraph;
+export declare function transitiveReduction(g: Digraph): Digraph;
+export declare function toMermaidHasse(gHasse: Digraph, { title }?: {
+    title?: string | undefined;
+}): string;
+export declare function toMermaidHasseStyled(g: Digraph, opts?: {
+    title?: string;
+    highlight?: Highlight;
+    labels?: EdgeLabels;
+}): string;
+export declare function toDotHasse(gHasse: Digraph, opts?: {
+    title?: string;
+    labels?: EdgeLabels;
+}): string;
+export declare function toDotHasseStyled(g: Digraph, opts?: {
+    title?: string;
+    highlight?: Highlight;
+    labels?: EdgeLabels;
+}): string;
+export declare function validatePoset(g: Digraph): {
+    valid: boolean;
+    cycles?: Id[][];
+};
+export declare function filterDigraph(g: Digraph, predicate: (id: string) => boolean): Digraph;
+export declare function filterByPrefix(g: Digraph, prefixes: string[]): Digraph;
+export declare function filterExcludePrefix(g: Digraph, prefixes: string[]): Digraph;
+export declare function khopSubgraph(g: Digraph, seeds: Set<string>, k?: number): Digraph;
+export declare function pickSeedsByPattern(nodes: Iterable<string>, pattern: string): Set<string>;
+//# sourceMappingURL=poset.d.ts.map

package/core/poset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poset.d.ts","sourceRoot":"","sources":["poset.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,EAAE,GAAG,MAAM,CAAC;AACxB,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAC/B,MAAM,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;AAEnC,MAAM,MAAM,OAAO,GAAG,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAGvC,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAM7C,+CAA+C;AAC/C,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAYnD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAwBvD;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,EAAE,EAAC,KAAe,EAAC;;CAAK,GAAG,MAAM,CAQ9E;AAGD,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,OAAO,EACV,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxE,MAAM,CAuCR;AAED,wBAAgB,UAAU,CACxB,MAAM,EAAE,OAAO,EACf,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACjD,MAAM,CAoBR;AAGD,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,OAAO,EACV,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAO,GACxE,MAAM,CAyCR;AAGD,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,CAAA;CAAE,CA2C7E;AAED,wBAAgB,aAAa,CAC3B,CAAC,EAAE,OAAO,EACV,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GACjC,OAAO,CAYT;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAKtE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAK3E;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,SAAI,GAAG,OAAO,CA8B3E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAOxF"}