@diegovelasquezweb/a11y-engine 0.6.5 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.6.5",
-  "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
+  "version": "0.7.0",
+  "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

@@ -744,6 +744,14 @@ function computeTestingMethodology(payload) {
   const routes = payload.routes || [];
   const scanned = routes.filter((r) => !r.error).length;
   const errored = routes.filter((r) => r.error).length;
+  const tags = payload.axeTags || [];
+  const conformanceLevel = tags.includes("wcag2aaa")
+    ? "AAA"
+    : tags.includes("wcag2aa") || tags.includes("wcag21aa") || tags.includes("wcag22aa")
+      ? "AA"
+      : tags.includes("wcag2a") || tags.includes("wcag21a") || tags.includes("wcag22a")
+        ? "A"
+        : null;
   return {
     automated_tools: [
       "axe-core (via @axe-core/playwright)",
@@ -751,7 +759,10 @@ function computeTestingMethodology(payload) {
       "pa11y (HTML CodeSniffer via Puppeteer)",
       "Playwright + Chromium",
     ],
-    compliance_target: "WCAG 2.2 AA",
+    compliance_target: "WCAG 2.2",
+    conformance_level: conformanceLevel,
+    best_practices: tags.includes("best-practice"),
+    axe_tags: tags.length > 0 ? tags : null,
     pages_scanned: scanned,
     pages_errored: errored,
     framework_detected: payload.projectContext?.framework || "Not detected",

package/src/index.d.mts

@@ -394,12 +394,22 @@ 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;
 }
 
+export interface AiOptions {
+  enabled?: boolean;
+  apiKey?: string;
+  githubToken?: string;
+  model?: string;
+}
+
 
 
 

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,23 @@ 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) {
+    if (onProgress) onProgress("repo", "running");
+    try {
+      const { fetchPackageJson } = await import("./core/github-api.mjs");
+      remotePackageJson = await fetchPackageJson(options.repoUrl, options.githubToken);
+      if (remotePackageJson) {
+        if (onProgress) onProgress("repo", "done", { packageJson: true });
+      } else {
+        if (onProgress) onProgress("repo", "skipped", { reason: "Could not read package.json" });
+      }
+    } catch (err) {
+      if (onProgress) onProgress("repo", "skipped", { reason: err.message });
+    }
+  }
+
   // Step 1: DOM scan (selected engines)
   if (onProgress) onProgress("page", "running");
 
@@ -672,6 +694,7 @@ export async function runAudit(options) {
       excludeSelectors: options.excludeSelectors,
       screenshotsDir: options.screenshotsDir,
       projectDir: options.projectDir,
+      remotePackageJson,
       engines,
     },
     { onProgress },
@@ -685,10 +708,11 @@ 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) {
+    if (onProgress) onProgress("patterns", "running");
     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,35 +720,97 @@ 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);
         }
       }
 
+      const confirmed = allPatternFindings.filter((f) => f.status === "confirmed").length;
+      const potential = allPatternFindings.filter((f) => f.status === "potential").length;
+
       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,
-            confirmed: allPatternFindings.filter((f) => f.status === "confirmed").length,
-            potential: allPatternFindings.filter((f) => f.status === "potential").length,
-          },
+          summary: { total: allPatternFindings.length, confirmed, potential },
         };
       }
+
+      if (onProgress) onProgress("patterns", "done", {
+        total: allPatternFindings.length,
+        confirmed,
+        potential,
+      });
     } catch (err) {
-      // Non-fatal: source scanning is optional
       const msg = err instanceof Error ? err.message : String(err);
+      if (onProgress) onProgress("patterns", "skipped", { reason: msg });
       console.warn(`Source pattern scan failed (non-fatal): ${msg}`);
     }
   }
 
   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 && onProgress && options.ai !== undefined) {
+    onProgress("ai", "skipped", { reason: "No API key configured" });
+  }
+  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 +1115,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: [] };
@@ -1253,6 +1288,7 @@ async function _runDomScannerInternal(args) {
     base_url: baseUrl,
     onlyRule: args.onlyRule || null,
     engines: args.engines,
+    axeTags: args.axeTags || null,
     projectContext,
     routes: results,
   };

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.
  */