eaa-kit 0.1.0

package/dist/jsdom-BEu6Ra_2.js

@@ -0,0 +1,163 @@
+import { i as shapeResults, n as failedPage, r as runOptions, t as DEFAULT_TAGS } from "./result-2aZPfM8w.js";
+import { pathToFileURL } from "node:url";
+import { Script } from "node:vm";
+import axe from "axe-core";
+import { JSDOM, VirtualConsole } from "jsdom";
+//#region src/audit/runners/jsdom.ts
+/**
+* Rules this engine structurally cannot decide.
+*
+* jsdom has no layout: every element reports a 0x0 box, computed style is
+* limited to the inline cascade, and nothing is ever fetched. axe-core does not
+* know that, so it happily returns `pass` for some of these — `target-size`
+* passes on any page because a 0x0 target gets measured against nothing, and
+* `color-contrast` passes on pages whose colours were never computed. Both were
+* observed on real sites. Reporting either as a pass would be a false clean
+* bill of health, so every rule listed here is force-reported as incomplete no
+* matter which bucket axe-core put it in.
+*
+* The browser runner passes an empty map instead: with real layout these rules
+* are exactly the ones it exists to answer.
+*
+* Rules tagged `experimental` are listed for completeness but filtered out at
+* scope time: axe-core does not run them by default, so a browser run would not
+* evaluate them either and telling the user to re-run with --browser would be
+* misleading.
+*/
+const ENGINE_BLIND_RULES = {
+	"color-contrast": {
+		detail: "needs rendered foreground and background colours",
+		applicabilityUnreliable: false
+	},
+	"color-contrast-enhanced": {
+		detail: "needs rendered foreground and background colours",
+		applicabilityUnreliable: false
+	},
+	"target-size": {
+		detail: "needs element geometry; every box is 0x0 without layout",
+		applicabilityUnreliable: false
+	},
+	"scrollable-region-focusable": {
+		detail: "needs computed overflow",
+		applicabilityUnreliable: true
+	},
+	"link-in-text-block": {
+		detail: "needs rendered colours and text decoration",
+		applicabilityUnreliable: true
+	},
+	"no-autoplay-audio": {
+		detail: "needs media duration, and media is never loaded",
+		applicabilityUnreliable: true
+	},
+	"avoid-inline-spacing": {
+		detail: "needs computed spacing after the full cascade",
+		applicabilityUnreliable: false
+	},
+	"p-as-heading": {
+		detail: "needs computed font size and weight",
+		applicabilityUnreliable: false
+	},
+	"css-orientation-lock": {
+		detail: "needs CSS media query evaluation",
+		applicabilityUnreliable: true
+	}
+};
+/** Per-page ceiling; one pathological document must not stall a CI run. */
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Audit collected pages with axe-core inside jsdom.
+*
+* Pages are processed sequentially: jsdom parsing and axe-core are both
+* CPU-bound on the main thread, so concurrency buys nothing here. A page that
+* throws or times out is recorded with an `error` and the run continues.
+*/
+async function runJsdomAudit(pages, options = {}) {
+	const audits = [];
+	for (const page of pages) audits.push(await auditPage(page, options));
+	return audits;
+}
+async function auditPage(page, options = {}) {
+	const tags = options.tags ?? DEFAULT_TAGS;
+	const url = pageUrl(page, options.baseUrl);
+	const startedAt = Date.now();
+	const identity = {
+		relativePath: page.relativePath,
+		absolutePath: page.absolutePath,
+		url,
+		engine: "jsdom"
+	};
+	let dom;
+	try {
+		dom = createDom(page.html, url);
+		injectAxe(dom);
+		const { axe: pageAxe } = dom.window;
+		const results = await withTimeout(pageAxe.run(dom.window.document, runOptions(tags)), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+		return shapeResults(results, {
+			...identity,
+			durationMs: Date.now() - startedAt,
+			blind: blindRulesInScope(tags)
+		});
+	} catch (cause) {
+		return failedPage({
+			...identity,
+			durationMs: Date.now() - startedAt
+		}, cause instanceof Error ? cause.message : String(cause));
+	} finally {
+		dom?.window.close();
+	}
+}
+function createDom(html, url) {
+	const virtualConsole = new VirtualConsole();
+	virtualConsole.on("jsdomError", () => {});
+	return new JSDOM(html, {
+		url,
+		virtualConsole,
+		runScripts: "outside-only",
+		pretendToBeVisual: true
+	});
+}
+/**
+* axe-core is 1.3 MB of source. Compiling it once and re-running the compiled
+* script in each window's context avoids re-parsing it for every page.
+*/
+let axeScript;
+function injectAxe(dom) {
+	axeScript ??= new Script(axe.source, { filename: "axe-core.js" });
+	axeScript.runInContext(dom.getInternalVMContext());
+}
+const blindScopeCache = /* @__PURE__ */ new Map();
+/**
+* Blind rules the requested tag filter would actually have run. Experimental
+* rules are excluded: axe-core leaves them off by default, so a browser run
+* would not have evaluated them either.
+*/
+function blindRulesInScope(tags) {
+	const key = [...tags].sort().join(",");
+	const cached = blindScopeCache.get(key);
+	if (cached) return cached;
+	const inScope = /* @__PURE__ */ new Map();
+	for (const rule of axe.getRules([...tags])) {
+		if (rule.tags.includes("experimental")) continue;
+		const blind = ENGINE_BLIND_RULES[rule.ruleId];
+		if (blind) inScope.set(rule.ruleId, blind);
+	}
+	blindScopeCache.set(key, inScope);
+	return inScope;
+}
+function pageUrl(page, baseUrl) {
+	if (!baseUrl) return pathToFileURL(page.absolutePath).href;
+	return new URL(page.relativePath, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).href;
+}
+async function withTimeout(promise, ms) {
+	promise.catch(() => {});
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`axe-core timed out after ${ms}ms`)), ms);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
+export { runJsdomAudit as i, auditPage as n, blindRulesInScope as r, ENGINE_BLIND_RULES as t };

package/dist/jsdom-C6dIyaxN.js

@@ -0,0 +1,3 @@
+import "./result-2aZPfM8w.js";
+import { i as runJsdomAudit } from "./jsdom-BEu6Ra_2.js";
+export { runJsdomAudit };

package/dist/json-1ESNIiHY.js

@@ -0,0 +1,139 @@
+import { i as isImpactLevel, r as countAtOrAbove } from "./impact-DvgBjupx.js";
+import { t as TOOL_VERSION } from "./version-B3v4rNoG.js";
+import axe from "axe-core";
+/**
+* Build the machine-readable report.
+*
+* This is a published contract, so it deliberately excludes things the internal
+* PageAudit carries: absolute filesystem paths (machine-specific, and they leak
+* into anything committed), per-page timings (non-deterministic, which would
+* make two reports of the same build differ), and raw axe-core tags (they move
+* between axe-core releases, and promising them would tie this schema to
+* theirs). Everything present here is meant to survive.
+*/
+function buildJsonReport(audits, options) {
+	const generatedAt = (options.now ?? /* @__PURE__ */ new Date()).toISOString();
+	return {
+		schemaVersion: 1,
+		tool: {
+			name: "eaa-kit",
+			version: TOOL_VERSION,
+			axeCore: axe.version
+		},
+		generatedAt,
+		engine: audits[0]?.engine ?? "jsdom",
+		target: {
+			directory: options.directory,
+			baseUrl: options.baseUrl ?? null
+		},
+		summary: buildSummary(audits, options.failOn),
+		rules: buildRuleIndex(audits),
+		pages: audits.map(toJsonPage)
+	};
+}
+/** Every rule mentioned by any page, keyed by id and sorted for stable diffs. */
+function buildRuleIndex(audits) {
+	const index = /* @__PURE__ */ new Map();
+	for (const audit of audits) {
+		const outcomes = [
+			...audit.violations,
+			...audit.accepted ?? [],
+			...audit.incomplete,
+			...audit.passes,
+			...audit.inapplicable
+		];
+		for (const outcome of outcomes) {
+			if (index.has(outcome.ruleId)) continue;
+			index.set(outcome.ruleId, {
+				help: outcome.help,
+				helpUrl: outcome.helpUrl,
+				successCriteria: outcome.successCriteria,
+				en301549: outcome.enClauses
+			});
+		}
+	}
+	return Object.fromEntries([...index].sort(([a], [b]) => a.localeCompare(b)));
+}
+/** Serialised form written to stdout or to --output, with a trailing newline. */
+function serialiseJsonReport(report) {
+	return `${JSON.stringify(report, null, 2)}\n`;
+}
+function buildSummary(audits, failOn) {
+	const byImpact = {
+		critical: 0,
+		serious: 0,
+		moderate: 0,
+		minor: 0,
+		unclassified: 0
+	};
+	let violations = 0;
+	let violatingElements = 0;
+	let needsReview = 0;
+	let notEvaluated = 0;
+	let passes = 0;
+	let inapplicable = 0;
+	let accepted = 0;
+	for (const audit of audits) {
+		for (const finding of audit.accepted ?? []) accepted += finding.nodes.length;
+		for (const finding of audit.violations) {
+			violations += 1;
+			violatingElements += finding.nodes.length;
+			const impact = finding.impact;
+			byImpact[impact && isImpactLevel(impact) ? impact : "unclassified"] += 1;
+		}
+		for (const finding of audit.incomplete) if (finding.reason === "engine-limitation") notEvaluated += 1;
+		else needsReview += 1;
+		passes += audit.passes.length;
+		inapplicable += audit.inapplicable.length;
+	}
+	return {
+		pages: audits.length,
+		pagesWithViolations: audits.filter((audit) => audit.violations.length > 0).length,
+		pagesNotAudited: audits.filter((audit) => audit.error).length,
+		violations,
+		violatingElements,
+		byImpact,
+		needsReview,
+		notEvaluated,
+		passes,
+		inapplicable,
+		failOn,
+		failing: countAtOrAbove(audits, failOn),
+		accepted
+	};
+}
+function toJsonPage(audit) {
+	return {
+		path: audit.relativePath,
+		url: audit.url,
+		violations: [...audit.violations].sort(byRuleId).map(toJsonFinding),
+		...audit.accepted ? { accepted: [...audit.accepted].sort(byRuleId).map(toJsonFinding) } : {},
+		incomplete: [...audit.incomplete].sort(byRuleId).map(toJsonIncomplete),
+		passes: [...audit.passes].sort(byRuleId).map((outcome) => outcome.ruleId),
+		inapplicable: [...audit.inapplicable].sort(byRuleId).map((outcome) => outcome.ruleId),
+		error: audit.error ?? null
+	};
+}
+function toJsonFinding(finding) {
+	return {
+		ruleId: finding.ruleId,
+		impact: finding.impact && isImpactLevel(finding.impact) ? finding.impact : null,
+		nodes: finding.nodes.map((node) => ({
+			html: node.html,
+			target: node.target,
+			failureSummary: node.failureSummary ?? null
+		}))
+	};
+}
+function toJsonIncomplete(finding) {
+	return {
+		...toJsonFinding(finding),
+		reason: finding.reason,
+		reasonDetail: finding.reasonDetail
+	};
+}
+function byRuleId(a, b) {
+	return a.ruleId.localeCompare(b.ruleId);
+}
+//#endregion
+export { buildJsonReport, serialiseJsonReport };

package/dist/playwright-BfWuTG_u.js

@@ -0,0 +1,235 @@
+import { i as shapeResults, n as failedPage, r as runOptions, t as DEFAULT_TAGS } from "./result-2aZPfM8w.js";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import axe from "axe-core";
+import { createReadStream } from "node:fs";
+import { createServer } from "node:http";
+//#region src/audit/serve.ts
+/**
+* Content types for what a static build actually contains. Anything else is
+* served as an octet-stream, which is fine: the browser only needs to parse
+* HTML, CSS and fonts for an audit to be meaningful.
+*/
+const CONTENT_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".htm": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".ico": "image/x-icon",
+	".woff": "font/woff",
+	".woff2": "font/woff2",
+	".ttf": "font/ttf",
+	".otf": "font/otf",
+	".txt": "text/plain; charset=utf-8",
+	".xml": "application/xml; charset=utf-8"
+};
+/**
+* Serve a build directory over loopback for the browser runner.
+*
+* A local server rather than file:// URLs, because root-absolute asset paths —
+* `/assets/site.css`, which every static site generator emits — do not resolve
+* under file://. Measured on a page whose stylesheet sets `color: #ccc`: the
+* computed colour is the default black over file:// and the real value over
+* http://. Auditing colour contrast against an unstyled page would be worse
+* than not auditing it at all.
+*
+* Bound to 127.0.0.1 on an ephemeral port, so it is not reachable off the
+* machine and cannot collide with a dev server.
+*/
+async function serveDirectory(root) {
+	const absoluteRoot = path.resolve(root);
+	const server = createServer((request, response) => {
+		handle(absoluteRoot, request.url ?? "/", response).catch(() => {
+			if (!response.headersSent) response.writeHead(500);
+			response.end();
+		});
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", resolve);
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") throw new Error("Static server did not bind to a port");
+	return {
+		origin: `http://127.0.0.1:${address.port}`,
+		close: () => closeServer(server)
+	};
+}
+async function handle(root, requestUrl, response) {
+	const file = resolveFile(root, requestUrl);
+	if (!file) {
+		response.writeHead(404).end();
+		return;
+	}
+	try {
+		const target = (await stat(file)).isDirectory() ? path.join(file, "index.html") : file;
+		if (!await isReadableFile(target)) {
+			response.writeHead(404).end();
+			return;
+		}
+		const type = CONTENT_TYPES[path.extname(target).toLowerCase()] ?? "application/octet-stream";
+		response.writeHead(200, { "content-type": type });
+		createReadStream(target).on("error", () => {
+			if (!response.headersSent) response.writeHead(404);
+			response.end();
+		}).pipe(response);
+	} catch {
+		response.writeHead(404).end();
+	}
+}
+async function isReadableFile(candidate) {
+	try {
+		return (await stat(candidate)).isFile();
+	} catch {
+		return false;
+	}
+}
+/** Resolves a request path inside the root, or nothing if it escapes it. */
+function resolveFile(root, requestUrl) {
+	const { pathname } = new URL(requestUrl, "http://127.0.0.1");
+	let decoded;
+	try {
+		decoded = decodeURIComponent(pathname);
+	} catch {
+		return;
+	}
+	const candidate = path.resolve(root, `.${path.posix.normalize(decoded)}`);
+	const relative = path.relative(root, candidate);
+	if (relative.startsWith("..") || path.isAbsolute(relative)) return void 0;
+	return candidate;
+}
+function closeServer(server) {
+	return new Promise((resolve) => {
+		server.closeAllConnections();
+		server.close(() => resolve());
+	});
+}
+//#endregion
+//#region src/audit/runners/playwright.ts
+/** Per-page ceiling. Real pages fetch real resources, so it is looser. */
+const DEFAULT_TIMEOUT_MS = 6e4;
+var BrowserUnavailableError = class extends Error {
+	name = "BrowserUnavailableError";
+};
+/** Desktop-ish default; large enough that nothing collapses to a mobile layout. */
+const DEFAULT_VIEWPORT = {
+	width: 1280,
+	height: 720
+};
+/**
+* Audit a built site in real Chromium.
+*
+* This is the engine that can answer the rules jsdom is blind to: colour
+* contrast, target size, computed overflow. Nothing is force-reported as
+* unevaluated here, because with layout and CSS there is no reason to.
+*
+* Two differences from the browserless path are deliberate and worth knowing:
+* the page's own JavaScript runs, so client-rendered content is audited as a
+* visitor would see it; and the build is served over loopback rather than
+* opened as a file, so absolute asset paths resolve.
+*/
+async function runBrowserAudit(directory, pages, options = {}) {
+	if (pages.length === 0) return [];
+	const chromium = await loadChromium();
+	const tags = options.tags ?? DEFAULT_TAGS;
+	const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const viewport = options.viewport ?? DEFAULT_VIEWPORT;
+	const server = await serveDirectory(directory);
+	const browser = await chromium.launch({ headless: true });
+	try {
+		const context = await browser.newContext({
+			viewport,
+			bypassCSP: true
+		});
+		const audits = [];
+		for (const page of pages) audits.push(await auditOne(context, server.origin, page, {
+			tags,
+			timeout,
+			...options
+		}));
+		await context.close();
+		return audits;
+	} finally {
+		await browser.close();
+		await server.close();
+	}
+}
+async function auditOne(context, origin, page, options) {
+	const startedAt = Date.now();
+	const identity = {
+		relativePath: page.relativePath,
+		absolutePath: page.absolutePath,
+		url: reportedUrl(page, options.baseUrl),
+		engine: "browser"
+	};
+	const tab = await context.newPage();
+	try {
+		tab.setDefaultTimeout(options.timeout);
+		const target = servedUrl(origin, page.relativePath);
+		const response = await tab.goto(target, {
+			waitUntil: "load",
+			timeout: options.timeout
+		});
+		if (response && response.status() >= 400) throw new Error(`Served ${page.relativePath} with HTTP ${response.status()}`);
+		await tab.addScriptTag({ content: axe.source });
+		const results = await tab.evaluate(([runnerOptions]) => globalThis.axe.run(runnerOptions), [{
+			...runOptions(options.tags),
+			preload: true
+		}]);
+		return shapeResults(results, {
+			...identity,
+			durationMs: Date.now() - startedAt,
+			blind: /* @__PURE__ */ new Map()
+		});
+	} catch (cause) {
+		return failedPage({
+			...identity,
+			durationMs: Date.now() - startedAt
+		}, cause instanceof Error ? cause.message : String(cause));
+	} finally {
+		await tab.close();
+	}
+}
+/**
+* Where the local server will hand this page over.
+*
+* Encoded per segment: a build with `#` or `?` in a filename would otherwise
+* have the browser read the rest of the path as a fragment or a query and audit
+* the wrong page, or none at all. The browserless engine gets this for free
+* from pathToFileURL; this path has to do it by hand.
+*/
+function servedUrl(origin, relativePath) {
+	return `${origin}/${relativePath.split("/").map(encodeURIComponent).join("/")}`;
+}
+function reportedUrl(page, baseUrl) {
+	if (!baseUrl) return pathToFileURL(page.absolutePath).href;
+	return new URL(page.relativePath, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`).href;
+}
+/**
+* Playwright is an optional peer dependency: the browserless path must never
+* pay for a Chromium download. Both failure modes get their own instruction,
+* because "install playwright" and "install the browser binary" are different
+* problems with different fixes.
+*/
+async function loadChromium() {
+	let module;
+	try {
+		module = await import("playwright");
+	} catch {
+		throw new BrowserUnavailableError("Browser mode needs Playwright, which is an optional peer dependency.\n  Install it with:  pnpm add -D playwright\n  Then the browser: npx playwright install chromium");
+	}
+	if (!module.chromium) throw new BrowserUnavailableError("Playwright is installed but exports no chromium launcher");
+	return module.chromium;
+}
+//#endregion
+export { BrowserUnavailableError, runBrowserAudit };