@surea11y/core 1.3.0 → 1.4.0

package/bin/core.js

@@ -1,473 +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');
-const { renderSarifReport } = require('../src/sarif.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
-  --custom-rules <path>   Load runtime custom rules from a JS file (repeatable)
-  --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>
-  --sarif <path>          Write a SARIF 2.1.0 report to <path> (for GitHub Code Scanning etc.)
-  -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
-  surea11y scan ./index.html --baseline baseline.json --sarif results.sarif
-  surea11y scan ./index.html --custom-rules ./a11y-rules.js
-
-See docs/BASELINE.md for the baseline/allowlist mechanism, docs/REPORT.md for the HTML report,
-docs/SARIF.md for the SARIF report, docs/CLI.md#custom-rules for custom rules.
-`);
-}
-
-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 '--custom-rules':
-        (out.customRules = out.customRules || []).push(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 '--sarif':
-        out.sarif = 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, customRules) {
-  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 };
-  if (customRules && customRules.length) engineOptions.customRules = customRules;
-  return engineOptions;
-}
-
-// Loads one --custom-rules file. The CLI runs custom rules in the same
-// process/JS realm as the scan itself (unlike a binding whose engineOptions
-// crosses page.evaluate()'s serialization boundary), so a descriptor's
-// runInPage/applicability may be a real function -- see the customRules
-// section of docs/ENGINE_OPTIONS.md for the full descriptor contract this
-// mirrors. Validated up front (not left to the engine's own silent-skip of
-// invalid entries) so a typo in a hand-authored file fails loudly as a usage
-// error instead of quietly producing a scan with one fewer rule than expected.
-function loadCustomRulesFile(customRulesPath) {
-  const resolved = path.resolve(process.cwd(), customRulesPath);
-
-  let loaded;
-  try {
-    loaded = require(resolved);
-  } catch (err) {
-    throw new Error(`Could not load custom rules file "${customRulesPath}": ${formatError(err)}`, {
-      cause: err
-    });
-  }
-
-  const descriptors = Array.isArray(loaded) ? loaded : [loaded];
-
-  for (const d of descriptors) {
-    const hasId = d && typeof d === 'object' && typeof d.id === 'string' && d.id.trim();
-    const hasRunInPage =
-      d &&
-      (typeof d.runInPage === 'function' ||
-        (typeof d.runInPage === 'string' && d.runInPage.trim()));
-    if (!hasId || !hasRunInPage) {
-      throw new Error(
-        `Custom rules file "${customRulesPath}" must export a rule descriptor ({ id, runInPage, ... }) or an array of them. See docs/CLI.md#custom-rules.`
-      );
-    }
-  }
-
-  return descriptors;
-}
-
-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.`,
-      { cause: err }
-    );
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`Baseline file "${baselinePath}" is not valid JSON: ${formatError(err)}`, {
-      cause: 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 customRules = [];
-  if (args.customRules && args.customRules.length) {
-    try {
-      for (const customRulesPath of args.customRules) {
-        customRules = customRules.concat(loadCustomRulesFile(customRulesPath));
-      }
-    } 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, customRules),
-      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.sarif) {
-    fs.writeFileSync(
-      args.sarif,
-      renderSarifReport(result, {
-        toolVersion: pkg.version,
-        informationUri: (pkg.homepage || '').replace(/#.*$/, ''),
-        baselineEntries: baselineFile ? baselineFile.entries : undefined
-      })
-    );
-    process.stderr.write(`Wrote SARIF report to: ${args.sarif}\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,128 +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. |
-| `--custom-rules <path>` | Load runtime custom rules from a local JS file. Repeatable. See [Custom rules](#custom-rules) below. |
-| `--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). |
-| `--sarif <path>` | Write a SARIF 2.1.0 report to `<path>` (e.g. for GitHub Code Scanning). See [`SARIF.md`](./SARIF.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.
-
-## Custom rules
-
-For an org-specific check that isn't (and shouldn't be) one of the built-in rules — an internal design-system convention, a company style-guide requirement — `--custom-rules <path>` registers your own rule(s) for that one scan, on top of every built-in rule:
-
-```sh
-surea11y scan ./dist/index.html --custom-rules ./a11y-rules.js
-```
-
-`a11y-rules.js` exports either a single rule descriptor or an array of them, using the same shape as a built-in rule module:
-
-```js
-// a11y-rules.js
-module.exports = [
-  {
-    id: 'org-no-inline-onclick',
-    meta: { title: 'No inline onclick handlers', defaultSeverity: 'moderate' },
-    runInPage(ctx) {
-      const els = ctx.helpers.queryAll('[onclick]');
-      const occurrences = els.map((el) => ({
-        selector: ctx.helpers.buildSelector(el),
-        html: el.outerHTML,
-        summary: 'Inline onclick handler found.',
-        hint: 'Move event handling into an external script.'
-      }));
-      return {
-        ruleId: ctx.rule.ruleId,
-        outcome: occurrences.length ? 'fail' : 'pass',
-        occurrences
-      };
-    }
-  }
-];
-```
-
-- `<path>` is a **local file**, `require()`d directly by the CLI — never a URL. (Unlike the scan target, which does accept a URL: fetching and executing remote code as a rule would be a very different, much riskier trust model than running a file you already have on disk.)
-- Because the CLI runs your rule in the same Node process as the scan, `runInPage`/`applicability` can be plain functions — no `fn.toString()` string-source workaround needed (that's only required for callers, like a browser-automation binding, whose `engineOptions` crosses a serialization boundary). See [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md) for the full descriptor contract (`meta` defaulting, the `ctx` shape, etc.) — it's identical here.
-- Repeat the flag to load rules from more than one file: `--custom-rules ./a.js --custom-rules ./b.js`.
-- A custom rule's `id` colliding with a built-in one **overrides** that built-in for the scan, surfaced via a `console.warn` and the result's top-level `overriddenBuiltinIds` array — see [`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md).
-- The file itself is validated at load time (must export a descriptor, or array of descriptors, each with a string `id` and a function-or-source-string `runInPage`) — a malformed export exits `2` with a clear error rather than silently scanning with one fewer rule than expected.
-- Works alongside every other flag, including `--rules`/`--exclude-rules`/`--tags` (which can target your custom rule's `id` exactly like a built-in one) and `--baseline`/`--html`/`--sarif`.
-
-## 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).
-
-## SARIF report
-
-For GitHub Code Scanning or another SARIF-consuming dashboard:
-
-```sh
-surea11y scan ./dist/index.html --sarif results.sarif
-```
-
-Works alongside any other output mode, and alongside `--baseline` (already-known `fail` occurrences are omitted from the SARIF output rather than re-reported). See [`SARIF.md`](./SARIF.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. See [`CI_INTEGRATIONS.md`](./CI_INTEGRATIONS.md) for ready-to-paste GitHub Actions and Bitbucket Pipelines templates, including a SARIF-upload example.
-
-## 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.