@jitsusama/agentic-harness.core 0.1.0

package/dist/web/audit/structure.js

@@ -0,0 +1,595 @@
+/**
+ * Structural accessibility rules of our own.
+ *
+ * These sit beside axe rather than duplicating it. Some are
+ * things axe reports only as best practice, where the failure is
+ * in fact severe; some it declines to decide; some it does not
+ * look at. Every one of them is a question about how a page is
+ * put together rather than how it is painted, which is why they
+ * can run against a stored capture.
+ *
+ * Nothing here parses CSS or re-derives a role. Roles and names
+ * come from the browser's accessibility tree and attributes come
+ * from its snapshot, joined before they arrive. What this module
+ * contributes is the reasoning about relationships between them:
+ * which reference points nowhere, which control is buried inside
+ * another, which heading skipped a level.
+ */
+/** Attributes whose value is one or more element ids. */
+export const IDREF_ATTRIBUTES = [
+    "aria-labelledby",
+    "aria-describedby",
+    "aria-controls",
+    "aria-owns",
+    "aria-details",
+    "aria-errormessage",
+    "aria-flowto",
+];
+/** Attributes holding exactly one id. */
+export const SINGLE_IDREF_ATTRIBUTES = [
+    "aria-activedescendant",
+    "for",
+];
+/** Roles that name a region of the page. */
+export const LANDMARK_ROLES = [
+    "banner",
+    "complementary",
+    "contentinfo",
+    "form",
+    "main",
+    "navigation",
+    "region",
+    "search",
+];
+/** Roles a person operates, for the nesting rule. */
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "checkbox",
+    "combobox",
+    "link",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "radio",
+    "searchbox",
+    "slider",
+    "spinbutton",
+    "switch",
+    "tab",
+    "textbox",
+]);
+/** Roles that must hold a name from the author, not the content. */
+const NEEDS_LABEL_ROLES = new Set([
+    "checkbox",
+    "combobox",
+    "listbox",
+    "radio",
+    "searchbox",
+    "slider",
+    "spinbutton",
+    "switch",
+    "textbox",
+]);
+function finding(rule, nodes) {
+    if (nodes.length === 0)
+        return [];
+    return [
+        {
+            rule: rule.rule,
+            kind: "violation",
+            impact: rule.impact,
+            authority: rule.criteria.length > 0 ? "wcag" : "best-practice",
+            criteria: rule.criteria,
+            levels: rule.levels,
+            help: rule.help,
+            nodes,
+        },
+    ];
+}
+function nodeOf(node, message) {
+    return {
+        selector: node.selector,
+        html: node.html ?? "",
+        messages: [message],
+    };
+}
+/**
+ * References that point at nothing.
+ *
+ * A broken aria-labelledby does not degrade, it erases: the
+ * element ends up with no accessible name at all rather than
+ * falling back to its content. That makes this more severe than
+ * the "invalid attribute value" it is usually filed under.
+ *
+ * Two attributes are not like the others. aria-controls and
+ * aria-owns routinely point at something the widget has not built
+ * yet: a closed combobox or disclosure has no popup in the
+ * document, and every popular menu library ships exactly that
+ * markup. axe settles it the same way and says so in its own
+ * source, refusing to fail either attribute while aria-expanded
+ * is "false". This rule used to fail both as critical, so a real
+ * app opened with two critical WCAG failures for a pattern that
+ * is correct.
+ */
+/**
+ * Attributes whose target may legitimately not exist yet.
+ *
+ * Both name something the widget owns and renders on demand, so
+ * their absence while collapsed says nothing about correctness.
+ */
+const DEFERS_TO_EXPANDED = new Set(["aria-controls", "aria-owns"]);
+/**
+ * Whether a widget is currently showing what it controls.
+ *
+ * Absent aria-expanded means this is not a disclosure at all, so
+ * there is no excuse to extend: only an explicit "false" earns
+ * one. aria-selected is included because axe treats a deselected
+ * tab the same way, and for the same reason.
+ */
+function isExpanded(node) {
+    return (node.attributes["aria-expanded"] !== "false" &&
+        node.attributes["aria-selected"] !== "false");
+}
+export function brokenReferences(nodes) {
+    const present = new Set(nodes.map((node) => node.attributes.id).filter(Boolean));
+    const broken = [];
+    for (const node of nodes) {
+        for (const attribute of [...IDREF_ATTRIBUTES, ...SINGLE_IDREF_ATTRIBUTES]) {
+            const value = node.attributes[attribute];
+            if (!value)
+                continue;
+            const single = SINGLE_IDREF_ATTRIBUTES.includes(attribute);
+            const wanted = single ? [value.trim()] : value.trim().split(/\s+/);
+            const missing = wanted.filter((id) => id !== "" && !present.has(id));
+            if (missing.length === 0)
+                continue;
+            if (DEFERS_TO_EXPANDED.has(attribute) && !isExpanded(node))
+                continue;
+            broken.push(nodeOf(node, `${attribute} points at ${missing
+                .map((id) => `'${id}'`)
+                .join(", ")}, which ${missing.length === 1 ? "is not" : "are not"} on the page.`));
+        }
+    }
+    return finding({
+        rule: "reference-resolves",
+        impact: "critical",
+        criteria: ["1.3.1", "4.1.2"],
+        levels: ["A"],
+        help: "ARIA references must point at elements that exist. A broken " +
+            "aria-labelledby erases the name rather than falling back to it.",
+    }, broken);
+}
+/**
+ * Things hidden from assistive technology but still tabbable.
+ *
+ * This is the worst kind of inconsistency, because the page
+ * behaves differently depending on which way somebody uses it:
+ * focus lands on something a screen reader will not announce, so
+ * the user is somewhere they cannot be told about.
+ */
+export function hiddenButFocusable(nodes) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const found = [];
+    for (const node of nodes) {
+        if (!node.focusable || !node.rendered)
+            continue;
+        if (node.attributes["aria-hidden"] === "true") {
+            found.push(nodeOf(node, "It is aria-hidden and can still be focused."));
+            continue;
+        }
+        const hiding = node.ancestors
+            .map((id) => byId.get(id))
+            .find((ancestor) => ancestor?.attributes["aria-hidden"] === "true");
+        if (hiding) {
+            found.push(nodeOf(node, `An ancestor (${hiding.selector}) is aria-hidden, so this ` +
+                "is announced to nobody but still takes focus."));
+        }
+    }
+    return finding({
+        rule: "hidden-focusable",
+        impact: "critical",
+        criteria: ["1.3.1", "4.1.2"],
+        levels: ["A"],
+        help: "Anything aria-hidden must not be focusable. Focus lands " +
+            "somewhere a screen reader will not announce.",
+    }, found);
+}
+/**
+ * Controls buried inside other controls.
+ *
+ * What happens on a click is then undefined in practice: the
+ * browser flattens the pair differently from the accessibility
+ * tree, so what a mouse does and what a screen reader reports
+ * stop agreeing.
+ */
+export function nestedInteractives(nodes) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const found = [];
+    for (const node of nodes) {
+        if (!node.role || !INTERACTIVE_ROLES.has(node.role))
+            continue;
+        const inside = node.ancestors
+            .map((id) => byId.get(id))
+            .find((ancestor) => ancestor?.role && INTERACTIVE_ROLES.has(ancestor.role));
+        if (!inside)
+            continue;
+        found.push(nodeOf(node, `A ${node.role} inside a ${inside.role} (${inside.selector}). ` +
+            "Only one of them can receive the interaction."));
+    }
+    return finding({
+        rule: "nested-interactive",
+        impact: "serious",
+        criteria: ["1.3.1", "4.1.2"],
+        levels: ["A"],
+        help: "An interactive element must not contain another. The mouse " +
+            "and the accessibility tree disagree about what was operated.",
+    }, found);
+}
+/**
+ * Headings that skip a level, and pages with several firsts.
+ *
+ * Headings are how most screen reader users navigate a long
+ * page, so a broken outline is a broken table of contents rather
+ * than a cosmetic complaint.
+ */
+export function headingOutline(nodes) {
+    // See SUPERSEDED_BY: axe reports the skip too, and classifies
+    // it as best practice rather than a criterion. Its judgment
+    // wins where both fire; this runs for captures with no axe.
+    const headings = nodes
+        .filter((node) => node.rendered)
+        .map((node) => ({ node, level: headingLevel(node) }))
+        .filter((entry) => Boolean(entry.level));
+    const skipped = [];
+    const firsts = [];
+    let previous = 0;
+    for (const { node, level } of headings) {
+        if (level === 1)
+            firsts.push(nodeOf(node, `Heading level 1: ${node.name ?? ""}`));
+        if (previous > 0 && level > previous + 1) {
+            skipped.push(nodeOf(node, `Jumps from level ${previous} to level ${level}, so the ` +
+                `level ${previous + 1} it belongs under is missing.`));
+        }
+        previous = level;
+    }
+    return [
+        ...finding({
+            rule: "heading-skips-level",
+            impact: "moderate",
+            criteria: ["1.3.1"],
+            levels: ["A"],
+            help: "Heading levels must not skip. Headings are how a page is " +
+                "navigated without sight, and a gap breaks the outline.",
+        }, skipped),
+        ...finding({
+            rule: "single-first-heading",
+            impact: "moderate",
+            criteria: [],
+            levels: [],
+            help: "A page should have one level 1 heading naming what the " +
+                "page is. Several leaves no single answer.",
+        }, firsts.length > 1 ? firsts : []),
+    ];
+}
+function headingLevel(node) {
+    const fromTag = /^h([1-6])$/.exec(node.tag);
+    if (fromTag?.[1])
+        return Number(fromTag[1]);
+    if (node.role !== "heading")
+        return undefined;
+    const declared = node.attributes["aria-level"];
+    return declared ? Number(declared) : undefined;
+}
+/**
+ * Landmarks that cannot be told apart.
+ *
+ * Two navigations are fine and common. Two navigations with no
+ * names are a menu with two identical entries: the reader is
+ * offered a choice they have no way to make.
+ */
+export function landmarkNaming(nodes) {
+    const landmarks = nodes.filter((node) => node.rendered &&
+        node.role &&
+        LANDMARK_ROLES.includes(node.role));
+    const found = [];
+    const byRole = new Map();
+    for (const node of landmarks) {
+        const role = node.role ?? "";
+        byRole.set(role, [...(byRole.get(role) ?? []), node]);
+    }
+    for (const [role, group] of byRole) {
+        if (group.length < 2)
+            continue;
+        const unnamed = group.filter((node) => !node.name?.trim());
+        if (unnamed.length < 2)
+            continue;
+        for (const node of unnamed) {
+            found.push(nodeOf(node, `One of ${group.length} ${role} landmarks, and ${unnamed.length} ` +
+                "of them have no name to tell them apart."));
+        }
+    }
+    return finding({
+        rule: "landmark-distinguishable",
+        impact: "moderate",
+        criteria: ["1.3.1"],
+        levels: ["A"],
+        help: "Repeated landmarks of the same role need names. Without them " +
+            "the landmark menu offers a choice nobody can make.",
+    }, found);
+}
+/**
+ * Controls with nothing to call them, and errors nobody is told
+ * about.
+ *
+ * The second half is the one tools usually miss: aria-invalid
+ * announces that something is wrong without saying what, and the
+ * message sitting next to it in the layout is not connected to
+ * it in any way a screen reader can follow.
+ */
+export function formLabelling(nodes) {
+    const unnamed = [];
+    const unexplained = [];
+    for (const node of nodes) {
+        if (!node.rendered || !node.role)
+            continue;
+        // Native fields are axe's ground, and it checks them more
+        // thoroughly than this could: wrapped labels, explicit
+        // labels, titles and placeholders each have their own rule.
+        // What is left to us is a field made out of ARIA, which its
+        // label rule does not look at.
+        const isNative = node.tag === "input" || node.tag === "select" || node.tag === "textarea";
+        if (!isNative && !NEEDS_LABEL_ROLES.has(node.role))
+            continue;
+        if (isNative && node.attributes.type === "hidden")
+            continue;
+        if (!isNative && !node.name?.trim()) {
+            unnamed.push(nodeOf(node, "No accessible name: nothing tells the user what to type."));
+        }
+        // Error association, though, is nobody else's ground: axe
+        // has no rule for it, and it matters on a native field just
+        // as much as on an ARIA one.
+        if (node.attributes["aria-invalid"] === "true" &&
+            !node.attributes["aria-errormessage"] &&
+            !node.attributes["aria-describedby"]) {
+            unexplained.push(nodeOf(node, "Marked invalid with no aria-errormessage or " +
+                "aria-describedby, so the reason is announced to nobody."));
+        }
+    }
+    return [
+        ...finding({
+            rule: "aria-field-has-name",
+            impact: "critical",
+            criteria: ["4.1.2"],
+            levels: ["A"],
+            help: "A field built from an ARIA role needs an accessible " +
+                "name, the same as a native one.",
+        }, unnamed),
+        ...finding({
+            rule: "error-is-announced",
+            impact: "serious",
+            criteria: ["3.3.1"],
+            levels: ["A"],
+            help: "A field marked invalid must point at the text explaining " +
+                "why, or the error exists only visually.",
+        }, unexplained),
+    ];
+}
+/**
+ * The autocomplete tokens the specification defines.
+ *
+ * Only the ones describing the person filling the form in, since
+ * 1.3.5 is about input collecting information about the user.
+ * Taken from the HTML specification's list rather than invented.
+ */
+const KNOWN_TOKENS = new Set([
+    "name",
+    "honorific-prefix",
+    "given-name",
+    "additional-name",
+    "family-name",
+    "honorific-suffix",
+    "nickname",
+    "username",
+    "new-password",
+    "current-password",
+    "one-time-code",
+    "organization-title",
+    "organization",
+    "street-address",
+    "address-line1",
+    "address-line2",
+    "address-line3",
+    "address-level4",
+    "address-level3",
+    "address-level2",
+    "address-level1",
+    "country",
+    "country-name",
+    "postal-code",
+    "cc-name",
+    "cc-given-name",
+    "cc-additional-name",
+    "cc-family-name",
+    "cc-number",
+    "cc-exp",
+    "cc-exp-month",
+    "cc-exp-year",
+    "cc-csc",
+    "cc-type",
+    "transaction-currency",
+    "transaction-amount",
+    "language",
+    "bday",
+    "bday-day",
+    "bday-month",
+    "bday-year",
+    "sex",
+    "url",
+    "photo",
+    "tel",
+    "tel-country-code",
+    "tel-national",
+    "tel-area-code",
+    "tel-local",
+    "tel-extension",
+    "email",
+    "impp",
+]);
+/**
+ * Words in a field's own name or id that say it wants something
+ * about the person filling it in.
+ *
+ * Deliberately narrow. A false finding here sends someone adding
+ * a token to a field that never wanted one, and the cost of
+ * missing a field is that it stays as it is today.
+ */
+const PERSONAL_HINTS = [
+    [/^(e-?mail)$|(^|[^a-z])e-?mail([^a-z]|$)/i, "email"],
+    [/(^|[^a-z])(first-?name|given-?name)([^a-z]|$)/i, "given-name"],
+    [/(^|[^a-z])(last-?name|surname|family-?name)([^a-z]|$)/i, "family-name"],
+    [/(^|[^a-z])(full-?name)([^a-z]|$)/i, "name"],
+    [/(^|[^a-z])(phone|tel|mobile)([^a-z]|$)/i, "tel"],
+    [/(^|[^a-z])(street|address-?1|addr1)([^a-z]|$)/i, "street-address"],
+    [/(^|[^a-z])(zip|postal-?code|postcode)([^a-z]|$)/i, "postal-code"],
+    [/(^|[^a-z])(country)([^a-z]|$)/i, "country-name"],
+    [/(^|[^a-z])(city|town)([^a-z]|$)/i, "address-level2"],
+    [/(^|[^a-z])(organization|company)([^a-z]|$)/i, "organization"],
+];
+/** Input types that are about the person by their nature. */
+const PERSONAL_TYPES = {
+    email: "email",
+    tel: "tel",
+};
+/**
+ * What a field appears to be asking the user for, if anything.
+ *
+ * The type is trusted before the name, because type="email" is
+ * the browser's own declaration and a name is a guess.
+ */
+function wants(node) {
+    const type = (node.attributes.type ?? "text").toLowerCase();
+    const byType = PERSONAL_TYPES[type];
+    if (byType !== undefined)
+        return byType;
+    // Only plain text fields are guessed at from their name. A
+    // search, a number or a checkbox named "city" is not an address.
+    if (type !== "text")
+        return undefined;
+    const described = `${node.attributes.name ?? ""} ${node.attributes.id ?? ""}`;
+    for (const [pattern, token] of PERSONAL_HINTS) {
+        if (pattern.test(described))
+            return token;
+    }
+    return undefined;
+}
+/**
+ * Fields the browser could fill, if it were told what they are.
+ *
+ * WCAG 1.3.5. Without a token the browser will not fill the
+ * field and a password manager cannot either, so somebody who
+ * finds typing hard retypes their own address on every site that
+ * asks. axe has no rule for this, so it has been passing in
+ * silence.
+ */
+export function autocompleteTokens(nodes) {
+    const missing = [];
+    for (const node of nodes) {
+        if (!node.rendered || node.tag !== "input")
+            continue;
+        const wanted = wants(node);
+        if (wanted === undefined)
+            continue;
+        const declared = node.attributes.autocomplete?.trim().toLowerCase();
+        // An author who wrote "off" has said the browser must not
+        // remember this, and for a one-time passcode they are right.
+        // Overruling them would be this tool claiming to know better
+        // about a decision only they can make.
+        if (declared === "off" || declared === "on")
+            continue;
+        if (declared === undefined || declared === "") {
+            missing.push(nodeOf(node, `Asks for the user's own details but carries no ` +
+                `autocomplete token. autocomplete="${wanted}" would let ` +
+                "the browser fill it."));
+            continue;
+        }
+        // The specification allows prefixes: a section name, then
+        // shipping or billing, then the token itself. Reading only the
+        // bare attribute would fail every well-built checkout.
+        const last = declared.split(/\s+/).at(-1);
+        if (last === undefined || !KNOWN_TOKENS.has(last)) {
+            missing.push(nodeOf(node, `autocomplete="${declared}" is not a token the ` +
+                `specification defines, so it does nothing. ` +
+                `"${wanted}" is the one that fits.`));
+        }
+    }
+    return finding({
+        rule: "field-has-autocomplete",
+        impact: "serious",
+        criteria: ["1.3.5"],
+        levels: ["AA"],
+        help: "A field collecting the user's own information needs an " +
+            "autocomplete token, or the browser cannot fill it and " +
+            "they type it again on every site.",
+    }, missing);
+}
+/**
+ * Tab order set by hand.
+ *
+ * A positive tabindex pulls an element to the front of the tab
+ * order for the whole page, so one of them rearranges everything
+ * after it. It is almost always a local fix with a global cost.
+ */
+export function manualTabOrder(nodes) {
+    const found = nodes
+        .filter((node) => Number(node.attributes.tabindex ?? "0") > 0)
+        .map((node) => nodeOf(node, `tabindex="${node.attributes.tabindex}" puts this ahead of ` +
+        "everything with a natural order."));
+    return finding({
+        rule: "no-positive-tabindex",
+        impact: "serious",
+        criteria: ["2.4.3"],
+        levels: ["A"],
+        help: "A positive tabindex reorders the whole page, not just the " +
+            "element it is on.",
+    }, found);
+}
+/**
+ * Rules of ours that axe also reports, and under what name.
+ *
+ * These were written before running both against the same page,
+ * which is the only way the overlap shows up. Where axe reports
+ * the same thing, its finding wins: it carries a help URL, a
+ * wider tag list, and a classification its authors argued
+ * through. Two of these had been given WCAG criteria here that
+ * axe deliberately withholds, and asserting a criterion a mature
+ * rule set declined to assert wants better grounds than a
+ * preference.
+ *
+ * Ours still run, because a capture audited without axe should
+ * not lose the check entirely.
+ */
+export const SUPERSEDED_BY = {
+    "heading-skips-level": "heading-order",
+    "no-positive-tabindex": "tabindex",
+    "landmark-distinguishable": "landmark-unique",
+    // Both of these overlap an axe rule that was missing from this
+    // map, so one defect was reported twice, at critical, and the
+    // violation count the accessibility skill tells a reader to
+    // compare across a change was doubled with it.
+    "hidden-focusable": "aria-hidden-focus",
+    "aria-field-has-name": "aria-input-field-name",
+};
+/** Every structural rule, run against one capture. */
+export function analyseStructure(nodes) {
+    return [
+        ...brokenReferences(nodes),
+        ...hiddenButFocusable(nodes),
+        ...nestedInteractives(nodes),
+        ...headingOutline(nodes),
+        ...landmarkNaming(nodes),
+        ...formLabelling(nodes),
+        ...autocompleteTokens(nodes),
+        ...manualTabOrder(nodes),
+    ];
+}

package/dist/web/audit/sweep.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Running a check under several conditions at once.
+ *
+ * Most layout and contrast faults are conditional. A page is
+ * fine at 1280 and unusable at 375; a colour pair passes in
+ * light and fails in dark. Checking one condition and reporting
+ * a pass is how those ship.
+ *
+ * The table comes first and the detail second, because the
+ * useful question is almost never "what is wrong" but "where
+ * does it start going wrong". A run of passes ending in two
+ * failures at the narrow end says more than either verdict does
+ * alone.
+ */
+import type { Standing, Verdict } from "./verdict.js";
+/** One condition a check was run under. */
+export interface Condition {
+    /** How the condition reads in a table, e.g. "375px". */
+    readonly label: string;
+    readonly standing: Standing;
+    /** The one-line result under this condition. */
+    readonly headline: string;
+    /** The full report, kept for when it is asked for. */
+    readonly detail: string;
+}
+/** The worst standing among several. */
+export declare function worstOf(standings: readonly Standing[]): Standing;
+/**
+ * Say where a sweep started going wrong.
+ *
+ * Conditions are reported in the order they were run, never
+ * sorted by severity, because their order is the finding: a
+ * table that reads pass, pass, fail, fail names a breakpoint,
+ * and the same rows sorted worst-first name nothing.
+ */
+export declare function renderSweep(conditions: readonly Condition[], options?: {
+    readonly only?: string;
+}): string;
+/** The widths a sweep uses when the caller names none. */
+export declare const DEFAULT_WIDTHS: readonly [375, 768, 1280, 1920];
+/** A named condition to run under, ready to apply. */
+export interface Sweepable<T> {
+    readonly label: string;
+    readonly setting: T;
+}
+/** Turn a list of widths into conditions to sweep. */
+export declare function widthsToSweep(widths?: readonly number[]): readonly Sweepable<{
+    width: number;
+}>[];
+/**
+ * Read a verdict's standing back out of a rendered report.
+ *
+ * A report that carries no verdict head reads as "warn", never
+ * "pass". This defaulted to pass once, and because two drill-down
+ * renderers returned bare prose, a swept rule query reported PASS
+ * at every width while the named rule was failing at all of them.
+ * Approval is the one answer a parser must never invent: prefer
+ * the standing a caller passes as data, and treat this as the
+ * fallback for prose we did not produce.
+ */
+export declare function standingOf(report: string): Standing;
+/** Read a verdict's headline back out of a rendered report. */
+export declare function headlineOf(report: string): string;
+/** Build a condition from a rendered report. */
+export declare function conditionFrom(label: string, report: string): Condition;
+export type { Verdict };