API

The equall-cli package exposes a small ESM API so you can embed the scanner inside a custom CI script, a pre-commit runner, or a dashboard backend. Everything the CLI does is reachable through runScan().

Module format

equall-cli is shipped as an ESM-only package with a single root export plus .d.ts declarations. The minimum supported runtime is Node ≥ 18.

{
  "type": "module",
  "dependencies": { "equall-cli": "^0.1.7" }
}

If you must call it from a CommonJS file, use a dynamic await import('equall-cli').

Example

import { runScan } from 'equall-cli'

const result = await runScan({
  path: './my-project',
  level: 'AA',
})

console.log(`Score: ${result.score} (${result.conformance_level})`)
console.log(`POUR:`, result.pour_scores)

for (const issue of result.issues) {
  if (issue.ignored) continue
  console.log(
    `${issue.file_path}:${issue.line ?? '?'}  ${issue.scanner_rule_id}  — ${issue.message}`,
  )
}

The full shape of the returned ScanResult document is documented on Output format.

Public exports

runScan(options)

Discovers files, runs every available scanner in parallel, deduplicates findings, applies equall-ignore comments, and returns a fully scored ScanResult.

function runScan(options?: RunScanOptions): Promise<ScanResult>

interface RunScanOptions {
  path?: string                  // Project root. Default: process.cwd()
  level?: 'A' | 'AA' | 'AAA'     // WCAG target. Default: 'AA'
  include?: string[]             // Glob patterns to include
  exclude?: string[]             // Glob patterns to exclude
  disableScanners?: string[]     // Scanner names to skip, e.g. ['readability']
}

The path, level, include, and exclude options mirror the CLI flags one-to-one — see Scanning for their semantics.

runScan never throws on individual scanner failures: a crashed scanner is logged to console.warn, its results are dropped, and the run continues with the others. It can throw if the root path is unreadable, so wrap the call in try/catch if you need to surface that as a domain error.

computeScanResult(...)

Lower-level helper that takes an already-collected issue list and produces a ScanResult. Exposed mainly so tooling that runs scanners on its own can still reuse Equall's scoring formula.

function computeScanResult(
  issues: EquallIssue[],
  filesScanned: number,
  scannersUsed: ScannerInfo[],
  durationMs: number,
  targetLevel?: 'A' | 'AA' | 'AAA',
  criteriaCovered?: string[],
  criteriaTotal?: number,
): ScanResult

Public types

All types are re-exported from the package root and ship with .d.ts declarations:

import type {
  RunScanOptions,
  ScanResult,
  EquallIssue,
  PourScores,
  ConformanceLevel,
  Severity,
  WcagLevel,
  PourPrinciple,
  ScannerAdapter,
  ScanContext,
  ScanOptions,
} from 'equall-cli'

The runtime shape of ScanResult, EquallIssue, PourScores, and the union types (ConformanceLevel, Severity, WcagLevel, PourPrinciple) is documented on Output format — that page is the canonical contract for both runScan() consumers and --json integrators.

ScannerAdapter, ScanContext, and ScanOptions are the lower-level interfaces the built-in scanners implement. They're exported for tooling that wants to call computeScanResult with its own issue list, but they aren't required for typical runScan usage.

Stability

Equall is pre-1.0 (current version 0.1.7). The shape of ScanResult and the signature of runScan are treated as a public contract: fields are added compatibly between minor versions, and any breaking change will be called out explicitly in the release notes. Known intentional limitations are tracked on Known issues.