A11y Audit

// Sample React component with intentional a11y issues for testing
import React from 'react';

export function UserCard({ user, onEdit, onDelete }) {
  return (
    <div className="card" onClick={() => onEdit(user.id)}>
      <img src={user.avatar} />
      <div className="name">{user.name}</div>
      <div className="email">{user.email}</div>
      <div className="actions">
        <div onClick={() => onDelete(user.id)} style={{ color: '#aaa', cursor: 'pointer' }}>
          Delete
        </div>
        <a href="#">Edit</a>
      </div>
      <input placeholder="Add note" />
    </div>
  );
}

export function SearchBar() {
  return (
    <div>
      <input type="text" placeholder="Search..." />
      <div onClick={() => alert('searching')} tabIndex={5}>
        🔍
      </div>
    </div>
  );
}

export function DataTable({ rows }) {
  return (
    <table>
      <tr>
        <td><b>Name</b></td>
        <td><b>Email</b></td>
        <td><b>Status</b></td>
      </tr>
      {rows.map((row) => (
        <tr key={row.id}>
          <td>{row.name}</td>
          <td>{row.email}</td>
          <td style={{ color: row.active ? 'green' : 'red' }}>
            {row.active ? '●' : '●'}
          </td>
        </tr>
      ))}
    </table>
  );
}

Contrast Check: #777777 on #ffffff

  Foreground: #777777 (r=119, g=119, b=119)
  Background: #ffffff (r=255, g=255, b=255)
  Contrast Ratio: 4.48:1

  Normal text (4.5:1 required):
    AA:  FAIL (4.48 < 4.5)
    AAA: FAIL (4.48 < 7.0)

  Large text (3.0:1 required):
    AA:  PASS (4.48 >= 3.0)
    AAA: FAIL (4.48 < 4.5)

  UI components (3.0:1 required):
    AA:  PASS (4.48 >= 3.0)

  Verdict: FAIL — does not meet AA for normal text

---

Contrast Check: #1a1a2e on #ffffff

  Foreground: #1a1a2e (r=26, g=26, b=46)
  Background: #ffffff (r=255, g=255, b=255)
  Contrast Ratio: 17.06:1

  Normal text (4.5:1 required):
    AA:  PASS
    AAA: PASS

  Large text (3.0:1 required):
    AA:  PASS
    AAA: PASS

  UI components (3.0:1 required):
    AA:  PASS

  Verdict: PASS — meets AAA for all categories

{
  "summary": {
    "files_scanned": 1,
    "files_with_issues": 1,
    "total_issues": 9,
    "critical": 3,
    "serious": 4,
    "moderate": 2,
    "minor": 0,
    "verdict": "FAIL"
  },
  "findings": [
    {
      "severity": "critical",
      "category": "IMG-ALT",
      "file": "sample-component.tsx",
      "line": 7,
      "code": "<img src={user.avatar} />",
      "wcag": "1.1.1",
      "message": "Image missing alt attribute",
      "fix": "Add alt text: alt=\"description of image\""
    },
    {
      "severity": "critical",
      "category": "KB-CLICK",
      "file": "sample-component.tsx",
      "line": 5,
      "code": "<div className=\"card\" onClick={() => onEdit(user.id)}>",
      "wcag": "2.1.1",
      "message": "Click handler on non-interactive element without keyboard support",
      "fix": "Use <button> or add role=\"button\", tabIndex={0}, onKeyDown"
    }
  ]
}

#!/usr/bin/env python3
"""WCAG 2.2 Accessibility Scanner for Frontend Codebases.

Scans HTML, JSX, TSX, Vue, Svelte, and CSS files for accessibility
violations across 10 categories: images, forms, headings, landmarks,
keyboard, ARIA, color/contrast, links, tables, and media.

Usage:
    python a11y_scanner.py /path/to/project
    python a11y_scanner.py /path/to/project --json
    python a11y_scanner.py /path/to/project --severity critical,serious
    python a11y_scanner.py /path/to/project --format json
"""

import argparse
import json
import os
import re
import sys
from dataclasses import dataclass, asdict
from typing import List, Optional


@dataclass
class Finding:
    """A single accessibility finding."""
    rule_id: str
    category: str
    severity: str
    message: str
    file: str
    line: int
    snippet: str
    wcag_criterion: str
    fix: str


# ---------------------------------------------------------------------------
# Rule definitions: each returns a list of Finding from a single file
# ---------------------------------------------------------------------------

VALID_ARIA_ATTRS = {
    "aria-activedescendant", "aria-atomic", "aria-autocomplete", "aria-busy",
    "aria-checked", "aria-colcount", "aria-colindex", "aria-colspan",
    "aria-controls", "aria-current", "aria-describedby", "aria-details",
    "aria-disabled", "aria-dropeffect", "aria-errormessage", "aria-expanded",
    "aria-flowto", "aria-grabbed", "aria-haspopup", "aria-hidden",
    "aria-invalid", "aria-keyshortcuts", "aria-label", "aria-labelledby",
    "aria-level", "aria-live", "aria-modal", "aria-multiline",
    "aria-multiselectable", "aria-orientation", "aria-owns", "aria-placeholder",
    "aria-posinset", "aria-pressed", "aria-readonly", "aria-relevant",
    "aria-required", "aria-roledescription", "aria-rowcount", "aria-rowindex",
    "aria-rowspan", "aria-selected", "aria-setsize", "aria-sort",
    "aria-valuemax", "aria-valuemin", "aria-valuenow", "aria-valuetext",
    "aria-braillelabel", "aria-brailleroledescription", "aria-description",
}

BAD_LINK_TEXT = re.compile(
    r">\s*(click here|here|read more|more|link|this)\s*<", re.IGNORECASE
)

TAG_RE = re.compile(r"<(\w[\w-]*)\b([^>]*)(/?)>", re.DOTALL)
ATTR_RE = re.compile(r"""([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))""")
ATTR_BOOL_RE = re.compile(r"\b([\w:.-]+)(?=\s|/?>|$)")
INLINE_COLOR_RE = re.compile(
    r'style\s*=\s*["\'][^"\']*\bcolor\s*:', re.IGNORECASE
)
ARIA_ATTR_RE = re.compile(r"\baria-[\w-]+")


def _attrs(attr_str: str) -> dict:
    """Parse HTML/JSX attribute string into a dict."""
    result = {}
    for m in ATTR_RE.finditer(attr_str):
        result[m.group(1)] = m.group(2) or m.group(3) or m.group(4) or ""
    # boolean attrs
    cleaned = ATTR_RE.sub("", attr_str)
    for m in ATTR_BOOL_RE.finditer(cleaned):
        name = m.group(1)
        if name not in result and not name.startswith("/"):
            result[name] = True
    return result


def _snippet(line_text: str) -> str:
    """Trim a line for display as a code snippet."""
    s = line_text.rstrip("\n\r")
    return s[:120] + "..." if len(s) > 120 else s


def _find(rule_id, cat, sev, msg, fp, ln, snip, wcag, fix):
    return Finding(rule_id, cat, sev, msg, fp, ln, snip, wcag, fix)


# ---------- Images ----------------------------------------------------------

def check_img_missing_alt(tag, attrs, fp, ln, snip):
    if tag == "img" and "alt" not in attrs:
        return _find("img-alt-missing", "images", "critical",
                      "<img> missing alt attribute",
                      fp, ln, snip, "1.1.1 Non-text Content",
                      "Add alt=\"description\" or alt=\"\" for decorative images.")

def check_img_empty_alt_informative(tag, attrs, fp, ln, snip):
    if tag == "img" and attrs.get("alt") == "" and attrs.get("src", ""):
        src = attrs.get("src", "")
        if not any(kw in src.lower() for kw in ("spacer", "border", "decorat", "bg")):
            return _find("img-alt-empty-informative", "images", "serious",
                          "<img> has empty alt but may be informative",
                          fp, ln, snip, "1.1.1 Non-text Content",
                          "If image conveys information, add descriptive alt text.")

def check_img_decorative_has_alt(tag, attrs, fp, ln, snip):
    if tag == "img" and attrs.get("role") == "presentation" and attrs.get("alt", "") != "":
        return _find("img-decorative-alt", "images", "moderate",
                      "Decorative image (role=presentation) should have alt=\"\"",
                      fp, ln, snip, "1.1.1 Non-text Content",
                      "Set alt=\"\" on decorative images with role=presentation.")


# ---------- Forms -----------------------------------------------------------

def check_input_missing_label(tag, attrs, fp, ln, snip):
    input_types = {"text", "email", "password", "search", "tel", "url", "number", "date"}
    if tag == "input" and attrs.get("type", "text") in input_types:
        if "aria-label" not in attrs and "aria-labelledby" not in attrs and "id" not in attrs:
            return _find("form-input-no-label", "forms", "critical",
                          "<input> has no id, aria-label, or aria-labelledby",
                          fp, ln, snip, "1.3.1 Info and Relationships",
                          "Add id + <label for>, or aria-label attribute.")

def check_input_no_aria_label(tag, attrs, fp, ln, snip):
    if tag in ("select", "textarea"):
        if "aria-label" not in attrs and "aria-labelledby" not in attrs and "id" not in attrs:
            return _find("form-select-no-label", "forms", "critical",
                          f"<{tag}> has no accessible name",
                          fp, ln, snip, "4.1.2 Name, Role, Value",
                          f"Add aria-label or id + <label for> to <{tag}>.")

def check_orphan_label(lines, fp):
    """Labels whose 'for' points to a non-existent id."""
    findings = []
    ids = set()
    label_fors = []
    for ln, line in enumerate(lines, 1):
        for m in re.finditer(r'\bid\s*=\s*["\']([^"\']+)["\']', line):
            ids.add(m.group(1))
        for m in re.finditer(r'<label[^>]*\bfor\s*=\s*["\']([^"\']+)["\']', line):
            label_fors.append((ln, m.group(1), line))
    for ln, for_val, line in label_fors:
        if for_val not in ids:
            findings.append(_find("form-orphan-label", "forms", "serious",
                                  f"<label for=\"{for_val}\"> references non-existent id",
                                  fp, ln, _snippet(line), "1.3.1 Info and Relationships",
                                  f"Ensure an element with id=\"{for_val}\" exists."))
    return findings

def check_fieldset_legend(lines, fp):
    """Radio/checkbox groups without fieldset."""
    findings = []
    radio_lines = []
    has_fieldset = any("fieldset" in l.lower() for l in lines)
    for ln, line in enumerate(lines, 1):
        if re.search(r'type\s*=\s*["\'](?:radio|checkbox)["\']', line, re.I):
            radio_lines.append((ln, line))
    if radio_lines and not has_fieldset:
        ln, line = radio_lines[0]
        findings.append(_find("form-missing-fieldset", "forms", "serious",
                              "Radio/checkbox group without <fieldset>/<legend>",
                              fp, ln, _snippet(line), "1.3.1 Info and Relationships",
                              "Wrap related radio/checkbox inputs in <fieldset> with <legend>."))
    return findings


# ---------- Headings --------------------------------------------------------

def check_headings(lines, fp):
    findings = []
    heading_levels = []
    for ln, line in enumerate(lines, 1):
        for m in re.finditer(r"<[hH]([1-6])\b", line):
            heading_levels.append((int(m.group(1)), ln, line))
    if not heading_levels:
        return findings
    # Missing h1
    levels_seen = {h[0] for h in heading_levels}
    if 1 not in levels_seen and any(l <= 3 for l in levels_seen):
        findings.append(_find("heading-missing-h1", "headings", "serious",
                              "Page has headings but no <h1>",
                              fp, heading_levels[0][1], _snippet(heading_levels[0][2]),
                              "1.3.1 Info and Relationships",
                              "Add a single <h1> as the main page heading."))
    # Multiple h1s
    h1_lines = [(ln, line) for lvl, ln, line in heading_levels if lvl == 1]
    if len(h1_lines) > 1:
        findings.append(_find("heading-multiple-h1", "headings", "moderate",
                              f"Page has {len(h1_lines)} <h1> elements",
                              fp, h1_lines[1][0], _snippet(h1_lines[1][1]),
                              "1.3.1 Info and Relationships",
                              "Use a single <h1> per page. Demote others to <h2>+."))
    # Skipped levels
    prev_level = 0
    for lvl, ln, line in heading_levels:
        if prev_level > 0 and lvl > prev_level + 1:
            findings.append(_find("heading-skipped", "headings", "moderate",
                                  f"Heading level skips from h{prev_level} to h{lvl}",
                                  fp, ln, _snippet(line),
                                  "1.3.1 Info and Relationships",
                                  f"Use <h{prev_level + 1}> instead of <h{lvl}>."))
        prev_level = lvl
    return findings


# ---------- Landmarks -------------------------------------------------------

def check_landmarks(lines, fp):
    findings = []
    content = "\n".join(lines)
    # Missing main landmark
    if not re.search(r'<main\b|role\s*=\s*["\']main["\']', content, re.I):
        findings.append(_find("landmark-no-main", "landmarks", "serious",
                              "Page missing <main> landmark",
                              fp, 1, "", "1.3.1 Info and Relationships",
                              "Add a <main> element to wrap primary content."))
    # Missing nav
    if not re.search(r'<nav\b|role\s*=\s*["\']navigation["\']', content, re.I):
        findings.append(_find("landmark-no-nav", "landmarks", "moderate",
                              "Page missing <nav> landmark",
                              fp, 1, "", "1.3.1 Info and Relationships",
                              "Add <nav> for primary navigation blocks."))
    # Missing skip link
    if not re.search(r'skip.{0,10}(nav|main|content)', content, re.I):
        findings.append(_find("landmark-no-skip-link", "landmarks", "serious",
                              "Page missing skip navigation link",
                              fp, 1, "", "2.4.1 Bypass Blocks",
                              "Add <a href=\"#main\">Skip to main content</a> as first focusable element."))
    return findings


# ---------- Keyboard --------------------------------------------------------

def check_tabindex_positive(tag, attrs, fp, ln, snip):
    ti = attrs.get("tabindex", "")
    if isinstance(ti, str) and ti.lstrip("-").isdigit() and int(ti) > 0:
        return _find("keyboard-tabindex-positive", "keyboard", "serious",
                      f"tabindex={ti} creates unexpected tab order",
                      fp, ln, snip, "2.4.3 Focus Order",
                      "Use tabindex=\"0\" or tabindex=\"-1\" instead of positive values.")

def check_click_no_keyboard(tag, attrs, fp, ln, snip):
    has_click = "onClick" in attrs or "onclick" in attrs or "@click" in attrs or "on:click" in attrs
    has_key = any(k for k in attrs if "keydown" in k.lower() or "keyup" in k.lower() or "keypress" in k.lower())
    if tag in ("div", "span", "td", "li", "p", "section") and has_click and not has_key:
        if attrs.get("role") not in ("button", "link", "tab", "menuitem"):
            return _find("keyboard-click-no-key", "keyboard", "critical",
                          f"<{tag}> has click handler but no keyboard handler",
                          fp, ln, snip, "2.1.1 Keyboard",
                          f"Add onKeyDown handler or use <button> instead of <{tag}>.")

def check_autofocus_misuse(tag, attrs, fp, ln, snip):
    if "autofocus" in attrs or "autoFocus" in attrs:
        if tag not in ("input", "textarea", "select"):
            return _find("keyboard-autofocus", "keyboard", "moderate",
                          f"autofocus on <{tag}> can disorient screen reader users",
                          fp, ln, snip, "3.2.1 On Focus",
                          "Avoid autofocus on non-input elements. Use focus management instead.")


# ---------- ARIA ------------------------------------------------------------

def check_invalid_aria(tag, attrs, fp, ln, snip):
    findings = []
    for key in attrs:
        if key.startswith("aria-") and key.lower() not in VALID_ARIA_ATTRS:
            findings.append(_find("aria-invalid-attr", "aria", "serious",
                                  f"Invalid ARIA attribute: {key}",
                                  fp, ln, snip, "4.1.2 Name, Role, Value",
                                  f"Remove or replace \"{key}\" with a valid ARIA attribute."))
    return findings

def check_aria_hidden_focusable(tag, attrs, fp, ln, snip):
    if attrs.get("aria-hidden") in ("true", True):
        focusable_tags = {"a", "button", "input", "select", "textarea"}
        if tag in focusable_tags or (isinstance(attrs.get("tabindex", ""), str) and
                                     attrs.get("tabindex", "-1") != "-1"):
            return _find("aria-hidden-focusable", "aria", "critical",
                          f"aria-hidden=\"true\" on focusable <{tag}>",
                          fp, ln, snip, "4.1.2 Name, Role, Value",
                          "Remove aria-hidden or make element non-focusable (tabindex=\"-1\").")

def check_aria_live_missing(lines, fp):
    """Alert/status roles or live regions without aria-live."""
    findings = []
    for ln, line in enumerate(lines, 1):
        if re.search(r'role\s*=\s*["\'](?:alert|status)["\']', line, re.I):
            if "aria-live" not in line:
                findings.append(_find("aria-live-missing", "aria", "serious",
                                      "role=alert/status without explicit aria-live",
                                      fp, ln, _snippet(line),
                                      "4.1.3 Status Messages",
                                      "Add aria-live=\"assertive\" (alert) or aria-live=\"polite\" (status)."))
    return findings


# ---------- Color/Contrast --------------------------------------------------

def check_inline_color(tag, attrs, fp, ln, snip):
    style = attrs.get("style", "")
    if isinstance(style, str) and re.search(r"\bcolor\s*:", style, re.I):
        if not re.search(r"background", style, re.I):
            return _find("color-inline-no-bg", "color", "moderate",
                          "Inline color set without background — contrast may be insufficient",
                          fp, ln, snip, "1.4.3 Contrast (Minimum)",
                          "Ensure foreground and background colors meet 4.5:1 contrast ratio.")

def check_text_over_image(lines, fp):
    """Detects patterns where text is positioned over background images without overlay."""
    findings = []
    for ln, line in enumerate(lines, 1):
        if re.search(r"background-image\s*:", line, re.I):
            if not re.search(r"(overlay|rgba|linear-gradient)", line, re.I):
                findings.append(_find("color-text-over-image", "color", "serious",
                                      "Background image without contrast overlay for text",
                                      fp, ln, _snippet(line),
                                      "1.4.3 Contrast (Minimum)",
                                      "Add a semi-transparent overlay or ensure text contrast."))
    return findings


# ---------- Links -----------------------------------------------------------

def check_empty_link(tag, attrs, fp, ln, snip):
    if tag == "a" and not attrs.get("aria-label") and not attrs.get("aria-labelledby"):
        return None  # handled by line-level check below

def check_empty_links_line(lines, fp):
    findings = []
    for ln, line in enumerate(lines, 1):
        # <a ...></a> or <a ...> </a>
        if re.search(r"<a\b[^>]*>\s*</a>", line, re.I):
            if "aria-label" not in line and "aria-labelledby" not in line:
                findings.append(_find("link-empty", "links", "critical",
                                      "Empty link — no text or accessible name",
                                      fp, ln, _snippet(line), "2.4.4 Link Purpose",
                                      "Add link text or aria-label."))
        # Bad link text
        if BAD_LINK_TEXT.search(line):
            findings.append(_find("link-bad-text", "links", "serious",
                                  "Link uses vague text like 'click here'",
                                  fp, ln, _snippet(line), "2.4.4 Link Purpose",
                                  "Use descriptive link text that makes sense out of context."))
    return findings

def check_same_page_link(tag, attrs, fp, ln, snip):
    href = attrs.get("href", "")
    if tag == "a" and isinstance(href, str) and href == "#":
        return _find("link-empty-fragment", "links", "moderate",
                      "Link with href=\"#\" — use a button or valid fragment",
                      fp, ln, snip, "2.4.4 Link Purpose",
                      "Use <button> for actions or href=\"#section-id\" for anchors.")


# ---------- Tables ----------------------------------------------------------

def check_table_headers(lines, fp):
    findings = []
    in_table = False
    table_start = 0
    has_th = False
    has_caption = False
    has_aria_label = False
    for ln, line in enumerate(lines, 1):
        if re.search(r"<table\b", line, re.I):
            in_table = True
            table_start = ln
            has_th = False
            has_caption = False
            has_aria_label = "aria-label" in line
        if in_table:
            if "<th" in line.lower():
                has_th = True
            if "<caption" in line.lower():
                has_caption = True
            if re.search(r"</table>", line, re.I):
                if not has_th:
                    findings.append(_find("table-no-headers", "tables", "serious",
                                          "<table> has no <th> header cells",
                                          fp, table_start, _snippet(lines[table_start - 1]),
                                          "1.3.1 Info and Relationships",
                                          "Add <th> elements to identify column/row headers."))
                if not has_caption and not has_aria_label:
                    findings.append(_find("table-no-caption", "tables", "moderate",
                                          "<table> missing <caption> or aria-label",
                                          fp, table_start, _snippet(lines[table_start - 1]),
                                          "1.3.1 Info and Relationships",
                                          "Add <caption> or aria-label to describe the table."))
                in_table = False
    return findings


# ---------- Media -----------------------------------------------------------

def check_media_captions(tag, attrs, fp, ln, snip):
    if tag == "video":
        return None  # handled at block level

def check_media_captions_block(lines, fp):
    findings = []
    in_video = False
    video_start = 0
    has_track = False
    has_controls = False
    has_autoplay = False
    for ln, line in enumerate(lines, 1):
        if re.search(r"<video\b", line, re.I):
            in_video = True
            video_start = ln
            has_track = False
            has_controls = "controls" in line.lower()
            has_autoplay = "autoplay" in line.lower()
        if in_video:
            if re.search(r'<track\b[^>]*kind\s*=\s*["\']captions["\']', line, re.I):
                has_track = True
            if "controls" in line.lower():
                has_controls = True
            if re.search(r"</video>", line, re.I) or (re.search(r"<video\b", line, re.I) and "/>" in line):
                if not has_track:
                    findings.append(_find("media-no-captions", "media", "critical",
                                          "<video> missing captions track",
                                          fp, video_start, _snippet(lines[video_start - 1]),
                                          "1.2.2 Captions (Prerecorded)",
                                          "Add <track kind=\"captions\" src=\"...\" srclang=\"en\">."))
                if has_autoplay and not has_controls:
                    findings.append(_find("media-autoplay-no-controls", "media", "serious",
                                          "<video> has autoplay without controls",
                                          fp, video_start, _snippet(lines[video_start - 1]),
                                          "1.4.2 Audio Control",
                                          "Add the controls attribute so users can pause/stop."))
                in_video = False
    # Single-line video tags
    for ln, line in enumerate(lines, 1):
        if re.search(r"<audio\b", line, re.I):
            if "autoplay" in line.lower() and "controls" not in line.lower():
                findings.append(_find("media-audio-autoplay", "media", "serious",
                                      "<audio> has autoplay without controls",
                                      fp, ln, _snippet(line), "1.4.2 Audio Control",
                                      "Add the controls attribute to <audio>."))
    return findings


# ---------------------------------------------------------------------------
# Scanner engine
# ---------------------------------------------------------------------------

SUPPORTED_EXTENSIONS = {".html", ".htm", ".jsx", ".tsx", ".vue", ".svelte", ".css"}

TAG_LEVEL_CHECKS = [
    check_img_missing_alt,
    check_img_empty_alt_informative,
    check_img_decorative_has_alt,
    check_input_missing_label,
    check_input_no_aria_label,
    check_tabindex_positive,
    check_click_no_keyboard,
    check_autofocus_misuse,
    check_aria_hidden_focusable,
    check_inline_color,
    check_same_page_link,
]

TAG_LEVEL_MULTI_CHECKS = [
    check_invalid_aria,
]


def scan_file(filepath: str) -> List[Finding]:
    """Scan a single file and return all findings."""
    findings: List[Finding] = []
    try:
        with open(filepath, "r", encoding="utf-8", errors="replace") as f:
            lines = f.readlines()
    except (OSError, IOError):
        return findings

    # Tag-level checks
    for ln, line in enumerate(lines, 1):
        for m in TAG_RE.finditer(line):
            tag = m.group(1).lower()
            attr_str = m.group(2)
            attrs = _attrs(attr_str)
            snip = _snippet(line)
            for check in TAG_LEVEL_CHECKS:
                result = check(tag, attrs, filepath, ln, snip)
                if result:
                    findings.append(result)
            for check in TAG_LEVEL_MULTI_CHECKS:
                results = check(tag, attrs, filepath, ln, snip)
                if results:
                    findings.extend(results)

    # File-level / multi-line checks
    findings.extend(check_orphan_label(lines, filepath))
    findings.extend(check_fieldset_legend(lines, filepath))
    findings.extend(check_headings(lines, filepath))
    findings.extend(check_landmarks(lines, filepath))
    findings.extend(check_aria_live_missing(lines, filepath))
    findings.extend(check_text_over_image(lines, filepath))
    findings.extend(check_empty_links_line(lines, filepath))
    findings.extend(check_table_headers(lines, filepath))
    findings.extend(check_media_captions_block(lines, filepath))

    return findings


def collect_files(path: str) -> List[str]:
    """Recursively collect scannable files under path."""
    files = []
    if os.path.isfile(path):
        _, ext = os.path.splitext(path)
        if ext.lower() in SUPPORTED_EXTENSIONS:
            files.append(path)
        return files
    for root, dirs, filenames in os.walk(path):
        # Skip common non-source directories
        dirs[:] = [d for d in dirs if d not in (
            "node_modules", ".git", "dist", "build", "__pycache__",
            ".next", ".nuxt", "vendor", "coverage"
        )]
        for fname in filenames:
            _, ext = os.path.splitext(fname)
            if ext.lower() in SUPPORTED_EXTENSIONS:
                files.append(os.path.join(root, fname))
    files.sort()
    return files


# ---------------------------------------------------------------------------
# Output formatting
# ---------------------------------------------------------------------------

SEVERITY_ORDER = {"critical": 0, "serious": 1, "moderate": 2, "minor": 3}


def format_human(findings: List[Finding], files_scanned: int) -> str:
    """Format findings as human-readable text report."""
    if not findings:
        return (f"Scanned {files_scanned} file(s) -- no accessibility issues found.\n"
                "All checks passed.")

    lines = []
    lines.append(f"WCAG 2.2 Accessibility Scan Results")
    lines.append(f"{'=' * 50}")
    lines.append(f"Files scanned: {files_scanned}")
    lines.append(f"Issues found:  {len(findings)}")

    # Summary by severity
    severity_counts = {}
    for f in findings:
        severity_counts[f.severity] = severity_counts.get(f.severity, 0) + 1
    for sev in ("critical", "serious", "moderate", "minor"):
        if sev in severity_counts:
            lines.append(f"  {sev.upper():10s}: {severity_counts[sev]}")
    lines.append("")

    # Summary by category
    cat_counts = {}
    for f in findings:
        cat_counts[f.category] = cat_counts.get(f.category, 0) + 1
    lines.append("By category:")
    for cat in sorted(cat_counts, key=lambda c: -cat_counts[c]):
        lines.append(f"  {cat:20s}: {cat_counts[cat]}")
    lines.append("")

    # Detailed findings sorted by severity then file
    sorted_findings = sorted(findings, key=lambda f: (SEVERITY_ORDER.get(f.severity, 9), f.file, f.line))
    for i, f in enumerate(sorted_findings, 1):
        lines.append(f"[{f.severity.upper()}] {f.rule_id}")
        lines.append(f"  File: {f.file}:{f.line}")
        lines.append(f"  WCAG: {f.wcag_criterion}")
        lines.append(f"  Issue: {f.message}")
        if f.snippet:
            lines.append(f"  Code:  {f.snippet}")
        lines.append(f"  Fix:   {f.fix}")
        lines.append("")

    return "\n".join(lines)


def format_json(findings: List[Finding], files_scanned: int) -> str:
    """Format findings as JSON."""
    severity_counts = {}
    for f in findings:
        severity_counts[f.severity] = severity_counts.get(f.severity, 0) + 1

    report = {
        "summary": {
            "files_scanned": files_scanned,
            "total_issues": len(findings),
            "by_severity": severity_counts,
        },
        "findings": [asdict(f) for f in findings],
    }
    return json.dumps(report, indent=2)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="a11y_scanner",
        description="Scan frontend codebases for WCAG 2.2 accessibility violations.",
        epilog=(
            "Supported file types: .html, .htm, .jsx, .tsx, .vue, .svelte, .css\n"
            "Exit codes: 0 = pass, 1 = critical/serious found, 2 = moderate/minor only"
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "path",
        help="File or directory to scan",
    )
    parser.add_argument(
        "--json", dest="json_flag", action="store_true",
        help="Output results as JSON (shorthand for --format json)",
    )
    parser.add_argument(
        "--format", dest="output_format", choices=["text", "json"],
        default="text",
        help="Output format: text (default) or json",
    )
    parser.add_argument(
        "--severity", dest="severity",
        default=None,
        help="Comma-separated severity filter (e.g. critical,serious)",
    )
    return parser


def main():
    parser = build_parser()
    args = parser.parse_args()

    path = os.path.abspath(args.path)
    if not os.path.exists(path):
        print(f"Error: path does not exist: {path}", file=sys.stderr)
        sys.exit(1)

    use_json = args.json_flag or args.output_format == "json"

    # Collect and scan files
    files = collect_files(path)
    if not files:
        print(f"No scannable files found in: {path}", file=sys.stderr)
        sys.exit(0)

    all_findings: List[Finding] = []
    for fpath in files:
        all_findings.extend(scan_file(fpath))

    # Filter by severity if requested
    if args.severity:
        allowed = {s.strip().lower() for s in args.severity.split(",")}
        all_findings = [f for f in all_findings if f.severity in allowed]

    # Output
    if use_json:
        print(format_json(all_findings, len(files)))
    else:
        print(format_human(all_findings, len(files)))

    # Exit code
    severities = {f.severity for f in all_findings}
    if severities & {"critical", "serious"}:
        sys.exit(1)
    elif severities & {"moderate", "minor"}:
        sys.exit(2)
    else:
        sys.exit(0)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""WCAG 2.2 Color Contrast Checker.

Checks foreground/background color pairs against WCAG 2.2 contrast ratio
thresholds for normal text, large text, and UI components. Supports hex,
rgb(), and named CSS colors.

Usage:
    python contrast_checker.py "#ffffff" "#000000"
    python contrast_checker.py --suggest "#336699"
    python contrast_checker.py --batch styles.css
    python contrast_checker.py --demo
"""

import argparse
import json
import re
import sys

# ---------------------------------------------------------------------------
# Named CSS colors (25 common ones)
# ---------------------------------------------------------------------------
NAMED_COLORS = {
    "black": (0, 0, 0),
    "white": (255, 255, 255),
    "red": (255, 0, 0),
    "green": (0, 128, 0),
    "blue": (0, 0, 255),
    "yellow": (255, 255, 0),
    "cyan": (0, 255, 255),
    "magenta": (255, 0, 255),
    "gray": (128, 128, 128),
    "grey": (128, 128, 128),
    "orange": (255, 165, 0),
    "purple": (128, 0, 128),
    "pink": (255, 192, 203),
    "brown": (165, 42, 42),
    "navy": (0, 0, 128),
    "teal": (0, 128, 128),
    "olive": (128, 128, 0),
    "maroon": (128, 0, 0),
    "lime": (0, 255, 0),
    "aqua": (0, 255, 255),
    "silver": (192, 192, 192),
    "gold": (255, 215, 0),
    "coral": (255, 127, 80),
    "salmon": (250, 128, 114),
    "tomato": (255, 99, 71),
}

# WCAG thresholds: (label, required_ratio)
WCAG_THRESHOLDS = [
    ("AA Normal Text", 4.5),
    ("AA Large Text", 3.0),
    ("AA UI Components", 3.0),
    ("AAA Normal Text", 7.0),
    ("AAA Large Text", 4.5),
]


# ---------------------------------------------------------------------------
# Color parsing
# ---------------------------------------------------------------------------
def parse_color(color_str: str) -> tuple:
    """Parse a color string into an (R, G, B) tuple.

    Accepts:
      - #RRGGBB or #RGB hex
      - rgb(r, g, b)  with values 0-255
      - Named CSS colors
    """
    s = color_str.strip().lower()

    # Named color
    if s in NAMED_COLORS:
        return NAMED_COLORS[s]

    # Hex: #RGB or #RRGGBB
    hex_match = re.match(r"^#([0-9a-f]{3}|[0-9a-f]{6})$", s)
    if hex_match:
        h = hex_match.group(1)
        if len(h) == 3:
            r, g, b = int(h[0] * 2, 16), int(h[1] * 2, 16), int(h[2] * 2, 16)
        else:
            r, g, b = int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
        return (r, g, b)

    # rgb(r, g, b)
    rgb_match = re.match(r"^rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)$", s)
    if rgb_match:
        r, g, b = int(rgb_match.group(1)), int(rgb_match.group(2)), int(rgb_match.group(3))
        if not all(0 <= c <= 255 for c in (r, g, b)):
            raise ValueError(f"RGB values must be 0-255, got rgb({r},{g},{b})")
        return (r, g, b)

    raise ValueError(
        f"Invalid color format: '{color_str}'. "
        "Use #RRGGBB, #RGB, rgb(r,g,b), or a named color."
    )


def color_to_hex(rgb: tuple) -> str:
    """Convert an (R, G, B) tuple to #RRGGBB."""
    return f"#{rgb[0]:02x}{rgb[1]:02x}{rgb[2]:02x}"


# ---------------------------------------------------------------------------
# WCAG luminance and contrast
# ---------------------------------------------------------------------------
def relative_luminance(rgb: tuple) -> float:
    """Calculate relative luminance per WCAG 2.2 (sRGB).

    https://www.w3.org/TR/WCAG22/#dfn-relative-luminance
    """
    channels = []
    for c in rgb:
        s = c / 255.0
        channels.append(s / 12.92 if s <= 0.04045 else ((s + 0.055) / 1.055) ** 2.4)
    return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]


def contrast_ratio(rgb1: tuple, rgb2: tuple) -> float:
    """Return the WCAG contrast ratio between two colors (>= 1.0)."""
    l1 = relative_luminance(rgb1)
    l2 = relative_luminance(rgb2)
    lighter = max(l1, l2)
    darker = min(l1, l2)
    return (lighter + 0.05) / (darker + 0.05)


def evaluate_contrast(ratio: float) -> list:
    """Return pass/fail results for each WCAG threshold."""
    results = []
    for label, threshold in WCAG_THRESHOLDS:
        results.append({
            "level": label,
            "required": threshold,
            "ratio": round(ratio, 2),
            "pass": ratio >= threshold,
        })
    return results


# ---------------------------------------------------------------------------
# Suggest accessible backgrounds
# ---------------------------------------------------------------------------
def suggest_backgrounds(fg_rgb: tuple, target_ratio: float = 4.5, count: int = 8) -> list:
    """Given a foreground color, suggest background colors passing AA normal text.

    Strategy: walk luminance in both directions (lighter / darker) from the
    foreground and collect the first colors that meet the target ratio.
    """
    suggestions = []

    # Try a spread of grays and tinted variants
    candidates = []
    for v in range(0, 256, 1):
        candidates.append((v, v, v))  # grays

    # Also try tinted versions toward the complement
    fr, fg, fb = fg_rgb
    for v in range(0, 256, 2):
        candidates.append((v, min(255, v + 20), min(255, v + 40)))
        candidates.append((min(255, v + 40), v, min(255, v + 20)))
        candidates.append((min(255, v + 20), min(255, v + 40), v))

    seen = set()
    scored = []
    for c in candidates:
        cr = contrast_ratio(fg_rgb, c)
        if cr >= target_ratio and c not in seen:
            seen.add(c)
            scored.append((cr, c))

    # Sort by ratio closest to target (prefer minimal-change backgrounds)
    scored.sort(key=lambda x: x[0])
    for cr, c in scored[:count]:
        suggestions.append({"hex": color_to_hex(c), "rgb": list(c), "ratio": round(cr, 2)})
    return suggestions


# ---------------------------------------------------------------------------
# Batch CSS parsing
# ---------------------------------------------------------------------------
_COLOR_RE = re.compile(
    r"(#[0-9a-fA-F]{3,6}|rgb\(\s*\d{1,3}\s*,\s*\d{1,3}\s*,\s*\d{1,3}\s*\))"
)


def extract_css_pairs(css_text: str) -> list:
    """Extract color / background-color pairs from CSS declarations.

    Returns a list of dicts with selector, foreground, and background strings.
    """
    pairs = []
    # Split into rule blocks
    block_re = re.compile(r"([^{}]+)\{([^}]+)\}", re.DOTALL)
    for m in block_re.finditer(css_text):
        selector = m.group(1).strip()
        body = m.group(2)

        fg = bg = None
        # Match color: ... (but not background-color)
        fg_match = re.search(
            r"(?<![-])color\s*:\s*([^;]+);", body, re.IGNORECASE
        )
        bg_match = re.search(
            r"background(?:-color)?\s*:\s*([^;]+);", body, re.IGNORECASE
        )

        if fg_match:
            val = fg_match.group(1).strip()
            c = _COLOR_RE.search(val)
            if c:
                fg = c.group(1)
            elif val.lower() in NAMED_COLORS:
                fg = val.lower()

        if bg_match:
            val = bg_match.group(1).strip()
            c = _COLOR_RE.search(val)
            if c:
                bg = c.group(1)
            elif val.lower() in NAMED_COLORS:
                bg = val.lower()

        if fg and bg:
            pairs.append({"selector": selector, "foreground": fg, "background": bg})

    return pairs


# ---------------------------------------------------------------------------
# Output formatting
# ---------------------------------------------------------------------------
def format_result_human(fg_str: str, bg_str: str, ratio: float, results: list) -> str:
    """Format a contrast check result for the terminal."""
    lines = [
        f"Foreground : {fg_str}",
        f"Background : {bg_str}",
        f"Contrast   : {ratio:.2f}:1",
        "",
    ]
    for r in results:
        status = "PASS" if r["pass"] else "FAIL"
        lines.append(f"  [{status}] {r['level']:20s}  (requires {r['required']}:1)")
    return "\n".join(lines)


def format_suggestions_human(fg_str: str, suggestions: list) -> str:
    """Format suggested backgrounds for the terminal."""
    lines = [f"Foreground: {fg_str}", "Suggested accessible backgrounds (AA Normal Text):"]
    if not suggestions:
        lines.append("  No suggestions found.")
    for s in suggestions:
        lines.append(f"  {s['hex']}  ratio={s['ratio']}:1")
    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Demo
# ---------------------------------------------------------------------------
DEMO_PAIRS = [
    ("#ffffff", "#000000"),
    ("#336699", "#ffffff"),
    ("#ff6600", "#ffffff"),
    ("navy", "white"),
    ("rgb(100,100,100)", "#eeeeee"),
]


def run_demo(as_json: bool) -> None:
    """Run demo checks and print results."""
    all_results = []
    for fg_str, bg_str in DEMO_PAIRS:
        fg_rgb = parse_color(fg_str)
        bg_rgb = parse_color(bg_str)
        ratio = contrast_ratio(fg_rgb, bg_rgb)
        results = evaluate_contrast(ratio)
        entry = {
            "foreground": fg_str,
            "background": bg_str,
            "foreground_hex": color_to_hex(fg_rgb),
            "background_hex": color_to_hex(bg_rgb),
            "ratio": round(ratio, 2),
            "results": results,
        }
        all_results.append(entry)

    if as_json:
        print(json.dumps({"demo": True, "checks": all_results}, indent=2))
    else:
        print("=" * 60)
        print("WCAG 2.2 Contrast Checker - Demo")
        print("=" * 60)
        for entry in all_results:
            print()
            print(
                format_result_human(
                    entry["foreground"], entry["background"],
                    entry["ratio"], entry["results"],
                )
            )
        print()
        print("-" * 60)
        print("Suggestion demo for foreground #336699:")
        suggestions = suggest_backgrounds(parse_color("#336699"))
        print(format_suggestions_human("#336699", suggestions))


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="WCAG 2.2 Color Contrast Checker. "
        "Checks foreground/background pairs against AA and AAA thresholds.",
        epilog="Examples:\n"
        "  %(prog)s '#ffffff' '#000000'\n"
        "  %(prog)s --suggest '#336699'\n"
        "  %(prog)s --batch styles.css\n"
        "  %(prog)s --demo\n",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "foreground",
        nargs="?",
        help="Foreground (text) color: #RRGGBB, #RGB, rgb(r,g,b), or named color",
    )
    parser.add_argument(
        "background",
        nargs="?",
        help="Background color: #RRGGBB, #RGB, rgb(r,g,b), or named color",
    )
    parser.add_argument(
        "--suggest",
        metavar="COLOR",
        help="Suggest accessible background colors for the given foreground color",
    )
    parser.add_argument(
        "--batch",
        metavar="CSS_FILE",
        help="Extract color pairs from a CSS file and check each",
    )
    parser.add_argument(
        "--json",
        action="store_true",
        dest="json_output",
        help="Output results as JSON",
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Show example output with sample color pairs",
    )
    parser.add_argument(
        "--sample",
        action="store_true",
        help="Run with embedded sample color pairs (alias for --demo)",
    )
    return parser


def main() -> int:
    parser = build_parser()
    args = parser.parse_args()

    # --demo / --sample mode
    if args.demo or args.sample:
        run_demo(args.json_output)
        return 0

    # --suggest mode
    if args.suggest:
        try:
            fg_rgb = parse_color(args.suggest)
        except ValueError as exc:
            print(f"Error: {exc}", file=sys.stderr)
            return 1

        suggestions = suggest_backgrounds(fg_rgb)
        if args.json_output:
            print(json.dumps({
                "foreground": args.suggest,
                "foreground_hex": color_to_hex(fg_rgb),
                "suggestions": suggestions,
            }, indent=2))
        else:
            print(format_suggestions_human(args.suggest, suggestions))
        return 0

    # --batch mode
    if args.batch:
        try:
            with open(args.batch, "r", encoding="utf-8") as fh:
                css_text = fh.read()
        except FileNotFoundError:
            print(f"Error: file not found: {args.batch}", file=sys.stderr)
            return 1
        except OSError as exc:
            print(f"Error reading file: {exc}", file=sys.stderr)
            return 1

        pairs = extract_css_pairs(css_text)
        if not pairs:
            msg = "No color/background-color pairs found in the CSS file."
            if args.json_output:
                print(json.dumps({"batch": args.batch, "pairs": [], "message": msg}, indent=2))
            else:
                print(msg)
            return 0

        all_results = []
        has_failure = False
        for pair in pairs:
            try:
                fg_rgb = parse_color(pair["foreground"])
                bg_rgb = parse_color(pair["background"])
            except ValueError as exc:
                entry = {
                    "selector": pair["selector"],
                    "foreground": pair["foreground"],
                    "background": pair["background"],
                    "error": str(exc),
                }
                all_results.append(entry)
                continue

            ratio = contrast_ratio(fg_rgb, bg_rgb)
            results = evaluate_contrast(ratio)
            if not results[0]["pass"]:  # AA Normal Text
                has_failure = True
            entry = {
                "selector": pair["selector"],
                "foreground": pair["foreground"],
                "background": pair["background"],
                "foreground_hex": color_to_hex(fg_rgb),
                "background_hex": color_to_hex(bg_rgb),
                "ratio": round(ratio, 2),
                "results": results,
            }
            all_results.append(entry)

        if args.json_output:
            print(json.dumps({"batch": args.batch, "pairs": all_results}, indent=2))
        else:
            print(f"Batch check: {args.batch}")
            print("=" * 60)
            for entry in all_results:
                print(f"\nSelector: {entry['selector']}")
                if "error" in entry:
                    print(f"  Error: {entry['error']}")
                else:
                    print(
                        format_result_human(
                            entry["foreground"], entry["background"],
                            entry["ratio"], entry["results"],
                        )
                    )
            print()
            summary_pass = sum(1 for e in all_results if "ratio" in e and e["results"][0]["pass"])
            summary_total = sum(1 for e in all_results if "ratio" in e)
            print(f"Summary: {summary_pass}/{summary_total} pairs pass AA Normal Text")

        return 1 if has_failure else 0

    # Default: check a single pair
    if not args.foreground or not args.background:
        parser.error(
            "Provide foreground and background colors, or use --suggest, --batch, or --demo."
        )

    try:
        fg_rgb = parse_color(args.foreground)
    except ValueError as exc:
        print(f"Error (foreground): {exc}", file=sys.stderr)
        return 1

    try:
        bg_rgb = parse_color(args.background)
    except ValueError as exc:
        print(f"Error (background): {exc}", file=sys.stderr)
        return 1

    ratio = contrast_ratio(fg_rgb, bg_rgb)
    results = evaluate_contrast(ratio)

    if args.json_output:
        print(json.dumps({
            "foreground": args.foreground,
            "background": args.background,
            "foreground_hex": color_to_hex(fg_rgb),
            "background_hex": color_to_hex(bg_rgb),
            "ratio": round(ratio, 2),
            "results": results,
        }, indent=2))
    else:
        print(format_result_human(args.foreground, args.background, ratio, results))

    return 0 if results[0]["pass"] else 1


if __name__ == "__main__":
    sys.exit(main())