@fringetools/cli 0.2.2 → 0.3.0

package/README.md

@@ -22,6 +22,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | Command | What it does |
 |---|---|
 | `fringe check [dir\|file]` | Scan a directory (default `.`) or judge one file (the project root is found by climbing to the nearest `package.json`). Prints findings and the health score. Exit `1` on any `error`. |
+| `fringe scan <url> [--json]` | **Runtime check of a live page** (needs `npm i -D playwright-core axe-core`; uses your installed Chrome). Runs axe-core for real contrast, computed names and ARIA relations (`FR-400`; critical/serious = `error`, the rest `review`), then walks the page with Tab and reports keyboard traps (`FR-401`, error) and controls Tab never reaches (review). Accepts `http(s)://` and `file://` URLs. Exit `1` on errors. |
 | `fringe plan [dir\|file] [--json] [--limit n]` | **Fix order for a repo with many findings**: P0 (errors in shared components or critical paths) → P1 (other errors, mechanical first) → P2 review → P3 polish, each cluster with its fix recipe. Never gates (exit 0). `--json` = `fringe/plan.v1`. |
 | `fringe explain [FR-203]` | Why a rule matters, the preferred fix and the tempting fix to avoid. No id lists all 36 rules. |
 | `fringe explain pattern [form]` | Build-time best-practice checklist for a component type (`form`, `modal`, `navigation`, `data-view`); each item is marked *verified* (a rule checks it) or *judged*. |
@@ -60,6 +61,19 @@ When a baseline or inline suppressions are in play, the last line adds `· N bas
 
 Each finding costs its weight (default error 10, review 3, signal 1). The total is scaled to a 10-file baseline (`× 10 / max(files, 10)`), so repo size doesn't flatten the score. Score = `100 − penalty` up to a penalty of 75; beyond that it decays smoothly (`25·75/penalty`) and never pins at 0. Repos under 10 files score exactly `100 − total`. Weights live in `fringe.config.json`.
 
+## Runtime scan (`fringe scan`)
+
+Static checks read source; `scan` looks at the page as a browser renders it, so it can see real colors (a CSS variable, a theme, text over an image), the names a browser actually computes, and how the keyboard behaves.
+
+```sh
+npm i -D playwright-core axe-core      # once, in the project being scanned (not installed by default)
+npx @fringetools/cli scan http://localhost:3000
+```
+
+What it reports: every axe-core WCAG 2.0 to 2.2 A/AA violation, one finding per element (`FR-400`, WCAG criterion attached), and a Tab walk (`FR-401`): focus that keeps landing on one element is a *keyboard trap*; interactive elements Tab never reaches are listed. Radio buttons (reached by arrow keys) and hidden controls are excluded.
+
+Example: on a real project page the static check reported no findings and `scan` reported 17 color-contrast errors. Limits, plainly: it scans one URL in its initial state (no login, no opening of menus or modals yet); it needs the page running; findings have no source line (they carry a CSS selector); automated checks only find part of the real problems. It does not feed `plan`, baseline or suppression yet, and is not part of the edit hook (it needs a running app and takes seconds).
+
 ## Priority, clusters and fix plans
 
 Every finding in `--json` carries `priority`, `cluster` and `fixability`, and the result has a `clusters` list. A cluster is one rule in one file: usually one root cause and one fix.

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-TNZKMKKQ.js";
+} from "./chunk-5RPXF7S7.js";
 
 // src/bin.ts
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/{chunk-TNZKMKKQ.js → chunk-5RPXF7S7.js}

@@ -1,10 +1,10 @@
 // src/index.ts
 import { randomUUID } from "crypto";
 import { existsSync as existsSync3, readFileSync as readFileSync9, statSync } from "fs";
-import { dirname as dirname2, join as join9, resolve } from "path";
+import { dirname as dirname2, join as join10, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.2.2";
+var VERSION = "0.3.0";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -1598,15 +1598,94 @@ function receipts(root, findings) {
   return { introduced, fixed: [...left.values()].reduce((a, b) => a + b, 0) };
 }
 
+// src/scan.ts
+import { createRequire } from "module";
+import { join as join8 } from "path";
+var SCAN_HELP = "fringe scan needs two optional packages in your project: npm i -D playwright-core axe-core (it uses your installed Google Chrome; otherwise run npx playwright-core install chromium)";
+var WCAG_TAG = /^wcag(\d)(\d)(\d+)$/;
+var FOCUSABLE = 'a[href], button, input:not([type=hidden]):not([type=radio]), select, textarea, summary, [tabindex]:not([tabindex="-1"])';
+var at = (url) => ({ file: url, line: 1, col: 0 });
+function axeToFindings(url, violations) {
+  return violations.flatMap((v) => {
+    const tag2 = v.tags.map((t) => WCAG_TAG.exec(t)).find(Boolean);
+    const wcag = tag2 ? `${tag2[1]}.${tag2[2]}.${tag2[3]}` : void 0;
+    const severity = v.impact === "critical" || v.impact === "serious" ? "error" : "review";
+    return v.nodes.map((n) => ({
+      rule: "FR-400",
+      severity,
+      message: `${v.id} at ${n.target.join(" ")}: ${v.help}`,
+      hint: `${(n.failureSummary ?? "").split("\n").slice(1, 2).join("").trim() || v.help} (${v.helpUrl})`,
+      loc: at(url),
+      ...wcag ? { wcag } : {}
+    }));
+  });
+}
+function tabWalkFindings(url, focusables, visits) {
+  const out = [];
+  let run = 1;
+  for (let i = 1; i < visits.length; i++) {
+    run = visits[i] !== null && visits[i] === visits[i - 1] ? run + 1 : 1;
+    if (run === 4) out.push({ rule: "FR-401", severity: "error", message: `keyboard trap: Tab keeps landing on ${visits[i]}`, hint: "let focus move on (Tab or Escape must leave), and trap it only inside an open modal dialog", loc: at(url), wcag: "2.1.2" });
+  }
+  const reached = new Set(visits.filter(Boolean));
+  const missed = focusables.filter((f) => !reached.has(f));
+  if (missed.length > 0)
+    out.push({ rule: "FR-401", severity: "review", message: `${missed.length} interactive element(s) were not reached with Tab: ${missed.slice(0, 5).join(", ")}${missed.length > 5 ? ", \u2026" : ""}`, hint: "make sure each control is a real button/link/input or has tabIndex={0}; hidden-until-hover controls also land here", loc: at(url), wcag: "2.1.1" });
+  return out;
+}
+async function scan(url, cwd = process.cwd()) {
+  if (!/^(https?|file):\/\//i.test(url)) throw new Error(`fringe scan takes an http(s):// or file:// URL, got '${url}'`);
+  const req = createRequire(join8(cwd, "noop.js"));
+  let playwright, axePath;
+  try {
+    playwright = req("playwright-core");
+    axePath = req.resolve("axe-core/axe.min.js");
+  } catch {
+    throw new Error(SCAN_HELP);
+  }
+  let browser;
+  try {
+    browser = await playwright.chromium.launch({ channel: "chrome" });
+  } catch {
+    try {
+      browser = await playwright.chromium.launch();
+    } catch {
+      throw new Error(SCAN_HELP);
+    }
+  }
+  try {
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: "load", timeout: 3e4 });
+    await page.addScriptTag({ path: axePath });
+    const axeRes = await page.evaluate(() => globalThis.axe.run(document, { runOnly: { type: "tag", values: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"] } }));
+    const describe = `(el) => { const i = [...document.querySelectorAll(${JSON.stringify(FOCUSABLE)})].indexOf(el); return i < 0 ? null : el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + '[' + i + ']'; }`;
+    const focusables = await page.evaluate(`[...document.querySelectorAll(${JSON.stringify(FOCUSABLE)})].filter((el) => { const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.visibility !== 'hidden' && !el.disabled; }).map((el, _i, all) => (${describe})(el))`);
+    const visits = [];
+    for (let i = 0; i < focusables.length + 6; i++) {
+      await page.keyboard.press("Tab");
+      await page.waitForTimeout(40);
+      const now = await page.evaluate(`(${describe})(document.activeElement)`);
+      if (now === null && visits.length > 0) break;
+      visits.push(now);
+    }
+    const findings = [...axeToFindings(url, axeRes.violations), ...tabWalkFindings(url, focusables, visits)];
+    const counts = { error: 0, review: 0, signal: 0 };
+    for (const f of findings) counts[f.severity]++;
+    return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files: 1, skipped: [], findings, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1) };
+  } finally {
+    await browser.close();
+  }
+}
+
 // src/init.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync3, writeFileSync as writeFileSync3, copyFileSync } from "fs";
-import { dirname, join as join8 } from "path";
+import { dirname, join as join9 } from "path";
 import { fileURLToPath } from "url";
 var HOOK = "npx -y @fringetools/cli check --claude-hook";
 var SKILL_DIR = fileURLToPath(new URL("../skill/", import.meta.url));
 function initProject(root) {
   const done = [];
-  const settingsPath = join8(root, ".claude", "settings.json");
+  const settingsPath = join9(root, ".claude", "settings.json");
   let settings = {};
   if (existsSync2(settingsPath)) {
     try {
@@ -1624,11 +1703,11 @@ function initProject(root) {
     done.push(`hook added to ${settingsPath}`);
   }
   for (const name of readdirSync3(SKILL_DIR)) {
-    const skillPath = join8(root, ".claude", "skills", name, "SKILL.md");
+    const skillPath = join9(root, ".claude", "skills", name, "SKILL.md");
     if (existsSync2(skillPath)) done.push(`skill ${name} already present`);
     else {
       mkdirSync3(dirname(skillPath), { recursive: true });
-      copyFileSync(join8(SKILL_DIR, name, "SKILL.md"), skillPath);
+      copyFileSync(join9(SKILL_DIR, name, "SKILL.md"), skillPath);
       done.push(`skill ${name} installed`);
     }
   }
@@ -1785,7 +1864,7 @@ function resolveTarget(arg) {
   if (!statSync(arg).isFile()) return { root: arg };
   let dir = dirname2(arg);
   for (let d = dir, i = 0; i < 12; i++, d = dirname2(d)) {
-    if (existsSync3(join9(d, "package.json")) || existsSync3(join9(d, "fringe.config.json"))) {
+    if (existsSync3(join10(d, "package.json")) || existsSync3(join10(d, "fringe.config.json"))) {
       dir = d;
       break;
     }
@@ -1797,6 +1876,7 @@ var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\
 var HELP = `fringe check [--json] [--hook] [--record] [--manifest <path>] [path]
 fringe check --claude-hook [path]       for Claude Code hooks (feeds errors back to the agent)
 fringe check --update-baseline [path]   accept today's findings; only new ones gate
+fringe scan <url> [--json]               runtime check in a real browser (axe-core + keyboard walk); needs playwright-core and axe-core
 fringe plan [dir|file] [--json] [--limit n]   ordered fix batches with recipes
 fringe explain pattern [form]           best-practice checklist for a component type
 fringe explain [FR-203]                 why a rule matters and how to fix it well
@@ -1867,6 +1947,22 @@ async function runCli(argv, opts = {}) {
       return result.counts.error > 0 ? 1 : 0;
     } catch (e) {
       err(opts)(`fringe: internal error: ${e.message}
+`);
+      return 2;
+    }
+  }
+  if (cmd === "scan") {
+    try {
+      const url = rest.find((a) => !a.startsWith("--"));
+      if (!url) {
+        err(opts)("fringe: scan needs a URL, e.g. fringe scan http://localhost:3000\n");
+        return 2;
+      }
+      const result = await scan(url, opts.cwd ?? process.cwd());
+      log(opts)(rest.includes("--json") ? toJson(result) : toPretty(result));
+      return result.counts.error > 0 ? 1 : 0;
+    } catch (e) {
+      err(opts)(`fringe: ${e.message}
 `);
       return 2;
     }

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-TNZKMKKQ.js";
+} from "./chunk-5RPXF7S7.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -20,6 +20,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "axe-core": "^4.14.0",
+    "playwright-core": "^1.64.1",
     "tsup": "^8.0.0",
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
@@ -49,5 +51,17 @@
   "homepage": "https://github.com/skc-learn/fringe#readme",
   "bugs": {
     "url": "https://github.com/skc-learn/fringe/issues"
+  },
+  "peerDependencies": {
+    "playwright-core": ">=1.40",
+    "axe-core": ">=4.8"
+  },
+  "peerDependenciesMeta": {
+    "playwright-core": {
+      "optional": true
+    },
+    "axe-core": {
+      "optional": true
+    }
   }
 }

package/skill/fringe-help/SKILL.md

@@ -24,6 +24,7 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `check [dir]` | Scan and print findings and the health score; exit 1 on any error |
 | `check --json` / `--hook` / `--claude-hook` | Machine output; CI gate; agent feedback form |
 | `check --update-baseline` | Accept today's findings; only new ones gate |
+| `scan <url>` | Runtime check of a live page: real contrast, keyboard walk (needs `playwright-core` + `axe-core`) |
 | `plan [dir\|file]` | Ordered fix batches (shared components first) with recipes |
 | `explain [FR-203]` | Why a rule matters and how to fix it well |
 | `check --record [--manifest f]` | Append the run to `.fringe/ledger.jsonl` |