eaa-kit 0.4.0 → 0.6.0

package/dist/command-CZKp9Wi_.js

@@ -0,0 +1,251 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pc from "picocolors";
+//#region src/audit/headers.ts
+/**
+* Request headers for the pages this tool fetches.
+*
+* The two places a small agency stages work are the two this tool could not
+* reach: a preview deployment, which every host protects by default, and a CMS
+* staging site behind basic auth or a session cookie. `--url` sent one fixed
+* pair of headers and had no way to add to it, so auditing either meant putting
+* the site on the public internet first.
+*
+* These values are credentials. They are handled on the principle that the tool
+* never writes one down: nothing here reaches a report, a baseline, a SARIF log
+* or the completeness record, and the errors below name the header rather than
+* echoing what was typed, because a malformed `--header` is exactly the case
+* where the value is a token and the terminal is a CI log.
+*
+* For the same reason there is no `headers` key in `eaa.config`. That file is
+* committed; a token in it is a token in the repository, and a tool that
+* offered the field would be inviting that. Pass them as flags — a shell
+* expands `--header "Authorization: Bearer $TOKEN"` — or as the GitHub Action's
+* input, which reads from `secrets`.
+*/
+/** Thrown for a header this cannot parse. Never carries the value. */
+var HeaderError = class extends Error {
+	name = "HeaderError";
+};
+/**
+* `Name: value` into a pair.
+*
+* Lenient about the space after the colon and about a value containing colons,
+* which `Authorization: Basic …` and a `Cookie` both do. Strict about the name,
+* because a header name is a token by RFC 9110 and anything else is a typo that
+* a server would reject in a way nobody could read.
+*/
+function parseHeader(input) {
+	const at = input.indexOf(":");
+	if (at <= 0) throw new HeaderError("a header must be written \"Name: value\"");
+	const name = input.slice(0, at).trim();
+	const value = input.slice(at + 1).trim();
+	if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name)) throw new HeaderError(`"${name}" is not a valid header name`);
+	if (value === "") throw new HeaderError(`the ${name} header was given no value`);
+	if (/[\r\n]/.test(value)) throw new HeaderError(`the ${name} header contains a line break`);
+	return [name, value];
+}
+/** Several `Name: value` strings into the record the fetchers take. */
+function parseHeaders(inputs) {
+	const headers = {};
+	for (const input of inputs) {
+		const [name, value] = parseHeader(input);
+		headers[name] = value;
+	}
+	return headers;
+}
+/**
+* `user:password` into an `Authorization` header.
+*
+* Sugar for the header somebody would otherwise have to base64 by hand, which
+* is the one credential a staging site is most likely to be behind. A password
+* may contain colons; a username may not, which is basic auth's own rule.
+*/
+function basicAuth(input) {
+	if (input.indexOf(":") <= 0) throw new HeaderError("basic auth must be written \"user:password\"");
+	return ["Authorization", `Basic ${Buffer.from(input, "utf8").toString("base64")}`];
+}
+/**
+* The headers a run will send, from whichever flags were given.
+*
+* `--basic-auth` first, so an explicit `--header "Authorization: …"` beats it:
+* a typed header is the more specific thing to have asked for.
+*/
+function requestHeaders(options) {
+	const headers = {};
+	if (options.basicAuth !== void 0) {
+		const [name, value] = basicAuth(options.basicAuth);
+		headers[name] = value;
+	}
+	Object.assign(headers, parseHeaders(options.header ?? []));
+	return Object.keys(headers).length === 0 ? void 0 : headers;
+}
+//#endregion
+//#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-dkexq5xo.js");
+		return runPooledAudit(pages, {
+			...runnerOptions,
+			...options.fast ? { fast: true } : {},
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency }
+		});
+	}
+	const { BrowserUnavailableError, runBrowserAudit } = await import("./playwright-C-miJP2b.js");
+	try {
+		return await runBrowserAudit(options.directory, pages, {
+			...runnerOptions,
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency },
+			...options.headers === void 0 ? {} : { headers: options.headers }
+		});
+	} 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-Bc_xDGAh.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, header, basicAuth, ...typed } = flags;
+	const { dir: configDir, build: configBuild, headers: _fromFile, ...fromConfig } = defaults;
+	const headers = requestHeaders({
+		...header ? { header } : {},
+		...basicAuth ? { basicAuth } : {}
+	});
+	return {
+		dir: dir ?? configDir,
+		options: {
+			...fromConfig,
+			...typed,
+			...build === false || configBuild === false ? { noBuild: true } : {},
+			...headers === void 0 ? {} : { headers }
+		}
+	};
+}
+/**
+* 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, header, basicAuth, ...typed } = flags;
+	const headers = requestHeaders({
+		...header ? { header } : {},
+		...basicAuth ? { basicAuth } : {}
+	});
+	return {
+		dir: dir ?? defaults.dir ?? "./dist",
+		options: {
+			...baselineDefaults(defaults),
+			...typed,
+			...headers === void 0 ? {} : { headers }
+		}
+	};
+}
+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, parseHeader as d, baselineInvocation as i, warn as l, auditDefaults as n, fail as o, auditInvocation as r, note as s, advise as t, basicAuth as u };

package/dist/{remediation-Dtowi2EC.js → completeness-Dwq3CPB3.js}

@@ -1,45 +1,6 @@
-import { a as impactRank } from "./impact-DZt2oBCP.js";
-import { t as elementFingerprint } from "./fingerprint-DRoneAjj.js";
-import { a as findingElements } from "./result-DoamKFsp.js";
-//#region src/audit/completeness.ts
-/**
-* Fold what the collector knew together with what the engine managed.
-*
-* The audits carry the second half: a page with an `error` was collected and
-* then not audited, and is as unmeasured as one that was never fetched.
-*/
-function runCompleteness(audits, collection) {
-	const errored = audits.filter((audit) => audit.error).length;
-	return {
-		...collection,
-		audited: audits.length - errored,
-		errored,
-		complete: collection.unreachable.length === 0 && !collection.truncated && errored === 0
-	};
-}
-/**
-* What was missed, as phrases both reports print.
-*
-* Separate clauses rather than one total, for the same reason the coverage
-* parts are: a page that could not be fetched and a page that could not be
-* parsed are different problems with different fixes, and summing them would
-* name neither.
-*/
-function missedParts(completeness) {
-	const parts = [];
-	if (completeness.unreachable.length > 0) parts.push(`${completeness.unreachable.length} could not be reached`);
-	if (completeness.errored > 0) parts.push(`${completeness.errored} could not be audited`);
-	if (completeness.truncated) parts.push("the run stopped at its page limit");
-	return parts;
-}
-/** How the pages were found, in words, for the run details both reports show. */
-function discoveryLabel(discovery) {
-	switch (discovery) {
-		case "directory": return "files in the build directory";
-		case "sitemap": return "sitemap.xml and links";
-		case "links": return "links from the entry page";
-	}
-}
+import { o as impactRank } from "./impact-luGCnN8F.js";
+import { t as elementFingerprint } from "./fingerprint-BjYV_0F7.js";
+import { o as findingElements } from "./result-DfUru6y_.js";
 /** Whether this element looks like one component rendered on many pages. */
 function isShared(element) {
 	return element.pages.length >= 3;
@@ -95,6 +56,23 @@ function groupIssues(audits) {
 	return issues;
 }
 /**
+* What the grouped issues add up to: distinct elements, and the violations they
+* account for. Both reports open their issues section with these two numbers,
+* and say something different when they are equal.
+*/
+function issueTotals(issues) {
+	let elements = 0;
+	let occurrences = 0;
+	for (const issue of issues) {
+		elements += issue.elements.length;
+		occurrences += issue.occurrences;
+	}
+	return {
+		elements,
+		occurrences
+	};
+}
+/**
 * Unevaluated rules folded across the site, sorted by rule id.
 *
 * Both reports list these once at the end rather than under every page: on a
@@ -318,4 +296,44 @@ function remediationFor(ruleId, framework) {
 	};
 }
 //#endregion
-export { isShared as a, runCompleteness as c, groupIssues as i, blindRules as n, discoveryLabel as o, coverageParts as r, missedParts as s, remediationFor as t };
+//#region src/audit/completeness.ts
+/**
+* Fold what the collector knew together with what the engine managed.
+*
+* The audits carry the second half: a page with an `error` was collected and
+* then not audited, and is as unmeasured as one that was never fetched.
+*/
+function runCompleteness(audits, collection) {
+	const errored = audits.filter((audit) => audit.error).length;
+	return {
+		...collection,
+		audited: audits.length - errored,
+		errored,
+		complete: collection.unreachable.length === 0 && !collection.truncated && errored === 0
+	};
+}
+/**
+* What was missed, as phrases both reports print.
+*
+* Separate clauses rather than one total, for the same reason the coverage
+* parts are: a page that could not be fetched and a page that could not be
+* parsed are different problems with different fixes, and summing them would
+* name neither.
+*/
+function missedParts(completeness) {
+	const parts = [];
+	if (completeness.unreachable.length > 0) parts.push(`${completeness.unreachable.length} could not be reached`);
+	if (completeness.errored > 0) parts.push(`${completeness.errored} could not be audited`);
+	if (completeness.truncated) parts.push("the run stopped at its page limit");
+	return parts;
+}
+/** How the pages were found, in words, for the run details both reports show. */
+function discoveryLabel(discovery) {
+	switch (discovery) {
+		case "directory": return "files in the build directory";
+		case "sitemap": return "sitemap.xml and links";
+		case "links": return "links from the entry page";
+	}
+}
+//#endregion
+export { blindRules as a, isShared as c, remediationFor as i, issueTotals as l, missedParts as n, coverageParts as o, runCompleteness as r, groupIssues as s, discoveryLabel as t };

package/dist/{component-C3GL1Mnu.js → component-ChisoFyY.js}

@@ -1,5 +1,5 @@
 import { i as toPosix } from "./fs-BmPtmFke.js";
-import { t as collapse } from "./text-CKKpzkYM.js";
+import { t as collapse } from "./text-BF1LHMiV.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { glob } from "tinyglobby";

package/dist/{component-DKd3EHOg.js → component-DcCn3BJS.js}

@@ -1,2 +1,2 @@
-import { n as componentFor, t as buildComponentIndex } from "./component-C3GL1Mnu.js";
+import { n as componentFor, t as buildComponentIndex } from "./component-ChisoFyY.js";
 export { buildComponentIndex, componentFor };

package/dist/coverage-7bQqWNfN.js

@@ -0,0 +1,2 @@
+import { t as WCAG22_AA_CRITERIA } from "./coverage-BD2_CYns.js";
+export { WCAG22_AA_CRITERIA };

package/dist/{coverage-B4IBKMO8.js → coverage-BD2_CYns.js}

@@ -1,4 +1,5 @@
-import { n as ENGINE_BLIND_RULES, t as DEFAULT_TAGS, u as successCriteria } from "./result-DoamKFsp.js";
+import { d as successCriteria, n as DEFAULT_TAGS, r as ENGINE_BLIND_RULES } from "./result-DfUru6y_.js";
+import { s as criterionReview } from "./review-CdMK2GpQ.js";
 import axe from "axe-core";
 //#region src/audit/manual.ts
 /**
@@ -463,10 +464,11 @@ function blindedRules(audits) {
 * the criterion is met on this site, and saying otherwise would be a coverage
 * claim resting on an empty page.
 */
-function buildCoverage(audits, tags = DEFAULT_TAGS) {
+function buildCoverage(audits, tags = DEFAULT_TAGS, review) {
 	const byCriterion = rulesByCriterion(tags);
 	const decided = decidedRules(audits);
 	const blinded = blindedRules(audits);
+	const jsdomBlindApplies = audits.length === 0 || audits.some((audit) => audit.engine !== "browser");
 	const criteria = WCAG22_AA_CRITERIA.map((criterion) => {
 		const rules = byCriterion.get(criterion.number) ?? [];
 		if (rules.length === 0) return {
@@ -481,7 +483,7 @@ function buildCoverage(audits, tags = DEFAULT_TAGS) {
 			rules,
 			browserWouldAnswer: false
 		};
-		const engineBlind = rules.filter((rule) => blinded.has(rule) || ENGINE_BLIND_RULES[rule] !== void 0);
+		const engineBlind = rules.filter((rule) => blinded.has(rule) || jsdomBlindApplies && ENGINE_BLIND_RULES[rule] !== void 0);
 		if (engineBlind.length > 0) return {
 			...criterion,
 			status: "not-evaluated",
@@ -495,15 +497,36 @@ function buildCoverage(audits, tags = DEFAULT_TAGS) {
 			browserWouldAnswer: false
 		};
 	});
-	const count = (status) => criteria.filter((criterion) => criterion.status === status).length;
+	const reviewed = review === void 0 ? criteria : criteria.map(withReview(review));
+	const count = (status) => reviewed.filter((criterion) => criterion.status === status).length;
+	const counted = reviewed.filter((criterion) => criterion.review?.counts === true);
 	return {
-		criteria,
+		criteria: reviewed,
 		evaluated: count("evaluated"),
 		notEvaluated: count("not-evaluated"),
 		nothingToCheck: count("nothing-to-check"),
 		noAutomatedRule: count("no-automated-rule"),
-		browserWouldAnswer: criteria.filter((criterion) => criterion.browserWouldAnswer).length,
-		total: WCAG22_AA_CRITERIA.length
+		browserWouldAnswer: reviewed.filter((criterion) => criterion.browserWouldAnswer).length,
+		total: WCAG22_AA_CRITERIA.length,
+		reviewed: counted.length,
+		reviewedNotMet: counted.filter((criterion) => criterion.review?.result === "not-met").length,
+		reviewNotCounted: reviewed.filter((criterion) => criterion.review?.counts === false).length
+	};
+}
+/**
+* Attach what a person recorded, without letting it move what the engine found.
+*
+* `status` is untouched here, deliberately and in every branch: a review adds a
+* second kind of claim beside the run's own, and the moment it could rewrite
+* one the report would stop being a record of what was measured.
+*/
+function withReview(review) {
+	return (criterion) => {
+		const recorded = criterionReview(criterion.number, review, criterion.status === "evaluated");
+		return recorded === void 0 ? criterion : {
+			...criterion,
+			review: recorded
+		};
 	};
 }
 /**
@@ -517,5 +540,20 @@ function coverageSummary(coverage) {
 	const unautomatable = coverage.noAutomatedRule;
 	return `Of the ${coverage.total} WCAG 2.2 A and AA success criteria, ${unautomatable} cannot be checked by any automated engine and need a person. This run reached a verdict on ${coverage.evaluated}.`;
 }
+/**
+* What a person added to the run, in one sentence, or nothing when nobody did.
+*
+* Kept out of `coverageSummary` so the sentence about the engine's reach does
+* not change shape depending on whether a review was supplied — and because a
+* reader has to be able to tell the two claims apart at a glance: one is what
+* an engine measured, the other is what somebody says they checked.
+*/
+function reviewSummary(coverage) {
+	if (coverage.reviewed === 0 && coverage.reviewNotCounted === 0) return void 0;
+	const parts = [`A person recorded a result for ${coverage.reviewed} of the criteria this run did not reach`];
+	if (coverage.reviewedNotMet > 0) parts.push(`${coverage.reviewedNotMet} of them as not met`);
+	if (coverage.reviewNotCounted > 0) parts.push(`${coverage.reviewNotCounted} further entries were not counted`);
+	return `${parts.join("; ")}. This is a claim by a person, not a measurement.`;
+}
 //#endregion
-export { understandingUrl as i, coverageSummary as n, manualCheckFor as r, buildCoverage as t };
+export { rulesByCriterion as a, reviewSummary as i, buildCoverage as n, manualCheckFor as o, coverageSummary as r, understandingUrl as s, WCAG22_AA_CRITERIA as t };