@diegovelasquezweb/a11y-engine 0.7.2 → 0.7.4

package/README.md

@@ -62,29 +62,7 @@ const payload = await runAudit({
 });
 ```
 
-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.
-
-**`runAudit` options**
-
-| 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.
+See [API Reference](docs/api-reference.md) for options, progress steps, and return types.
 
 #### getFindings
 
@@ -133,13 +111,13 @@ These functions render final artifacts from scan payload data.
 
 ### Knowledge API
 
-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.
+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 |
+| `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 |

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.2",
+  "version": "0.7.4",
   "description": "WCAG 2.2 accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/src/cli/audit.mjs

@@ -140,6 +140,31 @@ 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");
+
+  let remotePackageJson = null;
+  let detectedFramework = null;
+  if (repoUrl) {
+    try {
+      const { fetchPackageJson } = await import("../core/github-api.mjs");
+      remotePackageJson = await fetchPackageJson(repoUrl, githubToken || undefined);
+      if (remotePackageJson) {
+        const { detectProjectContext } = await import("../pipeline/dom-scanner.mjs");
+        const ctx = detectProjectContext(null, remotePackageJson);
+        if (ctx.framework) {
+          detectedFramework = ctx.framework;
+          log.info(`Detected framework from repository: ${ctx.framework}`);
+        }
+        if (ctx.uiLibraries.length) {
+          log.info(`Detected UI libraries: ${ctx.uiLibraries.join(", ")}`);
+        }
+      }
+    } catch (err) {
+      log.warn(`Could not fetch package.json from repo: ${err.message}`);
+    }
+  }
+
   const sessionFile = getInternalPath("a11y-session.json");
   let projectDir = getArgValue("project-dir");
   if (projectDir) {
@@ -265,12 +290,19 @@ async function main() {
 
     const analyzerArgs = [];
     if (ignoreFindings) analyzerArgs.push("--ignore-findings", ignoreFindings);
-    if (framework) analyzerArgs.push("--framework", framework);
+    const resolvedFramework = framework || detectedFramework;
+    if (resolvedFramework) analyzerArgs.push("--framework", resolvedFramework);
     await runScript("../enrichment/analyzer.mjs", analyzerArgs);
 
-    if (projectDir && !skipPatterns) {
-      const patternArgs = ["--project-dir", path.resolve(projectDir)];
-      let resolvedFramework = framework;
+    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 || detectedFramework;
       if (!resolvedFramework) {
         try {
           const findings = JSON.parse(fs.readFileSync(getInternalPath("a11y-findings.json"), "utf-8"));

package/src/reports/renderers/html.mjs

@@ -107,15 +107,7 @@ export function buildIssueCard(finding) {
       </div>`
     : "";
 
-  const implNotesHtml = finding.fixDifficultyNotes
-    ? `<div class="mt-4 pt-3 border-t border-indigo-100/50">
-        <h4 class="text-[10px] font-black text-amber-700 uppercase tracking-widest mb-2 flex items-center gap-1.5">
-          <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"></path></svg>
-          Implementation Notes
-        </h4>
-        <p class="text-[12px] text-amber-900/80 leading-relaxed bg-amber-50/60 border border-amber-100/60 rounded-lg p-3">${escapeHtml(finding.fixDifficultyNotes)}</p>
-      </div>`
-    : "";
+  const implNotesHtml = "";
 
   const problemPanelHtml = `
     <div class="grid grid-cols-1 gap-6">

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);
-  }
+  });
 }