bfsg-scanner 0.1.0

package/docs/adr/0001-page-discovery-strategy.md

@@ -0,0 +1,74 @@
+# 1. Page discovery strategy
+
+Date: 2026-08-26
+
+## Status
+
+Accepted
+
+## Context
+
+The scanner is given a single `baseUrl`. Before it can run axe-core it needs the
+list of pages to visit. Two sources are available for a typical site:
+
+- **`sitemap.xml`** (optionally a sitemap index pointing at sub-sitemaps) — an
+  explicit, machine-readable list published by the site owner.
+- **Crawling** — following same-origin `<a href>` links breadth-first from
+  `baseUrl`.
+
+Both were already implemented as standalone modules (`discoverFromSitemap`,
+`crawlSite`) but nothing combined them, and the CLI scanned only `[baseUrl]`,
+ignoring `maxPages` and `excludePaths`.
+
+Constraints:
+
+- A compliance report should reflect the whole site, not just the home page.
+- Runs must stay bounded (`maxPages`) and polite (per-host rate limiting already
+  exists in the scan engine; `robots.txt` is respected by the crawler).
+- Output must be deterministic so the golden e2e tests stay stable.
+
+## Decision
+
+Add a thin orchestrator, `discoverSite`, that picks one strategy:
+
+1. **Sitemap first.** Fetch `/sitemap.xml`, follow an index to its
+   sub-sitemaps, collect same-origin `<loc>` entries. The sitemap is the
+   owner's own declaration of what exists, so it is preferred whenever present.
+2. **Crawl as fallback.** If the root sitemap is missing or unparseable
+   (`SitemapError`), fall back to `crawlSite` from `baseUrl`.
+
+Shared rules across both strategies:
+
+- `excludePaths` globs and the non-page-asset filter (`.pdf`, `.jpg`, …) are
+  applied identically. `discoverFromSitemap` gained an `excludePaths` option in
+  this change so the two paths cannot diverge.
+- The result is capped at `maxPages` and stays in discovery order.
+
+Where they deliberately differ:
+
+- **`robots.txt`** is obeyed on the crawl path only. A URL the owner placed in
+  their own sitemap is taken as intended for scanning; `robots.txt` is a
+  crawl-politeness directive, and on the sitemap path there is no crawl.
+- **`baseUrl` guarantee**: on the sitemap path `baseUrl` is prepended if the
+  sitemap did not list it, so the home page is always covered. The crawl path
+  already starts from `baseUrl` and needs no fixup — including the case where a
+  `robots.txt`-disallowed home page correctly yields zero pages.
+
+The CLI now calls `discoverSite` and exits `3` when it returns no pages
+(previously `3` meant only "a page failed to load").
+
+## Consequences
+
+- The `discovery/` modules are now reachable from the CLI; `maxPages` and
+  `excludePaths` take effect for the first time.
+- A site with a stale or partial sitemap is scanned per that sitemap, not
+  crawled to fill the gaps. Merging both sources is possible later but adds
+  non-determinism and crawl cost; deferred until there is a real need.
+- URL normalisation still differs slightly between the two paths
+  (`crawlSite` strips fragments and normalises; `discoverFromSitemap` emits
+  `<loc>` verbatim). `discoverSite` compares normalised forms when deciding
+  whether to prepend `baseUrl`, but a fuller normalisation pass is left for a
+  follow-up.
+- `robots.txt` being ignored on the sitemap path is a conscious trade-off; if
+  it proves surprising it can be revisited without changing the module
+  boundaries.

package/docs/adr/0002-json-report-output.md

@@ -0,0 +1,54 @@
+# 2. JSON report output
+
+Date: 2026-08-27
+
+## Status
+
+Accepted
+
+## Context
+
+Discovery (ADR 0001) and the scan engine now produce a full `ScanResult`, but
+the CLI only prints a one-line summary — nothing is persisted. A compliance
+tool has to leave an artifact: something a CI job can archive, a diff can run
+against, and a human or a later HTML/PDF renderer can consume.
+
+`src/index.ts` already declares `SCHEMA_VERSION = 1` for exactly this, and the
+config already has `outputDir` (default `reports/`, git-ignored).
+
+## Decision
+
+Add a `report/` module with three pieces:
+
+- **`types.ts`** — the `Report` shape: `schemaVersion`, `generatedAt`, `tool`
+  (name/version), `target` (the `baseUrl` / `wcagTags` / `failOn` echoed back
+  so a stored report is self-describing), a `summary`, and `pages`.
+- **`buildReport(scanResult, target, options?)`** — pure apart from a default
+  clock and a one-time `package.json` read, both overridable via `options`
+  (`generatedAt`, `tool`) for deterministic tests. Computes the summary:
+  pages scanned/failed/with-violations, total violated rules, and rule counts
+  bucketed by axe-core impact (`critical|serious|moderate|minor|unknown`,
+  where `unknown` is impact `null`).
+- **`writeReport(report, outputDir)`** — `mkdir -p`, then write
+  `<outputDir>/report.json` as pretty JSON with a trailing newline; returns
+  the path.
+
+The CLI calls both after the scan, **before** the partial-failure check, so a
+run that exits `3` for unreachable pages still leaves a report — the partial
+results and the failure entries are worth keeping.
+
+## Consequences
+
+- `pages` is the scan engine's `PageScanResult[]` verbatim (failures
+  included). One source of truth for the result shape; no parallel type
+  hierarchy to keep in sync. The trade-off: the on-disk schema is now
+  coupled to `scan/types.ts`, so a change there is a `schemaVersion` bump.
+- Node HTML and selectors from axe are written in full. That is the actual
+  evidence for each violation; `maxPages` bounds the total size.
+- One canonical `report.json`, overwritten each run — predictable for CI.
+  Timestamped history, and non-JSON renderings (HTML, PDF), are deliberately
+  out of scope here.
+- `generatedAt` makes the file non-byte-deterministic; that is fine for an
+  artifact (it is not a golden fixture) and tests inject a fixed clock.
+- `failOn` is carried in the report but not yet acted on — scoring and a
+  threshold exit code are the next change.

package/docs/adr/0003-failon-threshold-and-exit-codes.md

@@ -0,0 +1,72 @@
+# 3. failOn threshold and exit codes
+
+Date: 2026-08-27
+
+## Status
+
+Accepted
+
+## Context
+
+`failOn` (`critical | serious | moderate | minor`, default `serious`) has
+been in the config since ADR 0002's predecessor, and ADR 0002 carried it into
+the report — but nothing acted on it. Every completed scan exited `0`, so no
+CI job could gate a merge on accessibility, which is the whole point of a
+compliance scanner in a pipeline.
+
+The existing exit codes were `0` (completed), `2` (bad config), `3` (nothing
+discovered, or a page failed to scan).
+
+## Decision
+
+**Severity ranking.** axe-core impacts rank `minor < moderate < serious <
+critical`. A violation meets the threshold when its impact is at least as
+severe as `failOn`.
+
+**Unranked violations.** A violation whose impact axe left `null` — or one
+carrying an impact string a future axe version might introduce — is never
+counted toward the threshold. It cannot be ranked, so it can neither be
+trusted to clear a threshold nor be assumed to breach one. Guessing in
+either direction is worse than saying so: such findings are counted in the
+report's `verdict.unrankedViolations`, and the CLI prints a warning naming
+them. They are excluded from the pass/fail arithmetic, never from view.
+
+**Verdict scope.** The verdict answers only "did the pages that scanned stay
+under the threshold?". A page that failed to load has *unknown* compliance:
+it is counted in `summary.pagesFailed` and drives the exit code, but it
+cannot flip a verdict in either direction.
+
+**Exit codes.**
+
+| Code | Meaning |
+|---|---|
+| `0` | scan completed, nothing at or above `failOn` |
+| `1` | scan completed, violations at or above `failOn` |
+| `2` | invalid or missing configuration |
+| `3` | no pages discovered, or a page could not be scanned |
+
+`3` outranks `1`. A run with unreachable pages scanned an incomplete site,
+so reporting "no violations found" would be a claim the data cannot support.
+The report is written before either check, so partial results and failure
+entries survive regardless of which code is returned.
+
+`1` is the conventional "ran fine, found problems" code (`grep`, `eslint`,
+`tsc`), which is what a CI gate expects.
+
+## Consequences
+
+- Adding `verdict` to the report is additive, so `schemaVersion` stays `1`:
+  nothing consumes a published report yet and no report from an earlier
+  build exists in the wild. The version starts mattering at the first
+  release.
+- `target.failOn` is now the `ImpactThreshold` union rather than a bare
+  `string`, so an unrankable threshold cannot reach the report at all.
+- The default `failOn: serious` means a `color-contrast` finding (impact
+  `serious`) fails a build. That matches the BFSG/EN 301 549 baseline, where
+  contrast is a genuine conformance failure rather than an advisory.
+- Counting is by **violated rule**, not by node. Ten images missing `alt` on
+  one page is one `image-alt` violation. Node-level counts stay available in
+  the report for anyone who needs to weigh breadth.
+- Not addressed here: per-rule ignores/waivers, and a budget ("fail only
+  above N violations"). Both are real needs for a team adopting the scanner
+  on an existing site, but neither belongs in the first threshold change.

package/docs/adr/0004-clause-mapping-from-axe-tags.md

@@ -0,0 +1,81 @@
+# 4. WCAG / EN 301 549 clause mapping from axe tags
+
+Date: 2026-08-28
+
+## Status
+
+Accepted
+
+## Context
+
+The report so far names each finding only by its axe `ruleId` (`color-contrast`,
+`image-alt`). A BFSG / EN 301 549 report has to say which clause of the standard
+a finding breaches — that citation is the compliance value the tool exists to
+produce. Something has to turn `color-contrast` into "WCAG SC 1.4.3 / EN 301 549
+clause 9.1.4.3".
+
+Two ways to get there:
+
+1. **Hand-author a table** `ruleId → clauses` in this repo.
+2. **Read it from axe-core.** Every rule's metadata already carries a `tags`
+   array, and the tags encode the mapping: `color-contrast` is tagged
+   `wcag143` (WCAG SC 1.4.3) and `EN-9.1.4.3` (EN 301 549 clause 9.1.4.3);
+   `wcag2aa` marks the conformance level. Verified against `axe-core@4.13.0`:
+   69 rules carry an `EN-301-549` tag, and every rule in the scanner's default
+   rule set that maps to a success criterion carries a `wcag<digits>` tag for it.
+
+## Decision
+
+**Read the mapping from the rule tags.** A hand-authored table is a second
+source of truth for something axe already states, drifts on every axe upgrade,
+and is exactly the kind of transcription that ships wrong. The scan layer now
+carries each finding's `tags` verbatim (`ScanFinding.tags`), and a pure
+function `clausesFor(tags)` in `src/report/clauses.ts` derives:
+
+- **WCAG success criteria** from `^wcag(\d)(\d)(\d+)$` — first two digits are
+  the principle and guideline, the rest is the criterion: `wcag143` → `1.4.3`,
+  `wcag1410` → `1.4.10`. Level tags (`wcag2a`, `wcag2aa`, `wcag21aa`) keep
+  letters after `wcag` and never match.
+- **EN 301 549 clauses** from `^EN-(\d+(?:\.\d+)+)$`: `EN-9.1.4.3` → `9.1.4.3`.
+  The bare `EN-301-549` marker uses hyphens, not dots, so it is skipped — it
+  says a rule maps to the standard, not to which clause.
+
+Everything else — `cat.*`, `ACT`, `TTv5`, `section508*`, `RGAA*`,
+`best-practice`, `experimental` — is ignored. Results are deduped and sorted
+numerically (`1.4.10` after `1.4.3`).
+
+**Where clauses live in the report.** `buildReport` attaches
+`clauses: { wcagSc, en301549 }` to every finding (violations and incomplete
+alike), and `summary` gains `breachedSuccessCriteria` and
+`breachedEn301549Clauses` — the distinct clauses across all *violations*.
+Incomplete results are excluded from that rollup: they are unconfirmed, and a
+rollup is a statement that the site breaches these clauses. The report's
+`pages` are therefore no longer the scan pages verbatim; the findings inside
+are enriched, the failure entries pass through unchanged.
+
+**BFSG.** The BFSG names no clauses of its own for web content. It grants a
+presumption of conformity (BFSG § 3 (1), § 4) to anything meeting the
+harmonised standard, and for ICT that standard is EN 301 549, whose Chapter 9
+("Web") is WCAG 2.1 level A/AA. So the EN 301 549 clauses this mapping emits
+*are* the BFSG-relevant citations; there is no separate BFSG layer to model,
+and inventing paragraph numbers for one would be worse than nothing. The legal
+chain (BFSG § 3/§ 4 → EN 301 549 § 9 → WCAG 2.1) is documentation, recorded
+here and in the README, not report data.
+
+## Consequences
+
+- `schemaVersion` stays `1`: `tags` on findings, `clauses` on findings, and the
+  two `summary` arrays are all additive, and nothing consumes a published
+  report yet. As ADR 0003 already noted, the version starts mattering at the
+  first release — that release freezes this shape.
+- The mapping tracks axe-core. An axe upgrade that renames a tag or corrects a
+  rule's criteria changes the scanner's output with no code change here. The
+  golden e2e test (`src/scan/scan.e2e.test.ts`) pins the clauses for the five
+  fixture rules against `fixtures/SITE_TRUTH.md`, so such a change fails CI and
+  gets reviewed rather than shipping silently.
+- A rule that carries no `wcag<digits>` / `EN-` tag (a `best-practice` rule)
+  contributes an empty `clauses` and nothing to the rollup. With the default
+  WCAG rule set none such fire, but a custom `wcagTags` could pull one in; the
+  finding still appears in the report, just without a citation.
+- `clausesFor` is independent of axe at runtime — it takes a `string[]`. Tests
+  feed it the real recorded tag arrays rather than calling into axe.

package/docs/adr/0005-html-report-rendering.md

@@ -0,0 +1,71 @@
+# 5. HTML report rendering
+
+Date: 2026-08-28
+
+## Status
+
+Accepted
+
+## Context
+
+`bfsg.config.yaml` has always advertised JSON, HTML and PDF output and a
+`reportLanguage: de | en` setting, but only JSON was written and
+`reportLanguage` was loaded and then ignored. The JSON report (ADR 0002) is
+the machine artifact; a compliance run also needs something a person —
+often a non-engineer acting on the BFSG obligation — can open and read, in
+German by default.
+
+## Decision
+
+Add `renderHtmlReport(report, locale)` (`src/report/render.ts`) and
+`writeHtmlReport(html, outputDir)` (`src/report/write.ts`). The CLI writes
+`<outputDir>/report.html` right after `report.json`, using
+`config.reportLanguage`.
+
+**Self-contained single file.** One HTML document with an inline `<style>`,
+no JavaScript, and no external assets. It has to survive being archived as a
+CI artifact, opened offline, emailed, and — next change — printed to PDF by
+a headless browser. A build step or an asset bundle would work against all
+of that.
+
+**Hand-written string table, not an i18n library** (`src/report/i18n.ts`).
+Two locales, ~40 keys, chosen once from config with no runtime negotiation.
+Every label is phrased to sidestep grammatical agreement
+(`Affected elements: 3`, not `3 elements`), so ICU plural handling buys
+nothing. A dependency here would be more API surface and supply chain than
+the problem has.
+
+**The JSON stays language-neutral.** A locale is a rendering argument, not
+report data: the same scan produces one `report.json` and can be rendered to
+either language. `Report` is unchanged, so `schemaVersion` is untouched —
+HTML is not part of the schema.
+
+**What the page leads with.** Verdict banner, then the summary, then the
+breached WCAG / EN 301 549 clauses from the scan (ADR 0004) as the headline
+compliance statement, then findings per page with the rule, impact, its
+clauses, the fix link, and the offending node markup as evidence. All
+interpolated text — URLs, rule evidence, error strings — is HTML-escaped;
+node HTML from axe is attacker-influenced (it is markup from the scanned
+site) and must never render as live markup in the report.
+
+## Consequences
+
+- A new on-disk artifact, `report.html`, overwritten each run like the JSON.
+  `outputDir` is git-ignored; `maxPages` still bounds total size, and the
+  full node markup makes the HTML larger than the JSON per finding.
+- The renderer duplicates presentation logic that a consumer of the JSON
+  would otherwise write. That is the point of shipping it, but it means the
+  clause/summary semantics now have two readers (JSON consumers and this
+  renderer) to keep in step.
+- Adding a locale is a third column in `i18n.ts` plus a `Locale` union
+  member; the "same keys in every locale" test fails until it is complete.
+- `reportLanguage` localises the report's own chrome — headings, labels,
+  the verdict, the legal note. axe-core's rule `help` text and node failure
+  summaries are English and are shown as axe emits them; translating
+  upstream rule copy is out of scope.
+- PDF is still not produced. It needs a browser in the report path
+  (Playwright's `page.pdf()` over this HTML) and its own lifecycle and
+  testing story — a separate change. The print CSS in this one is written
+  with that in mind.
+- The CLI still only prints "N rule(s) violated" — surfacing the breached
+  clauses in the terminal is a separate, small follow-up.

package/docs/adr/0006-pdf-report-rendering.md

@@ -0,0 +1,58 @@
+# 6. PDF report rendering
+
+Date: 2026-08-28
+
+## Status
+
+Accepted
+
+## Context
+
+`bfsg.config.yaml` has always advertised PDF output alongside JSON and HTML.
+JSON landed in ADR 0002 and the localised HTML in ADR 0005; the HTML is
+already a self-contained document with inline CSS, no JavaScript, and a
+`@media print` block written for this step. What is left is turning that
+HTML into a PDF a non-engineer can file as the compliance record.
+
+## Decision
+
+**Print the HTML with headless Chromium** (`page.setContent(html)` then
+`page.pdf()`), in a new `renderPdfReport(html, browser)` in the report
+module. Playwright and Chromium are already the scanner's engine, so this
+adds no dependency and no system binary. Chromium is the only engine
+Playwright can print with; that constraint is already accepted everywhere
+else in the tool. The HTML needs no server and no network — it carries its
+own styles — so `setContent` is enough.
+
+**One browser per run, owned by `run.ts`.** Until now `scan` launched and
+closed its own Chromium. `run` now launches one Chromium (unless a browser
+is injected, as tests do), passes it to `scan`, reuses it to print the PDF,
+and closes it in a `finally`. `run` closes only a browser it launched
+itself — the same contract `scan` keeps for an injected one. This replaces
+one launch with one launch; it does not add a second.
+
+**The PDF is written where the JSON and HTML are** — before the
+partial-failure check, so a run that exits `3` for unreachable pages still
+leaves all three artifacts. A failure inside `renderPdfReport` propagates
+like any other write failure; the JSON and HTML are already on disk by
+then, and there is no reason to treat a broken PDF render as recoverable
+when a broken HTML write is not.
+
+**A4, backgrounds on, ~15 mm margins.** Fixed, not configurable: the report
+is a document to read and file, not a layout to tune.
+
+## Consequences
+
+- `run` now has a browser lifecycle. The early exits for bad config (`2`)
+  and empty discovery (`3`) still return before any launch. The scan and
+  report body moved into a `scanAndReport` helper so the `try/finally` that
+  owns the browser stays readable.
+- `writeArtifact` now takes `string | Uint8Array`; `writeReport` and
+  `writeHtmlReport` are unchanged in behaviour.
+- PDF size tracks HTML size, which `maxPages` bounds. A large scan produces
+  a large PDF; that is the same trade-off ADR 0002 made for the JSON.
+- `renderPdfReport` needs a real Chromium to test, so its test launches one
+  like the scan tests do — it is not a pure unit like `renderHtmlReport`.
+- Still not configurable: page size, margins, and whether the PDF is
+  written at all. If a user only wants JSON, that is a `--format` flag for
+  later, not part of adding the format the config already promises.

package/docs/adr/0007-cli-argument-surface.md

@@ -0,0 +1,73 @@
+# 7. CLI argument surface
+
+Date: 2026-08-31
+
+## Status
+
+Accepted
+
+## Context
+
+Until now the CLI understood one flag, `--config <path>`, and defaulted to
+`bfsg.config.yaml`. Scanning a single URL meant writing a YAML file first,
+`--help` and `--version` did not exist (`run(['--help'])` tried to load a
+config and exited 2), and the report formats could not be narrowed — every
+run wrote JSON, HTML, and PDF.
+
+## Decision
+
+**Parser: `node:util` `parseArgs`.** Built in, no dependency. `strict` mode
+rejects unknown options; a `TypeError` from it is rewrapped as `ConfigError`
+so bad arguments exit 2 like a bad config.
+
+**Argument surface:**
+
+```
+bfsg-scanner [url] [options]
+
+  -c, --config <path>        YAML config (default: bfsg.config.yaml)
+      --fail-on <level>      critical | serious | moderate | minor
+      --report-language <l>  de | en
+      --output-dir <dir>
+      --format <list>        subset of json,html,pdf
+  -h, --help
+  -V, --version
+```
+
+- A **positional URL** scans that page with defaults, no config file — the
+  common first-run case. It is mutually exclusive with `--config`; passing
+  both, or more than one URL, is an error.
+- Only the four knobs a one-off run realistically varies get a flag.
+  `maxPages`, `wcagTags`, `excludePaths` are not mirrored: a run that needs
+  those needs a config file, and a flag for every field is a maintenance
+  cost with little payoff.
+
+**`reportFormats` is a config field, not just a flag.** Every other knob
+lives in the config; formats do too (`reportFormats`, default all three,
+minimum one). `--format` overrides it. This is the `--format` flag ADR 0006
+foresaw.
+
+**One validation path.** CLI overrides are collected as raw values and
+merged into the config object, which is then run through `configSchema`
+(the new exported `parseConfig`). `--fail-on nope` fails with the same
+machinery and message shape as `failOn: nope` in a file. `loadConfig` now
+delegates its validation to `parseConfig` too.
+
+**`toolInfo()` moved to `src/shared/`.** The package-manifest read that
+stamps the report's `tool` field is the same thing `--version` needs; it
+had one copy in `src/report/build.ts` and now has one shared copy.
+
+## Consequences
+
+- `reportFormats` selects which artifacts are written. With `pdf` absent the
+  run skips the browser `page.pdf()` call; with only `json` it skips HTML
+  rendering entirely. `buildReport` always runs — the verdict, exit code,
+  and breached-clause summary do not depend on any file being written.
+- A minimum of one format: a run that writes nothing is almost always a
+  mistake, and `outputDir` can already point at a throwaway directory for
+  the rare "exit code only" case.
+- `parseArgs` config errors ("Option '--config' argument missing",
+  "Unknown option '--nope'") surface verbatim. They are clear enough not to
+  reword.
+- Not added: a positional URL list, `--quiet`/`--verbose`, config-file
+  discovery up the directory tree. Out of scope until asked for.

package/docs/adr/0008-report-json-schema.md

@@ -0,0 +1,59 @@
+# 8. A JSON Schema for report.json
+
+Date: 2026-08-31
+
+## Status
+
+Accepted
+
+## Context
+
+`report.json` has carried `schemaVersion: 1` since ADR 0002, and ADRs 0003,
+0004, and 0005 each noted that the version "starts mattering at the first
+release" and deferred a formal schema. Nothing has ever described the file's
+shape to a consumer, and nothing stops an incompatible change to
+`src/report/types.ts` from shipping without anyone noticing the on-disk
+format moved.
+
+## Decision
+
+Add **`schema/report.v1.json`**, a JSON Schema (draft 2020-12) for the
+report envelope, and ship it in the package (`files`).
+
+**Hand-written, not generated.** The report types are plain TypeScript
+interfaces, not zod schemas, so there is nothing to derive a schema from
+without adding a type-to-schema codegen tool and a build step. The schema
+is written by hand against `types.ts`.
+
+**A validation test is the drift guard.** `src/report/report-schema.test.ts`
+builds a report with `buildReport` from a synthetic scan result that
+exercises every branch — rated and unrated violations, clauses present and
+absent, an incomplete result, a clean page, a failed page — and asserts it
+validates. Every object in the schema sets `additionalProperties: false`
+with a complete `required` list, so **adding or removing a field in
+`types.ts` breaks this test** until the schema is updated to match. The
+test also checks that `SCHEMA_VERSION` equals the schema's `const`.
+
+**`schemaVersion: 1` is now frozen.** A backwards-incompatible change to the
+envelope — a removed field, a narrowed type, a restructured `pages` entry —
+requires a new `schema/report.v2.json` and bumping `SCHEMA_VERSION`.
+Additive, optional fields can stay at 1.
+
+**`ajv` as a dev dependency** (test only), with a one-line `date-time`
+format check registered by hand rather than pulling in `ajv-formats`.
+
+## Consequences
+
+- The schema describes the report *envelope*. It does not re-validate
+  axe-core's internals: `node.target` is "array of strings or string
+  arrays" and `tags` / clause strings are unconstrained beyond being
+  strings. Their correctness is axe's and the clause mapper's job, tested
+  elsewhere.
+- Two sources of truth for the report shape now exist — `types.ts` and this
+  file — kept in step by the test rather than by generation. That is the
+  cost of not adding codegen; the test makes the cost visible rather than
+  silent.
+- Consumers can validate a stored `report.json` against the shipped schema
+  with any JSON Schema validator.
+- `format: date-time` on `generatedAt` is advisory in the file (many
+  validators do not enforce formats by default); the test enforces it.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "bfsg-scanner",
+  "version": "0.1.0",
+  "description": "WCAG 2.1 AA / BFSG compliance scanner built on Playwright and axe-core",
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "wcag",
+    "wcag2",
+    "en-301-549",
+    "bfsg",
+    "axe-core",
+    "playwright",
+    "accessibility-testing",
+    "compliance",
+    "cli"
+  ],
+  "homepage": "https://github.com/MihaelaAghirculesei/bfsg-scanner#readme",
+  "bugs": {
+    "url": "https://github.com/MihaelaAghirculesei/bfsg-scanner/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MihaelaAghirculesei/bfsg-scanner.git"
+  },
+  "license": "MIT",
+  "author": "Mihaela Aghirculesei",
+  "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "bfsg-scanner": "dist/cli/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "prepare": "git config core.hooksPath .githooks || exit 0",
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "cli": "tsx src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "npm run typecheck && npm run lint && npm run test",
+    "prepublishOnly": "npm run verify && npm run build"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "axe-core": "4.13.0",
+    "fast-xml-parser": "5.11.0",
+    "playwright": "1.62.1",
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "24.9.2",
+    "ajv": "8.20.0",
+    "rimraf": "6.0.1",
+    "tsx": "4.23.12",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  }
+}