@surea11y/core 1.2.0 → 1.4.0

package/bin/core.js

@@ -1,348 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * surea11y CLI — a thin wrapper around the library for ad hoc/CI use.
- *
- * This is the one part of the package that depends on jsdom (see
- * package.json's "dependencies" vs the library itself, which has none --
- * `require('surea11y')` never loads jsdom; only running this CLI does).
- * Static-HTML only: it does not execute page JavaScript, so client-rendered
- * content won't be scanned. For that, use a real browser via Puppeteer/
- * Playwright — see docs/INTEGRATION.md Pattern 2.
- *
- * Usage:
- *   surea11y scan <file-or-url> [options]
- *
- * See docs/CLI.md for the full option reference.
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const pkg = require('../package.json');
-const { buildBaselineEntries, matchBaseline } = require('../src/baseline.js');
-const { renderHtmlReport } = require('../src/report.js');
-
-// Piping output to `head`/`less`/etc. closes stdout early — without this,
-// the next write throws an unhandled EPIPE and crashes with a raw stack
-// trace instead of just stopping quietly, like well-behaved CLI tools do.
-process.stdout.on('error', (err) => {
-  if (err && err.code === 'EPIPE') process.exit(0);
-  throw err;
-});
-
-function printHelp() {
-  process.stdout.write(`surea11y v${pkg.version}
-
-Usage:
-  surea11y scan <file-or-url> [options]
-
-Options:
-  --json                  Print the raw result object as JSON instead of a summary
-  --locale <locale>       Locale for output text (default: en)
-  --rules <ids>           Comma-separated rule IDs to run (only these)
-  --exclude-rules <ids>   Comma-separated rule IDs to exclude
-  --tags <tags>           Comma-separated tags to run (e.g. wcag2a,wcag2aa)
-  --context <selector>    CSS selector to scope the scan to a subtree
-  --write-baseline <path> Write every current "fail" occurrence to <path>; never fails the build
-  --baseline <path>       Gate only on occurrences not already recorded in <path>
-  --html <path>           Write a self-contained, browsable HTML report to <path>
-  -h, --help              Show this help
-  -v, --version           Show the installed version
-
-Exit codes:
-  0  scan completed, no "fail" outcomes (or no *new* ones, with --baseline)
-  1  scan completed, at least one "fail" outcome (or *new* one, with --baseline)
-  2  usage error or the scan itself could not run (bad path/URL, network failure, etc.)
-
-Examples:
-  surea11y scan ./index.html
-  surea11y scan https://example.com/ --tags wcag2a,wcag2aa
-  surea11y scan ./index.html --json > result.json
-  surea11y scan ./index.html --write-baseline baseline.json
-  surea11y scan ./index.html --baseline baseline.json
-  surea11y scan ./index.html --html report.html
-
-See docs/BASELINE.md for the baseline/allowlist mechanism, docs/REPORT.md for the HTML report.
-`);
-}
-
-function parseArgs(argv) {
-  const out = { _: [], json: false };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    switch (a) {
-      case '--json':
-        out.json = true;
-        break;
-      case '--locale':
-        out.locale = argv[++i];
-        break;
-      case '--rules':
-        out.rules = argv[++i];
-        break;
-      case '--exclude-rules':
-        out.excludeRules = argv[++i];
-        break;
-      case '--tags':
-        out.tags = argv[++i];
-        break;
-      case '--context':
-        out.context = argv[++i];
-        break;
-      case '--baseline':
-        out.baseline = argv[++i];
-        break;
-      case '--write-baseline':
-        out.writeBaseline = argv[++i];
-        break;
-      case '--html':
-        out.html = argv[++i];
-        break;
-      case '-h':
-      case '--help':
-        out.help = true;
-        break;
-      case '-v':
-      case '--version':
-        out.version = true;
-        break;
-      default:
-        out._.push(a);
-    }
-  }
-  return out;
-}
-
-function isUrl(s) {
-  return /^https?:\/\//i.test(s);
-}
-
-function formatError(err) {
-  const base = err && err.message ? err.message : String(err);
-  const cause = err && err.cause && err.cause.message ? err.cause.message : (err && err.cause ? String(err.cause) : '');
-  return cause ? `${base}: ${cause}` : base;
-}
-
-async function loadHtml(target) {
-  if (isUrl(target)) {
-    const res = await fetch(target);
-    if (!res.ok) {
-      throw new Error(`Fetching ${target} failed: HTTP ${res.status} ${res.statusText}`);
-    }
-    return { html: await res.text(), url: target };
-  }
-
-  const resolved = path.resolve(process.cwd(), target);
-  if (!fs.existsSync(resolved)) {
-    throw new Error(`No such file: ${resolved}`);
-  }
-  return { html: fs.readFileSync(resolved, 'utf8'), url: `file://${resolved}` };
-}
-
-function buildEngineOptions(args) {
-  const engineOptions = {};
-  if (args.locale) engineOptions.locale = args.locale;
-  if (args.rules || args.excludeRules) {
-    engineOptions.rules = {};
-    if (args.rules) engineOptions.rules.include = args.rules;
-    if (args.excludeRules) engineOptions.rules.exclude = args.excludeRules;
-  }
-  if (args.tags) engineOptions.tags = { include: args.tags };
-  return engineOptions;
-}
-
-function printSummary(result, baselineMatch) {
-  const byOutcome = { pass: 0, fail: 0, cantTell: 0, notApplicable: 0 };
-  for (const r of result.checksResults) {
-    if (Object.prototype.hasOwnProperty.call(byOutcome, r.outcome)) byOutcome[r.outcome] += 1;
-  }
-
-  process.stdout.write(`\nsurea11y scan: ${result.url || '(no url)'}\n`);
-  process.stdout.write(`  pass: ${byOutcome.pass}   fail: ${byOutcome.fail}   cantTell: ${byOutcome.cantTell}   notApplicable: ${byOutcome.notApplicable}\n\n`);
-
-  const fails = result.checksResults.filter((r) => r.outcome === 'fail');
-  if (fails.length) {
-    process.stdout.write(`FAIL (${fails.length} rule(s)):\n`);
-    for (const r of fails) {
-      process.stdout.write(`\n  ${r.ruleId}  (${r.severity}, ${r.occurrences.length} occurrence(s))\n`);
-      for (const occ of r.occurrences.slice(0, 5)) {
-        process.stdout.write(`    - ${occ.selector || '(no selector)'}\n      ${occ.summary}\n`);
-        if (occ.hint) process.stdout.write(`      hint: ${occ.hint}\n`);
-      }
-      if (r.occurrences.length > 5) {
-        process.stdout.write(`    ... and ${r.occurrences.length - 5} more\n`);
-      }
-    }
-    process.stdout.write('\n');
-  }
-
-  const cantTells = result.checksResults.filter((r) => r.outcome === 'cantTell');
-  if (cantTells.length) {
-    process.stdout.write(`cantTell — needs human review (${cantTells.length} rule(s)): ${cantTells.map((r) => r.ruleId).join(', ')}\n\n`);
-  }
-
-  if (baselineMatch) {
-    process.stdout.write(`baseline: ${baselineMatch.knownCount} known, ${baselineMatch.newCount} new, ${baselineMatch.staleCount} stale (no longer detected)\n`);
-    if (baselineMatch.newCount) {
-      process.stdout.write(`\nNEW (not in baseline, ${baselineMatch.newCount} occurrence(s)):\n`);
-      for (const occ of baselineMatch.newOccurrences.slice(0, 5)) {
-        process.stdout.write(`  - ${occ.ruleId}: ${occ.selector || '(no selector)'}\n    ${occ.summary}\n`);
-      }
-      if (baselineMatch.newOccurrences.length > 5) {
-        process.stdout.write(`  ... and ${baselineMatch.newOccurrences.length - 5} more\n`);
-      }
-    }
-    process.stdout.write('\n');
-  }
-}
-
-function loadBaselineFile(baselinePath) {
-  let raw;
-  try {
-    raw = fs.readFileSync(baselinePath, 'utf8');
-  } catch (err) {
-    throw new Error(`Could not read baseline file "${baselinePath}": ${formatError(err)}. Run with --write-baseline ${baselinePath} first to create one.`);
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`Baseline file "${baselinePath}" is not valid JSON: ${formatError(err)}`);
-  }
-
-  if (!parsed || parsed.version !== 1 || !Array.isArray(parsed.entries)) {
-    throw new Error(`Baseline file "${baselinePath}" is not a supported baseline (expected { version: 1, entries: [...] }). Regenerate it with --write-baseline.`);
-  }
-
-  return parsed;
-}
-
-async function runScan(args) {
-  const target = args._[0];
-  if (!target) {
-    process.stderr.write('Error: scan requires a file path or URL. See --help.\n');
-    process.exitCode = 2;
-    return;
-  }
-
-  if (args.baseline && args.writeBaseline) {
-    process.stderr.write('Error: --baseline and --write-baseline cannot be used together in the same run. See --help.\n');
-    process.exitCode = 2;
-    return;
-  }
-
-  let baselineFile = null;
-  if (args.baseline) {
-    try {
-      baselineFile = loadBaselineFile(args.baseline);
-    } catch (err) {
-      process.stderr.write(`Error: ${formatError(err)}\n`);
-      process.exitCode = 2;
-      return;
-    }
-  }
-
-  let html, url;
-  try {
-    ({ html, url } = await loadHtml(target));
-  } catch (err) {
-    process.stderr.write(`Error: ${formatError(err)}\n`);
-    process.exitCode = 2;
-    return;
-  }
-
-  let JSDOM;
-  try {
-    ({ JSDOM } = require('jsdom'));
-  } catch {
-    process.stderr.write('Error: the surea11y CLI requires jsdom. Run `npm install jsdom` (it should already be a dependency of this package — this likely means a broken install).\n');
-    process.exitCode = 2;
-    return;
-  }
-
-  const { runDomRulesInPage } = require('../src/index.js');
-
-  const dom = new JSDOM(html, { url, pretendToBeVisual: true });
-  global.window = dom.window;
-  global.document = dom.window.document;
-
-  let result;
-  try {
-    result = runDomRulesInPage(url, args.context || null, buildEngineOptions(args), null);
-  } finally {
-    dom.window.close();
-  }
-
-  if (args.html) {
-    fs.writeFileSync(args.html, renderHtmlReport(result, { title: `surea11y scan report — ${target}` }));
-    process.stderr.write(`Wrote HTML report to: ${args.html}\n`);
-  }
-
-  if (args.writeBaseline) {
-    const entries = buildBaselineEntries(result);
-    const payload = { version: 1, generatedAt: new Date().toISOString(), entries };
-    fs.writeFileSync(args.writeBaseline, JSON.stringify(payload, null, 2) + '\n');
-
-    if (args.json) {
-      process.stdout.write(JSON.stringify({ ...result, baseline: { mode: 'write', path: args.writeBaseline, entries: entries.length } }, null, 2) + '\n');
-    } else {
-      printSummary(result);
-    }
-    process.stderr.write(`Wrote ${entries.length} occurrence(s) to baseline: ${args.writeBaseline}\n`);
-    process.exitCode = 0;
-    return;
-  }
-
-  if (baselineFile) {
-    const match = matchBaseline(result, baselineFile.entries);
-
-    if (args.json) {
-      process.stdout.write(JSON.stringify({ ...result, baseline: { mode: 'check', ...match } }, null, 2) + '\n');
-    } else {
-      printSummary(result, match);
-    }
-    process.exitCode = match.newCount > 0 ? 1 : 0;
-    return;
-  }
-
-  if (args.json) {
-    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-  } else {
-    printSummary(result);
-  }
-
-  const hasFail = result.checksResults.some((r) => r.outcome === 'fail');
-  process.exitCode = hasFail ? 1 : 0;
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-
-  if (args.version) {
-    process.stdout.write(`${pkg.version}\n`);
-    return;
-  }
-  if (args.help || args._.length === 0) {
-    printHelp();
-    process.exitCode = args._.length === 0 && !args.help ? 2 : 0;
-    return;
-  }
-
-  const [command, ...rest] = args._;
-  if (command !== 'scan') {
-    process.stderr.write(`Error: unknown command "${command}". Only "scan" is supported. See --help.\n`);
-    process.exitCode = 2;
-    return;
-  }
-
-  args._ = rest;
-  await runScan(args);
-}
-
-main().catch((err) => {
-  process.stderr.write(`Error: ${formatError(err)}\n`);
-  process.exitCode = 2;
-});

package/docs/CLI.md

@@ -1,75 +0,0 @@
-# CLI
-
-`surea11y` ships a small CLI (`bin/core.js`) for ad hoc scans and CI, on top of the library API described in [`INTEGRATION.md`](./INTEGRATION.md).
-
-```sh
-npx @surea11y/core scan ./index.html
-npx @surea11y/core scan https://example.com/
-```
-
-## What it can and can't scan
-
-The CLI reads **static HTML only** — a local file, or the raw response of an HTTP(S) GET request — and never executes page JavaScript. That means client-rendered content (anything your framework injects after page load) won't be captured, and geometry-dependent rules like `target-size-minimum` will report `notApplicable` (no real CSS layout — see [`LIMITATIONS.md`](./LIMITATIONS.md)). If you need either of those, drive a real browser yourself and use `runa11yCoreInPage` directly — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 2. The CLI is the fast path for static/server-rendered pages and CI; the library is what you reach for beyond that.
-
-## Options
-
-| Flag | Meaning |
-|---|---|
-| `--json` | Print the raw result object (see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md)) instead of a human-readable summary. |
-| `--locale <locale>` | Output text locale (default `en`) — see [`I18N.md`](./I18N.md). |
-| `--rules <ids>` | Comma-separated rule IDs — only run these. |
-| `--exclude-rules <ids>` | Comma-separated rule IDs — never run these. |
-| `--tags <tags>` | Comma-separated tags — e.g. `--tags wcag2a,wcag2aa` to target a conformance level (see [`WCAG_CONFORMANCE.md`](./WCAG_CONFORMANCE.md)). |
-| `--context <selector>` | Scope the scan to one CSS-selected subtree. |
-| `--write-baseline <path>` | Write every current `fail` occurrence to `<path>`; never fails the build. See [`BASELINE.md`](./BASELINE.md). |
-| `--baseline <path>` | Gate only on occurrences not already recorded in `<path>`. See [`BASELINE.md`](./BASELINE.md). |
-| `--html <path>` | Write a self-contained, browsable HTML report to `<path>`. See [`REPORT.md`](./REPORT.md). |
-| `-h`, `--help` | Show usage. |
-| `-v`, `--version` | Show the installed version. |
-
-These map directly onto `engineOptions`/`runOnly` (see [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md)) — `--rules`/`--exclude-rules` become `engineOptions.rules.include`/`.exclude`, `--tags` becomes `engineOptions.tags.include`.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | Scan completed, no `fail` outcomes. |
-| `1` | Scan completed, at least one `fail` outcome — the CI-gating case. |
-| `2` | Usage error, or the scan itself couldn't run (bad path/URL, network failure, missing `jsdom`). |
-
-`cantTell` outcomes never affect the exit code — they're printed as a "needs human review" summary, consistent with the manual/`cantTell` mental model in [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md#should-i-treat-canttell-as-a-failure). If you need `cantTell`-aware gating, use `--json` and inspect `checksResults` yourself, or call the library directly (see [`INTEGRATION.md`](./INTEGRATION.md#ci-gating-a-build-on-the-result)).
-
-With `--baseline`, exit code `1` means at least one *new* (not-yet-baselined) `fail` occurrence, not any `fail` occurrence — see [`BASELINE.md`](./BASELINE.md).
-
-## Baseline / allowlist
-
-For an existing, imperfect site, gating on every `fail` on day one is often an adoption blocker. `--write-baseline`/`--baseline` let you accept the current state once and gate CI only on genuinely new violations from then on:
-
-```sh
-surea11y scan ./dist/index.html --write-baseline baseline.json   # once, commit the file
-surea11y scan ./dist/index.html --baseline baseline.json         # in CI, from then on
-```
-
-See [`BASELINE.md`](./BASELINE.md) for the matching semantics, file format, and known limitations.
-
-## HTML report
-
-For a browsable view of a scan's results — hero summary, WCAG rollup grouped by conformance level, and a searchable/filterable occurrence table — rather than raw JSON or a terminal summary:
-
-```sh
-surea11y scan ./dist/index.html --html report.html
-```
-
-Open `report.html` directly from disk; no server, no external assets. Works alongside any other output mode. See [`REPORT.md`](./REPORT.md).
-
-## In CI
-
-```sh
-npx @surea11y/core scan ./dist/index.html || exit 1
-```
-
-Or, since the exit code already reflects pass/fail, just let the command's own exit code propagate — most CI systems fail the step automatically on a non-zero exit.
-
-## A note on dependencies
-
-The CLI is the one part of this package that depends on `jsdom` — `require('@surea11y/core')` as a library never loads it (see [`SECURITY.md`](../SECURITY.md)). If you only ever use the library API directly against your own DOM (jsdom, a real browser, whatever you already have), you're not paying for `jsdom` a second time.