eaa-kit 0.1.0

package/dist/audit-6gbV0Zjd.js

@@ -0,0 +1,582 @@
+import { n as IMPACT_LEVELS, r as countAtOrAbove } from "./impact-DvgBjupx.js";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+import { glob } from "tinyglobby";
+//#region src/audit/collect.ts
+/** Every HTML document a static build is expected to emit. */
+const DEFAULT_INCLUDE = ["**/*.html", "**/*.htm"];
+/** Vendored and tooling directories are never part of the shipped site. */
+const DEFAULT_EXCLUDE = ["**/node_modules/**", "**/.git/**"];
+/** Number of files read in parallel; keeps large builds under the fd limit. */
+const READ_CONCURRENCY = 24;
+/**
+* Thrown when the build directory itself is unusable. A missing or wrong
+* `dist/` is a user mistake worth reporting loudly, unlike a directory that
+* simply holds no HTML.
+*/
+var BuildDirectoryError = class extends Error {
+	dir;
+	name = "BuildDirectoryError";
+	constructor(message, dir) {
+		super(message);
+		this.dir = dir;
+	}
+};
+/**
+* Glob HTML files out of a build directory and read them.
+*
+* Returns pages sorted by relative path so reports and snapshots are stable
+* across platforms. An empty array means "no HTML found" — the caller decides
+* whether that is an error.
+*/
+async function collectPages(dir, options = {}) {
+	const root = path.resolve(dir);
+	await assertDirectory(root, dir);
+	const relativePaths = (await glob(options.include ?? DEFAULT_INCLUDE, {
+		cwd: root,
+		ignore: options.exclude ?? DEFAULT_EXCLUDE,
+		onlyFiles: true,
+		dot: false,
+		absolute: false
+	})).map(toPosix).sort();
+	const pages = [];
+	for (let i = 0; i < relativePaths.length; i += READ_CONCURRENCY) {
+		const batch = relativePaths.slice(i, i + READ_CONCURRENCY);
+		pages.push(...await Promise.all(batch.map((relativePath) => readPage(root, relativePath))));
+	}
+	return pages;
+}
+async function assertDirectory(root, original) {
+	let stats;
+	try {
+		stats = await stat(root);
+	} catch (cause) {
+		if (cause.code === "ENOENT") throw new BuildDirectoryError(`Build directory not found: ${original}`, root);
+		throw new BuildDirectoryError(`Build directory is not readable: ${original} (${cause.message})`, root);
+	}
+	if (!stats.isDirectory()) throw new BuildDirectoryError(`Build path is not a directory: ${original}`, root);
+}
+async function readPage(root, relativePath) {
+	const absolutePath = path.join(root, relativePath);
+	const html = await readFile(absolutePath, "utf8");
+	return {
+		absolutePath,
+		relativePath,
+		html: html.charCodeAt(0) === 65279 ? html.slice(1) : html
+	};
+}
+function toPosix(filePath) {
+	return filePath.split(path.sep).join("/");
+}
+//#endregion
+//#region src/audit/report/console.ts
+const DEFAULT_MAX_NODES = 3;
+const MIN_WIDTH = 40;
+const MAX_WIDTH = 100;
+/**
+* Human-readable audit report.
+*
+* Deliberately not a columnar table: rule ids, help text and selectors are all
+* variable-length, so a real table either wraps into soup or scrolls sideways
+* on a narrow terminal. Everything is left-aligned and indented instead, and
+* every line is assembled from segments trimmed as a group, so the width
+* guarantee holds however long a selector or rule id turns out to be.
+*
+* Returns a string rather than printing, so the format is testable.
+*/
+function formatConsoleReport(audits, options = {}) {
+	const ctx = context(options);
+	const lines = [
+		"",
+		...headerLines(audits, ctx),
+		""
+	];
+	for (const audit of audits) lines.push(...pageSection(audit, ctx));
+	lines.push(...summary(audits, ctx));
+	return lines.join("\n");
+}
+function context(options) {
+	const detected = process.stdout.columns ?? 80;
+	const width = Math.min(Math.max(options.width ?? detected, MIN_WIDTH), MAX_WIDTH);
+	const c = pc.createColors(options.color ?? pc.isColorSupported);
+	const unicode = supportsUnicode();
+	return {
+		width,
+		maxNodes: options.maxNodes ?? DEFAULT_MAX_NODES,
+		failOn: options.failOn ?? "serious",
+		c,
+		symbol: (kind) => {
+			switch (kind) {
+				case "violation": return unicode ? "✗" : "x";
+				case "review": return "?";
+				case "blind": return unicode ? "·" : "-";
+				case "clean": return unicode ? "✓" : "+";
+				case "error": return "!";
+			}
+		}
+	};
+}
+/** cmd.exe and older Windows consoles render these glyphs as mojibake. */
+function supportsUnicode() {
+	if (process.platform !== "win32") return true;
+	return Boolean(process.env["WT_SESSION"] || process.env["TERM_PROGRAM"] || process.env["ConEmuTask"] || process.env["TERM"]);
+}
+/**
+* Joins segments into one line, trimming the group to the terminal width.
+* Colour codes are applied after trimming, so they never count towards it.
+*/
+function render(ctx, segments) {
+	let remaining = ctx.width;
+	const parts = [];
+	for (const segment of segments) {
+		if (remaining <= 0) break;
+		const text = segment.text.length <= remaining ? segment.text : `${segment.text.slice(0, Math.max(remaining - 1, 0))}…`;
+		remaining -= text.length;
+		parts.push(segment.paint ? segment.paint(text) : text);
+	}
+	return parts.join("");
+}
+function headerLines(audits, ctx) {
+	const engineLabel = (audits[0]?.engine ?? "jsdom") === "browser" ? "chromium" : "jsdom (browserless)";
+	const pageCount = `${audits.length} ${plural(audits.length, "page")}`;
+	return [render(ctx, [{
+		text: "eaa-kit audit",
+		paint: ctx.c.bold
+	}, {
+		text: ` ${pageCount} · ${engineLabel}`,
+		paint: ctx.c.dim
+	}]), render(ctx, [{
+		text: "passed = checked and met · not applicable = nothing to check",
+		paint: ctx.c.dim
+	}])];
+}
+function pageSection(audit, ctx) {
+	const lines = [render(ctx, [{
+		text: audit.relativePath,
+		paint: ctx.c.underline
+	}])];
+	if (audit.error) {
+		lines.push(render(ctx, [{
+			text: `  ${ctx.symbol("error")} not audited: `,
+			paint: ctx.c.red
+		}, { text: audit.error }]), "");
+		return lines;
+	}
+	for (const finding of sortByImpact(audit.violations)) lines.push(...violationLines(finding, ctx));
+	for (const finding of audit.incomplete.filter((item) => item.reason === "needs-review")) lines.push(render(ctx, [
+		{
+			text: `  ${ctx.symbol("review")} `,
+			paint: ctx.c.yellow
+		},
+		{
+			text: finding.ruleId,
+			paint: ctx.c.yellow
+		},
+		{
+			text: ` needs manual review${criteria(finding)}`,
+			paint: ctx.c.dim
+		}
+	]));
+	if (audit.violations.length === 0) {
+		const clean = (audit.accepted ?? []).length === 0;
+		lines.push(render(ctx, [{
+			text: `  ${ctx.symbol("clean")} `,
+			paint: clean ? ctx.c.green : ctx.c.dim
+		}, {
+			text: clean ? "no violations" : "no new violations",
+			paint: clean ? ctx.c.green : ctx.c.dim
+		}]));
+	}
+	for (const finding of sortByImpact(audit.accepted ?? [])) {
+		const elements = finding.nodes.length;
+		lines.push(render(ctx, [
+			{
+				text: "  · ",
+				paint: ctx.c.dim
+			},
+			{
+				text: finding.ruleId,
+				paint: ctx.c.dim
+			},
+			{
+				text: ` accepted by the baseline (${elements} ${plural(elements, "element")})`,
+				paint: ctx.c.dim
+			}
+		]));
+	}
+	lines.push(coverageLine(audit, ctx));
+	lines.push("");
+	return lines;
+}
+/**
+* What this page's result actually rests on.
+*
+* The four counts stay separate on purpose. Only `passed` is evidence that a
+* criterion was met here; `not applicable` means the rule found nothing to
+* check, and adding the two together would turn an empty page into a
+* near-perfect score.
+*/
+function coverageLine(audit, ctx) {
+	const blind = audit.incomplete.filter((finding) => finding.reason === "engine-limitation").length;
+	const review = audit.incomplete.length - blind;
+	const parts = [`${audit.passes.length} passed`, `${audit.inapplicable.length} not applicable`];
+	if (review > 0) parts.push(`${review} to review`);
+	if (blind > 0) parts.push(`${blind} not evaluated`);
+	return render(ctx, [{
+		text: `    ${parts.join(" · ")}`,
+		paint: ctx.c.dim
+	}]);
+}
+function violationLines(finding, ctx) {
+	const impact = finding.impact ?? "unknown";
+	const lines = [render(ctx, [
+		{
+			text: `  ${ctx.symbol("violation")} `,
+			paint: ctx.c.red
+		},
+		{
+			text: finding.ruleId,
+			paint: ctx.c.bold
+		},
+		{
+			text: ` ${impact}${criteria(finding)}`,
+			paint: ctx.c.dim
+		}
+	]), render(ctx, [{ text: `      ${finding.help}` }])];
+	for (const node of finding.nodes.slice(0, ctx.maxNodes)) {
+		lines.push(render(ctx, [{
+			text: `      ${node.target.join(" ")}`,
+			paint: ctx.c.cyan
+		}]));
+		lines.push(render(ctx, [{
+			text: `        ${collapse(node.html)}`,
+			paint: ctx.c.dim
+		}]));
+	}
+	const hidden = finding.nodes.length - ctx.maxNodes;
+	if (hidden > 0) lines.push(render(ctx, [{
+		text: `      + ${hidden} more ${plural(hidden, "element")}`,
+		paint: ctx.c.dim
+	}]));
+	return lines;
+}
+function summary(audits, ctx) {
+	const withViolations = audits.filter((audit) => audit.violations.length > 0);
+	const errored = audits.filter((audit) => audit.error);
+	const ruleCount = audits.reduce((total, audit) => total + audit.violations.length, 0);
+	const elementCount = audits.reduce((total, audit) => total + audit.violations.reduce((sum, finding) => sum + finding.nodes.length, 0), 0);
+	const reviewCount = countRules(audits, "needs-review");
+	const pages = `${audits.length} ${plural(audits.length, "page")}`;
+	const lines = [render(ctx, [{
+		text: "Summary",
+		paint: ctx.c.bold
+	}])];
+	if (ruleCount === 0) lines.push(render(ctx, [{
+		text: `  No violations across ${pages}.`,
+		paint: ctx.c.green
+	}]));
+	else {
+		lines.push(render(ctx, [{
+			text: `  ${ruleCount} ${plural(ruleCount, "violation")} on ${withViolations.length} of ${pages}`,
+			paint: ctx.c.red
+		}, {
+			text: ` (${elementCount} ${plural(elementCount, "element")})`,
+			paint: ctx.c.dim
+		}]));
+		lines.push(thresholdLine(audits, ctx));
+	}
+	if (reviewCount > 0) lines.push(render(ctx, [{
+		text: `  ${reviewCount} ${plural(reviewCount, "rule")} ${reviewCount === 1 ? "needs" : "need"} manual review`,
+		paint: ctx.c.yellow
+	}]));
+	if (errored.length > 0) lines.push(render(ctx, [{
+		text: `  ${errored.length} ${plural(errored.length, "page")} could not be audited`,
+		paint: ctx.c.red
+	}]));
+	const accepted = audits.reduce((total, audit) => total + (audit.accepted ?? []).reduce((sum, finding) => sum + finding.nodes.length, 0), 0);
+	if (accepted > 0) lines.push(render(ctx, [{
+		text: `  ${accepted} ${plural(accepted, "element")} accepted by the baseline, not counted above`,
+		paint: ctx.c.dim
+	}]));
+	lines.push(...blindSection(audits, ctx));
+	return lines;
+}
+/**
+* Why the run passed or failed. Without this, a build that exits 0 while the
+* report lists violations looks like a bug rather than a threshold choice.
+*/
+function thresholdLine(audits, ctx) {
+	const failOn = ctx.failOn;
+	const failing = countAtOrAbove(audits, failOn);
+	if (failing === 0) return render(ctx, [{
+		text: `  none at or above ${failOn} (--fail-on ${failOn}), so this run passes`,
+		paint: ctx.c.green
+	}]);
+	return render(ctx, [{
+		text: `  ${failing} at or above ${failOn} (--fail-on ${failOn})`,
+		paint: ctx.c.red
+	}]);
+}
+/**
+* The unevaluated rules are listed once, at the end, rather than repeated under
+* every page: on a large site the same handful recurs on each one, and a wall
+* of "not evaluated" would bury the findings that are real.
+*/
+function blindSection(audits, ctx) {
+	const byRule = /* @__PURE__ */ new Map();
+	for (const audit of audits) for (const finding of audit.incomplete) {
+		if (finding.reason !== "engine-limitation") continue;
+		const entry = byRule.get(finding.ruleId);
+		if (entry) entry.pages += 1;
+		else byRule.set(finding.ruleId, {
+			pages: 1,
+			finding
+		});
+	}
+	if (byRule.size === 0) return [];
+	const lines = [
+		"",
+		render(ctx, [{
+			text: "Not evaluated",
+			paint: ctx.c.bold
+		}]),
+		render(ctx, [{
+			text: "  This engine reached no verdict on these.",
+			paint: ctx.c.dim
+		}]),
+		render(ctx, [{
+			text: "  They are never reported as passing.",
+			paint: ctx.c.dim
+		}])
+	];
+	for (const [ruleId, { pages, finding }] of [...byRule].sort((a, b) => b[1].pages - a[1].pages)) {
+		lines.push(render(ctx, [
+			{ text: `  ${ctx.symbol("blind")} ` },
+			{ text: ruleId },
+			{
+				text: ` ${pages} ${plural(pages, "page")}${criteria(finding)}`,
+				paint: ctx.c.dim
+			}
+		]));
+		lines.push(render(ctx, [{
+			text: `      ${finding.reasonDetail}`,
+			paint: ctx.c.dim
+		}]));
+	}
+	return lines;
+}
+function countRules(audits, reason) {
+	const ruleIds = /* @__PURE__ */ new Set();
+	for (const audit of audits) for (const finding of audit.incomplete) if (finding.reason === reason) ruleIds.add(finding.ruleId);
+	return ruleIds.size;
+}
+function sortByImpact(findings) {
+	return [...findings].sort((a, b) => {
+		const rank = impactRank(a) - impactRank(b);
+		return rank === 0 ? a.ruleId.localeCompare(b.ruleId) : rank;
+	});
+}
+/** Most severe first; anything axe-core left unclassified sorts last. */
+function impactRank(finding) {
+	const index = IMPACT_LEVELS.indexOf(finding.impact);
+	return index === -1 ? IMPACT_LEVELS.length : IMPACT_LEVELS.length - index;
+}
+function criteria(finding) {
+	return finding.successCriteria.length > 0 ? `, WCAG ${finding.successCriteria.join(" ")}` : "";
+}
+function collapse(html) {
+	return html.replace(/\s+/g, " ").trim();
+}
+function plural(count, word) {
+	return count === 1 ? word : `${word}s`;
+}
+//#endregion
+//#region src/cli/audit.ts
+/**
+* The engines and the machine-readable reporters are imported where they are
+* used, not at the top of the file.
+*
+* jsdom costs 630 ms to load and axe-core another 94 ms, and a static import
+* here charges that to every invocation — `eaa-kit statement`, `--help` and a
+* mistyped flag included, none of which parse a single page. The audit path
+* pays the same cost either way, a few milliseconds later.
+*/
+const OUTPUT_FORMATS = [
+	"console",
+	"json",
+	"sarif",
+	"html"
+];
+function isOutputFormat(value) {
+	return OUTPUT_FORMATS.includes(value);
+}
+/**
+* `eaa-kit audit [dir]`.
+*
+* Writes progress to stderr and the report to stdout, so the report can be
+* piped somewhere without the chatter coming along.
+*/
+async function runAuditCommand(dir, options = {}) {
+	let pages;
+	try {
+		pages = await collectPages(dir, {
+			...options.include ? { include: options.include } : {},
+			...options.exclude ? { exclude: options.exclude } : {}
+		});
+	} catch (cause) {
+		if (cause instanceof BuildDirectoryError) {
+			process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+			process.stderr.write(pc.dim("Point eaa-kit at your build output, e.g. eaa-kit audit ./dist\n"));
+			return {
+				audits: [],
+				exitCode: 2
+			};
+		}
+		throw cause;
+	}
+	if (pages.length === 0) {
+		process.stderr.write(`${pc.yellow("warning")} No HTML files found in ${dir}\n`);
+		return {
+			audits: [],
+			exitCode: 2
+		};
+	}
+	const engineNote = await describeEngine(pages, options);
+	process.stderr.write(pc.dim(`Auditing ${pages.length} ${pages.length === 1 ? "page" : "pages"} in ${dir}${engineNote}…\n`));
+	const runnerOptions = {
+		...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+	};
+	let audits;
+	if (options.browser) {
+		const { BrowserUnavailableError, runBrowserAudit } = await import("./playwright-BfWuTG_u.js");
+		try {
+			audits = await runBrowserAudit(dir, pages, runnerOptions);
+		} catch (cause) {
+			if (cause instanceof BrowserUnavailableError) {
+				process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+				return {
+					audits: [],
+					exitCode: 2
+				};
+			}
+			throw cause;
+		}
+	} else {
+		const { runPooledAudit } = await import("./pool-DixLeu8L.js");
+		audits = await runPooledAudit(pages, {
+			...runnerOptions,
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency }
+		});
+	}
+	const failOn = options.failOn ?? "serious";
+	if (options.baseline) {
+		const applied = await acceptBaseline(audits, options);
+		if (!applied) return {
+			audits,
+			exitCode: 2
+		};
+		audits = applied;
+	}
+	await emit(audits, dir, failOn, options);
+	const unaudited = audits.filter((audit) => audit.error);
+	if (unaudited.length > 0) {
+		process.stderr.write(`${pc.red("error")} ${unaudited.length} of ${audits.length} pages could not be audited\n`);
+		return {
+			audits,
+			exitCode: 2
+		};
+	}
+	return {
+		audits,
+		exitCode: countAtOrAbove(audits, failOn) > 0 ? 1 : 0
+	};
+}
+/**
+* Move the violations the baseline accounts for out of the failing set.
+*
+* Returns undefined when the baseline could not be read, which the caller
+* turns into exit 2: a run asked to use a baseline it cannot find has not
+* measured what it was told to measure, and silently failing on everything
+* would be as wrong as silently passing.
+*/
+async function acceptBaseline(audits, options) {
+	const { applyBaseline, BaselineError, readBaseline } = await import("./baseline-Itspu3-Y.js");
+	try {
+		const outcome = applyBaseline(audits, await readBaseline(options.baseline, options.cwd ?? process.cwd()));
+		if (outcome.accepted > 0) process.stderr.write(pc.dim(`Baseline accepted ${outcome.accepted} violating elements\n`));
+		if (outcome.stale.length > 0) {
+			const count = outcome.stale.length;
+			process.stderr.write(pc.dim(`${count} baseline ${count === 1 ? "entry no longer matches" : "entries no longer match"} and can be removed\n`));
+		}
+		if (outcome.expired.length > 0) process.stderr.write(pc.yellow(`${outcome.expired.length} baseline entries have expired and no longer suppress anything\n`));
+		return outcome.audits;
+	} catch (cause) {
+		if (cause instanceof BaselineError) {
+			process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+			return;
+		}
+		throw cause;
+	}
+}
+/**
+* What the progress line says about the engine.
+*
+* The thread count is on it because it is the difference between a run that
+* looks stalled and one that is working, and because a user comparing two
+* timings deserves to know which one used the machine.
+*/
+async function describeEngine(pages, options) {
+	if (options.browser) return " with Chromium";
+	const { plannedWorkers } = await import("./pool-DixLeu8L.js");
+	const workers = options.concurrency ?? plannedWorkers(pages);
+	return workers > 1 ? ` across ${workers} threads` : "";
+}
+/**
+* Emit the chosen format, to a file when --output is given and to stdout
+* otherwise. Colour is dropped when writing to a file, since escape codes in a
+* saved report are noise.
+*/
+async function emit(audits, dir, failOn, options) {
+	const body = await renderReport(audits, dir, failOn, options.format ?? "console", typeof options.output === "string", options);
+	if (!options.output) {
+		process.stdout.write(body);
+		return;
+	}
+	const target = path.resolve(options.cwd ?? process.cwd(), options.output);
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, body, "utf8");
+	process.stderr.write(pc.dim(`Report written to ${options.output}\n`));
+}
+async function renderReport(audits, dir, failOn, format, toFile, options) {
+	switch (format) {
+		case "json": {
+			const { buildJsonReport, serialiseJsonReport } = await import("./json-1ESNIiHY.js");
+			return serialiseJsonReport(buildJsonReport(audits, {
+				directory: dir,
+				failOn,
+				...options.baseUrl ? { baseUrl: options.baseUrl } : {}
+			}));
+		}
+		case "sarif": {
+			const { buildSarifReport, serialiseSarifReport } = await import("./sarif-eSCuI0eX.js");
+			return serialiseSarifReport(buildSarifReport(audits, { directory: dir }));
+		}
+		case "html": {
+			const { buildHtmlReport } = await import("./html-BLEuzep6.js");
+			return buildHtmlReport(audits, {
+				directory: dir,
+				failOn,
+				...options.baseUrl ? { baseUrl: options.baseUrl } : {}
+			});
+		}
+		case "console": return `${formatConsoleReport(audits, {
+			dir,
+			failOn,
+			...toFile ? { color: false } : {}
+		})}\n`;
+	}
+}
+//#endregion
+export { collectPages as a, BuildDirectoryError as i, isOutputFormat as n, runAuditCommand as r, OUTPUT_FORMATS as t };

package/dist/audit-VtuUOuyX.js

@@ -0,0 +1,2 @@
+import { r as runAuditCommand } from "./audit-6gbV0Zjd.js";
+export { runAuditCommand };