design-constraint-validator 1.0.0 → 2.0.1

package/cli/constraint-registry.ts

@@ -0,0 +1,304 @@
+/**
+ * Centralized constraint discovery and loading.
+ *
+ * This module provides a single source of truth for determining which constraints
+ * are active for a given validation run. It replaces the scattered constraint-loading
+ * logic previously split across engine-helpers.ts and constraints-loader.ts.
+ *
+ * Design principles:
+ * - Constraints are discovered from config and filesystem in ONE place
+ * - Core modules receive in-memory data (no filesystem access)
+ * - All entry points (validate, set, graph) use this registry for consistency
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Engine } from '../core/engine.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import type { DcvConfig } from './types.js';
+import { MonotonicPlugin, parseSize as parseSizePx } from '../core/constraints/monotonic.js';
+import { MonotonicLightness } from '../core/constraints/monotonic-lightness.js';
+import { WcagContrastPlugin } from '../core/constraints/wcag.js';
+import { ThresholdPlugin } from '../core/constraints/threshold.js';
+import { CrossAxisPlugin } from '../core/constraints/cross-axis.js';
+import { loadCrossAxisRules } from './cross-axis-loader.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type OrderRule = [string, '<=' | '>=', string];
+
+export type WcagRule = {
+  fg: string;
+  bg: string;
+  min: number;
+  where: string;
+  backdrop?: string;
+};
+
+export type ThresholdRule = {
+  id: string;
+  op: '<=' | '>=';
+  valuePx: number;
+  where?: string;
+  level?: 'error' | 'warn';
+};
+
+/**
+ * Represents a constraint source discovered from config or filesystem.
+ */
+export type ConstraintSource =
+  | { type: 'builtin-wcag'; enabled: boolean }
+  | { type: 'builtin-threshold'; enabled: boolean }
+  | { type: 'config-wcag'; rules: WcagRule[] }
+  | { type: 'order-file'; axis: string; orders: OrderRule[]; path: string }
+  | { type: 'lightness-file'; orders: OrderRule[]; path: string }
+  | { type: 'cross-axis-file'; path: string; bp?: Breakpoint }
+  | { type: 'custom-threshold'; rules: ThresholdRule[] };
+
+export type DiscoveryOptions = {
+  config: DcvConfig;
+  basePath?: string;
+  bp?: Breakpoint;
+  constraintsDir?: string;
+};
+
+export type AttachOptions = {
+  knownIds: Set<string>;
+  crossAxisDebug?: boolean;
+};
+
+// ============================================================================
+// Discovery
+// ============================================================================
+
+/**
+ * Discover all constraint sources for a given configuration and breakpoint.
+ *
+ * This function scans the filesystem and config to determine which constraints
+ * should be active, but does not load or attach them yet.
+ *
+ * @param opts Discovery options (config, basePath, breakpoint)
+ * @returns Array of constraint sources
+ */
+export function discoverConstraints(opts: DiscoveryOptions): ConstraintSource[] {
+  const { config, basePath = '.', bp, constraintsDir = 'themes' } = opts;
+  const sources: ConstraintSource[] = [];
+  const constraintsCfg = config.constraints ?? {};
+
+  // 1. Built-in WCAG defaults
+  const enableBuiltInWcag =
+    constraintsCfg.enableBuiltInWcagDefaults === undefined ? true : !!constraintsCfg.enableBuiltInWcagDefaults;
+
+  if (enableBuiltInWcag) {
+    sources.push({ type: 'builtin-wcag', enabled: true });
+  }
+
+  // 2. Built-in threshold (44px touch target)
+  const enableBuiltInThreshold =
+    constraintsCfg.enableBuiltInThreshold === undefined ? true : !!constraintsCfg.enableBuiltInThreshold;
+
+  if (enableBuiltInThreshold) {
+    sources.push({ type: 'builtin-threshold', enabled: true });
+  }
+
+  // 3. Config-defined WCAG rules
+  if (constraintsCfg.wcag && Array.isArray(constraintsCfg.wcag) && constraintsCfg.wcag.length > 0) {
+    const rules: WcagRule[] = constraintsCfg.wcag.map((r: any) => ({
+      fg: r.foreground,
+      bg: r.background,
+      min: r.ratio || 4.5,
+      where: r.description || 'Unknown',
+      backdrop: r.backdrop,
+    }));
+    sources.push({ type: 'config-wcag', rules });
+  }
+
+  // 4. Config-defined threshold rules
+  if (constraintsCfg.thresholds && Array.isArray(constraintsCfg.thresholds) && constraintsCfg.thresholds.length > 0) {
+    const rules: ThresholdRule[] = constraintsCfg.thresholds.map((r: any) => ({
+      id: r.id,
+      op: r.op,
+      valuePx: r.valuePx,
+      where: r.where,
+    }));
+    sources.push({ type: 'custom-threshold', rules });
+  }
+
+  // 5. Order files (monotonic constraints)
+  const axes = ['typography', 'spacing', 'layout'] as const;
+  for (const axis of axes) {
+    const suffix = bp ? `.${bp}` : '';
+    const orderPath = join(basePath, constraintsDir, `${axis}${suffix}.order.json`);
+
+    if (existsSync(orderPath)) {
+      try {
+        const data = JSON.parse(readFileSync(orderPath, 'utf8'));
+        const orders: OrderRule[] = data.order || [];
+        if (orders.length > 0) {
+          sources.push({ type: 'order-file', axis, orders, path: orderPath });
+        }
+      } catch {
+        // Silently skip malformed order files (consistent with old behavior)
+      }
+    }
+  }
+
+  // 6. Color lightness order files
+  const suffix = bp ? `.${bp}` : '';
+  const colorOrderPath = join(basePath, constraintsDir, `color${suffix}.order.json`);
+
+  if (existsSync(colorOrderPath)) {
+    try {
+      const data = JSON.parse(readFileSync(colorOrderPath, 'utf8'));
+      const orders: OrderRule[] = data.order || [];
+      if (orders.length > 0) {
+        sources.push({ type: 'lightness-file', orders, path: colorOrderPath });
+      }
+    } catch {
+      // Silently skip malformed color order files
+    }
+  }
+
+  // 7. Cross-axis rules (global)
+  const crossAxisPath = join(basePath, constraintsDir, 'cross-axis.rules.json');
+  if (existsSync(crossAxisPath)) {
+    sources.push({ type: 'cross-axis-file', path: crossAxisPath });
+  }
+
+  // 8. Cross-axis rules (breakpoint-specific)
+  if (bp) {
+    const crossAxisBpPath = join(basePath, constraintsDir, `cross-axis.${bp}.rules.json`);
+    if (existsSync(crossAxisBpPath)) {
+      sources.push({ type: 'cross-axis-file', path: crossAxisBpPath, bp });
+    }
+  }
+
+  return sources;
+}
+
+// ============================================================================
+// Attachment
+// ============================================================================
+
+/**
+ * Attach constraint plugins to an engine based on discovered sources.
+ *
+ * This function takes the output of `discoverConstraints()` and registers
+ * the appropriate plugins on the engine.
+ *
+ * @param engine Engine to attach plugins to
+ * @param sources Constraint sources (from discoverConstraints)
+ * @param opts Attachment options (knownIds, debug flags)
+ */
+export function attachConstraints(engine: Engine, sources: ConstraintSource[], opts: AttachOptions): void {
+  const { knownIds, crossAxisDebug = false } = opts;
+
+  for (const source of sources) {
+    try {
+      switch (source.type) {
+        case 'builtin-wcag': {
+          if (source.enabled) {
+            const defaultWcagPairs: WcagRule[] = [
+              {
+                fg: 'color.role.text.default',
+                bg: 'color.role.bg.surface',
+                min: 4.5,
+                where: 'Body text on surface',
+              },
+              {
+                fg: 'color.role.accent.default',
+                bg: 'color.role.bg.surface',
+                min: 3.0,
+                where: 'Accent on surface',
+              },
+              {
+                fg: 'color.role.focus.ring',
+                bg: 'color.role.bg.surface',
+                min: 3.0,
+                where: 'Focus ring on surface',
+                backdrop: '#ffffff',
+              },
+            ];
+            engine.use(WcagContrastPlugin(defaultWcagPairs));
+          }
+          break;
+        }
+
+        case 'builtin-threshold': {
+          if (source.enabled) {
+            const defaultThresholds: ThresholdRule[] = [
+              {
+                id: 'control.size.min',
+                op: '>=',
+                valuePx: 44,
+                where: 'Touch target (WCAG / Apple HIG)',
+              },
+            ];
+            engine.use(ThresholdPlugin(defaultThresholds, 'threshold'));
+          }
+          break;
+        }
+
+        case 'config-wcag': {
+          engine.use(WcagContrastPlugin(source.rules));
+          break;
+        }
+
+        case 'custom-threshold': {
+          engine.use(ThresholdPlugin(source.rules, 'custom-threshold'));
+          break;
+        }
+
+        case 'order-file': {
+          const pluginId = `monotonic-${source.axis}`;
+          engine.use(MonotonicPlugin(source.orders, parseSizePx, pluginId));
+          break;
+        }
+
+        case 'lightness-file': {
+          engine.use(MonotonicLightness(source.orders));
+          break;
+        }
+
+        case 'cross-axis-file': {
+          // Phase 3B: Load rules from filesystem in CLI layer, pass to core plugin
+          const rules = loadCrossAxisRules(source.path, {
+            bp: source.bp,
+            knownIds,
+            debug: crossAxisDebug,
+          });
+          engine.use(CrossAxisPlugin(rules, source.bp));
+          break;
+        }
+      }
+    } catch {
+      // Silently skip failed constraint attachments (consistent with old behavior)
+      // In the future, we may want to surface these as warnings
+    }
+  }
+}
+
+// ============================================================================
+// Convenience
+// ============================================================================
+
+/**
+ * Discover and attach constraints in one call.
+ *
+ * This is the main entry point for most use cases.
+ *
+ * @param engine Engine to attach plugins to
+ * @param discoveryOpts Discovery options
+ * @param attachOpts Attachment options
+ */
+export function setupConstraints(
+  engine: Engine,
+  discoveryOpts: DiscoveryOptions,
+  attachOpts: AttachOptions,
+): ConstraintSource[] {
+  const sources = discoverConstraints(discoveryOpts);
+  attachConstraints(engine, sources, attachOpts);
+  return sources;
+}

package/cli/constraints-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints-loader.d.ts","sourceRoot":"","sources":["constraints-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,KAAK,iBAAiB,GAAG;IACvB,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAkDtF"}

package/cli/cross-axis-loader.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Filesystem loader for cross-axis constraint rules.
+ *
+ * Phase 3B (Filesystem Separation): This module handles reading cross-axis rules
+ * from JSON files and parsing them into in-memory data structures.
+ *
+ * Core modules (core/constraints/cross-axis.ts) accept pre-parsed rules,
+ * while CLI modules use this loader to read from filesystem.
+ */
+import type { CrossAxisRule } from '../core/constraints/cross-axis.js';
+/**
+ * Raw rule format as stored in JSON files.
+ */
+export type RawCrossAxisRule = {
+    id: string;
+    level?: 'error' | 'warn';
+    where?: string;
+    bp?: string;
+    when?: {
+        id: string;
+        op: '<=' | '>=' | '<' | '>' | '==' | '!=';
+        value: number;
+    };
+    require?: {
+        id: string;
+        op: '<=' | '>=' | '<' | '>' | '==' | '!=';
+        ref?: string;
+        fallback?: string | number;
+    };
+    compare?: {
+        a: string;
+        op: '<=' | '>=' | '<' | '>' | '==' | '!=';
+        b: string;
+        delta?: string | number;
+    };
+};
+/**
+ * Result of loading and parsing cross-axis rules.
+ */
+export type LoadCrossAxisResult = {
+    rules: CrossAxisRule[];
+    unknownIds: Set<string>;
+    skipped: Array<{
+        id?: string;
+        reason: string;
+    }>;
+};
+/**
+ * Options for loading cross-axis rules.
+ */
+export type LoadCrossAxisOptions = {
+    /** Breakpoint to filter rules for */
+    bp?: string;
+    /** Set of known token IDs for validation */
+    knownIds?: Set<string>;
+    /** Enable debug logging */
+    debug?: boolean;
+};
+/**
+ * Load raw cross-axis rules from a JSON file.
+ *
+ * Returns undefined if file doesn't exist or can't be parsed.
+ *
+ * @param path Path to cross-axis rules JSON file
+ * @returns Parsed rules or undefined if file missing/invalid
+ */
+export declare function loadCrossAxisRulesFromFile(path: string): RawCrossAxisRule[] | undefined;
+/**
+ * Parse raw cross-axis rules into executable constraint rules.
+ *
+ * This function performs:
+ * - Breakpoint filtering (only include rules matching the target breakpoint)
+ * - Token ID validation (track unknown IDs)
+ * - Rule compilation (convert JSON predicates into executable functions)
+ *
+ * @param rawRules Raw rules from JSON file
+ * @param opts Parsing options (breakpoint, knownIds, debug)
+ * @returns Parsed rules with validation info
+ */
+export declare function parseCrossAxisRules(rawRules: RawCrossAxisRule[], opts?: LoadCrossAxisOptions): LoadCrossAxisResult;
+/**
+ * Load and parse cross-axis rules from a JSON file.
+ *
+ * This is the main entry point for CLI code that needs to load cross-axis rules.
+ *
+ * @param path Path to cross-axis rules JSON file
+ * @param opts Parsing options
+ * @returns Parsed rules (empty array if file doesn't exist)
+ */
+export declare function loadCrossAxisRules(path: string, opts?: LoadCrossAxisOptions): CrossAxisRule[];
+//# sourceMappingURL=cross-axis-loader.d.ts.map

package/cli/cross-axis-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-axis-loader.d.ts","sourceRoot":"","sources":["cross-axis-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;QAC1C,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;IACF,OAAO,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAC;QACX,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;QAC1C,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAC5B,CAAC;IACF,OAAO,CAAC,EAAE;QACR,CAAC,EAAE,MAAM,CAAC;QACV,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;QAC1C,CAAC,EAAE,MAAM,CAAC;QACV,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACzB,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,qCAAqC;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAMF;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,SAAS,CAYvF;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,EAAE,IAAI,GAAE,oBAAyB,GAAG,mBAAmB,CA6GtH;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,aAAa,EAAE,CAejG"}

package/cli/cross-axis-loader.js

@@ -0,0 +1,222 @@
+/**
+ * Filesystem loader for cross-axis constraint rules.
+ *
+ * Phase 3B (Filesystem Separation): This module handles reading cross-axis rules
+ * from JSON files and parsing them into in-memory data structures.
+ *
+ * Core modules (core/constraints/cross-axis.ts) accept pre-parsed rules,
+ * while CLI modules use this loader to read from filesystem.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+// ============================================================================
+// Filesystem Loading
+// ============================================================================
+/**
+ * Load raw cross-axis rules from a JSON file.
+ *
+ * Returns undefined if file doesn't exist or can't be parsed.
+ *
+ * @param path Path to cross-axis rules JSON file
+ * @returns Parsed rules or undefined if file missing/invalid
+ */
+export function loadCrossAxisRulesFromFile(path) {
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        return data.rules || [];
+    }
+    catch {
+        // Return undefined on parse errors (consistent with silent failure behavior)
+        return undefined;
+    }
+}
+// ============================================================================
+// Rule Parsing and Validation
+// ============================================================================
+// Helper functions (copied from core/cross-axis-config.ts)
+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);
+}
+// Lightweight Levenshtein distance for suggestions
+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, known, k = 3) {
+    return [...known]
+        .map((c) => ({ id: c, d: levenshtein(id, c) }))
+        .sort((a, b) => a.d - b.d)
+        .slice(0, k);
+}
+/**
+ * Parse raw cross-axis rules into executable constraint rules.
+ *
+ * This function performs:
+ * - Breakpoint filtering (only include rules matching the target breakpoint)
+ * - Token ID validation (track unknown IDs)
+ * - Rule compilation (convert JSON predicates into executable functions)
+ *
+ * @param rawRules Raw rules from JSON file
+ * @param opts Parsing options (breakpoint, knownIds, debug)
+ * @returns Parsed rules with validation info
+ */
+export function parseCrossAxisRules(rawRules, opts = {}) {
+    const { bp, knownIds = new Set(), debug = false } = opts;
+    const rules = [];
+    const unknownIds = new Set();
+    const skipped = [];
+    const log = (...args) => {
+        if (debug)
+            console.log('[cross-axis]', ...args);
+    };
+    const needId = (id) => {
+        if (!id)
+            return false;
+        if (!knownIds.has(id)) {
+            unknownIds.add(id);
+        }
+        return true;
+    };
+    for (const r of rawRules) {
+        // Filter by breakpoint
+        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}` });
+        }
+    }
+    // Debug logging
+    if (debug) {
+        log(`parsed ${rules.length} rule(s)${bp ? ` [bp=${bp}]` : ''}`);
+        if (unknownIds.size) {
+            log(`unknown ids referenced:`, [...unknownIds].join(', '));
+            for (const u of unknownIds) {
+                const s = suggest(u, knownIds, 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 rawRules) {
+            if (r.require?.ref && !knownIds.has(r.require.ref)) {
+                log(`anchor missing: ${r.require.ref} → will use fallback=${JSON.stringify(r.require.fallback)} when evaluating`);
+            }
+        }
+    }
+    return { rules, unknownIds, skipped };
+}
+/**
+ * Load and parse cross-axis rules from a JSON file.
+ *
+ * This is the main entry point for CLI code that needs to load cross-axis rules.
+ *
+ * @param path Path to cross-axis rules JSON file
+ * @param opts Parsing options
+ * @returns Parsed rules (empty array if file doesn't exist)
+ */
+export function loadCrossAxisRules(path, opts = {}) {
+    const { debug = false } = opts;
+    const log = (...args) => {
+        if (debug)
+            console.log('[cross-axis]', ...args);
+    };
+    const rawRules = loadCrossAxisRulesFromFile(path);
+    if (!rawRules) {
+        log(`no rules file at ${path} (bp=${opts.bp ?? 'global'})`);
+        return [];
+    }
+    const result = parseCrossAxisRules(rawRules, opts);
+    return result.rules;
+}