@jitsusama/agentic-harness.core 0.1.0

package/dist/web/audit/axe.js

@@ -0,0 +1,322 @@
+/**
+ * Reading axe-core's results.
+ *
+ * axe is the WCAG baseline here: a mature, widely trusted rule
+ * set that there is no reason to reimplement. What it needs is
+ * translating, for two reasons.
+ *
+ * The first is size. A thirteen element test page produces 54 KB
+ * of JSON, and a real application produces far more, most of it
+ * repeated rule metadata and full outerHTML for every node. Read
+ * whole, it would crowd out the answer it was fetched to give.
+ *
+ * The second is that axe draws a distinction people routinely
+ * lose, and it is worth preserving loudly. Some of its rules are
+ * WCAG success criteria and some are best practice, and a report
+ * that mixes them tells somebody their page fails a standard
+ * when it does not. Incomplete results matter for the same
+ * reason in reverse: axe declines to judge text over a gradient,
+ * and turning that silence into a pass is how a tool starts
+ * lying.
+ */
+/**
+ * The experimental axe rules that test a real WCAG criterion.
+ *
+ * axe ships these switched off because it does not trust them to
+ * be right, which is its call to make about its own rules. But
+ * off means never asked, and for 2.5.3 there is no other rule to
+ * ask: leaving the default alone means that criterion is not
+ * covered at all, while the report says the page passed the
+ * standard. Silence read as a pass is the failure this package
+ * cares most about.
+ *
+ * They are switched on and their findings come back as needing a
+ * person, so axe's doubt travels with them rather than being
+ * dropped on the floor.
+ *
+ * The list is checked against the installed axe by a test, so an
+ * upgrade that adds or retires one is a failure to read rather
+ * than a silent change in what gets audited.
+ */
+export const EXPERIMENTAL_WCAG_RULES = [
+    "css-orientation-lock",
+    "label-content-name-mismatch",
+    "p-as-heading",
+    "table-fake-caption",
+    "td-has-header",
+];
+/** How far each bar reaches, for comparing one against another. */
+const BAR_REACH = { A: 1, AA: 2, AAA: 3 };
+/**
+ * The AAA rules axe ships switched off.
+ *
+ * Measured against axe 4.12.1: exactly three rules carry a AAA
+ * tag and every one of them is disabled by default, so a run that
+ * does not name them checks no AAA criterion at all. Judging at
+ * AAA without switching these on would report a page as meeting
+ * the enhanced bar on the strength of never having tested it.
+ *
+ * Checked against the installed axe by a test, like the
+ * experimental list, so an upgrade that adds or retires one is a
+ * failure to read rather than a silent gap.
+ */
+export const ENHANCED_WCAG_RULES = [
+    "color-contrast-enhanced",
+    "identical-links-same-purpose",
+    "meta-refresh-no-exceptions",
+];
+/**
+ * Whether a finding is something the chosen bar actually asks for.
+ *
+ * A finding carrying no level is a best-practice rule rather than
+ * a conformance claim, and those are always reported: they were
+ * never the standard's to demand, so a bar cannot excuse them.
+ */
+export function withinBar(levels, bar) {
+    if (levels.length === 0)
+        return true;
+    return levels.some((level) => {
+        const reach = BAR_REACH[level];
+        return reach !== undefined && reach <= BAR_REACH[bar];
+    });
+}
+/** The strictest level any of these findings failed. */
+export function hardestLevel(findings) {
+    let hardest;
+    for (const finding of findings) {
+        for (const level of finding.levels) {
+            const bar = level;
+            if (BAR_REACH[bar] === undefined)
+                continue;
+            if (hardest === undefined || BAR_REACH[bar] < BAR_REACH[hardest]) {
+                hardest = bar;
+            }
+        }
+    }
+    return hardest;
+}
+/** How much markup to keep per node. */
+export const MAX_NODE_HTML = 160;
+const IMPACTS = ["critical", "serious", "moderate", "minor"];
+/** A criterion tag: wcag412 is 4.1.2. */
+const CRITERION = /^wcag(\d)(\d)(\d{1,2})$/;
+/** A level tag: wcag2a, wcag21aa, wcag22aa. */
+const LEVEL = /^wcag\d{1,2}(a{1,3})$/;
+/**
+ * Read the WCAG criteria a rule maps to.
+ *
+ * axe tags rules for several standards at once. Only the WCAG
+ * ones are read here, since quoting EN 301 549 clauses at
+ * somebody who asked about WCAG is noise.
+ */
+export function criteriaOf(tags) {
+    const found = [];
+    for (const tag of tags) {
+        const parts = CRITERION.exec(tag);
+        if (parts)
+            found.push(`${parts[1]}.${parts[2]}.${parts[3]}`);
+    }
+    return found;
+}
+/** Read the conformance levels a rule belongs to. */
+export function levelsOf(tags) {
+    const found = new Set();
+    for (const tag of tags) {
+        const parts = LEVEL.exec(tag);
+        if (parts?.[1])
+            found.add(parts[1].toUpperCase());
+    }
+    return [...found].sort();
+}
+/**
+ * Whether a rule states a standard or an opinion.
+ *
+ * axe marks its own recommendations best-practice. They are good
+ * advice and they are not WCAG, and a report that blurs the two
+ * tells somebody their page fails a standard when it does not.
+ */
+export function authorityOf(tags) {
+    if (criteriaOf(tags).length > 0)
+        return "wcag";
+    // A level tag on its own still says this is a WCAG rule. Every
+    // rule axe ships today carries both, so this changes nothing
+    // today; it matters because the mark at the top of the report
+    // now turns on this answer, and the failure it would cause is
+    // the bad one. Reading a real criterion as advice downgrades a
+    // violation to WARN and hides it.
+    return levelsOf(tags).length > 0 ? "wcag" : "best-practice";
+}
+function impactOf(value) {
+    return IMPACTS.find((impact) => impact === value) ?? "minor";
+}
+function selectorOf(node) {
+    const first = node.target?.[0];
+    if (typeof first === "string")
+        return first;
+    // A nested array is axe's way of naming a frame path.
+    if (Array.isArray(first))
+        return first.join(" >> ");
+    return "(unlocated)";
+}
+function messagesOf(node) {
+    const checks = [
+        ...(node.any ?? []),
+        ...(node.all ?? []),
+        ...(node.none ?? []),
+    ];
+    const messages = checks
+        .map((check) => check.message)
+        .filter((message) => Boolean(message));
+    return messages.length > 0
+        ? [...new Set(messages)]
+        : node.failureSummary
+            ? [node.failureSummary]
+            : [];
+}
+function clip(html) {
+    if (!html)
+        return "";
+    const flat = html.replace(/\s+/g, " ").trim();
+    return flat.length <= MAX_NODE_HTML
+        ? flat
+        : `${flat.slice(0, MAX_NODE_HTML)}...`;
+}
+/**
+ * The rule switches to hand axe, turning on the experimental
+ * rules that carry a WCAG criterion and touching nothing else.
+ *
+ * Enabling by name rather than by tag on purpose: a runOnly tag
+ * list replaces the default set instead of adding to it, so any
+ * rule whose tags fell outside the list would quietly stop
+ * running. Widening an audit must not narrow it.
+ */
+export function enabledRules(bar = "AAA") {
+    const switches = {};
+    for (const rule of EXPERIMENTAL_WCAG_RULES) {
+        switches[rule] = { enabled: true };
+    }
+    // The enhanced rules are only asked for when the enhanced bar is,
+    // because switching them on always would report AAA failures
+    // against a page that never claimed to reach for AAA.
+    if (bar === "AAA") {
+        for (const rule of ENHANCED_WCAG_RULES) {
+            switches[rule] = { enabled: true };
+        }
+    }
+    return switches;
+}
+/**
+ * Turn one raw axe result into a finding.
+ *
+ * A rule axe tags experimental never comes back decided. Five of
+ * those rules carry real WCAG criteria and are switched off by
+ * default, so running them is the only way some criteria get
+ * checked at all, 2.5.3 among them. But axe declines to trust
+ * their judgement, and repeating what they say as a settled
+ * failure would be claiming an authority its author did not.
+ * They are reported as needing a person, which is what they are.
+ */
+export function readResult(result, kind) {
+    const tags = result.tags ?? [];
+    return {
+        rule: result.id,
+        kind: tags.includes("experimental") ? "needs-review" : kind,
+        impact: impactOf(result.impact),
+        authority: authorityOf(tags),
+        criteria: criteriaOf(tags),
+        levels: levelsOf(tags),
+        help: result.help ?? result.description ?? result.id,
+        ...(result.helpUrl === undefined ? {} : { helpUrl: result.helpUrl }),
+        nodes: (result.nodes ?? []).map((node) => ({
+            selector: selectorOf(node),
+            html: clip(node.html),
+            messages: messagesOf(node),
+        })),
+    };
+}
+/**
+ * Read a whole axe run.
+ *
+ * Findings are ordered by how much they bite, then by rule, so
+ * the first thing read is the worst thing found. Violations come
+ * before the ones needing review, because a thing known to be
+ * broken outranks a thing that might be.
+ */
+export function readAxeRun(run) {
+    const findings = [
+        ...(run.violations ?? []).map((result) => readResult(result, "violation")),
+        ...(run.incomplete ?? []).map((result) => readResult(result, "needs-review")),
+    ];
+    return orderFindings(findings);
+}
+/** Worst first, and what is known broken before what might be. */
+export function orderFindings(findings) {
+    return [...findings].sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === "violation" ? -1 : 1;
+        const severity = IMPACTS.indexOf(a.impact) - IMPACTS.indexOf(b.impact);
+        return severity === 0 ? a.rule.localeCompare(b.rule) : severity;
+    });
+}
+/**
+ * Put two rule sets into one ordered report.
+ *
+ * A reader should not have to know which rule set caught a
+ * thing in order to act on it, so the sets are interleaved by
+ * severity rather than listed one after the other.
+ *
+ * Where both report the same thing, the primary set wins. Two
+ * entries saying the same thing is worse than either alone, and
+ * the overlap is not always visible from the rule names: a
+ * secondary rule can declare which primary rule supersedes it.
+ */
+export function mergeFindings(primary, secondary, supersededBy = {}) {
+    const taken = new Set(primary.map((finding) => finding.rule));
+    return orderFindings([
+        ...primary,
+        ...secondary.filter((finding) => !taken.has(finding.rule) &&
+            !taken.has(supersededBy[finding.rule] ?? "")),
+    ]);
+}
+/** Count what was found. */
+export function tallyFindings(findings) {
+    const byImpact = {
+        critical: 0,
+        serious: 0,
+        moderate: 0,
+        minor: 0,
+    };
+    let elements = 0;
+    let reviewElements = 0;
+    let wcag = 0;
+    let bestPractice = 0;
+    let violations = 0;
+    let needsReview = 0;
+    for (const finding of findings) {
+        if (finding.kind === "violation") {
+            // Counted apart, because an element nobody could judge has
+            // not been shown to be broken and must not inflate a
+            // failure count.
+            elements += finding.nodes.length;
+            violations += 1;
+            byImpact[finding.impact] += 1;
+            if (finding.authority === "wcag")
+                wcag += 1;
+            else
+                bestPractice += 1;
+        }
+        else {
+            reviewElements += finding.nodes.length;
+            needsReview += 1;
+        }
+    }
+    return {
+        violations,
+        needsReview,
+        elements,
+        reviewElements,
+        byImpact,
+        wcag,
+        bestPractice,
+    };
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Contrast for text whose background axe declines to judge.
+ *
+ * A gradient or a photograph defeats the usual reading: there is no
+ * single background colour to compare against, so axe reports the
+ * element as needing a person. The pixels are available, but they
+ * cannot be classified on colour alone, because where contrast is
+ * worst the glyph and its background are the same colour by
+ * definition, and antialiasing puts blends between the two.
+ *
+ * What works is a subtraction. Shoot the region, hide the text, shoot
+ * it again: the pixels that changed are exactly where the glyphs
+ * landed, edges included, and the second shot shows what lies under
+ * them. Every ratio here is measured over that mask and no wider, so
+ * the answer is about the text a reader has to read rather than about
+ * the box it sits in.
+ */
+import { type ContrastLevel, type TextSizing } from "./contrast.js";
+/** A decoded region: RGBA, row-major, as a PNG decodes. */
+export interface Pixels {
+    readonly width: number;
+    readonly height: number;
+    readonly data: Uint8Array | Buffer;
+}
+/** An sRGB colour, as a computed style reports one. */
+export interface Rgb {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+/** What the subtraction found. */
+export interface BehindReport {
+    /** How many pixels the glyphs touched. Zero means nothing to judge. */
+    readonly glyphPixels: number;
+    /** The worst ratio the text meets anywhere it lands. */
+    readonly worstRatio: number;
+    /** The ratio the criterion asks of text this size at this bar. */
+    readonly required: number;
+    readonly verdict: "pass" | "fail" | "undecidable";
+    /** Which undecidable this was, when it was one. */
+    readonly undecided: "no-text-pixels" | "unreadable-text-colour" | undefined;
+    /** Where the worst pixel sat, relative to the region. */
+    readonly worstAt: {
+        readonly x: number;
+        readonly y: number;
+    } | undefined;
+}
+/**
+ * Judge text against the background actually behind its glyphs.
+ *
+ * The two regions must be the same size and the same view: only the
+ * text may differ between them. Hiding text is a paint-only change,
+ * so nothing moves and the subtraction stays aligned.
+ */
+export declare function foldBehind(input: {
+    readonly withText: Pixels;
+    readonly bare: Pixels;
+    readonly textColour: Rgb | undefined;
+    readonly sizing: TextSizing;
+    readonly bar: ContrastLevel;
+}): BehindReport;
+/** Render a subtraction as a verdict a reader can act on. */
+export declare function renderBehind(report: BehindReport): string;

package/dist/web/audit/behind.js

@@ -0,0 +1,142 @@
+/**
+ * Contrast for text whose background axe declines to judge.
+ *
+ * A gradient or a photograph defeats the usual reading: there is no
+ * single background colour to compare against, so axe reports the
+ * element as needing a person. The pixels are available, but they
+ * cannot be classified on colour alone, because where contrast is
+ * worst the glyph and its background are the same colour by
+ * definition, and antialiasing puts blends between the two.
+ *
+ * What works is a subtraction. Shoot the region, hide the text, shoot
+ * it again: the pixels that changed are exactly where the glyphs
+ * landed, edges included, and the second shot shows what lies under
+ * them. Every ratio here is measured over that mask and no wider, so
+ * the answer is about the text a reader has to read rather than about
+ * the box it sits in.
+ */
+import { isLargeText, } from "./contrast.js";
+/** Relative luminance, per WCAG's definition. */
+function luminance(r, g, b) {
+    const channel = (raw) => {
+        const s = raw / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+/** The contrast ratio between two luminances, per WCAG. */
+function ratio(one, other) {
+    const [lighter, darker] = one > other ? [one, other] : [other, one];
+    return (lighter + 0.05) / (darker + 0.05);
+}
+/**
+ * Judge text against the background actually behind its glyphs.
+ *
+ * The two regions must be the same size and the same view: only the
+ * text may differ between them. Hiding text is a paint-only change,
+ * so nothing moves and the subtraction stays aligned.
+ */
+export function foldBehind(input) {
+    const { withText, bare, textColour, sizing, bar } = input;
+    const large = isLargeText(sizing);
+    // The four numbers WCAG 1.4.3 and 1.4.6 actually specify.
+    const required = bar === "AAA" ? (large ? 4.5 : 7) : large ? 3 : 4.5;
+    const width = Math.min(withText.width, bare.width);
+    const height = Math.min(withText.height, bare.height);
+    const textLum = textColour
+        ? luminance(textColour.r, textColour.g, textColour.b)
+        : undefined;
+    let glyphPixels = 0;
+    let worstRatio = Number.POSITIVE_INFINITY;
+    let worstAt;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const inText = (y * withText.width + x) * 4;
+            const inBare = (y * bare.width + x) * 4;
+            // Any difference at all counts. An antialiased edge can move a
+            // single channel by one, and that pixel is still text; a
+            // threshold here would quietly stop judging thin glyphs.
+            const touched = withText.data[inText] !== bare.data[inBare] ||
+                withText.data[inText + 1] !== bare.data[inBare + 1] ||
+                withText.data[inText + 2] !== bare.data[inBare + 2];
+            if (!touched)
+                continue;
+            glyphPixels++;
+            // The mask is worth building even with no colour to judge
+            // against: the count is then a measurement rather than a
+            // stand-in for one.
+            if (textLum === undefined)
+                continue;
+            const behind = ratio(textLum, luminance(bare.data[inBare] ?? 0, bare.data[inBare + 1] ?? 0, bare.data[inBare + 2] ?? 0));
+            if (behind < worstRatio) {
+                worstRatio = behind;
+                worstAt = { x, y };
+            }
+        }
+    }
+    if (glyphPixels === 0) {
+        return {
+            glyphPixels: 0,
+            worstRatio: 0,
+            required,
+            verdict: "undecidable",
+            undecided: "no-text-pixels",
+            worstAt: undefined,
+        };
+    }
+    if (textLum === undefined) {
+        // The glyphs are there and the background is readable; what is
+        // missing is the one colour the ratio needs. Substituting a
+        // plausible one would answer confidently about a colour nobody
+        // read, which is the failure this whole module exists to avoid.
+        return {
+            glyphPixels,
+            worstRatio: 0,
+            required,
+            verdict: "undecidable",
+            undecided: "unreadable-text-colour",
+            worstAt: undefined,
+        };
+    }
+    return {
+        glyphPixels,
+        worstRatio,
+        required,
+        verdict: worstRatio >= required ? "pass" : "fail",
+        undecided: undefined,
+        worstAt,
+    };
+}
+/** How much of the region the glyphs actually covered. */
+function glyphArea(pixels) {
+    return pixels === 1 ? "1 pixel" : `${pixels} pixels`;
+}
+/** Render a subtraction as a verdict a reader can act on. */
+export function renderBehind(report) {
+    if (report.verdict === "undecidable") {
+        const many = glyphArea(report.glyphPixels);
+        const why = report.undecided === "unreadable-text-colour"
+            ? `The glyphs are here, covering ${many}, but the text's own ` +
+                "colour could not be read, so there is nothing to compare " +
+                "the background against. A stylesheet using a colour " +
+                "syntax this build cannot parse will do that."
+            : "Hiding the text changed no pixels, so there is no text here " +
+                "to measure, or it was already invisible.";
+        return ["WARN contrast behind the text could not be judged", "", why].join("\n");
+    }
+    const mark = report.verdict === "pass" ? "PASS" : "FAIL";
+    const ratioText = `${report.worstRatio.toFixed(2)}:1`;
+    const where = report.worstAt
+        ? ` Worst at ${report.worstAt.x},${report.worstAt.y} in the region.`
+        : "";
+    // The pixel count is what keeps the ratio honest: it says the
+    // number describes the glyphs rather than the whole box.
+    const many = glyphArea(report.glyphPixels);
+    return [
+        `${mark} worst contrast behind the text is ${ratioText}` +
+            `, against ${report.required}:1 required`,
+        "",
+        `Measured over the ${many} the glyphs cover, against the ` +
+            `background underneath them.${where}`,
+    ].join("\n");
+}

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

@@ -0,0 +1,43 @@
+/**
+ * Building the structural view from two of the browser's own
+ * accounts of the page.
+ *
+ * The snapshot knows every element, its attributes, whether it
+ * was drawn and where it sits in the tree. The accessibility
+ * tree knows what each one is and what it is called. Neither
+ * knows both, and every structural rule needs both, so they are
+ * joined here on the backend node id that appears in each.
+ *
+ * The join is the whole of this module's job. No role is
+ * inferred from a tag, no name is derived from content, and
+ * nothing is guessed when a node appears in one account and not
+ * the other. What the browser did not say, this does not say.
+ */
+import type { IndexedNode } from "../snapshot/index.js";
+import type { StructureNode } from "./structure.js";
+/** The accessibility facts a structural rule needs. */
+export interface AxFacts {
+    readonly backendNodeId: number;
+    readonly role?: string;
+    readonly name?: string;
+    /** Absent when the tree did not say, which it does not for
+     * any node it ignored. Not the same as false. */
+    readonly focusable?: boolean;
+}
+/**
+ * Give an element an address a person can act on.
+ *
+ * An id is best, then a test hook, then a class, and a tag with
+ * its position as the last resort. This is presentation, not
+ * measurement: the browser did not offer a selector, and one
+ * that reads well is worth more than one that is unique.
+ */
+export declare function selectorFor(node: IndexedNode): string;
+/**
+ * Join a snapshot to an accessibility tree.
+ *
+ * Text nodes are dropped: every structural rule is about
+ * elements, and keeping the text would double the size of the
+ * capture to no purpose.
+ */
+export declare function buildStructure(nodes: readonly IndexedNode[], facts: readonly AxFacts[]): readonly StructureNode[];