eaa-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristof Kolity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# eaa-kit
+
+[![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.
+
+```bash
+npx eaa-kit audit ./dist          # WCAG 2.2 AA report over built HTML
+npx eaa-kit statement             # Barrierefreiheitserklärung from eaa.config
+```
+
+> **Not legal advice.** eaa-kit reports what an automated engine can and cannot determine
+> about your markup. Automated testing catches a minority of accessibility barriers; it is
+> a floor, not a certificate.
+
+## Install
+
+```bash
+pnpm add -D eaa-kit    # npm i -D eaa-kit
+```
+
+Node 22.22 or newer. jsdom, which the browserless engine is built on, does not support
+Node 20.
+
+## What it does
+
+**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.
+
+```bash
+eaa-kit audit ./dist --fail-on serious
+```
+
+**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.
+
+```bash
+eaa-kit statement --output src/content/a11y.md
+```
+
+**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.
+
+```bash
+eaa-kit baseline ./dist
+eaa-kit audit ./dist --baseline eaa-baseline.json
+```
+
+**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 an [Astro integration](docs/integrations.md#astro-integration)
+or the bundled [GitHub Action](docs/integrations.md#github-actions).
+
+## 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 |
+| [Baselines](docs/baseline.md) | Adopting the tool on a site that already has violations |
+| [Report formats](docs/reports.md) | The JSON contract, SARIF, and the HTML report |
+| [Integrations](docs/integrations.md) | Astro and GitHub Actions |
+
+Complete generated output for every format is checked in under [examples/](examples).
+
+## What it will not tell you
+
+The two things worth knowing before you rely on any of it:
+
+**Automated testing finds a minority of barriers.** It cannot judge whether alternative
+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.
+
+**The browserless engine cannot decide everything.** jsdom has no layout, so rules that
+depend on rendering — colour contrast, target size, computed overflow — cannot be
+evaluated. axe-core does not know that and will report some of them as *passing*. eaa-kit
+never passes those on: they are reported as **not evaluated**, with the reason, whatever
+axe-core said about them. See [what the browserless engine can and cannot tell
+you](docs/audit.md#what-the-browserless-engine-can-and-cannot-tell-you).
+
+The same applies to the statement: it says what you told it. eaa-kit cannot check whether
+those claims are true, and a statement claiming full conformance for a site that is not
+conformant is worse than no statement at all.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT

package/dist/astro/index.d.ts

@@ -0,0 +1,90 @@
+import { t as ImpactLevel } from "../impact-EEB9ZXmC.js";
+//#region src/cli/audit.d.ts
+/**
+ * The engines and the machine-readable reporters are imported where they are
+ * used, not at the top of the file.
+ *
+ * jsdom costs 630 ms to load and axe-core another 94 ms, and a static import
+ * here charges that to every invocation — `eaa-kit statement`, `--help` and a
+ * mistyped flag included, none of which parse a single page. The audit path
+ * pays the same cost either way, a few milliseconds later.
+ */
+declare const OUTPUT_FORMATS: readonly ['console', 'json', 'sarif', 'html'];
+type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+//#endregion
+//#region src/astro/index.d.ts
+/**
+ * An Astro integration that audits the build Astro just produced.
+ *
+ * `astro build` already knows where the output went and when it finished, which
+ * is the one moment a build-time auditor wants. Wiring the CLI into a project's
+ * scripts works, but it means remembering to, and it means the audit runs in a
+ * separate step that is easy to drop from a pipeline when it goes red.
+ *
+ * The Astro types are described structurally here rather than imported. Astro is
+ * an optional peer dependency, exactly like Playwright, and a published .d.ts
+ * that referenced `astro` would fail to typecheck for everyone who installed
+ * this package without it. The shapes below are checked against the real
+ * `AstroIntegration` type at compile time in the tests, and the integration is
+ * driven by an actual `astro build` there, so the structural copy cannot drift
+ * from the API it stands in for.
+ */
+/** The part of Astro's integration logger this uses. */
+interface AstroLoggerLike {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+interface BuildDoneOptions {
+  /** Where Astro wrote the build. */
+  dir: URL;
+  logger: AstroLoggerLike;
+}
+interface AstroIntegrationLike {
+  name: string;
+  hooks: {
+    'astro:build:done'?: (options: BuildDoneOptions) => void | Promise<void>;
+  };
+}
+interface EaaKitIntegrationOptions {
+  /** Lowest impact that fails the build. Defaults to 'serious'. */
+  failOn?: ImpactLevel;
+  /**
+   * Whether a failing audit fails the build. Defaults to true.
+   *
+   * The CLI has no equivalent because a shell can ignore an exit code; a build
+   * hook cannot. Turning this off is for the first week of adopting the tool on
+   * an existing site — after that, a baseline is the honest way to go green,
+   * because it records what is wrong instead of hiding it.
+   */
+  failBuild?: boolean;
+  /** Skip the audit entirely. For turning it off by environment. */
+  enabled?: boolean;
+  include?: string[];
+  exclude?: string[];
+  /** Audit pages under their real site URL instead of file://. */
+  baseUrl?: string;
+  /** Audit in real Chromium. Needs the playwright peer. */
+  browser?: boolean;
+  /** Worker threads for the browserless engine. */
+  concurrency?: number;
+  /** Accept the violations recorded in this file; fail only on new ones. */
+  baseline?: string;
+  /** Write a report as well as printing one. */
+  format?: OutputFormat;
+  /** Where to write it. Required for `format` to do anything useful. */
+  output?: string;
+}
+declare class AstroAuditError extends Error {
+  readonly name = "AstroAuditError";
+}
+/**
+ * Audit the build in `astro:build:done`, and fail the build if it does not pass.
+ *
+ * Failing by default is the point: an auditor that only ever prints is one
+ * nobody reads. `failBuild: false` is there for the week it takes to adopt it,
+ * and `baseline` is the answer after that.
+ */
+declare function eaaKit(options?: EaaKitIntegrationOptions): AstroIntegrationLike;
+//#endregion
+export { AstroAuditError, AstroIntegrationLike, AstroLoggerLike, BuildDoneOptions, EaaKitIntegrationOptions, eaaKit as default };

package/dist/astro/index.js

@@ -0,0 +1,48 @@
+import { fileURLToPath } from "node:url";
+//#region src/astro/index.ts
+var AstroAuditError = class extends Error {
+	name = "AstroAuditError";
+};
+/**
+* Audit the build in `astro:build:done`, and fail the build if it does not pass.
+*
+* Failing by default is the point: an auditor that only ever prints is one
+* nobody reads. `failBuild: false` is there for the week it takes to adopt it,
+* and `baseline` is the answer after that.
+*/
+function eaaKit(options = {}) {
+	return {
+		name: "eaa-kit",
+		hooks: { "astro:build:done": async ({ dir, logger }) => {
+			if (options.enabled === false) {
+				logger.info("skipped (enabled: false)");
+				return;
+			}
+			const { runAuditCommand } = await import("../audit-VtuUOuyX.js");
+			const { exitCode } = await runAuditCommand(fileURLToPath(dir), {
+				...options.failOn ? { failOn: options.failOn } : {},
+				...options.include ? { include: options.include } : {},
+				...options.exclude ? { exclude: options.exclude } : {},
+				...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+				...options.browser ? { browser: true } : {},
+				...options.concurrency === void 0 ? {} : { concurrency: options.concurrency },
+				...options.baseline ? { baseline: options.baseline } : {},
+				...options.format ? { format: options.format } : {},
+				...options.output ? { output: options.output } : {}
+			});
+			if (exitCode === 0) {
+				logger.info("no violations at or above the threshold");
+				return;
+			}
+			const message = exitCode === 2 ? "the audit could not be completed, so this build was not checked" : "accessibility violations at or above the threshold";
+			if (options.failBuild === false) {
+				logger.warn(`${message} (failBuild: false, so the build continues)`);
+				return;
+			}
+			logger.error(message);
+			throw new AstroAuditError(`eaa-kit: ${message}`);
+		} }
+	};
+}
+//#endregion
+export { AstroAuditError, eaaKit as default };

package/dist/audit/runners/worker.d.ts

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

package/dist/audit/runners/worker.js

@@ -0,0 +1,27 @@
+import { n as auditPage } from "../../jsdom-BEu6Ra_2.js";
+import { parentPort, workerData } from "node:worker_threads";
+//#region src/audit/runners/worker.ts
+/**
+* One audit worker: a thread that owns its own jsdom and axe-core, and audits
+* whatever page the pool hands it.
+*
+* It exists as a separate entry point rather than as inline source passed to
+* `new Worker(…, { eval: true })` because the thing it has to import — the
+* jsdom runner — sits at a different path when running from `src` than it does
+* in the bundle, and a string of code cannot be resolved against either.
+*
+* The protocol is deliberately one message each way: a CollectedPage in, the
+* PageAudit it produced out, both plain data that structured-clone handles.
+* `auditPage` turns a page it cannot audit into a PageAudit carrying an
+* `error`, so a failure is an ordinary reply rather than a special case. Only
+* something catastrophic — the thread running out of memory — reaches the
+* pool's error handler instead.
+*/
+const port = parentPort;
+if (!port) throw new Error("eaa-kit audit worker was started outside a worker thread");
+const options = workerData ?? {};
+port.on("message", async (page) => {
+	port.postMessage(await auditPage(page, options));
+});
+//#endregion
+export {};