design-constraint-validator 2.0.1 → 2.2.0

package/cli/validate-api.js

@@ -0,0 +1,90 @@
+/**
+ * Programmatic validation API.
+ *
+ * A thin convenience wrapper over the same flatten + engine + constraint-registry
+ * machinery the CLI uses, so library consumers (and the MCP server) get one call
+ * that takes tokens + constraints and returns structured violations — no argv, no
+ * process.exit, no prose.
+ *
+ * Re-exported from the package root (`design-constraint-validator`) via
+ * `core/index.ts`.
+ */
+import fs from 'node:fs';
+import { flattenTokens } from '../core/flatten.js';
+import { Engine } from '../core/engine.js';
+import { loadConfig } from './config.js';
+import { validateConfig } from './config-schema.js';
+import { setupConstraints, collectReferencedIds } from './constraint-registry.js';
+import { formatViolation } from './json-output.js';
+function readTokensFile(p) {
+    if (!fs.existsSync(p)) {
+        throw new Error(`Tokens file not found: ${p}`);
+    }
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`Tokens file is not valid JSON: ${p} (${detail})`);
+    }
+}
+function resolveConfig(input) {
+    if (input.constraints !== undefined) {
+        const { value, errors } = validateConfig({ constraints: input.constraints });
+        if (errors) {
+            throw new Error(`Inline constraints validation failed:\n  - ${errors.join('\n  - ')}`);
+        }
+        return value;
+    }
+    const res = loadConfig(input.configPath);
+    if (!res.ok) {
+        throw new Error(res.error);
+    }
+    return res.value;
+}
+/**
+ * Validate a token set against constraints and return structured results.
+ *
+ * Unlike the CLI, this treats `tokens` / `tokensPath` as the complete token set
+ * (no implicit cwd token overrides), so it is safe to call from a server that
+ * cannot share a filesystem with the caller.
+ */
+export function validate(input = {}) {
+    const tokens = input.tokens !== undefined
+        ? input.tokens
+        : input.tokensPath !== undefined
+            ? readTokensFile(input.tokensPath)
+            : {};
+    const config = resolveConfig(input);
+    const { flat, edges } = flattenTokens(tokens);
+    const init = {};
+    for (const t of Object.values(flat)) {
+        init[t.id] = t.value;
+    }
+    const engine = new Engine(init, edges);
+    const knownIds = new Set(Object.keys(init));
+    const sources = setupConstraints(engine, { config, bp: input.breakpoint, constraintsDir: input.constraintsDir ?? 'themes' }, { knownIds });
+    const issues = engine.evaluate(knownIds);
+    const errors = issues.filter((i) => i.level === 'error');
+    const warnings = issues.filter((i) => i.level !== 'error');
+    // No-match note: validated tokens that no active constraint references.
+    const coverage = collectReferencedIds(sources);
+    let matched = false;
+    for (const id of coverage.ids) {
+        if (knownIds.has(id)) {
+            matched = true;
+            break;
+        }
+    }
+    const note = knownIds.size > 0 && coverage.coverageKnown && !matched
+        ? `No active constraint references any of the ${knownIds.size} validated token(s) — nothing was checked. ` +
+            `Define constraints (constraints.wcag / constraints.thresholds) or point constraintsDir at your order/cross-axis files.`
+        : undefined;
+    return {
+        ok: errors.length === 0,
+        counts: { checked: issues.length, violations: errors.length, warnings: warnings.length },
+        violations: errors.map(formatViolation),
+        warnings: warnings.map(formatViolation),
+        note,
+    };
+}

package/cli/validate-api.ts

@@ -0,0 +1,131 @@
+/**
+ * Programmatic validation API.
+ *
+ * A thin convenience wrapper over the same flatten + engine + constraint-registry
+ * machinery the CLI uses, so library consumers (and the MCP server) get one call
+ * that takes tokens + constraints and returns structured violations — no argv, no
+ * process.exit, no prose.
+ *
+ * Re-exported from the package root (`design-constraint-validator`) via
+ * `core/index.ts`.
+ */
+import fs from 'node:fs';
+import { flattenTokens, type TokenNode, type FlatToken } from '../core/flatten.js';
+import { Engine, type ConstraintIssue } from '../core/engine.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import { loadConfig } from './config.js';
+import { validateConfig } from './config-schema.js';
+import { setupConstraints, collectReferencedIds } from './constraint-registry.js';
+import { formatViolation, type ConstraintViolation } from './json-output.js';
+import type { DcvConfig } from './types.js';
+
+export interface ValidateInput {
+  /** Inline tokens object (DTCG-style `$value`/`$type`). Takes precedence over `tokensPath`. */
+  tokens?: TokenNode;
+  /** Path to a tokens file. Used when `tokens` is not provided. */
+  tokensPath?: string;
+  /** Inline constraints config (the `constraints` block of dcv.config.json). Takes precedence over `configPath`. */
+  constraints?: DcvConfig['constraints'];
+  /** Path to a config file. When neither `constraints` nor `configPath` is given, a dcv.config.* in cwd is discovered. */
+  configPath?: string;
+  /** Directory holding order / cross-axis constraint files. Defaults to `themes`. */
+  constraintsDir?: string;
+  /** Optional breakpoint, selecting `<axis>.<bp>.order.json` / cross-axis variants. */
+  breakpoint?: Breakpoint;
+}
+
+export interface ValidateResult {
+  /** True when there are no error-level violations. */
+  ok: boolean;
+  counts: { checked: number; violations: number; warnings: number };
+  violations: ConstraintViolation[];
+  warnings: ConstraintViolation[];
+  /** Set when tokens were validated but no active constraint referenced any of them. */
+  note?: string;
+}
+
+function readTokensFile(p: string): TokenNode {
+  if (!fs.existsSync(p)) {
+    throw new Error(`Tokens file not found: ${p}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as TokenNode;
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    throw new Error(`Tokens file is not valid JSON: ${p} (${detail})`);
+  }
+}
+
+function resolveConfig(input: ValidateInput): DcvConfig {
+  if (input.constraints !== undefined) {
+    const { value, errors } = validateConfig({ constraints: input.constraints });
+    if (errors) {
+      throw new Error(`Inline constraints validation failed:\n  - ${errors.join('\n  - ')}`);
+    }
+    return value!;
+  }
+  const res = loadConfig(input.configPath);
+  if (!res.ok) {
+    throw new Error(res.error);
+  }
+  return res.value;
+}
+
+/**
+ * Validate a token set against constraints and return structured results.
+ *
+ * Unlike the CLI, this treats `tokens` / `tokensPath` as the complete token set
+ * (no implicit cwd token overrides), so it is safe to call from a server that
+ * cannot share a filesystem with the caller.
+ */
+export function validate(input: ValidateInput = {}): ValidateResult {
+  const tokens: TokenNode =
+    input.tokens !== undefined
+      ? input.tokens
+      : input.tokensPath !== undefined
+        ? readTokensFile(input.tokensPath)
+        : {};
+
+  const config = resolveConfig(input);
+
+  const { flat, edges } = flattenTokens(tokens);
+  const init: Record<string, string | number> = {};
+  for (const t of Object.values(flat)) {
+    init[(t as FlatToken).id] = (t as FlatToken).value;
+  }
+  const engine = new Engine(init, edges);
+  const knownIds = new Set(Object.keys(init));
+
+  const sources = setupConstraints(
+    engine,
+    { config, bp: input.breakpoint, constraintsDir: input.constraintsDir ?? 'themes' },
+    { knownIds },
+  );
+
+  const issues = engine.evaluate(knownIds);
+  const errors = issues.filter((i: ConstraintIssue) => i.level === 'error');
+  const warnings = issues.filter((i: ConstraintIssue) => i.level !== 'error');
+
+  // No-match note: validated tokens that no active constraint references.
+  const coverage = collectReferencedIds(sources);
+  let matched = false;
+  for (const id of coverage.ids) {
+    if (knownIds.has(id)) {
+      matched = true;
+      break;
+    }
+  }
+  const note =
+    knownIds.size > 0 && coverage.coverageKnown && !matched
+      ? `No active constraint references any of the ${knownIds.size} validated token(s) — nothing was checked. ` +
+        `Define constraints (constraints.wcag / constraints.thresholds) or point constraintsDir at your order/cross-axis files.`
+      : undefined;
+
+  return {
+    ok: errors.length === 0,
+    counts: { checked: issues.length, violations: errors.length, warnings: warnings.length },
+    violations: errors.map(formatViolation),
+    warnings: warnings.map(formatViolation),
+    note,
+  };
+}

package/core/breakpoints.d.ts

@@ -6,7 +6,13 @@ export declare function loadOrders(axis: string, bp?: Breakpoint): [string, "<="
 export declare function mergeTokens(base: unknown, overlay: unknown): TokenNode;
 /** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
 /**
- * Load tokens with override precedence: base < local < breakpoint
+ * Load tokens with override precedence: base < local < breakpoint.
+ *
+ * @param bp          optional breakpoint overlay (tokens/overrides/<bp>.json).
+ * @param tokensPath  explicit base tokens file. When provided, a missing or
+ *                    invalid file throws — callers must never silently validate
+ *                    an empty token set. When omitted, defaults to the repo
+ *                    example file and stays lenient (backward-compatible).
  */
-export declare function loadTokensWithBreakpoint(bp?: Breakpoint): TokenNode;
+export declare function loadTokensWithBreakpoint(bp?: Breakpoint, tokensPath?: string): TokenNode;
 //# sourceMappingURL=breakpoints.d.ts.map

package/core/breakpoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAM7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAKnE"}
+{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAM7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAkBxF"}

package/core/breakpoints.js

@@ -38,10 +38,31 @@ export function mergeTokens(base, overlay) {
 }
 /** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
 /**
- * Load tokens with override precedence: base < local < breakpoint
+ * Load tokens with override precedence: base < local < breakpoint.
+ *
+ * @param bp          optional breakpoint overlay (tokens/overrides/<bp>.json).
+ * @param tokensPath  explicit base tokens file. When provided, a missing or
+ *                    invalid file throws — callers must never silently validate
+ *                    an empty token set. When omitted, defaults to the repo
+ *                    example file and stays lenient (backward-compatible).
  */
-export function loadTokensWithBreakpoint(bp) {
-    const base = loadJsonSafe("tokens/tokens.example.json") ?? {};
+export function loadTokensWithBreakpoint(bp, tokensPath) {
+    let base;
+    if (tokensPath !== undefined) {
+        if (!fs.existsSync(tokensPath)) {
+            throw new Error(`Tokens file not found: ${tokensPath}`);
+        }
+        try {
+            base = JSON.parse(fs.readFileSync(tokensPath, "utf8"));
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            throw new Error(`Tokens file is not valid JSON: ${tokensPath} (${detail})`);
+        }
+    }
+    else {
+        base = loadJsonSafe("tokens/tokens.example.json") ?? {};
+    }
     const local = loadJsonSafe("tokens/overrides/local.json");
     const ov = bp ? loadJsonSafe(`tokens/overrides/${bp}.json`) : null;
     return mergeTokens(mergeTokens(base, local), ov);

package/core/breakpoints.ts

@@ -40,10 +40,29 @@ export function mergeTokens(base: unknown, overlay: unknown): TokenNode {
 
 /** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
 /**
- * Load tokens with override precedence: base < local < breakpoint
+ * Load tokens with override precedence: base < local < breakpoint.
+ *
+ * @param bp          optional breakpoint overlay (tokens/overrides/<bp>.json).
+ * @param tokensPath  explicit base tokens file. When provided, a missing or
+ *                    invalid file throws — callers must never silently validate
+ *                    an empty token set. When omitted, defaults to the repo
+ *                    example file and stays lenient (backward-compatible).
  */
-export function loadTokensWithBreakpoint(bp?: Breakpoint): TokenNode {
-  const base = loadJsonSafe<TokenNode>("tokens/tokens.example.json") ?? {};
+export function loadTokensWithBreakpoint(bp?: Breakpoint, tokensPath?: string): TokenNode {
+  let base: TokenNode;
+  if (tokensPath !== undefined) {
+    if (!fs.existsSync(tokensPath)) {
+      throw new Error(`Tokens file not found: ${tokensPath}`);
+    }
+    try {
+      base = JSON.parse(fs.readFileSync(tokensPath, "utf8")) as TokenNode;
+    } catch (e) {
+      const detail = e instanceof Error ? e.message : String(e);
+      throw new Error(`Tokens file is not valid JSON: ${tokensPath} (${detail})`);
+    }
+  } else {
+    base = loadJsonSafe<TokenNode>("tokens/tokens.example.json") ?? {};
+  }
   const local = loadJsonSafe<TokenNode>("tokens/overrides/local.json");
   const ov = bp ? loadJsonSafe<TokenNode>(`tokens/overrides/${bp}.json`) : null;
   return mergeTokens(mergeTokens(base, local), ov);

package/core/color.js

@@ -74,7 +74,7 @@ export function parseCssColor(input) {
         const C = Math.max(0, num(m[2]));
         const h = ((num(m[3]) % 360) + 360) % 360;
         const a = m[4] ? (m[4].includes("%") ? pct(m[4]) : num(m[4])) : 1;
-        const [r, g, b] = oklchToSrgb(L, C, h).map(v => clamp255(v * 255));
+        const [r, g, b] = oklchToLinearSrgb(L, C, h).map(v => linToSrgb(v));
         return { r, g, b, a: clamp01(a) };
     }
     // named "transparent"
@@ -103,8 +103,8 @@ function hslToRgb(H, S, L) {
     const m = L - C / 2;
     return { r: clamp255((r + m) * 255), g: clamp255((g + m) * 255), b: clamp255((b + m) * 255), a: 1 };
 }
-/* ---------- OKLCH → sRGB (0..1 channels) ---------- */
-function oklchToSrgb(L, C, hDeg) {
+/* ---------- OKLCH → linear sRGB (0..1 channels) ---------- */
+function oklchToLinearSrgb(L, C, hDeg) {
     const h = (hDeg * Math.PI) / 180;
     // OKLCH -> OKLab
     const a = C * Math.cos(h);
@@ -118,7 +118,7 @@ function oklchToSrgb(L, C, hDeg) {
     const R = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
     const G = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
     const B = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
-    // clamp to [0,1] (gamut clip)
+    // clamp to [0,1] (gamut clip). Callers gamma-encode to sRGB.
     return [clamp01(R), clamp01(G), clamp01(B)];
 }
 /* ---------- Alpha compositing (linear light) ---------- */

package/core/color.ts

@@ -87,7 +87,7 @@ export function parseCssColor(input: string | undefined | null): RGBA | null {
     const C = Math.max(0, num(m[2]));
     const h = ((num(m[3]) % 360) + 360) % 360;
     const a = m[4] ? (m[4].includes("%") ? pct(m[4]) : num(m[4])) : 1;
-    const [r, g, b] = oklchToSrgb(L, C, h).map(v => clamp255(v * 255));
+    const [r, g, b] = oklchToLinearSrgb(L, C, h).map(v => linToSrgb(v));
     return { r, g, b, a: clamp01(a) };
   }
 
@@ -113,8 +113,8 @@ function hslToRgb(H: number, S: number, L: number): RGBA {
   return { r: clamp255((r + m) * 255), g: clamp255((g + m) * 255), b: clamp255((b + m) * 255), a: 1 };
 }
 
-/* ---------- OKLCH → sRGB (0..1 channels) ---------- */
-function oklchToSrgb(L: number, C: number, hDeg: number): [number, number, number] {
+/* ---------- OKLCH → linear sRGB (0..1 channels) ---------- */
+function oklchToLinearSrgb(L: number, C: number, hDeg: number): [number, number, number] {
   const h = (hDeg * Math.PI) / 180;
   // OKLCH -> OKLab
   const a = C * Math.cos(h);
@@ -128,7 +128,7 @@ function oklchToSrgb(L: number, C: number, hDeg: number): [number, number, numbe
   const R = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
   const G = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
   const B = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
-  // clamp to [0,1] (gamut clip)
+  // clamp to [0,1] (gamut clip). Callers gamma-encode to sRGB.
   return [clamp01(R), clamp01(G), clamp01(B)];
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"cross-axis.d.ts","sourceRoot":"","sources":["cross-axis.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,aAAa,GACrB;IACE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,GAAC,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACnD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;KAAE,CAAC;IACnD,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;QAAC,GAAG,EAAE,CAAC,CAAC,EAAC,MAAM,EAAE,GAAG,EAAE,GAAG,KAAI,MAAM,CAAA;KAAE,CAAC;CACrG,GACD;IACE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,GAAC,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACnD,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAI,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,IAAI,EAAC,MAAM,EAAC,EAAE,EAAC,MAAM,EAAC,GAAG,EAAE,GAAG,KAAI,MAAM,CAAA;KAAE,CAAC;CACvH,CAAC;AAEN,MAAM,MAAM,GAAG,GAAG;IAChB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAqBF,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAqDrF;AAGD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,aAAa,EAAE,CAkBlG"}
+{"version":3,"file":"cross-axis.d.ts","sourceRoot":"","sources":["cross-axis.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,aAAa,GACrB;IACE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,GAAC,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACnD,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAA;KAAE,CAAC;IACnD,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;QAAC,GAAG,EAAE,CAAC,CAAC,EAAC,MAAM,EAAE,GAAG,EAAE,GAAG,KAAI,MAAM,CAAA;KAAE,CAAC;CACrG,GACD;IACE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,GAAC,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACnD,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAI,MAAM,CAAC;QAAC,KAAK,EAAE,CAAC,IAAI,EAAC,MAAM,EAAC,EAAE,EAAC,MAAM,EAAC,GAAG,EAAE,GAAG,KAAI,MAAM,CAAA;KAAE,CAAC;CACvH,CAAC;AAEN,MAAM,MAAM,GAAG,GAAG;IAChB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACjC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC;AAsCF,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAgErF;AAGD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,SAAI,GAAG,aAAa,EAAE,CAkBlG"}

package/core/constraints/cross-axis.js

@@ -1,23 +1,40 @@
+// Shares the hardened finite-size policy used by monotonic/threshold (TASK-037):
+// bare numbers / unitless as px, `rem`/`em` as 16px-relative, real numbers only
+// (rejects ".", "5.", "1.2.3px"), and non-finite guarded. The one addition over
+// the canonical parser is a clamp()/min()/max()/calc() heuristic — but it is
+// gated on a `(` so a malformed bare value like "1.2.3px" is rejected rather
+// than silently yielding a partial parse.
 const px = (v) => {
     if (typeof v === 'number')
-        return v;
+        return Number.isFinite(v) ? v : null;
     if (typeof v !== 'string')
         return null;
     const trimmed = v.trim();
-    // Direct simple form
-    let m = trimmed.match(/^([0-9.]+)\s*(px|rem)?$/i);
+    // Direct simple form: bare number / px / rem / em.
+    const m = trimmed.match(/^(\d*\.?\d+)\s*(px|rem|em)?$/i);
     if (m) {
         const n = parseFloat(m[1]);
-        return (m[2] || 'px').toLowerCase() === 'rem' ? n * 16 : n;
+        if (!Number.isFinite(n))
+            return null;
+        const unit = (m[2] || 'px').toLowerCase();
+        return unit === 'rem' || unit === 'em' ? n * 16 : n;
     }
-    // Heuristic: extract first numeric size token (px or rem) inside complex expressions (e.g., clamp())
-    const inner = trimmed.match(/([0-9.]+)\s*(px|rem)/i);
-    if (inner) {
-        const n = parseFloat(inner[1]);
-        return inner[2].toLowerCase() === 'rem' ? n * 16 : n;
+    // Heuristic: first px/rem/em token inside a CSS function expression (clamp(),
+    // min(), max(), calc(), …). Gated on `(` so garbage simple values don't leak.
+    if (trimmed.includes('(')) {
+        const inner = trimmed.match(/(\d*\.?\d+)\s*(px|rem|em)/i);
+        if (inner) {
+            const n = parseFloat(inner[1]);
+            if (!Number.isFinite(n))
+                return null;
+            return inner[2].toLowerCase() === 'px' ? n : n * 16;
+        }
     }
     return null;
 };
+// Distinguish "operand absent" (skip silently) from "operand present but
+// unparseable" (warn loudly) — a silent skip of a present value is a false green.
+const presentButUnparseable = (raw) => raw != null && raw !== '' && px(raw) === null;
 export function CrossAxisPlugin(rules, bp) {
     return {
         id: "cross-axis",
@@ -33,6 +50,17 @@ export function CrossAxisPlugin(rules, bp) {
                     // Evaluate if either referenced id is among candidates (looser gating so global validate works)
                     if (!candidates.has(r.when.id) && !candidates.has(r.require.id))
                         continue;
+                    // Present-but-unparseable operand → warn, don't silently skip (TASK-037).
+                    if (presentButUnparseable(ctx.get(r.when.id)) || presentButUnparseable(ctx.get(r.require.id))) {
+                        issues.push({
+                            id: r.require.id,
+                            rule: "cross-axis",
+                            level: "warn",
+                            where: r.where,
+                            message: `Cannot check cross-axis rule "${r.id}": unparseable size value(s)`
+                        });
+                        continue;
+                    }
                     const wv = ctx.getPx(r.when.id);
                     // compare-style loader rules set when.id = a, require.id = a; use same value if second missing
                     let rv = ctx.getPx(r.require.id);

package/core/constraints/cross-axis.ts

@@ -18,25 +18,42 @@ export type Ctx = {
   bp?: string;
 };
 
+// Shares the hardened finite-size policy used by monotonic/threshold (TASK-037):
+// bare numbers / unitless as px, `rem`/`em` as 16px-relative, real numbers only
+// (rejects ".", "5.", "1.2.3px"), and non-finite guarded. The one addition over
+// the canonical parser is a clamp()/min()/max()/calc() heuristic — but it is
+// gated on a `(` so a malformed bare value like "1.2.3px" is rejected rather
+// than silently yielding a partial parse.
 const px = (v: unknown): number | null => {
-  if (typeof v === 'number') return v;
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null;
   if (typeof v !== 'string') return null;
   const trimmed = v.trim();
-  // Direct simple form
-  let m = trimmed.match(/^([0-9.]+)\s*(px|rem)?$/i);
+  // Direct simple form: bare number / px / rem / em.
+  const m = trimmed.match(/^(\d*\.?\d+)\s*(px|rem|em)?$/i);
   if (m) {
     const n = parseFloat(m[1]);
-    return (m[2] || 'px').toLowerCase() === 'rem' ? n * 16 : n;
+    if (!Number.isFinite(n)) return null;
+    const unit = (m[2] || 'px').toLowerCase();
+    return unit === 'rem' || unit === 'em' ? n * 16 : n;
   }
-  // Heuristic: extract first numeric size token (px or rem) inside complex expressions (e.g., clamp())
-  const inner = trimmed.match(/([0-9.]+)\s*(px|rem)/i);
-  if (inner) {
-    const n = parseFloat(inner[1]);
-    return inner[2].toLowerCase() === 'rem' ? n * 16 : n;
+  // Heuristic: first px/rem/em token inside a CSS function expression (clamp(),
+  // min(), max(), calc(), …). Gated on `(` so garbage simple values don't leak.
+  if (trimmed.includes('(')) {
+    const inner = trimmed.match(/(\d*\.?\d+)\s*(px|rem|em)/i);
+    if (inner) {
+      const n = parseFloat(inner[1]);
+      if (!Number.isFinite(n)) return null;
+      return inner[2].toLowerCase() === 'px' ? n : n * 16;
+    }
   }
   return null;
 };
 
+// Distinguish "operand absent" (skip silently) from "operand present but
+// unparseable" (warn loudly) — a silent skip of a present value is a false green.
+const presentButUnparseable = (raw: unknown): boolean =>
+  raw != null && raw !== '' && px(raw) === null;
+
 export function CrossAxisPlugin(rules: CrossAxisRule[], bp?: string): ConstraintPlugin {
   return {
     id: "cross-axis",
@@ -57,6 +74,17 @@ export function CrossAxisPlugin(rules: CrossAxisRule[], bp?: string): Constraint
         if ("when" in r) {
           // Evaluate if either referenced id is among candidates (looser gating so global validate works)
           if (!candidates.has(r.when.id) && !candidates.has(r.require.id)) continue;
+          // Present-but-unparseable operand → warn, don't silently skip (TASK-037).
+          if (presentButUnparseable(ctx.get(r.when.id)) || presentButUnparseable(ctx.get(r.require.id))) {
+            issues.push({
+              id: r.require.id,
+              rule: "cross-axis",
+              level: "warn",
+              where: r.where,
+              message: `Cannot check cross-axis rule "${r.id}": unparseable size value(s)`
+            });
+            continue;
+          }
           const wv = ctx.getPx(r.when.id);
           // compare-style loader rules set when.id = a, require.id = a; use same value if second missing
           let rv = ctx.getPx(r.require.id);

package/core/constraints/monotonic-lightness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"monotonic-lightness.d.ts","sourceRoot":"","sources":["monotonic-lightness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOxD;AAED,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAElD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAuBpE"}
+{"version":3,"file":"monotonic-lightness.d.ts","sourceRoot":"","sources":["monotonic-lightness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAYxD;AAED,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAElD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAuBpE"}

package/core/constraints/monotonic-lightness.js

@@ -2,11 +2,15 @@ import { parseCssColor, relativeLuminance } from "../color.js";
 export function parseLightness(v) {
     if (typeof v !== "string")
         return null;
-    const s = v.trim().toLowerCase();
-    const m = /^oklch\(\s*([0-9.]+%?)\s+/.exec(s);
-    if (m)
-        return m[1].includes("%") ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
-    const rgba = parseCssColor(s);
+    // ONE consistent lightness scale for every format. parseCssColor handles
+    // hex / rgb / hsl / oklch (oklch→sRGB is the verified TASK-005 pipeline), so we
+    // always compare WCAG relative luminance.
+    //
+    // BUG FIXED (TASK-009): oklch() previously short-circuited to its raw perceptual
+    // L coordinate — a DIFFERENT scale from the relative luminance used for hex. A
+    // scale mixing the two formats then compared incomparable numbers (e.g. oklch L
+    // 0.60 vs hex luminance 0.216 for the same gray), yielding false pass/fail.
+    const rgba = parseCssColor(v.trim());
     return rgba ? relativeLuminance(rgba) : null;
 }
 export function MonotonicLightness(orders) {

package/core/constraints/monotonic-lightness.ts

@@ -3,10 +3,15 @@ import { parseCssColor, relativeLuminance } from "../color.js";
 
 export function parseLightness(v: unknown): number | null {
   if (typeof v !== "string") return null;
-  const s = v.trim().toLowerCase();
-  const m = /^oklch\(\s*([0-9.]+%?)\s+/.exec(s);
-  if (m) return m[1].includes("%") ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
-  const rgba = parseCssColor(s);
+  // ONE consistent lightness scale for every format. parseCssColor handles
+  // hex / rgb / hsl / oklch (oklch→sRGB is the verified TASK-005 pipeline), so we
+  // always compare WCAG relative luminance.
+  //
+  // BUG FIXED (TASK-009): oklch() previously short-circuited to its raw perceptual
+  // L coordinate — a DIFFERENT scale from the relative luminance used for hex. A
+  // scale mixing the two formats then compared incomparable numbers (e.g. oklch L
+  // 0.60 vs hex luminance 0.216 for the same gray), yielding false pass/fail.
+  const rgba = parseCssColor(v.trim());
   return rgba ? relativeLuminance(rgba) : null;
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"monotonic.d.ts","sourceRoot":"","sources":["monotonic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,EACpC,MAAM,SAAc,GACnB,gBAAgB,CAsBlB;AAGD,eAAO,MAAM,SAAS,GAAI,GAAG,OAAO,KAAG,MAAM,GAAG,IAO/C,CAAC;AAGF,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,MAAM,GAAG,IAOjD,CAAC;AAGF,eAAO,MAAM,cAAc,GAAI,GAAG,OAAO,KAAG,MAAM,GAAG,IAoBpD,CAAC"}
+{"version":3,"file":"monotonic.d.ts","sourceRoot":"","sources":["monotonic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,wBAAgB,eAAe,CAC7B,MAAM,EAAE,KAAK,EAAE,EACf,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,GAAG,IAAI,EACpC,MAAM,SAAc,GACnB,gBAAgB,CAoClB;AAMD,eAAO,MAAM,SAAS,GAAI,GAAG,OAAO,KAAG,MAAM,GAAG,IAW/C,CAAC;AAGF,eAAO,MAAM,WAAW,GAAI,GAAG,OAAO,KAAG,MAAM,GAAG,IAOjD,CAAC;AAGF,eAAO,MAAM,cAAc,GAAI,GAAG,OAAO,KAAG,MAAM,GAAG,IAoBpD,CAAC"}

package/core/constraints/monotonic.js

@@ -4,12 +4,27 @@ export function MonotonicPlugin(orders, parse, ruleId = "monotonic") {
         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 (!candidates.has(a) && !candidates.has(b))
+                    continue; // incremental
+                const rawA = engine.get(a);
+                const rawB = engine.get(b);
+                const va = parse(rawA);
+                const vb = parse(rawB);
+                // A present-but-unparseable size operand (e.g. "50%", "10vw") can't be
+                // compared — warn instead of silently skipping (TASK-031).
+                if ((rawA != null && rawA !== "" && va == null) || (rawB != null && rawB !== "" && vb == null)) {
+                    issues.push({
+                        id: `${a}|${b}`,
+                        rule: "monotonic",
+                        level: "warn",
+                        message: `Cannot check ${a} ${op} ${b}: unparseable size value(s)`
+                    });
+                    continue;
+                }
                 if (va == null || vb == null)
-                    continue; // skip unparseable
+                    continue; // operand absent — nothing to check
                 const ok = op === ">=" ? va >= vb : va <= vb;
-                if (!ok && (candidates.has(a) || candidates.has(b))) {
+                if (!ok) {
                     issues.push({
                         id: `${a}|${b}`,
                         rule: "monotonic",
@@ -22,16 +37,25 @@ export function MonotonicPlugin(orders, parse, ruleId = "monotonic") {
         }
     };
 }
-// a minimal parser for "rem"/"px" numbers
+// Parse a size to px for comparison. Coerces bare numbers and unitless strings to
+// px (TASK-031: numeric `$value` and aliases-to-numbers previously returned null,
+// silently skipping the rule). `rem`/`em` are 16px-relative. Returns null only for
+// genuinely unparseable operands (e.g. "50%", "10vw") — callers warn, not skip.
 export const parseSize = (v) => {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : null; // bare number == px
     if (typeof v !== "string")
         return null;
-    const m = v.trim().match(/^([0-9.]+)(rem|px)?$/i);
+    // Real number only: rejects ".", "5.", "1.2.3px" (which previously slipped
+    // through `[0-9.]+` + parseFloat as NaN/garbage and became spurious errors).
+    const m = v.trim().match(/^(\d*\.?\d+)\s*(px|rem|em)?$/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
+    if (!Number.isFinite(num))
+        return null;
+    const unit = (m[2] || "px").toLowerCase();
+    return unit === "rem" || unit === "em" ? num * 16 : num; // px and unitless as-is
 };
 // Parser for unitless numbers (like scale factors)
 export const parseNumber = (v) => {