@diegovelasquezweb/a11y-engine 0.1.3 → 0.1.4

package/docs/outputs.md

@@ -7,6 +7,7 @@
 ## Table of Contents
 
 - [Default output directory](#default-output-directory)
+- [progress.json](#progressjson)
 - [a11y-scan-results.json](#a11y-scan-resultsjson)
 - [a11y-findings.json](#a11y-findingsjson)
 - [remediation.md](#remediationmd)
@@ -23,7 +24,8 @@ All artifacts are written to `.audit/` relative to the package root (`SKILL_ROOT
 
 ```
 .audit/
-├── a11y-scan-results.json   # raw axe-core scan data
+├── progress.json            # real-time scan progress (per-engine steps + counts)
+├── a11y-scan-results.json   # merged raw results from axe + CDP + pa11y
 ├── a11y-findings.json       # enriched findings (primary data artifact)
 ├── remediation.md           # AI agent remediation guide
 ├── report.html              # interactive dashboard (--with-reports)
@@ -36,25 +38,62 @@ All artifacts are written to `.audit/` relative to the package root (`SKILL_ROOT
 
 ---
 
+## progress.json
+
+Real-time scan progress written by `scripts/engine/dom-scanner.mjs` as each engine runs. Used by integrations for live progress UI.
+
+```json
+{
+  "steps": {
+    "page":  { "status": "done", "updatedAt": "2026-03-14T14:02:50.609Z" },
+    "axe":   { "status": "done", "updatedAt": "2026-03-14T14:02:51.389Z", "found": 8 },
+    "cdp":   { "status": "done", "updatedAt": "2026-03-14T14:02:51.401Z", "found": 3 },
+    "pa11y": { "status": "done", "updatedAt": "2026-03-14T14:02:55.667Z", "found": 2 },
+    "merge": { "status": "done", "updatedAt": "2026-03-14T14:02:55.668Z", "axe": 8, "cdp": 3, "pa11y": 2, "merged": 11 }
+  },
+  "currentStep": "merge"
+}
+```
+
+### Step keys
+
+| Key | Engine | Description |
+| :--- | :--- | :--- |
+| `page` | — | Page navigation and load |
+| `axe` | axe-core | axe-core WCAG rule scan. `found` = violation count. |
+| `cdp` | CDP | Chrome DevTools Protocol accessibility tree check. `found` = issue count. |
+| `pa11y` | pa11y | HTML CodeSniffer scan. `found` = issue count. |
+| `merge` | — | Cross-engine merge and deduplication. `merged` = final unique count. |
+
+### Step statuses
+
+`pending` → `running` → `done` (or `error`)
+
+---
+
 ## a11y-scan-results.json
 
-Raw axe-core output per route. Written by `scripts/engine/dom-scanner.mjs`.
+Merged results from all three engines (axe-core + CDP + pa11y) per route. Written by `scripts/engine/dom-scanner.mjs`.
 
 ```json
 {
+  "generated_at": "2026-03-14T14:02:55.668Z",
+  "base_url": "https://example.com",
+  "projectContext": { "framework": "nextjs", "uiLibraries": ["radix-ui"] },
   "routes": [
     {
       "path": "/",
       "url": "https://example.com/",
       "violations": [...],
       "incomplete": [...],
-      "passes": [...],
-      "inapplicable": [...]
+      "passes": [...]
     }
   ]
 }
 ```
 
+Each violation in the `violations` array includes a `source` field indicating which engine produced it (`undefined` for axe-core, `"cdp"` for CDP checks, `"pa11y"` for pa11y).
+
 This file is consumed by `analyzer.mjs` and also used by `--affected-only` to determine which routes to re-scan on subsequent runs.
 
 ---
@@ -68,7 +107,8 @@ The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. Th
 ```json
 {
   "metadata": { ... },
-  "findings": [ ... ]
+  "findings": [ ... ],
+  "incomplete_findings": [ ... ]
 }
 ```
 
@@ -92,7 +132,8 @@ The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. Th
 | Field | Type | Description |
 | :--- | :--- | :--- |
 | `id` | `string` | Deterministic finding ID (e.g. `A11Y-001`) |
-| `rule_id` | `string` | axe-core rule ID (e.g. `color-contrast`) |
+| `rule_id` | `string` | Rule ID from the source engine (e.g. `color-contrast`, `cdp-missing-accessible-name`, `pa11y-wcag2aa-...`) |
+| `source_rule_id` | `string\|null` | Original rule ID when mapped from CDP/pa11y to axe equivalent |
 | `title` | `string` | Human-readable finding title |
 | `severity` | `string` | `Critical`, `Serious`, `Moderate`, or `Minor` |
 | `wcag` | `string` | WCAG success criterion (e.g. `1.4.3`) |
@@ -108,7 +149,7 @@ The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. Th
 | `category` | `string` | Violation category (e.g. `Color & Contrast`) |
 | `primary_failure_mode` | `string\|null` | Root cause classification |
 | `relationship_hint` | `string\|null` | Label/input relationship context |
-| `failure_checks` | `object[]` | axe check-level failure details |
+| `failure_checks` | `object[]` | Engine check-level failure details |
 | `related_context` | `object[]` | Surrounding DOM context |
 | `fix_description` | `string\|null` | Plain-language fix explanation |
 | `fix_code` | `string\|null` | Ready-to-apply code snippet |
@@ -116,13 +157,13 @@ The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. Th
 | `recommended_fix` | `string` | Link to canonical fix reference (APG, MDN) |
 | `mdn` | `string\|null` | MDN documentation URL |
 | `effort` | `string\|null` | Fix effort estimate (`low`, `medium`, `high`) |
-| `related_rules` | `string[]` | Related axe rule IDs |
+| `related_rules` | `string[]` | Related rule IDs |
 | `guardrails` | `object\|null` | Agent scope guardrails for this finding |
 | `false_positive_risk` | `string\|null` | Known false positive patterns |
 | `fix_difficulty_notes` | `string\|null` | Edge cases and pitfalls for this fix |
 | `framework_notes` | `string\|null` | Framework-specific fix guidance |
 | `cms_notes` | `string\|null` | CMS-specific fix guidance |
-| `check_data` | `object\|null` | Raw axe check data |
+| `check_data` | `object\|null` | Raw engine check data |
 | `total_instances` | `number` | Count of affected elements across all pages |
 | `evidence` | `object[]` | DOM HTML snippets for each affected element |
 | `screenshot_path` | `string\|null` | Path to element screenshot |
@@ -138,6 +179,10 @@ The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. Th
 | `pages_affected` | `number\|null` | Number of pages with this violation |
 | `affected_urls` | `string[]\|null` | All URLs where this violation appears |
 
+### `incomplete_findings`
+
+Violations that axe-core flagged as "needs review" (not confirmed pass or fail). Included for manual verification but not counted in the compliance score.
+
 ---
 
 ## remediation.md
@@ -236,6 +281,19 @@ const engineRoot = fs.realpathSync(symlinkBase);
 const findingsPath = path.join(engineRoot, ".audit", "a11y-findings.json");
 ```
 
+### Reading `progress.json` for live UI updates
+
+```js
+const progressPath = path.join(engineRoot, ".audit", "progress.json");
+
+// Poll this file during scan execution
+if (fs.existsSync(progressPath)) {
+  const progress = JSON.parse(fs.readFileSync(progressPath, "utf-8"));
+  console.log(`Current step: ${progress.currentStep}`);
+  console.log(`axe found: ${progress.steps?.axe?.found ?? "pending"}`);
+}
+```
+
 ### Parsing stdout markers
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,10 @@
   "engines": {
     "node": ">=18"
   },
+  "exports": {
+    ".": "./scripts/index.mjs"
+  },
+  "main": "scripts/index.mjs",
   "bin": {
     "a11y-audit": "scripts/audit.mjs"
   },

package/scripts/audit.mjs

@@ -31,6 +31,7 @@ Targeting & Scope:
 
 Audit Intelligence:
   --target <text>         Compliance target label (default: "WCAG 2.2 AA").
+  --axe-tags <csv>        Comma-separated axe tags (e.g., wcag2a,wcag2aa).
   --only-rule <id>        Only check for this specific rule ID.
   --ignore-findings <csv> Ignore specific rule IDs.
   --exclude-selectors <csv> Exclude CSS selectors from scan.
@@ -136,6 +137,7 @@ async function main() {
   const routes = getArgValue("routes");
   const waitMs = getArgValue("wait-ms") || DEFAULTS.waitMs;
   const timeoutMs = getArgValue("timeout-ms") || DEFAULTS.timeoutMs;
+  const axeTags = getArgValue("axe-tags");
 
   const sessionFile = getInternalPath("a11y-session.json");
   let projectDir = getArgValue("project-dir");
@@ -254,6 +256,7 @@ async function main() {
     if (viewport) {
       scanArgs.push("--viewport", `${viewport.width}x${viewport.height}`);
     }
+    if (axeTags) scanArgs.push("--axe-tags", axeTags);
 
     await runScript("engine/dom-scanner.mjs", scanArgs, childEnv);
 

package/scripts/core/asset-loader.mjs

@@ -34,6 +34,10 @@ export const ASSET_PATHS = {
     ),
     codePatterns: path.join(ASSET_ROOT, "remediation", "code-patterns.json"),
   },
+  engine: {
+    cdpChecks: path.join(ASSET_ROOT, "engine", "cdp-checks.json"),
+    pa11yConfig: path.join(ASSET_ROOT, "engine", "pa11y-config.json"),
+  },
   reporting: {
     wcagReference: path.join(ASSET_ROOT, "reporting", "wcag-reference.json"),
     complianceConfig: path.join(

package/scripts/engine/analyzer.mjs

@@ -745,7 +745,12 @@ function computeTestingMethodology(payload) {
   const scanned = routes.filter((r) => !r.error).length;
   const errored = routes.filter((r) => r.error).length;
   return {
-    automated_tools: ["axe-core (via @axe-core/playwright)", "Playwright + Chromium"],
+    automated_tools: [
+      "axe-core (via @axe-core/playwright)",
+      "CDP accessibility tree checks (Playwright)",
+      "pa11y (HTML CodeSniffer via Puppeteer)",
+      "Playwright + Chromium",
+    ],
     compliance_target: "WCAG 2.2 AA",
     pages_scanned: scanned,
     pages_errored: errored,
@@ -826,6 +831,8 @@ function buildFindings(inputPayload, cliArgs) {
         findings.push({
           id: "",
           rule_id: v.id,
+          source_rule_id: v.source_rule_id || null,
+          source: v.source || "axe",
           title: v.help,
           severity: IMPACT_MAP[v.impact] || "Medium",
           wcag: mapWcag(v.tags),

package/scripts/engine/dom-scanner.mjs

@@ -25,6 +25,14 @@ const STACK_DETECTION = loadAssetJson(
   ASSET_PATHS.discovery.stackDetection,
   "assets/discovery/stack-detection.json",
 );
+const CDP_CHECKS = loadAssetJson(
+  ASSET_PATHS.engine.cdpChecks,
+  "assets/engine/cdp-checks.json",
+);
+const PA11Y_CONFIG = loadAssetJson(
+  ASSET_PATHS.engine.pa11yConfig,
+  "assets/engine/pa11y-config.json",
+);
 const AXE_TAGS = [
   "wcag2a",
   "wcag2aa",
@@ -505,9 +513,14 @@ function writeProgress(step, status, extra = {}) {
  */
 async function runCdpChecks(page) {
   const violations = [];
+  const interactiveRoles = CDP_CHECKS.interactiveRoles || [];
+  const rulesById = {};
+  for (const rule of CDP_CHECKS.rules || []) {
+    rulesById[rule.condition] = rule;
+  }
+
   try {
     const cdp = await page.context().newCDPSession(page);
-
     const { nodes } = await cdp.send("Accessibility.getFullAXTree");
 
     for (const node of nodes) {
@@ -521,8 +534,9 @@ async function runCdpChecks(page) {
       const focusable = properties.find((p) => p.name === "focusable")?.value?.value === true;
       const hidden = properties.find((p) => p.name === "hidden")?.value?.value === true;
 
-      const interactiveRoles = ["button", "link", "textbox", "combobox", "listbox", "menuitem", "tab", "checkbox", "radio", "switch", "slider"];
       if (interactiveRoles.includes(role) && !name.trim()) {
+        const rule = rulesById["interactive-no-name"];
+        if (!rule) continue;
         const backendId = node.backendDOMNodeId;
         let selector = "";
         try {
@@ -543,13 +557,15 @@ async function runCdpChecks(page) {
           }
         } catch { /* fallback: no selector */ }
 
+        const desc = (rule.description || "").replace(/\{\{role\}\}/g, role);
+        const msg = (rule.failureMessage || "").replace(/\{\{role\}\}/g, role);
         violations.push({
-          id: "cdp-missing-accessible-name",
-          impact: "serious",
-          tags: ["wcag2a", "wcag412", "cdp-check"],
-          description: `Interactive element with role "${role}" has no accessible name`,
-          help: "Interactive elements must have an accessible name",
-          helpUrl: "https://dequeuniversity.com/rules/axe/4.11/button-name",
+          id: rule.id,
+          impact: rule.impact,
+          tags: rule.tags,
+          description: desc,
+          help: rule.help,
+          helpUrl: rule.helpUrl,
           source: "cdp",
           nodes: [{
             any: [],
@@ -557,26 +573,30 @@ async function runCdpChecks(page) {
               id: "cdp-accessible-name",
               data: { role, name: "(empty)" },
               relatedNodes: [],
-              impact: "serious",
-              message: `Element with role "${role}" has no accessible name in the accessibility tree`,
+              impact: rule.impact,
+              message: msg,
             }],
             none: [],
-            impact: "serious",
+            impact: rule.impact,
             html: `<${role} aria-role="${role}">`,
             target: selector ? [selector] : [`[role="${role}"]`],
-            failureSummary: `Fix all of the following:\n  Element with role "${role}" has no accessible name`,
+            failureSummary: `Fix all of the following:\n  ${msg}`,
           }],
         });
       }
 
       if (hidden && focusable) {
+        const rule = rulesById["hidden-focusable"];
+        if (!rule) continue;
+        const desc = (rule.description || "").replace(/\{\{role\}\}/g, role);
+        const msg = (rule.failureMessage || "").replace(/\{\{role\}\}/g, role);
         violations.push({
-          id: "cdp-aria-hidden-focusable",
-          impact: "serious",
-          tags: ["wcag2a", "wcag412", "cdp-check"],
-          description: `Focusable element with role "${role}" is aria-hidden`,
-          help: "aria-hidden elements must not be focusable",
-          helpUrl: "https://dequeuniversity.com/rules/axe/4.11/aria-hidden-focus",
+          id: rule.id,
+          impact: rule.impact,
+          tags: rule.tags,
+          description: desc,
+          help: rule.help,
+          helpUrl: rule.helpUrl,
           source: "cdp",
           nodes: [{
             any: [],
@@ -584,14 +604,14 @@ async function runCdpChecks(page) {
               id: "cdp-hidden-focusable",
               data: { role },
               relatedNodes: [],
-              impact: "serious",
-              message: `Focusable element with role "${role}" is hidden from the accessibility tree`,
+              impact: rule.impact,
+              message: msg,
             }],
             none: [],
-            impact: "serious",
+            impact: rule.impact,
             html: `<element role="${role}" aria-hidden="true">`,
             target: [`[role="${role}"]`],
-            failureSummary: `Fix all of the following:\n  Focusable element is hidden from the accessibility tree`,
+            failureSummary: `Fix all of the following:\n  ${msg}`,
           }],
         });
       }
@@ -614,6 +634,12 @@ async function runCdpChecks(page) {
  */
 async function runPa11yChecks(routeUrl, axeTags) {
   const violations = [];
+  const equivalenceMap = PA11Y_CONFIG.equivalenceMap || {};
+  const impactMap = {};
+  for (const [k, v] of Object.entries(PA11Y_CONFIG.impactMap || {})) {
+    impactMap[Number(k)] = v;
+  }
+
   try {
     let standard = "WCAG2AA";
     if (axeTags) {
@@ -622,6 +648,9 @@ async function runPa11yChecks(routeUrl, axeTags) {
       else if (axeTags.includes("wcag2a")) standard = "WCAG2A";
     }
 
+    // Build ignore list with dynamic standard prefix
+    const ignoreList = (PA11Y_CONFIG.ignoreByPrinciple || []).map((r) => `${standard}.${r}`);
+
     const results = await pa11y(routeUrl, {
       standard,
       timeout: 30000,
@@ -629,14 +658,9 @@ async function runPa11yChecks(routeUrl, axeTags) {
       chromeLaunchConfig: {
         args: ["--no-sandbox", "--disable-setuid-sandbox"],
       },
-      ignore: [
-        "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail",
-        "WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.A.NoContent",
-      ],
+      ignore: ignoreList,
     });
 
-    const impactMap = { 1: "serious", 2: "moderate", 3: "minor" };
-
     for (const issue of results.issues || []) {
       if (issue.type === "notice") continue;
 
@@ -648,7 +672,18 @@ async function runPa11yChecks(routeUrl, axeTags) {
         wcagCriterion = `${wcagMatch[3]}.${wcagMatch[4]}.${wcagMatch[5]}`;
       }
 
-      const ruleId = `pa11y-${(issue.code || "unknown").replace(/\./g, "-").toLowerCase().slice(0, 60)}`;
+      // Resolve axe-equivalent rule ID from equivalence map
+      const codeWithoutStandard = (issue.code || "").replace(/^WCAG2(A{1,3})\./, "");
+      let axeEquivId = null;
+      for (const [pattern, axeId] of Object.entries(equivalenceMap)) {
+        if (codeWithoutStandard.startsWith(pattern)) {
+          axeEquivId = axeId;
+          break;
+        }
+      }
+
+      const ruleId = axeEquivId || `pa11y-${(issue.code || "unknown").replace(/\./g, "-").toLowerCase().slice(0, 60)}`;
+      const originalCode = issue.code || "unknown";
 
       violations.push({
         id: ruleId,
@@ -660,11 +695,12 @@ async function runPa11yChecks(routeUrl, axeTags) {
           ? `https://www.w3.org/WAI/WCAG21/Understanding/${wcagCriterion.replace(/\./g, "")}`
           : "https://squizlabs.github.io/HTML_CodeSniffer/",
         source: "pa11y",
+        source_rule_id: originalCode,
         nodes: [{
           any: [],
           all: [{
             id: "pa11y-check",
-            data: { code: issue.code, context: issue.context?.slice(0, 200) },
+            data: { code: originalCode, context: issue.context?.slice(0, 200) },
             relatedNodes: [],
             impact,
             message: issue.message || "",
@@ -693,20 +729,28 @@ async function runPa11yChecks(routeUrl, axeTags) {
  */
 function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
   const seen = new Set();
+  const seenRuleTargets = new Map(); // rule -> Set<target> for cross-engine dedup
   const merged = [];
 
+  // Build CDP equivalence map from JSON config
+  const cdpAxeEquiv = {};
+  for (const rule of CDP_CHECKS.rules || []) {
+    cdpAxeEquiv[rule.id] = rule.axeEquivalents || [];
+  }
+
+  // Step 1: axe findings (baseline)
   for (const v of axeViolations) {
-    const key = `${v.id}::${v.nodes?.[0]?.target?.[0] || ""}`;
+    const target = v.nodes?.[0]?.target?.[0] || "";
+    const key = `${v.id}::${target}`;
     seen.add(key);
+    if (!seenRuleTargets.has(v.id)) seenRuleTargets.set(v.id, new Set());
+    seenRuleTargets.get(v.id).add(target);
     merged.push(v);
   }
 
+  // Step 2: CDP findings — check against axe equivalents from JSON
   for (const v of cdpViolations) {
-    const axeEquiv = {
-      "cdp-missing-accessible-name": ["button-name", "link-name", "input-name", "aria-command-name"],
-      "cdp-aria-hidden-focusable": ["aria-hidden-focus"],
-    };
-    const equivRules = axeEquiv[v.id] || [];
+    const equivRules = cdpAxeEquiv[v.id] || [];
     const target = v.nodes?.[0]?.target?.[0] || "";
     const isDuplicate = equivRules.some((r) => seen.has(`${r}::${target}`));
     if (!isDuplicate) {
@@ -718,12 +762,20 @@ function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
     }
   }
 
+  // Step 3: pa11y findings — check via canonical rule ID (axe-equivalent) + selector
   for (const v of pa11yViolations) {
     const target = v.nodes?.[0]?.target?.[0] || "";
     const key = `${v.id}::${target}`;
-    const selectorCovered = [...seen].some((k) => k.endsWith(`::${target}`) && target);
-    if (!seen.has(key) && (!selectorCovered || !target)) {
+
+    // If pa11y was mapped to an axe rule ID, check if that rule already covers this target
+    const isAxeEquivDuplicate = v.id && seenRuleTargets.has(v.id) && target && seenRuleTargets.get(v.id).has(target);
+    // Also check if any existing finding covers this exact target (broader dedup)
+    const selectorCovered = target && [...seen].some((k) => k.endsWith(`::${target}`));
+
+    if (!seen.has(key) && !isAxeEquivDuplicate && (!selectorCovered || !target)) {
       seen.add(key);
+      if (!seenRuleTargets.has(v.id)) seenRuleTargets.set(v.id, new Set());
+      seenRuleTargets.get(v.id).add(target);
       merged.push(v);
     }
   }
@@ -806,6 +858,7 @@ async function main() {
    * @type {Set<string>}
    */
   const SKIP_SELECTORS = new Set(["html", "body", "head", ":root", "document"]);
+  const SKIP_SELECTOR_PREFIXES = ["meta", "link", "style", "script", "title", "base"];
 
   /**
    * Captures a screenshot of an element associated with an accessibility violation.
@@ -818,7 +871,9 @@ async function main() {
     const firstNode = violation.nodes?.[0];
     if (!firstNode || firstNode.target.length > 1) return;
     const selector = firstNode.target[0];
-    if (!selector || SKIP_SELECTORS.has(selector.toLowerCase())) return;
+    const lowerSelector = (selector || "").toLowerCase();
+    if (!selector || SKIP_SELECTORS.has(lowerSelector)) return;
+    if (SKIP_SELECTOR_PREFIXES.some((p) => lowerSelector.startsWith(p))) return;
     try {
       fs.mkdirSync(args.screenshotsDir, { recursive: true });
       const safeRuleId = violation.id.replace(/[^a-z0-9-]/g, "-");