@a11y-lens/cli 0.4.1 → 0.5.0

package/README.md

@@ -31,6 +31,8 @@ husky - pre-commit hook exited with code 1
 
 **Infrastructure never blocks a commit.** No agent CLI, no network, agent crash → a11y-lens warns and exits 0. Only real accessibility findings gate.
 
+**…but a skipped check does not pass for a clean one.** Exiting 0 means your hook runner shows the same ✔️ either way, so when a staged check could not review a file — the agent timed out or failed, its output could not be parsed, or the file was dropped for the prompt size budget — a11y-lens records it as *pending*. The next check warns about it, and `a11y-lens check --pending` reviews it later. See [Skipped checks](#skipped-checks).
+
 ## It samples; it does not audit
 
 a11y-lens is an AI reviewer, not a deterministic linter. The same files reviewed twice can return different findings — even zero on a run that flagged issues a moment earlier. Read the output with that in mind:
@@ -76,11 +78,42 @@ a11y-lens check --staged           # what the git hook runs
 a11y-lens check src/Modal.tsx      # review specific files
 a11y-lens check --staged --strict  # warnings also fail
 a11y-lens check --staged --agent codex
+a11y-lens check --pending          # review files an earlier check skipped
 a11y-lens rules                    # list rule categories
 ```
 
 Escape hatches: `A11Y_LENS_SKIP=1 git commit …` or `git commit --no-verify`.
 
+| Environment | Effect |
+|---|---|
+| `A11Y_LENS_AGENT` | same as `--agent` |
+| `A11Y_LENS_MODEL` | model passed to `claude` |
+| `A11Y_LENS_TIMEOUT_MS` | agent timeout in milliseconds (default `180000`) |
+| `A11Y_LENS_SKIP=1` | skip the check entirely |
+
+## Skipped checks
+
+A staged check records a file as pending when it could not review it:
+
+| Why the file was not reviewed | Recorded? |
+|---|---|
+| Agent timed out, crashed, or exited non-zero (including logged out or out of quota) | yes |
+| Agent output could not be parsed as findings | yes |
+| Dropped because the prompt size budget was spent | yes |
+| `A11Y_LENS_SKIP=1`, no agent CLI installed, file over 48KB, no UI files staged | no: deliberate, or it would be skipped again |
+
+An entry is cleared when `check --pending` reviews it, or when a later `check --staged` in the same worktree reviews the very same staged content (a commit that was aborted and retried). If the skipped commit landed, its change is no longer in the next diff, so only `--pending` clears it. `--pending` reviews the content that was **staged at the time**, with its staged diff. That way it reports on the skipped change, not on the whole file as it is now. It works even after the file has changed or its worktree is gone. Each skipped check is reviewed in its own agent call. Anything that times out or is dropped again stays pending.
+
+**Layout (public contract, version 1).** Other tools may read this, for example a hook that reminds an agent to run `--pending`:
+
+```
+<git rev-parse --git-common-dir>/a11y-lens/pending/<sha1>.json
+{ "version": 1, "worktree": "/abs/path", "path": "src/A.tsx", "blob": "<index sha>",
+  "diff": "<staged diff>", "reason": "agent failed: …", "at": "2026-09-23T06:00:00.000Z" }
+```
+
+A non-empty directory means something was not reviewed. Any change to this layout bumps `version`. A record this version cannot read (another version wrote it, or it is damaged) is reported and never cleared automatically. Once it has been dealt with, delete the file by hand.
+
 ## Rule set
 
 One markdown file per category in `skills/a11y-lens/references/`, consumed by both the skill and the CLI. Each separates the **static baseline** (what eslint/axe already catch — not re-reported) from the **semantic checks** this tool exists for.

package/bin/a11y-lens.mjs

@@ -7,6 +7,7 @@ import { installHook, detectRunner } from '../src/hooks.mjs';
 import { detectAgent, runAgent } from '../src/agent.mjs';
 import { buildPrompt } from '../src/prompt.mjs';
 import { parseFindings, printReport, exitCodeFor } from '../src/report.mjs';
+import { recordPending, listPending, clearReviewed, clearEntry, contentOf, pendingDir } from '../src/pending.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -15,6 +16,7 @@ const HELP = `a11y-lens — AI-powered semantic accessibility linter
 Usage:
   a11y-lens check --staged            review staged UI files (for git hooks)
   a11y-lens check <files...>          review specific files
+  a11y-lens check --pending           review files an earlier check skipped
   a11y-lens init                      install the pre-commit hook (lefthook/husky/git hooks,
                                       auto-detected) + inject rules reference into ./AGENTS.md
   a11y-lens rules                     list rule categories
@@ -30,15 +32,18 @@ Environment:
   A11Y_LENS_AGENT                     same as --agent
   A11Y_LENS_MODEL                     model override passed to claude (optional)
   A11Y_LENS_SKIP=1                    skip the check entirely (escape hatch)
+  A11Y_LENS_TIMEOUT_MS                agent timeout in ms (default 180000)
 
 Infrastructure failures (no agent CLI, no network, agent error) never block:
-a11y-lens warns and exits 0. Only accessibility findings gate.`;
+a11y-lens warns and exits 0. Only accessibility findings gate. When a staged
+check could not review a file (agent failure or timeout, unparseable output,
+prompt budget), the file is recorded as pending until a later run reviews it.`;
 
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const token = argv[i];
-    if (token === '--staged' || token === '--strict' || token === '--no-hook') {
+    if (token === '--staged' || token === '--strict' || token === '--no-hook' || token === '--pending') {
       args.flags[token.slice(2)] = true;
     }
     else if (token === '--agent') args.flags.agent = argv[++i];
@@ -48,17 +53,60 @@ function parseArgs(argv) {
   return args;
 }
 
+const RECHECK = 'a11y-lens check --pending';
+
 function softFail(message) {
   console.warn(`a11y-lens: ${message} — skipping check (commits are never blocked by infrastructure).`);
   process.exit(0);
 }
 
+/** Record what a staged run could not review, and say so where the committer will see it. */
+const RUN_STARTED = new Date();
+
+function notePending(files, reason) {
+  const result = recordPending(files, reason, { now: RUN_STARTED });
+  if (result.error) {
+    console.warn(`a11y-lens: could not record ${files.length} unreviewed file(s) as pending (${result.error}).`);
+  } else {
+    console.warn(`a11y-lens: recorded ${result.recorded} unreviewed file(s) as pending — review them later with: ${RECHECK}`);
+  }
+}
+
+function skipStaged(files, message) {
+  notePending(files, message);
+  softFail(message);
+}
+
+function warnUnreadable(count) {
+  console.warn(
+    `a11y-lens: ${count} pending record(s) in ${pendingDir()} could not be read (another a11y-lens version, or damaged). ` +
+      'This version never clears them; delete them by hand once you have dealt with them.',
+  );
+}
+
+/**
+ * Before anything can exit early (a skip, a commit with no UI files): a skipped check looks like a
+ * clean one, so the next run is the first chance to say it happened.
+ */
+function warnPending() {
+  const { entries, unreadable } = listPending();
+  if (entries.length) {
+    console.warn(
+      `a11y-lens: ${entries.length} file(s) from earlier commits were never reviewed (the check was skipped). Review them with: ${RECHECK}`,
+    );
+  }
+  if (unreadable) {
+    warnUnreadable(unreadable);
+  }
+}
+
 function commandCheck(args) {
+  if (args.flags.pending) return commandCheckPending(args);
+  warnPending();
   if (process.env.A11Y_LENS_SKIP === '1') softFail('A11Y_LENS_SKIP=1');
 
-  const { files, error } = args.flags.staged
-    ? collectStagedUIFiles()
-    : collectPathArgs(args._);
+  const staged = Boolean(args.flags.staged);
+  const { files, error } = staged ? collectStagedUIFiles() : collectPathArgs(args._);
   if (error) softFail(error);
 
   const reviewable = files.filter((f) => !f.skipped);
@@ -66,7 +114,7 @@ function commandCheck(args) {
     console.warn(`a11y-lens: skipping ${f.path} (${f.skipped})`);
   }
   if (reviewable.length === 0) {
-    if (args.flags.staged) console.log('a11y-lens: no staged UI files, nothing to review.');
+    if (staged) console.log('a11y-lens: no staged UI files, nothing to review.');
     else console.log('a11y-lens: no reviewable files given. Try: a11y-lens check src/Component.tsx');
     process.exit(0);
   }
@@ -78,20 +126,106 @@ function commandCheck(args) {
   for (const path of dropped) {
     console.warn(`a11y-lens: dropped ${path} (prompt size budget exceeded)`);
   }
+  const included = reviewable.filter((f) => !dropped.includes(f.path));
+  if (staged && dropped.length) {
+    notePending(reviewable.filter((f) => dropped.includes(f.path)), 'prompt size budget exceeded');
+  }
 
-  console.log(
-    `a11y-lens: reviewing ${reviewable.length - dropped.length} file(s) with ${detection.name}…`,
-  );
+  if (included.length === 0) process.exit(0);
+  console.log(`a11y-lens: reviewing ${included.length} file(s) with ${detection.name}…`);
   const result = runAgent(detection.agent, prompt);
-  if (!result.ok) softFail(`agent failed: ${result.error}`);
+  if (!result.ok) {
+    if (staged) skipStaged(included, `agent failed: ${result.error}`);
+    softFail(`agent failed: ${result.error}`);
+  }
 
   const parsed = parseFindings(result.output);
-  if (parsed.error) softFail(parsed.error);
+  if (parsed.error) {
+    if (staged) skipStaged(included, parsed.error);
+    softFail(parsed.error);
+  }
+
+  // Reviewed now, so an entry left by an earlier skip of the same path — say, a commit that
+  // typecheck aborted in parallel — is answered.
+  if (staged) clearReviewed(included.map((f) => f.path));
 
   printReport(parsed.findings, { agentName: detection.name });
   process.exit(exitCodeFor(parsed.findings, { strict: args.flags.strict }));
 }
 
+/**
+ * Review what earlier staged runs skipped. One agent call per recorded skip, not one for all of
+ * them: a bad session leaves dozens of entries, and a single prompt that big would time out again
+ * and never let the list shrink. Each batch clears only what it actually reviewed.
+ */
+function commandCheckPending(args) {
+  const { entries, unreadable } = listPending();
+  if (unreadable) {
+    warnUnreadable(unreadable);
+  }
+  if (entries.length === 0) {
+    console.log('a11y-lens: nothing pending.');
+    process.exit(0);
+  }
+
+  const detection = detectAgent(args.flags.agent);
+  if (detection.error) softFail(`${detection.error}; ${entries.length} file(s) remain pending`);
+
+  const batches = new Map();
+  for (const item of [...entries].sort((a, b) => a.entry.at.localeCompare(b.entry.at))) {
+    const key = `${item.entry.worktree}\0${item.entry.at}`;
+    if (!batches.has(key)) batches.set(key, []);
+    batches.get(key).push(item);
+  }
+
+  const findings = [];
+  let remaining = 0;
+  for (const batch of batches.values()) {
+    const files = [];
+    for (const item of batch) {
+      const found = contentOf(item.entry);
+      if (found.gone) {
+        console.warn(`a11y-lens: dropping pending ${item.entry.path} (${found.gone})`);
+        clearEntry(item);
+        continue;
+      }
+      files.push({ path: item.entry.path, content: found.content, diff: item.entry.diff, item });
+    }
+    if (files.length === 0) continue;
+
+    const { prompt, dropped } = buildPrompt(files);
+    const included = files.filter((f) => !dropped.includes(f.path));
+    if (included.length === 0) {
+      console.warn(`a11y-lens: every file skipped at ${batch[0].entry.at} exceeds the prompt budget — they stay pending.`);
+      remaining += files.length;
+      continue;
+    }
+    console.log(
+      `a11y-lens: reviewing ${included.length} pending file(s) skipped at ${batch[0].entry.at} with ${detection.name}…`,
+    );
+    const result = runAgent(detection.agent, prompt);
+    const parsed = result.ok ? parseFindings(result.output) : { error: `agent failed: ${result.error}` };
+    if (parsed.error) {
+      console.warn(`a11y-lens: ${parsed.error} — ${files.length} file(s) stay pending.`);
+      remaining += files.length;
+      continue;
+    }
+    findings.push(...parsed.findings);
+    for (const f of files) {
+      if (dropped.includes(f.path)) {
+        console.warn(`a11y-lens: dropped ${f.path} (prompt size budget exceeded) — it stays pending.`);
+        remaining++;
+      } else {
+        clearEntry(f.item);
+      }
+    }
+  }
+
+  printReport(findings, { agentName: detection.name });
+  if (remaining) console.warn(`a11y-lens: ${remaining} file(s) are still pending — run ${RECHECK} again.`);
+  process.exit(exitCodeFor(findings, { strict: args.flags.strict }));
+}
+
 function commandInit(args) {
   // 1. Pre-commit hook (lefthook / husky / plain git hooks, auto-detected)
   if (!args.flags['no-hook']) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-lens/cli",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs"
   },
   "keywords": [
     "accessibility",

package/src/agent.mjs

@@ -1,37 +1,47 @@
 import { spawnSync } from 'node:child_process';
 
-const TIMEOUT_MS = 180_000;
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+/** A11Y_LENS_TIMEOUT_MS if it is a positive integer, else the default (with a warning for a bad value). */
+export function timeoutMs(env = process.env) {
+  const raw = env.A11Y_LENS_TIMEOUT_MS;
+  if (raw === undefined || raw === '') return DEFAULT_TIMEOUT_MS;
+  const value = Number(raw);
+  if (Number.isInteger(value) && value > 0) return value;
+  console.warn(`a11y-lens: ignoring A11Y_LENS_TIMEOUT_MS="${raw}" (not a positive integer); using ${DEFAULT_TIMEOUT_MS}ms`);
+  return DEFAULT_TIMEOUT_MS;
+}
 
 const AGENTS = {
   claude: {
     bin: 'claude',
-    invoke(prompt) {
+    invoke(prompt, timeout) {
       const args = ['-p', '--output-format', 'text'];
       if (process.env.A11Y_LENS_MODEL) args.push('--model', process.env.A11Y_LENS_MODEL);
       return spawnSync('claude', args, {
         input: prompt,
         encoding: 'utf8',
-        timeout: TIMEOUT_MS,
+        timeout,
         maxBuffer: 10 * 1024 * 1024,
       });
     },
   },
   codex: {
     bin: 'codex',
-    invoke(prompt) {
+    invoke(prompt, timeout) {
       return spawnSync('codex', ['exec', prompt], {
         encoding: 'utf8',
-        timeout: TIMEOUT_MS,
+        timeout,
         maxBuffer: 10 * 1024 * 1024,
       });
     },
   },
   cursor: {
     bin: 'cursor-agent',
-    invoke(prompt) {
+    invoke(prompt, timeout) {
       return spawnSync('cursor-agent', ['-p', prompt, '--output-format', 'text'], {
         encoding: 'utf8',
-        timeout: TIMEOUT_MS,
+        timeout,
         maxBuffer: 10 * 1024 * 1024,
       });
     },
@@ -61,10 +71,10 @@ export function detectAgent(preferred) {
 }
 
 /** Run the review prompt through the agent. Returns { ok, output, error }. */
-export function runAgent(agent, prompt) {
+export function runAgent(agent, prompt, timeout = timeoutMs()) {
   let result;
   try {
-    result = agent.invoke(prompt);
+    result = agent.invoke(prompt, timeout);
   } catch (err) {
     return { ok: false, error: String(err) };
   }

package/src/pending.mjs

@@ -0,0 +1,166 @@
+// Pending reviews: staged files a check could not review, kept so the skip is visible later.
+//
+// A skipped check exits 0 so a commit is never blocked by infrastructure — which also makes it look
+// exactly like a clean one. Each file it failed to review is recorded here, and stays until a later
+// run actually reviews it (`check --staged` on the same path, or `check --pending`).
+//
+// Layout (a public contract — other tools read it; bump PENDING_VERSION on any change):
+//   <git-common-dir>/a11y-lens/pending/<sha1(worktree + NUL + path)>.json
+//   { version, worktree, path, blob, diff, reason, at }
+//
+// - One file per entry: parallel commits in several worktrees record at the same moment, and a
+//   single shared file would lose one of them. Each is written to a temp file and renamed, so a
+//   reader never sees half an entry (untested: the race cannot be staged deterministically).
+// - The common dir, so an entry recorded in a worktree is still visible after that worktree is gone.
+// - `blob` is the index object that was staged. It lives in the shared object store, so the exact
+//   content that went unreviewed can still be read after the worktree is removed or the file edited.
+// - `diff` is the staged diff, so a re-check reviews the change rather than the whole file and does
+//   not report pre-existing issues as if the skipped commit introduced them.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PENDING_VERSION = 1;
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 10 * 1024 * 1024 });
+}
+
+/** Absolute pending directory, or null outside a git repository. */
+export function pendingDir(cwd = process.cwd()) {
+  try {
+    const common = git(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd).trim();
+    return join(common, 'a11y-lens', 'pending');
+  } catch {
+    return null;
+  }
+}
+
+function worktreeOf(cwd) {
+  return git(['rev-parse', '--show-toplevel'], cwd).trim();
+}
+
+function entryName(worktree, path) {
+  return `${createHash('sha1').update(`${worktree}\0${path}`).digest('hex')}.json`;
+}
+
+/**
+ * Record staged files that were not reviewed. `files` are staged entries ({ path, diff }).
+ * Returns { recorded } or { error } — never throws, because a failure here must not block a commit.
+ */
+export function recordPending(files, reason, { cwd = process.cwd(), now = new Date() } = {}) {
+  if (files.length === 0) return { recorded: 0 };
+  try {
+    const dir = pendingDir(cwd);
+    if (!dir) return { error: 'not a git repository' };
+    const worktree = worktreeOf(cwd);
+    mkdirSync(dir, { recursive: true });
+    const at = now.toISOString();
+    for (const file of files) {
+      let blob = null;
+      try {
+        blob = git(['rev-parse', `:${file.path}`], worktree).trim();
+      } catch {
+        /* not in the index (non-staged run); the working-tree path is the only locator */
+      }
+      const entry = { version: PENDING_VERSION, worktree, path: file.path, blob, diff: file.diff ?? '', reason, at };
+      const target = join(dir, entryName(worktree, file.path));
+      const temp = `${target}.${process.pid}.tmp`;
+      writeFileSync(temp, JSON.stringify(entry));
+      renameSync(temp, target);
+    }
+    return { recorded: files.length };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+/** All readable entries, each with its file name. Unreadable or foreign-version files are counted, not returned. */
+export function listPending(cwd = process.cwd()) {
+  const dir = pendingDir(cwd);
+  if (!dir) return { entries: [], unreadable: 0 };
+  let names;
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith('.json'));
+  } catch {
+    return { entries: [], unreadable: 0 };
+  }
+  const entries = [];
+  let unreadable = 0;
+  for (const name of names) {
+    try {
+      const raw = readFileSync(join(dir, name), 'utf8');
+      const entry = JSON.parse(raw);
+      if (entry?.version !== PENDING_VERSION || typeof entry.path !== 'string') {
+        unreadable++;
+        continue;
+      }
+      entries.push({ name, raw, entry });
+    } catch {
+      unreadable++;
+    }
+  }
+  return { entries, unreadable };
+}
+
+/**
+ * Drop entries a staged run has just reviewed — only when the recorded blob is the one staged now.
+ * That is a commit aborted (typecheck failed in parallel, say) and retried as it was: the skipped
+ * content is exactly what was reviewed. If the skipped commit landed instead, its change is in HEAD
+ * and absent from the new diff, so this review did not look at it and the entry must stay.
+ */
+export function clearReviewed(paths, cwd = process.cwd()) {
+  try {
+    const dir = pendingDir(cwd);
+    if (!dir) return;
+    const worktree = worktreeOf(cwd);
+    for (const path of paths) {
+      const file = join(dir, entryName(worktree, path));
+      let entry;
+      try {
+        entry = JSON.parse(readFileSync(file, 'utf8'));
+      } catch {
+        continue;
+      }
+      const staged = git(['rev-parse', `:${path}`], worktree).trim();
+      if (entry.blob && entry.blob === staged) rmSync(file, { force: true });
+    }
+  } catch {
+    /* best effort: a stale entry is re-checked later, never lost */
+  }
+}
+
+/**
+ * Drop an entry read earlier, but only if it has not been re-recorded since — a commit that skipped
+ * the same path while `--pending` ran has content this run did not review.
+ */
+export function clearEntry({ name, raw }, cwd = process.cwd()) {
+  const dir = pendingDir(cwd);
+  if (!dir) return;
+  const file = join(dir, name);
+  try {
+    if (readFileSync(file, 'utf8') === raw) rmSync(file, { force: true });
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * The content an entry stands for: the staged blob, else the working-tree file.
+ * Returns { content } or { gone: reason }.
+ */
+export function contentOf(entry, cwd = process.cwd()) {
+  if (entry.blob) {
+    try {
+      return { content: git(['cat-file', '-p', entry.blob], cwd) };
+    } catch {
+      /* pruned by gc — fall through to the working tree */
+    }
+  }
+  try {
+    return { content: readFileSync(join(entry.worktree, entry.path), 'utf8') };
+  } catch {
+    return { gone: 'neither the staged blob nor the file exists any more' };
+  }
+}

package/src/prompt.mjs

@@ -34,19 +34,19 @@ export function buildPrompt(files) {
   let budget = MAX_TOTAL_BYTES;
 
   for (const file of files) {
-    const block = [
-      `### FILE: ${file.path}`,
-      '```',
-      numbered(file.content),
-      '```',
-      file.diff ? `#### Staged diff for ${file.path} (focus your review here)\n\`\`\`diff\n${file.diff}\n\`\`\`` : '',
-    ].join('\n');
-    const size = Buffer.byteLength(block, 'utf8');
-    if (size > budget) {
+    const fileBlock = [`### FILE: ${file.path}`, '```', numbered(file.content), '```'].join('\n');
+    const withDiff = file.diff
+      ? `${fileBlock}\n#### Staged diff for ${file.path} (focus your review here)\n\`\`\`diff\n${file.diff}\n\`\`\``
+      : fileBlock;
+    // Content is capped at 48KB and a diff is not, so a rewrite can make one file's block larger
+    // than the whole budget — dropped every time, including on every `--pending` re-check. Without
+    // its diff it always fits an empty budget, so it is reviewed whole rather than never.
+    const block = [withDiff, fileBlock].find((b) => Buffer.byteLength(b, 'utf8') <= budget);
+    if (!block) {
       dropped.push(file.path);
       continue;
     }
-    budget -= size;
+    budget -= Buffer.byteLength(block, 'utf8');
     included.push(block);
   }
 

package/src/staged.mjs

@@ -58,7 +58,7 @@ export function collectStagedUIFiles() {
 
     let diff = '';
     try {
-      diff = git(['diff', '--cached', '--unified=3', '--', path]);
+      diff = git(['diff', '--cached', '--unified=3', '--', `:(top)${path}`]);
     } catch {
       /* diff is best-effort context */
     }