@diegovelasquezweb/a11y-engine 0.1.8 → 0.2.0

package/scripts/engine/analyzer.mjs

@@ -949,17 +949,23 @@ export function collectIncompleteFindings(routes) {
 }
 
 /**
- * The main execution function for the analyzer script.
- * Reads scan results, processes findings, and writes the final findings JSON.
+ * Runs the analyzer programmatically on a scan payload.
+ * @param {Object} scanPayload - The raw scan output from dom-scanner ({ routes, base_url, projectContext, ... }).
+ * @param {{ ignoreFindings?: string[], framework?: string, output?: string }} [options={}]
+ * @returns {Object} The enriched findings payload { findings, incomplete_findings, metadata, ... }.
  */
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const ignoredRules = new Set(args.ignoreFindings);
+export function runAnalyzer(scanPayload, options = {}) {
+  if (!scanPayload) throw new Error("Missing scan payload");
 
-  const payload = readJson(args.input);
-  if (!payload) throw new Error(`Input not found or invalid: ${args.input}`);
+  const args = {
+    input: null,
+    output: options.output || getInternalPath("a11y-findings.json"),
+    ignoreFindings: options.ignoreFindings || [],
+    framework: options.framework || null,
+  };
 
-  const result = buildFindings(payload, args);
+  const ignoredRules = new Set(args.ignoreFindings);
+  const result = buildFindings(scanPayload, args);
 
   if (ignoredRules.size > 0) {
     const knownIds = new Set(
@@ -989,15 +995,15 @@ function main() {
   if (deduplicatedCount > 0) log.info(`Deduplicated ${deduplicatedCount} cross-page finding group(s).`);
 
   const overallAssessment = computeOverallAssessment(dedupedFindings);
-  const passedCriteria = computePassedCriteria(payload.routes || [], WCAG_CRITERION_MAP, dedupedFindings);
-  const outOfScope = computeOutOfScope(payload.routes || []);
+  const passedCriteria = computePassedCriteria(scanPayload.routes || [], WCAG_CRITERION_MAP, dedupedFindings);
+  const outOfScope = computeOutOfScope(scanPayload.routes || []);
   const recommendations = computeRecommendations(dedupedFindings);
-  const testingMethodology = computeTestingMethodology(payload);
-  const incompleteFindings = collectIncompleteFindings(payload.routes || []);
+  const testingMethodology = computeTestingMethodology(scanPayload);
+  const incompleteFindings = collectIncompleteFindings(scanPayload.routes || []);
   if (incompleteFindings.length > 0)
     log.info(`${incompleteFindings.length} incomplete finding(s) require manual review.`);
 
-  writeJson(args.output, {
+  const outputPayload = {
     ...result,
     findings: dedupedFindings,
     incomplete_findings: incompleteFindings,
@@ -1011,12 +1017,32 @@ function main() {
       fpFiltered: fpRemovedCount,
       deduplicatedCount,
     },
-  });
+  };
+
+  // Write to disk for CLI compatibility
+  writeJson(args.output, outputPayload);
 
   if (dedupedFindings.length === 0) {
     log.info("Congratulations, no issues found.");
   }
   log.success(`Findings processed and saved to ${args.output}`);
+
+  return outputPayload;
+}
+
+/**
+ * CLI entry point — reads from disk, processes, writes to disk.
+ */
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const payload = readJson(args.input);
+  if (!payload) throw new Error(`Input not found or invalid: ${args.input}`);
+
+  runAnalyzer(payload, {
+    ignoreFindings: args.ignoreFindings,
+    framework: args.framework,
+    output: args.output,
+  });
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/engine/dom-scanner.mjs

@@ -489,7 +489,16 @@ async function analyzeRoute(
  * @param {"pending"|"running"|"done"|"error"} status - Step status.
  * @param {Object} [extra={}] - Additional metadata.
  */
+/** @type {((step: string, status: string, extra?: object) => void) | null} */
+let _onProgressCallback = null;
+
 function writeProgress(step, status, extra = {}) {
+  // Notify external callback if set (programmatic API)
+  if (_onProgressCallback) {
+    _onProgressCallback(step, status, extra);
+  }
+
+  // Always write to disk for CLI consumers
   const progressPath = getInternalPath("progress.json");
   let progress = {};
   try {
@@ -788,8 +797,45 @@ function mergeViolations(axeViolations, cdpViolations, pa11yViolations) {
  * Coordinates browser setup, crawling/discovery, parallel scanning, and result saving.
  * @throws {Error} If navigation to the base URL fails or browser setup issues occur.
  */
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
+/**
+ * Runs the DOM scanner programmatically.
+ * @param {Object} options - Scanner configuration (same shape as CLI args object).
+ * @param {{ onProgress?: (step: string, status: string, extra?: object) => void }} [callbacks={}]
+ * @returns {Promise<Object>} The scan payload { generated_at, base_url, onlyRule, projectContext, routes }.
+ */
+export async function runDomScanner(options = {}, callbacks = {}) {
+  const args = {
+    baseUrl: options.baseUrl || "",
+    routes: options.routes || "",
+    output: options.output || getInternalPath("a11y-scan-results.json"),
+    maxRoutes: options.maxRoutes ?? DEFAULTS.maxRoutes,
+    waitMs: options.waitMs ?? DEFAULTS.waitMs,
+    timeoutMs: options.timeoutMs ?? DEFAULTS.timeoutMs,
+    headless: options.headless ?? DEFAULTS.headless,
+    waitUntil: options.waitUntil ?? DEFAULTS.waitUntil,
+    colorScheme: options.colorScheme || null,
+    screenshotsDir: options.screenshotsDir || getInternalPath("screenshots"),
+    excludeSelectors: options.excludeSelectors || [],
+    onlyRule: options.onlyRule || null,
+    crawlDepth: Math.min(Math.max(options.crawlDepth ?? DEFAULTS.crawlDepth, 1), 3),
+    viewport: options.viewport || null,
+    axeTags: options.axeTags || null,
+  };
+
+  if (!args.baseUrl) throw new Error("Missing required option: baseUrl");
+
+  if (callbacks.onProgress) {
+    _onProgressCallback = callbacks.onProgress;
+  }
+
+  try {
+    return await _runDomScannerInternal(args);
+  } finally {
+    _onProgressCallback = null;
+  }
+}
+
+async function _runDomScannerInternal(args) {
   const baseUrl = new URL(args.baseUrl).toString();
   const origin = new URL(baseUrl).origin;
 
@@ -850,7 +896,7 @@ async function main() {
   } catch (err) {
     log.error(`Fatal: Could not load base URL ${baseUrl}: ${err.message}`);
     await browser.close();
-    process.exit(1);
+    throw new Error(`Could not load base URL ${baseUrl}: ${err.message}`);
   }
 
   /**
@@ -1036,6 +1082,13 @@ async function main() {
 
   writeJson(args.output, payload);
   log.success(`Routes scan complete. Results saved to ${args.output}`);
+
+  return payload;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  await runDomScanner(args);
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {

package/scripts/engine/source-scanner.mjs

@@ -113,7 +113,7 @@ function walkFiles(dir, extensions, results = []) {
  * @param {string} projectDir
  * @returns {string[]}
  */
-function resolveScanDirs(framework, projectDir) {
+export function resolveScanDirs(framework, projectDir) {
   const boundaries = framework ? SOURCE_BOUNDARIES?.[framework] : null;
   if (!boundaries) return [projectDir];
 

package/scripts/index.d.mts

@@ -63,7 +63,28 @@ export interface EnrichedFinding extends Finding {
   fixDifficultyNotes: string | string[] | null;
   screenshotPath: string | null;
   wcagCriterionId: string | null;
+  wcagClassification: string | null;
   impactedUsers: string | null;
+  primarySelector: string;
+  primaryFailureMode: string | null;
+  relationshipHint: string | null;
+  failureChecks: unknown[];
+  relatedContext: unknown[];
+  recommendedFix: string;
+  totalInstances: number | null;
+  relatedRules: string[];
+  ownershipStatus: string;
+  ownershipReason: string | null;
+  primarySourceScope: string[];
+  searchStrategy: string;
+  managedByLibrary: string | null;
+  componentHint: string | null;
+  verificationCommand: string | null;
+  verificationCommandFallback: string | null;
+  checkData: Record<string, unknown> | null;
+  pagesAffected: number | null;
+  affectedUrls: string[] | null;
+  effort: string;
 }
 
 export interface SeverityTotals {
@@ -79,12 +100,22 @@ export interface PersonaGroup {
   icon: string;
 }
 
+export interface DetectedStack {
+  framework: string | null;
+  cms: string | null;
+  uiLibraries: string[];
+}
+
 export interface AuditSummary {
   totals: SeverityTotals;
   score: number;
   label: string;
   wcagStatus: "Pass" | "Conditional Pass" | "Fail";
   personaGroups: Record<string, PersonaGroup>;
+  quickWins: EnrichedFinding[];
+  targetUrl: string;
+  detectedStack: DetectedStack;
+  totalFindings: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -106,19 +137,109 @@ export interface PDFReport {
   contentType: "application/pdf";
 }
 
+export interface HTMLReport {
+  html: string;
+  contentType: "text/html";
+}
+
 export interface ChecklistReport {
   html: string;
   contentType: "text/html";
 }
 
+export interface RemediationGuide {
+  markdown: string;
+  contentType: "text/markdown";
+}
+
+export interface SourcePatternFinding {
+  id: string;
+  pattern_id: string;
+  title: string;
+  severity: string;
+  wcag: string;
+  wcag_criterion: string;
+  wcag_level: string;
+  type: string;
+  fix_description: string | null;
+  status: "confirmed" | "potential";
+  file: string;
+  line: number;
+  match: string;
+  context: string;
+  source: "code-pattern";
+}
+
+export interface SourcePatternResult {
+  findings: SourcePatternFinding[];
+  summary: {
+    total: number;
+    confirmed: number;
+    potential: number;
+  };
+}
+
+export interface HTMLReportOptions extends ReportOptions {
+  screenshotsDir?: string;
+}
+
+export interface RemediationOptions extends ReportOptions {
+  patternFindings?: Record<string, unknown> | null;
+}
+
+export interface SourcePatternOptions {
+  framework?: string;
+  onlyPattern?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Audit options
+// ---------------------------------------------------------------------------
+
+export interface RunAuditOptions {
+  baseUrl: string;
+  maxRoutes?: number;
+  crawlDepth?: number;
+  routes?: string;
+  waitMs?: number;
+  timeoutMs?: number;
+  headless?: boolean;
+  waitUntil?: string;
+  colorScheme?: string;
+  viewport?: { width: number; height: number };
+  axeTags?: string[];
+  onlyRule?: string;
+  excludeSelectors?: string[];
+  ignoreFindings?: string[];
+  framework?: string;
+  projectDir?: string;
+  skipPatterns?: boolean;
+  onProgress?: (step: string, status: string, extra?: Record<string, unknown>) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Enrichment options
+// ---------------------------------------------------------------------------
+
+export interface EnrichmentOptions {
+  screenshotUrlBuilder?: (rawPath: string) => string;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
-export function getEnrichedFindings(findings: Finding[]): EnrichedFinding[];
-export function getEnrichedFindings(findings: Record<string, unknown>[]): EnrichedFinding[];
+export function runAudit(options: RunAuditOptions): Promise<ScanPayload>;
+
+export function getEnrichedFindings(
+  input: ScanPayload | Finding[] | Record<string, unknown>[],
+  options?: EnrichmentOptions
+): EnrichedFinding[];
 
-export function getAuditSummary(findings: EnrichedFinding[] | Record<string, unknown>[]): AuditSummary;
+export function getAuditSummary(
+  findings: EnrichedFinding[],
+  payload?: ScanPayload | null
+): AuditSummary;
 
 export function getPDFReport(
   payload: ScanPayload,
@@ -128,3 +249,18 @@ export function getPDFReport(
 export function getChecklist(
   options?: Pick<ReportOptions, "baseUrl">
 ): Promise<ChecklistReport>;
+
+export function getHTMLReport(
+  payload: ScanPayload,
+  options?: HTMLReportOptions
+): Promise<HTMLReport>;
+
+export function getRemediationGuide(
+  payload: ScanPayload & { incomplete_findings?: unknown[] },
+  options?: RemediationOptions
+): Promise<RemediationGuide>;
+
+export function getSourcePatterns(
+  projectDir: string,
+  options?: SourcePatternOptions
+): Promise<SourcePatternResult>;