@diegovelasquezweb/a11y-engine 0.7.1 → 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.1",
+  "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;
 }