eaa-kit 0.3.0 → 0.5.0

package/dist/cli/index.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
-import { l as STATEMENT_LOCALES, o as COUNTRIES, r as loadConfig, s as ConfigError } from "../load-UYXLqGV9.js";
-import { i as readAuditReport, o as StatementError, t as renderStatement } from "../render-DI_aCnAZ.js";
-import { n as IMPACT_LEVELS, t as DEFAULT_FAIL_ON } from "../impact-YdoOtFqm.js";
-import { n as count } from "../text-BFmNtMsV.js";
+import { a as impactRank, n as IMPACT_LEVELS, o as isImpactLevel, s as meetsThreshold, t as DEFAULT_FAIL_ON } from "../impact-DZt2oBCP.js";
+import { c as nullable, d as optional, h as string, l as number, m as safeParse, n as boolean, p as record, t as array, u as object, y as withDefault } from "../schema-DJSF4K05.js";
+import { c as ConfigError, i as loadConfig, s as COUNTRIES, u as STATEMENT_LOCALES } from "../load-yAR4wzez.js";
+import { i as readAuditReport, o as StatementError, t as renderStatement } from "../render-DbGOVmhx.js";
+import { n as count, t as collapse } from "../text-CKKpzkYM.js";
 import { t as TOOL_VERSION } from "../version-B3v4rNoG.js";
-import { i as buildBaseline, n as DEFAULT_BASELINE_FILE, s as writeBaseline, t as BaselineError } from "../baseline-s9F3fXTN.js";
-import { n as runAuditCommand, r as resolvePages, t as OUTPUT_FORMATS } from "../audit-DcL73mOC.js";
-import { a as runEngine, i as note, n as emitDocument, r as fail, t as advise } from "../command-Dxpa00Ha.js";
+import { t as elementFingerprint } from "../fingerprint-BjYV_0F7.js";
+import { i as buildBaseline, n as DEFAULT_BASELINE_FILE, s as writeBaseline, t as BaselineError } from "../baseline-CuAS2lMk.js";
+import { n as runAuditCommand, r as resolvePages, t as OUTPUT_FORMATS } from "../audit-B282A3EA.js";
+import { a as emitDocument, c as runEngine, i as baselineInvocation, l as warn, n as auditDefaults, o as fail, r as auditInvocation, s as note, t as advise } from "../command-C3D7JWn6.js";
+import { enableCompileCache } from "node:module";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Command, InvalidArgumentError } from "commander";
+import pc from "picocolors";
 //#region src/cli/baseline.ts
 /**
 * `eaa-kit baseline [dir]`.
@@ -32,7 +37,7 @@ async function runBaselineCommand(dir, options = {}) {
 		entries: 0,
 		exitCode: 2
 	};
-	const { pages, origin, label } = resolved;
+	const { pages, origin, label, directory } = resolved;
 	note(`Auditing ${count(pages.length, "page")} in ${label}…`);
 	const baseUrl = options.baseUrl ?? origin;
 	const audits = await runEngine(pages, {
@@ -41,7 +46,7 @@ async function runBaselineCommand(dir, options = {}) {
 		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
 		...options.browser ? { browser: true } : {},
 		...options.concurrency === void 0 ? {} : { concurrency: options.concurrency },
-		...options.url === void 0 ? { directory: path.resolve(cwd, dir) } : {}
+		...directory === void 0 ? {} : { directory }
 	});
 	if (!audits) return {
 		entries: 0,
@@ -80,6 +85,255 @@ async function runBaselineCommand(dir, options = {}) {
 		exitCode: 0
 	};
 }
+var DiffError = class extends Error {
+	name = "DiffError";
+};
+/**
+* Only the fields a comparison reads. `completeness` is optional: a report
+* written before it existed says nothing about coverage, which is not the same
+* as saying the run was complete, and is handled as the unknown it is.
+*/
+const reportSchema = object({
+	schemaVersion: number(),
+	generatedAt: string(),
+	target: withDefault(object({ source: withDefault(string(), () => "") }), () => ({ source: "" })),
+	completeness: optional(object({
+		complete: boolean(),
+		audited: withDefault(number(), () => 0)
+	})),
+	rules: withDefault(record(object({ help: withDefault(string(), () => "") })), () => ({})),
+	pages: withDefault(array(object({
+		path: string(),
+		error: withDefault(nullable(string()), () => null),
+		violations: withDefault(array(object({
+			ruleId: string(),
+			impact: withDefault(nullable(string()), () => null),
+			nodes: withDefault(array(object({
+				html: withDefault(string(), () => ""),
+				target: withDefault(array(string()), () => [])
+			})), () => [])
+		})), () => [])
+	})), () => [])
+});
+/**
+* The elements a violation points at.
+*
+* Mirrors `findingElements` for the JSON shape, including its one subtlety: a
+* rule can fail with no element attached, and it still has an identity. Getting
+* this wrong here would make document-level failures invisible to a diff while
+* remaining visible to the baseline.
+*/
+function elementsOf(violation) {
+	if (violation.nodes.length === 0) return [{
+		selector: "",
+		html: ""
+	}];
+	return violation.nodes.map((node) => ({
+		selector: node.target.join(" "),
+		html: node.html
+	}));
+}
+/** Every violating element in a report, keyed by page and element identity. */
+function entriesOf(report) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const page of report.pages) for (const violation of page.violations) {
+		const impact = violation.impact !== null && isImpactLevel(violation.impact) ? violation.impact : null;
+		for (const { selector, html } of elementsOf(violation)) {
+			const fingerprint = elementFingerprint(violation.ruleId, selector, html);
+			const key = `${page.path}\n${fingerprint}`;
+			if (entries.has(key)) continue;
+			entries.set(key, {
+				page: page.path,
+				ruleId: violation.ruleId,
+				fingerprint,
+				impact,
+				help: report.rules[violation.ruleId]?.help ?? violation.ruleId,
+				selector,
+				html
+			});
+		}
+	}
+	return entries;
+}
+/** Pages a run reached a verdict on. A page that errored is not one of them. */
+function auditedPages(report) {
+	return new Set(report.pages.filter((page) => page.error === null).map((page) => page.path));
+}
+function sideOf(report) {
+	return {
+		source: report.target.source,
+		generatedAt: report.generatedAt,
+		audited: report.completeness?.audited ?? auditedPages(report).size,
+		complete: report.completeness?.complete
+	};
+}
+/** Worst first, then by page, so two runs of one comparison agree. */
+function bySeverityThenPage(a, b) {
+	return impactRank(a.impact) - impactRank(b.impact) || a.page.localeCompare(b.page) || a.ruleId.localeCompare(b.ruleId) || a.selector.localeCompare(b.selector);
+}
+/** Compare two parsed reports, earlier first. */
+function diffReports(base, head) {
+	const before = entriesOf(base);
+	const after = entriesOf(head);
+	const measuredByHead = auditedPages(head);
+	const added = [];
+	const fixed = [];
+	const unchanged = [];
+	const unmeasured = [];
+	for (const [key, entry] of after) if (before.has(key)) unchanged.push(entry);
+	else added.push(entry);
+	for (const [key, entry] of before) {
+		if (after.has(key)) continue;
+		if (measuredByHead.has(entry.page)) fixed.push(entry);
+		else unmeasured.push(entry);
+	}
+	return {
+		base: sideOf(base),
+		head: sideOf(head),
+		added: added.sort(bySeverityThenPage),
+		fixed: fixed.sort(bySeverityThenPage),
+		unchanged: unchanged.sort(bySeverityThenPage),
+		unmeasured: unmeasured.sort(bySeverityThenPage)
+	};
+}
+/**
+* Read a JSON report from disk.
+*
+* Refuses a schema version it was not written against rather than reading it
+* optimistically: a field that changed meaning is exactly what the version
+* number exists to signal, and a diff built on a misread field would be wrong
+* quietly.
+*/
+async function readReport(file, cwd = process.cwd()) {
+	const target = path.resolve(cwd, file);
+	let raw;
+	try {
+		raw = await readFile(target, "utf8");
+	} catch {
+		throw new DiffError(`Report not found: ${file}`);
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new DiffError(`${file} is not valid JSON (${cause.message})`);
+	}
+	const result = safeParse(reportSchema, parsed);
+	if (!result.success) {
+		const first = result.error.issues[0];
+		throw new DiffError(`${file} is not an eaa-kit JSON report${first === void 0 || first.path.length === 0 ? "" : ` at ${first.path.join(".")}`}: ${first?.message ?? "unrecognised shape"}`);
+	}
+	if (result.data.schemaVersion !== 2) throw new DiffError(`${file} is schemaVersion ${result.data.schemaVersion}; this version of eaa-kit reads 2.\n  Write both reports with the same version of eaa-kit before comparing them.`);
+	return result.data;
+}
+//#endregion
+//#region src/cli/diff.ts
+/**
+* `eaa-kit diff <before.json> <after.json>`.
+*
+* What a change did to a site's accessibility, which is the question a review
+* actually asks and which neither report answers on its own. Running the
+* auditor on a branch prints everything wrong with the site; almost all of it
+* was already there, and the two or three findings somebody introduced are
+* somewhere in the middle of it.
+*
+* Deliberately stateless. A baseline is a file somebody commits and maintains,
+* and it answers "what have we agreed to live with". This answers "what did
+* this change do", needs no file and no decision, and can be run over any two
+* reports after the fact.
+*/
+const DIFF_FORMATS = ["console", "json"];
+/** Longest element markup shown before it is truncated. */
+const MAX_SNIPPET = 100;
+async function runDiffCommand(base, head, options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	let diff;
+	try {
+		diff = diffReports(await readReport(base, cwd), await readReport(head, cwd));
+	} catch (cause) {
+		if (cause instanceof DiffError) {
+			fail(cause.message);
+			return { exitCode: 2 };
+		}
+		throw cause;
+	}
+	const failOn = options.failOn ?? "serious";
+	const failing = diff.added.filter((entry) => meetsThreshold(entry.impact, failOn));
+	const body = (options.format ?? "console") === "json" ? `${JSON.stringify(toJson(diff, failOn, failing.length), null, 2)}\n` : `${formatDiff(diff, failOn, options.output === void 0)}\n`;
+	await emitDocument(body, options.output, cwd);
+	if (options.output !== void 0) note(`Diff written to ${options.output}`);
+	if (diff.unmeasured.length > 0) warn(`${count(diff.unmeasured.length, "violation")} could not be compared: the later run did not audit ${diff.unmeasured.length === 1 ? "its page" : "their pages"}`);
+	return {
+		diff,
+		exitCode: failing.length > 0 ? 1 : 0
+	};
+}
+/**
+* The machine-readable form.
+*
+* `unchanged` is counted and not listed: it is the whole of the pre-existing
+* report, it is already available in the report itself, and repeating it here
+* would make the common case — a diff with three entries — a document nobody
+* can read.
+*/
+function toJson(diff, failOn, failing) {
+	return {
+		base: diff.base,
+		head: diff.head,
+		summary: {
+			added: diff.added.length,
+			fixed: diff.fixed.length,
+			unchanged: diff.unchanged.length,
+			unmeasured: diff.unmeasured.length,
+			failOn,
+			failing
+		},
+		added: diff.added,
+		fixed: diff.fixed,
+		unmeasured: diff.unmeasured
+	};
+}
+function formatDiff(diff, failOn, colour = true) {
+	const c = pc.createColors(colour);
+	const lines = [""];
+	lines.push(c.bold("eaa-kit diff"));
+	lines.push(c.dim(`  before  ${describe(diff.base)}`));
+	lines.push(c.dim(`  after   ${describe(diff.head)}`));
+	lines.push("");
+	if (diff.added.length === 0 && diff.fixed.length === 0) lines.push(c.green("No change in violations."));
+	if (diff.added.length > 0) {
+		lines.push(c.red(c.bold(`New (${diff.added.length})`)));
+		lines.push(...diff.added.map((entry) => entryLine(entry, c)));
+		lines.push("");
+	}
+	if (diff.fixed.length > 0) {
+		lines.push(c.green(c.bold(`Fixed (${diff.fixed.length})`)));
+		lines.push(...diff.fixed.map((entry) => entryLine(entry, c)));
+		lines.push("");
+	}
+	if (diff.unmeasured.length > 0) {
+		lines.push(c.yellow(c.bold(`Not compared (${diff.unmeasured.length})`)));
+		lines.push(c.dim("  These failed before, and the later run did not audit the page they were on."));
+		lines.push(...diff.unmeasured.map((entry) => entryLine(entry, c)));
+		lines.push("");
+	}
+	const failing = diff.added.filter((entry) => meetsThreshold(entry.impact, failOn)).length;
+	lines.push(c.bold("Summary"));
+	lines.push(`  ${diff.added.length} new · ${diff.fixed.length} fixed · ${diff.unchanged.length} unchanged`);
+	lines.push(failing > 0 ? c.red(`  ${failing} new at or above ${failOn} (--fail-on ${failOn})`) : c.green(`  no new violations at or above ${failOn} (--fail-on ${failOn})`));
+	return lines.join("\n");
+}
+function describe(side) {
+	const source = side.source === "" ? "unknown source" : side.source;
+	const coverage = side.complete === void 0 ? "coverage not recorded" : side.complete ? "complete" : "incomplete";
+	return `${source} · ${count(side.audited, "page")} · ${coverage} · ${side.generatedAt}`;
+}
+function entryLine(entry, c) {
+	const where = entry.selector === "" ? entry.page : `${entry.page} ${c.dim(entry.selector)}`;
+	const impact = entry.impact ?? "unclassified";
+	const snippet = entry.html === "" ? "" : `\n      ${c.dim(collapse(entry.html, MAX_SNIPPET))}`;
+	return `  ${c.bold(entry.ruleId)} ${c.dim(`(${impact})`)} — ${entry.help}\n    ${where}${snippet}`;
+}
 //#endregion
 //#region src/cli/statement.ts
 /** Markdown for a content directory, HTML for dropping straight onto a site. */
@@ -143,6 +397,30 @@ function formatFor(output) {
 //#endregion
 //#region src/cli/index.ts
 /**
+* Reuse the compiled form of this tool and its dependencies between runs.
+*
+* Most of what a short audit costs is not the audit. jsdom alone is ~700 ms to
+* import on a warm page cache, and V8 pays to parse and compile it from source
+* on every single run — of a CLI somebody invokes from a build script, over and
+* over, against code that has not changed since the last time. Node can cache
+* the compiled bytecode instead, which is exactly the shape of this problem.
+*
+* Measured over ten pages: 2350 ms without, 2075 ms with. The saving is a fixed
+* cost, so it counts for most on the small sites where fixed cost is most of
+* the run.
+*
+* Best-effort by design. It is a cache: a read-only filesystem, a sandbox that
+* forbids the directory, or a Node built without the feature all mean the run
+* is a little slower, and none of them is a reason to fail an audit. Node's own
+* NODE_DISABLE_COMPILE_CACHE is honoured by the call itself.
+*/
+function useCompileCache() {
+	try {
+		enableCompileCache();
+	} catch {}
+}
+useCompileCache();
+/**
 * A parser for a fixed set of words, listing them when the answer is not one.
 *
 * `normalise` is for `--country de`, where the accepted spelling differs from
@@ -178,20 +456,24 @@ const parseConcurrency = wholeNumber(1);
 const program = new Command();
 program.exitOverride();
 program.name("eaa-kit").description("WCAG 2.2 AA auditor and EU accessibility statement generator for static sites.\nNot legal advice.").version(TOOL_VERSION, "-v, --version");
-program.command("audit").description("Audit built HTML against WCAG 2.2 AA").argument("[dir]", "directory holding the built site (default: found automatically)").option("--include <globs...>", "glob patterns to audit, relative to dir").option("--exclude <globs...>", "glob patterns to skip").option("--base-url <url>", "audit pages under their real site URL").option("--url <url>", "audit a running site instead of a build directory").option("--no-build", "never run the project build or start its server").option("--per-page", "also list every page and its result").option("--manual", "what to check by hand for the rules this engine cannot evaluate").option("--allow-remote", "allow --url to crawl a host that is not localhost").option("--ignore-robots", "crawl paths robots.txt disallows").option("--max-pages <n>", "stop the crawl after this many pages", parsePositive).option("--max-depth <n>", "how far from the entry URL to follow links", parseDepth).option("--fail-on <impact>", `exit 1 on violations at or above this impact (${IMPACT_LEVELS.join("|")})`, parseImpact, DEFAULT_FAIL_ON).option("--format <format>", `output format (${OUTPUT_FORMATS.join("|")})`, parseFormat, "console").option("--output <path>", "write the report to a file instead of stdout").option("--browser", "audit in real Chromium, covering the rules jsdom cannot evaluate").option("--concurrency <n>", "worker threads to audit with, or 1 for none (default: from the page and core count)", parseConcurrency).option("--baseline <path>", "accept the violations recorded in this file; fail only on new ones").action(async (dir, flags) => {
-	const { build, ...options } = flags;
-	const { exitCode } = await runAuditCommand(dir, {
-		...options,
-		...build === false ? { noBuild: true } : {}
-	});
+program.command("audit").description("Audit built HTML against WCAG 2.2 AA").argument("[dir]", "directory holding the built site (default: found automatically)").option("--include <globs...>", "glob patterns to audit, relative to dir").option("--exclude <globs...>", "glob patterns to skip").option("--base-url <url>", "audit pages under their real site URL").option("--url <url>", "audit a running site instead of a build directory").option("--no-build", "never run the project build or start its server").option("--per-page", "also list every page and its result").option("--manual", "what to check by hand for the rules this engine cannot evaluate").option("--coverage", "list every WCAG 2.2 A/AA criterion and what this run reached on it").option("--allow-remote", "allow --url to crawl a host that is not localhost").option("--ignore-robots", "crawl paths robots.txt disallows").option("--sitemap <path>", "where the site lists its pages, if not /sitemap.xml").option("--max-pages <n>", "stop the crawl after this many pages", parsePositive).option("--max-depth <n>", "how far from the entry URL to follow links", parseDepth).option("--fail-on <impact>", `exit 1 on violations at or above this impact (${IMPACT_LEVELS.join("|")}; default: ${DEFAULT_FAIL_ON})`, parseImpact).option("--format <format>", `output format (${OUTPUT_FORMATS.join("|")}; default: console)`, parseFormat).option("--output <path>", "write the report to a file instead of stdout").option("--browser", "audit in real Chromium, covering the rules jsdom cannot evaluate").option("--fast", "skip the rules the browserless engine cannot decide anyway, losing their element lists").option("--concurrency <n>", "pages to audit at once, or 1 for none (default: from the page and core count)", parseConcurrency).option("--baseline <path>", "accept the violations recorded in this file; fail only on new ones").option("--config <path>", "take defaults from this config file, otherwise it is searched for").action(async (dir, flags) => {
+	const defaults = await auditDefaults({ ...flags.config ? { config: flags.config } : {} });
+	const invocation = auditInvocation(dir, defaults, flags);
+	const { exitCode } = await runAuditCommand(invocation.dir, invocation.options);
 	process.exitCode = exitCode;
 });
-program.command("baseline").description("Record the violations a build already has, so later runs fail only on new ones").argument("[dir]", "directory holding the built site", "./dist").option("--include <globs...>", "glob patterns to audit, relative to dir").option("--exclude <globs...>", "glob patterns to skip").option("--base-url <url>", "audit pages under their real site URL").option("--url <url>", "record a baseline from a running site instead of a directory").option("--allow-remote", "allow --url to crawl a host that is not localhost").option("--ignore-robots", "crawl paths robots.txt disallows").option("--max-pages <n>", "stop the crawl after this many pages", parsePositive).option("--max-depth <n>", "how far from the entry URL to follow links", parseDepth).option("--output <path>", `where to write it (default: ${DEFAULT_BASELINE_FILE})`).option("--note <text>", "recorded on every entry, for whoever reads the file").option("--expires-on <date>", "ISO date after which the entries stop suppressing", parseDate).option("--browser", "audit in real Chromium instead of jsdom").option("--concurrency <n>", "worker threads to audit with, or 1 for none", parseConcurrency).action(async (dir, flags) => {
-	const { exitCode } = await runBaselineCommand(dir, flags);
+program.command("baseline").description("Record the violations a build already has, so later runs fail only on new ones").argument("[dir]", "directory holding the built site (default: ./dist)").option("--include <globs...>", "glob patterns to audit, relative to dir").option("--exclude <globs...>", "glob patterns to skip").option("--base-url <url>", "audit pages under their real site URL").option("--url <url>", "record a baseline from a running site instead of a directory").option("--allow-remote", "allow --url to crawl a host that is not localhost").option("--ignore-robots", "crawl paths robots.txt disallows").option("--sitemap <path>", "where the site lists its pages, if not /sitemap.xml").option("--max-pages <n>", "stop the crawl after this many pages", parsePositive).option("--max-depth <n>", "how far from the entry URL to follow links", parseDepth).option("--output <path>", `where to write it (default: ${DEFAULT_BASELINE_FILE})`).option("--note <text>", "recorded on every entry, for whoever reads the file").option("--expires-on <date>", "ISO date after which the entries stop suppressing", parseDate).option("--browser", "audit in real Chromium instead of jsdom").option("--concurrency <n>", "pages to audit at once, or 1 for none", parseConcurrency).option("--config <path>", "take defaults from this config file, otherwise it is searched for").action(async (dir, flags) => {
+	const defaults = await auditDefaults({ ...flags.config ? { config: flags.config } : {} });
+	const invocation = baselineInvocation(dir, defaults, flags);
+	const { exitCode } = await runBaselineCommand(invocation.dir, invocation.options);
+	process.exitCode = exitCode;
+});
+program.command("diff").description("Compare two JSON reports: what a change made worse, and what it fixed").argument("<before>", "JSON report from before the change").argument("<after>", "JSON report from after it").option("--format <format>", `output format (${DIFF_FORMATS.join("|")})`, oneOf(DIFF_FORMATS)).option("--output <path>", "write the diff here instead of stdout").option("--fail-on <impact>", `exit 1 on NEW violations at or above this impact (${IMPACT_LEVELS.join("|")})`, parseImpact, DEFAULT_FAIL_ON).action(async (before, after, flags) => {
+	const { exitCode } = await runDiffCommand(before, after, flags);
 	process.exitCode = exitCode;
 });
 program.command("init").description("Write an eaa.config.json to generate statements from").option("--output <path>", "write here instead of eaa.config.json").option("--force", "overwrite a config that is already there").option("-y, --yes", "take every default without asking").action(async (flags) => {
-	const { runInitCommand } = await import("../init-DiLiYvN1.js");
+	const { runInitCommand } = await import("../init-CW7LfGT5.js");
 	const { exitCode } = await runInitCommand(flags);
 	process.exitCode = exitCode;
 });
@@ -206,6 +488,12 @@ program.command("statement").description("Generate an EU accessibility statement
 try {
 	await program.parseAsync(process.argv);
 } catch (cause) {
+	if (cause instanceof ConfigError) {
+		fail(cause.message);
+		for (const issue of cause.issues) note(`  ${issue}`);
+		process.exitCode = 2;
+		process.exit(2);
+	}
 	const error = cause;
 	if (typeof error.exitCode === "number") process.exitCode = error.exitCode === 0 ? 0 : 2;
 	else {

package/dist/{collect-BkAQ0viT.js → collect-Cu1q9NTB.js}

@@ -46,10 +46,32 @@ async function collectPages(dir, options = {}) {
 	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))));
+		const read = await Promise.all(batch.map((relativePath) => readPage(root, relativePath, options.onUnreadable, options.maxBytes ?? 33554432)));
+		for (const page of read) if (page !== void 0) pages.push(page);
 	}
 	return pages;
 }
+/**
+* Whether the directory holds any HTML at all, ignoring include and exclude.
+*
+* Asked when a run collected nothing, to tell two different mistakes apart: a
+* build directory with no pages in it, and a directory full of pages that the
+* caller's own filters excluded. The advice for the first is wrong for the
+* second — it names another directory to audit — so the question has to be
+* answered before it is given.
+*
+* Globs rather than collecting: this only needs to know whether one file
+* exists, and reading every page of a large build to answer that on a path that
+* is about to print a warning and stop would be work for nothing.
+*/
+async function holdsHtml(dir) {
+	return (await glob([...DEFAULT_INCLUDE], {
+		cwd: path.resolve(dir),
+		ignore: [...DEFAULT_EXCLUDE],
+		onlyFiles: true,
+		dot: false
+	})).length > 0;
+}
 async function assertDirectory(root, original) {
 	let stats;
 	try {
@@ -60,13 +82,25 @@ async function assertDirectory(root, original) {
 	}
 	if (!stats.isDirectory()) throw new BuildDirectoryError(`Build path is not a directory: ${original}`, root);
 }
-async function readPage(root, relativePath) {
+async function readPage(root, relativePath, onUnreadable, maxBytes) {
 	const absolutePath = path.join(root, relativePath);
-	return {
-		absolutePath,
-		relativePath,
-		html: stripBom(await readFile(absolutePath, "utf8"))
-	};
+	try {
+		const { size } = await stat(absolutePath);
+		if (size > maxBytes) {
+			if (onUnreadable === void 0) throw new Error(`${relativePath} is ${size} bytes, over the ${maxBytes} byte limit`);
+			onUnreadable(relativePath, `${megabytes(size)} MB, over the ${megabytes(maxBytes)} MB limit for one page`);
+			return;
+		}
+		return {
+			absolutePath,
+			relativePath,
+			html: stripBom(await readFile(absolutePath, "utf8"))
+		};
+	} catch (cause) {
+		if (onUnreadable === void 0) throw cause;
+		onUnreadable(relativePath, cause.message);
+		return;
+	}
 }
 /**
 * What to suggest when a directory holds no HTML, or is not there at all.
@@ -79,8 +113,8 @@ async function readPage(root, relativePath) {
 */
 async function emptyDirectoryHint(dir, cwd = process.cwd()) {
 	const head = await exists(dir, cwd) ? `${dir} holds no HTML files.` : `${dir} does not exist.`;
-	const { detectFramework } = await import("./frameworks-DaDqrJOw.js");
-	const { readPackageJson } = await import("./project-DW08TseF.js");
+	const { detectFramework } = await import("./frameworks-etFg_O8K.js");
+	const { readPackageJson } = await import("./project-MFrXcw1M.js");
 	const detected = await detectFramework(cwd, await readPackageJson(cwd));
 	if (detected !== void 0) return frameworkAdvice(head, detected, cwd, dir);
 	return await siblingAdvice(head, cwd, dir) ?? generic(head);
@@ -91,6 +125,10 @@ async function frameworkAdvice(head, detected, cwd, dir) {
 	const given = dir.replace(/^\.\//, "");
 	for (const output of outputs) if (output !== given && await exists(output, cwd)) return `${head} ${framework.name} writes to ${output}/, not ${dir}.\n  Try: eaa-kit audit ./${output}`;
 	const lines = [`${head} This is ${article(framework.name)} ${framework.name} project.`];
+	if (outputs.length === 0) {
+		lines.push(`  It renders every page on a server and writes no HTML to disk, so there is`, `  no build directory to audit. Start it, then audit what it serves:`, ...framework.serveCommand === void 0 ? [] : [`    ${framework.serveCommand}`], "    eaa-kit audit --url http://localhost:8000");
+		return lines.join("\n");
+	}
 	if (framework.staticOutput !== void 0) lines.push(`  Static output takes ${framework.staticOutput.needs} — ${framework.staticOutput.how},`, `  then: eaa-kit audit ./${outputs[0]}`);
 	else if (outputs.length === 1 && outputs[0] === given) lines.push(`  That is where it writes, so the build has not run yet — or it failed.`);
 	else lines.push(`  It writes to ${outputs.map((output) => `${output}/`).join(" or ")}. Run your build, then:`, `    eaa-kit audit ./${outputs[0]}`);
@@ -99,7 +137,7 @@ async function frameworkAdvice(head, detected, cwd, dir) {
 }
 /** Naming a build directory that is actually there beats listing the usual ones. */
 async function siblingAdvice(head, cwd, dir) {
-	const { FALLBACK_OUTPUTS } = await import("./frameworks-DaDqrJOw.js");
+	const { FALLBACK_OUTPUTS } = await import("./frameworks-etFg_O8K.js");
 	const given = dir.replace(/^\.\//, "");
 	const others = (await Promise.all(FALLBACK_OUTPUTS.map(async (name) => name !== given && await exists(name, cwd) ? name : void 0))).filter((name) => name !== void 0);
 	if (others.length === 0) return void 0;
@@ -119,5 +157,9 @@ function generic(head) {
 function article(name) {
 	return /^[aeiou]/i.test(name) ? "an" : "a";
 }
+/** Sizes in the megabytes a person reads, not the bytes a computer counts. */
+function megabytes(bytes) {
+	return (bytes / 1048576).toFixed(1).replace(/\.0$/, "");
+}
 //#endregion
-export { stripBom as i, collectPages as n, emptyDirectoryHint as r, BuildDirectoryError as t };
+export { stripBom as a, holdsHtml as i, collectPages as n, emptyDirectoryHint as r, BuildDirectoryError as t };

package/dist/command-C3D7JWn6.js

@@ -0,0 +1,160 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+//#region src/cli/command.ts
+/**
+* What every command does around the audit itself: say what is happening, run
+* the engine, and put the document somewhere.
+*
+* `audit` and `baseline` are siblings — one reports what a run found and the
+* other writes it down — so they take the same flags, choose between the same
+* two engines and fail on the same setup problems. Keeping that in one place is
+* what stops the two commands drifting into disagreeing about what a run is.
+*/
+/** Progress and diagnostics go to stderr, so the report can be piped away. */
+function note(message) {
+	process.stderr.write(pc.dim(`${message}\n`));
+}
+function warn(message) {
+	process.stderr.write(`${pc.yellow("warning")} ${message}\n`);
+}
+function fail(message) {
+	process.stderr.write(`${pc.red("error")} ${message}\n`);
+}
+/**
+* Advice the reader should not miss, without the `warning` prefix: nothing has
+* gone wrong, but what happens next is theirs to get right.
+*/
+function advise(message) {
+	process.stderr.write(pc.yellow(`${message}\n`));
+}
+/**
+* Audit the pages with whichever engine was asked for.
+*
+* Returns undefined when the browser was asked for and is not usable, having
+* already said so: Playwright missing is a setup problem with a specific fix,
+* not a crash, and both commands turn it into exit 2.
+*/
+async function runEngine(pages, options) {
+	const runnerOptions = {
+		cwd: options.cwd,
+		...options.baseUrl === void 0 ? {} : { baseUrl: options.baseUrl },
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+	};
+	if (!options.browser) {
+		const { runPooledAudit } = await import("./pool-BO25OIez.js");
+		return runPooledAudit(pages, {
+			...runnerOptions,
+			...options.fast ? { fast: true } : {},
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency }
+		});
+	}
+	const { BrowserUnavailableError, runBrowserAudit } = await import("./playwright-BojtYVUa.js");
+	try {
+		return await runBrowserAudit(options.directory, pages, {
+			...runnerOptions,
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency }
+		});
+	} catch (cause) {
+		if (cause instanceof BrowserUnavailableError) {
+			fail(cause.message);
+			return;
+		}
+		throw cause;
+	}
+}
+/**
+* Write a document to `output`, or to stdout when there is none. Parent
+* directories are created, since a report path in CI usually names one that is
+* not there yet.
+*/
+async function emitDocument(body, output, cwd) {
+	if (output === void 0) {
+		process.stdout.write(body);
+		return;
+	}
+	const target = path.resolve(cwd, output);
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, body, "utf8");
+}
+/**
+* Audit defaults from the project's config file.
+*
+* `audit` and `baseline` are run from a build script over and over with the
+* same six flags, and the flags are the only place to say them: the config file
+* has existed since 0.2 and served the statement alone. An `audit` block there
+* is that list written once.
+*
+* Everything it returns is a default. The flags are merged over it by the
+* caller, because the file is the project's usual answer and a flag is somebody
+* asking for something else on this run.
+*
+* No config file at all is not an error, unlike for `statement`: this command
+* has always run against projects that have never heard of one. A file that
+* exists and cannot be read is exit 2 — it was written to be used, and running
+* on different settings than it names would be worse than stopping.
+*/
+async function auditDefaults(options = {}) {
+	const { loadAuditConfig } = await import("./load-CFq2VQtT.js");
+	const loaded = await loadAuditConfig({
+		...options.cwd ? { cwd: options.cwd } : {},
+		...options.config ? { path: options.config } : {}
+	});
+	if (!loaded?.audit) return {};
+	note(`Defaults from ${path.basename(loaded.path)}`);
+	return loaded.audit;
+}
+function auditInvocation(dir, defaults, flags) {
+	const { build, config: _config, ...typed } = flags;
+	const { dir: configDir, build: configBuild, ...fromConfig } = defaults;
+	return {
+		dir: dir ?? configDir,
+		options: {
+			...fromConfig,
+			...typed,
+			...build === false || configBuild === false ? { noBuild: true } : {}
+		}
+	};
+}
+/**
+* The same, for `baseline`, which reads the defaults that mean the same thing
+* to it.
+*
+* Deliberately a subset. `output` names where the report goes for one command
+* and where the baseline goes for the other, so carrying it across would write
+* a baseline over the path somebody set aside for a report; `format`, `failOn`
+* and `baseline` all describe a verdict this command does not reach.
+*/
+function baselineInvocation(dir, defaults, flags) {
+	const { config: _config, ...typed } = flags;
+	return {
+		dir: dir ?? defaults.dir ?? "./dist",
+		options: {
+			...baselineDefaults(defaults),
+			...typed
+		}
+	};
+}
+function baselineDefaults(config) {
+	return pick(config, [
+		"include",
+		"exclude",
+		"baseUrl",
+		"url",
+		"allowRemote",
+		"ignoreRobots",
+		"sitemap",
+		"maxPages",
+		"maxDepth",
+		"browser",
+		"concurrency"
+	]);
+}
+/** Copies the keys that are actually set, so nothing spreads an undefined over a real value. */
+function pick(source, keys) {
+	const out = {};
+	for (const key of keys) if (source[key] !== void 0) out[key] = source[key];
+	return out;
+}
+//#endregion
+export { emitDocument as a, runEngine as c, baselineInvocation as i, warn as l, auditDefaults as n, fail as o, auditInvocation as r, note as s, advise as t };