eaa-kit 0.1.0

package/dist/baseline-DQTnNlc4.js

@@ -0,0 +1,169 @@
+import { t as elementFingerprint } from "./fingerprint-DRoneAjj.js";
+import { z } from "zod";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** Default filename, used by the CLI when no path is given. */
+const DEFAULT_BASELINE_FILE = "eaa-baseline.json";
+const entrySchema = z.object({
+	/** Page path relative to the audited directory, POSIX separators. */
+	page: z.string(),
+	ruleId: z.string(),
+	/** Identity of the element, from elementFingerprint. */
+	fingerprint: z.string(),
+	/** Carried for readability only; matching never looks at these. */
+	selector: z.string().default(""),
+	help: z.string().default(""),
+	impact: z.string().nullable().default(null),
+	/** ISO date the entry was written. */
+	acceptedOn: z.string().default(""),
+	/** ISO date after which this entry stops suppressing anything. */
+	expiresOn: z.iso.date().optional(),
+	/** Why this is being lived with. Free text, for whoever reads the file. */
+	note: z.string().optional()
+});
+const baselineSchema = z.object({
+	schemaVersion: z.number(),
+	createdOn: z.string().default(""),
+	entries: z.array(entrySchema).default([])
+});
+var BaselineError = class extends Error {
+	name = "BaselineError";
+};
+/**
+* Move the violations a baseline accounts for out of the failing set.
+*
+* Returns new audit objects; the ones passed in are not touched, so a caller
+* can still report on what the run actually found.
+*/
+function applyBaseline(audits, baseline, options = {}) {
+	const today = isoDate(options.today ?? /* @__PURE__ */ new Date());
+	const expired = baseline.entries.filter((entry) => entry.expiresOn !== void 0 && entry.expiresOn < today);
+	const live = /* @__PURE__ */ new Map();
+	for (const entry of baseline.entries) {
+		if (entry.expiresOn !== void 0 && entry.expiresOn < today) continue;
+		live.set(key(entry.page, entry.ruleId, entry.fingerprint), entry);
+	}
+	const matched = /* @__PURE__ */ new Set();
+	let accepted = 0;
+	const next = audits.map((audit) => {
+		const violations = [];
+		const acceptedFindings = [];
+		for (const finding of audit.violations) {
+			const kept = [];
+			const waived = [];
+			for (const node of finding.nodes) {
+				const id = key(audit.relativePath, finding.ruleId, elementFingerprint(finding.ruleId, node.target.join(" "), node.html));
+				if (live.has(id)) {
+					matched.add(id);
+					waived.push(node);
+				} else kept.push(node);
+			}
+			if (finding.nodes.length === 0) {
+				const id = key(audit.relativePath, finding.ruleId, elementFingerprint(finding.ruleId, "", ""));
+				if (live.has(id)) {
+					matched.add(id);
+					acceptedFindings.push(finding);
+					continue;
+				}
+				violations.push(finding);
+				continue;
+			}
+			if (waived.length > 0) {
+				accepted += waived.length;
+				acceptedFindings.push({
+					...finding,
+					nodes: waived
+				});
+			}
+			if (kept.length > 0) violations.push({
+				...finding,
+				nodes: kept
+			});
+		}
+		return {
+			...audit,
+			violations,
+			...acceptedFindings.length > 0 ? { accepted: acceptedFindings } : {}
+		};
+	});
+	const audited = new Set(audits.map((audit) => audit.relativePath));
+	return {
+		audits: next,
+		stale: [...live.entries()].filter(([id, entry]) => !matched.has(id) && audited.has(entry.page)).map(([, entry]) => entry).sort(byEntry),
+		expired: [...expired].sort(byEntry),
+		accepted
+	};
+}
+/** Record every violation a run found, so a later run can fail only on new ones. */
+function buildBaseline(audits, options = {}) {
+	const acceptedOn = isoDate(options.today ?? /* @__PURE__ */ new Date());
+	const entries = [];
+	for (const audit of audits) for (const finding of audit.violations) {
+		const nodes = finding.nodes.length > 0 ? finding.nodes.map((node) => ({
+			selector: node.target.join(" "),
+			html: node.html
+		})) : [{
+			selector: "",
+			html: ""
+		}];
+		for (const node of nodes) entries.push({
+			page: audit.relativePath,
+			ruleId: finding.ruleId,
+			fingerprint: elementFingerprint(finding.ruleId, node.selector, node.html),
+			selector: node.selector,
+			help: finding.help,
+			impact: finding.impact ?? null,
+			acceptedOn,
+			...options.expiresOn ? { expiresOn: options.expiresOn } : {},
+			...options.note ? { note: options.note } : {}
+		});
+	}
+	return {
+		schemaVersion: 1,
+		createdOn: acceptedOn,
+		entries: entries.sort(byEntry)
+	};
+}
+/** Serialised form, with a trailing newline, sorted so it diffs cleanly. */
+function serialiseBaseline(baseline) {
+	return `${JSON.stringify(baseline, null, 2)}\n`;
+}
+async function readBaseline(file, cwd = process.cwd()) {
+	const target = path.resolve(cwd, file);
+	let raw;
+	try {
+		raw = await readFile(target, "utf8");
+	} catch {
+		throw new BaselineError(`Could not read the baseline at ${file}. Create one with: eaa-kit baseline`);
+	}
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch (cause) {
+		throw new BaselineError(`${path.basename(target)} is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`);
+	}
+	const result = baselineSchema.safeParse(value);
+	if (!result.success) {
+		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`);
+	return result.data;
+}
+async function writeBaseline(file, baseline, cwd = process.cwd()) {
+	const target = path.resolve(cwd, file);
+	await mkdir(path.dirname(target), { recursive: true });
+	await writeFile(target, serialiseBaseline(baseline), "utf8");
+	return target;
+}
+function key(page, ruleId, fingerprint) {
+	return `${page}\u0000${ruleId}\u0000${fingerprint}`;
+}
+function byEntry(a, b) {
+	return a.page.localeCompare(b.page) || a.ruleId.localeCompare(b.ruleId) || a.fingerprint.localeCompare(b.fingerprint);
+}
+function isoDate(date) {
+	return date.toISOString().slice(0, 10);
+}
+//#endregion
+export { readBaseline as a, buildBaseline as i, DEFAULT_BASELINE_FILE as n, serialiseBaseline as o, applyBaseline as r, writeBaseline as s, BaselineError as t };

package/dist/baseline-Itspu3-Y.js

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

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli/index.js

@@ -0,0 +1,259 @@
+#!/usr/bin/env node
+import { f as COUNTRIES, h as STATEMENT_LOCALES, i as readAuditReport, l as loadConfig, o as StatementError, p as ConfigError, t as renderStatement } from "../render-K9KxDDSA.js";
+import { i as isImpactLevel, n as IMPACT_LEVELS, t as DEFAULT_FAIL_ON } from "../impact-DvgBjupx.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-DQTnNlc4.js";
+import { a as collectPages, i as BuildDirectoryError, n as isOutputFormat, r as runAuditCommand, t as OUTPUT_FORMATS } from "../audit-6gbV0Zjd.js";
+import { mkdir, writeFile } 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]`.
+*
+* Runs the same audit the audit command runs and writes down every violation it
+* found, so that a later run can fail on what is new instead of on everything.
+*
+* Deliberately a subcommand rather than a flag on `audit`. Accepting a set of
+* violations is a decision somebody makes once and commits to a file others
+* will read; folding it into the command that checks them would make it far too
+* easy to type by reflex when a build goes red, which is precisely the moment
+* it should take a deliberate act.
+*/
+async function runBaselineCommand(dir, options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	let pages;
+	try {
+		pages = await collectPages(path.resolve(cwd, dir), {
+			...options.include ? { include: options.include } : {},
+			...options.exclude ? { exclude: options.exclude } : {}
+		});
+	} catch (cause) {
+		if (cause instanceof BuildDirectoryError) {
+			process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+			return {
+				entries: 0,
+				exitCode: 2
+			};
+		}
+		throw cause;
+	}
+	if (pages.length === 0) {
+		process.stderr.write(`${pc.yellow("warning")} No HTML files found in ${dir}\n`);
+		return {
+			entries: 0,
+			exitCode: 2
+		};
+	}
+	process.stderr.write(pc.dim(`Auditing ${pages.length} ${pages.length === 1 ? "page" : "pages"} in ${dir}…\n`));
+	const runnerOptions = {
+		...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+		...options.timeoutMs === void 0 ? {} : { timeoutMs: options.timeoutMs }
+	};
+	let audits;
+	if (options.browser) {
+		const { BrowserUnavailableError, runBrowserAudit } = await import("../playwright-BfWuTG_u.js");
+		try {
+			audits = await runBrowserAudit(path.resolve(cwd, dir), pages, runnerOptions);
+		} catch (cause) {
+			if (cause instanceof BrowserUnavailableError) {
+				process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+				return {
+					entries: 0,
+					exitCode: 2
+				};
+			}
+			throw cause;
+		}
+	} else {
+		const { runPooledAudit } = await import("../pool-DixLeu8L.js");
+		audits = await runPooledAudit(pages, {
+			...runnerOptions,
+			...options.concurrency === void 0 ? {} : { concurrency: options.concurrency }
+		});
+	}
+	const unaudited = audits.filter((audit) => audit.error);
+	if (unaudited.length > 0) {
+		process.stderr.write(`${pc.red("error")} ${unaudited.length} of ${audits.length} pages could not be audited, so no baseline was written\n`);
+		return {
+			entries: 0,
+			exitCode: 2
+		};
+	}
+	const baseline = buildBaseline(audits, {
+		...options.note ? { note: options.note } : {},
+		...options.expiresOn ? { expiresOn: options.expiresOn } : {}
+	});
+	const target = options.output ?? "eaa-baseline.json";
+	try {
+		await writeBaseline(target, baseline, cwd);
+	} catch (cause) {
+		if (cause instanceof BaselineError) {
+			process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+			return {
+				entries: 0,
+				exitCode: 2
+			};
+		}
+		throw cause;
+	}
+	const count = baseline.entries.length;
+	process.stderr.write(pc.dim(`Wrote ${count} ${count === 1 ? "entry" : "entries"} to ${target}\n`));
+	if (count > 0) process.stderr.write(pc.yellow("These are barriers, not exceptions. Commit the file, then work the list down.\n"));
+	return {
+		entries: count,
+		exitCode: 0
+	};
+}
+//#endregion
+//#region src/cli/statement.ts
+/** Markdown for a content directory, HTML for dropping straight onto a site. */
+const STATEMENT_FORMATS = ["markdown", "html"];
+function isStatementFormat(value) {
+	return STATEMENT_FORMATS.includes(value);
+}
+/**
+* `eaa-kit statement`.
+*
+* The document goes to stdout and everything else to stderr, so it can be piped
+* straight into a file or a static site's content directory.
+*/
+async function runStatementCommand(options = {}) {
+	const format = options.format ?? formatFor(options.output);
+	try {
+		const { config, path: configPath } = await loadConfig({
+			...options.cwd ? { cwd: options.cwd } : {},
+			...options.config ? { path: options.config } : {}
+		});
+		let audit;
+		if (options.audit) audit = await readAuditReport(options.audit, options.cwd ?? process.cwd());
+		const statement = await renderStatement(config, {
+			...options.locale ? { locale: options.locale } : {},
+			...options.country ? { country: options.country } : {},
+			...audit ? { audit } : {}
+		});
+		process.stderr.write(pc.dim(`Statement for ${config.site.url} from ${path.basename(configPath)} (${statement.template}, ${format})\n`));
+		if (audit) {
+			process.stderr.write(pc.dim(`${audit.findings.length} ${audit.findings.length === 1 ? "barrier" : "barriers"} taken from ${path.basename(options.audit ?? "")}\n`));
+			if (audit.findings.length > 0) process.stderr.write(pc.yellow("Rewrite those descriptions in your own words before publishing.\n"));
+		}
+		const document = format === "html" ? statement.html : statement.markdown;
+		if (options.output) {
+			const target = path.resolve(options.cwd ?? process.cwd(), options.output);
+			await mkdir(path.dirname(target), { recursive: true });
+			await writeFile(target, document, "utf8");
+			process.stderr.write(pc.dim(`Written to ${options.output}\n`));
+		} else process.stdout.write(document);
+		process.stderr.write(pc.yellow("Review before publishing. This is a draft, not legal advice.\n"));
+		return {
+			document,
+			format,
+			exitCode: 0
+		};
+	} catch (cause) {
+		if (cause instanceof ConfigError || cause instanceof StatementError) {
+			process.stderr.write(`${pc.red("error")} ${cause.message}\n`);
+			if (cause instanceof ConfigError) for (const issue of cause.issues) process.stderr.write(pc.dim(`  ${issue}\n`));
+			return {
+				document: "",
+				format,
+				exitCode: 2
+			};
+		}
+		throw cause;
+	}
+}
+/**
+* `--output a11y.html` means HTML. Writing a full HTML document into a file
+* somebody named .html and then having it be markdown would be a worse surprise
+* than ignoring the extension, and `--format` still overrides this.
+*/
+function formatFor(output) {
+	return output && /\.html?$/i.test(output) ? "html" : "markdown";
+}
+//#endregion
+//#region src/cli/index.ts
+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", "./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("--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, options) => {
+	const { exitCode } = await runAuditCommand(dir, {
+		...Array.isArray(options["include"]) ? { include: options["include"] } : {},
+		...Array.isArray(options["exclude"]) ? { exclude: options["exclude"] } : {},
+		...typeof options["baseUrl"] === "string" ? { baseUrl: options["baseUrl"] } : {},
+		failOn: options["failOn"],
+		format: options["format"],
+		...typeof options["output"] === "string" ? { output: options["output"] } : {},
+		...options["browser"] === true ? { browser: true } : {},
+		...typeof options["concurrency"] === "number" ? { concurrency: options["concurrency"] } : {},
+		...typeof options["baseline"] === "string" ? { baseline: options["baseline"] } : {}
+	});
+	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("--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, options) => {
+	const { exitCode } = await runBaselineCommand(dir, {
+		...Array.isArray(options["include"]) ? { include: options["include"] } : {},
+		...Array.isArray(options["exclude"]) ? { exclude: options["exclude"] } : {},
+		...typeof options["baseUrl"] === "string" ? { baseUrl: options["baseUrl"] } : {},
+		...typeof options["output"] === "string" ? { output: options["output"] } : {},
+		...typeof options["note"] === "string" ? { note: options["note"] } : {},
+		...typeof options["expiresOn"] === "string" ? { expiresOn: options["expiresOn"] } : {},
+		...options["browser"] === true ? { browser: true } : {},
+		...typeof options["concurrency"] === "number" ? { concurrency: options["concurrency"] } : {}
+	});
+	process.exitCode = exitCode;
+});
+program.command("statement").description("Generate an EU accessibility statement from eaa.config").option("--config <path>", "path to the config file, otherwise it is searched for").option("--lang <locale>", `statement language (${STATEMENT_LOCALES.join("|")})`, parseLocale).option("--country <code>", `override the country template (${COUNTRIES.join("|")})`, parseCountry).option("--audit <path>", "list the barriers from an eaa-kit audit --format json report").option("--format <format>", `output format (${STATEMENT_FORMATS.join("|")}), otherwise from the --output extension`, parseStatementFormat).option("--output <path>", "write the statement to a file instead of stdout").action(async (options) => {
+	const { exitCode } = await runStatementCommand({
+		...typeof options["config"] === "string" ? { config: options["config"] } : {},
+		...options["lang"] ? { locale: options["lang"] } : {},
+		...options["country"] ? { country: options["country"] } : {},
+		...typeof options["audit"] === "string" ? { audit: options["audit"] } : {},
+		...options["format"] ? { format: options["format"] } : {},
+		...typeof options["output"] === "string" ? { output: options["output"] } : {}
+	});
+	process.exitCode = exitCode;
+});
+function parseLocale(value) {
+	if (!STATEMENT_LOCALES.includes(value)) throw new InvalidArgumentError(`expected one of ${STATEMENT_LOCALES.join(", ")}`);
+	return value;
+}
+function parseCountry(value) {
+	const upper = value.toUpperCase();
+	if (!COUNTRIES.includes(upper)) throw new InvalidArgumentError(`expected one of ${COUNTRIES.join(", ")}`);
+	return upper;
+}
+function parseStatementFormat(value) {
+	if (!isStatementFormat(value)) throw new InvalidArgumentError(`expected one of ${STATEMENT_FORMATS.join(", ")}`);
+	return value;
+}
+function parseDate(value) {
+	if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`))) throw new InvalidArgumentError("expected an ISO date, e.g. 2026-12-31");
+	return value;
+}
+function parseConcurrency(value) {
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new InvalidArgumentError("expected a whole number of 1 or more");
+	return parsed;
+}
+function parseImpact(value) {
+	if (!isImpactLevel(value)) throw new InvalidArgumentError(`expected one of ${IMPACT_LEVELS.join(", ")}`);
+	return value;
+}
+function parseFormat(value) {
+	if (!isOutputFormat(value)) throw new InvalidArgumentError(`expected one of ${OUTPUT_FORMATS.join(", ")}`);
+	return value;
+}
+try {
+	await program.parseAsync(process.argv);
+} catch (cause) {
+	const error = cause;
+	if (typeof error.exitCode === "number") process.exitCode = error.exitCode === 0 ? 0 : 2;
+	else {
+		process.stderr.write(`${cause instanceof Error ? cause.stack : String(cause)}\n`);
+		process.exitCode = 2;
+	}
+}
+//#endregion
+export {};

package/dist/escape-Dm1o_RAk.js

@@ -0,0 +1,21 @@
+//#region src/escape.ts
+/**
+* HTML escaping, shared by everything in this package that writes HTML.
+*
+* Both documents eaa-kit produces embed text it did not write: an issue
+* description from a config file, axe-core's help text, and — in the audit
+* report — the markup of the element that failed, which is by definition
+* arbitrary HTML from somebody's build. Getting this wrong in the report would
+* mean a page that fails an accessibility audit for having a stray `<script>`
+* hands that script to whoever opens the report.
+*/
+/** For text nodes. Leaves quotes alone, which are fine between tags. */
+function escapeText(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** For attribute values, where a quote would end the attribute. */
+function escapeAttribute(value) {
+	return escapeText(value).replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+//#endregion
+export { escapeText as n, escapeAttribute as t };

package/dist/fingerprint-DRoneAjj.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+//#region src/audit/fingerprint.ts
+/**
+* A stable identity for one violating element.
+*
+* Derived from the rule, the selector and the element's own markup, and
+* deliberately not from the file it was found in. Two consumers need this and
+* they need it to agree: SARIF, so that moving a page does not close one code
+* scanning alert and open an identical one, and the baseline, so that an
+* accepted violation stays accepted when the surrounding page changes.
+*
+* Sixteen hex characters. This identifies a defect for humans and tooling, not
+* a secret, and a full digest in every entry would make a baseline file for a
+* large site unreadable.
+*/
+function elementFingerprint(ruleId, selector, html) {
+	return createHash("sha256").update(`${ruleId}\n${selector}\n${html}`).digest("hex").slice(0, 16);
+}
+//#endregion
+export { elementFingerprint as t };