design-constraint-validator 1.0.0 → 1.1.0

package/cli/constraints-loader.ts

@@ -0,0 +1,83 @@
+/**
+ * @deprecated This module is deprecated. Use constraint-registry.ts instead.
+ *
+ * Phase 3A (Architectural Cleanup): This file contains legacy runtime constraint
+ * loading logic that has been replaced by the centralized constraint-registry.ts module.
+ *
+ * Migration: Replace attachRuntimeConstraints() with setupConstraints() from constraint-registry.ts
+ *
+ * This file will be removed in a future major version.
+ */
+
+import type { Engine } from '../core/engine.js';
+import { loadCrossAxisPlugin } from '../core/cross-axis-config.js';
+import { ThresholdPlugin } from '../core/constraints/threshold.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import type { DcvConfig } from './types.js';
+
+type AttachRuntimeOpts = {
+  config: DcvConfig;
+  knownIds: Set<string>;
+  bp?: Breakpoint;
+  crossAxisDebug?: boolean;
+};
+
+/**
+ * Attach runtime constraints that depend on project files or built-in policies:
+ * - Cross-axis rules from themes/cross-axis*.rules.json
+ * - Built-in threshold rules (e.g., control.size.min >= 44px)
+ *
+ * @deprecated Use setupConstraints() from constraint-registry.ts instead.
+ * This function will be removed in a future major version.
+ */
+export function attachRuntimeConstraints(engine: Engine, opts: AttachRuntimeOpts): void {
+  const { knownIds, bp, crossAxisDebug, config } = opts;
+
+  // Cross-axis rules: global + optional breakpoint-specific
+  try {
+    engine.use(
+      loadCrossAxisPlugin('themes/cross-axis.rules.json', bp, {
+        debug: !!crossAxisDebug,
+        knownIds,
+      }),
+    );
+
+    if (bp) {
+      const bpRulesPath = `themes/cross-axis.${bp}.rules.json`;
+      engine.use(
+        loadCrossAxisPlugin(bpRulesPath, bp, {
+          debug: !!crossAxisDebug,
+          knownIds,
+        }),
+      );
+    }
+  } catch {
+    // If cross-axis configuration fails, continue with other constraints.
+  }
+
+  const constraintsCfg = config.constraints ?? {};
+
+  // Built-in threshold rule for touch targets (configurable)
+  const enableBuiltInThreshold =
+    constraintsCfg.enableBuiltInThreshold === undefined ? true : !!constraintsCfg.enableBuiltInThreshold;
+
+  if (enableBuiltInThreshold) {
+    try {
+      engine.use(
+        ThresholdPlugin(
+          [
+            {
+              id: 'control.size.min',
+              op: '>=',
+              valuePx: 44,
+              where: 'Touch target (WCAG / Apple HIG)',
+            },
+          ],
+          'threshold',
+        ),
+      );
+    } catch {
+      // Threshold attachment is best-effort; failures should not abort validation.
+    }
+  }
+}

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;
+}

package/cli/cross-axis-loader.ts

@@ -0,0 +1,289 @@
+/**
+ * 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';
+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;
+};
+
+// ============================================================================
+// 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: string): RawCrossAxisRule[] | undefined {
+  if (!existsSync(path)) {
+    return undefined;
+  }
+
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8')) as { rules: RawCrossAxisRule[] };
+    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: string | number) =>
+  typeof v === 'number' ? v : parseFloat(String(v)) * (String(v).trim().endsWith('rem') ? 16 : 1);
+
+const cmp = (a: number, b: number, op: '<=' | '>=' | '<' | '>' | '==' | '!=') =>
+  op === '>=' ? a >= b : op === '>' ? a > b : op === '<=' ? a <= b : op === '<' ? a < b : op === '==' ? a === b : a !== b;
+
+const prettyFail = (op: string) => ({ '>=': '<', '>': '≤', '<=': '>', '<': '≥', '==': '≠', '!=': '=' } as any)[op] || '≠';
+
+const fmt = (v: number | string) => (Number.isFinite(Number(v)) ? `${Number(v)}px` : String(v));
+
+function valueOrRef(ctx: any, ref?: string, fallback?: string | number) {
+  if (ref) {
+    const v = ctx.getPx(ref);
+    if (v != null) return v;
+  }
+  return typeof fallback === 'number' ? fallback : px(fallback ?? 0);
+}
+
+function makeOp(op: '<=' | '>=' | '<' | '>' | '==' | '!=', rhs: number) {
+  return (v: number) => cmp(v, rhs, op);
+}
+
+// Lightweight Levenshtein distance for suggestions
+function levenshtein(a: string, b: string) {
+  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: string, known: Set<string>, 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: RawCrossAxisRule[], opts: LoadCrossAxisOptions = {}): LoadCrossAxisResult {
+  const { bp, knownIds = new Set(), debug = false } = opts;
+  const rules: CrossAxisRule[] = [];
+  const unknownIds = new Set<string>();
+  const skipped: Array<{ id?: string; reason: string }> = [];
+
+  const log = (...args: any[]) => {
+    if (debug) console.log('[cross-axis]', ...args);
+  };
+
+  const needId = (id?: string) => {
+    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: number, ctx: any) => {
+              const rhs = valueOrRef(ctx, r.require!.ref, r.require!.fallback);
+              return cmp(v, rhs, r.require!.op);
+            },
+            msg: (v: number, ctx: any) => {
+              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: (_: number, ctx: any) => {
+              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: (_: number, ctx: any) => {
+              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: any) {
+      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: string, opts: LoadCrossAxisOptions = {}): CrossAxisRule[] {
+  const { debug = false } = opts;
+  const log = (...args: any[]) => {
+    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;
+}