@fringetools/cli 0.3.1 → 0.4.0

package/README.md

@@ -22,7 +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 scan <url> [--states file] [--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] [--scan url] [--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). `--scan <url>` adds the live page's runtime findings to the same plan (one cluster per axe rule, with element selectors). `--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*. |
@@ -72,7 +72,22 @@ 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. `fringe plan --scan <url>` merges it with the static findings into one fix order. It does not feed the baseline or `fringe-ignore` yet, and is not part of the edit hook (it needs a running app and takes seconds).
+Example: on a real project page the static check reported no findings and `scan` reported 17 color-contrast errors. ### States: audit what only exists after a click
+
+Most real problems live in states the first load never shows: an open menu, a modal, a form after a failed submit. Describe them in `fringe.scan.json` (found in the current directory, or pass `--states <file>`):
+
+```json
+{
+  "states": [
+    { "name": "filters open", "steps": [ { "click": "#open-filters" } ] },
+    { "name": "bad login",    "steps": [ { "fill": "#email", "value": "nobody@example.com" }, { "fill": "#password", "value": "wrong" }, { "click": "text=Sign in" }, { "waitFor": "[role=alert]" } ] }
+  ]
+}
+```
+
+For each state Fringe reloads the page, runs the steps, then audits the result (axe-core and the Tab walk). Steps are exactly one of `click`, `fill` (with `value`), `press`, `hover`, `waitFor`, `goto`; selectors are [Playwright selectors](https://playwright.dev/docs/other-locators) (CSS, `text=...`, `role=...`). Findings are labelled `[filters open]` and cluster separately from the same rule on the initial page. A step that fails (selector not found) is reported as `FR-402` ("state could not be reached") and nothing in that state is audited. Use throw-away test data in `fill` values and do not commit real credentials. `plan --scan` uses the same file.
+
+Limits, plainly: states are independent (each starts from a fresh load of the URL, so there are no multi-page flows that depend on earlier state beyond `goto`); it needs the page running; findings have no source line (they carry a CSS selector); automated checks only find part of the real problems. `fringe plan --scan <url>` merges it with the static findings into one fix order. It does not feed the baseline or `fringe-ignore` yet, and is not part of the edit hook (it needs a running app and takes seconds).
 
 ## Priority, clusters and fix plans
 

package/dist/bin.js

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

package/dist/{chunk-P5N5ETBT.js → chunk-JSWDIPHX.js}

@@ -4,7 +4,7 @@ import { existsSync as existsSync3, readFileSync as readFileSync9, statSync } fr
 import { dirname as dirname2, join as join10, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.3.1";
+var VERSION = "0.4.0";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -1639,7 +1639,51 @@ function tabWalkFindings(url, focusables, visits) {
     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()) {
+var STEP_KEYS = ["click", "fill", "press", "hover", "waitFor", "goto"];
+function parseStates(json) {
+  const bad = (m) => {
+    throw new Error(`fringe.scan.json: ${m}`);
+  };
+  const states = json?.states;
+  if (!Array.isArray(states)) return bad('expected { "states": [ ... ] }');
+  return states.map((s, i) => {
+    if (typeof s?.name !== "string" || !s.name.trim()) bad(`states[${i}] needs a "name"`);
+    if (!Array.isArray(s.steps) || s.steps.length === 0) bad(`state "${s.name}" needs a non-empty "steps" list`);
+    for (const [k, step] of s.steps.entries()) {
+      const keys = STEP_KEYS.filter((x) => step && typeof step === "object" && x in step);
+      if (keys.length !== 1 || typeof step[keys[0]] !== "string") bad(`state "${s.name}" step ${k + 1} must be exactly one of ${STEP_KEYS.join(", ")} with a string value`);
+      if (keys[0] === "fill" && typeof step.value !== "string") bad(`state "${s.name}" step ${k + 1}: fill needs a "value"`);
+    }
+    return { name: s.name.trim(), steps: s.steps };
+  });
+}
+async function runStep(page, step, base) {
+  const t = { timeout: 1e4 };
+  if ("click" in step) await page.click(step.click, t);
+  else if ("fill" in step) await page.fill(step.fill, step.value, t);
+  else if ("press" in step) await page.keyboard.press(step.press);
+  else if ("hover" in step) await page.hover(step.hover, t);
+  else if ("waitFor" in step) await page.waitForSelector(step.waitFor, t);
+  else await page.goto(new URL(step.goto, base).href, { waitUntil: "load", timeout: 3e4 });
+  await page.waitForTimeout(150);
+}
+async function audit(page, axePath, url) {
+  if (!await page.evaluate(() => !!globalThis.axe)) 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);
+  }
+  return [...axeToFindings(url, axeRes.violations), ...tabWalkFindings(url, focusables, visits)];
+}
+var inState = (name, url, f) => ({ ...f, message: `[${name}] ${f.message}`, loc: { ...f.loc, file: `${url} [${name}]` }, ...f.cluster ? { cluster: `${f.cluster} [${name}]` } : {} });
+async function scan(url, cwd = process.cwd(), states = []) {
   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;
@@ -1662,22 +1706,22 @@ async function scan(url, cwd = process.cwd()) {
   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 all = await audit(page, axePath, url);
+    for (const st of states) {
+      await page.goto(url, { waitUntil: "load", timeout: 3e4 });
+      let step = 0;
+      try {
+        for (; step < st.steps.length; step++) await runStep(page, st.steps[step], url);
+      } catch (e) {
+        all.push({ rule: "FR-402", severity: "review", message: `[${st.name}] state could not be reached: step ${step + 1} ${JSON.stringify(st.steps[step])} failed (${String(e.message).split("\n")[0].slice(0, 120)})`, hint: "fix the step in fringe.scan.json or the page; nothing in this state was audited", loc: { file: `${url} [${st.name}]`, line: 1, col: 0 } });
+        continue;
+      }
+      all.push(...(await audit(page, axePath, url)).map((f) => inState(st.name, url, f)));
     }
-    const { findings, clusters } = rankScan(url, [...axeToFindings(url, axeRes.violations), ...tabWalkFindings(url, focusables, visits)]);
+    const { findings, clusters } = rankScan(url, all);
     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, clusters, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1) };
+    return { stack: { jsx: false, tailwind: false, vue: false, svelte: false, html: true }, files: 1 + states.length, skipped: [], findings, clusters, counts, score: score(counts, { error: 10, review: 3, signal: 1 }, 1) };
   } finally {
     await browser.close();
   }
@@ -1687,7 +1731,7 @@ function rankScan(url, findings) {
   const ranked = findings.map((f) => {
     const priority = Math.round(TIER[f.severity] + wcagBonus(f.wcag));
     const id = f.cluster ?? `${f.rule}@${url}`;
-    const c = clusters.get(id) ?? { id, rule: f.rule, file: url, count: 0, priority: 0, fixability: "judgment", rootCause: "local", importedBy: 0, critical: false };
+    const c = clusters.get(id) ?? { id, rule: f.rule, file: f.loc.file, count: 0, priority: 0, fixability: "judgment", rootCause: "local", importedBy: 0, critical: false };
     c.count++;
     c.priority = Math.max(c.priority, priority);
     clusters.set(id, c);
@@ -1902,11 +1946,23 @@ function resolveTarget(arg) {
   }
   return { root: dir, only: /* @__PURE__ */ new Set([arg]) };
 }
+function loadStates(cwd, rest) {
+  const i = rest.indexOf("--states");
+  const file2 = i !== -1 ? resolve(cwd, rest[i + 1] ?? "") : join10(cwd, "fringe.scan.json");
+  if (i === -1 && !existsSync3(file2)) return [];
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync9(file2, "utf8"));
+  } catch (e) {
+    throw new Error(`${file2}: ${e.message}`);
+  }
+  return parseStates(raw);
+}
 var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\/?a|none|tbd|obvious|unnecessary|clutter|unused)\.?$/i.test(e.trim());
 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 scan <url> [--states f] [--json]               runtime check in a real browser (axe-core + keyboard walk); needs playwright-core and axe-core
 fringe plan [dir|file] [--scan url] [--json] [--limit n]   ordered fix batches with recipes; --scan adds the live page
 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
@@ -1983,12 +2039,13 @@ async function runCli(argv, opts = {}) {
   }
   if (cmd === "scan") {
     try {
-      const url = rest.find((a) => !a.startsWith("--"));
+      const url = rest.find((a, i) => !a.startsWith("--") && rest[i - 1] !== "--states");
       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());
+      const cwd = opts.cwd ?? process.cwd();
+      const result = await scan(url, cwd, loadStates(cwd, rest));
       log(opts)(rest.includes("--json") ? toJson(result) : toPretty(result));
       return result.counts.error > 0 ? 1 : 0;
     } catch (e) {
@@ -2007,12 +2064,15 @@ async function runCli(argv, opts = {}) {
       }
       const li = rest.indexOf("--limit");
       const limit = li !== -1 ? Number(rest[li + 1]) || void 0 : void 0;
-      const paths = parseArgs(rest.filter((a, i) => a !== "--limit" && rest[i - 1] !== "--limit" && a !== "--json" && a !== "--scan" && rest[i - 1] !== "--scan"), err(opts));
+      const paths = parseArgs(rest.filter((a, i) => a !== "--limit" && rest[i - 1] !== "--limit" && a !== "--json" && a !== "--scan" && rest[i - 1] !== "--scan" && a !== "--states" && rest[i - 1] !== "--states"), err(opts));
       const arg = resolve(opts.cwd ?? process.cwd(), paths[0] ?? ".");
       const { root, only } = resolveTarget(arg);
       const cfg = loadConfig(root);
       let result = await runCheck(root, cfg, true, only);
-      if (scanUrl) result = mergeScan(result, await scan(scanUrl, opts.cwd ?? process.cwd()), cfg.weights);
+      if (scanUrl) {
+        const cwd = opts.cwd ?? process.cwd();
+        result = mergeScan(result, await scan(scanUrl, cwd, loadStates(cwd, rest)), cfg.weights);
+      }
       log(opts)(rest.includes("--json") ? toPlanJson(result, limit) : toPlanMarkdown(result, paths[0] ?? ".", limit));
       return 0;
     } catch (e) {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-P5N5ETBT.js";
+} from "./chunk-JSWDIPHX.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "bin": {

package/skill/fringe-help/SKILL.md

@@ -24,7 +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`) |
+| `scan <url>` | Runtime check of a live page: real contrast, keyboard walk, and named states from `fringe.scan.json` (needs `playwright-core` + `axe-core`) |
 | `plan [dir\|file] [--scan url]` | Ordered fix batches (shared components first) with recipes; `--scan` adds the live page |
 | `explain [FR-203]` | Why a rule matters and how to fix it well |
 | `check --record [--manifest f]` | Append the run to `.fringe/ledger.jsonl` |