theaccessible-audit-ci 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# theaccessible-audit-ci
+
+CLI for TheAccessible CI/CD integration. Grades a target (URL, build artifact, or VPAT file) against WCAG 2.1 AA / Section 508 and emits a stored, queryable compliance record per commit.
+
+## Install
+
+```bash
+npm install -g theaccessible-audit-ci
+```
+
+## Authenticate
+
+Create an audit API key at <https://theaccessible.org/settings/api-keys>, scope it to a single GitHub-style `owner/repo`, then set:
+
+```bash
+export THEACCESSIBLE_API_KEY="tac_…"
+```
+
+The CLI **never** logs the raw key — it's masked in all stderr output (`tac_xy…wxyz`). Override the API host with `THEACCESSIBLE_API_URL` if you're using a self-hosted deployment.
+
+## Configure
+
+Drop a `.theaccessible.yml` at your repo root:
+
+```yaml
+version: 1
+targets:
+  - name: marketing-site
+    type: url
+    url: https://staging.theaccessible.org
+  - name: pdf-app-build
+    type: build-artifact
+    path: ./apps/web/dist
+gate:
+  mode: advisory          # advisory | blocking
+  min_grade: B            # A | B | C | D | F
+  fail_on: []             # new_critical_issues | grade_regression | min_grade_violation
+notifications:
+  email:
+    digest: weekly
+    recipients: [a11y@example.com]
+timeout_seconds: 300
+```
+
+**`gate.mode` defaults to `advisory` on first install.** Advisory mode prints warnings and exits 0, so installing the CLI never breaks a green build. Switch to `blocking` only after your team has reviewed a few runs and agreed on which gates to enforce.
+
+## Commands
+
+```bash
+theaccessible audit [target]              # run an audit (default: first target)
+theaccessible diff <base-sha> <head-sha>  # show regression delta between two prior runs
+theaccessible report <commit-sha>         # fetch stored reports for a commit
+```
+
+### `audit` options
+
+| Flag                       | Default                | Notes                                              |
+| -------------------------- | ---------------------- | -------------------------------------------------- |
+| `--config <path>`          | `.theaccessible.yml`   | Path to config                                     |
+| `--output-dir <dir>`       | `./.theaccessible`     | Writes `audit-report.json` + `.sarif`              |
+| `--timeout-seconds <n>`    | `gate.timeout_seconds` | Sync poll budget; falls back to async beyond this  |
+| `--fail-on <reasons>`      | `gate.fail_on`         | Comma-separated override                           |
+
+## Exit codes
+
+| Code | Meaning                                                                                         |
+| ---- | ----------------------------------------------------------------------------------------------- |
+| `0`  | Pass (including advisory-mode "would-have-failed" cases)                                        |
+| `1`  | Accessibility gate failed in `blocking` mode                                                    |
+| `2`  | Tool / network / auth error (treat differently from `1` in CI — don't blame the code)           |
+
+Distinguish these in your CI step:
+
+```yaml
+- run: theaccessible audit
+  continue-on-error: ${{ inputs.gate-mode == 'advisory' }}
+```
+
+## Outputs
+
+After every `audit` run you get three artifacts:
+
+- **stdout** — human-readable grade + top regressions.
+- **`./.theaccessible/audit-report.json`** — full machine-readable result.
+- **`./.theaccessible/audit-report.sarif`** — SARIF 2.1.0 for GitHub code-scanning annotations.
+
+## Git context auto-detection
+
+The CLI pulls `commit_sha`, `branch`, `repo`, and `actor` from CI env vars (`GITHUB_SHA`, `GITHUB_REF_NAME`, `GITHUB_REPOSITORY`, `GITHUB_ACTOR`, and the equivalent GitLab `CI_*` vars), falling back to `git rev-parse` locally. The audit endpoint is **idempotent on `(repo, commit_sha, target.name)`** — re-running the same commit returns the existing job and never re-bills.
+
+## Generic CI recipes
+
+See [`docs/ci-integration.md`](../../docs/ci-integration.md) for GitLab CI, CircleCI, Jenkins, and Bitbucket Pipelines snippets.

package/dist/api-client.d.ts

@@ -0,0 +1,60 @@
+export interface AuditRequest {
+    repo: string;
+    commit_sha: string;
+    branch?: string;
+    pr_number?: number;
+    actor?: string;
+    target: {
+        name: string;
+        type: 'url' | 'vpat' | 'build-artifact';
+        url?: string;
+        path?: string;
+        vpat?: unknown;
+        /** Inline HTML payload for single-page build-artifact (legacy). */
+        html?: string;
+        /** S3 key of an uploaded tar.gz build artifact (multipage). */
+        artifact_key?: string;
+        /** Entry HTML paths inside the artifact, relative to its root. */
+        entry_pages?: string[];
+    };
+    wcag_level?: 'A' | 'AA';
+}
+export interface AuditJobResponse {
+    status: 'queued' | 'running' | 'complete' | 'failed';
+    grade: 'A' | 'B' | 'C' | 'D' | 'F' | null;
+    score: number | null;
+    percentage: number | null;
+    result: unknown | null;
+    sarif: unknown | null;
+    error: string | null;
+    started_at: string;
+    finished_at: string | null;
+}
+export interface PostAuditResponse {
+    job_id: string;
+    status: 'queued' | 'running' | 'complete';
+    idempotent: boolean;
+}
+export interface PresignResponse {
+    artifact_key: string;
+    upload_url: string;
+    headers: Record<string, string>;
+    expires_in: number;
+}
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+export declare class ApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    private headers;
+    postAudit(req: AuditRequest): Promise<PostAuditResponse>;
+    presignArtifact(commitSha: string, targetName: string): Promise<PresignResponse>;
+    uploadArtifact(presign: PresignResponse, body: Buffer | Uint8Array): Promise<void>;
+    getJob(jobId: string): Promise<AuditJobResponse>;
+    getReport(id: string): Promise<unknown>;
+    listReports(repo: string, commitSha: string): Promise<unknown[]>;
+}

package/dist/api-client.js

@@ -0,0 +1,105 @@
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'ApiError';
+    }
+}
+export class ApiClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+    }
+    headers() {
+        return {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'theaccessible-audit-ci',
+        };
+    }
+    async postAudit(req) {
+        const res = await fetch(`${this.baseUrl}/api/audit`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify(req),
+        });
+        if (!res.ok && res.status !== 202) {
+            const body = await safeJson(res);
+            throw new ApiError(`POST /api/audit failed (${res.status})`, res.status, body);
+        }
+        const json = (await res.json());
+        if (!json.data)
+            throw new ApiError('Malformed POST /api/audit response', res.status, json);
+        return json.data;
+    }
+    async presignArtifact(commitSha, targetName) {
+        const res = await fetch(`${this.baseUrl}/api/audit/artifacts/presign`, {
+            method: 'POST',
+            headers: this.headers(),
+            body: JSON.stringify({ commit_sha: commitSha, target_name: targetName }),
+        });
+        if (!res.ok) {
+            throw new ApiError(`Presign failed (${res.status})`, res.status, await safeJson(res));
+        }
+        const json = (await res.json());
+        if (!json.data)
+            throw new ApiError('Malformed presign response', res.status, json);
+        return json.data;
+    }
+    async uploadArtifact(presign, body) {
+        const res = await fetch(presign.upload_url, {
+            method: 'PUT',
+            headers: presign.headers,
+            // Node's global fetch accepts Buffer/Uint8Array for body; the DOM
+            // BodyInit lib type isn't available without dom libs in tsconfig.
+            body: body,
+        });
+        if (!res.ok) {
+            throw new ApiError(`Artifact upload failed (${res.status})`, res.status);
+        }
+    }
+    async getJob(jobId) {
+        const res = await fetch(`${this.baseUrl}/api/audit/jobs/${jobId}`, {
+            method: 'GET',
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            throw new ApiError(`GET /api/audit/jobs/${jobId} failed (${res.status})`, res.status, await safeJson(res));
+        }
+        const json = (await res.json());
+        return json.data;
+    }
+    async getReport(id) {
+        const res = await fetch(`${this.baseUrl}/api/audit/reports/${id}`, {
+            method: 'GET',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            throw new ApiError(`GET /api/audit/reports/${id} failed`, res.status, await safeJson(res));
+        const json = (await res.json());
+        return json.data;
+    }
+    async listReports(repo, commitSha) {
+        const url = new URL(`${this.baseUrl}/api/audit/reports`);
+        url.searchParams.set('repo', repo);
+        url.searchParams.set('commit_sha', commitSha);
+        const res = await fetch(url, { headers: this.headers() });
+        if (!res.ok)
+            throw new ApiError('GET /api/audit/reports failed', res.status, await safeJson(res));
+        const json = (await res.json());
+        return json.data.reports;
+    }
+}
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/artifact.d.ts

@@ -0,0 +1,39 @@
+import type { ApiClient } from './api-client';
+/** Hard cap on pages per multipage audit; matches server schema. */
+export declare const MAX_ARTIFACT_PAGES = 25;
+export interface MultipageArtifact {
+    mode: 'multipage';
+    artifactKey: string;
+    entryPages: string[];
+}
+export interface SinglePageArtifact {
+    mode: 'single';
+    html: string;
+}
+export type PreparedArtifact = MultipageArtifact | SinglePageArtifact;
+/**
+ * Recursively list HTML files under `root`, returning paths relative to it.
+ *
+ * Ordering rules:
+ *   - `index.html` (top level) sorts first so it's always the first page
+ *     audited — common convention for entry points.
+ *   - Remaining files sort lexicographically so re-runs are idempotent.
+ *
+ * Skipped:
+ *   - Dot-prefixed entries (.git, .next, .cache) — never relevant for an audit
+ *   - `node_modules` — heuristic to avoid auditing transitive HTML inside deps
+ */
+export declare function listHtmlFiles(root: string): string[];
+/**
+ * Resolve a build-artifact target to either a multipage upload bundle or a
+ * single-page inline-HTML payload, based on whether `path` is a directory.
+ *
+ * Multipage path: tars the directory (system `tar`), presigns + uploads to S3
+ * via the API, returns the artifact key + entry-page list. The server then
+ * enqueues one audit job per page (file:// rendering).
+ *
+ * Single-page path: reads the HTML file directly. Kept for the case where a
+ * caller has only one HTML to audit and wants to skip the S3 round-trip;
+ * loses external-CSS rendering, hence the stderr warning.
+ */
+export declare function prepareBuildArtifact(path: string | undefined, targetName: string, commitSha: string, client: ApiClient, writeStderr?: (msg: string) => void): Promise<PreparedArtifact>;

package/dist/artifact.js

@@ -0,0 +1,80 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, relative, resolve } from 'node:path';
+/** Hard cap on pages per multipage audit; matches server schema. */
+export const MAX_ARTIFACT_PAGES = 25;
+/**
+ * Recursively list HTML files under `root`, returning paths relative to it.
+ *
+ * Ordering rules:
+ *   - `index.html` (top level) sorts first so it's always the first page
+ *     audited — common convention for entry points.
+ *   - Remaining files sort lexicographically so re-runs are idempotent.
+ *
+ * Skipped:
+ *   - Dot-prefixed entries (.git, .next, .cache) — never relevant for an audit
+ *   - `node_modules` — heuristic to avoid auditing transitive HTML inside deps
+ */
+export function listHtmlFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile() && /\.html?$/i.test(entry.name)) {
+                out.push(relative(root, full));
+            }
+        }
+    };
+    walk(root);
+    return out.sort((a, b) => {
+        if (a === 'index.html')
+            return -1;
+        if (b === 'index.html')
+            return 1;
+        return a.localeCompare(b);
+    });
+}
+/**
+ * Resolve a build-artifact target to either a multipage upload bundle or a
+ * single-page inline-HTML payload, based on whether `path` is a directory.
+ *
+ * Multipage path: tars the directory (system `tar`), presigns + uploads to S3
+ * via the API, returns the artifact key + entry-page list. The server then
+ * enqueues one audit job per page (file:// rendering).
+ *
+ * Single-page path: reads the HTML file directly. Kept for the case where a
+ * caller has only one HTML to audit and wants to skip the S3 round-trip;
+ * loses external-CSS rendering, hence the stderr warning.
+ */
+export async function prepareBuildArtifact(path, targetName, commitSha, client, writeStderr = (m) => process.stderr.write(m)) {
+    if (!path) {
+        throw new Error('build-artifact target requires a `path` (HTML file or directory)');
+    }
+    const abs = resolve(process.cwd(), path);
+    const stat = statSync(abs);
+    if (!stat.isDirectory()) {
+        writeStderr('  ℹ Single-page mode (CSS-derived axe rules may be skipped). Point `path` at a directory for full multipage + asset support.\n');
+        return { mode: 'single', html: readFileSync(abs, 'utf8') };
+    }
+    const htmls = listHtmlFiles(abs).slice(0, MAX_ARTIFACT_PAGES);
+    if (htmls.length === 0) {
+        throw new Error(`No HTML files found under ${abs}`);
+    }
+    writeStderr(`  → Tarring ${htmls.length} page(s) from ${abs}\n`);
+    // -C chdirs so the tar's root matches what we send as entry_pages.
+    const tarBuf = execFileSync('tar', ['-czf', '-', '-C', abs, '.'], {
+        maxBuffer: 256 * 1024 * 1024,
+    });
+    writeStderr(`  → Uploading ${tarBuf.length} bytes\n`);
+    const presign = await client.presignArtifact(commitSha, targetName);
+    await client.uploadArtifact(presign, tarBuf);
+    return {
+        mode: 'multipage',
+        artifactKey: presign.artifact_key,
+        entryPages: htmls,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { prepareBuildArtifact } from './artifact';
+import { ApiClient, ApiError } from './api-client';
+import { loadConfig, ConfigError } from './config';
+import { decideExitCode, ExitCode } from './exit-codes';
+import { humanSummary, writeOutputs } from './output';
+import { pollUntilComplete } from './poll';
+import { detectGitContext } from './git';
+const program = new Command();
+function getApiKey() {
+    const key = process.env.THEACCESSIBLE_API_KEY;
+    if (!key || !key.trim()) {
+        process.stderr.write('ERROR: THEACCESSIBLE_API_KEY env var is not set.\n');
+        process.exit(ExitCode.TOOL_ERROR);
+    }
+    return key.trim();
+}
+function getBaseUrl() {
+    return process.env.THEACCESSIBLE_API_URL ?? 'https://api.theaccessible.org';
+}
+function maskKey(k) {
+    if (k.length < 10)
+        return '****';
+    return `${k.slice(0, 6)}…${k.slice(-4)}`;
+}
+program
+    .name('theaccessible')
+    .description('TheAccessible CI/CD audit CLI')
+    .version('0.1.0');
+program
+    .command('audit')
+    .argument('[target]', 'Target name from .theaccessible.yml (default: first target)')
+    .option('-c, --config <path>', 'Path to .theaccessible.yml', '.theaccessible.yml')
+    .option('-o, --output-dir <dir>', 'Directory for audit-report.json + .sarif', './.theaccessible')
+    .option('--timeout-seconds <n>', 'Override config timeout', (v) => parseInt(v, 10))
+    .option('--fail-on <reasons>', 'Override gate.fail_on (comma-separated)')
+    .action(async (targetArg, opts) => {
+    let exit = ExitCode.PASS;
+    try {
+        const cfg = loadConfig(opts.config);
+        const target = targetArg
+            ? cfg.targets.find((t) => t.name === targetArg)
+            : cfg.targets[0];
+        if (!target) {
+            process.stderr.write(`ERROR: target "${targetArg}" not found in ${opts.config}\n`);
+            process.exit(ExitCode.TOOL_ERROR);
+        }
+        const apiKey = getApiKey();
+        const client = new ApiClient(getBaseUrl(), apiKey);
+        const ctx = detectGitContext();
+        if (!ctx.commitSha || !ctx.repo) {
+            process.stderr.write('ERROR: Could not detect commit_sha or repo. Set GITHUB_SHA + GITHUB_REPOSITORY or run inside a git repo.\n');
+            process.exit(ExitCode.TOOL_ERROR);
+        }
+        process.stderr.write(`→ Auditing ${target.name} (${target.type}) — key ${maskKey(apiKey)}\n`);
+        const vpat = target.type === 'vpat' && target.path ? readJsonFile(target.path) : undefined;
+        // For build-artifact targets, two shapes are supported:
+        //   - `path` points at a directory → tar it, upload, audit every
+        //     HTML inside (multipage; CSS / images load via file://)
+        //   - `path` points at a single .html file → legacy inline-HTML path
+        let html;
+        let artifactKey;
+        let entryPages;
+        if (target.type === 'build-artifact') {
+            const artifact = await prepareBuildArtifact(target.path, target.name, ctx.commitSha, client);
+            if (artifact.mode === 'multipage') {
+                artifactKey = artifact.artifactKey;
+                entryPages = artifact.entryPages;
+            }
+            else {
+                html = artifact.html;
+            }
+        }
+        const post = await client.postAudit({
+            repo: ctx.repo,
+            commit_sha: ctx.commitSha,
+            branch: ctx.branch,
+            actor: ctx.actor,
+            ...(ctx.prNumber ? { pr_number: ctx.prNumber } : {}),
+            target: {
+                name: target.name,
+                type: target.type,
+                url: target.url,
+                path: target.path,
+                vpat,
+                html,
+                ...(artifactKey ? { artifact_key: artifactKey } : {}),
+                ...(entryPages ? { entry_pages: entryPages } : {}),
+            },
+        });
+        if (post.idempotent)
+            process.stderr.write(`  ↻ Existing run reused (${post.job_id})\n`);
+        const timeout = opts.timeoutSeconds ?? cfg.timeout_seconds;
+        const job = await pollUntilComplete(client, post.job_id, { timeoutSeconds: timeout });
+        const outputs = writeOutputs(job, opts.outputDir);
+        process.stdout.write(`${humanSummary(job)}\n`);
+        process.stderr.write(`✓ Wrote ${outputs.jsonPath}\n`);
+        process.stderr.write(`✓ Wrote ${outputs.sarifPath}\n`);
+        // Credit exhaustion is an explicit pass-through: the design contract is
+        // "never fail a deploy because the org ran out of audit credits". The
+        // server marks the run failed with error=INSUFFICIENT_CREDITS so the
+        // dashboard can show it, but the CLI exits clean.
+        if (job.status === 'failed' && job.error === 'INSUFFICIENT_CREDITS') {
+            process.stderr.write('⚠ Audit skipped: organization is out of CI credits. Deploy not blocked.\n');
+            process.exit(ExitCode.PASS);
+        }
+        if (job.status === 'failed' || !job.grade) {
+            process.exit(ExitCode.TOOL_ERROR);
+        }
+        const failOnOverride = opts.failOn
+            ? opts.failOn.split(',').map((s) => s.trim()).filter(Boolean)
+            : cfg.gate.fail_on;
+        const result = job.result;
+        const newCriticalIssues = result?.failingCriteria?.filter((c) => c.conformance === 'Does Not Support').length ?? 0;
+        // Resolve previous grade from base SHA so grade_regression gates can fire.
+        // Best-effort: a network error or missing prior run shouldn't fail the
+        // CLI — regression detection just skips silently in that case.
+        let previousGrade = null;
+        if (ctx.baseSha && failOnOverride.includes('grade_regression')) {
+            try {
+                const baseReports = (await client.listReports(ctx.repo, ctx.baseSha));
+                const baseTarget = baseReports.find((r) => r.target_name === target.name);
+                previousGrade = baseTarget?.grade ?? null;
+            }
+            catch (err) {
+                process.stderr.write(`⚠ Could not fetch base report for ${ctx.baseSha}: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+        const decision = decideExitCode({ ...cfg.gate, fail_on: failOnOverride }, {
+            grade: job.grade,
+            newCriticalIssues,
+            previousGrade,
+        });
+        if (decision.code !== ExitCode.PASS) {
+            process.stderr.write(`✗ Gate failed: ${decision.reasons.join('; ')}\n`);
+        }
+        else if (decision.reasons.length > 0) {
+            process.stderr.write(`⚠ Advisory: ${decision.reasons.join('; ')}\n`);
+        }
+        exit = decision.code;
+    }
+    catch (err) {
+        handleError(err);
+        exit = ExitCode.TOOL_ERROR;
+    }
+    process.exit(exit);
+});
+program
+    .command('diff')
+    .argument('<base-sha>', 'Base commit SHA')
+    .argument('<head-sha>', 'Head commit SHA')
+    .option('-c, --config <path>', 'Path to .theaccessible.yml', '.theaccessible.yml')
+    .action(async (baseSha, headSha, opts) => {
+    try {
+        const cfg = loadConfig(opts.config);
+        const client = new ApiClient(getBaseUrl(), getApiKey());
+        const ctx = detectGitContext();
+        if (!ctx.repo)
+            throw new Error('Could not detect repo (set GITHUB_REPOSITORY)');
+        const [baseReports, headReports] = await Promise.all([
+            client.listReports(ctx.repo, baseSha),
+            client.listReports(ctx.repo, headSha),
+        ]);
+        process.stdout.write(formatDiff(cfg.targets, baseReports, headReports) + '\n');
+    }
+    catch (err) {
+        handleError(err);
+        process.exit(ExitCode.TOOL_ERROR);
+    }
+});
+program
+    .command('report')
+    .argument('<commit-sha>')
+    .action(async (commitSha) => {
+    try {
+        const client = new ApiClient(getBaseUrl(), getApiKey());
+        const ctx = detectGitContext();
+        if (!ctx.repo)
+            throw new Error('Could not detect repo');
+        const reports = await client.listReports(ctx.repo, commitSha);
+        process.stdout.write(JSON.stringify(reports, null, 2) + '\n');
+    }
+    catch (err) {
+        handleError(err);
+        process.exit(ExitCode.TOOL_ERROR);
+    }
+});
+function readJsonFile(path) {
+    return JSON.parse(readFileSync(resolve(process.cwd(), path), 'utf8'));
+}
+function formatDiff(targets, base, head) {
+    const byName = (rs) => new Map(rs.map((r) => [
+        r.target_name,
+        r,
+    ]));
+    const b = byName(base);
+    const h = byName(head);
+    const lines = ['Target              Base   Head   Δ%'];
+    for (const t of targets) {
+        const br = b.get(t.name);
+        const hr = h.get(t.name);
+        const delta = hr?.percentage != null && br?.percentage != null ? (hr.percentage - br.percentage).toFixed(1) : '—';
+        lines.push(`${t.name.padEnd(20)}${(br?.grade ?? '—').padEnd(7)}${(hr?.grade ?? '—').padEnd(7)}${delta}`);
+    }
+    return lines.join('\n');
+}
+function handleError(err) {
+    if (err instanceof ConfigError) {
+        process.stderr.write(`ERROR: ${err.message}\n`);
+        if (err.details)
+            process.stderr.write(JSON.stringify(err.details, null, 2) + '\n');
+    }
+    else if (err instanceof ApiError) {
+        process.stderr.write(`ERROR: ${err.message} (HTTP ${err.status})\n`);
+        if (err.body)
+            process.stderr.write(JSON.stringify(err.body, null, 2) + '\n');
+    }
+    else if (err instanceof Error) {
+        process.stderr.write(`ERROR: ${err.message}\n`);
+    }
+    else {
+        process.stderr.write(`ERROR: ${String(err)}\n`);
+    }
+}
+program.parseAsync(process.argv);

package/dist/config.d.ts

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+export declare const ConfigSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    targets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<["url", "vpat", "build-artifact"]>;
+        url: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "url" | "vpat" | "build-artifact";
+        name: string;
+        url?: string | undefined;
+        path?: string | undefined;
+    }, {
+        type: "url" | "vpat" | "build-artifact";
+        name: string;
+        url?: string | undefined;
+        path?: string | undefined;
+    }>, "many">;
+    gate: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<["advisory", "blocking"]>>;
+        min_grade: z.ZodDefault<z.ZodEnum<["A", "B", "C", "D", "F"]>>;
+        fail_on: z.ZodDefault<z.ZodArray<z.ZodEnum<["new_critical_issues", "grade_regression", "min_grade_violation"]>, "many">>;
+        allow_regressions_until: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        mode: "advisory" | "blocking";
+        min_grade: "A" | "B" | "C" | "D" | "F";
+        fail_on: ("new_critical_issues" | "grade_regression" | "min_grade_violation")[];
+        allow_regressions_until?: string | undefined;
+    }, {
+        mode?: "advisory" | "blocking" | undefined;
+        min_grade?: "A" | "B" | "C" | "D" | "F" | undefined;
+        fail_on?: ("new_critical_issues" | "grade_regression" | "min_grade_violation")[] | undefined;
+        allow_regressions_until?: string | undefined;
+    }>>;
+    notifications: z.ZodOptional<z.ZodObject<{
+        email: z.ZodOptional<z.ZodObject<{
+            digest: z.ZodDefault<z.ZodEnum<["off", "daily", "weekly"]>>;
+            recipients: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            digest: "off" | "daily" | "weekly";
+            recipients: string[];
+        }, {
+            digest?: "off" | "daily" | "weekly" | undefined;
+            recipients?: string[] | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        email?: {
+            digest: "off" | "daily" | "weekly";
+            recipients: string[];
+        } | undefined;
+    }, {
+        email?: {
+            digest?: "off" | "daily" | "weekly" | undefined;
+            recipients?: string[] | undefined;
+        } | undefined;
+    }>>;
+    timeout_seconds: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    targets: {
+        type: "url" | "vpat" | "build-artifact";
+        name: string;
+        url?: string | undefined;
+        path?: string | undefined;
+    }[];
+    gate: {
+        mode: "advisory" | "blocking";
+        min_grade: "A" | "B" | "C" | "D" | "F";
+        fail_on: ("new_critical_issues" | "grade_regression" | "min_grade_violation")[];
+        allow_regressions_until?: string | undefined;
+    };
+    timeout_seconds: number;
+    notifications?: {
+        email?: {
+            digest: "off" | "daily" | "weekly";
+            recipients: string[];
+        } | undefined;
+    } | undefined;
+}, {
+    version: 1;
+    targets: {
+        type: "url" | "vpat" | "build-artifact";
+        name: string;
+        url?: string | undefined;
+        path?: string | undefined;
+    }[];
+    gate?: {
+        mode?: "advisory" | "blocking" | undefined;
+        min_grade?: "A" | "B" | "C" | "D" | "F" | undefined;
+        fail_on?: ("new_critical_issues" | "grade_regression" | "min_grade_violation")[] | undefined;
+        allow_regressions_until?: string | undefined;
+    } | undefined;
+    notifications?: {
+        email?: {
+            digest?: "off" | "daily" | "weekly" | undefined;
+            recipients?: string[] | undefined;
+        } | undefined;
+    } | undefined;
+    timeout_seconds?: number | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare class ConfigError extends Error {
+    readonly details?: unknown | undefined;
+    constructor(message: string, details?: unknown | undefined);
+}
+export declare function loadConfig(path: string): Config;

package/dist/config.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import yaml from 'js-yaml';
+export const ConfigSchema = z.object({
+    version: z.literal(1),
+    targets: z
+        .array(z.object({
+        name: z.string().min(1),
+        type: z.enum(['url', 'vpat', 'build-artifact']),
+        url: z.string().url().optional(),
+        path: z.string().optional(),
+    }))
+        .min(1),
+    gate: z
+        .object({
+        mode: z.enum(['advisory', 'blocking']).default('advisory'),
+        min_grade: z.enum(['A', 'B', 'C', 'D', 'F']).default('B'),
+        fail_on: z
+            .array(z.enum(['new_critical_issues', 'grade_regression', 'min_grade_violation']))
+            .default([]),
+        allow_regressions_until: z.string().optional(),
+    })
+        .default({ mode: 'advisory', min_grade: 'B', fail_on: [] }),
+    notifications: z
+        .object({
+        email: z
+            .object({
+            digest: z.enum(['off', 'daily', 'weekly']).default('off'),
+            recipients: z.array(z.string().email()).default([]),
+        })
+            .optional(),
+    })
+        .optional(),
+    timeout_seconds: z.number().int().positive().default(300),
+});
+export class ConfigError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'ConfigError';
+    }
+}
+export function loadConfig(path) {
+    const abs = resolve(process.cwd(), path);
+    let raw;
+    try {
+        raw = readFileSync(abs, 'utf8');
+    }
+    catch (err) {
+        throw new ConfigError(`Could not read config at ${abs}: ${err.message}`);
+    }
+    const parsed = yaml.load(raw);
+    const result = ConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new ConfigError('Invalid .theaccessible.yml', result.error.flatten());
+    }
+    return result.data;
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,16 @@
+export declare const ExitCode: {
+    readonly PASS: 0;
+    readonly GATE_FAILURE: 1;
+    readonly TOOL_ERROR: 2;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+import type { Config } from './config';
+export interface GateInputs {
+    grade: 'A' | 'B' | 'C' | 'D' | 'F';
+    newCriticalIssues: number;
+    previousGrade?: 'A' | 'B' | 'C' | 'D' | 'F' | null;
+}
+export declare function decideExitCode(gate: Config['gate'], inputs: GateInputs): {
+    code: ExitCodeValue;
+    reasons: string[];
+};

package/dist/exit-codes.js

@@ -0,0 +1,25 @@
+export const ExitCode = {
+    PASS: 0,
+    GATE_FAILURE: 1,
+    TOOL_ERROR: 2,
+};
+const ORDER = { A: 5, B: 4, C: 3, D: 2, F: 1 };
+export function decideExitCode(gate, inputs) {
+    const reasons = [];
+    if (gate.fail_on.includes('min_grade_violation') && ORDER[inputs.grade] < ORDER[gate.min_grade]) {
+        reasons.push(`grade ${inputs.grade} is below min_grade ${gate.min_grade}`);
+    }
+    if (gate.fail_on.includes('new_critical_issues') && inputs.newCriticalIssues > 0) {
+        reasons.push(`${inputs.newCriticalIssues} new critical issue(s)`);
+    }
+    if (gate.fail_on.includes('grade_regression') &&
+        inputs.previousGrade &&
+        ORDER[inputs.grade] < ORDER[inputs.previousGrade]) {
+        reasons.push(`grade regressed from ${inputs.previousGrade} to ${inputs.grade}`);
+    }
+    if (reasons.length === 0)
+        return { code: ExitCode.PASS, reasons };
+    if (gate.mode === 'advisory')
+        return { code: ExitCode.PASS, reasons };
+    return { code: ExitCode.GATE_FAILURE, reasons };
+}

package/dist/git.d.ts

@@ -0,0 +1,14 @@
+export interface GitContext {
+    commitSha?: string;
+    branch?: string;
+    repo?: string;
+    actor?: string;
+    /**
+     * Base commit SHA for regression comparison. On a GitHub PR this is the
+     * merge target's SHA at fork time. Falls back to `git merge-base` against
+     * the local default branch.
+     */
+    baseSha?: string;
+    prNumber?: number;
+}
+export declare function detectGitContext(): GitContext;

package/dist/git.js

@@ -0,0 +1,39 @@
+import { execFileSync } from 'node:child_process';
+function safeGit(args) {
+    try {
+        return execFileSync('git', args, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function detectGitContext() {
+    const commitSha = process.env.GITHUB_SHA ?? process.env.CI_COMMIT_SHA ?? safeGit(['rev-parse', 'HEAD']);
+    // PR base SHA. GitHub exposes the merge target ref via GITHUB_BASE_REF
+    // (e.g. "main"). Resolve it against the remote so we get the SHA that the
+    // base branch had when CI started, not the local working tree.
+    let baseSha;
+    if (process.env.GITHUB_BASE_REF) {
+        baseSha = safeGit(['rev-parse', `origin/${process.env.GITHUB_BASE_REF}`]);
+    }
+    else if (process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA) {
+        baseSha = process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+    }
+    else if (commitSha) {
+        // Local / push event — best-effort merge-base against the default remote.
+        baseSha = safeGit(['merge-base', commitSha, 'origin/HEAD']) ?? safeGit(['merge-base', commitSha, 'origin/main']);
+    }
+    const prRaw = process.env.GITHUB_PR_NUMBER ?? process.env.CI_MERGE_REQUEST_IID;
+    const prNumber = prRaw ? Number.parseInt(prRaw, 10) : undefined;
+    return {
+        commitSha,
+        branch: process.env.GITHUB_HEAD_REF ??
+            process.env.GITHUB_REF_NAME ??
+            process.env.CI_COMMIT_REF_NAME ??
+            safeGit(['rev-parse', '--abbrev-ref', 'HEAD']),
+        repo: process.env.GITHUB_REPOSITORY ?? process.env.CI_PROJECT_PATH,
+        actor: process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN,
+        baseSha,
+        ...(prNumber && Number.isFinite(prNumber) ? { prNumber } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ApiClient, type AuditJobResponse, type AuditRequest } from './api-client';
+export { loadConfig, ConfigSchema, type Config } from './config';
+export { ExitCode, decideExitCode } from './exit-codes';
+export { humanSummary, writeOutputs } from './output';
+export { pollUntilComplete } from './poll';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { ApiClient } from './api-client';
+export { loadConfig, ConfigSchema } from './config';
+export { ExitCode, decideExitCode } from './exit-codes';
+export { humanSummary, writeOutputs } from './output';
+export { pollUntilComplete } from './poll';

package/dist/output.d.ts

@@ -0,0 +1,7 @@
+import type { AuditJobResponse } from './api-client';
+export interface OutputResult {
+    jsonPath: string;
+    sarifPath: string;
+}
+export declare function writeOutputs(job: AuditJobResponse, outputDir: string): OutputResult;
+export declare function humanSummary(job: AuditJobResponse): string;

package/dist/output.js

@@ -0,0 +1,37 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function writeOutputs(job, outputDir) {
+    const abs = resolve(process.cwd(), outputDir);
+    mkdirSync(abs, { recursive: true });
+    const jsonPath = `${abs}/audit-report.json`;
+    const sarifPath = `${abs}/audit-report.sarif`;
+    writeFileSync(jsonPath, JSON.stringify(job.result ?? {}, null, 2));
+    writeFileSync(sarifPath, JSON.stringify(job.sarif ?? emptySarif(), null, 2));
+    return { jsonPath, sarifPath };
+}
+function emptySarif() {
+    return {
+        $schema: 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json',
+        version: '2.1.0',
+        runs: [{ tool: { driver: { name: 'TheAccessible Audit', version: '1.0.0' } }, results: [] }],
+    };
+}
+export function humanSummary(job) {
+    if (job.status === 'failed') {
+        return `✗ Audit failed: ${job.error ?? 'unknown error'}`;
+    }
+    const result = job.result;
+    const lines = [];
+    lines.push(`Grade: ${job.grade ?? '—'}  (${(job.percentage ?? 0).toFixed(1)}%)`);
+    if (result?.summary) {
+        const s = result.summary;
+        lines.push(`Supports: ${s.supports ?? 0}   Partial: ${s.partiallySupports ?? 0}   Fails: ${s.doesNotSupport ?? 0}   N/A: ${s.notApplicable ?? 0}`);
+    }
+    if (result?.failingCriteria?.length) {
+        lines.push('Top regressions:');
+        for (const c of result.failingCriteria.slice(0, 5)) {
+            lines.push(`  • ${c.id} ${c.name} — ${c.conformance}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/poll.d.ts

@@ -0,0 +1,7 @@
+import type { ApiClient, AuditJobResponse } from './api-client';
+export interface PollOptions {
+    timeoutSeconds: number;
+    initialIntervalMs?: number;
+    maxIntervalMs?: number;
+}
+export declare function pollUntilComplete(client: ApiClient, jobId: string, opts: PollOptions): Promise<AuditJobResponse>;

package/dist/poll.js

@@ -0,0 +1,14 @@
+export async function pollUntilComplete(client, jobId, opts) {
+    const start = Date.now();
+    const deadline = start + opts.timeoutSeconds * 1000;
+    let interval = opts.initialIntervalMs ?? 5_000;
+    const maxInterval = opts.maxIntervalMs ?? 30_000;
+    while (Date.now() < deadline) {
+        const job = await client.getJob(jobId);
+        if (job.status === 'complete' || job.status === 'failed')
+            return job;
+        await new Promise((r) => setTimeout(r, interval));
+        interval = Math.min(maxInterval, Math.floor(interval * 1.5));
+    }
+    throw new Error(`Polling timed out after ${opts.timeoutSeconds}s waiting for job ${jobId}`);
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "theaccessible-audit-ci",
+  "version": "0.2.0",
+  "description": "TheAccessible CI/CD audit CLI — grade accessibility compliance on every PR and deploy.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LarryAnglin/theaccessible-platform.git",
+    "directory": "packages/audit-cli"
+  },
+  "bin": {
+    "theaccessible": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}