design-constraint-validator 1.0.0

package/core/constraints/monotonic.js

@@ -0,0 +1,65 @@
+export function MonotonicPlugin(orders, parse, ruleId = "monotonic") {
+    return {
+        id: ruleId,
+        evaluate(engine, candidates) {
+            const issues = [];
+            for (const [a, op, b] of orders) {
+                const va = parse(engine.get(a));
+                const vb = parse(engine.get(b));
+                if (va == null || vb == null)
+                    continue; // skip unparseable
+                const ok = op === ">=" ? va >= vb : va <= vb;
+                if (!ok && (candidates.has(a) || candidates.has(b))) {
+                    issues.push({
+                        id: `${a}|${b}`,
+                        rule: "monotonic",
+                        level: "error",
+                        message: `${a} ${op} ${b} violated: ${va} vs ${vb}`
+                    });
+                }
+            }
+            return issues;
+        }
+    };
+}
+// a minimal parser for "rem"/"px" numbers
+export const parseSize = (v) => {
+    if (typeof v !== "string")
+        return null;
+    const m = v.trim().match(/^([0-9.]+)(rem|px)?$/i);
+    if (!m)
+        return null;
+    const num = parseFloat(m[1]);
+    const unit = (m[2] || "rem").toLowerCase();
+    return unit === "px" ? num : num * 16; // assume 1rem=16px for comparisons
+};
+// Parser for unitless numbers (like scale factors)
+export const parseNumber = (v) => {
+    if (typeof v === "number")
+        return v;
+    if (typeof v === "string") {
+        const num = parseFloat(v.trim());
+        return isNaN(num) ? null : num;
+    }
+    return null;
+};
+// Parser for color lightness (OKLCH L channel)
+export const parseLightness = (v) => {
+    if (typeof v !== "string")
+        return null;
+    // Match oklch(L C H / A) format
+    const oklchMatch = v.trim().match(/oklch\s*\(\s*([0-9.]+)\s+/i);
+    if (oklchMatch) {
+        return parseFloat(oklchMatch[1]);
+    }
+    // For hex colors, rough approximation (you'd want a proper converter)
+    const hexMatch = v.trim().match(/^#([0-9a-f]{6})$/i);
+    if (hexMatch) {
+        const r = parseInt(hexMatch[1].slice(0, 2), 16) / 255;
+        const g = parseInt(hexMatch[1].slice(2, 4), 16) / 255;
+        const b = parseInt(hexMatch[1].slice(4, 6), 16) / 255;
+        // Simple luminance approximation
+        return 0.299 * r + 0.587 * g + 0.114 * b;
+    }
+    return null;
+};

package/core/constraints/monotonic.ts

@@ -0,0 +1,74 @@
+// core/constraints/monotonic.ts
+import type { ConstraintPlugin } from "../engine.js";
+import type { Order } from "../poset.js";
+
+export function MonotonicPlugin(
+  orders: Order[], 
+  parse: (v: unknown) => number | null,
+  ruleId = "monotonic"
+): ConstraintPlugin {
+  return {
+    id: ruleId,
+    evaluate(engine, candidates) {
+      const issues = [];
+      for (const [a, op, b] of orders) {
+        const va = parse(engine.get(a));
+        const vb = parse(engine.get(b));
+        if (va == null || vb == null) continue; // skip unparseable
+        const ok = op === ">=" ? va >= vb : va <= vb;
+        if (!ok && (candidates.has(a) || candidates.has(b))) {
+          issues.push({
+            id: `${a}|${b}`,
+            rule: "monotonic",
+            level: "error" as const,
+            message: `${a} ${op} ${b} violated: ${va} vs ${vb}`
+          });
+        }
+      }
+      return issues;
+    }
+  };
+}
+
+// a minimal parser for "rem"/"px" numbers
+export const parseSize = (v: unknown): number | null => {
+  if (typeof v !== "string") return null;
+  const m = v.trim().match(/^([0-9.]+)(rem|px)?$/i);
+  if (!m) return null;
+  const num = parseFloat(m[1]);
+  const unit = (m[2] || "rem").toLowerCase();
+  return unit === "px" ? num : num * 16; // assume 1rem=16px for comparisons
+};
+
+// Parser for unitless numbers (like scale factors)
+export const parseNumber = (v: unknown): number | null => {
+  if (typeof v === "number") return v;
+  if (typeof v === "string") {
+    const num = parseFloat(v.trim());
+    return isNaN(num) ? null : num;
+  }
+  return null;
+};
+
+// Parser for color lightness (OKLCH L channel)
+export const parseLightness = (v: unknown): number | null => {
+  if (typeof v !== "string") return null;
+  
+  // Match oklch(L C H / A) format
+  const oklchMatch = v.trim().match(/oklch\s*\(\s*([0-9.]+)\s+/i);
+  if (oklchMatch) {
+    return parseFloat(oklchMatch[1]);
+  }
+  
+  // For hex colors, rough approximation (you'd want a proper converter)
+  const hexMatch = v.trim().match(/^#([0-9a-f]{6})$/i);
+  if (hexMatch) {
+    const r = parseInt(hexMatch[1].slice(0, 2), 16) / 255;
+    const g = parseInt(hexMatch[1].slice(2, 4), 16) / 255;
+    const b = parseInt(hexMatch[1].slice(4, 6), 16) / 255;
+    // Simple luminance approximation
+    return 0.299 * r + 0.587 * g + 0.114 * b;
+  }
+  
+  return null;
+};

package/core/constraints/threshold.d.ts

@@ -0,0 +1,10 @@
+import type { ConstraintPlugin } from "../engine.js";
+export type ThresholdRule = {
+    id: string;
+    op: ">=" | "<=";
+    valuePx: number;
+    where?: string;
+    level?: "error" | "warn";
+};
+export declare function ThresholdPlugin(rules: ThresholdRule[], ruleId?: string): ConstraintPlugin;
+//# sourceMappingURL=threshold.d.ts.map

package/core/constraints/threshold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["threshold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,CAAC;AAWF,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,SAAc,GAAG,gBAAgB,CAuB9F"}

package/core/constraints/threshold.js

@@ -0,0 +1,36 @@
+const parseSizePx = (v) => {
+    if (typeof v !== "string")
+        return null;
+    const m = v.trim().match(/^([0-9.]+)\s*(px|rem)?$/i);
+    if (!m)
+        return null;
+    const n = parseFloat(m[1]);
+    const unit = (m[2] || "px").toLowerCase();
+    return unit === "rem" ? n * 16 : n;
+};
+export function ThresholdPlugin(rules, ruleId = "threshold") {
+    return {
+        id: ruleId,
+        evaluate(engine, candidates) {
+            const issues = [];
+            for (const r of rules) {
+                if (!candidates.has(r.id))
+                    continue; // incremental
+                const px = parseSizePx(engine.get(r.id));
+                if (px == null)
+                    continue;
+                const ok = r.op === ">=" ? px >= r.valuePx : px <= r.valuePx;
+                if (!ok) {
+                    issues.push({
+                        id: r.id,
+                        rule: ruleId,
+                        level: r.level ?? "error",
+                        where: r.where,
+                        message: `${r.id} ${r.op} ${r.valuePx}px violated: ${px}px`
+                    });
+                }
+            }
+            return issues;
+        }
+    };
+}

package/core/constraints/threshold.ts

@@ -0,0 +1,43 @@
+import type { ConstraintPlugin } from "../engine.js";
+
+export type ThresholdRule = {
+  id: string;                    // token id to check
+  op: ">=" | "<=";               // comparison
+  valuePx: number;               // threshold in px
+  where?: string;                // optional context label
+  level?: "error" | "warn";      // default error
+};
+
+const parseSizePx = (v: unknown): number | null => {
+  if (typeof v !== "string") return null;
+  const m = v.trim().match(/^([0-9.]+)\s*(px|rem)?$/i);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  const unit = (m[2] || "px").toLowerCase();
+  return unit === "rem" ? n * 16 : n;
+};
+
+export function ThresholdPlugin(rules: ThresholdRule[], ruleId = "threshold"): ConstraintPlugin {
+  return {
+    id: ruleId,
+    evaluate(engine, candidates) {
+      const issues = [];
+      for (const r of rules) {
+        if (!candidates.has(r.id)) continue; // incremental
+        const px = parseSizePx(engine.get(r.id));
+        if (px == null) continue;
+        const ok = r.op === ">=" ? px >= r.valuePx : px <= r.valuePx;
+        if (!ok) {
+          issues.push({
+            id: r.id,
+            rule: ruleId,
+            level: r.level ?? "error",
+            where: r.where,
+            message: `${r.id} ${r.op} ${r.valuePx}px violated: ${px}px`
+          });
+        }
+      }
+      return issues;
+    }
+  };
+}

package/core/constraints/wcag.d.ts

@@ -0,0 +1,11 @@
+import type { ConstraintPlugin } from "../engine.js";
+import type { TokenId } from "../flatten.js";
+export type ContrastPair = {
+    fg: TokenId;
+    bg: TokenId;
+    min: number;
+    where?: string;
+    backdrop?: TokenId | string;
+};
+export declare function WcagContrastPlugin(pairs: ContrastPair[]): ConstraintPlugin;
+//# sourceMappingURL=wcag.d.ts.map

package/core/constraints/wcag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wcag.d.ts","sourceRoot":"","sources":["wcag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC7B,CAAC;AASF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,gBAAgB,CAiD1E"}

package/core/constraints/wcag.js

@@ -0,0 +1,53 @@
+import { parseCssColor, compositeOver, relativeLuminance, contrastRatio } from "../color.js";
+function resolveColor(engineGet, x) {
+    if (typeof x !== "string")
+        return undefined;
+    // If it's a CSS color literal, return as is; else treat as token id.
+    const isLiteral = /^#|^rgb|^hsl|^oklch|^oklab|^transparent/i.test(x);
+    return isLiteral ? x : String(engineGet(x) ?? "");
+}
+export function WcagContrastPlugin(pairs) {
+    return {
+        id: "wcag-contrast",
+        evaluate(engine, candidates) {
+            const issues = [];
+            for (const p of pairs) {
+                if (!candidates.has(p.fg) && !candidates.has(p.bg))
+                    continue;
+                const fgStr = String(engine.get(p.fg) ?? "");
+                const bgStr = String(engine.get(p.bg) ?? "");
+                const fg = parseCssColor(fgStr);
+                const bgRaw = parseCssColor(bgStr);
+                const backdropStr = resolveColor(engine.get.bind(engine), p.backdrop ?? "#ffffff");
+                const backdrop = parseCssColor(backdropStr || "#ffffff");
+                if (!fg || !bgRaw || !backdrop) {
+                    issues.push({
+                        id: `${p.fg}|${p.bg}`,
+                        rule: "wcag-contrast",
+                        level: "warn",
+                        where: p.where,
+                        message: `Unparseable color(s): fg="${fgStr}" bg="${bgStr}" backdrop="${backdropStr}"`
+                    });
+                    continue;
+                }
+                // Effective background (handle bg alpha)
+                const effBg = bgRaw.a < 1 ? compositeOver(bgRaw, backdrop) : bgRaw;
+                // Effective foreground over effective background
+                const effFg = fg.a < 1 ? compositeOver(fg, effBg) : fg;
+                const Lfg = relativeLuminance(effFg);
+                const Lbg = relativeLuminance(effBg);
+                const ratio = contrastRatio(Lfg, Lbg);
+                if (ratio < p.min) {
+                    issues.push({
+                        id: `${p.fg}|${p.bg}`,
+                        rule: "wcag-contrast",
+                        level: "error",
+                        where: p.where,
+                        message: `Contrast ${ratio.toFixed(2)}:1 < ${p.min}:1`
+                    });
+                }
+            }
+            return issues;
+        }
+    };
+}

package/core/constraints/wcag.ts

@@ -0,0 +1,70 @@
+import type { ConstraintPlugin } from "../engine.js";
+import type { TokenId } from "../flatten.js";
+import { parseCssColor, compositeOver, relativeLuminance, contrastRatio } from "../color.js";
+
+export type ContrastPair = {
+  fg: TokenId;
+  bg: TokenId;
+  min: number;           // e.g., 4.5
+  where?: string;
+  // Optional ultimate backdrop if bg is transparent; token id or literal color.
+  backdrop?: TokenId | string; // default: "#ffffff"
+};
+
+function resolveColor(engineGet: (id: TokenId)=>unknown, x: TokenId | string): string | undefined {
+  if (typeof x !== "string") return undefined;
+  // If it's a CSS color literal, return as is; else treat as token id.
+  const isLiteral = /^#|^rgb|^hsl|^oklch|^oklab|^transparent/i.test(x);
+  return isLiteral ? x : String(engineGet(x) ?? "");
+}
+
+export function WcagContrastPlugin(pairs: ContrastPair[]): ConstraintPlugin {
+  return {
+    id: "wcag-contrast",
+    evaluate(engine, candidates) {
+      const issues = [];
+      for (const p of pairs) {
+        if (!candidates.has(p.fg) && !candidates.has(p.bg)) continue;
+
+        const fgStr = String(engine.get(p.fg) ?? "");
+        const bgStr = String(engine.get(p.bg) ?? "");
+        const fg = parseCssColor(fgStr);
+        const bgRaw = parseCssColor(bgStr);
+
+        const backdropStr = resolveColor(engine.get.bind(engine), p.backdrop ?? "#ffffff");
+        const backdrop = parseCssColor(backdropStr || "#ffffff");
+
+        if (!fg || !bgRaw || !backdrop) {
+          issues.push({
+            id: `${p.fg}|${p.bg}`,
+            rule: "wcag-contrast",
+            level: "warn" as const,
+            where: p.where,
+            message: `Unparseable color(s): fg="${fgStr}" bg="${bgStr}" backdrop="${backdropStr}"`
+          });
+          continue;
+        }
+
+        // Effective background (handle bg alpha)
+        const effBg = bgRaw.a < 1 ? compositeOver(bgRaw, backdrop) : bgRaw;
+        // Effective foreground over effective background
+        const effFg = fg.a < 1 ? compositeOver(fg, effBg) : fg;
+
+        const Lfg = relativeLuminance(effFg);
+        const Lbg = relativeLuminance(effBg);
+        const ratio = contrastRatio(Lfg, Lbg);
+
+        if (ratio < p.min) {
+          issues.push({
+            id: `${p.fg}|${p.bg}`,
+            rule: "wcag-contrast",
+            level: "error" as const,
+            where: p.where,
+            message: `Contrast ${ratio.toFixed(2)}:1 < ${p.min}:1`
+          });
+        }
+      }
+      return issues;
+    }
+  };
+}

package/core/cross-axis-config.d.ts

@@ -0,0 +1,5 @@
+export declare function loadCrossAxisPlugin(path: string, bp?: string, opts?: {
+    debug?: boolean;
+    knownIds?: Set<string>;
+}): import("./engine.js").ConstraintPlugin;
+//# sourceMappingURL=cross-axis-config.d.ts.map

package/core/cross-axis-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-axis-config.d.ts","sourceRoot":"","sources":["cross-axis-config.ts"],"names":[],"mappings":"AAQA,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,0CA2HnD"}

package/core/cross-axis-config.js

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import { CrossAxisPlugin } from "./constraints/cross-axis.js";
+export function loadCrossAxisPlugin(path, bp, opts) {
+    const debug = !!opts?.debug;
+    const known = opts?.knownIds ?? new Set();
+    const log = (...args) => { if (debug)
+        console.log("[cross-axis]", ...args); };
+    if (!fs.existsSync(path)) {
+        log(`no rules file at ${path} (bp=${bp ?? "global"})`);
+        return CrossAxisPlugin([], bp);
+    }
+    const raw = JSON.parse(fs.readFileSync(path, "utf8"));
+    const rules = [];
+    const unknownIds = new Set();
+    const skipped = [];
+    // Fuzzy suggestion helpers (lightweight Levenshtein)
+    function levenshtein(a, b) {
+        const dp = Array(b.length + 1).fill(0).map((_, j) => j);
+        for (let i = 1; i <= a.length; i++) {
+            let prev = i - 1, cur = i;
+            for (let j = 1; j <= b.length; j++) {
+                const tmp = cur;
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                cur = Math.min(dp[j] + 1, cur + 1, prev + cost);
+                dp[j] = tmp;
+                prev = tmp;
+            }
+            dp[b.length] = cur;
+        }
+        return dp[b.length];
+    }
+    function suggest(id, k = 3) {
+        return [...known].map(c => ({ id: c, d: levenshtein(id, c) }))
+            .sort((a, b) => a.d - b.d)
+            .slice(0, k);
+    }
+    const needId = (id) => {
+        if (!id)
+            return false;
+        if (!known.has(id)) {
+            unknownIds.add(id);
+        }
+        return true;
+    };
+    for (const r of raw.rules || []) {
+        if (r.bp && bp && r.bp !== bp) {
+            continue;
+        }
+        if (r.bp && !bp) { // rule targets specific breakpoint; skip in global run
+            continue;
+        }
+        try {
+            if (r.when && r.require) {
+                // Validate IDs
+                needId(r.when.id);
+                needId(r.require.id);
+                if (r.require.ref)
+                    needId(r.require.ref);
+                rules.push({
+                    id: r.id, level: r.level, where: r.where,
+                    when: { id: r.when.id, test: makeOp(r.when.op, r.when.value) },
+                    require: {
+                        id: r.require.id,
+                        test: (v, ctx) => {
+                            const rhs = valueOrRef(ctx, r.require.ref, r.require.fallback);
+                            return cmp(v, rhs, r.require.op);
+                        },
+                        msg: (v, ctx) => {
+                            const rhs = valueOrRef(ctx, r.require.ref, r.require.fallback);
+                            return `${r.require.id} ${prettyFail(r.require.op)} ${fmt(rhs)} (was ${fmt(v)})`;
+                        }
+                    }
+                });
+            }
+            else if (r.compare) {
+                needId(r.compare.a);
+                needId(r.compare.b);
+                rules.push({
+                    id: r.id, level: r.level, where: r.where,
+                    when: { id: r.compare.a, test: () => true },
+                    require: {
+                        id: r.compare.a,
+                        test: (_, ctx) => {
+                            const a = ctx.getPx(r.compare.a) ?? NaN;
+                            const b = ctx.getPx(r.compare.b) ?? NaN;
+                            const delta = px(r.compare.delta ?? 0);
+                            if (Number.isNaN(a) || Number.isNaN(b))
+                                return true; // skip check if missing
+                            return cmp(a, b + delta, r.compare.op);
+                        },
+                        msg: (_, ctx) => {
+                            const a = ctx.getPx(r.compare.a);
+                            const b = ctx.getPx(r.compare.b);
+                            const delta = px(r.compare.delta ?? 0);
+                            return `${r.compare.a} ${prettyFail(r.compare.op)} ${fmt((b ?? 0) + delta)} (was ${fmt(a ?? NaN)})`;
+                        }
+                    }
+                });
+            }
+            else {
+                skipped.push({ id: r.id, reason: "neither when+require nor compare present" });
+            }
+        }
+        catch (e) {
+            skipped.push({ id: r.id, reason: `exception: ${e?.message ?? e}` });
+        }
+    }
+    log(`loaded ${rules.length} rule(s) from ${path}${bp ? ` [bp=${bp}]` : ""}`);
+    if (unknownIds.size) {
+        log(`unknown ids referenced:`, [...unknownIds].join(", "));
+        for (const u of unknownIds) {
+            const s = suggest(u, 3);
+            if (s.length)
+                log(`  did you mean: ${s.map(x => `${x.id} (d=${x.d})`).join(', ')}`);
+        }
+    }
+    if (skipped.length) {
+        for (const s of skipped)
+            log(`skipped rule ${s.id ?? "(no id)"} — ${s.reason}`);
+    }
+    // Extra hint for common anchor pitfall
+    for (const r of raw.rules || []) {
+        if (r.require?.ref && !known.has(r.require.ref)) {
+            log(`anchor missing: ${r.require.ref} → will use fallback=${JSON.stringify(r.require.fallback)} when evaluating`);
+        }
+    }
+    return CrossAxisPlugin(rules, bp);
+}
+// helpers
+const px = (v) => typeof v === "number" ? v : parseFloat(String(v)) * (String(v).trim().endsWith("rem") ? 16 : 1);
+const cmp = (a, b, op) => op === ">=" ? a >= b : op === ">" ? a > b : op === "<=" ? a <= b : op === "<" ? a < b : op === "==" ? a === b : a !== b;
+const prettyFail = (op) => ({ ">=": "<", ">": "≤", "<=": ">", "<": "≥", "==": "≠", "!=": "=" }[op] || "≠");
+const fmt = (v) => Number.isFinite(Number(v)) ? `${Number(v)}px` : String(v);
+function valueOrRef(ctx, ref, fallback) {
+    if (ref) {
+        const v = ctx.getPx(ref);
+        if (v != null)
+            return v;
+    }
+    return typeof fallback === "number" ? fallback : px(fallback ?? 0);
+}
+function makeOp(op, rhs) {
+    return (v) => cmp(v, rhs, op);
+}