@diegovelasquezweb/a11y-engine 0.7.0 → 0.7.2

package/README.md

@@ -10,8 +10,9 @@ Accessibility automation engine for web applications. It orchestrates multi engi
 | **Multi engine scanning** | Runs axe-core, CDP accessibility tree checks, and pa11y HTML CodeSniffer against each page, then merges and deduplicates findings across all three engines |
 | **Stack detection** | Detects framework and CMS from runtime signals and from project source signals such as package.json and file structure |
 | **Fix intelligence** | Enriches each finding with WCAG mapping, fix code snippets, framework and CMS specific notes, UI library ownership hints, effort estimates, and persona impact |
+| **AI enrichment** | Optional Claude-powered analysis that adds contextual fix suggestions based on detected stack, repo structure, and finding patterns |
 | **Report generation** | Produces HTML dashboard, PDF compliance report, manual testing checklist, and Markdown remediation guide |
-| **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect |
+| **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect — works with local paths or remote GitHub repos |
 
 ## Installation
 
@@ -40,35 +41,48 @@ import {
   getScannerHelp,
   getPersonaReference,
   getUiHelp,
+  getConformanceLevels,
+  getWcagPrinciples,
+  getSeverityLevels,
   getKnowledge,
 } from "@diegovelasquezweb/a11y-engine";
 ```
 
 #### runAudit
 
-Runs the full scan pipeline: route discovery crawler, scan, merge, and analyze. Returns a payload ready for `getFindings`.
+Runs the full scan pipeline: route discovery, scan, merge, analyze, and optional AI enrichment. Returns a payload ready for `getFindings`.
 
 ```ts
 const payload = await runAudit({
   baseUrl: "https://example.com",
   maxRoutes: 5,
   axeTags: ["wcag2a", "wcag2aa", "best-practice"],
-  onProgress: (step, status) => console.log(`${step}: ${status}`),
+  engines: { axe: true, cdp: true, pa11y: true },
+  onProgress: (step, status, extra) => console.log(`${step}: ${status}`, extra),
 });
 ```
 
-Progress steps emitted: `page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`.
+Progress steps emitted: `repo`, `page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`, `patterns`, `ai`. Steps are conditional — `repo` only fires when `repoUrl` is set, `patterns` when source scanning is active, and `ai` when AI enrichment is configured.
 
-**Common `runAudit` options**
+**`runAudit` options**
 
-| Option | Description |
-| :--- | :--- |
-| `baseUrl` | Target URL to scan |
-| `maxRoutes` | Maximum routes to scan |
-| `axeTags` | WCAG tag filters |
-| `projectDir` | Project source path for source-aware detection and pattern scanning |
-| `skipPatterns` | Disable source pattern scanning |
-| `onProgress` | Progress callback for UI updates |
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `baseUrl` | `string` | Target URL to scan |
+| `maxRoutes` | `number` | Maximum routes to discover and scan |
+| `crawlDepth` | `number` | How many link levels to follow from the starting URL |
+| `axeTags` | `string[]` | WCAG tag filters (e.g. `["wcag2a", "wcag2aa"]`) |
+| `engines` | `{ axe?, cdp?, pa11y? }` | Enable or disable individual scan engines |
+| `waitUntil` | `string` | Page load strategy: `"domcontentloaded"`, `"load"`, or `"networkidle"` |
+| `timeoutMs` | `number` | Per-page timeout in milliseconds |
+| `viewport` | `{ width, height }` | Browser viewport size |
+| `colorScheme` | `string` | Emulated color scheme: `"light"` or `"dark"` |
+| `projectDir` | `string` | Local project path for stack detection and source pattern scanning |
+| `repoUrl` | `string` | GitHub repo URL for remote stack detection and source pattern scanning |
+| `githubToken` | `string` | GitHub token for API access when using `repoUrl` |
+| `skipPatterns` | `boolean` | Disable source pattern scanning |
+| `ai` | `{ enabled?, apiKey?, githubToken?, model? }` | AI enrichment configuration |
+| `onProgress` | `(step, status, extra?) => void` | Progress callback for UI updates |
 
 See [API Reference](docs/api-reference.md) for the full `RunAuditOptions` contract.
 
@@ -119,15 +133,17 @@ These functions render final artifacts from scan payload data.
 
 ### Knowledge API
 
-These functions expose scanner help content, persona explanations, and UI copy
-so frontends or agents can render tooltips and guidance from engine-owned data.
+These functions expose scanner help content, persona explanations, conformance levels, and UI copy so frontends or agents can render tooltips and guidance from engine-owned data.
 
 | Function | Returns | Description |
 | :--- | :--- | :--- |
 | `getScannerHelp(options?)` | `{ locale, version, title, engines, options }` | Scanner option and engine help metadata |
 | `getPersonaReference(options?)` | `{ locale, version, personas }` | Persona labels, descriptions, and mapping hints |
 | `getUiHelp(options?)` | `{ locale, version, tooltips, glossary }` | Shared tooltip copy and glossary entries |
-| `getKnowledge(options?)` | `{ locale, version, scanner, personas, tooltips, glossary }` | Full documentation pack for UI or agent flows |
+| `getConformanceLevels(options?)` | `{ locale, version, conformanceLevels }` | WCAG conformance level definitions with axe tag mappings |
+| `getWcagPrinciples(options?)` | `{ locale, version, wcagPrinciples }` | The four WCAG principles with criterion prefix patterns |
+| `getSeverityLevels(options?)` | `{ locale, version, severityLevels }` | Severity level definitions with labels and ordering |
+| `getKnowledge(options?)` | Full knowledge pack | Combines all knowledge APIs into a single response for UI or agent flows |
 
 See [API Reference](docs/api-reference.md) for exact options and return types.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "WCAG 2.2 accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/src/core/github-api.mjs

@@ -104,8 +104,87 @@ export async function fetchRepoFile(repoUrl, filePath, token) {
   return null;
 }
 
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", ".next", ".nuxt",
+  "coverage", ".cache", "out", ".turbo", ".vercel", ".netlify",
+  "public", "static", "wp-includes", "wp-admin",
+]);
+
+// Common source root directories to walk when the Trees API is truncated.
+const FALLBACK_SOURCE_DIRS = [
+  "src", "app", "pages", "components", "lib", "utils", "hooks",
+];
+
+/**
+ * Filters a flat list of tree items to only matching files.
+ * @param {Array<{type: string, path: string}>} tree
+ * @param {Set<string>} extSet
+ * @returns {string[]}
+ */
+function filterTree(tree, extSet) {
+  return tree
+    .filter((item) => {
+      if (item.type !== "blob") return false;
+      const parts = item.path.split("/");
+      if (parts.some((p) => SKIP_DIRS.has(p) || p.startsWith("."))) return false;
+      const ext = item.path.slice(item.path.lastIndexOf(".")).toLowerCase();
+      return extSet.has(ext);
+    })
+    .map((item) => item.path);
+}
+
+/**
+ * Recursively lists files in a directory using the GitHub Contents API.
+ * Used as fallback when the Trees API returns a truncated response.
+ *
+ * @param {string} owner
+ * @param {string} repo
+ * @param {string} branch
+ * @param {string} dir
+ * @param {Set<string>} extSet
+ * @param {Record<string, string>} headers
+ * @param {number} depth
+ * @returns {Promise<string[]>}
+ */
+async function walkContentsApi(owner, repo, branch, dir, extSet, headers, depth = 0) {
+  if (depth > 6) return [];
+
+  try {
+    const url = `${GITHUB_API}/repos/${owner}/${repo}/contents/${dir}?ref=${branch}`;
+    const res = await fetch(url, { headers });
+    if (!res.ok) return [];
+
+    const items = await res.json();
+    if (!Array.isArray(items)) return [];
+
+    const files = [];
+    const subdirPromises = [];
+
+    for (const item of items) {
+      if (item.type === "file") {
+        const ext = item.path.slice(item.path.lastIndexOf(".")).toLowerCase();
+        if (extSet.has(ext)) files.push(item.path);
+      } else if (item.type === "dir") {
+        const name = item.name;
+        if (!SKIP_DIRS.has(name) && !name.startsWith(".")) {
+          subdirPromises.push(
+            walkContentsApi(owner, repo, branch, item.path, extSet, headers, depth + 1)
+          );
+        }
+      }
+    }
+
+    const nested = await Promise.all(subdirPromises);
+    return [...files, ...nested.flat()];
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Lists files in a repository directory using the GitHub Trees API.
+ * Falls back to the Contents API for each common source directory if
+ * the Trees API response is truncated (large monorepos).
  * Returns file paths matching the given extensions.
  *
  * @param {string} repoUrl
@@ -118,32 +197,29 @@ export async function listRepoFiles(repoUrl, extensions, token) {
   if (!parsed) return [];
 
   const { owner, repo, branch } = parsed;
+  const extSet = new Set(extensions.map((e) => e.toLowerCase()));
+  const headers = authHeaders(token);
 
   try {
     const url = `${GITHUB_API}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
-    const res = await fetch(url, { headers: authHeaders(token) });
+    const res = await fetch(url, { headers });
     if (!res.ok) return [];
 
-    const { tree } = await res.json();
-    if (!Array.isArray(tree)) return [];
-
-    const extSet = new Set(extensions.map((e) => e.toLowerCase()));
-    const skipDirs = new Set([
-      "node_modules", ".git", "dist", "build", ".next", ".nuxt",
-      "coverage", ".cache", "out", ".turbo", ".vercel", ".netlify",
-      "public", "static", "wp-includes", "wp-admin",
-    ]);
-
-    return tree
-      .filter((item) => {
-        if (item.type !== "blob") return false;
-        const path = item.path;
-        const parts = path.split("/");
-        if (parts.some((p) => skipDirs.has(p) || p.startsWith("."))) return false;
-        const ext = path.slice(path.lastIndexOf(".")).toLowerCase();
-        return extSet.has(ext);
-      })
-      .map((item) => item.path);
+    const data = await res.json();
+    if (!Array.isArray(data.tree)) return [];
+
+    if (!data.truncated) {
+      return filterTree(data.tree, extSet);
+    }
+
+    // Trees API truncated — fall back to Contents API for common source dirs
+    const results = await Promise.all(
+      FALLBACK_SOURCE_DIRS.map((dir) =>
+        walkContentsApi(owner, repo, branch, dir, extSet, headers)
+      )
+    );
+
+    return [...new Set(results.flat())];
   } catch {
     return [];
   }

package/src/enrichment/analyzer.mjs

@@ -175,9 +175,9 @@ function resolveCmsNotesKey(framework) {
 function filterNotes(notes, framework) {
   if (!notes || typeof notes !== "object") return null;
   const intelKey = resolveFrameworkNotesKey(framework);
-  if (intelKey && notes[intelKey]) return { [intelKey]: notes[intelKey] };
+  if (intelKey && notes[intelKey]) return notes[intelKey];
   const cmsKey = resolveCmsNotesKey(framework);
-  if (cmsKey && notes[cmsKey]) return { [cmsKey]: notes[cmsKey] };
+  if (cmsKey && notes[cmsKey]) return notes[cmsKey];
   return null;
 }
 

package/src/pipeline/dom-scanner.mjs

@@ -1184,6 +1184,10 @@ async function _runDomScannerInternal(args) {
 
     writeProgress("page", "running");
 
+    // Track which steps have already emitted "done" so multi-route scans
+    // don't reset progress back to "running" for routes after the first.
+    const emittedDone = new Set();
+
     for (let i = 0; i < routes.length; i += tabPages.length) {
       const batch = [];
       for (let j = 0; j < tabPages.length && i + j < routes.length; j++) {
@@ -1195,7 +1199,10 @@ async function _runDomScannerInternal(args) {
             log.info(`[${idx + 1}/${total}] Scanning: ${routePath}`);
             const targetUrl = new URL(routePath, baseUrl).toString();
 
-            writeProgress("page", "done");
+            if (!emittedDone.has("page")) {
+              writeProgress("page", "done");
+              emittedDone.add("page");
+            }
 
             let result = { url: targetUrl, violations: [], incomplete: [], passes: [], metadata: {} };
             let cdpViolations = [];
@@ -1203,7 +1210,7 @@ async function _runDomScannerInternal(args) {
 
             // Step 1: axe-core (conditional)
             if (args.engines.axe) {
-              writeProgress("axe", "running");
+              if (!emittedDone.has("axe")) writeProgress("axe", "running");
               result = await analyzeRoute(
                 tabPage,
                 targetUrl,
@@ -1216,7 +1223,10 @@ async function _runDomScannerInternal(args) {
                 args.axeTags,
               );
               const axeViolationCount = result.violations?.length || 0;
-              writeProgress("axe", "done", { found: axeViolationCount });
+              if (!emittedDone.has("axe")) {
+                writeProgress("axe", "done", { found: axeViolationCount });
+                emittedDone.add("axe");
+              }
               log.info(`axe-core: ${axeViolationCount} violation(s) found`);
             } else {
               // Navigate for CDP/pa11y even if axe is off
@@ -1228,9 +1238,12 @@ async function _runDomScannerInternal(args) {
 
             // Step 2: CDP checks (conditional)
             if (args.engines.cdp) {
-              writeProgress("cdp", "running");
+              if (!emittedDone.has("cdp")) writeProgress("cdp", "running");
               cdpViolations = await runCdpChecks(tabPage);
-              writeProgress("cdp", "done", { found: cdpViolations.length });
+              if (!emittedDone.has("cdp")) {
+                writeProgress("cdp", "done", { found: cdpViolations.length });
+                emittedDone.add("cdp");
+              }
               log.info(`CDP checks: ${cdpViolations.length} issue(s) found`);
             } else {
               log.info("CDP checks: skipped (disabled)");
@@ -1238,9 +1251,12 @@ async function _runDomScannerInternal(args) {
 
             // Step 3: pa11y (conditional)
             if (args.engines.pa11y) {
-              writeProgress("pa11y", "running");
+              if (!emittedDone.has("pa11y")) writeProgress("pa11y", "running");
               pa11yViolations = await runPa11yChecks(targetUrl, args.axeTags);
-              writeProgress("pa11y", "done", { found: pa11yViolations.length });
+              if (!emittedDone.has("pa11y")) {
+                writeProgress("pa11y", "done", { found: pa11yViolations.length });
+                emittedDone.add("pa11y");
+              }
               log.info(`pa11y: ${pa11yViolations.length} issue(s) found`);
             } else {
               log.info("pa11y: skipped (disabled)");
@@ -1248,18 +1264,21 @@ async function _runDomScannerInternal(args) {
 
             // Step 4: Merge results
             const axeViolationCount = result.violations?.length || 0;
-            writeProgress("merge", "running");
+            if (!emittedDone.has("merge")) writeProgress("merge", "running");
             const mergedViolations = mergeViolations(
               result.violations || [],
               cdpViolations,
               pa11yViolations,
             );
-            writeProgress("merge", "done", {
-              axe: axeViolationCount,
-              cdp: cdpViolations.length,
-              pa11y: pa11yViolations.length,
-              merged: mergedViolations.length,
-            });
+            if (!emittedDone.has("merge")) {
+              writeProgress("merge", "done", {
+                axe: axeViolationCount,
+                cdp: cdpViolations.length,
+                pa11y: pa11yViolations.length,
+                merged: mergedViolations.length,
+              });
+              emittedDone.add("merge");
+            }
             log.info(`Merged: ${mergedViolations.length} total unique violations (axe: ${axeViolationCount}, cdp: ${cdpViolations.length}, pa11y: ${pa11yViolations.length})`);
 
             // Screenshots for merged violations