trykeyline-browser 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +14 -2
- package/audit/probe.mjs +390 -0
- package/audit.mjs +231 -0
- package/bin/trykeyline-browser.mjs +79 -0
- package/browse/args.mjs +44 -0
- package/browse/capture.mjs +181 -0
- package/browse/compare.mjs +263 -0
- package/browse/findings.mjs +129 -0
- package/browse/playwright.mjs +78 -0
- package/browse/report.mjs +301 -0
- package/browse/routes.mjs +252 -0
- package/browse/score.mjs +46 -0
- package/browse/serve.mjs +61 -0
- package/browse/walk.mjs +117 -0
- package/browse.mjs +175 -0
- package/package.json +53 -4
- package/probe.mjs +26 -0
- package/smoke/clicks.mjs +320 -0
- package/smoke/config.mjs +184 -0
- package/smoke/forms.mjs +329 -0
- package/smoke/keyboard.mjs +100 -0
- package/smoke/links.mjs +120 -0
- package/smoke/page.mjs +575 -0
- package/smoke/phone.mjs +126 -0
- package/smoke/shift.mjs +103 -0
- package/smoke/util.mjs +113 -0
- package/smoke.mjs +412 -0
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What changed since the last run: which findings are new, which are still
|
|
3
|
+
* there, which came back, which were fixed, and which pages look different.
|
|
4
|
+
*
|
|
5
|
+
* keyline report keyline-report --compare keyline-report-before
|
|
6
|
+
*
|
|
7
|
+
* Findings are matched on rule + page + viewport + theme + selector (the title
|
|
8
|
+
* when there's no selector) — the same key a run is de-duplicated on. Each
|
|
9
|
+
* finding in the current run gets `change`:
|
|
10
|
+
*
|
|
11
|
+
* "new" not in the previous run
|
|
12
|
+
* "still" in it too (a status a person set there — accepted, dismissed — carries over)
|
|
13
|
+
* "returned" not in the previous run, but in that run's own `fixed` list: fixed once, back now
|
|
14
|
+
*
|
|
15
|
+
* The previous run's findings with no match go under `fixed`, if the current
|
|
16
|
+
* run could have seen them again: their page was visited, at their viewport and
|
|
17
|
+
* theme. Pages left out of this run say nothing about what was fixed on them.
|
|
18
|
+
*
|
|
19
|
+
* Screenshots present in both runs are diffed pixel by pixel in the browser
|
|
20
|
+
* Playwright already drives (canvas, no image library), each diff written to
|
|
21
|
+
* `diffs/`. A page × viewport × theme whose changed share is above the
|
|
22
|
+
* threshold gets an info finding, `visual/changed`, boxed round what changed.
|
|
23
|
+
*/
|
|
24
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
25
|
+
import { dirname, join, relative } from "node:path";
|
|
26
|
+
import { split } from "trykeyline/check/findings";
|
|
27
|
+
import { readRun, writeRun } from "./findings.mjs";
|
|
28
|
+
import { shotKey } from "./capture.mjs";
|
|
29
|
+
|
|
30
|
+
/** The identity of a finding across runs. */
|
|
31
|
+
export function matchKey(f) {
|
|
32
|
+
return [f.rule, f.page ?? "", f.viewport ?? "", f.theme ?? "", f.selector ?? f.title].join("|");
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Findings that describe a comparison, not the product, never take part in one. */
|
|
36
|
+
const isVisual = (f) => f.rule?.startsWith("visual/");
|
|
37
|
+
|
|
38
|
+
/** Remove what an earlier compare wrote, so comparing twice gives the same answer. */
|
|
39
|
+
export function clearCompare(run) {
|
|
40
|
+
delete run.compare;
|
|
41
|
+
delete run.fixed;
|
|
42
|
+
run.findings = run.findings.filter((f) => !isVisual(f)).map(({ change, previous, diff, ...f }) => f);
|
|
43
|
+
for (const p of run.pages ?? []) delete p.diffs;
|
|
44
|
+
return run;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/** Mark `run`'s findings against `prev`. Mutates and returns `run`. */
|
|
48
|
+
export function compareRuns(run, prev, { against = null } = {}) {
|
|
49
|
+
const fixedBefore = new Set((prev.fixed ?? []).map(matchKey));
|
|
50
|
+
const { matched, left } = split(run.findings.filter((f) => !isVisual(f)), prev.findings.filter((f) => !isVisual(f)), matchKey);
|
|
51
|
+
for (const [f, was] of matched) {
|
|
52
|
+
if (was) {
|
|
53
|
+
f.change = "still";
|
|
54
|
+
f.previous = was.id;
|
|
55
|
+
if ((!f.status || f.status === "open") && was.status && was.status !== "open") f.status = was.status;
|
|
56
|
+
} else {
|
|
57
|
+
f.change = fixedBefore.has(matchKey(f)) ? "returned" : "new";
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
// Only what this run could have seen again counts as fixed.
|
|
62
|
+
const routes = new Set(run.pages.map((p) => p.route));
|
|
63
|
+
const passes = new Set(run.pages.flatMap((p) => Object.keys(p.shots ?? {})));
|
|
64
|
+
const seen = (f) => {
|
|
65
|
+
if (f.page && !routes.has(f.page)) return false;
|
|
66
|
+
if (f.viewport && f.theme && passes.size && !passes.has(shotKey(f.viewport, f.theme))) return false;
|
|
67
|
+
return true;
|
|
68
|
+
};
|
|
69
|
+
run.fixed = left.filter(seen).map(({ change, previous, ...f }, i) => ({ ...f, previous: f.id, id: `x${i + 1}`, change: "fixed" }));
|
|
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
|
+
|
|
74
|
+
const count = (c) => run.findings.filter((f) => f.change === c).length;
|
|
75
|
+
run.compare = {
|
|
76
|
+
against,
|
|
77
|
+
previous: { kind: prev.kind, started: prev.started, finished: prev.finished },
|
|
78
|
+
new: count("new"),
|
|
79
|
+
still: count("still"),
|
|
80
|
+
returned: count("returned"),
|
|
81
|
+
fixed: run.fixed.length,
|
|
82
|
+
};
|
|
83
|
+
return run;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Diff two PNGs in a browser page. `before` and `after` are PNG buffers.
|
|
88
|
+
* Returns the share of pixels that changed, a box round them, and a diff
|
|
89
|
+
* image: the new shot washed out, changed pixels in red. Where the sizes
|
|
90
|
+
* differ, the area only one shot covers counts as changed.
|
|
91
|
+
*/
|
|
92
|
+
export async function diffPngs(page, before, after, { tolerance = 24 } = {}) {
|
|
93
|
+
const r = await page.evaluate(
|
|
94
|
+
async ({ a, b, tolerance }) => {
|
|
95
|
+
const load = (src) =>
|
|
96
|
+
new Promise((res, rej) => {
|
|
97
|
+
const img = new Image();
|
|
98
|
+
img.onload = () => res(img);
|
|
99
|
+
img.onerror = () => rej(new Error("a screenshot couldn't be decoded"));
|
|
100
|
+
img.src = src;
|
|
101
|
+
});
|
|
102
|
+
const [ia, ib] = await Promise.all([load(a), load(b)]);
|
|
103
|
+
const w = Math.max(ia.naturalWidth, ib.naturalWidth);
|
|
104
|
+
const h = Math.max(ia.naturalHeight, ib.naturalHeight);
|
|
105
|
+
const pixels = (img) => {
|
|
106
|
+
const c = new OffscreenCanvas(w, h);
|
|
107
|
+
const ctx = c.getContext("2d", { willReadFrequently: true });
|
|
108
|
+
ctx.drawImage(img, 0, 0);
|
|
109
|
+
return ctx.getImageData(0, 0, w, h).data;
|
|
110
|
+
};
|
|
111
|
+
const pa = pixels(ia);
|
|
112
|
+
const pb = pixels(ib);
|
|
113
|
+
const out = new ImageData(w, h);
|
|
114
|
+
const d = out.data;
|
|
115
|
+
let changed = 0;
|
|
116
|
+
let x0 = w, y0 = h, x1 = -1, y1 = -1;
|
|
117
|
+
for (let y = 0; y < h; y++) {
|
|
118
|
+
const inA = y < ia.naturalHeight;
|
|
119
|
+
const inB = y < ib.naturalHeight;
|
|
120
|
+
for (let x = 0; x < w; x++) {
|
|
121
|
+
const i = (y * w + x) * 4;
|
|
122
|
+
const a1 = inA && x < ia.naturalWidth;
|
|
123
|
+
const b1 = inB && x < ib.naturalWidth;
|
|
124
|
+
const diff = !(a1 && b1) || Math.abs(pa[i] - pb[i]) > tolerance || Math.abs(pa[i + 1] - pb[i + 1]) > tolerance || Math.abs(pa[i + 2] - pb[i + 2]) > tolerance || Math.abs(pa[i + 3] - pb[i + 3]) > tolerance;
|
|
125
|
+
if (diff) {
|
|
126
|
+
changed++;
|
|
127
|
+
if (x < x0) x0 = x;
|
|
128
|
+
if (y < y0) y0 = y;
|
|
129
|
+
if (x > x1) x1 = x;
|
|
130
|
+
if (y > y1) y1 = y;
|
|
131
|
+
d[i] = 230; d[i + 1] = 30; d[i + 2] = 30; d[i + 3] = 255;
|
|
132
|
+
} else {
|
|
133
|
+
const src = b1 ? pb : pa;
|
|
134
|
+
const lum = 0.299 * src[i] + 0.587 * src[i + 1] + 0.114 * src[i + 2];
|
|
135
|
+
const v = 255 - (255 - lum) * 0.22;
|
|
136
|
+
d[i] = v; d[i + 1] = v; d[i + 2] = v; d[i + 3] = 255;
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
const c = new OffscreenCanvas(w, h);
|
|
141
|
+
c.getContext("2d").putImageData(out, 0, 0);
|
|
142
|
+
const blob = await c.convertToBlob({ type: "image/png" });
|
|
143
|
+
const png = await new Promise((res) => {
|
|
144
|
+
const fr = new FileReader();
|
|
145
|
+
fr.onload = () => res(String(fr.result).split(",")[1]);
|
|
146
|
+
fr.readAsDataURL(blob);
|
|
147
|
+
});
|
|
148
|
+
return {
|
|
149
|
+
width: w,
|
|
150
|
+
height: h,
|
|
151
|
+
before: { width: ia.naturalWidth, height: ia.naturalHeight },
|
|
152
|
+
after: { width: ib.naturalWidth, height: ib.naturalHeight },
|
|
153
|
+
changed,
|
|
154
|
+
total: w * h,
|
|
155
|
+
box: changed ? { x: x0, y: y0, w: x1 - x0 + 1, h: y1 - y0 + 1 } : null,
|
|
156
|
+
png,
|
|
157
|
+
};
|
|
158
|
+
},
|
|
159
|
+
{ a: `data:image/png;base64,${before.toString("base64")}`, b: `data:image/png;base64,${after.toString("base64")}`, tolerance },
|
|
160
|
+
);
|
|
161
|
+
return { ...r, percent: r.total ? Math.round((r.changed / r.total) * 100000) / 1000 : 0, png: Buffer.from(r.png, "base64") };
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Every shot present in both runs, as pairs of files. */
|
|
165
|
+
export function shotPairs(run, dir, prev, prevDir) {
|
|
166
|
+
const prevPages = new Map(prev.pages.map((p) => [p.route, p]));
|
|
167
|
+
const pairs = [];
|
|
168
|
+
for (const page of run.pages) {
|
|
169
|
+
const was = prevPages.get(page.route);
|
|
170
|
+
if (!was) continue;
|
|
171
|
+
for (const [key, shot] of Object.entries(page.shots ?? {})) {
|
|
172
|
+
const old = was.shots?.[key];
|
|
173
|
+
if (!old) continue;
|
|
174
|
+
const after = join(dir, shot.path);
|
|
175
|
+
const before = join(prevDir, old.path);
|
|
176
|
+
if (existsSync(after) && existsSync(before)) pairs.push({ page, key, shot, before, after });
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
return pairs;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* Diff every shared shot and record it: `pages[].diffs[key]`, a PNG in
|
|
184
|
+
* `diffs/`, and a `visual/changed` finding above `threshold` percent.
|
|
185
|
+
*/
|
|
186
|
+
export async function diffRuns(run, dir, prev, prevDir, { browser, threshold = 0.01, tolerance = 24, log = () => {} }) {
|
|
187
|
+
const pairs = shotPairs(run, dir, prev, prevDir);
|
|
188
|
+
if (!pairs.length) return { compared: 0, changed: 0 };
|
|
189
|
+
const page = await browser.newPage();
|
|
190
|
+
let changedPages = 0;
|
|
191
|
+
try {
|
|
192
|
+
for (const p of pairs) {
|
|
193
|
+
const r = await diffPngs(page, readFileSync(p.before), readFileSync(p.after), { tolerance });
|
|
194
|
+
const file = join("diffs", p.shot.path.split("/").pop());
|
|
195
|
+
mkdirSync(dirname(join(dir, file)), { recursive: true });
|
|
196
|
+
writeFileSync(join(dir, file), r.png);
|
|
197
|
+
const [viewport, theme] = p.key.split("-");
|
|
198
|
+
p.page.diffs ??= {};
|
|
199
|
+
p.page.diffs[p.key] = { path: file, percent: r.percent, width: r.width, height: r.height, box: r.box, sizeChanged: r.before.width !== r.after.width || r.before.height !== r.after.height };
|
|
200
|
+
log(` ${viewport} ${theme} ${p.page.route} ${r.percent}% changed`);
|
|
201
|
+
if (r.percent > threshold) {
|
|
202
|
+
changedPages++;
|
|
203
|
+
run.findings.push({
|
|
204
|
+
id: `v${changedPages}`,
|
|
205
|
+
kind: run.kind,
|
|
206
|
+
domain: "visual",
|
|
207
|
+
rule: "visual/changed",
|
|
208
|
+
severity: "info",
|
|
209
|
+
status: "open",
|
|
210
|
+
title: "This page looks different since the last run",
|
|
211
|
+
detail: "Red in the diff marks every pixel that changed. If the change wasn't meant, it's a regression; if it was, nothing to do.",
|
|
212
|
+
evidence: `${r.percent}% of the page changed${p.page.diffs[p.key].sizeChanged ? ` · ${r.before.width}×${r.before.height} → ${r.after.width}×${r.after.height}` : ""}`,
|
|
213
|
+
page: p.page.route,
|
|
214
|
+
viewport,
|
|
215
|
+
theme,
|
|
216
|
+
shot: p.key,
|
|
217
|
+
box: r.box ? clampBox(r.box, p.shot) : undefined,
|
|
218
|
+
diff: { path: file, width: r.width, height: r.height, box: r.box },
|
|
219
|
+
});
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
} finally {
|
|
223
|
+
await page.close();
|
|
224
|
+
}
|
|
225
|
+
return { compared: pairs.length, changed: changedPages };
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
function clampBox(box, shot) {
|
|
229
|
+
const x = Math.min(box.x, shot.width - 1);
|
|
230
|
+
const y = Math.min(box.y, shot.height - 1);
|
|
231
|
+
return { x, y, w: Math.max(1, Math.min(box.w, shot.width - x)), h: Math.max(1, Math.min(box.h, shot.height - y)) };
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Compare the run in `dir` with the one in `prevDir`, write the marks into
|
|
236
|
+
* `dir/findings.json`, and diff the screenshots unless `diff: false`. A browser
|
|
237
|
+
* is launched only when there are shots to diff; if none can launch, the
|
|
238
|
+
* findings are still compared and the diff is skipped with a note.
|
|
239
|
+
*/
|
|
240
|
+
export async function compareDirs(dir, prevDir, { diff = true, threshold = 0.01, tolerance = 24, browser = null, launch = null, log = (m) => process.stderr.write(m + "\n") } = {}) {
|
|
241
|
+
const run = clearCompare(readRun(dir));
|
|
242
|
+
const prev = readRun(prevDir);
|
|
243
|
+
if (prev.kind !== run.kind) log(`Comparing a ${run.kind} with a ${prev.kind}: findings only one of them looks for will show as new or fixed.`);
|
|
244
|
+
compareRuns(run, prev, { against: relative(dir, prevDir) || "." });
|
|
245
|
+
|
|
246
|
+
if (diff && shotPairs(run, dir, prev, prevDir).length) {
|
|
247
|
+
let own = null;
|
|
248
|
+
try {
|
|
249
|
+
if (!browser) {
|
|
250
|
+
const start = launch ?? (await import("./playwright.mjs")).launch;
|
|
251
|
+
own = await start({ root: run.root ?? process.cwd(), log });
|
|
252
|
+
}
|
|
253
|
+
log("Diffing screenshots …");
|
|
254
|
+
run.compare.visual = { threshold, ...(await diffRuns(run, dir, prev, prevDir, { browser: browser ?? own, threshold, tolerance, log })) };
|
|
255
|
+
} catch (err) {
|
|
256
|
+
log(`Screenshots not diffed: ${String(err?.message ?? err).split("\n")[0]}`);
|
|
257
|
+
run.compare.visual = { threshold, compared: 0, changed: 0, skipped: String(err?.message ?? err).split("\n")[0] };
|
|
258
|
+
} finally {
|
|
259
|
+
await own?.close();
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
return writeRun(dir, run);
|
|
263
|
+
}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One format for everything Keyline reports about a running product: the
|
|
3
|
+
* audit, the smoke test, a plain capture. Each run is a folder:
|
|
4
|
+
*
|
|
5
|
+
* keyline-report/
|
|
6
|
+
* findings.json the run, below
|
|
7
|
+
* index.html the report, rendered from findings.json by report.mjs
|
|
8
|
+
* shots/ one PNG per page × viewport × theme
|
|
9
|
+
*
|
|
10
|
+
* findings.json:
|
|
11
|
+
*
|
|
12
|
+
* {
|
|
13
|
+
* "version": 1,
|
|
14
|
+
* "kind": "audit" | "smoke" | "capture",
|
|
15
|
+
* "title": "Lumen", "base": "http://localhost:3000", "root": "/abs/project",
|
|
16
|
+
* "started": ISO, "finished": ISO,
|
|
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
|
|
20
|
+
* "summary": "one paragraph a person reads first" | null,
|
|
21
|
+
* "pages": [ { "route": "/settings", "url": …, "title": …, "status": 200,
|
|
22
|
+
* "shots": { "desktop-light": { "path": "shots/…png", "width": 1440, "height": 3120 } } } ],
|
|
23
|
+
* "findings": [ Finding ]
|
|
24
|
+
* }
|
|
25
|
+
*
|
|
26
|
+
* A Finding (only `rule` and `title` are required):
|
|
27
|
+
*
|
|
28
|
+
* id stable within the run, e.g. "f12"
|
|
29
|
+
* kind "audit" | "smoke" | "capture" | "check"
|
|
30
|
+
* domain type | color | layout | depth | motion | patterns | a11y | slop | flow | copy | states | runtime | visual
|
|
31
|
+
* rule "a11y/name", "flow/dead-click", "slop/purple-hero" …
|
|
32
|
+
* law "patterns law 1" — the law it comes from, when there is one
|
|
33
|
+
* severity "error" | "warning" | "info"
|
|
34
|
+
* title one line a person understands without the rule id
|
|
35
|
+
* detail what's wrong, what the reader feels, what to do
|
|
36
|
+
* evidence the measurement: "2.36:1", "click changed nothing", "404"
|
|
37
|
+
* page the route it was seen on
|
|
38
|
+
* viewport "desktop" | "phone"
|
|
39
|
+
* theme "light" | "dark"
|
|
40
|
+
* shot the key of the page's shot it was seen in, e.g. "desktop-light"
|
|
41
|
+
* box { x, y, w, h } in CSS pixels on that full-page shot — drawn in the report
|
|
42
|
+
* selector a CSS selector for the element
|
|
43
|
+
* file source file, relative to the project root, and `line`
|
|
44
|
+
* fix the command that fixes it: "/keyline color", "/keyline polish --from keyline-report"
|
|
45
|
+
* steps smoke only: the steps that reproduce it, in order
|
|
46
|
+
* status "open" (default) | "accepted" | "dismissed" | "fixed" — set by a person, the auditing agent, or polish --from
|
|
47
|
+
*
|
|
48
|
+
* Compared with an earlier run (`report --compare`, see compare.mjs), each
|
|
49
|
+
* finding also has `change` ("new" | "still" | "returned"), the run has
|
|
50
|
+
* `compare` (the counts) and `fixed` (the earlier run's findings that are
|
|
51
|
+
* gone), and each page has `diffs`, its screenshot diffs by shot key.
|
|
52
|
+
*/
|
|
53
|
+
|
|
54
|
+
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
55
|
+
import { join } from "node:path";
|
|
56
|
+
import { SEVERITIES, bySeverity, tally } from "trykeyline/check/findings";
|
|
57
|
+
import { DOMAINS as LAW_DOMAINS } from "trykeyline/check/rules";
|
|
58
|
+
|
|
59
|
+
/** The six law domains, and what only a rendered page shows. */
|
|
60
|
+
export const DOMAINS = [...LAW_DOMAINS, "a11y", "copy", "states", "slop", "flow", "runtime", "visual"];
|
|
61
|
+
|
|
62
|
+
export function newRun({ kind, title = null, base = null, root = null }) {
|
|
63
|
+
return {
|
|
64
|
+
version: 1,
|
|
65
|
+
kind,
|
|
66
|
+
title,
|
|
67
|
+
base,
|
|
68
|
+
root,
|
|
69
|
+
started: new Date().toISOString(),
|
|
70
|
+
finished: null,
|
|
71
|
+
scores: null,
|
|
72
|
+
score: null,
|
|
73
|
+
history: [],
|
|
74
|
+
summary: null,
|
|
75
|
+
pages: [],
|
|
76
|
+
findings: [],
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** Add a finding, filling defaults and an id. Returns it. */
|
|
81
|
+
export function add(run, f) {
|
|
82
|
+
if (!f.rule || !f.title) throw new Error(`a finding needs a rule and a title: ${JSON.stringify(f)}`);
|
|
83
|
+
const finding = {
|
|
84
|
+
id: f.id ?? `f${run.findings.length + 1}`,
|
|
85
|
+
kind: f.kind ?? run.kind,
|
|
86
|
+
domain: f.domain ?? f.rule.split("/")[0],
|
|
87
|
+
severity: SEVERITIES.includes(f.severity) ? f.severity : "warning",
|
|
88
|
+
status: f.status ?? "open",
|
|
89
|
+
...f,
|
|
90
|
+
};
|
|
91
|
+
run.findings.push(finding);
|
|
92
|
+
return finding;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The same problem seen on many pages is one finding per page, but not twice on one page. */
|
|
96
|
+
export function dedupe(findings) {
|
|
97
|
+
const seen = new Set();
|
|
98
|
+
return findings.filter((f) => {
|
|
99
|
+
const key = [f.rule, f.page, f.viewport, f.theme, f.selector ?? f.title].join("|");
|
|
100
|
+
if (seen.has(key)) return false;
|
|
101
|
+
seen.add(key);
|
|
102
|
+
return true;
|
|
103
|
+
});
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
export function sortFindings(findings) {
|
|
107
|
+
return [...findings].sort((a, b) => bySeverity(a, b) || String(a.page).localeCompare(String(b.page)) || a.rule.localeCompare(b.rule));
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** Open findings by severity and domain: dismissed and fixed ones don't count. */
|
|
111
|
+
export function counts(findings) {
|
|
112
|
+
return tally(findings, { skip: (f) => f.status === "dismissed" || f.status === "fixed" });
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export function writeRun(dir, run) {
|
|
116
|
+
mkdirSync(dir, { recursive: true });
|
|
117
|
+
run.finished ??= new Date().toISOString();
|
|
118
|
+
run.findings = sortFindings(dedupe(run.findings)).map((f, i) => ({ ...f, id: `f${i + 1}` }));
|
|
119
|
+
writeFileSync(join(dir, "findings.json"), JSON.stringify(run, null, 2) + "\n");
|
|
120
|
+
return run;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export function readRun(dir) {
|
|
124
|
+
const file = join(dir, "findings.json");
|
|
125
|
+
if (!existsSync(file)) throw new Error(`no findings.json in ${dir}`);
|
|
126
|
+
const run = JSON.parse(readFileSync(file, "utf8"));
|
|
127
|
+
if (run.version !== 1) throw new Error(`findings.json version ${run.version} isn't one this Keyline reads`);
|
|
128
|
+
return run;
|
|
129
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Playwright, only when a browser is needed. It's an optional peer of this
|
|
3
|
+
* package, never a dependency: the scripts that drive a page load it from the
|
|
4
|
+
* project if it has it, or from beside this package, else from Keyline's own
|
|
5
|
+
* cache, installing it there once (`~/.cache/keyline`, or $KEYLINE_CACHE) at
|
|
6
|
+
* the version below. The browser is the installed Chrome when there is one,
|
|
7
|
+
* so nothing large is downloaded; Playwright's own Chromium otherwise.
|
|
8
|
+
*
|
|
9
|
+
* An agent with its own browser tools (Claude's browser, a Playwright MCP) can
|
|
10
|
+
* skip all of this: the commands say how to walk the pages with those tools
|
|
11
|
+
* and write findings.json by hand, then render it with `keyline report`.
|
|
12
|
+
*/
|
|
13
|
+
import { execFileSync } from "node:child_process";
|
|
14
|
+
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
|
|
15
|
+
import { createRequire } from "node:module";
|
|
16
|
+
import { homedir } from "node:os";
|
|
17
|
+
import { dirname, join } from "node:path";
|
|
18
|
+
import { fileURLToPath, pathToFileURL } from "node:url";
|
|
19
|
+
import { runNpm } from "trykeyline/npm";
|
|
20
|
+
|
|
21
|
+
export const CACHE = process.env.KEYLINE_CACHE?.trim() || join(homedir(), ".cache", "keyline");
|
|
22
|
+
/** What a first run installs into the cache: one exact version, so every machine drives the same Playwright. */
|
|
23
|
+
export const PLAYWRIGHT_VERSION = "1.65.0";
|
|
24
|
+
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
25
|
+
|
|
26
|
+
function resolveFrom(base) {
|
|
27
|
+
try {
|
|
28
|
+
return createRequire(join(base, "noop.js")).resolve("playwright");
|
|
29
|
+
} catch {
|
|
30
|
+
return null;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
async function importFrom(path) {
|
|
35
|
+
const mod = await import(pathToFileURL(path).href);
|
|
36
|
+
const pw = mod.chromium ? mod : mod.default;
|
|
37
|
+
if (!pw?.chromium) throw new Error(`${path} didn't export chromium`);
|
|
38
|
+
return { pw, dir: dirname(path) };
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Find Playwright, or install it into the cache. `install: false` throws instead. */
|
|
42
|
+
export async function loadPlaywright({ root = process.cwd(), install = true, log = (m) => process.stderr.write(m + "\n") } = {}) {
|
|
43
|
+
for (const base of [root, HERE, CACHE]) {
|
|
44
|
+
const found = resolveFrom(base);
|
|
45
|
+
if (found) return importFrom(found);
|
|
46
|
+
}
|
|
47
|
+
if (!install) {
|
|
48
|
+
throw new Error("Playwright isn't installed. Run with install allowed, or `npm i -D playwright` in the project.");
|
|
49
|
+
}
|
|
50
|
+
log(`Keyline drives a browser with Playwright. Installing it once into ${CACHE} …`);
|
|
51
|
+
mkdirSync(CACHE, { recursive: true });
|
|
52
|
+
const pkg = join(CACHE, "package.json");
|
|
53
|
+
if (!existsSync(pkg)) writeFileSync(pkg, JSON.stringify({ name: "keyline-cache", private: true }) + "\n");
|
|
54
|
+
// npm is npm.cmd on Windows, which Node only spawns through a shell.
|
|
55
|
+
const r = runNpm("npm", ["install", "--no-audit", "--no-fund", "--prefix", CACHE, `playwright@${PLAYWRIGHT_VERSION}`], { stdio: ["ignore", "inherit", "inherit"] });
|
|
56
|
+
if (r.error || r.status !== 0) throw new Error(`couldn't install Playwright into ${CACHE}${r.error ? `: ${r.error.message}` : ""}. Install it in the project instead: npm i -D playwright`);
|
|
57
|
+
const found = resolveFrom(CACHE);
|
|
58
|
+
if (!found) throw new Error(`installed Playwright but can't resolve it from ${CACHE}`);
|
|
59
|
+
return importFrom(found);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Chrome if it's installed, Playwright's Chromium if not (downloaded once). `install: false` never installs anything: it throws instead. */
|
|
63
|
+
export async function launch({ root, headless = true, log, install = true } = {}) {
|
|
64
|
+
const { pw, dir } = await loadPlaywright({ root, log, install });
|
|
65
|
+
try {
|
|
66
|
+
return await pw.chromium.launch({ headless, channel: "chrome" });
|
|
67
|
+
} catch {
|
|
68
|
+
// No installed Chrome; fall through to Playwright's own build.
|
|
69
|
+
}
|
|
70
|
+
try {
|
|
71
|
+
return await pw.chromium.launch({ headless });
|
|
72
|
+
} catch (err) {
|
|
73
|
+
if (!install) throw err;
|
|
74
|
+
(log ?? ((m) => process.stderr.write(m + "\n")))("Downloading Playwright's Chromium once …");
|
|
75
|
+
execFileSync(process.execPath, [join(dir, "cli.js"), "install", "chromium"], { stdio: ["ignore", "inherit", "inherit"] });
|
|
76
|
+
return pw.chromium.launch({ headless });
|
|
77
|
+
}
|
|
78
|
+
}
|