bfsg-scanner 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-01
+
+First release.
+
+### Added
+
+- Site discovery: `sitemap.xml` first, then a `robots.txt`-respecting
+  breadth-first crawl, bounded by `maxPages` and `excludePaths`.
+- Scan engine: axe-core in Chromium via Playwright, with a concurrency pool,
+  a per-host rate limit, retries, and an identifiable User-Agent.
+- `report.json` — versioned, self-describing (`schemaVersion: 1`), with a
+  shipped JSON Schema at `schema/report.v1.json`.
+- Clause mapping: every finding is tagged with its WCAG success criteria and
+  EN 301 549 clauses, read from axe-core rule metadata; the report rolls up
+  the distinct breached clauses.
+- `failOn` severity threshold driving the process exit code (`0`/`1`), plus
+  `2` for bad configuration and `3` for an incomplete scan.
+- Localised `report.html` (German or English) — a self-contained page — and
+  `report.pdf` (the HTML printed to A4).
+- CLI: a positional `url` argument for a one-page scan without a config
+  file, `--config`, `--fail-on`, `--report-language`, `--output-dir`,
+  `--format`, `--help`, `--version`.
+- `reportFormats` config key / `--format` flag to choose which report files
+  are written.
+- Distributable package: a `bfsg-scanner` bin and a `dist` build that
+  excludes tests.
+
+[Unreleased]: https://github.com/MihaelaAghirculesei/bfsg-scanner/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/MihaelaAghirculesei/bfsg-scanner/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihaela Aghirculesei
+
+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,147 @@
+# bfsg-scanner
+
+Automated **WCAG 2.1 AA** accessibility scanning for a whole site, built on
+[Playwright](https://playwright.dev) and [axe-core](https://github.com/dequelabs/axe-core).
+Every finding is mapped to the clause it breaches in
+[EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/) and,
+through it, Germany's [BFSG](https://www.gesetze-im-internet.de/bfsg/) — so a
+run produces a citeable compliance report, not just a list of rule IDs.
+
+Requires **Node.js ≥ 24**.
+
+## What it does
+
+1. **Discovers** the pages of a site — `sitemap.xml` first, then a
+   `robots.txt`-respecting breadth-first crawl, bounded by `maxPages`.
+2. **Scans** each page in a real Chromium via axe-core, with a concurrency
+   pool and a per-host rate limit, sending an identifiable User-Agent.
+3. **Reports** the result as `report.json`, `report.html` (German or English),
+   and `report.pdf`, with each violation tagged with its WCAG success
+   criteria and EN 301 549 clauses.
+4. **Exits non-zero** when violations reach a configurable severity
+   threshold, so a CI job can gate a merge on accessibility.
+
+## Quick start
+
+```sh
+npx bfsg-scanner https://example.de
+
+# scan one page, JSON only, fail the process on any "critical" finding:
+npx bfsg-scanner https://example.de --format json --fail-on critical
+```
+
+The first run needs a Chromium build for Playwright:
+
+```sh
+npx playwright install chromium
+```
+
+Install it for repeated use with `npm i -g bfsg-scanner`.
+
+## From source
+
+```sh
+git clone https://github.com/MihaelaAghirculesei/bfsg-scanner.git
+cd bfsg-scanner
+npm install
+npx playwright install chromium
+npm run build
+node dist/cli/index.js --help   # or `npm link` for the bfsg-scanner command
+```
+
+## Usage
+
+```
+bfsg-scanner [url] [options]
+```
+
+| Argument / option        | Meaning |
+|--------------------------|---------|
+| `url`                    | Base URL to scan. Omit it to load a config file instead. |
+| `-c, --config <path>`    | YAML config file (default: `bfsg.config.yaml`). Not allowed together with a `url`. |
+| `--fail-on <level>`      | `critical` \| `serious` \| `moderate` \| `minor` (default: `serious`). |
+| `--report-language <l>`  | `de` \| `en` (default: `de`). |
+| `--output-dir <dir>`     | Directory for the report files (default: `reports`). |
+| `--format <list>`        | Comma-separated subset of `json,html,pdf` (default: all three). |
+| `-h, --help`             | Show help and exit. |
+| `-V, --version`          | Print the version and exit. |
+
+A `url` argument scans that one page with defaults; anything more (a page
+budget, excluded paths, a custom rule set) needs a config file.
+
+## Configuration
+
+A YAML file — `bfsg.config.yaml` by default, or `--config <path>`. Only
+`baseUrl` is required; every other key falls back to the default shown.
+
+```yaml
+baseUrl: "https://example.de"     # required
+
+maxPages: 50                      # sitemap + crawl combined
+wcagTags:                         # axe rule sets to run
+  - wcag2a
+  - wcag2aa
+  - wcag21aa
+excludePaths: []                  # URL-path globs to skip while crawling
+outputDir: reports                # where the report files are written
+failOn: serious                   # critical | serious | moderate | minor
+reportLanguage: de                # de | en — language of the HTML/PDF report
+reportFormats:                    # any non-empty subset of json | html | pdf
+  - json
+  - html
+  - pdf
+```
+
+CLI flags override the matching config key. See the annotated
+[`bfsg.config.yaml`](./bfsg.config.yaml) in this repo for a working example.
+
+## Output
+
+Written to `outputDir`, overwritten each run:
+
+- **`report.json`** — the machine-readable result. Its shape is described by
+  [`schema/report.v1.json`](./schema/report.v1.json) (JSON Schema, shipped
+  with the package); `schemaVersion` is `1`.
+- **`report.html`** — a self-contained page (no external assets) leading with
+  the pass/fail verdict, the breached WCAG / EN 301 549 clauses, and the
+  findings per page.
+- **`report.pdf`** — the HTML report printed to A4, for filing as the
+  compliance record.
+
+The terminal prints a summary and the distinct breached clauses.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | Scan completed; nothing at or above `--fail-on`. |
+| `1`  | Scan completed; violations at or above `--fail-on`. |
+| `2`  | Invalid arguments or 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
+"no violations found" would be a claim the data cannot support.
+
+## How the clause mapping works
+
+axe-core's rule metadata already carries the mapping: a rule tagged
+`wcag143` checks WCAG SC 1.4.3, `EN-9.1.4.3` maps it to that EN 301 549
+clause. The scanner reads those tags rather than maintaining a hand-authored
+table. § 4 BFSG presumes conformity for content that meets the relevant
+harmonised standard — for the web, EN 301 549, whose Chapter 9 references
+WCAG 2.1 level A/AA — so the EN 301 549 clauses in the report are the
+corresponding citations. This is not legal advice.
+
+## Responsible use
+
+This tool sends real traffic to whatever site you point it at. Scan only
+sites you own or are authorised to test. See
+[`docs/SCANNING-ETHICS.md`](./docs/SCANNING-ETHICS.md).
+
+## Design decisions
+
+Each significant choice is recorded as an ADR in [`docs/adr/`](./docs/adr).
+
+## License
+
+[MIT](./LICENSE)

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+process.exitCode = await run(process.argv.slice(2));
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,OAAO,CAAC,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/cli/run.d.ts

@@ -0,0 +1,29 @@
+import { type ScanDeps } from '../scan/index.js';
+interface CliArgs {
+    readonly help: boolean;
+    readonly version: boolean;
+    /** Explicit --config path, if given. */
+    readonly configPath?: string;
+    /** Positional base URL, if given. */
+    readonly url?: string;
+    /**
+     * Config fields overridden on the command line, still as raw values —
+     * `configSchema` is the single place they get validated.
+     */
+    readonly overrides: Record<string, unknown>;
+}
+/**
+ * Exit code contract:
+ *   0 - scan completed, nothing at or above the `failOn` threshold
+ *   1 - scan completed, violations at or above `failOn` were found
+ *   2 - invalid arguments or configuration
+ *   3 - no pages were discovered, or one or more pages could not be scanned
+ *
+ * 3 outranks 1: a run with unreachable pages scanned an incomplete site, so
+ * "no violations found" would be a claim the data cannot support. The
+ * report is still written first, so partial results and failure entries
+ * survive either way.
+ */
+export declare function parseCliArgs(argv: readonly string[]): CliArgs;
+export declare function run(argv: readonly string[], deps?: ScanDeps): Promise<number>;
+export {};

package/dist/cli/run.js

@@ -0,0 +1,202 @@
+import { parseArgs } from 'node:util';
+import { chromium } from 'playwright';
+import { ConfigError, loadConfig, parseConfig } from '../config/index.js';
+import { discoverSite } from '../discovery/index.js';
+import { buildReport, renderHtmlReport, renderPdfReport, writeHtmlReport, writePdfReport, writeReport, } from '../report/index.js';
+import { scan } from '../scan/index.js';
+import { toolInfo } from '../shared/index.js';
+const DEFAULT_CONFIG_PATH = 'bfsg.config.yaml';
+const HELP_TEXT = `bfsg-scanner — WCAG 2.1 AA / EN 301 549 / BFSG accessibility scanner
+
+Usage:
+  bfsg-scanner [url] [options]
+
+Arguments:
+  url                        Base URL to scan. Omit to load a config file instead.
+
+Options:
+  -c, --config <path>        YAML config file (default: ${DEFAULT_CONFIG_PATH}).
+                             Not allowed together with a url argument.
+      --fail-on <level>      critical | serious | moderate | minor (default: serious).
+      --report-language <l>  de | en (default: de).
+      --output-dir <dir>     Directory for the report files (default: reports).
+      --format <list>        Comma-separated subset of json,html,pdf (default: all three).
+  -h, --help                 Show this help and exit.
+  -V, --version              Print the version and exit.
+
+Exit codes:
+  0  scan completed, nothing at or above the fail-on threshold
+  1  scan completed, violations at or above fail-on
+  2  invalid arguments or configuration
+  3  no pages discovered, or a page could not be scanned
+`;
+const OPTIONS = {
+    help: { type: 'boolean', short: 'h' },
+    version: { type: 'boolean', short: 'V' },
+    config: { type: 'string', short: 'c' },
+    'fail-on': { type: 'string' },
+    'report-language': { type: 'string' },
+    'output-dir': { type: 'string' },
+    format: { type: 'string' },
+};
+function safeParseArgs(argv) {
+    try {
+        return parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true });
+    }
+    catch (cause) {
+        throw new ConfigError(cause.message);
+    }
+}
+/**
+ * Exit code contract:
+ *   0 - scan completed, nothing at or above the `failOn` threshold
+ *   1 - scan completed, violations at or above `failOn` were found
+ *   2 - invalid arguments or configuration
+ *   3 - no pages were discovered, or one or more pages could not be scanned
+ *
+ * 3 outranks 1: a run with unreachable pages scanned an incomplete site, so
+ * "no violations found" would be a claim the data cannot support. The
+ * report is still written first, so partial results and failure entries
+ * survive either way.
+ */
+export function parseCliArgs(argv) {
+    const { values, positionals } = safeParseArgs(argv);
+    if (positionals.length > 1) {
+        throw new ConfigError(`Expected at most one URL argument, got ${positionals.length}.`);
+    }
+    const url = positionals[0];
+    if (url !== undefined && values.config !== undefined) {
+        throw new ConfigError('Pass a URL argument or --config, not both.');
+    }
+    const overrides = {};
+    if (values['fail-on'] !== undefined) {
+        overrides.failOn = values['fail-on'];
+    }
+    if (values['report-language'] !== undefined) {
+        overrides.reportLanguage = values['report-language'];
+    }
+    if (values['output-dir'] !== undefined) {
+        overrides.outputDir = values['output-dir'];
+    }
+    if (values.format !== undefined) {
+        overrides.reportFormats = values.format
+            .split(',')
+            .map((part) => part.trim())
+            .filter((part) => part.length > 0);
+    }
+    return {
+        help: values.help ?? false,
+        version: values.version ?? false,
+        overrides,
+        ...(values.config !== undefined ? { configPath: values.config } : {}),
+        ...(url !== undefined ? { url } : {}),
+    };
+}
+function resolveConfig(cli) {
+    if (cli.url !== undefined) {
+        return parseConfig({ baseUrl: cli.url, ...cli.overrides }, 'command-line arguments');
+    }
+    const fromFile = loadConfig(cli.configPath ?? DEFAULT_CONFIG_PATH);
+    if (Object.keys(cli.overrides).length === 0) {
+        return fromFile;
+    }
+    return parseConfig({ ...fromFile, ...cli.overrides }, 'command-line arguments');
+}
+export async function run(argv, deps = {}) {
+    let cli;
+    try {
+        cli = parseCliArgs(argv);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    if (cli.help) {
+        console.log(HELP_TEXT);
+        return 0;
+    }
+    if (cli.version) {
+        const { name, version } = toolInfo();
+        console.log(`${name} ${version}`);
+        return 0;
+    }
+    let config;
+    try {
+        config = resolveConfig(cli);
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            console.error(error.message);
+            return 2;
+        }
+        throw error;
+    }
+    const urls = await discoverSite({
+        baseUrl: config.baseUrl,
+        maxPages: config.maxPages,
+        excludePaths: config.excludePaths,
+    });
+    if (urls.length === 0) {
+        console.error(`No scannable pages discovered for ${config.baseUrl}`);
+        return 3;
+    }
+    console.log(`Discovered ${urls.length} page(s) to scan.`);
+    // One Chromium for the whole run: the scan uses it, and the PDF report is
+    // printed with it. `run` closes only a browser it launched itself, so an
+    // injected one (tests) is left to its owner — the same contract `scan` keeps.
+    const browser = deps.browser ?? (await chromium.launch());
+    const launchedHere = deps.browser === undefined;
+    try {
+        return await scanAndReport(config, urls, browser);
+    }
+    finally {
+        if (launchedHere) {
+            await browser.close();
+        }
+    }
+}
+async function scanAndReport(config, urls, browser) {
+    const result = await scan(urls, { wcagTags: config.wcagTags }, { browser });
+    const report = buildReport(result, {
+        baseUrl: config.baseUrl,
+        wcagTags: config.wcagTags,
+        failOn: config.failOn,
+    });
+    const formats = new Set(config.reportFormats);
+    if (formats.has('json')) {
+        console.log(`Report written to ${await writeReport(report, config.outputDir)}`);
+    }
+    if (formats.has('html') || formats.has('pdf')) {
+        const html = renderHtmlReport(report, config.reportLanguage);
+        if (formats.has('html')) {
+            console.log(`HTML report written to ${await writeHtmlReport(html, config.outputDir)}`);
+        }
+        if (formats.has('pdf')) {
+            const pdf = await renderPdfReport(html, browser);
+            console.log(`PDF report written to ${await writePdfReport(pdf, config.outputDir)}`);
+        }
+    }
+    const failedPages = result.pages.filter((page) => page.status === 'error');
+    if (failedPages.length > 0) {
+        for (const page of failedPages) {
+            console.error(`Failed to scan ${page.url}: ${page.error}`);
+        }
+        return 3;
+    }
+    console.log(`Scanned ${report.summary.pagesScanned} page(s), ${report.summary.totalViolations} rule(s) violated.`);
+    const { breachedSuccessCriteria, breachedEn301549Clauses } = report.summary;
+    if (breachedSuccessCriteria.length > 0) {
+        console.log(`WCAG 2.1 SC breached: ${breachedSuccessCriteria.join(', ')}`);
+        console.log(`EN 301 549 clauses breached: ${breachedEn301549Clauses.join(', ')}`);
+    }
+    const { verdict } = report;
+    if (verdict.unrankedViolations > 0) {
+        console.warn(`${verdict.unrankedViolations} violation(s) carry no impact rating and were excluded from the ${config.failOn} threshold. Review them in the report.`);
+    }
+    if (!verdict.passed) {
+        console.error(`${verdict.violationsAtOrAboveThreshold} violation(s) at or above "${config.failOn}".`);
+        return 1;
+    }
+    return 0;
+}
+//# sourceMappingURL=run.js.map

package/dist/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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"}

package/dist/config/index.d.ts

@@ -0,0 +1,2 @@
+export { ConfigError, loadConfig, parseConfig } from './load.js';
+export { type Config, configSchema, failOnSchema, type ReportFormat, reportFormatSchema, reportLanguageSchema, wcagTagSchema, } from './schema.js';

package/dist/config/index.js

@@ -0,0 +1,3 @@
+export { ConfigError, loadConfig, parseConfig } from './load.js';
+export { configSchema, failOnSchema, reportFormatSchema, reportLanguageSchema, wcagTagSchema, } from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAEL,YAAY,EACZ,YAAY,EAEZ,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/config/load.d.ts

@@ -0,0 +1,12 @@
+import { type Config } from './schema.js';
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates an already-parsed config object against the schema, applying
+ * defaults. Throws {@link ConfigError} with all issues listed on failure.
+ * `source` names where the object came from, for the error message
+ * (e.g. a quoted file path, or "command-line arguments").
+ */
+export declare function parseConfig(raw: unknown, source: string): Config;
+export declare function loadConfig(path: string): Config;

package/dist/config/load.js

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { configSchema } from './schema.js';
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigError';
+    }
+}
+/**
+ * Validates an already-parsed config object against the schema, applying
+ * defaults. Throws {@link ConfigError} with all issues listed on failure.
+ * `source` names where the object came from, for the error message
+ * (e.g. a quoted file path, or "command-line arguments").
+ */
+export function parseConfig(raw, source) {
+    const result = configSchema.safeParse(raw);
+    if (!result.success) {
+        throw new ConfigError(formatIssues(source, result.error));
+    }
+    return result.data;
+}
+export function loadConfig(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (cause) {
+        throw new ConfigError(`Cannot read config file at "${path}": ${cause.message}`);
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (cause) {
+        throw new ConfigError(`Cannot parse "${path}" as YAML: ${cause.message}`);
+    }
+    return parseConfig(parsed, `"${path}"`);
+}
+function formatIssues(source, error) {
+    const lines = error.issues.map((issue) => {
+        const field = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `  - ${field}: ${issue.message}`;
+    });
+    return `Invalid config (${source}):\n${lines.join('\n')}`;
+}
+//# sourceMappingURL=load.js.map

package/dist/config/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAE1C,OAAO,EAAe,YAAY,EAAE,MAAM,aAAa,CAAC;AAExD,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,MAAc;IACtD,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,WAAW,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,+BAA+B,IAAI,MAAO,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,WAAW,CAAC,iBAAiB,IAAI,cAAe,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,WAAW,CAAC,MAAM,EAAE,IAAI,IAAI,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,KAAiB;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACvC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACtE,OAAO,OAAO,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IAC1C,CAAC,CAAC,CAAC;IACH,OAAO,mBAAmB,MAAM,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AAC5D,CAAC"}

package/dist/config/schema.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export declare const wcagTagSchema: z.ZodEnum<{
+    wcag2a: "wcag2a";
+    wcag2aa: "wcag2aa";
+    wcag21a: "wcag21a";
+    wcag21aa: "wcag21aa";
+}>;
+export declare const failOnSchema: z.ZodEnum<{
+    critical: "critical";
+    serious: "serious";
+    moderate: "moderate";
+    minor: "minor";
+}>;
+export declare const reportLanguageSchema: z.ZodEnum<{
+    de: "de";
+    en: "en";
+}>;
+export declare const reportFormatSchema: z.ZodEnum<{
+    json: "json";
+    html: "html";
+    pdf: "pdf";
+}>;
+export declare const configSchema: z.ZodObject<{
+    baseUrl: z.ZodURL;
+    maxPages: z.ZodDefault<z.ZodNumber>;
+    wcagTags: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        wcag2a: "wcag2a";
+        wcag2aa: "wcag2aa";
+        wcag21a: "wcag21a";
+        wcag21aa: "wcag21aa";
+    }>>>;
+    excludePaths: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    outputDir: z.ZodDefault<z.ZodString>;
+    failOn: z.ZodDefault<z.ZodEnum<{
+        critical: "critical";
+        serious: "serious";
+        moderate: "moderate";
+        minor: "minor";
+    }>>;
+    reportLanguage: z.ZodDefault<z.ZodEnum<{
+        de: "de";
+        en: "en";
+    }>>;
+    reportFormats: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        json: "json";
+        html: "html";
+        pdf: "pdf";
+    }>>>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof configSchema>;
+export type ReportFormat = z.infer<typeof reportFormatSchema>;

package/dist/config/schema.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const wcagTagSchema = z.enum(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']);
+export const failOnSchema = z.enum(['critical', 'serious', 'moderate', 'minor']);
+export const reportLanguageSchema = z.enum(['de', 'en']);
+export const reportFormatSchema = z.enum(['json', 'html', 'pdf']);
+export const configSchema = z.strictObject({
+    baseUrl: z.url(),
+    maxPages: z.number().int().positive().max(1000).default(50),
+    wcagTags: z.array(wcagTagSchema).min(1).default(['wcag2a', 'wcag2aa', 'wcag21aa']),
+    excludePaths: z.array(z.string()).default([]),
+    outputDir: z.string().min(1).default('reports'),
+    failOn: failOnSchema.default('serious'),
+    reportLanguage: reportLanguageSchema.default('de'),
+    reportFormats: z.array(reportFormatSchema).min(1).default(['json', 'html', 'pdf']),
+});
+//# sourceMappingURL=schema.js.map

package/dist/config/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/config/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;AAElF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;AAEzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAElE,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC3D,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IAClF,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC/C,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC;IACvC,cAAc,EAAE,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC;IAClD,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;CACnF,CAAC,CAAC"}

package/dist/discovery/crawl.d.ts

@@ -0,0 +1,21 @@
+export interface CrawlOptions {
+    readonly baseUrl: string;
+    readonly maxPages: number;
+    readonly excludePaths?: readonly string[];
+    /** Injectable for tests; defaults to the global fetch. */
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * Breadth-first fallback crawl, used when a site has no sitemap. Starts at
+ * baseUrl, follows same-origin links in document order, and stops once
+ * maxPages pages have been collected. robots.txt, the configured
+ * excludePaths, and non-page assets (mailto:, PDFs, images, ...) are all
+ * applied identically to the seed URL and to every discovered link, so a
+ * disallowed or excluded home page yields zero results rather than being
+ * scanned anyway.
+ *
+ * Deterministic: links are visited in a plain FIFO queue in the order they
+ * appear in each page's HTML, so the same input always produces the same
+ * page list in the same order.
+ */
+export declare function crawlSite(options: CrawlOptions): Promise<string[]>;