@diegovelasquezweb/a11y-engine 0.7.1 → 0.7.3

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,37 +41,28 @@ 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`.
-
-**Common `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 |
-
-See [API Reference](docs/api-reference.md) for the full `RunAuditOptions` contract.
+See [API Reference](docs/api-reference.md) for options, progress steps, and return types.
 
 #### getFindings
 
@@ -119,15 +111,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 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 |
+| `getUiHelp(options?)` | `{ locale, version, concepts, glossary }` | Shared concept definitions and glossary entries |
+| `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/docs/api-reference.md

@@ -8,7 +8,7 @@
 
 ### `runAudit(options)`
 
-Runs route discovery, runtime scan, merge, and analyzer enrichment.
+Runs route discovery, runtime scan, merge, analyzer enrichment, and optional AI enrichment. Supports local project paths or remote GitHub repos for stack detection and source pattern scanning.
 
 `options` (`RunAuditOptions`):
 
@@ -30,10 +30,28 @@ Runs route discovery, runtime scan, merge, and analyzer enrichment.
 | `ignoreFindings` | `string[]` |
 | `framework` | `string` |
 | `projectDir` | `string` |
+| `repoUrl` | `string` |
+| `githubToken` | `string` |
 | `skipPatterns` | `boolean` |
 | `screenshotsDir` | `string` |
+| `engines` | `{ axe?: boolean; cdp?: boolean; pa11y?: boolean }` |
+| `ai` | `{ enabled?: boolean; apiKey?: string; githubToken?: string; model?: string }` |
 | `onProgress` | `(step: string, status: string, extra?: Record<string, unknown>) => void` |
 
+Progress steps emitted via `onProgress`:
+
+| Step | When |
+| :--- | :--- |
+| `page` | Always — page load |
+| `axe` | Always — axe-core scan |
+| `cdp` | Always — CDP accessibility tree check |
+| `pa11y` | Always — pa11y HTML CodeSniffer scan |
+| `merge` | Always — finding deduplication |
+| `intelligence` | Always — enrichment and WCAG mapping |
+| `repo` | When `repoUrl` is set |
+| `patterns` | When source scanning is active |
+| `ai` | When AI enrichment is configured |
+
 Returns: `Promise<ScanPayload>`
 
 ### `getFindings(input, options?)`
@@ -123,14 +141,35 @@ Returns: `PersonaReference` (`{ locale, version, personas }`)
 - `options`: `KnowledgeOptions`
   - `locale?: string`
 
-Returns: `UiHelp` (`{ locale, version, tooltips, glossary }`)
+Returns: `UiHelp` (`{ locale, version, concepts, glossary }`)
+
+### `getConformanceLevels(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `ConformanceLevelsResult` (`{ locale, version, conformanceLevels }`)
+
+### `getWcagPrinciples(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `WcagPrinciplesResult` (`{ locale, version, wcagPrinciples }`)
+
+### `getSeverityLevels(options?)`
+
+- `options`: `KnowledgeOptions`
+  - `locale?: string`
+
+Returns: `SeverityLevelsResult` (`{ locale, version, severityLevels }`)
 
 ### `getKnowledge(options?)`
 
 - `options`: `KnowledgeOptions`
   - `locale?: string`
 
-Returns: `EngineKnowledge` (`{ locale, version, scanner, personas, tooltips, glossary }`)
+Returns: `EngineKnowledge` (`{ locale, version, scanner, personas, concepts, glossary, docs, conformanceLevels, wcagPrinciples, severityLevels }`)
 
 ---
 

package/package.json

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

package/src/cli/audit.mjs

@@ -140,6 +140,9 @@ async function main() {
   const timeoutMs = getArgValue("timeout-ms") || DEFAULTS.timeoutMs;
   const axeTags = getArgValue("axe-tags");
 
+  const repoUrl = getArgValue("repo-url");
+  const githubToken = getArgValue("github-token");
+
   const sessionFile = getInternalPath("a11y-session.json");
   let projectDir = getArgValue("project-dir");
   if (projectDir) {
@@ -268,8 +271,14 @@ async function main() {
     if (framework) analyzerArgs.push("--framework", framework);
     await runScript("../enrichment/analyzer.mjs", analyzerArgs);
 
-    if (projectDir && !skipPatterns) {
-      const patternArgs = ["--project-dir", path.resolve(projectDir)];
+    if ((projectDir || repoUrl) && !skipPatterns) {
+      const patternArgs = [];
+      if (projectDir) {
+        patternArgs.push("--project-dir", path.resolve(projectDir));
+      } else {
+        patternArgs.push("--repo-url", repoUrl);
+        if (githubToken) patternArgs.push("--github-token", githubToken);
+      }
       let resolvedFramework = framework;
       if (!resolvedFramework) {
         try {

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/source-patterns/source-scanner.mjs

@@ -46,6 +46,8 @@ function parseArgs(argv) {
 
   const args = {
     projectDir: null,
+    repoUrl: null,
+    githubToken: null,
     framework: null,
     output: getInternalPath("a11y-pattern-findings.json"),
     onlyPattern: null,
@@ -56,13 +58,15 @@ function parseArgs(argv) {
     const value = argv[i + 1];
     if (!key.startsWith("--") || value === undefined) continue;
     if (key === "--project-dir") args.projectDir = value;
+    if (key === "--repo-url") args.repoUrl = value;
+    if (key === "--github-token") args.githubToken = value;
     if (key === "--framework") args.framework = value;
     if (key === "--output") args.output = value;
     if (key === "--only-pattern") args.onlyPattern = value;
     i++;
   }
 
-  if (!args.projectDir) throw new Error("Missing required --project-dir");
+  if (!args.projectDir && !args.repoUrl) throw new Error("Missing required --project-dir or --repo-url");
   return args;
 }
 
@@ -320,7 +324,7 @@ export async function scanPatternRemote(pattern, repoUrl, githubToken, framework
 /**
  * Main execution function for the pattern scanner.
  */
-function main() {
+async function main() {
   const args = parseArgs(process.argv.slice(2));
   const { patterns } = loadAssetJson(
     ASSET_PATHS.remediation.codePatterns,
@@ -339,23 +343,44 @@ function main() {
     process.exit(0);
   }
 
-  const scanDirs = resolveScanDirs(args.framework, args.projectDir);
-  log.info(`Scanning source code at: ${args.projectDir}`);
-  if (scanDirs.length > 1 || scanDirs[0] !== args.projectDir) {
-    log.info(`  Scoped to: ${scanDirs.map((d) => relative(args.projectDir, d)).join(", ")}`);
-  }
-  log.info(`Running ${activePatterns.length} pattern(s)...`);
-
   const allFindings = [];
-  for (const pattern of activePatterns) {
-    const findings = [];
-    for (const scanDir of scanDirs) {
-      findings.push(...scanPattern(pattern, scanDir, args.projectDir));
+
+  if (args.repoUrl) {
+    // Remote scan via GitHub API — no clone needed
+    log.info(`Scanning source code at: ${args.repoUrl}`);
+    log.info(`Running ${activePatterns.length} pattern(s) via GitHub API...`);
+
+    for (const pattern of activePatterns) {
+      const findings = await scanPatternRemote(
+        pattern,
+        args.repoUrl,
+        args.githubToken || null,
+        args.framework || null,
+      );
+      if (findings.length > 0) {
+        log.info(`  ${pattern.id}: ${findings.length} match(es)`);
+      }
+      allFindings.push(...findings);
     }
-    if (findings.length > 0) {
-      log.info(`  ${pattern.id}: ${findings.length} match(es)`);
+  } else {
+    // Local filesystem scan
+    const scanDirs = resolveScanDirs(args.framework, args.projectDir);
+    log.info(`Scanning source code at: ${args.projectDir}`);
+    if (scanDirs.length > 1 || scanDirs[0] !== args.projectDir) {
+      log.info(`  Scoped to: ${scanDirs.map((d) => relative(args.projectDir, d)).join(", ")}`);
+    }
+    log.info(`Running ${activePatterns.length} pattern(s)...`);
+
+    for (const pattern of activePatterns) {
+      const findings = [];
+      for (const scanDir of scanDirs) {
+        findings.push(...scanPattern(pattern, scanDir, args.projectDir));
+      }
+      if (findings.length > 0) {
+        log.info(`  ${pattern.id}: ${findings.length} match(es)`);
+      }
+      allFindings.push(...findings);
     }
-    allFindings.push(...findings);
   }
 
   const confirmed = allFindings.filter((f) => f.status === "confirmed").length;
@@ -363,7 +388,7 @@ function main() {
 
   writeJson(args.output, {
     generated_at: new Date().toISOString(),
-    project_dir: args.projectDir,
+    project_dir: args.repoUrl || args.projectDir,
     findings: allFindings,
     summary: {
       total: allFindings.length,
@@ -378,10 +403,8 @@ function main() {
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  try {
-    main();
-  } catch (error) {
+  main().catch((error) => {
     log.error(error.message);
     process.exit(1);
-  }
+  });
 }