tewip-ai 0.35.0 → 0.36.0

package/README.md

@@ -629,6 +629,42 @@ Measured on four public projects, never on fixtures — excalidraw, bootstrap, v
 classes were found and fixed along the way, every one of them a defect in Tewip rather than in the
 projects, and none of them reachable from a fixture. They are listed in [ROADMAP.md](ROADMAP.md).
 
+### Already run axe? Give Tewip the JSON (Phase 29, new)
+
+```bash
+tewip access --report axe-results.json
+```
+
+Reading markup cannot see contrast. A browser can, so if your Playwright, Cypress or jest-axe suite
+already writes an axe report, hand it over — and Tewip will triage it instead of relaying it.
+
+This is where the numbers get uncomfortable. axe 4.14 over nine real pages returned **174 findings**:
+
+| | |
+|---|---|
+| **53 barriers** | a real WCAG criterion, with the **EN 301 549** clause the EU Accessibility Act cites |
+| **51 advice** | axe rules tagged `best-practice` that map to **no criterion at all** |
+| **70 questions** | axe's own `incomplete` — it could not determine them |
+
+**42% of what axe hands you tests no standard.** `region` alone — "all content should be contained by
+landmarks" — was 40 findings, outnumbering every real barrier on the page. Tewip reports those as advice,
+never as barriers, and they never fail a build. That separation is most of the point.
+
+And the unchecked list shrinks, honestly: **one** of its seven entries — 1.4.3 Contrast — moves to
+checked. The other six stay, because no tool settles them. The report also names how many pages the run
+covered, and says plainly that nothing is known about a page it did not open or a state it did not reach.
+
+```
+## Checked here only because a browser run was given
+
+- **1.4.3 Contrast (Minimum)** - would otherwise be unreachable: needs the computed colours of a
+  rendered page, not the markup
+```
+
+A source finding is set aside only when the run opened **that same file** and re-ran the equivalent rule.
+In a React or Vue project that means nothing is set aside — the source and the rendered output are two
+different artefacts, and neither is evidence about the other.
+
 ## Teach it your house rules (Phase 27)
 
 ```bash

package/dist/cli/help.js

@@ -118,7 +118,7 @@ Usage:
                                     is what was asked for covered. Answers ready, not ready, or cannot
                                     say - and cannot say is never rounded up to ready. --json writes a
                                     sealed verdict that can be checked later. No model, no cost.
-  tewip access [<file or directory>] [--strict] [--out access.md]
+  tewip access [<file or directory>] [--report axe.json] [--strict] [--out access.md]
                                     Can everybody use this? Reads your markup and names the barriers
                                     that reading alone can prove - a picture with no alt text, a field
                                     with no label, a div only a mouse can use - each against its WCAG
@@ -127,7 +127,11 @@ Usage:
                                     criterion it cannot reach without rendering the page (contrast,
                                     focus order, whether the alt text is any good) is printed every
                                     time. It never says a page is accessible, only what was checked.
-                                    No browser, no network, no model, no cost.
+                                    Give it --report with the JSON from an axe run and it reads that
+                                    too: contrast moves out of the unchecked list, axe rules that map
+                                    to no WCAG criterion are reported as advice rather than barriers
+                                    (51 of 174 findings on nine real pages), and what axe could not
+                                    determine becomes a question. No browser, no network, no model.
   tewip standards [--diff main...HEAD] [--strict] [--out standards.md]
                                     Teach Tewip your house rules. Markdown files in
                                     .tewip/standards/ - a forbid or require line is checked and

package/dist/cli/verbs-prove.js

@@ -22,11 +22,12 @@ export async function proveVerb(verb, args) {
         }
         case 'access': {
             const { runAccess } = await import('../engine/access/access-command.js');
-            const paths = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--out');
+            const paths = args.filter((a, i) => !a.startsWith('--') && args[i - 1] !== '--out' && args[i - 1] !== '--report');
             runAccess({
                 root: process.cwd(),
                 only: paths[0],
                 out: flag(args, 'out'),
+                report: flag(args, 'report'),
                 gate: args.includes('--strict'),
             });
             return true;

package/dist/engine/access/access-command.js

@@ -13,6 +13,8 @@ import { dirname, join, relative, resolve } from 'node:path';
 import { sourceFiles } from '../secure/secrets.js';
 import { JS_LIKE, MARKUP, tags } from './markup.js';
 import { checkFile } from './checks.js';
+import { readAxeReport } from './reports.js';
+import { merge, nowChecked, pagesIn, renderBrowserSection, standardOf, stillNotChecked } from './merge.js';
 import { blocks, criterionOf, NOT_CHECKED, RULES } from './wcag.js';
 const ORDER = { blocker: 0, serious: 1, moderate: 2, minor: 3 };
 /** One line per finding a person has already judged: "<rule> <file>:<line> - reason". */
@@ -101,10 +103,14 @@ function section(title, findings, lines) {
     }
 }
 export function renderAccess(result, scanned) {
-    const { barriers, questions, accepted, filesRead } = result;
+    const { barriers, questions, accepted, filesRead, browser } = result;
     const lines = ['# Tewip accessibility check', ''];
     lines.push(`Read ${filesRead} markup ${filesRead === 1 ? 'file' : 'files'} under \`${scanned}\`, without rendering any of them.`, '');
-    if (barriers.length === 0 && questions.length === 0) {
+    if (browser) {
+        lines.push(`Also read an axe run over ${browser.pages.length} rendered ${browser.pages.length === 1 ? 'page' : 'pages'}, ` +
+            'which settles what reading markup cannot.', '');
+    }
+    if (barriers.length === 0 && questions.length === 0 && !browser) {
         lines.push('No barrier was found that reading the markup can settle, and nothing needs a decision.', '');
     }
     else {
@@ -115,22 +121,67 @@ export function renderAccess(result, scanned) {
         ];
         if (accepted.length > 0)
             counts.push(`${accepted.length} already accepted`);
+        if (browser) {
+            counts.unshift(`${browser.barriers.length} barriers the browser run proves`);
+            if (browser.questions.length > 0)
+                counts.push(`${browser.questions.length} the browser could not determine`);
+        }
         lines.push(`**${counts.join(', ')}.**`, '');
     }
-    section('Barriers', [...barriers].sort(worstFirst), lines);
+    if (browser) {
+        renderBrowserSection('Barriers seen in the browser', browser.barriers, lines);
+        renderBrowserSection('The browser could not determine these', browser.questions, lines);
+    }
+    section('Barriers read from the source', [...barriers].sort(worstFirst), lines);
     section('Only a person can settle these', [...questions].sort(worstFirst), lines);
+    if (browser && browser.advice.length > 0) {
+        // Kept out of the counts above on purpose. These are axe's own best-practice rules, which test
+        // no standard: on nine real pages they were 51 of 174 findings, outnumbering every real barrier.
+        // Reporting them as equals is how a team learns to ignore the whole report.
+        const rules = [...new Set(browser.advice.map((f) => f.rule))].sort();
+        lines.push('## Advice, not barriers', '');
+        lines.push(`${browser.advice.length} findings come from axe rules that map to no WCAG criterion - ` +
+            `${rules.join(', ')}. They are somebody's good idea rather than a standard, so they are not counted as barriers ` +
+            'and never fail a build. Worth reading once; not worth a release.', '');
+    }
+    if (browser && browser.superseded.length > 0) {
+        lines.push('## Set aside, because the browser run checked them', '');
+        lines.push(`${browser.superseded.length} source ${browser.superseded.length === 1 ? 'finding' : 'findings'} ` +
+            'are not listed above: the axe run checked their criterion on a rendered page, so its answer is the better ' +
+            'one and repeating them here would count the same barrier twice. They are in the JSON beside this report.', '');
+    }
     if (accepted.length > 0) {
         lines.push('## Already accepted', '');
         lines.push(`${accepted.length} ${accepted.length === 1 ? 'finding is' : 'findings are'} listed in \`.tewip/access-accepted.txt\`, so they are not repeated here.`, '');
     }
+    // Coverage comes from every rule that ran, not from the ones that found something: a contrast
+    // check that ran and passed has still checked contrast.
+    const ran = browser?.rulesRun ?? new Set();
+    const settled = nowChecked(ran);
+    const remaining = stillNotChecked(ran);
+    if (settled.length > 0) {
+        lines.push('## Checked here only because a browser run was given', '');
+        for (const n of settled)
+            lines.push(`- **${n.criterion}** - would otherwise be unreachable: ${n.why}`);
+        lines.push('');
+    }
     lines.push('## What was not checked', '');
-    lines.push('This read the markup. It did not render a page, so none of the following was tested:', '');
-    for (const n of NOT_CHECKED)
+    lines.push(browser
+        ? 'Even with the browser run, none of the following was tested:'
+        : 'This read the markup. It did not render a page, so none of the following was tested:', '');
+    for (const n of remaining)
         lines.push(`- **${n.criterion}** - ${n.why}`);
+    if (browser) {
+        lines.push('');
+        lines.push(`The run covered ${browser.pages.length} ${browser.pages.length === 1 ? 'page' : 'pages'}. ` +
+            'Nothing is known about a page it did not open, or about a state it did not reach - a dialog that was never ' +
+            'opened, a form that was never submitted, an error that was never triggered.');
+    }
     lines.push('');
     lines.push('A clean result here means these checks found nothing, not that the product is accessible. ' +
-        'Roughly a third of WCAG can be judged by a machine at all, and reading source rather than a rendered page reaches less than that. ' +
-        'The rest needs a person, ideally one who uses a screen reader.', '');
+        'Roughly a third of WCAG can be judged by a machine at all' +
+        (browser ? '' : ', and reading source rather than a rendered page reaches less than that') +
+        '. The rest needs a person, ideally one who uses a screen reader.', '');
     lines.push('To accept a finding, add its key to `.tewip/access-accepted.txt`, one per line, with a reason after ` - `.', '');
     return lines.join('\n');
 }
@@ -140,18 +191,36 @@ export function runAccess(cmd) {
     const alreadyJudged = readAccepted(root);
     const accepted = findings.filter((f) => alreadyJudged.has(keyOf(f)));
     const open = findings.filter((f) => !alreadyJudged.has(keyOf(f)));
-    const barriers = open.filter((f) => f.confidence === 'barrier');
-    const questions = open.filter((f) => f.confidence === 'ask-a-person');
-    const result = { barriers, questions, accepted, filesRead };
+    // Phase 29: a browser run, where one was given. It is the better witness for every criterion it
+    // checked, so the source findings for those criteria are set aside rather than repeated.
+    const run = cmd.report ? readAxeReport(resolve(root, cmd.report)) : undefined;
+    const graded = run ? merge(open, run, root) : undefined;
+    const kept = graded ? graded.kept : open;
+    const barriers = kept.filter((f) => f.confidence === 'barrier');
+    const questions = kept.filter((f) => f.confidence === 'ask-a-person');
+    const browser = run && graded
+        ? {
+            barriers: run.findings.filter((f) => f.confidence === 'barrier'),
+            questions: run.findings.filter((f) => f.confidence === 'ask-a-person'),
+            advice: run.findings.filter((f) => f.confidence === 'advice'),
+            superseded: graded.superseded,
+            pages: pagesIn(run),
+            rulesRun: run.rulesRun,
+        }
+        : undefined;
+    const result = { barriers, questions, accepted, filesRead, ...(browser ? { browser } : {}) };
     const report = renderAccess(result, cmd.only ? resolve(root, cmd.only) : root);
     console.log(report);
     // What fails a build is deliberately narrower than what gets reported. A question never fails it:
     // a build that breaks because something needs a human decision teaches a team to stop asking. Nor
     // does a moderate finding - bootstrap's example pages skip a heading level, which is worth knowing
     // and not worth blocking a release over. Only the barriers that stop somebody outright.
-    const blocking = barriers.filter((f) => blocks(f.rule));
-    if (cmd.gate && blocking.length > 0) {
-        console.error(`${String.fromCharCode(10)}${blocking.length} accessibility barrier(s) that stop somebody outright, out of ${barriers.length} found.`);
+    // A browser barrier counts the same way: axe saw it on a rendered page, which is stronger
+    // evidence than reading source, not weaker. Advice never counts, whatever axe's impact says.
+    const blocking = barriers.filter((f) => blocks(f.rule)).length + (browser?.barriers.filter((f) => f.severity === 'blocker').length ?? 0);
+    if (cmd.gate && blocking > 0) {
+        const found = barriers.length + (browser?.barriers.length ?? 0);
+        console.error(`${String.fromCharCode(10)}${blocking} accessibility barrier(s) that stop somebody outright, out of ${found} found.`);
         process.exitCode = 1;
     }
     if (cmd.out) {

package/dist/engine/access/merge.js

@@ -0,0 +1,119 @@
+import { EQUIVALENT_AXE_RULE } from './reports.js';
+import { NOT_CHECKED, RULES } from './wcag.js';
+/** `1.1.1 Non-text Content` -> `1.1.1`, so a criterion from either source can be compared. */
+export function criterionNumber(criterion) {
+    return /^\d+(?:\.\d+)*/.exec(criterion.trim())?.[0] ?? '';
+}
+/** The criterion a source-read rule belongs to, as a bare number. */
+export function criterionOfRule(rule) {
+    const r = RULES[rule];
+    return r ? criterionNumber(r.criterion) : '';
+}
+/**
+ * Sets aside the source findings the run actually re-checked, rule by rule.
+ *
+ * The test is whether the *equivalent axe rule ran*, not whether axe found something and not
+ * whether some other rule under the same criterion ran. A rule that ran and passed still
+ * supersedes - axe looked at the rendered page and disagreed, which is the better evidence. A rule
+ * with no axe equivalent, like `click-without-keyboard`, is never superseded by anything.
+ */
+export function merge(source, run, root) {
+    const opened = pagesAsFiles(run, root);
+    const kept = [];
+    const superseded = [];
+    for (const f of source) {
+        const equivalent = EQUIVALENT_AXE_RULE[f.rule];
+        // Both conditions, and the second is the one that was missing. A run of nine pages does not
+        // supersede a finding in the hundredth file it never opened: on bootstrap that silently
+        // discarded all 44 source findings, including every one in the example pages axe never saw.
+        // A component file is never a page a browser opens, so in a React or Vue project nothing is
+        // superseded at all - correctly, because the source and the rendered output are two artefacts
+        // and neither is evidence about the other.
+        if (equivalent !== undefined && run.rulesRun.has(equivalent) && opened.has(f.file))
+            superseded.push(f);
+        else
+            kept.push(f);
+    }
+    return { kept, superseded, covered: run.criteriaCovered };
+}
+/** The pages a run opened, as repository-relative paths, for the ones that were local files. */
+export function pagesAsFiles(run, root) {
+    const out = new Set();
+    const base = root.replaceAll('\\', '/').replace(/\/$/, '').toLowerCase();
+    for (const page of run.pages) {
+        // `file:///C:/repo/a.html` -> `C:/repo/a.html`, but `file:///repo/a.html` -> `/repo/a.html`.
+        // Stripping every slash after the scheme is wrong on anything but Windows: the third one is
+        // the root, not padding.
+        const stripped = decodeURIComponent(page.replace(/^file:\/\//i, '')).replaceAll('\\', '/');
+        const path = /^\/[A-Za-z]:/.test(stripped) ? stripped.slice(1) : stripped;
+        const lower = path.toLowerCase();
+        if (lower.startsWith(`${base}/`))
+            out.add(path.slice(base.length + 1));
+    }
+    return out;
+}
+/**
+ * What is still unchecked once the browser run is counted.
+ *
+ * This is the payoff of the phase and the reason it is worth building: the list of criteria Tewip
+ * admits it cannot reach should get shorter when real evidence arrives, rather than being printed
+ * unchanged beneath a browser run that already settled half of it.
+ */
+export function stillNotChecked(rulesRun) {
+    return NOT_CHECKED.filter((n) => n.settledBy === undefined || !rulesRun.has(n.settledBy));
+}
+/** The criteria from NOT_CHECKED that this run did settle, for the report to say so. */
+export function nowChecked(rulesRun) {
+    return NOT_CHECKED.filter((n) => n.settledBy !== undefined && rulesRun.has(n.settledBy));
+}
+const SEVERITY_ORDER = { blocker: 0, serious: 1, moderate: 2, minor: 3 };
+export function worstBrowserFirst(a, b) {
+    const d = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+    if (d !== 0)
+        return d;
+    if (a.rule !== b.rule)
+        return a.rule < b.rule ? -1 : 1;
+    return a.selector < b.selector ? -1 : 1;
+}
+/** Groups by rule, keeping the order the comparator produced. */
+function byRule(findings) {
+    const out = new Map();
+    for (const f of [...findings].sort(worstBrowserFirst)) {
+        const list = out.get(f.rule);
+        if (list)
+            list.push(f);
+        else
+            out.set(f.rule, [f]);
+    }
+    return out;
+}
+/** How a browser finding names its standard: both WCAG and the clause the EAA cites. */
+export function standardOf(f) {
+    if (!f.criterion)
+        return 'no criterion - this is a best-practice rule, not a standard';
+    const en = f.en301549 ? `, EN 301 549 clause ${f.en301549}` : '';
+    return `WCAG 2.2 ${f.criterion} (${f.level ?? 'A'})${en}`;
+}
+export function renderBrowserSection(title, findings, lines, limit = 8) {
+    if (findings.length === 0)
+        return;
+    lines.push(`## ${title}`, '');
+    for (const [rule, found] of byRule(findings)) {
+        lines.push(`### ${rule} - ${found.length} ${found.length === 1 ? 'place' : 'places'}`, '');
+        lines.push(`${standardOf(found[0])}, ${found[0].severity}.`, '');
+        lines.push(`${found[0].why}`, '');
+        for (const f of found.slice(0, limit)) {
+            lines.push(`- \`${f.selector}\``);
+            lines.push(`  - \`${f.html}\``);
+            if (f.next && f.next !== found[0].why)
+                lines.push(`  - ${f.next}`);
+        }
+        if (found.length > limit)
+            lines.push(`- ...and ${found.length - limit} more of the same.`);
+        lines.push('');
+    }
+}
+/** The pages a browser run covered, which bounds everything it can be said to prove. */
+export function pagesIn(run) {
+    return [...run.pages].sort();
+}

package/dist/engine/access/reports.js

@@ -0,0 +1,206 @@
+// Phase 29: reading a real browser run, so the criteria Phase 28 says it cannot reach stop being
+// unreachable.
+//
+// `tewip access` reads markup and is honest that contrast, focus order and anything else needing a
+// rendered page is outside it. The answer is not for Tewip to ship a browser. It is to read the run
+// a team already produces - axe, in a Playwright, Cypress or jest-axe suite - and do to its output
+// what Phase 9 does to a security scanner's: decide which findings matter, and say why.
+//
+// Why that is worth doing, measured on axe 4.14 over nine real pages (bootstrap's own component
+// pages and excalidraw's index): 122 findings, of which **51 carry no WCAG criterion at all**. Forty
+// are `region` ("all content should be contained by landmarks") and nine are `landmark-one-main`.
+// Both are axe's own `best-practice` rules, not failures of any standard, and they outnumber every
+// real barrier on the page. A team that is handed all 122 as equals stops reading them, which is the
+// reported reason accessibility tooling gets switched off.
+//
+// So the tags decide, not the impact:
+//   a wcag* tag  -> a numbered criterion a regulator can cite, and a barrier;
+//   best-practice only -> advice, reported apart and never failing a build;
+//   `incomplete` -> axe could not determine it, which is exactly Tewip's "ask a person".
+import { readFileSync } from 'node:fs';
+/** axe's impact, in Tewip's words. A WCAG-tagged `moderate` is still worth fixing, not a blocker. */
+const SEVERITY = {
+    critical: 'blocker',
+    serious: 'blocker',
+    moderate: 'moderate',
+    minor: 'minor',
+};
+/**
+ * `wcag143` -> `1.4.3`. The first digit is the principle, the second the guideline, the rest the
+ * criterion - so `wcag1411` is 1.4.11 and not 14.1.1, there being no fourteenth principle.
+ */
+function criterionFrom(tags) {
+    for (const tag of tags) {
+        const m = /^wcag(\d)(\d)(\d+)$/.exec(tag);
+        if (m)
+            return `${m[1]}.${m[2]}.${m[3]}`;
+    }
+    return null;
+}
+/** `wcag2a`, `wcag21aa`, `wcag22aa` -> the conformance level being claimed. */
+function levelFrom(tags) {
+    let best = null;
+    for (const tag of tags) {
+        const m = /^wcag\d{1,2}(a{1,3})$/.exec(tag);
+        if (!m)
+            continue;
+        const level = m[1].toUpperCase();
+        // The strictest statement wins, so a rule tagged both A and AA is reported as AA.
+        if (best === null || level.length > best.length)
+            best = level;
+    }
+    return best;
+}
+/** `EN-9.1.4.3` -> `9.1.4.3`. */
+function enClauseFrom(tags) {
+    for (const tag of tags) {
+        const m = /^EN-(\d+(?:\.\d+)+)$/.exec(tag);
+        if (m)
+            return m[1];
+    }
+    return null;
+}
+/** axe writes its guidance as "Fix any of the following:\n  <reason>". One line reads better. */
+function tidySummary(summary, fallback) {
+    const cleaned = summary
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l !== '' && !/^Fix (any|all) of the following:$/.test(l))
+        .join('; ');
+    return cleaned === '' ? fallback : cleaned;
+}
+const strings = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : []);
+const text = (v) => (typeof v === 'string' ? v : '');
+function fromRule(rule, page, kind) {
+    const tags = strings(rule.tags);
+    const criterion = criterionFrom(tags);
+    const help = text(rule.help) || text(rule.description);
+    const id = text(rule.id);
+    // No criterion and axe's own best-practice tag: somebody's good idea, not a standard. Reported,
+    // but never as a barrier and never as something that fails a build.
+    const advice = criterion === null && tags.includes('best-practice');
+    const confidence = kind === 'incomplete' ? 'ask-a-person' : advice ? 'advice' : 'barrier';
+    const nodes = Array.isArray(rule.nodes) ? rule.nodes : [];
+    return nodes.map((node) => ({
+        rule: id,
+        tool: 'axe',
+        confidence,
+        criterion,
+        level: levelFrom(tags),
+        en301549: enClauseFrom(tags),
+        severity: advice ? 'minor' : (SEVERITY[text(rule.impact)] ?? 'moderate'),
+        html: text(node.html).replace(/\s+/g, ' ').slice(0, 160),
+        selector: strings(node.target).join(' '),
+        page,
+        why: kind === 'incomplete'
+            ? `${help}. axe could not determine this one: ${tidySummary(text(node.failureSummary), 'no reason given')}`
+            : help,
+        next: tidySummary(text(node.failureSummary), help),
+    }));
+}
+const OUTCOMES = ['violations', 'incomplete', 'passes', 'inapplicable'];
+/** One axe result object: what `axe.run()` resolves to. */
+function fromResult(result, page, run) {
+    // Recorded before any finding is read: a page on which every rule passed has still been opened,
+    // and leaving it out made a clean page look like one the browser never visited.
+    run.pages.add(page);
+    for (const outcome of OUTCOMES) {
+        for (const rule of (Array.isArray(result[outcome]) ? result[outcome] : [])) {
+            const id = text(rule.id);
+            if (id !== '')
+                run.rulesRun.add(id);
+            const criterion = criterionFrom(strings(rule.tags));
+            if (criterion)
+                run.criteriaCovered.add(criterion);
+            // Only the two outcomes that need a person's attention become findings. A rule that passed
+            // or did not apply is evidence of coverage, not something to report.
+            if (outcome === 'violations')
+                run.findings.push(...fromRule(rule, page, 'violation'));
+            if (outcome === 'incomplete')
+                run.findings.push(...fromRule(rule, page, 'incomplete'));
+        }
+    }
+}
+/** True of anything shaped like the object `axe.run()` resolves to. */
+function looksLikeAxe(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return Array.isArray(v.violations) || Array.isArray(v.incomplete) || Array.isArray(v.passes);
+}
+/**
+ * Reads an axe report, in any of the shapes real suites write it.
+ *
+ * One run; an array of runs, which is what a suite checking several pages produces; or an array of
+ * `{ url, result }` wrappers, which is what people write when they want to keep the page alongside
+ * its findings. Guessing wrong here means reporting a clean page, so an unreadable file throws
+ * rather than returning nothing.
+ */
+export function readAxeReport(path) {
+    let parsed;
+    const raw = readFileSync(path, 'utf8');
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${path} is not JSON. Tewip reads the JSON an axe run writes.`);
+    }
+    const run = { findings: [], pages: new Set(), rulesRun: new Set(), criteriaCovered: new Set() };
+    const pageOf = (v, fallback) => text(v.url) || text(v.page) || fallback;
+    if (looksLikeAxe(parsed)) {
+        fromResult(parsed, pageOf(parsed, path), run);
+        return run;
+    }
+    if (Array.isArray(parsed)) {
+        let read = 0;
+        for (const entry of parsed) {
+            if (looksLikeAxe(entry)) {
+                fromResult(entry, pageOf(entry, path), run);
+                read++;
+                continue;
+            }
+            // A wrapper: { page | url, result: <axe run> }.
+            if (typeof entry !== 'object' || entry === null)
+                continue;
+            const wrapper = entry;
+            // axe records the page it actually ran against in `result.url`, which is authoritative.
+            // A wrapper's own label is only a fallback for runs that did not keep it.
+            if (looksLikeAxe(wrapper.result)) {
+                fromResult(wrapper.result, pageOf(wrapper.result, pageOf(wrapper, path)), run);
+                read++;
+            }
+        }
+        if (read > 0 || parsed.length === 0)
+            return run;
+    }
+    throw new Error(`${path} is JSON, but not an axe report: Tewip looked for a "violations" array, a list of runs, ` +
+        'or a list of { page, result } wrappers. Write one with axe.run() in your Playwright, Cypress or jest-axe suite.');
+}
+/**
+ * The axe rule that tests the same thing as one of Tewip's source-read rules.
+ *
+ * Supersession is decided here, rule by rule, rather than by criterion. By criterion it is too
+ * coarse and loses real findings: axe reporting `aria-required-children` means it checked *that*
+ * part of 1.3.1, not that it looked at heading structure, which axe treats as best-practice and
+ * tests under no criterion at all. Nineteen real heading findings disappeared that way before this
+ * map existed.
+ *
+ * `click-without-keyboard` has no entry on purpose: axe has no equivalent rule, so a source finding
+ * for it is never superseded by any run.
+ */
+export const EQUIVALENT_AXE_RULE = {
+    'image-alt': 'image-alt',
+    'input-label': 'label',
+    'button-name': 'button-name',
+    'link-name': 'link-name',
+    'html-lang': 'html-has-lang',
+    'iframe-title': 'frame-title',
+    'zoom-blocked': 'meta-viewport',
+    'nested-interactive': 'nested-interactive',
+    'aria-hidden-focusable': 'aria-hidden-focus',
+    'duplicate-id': 'duplicate-id',
+    'aria-unknown': 'aria-valid-attr',
+    'positive-tabindex': 'tabindex',
+    'autoplay-sound': 'no-autoplay-audio',
+    'heading-skip': 'heading-order',
+};

package/dist/engine/access/wcag.js

@@ -106,7 +106,17 @@ export const RULES = {
  * every time is what stops "Tewip found no barriers" from being heard as "this is accessible".
  */
 export const NOT_CHECKED = [
-    { criterion: '1.4.3 Contrast (Minimum)', why: 'needs the computed colours of a rendered page, not the markup' },
+    {
+        criterion: '1.4.3 Contrast (Minimum)',
+        why: 'needs the computed colours of a rendered page, not the markup',
+        // The one entry on this list a browser run genuinely closes (Phase 29).
+        settledBy: 'color-contrast',
+    },
+    // Everything below has no `settledBy` on purpose, and must not acquire one because a tool
+    // reports something under the same criterion number. axe's `image-alt` checks that an alt
+    // attribute exists; it has no opinion on whether the words describe the picture, which is the
+    // part named here. Matching on the number alone briefly made Tewip claim it had checked alt-text
+    // quality and timing behaviour, which no tool can.
     { criterion: '1.1.1 Non-text Content, quality', why: 'whether alt text actually describes the picture is a human judgement' },
     { criterion: '2.4.7 Focus Visible', why: 'needs a rendered page to see whether the focus ring survives the stylesheet' },
     { criterion: '1.3.2 Meaningful Sequence', why: 'needs the rendered order, which CSS can change from the source order' },

package/dist/mcp/tools-prove.js

@@ -101,21 +101,42 @@ export function registerProofTools(server, { answer, readOnly, project }) {
         inputSchema: {
             project,
             path: z.string().optional().describe('A file or directory inside the project to check instead of all of it'),
+            axeReport: z
+                .string()
+                .optional()
+                .describe('The JSON from an axe run, if the project has one. It settles contrast, which reading markup cannot, and its findings are triaged rather than relayed: axe rules that map to no WCAG criterion are reported as advice, and what axe could not determine becomes a question.'),
         },
         annotations: readOnly,
-    }, ({ project: root, path }) => answer(async () => {
+    }, ({ project: root, path, axeReport }) => answer(async () => {
         if (!isAbsolute(root) || !existsSync(root))
             throw new Error(`project must be an existing absolute path, got "${root}"`);
         // The pure functions, not runAccess: that one prints, and anything on stdout breaks JSON-RPC.
         const { findBarriers, keyOf, readAccepted, renderAccess } = await import('../engine/access/access-command.js');
+        const { merge, pagesIn } = await import('../engine/access/merge.js');
+        const { readAxeReport } = await import('../engine/access/reports.js');
         const { findings, filesRead } = findBarriers(root, path);
         const judged = readAccepted(root);
         const open = findings.filter((f) => !judged.has(keyOf(f)));
+        const run = axeReport ? readAxeReport(isAbsolute(axeReport) ? axeReport : `${root}/${axeReport}`) : undefined;
+        const graded = run ? merge(open, run, root) : undefined;
+        const kept = graded ? graded.kept : open;
         return renderAccess({
-            barriers: open.filter((f) => f.confidence === 'barrier'),
-            questions: open.filter((f) => f.confidence === 'ask-a-person'),
+            barriers: kept.filter((f) => f.confidence === 'barrier'),
+            questions: kept.filter((f) => f.confidence === 'ask-a-person'),
             accepted: findings.filter((f) => judged.has(keyOf(f))),
             filesRead,
+            ...(run && graded
+                ? {
+                    browser: {
+                        barriers: run.findings.filter((f) => f.confidence === 'barrier'),
+                        questions: run.findings.filter((f) => f.confidence === 'ask-a-person'),
+                        advice: run.findings.filter((f) => f.confidence === 'advice'),
+                        superseded: graded.superseded,
+                        pages: pagesIn(run),
+                        rulesRun: run.rulesRun,
+                    },
+                }
+                : {}),
         }, path ?? root);
     }));
     server.registerTool('project_standards', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "mcpName": "io.github.hmamut39/tewip",
   "description": "Tewip finds why each failing test failed - real bug, flaky test, environment, test data or changed selector - for any stack, from the command line, CI, or your editor.",
   "keywords": [