aria-ease 6.5.1 → 6.7.0

package/README.md

@@ -13,19 +13,15 @@ Stop treating accessibility as an afterthought. Aria-Ease engineers accessibilit
 
 Aria-Ease isn't a utility library. **It's an accessibility infrastructure** that integrates into every phase of your frontend engineering lifecycle:
 
-| Phase              | Feature                                       | Status       | Impact                                  |
-| ------------------ | --------------------------------------------- | ------------ | --------------------------------------- |
-| **🔧 Development** | Component utilities for accessible patterns   | ✅ Available | Build it right from the start           |
-| **⚡ Linting**     | ESLint rules to enforce accessible coding     | 🚧 Roadmap   | Catch mistakes as you type              |
-| **🔍 Pre-Deploy**  | Axe-core powered static accessibility audit   | ✅ Available | Verify before it ships                  |
-| **🧪 Testing**     | WAI-ARIA APG contract testing with Playwright | ✅ Available | 26 combobox assertions in ~4 seconds    |
-| **🚀 CI/CD**       | Accessibility as deployment gatekeeper        | ✅ Available | Block inaccessible code from production |
-| **📊 Production**  | Real user signal monitoring and replay        | 🚧 Roadmap   | Understand how users actually interact  |
-| **📈 Insights**    | Dashboard for reporting and analytics         | 🚧 Roadmap   | Visualize accessibility health          |
-
-**The philosophy:** By the time your app reaches manual testing, there should only be minute, non-automatable aspects left to verify.
-
-**The reality:** Code that fails accessibility checks cannot reach production. Period.
+| Phase              | Feature                                       | Status       | Impact                                        |
+| ------------------ | --------------------------------------------- | ------------ | --------------------------------------------- |
+| **🔧 Development** | Component utilities for accessible patterns   | ✅ Available | Build it right from the start                 |
+| **⚡ Linting**     | ESLint rules to enforce accessible coding     | 🚧 Roadmap   | Catch mistakes as you type                    |
+| **🔍 Pre-Deploy**  | Axe-core powered static accessibility audit   | ✅ Available | Verify before it ships                        |
+| **🧪 Testing**     | WAI-ARIA APG contract testing with Playwright | ✅ Available | Fast, determinic component accessibility test |
+| **🚀 CI/CD**       | Accessibility as deployment gatekeeper        | ✅ Available | Block inaccessible code from production       |
+| **📊 Production**  | Real user signal monitoring and replay        | 🚧 Roadmap   | Understand how users actually interact        |
+| **📈 Insights**    | Dashboard for reporting and analytics         | 🚧 Roadmap   | Visualize accessibility health                |
 
 ---
 
@@ -35,7 +31,7 @@ Aria-Ease isn't a utility library. **It's an accessibility infrastructure** that
 
 **Traditional approach:** Build features → Manual testing → Find accessibility issues → Fix them → Manual testing again → Ship (maybe)
 
-**Aria-Ease approach:** Build with accessible utilities → Automated audits catch issues → Contract tests verify behavior → CI/CD gates deployment → Ship with confidence
+**Aria-Ease approach:** Build with accessible utilities → Automated audits catch issues → Contract tests verify deterministic component behaviors → CI/CD gates deployment → Ship with confidence
 
 ### What Makes This Different?
 
@@ -70,11 +66,11 @@ This is the game-changer. We encoded the WAI-ARIA APG into deterministic JSON "c
 
 ```bash
 npx aria-ease test
-# ✓ 26 assertions in ~4 seconds
+# ✓ 26 assertions in ~2 seconds
 # ✓ 26 assertions in ~1 second in CI
 ```
 
-**Why this matters:** Before, verifying a combobox meant manual keyboard testing across browsers. Now, it's automated, fast, and repeatable. You can boast about executing 26 combobox interaction assertions in ~4 seconds.
+**Why this matters:** Before, verifying a combobox meant manual keyboard testing across browsers. Now, it's automated, fast, and repeatable. You can boast about executing 26 combobox interaction assertions in ~2 seconds.
 
 #### 4. **CI/CD Integration** (Available Now)
 
@@ -134,7 +130,7 @@ pnpm add aria-ease
 
 ### Automated Accessibility Audits (CLI)
 
-Run automated accessibility audits on your website with one command:
+Run axe-core powered automated accessibility audits on your website with one command:
 
 ```bash
 npx aria-ease audit --url https://yoursite.com
@@ -158,6 +154,9 @@ export default {
       out: "./accessibility-reports",
     },
   },
+  test: {
+    strictness: "balanced", // 'minimal' | 'balanced' | 'strict' | 'paranoid'
+  },
 };
 ```
 
@@ -662,6 +661,67 @@ describe("Shopify User Menu Accessibility Test", () => {
 });
 ```
 
+### Strictness Modes
+
+Aria-Ease supports strictness policies to define how contract levels are enforced.
+
+- `minimal`
+  - `required` -> error
+  - `recommended` -> ignore
+  - `optional` -> ignore
+- `balanced` (default)
+  - `required` -> error
+  - `recommended` -> warning
+  - `optional` -> ignore
+- `strict`
+  - `required` -> error
+  - `recommended` -> error
+  - `optional` -> warning
+- `paranoid`
+  - `required` -> error
+  - `recommended` -> error
+  - `optional` -> error
+
+Configure strictness globally in `ariaease.config.*`:
+
+```javascript
+export default {
+  test: {
+    strictness: "balanced",
+  },
+};
+```
+
+Or define strictness per component (recommended when components have different maturity levels):
+
+```javascript
+export default {
+  test: {
+    strictness: "balanced", // fallback
+    components: [
+      {
+        name: "menu",
+        strictness: "strict",
+      },
+      {
+        name: "accordion",
+        strictness: "minimal",
+      },
+    ],
+  },
+};
+```
+
+`path` is optional and not required for strictness resolution.
+
+Or override per test call:
+
+```javascript
+await testUiComponent("menu", null, "http://localhost:5173/test-harness?component=menu", {
+  strictness: "strict",
+});
+```
+
 ---
 
 ## 📦 Bundle Size
@@ -754,7 +814,7 @@ For older browser support, use a polyfill service or transpile with appropriate
 
 ---
 
-## � CI/CD Integration: Accessibility as a Deployment Gatekeeper
+## 🚀 CI/CD Integration: Accessibility as a Deployment Gatekeeper
 
 **The game-changer:** Turn accessibility into a deployment invariant. Code that fails accessibility checks cannot reach production.
 
@@ -876,10 +936,14 @@ Create `ariaease.config.js` in your project root:
 ```javascript
 export default {
   audit: {
-    urls: ["http://localhost:5173/", "http://localhost:5173/changelog"],
+    urls: [
+      "http://localhost:5173", // Homepage
+      "http://localhost:5173/docs", // Docs
+      "http://localhost:5173/examples", // Examples
+    ],
     output: {
-      format: "html",
-      out: "./accessibility-reports/audit",
+      format: "all", // Generate JSON, CSV, and HTML reports
+      out: "./accessibility-reports",
     },
   },
 };
@@ -985,7 +1049,7 @@ npx aria-ease test
 - Deterministic JSON contracts (no flaky selectors)
 - Runs headless in CI
 
-**Compare to manual testing:** Manually verifying keyboard interactions for a combobox (arrow keys, typing, Enter, Escape, Home/End, etc.) across browsers, verifying WAI-ARIA roles, states and properties = 20-30 minutes. Aria-Ease = 4 seconds.
+**Compare to manual testing:** Manually verifying keyboard interactions for a combobox listbox (arrow keys, typing, Enter, Escape, Home/End, etc.) across browsers, verifying WAI-ARIA roles, states and properties = 20-30 minutes. Aria-Ease = ~2 seconds.
 
 ### The Moment of Truth
 
@@ -993,11 +1057,11 @@ The first time you see that green check mark in your CI/CD pipeline—knowing th
 
 **No one has any excuse to ship inaccessible code anymore.**
 
-You've shifted accessibility left (into development), automated the verification, and made it a deployment gatekeeper. By the time code reaches manual testing, there should only be minute, non-automatable aspects left to verify.
+You've shifted accessibility left (into development), automated the verification, and made it a deployment gatekeeper.
 
 ---
 
-## �📖 More Resources
+## 📖 More Resources
 
 - [Full Documentation](https://ariaease.site/docs)
 - [GitHub Repository](https://github.com/aria-ease/aria-ease)

package/bin/{chunk-AUJAN4RK.js → chunk-2TOYEY5L.js}

@@ -24,10 +24,11 @@ var ContractReporter = class {
   componentName = "";
   staticPasses = 0;
   staticFailures = 0;
+  staticWarnings = 0;
   dynamicResults = [];
   totalTests = 0;
   skipped = 0;
-  optionalSuggestions = 0;
+  warnings = 0;
   isPlaywright = false;
   apgUrl = "https://www.w3.org/WAI/ARIA/apg/";
   hasPrintedStaticSection = false;
@@ -54,23 +55,27 @@ ${"\u2550".repeat(60)}`);
     this.log(`${"\u2550".repeat(60)}
 `);
   }
-  reportStatic(passes, failures) {
+  reportStatic(passes, failures, warnings = 0) {
     this.staticPasses = passes;
     this.staticFailures = failures;
+    this.staticWarnings = warnings;
   }
   /**
    * Report individual static test pass
    */
-  reportStaticTest(description, passed, failureMessage) {
+  reportStaticTest(description, status, failureMessage, level) {
     if (!this.hasPrintedStaticSection) {
       this.log(`${"\u2500".repeat(60)}`);
       this.log(`\u{1F9EA} Static Assertions`);
       this.log(`${"\u2500".repeat(60)}`);
       this.hasPrintedStaticSection = true;
     }
-    const icon = passed ? "\u2713" : "\u2717";
+    const icon = status === "pass" ? "\u2713" : status === "warn" ? "\u26A0" : status === "skip" ? "\u25CB" : "\u2717";
     this.log(`  ${icon} ${description}`);
-    if (!passed && failureMessage) {
+    if (level) {
+      this.log(`     \u21B3 level=${level}`);
+    }
+    if ((status === "fail" || status === "warn" || status === "skip") && failureMessage) {
       this.log(`     \u21B3 ${failureMessage}`);
     }
   }
@@ -89,23 +94,26 @@ ${"\u2550".repeat(60)}`);
       description: test.description,
       status,
       failureMessage,
-      isOptional: test.isOptional
+      level: test.level
     };
     if (status === "skip") {
       result.skipReason = "Requires real browser (addEventListener events)";
     }
     this.dynamicResults.push(result);
-    const icons = { pass: "\u2713", fail: "\u2717", skip: "\u25CB", "optional-fail": "\u25CB" };
-    const prefix = test.isOptional ? "[OPTIONAL] " : "";
-    this.log(`  ${icons[status]} ${prefix}${test.description}`);
+    const icons = { pass: "\u2713", fail: "\u2717", warn: "\u26A0", skip: "\u25CB" };
+    const levelPrefix = test.level ? `[${test.level.toUpperCase()}] ` : "";
+    this.log(`  ${icons[status]} ${levelPrefix}${test.description}`);
     if (status === "skip" && !this.isPlaywright) {
       this.log(`     \u21B3 Skipped in jsdom (runs in Playwright)`);
     }
-    if (status === "fail" && failureMessage && !test.isOptional) {
+    if (status === "fail" && failureMessage) {
       this.log(`     \u21B3 ${failureMessage}`);
     }
-    if (status === "optional-fail") {
-      this.log(`     \u21B3 Not implemented (recommended for enhanced UX)`);
+    if (status === "warn" && failureMessage) {
+      this.log(`     \u21B3 ${failureMessage}`);
+    }
+    if (status === "skip" && failureMessage) {
+      this.log(`     \u21B3 ${failureMessage}`);
     }
   }
   /**
@@ -129,29 +137,29 @@ ${"\u2500".repeat(60)}`);
       this.log("");
     });
   }
-  /**
-   * Report optional features that aren't implemented
-   */
-  reportOptionalSuggestions() {
-    const suggestions = this.dynamicResults.filter((r) => r.status === "optional-fail");
-    if (suggestions.length === 0) return;
+  reportWarnings() {
+    const warnings = this.dynamicResults.filter((r) => r.status === "warn");
+    if (warnings.length === 0 && this.staticWarnings === 0) return;
     this.log(`
 ${"\u2500".repeat(60)}`);
-    this.log(`\u{1F4A1} Optional Enhancements (${suggestions.length}):
+    this.log(`\u26A0\uFE0F Warnings (${this.staticWarnings + warnings.length}):
 `);
-    this.log(`These features are optional per APG guidelines but recommended`);
-    this.log(`for improved user experience and keyboard interaction:
+    this.log(`These checks are failing but treated as warnings under the active strictness mode.
 `);
-    suggestions.forEach((test, index) => {
+    warnings.forEach((test, index) => {
       this.log(`${index + 1}. ${test.description}`);
       if (test.failureMessage) {
         this.log(`   \u21B3 ${test.failureMessage}`);
       }
+      if (test.level) {
+        this.log(`   \u21B3 level=${test.level}`);
+      }
     });
-    this.log(`
-\u2728 Consider implementing these for better accessibility`);
-    this.log(`   Reference: ${this.apgUrl}
+    if (this.apgUrl) {
+      this.log(`
+Reference: ${this.apgUrl}
 `);
+    }
   }
   /**
    * Report skipped tests with helpful context
@@ -181,46 +189,42 @@ ${"\u2500".repeat(60)}`);
     const duration = Date.now() - this.startTime;
     const dynamicPasses = this.dynamicResults.filter((r) => r.status === "pass").length;
     const dynamicFailures = this.dynamicResults.filter((r) => r.status === "fail").length;
+    const dynamicWarnings = this.dynamicResults.filter((r) => r.status === "warn").length;
     this.skipped = this.dynamicResults.filter((r) => r.status === "skip").length;
-    this.optionalSuggestions = this.dynamicResults.filter((r) => r.status === "optional-fail").length;
+    this.warnings = this.staticWarnings + dynamicWarnings;
     const totalPasses = this.staticPasses + dynamicPasses;
     const totalFailures = this.staticFailures + dynamicFailures;
-    const totalRun = totalPasses + totalFailures;
+    const totalRun = totalPasses + totalFailures + this.warnings;
     if (failures.length > 0) {
       this.reportFailures(failures);
     }
-    this.reportOptionalSuggestions();
+    this.reportWarnings();
     this.reportSkipped();
     this.log(`
 ${"\u2550".repeat(60)}`);
     this.log(`\u{1F4CA} Summary
 `);
-    const staticIcon = this.staticFailures === 0 ? "\u2705" : "\u274C";
-    const staticStatus = this.staticFailures === 0 ? "PASS" : "FAIL";
-    this.log(`${staticIcon} Static ARIA Tests: ${staticStatus}`);
-    this.log(`   ${this.staticPasses}/${this.staticPasses + this.staticFailures} required attributes present`);
-    this.log("");
-    if (totalFailures === 0 && this.skipped === 0 && this.optionalSuggestions === 0) {
+    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`);
     } else if (totalFailures === 0) {
-      this.log(`\u2705 ${totalPasses}/${totalRun} required tests passed`);
+      this.log(`\u2705 ${totalPasses}/${totalRun} tests passed`);
       if (this.skipped > 0) {
         this.log(`\u25CB  ${this.skipped} tests skipped`);
       }
-      if (this.optionalSuggestions > 0) {
-        this.log(`\u{1F4A1} ${this.optionalSuggestions} optional enhancement${this.optionalSuggestions > 1 ? "s" : ""} suggested`);
+      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`);
     } else {
       this.log(`\u274C ${totalFailures} test${totalFailures > 1 ? "s" : ""} failed`);
       this.log(`\u2705 ${totalPasses} test${totalPasses > 1 ? "s" : ""} passed`);
+      if (this.warnings > 0) {
+        this.log(`\u26A0\uFE0F ${this.warnings} warning${this.warnings > 1 ? "s" : ""}`);
+      }
       if (this.skipped > 0) {
         this.log(`\u25CB  ${this.skipped} test${this.skipped > 1 ? "s" : ""} skipped`);
       }
-      if (this.optionalSuggestions > 0) {
-        this.log(`\u{1F4A1} ${this.optionalSuggestions} optional enhancement${this.optionalSuggestions > 1 ? "s" : ""} suggested`);
-      }
     }
     this.log(`\u23F1\uFE0F  Duration: ${duration}ms`);
     this.log(`${"\u2550".repeat(60)}
@@ -255,6 +259,46 @@ ${"\u2550".repeat(60)}`);
   }
 };
 
+// src/utils/test/src/strictness.ts
+var FALLBACK_LEVEL = "required";
+function normalizeLevel(level) {
+  if (level === "required" || level === "recommended" || level === "optional") {
+    return level;
+  }
+  return FALLBACK_LEVEL;
+}
+function normalizeStrictness(strictness) {
+  if (strictness === "minimal" || strictness === "balanced" || strictness === "strict" || strictness === "paranoid") {
+    return strictness;
+  }
+  return "balanced";
+}
+function resolveEnforcement(level, strictness) {
+  const matrix = {
+    minimal: {
+      required: "error",
+      recommended: "ignore",
+      optional: "ignore"
+    },
+    balanced: {
+      required: "error",
+      recommended: "warning",
+      optional: "ignore"
+    },
+    strict: {
+      required: "error",
+      recommended: "error",
+      optional: "warning"
+    },
+    paranoid: {
+      required: "error",
+      recommended: "error",
+      optional: "error"
+    }
+  };
+  return matrix[strictness][level];
+}
+
 // src/utils/test/src/playwrightTestHarness.ts
 import { chromium } from "playwright";
 var sharedBrowser = null;
@@ -302,6 +346,9 @@ async function closeSharedBrowser() {
 export {
   contract_default,
   ContractReporter,
+  normalizeLevel,
+  normalizeStrictness,
+  resolveEnforcement,
   createTestPage,
   closeSharedBrowser
 };

package/bin/chunk-VPBHLMAS.js

@@ -0,0 +1,127 @@
+// src/utils/cli/configLoader.ts
+import path from "path";
+import fs from "fs-extra";
+function validateConfig(config) {
+  const errors = [];
+  if (!config || typeof config !== "object") {
+    errors.push("Config must be an object");
+    return { valid: false, errors };
+  }
+  const cfg = config;
+  if (cfg.audit !== void 0) {
+    if (typeof cfg.audit !== "object" || cfg.audit === null) {
+      errors.push("audit must be an object");
+    } else {
+      if (cfg.audit.urls !== void 0) {
+        if (!Array.isArray(cfg.audit.urls)) {
+          errors.push("audit.urls must be an array");
+        } else if (cfg.audit.urls.some((url) => typeof url !== "string")) {
+          errors.push("audit.urls must contain only strings");
+        }
+      }
+      if (cfg.audit.output !== void 0) {
+        if (typeof cfg.audit.output !== "object") {
+          errors.push("audit.output must be an object");
+        } else {
+          const output = cfg.audit.output;
+          if (output.format !== void 0) {
+            if (!["json", "csv", "html", "all"].includes(output.format)) {
+              errors.push("audit.output.format must be one of: json, csv, html, all");
+            }
+          }
+          if (output.out !== void 0 && typeof output.out !== "string") {
+            errors.push("audit.output.out must be a string");
+          }
+        }
+      }
+    }
+  }
+  if (cfg.test !== void 0) {
+    if (typeof cfg.test !== "object" || cfg.test === null) {
+      errors.push("test must be an object");
+    } else {
+      if (cfg.test.components !== void 0) {
+        if (!Array.isArray(cfg.test.components)) {
+          errors.push("test.components must be an array");
+        } else {
+          cfg.test.components.forEach((comp, idx) => {
+            if (typeof comp !== "object" || comp === null) {
+              errors.push(`test.components[${idx}] must be an object`);
+            } else {
+              if (typeof comp.name !== "string") {
+                errors.push(`test.components[${idx}].name must be a string`);
+              }
+              if (comp.path !== void 0 && typeof comp.path !== "string") {
+                errors.push(`test.components[${idx}].path 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`);
+              }
+            }
+          });
+        }
+      }
+      if (cfg.test.strictness !== void 0) {
+        if (!["minimal", "balanced", "strict", "paranoid"].includes(cfg.test.strictness)) {
+          errors.push("test.strictness must be one of: minimal, balanced, strict, paranoid");
+        }
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+async function loadConfigFile(filePath) {
+  try {
+    const ext = path.extname(filePath);
+    if (ext === ".json") {
+      const content = await fs.readFile(filePath, "utf-8");
+      return JSON.parse(content);
+    } else if ([".js", ".mjs", ".cjs", ".ts"].includes(ext)) {
+      const imported = await import(filePath);
+      return imported.default || imported;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function loadConfig(cwd = process.cwd()) {
+  const configNames = [
+    "ariaease.config.js",
+    "ariaease.config.mjs",
+    "ariaease.config.cjs",
+    "ariaease.config.json",
+    "ariaease.config.ts"
+  ];
+  let loadedConfig = null;
+  let foundPath = null;
+  const errors = [];
+  for (const name of configNames) {
+    const configPath = path.resolve(cwd, name);
+    if (await fs.pathExists(configPath)) {
+      foundPath = configPath;
+      loadedConfig = await loadConfigFile(configPath);
+      if (loadedConfig === null) {
+        errors.push(`Found config at ${name} but failed to load it. Check for syntax errors.`);
+        continue;
+      }
+      const validation = validateConfig(loadedConfig);
+      if (!validation.valid) {
+        errors.push(`Config validation failed in ${name}:`);
+        errors.push(...validation.errors.map((err) => `  - ${err}`));
+        loadedConfig = null;
+        continue;
+      }
+      break;
+    }
+  }
+  return {
+    config: loadedConfig || {},
+    configPath: loadedConfig ? foundPath : null,
+    errors
+  };
+}
+
+export {
+  loadConfig
+};