design-constraint-validator 1.0.0 → 1.1.0

package/cli/constraint-registry.js

@@ -0,0 +1,225 @@
+/**
+ * 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 { 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';
+// ============================================================================
+// 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) {
+    const { config, basePath = '.', bp, constraintsDir = 'themes' } = opts;
+    const sources = [];
+    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 = constraintsCfg.wcag.map((r) => ({
+            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 = constraintsCfg.thresholds.map((r) => ({
+            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'];
+    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 = 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 = 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, sources, opts) {
+    const { knownIds, crossAxisDebug = false } = opts;
+    for (const source of sources) {
+        try {
+            switch (source.type) {
+                case 'builtin-wcag': {
+                    if (source.enabled) {
+                        const defaultWcagPairs = [
+                            {
+                                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 = [
+                            {
+                                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, discoveryOpts, attachOpts) {
+    const sources = discoverConstraints(discoveryOpts);
+    attachConstraints(engine, sources, attachOpts);
+    return sources;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * @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 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 declare function attachRuntimeConstraints(engine: Engine, opts: AttachRuntimeOpts): void;
+export {};
+//# sourceMappingURL=constraints-loader.d.ts.map

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/constraints-loader.js

@@ -0,0 +1,58 @@
+/**
+ * @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 { loadCrossAxisPlugin } from '../core/cross-axis-config.js';
+import { ThresholdPlugin } from '../core/constraints/threshold.js';
+/**
+ * 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, opts) {
+    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.
+        }
+    }
+}