@diegovelasquezweb/a11y-engine 0.6.4 → 0.6.6

package/assets/knowledge/knowledge.mjs

@@ -107,7 +107,7 @@ export default {
         {
           id: "A",
           label: "Level A",
-          badge: "Minimum",
+          tag: "Minimum",
           description: "The baseline: essential requirements that remove the most severe barriers.",
           shortDescription: "Minimum baseline",
           hint: "Failing Level A means some users cannot access the content at all.",
@@ -116,7 +116,7 @@ export default {
         {
           id: "AA",
           label: "Level AA",
-          badge: "Standard",
+          tag: "Standard",
           description: "The recommended target for most websites — required by most accessibility laws.",
           shortDescription: "Recommended for most websites",
           hint: "Referenced by ADA, Section 508, EN 301 549, and EAA.",
@@ -125,7 +125,7 @@ export default {
         {
           id: "AAA",
           label: "Level AAA",
-          badge: "Enhanced",
+          tag: "Enhanced",
           description: "The highest conformance level — not required but beneficial for specialized audiences.",
           shortDescription: "Strictest — not required by most regulations",
           hint: "Full AAA conformance is not recommended as a general policy for entire sites.",
@@ -251,21 +251,21 @@ export default {
                   {
                     id: "wcag-2-0",
                     title: "WCAG 2.0",
-                    badge: "2008",
+                    tag: "2008",
                     summary: "The original W3C recommendation that established the foundation for web accessibility.",
                     body: "Introduced the four principles (Perceivable, Operable, Understandable, Robust) and three conformance levels (A, AA, AAA). Covers core requirements like text alternatives, keyboard access, color contrast, and form labels. Still widely referenced in legal frameworks worldwide.",
                   },
                   {
                     id: "wcag-2-1",
                     title: "WCAG 2.1",
-                    badge: "2018",
+                    tag: "2018",
                     summary: "Extended 2.0 with 17 new success criteria for mobile, low vision, and cognitive disabilities.",
                     body: "Added criteria for touch targets (2.5.5), text spacing (1.4.12), content reflow (1.4.10), orientation (1.3.4), and input purpose (1.3.5). Required by the European Accessibility Act (EAA) and referenced in updated ADA guidance. All 2.0 criteria remain \u2014 2.1 is a superset.",
                   },
                   {
                     id: "wcag-2-2",
                     title: "WCAG 2.2",
-                    badge: "2023",
+                    tag: "2023",
                     summary: "The latest version, adding 9 new criteria focused on cognitive accessibility and consistent help.",
                     body: "Key additions include consistent help (3.2.6), accessible authentication (3.3.8), dragging movements (2.5.7), and focus appearance (2.4.11/2.4.12). Removed criterion 4.1.1 (Parsing) as it\u2019s now handled by modern browsers. Supersedes both 2.0 and 2.1 \u2014 all prior criteria are included.",
                   },
@@ -278,21 +278,21 @@ export default {
                   {
                     id: "level-a",
                     title: "Level A",
-                    badge: "Minimum",
+                    tag: "Minimum",
                     summary: "The baseline: essential requirements that remove the most severe barriers.",
                     body: "Covers fundamentals like non-text content alternatives (1.1.1), keyboard operability (2.1.1), page titles (2.4.2), and language of the page (3.1.1). Failing Level A means some users cannot access the content at all. Every site should meet Level A at minimum.",
                   },
                   {
                     id: "level-aa",
                     title: "Level AA",
-                    badge: "Standard",
+                    tag: "Standard",
                     summary: "The recommended target for most websites \u2014 required by most accessibility laws.",
                     body: "Includes all Level A criteria plus requirements for color contrast (1.4.3 \u2014 4.5:1 ratio), resize text (1.4.4), focus visible (2.4.7), error suggestion (3.3.3), and consistent navigation (3.2.3). Referenced by ADA, Section 508, EN 301 549, and EAA. This is the standard the scanner defaults to.",
                   },
                   {
                     id: "level-aaa",
                     title: "Level AAA",
-                    badge: "Enhanced",
+                    tag: "Enhanced",
                     summary: "The highest conformance level \u2014 not required but beneficial for specialized audiences.",
                     body: "Adds stricter contrast (1.4.6 \u2014 7:1 ratio), sign language for audio (1.2.6), extended audio description (1.2.7), and reading level (3.1.5). Full AAA conformance is not recommended as a general policy because some criteria cannot be satisfied for all content types. Useful for targeted sections like education or government services.",
                   },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.6.4",
-  "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
+  "version": "0.6.6",
+  "description": "WCAG 2.2 accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/ai/claude.mjs

@@ -0,0 +1,249 @@
+/**
+ * @file claude.mjs
+ * @description Claude AI enrichment layer for the a11y-engine.
+ * Enhances Critical/Serious findings with context-aware fix suggestions,
+ * leveraging repository source code when available via GitHub API.
+ *
+ * This module is a passthrough when:
+ * - options.enabled is false
+ * - no apiKey is provided
+ *
+ * Requires: ANTHROPIC_API_KEY in options.apiKey
+ * Optional: githubToken for reading private repo files
+ */
+
+const ANTHROPIC_API = "https://api.anthropic.com/v1/messages";
+const DEFAULT_MODEL = "claude-sonnet-4-5";
+const MAX_AI_FINDINGS = 20; // cap to control cost
+
+/**
+ * @typedef {import('../index.d.mts').EnrichedFinding} EnrichedFinding
+ */
+
+/**
+ * Builds the system prompt for the AI enrichment task.
+ * @param {object} context
+ * @returns {string}
+ */
+function buildSystemPrompt(context) {
+  const { framework, cms, uiLibraries } = context.stack || {};
+
+  let stackInfo = "";
+  if (framework) stackInfo += `Framework: ${framework}\n`;
+  if (cms) stackInfo += `CMS: ${cms}\n`;
+  if (uiLibraries?.length) stackInfo += `UI Libraries: ${uiLibraries.join(", ")}\n`;
+
+  return `You are an expert web accessibility engineer specializing in WCAG 2.2 AA remediation.
+
+Your task is to improve the fix guidance for accessibility findings from an automated scan.
+${stackInfo ? `\nProject context:\n${stackInfo}` : ""}
+For each finding you receive, provide:
+1. A clear, specific fix description (1-2 sentences, actionable, no jargon)
+2. Ready-to-use fix code in the correct language for the stack${context.hasSourceCode ? "\n3. The exact line/component to change if you can identify it from the source code" : ""}
+
+Rules:
+- Keep fix code minimal and focused — only the changed element, not the whole file
+- Use the detected framework syntax (JSX for React/Next.js, template syntax for Vue, etc.)
+- Do not change component logic, only accessibility attributes
+- If the fix requires multiple changes, show the most important one
+- Respond in JSON only — no markdown, no explanation outside the JSON structure`;
+}
+
+/**
+ * Builds the user message for a batch of findings.
+ * @param {EnrichedFinding[]} findings
+ * @param {Record<string, string>} sourceFiles - map of filePath -> content
+ * @returns {string}
+ */
+function buildUserMessage(findings, sourceFiles) {
+  const items = findings.map((f, i) => ({
+    index: i,
+    ruleId: f.ruleId,
+    severity: f.severity,
+    wcag: f.wcag,
+    title: f.title,
+    selector: f.primarySelector || f.selector,
+    actual: f.actual,
+    currentFix: f.fixDescription,
+    currentCode: f.fixCode,
+    fileSearchPattern: f.fileSearchPattern || null,
+  }));
+
+  let message = `Improve the fix guidance for these ${findings.length} accessibility finding(s).\n\n`;
+  message += `FINDINGS:\n${JSON.stringify(items, null, 2)}\n`;
+
+  if (Object.keys(sourceFiles).length > 0) {
+    message += `\nSOURCE FILES (for context):\n`;
+    for (const [filePath, content] of Object.entries(sourceFiles)) {
+      const truncated = content.length > 4000 ? content.slice(0, 4000) + "\n... (truncated)" : content;
+      message += `\n--- ${filePath} ---\n${truncated}\n`;
+    }
+  }
+
+  message += `\nRespond with a JSON array where each item has:
+{
+  "index": <number>,
+  "fixDescription": "<improved description>",
+  "fixCode": "<improved code snippet>",
+  "fixCodeLang": "<language: html|jsx|tsx|vue|svelte|astro|liquid|php|css>"
+}`;
+
+  return message;
+}
+
+/**
+ * Calls the Claude API with the given messages.
+ * @param {string} apiKey
+ * @param {string} model
+ * @param {string} systemPrompt
+ * @param {string} userMessage
+ * @returns {Promise<string>}
+ */
+async function callClaude(apiKey, model, systemPrompt, userMessage) {
+  const res = await fetch(ANTHROPIC_API, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages: [{ role: "user", content: userMessage }],
+    }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Claude API error ${res.status}: ${text}`);
+  }
+
+  const data = await res.json();
+  return data.content?.[0]?.text ?? "";
+}
+
+/**
+ * Tries to fetch source files for findings that have a fileSearchPattern.
+ * @param {EnrichedFinding[]} findings
+ * @param {string} repoUrl
+ * @param {string|undefined} githubToken
+ * @returns {Promise<Record<string, string>>}
+ */
+async function fetchSourceFilesForFindings(findings, repoUrl, githubToken) {
+  const sourceFiles = {};
+  if (!repoUrl) return sourceFiles;
+
+  const { fetchRepoFile, listRepoFiles, parseRepoUrl } = await import("../core/github-api.mjs");
+  if (!parseRepoUrl(repoUrl)) return sourceFiles;
+
+  const patterns = new Set(
+    findings
+      .filter((f) => f.fileSearchPattern)
+      .map((f) => f.fileSearchPattern)
+  );
+
+  for (const pattern of patterns) {
+    try {
+      // Extract extension from pattern (e.g. "src/components/*.tsx" -> ".tsx")
+      const extMatch = pattern.match(/\*\.(\w+)$/);
+      if (!extMatch) continue;
+      const ext = `.${extMatch[1]}`;
+
+      const files = await listRepoFiles(repoUrl, [ext], githubToken);
+      // Pick up to 3 most relevant files per pattern
+      const relevant = files.slice(0, 3);
+      for (const filePath of relevant) {
+        if (!sourceFiles[filePath]) {
+          const content = await fetchRepoFile(repoUrl, filePath, githubToken);
+          if (content) sourceFiles[filePath] = content;
+        }
+      }
+    } catch {
+      // non-fatal
+    }
+  }
+
+  return sourceFiles;
+}
+
+/**
+ * Enriches Critical and Serious findings using Claude AI.
+ * Returns findings with improved fixDescription, fixCode, and fixCodeLang.
+ * Passthrough if AI is disabled or no apiKey is provided.
+ *
+ * @param {EnrichedFinding[]} findings
+ * @param {{
+ *   stack?: { framework?: string, cms?: string, uiLibraries?: string[] },
+ *   repoUrl?: string,
+ * }} context
+ * @param {{
+ *   enabled?: boolean,
+ *   apiKey?: string,
+ *   githubToken?: string,
+ *   model?: string,
+ * }} options
+ * @returns {Promise<EnrichedFinding[]>}
+ */
+export async function enrichWithAI(findings, context = {}, options = {}) {
+  const enabled = options.enabled !== false && !!options.apiKey;
+  if (!enabled) return findings;
+
+  const model = options.model || DEFAULT_MODEL;
+
+  // Only enrich Critical and Serious findings, cap total
+  const targets = findings
+    .filter((f) => f.severity === "Critical" || f.severity === "Serious")
+    .slice(0, MAX_AI_FINDINGS);
+
+  if (targets.length === 0) return findings;
+
+  try {
+    // Fetch source files if repo is available
+    const sourceFiles = context.repoUrl
+      ? await fetchSourceFilesForFindings(targets, context.repoUrl, options.githubToken)
+      : {};
+
+    const systemPrompt = buildSystemPrompt({
+      stack: context.stack,
+      hasSourceCode: Object.keys(sourceFiles).length > 0,
+    });
+    const userMessage = buildUserMessage(targets, sourceFiles);
+
+    const responseText = await callClaude(options.apiKey, model, systemPrompt, userMessage);
+
+    // Parse Claude's JSON response
+    let improvements = [];
+    try {
+      const jsonMatch = responseText.match(/\[[\s\S]*\]/);
+      if (jsonMatch) improvements = JSON.parse(jsonMatch[0]);
+    } catch {
+      console.warn("[a11y-engine] Could not parse Claude response as JSON, skipping AI enrichment");
+      return findings;
+    }
+
+    // Build a map by target index for fast lookup
+    const targetIds = new Set(targets.map((f) => f.id));
+    const targetList = findings.filter((f) => targetIds.has(f.id));
+    const improvementMap = new Map(improvements.map((imp) => [imp.index, imp]));
+
+    // Apply improvements to findings
+    return findings.map((finding) => {
+      const targetIdx = targetList.findIndex((t) => t.id === finding.id);
+      if (targetIdx === -1) return finding;
+      const imp = improvementMap.get(targetIdx);
+      if (!imp) return finding;
+
+      return {
+        ...finding,
+        fixDescription: imp.fixDescription || finding.fixDescription,
+        fixCode: imp.fixCode || finding.fixCode,
+        fixCodeLang: imp.fixCodeLang || finding.fixCodeLang,
+      };
+    });
+  } catch (err) {
+    console.warn(`[a11y-engine] AI enrichment failed (non-fatal): ${err.message}`);
+    return findings;
+  }
+}

package/src/core/github-api.mjs

@@ -0,0 +1,150 @@
+/**
+ * @file github-api.mjs
+ * @description Minimal GitHub API client for reading repository content without cloning.
+ * Used by the engine to fetch package.json for stack detection and source files for
+ * pattern scanning and AI enrichment.
+ */
+
+const GITHUB_API = "https://api.github.com";
+const GITHUB_RAW = "https://raw.githubusercontent.com";
+
+/**
+ * Parses a GitHub URL into owner and repo components.
+ * @param {string} repoUrl
+ * @returns {{ owner: string, repo: string, branch: string } | null}
+ */
+export function parseRepoUrl(repoUrl) {
+  try {
+    const url = new URL(repoUrl);
+    if (url.hostname !== "github.com") return null;
+    const parts = url.pathname.replace(/^\//, "").replace(/\.git$/, "").split("/");
+    if (parts.length < 2) return null;
+    const [owner, repo, , branch] = parts;
+    return { owner, repo, branch: branch || "main" };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Builds Authorization header if token is present.
+ * @param {string|undefined} token
+ * @returns {Record<string, string>}
+ */
+function authHeaders(token) {
+  const headers = {
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+  };
+  if (token) headers["Authorization"] = `Bearer ${token}`;
+  return headers;
+}
+
+/**
+ * Fetches and parses package.json from a GitHub repository.
+ * Tries the default branch first, then falls back to 'master'.
+ *
+ * @param {string} repoUrl
+ * @param {string|undefined} token
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+export async function fetchPackageJson(repoUrl, token) {
+  const parsed = parseRepoUrl(repoUrl);
+  if (!parsed) return null;
+
+  const { owner, repo, branch } = parsed;
+  const branches = [branch, branch === "main" ? "master" : "main"];
+
+  for (const b of branches) {
+    try {
+      const url = `${GITHUB_RAW}/${owner}/${repo}/${b}/package.json`;
+      const res = await fetch(url, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+      });
+      if (res.ok) {
+        const text = await res.text();
+        return JSON.parse(text);
+      }
+    } catch {
+      // try next branch
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Fetches a file from a GitHub repository.
+ * Returns the raw file content as a string.
+ *
+ * @param {string} repoUrl
+ * @param {string} filePath - Relative path within the repo (e.g. "src/components/Header.tsx")
+ * @param {string|undefined} token
+ * @returns {Promise<string | null>}
+ */
+export async function fetchRepoFile(repoUrl, filePath, token) {
+  const parsed = parseRepoUrl(repoUrl);
+  if (!parsed) return null;
+
+  const { owner, repo, branch } = parsed;
+  const branches = [branch, branch === "main" ? "master" : "main"];
+
+  for (const b of branches) {
+    try {
+      const url = `${GITHUB_RAW}/${owner}/${repo}/${b}/${filePath}`;
+      const res = await fetch(url, {
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+      });
+      if (res.ok) return await res.text();
+    } catch {
+      // try next branch
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Lists files in a repository directory using the GitHub Trees API.
+ * Returns file paths matching the given extensions.
+ *
+ * @param {string} repoUrl
+ * @param {string[]} extensions - e.g. [".tsx", ".jsx", ".html"]
+ * @param {string|undefined} token
+ * @returns {Promise<string[]>}
+ */
+export async function listRepoFiles(repoUrl, extensions, token) {
+  const parsed = parseRepoUrl(repoUrl);
+  if (!parsed) return [];
+
+  const { owner, repo, branch } = parsed;
+
+  try {
+    const url = `${GITHUB_API}/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`;
+    const res = await fetch(url, { headers: authHeaders(token) });
+    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);
+  } catch {
+    return [];
+  }
+}

package/src/enrichment/analyzer.mjs

@@ -751,7 +751,7 @@ function computeTestingMethodology(payload) {
       "pa11y (HTML CodeSniffer via Puppeteer)",
       "Playwright + Chromium",
     ],
-    compliance_target: "WCAG 2.2 AA",
+    compliance_target: "WCAG 2.2",
     pages_scanned: scanned,
     pages_errored: errored,
     framework_detected: payload.projectContext?.framework || "Not detected",

package/src/index.d.mts

@@ -1,6 +1,6 @@
-// ---------------------------------------------------------------------------
-// Core types
-// ---------------------------------------------------------------------------
+
+
+
 
 export interface Finding {
   id: string;
@@ -135,9 +135,9 @@ export interface AuditSummary {
   totalFindings: number;
 }
 
-// ---------------------------------------------------------------------------
-// Report types
-// ---------------------------------------------------------------------------
+
+
+
 
 export interface ScanPayload {
   findings: Finding[] | Record<string, unknown>[];
@@ -209,9 +209,9 @@ export interface SourcePatternOptions {
   onlyPattern?: string;
 }
 
-// ---------------------------------------------------------------------------
-// Knowledge APIs
-// ---------------------------------------------------------------------------
+
+
+
 
 export interface ScannerEngineHelp {
   id: "axe" | "cdp" | "pa11y" | string;
@@ -222,25 +222,53 @@ export interface ScannerEngineHelp {
   defaultEnabled: boolean;
 }
 
-export interface EnumOptionValue {
-  value: string;
-  label: string;
-  description?: string;
-}
-
 export interface ScannerOptionHelp {
   id: string;
   label: string;
   description: string;
   defaultValue: unknown;
   type: string;
-  allowedValues?: unknown[] | EnumOptionValue[];
+  allowedValues?: unknown[];
+}
+
+export interface GlossaryEntry {
+  term: string;
+  definition: string;
+}
+
+export interface ConceptEntry {
+  title: string;
+  body: string;
+  context?: string;
+}
+
+export interface PersonaReferenceItem {
+  id: string;
+  icon: string;
+  label: string;
+  description: string;
+  keywords: string[];
+  mappedRules: string[];
+}
+
+export interface PersonaReference {
+  locale: string;
+  version: string;
+  personas: PersonaReferenceItem[];
+}
+
+export interface ScannerHelp {
+  locale: string;
+  version: string;
+  title: string;
+  engines: ScannerEngineHelp[];
+  options: ScannerOptionHelp[];
 }
 
 export interface ConformanceLevel {
   id: "A" | "AA" | "AAA";
   label: string;
-  badge: string;
+  tag: string;
   description: string;
   shortDescription: string;
   hint: string;
@@ -267,7 +295,7 @@ export interface DocArticle {
   id: string;
   title: string;
   icon?: string;
-  badge?: string;
+  tag?: string;
   summary: string;
   body: string;
 }
@@ -335,9 +363,9 @@ export interface KnowledgeOptions {
   locale?: string;
 }
 
-// ---------------------------------------------------------------------------
-// Engine selection
-// ---------------------------------------------------------------------------
+
+
+
 
 export interface EngineSelection {
   axe?: boolean;
@@ -345,9 +373,9 @@ export interface EngineSelection {
   pa11y?: boolean;
 }
 
-// ---------------------------------------------------------------------------
-// Audit options
-// ---------------------------------------------------------------------------
+
+
+
 
 export interface RunAuditOptions {
   baseUrl: string;
@@ -366,23 +394,33 @@ export interface RunAuditOptions {
   ignoreFindings?: string[];
   framework?: string;
   projectDir?: string;
+  repoUrl?: string;
+  githubToken?: string;
   skipPatterns?: boolean;
   screenshotsDir?: string;
   engines?: EngineSelection;
+  ai?: AiOptions;
   onProgress?: (step: string, status: string, extra?: Record<string, unknown>) => void;
 }
 
-// ---------------------------------------------------------------------------
-// Enrichment options
-// ---------------------------------------------------------------------------
+export interface AiOptions {
+  enabled?: boolean;
+  apiKey?: string;
+  githubToken?: string;
+  model?: string;
+}
+
+
+
+
 
 export interface EnrichmentOptions {
   screenshotUrlBuilder?: (rawPath: string) => string;
 }
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
+
+
+
 
 export function runAudit(options: RunAuditOptions): Promise<ScanPayload>;
 

package/src/index.mjs

@@ -188,6 +188,11 @@ export function getFindings(input, options = {}) {
   const { screenshotUrlBuilder = null } = options;
   const rules = getIntelligence().rules || {};
 
+  // If AI enrichment ran, return those findings directly (already normalized + enriched)
+  if (input?.ai_enriched_findings?.length > 0 && !screenshotUrlBuilder) {
+    return input.ai_enriched_findings;
+  }
+
   const rawFindings = input?.findings || [];
 
   // Normalize raw findings
@@ -652,6 +657,20 @@ export async function runAudit(options) {
     pa11y: options.engines?.pa11y !== false,
   };
 
+  // Fetch remote package.json via GitHub API if repoUrl is provided
+  let remotePackageJson = null;
+  if (options.repoUrl && !options.projectDir) {
+    try {
+      const { fetchPackageJson } = await import("./core/github-api.mjs");
+      remotePackageJson = await fetchPackageJson(options.repoUrl, options.githubToken);
+      if (remotePackageJson) {
+        console.info("[a11y-engine] Fetched package.json from GitHub repo");
+      }
+    } catch (err) {
+      console.warn(`[a11y-engine] Could not fetch package.json from repo (non-fatal): ${err.message}`);
+    }
+  }
+
   // Step 1: DOM scan (selected engines)
   if (onProgress) onProgress("page", "running");
 
@@ -672,6 +691,7 @@ export async function runAudit(options) {
       excludeSelectors: options.excludeSelectors,
       screenshotsDir: options.screenshotsDir,
       projectDir: options.projectDir,
+      remotePackageJson,
       engines,
     },
     { onProgress },
@@ -685,10 +705,10 @@ export async function runAudit(options) {
     framework: options.framework,
   });
 
-  // Step 3: Source patterns (optional)
-  if (options.projectDir && !options.skipPatterns) {
+  // Step 3: Source patterns (optional) — works with local projectDir or remote repoUrl
+  const hasSourceContext = (options.projectDir || options.repoUrl) && !options.skipPatterns;
+  if (hasSourceContext) {
     try {
-      const { resolveScanDirs, scanPattern } = await import("./source-patterns/source-scanner.mjs");
       const { patterns } = loadAssetJson(ASSET_PATHS.remediation.codePatterns, "code-patterns.json");
 
       let resolvedFramework = options.framework;
@@ -696,18 +716,35 @@ export async function runAudit(options) {
         resolvedFramework = findingsPayload.metadata.projectContext.framework;
       }
 
-      const scanDirs = resolveScanDirs(resolvedFramework || null, options.projectDir);
-      const allPatternFindings = [];
-      for (const pattern of patterns) {
-        for (const scanDir of scanDirs) {
-          allPatternFindings.push(...scanPattern(pattern, scanDir, options.projectDir));
+      let allPatternFindings = [];
+
+      if (options.projectDir) {
+        // Local filesystem scan
+        const { resolveScanDirs, scanPattern } = await import("./source-patterns/source-scanner.mjs");
+        const scanDirs = resolveScanDirs(resolvedFramework || null, options.projectDir);
+        for (const pattern of patterns) {
+          for (const scanDir of scanDirs) {
+            allPatternFindings.push(...scanPattern(pattern, scanDir, options.projectDir));
+          }
+        }
+      } else if (options.repoUrl) {
+        // Remote GitHub API scan
+        const { scanPatternRemote } = await import("./source-patterns/source-scanner.mjs");
+        for (const pattern of patterns) {
+          const remoteFindings = await scanPatternRemote(
+            pattern,
+            options.repoUrl,
+            options.githubToken,
+            resolvedFramework || null,
+          );
+          allPatternFindings.push(...remoteFindings);
         }
       }
 
       if (allPatternFindings.length > 0) {
         findingsPayload.patternFindings = {
           generated_at: new Date().toISOString(),
-          project_dir: options.projectDir,
+          project_dir: options.projectDir || options.repoUrl,
           findings: allPatternFindings,
           summary: {
             total: allPatternFindings.length,
@@ -725,6 +762,43 @@ export async function runAudit(options) {
 
   if (onProgress) onProgress("intelligence", "done");
 
+  // Step 4: AI enrichment (optional) — requires ANTHROPIC_API_KEY
+  const aiOptions = options.ai || {};
+  const aiEnabled = aiOptions.enabled !== false && !!aiOptions.apiKey;
+  if (aiEnabled) {
+    try {
+      if (onProgress) onProgress("ai", "running");
+      const { enrichWithAI } = await import("./ai/claude.mjs");
+
+      const projectContext = findingsPayload.metadata?.projectContext || {};
+      const rawFindings = getFindings(findingsPayload);
+
+      const enrichedFindings = await enrichWithAI(
+        rawFindings,
+        {
+          stack: {
+            framework: projectContext.framework || null,
+            cms: projectContext.cms || null,
+            uiLibraries: projectContext.uiLibraries || [],
+          },
+          repoUrl: options.repoUrl,
+        },
+        {
+          enabled: true,
+          apiKey: aiOptions.apiKey,
+          githubToken: aiOptions.githubToken || options.githubToken,
+          model: aiOptions.model,
+        }
+      );
+
+      // Store enriched findings back into the payload
+      findingsPayload.ai_enriched_findings = enrichedFindings;
+      if (onProgress) onProgress("ai", "done");
+    } catch (err) {
+      console.warn(`[a11y-engine] AI step failed (non-fatal): ${err.message}`);
+    }
+  }
+
   // Attach active engines to metadata so consumers know which ran
   findingsPayload.metadata = findingsPayload.metadata || {};
   findingsPayload.metadata.engines = engines;
@@ -1029,7 +1103,7 @@ export async function getHTMLReport(payload, options = {}) {
       </div>
       <div class="bg-white rounded-xl p-4 border border-slate-200 shadow-sm">
         <div class="text-3xl font-black ${wcagStatus === 'Pass' ? 'text-emerald-600' : 'text-rose-600'}">${wcagStatus}</div>
-        <div class="text-xs font-bold text-slate-500 uppercase">WCAG 2.2 AA</div>
+        <div class="text-xs font-bold text-slate-500 uppercase">WCAG 2.2</div>
       </div>
       <div class="bg-white rounded-xl p-4 border border-slate-200 shadow-sm">
         <div class="text-3xl font-black">${Object.keys(pageGroups).length}</div>

package/src/pipeline/dom-scanner.mjs

@@ -341,16 +341,62 @@ export async function discoverRoutes(page, baseUrl, maxRoutes, crawlDepth = 2) {
   return [...routes].slice(0, maxRoutes);
 }
 
+/**
+ * Extracts framework and UI library info from a parsed package.json object.
+ * Used both for local file reads and remote GitHub API reads.
+ * @param {Record<string, unknown>} pkg
+ * @returns {{ framework: string|null, uiLibraries: string[] }}
+ */
+function detectFromPackageJson(pkg) {
+  const uiLibraries = [];
+  let pkgFramework = null;
+
+  const allDeps = Object.keys({
+    ...(pkg.dependencies || {}),
+    ...(pkg.devDependencies || {}),
+  });
+
+  for (const [dep, fw] of STACK_DETECTION.frameworkPackageDetectors) {
+    if (allDeps.some((d) => d === dep || d.startsWith(`${dep}/`))) {
+      pkgFramework = fw;
+      break;
+    }
+  }
+  for (const [prefix, name] of STACK_DETECTION.uiLibraryPackageDetectors) {
+    if (allDeps.some((d) => d === prefix || d.startsWith(`${prefix}/`))) {
+      uiLibraries.push(name);
+    }
+  }
+
+  return { framework: pkgFramework, uiLibraries };
+}
+
 /**
  * Detects the web framework and UI libraries used by analyzing package.json and file structure.
+ * Accepts either a local project directory path or a pre-parsed package.json object
+ * (useful when the package.json was fetched remotely via GitHub API).
+ *
  * @param {string|null} [explicitProjectDir=null] - Explicit project directory. Falls back to env/cwd.
+ * @param {Record<string, unknown>|null} [remotePackageJson=null] - Pre-parsed package.json from GitHub API.
  * @returns {Object} An object containing detected framework and UI libraries.
  */
-function detectProjectContext(explicitProjectDir = null) {
+function detectProjectContext(explicitProjectDir = null, remotePackageJson = null) {
   const uiLibraries = [];
   let pkgFramework = null;
   let fileFramework = null;
 
+  // If a remote package.json was provided (from GitHub API), use it directly
+  if (remotePackageJson) {
+    const result = detectFromPackageJson(remotePackageJson);
+    if (result.framework) {
+      log.info(`Detected framework: ${result.framework} (from remote package.json)`);
+    }
+    if (result.uiLibraries.length) {
+      log.info(`Detected UI libraries: ${result.uiLibraries.join(", ")}`);
+    }
+    return result;
+  }
+
   const projectDir = explicitProjectDir || process.env.A11Y_PROJECT_DIR || null;
   if (!projectDir) {
     return { framework: null, uiLibraries: [] };
@@ -360,21 +406,9 @@ function detectProjectContext(explicitProjectDir = null) {
     const pkgPath = path.join(projectDir, "package.json");
     if (fs.existsSync(pkgPath)) {
       const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-      const allDeps = Object.keys({
-        ...(pkg.dependencies || {}),
-        ...(pkg.devDependencies || {}),
-      });
-      for (const [dep, fw] of STACK_DETECTION.frameworkPackageDetectors) {
-        if (allDeps.some((d) => d === dep || d.startsWith(`${dep}/`))) {
-          pkgFramework = fw;
-          break;
-        }
-      }
-      for (const [prefix, name] of STACK_DETECTION.uiLibraryPackageDetectors) {
-        if (allDeps.some((d) => d === prefix || d.startsWith(`${prefix}/`))) {
-          uiLibraries.push(name);
-        }
-      }
+      const result = detectFromPackageJson(pkg);
+      pkgFramework = result.framework;
+      uiLibraries.push(...result.uiLibraries);
     }
   } catch { /* package.json unreadable */ }
 
@@ -951,6 +985,7 @@ export async function runDomScanner(options = {}, callbacks = {}) {
     viewport: options.viewport || null,
     axeTags: options.axeTags || null,
     projectDir: options.projectDir || null,
+    remotePackageJson: options.remotePackageJson || null,
     engines: {
       axe: options.engines?.axe !== false,
       cdp: options.engines?.cdp !== false,
@@ -1002,8 +1037,8 @@ async function _runDomScannerInternal(args) {
       timeout: args.timeoutMs,
     });
 
-    // 1. File-system / package.json detection (works when projectDir is available)
-    const repoCtx = detectProjectContext(args.projectDir || null);
+    // 1. File-system / package.json detection (local projectDir) or remote package.json
+    const repoCtx = detectProjectContext(args.projectDir || null, args.remotePackageJson || null);
 
     // 2. DOM/runtime detection (always works for any remote URL)
     let domCtx = { framework: null, cms: null, uiLibraries: [] };

package/src/reports/checklist.mjs

@@ -152,7 +152,7 @@ function buildHtml(args) {
     </div>
 
     <footer class="mt-12 py-6 border-t border-slate-200 text-center">
-      <p class="text-slate-600 text-sm font-medium">Generated by <a href="https://github.com/diegovelasquezweb/a11y" target="_blank" class="text-slate-700 hover:text-amber-700 font-semibold transition-colors">a11y</a> &bull; <span class="text-slate-700">WCAG 2.2 AA</span></p>
+      <p class="text-slate-600 text-sm font-medium">Generated by <a href="https://github.com/diegovelasquezweb/a11y" target="_blank" class="text-slate-700 hover:text-amber-700 font-semibold transition-colors">a11y</a> &bull; <span class="text-slate-700">WCAG 2.2</span></p>
     </footer>
 
   </main>

package/src/reports/renderers/md.mjs

@@ -564,7 +564,7 @@ ${rows.join("\n")}
   const sourceBoundariesSection = buildSourceBoundariesSection(framework);
 
   return (
-      `# Accessibility Remediation Guide — WCAG 2.2 AA
+      `# Accessibility Remediation Guide — WCAG 2.2
 > **Base URL:** ${args.baseUrl || "N/A"}
 
 | Severity | Count |

package/src/source-patterns/source-scanner.mjs

@@ -230,6 +230,93 @@ export function scanPattern(pattern, scanDir, projectDir = scanDir) {
   return findings;
 }
 
+/**
+ * Scans files in a remote GitHub repository for a pattern.
+ * Functionally equivalent to scanPattern but reads files via GitHub API.
+ *
+ * @param {Object} pattern
+ * @param {string} repoUrl
+ * @param {string|undefined} githubToken
+ * @param {string|null} framework
+ * @returns {Promise<Object[]>}
+ */
+export async function scanPatternRemote(pattern, repoUrl, githubToken, framework = null) {
+  const { fetchRepoFile, listRepoFiles, parseRepoUrl } = await import("../core/github-api.mjs");
+  const parsed = parseRepoUrl(repoUrl);
+  if (!parsed) return [];
+
+  const extensions = [...parseExtensions(pattern.globs)];
+  if (extensions.length === 0) return [];
+
+  const allFiles = await listRepoFiles(repoUrl, extensions, githubToken);
+
+  // Scope to framework boundaries if known
+  const boundaries = framework ? SOURCE_BOUNDARIES?.[framework] : null;
+  let scopedFiles = allFiles;
+  if (boundaries) {
+    const allGlobs = [boundaries.components, boundaries.styles]
+      .filter(Boolean)
+      .flatMap((g) => g.split(",").map((s) => s.trim()));
+
+    const prefixes = new Set();
+    for (const glob of allGlobs) {
+      const prefix = glob.split(/[*?{]/)[0].replace(/\/$/, "");
+      if (prefix) prefixes.add(prefix);
+    }
+
+    if (prefixes.size > 0) {
+      scopedFiles = allFiles.filter((f) =>
+        [...prefixes].some((p) => f.startsWith(p))
+      );
+      if (scopedFiles.length === 0) scopedFiles = allFiles; // fallback
+    }
+  }
+
+  const regex = new RegExp(pattern.regex, "gi");
+  const findings = [];
+
+  for (const filePath of scopedFiles) {
+    const content = await fetchRepoFile(repoUrl, filePath, githubToken);
+    if (!content) continue;
+
+    const lines = content.split("\n");
+
+    for (let i = 0; i < lines.length; i++) {
+      regex.lastIndex = 0;
+      if (!regex.test(lines[i])) continue;
+
+      const contextStart = Math.max(0, i - 3);
+      const contextEnd = Math.min(lines.length - 1, i + 3);
+      const context = lines
+        .slice(contextStart, contextEnd + 1)
+        .map((l, idx) => `${contextStart + idx + 1}  ${l}`)
+        .join("\n");
+
+      const confirmed = isConfirmedByContext(pattern, lines, i);
+
+      findings.push({
+        id: makeFindingId(pattern.id, filePath, i + 1),
+        pattern_id: pattern.id,
+        title: pattern.title,
+        severity: pattern.severity,
+        wcag: pattern.wcag,
+        wcag_criterion: pattern.wcag_criterion,
+        wcag_level: pattern.wcag_level,
+        type: pattern.type,
+        fix_description: pattern.fix_description ?? null,
+        status: confirmed ? "confirmed" : "potential",
+        file: filePath,
+        line: i + 1,
+        match: lines[i].trim(),
+        context,
+        source: "code-pattern",
+      });
+    }
+  }
+
+  return findings;
+}
+
 /**
  * Main execution function for the pattern scanner.
  */