Output format

interface ScanSummary {
  files_scanned: number
  total_issues: number
  by_severity: Record<Severity, number>
  by_scanner: Record<string, number>      // keyed by scanner.name
  criteria_tested: string[]               // WCAG criteria genuinely EXERCISED this scan (coverage-derived —
                                           // a scanner with eligible files actually ran the check, minus
                                           // page-level rules reclassified on a fragment). Not the same set
                                           // as criteria_failed — a criterion can be tested and pass.
  criteria_failed: string[]               // WCAG criteria with at least one violation
  ignored_count: number                   // Issues suppressed via equall-ignore
}

interface ScannerInfo {
  name: string
  version: string
  rules_count: number
  issues_found: number
}

interface CoverageReport {
  criteria: CriterionCoverage[]
  counts: Record<CoverageStatus, number>   // how many criteria fall in each status
  auto_criteria: string[]                  // criteria with status 'auto' — the genuinely-checked set
  reclassified?: ReclassifiedRule[]        // page-level rules moved out of violations on fragment
                                           // scans — optional in the type for older consumers,
                                           // but runScan always attaches it ([] when none)
}

interface CriterionCoverage {
  criterion: string                        // e.g. '1.4.3'
  status: CoverageStatus
  scanners: string[]                       // scanners that exercised it (empty for 'manual')
}

type CoverageStatus =
  | 'auto'      // genuinely tested — a scanner received eligible files and exercised it
  | 'partial'   // nominally covered but statically incomplete (e.g. axe 1.4.3 contrast needs a render)
  | 'manual'    // a scanner is capable of it but got no eligible files — verify another way

interface ReclassifiedRule {
  rule_id: string                          // e.g. 'region'
  scanner: string                          // e.g. 'axe-core'
  reason: string                           // why it is not statically verifiable here
  count: number                            // occurrences reclassified this scan
  files: string[]                          // unique affected files
  wcag_criteria: string[]                  // [] for best-practice rules
}

interface ConfidenceFlag {
  criterion: string     // the criterion the advisory relates to, e.g. '1.1.1'
  signal: string        // which precision signal fired: 'filename_as_alt' | 'alt_equals_src' |
                         // 'generic_placeholder' | 'gibberish'
  value: string          // the offending alt text
  file_path: string
  line?: number          // best-effort; absent when not derivable
  reason: string         // plain-language why it looks suspect
  confidence: 'low'      // advisory only — reserved for future tiers
}

interface CriterionConformance {
  criterion: string              // e.g. '1.4.3'
  level: WcagLevel                // from the WCAG catalog
  name: string                    // criterion name from the catalog
  verdict: ConformanceVerdict
  evidence?: string[]             // failing issue fingerprints — `fail` only
  reason?: string                 // why not verifiable / not tested — non-fail, non-pass verdicts only
}

type ConformanceVerdict =
  | 'fail'                         // ≥1 active issue maps to the criterion — fail always wins
  | 'pass_automated'               // exercised `auto` this scan, zero issues — an automated basis
                                   // only, never a bare "pass"
  | 'not_verifiable_on_this_scan'  // reclassified page-level rule on a fragment — verify on the
                                   // rendered page
  | 'not_tested_assisted'          // coverage `partial` (e.g. contrast) — needs a rendered/assisted check
  | 'not_tested_manual'            // coverage `manual` or uncovered — verify manually

type ConformanceLevel = 'AAA' | 'AA' | 'A' | 'Partial A' | 'None'
type Severity         = 'critical' | 'serious' | 'moderate' | 'minor'
type WcagLevel        = 'A' | 'AA' | 'AAA'
type WcagStandard     = 'wcag22' | 'wcag21'
type PourPrinciple    = 'perceivable' | 'operable' | 'understandable' | 'robust'

{
  "score": 56.34,
  "conformance_level": "Partial A",
  "issues": [
    {
      "scanner": "axe-core",
      "scanner_rule_id": "image-alt",
      "wcag_criteria": ["1.1.1"],
      "wcag_level": "A",
      "pour": "perceivable",
      "file_path": "src/components/Logo.tsx",
      "line": null,
      "column": null,
      "html_snippet": "<img src=\"/logo.svg\">",
      "severity": "critical",
      "message": "Images must have alternate text",
      "help_url": "https://dequeuniversity.com/rules/axe/4.11/image-alt",
      "suggestion": "Add an alt attribute describing the image, or alt=\"\" if it's decorative."
    }
  ],
  "summary": {
    "files_scanned": 33,
    "total_issues": 34,
    "by_severity": { "critical": 2, "serious": 11, "moderate": 19, "minor": 0 },
    "by_scanner": { "axe-core": 23, "eslint-jsx-a11y": 13 },
    "criteria_tested": ["1.1.1", "1.3.1", "2.4.4", "4.1.2"],
    "criteria_failed": ["1.1.1", "4.1.2"],
    "ignored_count": 2
  },
  "scanners_used": [
    { "name": "axe-core",        "version": "4.11.1", "rules_count": 0, "issues_found": 23 },
    { "name": "eslint-jsx-a11y", "version": "6.10.2", "rules_count": 0, "issues_found": 13 }
  ],
  "criteria_covered": ["1.1.1", "1.3.1", "2.4.4", "4.1.2"],
  "criteria_total": 55,
  "criterion_conformance": [
    { "criterion": "1.1.1", "level": "A", "name": "Non-text Content", "verdict": "fail", "evidence": ["9f3a1c7e2b4d6081"] },
    { "criterion": "1.3.1", "level": "A", "name": "Info and Relationships", "verdict": "pass_automated" },
    { "criterion": "2.4.4", "level": "A", "name": "Link Purpose (In Context)", "verdict": "pass_automated" },
    { "criterion": "4.1.2", "level": "A", "name": "Name, Role, Value", "verdict": "fail", "evidence": ["a7c02e5f19d3b644"] },
    { "criterion": "2.4.6", "level": "AA", "name": "Headings and Labels", "verdict": "not_tested_manual", "reason": "No automated coverage on this scan — verify manually (keyboard, screen reader, human review)." }
  ],
  "standard": "wcag22",
  "confidence_flags": [
    {
      "criterion": "1.1.1",
      "signal": "filename_as_alt",
      "value": "DSC00423",
      "file_path": "src/components/Gallery.tsx",
      "line": 12,
      "reason": "The alt looks like a file name, not a description.",
      "confidence": "low"
    }
  ],
  "diagnostics": [],
  "scanned_at": "2026-04-26T10:32:11.482Z",
  "duration_ms": 812,
  "engine_version": "0.2.0",
  "score_model": 2
}