@jitsusama/agentic-harness.core 0.1.0

package/dist/web/audit/report.js

@@ -0,0 +1,250 @@
+/**
+ * Reporting accessibility findings without drowning the reader.
+ *
+ * Summary first, then one line per rule, then detail only when
+ * asked for by rule name. A finding nobody can act on because it
+ * arrived inside forty kilobytes of markup is not a finding.
+ */
+import { hardestLevel, orderFindings, tallyFindings, } from "./axe.js";
+import { count, renderVerdict, standingFor } from "./verdict.js";
+/** How many elements to name under a rule before counting. */
+export const MAX_LISTED_NODES = 5;
+const IMPACT_ORDER = [
+    "critical",
+    "serious",
+    "moderate",
+    "minor",
+];
+/**
+ * The headline: what a person needs before deciding to read on.
+ *
+ * WCAG failures and best-practice advice are counted separately
+ * and always, even when one of them is zero. The difference is
+ * the difference between failing a standard and disagreeing with
+ * a linter.
+ */
+/**
+ * Where a tally stands against the standards, which is what the
+ * mark at the top means.
+ *
+ * FAIL is reserved for a criterion that was actually violated.
+ * Best practice is somebody's good advice, not a standard, and a
+ * report that opened with FAIL because a page has two level-one
+ * headings spends the word on an opinion. Anybody gating a build
+ * on it then has to ignore it, and the one time it means a real
+ * violation they will.
+ *
+ * So best-practice failures land with the undecided ones under
+ * WARN, which keeps a single honest meaning for that mark: the
+ * tool will not decide this one for you, either because nothing
+ * could measure it or because whether it matters is a judgment
+ * call. The headline always says which.
+ */
+function standardsPosition(tally) {
+    return {
+        failures: tally.wcag,
+        warnings: tally.needsReview + tally.bestPractice,
+    };
+}
+/**
+ * Which bar this was judged against, and whether a lower one
+ * would have been met.
+ *
+ * The bar has to be named or the report is unreadable: a page
+ * built to AA, judged at AAA, reads as broken rather than as not
+ * reaching for the enhanced level. And naming it is not enough on
+ * its own. A reader whose only failures are AAA ones needs to be
+ * told the page still meets AA, because the difference between
+ * "non-conformant" and "conformant, short of enhanced" is the
+ * difference between an emergency and a backlog item.
+ */
+function againstBar(findings, bar) {
+    if (bar === undefined)
+        return "";
+    const failed = findings.filter((finding) => finding.kind === "violation");
+    if (failed.length === 0)
+        return ` Judged against ${bar}.`;
+    const hardest = hardestLevel(failed);
+    if (bar === "AAA" && hardest === "AAA") {
+        return " Judged against AAA; every failure is a AAA one, so the page still meets AA.";
+    }
+    return ` Judged against ${bar}.`;
+}
+export function renderSummary(tally) {
+    if (tally.violations === 0 && tally.needsReview === 0) {
+        return "Nothing failed.";
+    }
+    const parts = [];
+    // Say outright when nothing broke a standard, because the mark
+    // above now reads WARN and a reader deserves to know why before
+    // the counts start.
+    if (tally.wcag === 0 && tally.bestPractice > 0) {
+        parts.push(`No WCAG criterion failed. ${count(tally.bestPractice, "best-practice rule")} did, across ${count(tally.elements, "element")}.`);
+        if (tally.needsReview > 0) {
+            parts.push(`${count(tally.needsReview, "rule")} on ` +
+                `${count(tally.reviewElements, "element")} ` +
+                `${tally.needsReview === 1 ? "needs" : "need"} a person to ` +
+                "look: nothing could decide on its own.");
+        }
+        return parts.join(" ");
+    }
+    if (tally.violations > 0) {
+        const severities = IMPACT_ORDER.filter((impact) => tally.byImpact[impact] > 0)
+            .map((impact) => `${tally.byImpact[impact]} ${impact}`)
+            .join(", ");
+        parts.push(`${count(tally.violations, "rule")} failed across ` +
+            `${count(tally.elements, "element")}: ${severities}.`);
+        parts.push(`${tally.wcag === 1
+            ? "1 is a WCAG criterion"
+            : `${tally.wcag} are WCAG criteria`}, ${tally.bestPractice} best practice.`);
+    }
+    if (tally.needsReview > 0) {
+        parts.push(`${count(tally.needsReview, "rule")} on ` +
+            `${count(tally.reviewElements, "element")} ` +
+            `${tally.needsReview === 1 ? "needs" : "need"} a person to ` +
+            "look: nothing could decide on its own.");
+    }
+    return parts.join(" ");
+}
+/**
+ * Reported rules whose name shares a word with the one asked for.
+ *
+ * Rule names are hyphenated words, and the ways people get one
+ * wrong nearly always keep a word: target-size for
+ * target-is-big-enough, contrast for color-contrast. Matching on
+ * whole words rather than on edit distance keeps an unrelated
+ * rule out of a suggestion that is meant to be a short list.
+ */
+function nearestRules(asked, reported) {
+    const words = new Set(asked.toLowerCase().split(/[^a-z0-9]+/i));
+    words.delete("");
+    return reported
+        .filter((rule) => rule
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .some((word) => words.has(word)))
+        .slice(0, MAX_SUGGESTED_RULES);
+}
+/** How many near misses are a help rather than a second list. */
+const MAX_SUGGESTED_RULES = 3;
+/** One line per rule: enough to choose what to read. */
+export function renderIndex(findings) {
+    if (findings.length === 0)
+        return "";
+    const lines = [];
+    let heading;
+    for (const finding of findings) {
+        const group = finding.kind === "violation" ? "Failures" : "Needs a person to look";
+        if (group !== heading) {
+            if (heading !== undefined)
+                lines.push("");
+            lines.push(group);
+            heading = group;
+        }
+        lines.push(`  ${describeRule(finding)}`);
+    }
+    return lines.join("\n");
+}
+function describeRule(finding) {
+    const where = finding.criteria.length > 0
+        ? `WCAG ${finding.criteria.join(", ")}`
+        : "best practice";
+    const hits = count(finding.nodes.length, "element");
+    return `${finding.impact.padEnd(8)} ${finding.rule.padEnd(28)} ${hits.padEnd(12)} ${where}`;
+}
+/** Everything known about one rule, for when it is asked about. */
+export function renderFinding(finding) {
+    const lines = [
+        `${finding.rule}  (${finding.impact}, ${finding.criteria.length > 0
+            ? `WCAG ${finding.criteria.join(", ")}${finding.levels.length > 0
+                ? ` level ${finding.levels.join("/")}`
+                : ""}`
+            : "best practice"})`,
+        finding.help,
+    ];
+    if (finding.kind === "needs-review") {
+        lines.push("axe could not decide this one; it needs a person to look.");
+    }
+    lines.push("");
+    for (const node of finding.nodes.slice(0, MAX_LISTED_NODES)) {
+        lines.push(`  ${node.selector}`);
+        if (node.html)
+            lines.push(`    ${node.html}`);
+        for (const message of node.messages)
+            lines.push(`    ${message}`);
+    }
+    if (finding.nodes.length > MAX_LISTED_NODES) {
+        lines.push(`  ... and ${count(finding.nodes.length - MAX_LISTED_NODES, "more element")}`);
+    }
+    if (finding.helpUrl) {
+        lines.push("", finding.helpUrl);
+    }
+    return lines.join("\n");
+}
+/** The whole report, summary first. */
+export function renderAudit(unordered, tally, options = {}) {
+    // Ordered here rather than trusted from the caller. A report
+    // that claims to lead with the worst thing found has to do so
+    // however the findings were assembled: the layout rules build
+    // their list in rule order, and reported a serious finding
+    // below a moderate one until this was moved here.
+    const findings = orderFindings(unordered);
+    if (options.rule) {
+        // A rule can be reported twice, once as a failure and once as
+        // undecided: colour contrast does exactly this when some text
+        // sits on a gradient. Showing only the first would hide the
+        // half that most needs a person.
+        const found = findings.filter((finding) => finding.rule === options.rule);
+        // A drill-down carries a verdict head like every other answer.
+        // It used to return bare prose, and a caller that recovered the
+        // standing by reading the first word then scored it a pass, so
+        // a swept rule query reported PASS at every width while the
+        // rule was failing at all of them.
+        if (found.length === 0) {
+            const reported = [...new Set(findings.map((finding) => finding.rule))];
+            const names = reported.slice(0, MAX_LISTED_NODES).join(", ");
+            // A clean page is a clean page, whatever was asked for.
+            if (names === "") {
+                return renderVerdict({
+                    standing: "pass",
+                    headline: `Nothing was reported for '${options.rule}', and ` +
+                        "nothing failed.",
+                }, "");
+            }
+            // On a page that did report, a name matching none of it is
+            // two different answers wearing one face: the rule ran and
+            // was clean, or the name is wrong. Nothing here can tell
+            // them apart, and PASS picks the flattering one. Asked for
+            // 'target-size', which is what axe calls this rule elsewhere
+            // and what WCAG calls the criterion, a page failing ten
+            // rules answered PASS with the failures a line below.
+            const close = nearestRules(options.rule, reported);
+            return renderVerdict({
+                standing: "warn",
+                headline: `Nothing was reported for '${options.rule}'. It may ` +
+                    "have passed, or it may not be a rule name.",
+                measured: (close.length === 0
+                    ? ""
+                    : `Closest reported: ${close.join(", ")}. `) +
+                    `Reported: ${names}.`,
+            }, "");
+        }
+        const ruleTally = tallyFindings(found);
+        return renderVerdict({
+            standing: standingFor(standardsPosition(ruleTally)),
+            headline: `${options.rule}: ${renderSummary(ruleTally)}`,
+            ...(options.measured === undefined
+                ? {}
+                : { measured: options.measured }),
+        }, found.map(renderFinding).join("\n\n"));
+    }
+    const index = renderIndex(findings);
+    const verdict = {
+        standing: standingFor(standardsPosition(tally)),
+        headline: `${renderSummary(tally)}${againstBar(findings, options.bar)}`,
+        ...(options.measured === undefined ? {} : { measured: options.measured }),
+    };
+    return renderVerdict(verdict, index === ""
+        ? ""
+        : `${index}\n\nName a rule to see the elements and how to fix them.`);
+}

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

@@ -0,0 +1,126 @@
+/**
+ * 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.
+ */
+import type { A11yFinding } from "./axe.js";
+/** One element, as these rules need to see it. */
+export interface StructureNode {
+    /** Stable id for addressing, from whatever captured it. */
+    readonly id: string;
+    /** A selector or path a person can use to find it. */
+    readonly selector: string;
+    readonly tag: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    /** The browser's computed role, when it has one. */
+    readonly role?: string;
+    /** The browser's computed accessible name. */
+    readonly name?: string;
+    /** Whether the browser says this can take focus. */
+    readonly focusable: boolean;
+    /** Whether the browser drew it. */
+    readonly rendered: boolean;
+    /** Ancestor ids, nearest first. */
+    readonly ancestors: readonly string[];
+    /** The element's own markup, already clipped. */
+    readonly html?: string;
+}
+/** Attributes whose value is one or more element ids. */
+export declare const IDREF_ATTRIBUTES: readonly ["aria-labelledby", "aria-describedby", "aria-controls", "aria-owns", "aria-details", "aria-errormessage", "aria-flowto"];
+/** Attributes holding exactly one id. */
+export declare const SINGLE_IDREF_ATTRIBUTES: readonly ["aria-activedescendant", "for"];
+/** Roles that name a region of the page. */
+export declare const LANDMARK_ROLES: readonly ["banner", "complementary", "contentinfo", "form", "main", "navigation", "region", "search"];
+export declare function brokenReferences(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function hiddenButFocusable(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function nestedInteractives(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function headingOutline(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function landmarkNaming(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function formLabelling(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function autocompleteTokens(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare function manualTabOrder(nodes: readonly StructureNode[]): readonly A11yFinding[];
+/**
+ * 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 declare const SUPERSEDED_BY: Readonly<Record<string, string>>;
+/** Every structural rule, run against one capture. */
+export declare function analyseStructure(nodes: readonly StructureNode[]): readonly A11yFinding[];