@diegovelasquezweb/a11y-engine 0.4.1 → 0.5.0

package/docs/architecture.md

@@ -1,240 +1,114 @@
 # Engine Architecture
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+**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)
 
 ---
 
 ## Table of Contents
 
-- [Pipeline overview](#pipeline-overview)
-- [Stage 1: DOM scanner](#stage-1-dom-scanner)
-  - [axe-core](#axe-core)
-  - [CDP checks](#cdp-checks)
-  - [pa11y](#pa11y)
-  - [Merge and deduplication](#merge-and-deduplication)
-- [Stage 1b: Source scanner](#optional-source-scanner)
-- [Stage 2: Analyzer](#stage-2-analyzer)
-- [Stage 3: Report builders](#stage-3-report-builders)
-- [Assets and rule intelligence](#assets-and-rule-intelligence)
-- [Execution model and timeouts](#execution-model-and-timeouts)
+- [High-Level Pipeline](#high-level-pipeline)
+- [Execution Modes](#execution-modes)
+- [Module Responsibilities](#module-responsibilities)
+- [Stack Detection Model](#stack-detection-model)
+- [Data Contracts](#data-contracts)
 
----
-
-The engine operates as a three-stage pipeline. Each stage is an independent Node.js process spawned by `audit.mjs`. Stages communicate through JSON files written to `.audit/`.
-
-## Pipeline overview
-
-```
-Target URL
-    │
-    ▼
-┌─────────────────────────────────┐
-│  Stage 1: DOM Scanner           │  Three engines per route:
-│  dom-scanner.mjs                │
-│                                 │
-│  ┌──────────┐  ┌──────┐        │
-│  │ axe-core │  │ CDP  │        │  Playwright Chromium
-│  └────┬─────┘  └──┬───┘        │
-│       │           │             │
-│  ┌────▼───────────▼────┐       │
-│  │      pa11y          │       │  Puppeteer Chrome
-│  └────────┬────────────┘       │
-│           │                    │
-│  ┌────────▼────────────┐       │
-│  │  Merge & Dedup      │       │
-│  └────────┬────────────┘       │
-└───────────┼─────────────────────┘
-            │ a11y-scan-results.json
-            │ progress.json
-            ▼
-┌─────────────────────────────────┐
-│  Stage 1b: Source Scanner       │  Static regex analysis
-│  source-scanner.mjs             │  (optional — requires --project-dir)
-└───────────┬─────────────────────┘
-            │ merges into a11y-findings.json
-            ▼
-┌─────────────────────────────────┐
-│  Stage 2: Analyzer              │  Fix intelligence enrichment
-│  analyzer.mjs                   │  intelligence.json + guardrails
-└───────────┬─────────────────────┘
-            │ a11y-findings.json
-            ▼
-┌─────────────────────────────────┐
-│  Stage 3: Report Builders       │  Parallel rendering
-│  md / html / pdf / checklist    │
-└───────────┬─────────────────────┘
-            │
-    ┌───────┼──────────┬──────────────┐
-    ▼       ▼          ▼              ▼
-remediation report   report        checklist
-   .md      .html     .pdf           .html
-```
-
-## Stage 1: DOM scanner
-
-**Script**: `scripts/engine/dom-scanner.mjs`
-
-Launches a Playwright-controlled Chromium browser, discovers routes, and runs three independent accessibility engines against each page. Results are merged and deduplicated before output.
-
-### Route discovery
-
-- If the site exposes a `sitemap.xml`, all listed URLs are scanned (up to `--max-routes`).
-- Otherwise, BFS crawl starting from `--base-url`, following same-origin `<a href>` links up to `--crawl-depth` levels deep.
-- Routes are deduplicated and normalized before scanning.
-- 3 parallel browser tabs scan routes concurrently (~2-3x faster than sequential).
-
-### axe-core
-
-**Dependency**: `@axe-core/playwright`
+The engine is the shared core used by CLI and applications. It runs a multi-engine scan, enriches findings, and produces report-ready outputs.
 
-The primary engine. Injects axe-core into the live page via Playwright and runs WCAG 2.2 A/AA tag checks. Covers the majority of automatable WCAG success criteria (~80+ rules).
+## High-Level Pipeline
 
-- Configurable via `--axe-tags` (default: `wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22a,wcag22aa`)
-- Supports `--only-rule` for focused single-rule audits
-- Supports `--exclude-selectors` to skip specific elements
+```mermaid
+flowchart TD
+    A[Target URL] --> B[Route Discovery]
+    B --> C[Scan Route]
 
-### CDP checks
+    subgraph Engines[Runtime Engines]
+      C --> AXE[axe-core]
+      C --> CDP[CDP checks]
+      C --> P11Y[pa11y]
+    end
 
-**Dependency**: Playwright's built-in CDP session (`page.context().newCDPSession()`)
+    AXE --> M[Merge and Dedup]
+    CDP --> M
+    P11Y --> M
 
-Queries the browser's full accessibility tree via Chrome DevTools Protocol. Catches issues axe may miss because it operates on the computed accessibility tree rather than the DOM:
+    M --> R[a11y-scan-results.json]
+    R --> AN[Analyzer]
+    AN --> F[a11y-findings.json]
 
-- **Missing accessible names** — interactive elements (`button`, `link`, `textbox`, `combobox`, etc.) with empty names in the accessibility tree
-- **aria-hidden on focusable elements** — elements that are focusable but hidden from assistive technology
-
-CDP findings use axe-compatible violation format with `source: "cdp"` for downstream processing.
-
-### pa11y
-
-**Dependency**: `pa11y` (which uses Puppeteer + Chrome internally)
-
-Runs Squiz's HTML CodeSniffer against each page URL. Catches WCAG violations that axe and CDP may miss:
-
-- Heading hierarchy issues
-- Link purpose violations
-- Form label associations
-- Additional WCAG2AA/WCAG2AAA checks from HTML CodeSniffer's rule set
+    F --> MD[remediation.md]
+    F --> HTML[report.html]
+    F --> PDF[report.pdf]
+    F --> CHK[checklist.html]
+```
 
-pa11y requires a separate Chrome installation (`npx puppeteer browsers install chrome`). This is separate from Playwright's Chromium. If Chrome is missing, pa11y fails silently (non-fatal) and the scan continues with axe + CDP only.
+## Execution Modes
+
+```mermaid
+flowchart LR
+    subgraph CLI[CLI Mode]
+      C1[src/cli/audit.mjs]
+      C2[src/pipeline/dom-scanner.mjs]
+      C3[src/enrichment/analyzer.mjs]
+      C4[src/reports/*.mjs]
+      C1 --> C2 --> C3 --> C4
+    end
+
+    subgraph API[Programmatic Mode]
+      A1[src/index.mjs]
+      A2[runAudit]
+      A3[getFindings]
+      A4[getOverview]
+      A5[get*Report functions]
+      A1 --> A2
+      A1 --> A3
+      A1 --> A4
+      A1 --> A5
+    end
+```
 
-pa11y findings use axe-compatible violation format with `source: "pa11y"` for downstream processing.
+- **CLI mode** writes artifacts to `.audit/`.
+- **API mode** returns data in memory (objects/strings/buffers).
 
-### Merge and deduplication
+## Module Responsibilities
 
-After all three engines complete, `mergeViolations()` combines findings and removes cross-engine duplicates:
+| Module | Responsibility |
+| :--- | :--- |
+| `src/pipeline/dom-scanner.mjs` | Route discovery, engine execution (axe/CDP/pa11y), merge/dedup, progress updates, screenshots |
+| `src/enrichment/analyzer.mjs` | Rule enrichment, selector strategy, ownership hints, recommendations, scoring metadata |
+| `src/source-patterns/source-scanner.mjs` | Static source pattern detection for issues runtime engines cannot see |
+| `src/reports/*.mjs` | Report builders for markdown/html/pdf/checklist |
+| `src/reports/renderers/*.mjs` | Shared rendering and normalization helpers |
+| `src/core/asset-loader.mjs` | Centralized access to bundled assets |
+| `src/index.mjs` | Public API facade (`runAudit`, `getFindings`, `getOverview`, report APIs, source patterns) |
 
-1. **axe findings** are added first as the baseline
-2. **CDP findings** are checked against axe equivalents (e.g. `cdp-missing-accessible-name` maps to `button-name`, `link-name`, `input-name`, `aria-command-name`). Only truly new findings are added.
-3. **pa11y findings** are checked against existing selectors. If the same element is already flagged by axe or CDP, the pa11y finding is dropped.
+## Stack Detection Model
 
-The merged violations are written to `a11y-scan-results.json` per route.
+Detection combines runtime and source signals:
 
-### Progress tracking
+1. **Runtime signals** from scanned pages:
+   - DOM markers, globals, script URLs, and meta tags
+2. **Project source signals** when `projectDir` is provided:
+   - package dependencies and file structure
+3. **Merge strategy**:
+   - source-based detection has priority when present
+   - runtime detection fills missing fields
 
-The scanner writes `progress.json` in real-time as each engine runs. This file is used by integrations (like `a11y-scanner`) for live progress UI:
+Output shape:
 
 ```json
 {
-  "steps": {
-    "page":  { "status": "done", "updatedAt": "..." },
-    "axe":   { "status": "done", "updatedAt": "...", "found": 8 },
-    "cdp":   { "status": "done", "updatedAt": "...", "found": 3 },
-    "pa11y": { "status": "done", "updatedAt": "...", "found": 2 },
-    "merge": { "status": "done", "updatedAt": "...", "axe": 8, "cdp": 3, "pa11y": 2, "merged": 11 }
-  },
-  "currentStep": "merge"
+  "framework": "nextjs",
+  "cms": null,
+  "uiLibraries": ["radix"]
 }
 ```
 
-### Screenshots
-
-After merging, element screenshots are captured for each violation. Non-visible elements (`<meta>`, `<link>`, `<script>`, etc.) are automatically skipped. Screenshots are stored in `.audit/screenshots/` and referenced by each violation's `screenshot_path` field.
-
-### Optional: Source scanner
-
-**Script**: `scripts/engine/source-scanner.mjs` — runs when `--project-dir` is set and `--skip-patterns` is not.
-
-Performs static analysis of source files for accessibility issues no runtime engine can detect (e.g. focus outline suppression, missing alt text in templates). Uses regex patterns from `assets/remediation/code-patterns.json` scoped to framework-specific file boundaries from `assets/remediation/source-boundaries.json`.
-
-Findings are classified as `confirmed` (pattern unambiguously matches) or `potential` (requires human verification).
-
-## Stage 2: Analyzer
-
-**Script**: `scripts/engine/analyzer.mjs`
-
-Reads `a11y-scan-results.json` (which contains merged axe + CDP + pa11y results) and enriches each violation with:
-
-- **Fix intelligence** from `assets/remediation/intelligence.json` — 106 axe-core rules with code snippets, MDN links, framework-specific notes, and WCAG criterion mapping. CDP and pa11y findings receive generic enrichment based on their rule structure.
-- **Selector scoring** — picks the most stable selector from axe's `nodes` list. Priority: `#id` > `[data-*]` > `[aria-*]` > `[type=]`, with penalty for Tailwind utility classes.
-- **Framework context** — `assets/discovery/stack-detection.json` fingerprints the DOM to detect framework and CMS. Per-finding `framework_notes` and `cms_notes` are filtered to the detected stack.
-- **Guardrails** — `assets/remediation/guardrails.json` defines scope rules that prevent agents from touching backend code, third-party scripts, or minified files.
-- **Compliance scoring** — `assets/reporting/compliance-config.json` weights findings by severity to produce a 0-100 score with grade thresholds.
-- **Persona impact groups** — `assets/reporting/wcag-reference.json` maps findings to disability personas (visual, motor, cognitive, etc.).
-
-**Output**: `a11y-findings.json` — enriched findings array with all intelligence fields.
-
-## Stage 3: Report builders
-
-All builders run in parallel when `--with-reports` is set. Each reads `a11y-findings.json` independently.
-
-| Builder | Script | Output | Audience |
-| :--- | :--- | :--- | :--- |
-| Markdown | `reports/builders/md.mjs` | `remediation.md` | AI agents |
-| HTML | `reports/builders/html.mjs` | `report.html` | Developers |
-| PDF | `reports/builders/pdf.mjs` | `report.pdf` | Stakeholders |
-| Checklist | `reports/builders/checklist.mjs` | `checklist.html` | QA / Developers |
-
-The `remediation.md` builder always runs (even without `--with-reports`) since it is the primary output for AI agent consumption.
-
-Renderers in `scripts/reports/renderers/` contain the actual rendering logic — builders are thin orchestrators that call renderers and write output files.
-
-## Assets and rule intelligence
-
-Assets are static JSON files bundled with the package under `assets/`. They are read at runtime by the analyzer and report builders.
-
-| Asset | Purpose |
-| :--- | :--- |
-| `reporting/compliance-config.json` | Score weights, grade thresholds, legal regulation list |
-| `reporting/wcag-reference.json` | WCAG criterion map, persona config, persona-rule mapping |
-| `reporting/manual-checks.json` | 41 manual checks for the WCAG checklist |
-| `discovery/crawler-config.json` | BFS crawl defaults (timeouts, concurrency) |
-| `discovery/stack-detection.json` | Framework/CMS DOM fingerprints |
-| `remediation/intelligence.json` | Per-rule fix intelligence for 106 axe-core rules |
-| `remediation/code-patterns.json` | Source code pattern definitions |
-| `remediation/guardrails.json` | Agent fix scope guardrails |
-| `remediation/axe-check-maps.json` | axe check-to-rule mapping |
-| `remediation/source-boundaries.json` | Framework-specific source file locations |
-
-## Programmatic API
-
-In addition to the CLI pipeline, the engine exports 7 functions via `scripts/index.mjs` for direct consumption by Node.js applications (e.g. `a11y-scanner`). These functions reuse the same internal renderers, assets, and enrichment logic as the CLI — no duplication.
-
-```
-scripts/index.mjs (public API)
-  ├── getEnrichedFindings()   ← uses asset-loader, intelligence.json, pa11y-config.json
-  ├── getAuditSummary()       ← uses compliance-config.json, wcag-reference.json
-  ├── getPDFReport()          ← uses reports/renderers/pdf.mjs + Playwright
-  ├── getHTMLReport()         ← uses reports/renderers/html.mjs + findings.mjs
-  ├── getChecklist()          ← uses reports/renderers/html.mjs (manual checks)
-  ├── getRemediationGuide()   ← uses reports/renderers/md.mjs
-  └── getSourcePatterns()     ← uses engine/source-scanner.mjs
-```
-
-### Key design decisions
-
-- **No filesystem output** — all API functions return data in memory (strings, Buffers, arrays). The consumer decides where to write.
-- **Payload in, results out** — functions accept the raw `{ findings, metadata }` payload that `a11y-findings.json` contains. No need to resolve paths or read files.
-- **`screenshotUrlBuilder` callback** — `getEnrichedFindings` accepts an optional function to transform raw screenshot paths (e.g. `screenshots/0-color-contrast.png`) into consumer-specific URLs (e.g. `/api/scan/{id}/screenshot?path=...`). This keeps URL construction out of the engine.
-- **CLI unaffected** — the `audit.mjs` orchestrator and all CLI builders continue to work exactly as before. The API is additive.
-
-## Execution model and timeouts
-
-`audit.mjs` spawns each stage as a child process via `node:child_process`. All child processes:
+## Data Contracts
 
-- Inherit the parent's environment
-- Run with `cwd` set to the package root (`SKILL_ROOT`)
-- Have a hard timeout of **15 minutes** (configurable via the `SCRIPT_TIMEOUT_MS` constant)
+Core artifacts generated by the pipeline:
 
-The orchestrator exits with code `1` if any stage fails. Individual stage timeouts are also enforced per page via `--timeout-ms` (default: 30s).
+- `progress.json`: step status (`page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`)
+- `a11y-scan-results.json`: merged runtime scan output per route
+- `a11y-findings.json`: enriched findings payload used by reports and API consumers
 
-If `node_modules/` is absent on first run, the orchestrator automatically installs dependencies via `pnpm install` (falls back to `npm install`).
+For schemas and field-level details, see [Output Artifacts](outputs.md).

package/docs/cli-handbook.md

@@ -1,6 +1,6 @@
 # CLI Handbook
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+**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)
 
 ---
 
@@ -24,10 +24,10 @@
 npx a11y-audit --base-url <url> [options]
 ```
 
-Or if installed locally:
+Or via pnpm in a project that depends on the engine:
 
 ```bash
-node node_modules/@diegovelasquezweb/a11y-engine/scripts/audit.mjs --base-url <url> [options]
+pnpm exec a11y-audit --base-url <url> [options]
 ```
 
 The only required flag is `--base-url`. All other flags are optional.
@@ -62,7 +62,7 @@ Controls what gets scanned.
 | `--max-routes` | `<num>` | `10` | Maximum unique same-origin paths to discover and scan. |
 | `--crawl-depth` | `<num>` | `2` | How deep to follow links during BFS discovery (1-3). Has no effect when `--routes` is set. |
 | `--routes` | `<csv>` | — | Explicit paths to scan (e.g. `/,/about,/contact`). Overrides auto-discovery entirely. |
-| `--project-dir` | `<path>` | — | Path to the audited project source. Enables the source code pattern scanner and framework auto-detection from `package.json`. |
+| `--project-dir` | `<path>` | — | Path to the audited project source. Enables the source code pattern scanner and framework auto-detection from package.json. |
 
 **Route discovery logic**:
 1. If the target has a `sitemap.xml`, all listed URLs are used (up to `--max-routes`).

package/docs/engine-manifest.md

@@ -0,0 +1,58 @@
+# Engine Manifest
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+
+---
+
+This document is the current technical inventory of the engine package.
+
+## 1) Source Modules
+
+| Path | Role |
+| :--- | :--- |
+| `src/index.mjs` | Public API entry point |
+| `src/index.d.mts` | Public TypeScript declarations |
+| `src/cli/audit.mjs` | CLI adapter and orchestration |
+| `src/core/utils.mjs` | Logging, JSON I/O, shared helpers |
+| `src/core/asset-loader.mjs` | Centralized asset map and loader |
+| `src/core/toolchain.mjs` | Environment/toolchain checks |
+| `src/pipeline/dom-scanner.mjs` | Runtime scan stage (axe/CDP/pa11y + merge) |
+| `src/enrichment/analyzer.mjs` | Finding enrichment and metadata synthesis |
+| `src/source-patterns/source-scanner.mjs` | Static source-pattern scanner |
+| `src/reports/html.mjs` | HTML report builder |
+| `src/reports/pdf.mjs` | PDF report builder |
+| `src/reports/md.mjs` | Markdown remediation builder |
+| `src/reports/checklist.mjs` | Manual checklist builder |
+| `src/reports/renderers/*.mjs` | Shared report rendering primitives |
+
+## 2) Asset Modules
+
+| Path | Purpose |
+| :--- | :--- |
+| `assets/discovery/crawler-config.mjs` | Crawl defaults and URL filters |
+| `assets/discovery/stack-detection.mjs` | Runtime/source stack detection rules |
+| `assets/scanning/cdp-checks.mjs` | CDP accessibility checks |
+| `assets/scanning/pa11y-config.mjs` | pa11y mappings, ignores, canonicalization |
+| `assets/remediation/intelligence.mjs` | Rule-level remediation intelligence |
+| `assets/remediation/guardrails.mjs` | Safe-fix and ownership guardrails |
+| `assets/remediation/code-patterns.mjs` | Source code pattern definitions |
+| `assets/remediation/source-boundaries.mjs` | Framework source boundaries |
+| `assets/remediation/axe-check-maps.mjs` | axe check-to-rule mappings |
+| `assets/reporting/compliance-config.mjs` | Compliance scoring configuration |
+| `assets/reporting/wcag-reference.mjs` | WCAG + persona mapping reference |
+| `assets/reporting/manual-checks.mjs` | Manual checklist data |
+
+## 3) Test Suite
+
+All tests live under `tests/` and run with Vitest.
+
+Current files:
+
+- `tests/asset-loader.test.mjs`
+- `tests/audit-summary.test.mjs`
+- `tests/enriched-findings.test.mjs`
+- `tests/reports-api.test.mjs`
+- `tests/reports-paths.test.mjs`
+- `tests/run-audit.integration.test.mjs`
+- `tests/source-patterns.test.mjs`
+- `tests/source-scanner-utils.test.mjs`

package/docs/outputs.md

@@ -1,6 +1,6 @@
 # Output Artifacts
 
-**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md)
+**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)
 
 ---
 
@@ -34,13 +34,11 @@ All artifacts are written to `.audit/` relative to the package root (`SKILL_ROOT
 └── screenshots/             # element screenshots per violation
 ```
 
-> When integrating the engine as a dependency (e.g. in `a11y-scanner`), use `fs.realpathSync` on the symlink path to resolve the real `.audit/` location — pnpm uses a deep `.pnpm/` directory structure, not the `node_modules/@scope/pkg` symlink.
-
 ---
 
 ## progress.json
 
-Real-time scan progress written by `scripts/engine/dom-scanner.mjs` as each engine runs. Used by integrations for live progress UI.
+Real-time scan progress written by `src/pipeline/dom-scanner.mjs` as each engine runs. Used by integrations for live progress UI.
 
 ```json
 {
@@ -73,7 +71,7 @@ Real-time scan progress written by `scripts/engine/dom-scanner.mjs` as each engi
 
 ## a11y-scan-results.json
 
-Merged results from all three engines (axe-core + CDP + pa11y) per route. Written by `scripts/engine/dom-scanner.mjs`.
+Merged results from all three engines (axe-core + CDP + pa11y) per route. Written by `src/pipeline/dom-scanner.mjs`.
 
 ```json
 {
@@ -100,7 +98,7 @@ This file is consumed by `analyzer.mjs` and also used by `--affected-only` to de
 
 ## a11y-findings.json
 
-The primary enriched data artifact. Written by `scripts/engine/analyzer.mjs`. This is the file consumed by all report builders.
+The primary enriched data artifact. Written by `src/enrichment/analyzer.mjs`. This is the file consumed by all report builders.
 
 ### Top-level structure
 
@@ -263,8 +261,8 @@ The engine exports functions that process scan data directly in memory — no fi
 
 ```ts
 import {
-  getEnrichedFindings,
-  getAuditSummary,
+  getFindings,
+  getOverview,
   getPDFReport,
   getHTMLReport,
   getChecklist,
@@ -276,12 +274,12 @@ import {
 const payload = JSON.parse(fs.readFileSync(findingsPath, "utf-8"));
 
 // Enrich findings with fix intelligence
-const findings = getEnrichedFindings(payload, {
+const findings = getFindings(payload, {
   screenshotUrlBuilder: (path) => `/api/screenshot?path=${encodeURIComponent(path)}`,
 });
 
 // Get full audit summary
-const summary = getAuditSummary(findings, payload);
+const summary = getOverview(findings, payload);
 
 // Generate reports
 const pdf = await getPDFReport(payload, { baseUrl: "https://example.com" });
@@ -311,7 +309,7 @@ if (fs.existsSync(progressPath)) {
 ### Parsing stdout markers
 
 ```bash
-OUTPUT=$(node scripts/audit.mjs --base-url https://example.com --with-reports --output ./audit/report.html)
+OUTPUT=$(npx a11y-audit --base-url https://example.com --with-reports --output ./audit/report.html)
 REMEDIATION_PATH=$(echo "$OUTPUT" | grep REMEDIATION_PATH | cut -d= -f2)
 REPORT_PATH=$(echo "$OUTPUT" | grep REPORT_PATH | cut -d= -f2)
 ```

package/docs/testing.md

@@ -0,0 +1,63 @@
+# Testing Strategy
+
+**Navigation**: [Home](../README.md) • [Architecture](architecture.md) • [CLI Handbook](cli-handbook.md) • [Output Artifacts](outputs.md) • [Engine Manifest](engine-manifest.md) • [Testing](testing.md)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Test Categories](#test-categories)
+- [Run Commands](#run-commands)
+
+## Overview
+
+- **Framework**: Vitest
+- **Command**: `pnpm test`
+- **Current suite**: 8 files, 26 tests
+
+The suite focuses on regression protection for architecture changes, public API contracts, and critical report-generation paths.
+
+## Test Categories
+
+### 1) Asset loading and compatibility
+
+- `tests/asset-loader.test.mjs`
+- Verifies all asset groups load correctly.
+- Verifies compatibility alias: `ASSET_PATHS.engine` -> `ASSET_PATHS.scanning`.
+
+### 2) Enrichment and summary contracts
+
+- `tests/enriched-findings.test.mjs`
+- `tests/audit-summary.test.mjs`
+- Verifies canonicalization, normalization, sorting, effort inference, quick wins, and detected stack output.
+
+### 3) Report API and import safety
+
+- `tests/reports-api.test.mjs`
+- `tests/reports-paths.test.mjs`
+- Verifies report APIs return expected output types and protects against broken relative imports after refactors.
+
+### 4) Source-pattern behavior
+
+- `tests/source-patterns.test.mjs`
+- `tests/source-scanner-utils.test.mjs`
+- Verifies edge behavior for pattern filtering and source scanner utility functions.
+
+### 5) Integration tests (no network)
+
+- `tests/run-audit.integration.test.mjs`
+- Mocks scanner/analyzer modules to verify:
+  - `runAudit` progress event order
+  - scanner/analyzer wiring
+  - output payload shape
+
+## Run Commands
+
+```bash
+# Full suite
+pnpm test
+
+# Run a single file
+pnpm vitest run tests/run-audit.integration.test.mjs
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "WCAG 2.2 AA accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",
@@ -26,17 +26,14 @@
   },
   "files": [
     "src/**",
-    "assets/source/**",
-    "assets/generated/**",
+    "assets/**",
     "docs/**",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "sync-assets": "node src/sync-assets.mjs",
-    "test": "vitest run",
-    "prepublishOnly": "node src/sync-assets.mjs"
+    "test": "vitest run"
   },
   "dependencies": {
     "@axe-core/playwright": "^4.11.1",

package/src/core/asset-loader.mjs

@@ -5,18 +5,18 @@
  * This ensures bundlers (Turbopack, Webpack) can trace them automatically.
  */
 
-import crawlerConfig from "../../assets/generated/discovery/crawler-config.mjs";
-import stackDetection from "../../assets/generated/discovery/stack-detection.mjs";
-import cdpChecks from "../../assets/generated/engine/cdp-checks.mjs";
-import pa11yConfig from "../../assets/generated/engine/pa11y-config.mjs";
-import axeCheckMaps from "../../assets/generated/remediation/axe-check-maps.mjs";
-import codePatterns from "../../assets/generated/remediation/code-patterns.mjs";
-import guardrails from "../../assets/generated/remediation/guardrails.mjs";
-import intelligence from "../../assets/generated/remediation/intelligence.mjs";
-import sourceBoundaries from "../../assets/generated/remediation/source-boundaries.mjs";
-import complianceConfig from "../../assets/generated/reporting/compliance-config.mjs";
-import manualChecks from "../../assets/generated/reporting/manual-checks.mjs";
-import wcagReference from "../../assets/generated/reporting/wcag-reference.mjs";
+import crawlerConfig from "../../assets/discovery/crawler-config.mjs";
+import stackDetection from "../../assets/discovery/stack-detection.mjs";
+import cdpChecks from "../../assets/scanning/cdp-checks.mjs";
+import pa11yConfig from "../../assets/scanning/pa11y-config.mjs";
+import axeCheckMaps from "../../assets/remediation/axe-check-maps.mjs";
+import codePatterns from "../../assets/remediation/code-patterns.mjs";
+import guardrails from "../../assets/remediation/guardrails.mjs";
+import intelligence from "../../assets/remediation/intelligence.mjs";
+import sourceBoundaries from "../../assets/remediation/source-boundaries.mjs";
+import complianceConfig from "../../assets/reporting/compliance-config.mjs";
+import manualChecks from "../../assets/reporting/manual-checks.mjs";
+import wcagReference from "../../assets/reporting/wcag-reference.mjs";
 
 /**
  * Pre-loaded asset map. Each value is the parsed JSON object, ready to use.
@@ -26,6 +26,10 @@ export const ASSETS = {
     crawlerConfig,
     stackDetection,
   },
+  scanning: {
+    cdpChecks,
+    pa11yConfig,
+  },
   engine: {
     cdpChecks,
     pa11yConfig,
@@ -54,9 +58,13 @@ export const ASSET_PATHS = {
     crawlerConfig: "discovery.crawlerConfig",
     stackDetection: "discovery.stackDetection",
   },
+  scanning: {
+    cdpChecks: "scanning.cdpChecks",
+    pa11yConfig: "scanning.pa11yConfig",
+  },
   engine: {
-    cdpChecks: "engine.cdpChecks",
-    pa11yConfig: "engine.pa11yConfig",
+    cdpChecks: "scanning.cdpChecks",
+    pa11yConfig: "scanning.pa11yConfig",
   },
   remediation: {
     intelligence: "remediation.intelligence",