@fringetools/cli 0.3.0 → 0.3.1

package/README.md

@@ -23,7 +23,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 |---|---|
 | `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 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*. |
 | `fringe check --json` | Full report as JSON, schema `fringe/check.v1` (stack, files, findings, counts, score). |
@@ -72,7 +72,7 @@ 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).
+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).
 
 ## Priority, clusters and fix plans
 

package/dist/bin.js

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

package/dist/{chunk-5RPXF7S7.js → chunk-P5N5ETBT.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.0";
+var VERSION = "0.3.1";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -1346,6 +1346,7 @@ var WCAG_A = /* @__PURE__ */ new Set(["1.1.1", "1.3.1", "2.1.1", "2.4.3", "3.3.2
 var WCAG_AA = /* @__PURE__ */ new Set(["1.4.3", "2.4.7", "2.5.8"]);
 var CRITICAL_BONUS = 40;
 var SHARED_FROM = 3;
+var wcagBonus = (wcag) => wcag && WCAG_A.has(wcag) ? 30 : wcag && WCAG_AA.has(wcag) ? 15 : 0;
 var IMPORT = /(?:from\s+|import\s*\(\s*|require\(\s*)['"]([^'"]+)['"]/g;
 function importerCounts(sources) {
   const counts = /* @__PURE__ */ new Map();
@@ -1610,14 +1611,19 @@ function axeToFindings(url, violations) {
     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 } : {}
-    }));
+    return v.nodes.map((n) => {
+      const detail = (n.failureSummary ?? "").split("\n").slice(1, 2).join("").trim() || v.help;
+      return {
+        rule: "FR-400",
+        severity,
+        target: n.target.join(" "),
+        cluster: `${v.id}@${url}`,
+        message: `${v.id} at ${n.target.join(" ")}: ${detail}`,
+        hint: `${v.help} (${v.helpUrl})`,
+        loc: at(url),
+        ...wcag ? { wcag } : {}
+      };
+    });
   });
 }
 function tabWalkFindings(url, focusables, visits) {
@@ -1668,14 +1674,32 @@ async function scan(url, cwd = process.cwd()) {
       if (now === null && visits.length > 0) break;
       visits.push(now);
     }
-    const findings = [...axeToFindings(url, axeRes.violations), ...tabWalkFindings(url, focusables, visits)];
+    const { findings, clusters } = rankScan(url, [...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) };
+    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) };
   } finally {
     await browser.close();
   }
 }
+function rankScan(url, findings) {
+  const clusters = /* @__PURE__ */ new Map();
+  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 };
+    c.count++;
+    c.priority = Math.max(c.priority, priority);
+    clusters.set(id, c);
+    return { ...f, priority, cluster: id, fixability: c.fixability };
+  });
+  for (const c of clusters.values()) c.priority += Math.round(Math.min(15, 3 * Math.log2(c.count)));
+  return { findings: ranked, clusters: [...clusters.values()] };
+}
+function mergeScan(base, scanned, weights) {
+  const counts = { error: base.counts.error + scanned.counts.error, review: base.counts.review + scanned.counts.review, signal: base.counts.signal + scanned.counts.signal };
+  return { ...base, findings: [...base.findings, ...scanned.findings], clusters: [...base.clusters ?? [], ...scanned.clusters ?? []].sort((a, b) => b.priority - a.priority), counts, score: score(counts, weights, base.files) };
+}
 
 // src/init.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync3, writeFileSync as writeFileSync3, copyFileSync } from "fs";
@@ -1779,10 +1803,14 @@ var TITLES = {
   P3: ["Polish", "advice only; never blocks"]
 };
 function buildPlan(r, limit = 15) {
-  const lines = /* @__PURE__ */ new Map();
-  for (const f of r.findings) if (f.cluster) lines.set(f.cluster, [...lines.get(f.cluster) ?? [], f.loc.line]);
+  const lines = /* @__PURE__ */ new Map(), targets = /* @__PURE__ */ new Map(), hints = /* @__PURE__ */ new Map();
+  for (const f of r.findings) if (f.cluster) {
+    if (f.target) targets.set(f.cluster, [...targets.get(f.cluster) ?? [], f.target]);
+    else lines.set(f.cluster, [...lines.get(f.cluster) ?? [], f.loc.line]);
+    if (!hints.has(f.cluster)) hints.set(f.cluster, f.hint);
+  }
   const sev = new Map(r.findings.map((f) => [f.cluster, f.severity]));
-  const items = (r.clusters ?? []).map((c) => ({ ...c, lines: lines.get(c.id) ?? [], recipe: GUIDANCE[c.rule]?.recipe, avoid: GUIDANCE[c.rule]?.avoid }));
+  const items = (r.clusters ?? []).map((c) => ({ ...c, lines: lines.get(c.id) ?? [], targets: targets.get(c.id) ?? [], recipe: GUIDANCE[c.rule]?.recipe ?? hints.get(c.id), avoid: GUIDANCE[c.rule]?.avoid }));
   const mechFirst = (a, b) => (a.fixability === b.fixability ? 0 : a.fixability === "mechanical" ? -1 : 1) || b.priority - a.priority;
   const pick = (id) => items.filter((c) => {
     const s = sev.get(c.id);
@@ -1816,8 +1844,10 @@ _${b.why}_`);
       const tags = [c.rootCause === "shared component" ? `shared component, imported by ${c.importedBy} files` : "", c.critical ? "critical path" : "", `${c.fixability} fix`].filter(Boolean);
       out.push(`
 ### ${c.rule} \xB7 \xD7${c.count} \xB7 ${c.file} (${tags.join("; ")})`);
-      out.push(`Lines: ${c.lines.slice(0, 8).join(", ")}${c.lines.length > 8 ? ", \u2026" : ""}`);
-      if (c.recipe && !shown.has(c.rule)) {
+      out.push(c.targets.length ? `Elements: ${c.targets.slice(0, 4).join(" | ")}${c.targets.length > 4 ? " | \u2026" : ""}` : `Lines: ${c.lines.slice(0, 8).join(", ")}${c.lines.length > 8 ? ", \u2026" : ""}`);
+      if (c.rule.startsWith("FR-4")) {
+        if (c.recipe) out.push(`Fix: ${c.recipe}`);
+      } else if (c.recipe && !shown.has(c.rule)) {
         shown.add(c.rule);
         out.push(`Fix: ${c.recipe}${c.avoid ? `
 Avoid: ${c.avoid}` : ""}`);
@@ -1877,7 +1907,7 @@ 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 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
 fringe init [path]                       add the Claude Code hook + skill
@@ -1969,12 +1999,20 @@ async function runCli(argv, opts = {}) {
   }
   if (cmd === "plan") {
     try {
+      const si = rest.indexOf("--scan");
+      const scanUrl = si !== -1 ? rest[si + 1] : void 0;
+      if (si !== -1 && (!scanUrl || scanUrl.startsWith("--"))) {
+        err(opts)("fringe: --scan needs a URL, e.g. fringe plan --scan http://localhost:3000\n");
+        return 2;
+      }
       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"), err(opts));
+      const paths = parseArgs(rest.filter((a, i) => a !== "--limit" && rest[i - 1] !== "--limit" && a !== "--json" && a !== "--scan" && rest[i - 1] !== "--scan"), err(opts));
       const arg = resolve(opts.cwd ?? process.cwd(), paths[0] ?? ".");
       const { root, only } = resolveTarget(arg);
-      const result = await runCheck(root, loadConfig(root), true, only);
+      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);
       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-5RPXF7S7.js";
+} from "./chunk-P5N5ETBT.js";
 export {
   runCli
 };

package/package.json

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

package/skill/fringe-help/SKILL.md

@@ -25,7 +25,7 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `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 |
+| `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` |
 | `init` | Add the hook and install the skills |