@jitsusama/agentic-harness.core 0.1.0

package/dist/web/a11y/walkprobe.js

@@ -0,0 +1,365 @@
+/**
+ * The page-side half of the keyboard walk.
+ *
+ * These ship as source strings because they declare helpers of
+ * their own, and the bundler renames every named inner binding
+ * through a wrapper the page has never heard of. A function
+ * handed over as a value would throw before it registered
+ * anything, silently.
+ */
+/**
+ * What counts as a modal, from the page's own point of view.
+ *
+ * A dialog that contains focus is doing its job, and a keyboard
+ * checker that cannot tell that from a dead end reports the
+ * reference implementation of the pattern as the defect it
+ * exists to find.
+ */
+const MODAL_SELECTOR = 'dialog[open], [role="dialog"][aria-modal="true"], ' +
+    '[role="alertdialog"][aria-modal="true"]';
+import { DEEP_DOM } from "../snapshot/deep.js";
+/**
+ * What to call a focus stop, shared by both halves of the walk.
+ *
+ * A form control carries none of its name on itself: the name sits
+ * in a label pointing at it, a label wrapping it, or an element
+ * named through aria-labelledby. Reading attributes alone made
+ * every field in a form report as a bare INPUT, which is precisely
+ * the listing a reviewer uses to check that tab order follows the
+ * page. The browser already implements the label algorithm, so
+ * `el.labels` is asked rather than the association being worked out
+ * here.
+ *
+ * Interpolated into both probes rather than written twice. It was
+ * written twice, the two copies drifted, and fixing the one that
+ * collects candidates left the one that records stops still
+ * answering the old way.
+ */
+const NAMING = `
+	const labelled = (el) => {
+		const by = el.getAttribute && el.getAttribute("aria-labelledby");
+		if (by) {
+			const words = by.split(/\\s+/)
+				.map((id) => {
+					const source = document.getElementById(id);
+					return source ? source.innerText || source.textContent || "" : "";
+				})
+				.join(" ").trim();
+			if (words) return words;
+		}
+		const labels = el.labels;
+		if (labels && labels.length) {
+			return Array.prototype.map
+				.call(labels, (label) => label.innerText || label.textContent || "")
+				.join(" ").trim();
+		}
+		return "";
+	};
+	const nameOf = (el) =>
+		(el.getAttribute("aria-label") || labelled(el) || el.innerText ||
+			el.value || el.getAttribute("title") || el.getAttribute("alt") ||
+			"").trim().slice(0, 60);
+`;
+/**
+ * Collect everything the browser will let focus land on, and
+ * remember what each looks like at rest.
+ *
+ * The list is deliberately built from the browser's own view: an
+ * element that is display:none or disabled is not focusable no
+ * matter what its markup says, and asking the computed style is
+ * the only way to know.
+ */
+export const WALK_COLLECT = `(() => {
+	${DEEP_DOM}
+	const selector = [
+		"a[href]", "button", "input", "select", "textarea",
+		"[tabindex]", "details", "audio[controls]", "video[controls]",
+		"[contenteditable]",
+	].join(",");
+	const modalSelector = ${JSON.stringify(MODAL_SELECTOR)};
+
+	// checkVisibility is the browser's own answer, but only if it
+	// is asked the whole question. Bare checkVisibility() reports
+	// on display and nothing else: it calls a visibility:hidden
+	// control focusable, and a real app hides its closed menus and
+	// dialogs that way. Measured on one page: 58 said focusable
+	// against 13 that could actually take focus.
+	//
+	// opacity is deliberately NOT asked about. An opacity:0 control
+	// is still in the focus order, so excluding it would bury a
+	// real defect: focus landing somewhere invisible. That is the
+	// walk's own "no visible focus indicator" finding, and it can
+	// only make it if the element survives to be walked.
+	const visible = (el) =>
+		typeof el.checkVisibility === "function"
+			? el.checkVisibility({
+					visibilityProperty: true,
+					contentVisibilityAuto: true,
+				})
+			: el.getClientRects().length > 0;
+
+	// inert takes an element out of the focus order without
+	// touching how it looks, so no style question finds it. A
+	// closed dialog's contents are the ordinary case.
+	const inert = (el) =>
+		typeof el.closest === "function" && el.closest("[inert]") !== null;
+
+	// The browser's own answer, and the last word: try it. Style
+	// rules approximate the focus order, but inertness applied by
+	// an open modal is not spelled anywhere in markup, and only an
+	// attempt can settle it. Focusing something unfocusable is a
+	// no-op, so the only elements this can disturb are the ones the
+	// walk is about to tab through anyway, and preventScroll keeps
+	// it from moving the page under us.
+	const canHoldFocus = (el) => {
+		try {
+			el.focus({ preventScroll: true });
+		} catch (error) {
+			return false;
+		}
+		const root = el.getRootNode();
+		return (root.activeElement || document.activeElement) === el;
+	};
+
+	// Every focusable thing on the page, including inside open
+	// shadow roots and same-origin frames. Reading only the top
+	// document reported a design-system page as having no
+	// focusable controls at all, which the check then rendered as
+	// "Nothing on this page can hold focus".
+	// Everything the cheap tests allow, before focus is touched.
+	const plausible = deepElements(document).filter((el) => {
+		if (!el.matches(selector)) return false;
+		if (el.disabled) return false;
+		if (el.getAttribute("tabindex") === "-1") return false;
+		if (!visible(el)) return false;
+		return !inert(el);
+	});
+
+	const styleOf = (el) => {
+		const c = getComputedStyle(el);
+		return {
+			outlineStyle: c.outlineStyle, outlineWidth: c.outlineWidth,
+			outlineColor: c.outlineColor, boxShadow: c.boxShadow,
+			backgroundColor: c.backgroundColor, borderColor: c.borderColor,
+			color: c.color,
+		};
+	};
+${NAMING}
+	const inModal = (el) => el.closest(modalSelector) !== null;
+
+	// Resting styles are read now, while focus is still wherever the
+	// page left it, and BEFORE anything below moves focus. Reading
+	// them afterwards records the probe's own focus ring as the
+	// element's resting state, and the element then appears to gain
+	// nothing when focused: the walk reported the last control in
+	// the document as having no focus indicator, on a page where it
+	// has a perfectly good one. That is a false accusation of the
+	// exact defect this check exists to find, so the ordering here
+	// is load-bearing rather than incidental.
+	const resting = new Map(plausible.map((el) => [el, styleOf(el)]));
+
+	// Now the authoritative pass. Style rules only approximate the
+	// focus order: inertness applied by an open modal is written
+	// nowhere in markup, and only an attempt settles it.
+	const restoreFocusTo = document.activeElement;
+	const focusable = plausible.filter(canHoldFocus);
+	try {
+		// blur first, so a body that refuses focus still ends up
+		// without it rather than leaving the last probe's element
+		// focused.
+		if (document.activeElement && document.activeElement.blur) {
+			document.activeElement.blur();
+		}
+		if (
+			restoreFocusTo &&
+			restoreFocusTo !== document.body &&
+			typeof restoreFocusTo.focus === "function"
+		) {
+			restoreFocusTo.focus({ preventScroll: true });
+		}
+	} catch (error) {
+		// Whatever held focus has gone or refuses it; the walk sets
+		// focus from the top anyway, so this is not worth failing on.
+	}
+
+	window.__walkCandidates = focusable;
+
+	const candidates = focusable.map((el, index) => {
+		const tabindex = el.getAttribute("tabindex");
+		return {
+			index, tag: el.tagName, name: nameOf(el),
+			...(el.id ? { id: el.id } : {}),
+			...(el.getAttribute("role") ? { role: el.getAttribute("role") } : {}),
+			...(tabindex === null ? {} : { tabindex: Number(tabindex) }),
+			...(inModal(el) ? { inModal: true } : {}),
+			resting: resting.get(el) || styleOf(el),
+		};
+	});
+
+	// Anything that behaves like a control without being one. An
+	// interactive role is a promise to the reader; not being
+	// focusable breaks it.
+	//
+	// The handler test only sees an inline onclick. A framework
+	// that delegates from the root, which is every React, Vue and
+	// Svelte page, registers nothing this can read, and there is
+	// no cheap document-wide way to ask. So the reason string says
+	// what was actually checked rather than implying more, and the
+	// verdict reports the limit instead of letting silence read as
+	// coverage.
+	const interactiveRoles = new Set([
+		"button", "link", "checkbox", "radio", "switch", "tab",
+		"menuitem", "option", "slider", "textbox",
+	]);
+	// Structure, not controls. A handler on one of these is
+	// delegation or an outside-click listener rather than a promise
+	// that it can be operated.
+	const CONTAINER_TAGS = new Set([
+		"NAV", "HEADER", "FOOTER", "SECTION", "ARTICLE", "ASIDE",
+		"FORM", "UL", "OL", "TABLE", "TBODY", "TR", "DIALOG",
+	]);
+	// Where a framework hangs its delegated click handler. A root
+	// carrying one is not a control that forgot to be focusable, it
+	// is how React, Vue and Svelte deliver every event they have, so
+	// flagging it says nothing except that the page uses a
+	// framework. It read especially badly: the finding named the
+	// element by its text, so the whole header bled into the label,
+	// and on a real app this single false positive was the only
+	// thing failing the keyboard check.
+	const DELEGATES = new Set(["HTML", "BODY", "MAIN", "#document"]);
+
+	const reachable = new Set(focusable);
+	const unreachable = [];
+	for (const el of deepElements(document)) {
+		if (reachable.has(el)) continue;
+		if (DELEGATES.has(el.tagName)) continue;
+		const role = el.getAttribute("role");
+		const hasRole = role && interactiveRoles.has(role);
+		const hasHandler = typeof el.onclick === "function";
+		if (!hasRole && !hasHandler) continue;
+		// A landmark or a section is a container, not a control, even
+		// when something has attached a handler to it.
+		if (hasHandler && !hasRole && CONTAINER_TAGS.has(el.tagName)) continue;
+		if (!visible(el)) continue;
+		// An inert control is not being offered to anybody yet: the
+		// closed search dialog's inputs are inert, look perfectly
+		// visible, and tab is right not to reach them. Complaining
+		// here would blame a page for a dialog that is shut.
+		if (inert(el)) continue;
+		unreachable.push({
+			tag: el.tagName, name: nameOf(el), selector: deepSelectorFor(el),
+			...(role ? { role } : {}),
+			because: hasRole
+				? "carries role " + role + " but nothing can focus it"
+				: "has an inline click handler but nothing can focus it",
+		});
+	}
+
+	return { candidates, unreachable };
+})()`;
+/**
+ * Read where focus is now.
+ *
+ * The index is looked up against the same array the collection
+ * pass stored, so identity is the element itself rather than a
+ * selector that might match twice.
+ */
+export const WALK_READ = `(() => {
+${NAMING}
+	// document.activeElement stops at a shadow host: focus inside a
+	// component reports as the custom element, not the control. So
+	// the walk collected four candidates in a design system and
+	// then matched none of them, reporting zero stops. Descend to
+	// the element that really has focus.
+	let el = document.activeElement;
+	for (let hops = 0; hops < 10; hops++) {
+		const inner = el && el.shadowRoot && el.shadowRoot.activeElement;
+		if (!inner) break;
+		el = inner;
+	}
+	const list = window.__walkCandidates || [];
+	const modalSelector = ${JSON.stringify(MODAL_SELECTOR)};
+	if (!el || el === document.body || el === document.documentElement) {
+		return { index: -1, tag: el ? el.tagName : "NONE", name: "",
+			inViewport: false, focused: null };
+	}
+	const visibleNow = (node) =>
+		typeof node.checkVisibility === "function"
+			? node.checkVisibility({
+					visibilityProperty: true,
+					contentVisibilityAuto: true,
+				})
+			: node.getClientRects().length > 0;
+	const c = getComputedStyle(el);
+	const box = el.getBoundingClientRect();
+	return {
+		index: list.indexOf(el),
+		tag: el.tagName,
+		...(el.id ? { id: el.id } : {}),
+		name: nameOf(el),
+		// Where it is, and whether the browser paints it: two
+		// questions, asked separately. Requiring the element's own
+		// box to have width and height conflated them, and an anchor
+		// whose only child is floated measures 35 by 0 while the text
+		// inside it is plainly on the page. Twenty-seven of those on
+		// one article were each reported as focus landing off screen.
+		// The census already trusts checkVisibility for exactly this
+		// question; the stop reader was the one place that did not.
+		inViewport: box.bottom >= 0 && box.right >= 0 &&
+			box.top <= innerHeight && box.left <= innerWidth &&
+			visibleNow(el),
+		// Kept so tab order can be compared against the order things
+		// are read in, which document order cannot answer.
+		rect: { x: box.left, y: box.top, width: box.width,
+			height: box.height },
+		...(el.closest(modalSelector) !== null ? { inModal: true } : {}),
+		focused: {
+			outlineStyle: c.outlineStyle, outlineWidth: c.outlineWidth,
+			outlineColor: c.outlineColor, boxShadow: c.boxShadow,
+			backgroundColor: c.backgroundColor, borderColor: c.borderColor,
+			color: c.color,
+		},
+	};
+})()`;
+/**
+ * Remember where focus and the viewport were before the walk.
+ *
+ * The walk is one of the two reads that deliberately change the
+ * page, so it owes the caller the page it was handed back. Tab
+ * scrolls each stop into view, and the health digest runs the
+ * keyboard check before the visual and design ones, so a walk
+ * that leaves the page scrolled moves the ground under every
+ * measurement that follows it in the same run. Performance now
+ * runs ahead of the walk rather than behind it, for a related
+ * reason: the walk's own work was being measured as the page's.
+ *
+ * Paired with WALK_RESTORE below, which puts both back.
+ */
+export const WALK_REMEMBER = `(() => {
+	window.__walkOrigin = {
+		el: document.activeElement,
+		x: window.scrollX,
+		y: window.scrollY,
+	};
+	return true;
+})()`;
+/** Put focus and the scroll position back where the walk found them. */
+export const WALK_RESTORE = `(() => {
+	const origin = window.__walkOrigin;
+	if (document.activeElement && document.activeElement.blur) {
+		document.activeElement.blur();
+	}
+	if (origin) {
+		const el = origin.el;
+		// Refocusing only makes sense if it is still in the document
+		// and could hold focus in the first place; body cannot.
+		if (el && el.isConnected && typeof el.focus === "function" &&
+			el !== document.body && el !== document.documentElement) {
+			try { el.focus({ preventScroll: true }); } catch { /* gone */ }
+		}
+		window.scrollTo(origin.x, origin.y);
+	}
+	window.__walkOrigin = undefined;
+	window.__walkCandidates = undefined;
+	return true;
+})()`;

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

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+/** One check axe ran against one element. */
+export interface RawAxeNode {
+    readonly html?: string;
+    readonly target?: readonly (string | readonly string[])[];
+    readonly impact?: string | null;
+    readonly failureSummary?: string;
+    readonly any?: readonly {
+        readonly message?: string;
+    }[];
+    readonly all?: readonly {
+        readonly message?: string;
+    }[];
+    readonly none?: readonly {
+        readonly message?: string;
+    }[];
+}
+/** One rule axe reported on. */
+export interface RawAxeResult {
+    readonly id: string;
+    readonly impact?: string | null;
+    readonly tags?: readonly string[];
+    readonly description?: string;
+    readonly help?: string;
+    readonly helpUrl?: string;
+    readonly nodes?: readonly RawAxeNode[];
+}
+/** What axe.run resolves to. */
+export interface RawAxeRun {
+    readonly violations?: readonly RawAxeResult[];
+    readonly incomplete?: readonly RawAxeResult[];
+    readonly passes?: readonly RawAxeResult[];
+    readonly inapplicable?: readonly RawAxeResult[];
+}
+/** How badly a finding bites, in axe's vocabulary. */
+export type Impact = "critical" | "serious" | "moderate" | "minor";
+/** Whether a finding is a standard failing or an opinion. */
+export type Authority = "wcag" | "best-practice";
+/**
+ * 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 declare const EXPERIMENTAL_WCAG_RULES: readonly string[];
+/**
+ * Which conformance level an audit is being held to.
+ *
+ * The levels nest: everything A demands, AA demands too, and AAA
+ * demands all of it. So a bar is a ceiling on what gets asked,
+ * not a slice.
+ */
+export type ConformanceBar = "A" | "AA" | "AAA";
+/**
+ * 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 declare const ENHANCED_WCAG_RULES: readonly string[];
+/**
+ * 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 declare function withinBar(levels: readonly string[], bar: ConformanceBar): boolean;
+/** The strictest level any of these findings failed. */
+export declare function hardestLevel(findings: readonly {
+    readonly levels: readonly string[];
+}[]): ConformanceBar | undefined;
+/** Whether axe decided, or declined to. */
+export type FindingKind = "violation" | "needs-review";
+/** One element that failed a rule. */
+export interface FindingNode {
+    /** A CSS selector that reaches the element. */
+    readonly selector: string;
+    /** The element's own markup, clipped. */
+    readonly html: string;
+    /** What specifically was wrong with this one. */
+    readonly messages: readonly string[];
+}
+/** One accessibility finding, ready to report. */
+export interface A11yFinding {
+    readonly rule: string;
+    readonly kind: FindingKind;
+    readonly impact: Impact;
+    readonly authority: Authority;
+    /** WCAG criteria this rule maps to, e.g. 1.4.3. */
+    readonly criteria: readonly string[];
+    /** The conformance levels involved, e.g. AA. */
+    readonly levels: readonly string[];
+    readonly help: string;
+    readonly helpUrl?: string;
+    readonly nodes: readonly FindingNode[];
+}
+/** How much markup to keep per node. */
+export declare const MAX_NODE_HTML = 160;
+/**
+ * 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 declare function criteriaOf(tags: readonly string[]): readonly string[];
+/** Read the conformance levels a rule belongs to. */
+export declare function levelsOf(tags: readonly string[]): readonly string[];
+/**
+ * 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 declare function authorityOf(tags: readonly string[]): Authority;
+/**
+ * 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 declare function enabledRules(bar?: ConformanceBar): Record<string, {
+    enabled: true;
+}>;
+/**
+ * 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 declare function readResult(result: RawAxeResult, kind: FindingKind): A11yFinding;
+/**
+ * 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 declare function readAxeRun(run: RawAxeRun): readonly A11yFinding[];
+/** Worst first, and what is known broken before what might be. */
+export declare function orderFindings(findings: readonly A11yFinding[]): readonly A11yFinding[];
+/**
+ * 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 declare function mergeFindings(primary: readonly A11yFinding[], secondary: readonly A11yFinding[], supersededBy?: Readonly<Record<string, string>>): readonly A11yFinding[];
+/** A count of findings and elements, for a headline. */
+export interface AxeTally {
+    readonly violations: number;
+    readonly needsReview: number;
+    /** Elements that failed a rule. Excludes the undecided ones. */
+    readonly elements: number;
+    /** Elements axe declined to judge. */
+    readonly reviewElements: number;
+    readonly byImpact: Readonly<Record<Impact, number>>;
+    readonly wcag: number;
+    readonly bestPractice: number;
+}
+/** Count what was found. */
+export declare function tallyFindings(findings: readonly A11yFinding[]): AxeTally;