@diegovelasquezweb/a11y-engine 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -5,38 +5,92 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.4.2] — 2026-03-15
+
+### Fixed
+
+- Broken relative imports in `src/reports/` after architecture migration — report builders were resolving `../../core/` and `../renderers/` instead of `../core/` and `./renderers/`
+
+---
+
+## [0.4.1] — 2026-03-15
+
+### Fixed
+
+- Asset loader imports updated to match flattened `assets/` structure (removed `generated/` and `source/` subdirectories)
+
+---
+
+## [0.4.0] — 2026-03-15
+
+### Changed
+
+- **Architecture migration**: all source code moved from `scripts/` to `src/` with domain-based modules:
+  - `src/cli/` — CLI adapter
+  - `src/core/` — utilities, asset loader, toolchain
+  - `src/pipeline/` — DOM scanner (axe + CDP + pa11y + merge)
+  - `src/enrichment/` — finding analyzer
+  - `src/reports/` — report builders and renderers
+  - `src/source-patterns/` — source code pattern scanner
+  - `src/index.mjs` — public API entry point
+  - `src/index.d.mts` — TypeScript declarations
+- Assets simplified to single `.mjs` modules under `assets/` (no more `source/` + `generated/` duplication)
+- `assets/engine/` renamed to `assets/scanning/` for semantic clarity
+- Package entrypoints updated: `main`, `types`, `bin`, `exports` all point to `src/`
+- CLI now invocable via `pnpm exec a11y-audit` (uses package `bin` field instead of internal paths)
+
+### Added
+
+- Vitest regression suite: 8 test files, 26 tests covering asset loading, enrichment, summary, report APIs, source patterns, and `runAudit` integration with mocked modules
+
+---
+
+## [0.3.1] — 2026-03-15
+
+### Changed
+
+- Assets converted to ESM modules with static imports — eliminates runtime `fs.readFileSync` and resolves Turbopack/Next.js chunk resolution failures
+- `asset-loader.mjs` now uses `import` statements instead of filesystem reads
+
+---
+
+## [0.3.0] — 2026-03-15
+
+### Added
+
+- **DOM-based stack detection** — detects framework (Next.js, Nuxt, Gatsby, Angular, Svelte, Astro, Remix, Vue, React), CMS (WordPress, Shopify, Drupal, Wix, Squarespace, Webflow, Joomla, Magento), and UI libraries (Bootstrap, Material UI, jQuery, Foundation) from the live page using window globals, script sources, meta tags, and DOM selectors
+- `runAudit()` — new programmatic API function that orchestrates the full scan pipeline with `onProgress` callback support
+- `detectProjectContextFromDom(page)` — runtime stack detection via `page.evaluate()`
+
+### Changed
+
+- Stack detection now merges repo-based detection (when `projectDir` is available) with DOM-based detection — repo takes priority, DOM fills gaps
+- `detectProjectContext()` no longer falls back to `process.cwd()` without explicit `projectDir` — prevents false detection of the scanner/host app as the audited site
+- `getAuditSummary` includes `cms` field in `detectedStack`
+- UI library detection requires at least 2 signals or 1 strong signal (global/scriptSrc/meta) to avoid false positives
+
+---
+
+## [0.2.0] — 2026-03-14
 
 ### Added
 
-- **Programmatic API** — 7 exported functions accessible via `import { ... } from "@diegovelasquezweb/a11y-engine"`:
-  - `getEnrichedFindings(input, options?)` — normalizes raw findings, canonicalizes pa11y rules, enriches with fix intelligence, infers effort, sorts by severity. Accepts a full scan payload or a raw findings array. Supports `screenshotUrlBuilder` callback for consumer-specific screenshot URLs.
-  - `getAuditSummary(findings, payload?)` — computes severity totals, compliance score, grade label, WCAG pass/fail status, persona impact groups, quick wins, target URL, and detected stack from metadata.
-  - `getPDFReport(payload, options?)` — generates a formal A4 PDF compliance report via Playwright. Returns `{ buffer, contentType }`.
-  - `getChecklist(options?)` — generates a standalone manual accessibility testing checklist as HTML. Returns `{ html, contentType }`.
-  - `getHTMLReport(payload, options?)` — generates an interactive HTML audit dashboard with severity filters and fix guidance. Supports embedded base64 screenshots via `screenshotsDir`. Returns `{ html, contentType }`.
-  - `getRemediationGuide(payload, options?)` — generates a Markdown remediation guide optimized for AI agents. Supports optional `patternFindings` from source scanner. Returns `{ markdown, contentType }`.
-  - `getSourcePatterns(projectDir, options?)` — scans project source code for accessibility patterns not detectable by axe-core. Returns `{ findings, summary }`.
-- **TypeScript type declarations** shipped with the package (`scripts/index.d.mts`):
-  - `Finding` — raw finding with all snake_case fields
-  - `EnrichedFinding` — extends Finding with camelCase aliases and enriched fields
-  - `AuditSummary` — full audit summary including totals, score, personas, quick wins, detected stack
-  - `SeverityTotals`, `PersonaGroup`, `DetectedStack`, `ComplianceScore`
-  - `ScanPayload`, `EnrichmentOptions`, `ReportOptions`
-  - `PDFReport`, `HTMLReport`, `ChecklistReport`, `RemediationGuide`
-  - `SourcePatternFinding`, `SourcePatternResult`, `SourcePatternOptions`
-- `exports` and `main` fields in `package.json` pointing to `scripts/index.mjs`
-- `--axe-tags` CLI flag passthrough from `audit.mjs` to `dom-scanner.mjs`
-- `resolveScanDirs` exported from `source-scanner.mjs` for programmatic use
+- **Programmatic API** — 8 exported functions accessible via `import { ... } from "@diegovelasquezweb/a11y-engine"`:
+  - `runAudit(options)` — runs the full scan pipeline programmatically with progress callback
+  - `getEnrichedFindings(input, options?)` — normalizes, canonicalizes, enriches, and sorts findings
+  - `getAuditSummary(findings, payload?)` — computes totals, score, personas, quick wins, detected stack
+  - `getPDFReport(payload, options?)` — PDF compliance report
+  - `getHTMLReport(payload, options?)` — interactive HTML dashboard
+  - `getChecklist(options?)` — manual testing checklist
+  - `getRemediationGuide(payload, options?)` — Markdown remediation guide
+  - `getSourcePatterns(projectDir, options?)` — source code pattern analysis
+- **TypeScript type declarations** shipped with the package (`src/index.d.mts`)
 
 ### Changed
 
-- `getEnrichedFindings` always creates camelCase aliases (`fixDescription`, `fixCode`, `screenshotPath`, `wcagCriterionId`, `impactedUsers`, etc.) regardless of whether the finding already has fix data — fixes bug where camelCase fields were `undefined` when snake_case data existed
-- `getEnrichedFindings` infers `effort` field after intelligence enrichment: findings with `fixCode` default to `"low"`, others to `"high"` — unless an explicit effort value already exists
-- `getEnrichedFindings` normalizes raw findings internally — consumers no longer need to pre-process the findings array
-- `getEnrichedFindings` sorts findings by severity (Critical > Serious > Moderate > Minor) then by ID
-- `getAuditSummary` now includes `quickWins` (top 3 Critical/Serious findings with fix code), `targetUrl` (extracted from metadata with fallbacks), and `detectedStack` (framework/CMS/libraries from project context)
-- CLI (`audit.mjs`) continues to work standalone — the programmatic API is additive
+- `getEnrichedFindings` always creates camelCase aliases regardless of existing fix data
+- `getEnrichedFindings` infers `effort` after enrichment: findings with `fixCode` default to `"low"`, others to `"high"`
+- `getAuditSummary` includes `quickWins`, `targetUrl`, and `detectedStack`
 
 ---
 

package/README.md

@@ -1,271 +1,132 @@
 # @diegovelasquezweb/a11y-engine
 
-Multi-engine WCAG 2.2 accessibility audit engine. Combines three scanning engines (axe-core, Chrome DevTools Protocol, and pa11y), merges and deduplicates their findings, enriches results with fix intelligence, and produces structured artifacts for developers, agents, and stakeholders.
+Accessibility automation engine for web applications. It orchestrates multi engine scanning, stack aware enrichment, and report generation for apps and services through a stable API.
 
-## What it is
+## What it does
 
-A Node.js package that works two ways:
-
-1. **CLI** — run `npx a11y-audit --base-url <url>` to scan a site and generate reports
-2. **Programmatic API** — import functions directly to normalize findings, compute scores, and generate reports in your own application
+| Capability | Description |
+| :--- | :--- |
+| **Route discovery crawler** | Builds the scan route set using sitemap discovery first, then a same origin multi level crawl with robots filtering, depth control, and max route limits |
+| **Multi engine scanning** | Runs axe-core, CDP accessibility tree checks, and pa11y HTML CodeSniffer against each page, then merges and deduplicates findings across all three engines |
+| **Stack detection** | Detects framework and CMS from runtime signals and from project source signals such as package.json and file structure |
+| **Fix intelligence** | Enriches each finding with WCAG mapping, fix code snippets, framework and CMS specific notes, UI library ownership hints, effort estimates, and persona impact |
+| **Report generation** | Produces HTML dashboard, PDF compliance report, manual testing checklist, and Markdown remediation guide |
+| **Source code scanning** | Static regex analysis of project source for accessibility patterns that runtime engines cannot detect |
 
-## Programmatic API
+## Installation
 
 ```bash
 npm install @diegovelasquezweb/a11y-engine
+
+# Required browsers
+npx playwright install chromium        # used by axe-core and CDP checks
+npx puppeteer browsers install chrome  # used by pa11y
 ```
 
+## API Reference
+
+### Core API
+
 ```ts
 import {
-  getEnrichedFindings,
-  getAuditSummary,
+  runAudit,
+  getFindings,
+  getOverview,
   getPDFReport,
-  getChecklist,
   getHTMLReport,
+  getChecklist,
   getRemediationGuide,
   getSourcePatterns,
 } from "@diegovelasquezweb/a11y-engine";
 ```
 
-### getEnrichedFindings
-
-Normalizes raw scan findings, canonicalizes pa11y rules to axe equivalents, enriches with fix intelligence, infers effort, and sorts by severity.
-
-```ts
-const findings = getEnrichedFindings(scanPayload, {
-  screenshotUrlBuilder: (path) => `/api/screenshot?path=${encodeURIComponent(path)}`,
-});
-```
-
-| Parameter | Type | Description |
-| :--- | :--- | :--- |
-| `input` | `ScanPayload \| Finding[] \| Record<string, unknown>[]` | Raw scan output or findings array |
-| `options.screenshotUrlBuilder` | `(rawPath: string) => string` | Transforms screenshot file paths into consumer-specific URLs |
-
-**Returns**: `EnrichedFinding[]` — normalized, enriched, sorted findings with both snake_case and camelCase fields.
-
-### getAuditSummary
-
-Computes a complete audit summary from enriched findings.
-
-```ts
-const summary = getAuditSummary(findings, scanPayload);
-// summary.score         → 72
-// summary.label         → "Good"
-// summary.wcagStatus    → "Fail"
-// summary.totals        → { Critical: 1, Serious: 3, Moderate: 5, Minor: 2 }
-// summary.personaGroups → { screenReader: {...}, keyboard: {...}, ... }
-// summary.quickWins     → [top 3 fixable Critical/Serious findings]
-// summary.targetUrl     → "https://example.com"
-// summary.detectedStack → { framework: "nextjs", cms: null, uiLibraries: [] }
-```
-
-| Parameter | Type | Description |
-| :--- | :--- | :--- |
-| `findings` | `EnrichedFinding[]` | Output from `getEnrichedFindings` |
-| `payload` | `ScanPayload \| null` | Original scan payload for metadata extraction |
-
-**Returns**: `AuditSummary`
-
-### getPDFReport
+#### runAudit
 
-Generates a formal A4 PDF compliance report using Playwright.
+Runs the full scan pipeline: route discovery crawler, scan, merge, and analyze. Returns a payload ready for `getFindings`.
 
 ```ts
-const { buffer, contentType } = await getPDFReport(scanPayload, {
+const payload = await runAudit({
   baseUrl: "https://example.com",
+  maxRoutes: 5,
+  axeTags: ["wcag2a", "wcag2aa", "best-practice"],
+  onProgress: (step, status) => console.log(`${step}: ${status}`),
 });
-fs.writeFileSync("report.pdf", buffer);
 ```
 
-**Returns**: `Promise<PDFReport>` — `{ buffer: Buffer, contentType: "application/pdf" }`
+Progress steps emitted: `page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`.
 
-### getHTMLReport
+**Common `runAudit` options**
 
-Generates an interactive HTML audit dashboard with severity filters, persona impact, and fix guidance.
-
-```ts
-const { html, contentType } = await getHTMLReport(scanPayload, {
-  baseUrl: "https://example.com",
-  screenshotsDir: "/path/to/.audit/screenshots",
-});
-```
+| Option | Description |
+| :--- | :--- |
+| `baseUrl` | Target URL to scan |
+| `maxRoutes` | Maximum routes to scan |
+| `axeTags` | WCAG tag filters |
+| `projectDir` | Project source path for source-aware detection and pattern scanning |
+| `skipPatterns` | Disable source pattern scanning |
+| `onProgress` | Progress callback for UI updates |
 
-**Returns**: `Promise<HTMLReport>` — `{ html: string, contentType: "text/html" }`
+See [API Reference](docs/api-reference.md) for the full `RunAuditOptions` contract.
 
-### getChecklist
+#### getFindings
 
-Generates a standalone manual accessibility testing checklist.
+Builds the enriched findings list from the `payload` returned by `runAudit`.
 
 ```ts
-const { html, contentType } = await getChecklist({
-  baseUrl: "https://example.com",
+const findings = getFindings(payload, {
+  screenshotUrlBuilder: (path) => `/api/screenshot?path=${encodeURIComponent(path)}`,
 });
 ```
 
-**Returns**: `Promise<ChecklistReport>` — `{ html: string, contentType: "text/html" }`
+Returns `EnrichedFinding[]` ready for UI rendering and report generation.
 
-### getRemediationGuide
+**Options (`EnrichmentOptions`)**
 
-Generates a Markdown remediation guide optimized for AI agents.
-
-```ts
-const { markdown, contentType } = await getRemediationGuide(scanPayload, {
-  baseUrl: "https://example.com",
-  patternFindings: sourcePatternResult,
-});
-```
-
-**Returns**: `Promise<RemediationGuide>` — `{ markdown: string, contentType: "text/markdown" }`
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `screenshotUrlBuilder` | `(rawPath: string) => string` | Rewrites internal screenshot paths into app URLs |
 
-### getSourcePatterns
+#### getOverview
 
-Scans project source code for accessibility patterns not detectable by axe-core at runtime.
+Computes severity totals, compliance score, WCAG pass/fail status, persona impact groups, quick wins, and detected stack.
 
 ```ts
-const { findings, summary } = await getSourcePatterns("/path/to/project", {
-  framework: "nextjs",
-});
-// summary → { total: 12, confirmed: 10, potential: 2 }
-```
-
-**Returns**: `Promise<SourcePatternResult>` — `{ findings: SourcePatternFinding[], summary: { total, confirmed, potential } }`
-
-## CLI usage
-
-The CLI runs the full scan pipeline: crawl, scan with 3 engines, merge, analyze, and generate reports.
-
-```bash
-# Minimal scan
-npx a11y-audit --base-url https://example.com
-
-# Full audit with all reports
-npx a11y-audit --base-url https://example.com --with-reports --output ./audit/report.html
-
-# Scan with source code intelligence
-npx a11y-audit --base-url http://localhost:3000 --project-dir . --with-reports --output ./audit/report.html
-```
-
-### Targeting and scope
-
-| Flag | Argument | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `--base-url` | `<url>` | (Required) | Starting URL for the audit |
-| `--max-routes` | `<num>` | `10` | Max routes to discover and scan |
-| `--crawl-depth` | `<num>` | `2` | BFS link-follow depth during discovery (1-3) |
-| `--routes` | `<csv>` | — | Explicit path list, bypasses auto-discovery |
-| `--project-dir` | `<path>` | — | Path to project source for stack-aware fixes and source pattern scanning |
-
-### Audit intelligence
-
-| Flag | Argument | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `--target` | `<text>` | `WCAG 2.2 AA` | Compliance target label in reports |
-| `--axe-tags` | `<csv>` | `wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa` | axe-core WCAG tag filter |
-| `--only-rule` | `<id>` | — | Run a single axe rule (e.g. `color-contrast`) |
-| `--ignore-findings` | `<csv>` | — | Rule IDs to exclude from output |
-| `--exclude-selectors` | `<csv>` | — | CSS selectors to skip during DOM scan |
-| `--framework` | `<name>` | — | Override auto-detected stack (`nextjs`, `react`, `vue`, `angular`, `svelte`, `shopify`, `wordpress`, etc.) |
-
-### Execution and emulation
-
-| Flag | Argument | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `--color-scheme` | `light\|dark` | `light` | Emulate `prefers-color-scheme` |
-| `--wait-until` | `domcontentloaded\|load\|networkidle` | `domcontentloaded` | Playwright page load strategy |
-| `--viewport` | `<WxH>` | — | Viewport size (e.g. `375x812`) |
-| `--wait-ms` | `<num>` | `2000` | Delay after page load before scanning (ms) |
-| `--timeout-ms` | `<num>` | `30000` | Network timeout per page (ms) |
-| `--headed` | — | `false` | Run browser in visible mode |
-| `--affected-only` | — | `false` | Re-scan only routes with previous violations |
-
-### Output generation
-
-| Flag | Argument | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `--with-reports` | — | `false` | Generate HTML + PDF + Checklist reports |
-| `--output` | `<path>` | — | Output path for `report.html` |
-| `--skip-patterns` | — | `false` | Disable source code pattern scanner |
-
-## How the scan pipeline works
-
-```
-URL
- |
- v
-[1. Crawl & Discover]  sitemap.xml / BFS link crawl / explicit --routes
- |
- v
-[2. Navigate]           Playwright opens each route in Chromium
- |
- +---> [axe-core]       Injects axe into the page, runs WCAG tag checks
- |
- +---> [CDP]            Opens a CDP session, reads the full accessibility tree
- |
- +---> [pa11y]          Launches HTML CodeSniffer via Puppeteer Chrome
- |
- v
-[3. Merge & Dedup]      Combines findings, removes cross-engine duplicates
- |
- v
-[4. Analyze]            Enriches with WCAG mapping, severity, fix code, framework hints
- |
- v
-[5. Reports]            HTML dashboard, PDF, checklist, Markdown remediation
+const summary = getOverview(findings, payload);
+// summary.score         -> 72
+// summary.label         -> "Good"
+// summary.wcagStatus    -> "Fail"
+// summary.totals        -> { Critical: 1, Serious: 3, Moderate: 5, Minor: 2 }
+// summary.personaGroups -> { screenReader: {...}, keyboard: {...}, ... }
+// summary.quickWins     -> [top 3 fixable Critical/Serious findings]
+// summary.detectedStack -> { framework: "nextjs", cms: null, uiLibraries: [] }
 ```
 
-## Scan engines
-
-### axe-core (via @axe-core/playwright)
-
-The primary engine. Runs Deque's axe-core rule set against the live DOM inside Playwright's Chromium. Covers the majority of automatable WCAG 2.2 AA success criteria.
-
-### CDP (Chrome DevTools Protocol)
-
-Queries the browser's full accessibility tree via a CDP session. Catches issues axe may miss:
-- Interactive elements with no accessible name
-- Focusable elements hidden with `aria-hidden`
-
-### pa11y (HTML CodeSniffer)
-
-Runs Squiz's HTML CodeSniffer via Puppeteer Chrome. Catches WCAG violations around heading hierarchy, link purpose, and form label associations.
+### Output API
 
-Requires a separate Chrome installation (`npx puppeteer browsers install chrome`). If Chrome is missing, pa11y fails silently and the scan continues with axe + CDP.
+These functions render final artifacts from scan payload data.
 
-## Output artifacts
-
-All artifacts are written to `.audit/` relative to the package root.
-
-| File | Always generated | Description |
+| Function | Returns | Description |
 | :--- | :--- | :--- |
-| `a11y-scan-results.json` | Yes | Raw merged results from axe + CDP + pa11y per route |
-| `a11y-findings.json` | Yes | Enriched findings with fix intelligence |
-| `progress.json` | Yes | Real-time scan progress with per-engine step status |
-| `remediation.md` | Yes | AI-agent-optimized remediation roadmap |
-| `report.html` | With `--with-reports` | Interactive HTML dashboard |
-| `report.pdf` | With `--with-reports` | Formal compliance PDF |
-| `checklist.html` | With `--with-reports` | Manual WCAG testing checklist |
+| `getPDFReport(payload, options?)` | `{ buffer, contentType }` | Formal A4 PDF compliance report |
+| `getHTMLReport(payload, options?)` | `{ html, contentType }` | Interactive HTML audit dashboard |
+| `getChecklist(options?)` | `{ html, contentType }` | Manual WCAG testing checklist |
+| `getRemediationGuide(payload, options?)` | `{ markdown, contentType }` | Markdown remediation guide |
+| `getSourcePatterns(projectDir, options?)` | `{ findings, summary }` | Source code pattern analysis |
 
-## Installation
+See [API Reference](docs/api-reference.md) for exact options and return types.
 
-```bash
-npm install @diegovelasquezweb/a11y-engine
-npx playwright install chromium
-npx puppeteer browsers install chrome
-```
+## Optional CLI
 
-> **Two browsers are required:**
-> - **Playwright Chromium** — used by axe-core and CDP checks
-> - **Puppeteer Chrome** — used by pa11y (HTML CodeSniffer)
+If you need terminal execution, the package also exposes `a11y-audit`.
+See the [CLI Handbook](docs/cli-handbook.md) for command flags and examples.
 
 ## Documentation
 
 | Resource | Description |
 | :--- | :--- |
-| [Architecture](docs/architecture.md) | How the multi-engine scanner pipeline works |
-| [CLI Handbook](docs/cli-handbook.md) | Full flag reference and usage patterns |
+| [Architecture](docs/architecture.md) | Multi-engine pipeline, merge logic, and execution model |
+| [API Reference](docs/api-reference.md) | Function signatures, options, and return contracts |
+| [CLI Handbook](docs/cli-handbook.md) | Full flag reference and usage examples |
 | [Output Artifacts](docs/outputs.md) | Schema and structure of every generated file |
-
-## License
-
-MIT
+| [Engine Manifest](docs/engine-manifest.md) | Current inventory of source modules, assets, and tests |
+| [Testing](docs/testing.md) | Test categories, scope, and execution commands |

package/docs/api-reference.md

@@ -0,0 +1,107 @@
+# API Reference
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [API Reference](api-reference.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+
+---
+
+## Core API
+
+### `runAudit(options)`
+
+Runs route discovery, runtime scan, merge, and analyzer enrichment.
+
+`options` (`RunAuditOptions`):
+
+| Option | Type |
+| :--- | :--- |
+| `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` |
+| `screenshotsDir` | `string` |
+| `onProgress` | `(step: string, status: string, extra?: Record<string, unknown>) => void` |
+
+Returns: `Promise<ScanPayload>`
+
+### `getFindings(input, options?)`
+
+Normalizes and enriches findings and returns sorted enriched findings.
+
+- `input`: `ScanPayload` from `runAudit`
+- `options` (`EnrichmentOptions`):
+  - `screenshotUrlBuilder?: (rawPath: string) => string`
+
+Returns: `EnrichedFinding[]`
+
+### `getOverview(findings, payload?)`
+
+Computes totals, score, WCAG status, persona groups, quick wins, target URL, and detected stack.
+
+- `findings`: `EnrichedFinding[]`
+- `payload`: `ScanPayload | null`
+
+Returns: `AuditSummary`
+
+## Output API
+
+### `getPDFReport(payload, options?)`
+
+- `payload`: `ScanPayload`
+- `options`: `ReportOptions`
+  - `baseUrl?: string`
+  - `target?: string`
+
+Returns: `Promise<PDFReport>` (`{ buffer, contentType }`)
+
+### `getHTMLReport(payload, options?)`
+
+- `payload`: `ScanPayload`
+- `options`: `HTMLReportOptions`
+  - `baseUrl?: string`
+  - `target?: string`
+  - `screenshotsDir?: string`
+
+Returns: `Promise<HTMLReport>` (`{ html, contentType }`)
+
+### `getChecklist(options?)`
+
+- `options`: `Pick<ReportOptions, "baseUrl">`
+  - `baseUrl?: string`
+
+Returns: `Promise<ChecklistReport>` (`{ html, contentType }`)
+
+### `getRemediationGuide(payload, options?)`
+
+- `payload`: `ScanPayload & { incomplete_findings?: unknown[] }`
+- `options`: `RemediationOptions`
+  - `baseUrl?: string`
+  - `target?: string`
+  - `patternFindings?: Record<string, unknown> | null`
+
+Returns: `Promise<RemediationGuide>` (`{ markdown, contentType }`)
+
+### `getSourcePatterns(projectDir, options?)`
+
+- `projectDir`: `string`
+- `options`: `SourcePatternOptions`
+  - `framework?: string`
+  - `onlyPattern?: string`
+
+Returns: `Promise<SourcePatternResult>`
+
+---
+
+Canonical type source: `src/index.d.mts`