hpcompaq435/accessaudit-scanner

AccessAudit — Scanner Engine (Slice 1 of 5)

The core of AccessAudit: give it a URL, it renders the page in a real browser, runs axe-core against WCAG 2.0 / 2.1 / 2.2 rules, and returns structured violations plus a transparent 0–100 score. This is the piece everything else builds on.

Honesty note: automated testing catches a large share of WCAG issues but never all of them. This tool is a detection + monitoring aid, not a guarantee of legal compliance. Complex issues still need human review.

Requirements

• —Node.js 20+
• —This runs a headless browser, so it needs a Node host (your laptop, Railway, Render, Fly, or Modal). It will not run on Vercel serverless functions as-is.

Setup

npm install
npx playwright install chromium   # downloads the headless browser (~150MB)

Run

# Scan a live site
npm run scan -- https://example.com

# Scan the included broken fixture (works offline, good first test)
npm run scan -- ./fixtures/sample.html

You'll see a summary in the terminal and a full scan-result.json written to the project root.

Remediation (Slice 2) — turn violations into plain-English fixes

After a scan, enrich scan-result.json with prioritized, copy-paste fixes:

npm run remediate

Writes report.json — the scan plus a remediation block on every violation, sorted by priority (now → soon → later).

Remediation is rule-based and deterministic — a curated library of fixes keyed by axe-core rule id, with a sensible generic fallback (built from axe's own description + help URL) for any rule not in the library. This means:

• —No API key, no cost, no rate limits — nothing is sent to a third party.
• —No data leaves the server — good for privacy-sensitive (e.g. GDPR) clients.
• —No hallucinated compliance advice — safer for a compliance product.

To extend coverage, add an entry to TEMPLATES in src/remediate.ts.

Run as a service (Slice 3) — so the web app can call it

npm run serve            # starts an HTTP server on :8080
# POST /scan { "url": "https://example.com" }  ->  full enriched report
# GET  /health           # -> { ok: true }

Set SCANNER_API_KEY to require an x-api-key header (recommended in production). Deploy with the included Dockerfile (Playwright base image, browsers preinstalled) to Railway / Render / Fly — not Vercel serverless.

Test (no browser needed)

npm run test:score
npm run test:remediate

What you get (scan-result.json shape)

{
  "url": "...",
  "scannedAt": "2026-05-30T...Z",
  "score": 72,
  "summary": { "critical": 1, "serious": 3, "moderate": 2, "minor": 4, "total": 10 },
  "violations": [
    {
      "id": "image-alt",
      "impact": "critical",
      "description": "Ensures <img> elements have alternate text...",
      "help": "Images must have alternate text",
      "helpUrl": "https://dequeuniversity.com/rules/axe/4.10/image-alt",
      "wcagTags": ["wcag2a", "wcag111"],
      "nodeCount": 2,
      "nodes": [{ "target": "img", "html": "<img src=...>", "failureSummary": "..." }]
    }
  ]
}

This JSON is the contract the next slices consume.

Architecture (the whole app)

Next.js (UI + API)  ──►  Scanner worker (THIS repo, Node + Playwright)
   on Vercel                on Railway/Render/Fly/Modal
       │                          │
       ├─► Supabase (auth, store scans, subscriptions)
       ├─► Claude API (turn violations into plain-English fixes)  [Slice 2]
       └─► Lemon Squeezy webhook (billing + plan gating)          [Slice 5]

Slice roadmap

1. 1.Scanner engine — ✅ this repo (URL → structured WCAG violations + score)
2. 2.Remediation AI — ✅ feed each violation to the Claude API → plain-English, prioritized, copy-paste fixes (src/remediate.ts).
3. 3.Web app — Next.js + Supabase: auth, run scans, save history, dashboard. (Build with the frontend-design guidance.)
4. 4.Reports — generate the WCAG 2.2 / EAA PDF report + accessibility statement.
5. 5.Billing — Lemon Squeezy product + webhook, plan gating (Free/Starter/Pro/Agency).

Build each slice, run it, fix what breaks, commit — then start the next.