tewip-ai 0.34.0 → 0.35.0

package/README.md

@@ -574,6 +574,61 @@ With `--json` the verdict is **sealed**: editing `not-ready` to `ready` in the f
 fail, so a verdict that travels into a ticket or a release note can be checked rather than trusted. It is
 also an MCP tool, so an agent can ask whether its own work is done before saying that it is.
 
+## Can everybody use it? (Phase 28, new)
+
+```bash
+tewip access                           # every markup file in the project
+tewip access src/components/Nav.tsx    # or just one
+tewip access --strict                  # fails the build on a barrier that stops somebody outright
+```
+
+Accessibility is the one quality question that is also a legal one. The European Accessibility Act has
+been enforceable since June 2025, and it lands on the people who already own testing.
+
+The reason teams do not trust the tools they have is the reason they switch off every scanner: axe,
+Lighthouse and pa11y hand back several hundred undifferentiated violations, a large share of which are
+not barriers at all, and nobody has the afternoon it takes to sort them.
+
+Tewip makes **two kinds of statement and no third**:
+
+- **a barrier** — the element as written stops somebody, and reading it is enough to know that;
+- **a question** — something here is missing or unreadable, and only you can settle it.
+
+There is no "warning", because a warning is the category people learn to scroll past.
+
+```
+**6 barriers (5 that stop somebody outright), 18 for a person to settle.**
+
+### button-name - 3 places
+
+WCAG 2.2 4.1.2 Name, Role, Value (A), blocker.
+
+Who it stops: a screen reader announces "button" and nothing else, so it cannot be used or spoken to.
+
+- `components/VPNavBarAskAiButton.vue:2`  <button type="button" class="VPNavBarAskAiButton">
+  - it contains no text and carries no aria-label, so it is announced with its role and nothing else
+  - do this: put text inside it, or add aria-label="..." saying what it does
+```
+
+Every finding names its **WCAG 2.2 success criterion and level**, which is what turns it into something
+you can put in front of a regulator instead of a note saying "bad contrast".
+
+**What it refuses to decide is the reason it is worth running.** `alt={caption}` is not a missing alt.
+A button whose text comes from a child component cannot be called empty. `:aria-label="label"` is a
+label. `<slot />` is content this file cannot see. Each of those becomes a question, never an accusation
+— because a tool that accuses `<img alt={alt} />` of having no alt text gets switched off in a day.
+
+**And every report prints what it did not check** — contrast, focus order, meaningful sequence, whether
+the alt text is any good — because those need a rendered page. A clean result means these checks found
+nothing. It never means the product is accessible.
+
+No browser, no server, no network, no model, no cost. 416 real files in 1.65 seconds.
+
+Measured on four public projects, never on fixtures — excalidraw, bootstrap, vitepress and svelte:
+**50 barriers, 29 of them the kind that stop somebody outright, and 90 questions.** Seven false-positive
+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).
+
 ## Teach it your house rules (Phase 27)
 
 ```bash

package/dist/cli/help.js

@@ -118,6 +118,16 @@ 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]
+                                    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
+                                    2.2 criterion, which is what a regulator asks for. What only a
+                                    person can settle is kept apart from what is proved, and every
+                                    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.
   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

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

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

@@ -0,0 +1,164 @@
+// Phase 28: `tewip access` - the accessibility barriers that can be proved by reading the markup,
+// separated from the questions only a person can answer, with everything it did not check named.
+//
+// Why this exists when axe, Lighthouse and pa11y already do: those tools hand a team a few hundred
+// undifferentiated violations, a large share of which are not barriers at all, and the team turns
+// the check off. Tewip makes exactly two kinds of statement - "this stops somebody, here is the
+// element" and "only you can settle this one" - and prints the criteria it cannot reach. It needs
+// no browser, no server, no network and no model, so it runs on any repository in a second.
+//
+// It never says a page is accessible. It says what was checked.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+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 { 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". */
+export function readAccepted(root) {
+    const file = join(root, '.tewip', 'access-accepted.txt');
+    if (!existsSync(file))
+        return new Set();
+    return new Set(readFileSync(file, 'utf8')
+        .split('\n')
+        .map((l) => l.split(' - ')[0].trim())
+        .filter((l) => l !== '' && !l.startsWith('#')));
+}
+export function keyOf(f) {
+    return `${f.rule} ${f.file}:${f.line}`;
+}
+export function worstFirst(a, b) {
+    const sa = ORDER[RULES[a.rule]?.severity ?? 'minor'];
+    const sb = ORDER[RULES[b.rule]?.severity ?? 'minor'];
+    if (sa !== sb)
+        return sa - sb;
+    if (a.file !== b.file)
+        return a.file < b.file ? -1 : 1;
+    return a.line - b.line;
+}
+/** Reads every markup file under `root` and returns what the markup alone can settle. */
+/**
+ * Markup written to exercise code, not to be used by a person. An `<img>` with no alt in a
+ * clipboard test is not a barrier to anybody, and excalidraw's test suite produced exactly that.
+ */
+const TEST_MARKUP = /(?:^|[\\/])(?:__tests__|__mocks__|tests?|spec|e2e|stories|fixtures?)[\\/]|\.(?:test|spec|stories|cy)\.[cm]?[jt]sx?$/i;
+export function findBarriers(root, only) {
+    const base = only ? resolve(root, only) : root;
+    const all = existsSync(base) && MARKUP.test(base) ? [base] : sourceFiles(base).filter((f) => MARKUP.test(f));
+    // Asking for a path by name overrides the exclusion: if you point at a fixture, you want it read.
+    const files = only ? all : all.filter((f) => !TEST_MARKUP.test(relative(root, f)));
+    const findings = [];
+    let filesRead = 0;
+    for (const path of files) {
+        let source;
+        try {
+            source = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // A file too large to be hand-written is generated or minified, and accusing it helps nobody.
+        if (source.length > 400_000)
+            continue;
+        filesRead++;
+        const jsLike = JS_LIKE.test(path);
+        // One page, rather than a file of components: only then do repeated ids land in one document.
+        const isDocument = /\.html?$/i.test(path);
+        findings.push(...checkFile(source, tags(source, jsLike), relative(root, path).replaceAll('\\', '/'), isDocument));
+    }
+    return { findings, filesRead };
+}
+function group(findings) {
+    const by = new Map();
+    for (const f of findings) {
+        const list = by.get(f.rule);
+        if (list)
+            list.push(f);
+        else
+            by.set(f.rule, [f]);
+    }
+    return by;
+}
+function section(title, findings, lines) {
+    if (findings.length === 0)
+        return;
+    lines.push(`## ${title}`, '');
+    for (const [rule, found] of group(findings)) {
+        const meta = RULES[rule];
+        lines.push(`### ${rule} - ${found.length} ${found.length === 1 ? 'place' : 'places'}`, '');
+        lines.push(`${criterionOf(rule)}, ${meta?.severity ?? 'unrated'}.`, '');
+        if (meta)
+            lines.push(`Who it stops: ${meta.stops}.`, '');
+        for (const f of found.slice(0, 20)) {
+            lines.push(`- \`${f.file}:${f.line}\`  ${f.element}`);
+            lines.push(`  - ${f.why}`);
+            lines.push(`  - do this: ${f.next}`);
+        }
+        if (found.length > 20)
+            lines.push(`- ...and ${found.length - 20} more of the same, in the JSON beside this report.`);
+        lines.push('');
+    }
+}
+export function renderAccess(result, scanned) {
+    const { barriers, questions, accepted, filesRead } = 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) {
+        lines.push('No barrier was found that reading the markup can settle, and nothing needs a decision.', '');
+    }
+    else {
+        const stopping = barriers.filter((f) => blocks(f.rule)).length;
+        const counts = [
+            `${barriers.length} ${barriers.length === 1 ? 'barrier' : 'barriers'} (${stopping} that stop somebody outright)`,
+            `${questions.length} for a person to settle`,
+        ];
+        if (accepted.length > 0)
+            counts.push(`${accepted.length} already accepted`);
+        lines.push(`**${counts.join(', ')}.**`, '');
+    }
+    section('Barriers', [...barriers].sort(worstFirst), lines);
+    section('Only a person can settle these', [...questions].sort(worstFirst), lines);
+    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.`, '');
+    }
+    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(`- **${n.criterion}** - ${n.why}`);
+    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.', '');
+    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');
+}
+export function runAccess(cmd) {
+    const root = resolve(cmd.root);
+    const { findings, filesRead } = findBarriers(root, cmd.only);
+    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 };
+    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.`);
+        process.exitCode = 1;
+    }
+    if (cmd.out) {
+        const path = resolve(root, cmd.out);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, report, 'utf8');
+        writeFileSync(path.replace(/\.md$/, '') + '.json', JSON.stringify({ barriers, questions, accepted, filesRead }, null, 2), 'utf8');
+    }
+    return { ...result, report };
+}

package/dist/engine/access/checks.js

@@ -0,0 +1,231 @@
+// Phase 28: the checks. Each one is deterministic, each one names the element it is talking about,
+// and each one has a shape it refuses rather than guesses on.
+//
+// The restraint matters more than the coverage. These are the barriers that can be decided by
+// reading the markup - a picture with no alt attribute at all, a field with no label anywhere, a
+// div that only answers to a mouse. The ones that need a rendered page (contrast, focus order,
+// whether alt text is any good) are not attempted here and are listed in NOT_CHECKED instead.
+import { inside, labelledBy } from './markup.js';
+/** Elements that already answer to the keyboard and already carry a role. */
+const INTERACTIVE = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary', 'details']);
+/** `role="presentation"` and friends: the author has said this is decoration. */
+function decorative(t) {
+    return t.attrs['aria-hidden'] === 'true' || t.attrs.role === 'presentation' || t.attrs.role === 'none';
+}
+function show(t) {
+    const keep = ['src', 'href', 'type', 'name', 'id', 'class', 'role'];
+    const shown = keep
+        .filter((k) => typeof t.attrs[k] === 'string' && t.attrs[k] !== '')
+        .slice(0, 2)
+        .map((k) => ` ${k}="${t.attrs[k].slice(0, 40)}"`)
+        .join('');
+    return `<${t.name}${shown}${t.spread ? ' {...}' : ''}>`;
+}
+function at(t, file) {
+    return { file, line: t.line, element: show(t) };
+}
+/** Every real `aria-*` attribute. A name outside this set is a typo, and a typo does nothing at all. */
+const ARIA = new Set([
+    'aria-activedescendant', 'aria-atomic', 'aria-autocomplete', 'aria-braillelabel', 'aria-brailleroledescription',
+    'aria-busy', 'aria-checked', 'aria-colcount', 'aria-colindex', 'aria-colindextext', 'aria-colspan',
+    'aria-controls', 'aria-current', 'aria-describedby', 'aria-description', '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-rowindextext', 'aria-rowspan', 'aria-selected', 'aria-setsize',
+    'aria-sort', 'aria-valuemax', 'aria-valuemin', 'aria-valuenow', 'aria-valuetext',
+]);
+/** A click handler, in any of the four dialects this scanner reads. */
+function clickHandler(t) {
+    return ['onclick', '@click', 'v-on:click', 'on:click'].some((a) => a in t.attrs || t.dynamic.has(a));
+}
+function keyHandler(t) {
+    return Object.keys(t.attrs).concat([...t.dynamic]).some((a) => /key(down|up|press)/i.test(a));
+}
+function tabIndexOf(t) {
+    const raw = t.attrs.tabindex ?? t.attrs.tabIndex;
+    if (raw === undefined)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Fields that take typing, and therefore need a label. Buttons and hidden fields are excluded: a
+ * submit button is named by its value, and a hidden field is not announced at all.
+ */
+const UNLABELLED_TYPES = new Set(['hidden', 'submit', 'reset', 'button', 'image']);
+/** Checks that look at one element at a time. */
+function perElement(t, file, labelFor, openLabels, ancestorKey) {
+    const out = [];
+    const place = at(t, file);
+    const name = labelledBy(t);
+    if (t.name === 'img' && !t.component) {
+        if (decorative(t)) {
+            // Said to be decoration. That is a legitimate choice and not Tewip's to second-guess.
+        }
+        else if ('alt' in t.attrs || t.dynamic.has('alt')) {
+            // An alt attribute is present. Whether its words are any good is in NOT_CHECKED.
+        }
+        else if (t.spread) {
+            out.push({ rule: 'image-alt', confidence: 'ask-a-person', ...place,
+                why: 'no alt attribute is written here, but the element carries a spread, so alt may come from the props',
+                next: 'check what is spread in; if alt is not among it, add alt, or alt="" if the image is decoration' });
+        }
+        else {
+            out.push({ rule: 'image-alt', confidence: 'barrier', ...place,
+                why: 'no alt attribute at all, and nothing marks the image as decoration',
+                next: 'add alt="..." describing what the image conveys, or alt="" if it conveys nothing' });
+        }
+    }
+    if (t.name === 'input' && !UNLABELLED_TYPES.has(t.attrs.type ?? 'text')) {
+        const linked = typeof t.attrs.id === 'string' && labelFor.has(t.attrs.id);
+        if (!name.named && !linked && openLabels === 0) {
+            if (name.unknown || t.dynamic.has('id')) {
+                out.push({ rule: 'input-label', confidence: 'ask-a-person', ...place,
+                    why: 'no label, aria-label or wrapping <label> can be read here, and part of the element is an expression',
+                    next: 'confirm the field is labelled at runtime; if not, add aria-label or a <label for>' });
+            }
+            else {
+                out.push({ rule: 'input-label', confidence: 'barrier', ...place,
+                    why: 'no aria-label, no title, no id matching a <label for>, and not inside a <label>',
+                    next: 'wrap it in a <label>, or give it an id and point a <label for> at it' });
+            }
+        }
+    }
+    if (t.name === 'iframe' && !name.named && !decorative(t)) {
+        out.push({ rule: 'iframe-title', confidence: name.unknown ? 'ask-a-person' : 'barrier', ...place,
+            why: 'an iframe with no title and no aria-label',
+            next: 'add title="..." saying what the frame contains' });
+    }
+    const tabindex = tabIndexOf(t);
+    if (tabindex !== null && tabindex > 0) {
+        out.push({ rule: 'positive-tabindex', confidence: 'barrier', ...place,
+            why: `tabindex="${tabindex}" takes this element out of the document order and puts it before everything that has none`,
+            next: 'use tabindex="0" and let the source order decide, or move the element in the markup' });
+    }
+    if (t.attrs['aria-hidden'] === 'true' && (INTERACTIVE.has(t.name) || (tabindex !== null && tabindex >= 0))) {
+        out.push({ rule: 'aria-hidden-focusable', confidence: 'barrier', ...place,
+            why: 'hidden from screen readers but still reachable by the tab key',
+            next: 'also remove it from the tab order with tabindex="-1", or stop hiding it' });
+    }
+    // `ancestorKey`: an enclosing element already handles keys, which is how every dialog in the
+    // world is built - a backdrop div closes on click, and Escape closes it from the dialog itself.
+    // WCAG 2.1.1 asks that the *function* be reachable from the keyboard, not that this particular
+    // div be focusable. Excalidraw's Modal.tsx is exactly this shape, and calling it a blocker is wrong.
+    if (clickHandler(t) && !INTERACTIVE.has(t.name) && !t.component && !t.attrs.role && tabindex === null && !keyHandler(t) && !ancestorKey) {
+        out.push({ rule: 'click-without-keyboard', confidence: 'barrier', ...place,
+            why: 'it responds to a click, but it has no role, no tabindex and no key handler, so the keyboard cannot reach or fire it',
+            next: 'use a <button>, or add role="button", tabindex="0" and a key handler' });
+    }
+    if ((t.name === 'video' || t.name === 'audio') && 'autoplay' in t.attrs && !('muted' in t.attrs)) {
+        out.push({ rule: 'autoplay-sound', confidence: 'barrier', ...place,
+            why: 'it plays on load and is not muted, so it talks over a screen reader',
+            next: 'add muted, or remove autoplay and let the person press play' });
+    }
+    if (t.name === 'meta' && (t.attrs.name ?? '').toLowerCase() === 'viewport') {
+        const content = (t.attrs.content ?? '').toLowerCase();
+        const max = /maximum-scale\s*=\s*([\d.]+)/.exec(content);
+        if (/user-scalable\s*=\s*(no|0)/.test(content) || (max && Number(max[1]) < 2)) {
+            out.push({ rule: 'zoom-blocked', confidence: 'barrier', ...place,
+                why: `the viewport meta tag prevents zooming: ${content}`,
+                next: 'drop user-scalable=no and maximum-scale, or set maximum-scale to at least 2' });
+        }
+    }
+    for (const a of Object.keys(t.attrs).concat([...t.dynamic])) {
+        if (a.startsWith('aria-') && !ARIA.has(a)) {
+            out.push({ rule: 'aria-unknown', confidence: 'barrier', ...place,
+                why: `${a} is not an ARIA attribute, so it is ignored entirely and whatever it was meant to do does not happen`,
+                next: 'correct the spelling, or remove it' });
+        }
+    }
+    return out;
+}
+/**
+ * Everything that needs more than one element: names from content, nesting, ids, heading order.
+ *
+ * `isDocument` says this file is one page. It is false for a component file, and that distinction
+ * decides whether duplicate ids mean anything: excalidraw's icons.tsx holds fifty separate SVG
+ * icons, each with its own `<clipPath id="a">`, and they are never in one document together. A
+ * check that calls that a defect is wrong fifty times in one file.
+ */
+export function checkFile(source, all, file, isDocument = false) {
+    const out = [];
+    const labelFor = new Set(all.filter((t) => t.name === 'label' && t.attrs.for).map((t) => t.attrs.for));
+    const seenIds = new Set();
+    let openLabels = 0;
+    let interactiveDepth = 0;
+    let lastHeading = 0;
+    /** The elements currently open around this one, and whether each handles keys. */
+    const open = [];
+    for (const [i, t] of all.entries()) {
+        if (t.name === 'label')
+            openLabels += t.closing ? -1 : t.selfClosing ? 0 : 1;
+        if (t.closing) {
+            if (INTERACTIVE.has(t.name) && interactiveDepth > 0)
+                interactiveDepth--;
+            // Unwind to the matching open element, tolerating markup that never closed it.
+            const from = open.map((o) => o.name).lastIndexOf(t.name);
+            if (from !== -1)
+                open.length = from;
+            continue;
+        }
+        out.push(...perElement(t, file, labelFor, Math.max(openLabels - (t.name === 'label' ? 1 : 0), 0), open.some((o) => o.keys)));
+        if (!t.selfClosing)
+            open.push({ name: t.name, keys: keyHandler(t) });
+        const id = t.attrs.id;
+        if (isDocument && id && !t.dynamic.has('id')) {
+            if (seenIds.has(id)) {
+                out.push({ rule: 'duplicate-id', confidence: 'barrier', ...at(t, file),
+                    why: `id="${id}" is used more than once in this file, so anything pointing at it reaches only the first`,
+                    next: 'make the ids unique' });
+            }
+            seenIds.add(id);
+        }
+        const heading = /^h([1-6])$/.exec(t.name);
+        if (heading) {
+            const level = Number(heading[1]);
+            if (lastHeading > 0 && level > lastHeading + 1) {
+                out.push({ rule: 'heading-skip', confidence: 'barrier', ...at(t, file),
+                    why: `h${level} follows h${lastHeading}, so a level is missing from the outline`,
+                    next: `use h${lastHeading + 1} here, or add the missing heading above it` });
+            }
+            lastHeading = level;
+        }
+        // A name from content: a button or link whose text is the only thing announcing it.
+        if ((t.name === 'button' || (t.name === 'a' && ('href' in t.attrs || t.dynamic.has('href')))) && !t.component) {
+            const label = labelledBy(t);
+            if (!label.named) {
+                const body = inside(source, all, i);
+                const rule = t.name === 'button' ? 'button-name' : 'link-name';
+                if (body.text !== '') {
+                    // Named by its own text. Nothing to say.
+                }
+                else if (label.unknown || body.unreadable) {
+                    out.push({ rule, confidence: 'ask-a-person', ...at(t, file),
+                        why: 'its name would come from content this scanner cannot read - an expression, a component, or an image whose alt is set elsewhere',
+                        next: 'check what it announces with a screen reader; if it is silent, add aria-label' });
+                }
+                else {
+                    out.push({ rule, confidence: 'barrier', ...at(t, file),
+                        why: 'it contains no text and carries no aria-label, so it is announced with its role and nothing else',
+                        next: 'put text inside it, or add aria-label="..." saying what it does' });
+                }
+            }
+            if (interactiveDepth > 0) {
+                out.push({ rule: 'nested-interactive', confidence: 'barrier', ...at(t, file),
+                    why: 'a link or button inside another link or button',
+                    next: 'move it out, so the two controls are siblings rather than nested' });
+            }
+            if (!t.selfClosing)
+                interactiveDepth++;
+        }
+    }
+    const html = all.find((t) => t.name === 'html' && !t.closing);
+    if (html && !('lang' in html.attrs) && !html.dynamic.has('lang')) {
+        out.push({ rule: 'html-lang', confidence: 'barrier', ...at(html, file),
+            why: 'the <html> element has no lang attribute, so a screen reader guesses the language',
+            next: 'add lang="en", or whichever language the page is written in' });
+    }
+    return out;
+}

package/dist/engine/access/markup.js

@@ -0,0 +1,174 @@
+// Phase 28: reading markup well enough to be honest about it.
+//
+// This is not an HTML parser and does not try to be. It is a tolerant tag scanner over the four
+// shapes a real project writes its interface in - HTML, JSX/TSX, Vue and Svelte templates - and its
+// one job is to know *when it does not know*. An attribute whose value is an expression
+// (`alt={caption}`), an element carrying a spread (`<img {...props} />`), a component rather than an
+// element (`<Image />`): in every one of those the markup alone cannot say whether a barrier exists,
+// and the scanner says so rather than guessing. That refusal is the whole reason this is worth
+// shipping; a tool that accuses `<img alt={alt} />` of having no alt text gets switched off in a day.
+//
+// Everything here is deterministic and costs nothing: no browser, no network, no model.
+/**
+ * Elements HTML closes for you. A scanner that expects `</img>` pairs everything wrong from the
+ * first image onwards, which is how naive checkers end up reporting a button as empty.
+ */
+const VOID = new Set([
+    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr',
+]);
+/**
+ * A tag, with the three attribute-value shapes that appear in practice kept apart from `>` so an
+ * expression containing a greater-than sign does not end the tag early.
+ */
+// The lookahead after the name is load-bearing: a real tag is followed by whitespace, `/` or `>`.
+// Without it `/<!doctype html|<html[\s>]/i` - a regex literal in excalidraw's App.tsx - parsed as an
+// <html> element and was reported as a page with no lang attribute.
+// The attribute group is lazy on purpose. Greedy, it absorbs the `/` of `<button ... />` into the
+// attributes, the element is recorded as still open, and the next sibling control is reported as
+// nested inside it. Quoted and braced values are matched as whole units in the alternation, so
+// laziness cannot stop at a `>` that lives inside one.
+const TAG = /<(\/?)([A-Za-z][A-Za-z0-9._:-]*)(?=[\s/>])((?:[^>"'{]|"[^"]*"|'[^']*'|\{(?:[^{}]|\{(?:[^{}]|\{[^{}]*\})*\})*\})*?)(\/?)>/g;
+const ATTRIBUTE = /([@:#\[A-Za-z_][-A-Za-z0-9_:.@\]]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|\{((?:[^{}]|\{[^{}]*\})*)\}|([^\s"'<>`=]+)))?/g;
+/** `{...props}`, `{...rest}` - the thing that makes every other judgement about the element unsafe. */
+const SPREAD = /\{\s*\.\.\./;
+/**
+ * Comments, and the bodies of script and style, hold things shaped like tags that are not tags.
+ *
+ * `jsLike` additionally blanks template literals, which is not optional in a .tsx file: real
+ * projects build HTML in backtick strings - an iframe's srcDoc, an email body, a test fixture - and
+ * reading those as the page's own markup produces findings about code that no browser ever renders
+ * as part of this component. Found on excalidraw, whose AI.tsx holds an entire error page in a
+ * template literal and was reported as a page with no lang attribute.
+ *
+ * Blanking rather than scanning is the conservative choice: a string may be a page, or it may be a
+ * SQL query, a documentation sample or an assertion. Tewip does not guess which.
+ */
+function withoutNonMarkup(source, jsLike) {
+    const blank = (m) => m.replace(/[^\n]/g, ' ');
+    const stripped = source
+        .replace(/<!--[\s\S]*?-->/g, blank)
+        .replace(/\{\/\*[\s\S]*?\*\/\}/g, blank)
+        .replace(/<script\b[\s\S]*?<\/script\s*>/gi, blank)
+        .replace(/<style\b[\s\S]*?<\/style\s*>/gi, blank);
+    return jsLike ? stripped.replace(/`(?:[^`\\]|\\[\s\S])*`/g, blank) : stripped;
+}
+/** Files whose markup is embedded in JavaScript, where a backtick string is not page markup. */
+export const JS_LIKE = /\.(?:[cm]?[jt]sx?|vue|svelte|astro)$/i;
+function readAttributes(blob) {
+    const attrs = {};
+    const dynamic = new Set();
+    const spread = SPREAD.test(blob);
+    // A spread's contents would otherwise be read as attribute names: `{...props}` becomes `props`.
+    const readable = blob.replace(/\{\s*\.\.\.(?:[^{}]|\{[^{}]*\})*\}/g, ' ');
+    for (const m of readable.matchAll(ATTRIBUTE)) {
+        // A bound attribute is the same attribute. Vue writes `:aria-label="label"` and
+        // `v-bind:title="t"`, Angular writes `[attr.aria-label]="l"`, and reading those names
+        // literally means the element looks as though it has no label at all - which reported eight
+        // perfectly well-labelled buttons in vitepress as unnamed. The value is an expression, so the
+        // attribute is present but unreadable: that is `dynamic`, which asks rather than accuses.
+        const written = m[1].toLowerCase();
+        const binding = /^(?::|v-bind:|\[attr\.|\[)/.exec(written);
+        const name = binding ? written.slice(binding[0].length).replace(/\]$/, '') : written;
+        const quoted = m[2] ?? m[3] ?? m[5];
+        const expression = m[4];
+        if (binding && name !== '') {
+            dynamic.add(name);
+            continue;
+        }
+        if (expression !== undefined) {
+            // A literal inside braces is still a literal: alt={"a cat"} and alt={''} are both readable.
+            const literal = /^\s*(?:"([^"]*)"|'([^']*)'|`([^`$]*)`)\s*$/.exec(expression);
+            if (literal)
+                attrs[name] = literal[1] ?? literal[2] ?? literal[3] ?? '';
+            else
+                dynamic.add(name);
+            continue;
+        }
+        attrs[name] = quoted ?? '';
+    }
+    return { attrs, dynamic, spread };
+}
+/** Every tag in a file, in source order. `jsLike` says to ignore template literals. */
+export function tags(source, jsLike = false) {
+    const text = withoutNonMarkup(source, jsLike);
+    const out = [];
+    let line = 1;
+    let read = 0;
+    for (const m of text.matchAll(TAG)) {
+        const at = m.index;
+        for (let i = read; i < at; i++)
+            if (text[i] === '\n')
+                line++;
+        read = at;
+        const raw = m[2];
+        const name = raw.toLowerCase();
+        out.push({
+            name,
+            component: /^[A-Z]/.test(raw) || raw.includes('.'),
+            ...readAttributes(m[3]),
+            closing: m[1] === '/',
+            selfClosing: m[4] === '/' || VOID.has(name),
+            line,
+            start: at,
+            end: at + m[0].length,
+        });
+    }
+    return out;
+}
+/** Reads what is inside the element opened by `tags[index]`, pairing tags with a depth count. */
+export function inside(source, all, index) {
+    const open = all[index];
+    if (open.selfClosing || open.closing)
+        return { text: '', unreadable: false, within: [] };
+    let depth = 1;
+    let close = -1;
+    const within = [];
+    for (let i = index + 1; i < all.length; i++) {
+        const t = all[i];
+        if (t.name === open.name && !t.selfClosing)
+            depth += t.closing ? -1 : 1;
+        if (depth === 0) {
+            close = i;
+            break;
+        }
+        within.push(t);
+    }
+    // No closing tag found: the file is a fragment, or the markup is broken. Either way, refuse.
+    if (close === -1)
+        return { text: '', unreadable: true, within };
+    const between = source.slice(open.end, all[close].start);
+    const literal = between
+        .replace(/<[^>]*>/g, ' ')
+        .replace(/\{(?:[^{}]|\{[^{}]*\})*\}/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    const expressions = /\{(?:[^{}]|\{[^{}]*\})*\}/.test(between);
+    // An image inside a link or button *is* its accessible name when it has alt text. A logo link
+    // written `<a href="/"><img src="logo.png" alt="Home"></a>` is the commonest shape on the web,
+    // and reporting it as an unnamed link would be wrong on nearly every site there is.
+    const alts = within
+        .filter((t) => t.name === 'img' && typeof t.attrs.alt === 'string' && t.attrs.alt.trim() !== '')
+        .map((t) => t.attrs.alt.trim());
+    // `<slot />` is Vue's and Svelte's `{children}`: whatever is inside comes from whoever used this
+    // component, so the markup here cannot say whether the control ends up named. vitepress's
+    // VPSwitch is exactly that shape and was being accused rather than asked about.
+    const unknownChild = within.some((t) => t.component || t.name === 'slot' || t.dynamic.size > 0 || t.spread);
+    const text = [literal, ...alts].filter((s) => s !== '').join(' ');
+    return { text, unreadable: expressions || (unknownChild && alts.length === 0), within };
+}
+/** The accessible name an element carries on its own attributes, if one can be read. */
+export function labelledBy(tag) {
+    const explicit = ['aria-label', 'aria-labelledby', 'title', 'alt'];
+    for (const a of explicit) {
+        if (tag.dynamic.has(a))
+            return { named: false, unknown: true };
+        const v = tag.attrs[a];
+        if (typeof v === 'string' && v.trim() !== '')
+            return { named: true, unknown: false };
+    }
+    if (tag.spread)
+        return { named: false, unknown: true };
+    return { named: false, unknown: false };
+}
+/** Files whose markup this scanner reads. */
+export const MARKUP = /\.(?:html?|jsx|tsx|vue|svelte|astro|erb|php)$/i;

package/dist/engine/access/wcag.js

@@ -0,0 +1,125 @@
+// Phase 28: the catalogue. Which success criterion each check belongs to, how much it matters, and
+// - the part no other tool writes down - which criteria this check deliberately does not touch.
+//
+// Why the criterion numbers are here at all: accessibility is the one quality question that is also
+// a legal one. The European Accessibility Act has been enforceable since June 2025 and the US
+// Section 508 and ADA rules point at the same standard, WCAG 2.2 level AA. A finding a team can
+// trace to a numbered criterion is a finding they can put in front of a lawyer or a regulator; a
+// finding that only says "bad contrast" is not. So every rule carries its criterion and its level.
+export const RULES = {
+    'image-alt': {
+        criterion: '1.1.1 Non-text Content',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader reads the file name instead of the picture, or says nothing at all',
+    },
+    'input-label': {
+        criterion: '3.3.2 Labels or Instructions',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader announces "edit text" with no way to know what to type',
+    },
+    'button-name': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader announces "button" and nothing else, so it cannot be used or spoken to',
+    },
+    'link-name': {
+        criterion: '2.4.4 Link Purpose',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'a screen reader lists the page links as "link, link, link"',
+    },
+    'html-lang': {
+        criterion: '3.1.1 Language of Page',
+        level: 'A',
+        severity: 'serious',
+        stops: 'a screen reader reads the page in the wrong accent, which can make it unintelligible',
+    },
+    'click-without-keyboard': {
+        criterion: '2.1.1 Keyboard',
+        level: 'A',
+        severity: 'blocker',
+        stops: 'anyone who cannot use a mouse, including every screen reader user, cannot activate it',
+    },
+    'positive-tabindex': {
+        criterion: '2.4.3 Focus Order',
+        level: 'A',
+        severity: 'serious',
+        stops: 'the tab key jumps around the page in an order that does not match what is on screen',
+    },
+    'nested-interactive': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'serious',
+        stops: 'a control inside a control is announced and operated unpredictably, and often cannot be reached',
+    },
+    'iframe-title': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'serious',
+        stops: 'a screen reader announces an unnamed frame with no clue what is inside it',
+    },
+    'zoom-blocked': {
+        criterion: '1.4.4 Resize Text',
+        level: 'AA',
+        severity: 'serious',
+        stops: 'anyone with low vision cannot pinch to zoom the page on a phone',
+    },
+    'autoplay-sound': {
+        criterion: '1.4.2 Audio Control',
+        level: 'A',
+        severity: 'serious',
+        stops: 'sound plays over a screen reader, which makes the page unusable while it runs',
+    },
+    'duplicate-id': {
+        criterion: '4.1.1 Parsing',
+        level: 'A',
+        severity: 'moderate',
+        stops: 'a label or description points at the wrong element, so the wrong thing is announced',
+    },
+    'heading-skip': {
+        criterion: '1.3.1 Info and Relationships',
+        level: 'A',
+        severity: 'moderate',
+        stops: 'a screen reader user navigating by heading cannot tell how the page is organised',
+    },
+    'aria-unknown': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'moderate',
+        stops: 'nothing - a misspelled aria attribute is silently ignored, so the help it was meant to give never arrives',
+    },
+    'aria-hidden-focusable': {
+        criterion: '4.1.2 Name, Role, Value',
+        level: 'A',
+        severity: 'serious',
+        stops: 'the tab key lands on something a screen reader has been told does not exist',
+    },
+};
+/**
+ * What reading markup cannot settle, said plainly so nobody mistakes a clean run for a pass.
+ *
+ * This list is the honest half of the command. Roughly a third of WCAG is machine-checkable at all,
+ * and a scanner reading source rather than a rendered page checks less than that. Printing this
+ * 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.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' },
+    { criterion: '4.1.3 Status Messages', why: 'needs a running page to observe what a live region announces' },
+    { criterion: '2.2.1 Timing Adjustable', why: 'needs the running behaviour of timeouts' },
+    { criterion: '3.2.x Predictable', why: 'needs a person to use the page and judge it' },
+];
+/** Rules whose finding, on its own, should stop a release. */
+export function blocks(rule) {
+    return RULES[rule]?.severity === 'blocker';
+}
+/** `1.1.1 Non-text Content (A)` - how a finding names its criterion in a report. */
+export function criterionOf(rule) {
+    const r = RULES[rule];
+    return r ? `WCAG 2.2 ${r.criterion} (${r.level})` : 'WCAG 2.2';
+}

package/dist/mcp/tools-prove.js

@@ -95,6 +95,29 @@ export function registerProofTools(server, { answer, readOnly, project }) {
             return 'No migration or schema file in that change.';
         return renderSchema(migrations, stillUsed(root, migrations.flatMap((m) => m.findings)));
     }));
+    server.registerTool('accessibility_barriers', {
+        title: 'Can everybody use this interface?',
+        description: "Accessibility barriers in a project's markup, each named against the WCAG 2.2 criterion a regulator would cite, with the evidence to check it. Two kinds of answer, kept apart on purpose: barriers that reading the markup proves (no alt attribute at all, a field with no label anywhere, a div that only a mouse can activate), and the ones only a person can settle, where something is written as an expression or a component and the markup cannot say. It also returns every criterion it did NOT check - contrast, focus order, whether alt text is any good - because those need a rendered page. Use it before shipping an interface, or when asked whether something is accessible; a clean result means these checks found nothing, never that the product is accessible. No browser, no network, no model.",
+        inputSchema: {
+            project,
+            path: z.string().optional().describe('A file or directory inside the project to check instead of all of it'),
+        },
+        annotations: readOnly,
+    }, ({ project: root, path }) => 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 { findings, filesRead } = findBarriers(root, path);
+        const judged = readAccepted(root);
+        const open = findings.filter((f) => !judged.has(keyOf(f)));
+        return renderAccess({
+            barriers: open.filter((f) => f.confidence === 'barrier'),
+            questions: open.filter((f) => f.confidence === 'ask-a-person'),
+            accepted: findings.filter((f) => judged.has(keyOf(f))),
+            filesRead,
+        }, path ?? root);
+    }));
     server.registerTool('project_standards', {
         title: "What are this project's own rules?",
         description: "The house rules this team has written down in .tewip/standards/, and whether a change keeps them. Returns two things kept carefully apart: rules Tewip checks and enforces (a forbid or require pattern over a set of files), and guidance it can only carry - prose for the parts no pattern captures, which is passed on when something is written but never reported as verified. Use it before writing or changing code in somebody's project, so what you produce matches their conventions rather than yours.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tewip-ai",
-  "version": "0.34.0",
+  "version": "0.35.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": [