trykeyline-browser 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/audit.mjs CHANGED
@@ -2,8 +2,8 @@
2
2
  * The audit's machine half: walk every page of a running product at desktop
3
3
  * and phone, light and dark; measure contrast, names, targets, overflow, the
4
4
  * type actually rendered, copy and the tells of AI slop inside each page; add
5
- * the detector's findings from the source; draft a score per domain; write
6
- * keyline-report/ (findings.json, index.html, shots/).
5
+ * the detector's findings from the source; draft a score per domain and one
6
+ * out of 10; write keyline-report/ (findings.json, index.html, shots/).
7
7
  *
8
8
  * The agent's half follows (commands/audit.md): look at the shots, add the
9
9
  * findings only judgement can make, settle the scores, write the summary, and
@@ -17,9 +17,10 @@
17
17
  */
18
18
  import { existsSync, rmSync } from "node:fs";
19
19
  import { resolve } from "node:path";
20
- import { add, counts, writeRun } from "./browse/findings.mjs";
20
+ import { add, counts, readRun, writeRun } from "./browse/findings.mjs";
21
21
  import { shotKey } from "./browse/capture.mjs";
22
22
  import { renderDir } from "./browse/report.mjs";
23
+ import { SHIP, draftScore, scoreCaps } from "./browse/score.mjs";
23
24
  import { walk } from "./browse/walk.mjs";
24
25
  import { parseOrExplain } from "./browse/args.mjs";
25
26
  import { target } from "./browse.mjs";
@@ -47,6 +48,7 @@ Options:
47
48
 
48
49
  /** The six law domains the scores are kept for, and where the audit's own rules fall among them. */
49
50
  export const SCORED = DOMAINS;
51
+ export { SHIP, draftScore, scoreCaps };
50
52
  const SCORE_DOMAIN = {
51
53
  a11y: "patterns",
52
54
  copy: "patterns",
@@ -102,6 +104,24 @@ export function draftScores(findings) {
102
104
  return scores;
103
105
  }
104
106
 
107
+ /**
108
+ * The scores of earlier runs in the same folder over the same pages, oldest
109
+ * first, so a polish loop shows its progress (6 → 7.5 → 8.5). A run over other
110
+ * pages starts a new history.
111
+ */
112
+ export function carryHistory(out, routes) {
113
+ let prev;
114
+ try {
115
+ prev = readRun(out);
116
+ } catch {
117
+ return [];
118
+ }
119
+ if (prev.kind !== "audit" || typeof prev.score !== "number") return [];
120
+ const same = (a, b) => a.length === b.length && a.every((r, i) => r === b[i]);
121
+ if (!same([...(prev.pages ?? [])].map((p) => p.route).sort(), [...routes].sort())) return [];
122
+ return [...(prev.history ?? []), prev.score];
123
+ }
124
+
105
125
  /** The detector's findings, as report findings pointing at source lines. Its walk already skips reports, dependencies and build output. */
106
126
  export function sourceFindings(run, root, ignores = []) {
107
127
  const result = check({ root, paths: ["."], ignores });
@@ -197,6 +217,8 @@ export async function run(argv) {
197
217
 
198
218
  if (!opts["no-check"] && t.root && existsSync(t.root)) sourceFindings(result, t.root);
199
219
  result.scores = draftScores(result.findings);
220
+ result.score = draftScore(result.scores, result.findings);
221
+ result.history = carryHistory(out, result.pages.map((p) => p.route));
200
222
  result.scoresDraft = true;
201
223
  writeRun(out, result);
202
224
  const file = renderDir(out);
@@ -68,6 +68,9 @@ export function compareRuns(run, prev, { against = null } = {}) {
68
68
  };
69
69
  run.fixed = left.filter(seen).map(({ change, previous, ...f }, i) => ({ ...f, previous: f.id, id: `x${i + 1}`, change: "fixed" }));
70
70
 
71
+ // An audit compared with an earlier audit carries its score trail, so a polish loop shows its progress.
72
+ if (run.kind === "audit" && prev.kind === "audit" && typeof prev.score === "number") run.history = [...(prev.history ?? []), prev.score];
73
+
71
74
  const count = (c) => run.findings.filter((f) => f.change === c).length;
72
75
  run.compare = {
73
76
  against,
@@ -15,6 +15,8 @@
15
15
  * "title": "Lumen", "base": "http://localhost:3000", "root": "/abs/project",
16
16
  * "started": ISO, "finished": ISO,
17
17
  * "scores": { "type": 3, … } | null, // 0–4 per domain, audit only
18
+ * "score": 7.5 | null, // out of 10, audit only; 8 is ready to ship (score.mjs)
19
+ * "history": [6, 7], // earlier runs' scores over the same pages, oldest first
18
20
  * "summary": "one paragraph a person reads first" | null,
19
21
  * "pages": [ { "route": "/settings", "url": …, "title": …, "status": 200,
20
22
  * "shots": { "desktop-light": { "path": "shots/…png", "width": 1440, "height": 3120 } } } ],
@@ -67,6 +69,8 @@ export function newRun({ kind, title = null, base = null, root = null }) {
67
69
  started: new Date().toISOString(),
68
70
  finished: null,
69
71
  scores: null,
72
+ score: null,
73
+ history: [],
70
74
  summary: null,
71
75
  pages: [],
72
76
  findings: [],
package/browse/report.mjs CHANGED
@@ -11,6 +11,7 @@
11
11
  import { writeFileSync } from "node:fs";
12
12
  import { join } from "node:path";
13
13
  import { counts, readRun, sortFindings } from "./findings.mjs";
14
+ import { SHIP, scoreCaps } from "./score.mjs";
14
15
 
15
16
  const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
16
17
 
@@ -96,12 +97,38 @@ function card(f, page) {
96
97
  </article>`;
97
98
  }
98
99
 
99
- function scoreTable(scores, draft) {
100
+ /** What a score out of 10 means, in the words the audit's anchors use (commands/audit.md). */
101
+ export function scoreWord(n) {
102
+ if (n >= 9) return "Excellent";
103
+ if (n >= SHIP) return "Ready to ship";
104
+ if (n >= 7) return "Close to the bar";
105
+ if (n >= 5) return "Works, but a reader feels the faults";
106
+ if (n >= 3) return "Broken for someone";
107
+ return "Broken";
108
+ }
109
+
110
+ const fmt = (n) => (Number.isInteger(n) ? String(n) : n.toFixed(1));
111
+
112
+ /** The headline: the score out of 10, how it got here, and what holds it down. */
113
+ function headline(run) {
114
+ if (typeof run.score !== "number") return "";
115
+ const caps = scoreCaps(run.scores, run.findings);
116
+ const cap = caps.length ? caps[0].max : 10;
117
+ const trail = [...(run.history ?? []), run.score].map(fmt).join(" → ");
118
+ const over = run.score > cap ? `<p class="headline__warn">Settled above what the evidence allows: at most ${fmt(cap)} while ${esc(caps[0].why)}.</p>` : "";
119
+ const held = caps.length ? `<ul class="headline__caps">${caps.map((c) => `<li>At most ${fmt(c.max)}: ${esc(c.why)}</li>`).join("")}</ul>` : "";
120
+ return `<section class="block headline"><h2>Score${run.scoresDraft ? ` <small class="draft">drafted from the measurements; not yet reviewed</small>` : ""}</h2>
121
+ <p class="headline__score"><b>${esc(fmt(run.score))}</b><span>/10</span></p>
122
+ <p class="headline__word">${esc(scoreWord(run.score))} · the bar is ${SHIP}${run.history?.length ? ` · <span class="headline__trail">rounds ${esc(trail)}</span>` : ""}</p>
123
+ ${over}${held}</section>`;
124
+ }
125
+
126
+ function scoreTable(scores, draft, title = "Scores") {
100
127
  if (!scores) return "";
101
128
  const rows = Object.entries(scores)
102
129
  .map(([d, s]) => `<tr><th scope="row">${esc(DOMAIN_NAMES[d] ?? d)}</th><td><span class="meter" style="--v:${Number(s) / 4}"></span></td><td>${esc(s)}/4</td><td>${esc(SCORE_WORDS[s] ?? "")}</td></tr>`)
103
130
  .join("");
104
- return `<section class="block"><h2>Scores${draft ? ` <small class="draft">drafted from the measurements; not yet reviewed</small>` : ""}</h2><table class="scores"><tbody>${rows}</tbody></table></section>`;
131
+ return `<section class="block"><h2>${esc(title)}${draft ? ` <small class="draft">drafted from the measurements; not yet reviewed</small>` : ""}</h2><table class="scores"><tbody>${rows}</tbody></table></section>`;
105
132
  }
106
133
 
107
134
  function sinceSection(run) {
@@ -146,6 +173,14 @@ h2{margin:0 0 12px;font-size:16px;font-weight:500;letter-spacing:-.015em}
146
173
  .totals b{display:block;font-size:20px;font-weight:500;font-variant-numeric:tabular-nums}
147
174
  .totals span{font-size:13px;color:var(--faint)}
148
175
  .block{margin-top:48px}
176
+ .headline__score{margin:0;display:flex;align-items:baseline;gap:4px}
177
+ .headline__score b{font-size:48px;font-weight:500;letter-spacing:-.03em;line-height:1;font-variant-numeric:tabular-nums}
178
+ .headline__score span{font-size:20px;color:var(--faint)}
179
+ .headline__word{margin:8px 0 0;color:var(--muted);font-size:14px}
180
+ .headline__trail{font-variant-numeric:tabular-nums}
181
+ .headline__warn{margin:12px 0 0;font-size:14px;color:var(--err)}
182
+ .headline__caps{margin:12px 0 0;padding-left:20px;font-size:14px;color:var(--muted)}
183
+ .headline+.block{margin-top:24px}
149
184
  .scores{border-collapse:collapse;width:100%;font-size:14px}
150
185
  .scores th,.scores td{padding:8px 12px 8px 0;border-top:.5px solid var(--line);text-align:left;font-weight:400}
151
186
  .scores td:nth-child(3){font-variant-numeric:tabular-nums;color:var(--muted);width:4em}
@@ -242,7 +277,8 @@ export function render(run) {
242
277
  ${run.summary ? `<p class="summary">${esc(run.summary)}</p>` : ""}
243
278
  <ul class="totals"><li><b>${c.error}</b><span>Errors</span></li><li><b>${c.warning}</b><span>Warnings</span></li><li><b>${c.info}</b><span>Notes</span></li></ul>
244
279
  ${sinceSection(run)}
245
- ${scoreTable(run.scores, run.scoresDraft)}
280
+ ${headline(run)}
281
+ ${typeof run.score === "number" ? scoreTable(run.scores, false, "By area") : scoreTable(run.scores, run.scoresDraft)}
246
282
  <nav class="filters" aria-label="Filter findings">
247
283
  <select name="severity" aria-label="Severity">${option("", "Every severity")}${option("error", "Errors")}${option("warning", "Warnings")}${option("info", "Notes")}</select>
248
284
  <select name="domain" aria-label="Area">${option("", "Every area")}${domains.map((d) => option(d, DOMAIN_NAMES[d] ?? d)).join("")}</select>
@@ -0,0 +1,46 @@
1
+ /**
2
+ * The score out of 10: one number a person reads first, drafted from the six
3
+ * domain scores (0–4) and held under caps that come from evidence. The audit
4
+ * drafts it; the agent settles it (commands/audit.md); the report renders it
5
+ * and recomputes the caps, so a score settled above them shows as such.
6
+ */
7
+
8
+ /** The score out of 10 a product has to reach before it ships. */
9
+ export const SHIP = 8;
10
+
11
+ const NAMES = { type: "type", color: "colour", layout: "layout", depth: "depth", motion: "motion", patterns: "patterns" };
12
+ const named = (ds) => ds.map((d) => NAMES[d] ?? d).join(", ");
13
+
14
+ const isOpen = (f) => f.status !== "dismissed" && f.status !== "fixed";
15
+
16
+ /**
17
+ * What holds the score out of 10 down, whatever the judgement: each cap is
18
+ * evidence a reader would meet. The agent settling the score may go lower
19
+ * than the lowest cap, never higher.
20
+ */
21
+ export function scoreCaps(scores, findings) {
22
+ const caps = [];
23
+ const errors = findings.filter((f) => isOpen(f) && f.severity === "error").length;
24
+ if (errors) caps.push({ max: 6, why: `${errors} open ${errors === 1 ? "error" : "errors"}: broken for someone` });
25
+ const warnings = findings.filter((f) => isOpen(f) && f.severity === "warning").length;
26
+ if (warnings) caps.push({ max: 7, why: `${warnings} open ${warnings === 1 ? "warning" : "warnings"}: a law a reader feels` });
27
+ const at = (test) => Object.entries(scores ?? {}).filter(([, s]) => test(s)).map(([d]) => d);
28
+ const broken = at((s) => s <= 1);
29
+ if (broken.length) caps.push({ max: 5, why: `${named(broken)} not working as a system` });
30
+ const felt = at((s) => s === 2);
31
+ if (felt.length) caps.push({ max: 7, why: `a law a reader feels is broken in ${named(felt)}` });
32
+ return caps.sort((a, b) => a.max - b.max);
33
+ }
34
+
35
+ /**
36
+ * A draft score out of 10 from the domain scores: 2 + 2 × their mean, so all
37
+ * 4s is 10, all 3s is 8 (ready to ship), all 2s is 6. Then held under the
38
+ * caps, and rounded to the half point.
39
+ */
40
+ export function draftScore(scores, findings) {
41
+ const values = Object.values(scores ?? {});
42
+ if (!values.length) return null;
43
+ const mean = values.reduce((a, b) => a + b, 0) / values.length;
44
+ const capped = Math.min(2 + 2 * mean, ...scoreCaps(scores, findings).map((c) => c.max));
45
+ return Math.round(capped * 2) / 2;
46
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "trykeyline-browser",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "Keyline's browser tools: find a product's pages, walk them at desktop and phone in light and dark, and report what the audit and the smoke test find. Run through `npx trykeyline audit|smoke|pages|capture|report|probe`.",
5
5
  "keywords": [
6
6
  "design",
@@ -38,7 +38,7 @@
38
38
  "node": ">=18"
39
39
  },
40
40
  "dependencies": {
41
- "trykeyline": "0.2.0"
41
+ "trykeyline": "0.3.0"
42
42
  },
43
43
  "peerDependencies": {
44
44
  "playwright": "^1.40.0"