@diegovelasquezweb/a11y-engine 0.7.2 → 0.7.3

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