@bounded-systems/conformance-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bounded Systems
+
+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,143 @@
+# @bounded-systems/conformance-kit
+
+A standalone, **site-agnostic web-conformance toolkit**: build-integrity tooling,
+fail-closed conformance gates, and provenance generators — extracted from
+`bdelanghe/site` and `bounded-systems/site` and **generalized** so a site vendors
+**one kit** instead of duplicating scripts.
+
+Every site value (paths, thresholds, site URL, account/repo id, issuer/DID, SHACL
+shapes, the markdown renderer, the prose corpus, the build itself) is an **INPUT**,
+injected by the consumer via CLI args, env vars, or a passed config. Nothing here
+hardcodes `robertdelanghe.dev`, `bounded.tools`, an account, or an email.
+
+```
+integrity/    verify-site · verify (sigstore) · gen-sitemanifest · gen-provenance · structure-audit · http-probe
+gates/        sbom (gen + completeness) · shacl-runner · seo-gate · axe-gate (axe-core a11y) · vuln-gate (npm audit) · html-validator-gate (vnu) · baseline-gate (web-features) · readability-gate · commonmark-runner · semantic (lone)
+gates/conformance/  conformance-report — lone's conformance() projection (Node port of jsr:@bounded-systems/lone@0.4) + a generic HTML renderer
+generators/   gen-cid (IPFS UnixFS) · gen-identity (did:web + VC) · gen-snapshots (reader/markdown) · openapi (static-API helper core)
+emitters/     reprDigest (RFC 9530) · securityTxt (RFC 9116) · webManifest · markdown-sibling headers
+lib/          schema-validate (zero-dep JSON Schema) · config (env/arg helpers)
+fixtures/ test/  isolated verification of the generic logic
+```
+
+Design rules: zero-dep where the source was zero-dep; pure/offline gates read only
+the built output; deterministic generators are a function of their inputs (no wall
+clock); fail-closed (`exit 1`) on any violation.
+
+## Install / vendor
+
+Three consumption models:
+
+1. **Vendor (recommended, matches the existing `vendor/integrity/` pattern).** Copy
+   the kit at a pinned commit into `vendor/conformance-kit/`, write a hash-pin
+   manifest (see [`vendor.example.json`](./vendor.example.json) — mirrors
+   `bdelanghe/site` `vendor/integrity/provenance.json`: `source`, `commit`,
+   `fetched`, `files{path: sha256}`), and verify against it before every use. The
+   site then `import`s / invokes the vendored copies. The kit's own
+   [`provenance.json`](./provenance.json) records which source repo + commit each
+   tool was generalized from.
+2. **npm dep.** `npm i @bounded-systems/conformance-kit` and use the `ck-*` bins
+   (see `package.json`) or `import` the library modules.
+3. **Nix flake (reproducible, runtime-bundled).** `nix run
+   github:bounded-systems/conformance-kit#ck-axe-gate -- dist`, or add the flake to
+   a `home-manager` / `nix profile`. Each `ck-*` bin is a hermetic, pinned closure;
+   the gates that shell out get their runtime bundled in — `ck-html-validator-gate`
+   carries a JRE for vnu, `ck-vuln-gate` carries npm — so no JRE/Node on `$PATH` is
+   needed. (`ck-axe-gate` still needs a browser the consumer supplies via
+   `$AXE_RUNNER`: `tezcatl` or Playwright.)
+
+Runtime deps are declared in `package.json` (only the gates that need them pull
+them: `linkedom`/`@mozilla/readability` for structure-audit; `jsonld`/`n3`/
+`@zazuko/env-node`/`rdf-validate-shacl` for the SHACL runner; `sigstore` for the
+in-process verifier). The Deno semantic runner pins its imports in
+`gates/semantic/deno.json`.
+
+## Tools — what each does + **how a site consumes it** (the input it must supply)
+
+### integrity/
+
+| Tool | Invoke | Consumer supplies |
+|---|---|---|
+| `gen-sitemanifest.mjs` | `DIST=dist node …/gen-sitemanifest.mjs` | `$DIST` (build dir). Optional `$MANIFEST_EXCLUDE` (extra platform control files). Emits `$DIST/site.sha256`. |
+| `gen-provenance.mjs` | run at deploy after signing | GitHub Actions env (`GITHUB_*`), `$OCI_REF`/`$OCI_DIGEST`, optional `$PROVENANCE_DOC_URL`, `$DIST`. The emitted `builder.repository` becomes the identity the verifiers enforce. |
+| `verify-site.mjs` | `node …/verify-site.mjs <https://site \| ./dist>` | A deployed site (or local dir) carrying `provenance.json` + `site.sha256` + its `.sigstore.json` bundle. Identity is read from `provenance.builder.repository` — nothing hardcoded. Shells to `cosign` if present, else SKIPs with a recipe. |
+| `verify/verify.mjs` | `node …/verify/verify.mjs <url\|dir>` | Same inputs; verifies the Sigstore **bundle** in-process (offline) via `sigstore-js`. |
+| `structure-audit/audit.mjs` | `node …/audit.mjs <distDir> [--check]` | `<distDir>`. Optional `$STRUCTURE_ARTICLE_PREFIX` (default `blog/`), `$STRUCTURE_ERROR_PAGE` (default `404.html`), `$STRUCTURE_AUDIT_SIDECARS` (deploy-time live paths, e.g. `/resume.pdf`), `$STRUCTURE_BASELINE` (where the committed `structure.json` lives — keep it in the **consumer**, not the vendored kit). |
+| `http-probe.mjs` | `node …/http-probe.mjs <https://site> [config.json]` | A live URL **and** a probe config: `$PROBE_CONFIG`/2nd arg JSON `{htmlRoutes,typed,missing}`, or `$PROBE_HTML_ROUTES`+`$PROBE_MISSING`. Routes are NOT hardcoded. |
+
+### gates/
+
+| Tool | Invoke | Consumer supplies |
+|---|---|---|
+| `sbom/gen-sbom.mjs` | `ROOT=. DIST=dist node …/gen-sbom.mjs` | `$ROOT` (lockfiles live here), `$SBOM_LOCKFILES` (comma list, default `package-lock.json`), `$SBOM_NAME`, `$SBOM_NAMESPACE_BASE`, `$SBOM_CREATORS`. Reads `flake.lock` if present. Emits `$DIST/sbom.spdx.json`. |
+| `sbom/check-sbom.mjs` | `ROOT=. DIST=dist node …/check-sbom.mjs` | Same `$ROOT`/`$DIST`. Fails closed unless pinned-set ⊆ SBOM ⊆ pinned-set and (optionally) the in-toto attestation reconciles. |
+| `shacl-runner.mjs` | `node …/shacl-runner.mjs <shapes.ttl> <htmlDir>` | **The SHACL shapes file stays in the site** (its structured-data contract) + the built-HTML dir. Optional `$SHACL_CONTEXT` (custom offline JSON-LD context; default schema.org). Fails unless every JSON-LD block `conforms: true`. |
+| `seo-gate.mjs` | `node …/seo-gate.mjs [distDir]` | `$DIST`. Optional `$SEO_ERROR_PAGE`, `$SEO_DEPLOY_SIDECARS`. Enforces canonical/title/description uniqueness + self-consistency, robots.txt (RFC 9309), sitemap, internal links. |
+| `axe-gate.mjs` | `node …/axe-gate.mjs [distDir]` | `$DIST`. Optional `$AXE_PAGES` (comma list, default: every `*.html` in dist), `$AXE_TAGS` (default `wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa`), `$AXE_IMPACT_THRESHOLD` (`minor`/`moderate`/`serious`/`critical`, default `serious`), `$AXE_RUNNER` (`playwright` (CI, needs `playwright` + `@axe-core/playwright` + `npx playwright install chromium`) \| `tezcatl` (macOS WebKit, local)), `$AXE_REPORT` (write the JSON report). Serves dist over an ephemeral origin (so assets resolve), runs **axe-core** per page, and **fails closed** on any violation at/above the threshold. The emitted report's `axe: { serious, critical }` envelope is exactly what `conformance-report`'s `a11y.axe-serious-critical` criterion consumes — a clean run is what lets a site honestly assert it. |
+| `vuln-gate.mjs` | `node …/vuln-gate.mjs [projectDir]` | `$VULN_ROOT` (lockfile lives here, default `.`). Optional `$VULN_OMIT_DEV` (`true`→production deps only, default `true`), `$VULN_THRESHOLD` (highest tolerated known critical/high, default `0`), `$VULN_REPORT` (write the JSON report). Runs **`npm audit`** and **fails closed** when the known critical/high count exceeds the threshold. The report's `vulns: { knownCriticalOrHighVulns }` envelope is what `conformance-report`'s `security.no-critical-vulns` criterion consumes. |
+| `html-validator-gate.mjs` | `node …/html-validator-gate.mjs [distDir]` | `$HTML_DIST`. Optional `$HTML_PAGES` (comma list, default: every `*.html`), `$HTML_THRESHOLD` (default `0`), `$HTML_REPORT`. Runs **vnu** (the Nu Html Checker, a self-contained Java jar — needs a JRE) `--errors-only` over the built pages and **fails closed** above the threshold. The report's `htmlValidator: { errors }` envelope is what `conformance-report`'s `html.validator-clean` criterion consumes. |
+| `baseline-gate.mjs` | `node …/baseline-gate.mjs [cssGlob]` | `$BASELINE_CSS` (default `dist/**/*.css`). Optional `$BASELINE_TARGET` (`widely`/`newly`, default `widely`), `$BASELINE_REPORT`. Maps the shipped CSS to **web-features Baseline** data (via `stylelint-plugin-use-baseline` — headless, no browser) and **fails closed** when the site-wide status is below target. A feature behind an `@supports` query is a tested fallback and doesn't count against it. The report's `baseline: { status, fallbackTested }` envelope is what `conformance-report`'s `compatibility.baseline` criterion consumes. |
+| `readability-gate.mjs` | `node …/readability-gate.mjs <corpus.json> [--strict]` | **The corpus is an input** the site assembles from its copy: a JSON array of `{id,text}` or an `{id:text}` map. Optional `$READABILITY_THRESHOLDS`, `$READABILITY_MIN_WORDS`, `$READABILITY_KNOWN_ACRONYMS`. WARN-only unless `--strict`. |
+| `commonmark-runner.mjs` | `node …/commonmark-runner.mjs <renderer.mjs> [fixtures.json]` | **The site's markdown renderer module** (export `renderMarkdown`, or set `$COMMONMARK_RENDER_EXPORT`). Default fixtures pin a safe CommonMark subset + 4 hostile-HTML escapes; a site with a different renderer supplies its own `fixtures.json`. |
+| `semantic/gate.ts` | `deno run --allow-read --allow-net …/gate.ts` | Built HTML in `$SEMANTIC_DIR` (default `dist/blog`); `$SEMANTIC_SELECTOR` (subject node, default `article`). Imports `jsr:@bounded-systems/lone`; any error-severity finding fails CI. |
+| `conformance-report.mjs` | `import { buildConformanceReport, renderConformanceReport } from "…/gates/conformance-report.mjs"` | **The site's evidence** — `loneFindings` (the semantic gate's DOM findings, or `null` when no DOM was blessed → those criteria report `not-assessed`) + an external-evidence envelope whose fields it gathers from its own gates (`jsonLdShacl`, `sbom`, `contentDigests`, `slsaProvenance`, …). `renderConformanceReport(report, { evidenceHref })` → a class-based HTML fragment; the consumer wraps it in its template and supplies per-criterion evidence URLs. Zero-dep; the conformance MODEL is a Node port of `jsr:@bounded-systems/lone@0.4`'s `conformance()` in `gates/conformance/`. |
+
+The conformance projection makes overclaim impossible by construction: the strong
+compact claim (`COMPACT_CLAIM`) is emitted **only** when every tier-1 `required`
+criterion has passing evidence; unsupplied criteria (manual WCAG audit, OWASP ASVS,
+field Core Web Vitals, Baseline) are `not-assessed`, never `met` — so automation can
+never print "WCAG 2.2 AA" or "ASVS conformant" on its own. tier-2/tier-3/cognitive
+criteria are reported + summarised per area but never widen the headline claim.
+
+### generators/
+
+| Tool | Invoke | Consumer supplies |
+|---|---|---|
+| `gen-cid.mjs` | `DIST=dist node …/gen-cid.mjs` | `$DIST`. Walks the `site.sha256` file set (or `dist`), computes the IPFS UnixFS dir CIDv1 with no daemon, records it into `$DIST/provenance.json`. |
+| `gen-identity.mjs` | `IDENTITY_DOMAIN=… IDENTITY_REPO=owner/repo node …/gen-identity.mjs` | `$IDENTITY_DOMAIN`, `$IDENTITY_REPO` (cert-identity regexp), `$IDENTITY_SUBJECT` (the credentialSubject JSON, default `$DIST/resume.json`), optional `$IDENTITY_SUBJECT_SCHEMA`, `$IDENTITY_VC_NAME/DESCRIPTION`, `$IDENTITY_VALID_FROM_PATH`. Emits `did.json` + a W3C VC 2.0. |
+| `gen-snapshots.mjs` | `node …/gen-snapshots.mjs [distDir]` | `$SNAPSHOT_DIST` (default `dist`). Optional `$SNAPSHOT_PAGES`, `$SNAPSHOT_BASE_URL` (recorded as `source` in the front-matter), `$SNAPSHOT_SUFFIX` (default `.reader`). For every built page, runs **@mozilla/readability** (the Firefox/Safari Reader engine, via `linkedom` — headless, no browser) and writes a clean reader **`<page>.reader.html`** + an analysis-friendly **`<page>.reader.md`** (YAML front-matter + Markdown via `turndown`). The Markdown is the durable, diffable twin of the page — far easier to run NLP/LLM analysis over than scraping live HTML — and doubles as the AI-readable Markdown sibling. (The printed/PDF view needs a print-CSS renderer and is a separate generator.) |
+| `openapi.mjs` | `import { sortKeys, writeApiFile, embedSchema, jsonResponse, validateOpenapi }` | The **generic core** of a static-API generator. The per-endpoint projection of a site's contracts (profile/posts/corpus/VC, etc.) stays in the site's build; this module provides deterministic JSON output, schema embedding, and OpenAPI 3.1/3.2 well-formedness validation. Pair with `lib/schema-validate.mjs` to self-check emitted docs. |
+
+### emitters/
+
+`import { reprDigest, securityTxt, securityTxtExpires, webManifest, markdownSiblingHeaders } from "…/emitters/index.mjs"` — pure helpers a site's own `build.mjs` calls to emit standards-compliant artifacts (RFC 9530 `Repr-Digest`, RFC 9116 `security.txt`, the W3C web app manifest, the `_headers` Content-Type rules for `.md` siblings). All values injected; the page **content** stays in the site.
+
+## `@bounded-systems/verify` (vendored here; published elsewhere)
+
+The in-process Sigstore verifier (`integrity/verify/verify.mjs`) is **vendored** in
+this kit so sites can pull it into a hermetic build. It is no longer **published**
+from here: the canonical home of the [`@bounded-systems/verify`](https://jsr.io/@bounded-systems/verify)
+JSR package is now its own repo,
+[`bounded-systems/verify`](https://github.com/bounded-systems/verify). That repo owns
+the package manifest (`deno.json`) and the keyless-OIDC release workflow; cut releases
+there. The copy here is kept byte-for-byte in sync with the published source.
+
+Consumers run it straight from JSR:
+
+```sh
+deno run -A jsr:@bounded-systems/verify https://your-site
+```
+
+## Test
+
+```
+npm install && npm test    # 13 cases against fixtures/, in isolation
+```
+
+The suite verifies the generic logic end-to-end: gen-sbom against a sample lockfile;
+shacl-runner against sample shapes+HTML → `conforms: true`; structure-audit / seo /
+readability / commonmark against sample inputs; gen-sitemanifest + gen-cid + verify-site
+round-trip on a sample build; gen-identity; the emitter/openapi/schema helpers; the
+conformance projection; and the **axe-gate** (its classification/threshold/report logic
+deterministically, plus a real end-to-end pass on the known-bad + known-good
+`fixtures/axe/` snippets when a browser engine — tezcatl or Playwright/Chromium — is on
+PATH; skipped, like the cosign step, when none is). (The Deno semantic runner is
+exercised by the consuming site, as it needs Deno + JSR.)
+
+## Provenance / determinism
+
+The gates are pure functions of the built output; the generators are deterministic
+functions of their inputs (the SBOM creation date is derived from `flake.lock`, never
+a wall clock; the CID re-derives from the served bytes with any IPFS implementation).
+Site-specific artifacts — SHACL shapes, the prose corpus, the markdown renderer,
+thresholds, copy, and `build.mjs` itself — are inputs, never part of the kit.

package/emitters/index.mjs

@@ -0,0 +1,68 @@
+// emitters — pure helpers for the standards-compliant build artifacts a site's
+// own build.mjs emits. Each is a PURE FUNCTION of injected config; nothing here
+// reads a site's content model, so the actual copy/data stays in the consumer.
+// Extracted from the emitters embedded in bdelanghe/site/build.mjs.
+import { createHash } from "node:crypto";
+
+// RFC 9530 representation digest: sha-256 of a doc's exact served bytes, as a
+// structured-field byte sequence — `sha-256=:<base64>:`. Compute over the bytes the
+// build itself writes (self-contained), per canonical document, then add as a
+// `Repr-Digest:` response header for that route.
+export const reprDigest = (buf) =>
+  "sha-256=:" + createHash("sha256").update(Buffer.isBuffer(buf) ? buf : Buffer.from(buf)).digest("base64") + ":";
+
+// RFC 9116 /.well-known/security.txt — a machine-readable security-contact channel.
+//   securityTxt({ contact, canonical, expires, preferredLanguages })
+// `contact` is one or more mailto:/https: values; `expires` is an ISO timestamp (a
+// year out from the build date is the convention, so a weekly rebuild rolls it
+// forward and it never goes stale).
+export function securityTxt({ contact, canonical, expires, preferredLanguages = ["en"] } = {}) {
+  if (!contact) throw new Error("securityTxt: `contact` is required (mailto: or https: URL)");
+  if (!expires) throw new Error("securityTxt: `expires` (ISO timestamp) is required");
+  const contacts = Array.isArray(contact) ? contact : [contact];
+  const lines = [
+    ...contacts.map((c) => `Contact: ${c}`),
+    `Expires: ${expires}`,
+    ...(canonical ? [`Canonical: ${canonical}`] : []),
+    ...(preferredLanguages?.length ? [`Preferred-Languages: ${preferredLanguages.join(", ")}`] : []),
+  ];
+  return lines.join("\n") + "\n";
+}
+
+// `expires` one year out from a reference date (ISO string), the security.txt convention.
+export const securityTxtExpires = (fromISO = new Date().toISOString()) => {
+  const d = new Date(fromISO);
+  d.setUTCFullYear(d.getUTCFullYear() + 1);
+  return d.toISOString();
+};
+
+// W3C Web App Manifest (no service worker). All values injected by the consumer —
+// typically from its design tokens so the <head> theme-color and the manifest can't
+// drift. Returns the manifest object; the caller JSON.stringifies + writes it to
+// /site.webmanifest and serves it as `application/manifest+json`.
+export function webManifest({
+  name, shortName, description,
+  themeColor, backgroundColor,
+  display = "standalone", startUrl = "/", icons = [],
+} = {}) {
+  if (!name) throw new Error("webManifest: `name` is required");
+  return {
+    name,
+    ...(shortName ? { short_name: shortName } : { short_name: name.split(" ")[0] }),
+    ...(description ? { description } : {}),
+    ...(themeColor ? { theme_color: themeColor } : {}),
+    ...(backgroundColor ? { background_color: backgroundColor } : {}),
+    display,
+    start_url: startUrl,
+    icons,
+  };
+}
+
+// The Cloudflare-_headers Content-Type rules a site needs once it serves Markdown
+// siblings (/index.md, /resume.md, /blog/<slug>.md) + a web app manifest. Returned
+// as a string a consumer concatenates into its own _headers file. The Markdown
+// SIBLING CONTENT itself (rendering a page to text/markdown) is the site's job —
+// only the serving rule is generic.
+export const markdownSiblingHeaders = () =>
+  `/*.md\n  Content-Type: text/markdown; charset=utf-8\n` +
+  `/site.webmanifest\n  Content-Type: application/manifest+json; charset=utf-8\n`;

package/gates/axe-gate.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+// axe accessibility gate — turns "we ran axe once" into a CONTINUOUSLY-ENFORCED
+// member of the conformance contract. It loads each BUILT page in a real browser,
+// runs axe-core with the WCAG 2.x A/AA ruleset, and FAILS CLOSED (exit 1) on any
+// violation at or above a configurable impact threshold (default: serious). The
+// machine-readable result it emits is exactly the shape lone's conformance() model
+// consumes for `a11y.axe-serious-critical` (`{ serious, critical }`), so a clean run
+// is what lets a site honestly assert that criterion — and a regression turns CI red.
+//
+//   node gates/axe-gate.mjs [distDir]          # build gate (exit 1 on any blocking violation)
+//
+// Pure data in → typed report out. The browser is the ONLY impurity: axe needs real
+// layout/computed-style (e.g. colour-contrast, target-size), so a DOM shim is not
+// enough. Two interchangeable runners drive a real engine:
+//   - playwright (default) — `@axe-core/playwright` + Playwright's bundled Chromium.
+//     The CI runner: hermetic, headless, cross-platform.
+//   - tezcatl              — macOS-native headless WebKit. Injects axe.min.js into the
+//     served page and reads the result back. The LOCAL runner (no Chromium download).
+// Both serve dist/ over an ephemeral localhost HTTP origin first, so absolute asset
+// paths (`/assets/…css`, fonts) resolve — running file:// would strip the styles and
+// fabricate layout-dependent violations.
+//
+// Everything is config-driven; NOTHING about any one site is hard-coded:
+//   argv[2] / $DIST            built output dir                  (default: "dist")
+//   $AXE_PAGES                 comma list of page paths under dist to scan
+//                              (default: every *.html discovered in dist)
+//   $AXE_TAGS                  comma list of axe ruleset tags
+//                              (default: wcag2a,wcag2aa,wcag21a,wcag21aa,wcag22aa)
+//   $AXE_IMPACT_THRESHOLD      lowest impact that BLOCKS: minor|moderate|serious|critical
+//                              (default: serious)
+//   $AXE_RUNNER               playwright | tezcatl              (default: playwright)
+//   $AXE_REPORT               path to write the JSON report     (default: none → stdout only)
+//   $AXE_TEZCATL_WAIT         ms to let axe settle, tezcatl runner (default: 3000)
+//
+// The pure evaluation/report functions are exported for unit testing without a browser.
+import { readFile, readdir, access, mkdtemp, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { join, relative, resolve, extname } from "node:path";
+import { tmpdir } from "node:os";
+import { createRequire } from "node:module";
+import { spawn } from "node:child_process";
+
+// ── Pure core (browser-free; unit-testable) ──────────────────────────────────
+
+/** Impact levels, weakest → strongest. A violation BLOCKS when its impact ranks at
+ *  or above the configured threshold. axe may report `impact: null`; such findings
+ *  rank below `minor` and so never block (but are still counted/reported). */
+export const IMPACT_ORDER = ["minor", "moderate", "serious", "critical"];
+export const DEFAULT_TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
+export const DEFAULT_THRESHOLD = "serious";
+
+export const impactRank = (impact) => IMPACT_ORDER.indexOf(impact); // -1 when null/unknown
+export const blocksAt = (impact, threshold) => {
+  const t = impactRank(threshold);
+  return t >= 0 && impactRank(impact) >= t;
+};
+
+/** Normalise one axe violation to the compact, stable shape we report/persist. */
+export function normalizeViolation(v) {
+  const nodes = Array.isArray(v.nodes) ? v.nodes : [];
+  const targets = nodes
+    .map((n) => (Array.isArray(n.target) ? n.target.join(" ") : String(n.target ?? "")))
+    .filter(Boolean);
+  return {
+    id: v.id,
+    impact: v.impact ?? null,
+    help: v.help ?? "",
+    helpUrl: v.helpUrl ?? "",
+    nodes: nodes.length,
+    targets: targets.slice(0, 8), // cap; full detail lives in axe's own helpUrl
+  };
+}
+
+/** Empty {critical,serious,moderate,minor,unknown} counter. */
+const emptyCounts = () => ({ critical: 0, serious: 0, moderate: 0, minor: 0, unknown: 0 });
+
+/** Evaluate one page's raw axe violations against the threshold. */
+export function evaluatePage(page, rawViolations, threshold = DEFAULT_THRESHOLD) {
+  const violations = (rawViolations ?? []).map(normalizeViolation);
+  const counts = emptyCounts();
+  let blocking = 0;
+  for (const v of violations) {
+    counts[v.impact && v.impact in counts ? v.impact : "unknown"]++;
+    if (blocksAt(v.impact, threshold)) blocking++;
+  }
+  // Group by impact for the machine-readable report (serious/critical first).
+  const byImpact = {};
+  for (const lvl of [...IMPACT_ORDER].reverse()) {
+    const inLvl = violations.filter((v) => v.impact === lvl);
+    if (inLvl.length) byImpact[lvl] = inLvl;
+  }
+  const unknown = violations.filter((v) => impactRank(v.impact) < 0);
+  if (unknown.length) byImpact.unknown = unknown;
+  return { page, counts, blocking, violations: byImpact };
+}
+
+/** Fold per-page evaluations into the whole-run report consumed by conformance(). */
+export function summarize(pageResults, { threshold = DEFAULT_THRESHOLD, tags = DEFAULT_TAGS, runner = "playwright" } = {}) {
+  const totals = emptyCounts();
+  let blocking = 0;
+  for (const p of pageResults) {
+    for (const k of Object.keys(totals)) totals[k] += p.counts[k];
+    blocking += p.blocking;
+  }
+  return {
+    tool: "axe-core",
+    runner,
+    standard: "WCAG 2.x A/AA (axe ruleset)",
+    tags,
+    impactThreshold: threshold,
+    generatedAt: new Date().toISOString(),
+    pages: pageResults,
+    totals,
+    // The exact envelope lone's `a11y.axe-serious-critical` evaluator reads.
+    axe: { serious: totals.serious, critical: totals.critical },
+    blocking, // count of violations at/above threshold across all pages
+    passed: blocking === 0,
+  };
+}
+
+// ── dist discovery + static origin (shared by both runners) ──────────────────
+
+async function walkHtml(dir, base = dir) {
+  const out = [];
+  for (const e of await readdir(dir, { withFileTypes: true })) {
+    const abs = join(dir, e.name);
+    if (e.isDirectory()) out.push(...await walkHtml(abs, base));
+    else if (e.name.endsWith(".html")) out.push(relative(base, abs).replace(/\\/g, "/"));
+  }
+  return out;
+}
+
+const MIME = {
+  ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "application/javascript",
+  ".mjs": "application/javascript", ".json": "application/json", ".svg": "image/svg+xml",
+  ".png": "image/png", ".jpg": "image/jpeg", ".webp": "image/webp", ".ico": "image/x-icon",
+  ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf", ".xml": "application/xml",
+  ".txt": "text/plain", ".webmanifest": "application/manifest+json", ".pdf": "application/pdf",
+};
+
+/**
+ * Serve `root` over an ephemeral localhost origin. When `inject` is set, HTML
+ * responses get axe-core + a runner appended before </body>, and `/__axe-core.js`
+ * serves the axe source — used by the tezcatl runner, which cannot inject async JS
+ * itself. Returns { origin, close }.
+ */
+async function startServer(root, { inject = false, tags = DEFAULT_TAGS } = {}) {
+  let axeSrc = "";
+  if (inject) {
+    const require = createRequire(import.meta.url);
+    axeSrc = await readFile(require.resolve("axe-core/axe.min.js"), "utf8");
+  }
+  const runnerScript =
+    `<script src="/__axe-core.js"></script><script>` +
+    `window.addEventListener("load",function(){setTimeout(function(){` +
+    `axe.run(document,{runOnly:{type:"tag",values:${JSON.stringify(tags)}}}).then(function(r){` +
+    `var e=document.createElement("script");e.type="application/json";e.id="__axe_results";` +
+    `e.textContent=JSON.stringify({violations:r.violations});document.documentElement.appendChild(e);` +
+    `}).catch(function(err){var e=document.createElement("script");e.type="application/json";` +
+    `e.id="__axe_results";e.textContent=JSON.stringify({error:String(err)});document.documentElement.appendChild(e);});` +
+    `},150);});</script>`;
+
+  const server = createServer(async (req, res) => {
+    try {
+      let urlPath = decodeURIComponent((req.url || "/").split("?")[0]);
+      if (inject && urlPath === "/__axe-core.js") {
+        res.writeHead(200, { "content-type": "application/javascript" });
+        return res.end(axeSrc);
+      }
+      let file = join(root, urlPath);
+      if (urlPath.endsWith("/")) file = join(file, "index.html");
+      let buf;
+      try { buf = await readFile(file); }
+      catch { try { buf = await readFile(file + ".html"); file += ".html"; } catch { res.writeHead(404); return res.end("not found"); } }
+      const ext = extname(file).toLowerCase();
+      if (inject && ext === ".html") {
+        let html = buf.toString("utf8");
+        html = html.includes("</body>") ? html.replace("</body>", runnerScript + "</body>") : html + runnerScript;
+        buf = Buffer.from(html, "utf8");
+      }
+      res.writeHead(200, { "content-type": MIME[ext] || "application/octet-stream" });
+      res.end(buf);
+    } catch (e) { res.writeHead(500); res.end(String(e)); }
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  const { port } = server.address();
+  return { origin: `http://127.0.0.1:${port}`, close: () => new Promise((r) => server.close(r)) };
+}
+
+// ── Runners: page → raw axe violations[] ─────────────────────────────────────
+
+async function collectWithPlaywright(pages, { dist, tags }) {
+  let chromium, AxeBuilder;
+  try {
+    ({ chromium } = await import("playwright"));
+    ({ default: AxeBuilder } = await import("@axe-core/playwright"));
+  } catch (e) {
+    throw new Error(
+      "playwright runner needs `playwright` + `@axe-core/playwright` installed " +
+      "(and `npx playwright install --with-deps chromium`). " + e.message,
+    );
+  }
+  const srv = await startServer(dist, { inject: false });
+  const browser = await chromium.launch();
+  const out = new Map();
+  try {
+    const ctx = await browser.newContext();
+    for (const page of pages) {
+      const pg = await ctx.newPage();
+      await pg.goto(`${srv.origin}/${page}`, { waitUntil: "load" });
+      const results = await new AxeBuilder({ page: pg }).withTags(tags).analyze();
+      out.set(page, results.violations);
+      await pg.close();
+    }
+  } finally {
+    await browser.close();
+    await srv.close();
+  }
+  return out;
+}
+
+// Run tezcatl async (NOT execFileSync) — the static origin lives on this same event
+// loop, so a blocking child would deadlock its own server. Resolves to trimmed stdout.
+function tezcatl(args) {
+  return new Promise((res, rej) => {
+    const ch = spawn("tezcatl", args, { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    ch.stdout.on("data", (d) => (out += d));
+    ch.stderr.on("data", (d) => (err += d));
+    ch.on("error", (e) => rej(new Error(`tezcatl not runnable (on PATH?): ${e.message}`)));
+    ch.on("close", (code) => (code === 0 ? res(out.trim()) : rej(new Error(`tezcatl exit ${code}: ${err.trim() || out.trim()}`))));
+  });
+}
+
+async function collectWithTezcatl(pages, { dist, tags }) {
+  const waitMs = Number(process.env.AXE_TEZCATL_WAIT || 3000);
+  const readResults = `--eval=(function(){var e=document.getElementById('__axe_results');return e?e.textContent:'';})()`;
+  const srv = await startServer(dist, { inject: true, tags });
+  const out = new Map();
+  try {
+    for (const page of pages) {
+      const url = `${srv.origin}/${page}`;
+      let text = "";
+      for (const attempt of [waitMs, waitMs * 2]) { // one retry with a longer settle window
+        const raw = await tezcatl([url, `--wait=${attempt}`, readResults]);
+        if (raw && raw !== "NORESULT") { text = raw; break; }
+      }
+      if (!text) throw new Error(`tezcatl: no axe result for ${page} (raise $AXE_TEZCATL_WAIT?)`);
+      const parsed = JSON.parse(text);
+      if (parsed.error) throw new Error(`axe failed on ${page}: ${parsed.error}`);
+      out.set(page, parsed.violations || []);
+    }
+  } finally {
+    await srv.close();
+  }
+  return out;
+}
+
+const RUNNERS = { playwright: collectWithPlaywright, tezcatl: collectWithTezcatl };
+
+/**
+ * Run the configured runner over `pages` of `dist` and return the summarized report.
+ * Exposed for programmatic use (and the kit's own test) in addition to the CLI.
+ */
+export async function runAxeGate({ dist, pages, tags = DEFAULT_TAGS, threshold = DEFAULT_THRESHOLD, runner = "playwright" }) {
+  const collect = RUNNERS[runner];
+  if (!collect) throw new Error(`unknown runner "${runner}" (expected: ${Object.keys(RUNNERS).join(", ")})`);
+  const raw = await collect(pages, { dist, tags });
+  const pageResults = pages.map((p) => evaluatePage(p, raw.get(p) || [], threshold));
+  return summarize(pageResults, { threshold, tags, runner });
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const dist = resolve(process.argv[2] && !process.argv[2].startsWith("--") ? process.argv[2] : process.env.DIST || "dist");
+  const exists = async (p) => { try { await access(p); return true; } catch { return false; } };
+  if (!(await exists(dist))) { console.error(`✗ axe-gate: ${dist} not found — build first.`); process.exit(2); }
+
+  const tags = (process.env.AXE_TAGS || DEFAULT_TAGS.join(",")).split(",").map((s) => s.trim()).filter(Boolean);
+  const threshold = (process.env.AXE_IMPACT_THRESHOLD || DEFAULT_THRESHOLD).trim();
+  if (!IMPACT_ORDER.includes(threshold)) {
+    console.error(`✗ axe-gate: $AXE_IMPACT_THRESHOLD must be one of ${IMPACT_ORDER.join("|")} (got "${threshold}")`);
+    process.exit(2);
+  }
+  const runner = (process.env.AXE_RUNNER || "playwright").trim();
+  let pages = (process.env.AXE_PAGES || "").split(",").map((s) => s.trim().replace(/^\//, "")).filter(Boolean);
+  if (pages.length === 0) pages = (await walkHtml(dist)).sort();
+  if (pages.length === 0) { console.error(`✗ axe-gate: no HTML pages found under ${dist}`); process.exit(2); }
+
+  console.log(`axe-gate: ${runner} runner · ${pages.length} page(s) · tags [${tags.join(", ")}] · block ≥ ${threshold}`);
+  const report = await runAxeGate({ dist, pages, tags, threshold, runner });
+
+  if (process.env.AXE_REPORT) {
+    await writeFile(resolve(process.env.AXE_REPORT), JSON.stringify(report, null, 2) + "\n");
+    console.log(`  ↳ wrote ${process.env.AXE_REPORT}`);
+  }
+
+  for (const p of report.pages) {
+    const tally = IMPACT_ORDER.map((l) => `${p.counts[l]} ${l}`).join(", ");
+    const mark = p.blocking ? "✗" : "✓";
+    console.log(`  ${mark} ${p.page} — ${tally}${p.counts.unknown ? `, ${p.counts.unknown} unknown` : ""}`);
+    if (p.blocking) {
+      for (const lvl of ["critical", "serious", "moderate", "minor"]) {
+        for (const v of p.violations[lvl] || []) {
+          if (!blocksAt(lvl, threshold)) continue;
+          console.error(`      [${lvl}] ${v.id} — ${v.help} (${v.nodes} node(s)) ${v.helpUrl}`);
+          for (const t of v.targets) console.error(`         · ${t}`);
+        }
+      }
+    }
+  }
+
+  console.log("");
+  if (!report.passed) {
+    console.error(`✗ axe-gate: ${report.blocking} violation(s) at or above "${threshold}" across ${report.pages.length} page(s) (${report.totals.critical} critical, ${report.totals.serious} serious).`);
+    process.exit(1);
+  }
+  console.log(`✓ axe-gate: ${report.pages.length} page(s) clean — 0 violations at or above "${threshold}" (axe ${tags.includes("wcag22aa") ? "WCAG 2.2 A/AA" : "WCAG A/AA"}).`);
+}
+
+// Only run the CLI when invoked directly (not when imported by a test).
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((e) => { console.error("✗ axe-gate: error —", e.stack || e.message); process.exit(1); });
+}