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 +25 -3
- package/browse/compare.mjs +3 -0
- package/browse/findings.mjs +4 -0
- package/browse/report.mjs +39 -3
- package/browse/score.mjs +46 -0
- package/package.json +2 -2
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
|
|
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);
|
package/browse/compare.mjs
CHANGED
|
@@ -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,
|
package/browse/findings.mjs
CHANGED
|
@@ -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) => ({ "&": "&", "<": "<", ">": ">", '"': """, "'": "'" })[c]);
|
|
16
17
|
|
|
@@ -96,12 +97,38 @@ function card(f, page) {
|
|
|
96
97
|
</article>`;
|
|
97
98
|
}
|
|
98
99
|
|
|
99
|
-
|
|
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
|
|
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
|
-
${
|
|
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>
|
package/browse/score.mjs
ADDED
|
@@ -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.
|
|
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.
|
|
41
|
+
"trykeyline": "0.3.0"
|
|
42
42
|
},
|
|
43
43
|
"peerDependencies": {
|
|
44
44
|
"playwright": "^1.40.0"
|