eaa-kit 0.3.0 → 0.5.0

package/README.md

@@ -3,14 +3,17 @@
 [![CI](https://github.com/likeBloodMoon/eaa-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/likeBloodMoon/eaa-kit/actions/workflows/ci.yml)
 
 Build-time WCAG 2.2 AA auditor and EU accessibility statement generator for static sites,
-aimed at freelancers and small agencies in the DACH region who have to comply with the
-European Accessibility Act (in force since 28 June 2025), the BFSG in Germany and the BaFG
-in Austria.
+built for the freelancers and small agencies who have to comply with the European
+Accessibility Act (in force since 28 June 2025) without an accessibility budget. It started
+in the DACH region — the BFSG in Germany, the BaFG in Austria — and the statement now names
+the statute and supervisory body of **seven countries**: Austria, Germany, Switzerland,
+Spain, France, Italy and the Netherlands, each in its own language as well as English.
 
 ```bash
 npx eaa-kit audit                 # WCAG 2.2 AA report; finds your build itself
+npx eaa-kit diff a.json b.json    # what a change made worse, and what it fixed
 npx eaa-kit init                  # write an eaa.config.json
-npx eaa-kit statement             # Barrierefreiheitserklärung from that config
+npx eaa-kit statement             # accessibility statement, in one of seven countries
 ```
 
 > **Not legal advice.** eaa-kit reports what an automated engine can and cannot determine
@@ -32,7 +35,9 @@ supported here either.
 **Audits your build.** Globs the HTML out of `./dist`, parses it with jsdom and runs
 axe-core against it. No Chromium download, fast enough for CI, and it never fetches
 anything or executes your site's JavaScript. `--browser` swaps in real Chromium for the
-rules that need layout and CSS.
+rules that need layout and CSS; `--fast` goes the other way and skips the rules the
+browserless engine cannot decide anyway, rather than running them and discarding the
+answer.
 
 ```bash
 eaa-kit audit ./dist --fail-on serious
@@ -45,14 +50,21 @@ export, Nuxt, SvelteKit, anything behind a CMS — are audited running instead:
 eaa-kit audit --url http://localhost:3000
 ```
 
-**Writes the statement.** A Barrierefreiheitserklärung from one config file, in German or
-English, as Markdown or HTML, naming the statute and supervisory body of Austria,
-Switzerland or Germany — and optionally listing the barriers a real audit found.
+**Writes the statement.** A Barrierefreiheitserklärung, a déclaration d'accessibilité, a
+dichiarazione di accessibilità — whatever the country calls it — from one config file, as
+Markdown or HTML, naming that country's statute and supervisory body, and optionally
+listing the barriers a real audit found.
 
 ```bash
 eaa-kit statement --output src/content/a11y.md
+eaa-kit statement --country FR --lang fr    # or ES, IT, NL, AT, DE, CH
 ```
 
+Each country's statement is a document under its own law rather than a translation of
+another's, so where a national regime asks for more than this — France's RGAA declaration,
+Italy's filing with AgID — the text says so instead of letting a generated file look like
+it settles the matter.
+
 **Fails only on what is new.** The first run on a site that already exists finds
 everything at once. A baseline records what is already wrong so the build fails on
 regressions instead, without ever letting an accepted barrier look like a passing one.
@@ -62,23 +74,77 @@ eaa-kit baseline ./dist
 eaa-kit audit ./dist --baseline eaa-baseline.json
 ```
 
+**Says what a change did.** Two reports, and the difference between them: what is new, what
+was fixed, and what the later run never looked at — which is kept apart, because a
+violation missing from a run that stopped early was not fixed by anybody.
+
+```bash
+eaa-kit diff before.json after.json
+```
+
+**Says what to do about it.** Not "images must have alternative text" and a link — who the
+barrier stops, what to change, and the corrected form of *your* markup, in your framework's
+idiom where that differs. Deterministic and offline: no model, no API key, nothing that
+could invent a fix that looks right and is not.
+
+```
+✗ image-alt critical, WCAG 1.1.1
+    A screen reader announces this image by its filename, or skips it entirely.
+    Fix: Add alt text describing what the image conveys…
+    → <img src="/assets/logo.svg" alt="What this image shows">
+    written in src/components/Header.astro:12
+```
+
+**Says how much of WCAG it could reach.** WCAG 2.2 has 55 success criteria at Levels A and
+AA. axe-core has rules touching 23 of them. Every run says so, and `--coverage` lists all
+55 with what this run reached on each — never as a percentage, because most of WCAG cannot
+be automated and a score would present that as a fact about your site.
+
+**Says what it did not measure.** A crawl that stopped at its page limit, or could not
+fetch forty URLs, no longer produces a report that looks like a complete one.
+
 **Reports in four shapes**: a console report for whoever ran it, JSON for other tools,
 SARIF for GitHub code scanning, and a self-contained HTML page for the client whose site
 it is.
 
-**Runs in your build**, as a [Vite plugin](docs/integrations.md#vite-plugin) — covering
-SvelteKit, Nuxt and Remix too — an [Astro integration](docs/integrations.md#astro-integration),
-or the bundled [GitHub Action](docs/integrations.md#github-actions).
+**Says it once.** The flags a project runs on every build belong in the project, not in the
+build script that repeats them. `eaa.config` — the same file the statement reads — takes an
+[`audit` block](docs/audit.md#defaults-from-eaaconfig) of defaults, and `baseline` reads the
+keys that mean the same thing to it. A flag you type still wins, so a one-off `--browser`
+check needs no edit to a committed file.
+
+```jsonc
+{ "audit": { "dir": "build", "failOn": "critical", "browser": true } }
+```
+
+**Runs in your build**: a [Vite plugin](docs/integrations.md#vite-plugin) covering SvelteKit
+and Remix too, and integrations for
+[Astro](docs/integrations.md#astro-integration),
+[Nuxt](docs/integrations.md#nuxt-module),
+[Eleventy](docs/integrations.md#eleventy-plugin) and
+[webpack](docs/integrations.md#webpack-plugin) — or the bundled
+[GitHub Action](docs/integrations.md#github-actions).
+
+**Audits what a CMS serves.** WordPress, TYPO3, Craft, Laravel, Symfony, Rails and Django
+write no HTML to disk, so eaa-kit names the command that gets the site running and audits
+that instead — following the site's own sitemap, wherever it keeps it.
+
+```bash
+eaa-kit audit --url http://localhost:8000 --sitemap /sitemap_index.xml
+```
 
 ## Documentation
 
 | | |
 | --- | --- |
 | [Auditing a build](docs/audit.md) | The `audit` command, both engines, exit codes, and what an automated run can and cannot tell you |
-| [The statement command](docs/statement.md) | The config file, the three countries, and filling a statement from audit results |
+| [Defaults from eaa.config](docs/audit.md#defaults-from-eaaconfig) | Writing the flags down once, and what still overrides them |
+| [The statement command](docs/statement.md) | The config file, the seven countries, and filling a statement from audit results |
 | [Baselines](docs/baseline.md) | Adopting the tool on a site that already has violations |
+| [Comparing two runs](docs/reports.md#comparing-two-runs) | The `diff` command, and what it refuses to call fixed |
+| [Coverage of WCAG](docs/audit.md#how-much-of-wcag-a-run-reaches) | What an automated engine can reach at all, and what it cannot |
 | [Report formats](docs/reports.md) | The JSON contract, SARIF, and the HTML report |
-| [Integrations](docs/integrations.md) | Astro and GitHub Actions |
+| [Integrations](docs/integrations.md) | The build plugins, the GitHub Action, and the two builders that get a command instead |
 
 Complete generated output for every format is checked in under [examples/](examples).
 
@@ -90,7 +156,9 @@ The two things worth knowing before you rely on any of it:
 text is accurate, whether a page makes sense in reading order, or whether a form can
 actually be completed with a screen reader. A clean report means nothing was found by this
 engine, which is not the same as a site being accessible — and none of the four output
-formats will say otherwise on your behalf.
+formats will say otherwise on your behalf. This is not a disclaimer the tool leaves you to
+take on faith: it counts it. Of the 55 WCAG 2.2 A and AA criteria, 34 have no automated
+rule at all, and every report says so.
 
 **The browserless engine cannot decide everything.** jsdom has no layout, so rules that
 depend on rendering — colour contrast, target size, computed overflow — cannot be

package/dist/astro/index.d.ts

@@ -1,4 +1,4 @@
-import { n as IntegrationOptions } from "../run-BMASMmwO.js";
+import { n as IntegrationOptions } from "../run-CtcEUhbe.js";
 //#region src/astro/index.d.ts
 /**
  * An Astro integration that audits the build Astro just produced.

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { n as auditBuild, t as BuildAuditError } from "../run-BW6CVuND.js";
+import { n as auditBuild, t as BuildAuditError } from "../run-C2nKFcb-.js";
 import { fileURLToPath } from "node:url";
 //#region src/astro/index.ts
 var AstroAuditError = class extends Error {

package/dist/audit/runners/worker.js

@@ -1,4 +1,5 @@
-import { n as auditPage } from "../../jsdom-BjpF-2V-.js";
+import { t as auditPage } from "../../jsdom-B--cEH-G.js";
+import { enableCompileCache } from "node:module";
 import { parentPort, workerData } from "node:worker_threads";
 //#region src/audit/runners/worker.ts
 /**
@@ -17,6 +18,9 @@ import { parentPort, workerData } from "node:worker_threads";
 * something catastrophic — the thread running out of memory — reaches the
 * pool's error handler instead.
 */
+try {
+	enableCompileCache();
+} catch {}
 const port = parentPort;
 if (!port) throw new Error("eaa-kit audit worker was started outside a worker thread");
 const options = workerData ?? {};

package/dist/{audit-DcL73mOC.js → audit-B282A3EA.js}

@@ -1,8 +1,10 @@
-import { a as impactRank, i as impactLabel, r as countAtOrAbove } from "./impact-YdoOtFqm.js";
-import { n as count, t as collapse } from "./text-BFmNtMsV.js";
-import { a as groupIssues, i as coverageParts, n as understandingUrl, o as isShared, r as blindRules, t as manualCheckFor } from "./manual-Vz-oX1I_.js";
-import { a as runEngine, i as note, n as emitDocument, o as warn, r as fail, t as advise } from "./command-Dxpa00Ha.js";
-import { n as collectPages, r as emptyDirectoryHint, t as BuildDirectoryError } from "./collect-BkAQ0viT.js";
+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-CMBIrnpN.js";
+import { r as componentPath } from "./component-C3GL1Mnu.js";
+import { i as understandingUrl, n as coverageSummary, r as manualCheckFor, t as buildCoverage } from "./coverage-B_Y6l-Ra.js";
+import { a as emitDocument, c as runEngine, l as warn, o as fail, s as note, t as advise } from "./command-C3D7JWn6.js";
+import { i as holdsHtml, n as collectPages, r as emptyDirectoryHint, t as BuildDirectoryError } from "./collect-Cu1q9NTB.js";
 import path from "node:path";
 import pc from "picocolors";
 //#region src/audit/report/console.ts
@@ -47,6 +49,9 @@ function context(options) {
 		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) {
@@ -182,11 +187,15 @@ function summary(audits, ctx) {
 	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)];
-	if (ruleCount === 0) lines.push(line(ctx, `  No violations across ${pages}.`, ctx.c.green));
-	else {
+	const audited = audits.length - errored.length;
+	const lines = [line(ctx, "Summary", ctx.c.bold), ...completenessLines(ctx)];
+	if (ruleCount === 0 && audited === 0 && errored.length > 0) lines.push(line(ctx, "  Nothing was audited: no page could be read.", ctx.c.red));
+	else if (ruleCount === 0) {
+		const clean = errored.length > 0 || ctx.completeness && !ctx.completeness.complete ? `  No violations across the ${count(audited, "page")} 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}`,
+			text: `  ${count(ruleCount, "violation")} on ${withViolations.length} of ${count(audited, "page")}`,
 			paint: ctx.c.red
 		}, {
 			text: ` (${count(elementCount, "element")})`,
@@ -202,6 +211,74 @@ function summary(audits, ctx) {
 	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");
+		const verb = completeness.unreachable.length === 1 ? "was" : "were";
+		lines.push(line(ctx, `  ${completeness.unreachable.length} ${noun} could not be reached, and ${verb} 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;
 }
 /**
@@ -296,6 +373,7 @@ function issuesSection(audits, ctx) {
 			}] : []
 		]));
 		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));
@@ -305,6 +383,27 @@ function issuesSection(audits, ctx) {
 	}
 	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);
@@ -313,7 +412,7 @@ function whereLines(element, ctx) {
 	const lines = component === void 0 ? [] : [render(ctx, [{
 		text: "        written in ",
 		paint: ctx.c.dim
-	}, { text: component }])];
+	}, { 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);
@@ -364,16 +463,22 @@ async function resolvePages(directory, options = {}) {
 		return {
 			pages: crawled.pages,
 			origin: crawled.origin,
-			label: options.url
+			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 } : {}
+			...options.exclude ? { exclude: options.exclude } : {},
+			onUnreadable: (relativePath, reason) => unreachable.push({
+				location: relativePath,
+				reason
+			})
 		});
 	} catch (cause) {
 		if (!(cause instanceof BuildDirectoryError)) throw cause;
@@ -382,12 +487,32 @@ async function resolvePages(directory, options = {}) {
 		return;
 	}
 	if (pages.length === 0) {
+		if ((options.include !== void 0 || options.exclude !== void 0) && await holdsHtml(directory)) {
+			warn(`No page in ${shown} matched the filters, so nothing was audited.`);
+			if (options.include !== void 0) note(`  --include ${options.include.join(" ")}`);
+			if (options.exclude !== void 0) note(`  --exclude ${options.exclude.join(" ")}`);
+			note("  Patterns are relative to the audited directory, with POSIX separators.");
+			return;
+		}
 		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
+		directory,
+		label: shown,
+		completeness: {
+			discovery: "directory",
+			collected: pages.length,
+			unreachable,
+			truncated: false
+		}
 	};
 }
 /**
@@ -397,7 +522,7 @@ async function resolvePages(directory, options = {}) {
 * exit 2 — a run that reached no verdict, not a clean one.
 */
 async function crawlPages(url, options) {
-	const { crawlSite, CrawlError, parseEntryUrl } = await import("./crawl-Oxt2Gaqo.js");
+	const { crawlSite, CrawlError, parseEntryUrl } = await import("./crawl-BUWPgaGW.js");
 	let entry;
 	try {
 		entry = parseEntryUrl(url, options.allowRemote ?? false);
@@ -412,6 +537,7 @@ async function crawlPages(url, options) {
 	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 }
@@ -432,7 +558,16 @@ async function crawlPages(url, options) {
 	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
+		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
+		}
 	};
 }
 /**
@@ -444,7 +579,7 @@ async function crawlPages(url, options) {
 */
 async function resolveAutomatically(options) {
 	const cwd = options.cwd ?? process.cwd();
-	const { autoDetectSource } = await import("./project-DW08TseF.js");
+	const { autoDetectSource } = await import("./project-MFrXcw1M.js");
 	const detected = await autoDetectSource(cwd, {
 		...options.noBuild ? { noBuild: true } : {},
 		onStep: note
@@ -485,12 +620,13 @@ const OUTPUT_FORMATS = [
 * piped somewhere without the chatter coming along.
 */
 async function runAuditCommand(dir, options = {}) {
+	if (options.fast && options.browser) warn("--fast has no effect with --browser: a real browser can decide those rules.");
 	const resolved = await resolvePages(dir, options);
 	if (!resolved) return {
 		audits: [],
 		exitCode: 2
 	};
-	const { pages, origin, label, cleanup } = resolved;
+	const { pages, origin, label, cleanup, directory, completeness: collection } = resolved;
 	try {
 		note(`Auditing ${count(pages.length, "page")} in ${label}${await describeEngine(pages, options)}…`);
 		const baseUrl = options.baseUrl ?? origin;
@@ -499,8 +635,9 @@ async function runAuditCommand(dir, options = {}) {
 			...baseUrl === void 0 ? {} : { baseUrl },
 			...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs },
 			...options.browser ? { browser: true } : {},
+			...options.fast && !options.browser ? { fast: true } : {},
 			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency },
-			...options.url === void 0 && dir !== void 0 ? { directory: dir } : {}
+			...directory === void 0 ? {} : { directory }
 		});
 		if (!audits) return {
 			audits: [],
@@ -515,7 +652,8 @@ async function runAuditCommand(dir, options = {}) {
 			};
 			audits = applied;
 		}
-		await emit(audits, label, failOn, options);
+		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`);
@@ -541,7 +679,7 @@ async function runAuditCommand(dir, options = {}) {
 * would be as wrong as silently passing.
 */
 async function acceptBaseline(audits, options) {
-	const { applyBaseline, BaselineError, readBaseline } = await import("./baseline-CuKFq4IF.js");
+	const { applyBaseline, BaselineError, readBaseline } = await import("./baseline-0u4df12v.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`);
@@ -568,52 +706,66 @@ async function acceptBaseline(audits, options) {
 */
 async function describeEngine(pages, options) {
 	if (options.browser) return " with Chromium";
-	const { plannedWorkers } = await import("./pool-BWkWZiJW.js");
+	const { plannedWorkers } = await import("./pool-BO25OIez.js");
 	const workers = options.concurrency ?? plannedWorkers(pages);
-	return workers > 1 ? ` across ${workers} threads` : "";
+	const threads = workers > 1 ? ` across ${workers} threads` : "";
+	return options.fast ? `${threads}, skipping what this engine cannot decide` : 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);
+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, format, toFile, options) {
+async function renderReport(audits, dir, failOn, completeness, format, toFile, options) {
 	switch (format) {
 		case "json": {
-			const { buildJsonReport, serialiseJsonReport } = await import("./json-B0Y7rNjt.js");
+			const { buildJsonReport, serialiseJsonReport } = await import("./json-D_Mnnft5.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-DB3WG7T9.js");
-			return serialiseSarifReport(buildSarifReport(audits, { directory: dir }));
+			const { buildSarifReport, serialiseSarifReport } = await import("./sarif-B-UBcVu8.js");
+			return serialiseSarifReport(buildSarifReport(audits, {
+				directory: dir,
+				completeness
+			}));
 		}
 		case "html": {
-			const { buildHtmlReport } = await import("./html-DKiI_3gs.js");
+			const { buildHtmlReport } = await import("./html-C4vktg0A.js");
+			const framework = await detectedFramework(options.cwd ?? process.cwd());
 			return buildHtmlReport(audits, {
-				...await sourceLookups(options.cwd ?? process.cwd()),
+				...await sourceLookups(options.cwd ?? process.cwd(), audits),
 				directory: dir,
 				failOn,
+				completeness,
+				...framework === void 0 ? {} : { framework },
 				...options.baseUrl ? { baseUrl: options.baseUrl } : {}
 			});
 		}
-		case "console": return `${formatConsoleReport(audits, {
-			...await sourceLookups(options.cwd ?? process.cwd()),
-			dir,
-			failOn,
-			...options.perPage ? { perPage: true } : {},
-			...options.manual ? { manual: true } : {},
-			...toFile ? { color: false } : {}
-		})}\n`;
+		case "console": {
+			const framework = await detectedFramework(options.cwd ?? process.cwd());
+			return `${formatConsoleReport(audits, {
+				...await sourceLookups(options.cwd ?? process.cwd(), audits),
+				dir,
+				failOn,
+				completeness,
+				...options.perPage ? { perPage: true } : {},
+				...options.manual ? { manual: true } : {},
+				...options.coverage ? { coverage: true } : {},
+				...framework === void 0 ? {} : { framework },
+				...toFile ? { color: false } : {}
+			})}\n`;
+		}
 	}
 }
 /**
@@ -621,15 +773,29 @@ async function renderReport(audits, dir, failOn, format, toFile, options) {
 * so. Best-effort: a project using no convention this recognises gets the
 * report it always got, with no source named.
 */
-async function sourceLookups(cwd) {
-	const { buildRouteMap, sourceFor } = await import("./routes-C2Cgf6Ko.js");
-	const { buildComponentIndex, componentFor } = await import("./component-7kEBjv_y.js");
+/** 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, audits) {
+	const { buildRouteMap, sourceFor } = await import("./routes-CmdRUuOs.js");
 	const routes = await buildRouteMap(cwd);
+	if (!hasElementsToAttribute(audits)) return {
+		sourceFor: (page) => sourceFor(routes, page),
+		componentFor: () => void 0
+	};
+	const { buildComponentIndex, componentFor } = await import("./component-DKd3EHOg.js");
 	const components = await buildComponentIndex(cwd);
 	return {
 		sourceFor: (page) => sourceFor(routes, page),
 		componentFor: (html) => componentFor(components, html)
 	};
 }
+/** Whether any element will be listed, and so looked up against the source. */
+function hasElementsToAttribute(audits) {
+	return audits.some((audit) => audit.violations.length > 0 || (audit.accepted?.length ?? 0) > 0);
+}
 //#endregion
 export { runAuditCommand as n, resolvePages as r, OUTPUT_FORMATS as t };

package/dist/audit-DyHPmGeD.js

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

package/dist/{baseline-CuKFq4IF.js → baseline-0u4df12v.js}

@@ -1,2 +1,2 @@
-import { a as readBaseline, r as applyBaseline, t as BaselineError } from "./baseline-s9F3fXTN.js";
+import { a as readBaseline, r as applyBaseline, t as BaselineError } from "./baseline-CuAS2lMk.js";
 export { BaselineError, applyBaseline, readBaseline };

package/dist/{baseline-s9F3fXTN.js → baseline-CuAS2lMk.js}

@@ -1,6 +1,6 @@
-import { _ as withDefault, c as object, f as safeParse, i as isoDate$1, l as optional, o as nullable, p as string, s as number, t as array } from "./schema-CMZ8ItGk.js";
-import { t as elementFingerprint } from "./fingerprint-DRoneAjj.js";
-import { r as findingElements } from "./result-DLxd2Eip.js";
+import { c as nullable, d as optional, h as string, l as number, m as safeParse, o as isoDate$1, t as array, u as object, y as withDefault } from "./schema-DJSF4K05.js";
+import { t as elementFingerprint } from "./fingerprint-BjYV_0F7.js";
+import { o as findingElements } from "./result-BWcYXeRs.js";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 /** Default filename, used by the CLI when no path is given. */
@@ -109,7 +109,7 @@ function buildBaseline(audits, options = {}) {
 		...options.note ? { note: options.note } : {}
 	});
 	return {
-		schemaVersion: 1,
+		schemaVersion: 2,
 		createdOn: acceptedOn,
 		entries: entries.sort(byEntry)
 	};
@@ -137,7 +137,8 @@ async function readBaseline(file, cwd = process.cwd()) {
 		const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "document"}: ${issue.message}`).slice(0, 5);
 		throw new BaselineError(`${path.basename(target)} is not an eaa-kit baseline (${issues.join("; ")})`);
 	}
-	if (result.data.schemaVersion !== 1) throw new BaselineError(`${path.basename(target)} has schemaVersion ${result.data.schemaVersion}; this version of eaa-kit reads 1`);
+	if (result.data.schemaVersion !== 2) throw new BaselineError(`${path.basename(target)} has schemaVersion ${result.data.schemaVersion}; this version of eaa-kit reads 2.\n  Record it again on the current build: eaa-kit baseline\n  Read the new file before committing it: it lists what this run found, which is
+  not necessarily what the old one accepted.`);
 	return result.data;
 }
 async function writeBaseline(file, baseline, cwd = process.cwd()) {