@setsquare/review-sdk 0.0.1 → 0.1.1

package/dist/checks/heuristics.js

@@ -0,0 +1,961 @@
+import { ABBREVIATIONS_HELP_URL, CAPTIONS_PRERECORDED_HELP_URL, HEADINGS_AND_LABELS_HELP_URL, LOCATION_HELP_URL, MEANINGFUL_SEQUENCE_HELP_URL, SECTION_HEADINGS_HELP_URL, SENSORY_CHARACTERISTICS_HELP_URL, } from '../links.js';
+import { sanitiseSelectors } from '../sanitise.js';
+/**
+ * Seven heuristics for criteria no rule can decide.
+ *
+ * Every one follows the shape `reading-level.ts` established, and following it
+ * is the point of grouping them:
+ *
+ *   1. **A judgement is `incomplete`; a measurement is a `violation`.** This
+ *      rule used to read "never a violation, always incomplete", and it was
+ *      too broad. It is right for the heuristics that read English or guess
+ *      intent — 1.3.2, 1.3.3, 2.4.6, 3.1.4 — where a customer who disproves
+ *      one would stop trusting all of them, including the rules that are not
+ *      heuristics at all.
+ *
+ *      It was wrong for the ones that do arithmetic or look for a mechanism.
+ *      2.4.8 names four sufficient techniques and every one of them is a thing
+ *      in the DOM; a page carrying none of them has a fact reported about it,
+ *      not an opinion. Those use `fail()` rather than `note()`, at `minor`
+ *      where the measure is a correlate and `moderate` where it is the thing
+ *      the SC names. The caveat stays in the message either way — the change
+ *      is which column it is answered in, and "needs a person", repeated
+ *      across every page of a site, is a column nobody ever works through.
+ *   2. **Fire only above a margin**, and the margin is argued in a comment
+ *      rather than chosen. Every one of these is a judgement about where the
+ *      signal stops being noise, and a number nobody defended is a number
+ *      somebody will quietly change.
+ *   3. **Say what would resolve it.** "This might be a problem" is not a
+ *      finding; "add a `<track kind="captions">` or confirm the media has no
+ *      speech" is.
+ *   4. **Language-gated where the heuristic is language-specific**, and silent
+ *      rather than guessing otherwise. Three of these read English words. A
+ *      page in Finnish gets nothing from them, and a phrase list applied to a
+ *      language it was not written for manufactures findings.
+ *
+ * **Individually switchable**, because a customer who disagrees with one of
+ * these must not have to turn off the lot. They are read-only and can never
+ * fail a build, so they are on by default.
+ *
+ * The seven share ONE page evaluate. They are all DOM reads, and seven round
+ * trips per scan for seven cheap questions would be the wrong trade.
+ */
+export const SETSQUARE_HEURISTICS_VERSION = 'setsquare-heuristics@3';
+export const HEURISTIC_RULE_IDS = {
+    meaningfulSequence: 'setsquare-meaningful-sequence',
+    sensoryCharacteristics: 'setsquare-sensory-characteristics',
+    headingsAndLabels: 'setsquare-headings-and-labels',
+    sectionHeadings: 'setsquare-section-headings',
+    abbreviations: 'setsquare-abbreviations',
+    location: 'setsquare-location',
+    captions: 'setsquare-captions',
+};
+/**
+ * The margins, together, because they are the part of this file most likely to
+ * be argued with and they should be arguable in one place.
+ */
+const MARGINS = {
+    /**
+     * Three re-ordered items, not one. A single `order` on a flex child is a
+     * routine layout tweak (a logo before a nav on mobile); three or more is a
+     * layout whose reading order has been deliberately rearranged, which is when
+     * DOM order and visual order start to disagree in ways a screen-reader user
+     * notices.
+     */
+    reorderedItems: 3,
+    /**
+     * Two thousand characters. A run of prose that long with no heading is past
+     * what anyone scans by ear — a screen-reader user navigating by heading has
+     * nothing to navigate to. Below it, headings are a style choice.
+     */
+    unheadedChars: 2_000,
+    /**
+     * Three distinct all-caps tokens that have no expansion and no `<abbr>`. One
+     * or two are almost always a brand or a currency; three starts to look like
+     * jargon.
+     *
+     * The margin does less work than it used to, because the check now excludes
+     * anything the page expands in its own prose and anything already carrying
+     * an `<abbr>` — so what reaches here is already the residue rather than
+     * every capitalised token on the page.
+     */
+    abbreviations: 3,
+    /**
+     * Two generic labels, or one empty heading. An empty heading is
+     * unambiguous — there is nothing to read — so it needs no margin. "More" or
+     * "Section" appearing once is usually fine in context; twice on one page and
+     * the headings have stopped describing anything.
+     */
+    genericLabels: 2,
+};
+/**
+ * The level A time-based-media criteria a page with no media does not engage.
+ *
+ * Only level A here: a finding carries one level, and the AA and AAA media
+ * criteria (1.2.4, 1.2.5, 1.2.7–1.2.9) need their own row rather than being
+ * smuggled under an A label. `captionsHigherLevels` below emits those.
+ */
+const MEDIA_CRITERIA_A = ['1.2.1', '1.2.2', '1.2.3'];
+const MEDIA_CRITERIA_AA = ['1.2.4', '1.2.5'];
+const MEDIA_CRITERIA_AAA = ['1.2.6', '1.2.7', '1.2.8', '1.2.9'];
+/** English-only heuristics. See rule 4 above. */
+const ENGLISH_ONLY = new Set([
+    'sensoryCharacteristics',
+    'headingsAndLabels',
+    'abbreviations',
+]);
+/**
+ * Read every signal in one pass. Returns undefined on any failure — a page we
+ * could not read produces no heuristic findings rather than empty ones.
+ */
+export async function readHeuristicSignals(page) {
+    try {
+        return await page.evaluate(collectSignals);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The seven verdicts, as a pure function of the signals.
+ *
+ * Separated from the reading for the reason `focus.ts` records at length: the
+ * unit lane cannot see a computed style, and the half of a check that decides
+ * what to CLAIM is the half where the honesty rules live.
+ */
+/**
+ * Heuristics whose finding is "this page carries none of the mechanisms".
+ *
+ * A claim about what is ABSENT is only as good as the page being finished, and
+ * these two read the whole document to make it: 2.4.8 asks whether anything —
+ * breadcrumb, `aria-current`, site map, `rel` link — says where you are, and
+ * 3.1.4 asks whether anything expands an abbreviation. Every other heuristic
+ * here reasons about content it can SEE, and a half-rendered page gives it less
+ * to look at rather than a different answer.
+ *
+ * Found by friction record run 4: the 2.4.8 cue fired on one run and not the
+ * next, on identical code, because an SPA's router had or had not painted its
+ * active state by the time the page was scanned. This file's own first rule is
+ * that a heuristic fires only above a margin, and one that flips on render
+ * timing does not clear it — so on a page we already know never went quiet, the
+ * honest answer is silence rather than a finding we cannot reproduce.
+ */
+const PAGE_ABSENCE_CLAIMS = new Set(['location', 'abbreviations']);
+export function heuristicEvidence(signals, target, switches = {}, 
+/**
+ * Had the page met the quiet definition when these signals were read?
+ *
+ * Defaults to true, so nothing is suppressed unless a caller can actually say
+ * otherwise — an explicit scan suppresses nothing, because the customer chose
+ * the moment and it is not ours to second-guess.
+ */
+pageWentQuiet = true) {
+    const english = signals.lang.toLowerCase().startsWith('en');
+    const enabled = (id) => {
+        if (switches[id] === false)
+            return false;
+        // Silent, not a pass: the page never finished, so we did not look at the
+        // whole of it, and "we saw no mechanism" would be a claim about our timing.
+        if (!pageWentQuiet && PAGE_ABSENCE_CLAIMS.has(id))
+            return false;
+        // Silent rather than guessing: a phrase list applied to a language it was
+        // not written for manufactures findings, and a missing `lang` is already
+        // an axe violation (3.1.1) rather than this check's problem to solve.
+        if (ENGLISH_ONLY.has(id) && !english)
+            return false;
+        return true;
+    };
+    const evidence = [];
+    const add = (id, build) => {
+        if (!enabled(id))
+            return;
+        const result = build();
+        if (result)
+            evidence.push(result);
+    };
+    add('meaningfulSequence', () => meaningfulSequence(signals));
+    add('sensoryCharacteristics', () => sensoryCharacteristics(signals));
+    add('headingsAndLabels', () => headingsAndLabels(signals));
+    add('captions', () => captions(signals));
+    add('captions', () => mediaLevel(signals, MEDIA_CRITERIA_AA, 'AA'));
+    if (target === 'AAA') {
+        add('captions', () => mediaLevel(signals, MEDIA_CRITERIA_AAA, 'AAA'));
+        add('sectionHeadings', () => sectionHeadings(signals));
+        add('abbreviations', () => abbreviations(signals));
+        add('location', () => locationCue(signals));
+    }
+    return evidence;
+}
+function note(ruleId, criteria, level, helpUrl, failureSummary, selectors) {
+    const finding = {
+        ruleId,
+        // A judgement, so it asks. `fail()` is the sibling for the ones that
+        // measure. See rule 1 at the top of this file.
+        status: 'incomplete',
+        impact: 'moderate',
+        wcag: { criteria, level, versionTags: [] },
+        helpUrl,
+        evidence: { failureSummary },
+        targets: { nodeCount: Math.max(selectors.length, 1), ...sanitiseSelectors(selectors) },
+    };
+    return { finding };
+}
+/**
+ * The same finding as `note()`, reported as a failure.
+ *
+ * Separate function rather than a flag on `note()`, so that the choice is
+ * visible at every call site: reading a check, you can see in one word whether
+ * it decides or asks, and a check that quietly changed from one to the other
+ * shows up in a diff as what it is.
+ */
+function fail(ruleId, criteria, level, helpUrl, impact, failureSummary, selectors) {
+    const finding = {
+        ruleId,
+        status: 'violation',
+        impact,
+        wcag: { criteria, level, versionTags: [] },
+        helpUrl,
+        evidence: { failureSummary },
+        targets: { nodeCount: Math.max(selectors.length, 1), ...sanitiseSelectors(selectors) },
+    };
+    return { finding };
+}
+/** 1.3.2 Meaningful Sequence (A). */
+function meaningfulSequence(signals) {
+    if (signals.reordered.length < MARGINS.reorderedItems)
+        return undefined;
+    return note(HEURISTIC_RULE_IDS.meaningfulSequence, ['1.3.2'], 'A', MEANINGFUL_SEQUENCE_HELP_URL, `${signals.reordered.length} elements are moved by CSS \`order\` or a reversed flex or grid ` +
+        `container, so what a sighted reader sees is not the order a screen reader announces. ` +
+        `Whether that changes the MEANING is a judgement about the content, which is why this is ` +
+        `not reported as a failure. Resolve it by reading the page with the stylesheet off, or by ` +
+        `putting the DOM in the order the page reads in.`, signals.reordered);
+}
+/** 1.3.3 Sensory Characteristics (A). */
+/**
+ * 1.3.3 Sensory Characteristics (A) — a failure, because "solely" is readable.
+ *
+ * The extraction above applies the criterion's own two conditions: the sentence
+ * is an instruction, and the sensory phrase is the only thing in it identifying
+ * the target. A sentence failing either test never reaches here. So what is
+ * left is an instruction nobody can follow without seeing the layout, which is
+ * the criterion rather than a suspicion about it.
+ */
+function sensoryCharacteristics(signals) {
+    if (signals.sensory.length === 0)
+        return undefined;
+    const first = signals.sensory[0];
+    return fail(HEURISTIC_RULE_IDS.sensoryCharacteristics, ['1.3.3'], 'A', SENSORY_CHARACTERISTICS_HELP_URL, 'moderate', `An instruction identifies its target by "${first.phrase}" and by nothing else — ` +
+        `"${first.sentence}". ${signals.sensory.length} found. The sentence reads as an ` +
+        `instruction and carries no name, no quoted label and no code for the thing it is ` +
+        `pointing at, so somebody who cannot see the layout cannot follow it; a sentence that ` +
+        `names its target, or that describes rather than instructs, is not reported. Resolve it ` +
+        `by adding the name: "the Save button on the right" rather than "the button on the right".`, signals.sensory.map((row) => row.selector));
+}
+/** 2.4.6 Headings and Labels (AA). */
+function headingsAndLabels(signals) {
+    const empty = signals.weakHeadings.filter((row) => row.why === 'empty');
+    const rest = signals.weakHeadings.filter((row) => row.why !== 'empty');
+    if (empty.length === 0 && rest.length < MARGINS.genericLabels)
+        return undefined;
+    const rows = [...empty, ...rest];
+    const first = rows[0];
+    return note(HEURISTIC_RULE_IDS.headingsAndLabels, ['2.4.6'], 'AA', HEADINGS_AND_LABELS_HELP_URL, `${rows.length} heading(s) or label(s) do not describe what they head: ${first.selector} is ` +
+        `${first.why}. 2.4.6 asks that they be descriptive, which is a judgement about the content ` +
+        `they introduce — so this points, and a person decides. Resolve it by naming the thing: ` +
+        `"Billing address" rather than "Section", "Read the release notes" rather than "More".`, rows.map((row) => row.selector));
+}
+/** 2.4.10 Section Headings (AAA). */
+/**
+ * 2.4.10 Section Headings (AAA) — two answers, and only one of them used to
+ * exist.
+ *
+ * **A declared section with no name is a failure.** `<section>`, `<article>`
+ * and `role="region"` are the author stating that the content divides into
+ * sections. Once that is stated, "where content is organized into sections"
+ * is not a judgement any more and the criterion applies directly. This was
+ * not checked at all; the whole criterion rested on the character count below.
+ *
+ * **A long unheaded run is a warning.** Nothing in the SC names a character
+ * count — 2,000 is ours — so this is a correlate and reports at `minor` with
+ * that said in the message. It is still reported rather than asked, because a
+ * question repeated on every long page of a site is one nobody answers.
+ */
+function sectionHeadings(signals) {
+    if (signals.unheadedSections.length > 0) {
+        return fail(HEURISTIC_RULE_IDS.sectionHeadings, ['2.4.10'], 'AAA', SECTION_HEADINGS_HELP_URL, 'moderate', `${signals.unheadedSections.length} element(s) declare themselves a section — ` +
+            `\`<section>\`, \`<article>\` or \`role="region"\` — and carry no heading and no ` +
+            `\`aria-label\`. The markup has already divided this content into sections, so the ` +
+            `judgement 2.4.10 normally turns on does not arise here: the sections exist and are ` +
+            `unnamed. Resolve it with a heading inside each, or an \`aria-label\` where the ` +
+            `section genuinely has no visible title — or use a \`<div>\`, if it was never a ` +
+            `section.`, signals.unheadedSections);
+    }
+    if (signals.unheadedChars < MARGINS.unheadedChars)
+        return undefined;
+    return fail(HEURISTIC_RULE_IDS.sectionHeadings, ['2.4.10'], 'AAA', SECTION_HEADINGS_HELP_URL, 'minor', `A run of roughly ${signals.unheadedChars} characters carries no heading, so somebody ` +
+        `navigating by heading has nothing to navigate to across it. Reported as a warning ` +
+        `rather than a plain failure because the character count is ours, not the SC's: 2.4.10 ` +
+        `applies where content divides into sections, and a single continuous argument ` +
+        `legitimately has none. Resolve it by adding headings where the subject changes, or by ` +
+        `recording that this page is one section.`, ['main']);
+}
+/**
+ * 3.1.4 Abbreviations (AAA) — a warning, because the mechanism half is exact.
+ *
+ * The criterion asks for A MECHANISM, and every mechanism it accepts is a thing
+ * in the page: an `<abbr>`, an expansion in the prose, or a glossary. All three
+ * are now looked for, so "this token has no mechanism" is a fact rather than a
+ * suspicion. The check used to decline on the grounds that "3.1.4 also accepts
+ * a glossary this check cannot see", which was the 2.4.8 excuse one criterion
+ * along.
+ *
+ * What stays a correlate is the other half: an all-capital token STANDS IN for
+ * an abbreviation, and a page can capitalise something that is neither an
+ * abbreviation nor an acronym. That is why this is `minor` and why the tokens
+ * are named in the message — an author who thinks it is wrong can see in one
+ * line which words we meant, which is a different conversation from being told
+ * a criterion needs a person.
+ */
+function abbreviations(signals) {
+    if (signals.abbreviations.length < MARGINS.abbreviations)
+        return undefined;
+    // A glossary answers the criterion for every abbreviation at once, which is
+    // exactly why the SC lists it: it is one mechanism covering the page.
+    if (signals.hasGlossary)
+        return undefined;
+    return fail(HEURISTIC_RULE_IDS.abbreviations, ['3.1.4'], 'AAA', ABBREVIATIONS_HELP_URL, 'minor', `${signals.abbreviations.length} all-capital token(s) appear with no expansion anywhere in ` +
+        `the page's text, no \`<abbr>\` of their own, and no glossary linked from the page: ` +
+        `${signals.abbreviations.slice(0, 6).join(', ')}. Tokens the prose expands — ` +
+        `"Web Content Accessibility Guidelines (WCAG)" — and tokens already wrapped in ` +
+        `\`<abbr>\` are excluded, so these are the ones with no mechanism at all. Reported as a ` +
+        `warning rather than a plain failure because an all-capital token is a correlate for an ` +
+        `abbreviation and a page may capitalise something that is neither — the tokens are named ` +
+        `above so you can see in one line whether we have that wrong. This is usually a small ` +
+        `fix. Resolve it with one \`<abbr title="…">\` anywhere on the page, which clears that ` +
+        `token for the whole page — or, once, with a glossary linked from a shared footer, which ` +
+        `clears every token on every page including the pages not written yet.`, ['body']);
+}
+/**
+ * 2.4.8 Location (AAA) — a failure, because every mechanism is visible.
+ *
+ * The SC's sufficient techniques are a breadcrumb, a site map, the current
+ * item marked in a navigation bar, and `rel` links stating the page's place in
+ * a collection. All four are things in the DOM, and the signal extraction now
+ * looks for all four rather than two. A page that is inside a set of pages and
+ * carries none of them does not make its location available — that is a
+ * statement about the markup, not an opinion about it.
+ *
+ * The one judgement left is whether the page is part of a set, and `hasNav`
+ * stands in for it: a page with navigation to other pages is in a set, and the
+ * front door of a site does not need to say where you are.
+ */
+function locationCue(signals) {
+    const { hasNav, hasBreadcrumb, hasCurrent, hasSiteMap, hasRelLink, isRoot } = signals.location;
+    if (!hasNav || isRoot)
+        return undefined;
+    if (hasBreadcrumb || hasCurrent || hasSiteMap || hasRelLink)
+        return undefined;
+    return fail(HEURISTIC_RULE_IDS.location, ['2.4.8'], 'AAA', LOCATION_HELP_URL, 'moderate', `This page has navigation to other pages but carries none of the mechanisms 2.4.8 is met ` +
+        `by: no breadcrumb trail, no \`aria-current\` on any navigation item, no link to a site ` +
+        `map, and no \`rel\` stating where the page sits in a collection. Somebody arriving here ` +
+        `from a search result has nothing telling them where they are. Resolve it with ` +
+        `\`aria-current="page"\` on the navigation item for this page, which is usually already ` +
+        `styled as the active one — the styling is the part that is generally there and the ` +
+        `attribute is the part that is generally missing.`, ['nav']);
+}
+/**
+ * The time-based-media criteria: 1.2.1 through 1.2.9.
+ *
+ * Two answers, and the second one was missing for long enough to matter.
+ *
+ * **A page with media and no caption track** is the finding: whether captions
+ * are correct is not something any check can judge, whether there are none is,
+ * and "no automated result" was a much weaker answer than the one available.
+ *
+ * **A page with no media at all** is INAPPLICABLE, not silence. The page
+ * contains nothing these criteria regulate, we looked, and that is a real
+ * observation — the same distinction as "scanned and found nothing" versus
+ * "never scanned", which this repository cares about everywhere else. Without
+ * it, seven criteria read "no automated result" on a site that has never had a
+ * video on it, which is the least useful true thing we could have said.
+ *
+ * An iframe, object or embed stops the claim. An embedded player is media we
+ * cannot see, and inapplicability asserted over a thing we did not look inside
+ * is exactly the confident wrong answer this file's discipline exists to
+ * prevent.
+ */
+function captions(signals) {
+    if (signals.uncaptioned.length === 0) {
+        if (signals.media.elements > 0 || signals.media.frames > 0)
+            return undefined;
+        return {
+            inapplicable: {
+                ruleId: HEURISTIC_RULE_IDS.captions,
+                wcag: { criteria: [...MEDIA_CRITERIA_A], level: 'A', versionTags: [] },
+            },
+        };
+    }
+    return note(HEURISTIC_RULE_IDS.captions, ['1.2.1', '1.2.2'], 'A', CAPTIONS_PRERECORDED_HELP_URL, `${signals.uncaptioned.length} media element(s) carry no \`<track kind="captions">\` or ` +
+        `\`kind="subtitles">\`. Whether captions are CORRECT is not something any check can ` +
+        `judge; whether there are none is, and there are none here. Media with no speech and no ` +
+        `meaningful sound needs no captions, which is the case a person confirms. Resolve it by ` +
+        `adding a caption track, or by confirming the media is silent.`, signals.uncaptioned);
+}
+/**
+ * The AA and AAA media criteria, for a page with no media.
+ *
+ * A separate row per level because a finding carries ONE level, and reporting
+ * 1.2.5 under a level A label would misstate what was assessed. Emits nothing
+ * where media exists: whether an audio description is adequate is a judgement
+ * no check makes, so there is nothing to say beyond the caption-track finding
+ * above.
+ */
+function mediaLevel(signals, criteria, level) {
+    if (signals.media.elements > 0 || signals.media.frames > 0)
+        return undefined;
+    return {
+        inapplicable: {
+            ruleId: `${HEURISTIC_RULE_IDS.captions}-${level.toLowerCase()}`,
+            wcag: { criteria: [...criteria], level, versionTags: [] },
+        },
+    };
+}
+/**
+ * The in-page half. One evaluate, seven questions, no writes.
+ *
+ * Kept as a named function passed to `evaluate` rather than a source string so
+ * it typechecks; it must not close over anything in this module.
+ */
+function collectSignals() {
+    const step = (el) => {
+        const tag = el.tagName.toLowerCase();
+        if (el.id)
+            return `${tag}#${el.id}`;
+        if (el.classList.length > 0)
+            return `${tag}.${el.classList[0]}`;
+        const parent = el.parentElement;
+        if (!parent)
+            return tag;
+        return `${tag}:nth-child(${Array.prototype.indexOf.call(parent.children, el) + 1})`;
+    };
+    const describe = (el) => {
+        const parts = [];
+        let node = el;
+        for (let depth = 0; node && depth < 3; depth += 1) {
+            parts.unshift(step(node));
+            if (node.id || node.classList.length > 0)
+                break;
+            node = node.parentElement;
+            if (!node || node === document.body)
+                break;
+        }
+        return parts.join(' > ');
+    };
+    const textOf = (el) => (el.innerText ?? el.textContent ?? '').replace(/\s+/g, ' ').trim();
+    /* --- 1.3.2: DOM order versus visual order --- */
+    const reordered = [];
+    for (const el of Array.from(document.body.querySelectorAll('*')).slice(0, 2000)) {
+        if (reordered.length >= 10)
+            break;
+        const cs = window.getComputedStyle(el);
+        const order = cs.order;
+        if (order && order !== '0' && order !== 'normal') {
+            reordered.push(describe(el));
+            continue;
+        }
+        if (cs.flexDirection === 'row-reverse' || cs.flexDirection === 'column-reverse') {
+            reordered.push(describe(el));
+        }
+    }
+    /* --- 1.3.3: instructions relying on shape, size or position alone --- */
+    const SENSORY = [
+        'the button on the right',
+        'the button on the left',
+        'on the right',
+        'on the left',
+        'the round button',
+        'the round icon',
+        'the square icon',
+        'click below',
+        'see below',
+        'the box above',
+        'the link above',
+        'the green button',
+        'the red button',
+        'in the top right',
+        'in the top left',
+        'the icon shaped like',
+    ];
+    /*
+     * The two tests the SC actually states, applied to the SENTENCE.
+     *
+     * 1.3.3 is about instructions that rely SOLELY on a sensory characteristic.
+     * The check used to find the phrase and stop, then say "that is only a
+     * failure if the instruction cannot be followed without seeing the layout,
+     * which depends on what else the sentence says, so a person decides" — while
+     * its own next line told the author the answer: *"the Save button on the
+     * right" rather than "the button on the right"*. What the sentence says is
+     * readable, and the resolution it printed is the test it declined to run.
+     *
+     * So, per phrase found:
+     *
+     *   1. Is the sentence an INSTRUCTION? The criterion governs instructions for
+     *      understanding and operating content, not description. "Review, on the
+     *      left, runs now" is a statement about a product, and an imperative is
+     *      how an instruction reads in English.
+     *   2. Does it rely SOLELY on the sensory characteristic? A quoted label, a
+     *      capitalised name that is not the first word, or a `code`/`kbd` in the
+     *      sentence is another way to identify the thing — and the SC's word is
+     *      "solely".
+     *
+     * Both true is a failure. Either false is silence, not needs-review: a
+     * description is out of scope and a named control satisfies the criterion.
+     * Still English-only, which is why the whole group is language-gated.
+     */
+    const IMPERATIVES = 'click|select|press|choose|tap|use|see|open|enter|type|find|look|go|pick|drag|drop|tick|check|scroll|follow|read|expand|collapse|copy|paste|set|add|remove|switch|toggle';
+    /*
+     * An imperative opens a sentence, follows a comma, or follows a connective.
+     *
+     * The position is the whole test: it is what separates "press the button on
+     * the right" from "the column on the right is what that looks like". A bare
+     * word-boundary match on the verb list would catch every descriptive
+     * sentence containing "use" or "see", which is how a heuristic earns its
+     * reputation. "To continue, press …" is why the comma is in here — the first
+     * version had only sentence-start and connectives, and missed the commonest
+     * shape an instruction takes.
+     */
+    const INSTRUCTION = new RegExp(`(^|[.;:!?,—]\\s*|\\b(?:to|then|and|please|now|first|next|you can|you must)\\s+)(?:${IMPERATIVES})\\b`, 'i');
+    /*
+     * Is there another way to identify the thing? A quoted label, or a
+     * capitalised word that is not the sentence's first word — "press the Save
+     * button on the right" names its target and "press the button on the right"
+     * does not.
+     *
+     * Written as a word scan rather than one regex because the regex version was
+     * wrong in a way that read as correct: `\b[a-z]` requires the lowercase
+     * character to START a word, so "the Save" never matched — the `e` it needed
+     * is the end of "the". Every named control was reported as unnamed.
+     *
+     * It errs toward silence: a proper noun anywhere in the sentence counts, so
+     * "click the button on the right to open Settings" is not reported even
+     * though Settings is the destination rather than the control. On a heuristic
+     * that is the right direction to be wrong in.
+     */
+    const named = (sentence) => {
+        if (/["“'‘][^"”'’]{2,}["”'’]/.test(sentence))
+            return true;
+        const words = sentence.split(/\s+/).slice(1);
+        return words.some((word) => /^[A-Z][a-zA-Z]/.test(word.replace(/^[^A-Za-z]+/, '')));
+    };
+    const sensory = [];
+    for (const el of Array.from(document.querySelectorAll('p, li, label, td, div')).slice(0, 800)) {
+        if (sensory.length >= 10)
+            break;
+        // Leaf-ish only, so a wrapper does not report its children's sentence.
+        if (el.querySelector('p, li, label, td'))
+            continue;
+        const full = textOf(el);
+        if (full.length === 0 || full.length > 400)
+            continue;
+        const lower = full.toLowerCase();
+        const phrase = SENSORY.find((candidate) => lower.includes(candidate));
+        if (!phrase)
+            continue;
+        // The sentence carrying the phrase, not the whole paragraph: a name three
+        // sentences away is not what identifies this control.
+        const sentence = full.split(/(?<=[.!?])\s+/).find((part) => part.toLowerCase().includes(phrase)) ?? full;
+        if (!INSTRUCTION.test(sentence))
+            continue;
+        if (named(sentence) || el.querySelector('code, kbd'))
+            continue;
+        sensory.push({ selector: describe(el), phrase, sentence: sentence.slice(0, 160) });
+    }
+    /* --- 2.4.6: headings and labels that say nothing --- */
+    const GENERIC = new Set([
+        'more',
+        'section',
+        'input',
+        'field',
+        'details',
+        'info',
+        'information',
+        'text',
+        'title',
+        'label',
+        'heading',
+        'untitled',
+        'read more',
+        'learn more',
+        'click here',
+    ]);
+    const weakHeadings = [];
+    const seenHeading = new Map();
+    const headings = Array.from(document.querySelectorAll('h1, h2, h3, h4, h5, h6, legend, label'));
+    for (const el of headings.slice(0, 200)) {
+        if (weakHeadings.length >= 10)
+            break;
+        const text = textOf(el);
+        if (text.length === 0) {
+            weakHeadings.push({ selector: describe(el), why: 'empty' });
+            continue;
+        }
+        const lower = text.toLowerCase();
+        if (GENERIC.has(lower)) {
+            weakHeadings.push({ selector: describe(el), why: `generic ("${text}")` });
+            continue;
+        }
+        const key = `${el.tagName}:${lower}`;
+        const count = (seenHeading.get(key) ?? 0) + 1;
+        seenHeading.set(key, count);
+        if (count === 2)
+            weakHeadings.push({ selector: describe(el), why: `a duplicate of "${text}"` });
+    }
+    /* --- 2.4.10: sections the author declared and did not head --- */
+    /*
+     * The half this check was not doing at all, and the only half that needs no
+     * judgement. `<section>` and `role="region"` exist to say "this content is a
+     * section" — the author has already made the division the SC asks about. So
+     * "content is organized into sections" is not in doubt for these, and the
+     * criterion's requirement lands squarely: the section gets a heading.
+     *
+     * `<article>` counts too, for the same reason. `<nav>`, `<aside>`, `<form>`
+     * and `<header>`/`<footer>` do not: they are landmarks with their own naming
+     * conventions, and a nav without a visible heading is normal markup rather
+     * than an unheaded section of content.
+     *
+     * An `aria-label` or `aria-labelledby` satisfies it as well as a heading
+     * does. The requirement is that the section is named, not that the name is
+     * an `<h2>`.
+     */
+    const unheadedSections = [];
+    for (const el of Array.from(document.querySelectorAll('section, article, [role="region"]'))) {
+        if (el.hasAttribute('aria-label') || el.hasAttribute('aria-labelledby'))
+            continue;
+        if (el.querySelector('h1, h2, h3, h4, h5, h6, [role="heading"]'))
+            continue;
+        if (unheadedSections.length < 20)
+            unheadedSections.push(describe(el));
+    }
+    /* --- 2.4.10: the longest run of text with no heading --- */
+    const main = document.querySelector('main, [role="main"]') ?? document.body;
+    let unheadedChars = 0;
+    let run = 0;
+    /*
+     * UNLABELLED prose, which is not the same as everything with text in it.
+     *
+     * The run used to count `td` and `dd`, and both are wrong for the same
+     * reason: they already carry a label. A `<td>` is named by its column and
+     * row headers, a `<dd>` by its `<dt>`, and a screen reader announces both —
+     * so that content is organised and labelled, which is the shape 2.4.10 asks
+     * for rather than a breach of it.
+     *
+     * What it cost: on this repository's own site three of the four findings
+     * were this. The pricing capability table and the evidence page's surface
+     * table each read as two and a half thousand characters of unheaded prose,
+     * and the evidence page's definition list of criteria read as another three
+     * thousand. None of them wants a heading between its rows.
+     *
+     * `reading-level.ts` already drops tables for the same reason, which is the
+     * tell that this was one mistake made twice in different units. Excluded by
+     * ancestor rather than by tag, because the text sits in a `<p>` inside the
+     * cell as often as in the cell itself.
+     *
+     * What is left is `p` and `li`: running prose with nothing naming it but the
+     * heading above it, which is exactly what the criterion is about.
+     */
+    const labelled = (el) => el.closest('table, [role="table"], [role="grid"], dl, [role="term"], [role="definition"]') !==
+        null;
+    for (const el of Array.from(main.querySelectorAll('h1, h2, h3, h4, h5, h6, p, li'))) {
+        if (/^H[1-6]$/.test(el.tagName)) {
+            unheadedChars = Math.max(unheadedChars, run);
+            run = 0;
+            continue;
+        }
+        if (labelled(el))
+            continue;
+        run += textOf(el).length;
+    }
+    unheadedChars = Math.max(unheadedChars, run);
+    /* --- 3.1.4: abbreviations with no expansion and no <abbr> --- */
+    const abbreviations = [];
+    {
+        /*
+         * AUTHORED text, not rendered text.
+         *
+         * `innerText` returns what CSS painted, so an eyebrow set in
+         * `text-transform: uppercase` comes back as an abbreviation. On this
+         * repository's own site that reported THE, GAP, REVIEW and US as
+         * abbreviations needing expansion — ordinary words the stylesheet had
+         * shouted. `textContent` is what somebody typed.
+         */
+        /*
+         * Text nodes joined with a SPACE, not `main.textContent`.
+         *
+         * `textContent` concatenates across element boundaries with no separator,
+         * so it invents tokens that are not on the page. On this repository's own
+         * docs a heading ending "…at AAA rather than AA" ran into a paragraph
+         * starting "AA is the default…" and the check reported `AAAA` — a string
+         * nobody wrote, in a finding telling the author to expand it. The same
+         * glue turned an ordinal into `02Assess`, which destroys the word boundary
+         * the token regex depends on.
+         *
+         * Still authored text rather than `innerText`: the point of reading
+         * `textContent` at all is that CSS `text-transform` must not manufacture
+         * an abbreviation out of a shouted ordinary word.
+         */
+        const walker = document.createTreeWalker(main, NodeFilter.SHOW_TEXT);
+        const pieces = [];
+        let length = 0;
+        for (let node = walker.nextNode(); node && length < 20_000; node = walker.nextNode()) {
+            /*
+             * Not code. 3.1.4 is about the page's TEXT, and a token inside a
+             * snippet is an identifier the reader is meant to type verbatim — you
+             * cannot expand it on first use and it would be wrong to.
+             *
+             * Found on our own docs, where the locale `en-GB` in a config example
+             * was reported as the abbreviation `GB`, and the fix it asked for would
+             * have broken the snippet.
+             */
+            if (node.parentElement?.closest('code, pre, kbd, samp'))
+                continue;
+            const piece = (node.nodeValue ?? '').replace(/\s+/g, ' ').trim();
+            if (!piece)
+                continue;
+            pieces.push(piece);
+            length += piece.length + 1;
+        }
+        const authored = pieces.join(' ').slice(0, 20_000);
+        /** Tokens already carrying an `<abbr>`, which need nothing further. */
+        const marked = new Set();
+        for (const el of Array.from(document.querySelectorAll('abbr'))) {
+            const token = (el.textContent ?? '').trim();
+            if (token)
+                marked.add(token);
+        }
+        /*
+         * Ordinary English words somebody wrote in capitals, which are not
+         * abbreviations however emphatic they are. Reported `TO` and `AN` on this
+         * repository's own evidence page, in a finding asking us to expand them.
+         *
+         * Short and closed on purpose: it holds the function words and the few
+         * content words that turn up in a shouted sentence, and nothing that could
+         * plausibly also be an acronym. `IT` is deliberately absent — it is the
+         * department at least as often as it is the pronoun, and the wrong call
+         * there is a missed finding rather than a manufactured one.
+         */
+        const WORDS = new Set([
+            'THE',
+            'AND',
+            'BUT',
+            'FOR',
+            'NOR',
+            'YET',
+            'SO',
+            'OR',
+            'AS',
+            'AT',
+            'BY',
+            'IN',
+            'OF',
+            'ON',
+            'TO',
+            'UP',
+            'AN',
+            'A',
+            'IS',
+            'ARE',
+            'WAS',
+            'WERE',
+            'BE',
+            'BEEN',
+            'DO',
+            'DOES',
+            'DID',
+            'HAS',
+            'HAVE',
+            'HAD',
+            'CAN',
+            'WILL',
+            'NOT',
+            'NO',
+            'ALL',
+            'ANY',
+            'ONE',
+            'TWO',
+            'YOU',
+            'YOUR',
+            'WE',
+            'OUR',
+            'US',
+            'THIS',
+            'THAT',
+            'THEM',
+            'THEY',
+            'WHAT',
+            'WHEN',
+            'WHY',
+            'HOW',
+            'WHO',
+            'IF',
+            'THEN',
+            'ELSE',
+            'FROM',
+            'WITH',
+            'INTO',
+            'OVER',
+            'ONLY',
+            'EVERY',
+            'NEVER',
+            'NOW',
+            'NEW',
+            'OLD',
+            'SAME',
+            'MORE',
+            'MOST',
+            'LESS',
+            'EACH',
+            'BOTH',
+            'SOME',
+            'SUCH',
+            'HERE',
+            'THERE',
+            'WHERE',
+            'WHICH',
+            'WHILE',
+            'ABOUT',
+            'AFTER',
+            'AGAIN',
+            'STILL',
+        ]);
+        /*
+         * Not a run of capitals inside an identifier.
+         *
+         * `en-GB` is one token — a language tag — and the word-boundary regex cuts
+         * `GB` out of it. Expanding that is not what 3.1.4 asks for and the
+         * "resolution" would corrupt the value. Same for a dotted or slashed
+         * identifier. Found on our own home page, where a consent manifest figure
+         * lists `locales en-GB, cy, fr`.
+         */
+        const tokens = [...authored.matchAll(/\b[A-Z]{2,6}\b/g)].filter((match) => {
+            const before = authored[match.index - 1] ?? ' ';
+            const after = authored[match.index + match[0].length] ?? ' ';
+            return !'-_/.'.includes(before) && !'-_/'.includes(after);
+        });
+        const counted = new Set();
+        for (const [token] of tokens) {
+            // Roman numerals are not abbreviations, and `I` is not either.
+            if (/^[IVXLCDM]+$/.test(token))
+                continue;
+            if (WORDS.has(token))
+                continue;
+            if (counted.has(token))
+                continue;
+            counted.add(token);
+            // Already explained: an `<abbr>` anywhere for THIS token. The first
+            // version asked whether the page had ANY `<abbr>` at all, so one
+            // expanded abbreviation silenced the check for every other one.
+            if (marked.has(token))
+                continue;
+            /*
+             * Expanded in the prose is a mechanism too, and the commonest one:
+             * "Web Content Accessibility Guidelines (WCAG)" or "WCAG (Web Content
+             * Accessibility Guidelines)". Detected rather than ignored, because
+             * reporting a term the page defines in its first sentence is how a
+             * check gets switched off.
+             */
+            const expanded = new RegExp('(\\([^)]*\\b' + token + '\\b[^)]*\\)|\\b' + token + '\\b\\s*\\([^)]{4,}\\))').test(authored);
+            if (expanded)
+                continue;
+            if (abbreviations.length < 12)
+                abbreviations.push(token);
+        }
+    }
+    /*
+     * --- 3.1.4: a glossary, which is a mechanism like any other ---
+     *
+     * The check used to report needs-review partly on the grounds that "3.1.4
+     * also accepts a glossary this check cannot see". It can see one. That is
+     * the same excuse 2.4.8 was making about site maps, one criterion along:
+     * naming a sufficient technique and then declining to look for it.
+     *
+     * G62 is a glossary; a link to one is how a page carries it. Matched on the
+     * link rather than on any `<dl>` in the page, because a definition list is
+     * the markup for a glossary and also the markup for a dozen other things —
+     * this repository's own evidence page has three of them and none is a
+     * glossary. A false silence here switches the criterion off completely,
+     * which is worse than a finding somebody dismisses.
+     */
+    const hasGlossary = Array.from(document.querySelectorAll('a[href]')).some((a) => {
+        const href = (a.getAttribute('href') ?? '').toLowerCase();
+        const text = (a.textContent ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+        return /glossary|definitions/.test(href) || /^(a |the )?(glossary|definitions)$/.test(text);
+    });
+    /* --- 2.4.8: does anything say where you are? --- */
+    /*
+     * Every sufficient technique the SC lists, not two of them.
+     *
+     * This used to look for a breadcrumb and an `aria-current`, find neither,
+     * and report needs-review on the grounds that "2.4.8 can also be met by a
+     * site map or by the page's own heading structure, neither of which this
+     * check can judge". A site map is a link and is perfectly visible; `rel`
+     * links are an attribute. Naming two mechanisms, failing to look for the
+     * rest, and calling the gap a judgement is the pattern this file keeps
+     * getting caught by.
+     *
+     * G65 breadcrumb · G63 site map · G128 current item in a nav bar ·
+     * H59 link rel. What survives as a genuine judgement is only whether a page
+     * is part of a set at all, which `hasNav` stands in for.
+     */
+    const navs = Array.from(document.querySelectorAll('nav, [role="navigation"]'));
+    const hasBreadcrumb = document.querySelector('[aria-label*="readcrumb"], .breadcrumb, .breadcrumbs, ol.breadcrumb') !== null;
+    const hasCurrent = navs.some((nav) => nav.querySelector('[aria-current]') !== null);
+    /*
+     * A site map, by href or by link text. Both, because a site links to its
+     * map as `/sitemap` far more often than it labels it, and labels it
+     * "Site map" far more often than it uses a recognisable href.
+     */
+    const hasSiteMap = Array.from(document.querySelectorAll('a[href]')).some((a) => {
+        const href = (a.getAttribute('href') ?? '').toLowerCase();
+        const text = (a.textContent ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+        return /sitemap|site-map/.test(href) || /^site\s?map$/.test(text);
+    });
+    /*
+     * H59: `rel` stating the page's place in a collection. On `<link>` in the
+     * head, and on `<a>` — `rel="up"` on a parent link is the same statement.
+     */
+    const REL = /\b(index|contents|up|start|prev|previous|next)\b/i;
+    const hasRelLink = Array.from(document.querySelectorAll('link[rel], a[rel]')).some((el) => REL.test(el.getAttribute('rel') ?? ''));
+    const path = window.location.pathname.replace(/\/+$/, '');
+    /* --- 1.2.x: media with no caption track --- */
+    const mediaElements = Array.from(document.querySelectorAll('video, audio'));
+    const uncaptioned = [];
+    for (const media of mediaElements.slice(0, 20)) {
+        const track = media.querySelector('track[kind="captions"], track[kind="subtitles"]');
+        if (!track)
+            uncaptioned.push(describe(media));
+    }
+    return {
+        lang: document.documentElement.getAttribute('lang') ?? '',
+        reordered,
+        sensory,
+        weakHeadings,
+        unheadedSections,
+        unheadedChars,
+        abbreviations,
+        hasGlossary,
+        location: {
+            hasNav: navs.length > 0,
+            hasBreadcrumb,
+            hasCurrent,
+            hasSiteMap,
+            hasRelLink,
+            isRoot: path === '' || path === '/index.html',
+        },
+        uncaptioned,
+        media: {
+            elements: mediaElements.length,
+            frames: document.querySelectorAll('iframe, object, embed').length,
+        },
+    };
+}
+//# sourceMappingURL=heuristics.js.map