eaa-kit 0.2.1 → 0.4.0

package/dist/coverage-B4IBKMO8.js

@@ -0,0 +1,521 @@
+import { n as ENGINE_BLIND_RULES, t as DEFAULT_TAGS, u as successCriteria } from "./result-DoamKFsp.js";
+import axe from "axe-core";
+//#region src/audit/manual.ts
+/**
+* What a person has to check, and where to read about it.
+*
+* Automated testing finds a minority of accessibility barriers. This tool says
+* so everywhere, and saying so is not much use on its own: a reader told that
+* six rules "could not be evaluated" is left knowing there is a gap and not
+* what to do about it.
+*
+* So each rule the browserless engine cannot decide carries the check somebody
+* would do by hand, and each success criterion carries a link to what it
+* actually requires. The point is to turn the honest disclaimer into the part
+* of the report with the most work in it.
+*/
+/**
+* WCAG 2.2 Understanding pages, by success criterion.
+*
+* The Understanding document rather than the criterion text: the text says what
+* conformance is, and the Understanding page says what it is for and how to
+* meet it, which is what somebody reading a report needs.
+*
+* Level A and AA only, since that is what this tool audits against.
+*/
+const UNDERSTANDING = {
+	"1.1.1": "non-text-content",
+	"1.2.1": "audio-only-and-video-only-prerecorded",
+	"1.2.2": "captions-prerecorded",
+	"1.2.3": "audio-description-or-media-alternative-prerecorded",
+	"1.2.4": "captions-live",
+	"1.2.5": "audio-description-prerecorded",
+	"1.3.1": "info-and-relationships",
+	"1.3.2": "meaningful-sequence",
+	"1.3.3": "sensory-characteristics",
+	"1.3.4": "orientation",
+	"1.3.5": "identify-input-purpose",
+	"1.4.1": "use-of-color",
+	"1.4.2": "audio-control",
+	"1.4.3": "contrast-minimum",
+	"1.4.4": "resize-text",
+	"1.4.5": "images-of-text",
+	"1.4.10": "reflow",
+	"1.4.11": "non-text-contrast",
+	"1.4.12": "text-spacing",
+	"1.4.13": "content-on-hover-or-focus",
+	"2.1.1": "keyboard",
+	"2.1.2": "no-keyboard-trap",
+	"2.1.4": "character-key-shortcuts",
+	"2.2.1": "timing-adjustable",
+	"2.2.2": "pause-stop-hide",
+	"2.3.1": "three-flashes-or-below-threshold",
+	"2.4.1": "bypass-blocks",
+	"2.4.2": "page-titled",
+	"2.4.3": "focus-order",
+	"2.4.4": "link-purpose-in-context",
+	"2.4.5": "multiple-ways",
+	"2.4.6": "headings-and-labels",
+	"2.4.7": "focus-visible",
+	"2.4.11": "focus-not-obscured-minimum",
+	"2.5.1": "pointer-gestures",
+	"2.5.2": "pointer-cancellation",
+	"2.5.3": "label-in-name",
+	"2.5.4": "motion-actuation",
+	"2.5.7": "dragging-movements",
+	"2.5.8": "target-size-minimum",
+	"3.1.1": "language-of-page",
+	"3.1.2": "language-of-parts",
+	"3.2.1": "on-focus",
+	"3.2.2": "on-input",
+	"3.2.3": "consistent-navigation",
+	"3.2.4": "consistent-identification",
+	"3.2.6": "consistent-help",
+	"3.3.1": "error-identification",
+	"3.3.2": "labels-or-instructions",
+	"3.3.3": "error-suggestion",
+	"3.3.4": "error-prevention-legal-financial-data",
+	"3.3.7": "redundant-entry",
+	"3.3.8": "accessible-authentication-minimum",
+	"4.1.2": "name-role-value",
+	"4.1.3": "status-messages"
+};
+/** Where to read what a success criterion requires, or undefined if unknown. */
+function understandingUrl(criterion) {
+	const slug = UNDERSTANDING[criterion];
+	return slug === void 0 ? void 0 : `https://www.w3.org/WAI/WCAG22/Understanding/${slug}.html`;
+}
+/**
+* The check a person does for a rule this engine could not decide.
+*
+* Written as an action rather than a restatement of the criterion. "Ensure
+* sufficient contrast" tells somebody nothing they did not already know; the
+* useful sentence names what to open and what to look at.
+*/
+const MANUAL_CHECKS = {
+	"color-contrast": {
+		check: "Open the page and check text against its background with a contrast checker. Body text needs 4.5:1, and large or bold text 3:1. Check the states too — hover, focus, visited, disabled and placeholder text are the ones usually missed.",
+		browserAnswers: true
+	},
+	"color-contrast-enhanced": {
+		check: "Only needed if you are claiming AAA. Body text needs 7:1 and large text 4.5:1.",
+		browserAnswers: true
+	},
+	"target-size": {
+		check: "Measure the clickable area of buttons, icon links and form controls: 24×24 CSS pixels at minimum, unless they are inline in a sentence or have that much clear space around them. Icon-only controls in a header or a media player are where this usually fails.",
+		browserAnswers: true
+	},
+	"scrollable-region-focusable": {
+		check: "Find anything that scrolls inside the page — a code block, a wide table, a long list — and try reaching it with the Tab key alone. If it cannot take focus, a keyboard user cannot scroll it.",
+		browserAnswers: true
+	},
+	"link-in-text-block": {
+		check: "Look at links inside paragraphs. If the only thing distinguishing them from the surrounding text is colour, they need an underline or a 3:1 contrast difference against that text as well.",
+		browserAnswers: true
+	},
+	"no-autoplay-audio": {
+		check: "Load the page and listen. Anything that plays for more than three seconds on its own needs a pause or stop control, or a volume control independent of the system volume.",
+		browserAnswers: false
+	},
+	"avoid-inline-spacing": {
+		check: "Override line height to 1.5×, paragraph spacing to 2×, letter spacing to 0.12× and word spacing to 0.16× the font size, then check nothing is clipped or overlapping. Inline styles that set spacing with !important are what break this.",
+		browserAnswers: true
+	},
+	"p-as-heading": {
+		check: "Look for paragraphs styled to look like headings. A screen reader reads them as body text, so they are invisible to anyone navigating by heading.",
+		browserAnswers: false
+	},
+	"css-orientation-lock": {
+		check: "Rotate a phone or tablet. The content should work in both orientations unless one is essential, which is rare outside games and instruments.",
+		browserAnswers: false
+	}
+};
+/** The check for a rule, if there is one written for it. */
+function manualCheckFor(ruleId) {
+	return MANUAL_CHECKS[ruleId];
+}
+//#endregion
+//#region src/audit/coverage.ts
+/**
+* WCAG 2.2 at Levels A and AA, which is what this tool audits against.
+*
+* 4.1.1 Parsing is deliberately absent: it was removed in WCAG 2.2 and counting
+* it would inflate the denominator with a criterion nobody has to meet.
+*/
+const WCAG22_AA_CRITERIA = [
+	{
+		number: "1.1.1",
+		title: "Non-text Content",
+		level: "A"
+	},
+	{
+		number: "1.2.1",
+		title: "Audio-only and Video-only (Prerecorded)",
+		level: "A"
+	},
+	{
+		number: "1.2.2",
+		title: "Captions (Prerecorded)",
+		level: "A"
+	},
+	{
+		number: "1.2.3",
+		title: "Audio Description or Media Alternative (Prerecorded)",
+		level: "A"
+	},
+	{
+		number: "1.2.4",
+		title: "Captions (Live)",
+		level: "AA"
+	},
+	{
+		number: "1.2.5",
+		title: "Audio Description (Prerecorded)",
+		level: "AA"
+	},
+	{
+		number: "1.3.1",
+		title: "Info and Relationships",
+		level: "A"
+	},
+	{
+		number: "1.3.2",
+		title: "Meaningful Sequence",
+		level: "A"
+	},
+	{
+		number: "1.3.3",
+		title: "Sensory Characteristics",
+		level: "A"
+	},
+	{
+		number: "1.3.4",
+		title: "Orientation",
+		level: "AA"
+	},
+	{
+		number: "1.3.5",
+		title: "Identify Input Purpose",
+		level: "AA"
+	},
+	{
+		number: "1.4.1",
+		title: "Use of Color",
+		level: "A"
+	},
+	{
+		number: "1.4.2",
+		title: "Audio Control",
+		level: "A"
+	},
+	{
+		number: "1.4.3",
+		title: "Contrast (Minimum)",
+		level: "AA"
+	},
+	{
+		number: "1.4.4",
+		title: "Resize Text",
+		level: "AA"
+	},
+	{
+		number: "1.4.5",
+		title: "Images of Text",
+		level: "AA"
+	},
+	{
+		number: "1.4.10",
+		title: "Reflow",
+		level: "AA"
+	},
+	{
+		number: "1.4.11",
+		title: "Non-text Contrast",
+		level: "AA"
+	},
+	{
+		number: "1.4.12",
+		title: "Text Spacing",
+		level: "AA"
+	},
+	{
+		number: "1.4.13",
+		title: "Content on Hover or Focus",
+		level: "AA"
+	},
+	{
+		number: "2.1.1",
+		title: "Keyboard",
+		level: "A"
+	},
+	{
+		number: "2.1.2",
+		title: "No Keyboard Trap",
+		level: "A"
+	},
+	{
+		number: "2.1.4",
+		title: "Character Key Shortcuts",
+		level: "A"
+	},
+	{
+		number: "2.2.1",
+		title: "Timing Adjustable",
+		level: "A"
+	},
+	{
+		number: "2.2.2",
+		title: "Pause, Stop, Hide",
+		level: "A"
+	},
+	{
+		number: "2.3.1",
+		title: "Three Flashes or Below Threshold",
+		level: "A"
+	},
+	{
+		number: "2.4.1",
+		title: "Bypass Blocks",
+		level: "A"
+	},
+	{
+		number: "2.4.2",
+		title: "Page Titled",
+		level: "A"
+	},
+	{
+		number: "2.4.3",
+		title: "Focus Order",
+		level: "A"
+	},
+	{
+		number: "2.4.4",
+		title: "Link Purpose (In Context)",
+		level: "A"
+	},
+	{
+		number: "2.4.5",
+		title: "Multiple Ways",
+		level: "AA"
+	},
+	{
+		number: "2.4.6",
+		title: "Headings and Labels",
+		level: "AA"
+	},
+	{
+		number: "2.4.7",
+		title: "Focus Visible",
+		level: "AA"
+	},
+	{
+		number: "2.4.11",
+		title: "Focus Not Obscured (Minimum)",
+		level: "AA"
+	},
+	{
+		number: "2.5.1",
+		title: "Pointer Gestures",
+		level: "A"
+	},
+	{
+		number: "2.5.2",
+		title: "Pointer Cancellation",
+		level: "A"
+	},
+	{
+		number: "2.5.3",
+		title: "Label in Name",
+		level: "A"
+	},
+	{
+		number: "2.5.4",
+		title: "Motion Actuation",
+		level: "A"
+	},
+	{
+		number: "2.5.7",
+		title: "Dragging Movements",
+		level: "AA"
+	},
+	{
+		number: "2.5.8",
+		title: "Target Size (Minimum)",
+		level: "AA"
+	},
+	{
+		number: "3.1.1",
+		title: "Language of Page",
+		level: "A"
+	},
+	{
+		number: "3.1.2",
+		title: "Language of Parts",
+		level: "AA"
+	},
+	{
+		number: "3.2.1",
+		title: "On Focus",
+		level: "A"
+	},
+	{
+		number: "3.2.2",
+		title: "On Input",
+		level: "A"
+	},
+	{
+		number: "3.2.3",
+		title: "Consistent Navigation",
+		level: "AA"
+	},
+	{
+		number: "3.2.4",
+		title: "Consistent Identification",
+		level: "AA"
+	},
+	{
+		number: "3.2.6",
+		title: "Consistent Help",
+		level: "A"
+	},
+	{
+		number: "3.3.1",
+		title: "Error Identification",
+		level: "A"
+	},
+	{
+		number: "3.3.2",
+		title: "Labels or Instructions",
+		level: "A"
+	},
+	{
+		number: "3.3.3",
+		title: "Error Suggestion",
+		level: "AA"
+	},
+	{
+		number: "3.3.4",
+		title: "Error Prevention (Legal, Financial, Data)",
+		level: "AA"
+	},
+	{
+		number: "3.3.7",
+		title: "Redundant Entry",
+		level: "A"
+	},
+	{
+		number: "3.3.8",
+		title: "Accessible Authentication (Minimum)",
+		level: "AA"
+	},
+	{
+		number: "4.1.2",
+		title: "Name, Role, Value",
+		level: "A"
+	},
+	{
+		number: "4.1.3",
+		title: "Status Messages",
+		level: "AA"
+	}
+];
+/**
+* Rules axe-core would run under these tags, mapped to the criteria they cover.
+*
+* Experimental rules are excluded, matching `blindRulesInScope`: axe-core leaves
+* them off by default, so counting them as coverage would promise checks that
+* never run.
+*/
+function rulesByCriterion(tags) {
+	const byCriterion = /* @__PURE__ */ new Map();
+	for (const rule of axe.getRules([...tags])) {
+		if (rule.tags.includes("experimental")) continue;
+		for (const criterion of successCriteria(rule.tags)) {
+			const rules = byCriterion.get(criterion);
+			if (rules) rules.push(rule.ruleId);
+			else byCriterion.set(criterion, [rule.ruleId]);
+		}
+	}
+	for (const rules of byCriterion.values()) rules.sort();
+	return byCriterion;
+}
+/** Rule ids this run reached a pass or a violation on, across every page. */
+function decidedRules(audits) {
+	const decided = /* @__PURE__ */ new Set();
+	for (const audit of audits) {
+		for (const finding of audit.violations) decided.add(finding.ruleId);
+		for (const finding of audit.accepted ?? []) decided.add(finding.ruleId);
+		for (const outcome of audit.passes) decided.add(outcome.ruleId);
+	}
+	return decided;
+}
+/** Rule ids this run reached no verdict on because the engine cannot see them. */
+function blindedRules(audits) {
+	const blind = /* @__PURE__ */ new Set();
+	for (const audit of audits) for (const finding of audit.incomplete) if (finding.reason === "engine-limitation") blind.add(finding.ruleId);
+	return blind;
+}
+/**
+* What this run reached, criterion by criterion.
+*
+* `audits` decides `evaluated` rather than the engine's capabilities alone: a
+* rule that could have run and never matched anything has not established that
+* the criterion is met on this site, and saying otherwise would be a coverage
+* claim resting on an empty page.
+*/
+function buildCoverage(audits, tags = DEFAULT_TAGS) {
+	const byCriterion = rulesByCriterion(tags);
+	const decided = decidedRules(audits);
+	const blinded = blindedRules(audits);
+	const criteria = WCAG22_AA_CRITERIA.map((criterion) => {
+		const rules = byCriterion.get(criterion.number) ?? [];
+		if (rules.length === 0) return {
+			...criterion,
+			status: "no-automated-rule",
+			rules,
+			browserWouldAnswer: false
+		};
+		if (rules.some((rule) => decided.has(rule))) return {
+			...criterion,
+			status: "evaluated",
+			rules,
+			browserWouldAnswer: false
+		};
+		const engineBlind = rules.filter((rule) => blinded.has(rule) || ENGINE_BLIND_RULES[rule] !== void 0);
+		if (engineBlind.length > 0) return {
+			...criterion,
+			status: "not-evaluated",
+			rules,
+			browserWouldAnswer: engineBlind.every((rule) => manualCheckFor(rule)?.browserAnswers === true)
+		};
+		return {
+			...criterion,
+			status: "nothing-to-check",
+			rules,
+			browserWouldAnswer: false
+		};
+	});
+	const count = (status) => criteria.filter((criterion) => criterion.status === status).length;
+	return {
+		criteria,
+		evaluated: count("evaluated"),
+		notEvaluated: count("not-evaluated"),
+		nothingToCheck: count("nothing-to-check"),
+		noAutomatedRule: count("no-automated-rule"),
+		browserWouldAnswer: criteria.filter((criterion) => criterion.browserWouldAnswer).length,
+		total: WCAG22_AA_CRITERIA.length
+	};
+}
+/**
+* The sentence a reader needs before drawing anything from a clean report.
+*
+* Deliberately leads with what was not checked. A report that opened with "23
+* criteria evaluated" would read as a score, which is precisely what this
+* refuses to be.
+*/
+function coverageSummary(coverage) {
+	const unautomatable = coverage.noAutomatedRule;
+	return `Of the ${coverage.total} WCAG 2.2 A and AA success criteria, ${unautomatable} cannot be checked by any automated engine and need a person. This run reached a verdict on ${coverage.evaluated}.`;
+}
+//#endregion
+export { understandingUrl as i, coverageSummary as n, manualCheckFor as r, buildCoverage as t };

package/dist/{crawl-CtJbMNNb.js → crawl-BiI1Lau_.js}

@@ -1,3 +1,4 @@
+import { i as stripBom } from "./collect-CFM8gEVv.js";
 /** Requests in flight at once. Politeness, not throughput. */
 const REQUEST_CONCURRENCY = 4;
 var CrawlError = class extends Error {
@@ -142,31 +143,18 @@ function disallowedPaths(robots) {
 	return paths;
 }
 /**
-* Paths this crawler must not visit, from the site's own robots.txt.
+* One of the two files a site publishes about itself, or undefined.
 *
 * Read directly rather than through fetchPage, which correctly refuses anything
-* that is not a page. A site with no robots.txt disallows nothing.
+* that is not a page. A site that does not publish one is the ordinary case,
+* not a failure, so it comes back empty either way.
 */
-async function blockedPaths(entry, impl) {
+async function fetchSiteFile(entry, impl, name) {
 	try {
-		const response = await impl(new URL("/robots.txt", entry).href, { redirect: "follow" });
-		return response.ok ? disallowedPaths(await response.text()) : [];
+		const response = await impl(new URL(name, entry).href, { redirect: "follow" });
+		return response.ok ? await response.text() : void 0;
 	} catch {
-		return [];
-	}
-}
-/**
-* Page URLs the site lists for itself.
-*
-* Worth one request: a sitemap finds pages nothing links to, which link
-* following alone never reaches.
-*/
-async function sitemapUrls(entry, impl) {
-	try {
-		const response = await impl(new URL("/sitemap.xml", entry).href, { redirect: "follow" });
-		return response.ok ? urlsFromSitemap(await response.text(), entry) : [];
-	} catch {
-		return [];
+		return;
 	}
 }
 /**
@@ -182,7 +170,8 @@ async function crawlSite(entry, options = {}) {
 	const maxDepth = options.maxDepth ?? 3;
 	const timeoutMs = options.timeoutMs ?? 15e3;
 	const failures = [];
-	const blocked = options.ignoreRobots ? [] : await blockedPaths(entry, impl);
+	const robots = options.ignoreRobots ? void 0 : await fetchSiteFile(entry, impl, "/robots.txt");
+	const blocked = robots === void 0 ? [] : disallowedPaths(robots);
 	const allowed = (url) => !blocked.some((path) => url.pathname.startsWith(path));
 	let discovery = "links";
 	const queue = [];
@@ -195,7 +184,8 @@ async function crawlSite(entry, options = {}) {
 			depth
 		});
 	};
-	const listed = await sitemapUrls(entry, impl);
+	const sitemap = await fetchSiteFile(entry, impl, options.sitemap ?? "/sitemap.xml");
+	const listed = sitemap === void 0 ? [] : urlsFromSitemap(sitemap, entry);
 	if (listed.length > 0) {
 		discovery = "sitemap";
 		for (const url of listed) enqueue(url, 0);
@@ -220,7 +210,7 @@ async function crawlSite(entry, options = {}) {
 			pages.push({
 				absolutePath: url.href,
 				relativePath: pageIdentity(url),
-				html: html.charCodeAt(0) === 65279 ? html.slice(1) : html
+				html: stripBom(html)
 			});
 			options.onProgress?.(pages.length, queue.length);
 			if (item.depth < maxDepth) for (const link of linksFrom(html, url)) enqueue(link, item.depth + 1);

package/dist/eleventy/index.d.ts

@@ -0,0 +1,28 @@
+import { n as IntegrationOptions, t as BuildAuditError } from "../run-BMASMmwO.js";
+//#region src/eleventy/index.d.ts
+/** What `eleventy.after` is given. Only two of its fields are read. */
+interface EleventyAfterEvent {
+  dir: {
+    input: string;
+    output: string;
+  };
+  /** `build`, `watch` or `serve`. Only a one-shot build is audited. */
+  runMode?: string;
+  /** `fs`, `json`, `ndjson` or `text`. Only `fs` writes files to audit. */
+  outputMode?: string;
+}
+/** The part of Eleventy's config object this plugin touches. */
+interface EleventyConfigLike {
+  on(event: 'eleventy.after', handler: (event: EleventyAfterEvent) => Promise<void>): void;
+}
+type EaaKitEleventyOptions = IntegrationOptions;
+/**
+ * Usable both as a bare plugin and as a configured one.
+ *
+ * `addPlugin(eaaKit)` and `addPlugin(eaaKit, { failOn: 'moderate' })` are both
+ * how Eleventy plugins are written, and a plugin that only supported the second
+ * would be the one people got wrong.
+ */
+declare function eaaKit(eleventyConfig: EleventyConfigLike, options?: EaaKitEleventyOptions): void;
+//#endregion
+export { BuildAuditError, EaaKitEleventyOptions, EleventyAfterEvent, EleventyConfigLike, eaaKit as default };

package/dist/eleventy/index.js

@@ -0,0 +1,19 @@
+import { n as auditBuild, r as stderrLogger, t as BuildAuditError } from "../run-DB34BSOZ.js";
+import path from "node:path";
+//#region src/eleventy/index.ts
+/**
+* Usable both as a bare plugin and as a configured one.
+*
+* `addPlugin(eaaKit)` and `addPlugin(eaaKit, { failOn: 'moderate' })` are both
+* how Eleventy plugins are written, and a plugin that only supported the second
+* would be the one people got wrong.
+*/
+function eaaKit(eleventyConfig, options = {}) {
+	eleventyConfig.on("eleventy.after", async (event) => {
+		if (event.runMode !== void 0 && event.runMode !== "build") return;
+		if (event.outputMode !== void 0 && event.outputMode !== "fs") return;
+		await auditBuild(path.resolve(event.dir.output), options, stderrLogger());
+	});
+}
+//#endregion
+export { BuildAuditError, eaaKit as default };