@a11y-lens/cli 0.4.0 → 0.4.1

package/README.md

@@ -31,6 +31,16 @@ 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.
 
+## 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:
+
+- **A clean run ≠ zero issues.** It means nothing surfaced *in that sample*, not that the code is fully accessible.
+- **Findings don't converge to zero.** Re-running to "clear" every last warning is the wrong mental model; a later run may raise something new.
+- **The intended job is gating `--staged` diffs** — catching problems as they're *introduced*. It is not a full-audit tool for an existing codebase; for that, pair it with a human accessibility review.
+
+This is deliberate: only clear `error`-severity violations gate and warnings never block, precisely because AI output varies run to run. (This note belongs here, in the tool's own README — not in the `AGENTS.md` rules block that `init` injects into a consuming project, which is reserved for the accessibility rules themselves.)
+
 ## Install
 
 a11y-lens has two layers — install either or both:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-lens/cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "publishConfig": {
     "access": "public"
   },

package/src/staged.mjs

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 
 const UI_EXTENSIONS = new Set([
   '.jsx', '.tsx', '.html', '.htm', '.vue', '.svelte', '.astro', '.mdx',
@@ -72,12 +73,17 @@ export function collectPathArgs(paths) {
   for (const path of paths) {
     let content;
     try {
-      content = execFileSync('cat', [path], {
-        encoding: 'utf8',
-        maxBuffer: 10 * 1024 * 1024,
-      });
+      // readFileSync (not a `cat` shell-out): portable to Windows, and filenames
+      // that start with `-` are never mistaken for flags.
+      content = readFileSync(path, 'utf8');
     } catch {
-      files.push({ path, skipped: 'unreadable' });
+      // An unreadable argument that contains whitespace is almost always several
+      // paths the shell never word-split (e.g. an unquoted joined variable in zsh)
+      // delivered as one argument. Surface that instead of silently skipping.
+      const skipped = /\s/.test(path)
+        ? 'looks like several paths passed as one argument — pass each file as a separate, unquoted argument (in zsh, check array/glob expansion)'
+        : 'unreadable';
+      files.push({ path, skipped });
       continue;
     }
     if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {