@a11y-skills/audit 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to `@a11y-skills/audit` are documented here. This project
 adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.4.0 — 2026-06-12
+
+### Added
+
+- `bin` CLI (`a11y-audit`): run all ten WCAG checks against a URL without a
+  Playwright test runner — `npx -y @a11y-skills/audit --url <url>`. Flags:
+  `--checks <list>`, `--output-dir`, `--screenshot`, `--list-checks`,
+  `--version`, `--help`. Exit codes: `0` = no violations, `1` = violations
+  found, `2` = runtime error. JSON output uses the same envelope as the
+  function API regardless of exit code.
+- `test/fixtures/cli-smoke.html`: network-independent smoke fixture (a page
+  with intentional axe violations) for the CI CLI smoke test.
+
+## 0.3.1
+
+### Fixed
+
+- `runFocusIndicatorCheck`: focus-triggered navigations slower than the
+  per-Tab settle window are no longer silently missed. The settle window is
+  now configurable via the new `navigationSettleMs` option (default: 50), and
+  a `framenavigated` listener additionally catches URL changes that commit and
+  revert within a single window. (#26)
+
 ## 0.3.0
 
 **Breaking** — every check now returns (and saves) a single axe-style envelope

package/README.ja.md

@@ -50,6 +50,70 @@ npm install -D pixelmatch pngjs   # runAutoPlayDetection を使う場合のみ
 > ESM 専用です。CommonJS ビルドは同梱しません。ESM（または ESM 出力の TypeScript）から
 > import してください。
 
+## CLI
+
+テストランナー不要で、コマンド 1 本で 10 検査すべてを実行できます。
+
+```sh
+npx -y @a11y-skills/audit --url https://example.com
+```
+
+npm 7 以降では peer dependencies（`@playwright/test`、`@axe-core/playwright`）が
+自動でインストールされます。初回は Chromium のインストールが必要です:
+
+```sh
+npx playwright install chromium
+```
+
+### フラグ
+
+| フラグ | デフォルト | 説明 |
+| --- | --- | --- |
+| `--url <url>` | `TEST_PAGE` 環境変数 | 対象 URL。`--url` が環境変数より優先されます。どちらも未設定の場合は usage を表示して exit 2。 |
+| `--checks <list>` | `all` | カンマ区切りのチェック名（下記一覧参照）。 |
+| `--output-dir <dir>` | `./a11y-audit-results` | 結果 JSON の出力ディレクトリ。 |
+| `--screenshot` | off | focus-indicator のスクリーンショットを有効化。 |
+| `--list-checks` | — | チェック名一覧を出力して exit 0。 |
+| `--version` | — | バージョンを出力して exit 0。 |
+| `--help` | — | usage を出力して exit 0。 |
+
+### チェック名一覧
+
+```
+axe-audit
+focus-indicator-check
+reflow-check
+text-spacing-check
+zoom-200-check
+orientation-check
+autocomplete-audit
+time-limit-detector
+auto-play-detection
+target-size-check
+```
+
+### 終了コード
+
+| コード | 意味 |
+| --- | --- |
+| `0` | すべてのチェックが完了し、違反なし。 |
+| `1` | すべてのチェックが完了し、1 件以上の違反あり。 |
+| `2` | 実行時エラー — 引数不正・peer 欠落・ナビゲーション失敗・チェックのクラッシュ。 |
+
+exit コードが非 0 でも、完了したチェックの JSON は必ず書き出されます。
+
+### peer 要件
+
+`@playwright/test >=1.50.0` および `@axe-core/playwright >=4.10.0` が必要です。
+見つからない場合は exit 2 でインストール手順を案内します。
+`--list-checks`、`--help`、`--version` は peer なしでも動作します。
+
+### `auto-play-detection` と optional deps
+
+`auto-play-detection` は `pixelmatch` と `pngjs` が必要です。
+未インストールの場合はそのチェックだけ `SKIPPED` となり、終了コードには影響しません。
+他の 9 検査は通常通り実行されます。
+
 ## 使い方 — 関数 API（推奨）
 
 ページの遷移は呼び出し側で行い、関数は検査の実行・結果 JSON の書き出し・結果オブジェクトの

package/README.md

@@ -52,6 +52,70 @@ npm install -D pixelmatch pngjs   # only if you use runAutoPlayDetection
 > ESM only. This package does not ship a CommonJS build; import it from ESM
 > (or a TypeScript project compiled to ESM).
 
+## CLI
+
+Run all ten checks against a URL with a single command — no test runner needed.
+
+```sh
+npx -y @a11y-skills/audit --url https://example.com
+```
+
+Peer dependencies (`@playwright/test`, `@axe-core/playwright`) are pulled in
+automatically by npm 7+. Install Chromium on first use:
+
+```sh
+npx playwright install chromium
+```
+
+### Flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--url <url>` | `TEST_PAGE` env | Target URL. `--url` takes priority over the env var. If neither is set, usage is printed and the process exits 2. |
+| `--checks <list>` | `all` | Comma-separated check names (see list below). |
+| `--output-dir <dir>` | `./a11y-audit-results` | Directory for result JSON files. |
+| `--screenshot` | off | Enable focus-indicator screenshot. |
+| `--list-checks` | — | Print check names and exit 0. |
+| `--version` | — | Print version and exit 0. |
+| `--help` | — | Print usage and exit 0. |
+
+### Available check names
+
+```
+axe-audit
+focus-indicator-check
+reflow-check
+text-spacing-check
+zoom-200-check
+orientation-check
+autocomplete-audit
+time-limit-detector
+auto-play-detection
+target-size-check
+```
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | All checks completed, no violations found. |
+| `1` | All checks completed, at least one violation found. |
+| `2` | Runtime error — bad arguments, missing peers, navigation failure, or check crash. |
+
+Completed-check JSON is always written even when the exit code is non-zero.
+
+### Peer requirements
+
+`@playwright/test >=1.50.0` and `@axe-core/playwright >=4.10.0` must be
+resolvable. If they are not found, the CLI exits 2 with an install hint.
+`--list-checks`, `--help`, and `--version` work without peers.
+
+### `auto-play-detection` and optional deps
+
+`auto-play-detection` needs `pixelmatch` and `pngjs`. If they are absent, that
+check is skipped with a `SKIPPED` message and does not affect the exit code.
+The other nine checks continue normally.
+
 ## Usage — function API (recommended)
 
 You navigate the page; the function runs the check, writes a result JSON, and

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * @a11y-skills/audit CLI
+ *
+ * Runs WCAG 2.2 accessibility checks against a URL without needing a
+ * Playwright test runner. All 10 checks are available via --checks.
+ *
+ * Exit codes:
+ *   0 — completed, no violations found across all checks
+ *   1 — completed, at least one violation found
+ *   2 — runtime error (bad args, missing peers, navigation failure, check crash)
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * @a11y-skills/audit CLI
+ *
+ * Runs WCAG 2.2 accessibility checks against a URL without needing a
+ * Playwright test runner. All 10 checks are available via --checks.
+ *
+ * Exit codes:
+ *   0 — completed, no violations found across all checks
+ *   1 — completed, at least one violation found
+ *   2 — runtime error (bad args, missing peers, navigation failure, check crash)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseArgs } from 'node:util';
+// ---------------------------------------------------------------------------
+// Check registry
+// ---------------------------------------------------------------------------
+// Checks are registered with lazy imports to avoid top-level peer resolution.
+const CHECK_REGISTRY = [
+    {
+        name: 'axe-audit',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runAxeAudit } = await import('./playwright/runAxeAudit.js');
+            return (await runAxeAudit({ page, outputDir }));
+        },
+    },
+    {
+        name: 'focus-indicator-check',
+        kind: 'browser',
+        async run({ browser, outputDir, screenshot, url }) {
+            const { runFocusIndicatorCheck } = await import('./playwright/runFocusIndicatorCheck.js');
+            return (await runFocusIndicatorCheck({
+                browser,
+                targetUrl: url,
+                outputDir,
+                screenshot,
+            }));
+        },
+    },
+    {
+        name: 'reflow-check',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runReflowCheck } = await import('./playwright/runReflowCheck.js');
+            return (await runReflowCheck({ page, outputDir }));
+        },
+    },
+    {
+        name: 'text-spacing-check',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runTextSpacingCheck } = await import('./playwright/runTextSpacingCheck.js');
+            return (await runTextSpacingCheck({
+                page,
+                outputDir,
+            }));
+        },
+    },
+    {
+        name: 'zoom-200-check',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runZoomCheck } = await import('./playwright/runZoomCheck.js');
+            return (await runZoomCheck({ page, outputDir }));
+        },
+    },
+    {
+        name: 'orientation-check',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runOrientationCheck } = await import('./playwright/runOrientationCheck.js');
+            return (await runOrientationCheck({
+                page,
+                outputDir,
+            }));
+        },
+    },
+    {
+        name: 'autocomplete-audit',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runAutocompleteAudit } = await import('./playwright/runAutocompleteAudit.js');
+            return (await runAutocompleteAudit({
+                page,
+                outputDir,
+            }));
+        },
+    },
+    {
+        name: 'time-limit-detector',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runTimeLimitDetector } = await import('./playwright/runTimeLimitDetector.js');
+            return (await runTimeLimitDetector({
+                page,
+                outputDir,
+            }));
+        },
+    },
+    {
+        name: 'auto-play-detection',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runAutoPlayDetection } = await import('./playwright/runAutoPlayDetection.js');
+            return (await runAutoPlayDetection({
+                page,
+                outputDir: path.join(outputDir, 'auto-play-screenshots'),
+            }));
+        },
+    },
+    {
+        name: 'target-size-check',
+        kind: 'page',
+        async run({ page, outputDir }) {
+            const { runTargetSizeCheck } = await import('./playwright/runTargetSizeCheck.js');
+            return (await runTargetSizeCheck({
+                page,
+                outputDir,
+            }));
+        },
+    },
+];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function printUsage() {
+    process.stdout.write(`
+Usage: a11y-audit --url <url> [options]
+
+Options:
+  --url <url>            Target URL to audit. Overrides TEST_PAGE env var.
+  --checks <list>        Comma-separated check names (default: all).
+                         Use --list-checks to see available names.
+  --output-dir <dir>     Directory for result JSON files (default: ./a11y-audit-results).
+  --screenshot           Enable focus-indicator screenshot (default: off).
+  --list-checks          Print available check names and exit.
+  --version              Print version and exit.
+  --help                 Print this message and exit.
+
+Exit codes:
+  0  No violations found.
+  1  One or more violations found.
+  2  Runtime error (bad arguments, missing peers, navigation failure).
+
+Peer requirements:
+  @playwright/test >=1.50.0
+  @axe-core/playwright >=4.10.0
+
+  Install if missing: npm i -D @playwright/test @axe-core/playwright
+  Install browsers:   npx playwright install chromium
+
+auto-play-detection requires optional deps (pixelmatch, pngjs). If they are
+missing, that check is skipped with a SKIPPED notice.
+`);
+}
+/** Verify required peers are resolvable. Returns an error string or null. */
+async function checkPeers() {
+    const missing = [];
+    for (const pkg of ['@playwright/test', '@axe-core/playwright']) {
+        try {
+            await import(pkg);
+        }
+        catch {
+            missing.push(pkg);
+        }
+    }
+    if (missing.length > 0) {
+        return (`Missing required peer dependencies: ${missing.join(', ')}\n` +
+            `Install them with: npm i -D @playwright/test @axe-core/playwright`);
+    }
+    return null;
+}
+function formatDuration(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+async function main() {
+    // Read package version from package.json
+    let pkgVersion = 'unknown';
+    try {
+        const pkgPath = new URL('../package.json', import.meta.url);
+        const pkgJson = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        pkgVersion = pkgJson.version;
+    }
+    catch {
+        // ignore
+    }
+    let values;
+    try {
+        const result = parseArgs({
+            args: process.argv.slice(2),
+            options: {
+                url: { type: 'string' },
+                checks: { type: 'string' },
+                'output-dir': { type: 'string' },
+                screenshot: { type: 'boolean', default: false },
+                'list-checks': { type: 'boolean', default: false },
+                version: { type: 'boolean', default: false },
+                help: { type: 'boolean', default: false },
+            },
+            strict: true,
+        });
+        values = result.values;
+    }
+    catch (err) {
+        process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+        printUsage();
+        process.exit(2);
+    }
+    if (values.help) {
+        printUsage();
+        process.exit(0);
+    }
+    if (values.version) {
+        process.stdout.write(`${pkgVersion}\n`);
+        process.exit(0);
+    }
+    if (values['list-checks']) {
+        process.stdout.write(CHECK_REGISTRY.map((c) => c.name).join('\n') + '\n');
+        process.exit(0);
+    }
+    // --- Resolve URL ---
+    const url = values.url ?? process.env.TEST_PAGE;
+    if (!url) {
+        process.stderr.write('Error: --url is required (or set the TEST_PAGE environment variable).\n');
+        printUsage();
+        process.exit(2);
+    }
+    // --- Resolve checks ---
+    const checksArg = values.checks;
+    let selectedChecks;
+    if (!checksArg || checksArg === 'all') {
+        selectedChecks = CHECK_REGISTRY;
+    }
+    else {
+        const names = checksArg.split(',').map((n) => n.trim());
+        const unknown = names.filter((n) => !CHECK_REGISTRY.some((c) => c.name === n));
+        if (unknown.length > 0) {
+            process.stderr.write(`Error: unknown check(s): ${unknown.join(', ')}\n` +
+                `Run --list-checks to see available names.\n`);
+            process.exit(2);
+        }
+        selectedChecks = names
+            .map((n) => CHECK_REGISTRY.find((c) => c.name === n))
+            .filter((c) => c !== undefined);
+    }
+    const outputDir = path.resolve(values['output-dir'] ?? './a11y-audit-results');
+    const screenshot = values.screenshot === true;
+    // --- Peer check (only before running checks) ---
+    const peerError = await checkPeers();
+    if (peerError) {
+        process.stderr.write(`Error: ${peerError}\n`);
+        process.exit(2);
+    }
+    // --- Launch browser ---
+    let browser;
+    try {
+        const { chromium } = await import('@playwright/test');
+        browser = await chromium.launch();
+    }
+    catch (err) {
+        process.stderr.write(`Error launching browser: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+    }
+    // Ensure output directory exists
+    fs.mkdirSync(outputDir, { recursive: true });
+    process.stdout.write(`a11y-audit v${pkgVersion}\n`);
+    process.stdout.write(`URL:        ${url}\n`);
+    process.stdout.write(`Checks:     ${selectedChecks.map((c) => c.name).join(', ')}\n`);
+    process.stdout.write(`Output dir: ${outputDir}\n`);
+    process.stdout.write(`\n`);
+    const summaries = [];
+    let hasViolations = false;
+    let hasErrors = false;
+    for (const check of selectedChecks) {
+        const start = Date.now();
+        // page-based checks get a fresh context + navigated page
+        let context = null;
+        let page = null;
+        try {
+            if (check.kind === 'page') {
+                context = await browser.newContext();
+                page = await context.newPage();
+                // Use 'load' for file: URLs to avoid networkidle hanging
+                const waitUntil = url.startsWith('file:') ? 'load' : 'networkidle';
+                try {
+                    await page.goto(url, { waitUntil });
+                }
+                catch (navErr) {
+                    const msg = navErr instanceof Error ? navErr.message : String(navErr);
+                    process.stderr.write(`[${check.name}] Navigation failed: ${msg}\n`);
+                    summaries.push({
+                        name: check.name,
+                        status: 'ERROR',
+                        durationMs: Date.now() - start,
+                        error: msg,
+                    });
+                    hasErrors = true;
+                    continue;
+                }
+            }
+            const result = await check.run({
+                // page is null only for browser-kind checks, which do not use it
+                page: page,
+                browser,
+                outputDir,
+                screenshot,
+                url,
+            });
+            const durationMs = Date.now() - start;
+            const summary = result.summary;
+            const violationCount = summary?.violationCount ?? 0;
+            const incompleteCount = summary?.incompleteCount ?? 0;
+            const passCount = summary?.passCount ?? 0;
+            if (violationCount > 0) {
+                hasViolations = true;
+            }
+            process.stdout.write(`[${check.name}] DONE in ${formatDuration(durationMs)} — ` +
+                `violations: ${violationCount}, passes: ${passCount}, incomplete: ${incompleteCount}\n`);
+            summaries.push({
+                name: check.name,
+                status: 'DONE',
+                durationMs,
+                violationCount,
+                incompleteCount,
+                passCount,
+            });
+        }
+        catch (err) {
+            const durationMs = Date.now() - start;
+            const msg = err instanceof Error ? err.message : String(err);
+            // auto-play-detection: optional dep missing → SKIPPED, not ERROR
+            const isOptionalDepMissing = check.name === 'auto-play-detection' &&
+                (msg.includes('pixelmatch') ||
+                    msg.includes('pngjs') ||
+                    msg.includes('Cannot find module') ||
+                    msg.includes('ERR_MODULE_NOT_FOUND'));
+            if (isOptionalDepMissing) {
+                process.stdout.write(`[${check.name}] SKIPPED — optional deps missing (pixelmatch, pngjs). ` +
+                    `Install with: npm i pixelmatch pngjs\n`);
+                summaries.push({
+                    name: check.name,
+                    status: 'SKIPPED',
+                    durationMs,
+                    skipReason: 'optional deps missing (pixelmatch, pngjs)',
+                });
+            }
+            else {
+                process.stderr.write(`[${check.name}] ERROR: ${msg}\n`);
+                summaries.push({
+                    name: check.name,
+                    status: 'ERROR',
+                    durationMs,
+                    error: msg,
+                });
+                hasErrors = true;
+            }
+        }
+        finally {
+            if (context !== null) {
+                try {
+                    await context.close();
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+        }
+    }
+    // --- Close browser ---
+    try {
+        await browser.close();
+    }
+    catch {
+        // ignore
+    }
+    // --- Summary ---
+    const totalMs = summaries.reduce((acc, s) => acc + s.durationMs, 0);
+    const doneCount = summaries.filter((s) => s.status === 'DONE').length;
+    const skippedCount = summaries.filter((s) => s.status === 'SKIPPED').length;
+    const errorCount = summaries.filter((s) => s.status === 'ERROR').length;
+    const totalViolations = summaries.reduce((acc, s) => acc + (s.violationCount ?? 0), 0);
+    process.stdout.write(`\n`);
+    process.stdout.write(`--- Summary (${formatDuration(totalMs)}) ---\n` +
+        `  Checks run:   ${doneCount}\n` +
+        `  Skipped:      ${skippedCount}\n` +
+        `  Errors:       ${errorCount}\n` +
+        `  Total violations: ${totalViolations}\n` +
+        `  Results written to: ${outputDir}\n`);
+    if (hasErrors) {
+        process.exit(2);
+    }
+    else if (hasViolations) {
+        process.exit(1);
+    }
+    else {
+        process.exit(0);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+});

package/dist/constants.d.ts

@@ -24,6 +24,8 @@ export declare const FOCUS_STYLE_PROPERTIES: readonly ["outline", "outlineStyle"
 export declare const FOCUSABLE_SELECTOR: string;
 /** Extra tab iterations for safety margin */
 export declare const EXTRA_TAB_ITERATIONS = 10;
+/** Default ms to wait after each Tab press for a focus-triggered navigation to surface. */
+export declare const DEFAULT_NAVIGATION_SETTLE_MS = 50;
 /**
  * Minimum overlap ratio to report as obscured (0-1)
  * 0.2 means 20% of the focused element must be covered