aria-ease 6.7.0 → 6.9.0

package/dist/src/utils/test/index.cjs

@@ -1,9 +1,10 @@
 'use strict';
 
 var playwright = require('playwright');
-var path = require('path');
+var path3 = require('path');
 var fs3 = require('fs-extra');
 var test = require('@playwright/test');
+var url = require('url');
 var fs = require('fs');
 var chalk = require('chalk');
 var readline = require('readline');
@@ -13,7 +14,7 @@ var fs$1 = require('fs/promises');
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
-var path__default = /*#__PURE__*/_interopDefault(path);
+var path3__default = /*#__PURE__*/_interopDefault(path3);
 var fs3__default = /*#__PURE__*/_interopDefault(fs3);
 var chalk__default = /*#__PURE__*/_interopDefault(chalk);
 var readline__default = /*#__PURE__*/_interopDefault(readline);
@@ -69,11 +70,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");
@@ -234,6 +237,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);
         }
@@ -245,7 +255,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) {
@@ -254,7 +264,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`);
@@ -449,6 +459,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`);
               }
@@ -463,11 +476,29 @@ 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) {
   try {
-    const ext = path__default.default.extname(filePath);
+    const ext = path3__default.default.extname(filePath);
     if (ext === ".json") {
       const content = await fs3__default.default.readFile(filePath, "utf-8");
       return JSON.parse(content);
@@ -492,7 +523,7 @@ async function loadConfig(cwd = process.cwd()) {
   let foundPath = null;
   const errors = [];
   for (const name of configNames) {
-    const configPath = path__default.default.resolve(cwd, name);
+    const configPath = path3__default.default.resolve(cwd, name);
     if (await fs3__default.default.pathExists(configPath)) {
       foundPath = configPath;
       loadedConfig = await loadConfigFile(configPath);
@@ -520,10 +551,16 @@ var init_configLoader = __esm({
   "src/utils/cli/configLoader.ts"() {
   }
 });
-var ComboboxComponentStrategy;
-var init_ComboboxComponentStrategy = __esm({
-  "src/utils/test/src/component-strategies/ComboboxComponentStrategy.ts"() {
-    ComboboxComponentStrategy = class {
+
+// 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"() {
+    MenuComponentStrategy = class {
       constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
         this.mainSelector = mainSelector;
         this.selectors = selectors;
@@ -560,19 +597,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;
@@ -580,6 +634,12 @@ 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"() {
@@ -618,10 +678,16 @@ var init_AccordionComponentStrategy = __esm({
     };
   }
 });
-var MenuComponentStrategy;
-var init_MenuComponentStrategy = __esm({
-  "src/utils/test/src/component-strategies/MenuComponentStrategy.ts"() {
-    MenuComponentStrategy = class {
+
+// 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"() {
+    ComboboxComponentStrategy = class {
       constructor(mainSelector, selectors, actionTimeoutMs = 400, assertionTimeoutMs = 400) {
         this.mainSelector = mainSelector;
         this.selectors = selectors;
@@ -634,60 +700,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 test.expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+          listBoxClosed = await test.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 test.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 test.expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
         }
-        if (!menuClosed) {
+        if (!listBoxClosed) {
           await page.mouse.click(10, 10);
-          menuClosed = await test.expect(popupElement).toBeHidden({ timeout: this.assertionTimeoutMs }).then(() => true).catch(() => false);
+          listBoxClosed = await test.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;
@@ -697,6 +746,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"() {
@@ -725,42 +778,163 @@ var init_TabsComponentStrategy = __esm({
     };
   }
 });
+var StrategyRegistry;
+var init_StrategyRegistry = __esm({
+  "src/utils/test/src/StrategyRegistry.ts"() {
+    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 = path3__default.default.isAbsolute(customStrategyPath) ? customStrategyPath : path3__default.default.resolve(configBaseDir || process.cwd(), customStrategyPath);
+              const customModule = await 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);
+      }
+    };
+  }
+});
 var ComponentDetector;
 var init_ComponentDetector = __esm({
   "src/utils/test/src/ComponentDetector.ts"() {
-    init_ComboboxComponentStrategy();
-    init_AccordionComponentStrategy();
-    init_MenuComponentStrategy();
-    init_TabsComponentStrategy();
     init_contract();
+    init_StrategyRegistry();
     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, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))).pathname;
+        const resolvedPath = (() => {
+          if (path3__default.default.isAbsolute(contractPath)) return contractPath;
+          if (configBaseDir) {
+            const configResolved = path3__default.default.resolve(configBaseDir, contractPath);
+            try {
+              fs.readFileSync(configResolved, "utf-8");
+              return configResolved;
+            } catch {
+            }
+          }
+          const cwdResolved = path3__default.default.resolve(process.cwd(), contractPath);
+          try {
+            fs.readFileSync(cwdResolved, "utf-8");
+            return cwdResolved;
+          } catch {
+            return new URL(contractPath, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))).pathname;
+          }
+        })();
         const contractData = 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
+        );
       }
     };
   }
@@ -1265,17 +1439,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, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))).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 (path3__default.default.isAbsolute(contractPath)) return contractPath;
+    if (configBaseDir) {
+      const configResolved = path3__default.default.resolve(configBaseDir, contractPath);
+      try {
+        fs.readFileSync(configResolved, "utf-8");
+        return configResolved;
+      } catch {
+      }
+    }
+    const cwdResolved = path3__default.default.resolve(process.cwd(), contractPath);
+    try {
+      fs.readFileSync(cwdResolved, "utf-8");
+      return cwdResolved;
+    } catch {
+      return new URL(contractPath, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))).pathname;
+    }
+  })();
   const contractData = fs.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 = [];
@@ -1312,7 +1511,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}`);
     }
@@ -1345,6 +1544,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;
@@ -1611,7 +1909,7 @@ function displayBadgeInfo(badgeType) {
   console.log(chalk__default.default.dim("\n   This helps others discover accessibility tools and shows you care!\n"));
 }
 async function promptAddBadge(badgeType, cwd = process.cwd()) {
-  const readmePath = path__default.default.join(cwd, "README.md");
+  const readmePath = path3__default.default.join(cwd, "README.md");
   const readmeExists = await fs3__default.default.pathExists(readmePath);
   if (!readmeExists) {
     console.log(chalk__default.default.yellow("   \u2139\uFE0F  No README.md found in current directory"));
@@ -1714,7 +2012,7 @@ async function runContractTests(componentName, component, strictness) {
   const resolvedPath = new URL(contractPath, (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href))).pathname;
   const contractData = await fs__default.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 = [];
@@ -1738,6 +2036,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);
@@ -1833,14 +2207,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 = path3__default.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;
@@ -1850,7 +2234,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}