eaa-kit 0.2.1 → 0.4.0

package/dist/audit-CPoZMXGM.js

@@ -0,0 +1,779 @@
+import { a as impactRank, i as impactLabel, r as countAtOrAbove } from "./impact-DZt2oBCP.js";
+import { a as plural, n as count, t as collapse } from "./text-CKKpzkYM.js";
+import { a as isShared, c as runCompleteness, i as groupIssues, n as blindRules, r as coverageParts, t as remediationFor } from "./remediation-Dtowi2EC.js";
+import { r as componentPath } from "./component-C3GL1Mnu.js";
+import { i as understandingUrl, n as coverageSummary, r as manualCheckFor, t as buildCoverage } from "./coverage-B4IBKMO8.js";
+import { a as runEngine, i as note, n as emitDocument, o as warn, r as fail, t as advise } from "./command-D8l_oYbV.js";
+import { n as collectPages, r as emptyDirectoryHint, t as BuildDirectoryError } from "./collect-CFM8gEVv.js";
+import path from "node:path";
+import pc from "picocolors";
+//#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),
+		""
+	];
+	lines.push(...issuesSection(audits, ctx));
+	if (options.perPage) {
+		lines.push("", ...legendLines(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",
+		sourceFor: options.sourceFor ?? (() => void 0),
+		componentFor: options.componentFor ?? (() => void 0),
+		manual: options.manual ?? false,
+		coverage: options.coverage ?? false,
+		framework: options.framework,
+		completeness: options.completeness,
+		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("");
+}
+/** One line from a single segment, which is what most of this report is. */
+function line(ctx, text, paint) {
+	return render(ctx, paint === void 0 ? [{ text }] : [{
+		text,
+		paint
+	}]);
+}
+function headerLines(audits, ctx) {
+	const engineLabel = (audits[0]?.engine ?? "jsdom") === "browser" ? "chromium" : "jsdom (browserless)";
+	return [render(ctx, [{
+		text: "eaa-kit audit",
+		paint: ctx.c.bold
+	}, {
+		text: ` ${count(audits.length, "page")} · ${engineLabel}`,
+		paint: ctx.c.dim
+	}])];
+}
+/**
+* What the per-page counts mean.
+*
+* Only with the per-page listing, which is the only place those words appear:
+* "not applicable" reads like good news unless it is spelled out, and printing
+* the gloss for a section that is not there is noise.
+*/
+function legendLines(ctx) {
+	return [line(ctx, "passed = checked and met · not applicable = nothing to check", ctx.c.dim)];
+}
+function pageSection(audit, ctx) {
+	const lines = [line(ctx, audit.relativePath, 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 = count(finding.nodes.length, "element");
+		lines.push(line(ctx, `  · ${finding.ruleId} accepted by the baseline (${elements})`, ctx.c.dim));
+	}
+	lines.push(coverageLine(audit, ctx));
+	lines.push("");
+	return lines;
+}
+function coverageLine(audit, ctx) {
+	return line(ctx, `    ${coverageParts(audit).join(" · ")}`, 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
+		}
+	]), line(ctx, `      ${finding.help}`)];
+	for (const node of finding.nodes.slice(0, ctx.maxNodes)) {
+		lines.push(line(ctx, `      ${node.target.join(" ")}`, ctx.c.cyan));
+		lines.push(line(ctx, `        ${collapse(node.html)}`, ctx.c.dim));
+	}
+	const hidden = finding.nodes.length - ctx.maxNodes;
+	if (hidden > 0) lines.push(line(ctx, `      + ${count(hidden, "more element")}`, 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 = count(audits.length, "page");
+	const lines = [line(ctx, "Summary", ctx.c.bold), ...completenessLines(ctx)];
+	if (ruleCount === 0) {
+		const clean = ctx.completeness && !ctx.completeness.complete ? `  No violations across the ${pages} that were audited.` : `  No violations across ${pages}.`;
+		lines.push(line(ctx, clean, ctx.c.green));
+	} else {
+		lines.push(render(ctx, [{
+			text: `  ${count(ruleCount, "violation")} on ${withViolations.length} of ${pages}`,
+			paint: ctx.c.red
+		}, {
+			text: ` (${count(elementCount, "element")})`,
+			paint: ctx.c.dim
+		}]));
+		lines.push(thresholdLine(audits, ctx));
+	}
+	if (reviewCount > 0) {
+		const verb = reviewCount === 1 ? "needs" : "need";
+		lines.push(line(ctx, `  ${count(reviewCount, "rule")} ${verb} manual review`, ctx.c.yellow));
+	}
+	if (errored.length > 0) lines.push(line(ctx, `  ${count(errored.length, "page")} could not be audited`, 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(line(ctx, `  ${count(accepted, "element")} accepted by the baseline, not counted above`, ctx.c.dim));
+	lines.push(...blindSection(audits, ctx));
+	lines.push(...coverageSection(audits, ctx));
+	return lines;
+}
+/**
+* How much of the standard this run could reach.
+*
+* One line by default. It is the sentence that stops a clean report reading as
+* a clean site: most of WCAG cannot be checked by any automated engine, and
+* until this was printed the report said so only in prose, in the footer, where
+* it could be read as boilerplate.
+*/
+function coverageSection(audits, ctx) {
+	const coverage = buildCoverage(audits);
+	const lines = ["", ...wrap(coverageSummary(coverage), ctx.width - 2).map((text) => line(ctx, `  ${text}`, ctx.c.dim))];
+	if (coverage.browserWouldAnswer > 0) {
+		const verb = coverage.browserWouldAnswer === 1 ? "criterion" : "criteria";
+		lines.push(line(ctx, `  --browser would answer ${coverage.browserWouldAnswer} more ${verb}.`, ctx.c.dim));
+	}
+	if (!ctx.coverage) {
+		lines.push(line(ctx, "  Run with --coverage for the criterion-by-criterion breakdown.", ctx.c.dim));
+		return lines;
+	}
+	lines.push("", line(ctx, "Coverage", ctx.c.bold));
+	for (const criterion of coverage.criteria) {
+		const paint = criterion.status === "evaluated" ? ctx.c.green : ctx.c.dim;
+		const note = criterion.browserWouldAnswer ? " (--browser would answer this)" : "";
+		lines.push(render(ctx, [
+			{
+				text: `  ${criterion.number} `,
+				paint: ctx.c.bold
+			},
+			{ text: `${criterion.title} (${criterion.level}) — ` },
+			{
+				text: `${STATUS_WORDS[criterion.status]}${note}`,
+				paint
+			}
+		]));
+	}
+	return lines;
+}
+/** What each outcome is called, in words rather than a symbol. */
+const STATUS_WORDS = {
+	evaluated: "evaluated here",
+	"not-evaluated": "this engine could not evaluate it",
+	"nothing-to-check": "rules ran and found nothing on this site to check",
+	"no-automated-rule": "no automated rule exists; a person must check it"
+};
+/**
+* What the run never looked at.
+*
+* Printed before the counts rather than after them, because it changes how they
+* read: "no violations" means one thing over a whole site and another over the
+* twelve pages of it a crawl managed to fetch before it hit its limit.
+*
+* Pages that errored are left to the summary's own line, which already names
+* them; repeating the number here would read as twice as many.
+*/
+function completenessLines(ctx) {
+	const completeness = ctx.completeness;
+	if (completeness === void 0 || completeness.complete) return [];
+	const lines = [];
+	if (completeness.unreachable.length > 0) {
+		const noun = plural(completeness.unreachable.length, "page");
+		lines.push(line(ctx, `  ${completeness.unreachable.length} ${noun} could not be reached, and were not audited`, ctx.c.yellow));
+	}
+	if (completeness.truncated) lines.push(line(ctx, "  The run stopped at its page limit; the site has more", ctx.c.yellow));
+	if (lines.length > 0) lines.push(line(ctx, "  This report describes what was audited, not the whole site.", ctx.c.dim));
+	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 line(ctx, `  none at or above ${failOn} (--fail-on ${failOn}), so this run passes`, ctx.c.green);
+	return line(ctx, `  ${failing} at or above ${failOn} (--fail-on ${failOn})`, 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 blind = blindRules(audits).sort((a, b) => b.pages - a.pages);
+	if (blind.length === 0) return [];
+	const lines = [
+		"",
+		line(ctx, "Not evaluated", ctx.c.bold),
+		line(ctx, "  This engine reached no verdict on these.", ctx.c.dim),
+		line(ctx, "  They are never reported as passing.", ctx.c.dim)
+	];
+	for (const { ruleId, pages, finding } of blind) {
+		lines.push(render(ctx, [
+			{ text: `  ${ctx.symbol("blind")} ` },
+			{ text: ruleId },
+			{
+				text: ` ${count(pages, "page")}${criteria(finding)}`,
+				paint: ctx.c.dim
+			}
+		]), line(ctx, `      ${finding.reasonDetail}`, ctx.c.dim));
+		const manual = manualCheckFor(ruleId);
+		if (manual !== void 0 && ctx.manual) {
+			for (const wrapped of wrap(manual.check, ctx.width - 8)) lines.push(line(ctx, `      ${wrapped}`, ctx.c.dim));
+			if (manual.browserAnswers) lines.push(line(ctx, "      or run again with --browser", ctx.c.dim));
+		}
+		for (const criterion of finding.successCriteria) {
+			const url = understandingUrl(criterion);
+			if (url !== void 0) lines.push(line(ctx, `      ${criterion}: ${url}`, ctx.c.dim));
+		}
+	}
+	if (!ctx.manual) lines.push(line(ctx, "  Run with --manual for what to check by hand.", 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) => impactRank(a.impact) - impactRank(b.impact) || a.ruleId.localeCompare(b.ruleId));
+}
+function criteria(finding) {
+	return finding.successCriteria.length > 0 ? `, WCAG ${finding.successCriteria.join(" ")}` : "";
+}
+/**
+* What is actually broken, once per element rather than once per page.
+*
+* The page-by-page listing above is the truth, and on a site built from
+* components it is not the work: one header with a missing `alt` reappears on
+* every page that renders it, and nothing in a per-page report says those are
+* one line in one file. This section says it, and orders the result by what
+* fixing it would buy.
+*/
+function issuesSection(audits, ctx) {
+	const issues = groupIssues(audits);
+	if (issues.length === 0) return [];
+	const elements = issues.reduce((total, issue) => total + issue.elements.length, 0);
+	const occurrences = issues.reduce((total, issue) => total + issue.occurrences, 0);
+	const lines = [line(ctx, "Issues", ctx.c.bold)];
+	const intro = occurrences === elements ? `  ${count(elements, "distinct element")} to fix.` : `  ${count(occurrences, "violation")} across the site come from ${count(elements, "distinct element")}.`;
+	lines.push(line(ctx, intro, ctx.c.dim));
+	for (const issue of issues) {
+		lines.push("");
+		lines.push(render(ctx, [
+			{ text: `  ${ctx.symbol("violation")} ` },
+			{
+				text: issue.ruleId,
+				paint: ctx.c.bold
+			},
+			{
+				text: ` ${impactLabel(issue.impact)}`,
+				paint: ctx.c.dim
+			},
+			...issue.successCriteria.length > 0 ? [{
+				text: `, WCAG ${issue.successCriteria.join(" ")}`,
+				paint: ctx.c.dim
+			}] : []
+		]));
+		lines.push(line(ctx, `      ${issue.help}`, ctx.c.dim));
+		lines.push(...remediationLines(issue.ruleId, issue.elements[0]?.html, ctx));
+		for (const element of issue.elements.slice(0, ctx.maxNodes)) {
+			lines.push(line(ctx, `      ${collapse(element.html)}`));
+			lines.push(...whereLines(element, ctx));
+		}
+		const hidden = issue.elements.length - ctx.maxNodes;
+		if (hidden > 0) lines.push(line(ctx, `      …and ${count(hidden, "more element")}`, ctx.c.dim));
+	}
+	return lines;
+}
+/**
+* What to do about the rule, under the finding rather than in a link.
+*
+* axe-core's help text says what is wrong; this says who it stops and what to
+* change. The corrected line is built from the element that actually failed,
+* because a textbook snippet is a second thing to translate before anybody can
+* use it.
+*/
+function remediationLines(ruleId, html, ctx) {
+	const remediation = remediationFor(ruleId, ctx.framework);
+	if (remediation === void 0) return [];
+	const indent = "      ";
+	const width = ctx.width - 6 - 2;
+	const lines = [...wrap(remediation.why, width).map((text) => line(ctx, `${indent}${text}`, ctx.c.dim)), ...wrap(`Fix: ${remediation.fix}`, width).map((text) => line(ctx, `${indent}${text}`))];
+	const example = html === void 0 ? void 0 : remediation.example?.(html);
+	if (example !== void 0) lines.push(render(ctx, [{
+		text: `${indent}→ `,
+		paint: ctx.c.green
+	}, { text: collapse(example) }]));
+	return lines;
+}
+/** Where one element appears, and what that says about where the fix goes. */
+function whereLines(element, ctx) {
+	const shown = element.pages.slice(0, ctx.maxNodes);
+	const rest = element.pages.length - shown.length;
+	const component = ctx.componentFor(element.html);
+	const lines = component === void 0 ? [] : [render(ctx, [{
+		text: "        written in ",
+		paint: ctx.c.dim
+	}, { text: componentPath(component) }])];
+	lines.push(line(ctx, `        on ${count(element.pages.length, "page")}:`, ctx.c.dim));
+	for (const page of shown) {
+		const source = ctx.sourceFor(page);
+		lines.push(render(ctx, [{
+			text: `          ${page}`,
+			paint: ctx.c.dim
+		}, ...source === void 0 ? [] : [{
+			text: `  ${source}`,
+			paint: ctx.c.dim
+		}]]));
+	}
+	if (rest > 0) lines.push(line(ctx, `          …and ${count(rest, "more page")}`, ctx.c.dim));
+	if (isShared(element)) lines.push(line(ctx, "        identical on each — likely one shared component", ctx.c.dim));
+	return lines;
+}
+/** Wraps a sentence to the terminal, so a paragraph of advice stays readable. */
+function wrap(text, width) {
+	const words = text.split(" ");
+	const lines = [];
+	let line = "";
+	for (const word of words) if (line === "") line = word;
+	else if (`${line} ${word}`.length <= width) line = `${line} ${word}`;
+	else {
+		lines.push(line);
+		line = word;
+	}
+	if (line !== "") lines.push(line);
+	return lines;
+}
+//#endregion
+//#region src/cli/pages.ts
+/**
+* Collect the pages to audit, reporting to stderr on the way.
+*
+* Returns undefined when there is nothing to audit, having already explained
+* why. Every caller turns that into exit 2 — a run that reached no verdict,
+* which is not the same as a clean one.
+*/
+async function resolvePages(directory, options = {}) {
+	if (directory === void 0 && options.url === void 0) return resolveAutomatically(options);
+	if (options.url !== void 0) {
+		const crawled = await crawlPages(options.url, options);
+		if (!crawled) return void 0;
+		if (crawled.pages.length === 0) {
+			warn(`No pages could be fetched from ${options.url}`);
+			return;
+		}
+		return {
+			pages: crawled.pages,
+			origin: crawled.origin,
+			label: options.url,
+			completeness: crawled.completeness
+		};
+	}
+	const cwd = options.cwd ?? process.cwd();
+	const shown = options.label ?? directory;
+	const unreachable = [];
+	let pages;
+	try {
+		pages = await collectPages(directory, {
+			...options.include ? { include: options.include } : {},
+			...options.exclude ? { exclude: options.exclude } : {},
+			onUnreadable: (relativePath, reason) => unreachable.push({
+				location: relativePath,
+				reason
+			})
+		});
+	} catch (cause) {
+		if (!(cause instanceof BuildDirectoryError)) throw cause;
+		fail(cause.message);
+		note(await emptyDirectoryHint(shown, cwd));
+		return;
+	}
+	if (pages.length === 0) {
+		warn(await emptyDirectoryHint(shown, cwd));
+		return;
+	}
+	if (unreachable.length > 0) {
+		const verb = unreachable.length === 1 ? "file was" : "files were";
+		warn(`${unreachable.length} ${verb} not readable, and so not audited:`);
+		for (const file of unreachable.slice(0, 10)) note(`  ${file.location} — ${file.reason}`);
+		if (unreachable.length > 10) note(`  …and ${unreachable.length - 10} more`);
+	}
+	return {
+		pages,
+		label: shown,
+		completeness: {
+			discovery: "directory",
+			collected: pages.length,
+			unreachable,
+			truncated: false
+		}
+	};
+}
+/**
+* Fetch the pages of a running site, reporting what happened on the way.
+*
+* Returns undefined when the crawl could not start, which the caller turns into
+* exit 2 — a run that reached no verdict, not a clean one.
+*/
+async function crawlPages(url, options) {
+	const { crawlSite, CrawlError, parseEntryUrl } = await import("./crawl-BiI1Lau_.js");
+	let entry;
+	try {
+		entry = parseEntryUrl(url, options.allowRemote ?? false);
+	} catch (cause) {
+		if (cause instanceof CrawlError) {
+			fail(cause.message);
+			return;
+		}
+		throw cause;
+	}
+	note(`Crawling ${entry.origin}…`);
+	const result = await crawlSite(entry, {
+		...options.allowRemote ? { allowRemote: true } : {},
+		...options.ignoreRobots ? { ignoreRobots: true } : {},
+		...options.sitemap === void 0 ? {} : { sitemap: options.sitemap },
+		...options.maxPages === void 0 ? {} : { maxPages: options.maxPages },
+		...options.maxDepth === void 0 ? {} : { maxDepth: options.maxDepth },
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+	});
+	if (result.pages.length === 0 && result.failures.length > 0) {
+		fail(`Could not fetch ${entry.href} (${result.failures[0]?.reason})`);
+		note("  Is the site running at that address?");
+		return;
+	}
+	const found = result.discovery === "sitemap" ? "sitemap.xml and links" : "links";
+	note(`Found ${count(result.pages.length, "page")} from ${found}`);
+	if (result.failures.length > 0) {
+		const verb = result.failures.length === 1 ? "URL was" : "URLs were";
+		warn(`${result.failures.length} ${verb} not fetched, and so not audited:`);
+		for (const failure of result.failures.slice(0, 10)) note(`  ${failure.url} — ${failure.reason}`);
+		if (result.failures.length > 10) note(`  …and ${result.failures.length - 10} more`);
+	}
+	if (result.truncated) warn(`Stopped at ${count(result.pages.length, "page")}; the site has more. Raise --max-pages to go further.`);
+	return {
+		pages: result.pages,
+		origin: result.origin,
+		completeness: {
+			discovery: result.discovery,
+			collected: result.pages.length,
+			unreachable: result.failures.map((failure) => ({
+				location: failure.url,
+				reason: failure.reason
+			})),
+			truncated: result.truncated
+		}
+	};
+}
+/**
+* No directory and no URL: work out what this project needs.
+*
+* The point is that `eaa-kit audit` on its own does something useful. Anything
+* this starts is handed back as `cleanup` so the caller can stop it once the
+* report is written.
+*/
+async function resolveAutomatically(options) {
+	const cwd = options.cwd ?? process.cwd();
+	const { autoDetectSource } = await import("./project-MFrXcw1M.js");
+	const detected = await autoDetectSource(cwd, {
+		...options.noBuild ? { noBuild: true } : {},
+		onStep: note
+	});
+	if (detected?.directory !== void 0) return resolvePages(detected.directory, {
+		...options,
+		label: path.relative(cwd, detected.directory) || "."
+	});
+	if (detected?.url !== void 0) {
+		const resolved = await resolvePages(void 0, {
+			...options,
+			url: detected.url
+		});
+		if (resolved === void 0) {
+			await detected.cleanup?.();
+			return;
+		}
+		return {
+			...resolved,
+			...detected.cleanup ? { cleanup: detected.cleanup } : {}
+		};
+	}
+	await detected?.cleanup?.();
+	warn(await emptyDirectoryHint("./dist", cwd));
+}
+//#endregion
+//#region src/cli/audit.ts
+const OUTPUT_FORMATS = [
+	"console",
+	"json",
+	"sarif",
+	"html"
+];
+/**
+* `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 = {}) {
+	const resolved = await resolvePages(dir, options);
+	if (!resolved) return {
+		audits: [],
+		exitCode: 2
+	};
+	const { pages, origin, label, cleanup, completeness: collection } = resolved;
+	try {
+		note(`Auditing ${count(pages.length, "page")} in ${label}${await describeEngine(pages, options)}…`);
+		const baseUrl = options.baseUrl ?? origin;
+		let audits = await runEngine(pages, {
+			cwd: options.cwd ?? process.cwd(),
+			...baseUrl === void 0 ? {} : { baseUrl },
+			...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
+			...options.browser ? { browser: true } : {},
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency },
+			...options.url === void 0 && dir !== void 0 ? { directory: dir } : {}
+		});
+		if (!audits) return {
+			audits: [],
+			exitCode: 2
+		};
+		const failOn = options.failOn ?? "serious";
+		if (options.baseline) {
+			const applied = await acceptBaseline(audits, options);
+			if (!applied) return {
+				audits,
+				exitCode: 2
+			};
+			audits = applied;
+		}
+		const completeness = runCompleteness(audits, collection);
+		await emit(audits, label, failOn, completeness, options);
+		const unaudited = audits.filter((audit) => audit.error);
+		if (unaudited.length > 0) {
+			fail(`${unaudited.length} of ${audits.length} pages could not be audited`);
+			return {
+				audits,
+				exitCode: 2
+			};
+		}
+		return {
+			audits,
+			exitCode: countAtOrAbove(audits, failOn) > 0 ? 1 : 0
+		};
+	} finally {
+		await cleanup?.();
+	}
+}
+/**
+* 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-22Y1NWxM.js");
+	try {
+		const outcome = applyBaseline(audits, await readBaseline(options.baseline, options.cwd ?? process.cwd()));
+		if (outcome.accepted > 0) note(`Baseline accepted ${outcome.accepted} violating elements`);
+		if (outcome.stale.length > 0) {
+			const stale = outcome.stale.length;
+			note(`${stale} baseline ${stale === 1 ? "entry no longer matches" : "entries no longer match"} and can be removed`);
+		}
+		if (outcome.expired.length > 0) advise(`${outcome.expired.length} baseline entries have expired and no longer suppress anything`);
+		return outcome.audits;
+	} catch (cause) {
+		if (cause instanceof BaselineError) {
+			fail(cause.message);
+			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-BMevaLWD.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, completeness, options) {
+	const body = await renderReport(audits, dir, failOn, completeness, options.format ?? "console", typeof options.output === "string", options);
+	await emitDocument(body, options.output, options.cwd ?? process.cwd());
+	if (options.output !== void 0) note(`Report written to ${options.output}`);
+}
+async function renderReport(audits, dir, failOn, completeness, format, toFile, options) {
+	switch (format) {
+		case "json": {
+			const { buildJsonReport, serialiseJsonReport } = await import("./json-QQuFIw1W.js");
+			return serialiseJsonReport(buildJsonReport(audits, {
+				directory: dir,
+				...options.url === void 0 ? {} : { sourceKind: "url" },
+				failOn,
+				completeness,
+				...options.baseUrl ? { baseUrl: options.baseUrl } : {}
+			}));
+		}
+		case "sarif": {
+			const { buildSarifReport, serialiseSarifReport } = await import("./sarif-SR3_lLYd.js");
+			return serialiseSarifReport(buildSarifReport(audits, {
+				directory: dir,
+				completeness
+			}));
+		}
+		case "html": {
+			const { buildHtmlReport } = await import("./html-BGTO3ypW.js");
+			const framework = await detectedFramework(options.cwd ?? process.cwd());
+			return buildHtmlReport(audits, {
+				...await sourceLookups(options.cwd ?? process.cwd()),
+				directory: dir,
+				failOn,
+				completeness,
+				...framework === void 0 ? {} : { framework },
+				...options.baseUrl ? { baseUrl: options.baseUrl } : {}
+			});
+		}
+		case "console": {
+			const framework = await detectedFramework(options.cwd ?? process.cwd());
+			return `${formatConsoleReport(audits, {
+				...await sourceLookups(options.cwd ?? process.cwd()),
+				dir,
+				failOn,
+				completeness,
+				...options.perPage ? { perPage: true } : {},
+				...options.manual ? { manual: true } : {},
+				...options.coverage ? { coverage: true } : {},
+				...framework === void 0 ? {} : { framework },
+				...toFile ? { color: false } : {}
+			})}\n`;
+		}
+	}
+}
+/**
+* Where a page and a failing element were written, for the two reports that say
+* so. Best-effort: a project using no convention this recognises gets the
+* report it always got, with no source named.
+*/
+/** The registry id of whatever built this project, for framework-shaped advice. */
+async function detectedFramework(cwd) {
+	const { detectFramework } = await import("./frameworks-etFg_O8K.js");
+	const { readPackageJson } = await import("./project-MFrXcw1M.js");
+	return (await detectFramework(cwd, await readPackageJson(cwd)))?.framework.id;
+}
+async function sourceLookups(cwd) {
+	const { buildRouteMap, sourceFor } = await import("./routes-CmdRUuOs.js");
+	const { buildComponentIndex, componentFor } = await import("./component-DKd3EHOg.js");
+	const routes = await buildRouteMap(cwd);
+	const components = await buildComponentIndex(cwd);
+	return {
+		sourceFor: (page) => sourceFor(routes, page),
+		componentFor: (html) => componentFor(components, html)
+	};
+}
+//#endregion
+export { runAuditCommand as n, resolvePages as r, OUTPUT_FORMATS as t };