design-constraint-validator 1.0.0 → 2.0.1

package/cli/commands/why.ts

@@ -1,46 +1,158 @@
-import { readFileSync } from 'node:fs';
-import { flattenTokens } from '../../core/flatten.js';
-import { explain } from '../../core/why.js';
-import type { WhyOptions } from '../types.js';
-import { loadTokens } from './utils.js';
-
-export async function whyCommand(options: WhyOptions): Promise<void> {
-  const tokensPath = options.tokens || 'tokens/tokens.json';
-  const tokens = loadTokens(tokensPath);
-  const { flat, edges } = flattenTokens(tokens);
-  const target = options.tokenId;
-  if (!flat[target]) {
-    console.error(`❌ Token not found: ${target}`);
-    const { suggestIds } = await import('../../core/cli-format.js');
-    const suggestions = suggestIds(target, Object.keys(flat));
-    if (suggestions.length > 0) {
-      console.log(`\nDid you mean:`); suggestions.slice(0, 5).forEach(s => console.log(`  ${s.id}`));
-    } else {
-      console.log(`\nAvailable tokens:`); Object.keys(flat).sort().slice(0, 10).forEach(id => console.log(`  ${id}`));
-      if (Object.keys(flat).length > 10) console.log(`  ... and ${Object.keys(flat).length - 10} more`);
-    }
-    process.exit(1);
-  }
-  function safeLoad(p: string) { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return {}; } }
-  const overrides = safeLoad('tokens/overrides/local.json');
-  const theme = safeLoad('themes/theme.json');
-  const report = explain(target, flat, edges, { overrides: overrides?.overrides ?? overrides, theme });
-  const format = options.format || 'json';
-  if (format === 'table') {
-    const { pad, trunc } = await import('../../core/cli-format.js');
-    console.log(`\n=== Token Analysis: ${target} ===`);
-    console.log(`Value: ${report.value}`); console.log(`Raw: ${report.raw || 'N/A'}`); console.log(`Provenance: ${report.provenance}`);
-    if (report.dependsOn && report.dependsOn.length > 0) {
-      console.log(`\nDependencies (${report.dependsOn.length}):`); console.log(pad('TOKEN', 30) + pad('VALUE', 20) + 'TYPE'); console.log('-'.repeat(70));
-      report.dependsOn.forEach((depId: string) => { const dep = flat[depId]; if (dep) console.log(pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown')); });
-    }
-    if (report.dependents && report.dependents.length > 0) {
-      console.log(`\nDependents (${report.dependents.length}):`); console.log(pad('TOKEN', 30) + pad('VALUE', 20) + 'TYPE'); console.log('-'.repeat(70));
-      report.dependents.forEach((depId: string) => { const dep = flat[depId]; if (dep) console.log(pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown')); });
-    }
-    if (report.refs && report.refs.length > 0) console.log(`\nReferences: ${report.refs.join(', ')}`);
-    if (report.chain && report.chain.length > 0) console.log(`\nReference Chain: ${report.chain.join(' → ')}`);
-  } else {
-    console.log(JSON.stringify(report, null, 2));
-  }
-}
+import { readFileSync } from 'node:fs';
+import { flattenTokens, type FlatToken } from '../../core/flatten.js';
+import { explain } from '../../core/why.js';
+import type { WhyOptions } from '../types.js';
+import { loadTokens } from './utils.js';
+import { Engine } from '../../core/engine.js';
+import { loadConfig } from '../config.js';
+import type { ConstraintIssue } from '../../core/engine.js';
+import { setupConstraints } from '../constraint-registry.js';
+
+export async function whyCommand(options: WhyOptions): Promise<void> {
+  const tokensPath = options.tokens || 'tokens/tokens.json';
+  const tokens = loadTokens(tokensPath);
+  const { flat, edges } = flattenTokens(tokens);
+  const target = options.tokenId;
+
+  if (!flat[target]) {
+    console.error(`Token not found: ${target}`);
+    const { suggestIds } = await import('../../core/cli-format.js');
+    const suggestions = suggestIds(target, Object.keys(flat));
+    if (suggestions.length > 0) {
+      console.log('\nDid you mean:');
+      suggestions.slice(0, 5).forEach((s) => console.log(`  ${s.id}`));
+    } else {
+      console.log('\nAvailable tokens:');
+      Object.keys(flat)
+        .sort()
+        .slice(0, 10)
+        .forEach((id) => console.log(`  ${id}`));
+      if (Object.keys(flat).length > 10) {
+        console.log(`  ... and ${Object.keys(flat).length - 10} more`);
+      }
+    }
+    process.exit(1);
+  }
+
+  function safeLoad(p: string) {
+    try {
+      return JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      return {};
+    }
+  }
+
+  const overrides = safeLoad('tokens/overrides/local.json');
+  const theme = safeLoad('themes/theme.json');
+
+  const baseReport = explain(target, flat, edges, {
+    overrides: (overrides as any)?.overrides ?? overrides,
+    theme,
+  });
+
+  // Best-effort constraint summary: which rules currently implicate this token
+  let constraintsSummary:
+    | {
+        ruleId: string;
+        level: 'error' | 'warn';
+        message: string;
+        where?: string;
+      }[]
+    | undefined;
+
+  try {
+    const cfgRes = loadConfig(options.config);
+    if (cfgRes.ok) {
+      const config = cfgRes.value;
+
+      // Create engine with flattened 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));
+
+      // Discover and attach all constraints via centralized registry
+      setupConstraints(
+        engine,
+        { config, constraintsDir: 'themes' },
+        { knownIds },
+      );
+
+      const candidates = new Set<string>([target]);
+      const allIssues: ConstraintIssue[] = engine.evaluate(candidates);
+      if (allIssues.length) {
+        const related = allIssues.filter((issue) => {
+          const parts = String(issue.id).split('|');
+          return parts.includes(target);
+        });
+        if (related.length) {
+          constraintsSummary = related.map((issue) => ({
+            ruleId: issue.rule,
+            level: issue.level,
+            message: issue.message,
+            where: issue.where,
+          }));
+        }
+      }
+    }
+  } catch {
+    // If constraint analysis fails, fall back to provenance-only report.
+  }
+
+  const report: any = constraintsSummary ? { ...baseReport, constraints: constraintsSummary } : baseReport;
+
+  const format = options.format || 'json';
+  if (format === 'table') {
+    const { pad, trunc } = await import('../../core/cli-format.js');
+    console.log(`\n=== Token Analysis: ${target} ===`);
+    console.log(`Value: ${report.value}`);
+    console.log(`Raw: ${report.raw ?? 'N/A'}`);
+    console.log(`Provenance: ${report.provenance}`);
+
+    if (report.dependsOn && report.dependsOn.length > 0) {
+      console.log(`\nDependencies (${report.dependsOn.length}):`);
+      console.log(pad('TOKEN', 30) + pad('VALUE', 20) + 'TYPE');
+      console.log('-'.repeat(70));
+      report.dependsOn.forEach((depId: string) => {
+        const dep = flat[depId] as any;
+        if (dep) {
+          console.log(
+            pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown'),
+          );
+        }
+      });
+    }
+
+    if (report.dependents && report.dependents.length > 0) {
+      console.log(`\nDependents (${report.dependents.length}):`);
+      console.log(pad('TOKEN', 30) + pad('VALUE', 20) + 'TYPE');
+      console.log('-'.repeat(70));
+      report.dependents.forEach((depId: string) => {
+        const dep = flat[depId] as any;
+        if (dep) {
+          console.log(
+            pad(trunc(depId, 28), 30) + pad(trunc(String(dep.value), 18), 20) + (dep.type || 'unknown'),
+          );
+        }
+      });
+    }
+
+    if (report.refs && report.refs.length > 0) {
+      console.log(`\nReferences: ${report.refs.join(', ')}`);
+    }
+    if (report.chain && report.chain.length > 0) {
+      console.log(`\nReference Chain: ${report.chain.join(' -> ')}`);
+    }
+    if (constraintsSummary && constraintsSummary.length > 0) {
+      console.log('\nConstraints (violations involving this token):');
+      constraintsSummary.forEach((c) => {
+        const where = c.where ? ` @ ${c.where}` : '';
+        console.log(`- [${c.level}] ${c.ruleId}${where}: ${c.message}`);
+      });
+    }
+  } else {
+    console.log(JSON.stringify(report, null, 2));
+  }
+}

package/cli/config-schema.ts

@@ -1,27 +1,27 @@
-import { z } from 'zod';
-
-export const WcagRuleSchema = z.object({
-  foreground: z.string(),
-  background: z.string(),
-  ratio: z.number().positive().optional(),
-  description: z.string().optional()
-});
-
-export const ConstraintsSchema = z.object({
-  wcag: z.array(WcagRuleSchema).optional()
-}).passthrough();
-
-export const DcvConfigSchema = z.object({
-  version: z.string().optional(),
-  constraints: ConstraintsSchema.optional()
-}).passthrough();
-
-export type DcvConfigParsed = z.infer<typeof DcvConfigSchema>;
-
-export function validateConfig(raw: unknown): { value?: DcvConfigParsed; errors?: string[] } {
-  const res = DcvConfigSchema.safeParse(raw);
-  if (!res.success) {
-    return { errors: res.error.errors.map(e => `${e.path.join('.')||'<root>'}: ${e.message}`) };
-  }
-  return { value: res.data };
-}
+import { z } from 'zod';
+
+export const WcagRuleSchema = z.object({
+  foreground: z.string(),
+  background: z.string(),
+  ratio: z.number().positive().optional(),
+  description: z.string().optional()
+});
+
+export const ConstraintsSchema = z.object({
+  wcag: z.array(WcagRuleSchema).optional()
+}).passthrough();
+
+export const DcvConfigSchema = z.object({
+  version: z.string().optional(),
+  constraints: ConstraintsSchema.optional()
+}).passthrough();
+
+export type DcvConfigParsed = z.infer<typeof DcvConfigSchema>;
+
+export function validateConfig(raw: unknown): { value?: DcvConfigParsed; errors?: string[] } {
+  const res = DcvConfigSchema.safeParse(raw);
+  if (!res.success) {
+    return { errors: res.error.errors.map(e => `${e.path.join('.')||'<root>'}: ${e.message}`) };
+  }
+  return { value: res.data };
+}

package/cli/config.ts

@@ -1,35 +1,35 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { validateConfig } from './config-schema.js';
-import { ok, err, type Result } from './result.js';
-import type { DcvConfig } from './types.js';
-
-export function loadConfig(configPath?: string): Result<DcvConfig, string> {
-  const candidates = configPath ? [configPath] : [
-    'dcv.config.json',
-    'dcv.config.js',
-    '.dcvrc.json',
-    'package.json'
-  ];
-  for (const p of candidates) {
-    if (!existsSync(p)) continue;
-    try {
-      const rawTxt = readFileSync(p, 'utf8');
-      let raw: unknown = JSON.parse(rawTxt);
-      if (p === 'package.json' && raw && typeof raw === 'object') {
-        const pkg = raw as Record<string, unknown>;
-        if ('dcv' in pkg) {
-          raw = pkg.dcv;
-        } else {
-          continue; // No dcv config in package.json
-        }
-      }
-      const { value, errors } = validateConfig(raw);
-      if (errors) return err(`Config validation failed in ${p}:\n  - ${errors.join('\n  - ')}`);
-      return ok(value!);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      return err(`Failed reading config ${p}: ${msg}`);
-    }
-  }
-  return ok({});
-}
+import { readFileSync, existsSync } from 'node:fs';
+import { validateConfig } from './config-schema.js';
+import { ok, err, type Result } from './result.js';
+import type { DcvConfig } from './types.js';
+
+export function loadConfig(configPath?: string): Result<DcvConfig, string> {
+  const candidates = configPath ? [configPath] : [
+    'dcv.config.json',
+    'dcv.config.js',
+    '.dcvrc.json',
+    'package.json'
+  ];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      const rawTxt = readFileSync(p, 'utf8');
+      let raw: unknown = JSON.parse(rawTxt);
+      if (p === 'package.json' && raw && typeof raw === 'object') {
+        const pkg = raw as Record<string, unknown>;
+        if ('dcv' in pkg) {
+          raw = pkg.dcv;
+        } else {
+          continue; // No dcv config in package.json
+        }
+      }
+      const { value, errors } = validateConfig(raw);
+      if (errors) return err(`Config validation failed in ${p}:\n  - ${errors.join('\n  - ')}`);
+      return ok(value!);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return err(`Failed reading config ${p}: ${msg}`);
+    }
+  }
+  return ok({});
+}

package/cli/constraint-registry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 type { Engine } from '../core/engine.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import type { DcvConfig } from './types.js';
+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;
+};
+/**
+ * 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 declare function discoverConstraints(opts: DiscoveryOptions): ConstraintSource[];
+/**
+ * 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 declare function attachConstraints(engine: Engine, sources: ConstraintSource[], opts: AttachOptions): void;
+/**
+ * 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 declare function setupConstraints(engine: Engine, discoveryOpts: DiscoveryOptions, attachOpts: AttachOptions): ConstraintSource[];
+//# sourceMappingURL=constraint-registry.d.ts.map

package/cli/constraint-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-registry.d.ts","sourceRoot":"","sources":["constraint-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAY5C,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAEtD,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACvE;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,UAAU,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC;AAEzD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAMF;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CA8F9E;AAMD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAsFxG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,gBAAgB,EAC/B,UAAU,EAAE,aAAa,GACxB,gBAAgB,EAAE,CAIpB"}

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