aria-ease 6.8.0 → 6.9.1

package/bin/cli.cjs

@@ -89,6 +89,9 @@ function validateConfig(config) {
               if (comp.path !== void 0 && typeof comp.path !== "string") {
                 errors.push(`test.components[${idx}].path must be a string when provided`);
               }
+              if (comp.strategyPath !== void 0 && typeof comp.strategyPath !== "string") {
+                errors.push(`test.components[${idx}].strategyPath must be a string when provided`);
+              }
               if (comp.strictness !== void 0 && !["minimal", "balanced", "strict", "paranoid"].includes(comp.strictness)) {
                 errors.push(`test.components[${idx}].strictness must be one of: minimal, balanced, strict, paranoid`);
               }
@@ -103,6 +106,24 @@ function validateConfig(config) {
       }
     }
   }
+  if (cfg.contracts !== void 0) {
+    if (!Array.isArray(cfg.contracts)) {
+      errors.push("contracts must be an array");
+    } else {
+      cfg.contracts.forEach((contract, idx) => {
+        if (typeof contract !== "object" || contract === null) {
+          errors.push(`contracts[${idx}] must be an object`);
+        } else {
+          if (typeof contract.src !== "string") {
+            errors.push(`contracts[${idx}].src is required and must be a string`);
+          }
+          if (contract.out !== void 0 && typeof contract.out !== "string") {
+            errors.push(`contracts[${idx}].out must be a string`);
+          }
+        }
+      });
+    }
+  }
   return { valid: errors.length === 0, errors };
 }
 async function loadConfigFile(filePath) {
@@ -572,11 +593,13 @@ var init_ContractReporter = __esm({
       skipped = 0;
       warnings = 0;
       isPlaywright = false;
+      isCustomContract = false;
       apgUrl = "https://www.w3.org/WAI/ARIA/apg/";
       hasPrintedStaticSection = false;
       hasPrintedDynamicSection = false;
-      constructor(isPlaywright = false) {
+      constructor(isPlaywright = false, isCustomContract = false) {
         this.isPlaywright = isPlaywright;
+        this.isCustomContract = isCustomContract;
       }
       log(message) {
         process.stderr.write(message + "\n");
@@ -737,6 +760,13 @@ ${"\u2500".repeat(60)}`);
         const totalPasses = this.staticPasses + dynamicPasses;
         const totalFailures = this.staticFailures + dynamicFailures;
         const totalRun = totalPasses + totalFailures + this.warnings;
+        const getComponentMessage = () => {
+          const componentDisplayName = `${this.componentName.charAt(0).toUpperCase()}${this.componentName.slice(1)}`;
+          if (this.isCustomContract) {
+            return `${componentDisplayName} component validates against your custom accessibility policy \u2713`;
+          }
+          return `${componentDisplayName} component meets Aria-Ease baseline WAI-ARIA expectations \u2713`;
+        };
         if (failures.length > 0) {
           this.reportFailures(failures);
         }
@@ -748,7 +778,7 @@ ${"\u2550".repeat(60)}`);
 `);
         if (totalFailures === 0 && this.skipped === 0 && this.warnings === 0) {
           this.log(`\u2705 All ${totalRun} tests passed!`);
-          this.log(`   ${this.componentName.charAt(0).toUpperCase()}${this.componentName.slice(1)} component meets WAI-ARIA expectations for Roles, States, Properties, and Keyboard Interactions \u2713`);
+          this.log(`   ${getComponentMessage()}`);
         } else if (totalFailures === 0) {
           this.log(`\u2705 ${totalPasses}/${totalRun} tests passed`);
           if (this.skipped > 0) {
@@ -757,7 +787,7 @@ ${"\u2550".repeat(60)}`);
           if (this.warnings > 0) {
             this.log(`\u26A0\uFE0F ${this.warnings} warning${this.warnings > 1 ? "s" : ""}`);
           }
-          this.log(`   ${this.componentName.charAt(0).toUpperCase()}${this.componentName.slice(1)} component meets WAI-ARIA expectations for Roles, States, Properties, and Keyboard Interactions \u2713`);
+          this.log(`   ${getComponentMessage()}`);
         } else {
           this.log(`\u274C ${totalFailures} test${totalFailures > 1 ? "s" : ""} failed`);
           this.log(`\u2705 ${totalPasses} test${totalPasses > 1 ? "s" : ""} passed`);
@@ -861,7 +891,7 @@ async function runContractTests(componentName, component, strictness) {
   const resolvedPath = new URL(contractPath, import_meta.url).pathname;
   const contractData = await import_promises.default.readFile(resolvedPath, "utf-8");
   const componentContract = JSON.parse(contractData);
-  const totalTests = componentContract.static[0].assertions.length + componentContract.dynamic.length;
+  const totalTests = (componentContract.relationships?.length || 0) + (componentContract.static[0]?.assertions.length || 0) + componentContract.dynamic.length;
   reporter.start(componentName, totalTests);
   const failures = [];
   const passes = [];
@@ -885,6 +915,82 @@ async function runContractTests(componentName, component, strictness) {
   let staticPassed = 0;
   let staticFailed = 0;
   let staticWarnings = 0;
+  for (const rel of componentContract.relationships || []) {
+    const relationshipLevel = normalizeLevel(rel.level);
+    if (rel.type === "aria-reference") {
+      const fromSelector = componentContract.selectors[rel.from];
+      const toSelector = componentContract.selectors[rel.to];
+      const relDescription = `${rel.from}.${rel.attribute} references ${rel.to}`;
+      if (!fromSelector || !toSelector) {
+        const outcome = classifyFailure(`Relationship selector missing: from="${rel.from}" or to="${rel.to}" not found in selectors.`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      const fromTarget = component.querySelector(fromSelector);
+      const toTarget = component.querySelector(toSelector);
+      if (!fromTarget || !toTarget) {
+        const outcome = classifyFailure(`Relationship target not found: ${!fromTarget ? rel.from : rel.to}.`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      const toId = toTarget.getAttribute("id");
+      const attrValue = fromTarget.getAttribute(rel.attribute) || "";
+      if (!toId) {
+        const outcome = classifyFailure(`Relationship target "${rel.to}" must have an id for ${rel.attribute} validation.`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      const references = attrValue.split(/\s+/).filter(Boolean);
+      if (!references.includes(toId)) {
+        const outcome = classifyFailure(`Expected ${rel.from} ${rel.attribute} to reference id "${toId}", found "${attrValue}".`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      passes.push(`Relationship valid: ${rel.from}.${rel.attribute} -> ${rel.to} (id=${toId}).`);
+      staticPassed += 1;
+      reporter.reportStaticTest(relDescription, "pass", void 0, relationshipLevel);
+      continue;
+    }
+    if (rel.type === "contains") {
+      const parentSelector = componentContract.selectors[rel.parent];
+      const childSelector = componentContract.selectors[rel.child];
+      const relDescription = `${rel.parent} contains ${rel.child}`;
+      if (!parentSelector || !childSelector) {
+        const outcome = classifyFailure(`Relationship selector missing: parent="${rel.parent}" or child="${rel.child}" not found in selectors.`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      const parentTarget = component.querySelector(parentSelector);
+      if (!parentTarget) {
+        const outcome = classifyFailure(`Relationship parent target not found: ${rel.parent}.`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      const nestedChild = parentTarget.querySelector(childSelector);
+      if (!nestedChild) {
+        const outcome = classifyFailure(`Expected ${rel.parent} to contain descendant matching selector for ${rel.child}.`, rel.level);
+        if (outcome.status === "fail") staticFailed += 1;
+        if (outcome.status === "warn") staticWarnings += 1;
+        reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+        continue;
+      }
+      passes.push(`Relationship valid: ${rel.parent} contains ${rel.child}.`);
+      staticPassed += 1;
+      reporter.reportStaticTest(relDescription, "pass", void 0, relationshipLevel);
+    }
+  }
   for (const test of componentContract.static[0].assertions) {
     if (test.target !== "relative") {
       const staticLevel = normalizeLevel(test.level);
@@ -1014,13 +1120,17 @@ var init_test = __esm({
   }
 });
 
-// src/utils/test/src/component-strategies/ComboboxComponentStrategy.ts
-var ComboboxComponentStrategy;
-var init_ComboboxComponentStrategy = __esm({
-  "src/utils/test/src/component-strategies/ComboboxComponentStrategy.ts"() {
+// src/utils/test/src/component-strategies/MenuComponentStrategy.ts
+var MenuComponentStrategy_exports = {};
+__export(MenuComponentStrategy_exports, {
+  MenuComponentStrategy: () => MenuComponentStrategy
+});
+var MenuComponentStrategy;
+var init_MenuComponentStrategy = __esm({
+  "src/utils/test/src/component-strategies/MenuComponentStrategy.ts"() {
     "use strict";
     init_test();
-    ComboboxComponentStrategy = class {
+    MenuComponentStrategy = class {
       constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
         this.mainSelector = mainSelector;
         this.selectors = selectors;
@@ -1057,19 +1167,36 @@ var init_ComboboxComponentStrategy = __esm({
         }
         if (!menuClosed) {
           throw new Error(
-            `\u274C FATAL: Cannot close combobox popup between tests. Popup remains visible after trying:
+            `\u274C FATAL: Cannot close menu between tests. Menu remains visible after trying:
   1. Escape key
   2. Clicking trigger
   3. Clicking outside
-This indicates a problem with the combobox component's close functionality.`
+This indicates a problem with the menu component's close functionality.`
           );
         }
         if (this.selectors.input) {
           await page.locator(this.selectors.input).first().clear();
         }
+        if (this.selectors.trigger) {
+          const triggerElement = page.locator(this.selectors.trigger).first();
+          await triggerElement.focus();
+        }
       }
-      async shouldSkipTest() {
-        return false;
+      async shouldSkipTest(test, page) {
+        const requiresSubmenu = test.action.some(
+          (act) => act.target === "submenu" || act.target === "submenuTrigger" || act.target === "submenuItems"
+        ) || test.assertions.some(
+          (assertion) => assertion.target === "submenu" || assertion.target === "submenuTrigger" || assertion.target === "submenuItems"
+        );
+        if (!requiresSubmenu) {
+          return false;
+        }
+        const submenuTriggerSelector = this.selectors.submenuTrigger;
+        if (!submenuTriggerSelector) {
+          return true;
+        }
+        const submenuTriggerCount = await page.locator(submenuTriggerSelector).count();
+        return submenuTriggerCount === 0;
       }
       getMainSelector() {
         return this.mainSelector;
@@ -1079,6 +1206,10 @@ This indicates a problem with the combobox component's close functionality.`
 });
 
 // src/utils/test/src/component-strategies/AccordionComponentStrategy.ts
+var AccordionComponentStrategy_exports = {};
+__export(AccordionComponentStrategy_exports, {
+  AccordionComponentStrategy: () => AccordionComponentStrategy
+});
 var AccordionComponentStrategy;
 var init_AccordionComponentStrategy = __esm({
   "src/utils/test/src/component-strategies/AccordionComponentStrategy.ts"() {
@@ -1120,13 +1251,17 @@ var init_AccordionComponentStrategy = __esm({
   }
 });
 
-// src/utils/test/src/component-strategies/MenuComponentStrategy.ts
-var MenuComponentStrategy;
-var init_MenuComponentStrategy = __esm({
-  "src/utils/test/src/component-strategies/MenuComponentStrategy.ts"() {
+// src/utils/test/src/component-strategies/ComboboxComponentStrategy.ts
+var ComboboxComponentStrategy_exports = {};
+__export(ComboboxComponentStrategy_exports, {
+  ComboboxComponentStrategy: () => ComboboxComponentStrategy
+});
+var ComboboxComponentStrategy;
+var init_ComboboxComponentStrategy = __esm({
+  "src/utils/test/src/component-strategies/ComboboxComponentStrategy.ts"() {
     "use strict";
     init_test();
-    MenuComponentStrategy = class {
+    ComboboxComponentStrategy = class {
       constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
         this.mainSelector = mainSelector;
         this.selectors = selectors;
@@ -1139,60 +1274,43 @@ var init_MenuComponentStrategy = __esm({
         const popupElement = page.locator(popupSelector).first();
         const isPopupVisible = await popupElement.isVisible().catch(() => false);
         if (!isPopupVisible) return;
-        let menuClosed = false;
+        let listBoxClosed = false;
         let closeSelector = this.selectors.input;
         if (!closeSelector && this.selectors.focusable) {
           closeSelector = this.selectors.focusable;
         } else if (!closeSelector) {
-          closeSelector = this.selectors.trigger;
+          closeSelector = this.selectors.button;
         }
         if (closeSelector) {
           const closeElement = page.locator(closeSelector).first();
           await closeElement.focus();
           await page.keyboard.press("Escape");
-          menuClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+          listBoxClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
         }
-        if (!menuClosed && this.selectors.trigger) {
-          const triggerElement = page.locator(this.selectors.trigger).first();
-          await triggerElement.click({ timeout: this.actionTimeoutMs });
-          menuClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+        if (!listBoxClosed && this.selectors.button) {
+          const buttonElement = page.locator(this.selectors.button).first();
+          await buttonElement.click({ timeout: this.actionTimeoutMs });
+          listBoxClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
         }
-        if (!menuClosed) {
+        if (!listBoxClosed) {
           await page.mouse.click(10, 10);
-          menuClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+          listBoxClosed = await (0, test_exports.expect)(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
         }
-        if (!menuClosed) {
+        if (!listBoxClosed) {
           throw new Error(
-            `\u274C FATAL: Cannot close menu between tests. Menu remains visible after trying:
+            `\u274C FATAL: Cannot close combobox popup between tests. Popup remains visible after trying:
   1. Escape key
-  2. Clicking trigger
+  2. Clicking button
   3. Clicking outside
-This indicates a problem with the menu component's close functionality.`
+This indicates a problem with the combobox component's close functionality.`
           );
         }
         if (this.selectors.input) {
           await page.locator(this.selectors.input).first().clear();
         }
-        if (this.selectors.trigger) {
-          const triggerElement = page.locator(this.selectors.trigger).first();
-          await triggerElement.focus();
-        }
       }
-      async shouldSkipTest(test, page) {
-        const requiresSubmenu = test.action.some(
-          (act) => act.target === "submenu" || act.target === "submenuTrigger" || act.target === "submenuItems"
-        ) || test.assertions.some(
-          (assertion) => assertion.target === "submenu" || assertion.target === "submenuTrigger" || assertion.target === "submenuItems"
-        );
-        if (!requiresSubmenu) {
-          return false;
-        }
-        const submenuTriggerSelector = this.selectors.submenuTrigger;
-        if (!submenuTriggerSelector) {
-          return true;
-        }
-        const submenuTriggerCount = await page.locator(submenuTriggerSelector).count();
-        return submenuTriggerCount === 0;
+      async shouldSkipTest() {
+        return false;
       }
       getMainSelector() {
         return this.mainSelector;
@@ -1202,6 +1320,10 @@ This indicates a problem with the menu component's close functionality.`
 });
 
 // src/utils/test/src/component-strategies/TabsComponentStrategy.ts
+var TabsComponentStrategy_exports = {};
+__export(TabsComponentStrategy_exports, {
+  TabsComponentStrategy: () => TabsComponentStrategy
+});
 var TabsComponentStrategy;
 var init_TabsComponentStrategy = __esm({
   "src/utils/test/src/component-strategies/TabsComponentStrategy.ts"() {
@@ -1232,46 +1354,173 @@ var init_TabsComponentStrategy = __esm({
   }
 });
 
+// src/utils/test/src/StrategyRegistry.ts
+var import_path3, import_url, StrategyRegistry;
+var init_StrategyRegistry = __esm({
+  "src/utils/test/src/StrategyRegistry.ts"() {
+    "use strict";
+    import_path3 = __toESM(require("path"), 1);
+    import_url = require("url");
+    StrategyRegistry = class {
+      builtInStrategies = /* @__PURE__ */ new Map();
+      constructor() {
+        this.registerBuiltInStrategies();
+      }
+      /**
+       * Register built-in strategies
+       */
+      registerBuiltInStrategies() {
+        this.builtInStrategies.set(
+          "menu",
+          () => Promise.resolve().then(() => (init_MenuComponentStrategy(), MenuComponentStrategy_exports)).then(
+            (m) => m.MenuComponentStrategy
+          )
+        );
+        this.builtInStrategies.set(
+          "accordion",
+          () => Promise.resolve().then(() => (init_AccordionComponentStrategy(), AccordionComponentStrategy_exports)).then(
+            (m) => m.AccordionComponentStrategy
+          )
+        );
+        this.builtInStrategies.set(
+          "combobox",
+          () => Promise.resolve().then(() => (init_ComboboxComponentStrategy(), ComboboxComponentStrategy_exports)).then(
+            (m) => m.ComboboxComponentStrategy
+          )
+        );
+        this.builtInStrategies.set(
+          "tabs",
+          () => Promise.resolve().then(() => (init_TabsComponentStrategy(), TabsComponentStrategy_exports)).then(
+            (m) => m.TabsComponentStrategy
+          )
+        );
+        this.builtInStrategies.set(
+          "combobox.listbox",
+          () => Promise.resolve().then(() => (init_ComboboxComponentStrategy(), ComboboxComponentStrategy_exports)).then(
+            (m) => m.ComboboxComponentStrategy
+          )
+        );
+      }
+      /**
+       * Load a strategy - either from custom path or built-in registry
+       * @param componentName - Component name (e.g., "menu", "accordion")
+       * @param customStrategyPath - Optional custom strategy file path
+       * @returns Strategy constructor function or null if not found
+       */
+      async loadStrategy(componentName, customStrategyPath, configBaseDir) {
+        try {
+          if (customStrategyPath) {
+            try {
+              const resolvedCustomPath = import_path3.default.isAbsolute(customStrategyPath) ? customStrategyPath : import_path3.default.resolve(configBaseDir || process.cwd(), customStrategyPath);
+              const customModule = await import((0, import_url.pathToFileURL)(resolvedCustomPath).href);
+              const strategy = customModule.default || customModule;
+              if (!strategy) {
+                throw new Error(`No default export found in ${customStrategyPath}`);
+              }
+              return strategy;
+            } catch (error) {
+              throw new Error(
+                `Failed to load custom strategy from ${customStrategyPath}: ${error instanceof Error ? error.message : String(error)}`
+              );
+            }
+          }
+          const builtInLoader = this.builtInStrategies.get(componentName);
+          if (!builtInLoader) {
+            return null;
+          }
+          return builtInLoader();
+        } catch (error) {
+          throw new Error(
+            `Strategy loading failed for ${componentName}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      }
+      /**
+       * Check if a strategy exists (either built-in or custom path provided)
+       */
+      has(componentName, customStrategyPath) {
+        return !!customStrategyPath || this.builtInStrategies.has(componentName);
+      }
+    };
+  }
+});
+
 // src/utils/test/src/ComponentDetector.ts
-var import_fs, import_meta2, ComponentDetector;
+var import_fs, import_path4, import_meta2, ComponentDetector;
 var init_ComponentDetector = __esm({
   "src/utils/test/src/ComponentDetector.ts"() {
     "use strict";
-    init_ComboboxComponentStrategy();
-    init_AccordionComponentStrategy();
-    init_MenuComponentStrategy();
-    init_TabsComponentStrategy();
     import_fs = require("fs");
+    import_path4 = __toESM(require("path"), 1);
     init_contract();
+    init_StrategyRegistry();
     import_meta2 = {};
     ComponentDetector = class {
-      static detect(componentName, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
-        const contractTyped = contract_default;
-        const contractPath = contractTyped[componentName]?.path;
+      static strategyRegistry = new StrategyRegistry();
+      static isComponentConfig(value) {
+        return typeof value === "object" && value !== null;
+      }
+      /**
+       * Detect and instantiate a component strategy
+       * Supports:
+       * - Built-in strategies (menu, accordion, combobox, tabs)
+       * - Custom strategies via config (strategyPath)
+       * - Custom contract paths via config (path)
+       * @param componentName - Component name
+       * @param componentConfig - Component config from ariaease.config.js
+       * @param actionTimeoutMs - Action timeout in milliseconds
+       * @param assertionTimeoutMs - Assertion timeout in milliseconds
+       * @returns Instantiated ComponentStrategy or null
+       */
+      static async detect(componentName, componentConfig, actionTimeoutMs = 400, assertionTimeoutMs = 400, configBaseDir) {
+        const typedComponentConfig = this.isComponentConfig(componentConfig) ? componentConfig : void 0;
+        let contractPath = typedComponentConfig?.path;
+        if (!contractPath) {
+          const contractTyped = contract_default;
+          contractPath = contractTyped[componentName]?.path;
+        }
         if (!contractPath) {
           throw new Error(`Contract path not found for component: ${componentName}`);
         }
-        const resolvedPath = new URL(contractPath, import_meta2.url).pathname;
+        const resolvedPath = (() => {
+          if (import_path4.default.isAbsolute(contractPath)) return contractPath;
+          if (configBaseDir) {
+            const configResolved = import_path4.default.resolve(configBaseDir, contractPath);
+            try {
+              (0, import_fs.readFileSync)(configResolved, "utf-8");
+              return configResolved;
+            } catch {
+            }
+          }
+          const cwdResolved = import_path4.default.resolve(process.cwd(), contractPath);
+          try {
+            (0, import_fs.readFileSync)(cwdResolved, "utf-8");
+            return cwdResolved;
+          } catch {
+            return new URL(contractPath, import_meta2.url).pathname;
+          }
+        })();
         const contractData = (0, import_fs.readFileSync)(resolvedPath, "utf-8");
         const componentContract = JSON.parse(contractData);
         const selectors = componentContract.selectors;
-        if (componentName.includes("combobox")) {
-          const mainSelector = selectors.input || selectors.container;
-          return new ComboboxComponentStrategy(mainSelector, selectors, actionTimeoutMs, assertionTimeoutMs);
-        }
-        if (componentName === "accordion") {
-          const mainSelector = selectors.trigger || selectors.container;
-          return new AccordionComponentStrategy(mainSelector, selectors, actionTimeoutMs, assertionTimeoutMs);
-        }
-        if (componentName === "menu") {
-          const mainSelector = selectors.trigger || selectors.container;
-          return new MenuComponentStrategy(mainSelector, selectors, actionTimeoutMs, assertionTimeoutMs);
+        const strategyClass = await this.strategyRegistry.loadStrategy(
+          componentName,
+          typedComponentConfig?.strategyPath,
+          configBaseDir
+        );
+        if (!strategyClass) {
+          return null;
         }
+        const mainSelector = selectors.trigger || selectors.input || selectors.tablist || selectors.container;
         if (componentName === "tabs") {
-          const mainSelector = selectors.tablist || selectors.tab;
-          return new TabsComponentStrategy(mainSelector, selectors);
+          return new strategyClass(mainSelector, selectors);
         }
-        return null;
+        return new strategyClass(
+          mainSelector,
+          selectors,
+          actionTimeoutMs,
+          assertionTimeoutMs
+        );
       }
     };
   }
@@ -1782,17 +2031,42 @@ var contractTestRunnerPlaywright_exports = {};
 __export(contractTestRunnerPlaywright_exports, {
   runContractTestsPlaywright: () => runContractTestsPlaywright
 });
-async function runContractTestsPlaywright(componentName, url, strictness) {
-  const reporter = new ContractReporter(true);
+async function runContractTestsPlaywright(componentName, url, strictness, config, configBaseDir) {
+  const componentConfig = config?.test?.components?.find((c) => c.name === componentName);
+  const isCustomContract = !!componentConfig?.path;
+  const reporter = new ContractReporter(true, isCustomContract);
   const actionTimeoutMs = 400;
   const assertionTimeoutMs = 400;
   const strictnessMode = normalizeStrictness(strictness);
-  const contractTyped = contract_default;
-  const contractPath = contractTyped[componentName]?.path;
-  const resolvedPath = new URL(contractPath, import_meta3.url).pathname;
+  let contractPath = componentConfig?.path;
+  if (!contractPath) {
+    const contractTyped = contract_default;
+    contractPath = contractTyped[componentName]?.path;
+  }
+  if (!contractPath) {
+    throw new Error(`Contract path not found for component: ${componentName}`);
+  }
+  const resolvedPath = (() => {
+    if (import_path5.default.isAbsolute(contractPath)) return contractPath;
+    if (configBaseDir) {
+      const configResolved = import_path5.default.resolve(configBaseDir, contractPath);
+      try {
+        (0, import_fs2.readFileSync)(configResolved, "utf-8");
+        return configResolved;
+      } catch {
+      }
+    }
+    const cwdResolved = import_path5.default.resolve(process.cwd(), contractPath);
+    try {
+      (0, import_fs2.readFileSync)(cwdResolved, "utf-8");
+      return cwdResolved;
+    } catch {
+      return new URL(contractPath, import_meta3.url).pathname;
+    }
+  })();
   const contractData = (0, import_fs2.readFileSync)(resolvedPath, "utf-8");
   const componentContract = JSON.parse(contractData);
-  const totalTests = componentContract.static[0].assertions.length + componentContract.dynamic.length;
+  const totalTests = (componentContract.relationships?.length || 0) + (componentContract.static[0]?.assertions.length || 0) + componentContract.dynamic.length;
   const apgUrl = componentContract.meta?.source?.apg;
   const failures = [];
   const warnings = [];
@@ -1829,7 +2103,7 @@ async function runContractTestsPlaywright(componentName, url, strictness) {
       }
       await page.addStyleTag({ content: `* { transition: none !important; animation: none !important; }` });
     }
-    const strategy = ComponentDetector.detect(componentName, actionTimeoutMs, assertionTimeoutMs);
+    const strategy = await ComponentDetector.detect(componentName, componentConfig, actionTimeoutMs, assertionTimeoutMs, configBaseDir);
     if (!strategy) {
       throw new Error(`Unsupported component: ${componentName}`);
     }
@@ -1862,6 +2136,105 @@ This usually means:
     let staticPassed = 0;
     let staticFailed = 0;
     let staticWarnings = 0;
+    for (const rel of componentContract.relationships || []) {
+      const relationshipLevel = normalizeLevel(rel.level);
+      if (rel.type === "aria-reference") {
+        const relDescription = `${rel.from}.${rel.attribute} references ${rel.to}`;
+        const fromSelector = componentContract.selectors[rel.from];
+        const toSelector = componentContract.selectors[rel.to];
+        if (!fromSelector || !toSelector) {
+          const outcome = classifyFailure(
+            `Relationship selector missing: from="${rel.from}" or to="${rel.to}" not found in selectors.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const fromTarget = page.locator(fromSelector).first();
+        const toTarget = page.locator(toSelector).first();
+        const fromExists = await fromTarget.count() > 0;
+        const toExists = await toTarget.count() > 0;
+        if (!fromExists || !toExists) {
+          const outcome = classifyFailure(
+            `Relationship target not found: ${!fromExists ? rel.from : rel.to}.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const attrValue = await fromTarget.getAttribute(rel.attribute);
+        const toId = await toTarget.getAttribute("id");
+        if (!toId) {
+          const outcome = classifyFailure(
+            `Relationship target "${rel.to}" must have an id for ${rel.attribute} validation.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const references = (attrValue || "").split(/\s+/).filter(Boolean);
+        const matches = references.includes(toId);
+        if (!matches) {
+          const outcome = classifyFailure(
+            `Expected ${rel.from} ${rel.attribute} to reference id "${toId}", found "${attrValue || ""}".`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        passes.push(`Relationship valid: ${rel.from}.${rel.attribute} -> ${rel.to} (id=${toId}).`);
+        staticPassed += 1;
+        reporter.reportStaticTest(relDescription, "pass", void 0, relationshipLevel);
+        continue;
+      }
+      if (rel.type === "contains") {
+        const relDescription = `${rel.parent} contains ${rel.child}`;
+        const parentSelector = componentContract.selectors[rel.parent];
+        const childSelector = componentContract.selectors[rel.child];
+        if (!parentSelector || !childSelector) {
+          const outcome = classifyFailure(
+            `Relationship selector missing: parent="${rel.parent}" or child="${rel.child}" not found in selectors.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const parent = page.locator(parentSelector).first();
+        const parentExists = await parent.count() > 0;
+        if (!parentExists) {
+          const outcome = classifyFailure(`Relationship parent target not found: ${rel.parent}.`, rel.level);
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        const descendants = parent.locator(childSelector);
+        const descendantCount = await descendants.count();
+        if (descendantCount < 1) {
+          const outcome = classifyFailure(
+            `Expected ${rel.parent} to contain descendant matching selector for ${rel.child}.`,
+            rel.level
+          );
+          if (outcome.status === "fail") staticFailed += 1;
+          if (outcome.status === "warn") staticWarnings += 1;
+          reporter.reportStaticTest(relDescription, outcome.status, outcome.detail, outcome.level);
+          continue;
+        }
+        passes.push(`Relationship valid: ${rel.parent} contains ${rel.child}.`);
+        staticPassed += 1;
+        reporter.reportStaticTest(relDescription, "pass", void 0, relationshipLevel);
+      }
+    }
     const staticAssertionRunner = new AssertionRunner(page, componentContract.selectors, assertionTimeoutMs);
     for (const test of componentContract.static[0]?.assertions || []) {
       if (test.target === "relative") continue;
@@ -2095,11 +2468,12 @@ Make sure your dev server is running at ${url}`);
   }
   return { passes, failures, skipped, warnings };
 }
-var import_fs2, import_meta3;
+var import_fs2, import_path5, import_meta3;
 var init_contractTestRunnerPlaywright = __esm({
   "src/utils/test/src/contractTestRunnerPlaywright.ts"() {
     "use strict";
     import_fs2 = require("fs");
+    import_path5 = __toESM(require("path"), 1);
     init_contract();
     init_playwrightTestHarness();
     init_ComponentDetector();
@@ -2150,14 +2524,24 @@ Error: ${error instanceof Error ? error.message : String(error)}`
     return null;
   }
   let strictness = normalizeStrictness(options.strictness);
-  if (options.strictness === void 0 && typeof window === "undefined") {
+  let config = {};
+  let configBaseDir = typeof process !== "undefined" ? process.cwd() : "";
+  if (typeof process !== "undefined" && typeof process.cwd === "function") {
     try {
       const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_configLoader(), configLoader_exports));
-      const { config } = await loadConfig2(process.cwd());
-      const componentStrictness = config.test?.components?.find((comp) => comp?.name === componentName)?.strictness;
-      strictness = normalizeStrictness(componentStrictness ?? config.test?.strictness);
+      const result2 = await loadConfig2(process.cwd());
+      config = result2.config;
+      if (result2.configPath) {
+        configBaseDir = import_path6.default.dirname(result2.configPath);
+      }
+      if (options.strictness === void 0) {
+        const componentStrictness = config.test?.components?.find((comp) => comp?.name === componentName)?.strictness;
+        strictness = normalizeStrictness(componentStrictness ?? config.test?.strictness);
+      }
     } catch {
-      strictness = "balanced";
+      if (options.strictness === void 0) {
+        strictness = "balanced";
+      }
     }
   }
   let contract;
@@ -2167,7 +2551,7 @@ Error: ${error instanceof Error ? error.message : String(error)}`
       if (devServerUrl) {
         console.log(`\u{1F3AD} Running Playwright tests on ${devServerUrl}`);
         const { runContractTestsPlaywright: runContractTestsPlaywright2 } = await Promise.resolve().then(() => (init_contractTestRunnerPlaywright(), contractTestRunnerPlaywright_exports));
-        contract = await runContractTestsPlaywright2(componentName, devServerUrl, strictness);
+        contract = await runContractTestsPlaywright2(componentName, devServerUrl, strictness, config, configBaseDir);
       } else {
         throw new Error(
           `\u274C Dev server not running at ${url}
@@ -2223,7 +2607,7 @@ ${violationDetails}
 async function cleanupTests() {
   await closeSharedBrowser();
 }
-var import_jest_axe, runTest;
+var import_jest_axe, import_path6, runTest;
 var init_test2 = __esm({
   "src/utils/test/src/test.ts"() {
     "use strict";
@@ -2231,6 +2615,7 @@ var init_test2 = __esm({
     init_contractTestRunner();
     init_playwrightTestHarness();
     init_strictness();
+    import_path6 = __toESM(require("path"), 1);
     runTest = async () => {
       return {
         passes: [],
@@ -2243,7 +2628,7 @@ var init_test2 = __esm({
         console.log(`\u{1F680} Running component accessibility tests...
 `);
         const { exec } = await import("child_process");
-        const chalk3 = (await import("chalk")).default;
+        const chalk4 = (await import("chalk")).default;
         return new Promise((resolve, reject) => {
           exec(
             `npx vitest --run --reporter verbose`,
@@ -2256,11 +2641,11 @@ var init_test2 = __esm({
                   const { displayBadgeInfo: displayBadgeInfo2, promptAddBadge: promptAddBadge2 } = await Promise.resolve().then(() => (init_badgeHelper(), badgeHelper_exports));
                   displayBadgeInfo2("component");
                   await promptAddBadge2("component", process.cwd());
-                  console.log(chalk3.dim("\n" + "\u2500".repeat(60)));
-                  console.log(chalk3.cyan("\u{1F499} Found aria-ease helpful?"));
-                  console.log(chalk3.white("   \u2022 Star us on GitHub: ") + chalk3.blue.underline("https://github.com/aria-ease/aria-ease"));
-                  console.log(chalk3.white("   \u2022 Share feedback: ") + chalk3.blue.underline("https://github.com/aria-ease/aria-ease/discussions"));
-                  console.log(chalk3.dim("\u2500".repeat(60) + "\n"));
+                  console.log(chalk4.dim("\n" + "\u2500".repeat(60)));
+                  console.log(chalk4.cyan("\u{1F499} Found aria-ease helpful?"));
+                  console.log(chalk4.white("   \u2022 Star us on GitHub: ") + chalk4.blue.underline("https://github.com/aria-ease/aria-ease"));
+                  console.log(chalk4.white("   \u2022 Share feedback: ") + chalk4.blue.underline("https://github.com/aria-ease/aria-ease/discussions"));
+                  console.log(chalk4.dim("\u2500".repeat(60) + "\n"));
                 } catch (badgeError) {
                   console.error("Warning: Could not display badge prompt:", badgeError);
                 }
@@ -2293,33 +2678,480 @@ var init_test3 = __esm({
   }
 });
 
+// src/utils/cli/contractValidator.ts
+function validateContractSchema(contract) {
+  const errors = [];
+  if (!contract || typeof contract !== "object") {
+    return {
+      valid: false,
+      errors: [{ path: "$", message: "Contract must be an object" }]
+    };
+  }
+  const c = contract;
+  if (!c.selectors) {
+    errors.push({ path: "$.selectors", message: "selectors is required" });
+  } else if (typeof c.selectors !== "object" || c.selectors === null || Array.isArray(c.selectors)) {
+    errors.push({ path: "$.selectors", message: "selectors must be an object" });
+  } else {
+    const selectors = c.selectors;
+    Object.entries(selectors).forEach(([key, value]) => {
+      if (typeof value !== "string") {
+        errors.push({ path: `$.selectors['${key}']`, message: "All selectors must be strings" });
+      }
+    });
+  }
+  if (!Array.isArray(c.static)) {
+    errors.push({ path: "$.static", message: "static must be an array" });
+  } else {
+    c.static.forEach((item, idx) => {
+      if (typeof item !== "object" || item === null) {
+        errors.push({ path: `$.static[${idx}]`, message: "static item must be an object" });
+        return;
+      }
+      const staticItem = item;
+      if (!Array.isArray(staticItem.assertions)) {
+        errors.push({
+          path: `$.static[${idx}].assertions`,
+          message: "assertions must be an array"
+        });
+        return;
+      }
+      staticItem.assertions.forEach((assertion, assertIdx) => {
+        if (typeof assertion !== "object" || assertion === null) {
+          errors.push({
+            path: `$.static[${idx}].assertions[${assertIdx}]`,
+            message: "assertion must be an object"
+          });
+          return;
+        }
+        const a = assertion;
+        if (typeof a.target !== "string") {
+          errors.push({
+            path: `$.static[${idx}].assertions[${assertIdx}].target`,
+            message: "target is required and must be a string"
+          });
+        }
+        if (typeof a.attribute !== "string") {
+          errors.push({
+            path: `$.static[${idx}].assertions[${assertIdx}].attribute`,
+            message: "attribute is required and must be a string"
+          });
+        }
+        if (typeof a.failureMessage !== "string") {
+          errors.push({
+            path: `$.static[${idx}].assertions[${assertIdx}].failureMessage`,
+            message: "failureMessage is required and must be a string"
+          });
+        }
+        if (a.level !== void 0 && !["required", "recommended", "optional"].includes(a.level)) {
+          errors.push({
+            path: `$.static[${idx}].assertions[${assertIdx}].level`,
+            message: "level must be one of: required, recommended, optional"
+          });
+        }
+      });
+    });
+  }
+  if (!Array.isArray(c.dynamic)) {
+    errors.push({ path: "$.dynamic", message: "dynamic must be an array" });
+  } else {
+    c.dynamic.forEach((item, idx) => {
+      if (typeof item !== "object" || item === null) {
+        errors.push({ path: `$.dynamic[${idx}]`, message: "dynamic item must be an object" });
+        return;
+      }
+      const dynamicItem = item;
+      if (typeof dynamicItem.description !== "string") {
+        errors.push({
+          path: `$.dynamic[${idx}].description`,
+          message: "description is required and must be a string"
+        });
+      }
+      if (!Array.isArray(dynamicItem.action)) {
+        errors.push({
+          path: `$.dynamic[${idx}].action`,
+          message: "action is required and must be an array"
+        });
+      } else {
+        dynamicItem.action.forEach((action, actIdx) => {
+          if (typeof action !== "object" || action === null) {
+            errors.push({
+              path: `$.dynamic[${idx}].action[${actIdx}]`,
+              message: "action item must be an object"
+            });
+            return;
+          }
+          const a = action;
+          if (typeof a.type !== "string") {
+            errors.push({
+              path: `$.dynamic[${idx}].action[${actIdx}].type`,
+              message: "type is required and must be a string"
+            });
+          }
+          if (typeof a.target !== "string") {
+            errors.push({
+              path: `$.dynamic[${idx}].action[${actIdx}].target`,
+              message: "target is required and must be a string"
+            });
+          }
+        });
+      }
+      if (!Array.isArray(dynamicItem.assertions)) {
+        errors.push({
+          path: `$.dynamic[${idx}].assertions`,
+          message: "assertions is required and must be an array"
+        });
+      } else {
+        dynamicItem.assertions.forEach((assertion, assertIdx) => {
+          if (typeof assertion !== "object" || assertion === null) {
+            errors.push({
+              path: `$.dynamic[${idx}].assertions[${assertIdx}]`,
+              message: "assertion must be an object"
+            });
+            return;
+          }
+          const a = assertion;
+          if (typeof a.target !== "string") {
+            errors.push({
+              path: `$.dynamic[${idx}].assertions[${assertIdx}].target`,
+              message: "target is required and must be a string"
+            });
+          }
+          if (typeof a.assertion !== "string") {
+            errors.push({
+              path: `$.dynamic[${idx}].assertions[${assertIdx}].assertion`,
+              message: "assertion is required and must be a string"
+            });
+          }
+          if (a.level !== void 0 && !["required", "recommended", "optional"].includes(a.level)) {
+            errors.push({
+              path: `$.dynamic[${idx}].assertions[${assertIdx}].level`,
+              message: "level must be one of: required, recommended, optional"
+            });
+          }
+        });
+      }
+    });
+  }
+  if (c.relationships !== void 0) {
+    if (!Array.isArray(c.relationships)) {
+      errors.push({ path: "$.relationships", message: "relationships must be an array" });
+    } else {
+      c.relationships.forEach((rel, idx) => {
+        if (typeof rel !== "object" || rel === null) {
+          errors.push({ path: `$.relationships[${idx}]`, message: "relationship must be an object" });
+          return;
+        }
+        const r = rel;
+        const type = r.type;
+        if (!["aria-reference", "contains"].includes(type)) {
+          errors.push({
+            path: `$.relationships[${idx}].type`,
+            message: "type must be one of: aria-reference, contains"
+          });
+        }
+        if (type === "aria-reference") {
+          if (typeof r.from !== "string") {
+            errors.push({
+              path: `$.relationships[${idx}].from`,
+              message: "from is required for aria-reference and must be a string"
+            });
+          }
+          if (typeof r.attribute !== "string") {
+            errors.push({
+              path: `$.relationships[${idx}].attribute`,
+              message: "attribute is required for aria-reference and must be a string"
+            });
+          }
+          if (typeof r.to !== "string") {
+            errors.push({
+              path: `$.relationships[${idx}].to`,
+              message: "to is required for aria-reference and must be a string"
+            });
+          }
+        } else if (type === "contains") {
+          if (typeof r.parent !== "string") {
+            errors.push({
+              path: `$.relationships[${idx}].parent`,
+              message: "parent is required for contains and must be a string"
+            });
+          }
+          if (typeof r.child !== "string") {
+            errors.push({
+              path: `$.relationships[${idx}].child`,
+              message: "child is required for contains and must be a string"
+            });
+          }
+        }
+      });
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateRelationshipReferences(contract, selectorKeys) {
+  const errors = [];
+  if (!contract || typeof contract !== "object") {
+    return errors;
+  }
+  const c = contract;
+  const relationships = c.relationships;
+  if (!Array.isArray(relationships)) {
+    return errors;
+  }
+  relationships.forEach((rel, idx) => {
+    const type = rel.type;
+    if (type === "aria-reference") {
+      const from = rel.from;
+      const to = rel.to;
+      if (from && !selectorKeys.has(from)) {
+        errors.push({
+          path: `$.relationships[${idx}].from`,
+          message: `Selector '${from}' not found in selectors`
+        });
+      }
+      if (to && !selectorKeys.has(to)) {
+        errors.push({
+          path: `$.relationships[${idx}].to`,
+          message: `Selector '${to}' not found in selectors`
+        });
+      }
+    } else if (type === "contains") {
+      const parent = rel.parent;
+      const child = rel.child;
+      if (parent && !selectorKeys.has(parent)) {
+        errors.push({
+          path: `$.relationships[${idx}].parent`,
+          message: `Selector '${parent}' not found in selectors`
+        });
+      }
+      if (child && !selectorKeys.has(child)) {
+        errors.push({
+          path: `$.relationships[${idx}].child`,
+          message: `Selector '${child}' not found in selectors`
+        });
+      }
+    }
+  });
+  return errors;
+}
+function validateTargetReferences(contract, selectorKeys) {
+  const errors = [];
+  if (!contract || typeof contract !== "object") {
+    return errors;
+  }
+  const c = contract;
+  const staticItems = c.static;
+  if (Array.isArray(staticItems)) {
+    staticItems.forEach((item, itemIdx) => {
+      const assertions = item.assertions;
+      if (Array.isArray(assertions)) {
+        assertions.forEach((assertion, assertIdx) => {
+          const target = assertion.target;
+          if (target && !selectorKeys.has(target)) {
+            errors.push({
+              path: `$.static[${itemIdx}].assertions[${assertIdx}].target`,
+              message: `Selector '${target}' not found in selectors`
+            });
+          }
+        });
+      }
+    });
+  }
+  const dynamicItems = c.dynamic;
+  if (Array.isArray(dynamicItems)) {
+    dynamicItems.forEach((item, itemIdx) => {
+      const actions = item.action;
+      if (Array.isArray(actions)) {
+        actions.forEach((action, actIdx) => {
+          const target = action.target;
+          if (target && target !== "document" && !selectorKeys.has(target)) {
+            errors.push({
+              path: `$.dynamic[${itemIdx}].action[${actIdx}].target`,
+              message: `Selector '${target}' not found in selectors (or use 'document')`
+            });
+          }
+        });
+      }
+      const assertions = item.assertions;
+      if (Array.isArray(assertions)) {
+        assertions.forEach((assertion, assertIdx) => {
+          const target = assertion.target;
+          if (target && target !== "relative" && !selectorKeys.has(target)) {
+            errors.push({
+              path: `$.dynamic[${itemIdx}].assertions[${assertIdx}].target`,
+              message: `Selector '${target}' not found in selectors (or use 'relative')`
+            });
+          }
+        });
+      }
+    });
+  }
+  return errors;
+}
+var init_contractValidator = __esm({
+  "src/utils/cli/contractValidator.ts"() {
+    "use strict";
+  }
+});
+
+// src/utils/cli/buildContracts.ts
+var buildContracts_exports = {};
+__export(buildContracts_exports, {
+  buildContracts: () => buildContracts
+});
+async function buildContracts(cwd, config) {
+  const errors = [];
+  const built = [];
+  if (!config.contracts || config.contracts.length === 0) {
+    console.log(import_chalk2.default.yellow('\u2139\uFE0F  No contracts configured. Add "contracts" array to ariaease.config.js'));
+    return { success: true, built, errors };
+  }
+  try {
+    console.log(import_chalk2.default.cyanBright("\n\u{1F3D7}\uFE0F  Building contracts...\n"));
+    for (const contractSource of config.contracts) {
+      const srcPattern = import_path7.default.resolve(cwd, contractSource.src);
+      const outDir = contractSource.out ? import_path7.default.resolve(cwd, contractSource.out) : void 0;
+      console.log(import_chalk2.default.gray(`   Pattern: ${contractSource.src}`));
+      if (outDir) {
+        console.log(import_chalk2.default.gray(`   Output:  ${contractSource.out}
+`));
+      } else {
+        console.log(import_chalk2.default.gray(`   Output:  Same directory as source
+`));
+      }
+      const contractFiles = [];
+      for await (const file of (0, import_promises2.glob)(srcPattern, { cwd })) {
+        contractFiles.push(file);
+      }
+      if (contractFiles.length === 0) {
+        console.log(import_chalk2.default.yellow(`\u26A0\uFE0F  No contract files found matching pattern: ${contractSource.src}`));
+        continue;
+      }
+      if (outDir) {
+        await import_fs_extra3.default.ensureDir(outDir);
+      }
+      for (const contractFile of contractFiles) {
+        try {
+          const absolutePath = contractFile.startsWith("/") ? contractFile : import_path7.default.resolve(cwd, contractFile);
+          const module2 = await import(`file://${absolutePath}`);
+          let contract = module2.default;
+          if (!contract) {
+            const namedExports = Object.entries(module2).find(
+              ([, value]) => value && typeof value === "object" && "toJSON" in value
+            );
+            if (namedExports) {
+              contract = namedExports[1];
+            }
+          }
+          if (!contract || typeof contract.toJSON !== "function") {
+            errors.push(`${import_path7.default.basename(contractFile)}: No contract with toJSON() method found`);
+            continue;
+          }
+          const json = contract.toJSON();
+          const schemaValidation = validateContractSchema(json);
+          if (!schemaValidation.valid) {
+            const errorLines = schemaValidation.errors.map((err) => `     ${import_chalk2.default.red("\u2717")} ${err.path}: ${err.message}`).join("\n");
+            const errorMsg = `Schema validation failed:
+${errorLines}`;
+            errors.push(`${import_path7.default.basename(contractFile)}: ${errorMsg}`);
+            console.log(import_chalk2.default.red(`\u274C ${import_path7.default.basename(contractFile)}`));
+            console.log(import_chalk2.default.red(`   ${errorMsg}`));
+            continue;
+          }
+          const selectorKeys = /* @__PURE__ */ new Set();
+          if (json && typeof json === "object" && "selectors" in json) {
+            const selectors = json.selectors;
+            Object.keys(selectors).forEach((key) => selectorKeys.add(key));
+          }
+          const refErrors = [
+            ...validateRelationshipReferences(json, selectorKeys),
+            ...validateTargetReferences(json, selectorKeys)
+          ];
+          if (refErrors.length > 0) {
+            const errorLines = refErrors.map((err) => `     ${import_chalk2.default.red("\u2717")} ${err.path}: ${err.message}`).join("\n");
+            const errorMsg = `Reference validation failed:
+${errorLines}`;
+            errors.push(`${import_path7.default.basename(contractFile)}: ${errorMsg}`);
+            console.log(import_chalk2.default.red(`\u274C ${import_path7.default.basename(contractFile)}`));
+            console.log(import_chalk2.default.red(`   ${errorMsg}`));
+            continue;
+          }
+          const contractName = import_path7.default.basename(contractFile, import_path7.default.extname(contractFile));
+          const outputFile = outDir ? import_path7.default.join(outDir, `${contractName}.json`) : import_path7.default.join(import_path7.default.dirname(absolutePath), `${contractName}.json`);
+          await import_fs_extra3.default.writeFile(outputFile, JSON.stringify(json, null, 2) + "\n", "utf-8");
+          const relativePath = import_path7.default.relative(cwd, outputFile);
+          built.push(relativePath);
+          console.log(import_chalk2.default.green(`\u2705 ${import_path7.default.basename(contractFile)} \u2192 ${import_path7.default.basename(outputFile)}`));
+        } catch (error) {
+          const errorMsg = error instanceof Error ? error.message : String(error);
+          const filename = import_path7.default.basename(contractFile);
+          errors.push(`${filename}: ${errorMsg}`);
+          console.log(import_chalk2.default.red(`\u274C ${filename}`));
+          console.log(import_chalk2.default.red(`   Error: ${errorMsg}`));
+        }
+      }
+    }
+    console.log("");
+    if (errors.length === 0) {
+      console.log(import_chalk2.default.green(`\u2705 Built ${built.length} contract${built.length !== 1 ? "s" : ""} successfully
+`));
+      return { success: true, built, errors };
+    } else {
+      console.log(import_chalk2.default.yellow(`\u26A0\uFE0F  Built ${built.length} contracts with ${errors.length} error${errors.length !== 1 ? "s" : ""}
+`));
+      return { success: false, built, errors };
+    }
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    const msg = `Failed to build contracts: ${errorMsg}`;
+    errors.push(msg);
+    console.log(import_chalk2.default.red(`\u274C ${msg}
+`));
+    return { success: false, built, errors };
+  }
+}
+var import_path7, import_fs_extra3, import_promises2, import_chalk2;
+var init_buildContracts = __esm({
+  "src/utils/cli/buildContracts.ts"() {
+    "use strict";
+    import_path7 = __toESM(require("path"), 1);
+    import_fs_extra3 = __toESM(require("fs-extra"), 1);
+    import_promises2 = require("fs/promises");
+    import_chalk2 = __toESM(require("chalk"), 1);
+    init_contractValidator();
+  }
+});
+
 // src/utils/cli/cli.ts
 var import_commander = require("commander");
-var import_chalk2 = __toESM(require("chalk"), 1);
-var import_path3 = __toESM(require("path"), 1);
-var import_fs_extra3 = __toESM(require("fs-extra"), 1);
+var import_chalk3 = __toESM(require("chalk"), 1);
+var import_path8 = __toESM(require("path"), 1);
+var import_fs_extra4 = __toESM(require("fs-extra"), 1);
 init_configLoader();
 init_badgeHelper();
 var program = new import_commander.Command();
 program.name("aria-ease").description("Run accessibility tests and audits").version("2.2.3");
 program.command("audit").description("Run axe-core powered accessibility audit on webpages").option("-u, --url <url>", "Single URL to audit").option("-f, --format <format>", "Output format for the audit report: json | csv | html | all", "all").option("-o, --out <path>", "Directory to save the audit report", "./accessibility-reports/audit").action(async (opts) => {
-  console.log(import_chalk2.default.cyanBright("\u{1F680} Starting accessibility audit...\n"));
+  console.log(import_chalk3.default.cyanBright("\u{1F680} Starting accessibility audit...\n"));
   const { runAudit: runAudit2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
   const { formatResults: formatResults2 } = await Promise.resolve().then(() => (init_formatters(), formatters_exports));
   const needsConfig = !opts.url;
   const { config, configPath, errors } = await loadConfig(process.cwd());
   if (configPath) {
-    console.log(import_chalk2.default.green(`\u2705 Loaded config from ${import_path3.default.basename(configPath)}
+    console.log(import_chalk3.default.green(`\u2705 Loaded config from ${import_path8.default.basename(configPath)}
 `));
   } else if (errors.length > 0 && needsConfig) {
-    console.log(import_chalk2.default.red("\u274C Config file errors:\n"));
-    errors.forEach((err) => console.log(import_chalk2.default.red(`   ${err}`)));
+    console.log(import_chalk3.default.red("\u274C Config file errors:\n"));
+    errors.forEach((err) => console.log(import_chalk3.default.red(`   ${err}`)));
     console.log("");
     process.exit(1);
   } else if (errors.length > 0) {
-    console.log(import_chalk2.default.yellow("\u26A0\uFE0F  Config file has errors (ignored, using CLI options)\n"));
+    console.log(import_chalk3.default.yellow("\u26A0\uFE0F  Config file has errors (ignored, using CLI options)\n"));
   } else if (!configPath && needsConfig) {
-    console.log(import_chalk2.default.yellow("\u2139\uFE0F  No config file found, using CLI options.\n"));
+    console.log(import_chalk3.default.yellow("\u2139\uFE0F  No config file found, using CLI options.\n"));
   }
   const urls = [];
   if (opts.url) {
@@ -2329,11 +3161,11 @@ program.command("audit").description("Run axe-core powered accessibility audit o
   }
   const format = config.audit?.output && config.audit.output.format || opts.format;
   if (!["json", "csv", "html", "all"].includes(format)) {
-    console.log(import_chalk2.default.red('\u274C Invalid format. Use "json", "csv", "html" or "all".'));
+    console.log(import_chalk3.default.red('\u274C Invalid format. Use "json", "csv", "html" or "all".'));
     process.exit(1);
   }
   if (urls.length === 0) {
-    console.log(import_chalk2.default.red('\u274C No URLs provided. Use --url option or add "urls" in config file'));
+    console.log(import_chalk3.default.red('\u274C No URLs provided. Use --url option or add "urls" in config file'));
     process.exit(1);
   }
   const allResults = [];
@@ -2342,15 +3174,15 @@ program.command("audit").description("Run axe-core powered accessibility audit o
   try {
     const auditOptions = { browser };
     for (const url of urls) {
-      console.log(import_chalk2.default.yellow(`\u{1F50E} Auditing: ${url}`));
+      console.log(import_chalk3.default.yellow(`\u{1F50E} Auditing: ${url}`));
       try {
         const result = await runAudit2(url, auditOptions);
         allResults.push({ url, result });
-        console.log(import_chalk2.default.green(`\u2705 Completed audit for ${url}
+        console.log(import_chalk3.default.green(`\u2705 Completed audit for ${url}
 `));
       } catch (error) {
         if (error instanceof Error && error.message) {
-          console.log(import_chalk2.default.red(`\u274C Failed auditing ${url}: ${error.message}`));
+          console.log(import_chalk3.default.red(`\u274C Failed auditing ${url}: ${error.message}`));
         }
       }
     }
@@ -2361,32 +3193,32 @@ program.command("audit").description("Run axe-core powered accessibility audit o
   if (!hasResults) {
     const auditedCount = allResults.filter((r) => r.result).length;
     if (auditedCount === 0) {
-      console.log(import_chalk2.default.red("\u274C No pages were successfully audited."));
+      console.log(import_chalk3.default.red("\u274C No pages were successfully audited."));
       process.exit(1);
     }
-    console.log(import_chalk2.default.green("\n\u{1F389} Great news! No static accessibility violations found!"));
-    console.log(import_chalk2.default.gray(`   Audited ${auditedCount} page${auditedCount > 1 ? "s" : ""} successfully.
+    console.log(import_chalk3.default.green("\n\u{1F389} Great news! No static accessibility violations found!"));
+    console.log(import_chalk3.default.gray(`   Audited ${auditedCount} page${auditedCount > 1 ? "s" : ""} successfully.
 `));
     displayBadgeInfo("audit");
     await promptAddBadge("audit", process.cwd());
-    console.log(import_chalk2.default.dim("\n" + "\u2500".repeat(60)));
-    console.log(import_chalk2.default.cyan("\u{1F499} Found aria-ease helpful?"));
-    console.log(import_chalk2.default.white("   \u2022 Star us on GitHub: ") + import_chalk2.default.blue.underline("https://github.com/aria-ease/aria-ease"));
-    console.log(import_chalk2.default.white("   \u2022 Share feedback: ") + import_chalk2.default.blue.underline("https://github.com/aria-ease/aria-ease/discussions"));
-    console.log(import_chalk2.default.dim("\u2500".repeat(60) + "\n"));
+    console.log(import_chalk3.default.dim("\n" + "\u2500".repeat(60)));
+    console.log(import_chalk3.default.cyan("\u{1F499} Found aria-ease helpful?"));
+    console.log(import_chalk3.default.white("   \u2022 Star us on GitHub: ") + import_chalk3.default.blue.underline("https://github.com/aria-ease/aria-ease"));
+    console.log(import_chalk3.default.white("   \u2022 Share feedback: ") + import_chalk3.default.blue.underline("https://github.com/aria-ease/aria-ease/discussions"));
+    console.log(import_chalk3.default.dim("\u2500".repeat(60) + "\n"));
     process.exit(0);
   }
   async function createReport(format2) {
     const formatted = formatResults2(allResults, format2);
     const out = config.audit?.output && config.audit.output.out || opts.out;
-    await import_fs_extra3.default.ensureDir(out);
+    await import_fs_extra4.default.ensureDir(out);
     const d = /* @__PURE__ */ new Date();
     const pad = (n) => String(n).padStart(2, "0");
     const timestamp = `${pad(d.getDate())}-${pad(d.getMonth() + 1)}-${d.getFullYear()} ${pad(d.getHours())}h ${pad(d.getMinutes())}m ${pad(d.getSeconds())}s`;
     const fileName = `ariaease-report-${timestamp}.${format2}`;
-    const filePath = import_path3.default.join(out, fileName);
-    await import_fs_extra3.default.writeFile(filePath, formatted, "utf-8");
-    console.log(import_chalk2.default.magentaBright(`\u{1F4C1} Report saved to ${filePath}`));
+    const filePath = import_path8.default.join(out, fileName);
+    await import_fs_extra4.default.writeFile(filePath, formatted, "utf-8");
+    console.log(import_chalk3.default.magentaBright(`\u{1F4C1} Report saved to ${filePath}`));
   }
   if (["json", "csv", "html"].includes(format)) {
     await createReport(format);
@@ -2396,22 +3228,53 @@ program.command("audit").description("Run axe-core powered accessibility audit o
   const totalViolations = allResults.reduce((sum, r) => {
     return sum + (r.result?.violations?.length || 0);
   }, 0);
-  console.log(import_chalk2.default.red(`
+  console.log(import_chalk3.default.red(`
 \u274C Accessibility violations found!`));
-  console.log(import_chalk2.default.yellow(`   ${totalViolations} violation${totalViolations !== 1 ? "s" : ""} detected across ${allResults.length} page${allResults.length !== 1 ? "s" : ""}.`));
-  console.log(import_chalk2.default.gray(`   Review the generated report for details.
+  console.log(import_chalk3.default.yellow(`   ${totalViolations} violation${totalViolations !== 1 ? "s" : ""} detected across ${allResults.length} page${allResults.length !== 1 ? "s" : ""}.`));
+  console.log(import_chalk3.default.gray(`   Review the generated report for details.
 `));
-  console.log(import_chalk2.default.dim("\n" + "\u2500".repeat(60)));
-  console.log(import_chalk2.default.cyan("\u{1F499} Found aria-ease helpful?"));
-  console.log(import_chalk2.default.white("   \u2022 Star us on GitHub: ") + import_chalk2.default.blue.underline("https://github.com/aria-ease/aria-ease"));
-  console.log(import_chalk2.default.white("   \u2022 Share feedback: ") + import_chalk2.default.blue.underline("https://github.com/aria-ease/aria-ease/discussions"));
-  console.log(import_chalk2.default.dim("\u2500".repeat(60) + "\n"));
+  console.log(import_chalk3.default.dim("\n" + "\u2500".repeat(60)));
+  console.log(import_chalk3.default.cyan("\u{1F499} Found aria-ease helpful?"));
+  console.log(import_chalk3.default.white("   \u2022 Star us on GitHub: ") + import_chalk3.default.blue.underline("https://github.com/aria-ease/aria-ease"));
+  console.log(import_chalk3.default.white("   \u2022 Share feedback: ") + import_chalk3.default.blue.underline("https://github.com/aria-ease/aria-ease/discussions"));
+  console.log(import_chalk3.default.dim("\u2500".repeat(60) + "\n"));
   process.exit(1);
 });
 program.command("test").description("Run core a11y accessibility standard tests on UI components").action(async () => {
   const { runTest: runTest2 } = await Promise.resolve().then(() => (init_test3(), test_exports2));
   runTest2();
 });
+program.command("build").description("Build accessibility artifacts").addCommand(
+  new import_commander.Command("contracts").description("Build DSL contracts to JSON").action(async () => {
+    const { buildContracts: buildContracts2 } = await Promise.resolve().then(() => (init_buildContracts(), buildContracts_exports));
+    const { loadConfig: loadConfig2 } = await Promise.resolve().then(() => (init_configLoader(), configLoader_exports));
+    const cwd = process.cwd();
+    const { config, configPath, errors } = await loadConfig2(cwd);
+    if (configPath) {
+      console.log(import_chalk3.default.green(`\u2705 Loaded config from ${import_path8.default.basename(configPath)}
+`));
+    } else if (errors.length > 0) {
+      console.log(import_chalk3.default.red("\u274C Config file has errors:\n"));
+      errors.forEach((err) => console.log(import_chalk3.default.red(`   ${err}`)));
+      console.log("");
+      process.exit(1);
+    }
+    const result = await buildContracts2(cwd, config);
+    if (!result.success && result.errors.length > 0) {
+      console.log(import_chalk3.default.red(`\u274C ${result.errors.length} error${result.errors.length !== 1 ? "s" : ""} occurred during build
+`));
+      process.exit(1);
+    }
+    if (result.built.length === 0 && (!config.contracts || config.contracts.length === 0)) {
+      process.exit(0);
+    }
+    if (result.built.length === 0) {
+      console.log(import_chalk3.default.yellow("\u26A0\uFE0F  No contracts were built\n"));
+      process.exit(1);
+    }
+    process.exit(0);
+  })
+);
 program.command("help").description("Display help information").action(() => {
   program.outputHelp();
 });