inclusa

Point it at a site; it crawls the same-origin pages in a real browser, runs accessibility checks on every rendered page, and saves a structured accessibility report into your repo - one that diffs cleanly over time.

Install & run

A command-line tool, like the Angular CLI. Two ways to use it:

# 1. Global (recommended) - install once, then run `inclusa` in any project folder
npm install -g @xtrable-ltd/inclusa
inclusa

# 2. Per-project (no global install) - add it as a dev dependency and run it via a script
npm install -D @xtrable-ltd/inclusa
#   then add to that project's package.json:  "scripts": { "inclusa": "inclusa" }
npm run inclusa

Either way, inclusa boots the studio in your browser, scoped to the folder you ran it in (its reports save under that project's .inclusa/). It assumes Node >= 20 and is pure JS - no native binaries, no compiler, no admin rights. It drives a Chromium browser you already have (Chrome / Edge / Brave) over the DevTools Protocol; the checks run in the real, rendered page.

If your browser is installed somewhere unusual and auto-detection misses it, set the INCLUSA_BROWSER environment variable to the executable path.

What makes it different

• A real package, a real browser - install once and run inclusa anywhere; it uses a Chromium browser you already have, so there's no bundled headless download.
• Reports are files in your repo - a scan writes a report you can open, diff, and track in git.
• Real pages - checks run against the rendered DOM in an actual browser, headless or visible, so SPA / client-routed pages are checked the way a user sees them.
• A PDF for stakeholders - export a polished assessment (verdict, charts, findings, honest caveat) to hand to a tech leader or client. Rendered by the browser you already have - no PDF library, nothing leaves your machine.

Use in CI

inclusa scan runs headless (no studio) and, with --ci, sets the exit code so a pipeline can fail on an accessibility regression (install it in the CI job - globally or as a dev dependency - then call inclusa):

inclusa scan https://staging.example.com --ci --crawl \
  --sarif a11y.sarif --junit a11y.xml

• Exit code: 0 pass, 2 gate failed, 1 execution error. stdout is the written report's path; the human verdict and progress go to stderr.
• Gate (defaults can live in inclusa.config.json's ci block; flags win):
  • default - fail on any automated failure at the target (--target wcag21aa by default),
  • --fail-on <critical|serious|moderate|minor> - fail on that impact or worse,
  • --max-violations <n> - fail above a count,
  • --baseline <report.json> --new-only - fail only on new findings vs a committed baseline.
• --sarif <path> emits SARIF 2.1.0 (GitHub code-scanning); --junit <path> emits JUnit XML for CI dashboards. Triaged and disabled rules from your config are respected throughout.
• --pdf <path> writes the stakeholder assessment PDF (add --pdf-appendix for screenshot evidence, --title "…" to set the document title) - handy for archiving a dated assessment from a pipeline. In the studio, use Export PDF on any report.

See inclusa.config.example.json for the config defaults.

Learn more

More at xtrable.com.

Develop inclusa itself

Setup (each machine, once)

git clone <repo-url> inclusa && cd inclusa
npm install          # install dev dependencies
npm run build        # build dist/ (needed before the global link below)

Requires Node >= 20 and a Chromium browser (Chrome / Edge / Brave).

Everyday commands

npm run dev          # Vite UI dev server (HMR) + the Node API server, one terminal
npm test             # the fast test suite (Vitest): pure core + I/O-edge integration
npm run test:e2e     # opt-in real-browser smoke (launches Chromium; skips if none found)
npm run typecheck    # tsc + svelte-check
npm run lint         # ESLint
npm run build        # build the shipped artifact into dist/ (backend + dist/ui)

npm run dev roots the studio at the repo by default. To point the dev studio at another folder (a test workspace), forward --root after --:

npm run dev -- --root /path/to/some-project

Open the URL printed in the cyan [ui ] lines (Vite's port), not the API server's.

Run inclusa dev from any folder (like meddle dev)

Link the source checkout onto your PATH once per machine, then inclusa dev works from anywhere - it boots the hot-reload dev studio (Vite + the watched API) rooted at the folder you run it in:

# in the inclusa repo (after `npm run build`):
npm link

# then, in any project folder:
cd /path/to/some-project
inclusa dev

Because the link points at your source checkout, inclusa dev always runs the current src/ (tsx watches it) - no rebuild needed unless you change how dist/cli.js itself dispatches commands. The same npm link also makes the production studio (inclusa) and headless inclusa scan resolve to your checkout.

Note: inclusa dev only works from a source checkout (it shells out to the repo's Vite/tsx toolchain). A plain published install (npm i -g @xtrable-ltd/inclusa) deliberately refuses inclusa dev - use npm link from the cloned repo as above.

If inclusa isn't found after npm link: npm's global bin directory isn't on your PATH. Print it with npm prefix -g (the binary lives there, or in its bin/ subfolder) and add that to PATH - e.g. %AppData%\npm on Windows, $(npm prefix -g)/bin on macOS/Linux.

Gotcha when stopping it: Ctrl+C in the foreground tears the whole tree down cleanly. But if you background inclusa dev (or your terminal kills only the launcher), the npm bin shim can exit and orphan the child node/vite/esbuild processes, which keep ports held. Find and stop them by command line, e.g. on Windows PowerShell:

Get-CimInstance Win32_Process -Filter "Name='node.exe' OR Name='esbuild.exe'" |
  Where-Object { $_.CommandLine -match 'inclusa|dev\.mjs|vite' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

(on macOS/Linux: pkill -f 'dev\.mjs|inclusa').

To undo the global link later: npm rm -g @xtrable-ltd/inclusa.

License

MIT © Xtrable Ltd. See LICENSE.