shapewall 0.2.3 → 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/CHANGELOG.md +48 -0
- package/README.md +35 -1
- package/dist/agent/package-lock.json +2 -2
- package/dist/client/assets/BoardChat-CupOxioV.js +27 -0
- package/dist/client/assets/{BuzzDialog-CZdwIQLF.js → BuzzDialog-Ds7Thpfe.js} +1 -1
- package/dist/client/assets/ChecksPanel-BqrS02Ih.js +1 -0
- package/dist/client/assets/History-CQG3NQOC.js +1 -0
- package/dist/client/assets/{LocalSettings-CvlVtNY_.js → LocalSettings-CSNMhNyV.js} +1 -1
- package/dist/client/assets/{Management-DOJkFY_o.js → Management-CJVNAqAW.js} +1 -1
- package/dist/client/assets/QuickConnect-B-4pUgXH.js +1 -0
- package/dist/client/assets/{ShareDialog-CdVAreaw.js → ShareDialog-BouvNraR.js} +2 -2
- package/dist/client/assets/{app-update-dialog-Dox9-LWv.js → app-update-dialog-rhaw0MRk.js} +1 -1
- package/dist/client/assets/{circle-x-BmT6vHKl.js → circle-x-PRxj7kPi.js} +1 -1
- package/dist/client/assets/index-CXtuJi1K.css +2 -0
- package/dist/client/assets/index-DKOCIQiq.js +37 -0
- package/dist/client/assets/{refresh-cw-ugt3cWKH.js → refresh-cw-aeOBDuGQ.js} +1 -1
- package/dist/client/assets/{square-_KG6tM5A.js → shield-check-DuPBJ6H_.js} +1 -1
- package/dist/client/assets/ui-Cg4TTrec.js +41 -0
- package/dist/client/build-info.json +1 -1
- package/dist/client/index.html +3 -3
- package/dist/client/sw.js +2 -2
- package/dist/console/assets/LocalAccountsApp-DOKZI6Lt.js +1 -0
- package/dist/console/assets/LocalConsole-DXzldLW9.js +1 -0
- package/dist/console/assets/app-update-dialog-CrqIMEwN.js +1 -0
- package/dist/console/assets/console-76WovHlh.js +55 -0
- package/dist/console/assets/console-Fp4k9iyx.css +2 -0
- package/dist/console/build-info.json +1 -1
- package/dist/console/console.html +2 -2
- package/docs/agent-hardening.md +19 -0
- package/docs/agent-workflow.md +33 -0
- package/docs/agents.md +112 -0
- package/docs/config.md +41 -0
- package/docs/deployment.md +3 -0
- package/docs/design-system.md +13 -5
- package/docs/hosted.md +10 -0
- package/docs/journeys.md +13 -1
- package/docs/pull-requests.md +192 -0
- package/package.json +2 -1
- package/src/agent/backends/acp.js +35 -6
- package/src/agent/batch-fixes.js +45 -0
- package/src/agent/batch-queue.js +204 -0
- package/src/agent/branch-mode.js +753 -0
- package/src/agent/config.js +6 -0
- package/src/agent/fix-prompt.js +5 -0
- package/src/agent/manage.js +1 -1
- package/src/agent/routes.js +901 -186
- package/src/agent/run.js +8 -1
- package/src/agent/settings-events.js +103 -0
- package/src/agent/settings-routes.js +92 -2
- package/src/agent/starter/worktree.js +254 -25
- package/src/agent/threads.js +2 -7
- package/src/agent/tools.js +51 -0
- package/src/agent/user-settings.js +33 -2
- package/src/ci/capture.js +103 -0
- package/src/ci/compare.js +267 -0
- package/src/ci/github.js +307 -0
- package/src/ci/images.js +76 -0
- package/src/ci/settings.js +211 -0
- package/src/ci/start.js +148 -0
- package/src/ci/summary.js +262 -0
- package/src/ci/workflow.js +238 -0
- package/src/cli/args.js +24 -1
- package/src/cli/ci.js +229 -0
- package/src/cli/help.js +23 -1
- package/src/cli/init.js +33 -1
- package/src/cli.js +6 -2
- package/src/comment-drawing.js +161 -0
- package/src/comment-fields.js +51 -0
- package/src/comment-media.js +528 -0
- package/src/config.js +7 -0
- package/src/doctor.js +23 -0
- package/src/export.js +8 -0
- package/src/feedback.js +89 -12
- package/src/github.js +3 -3
- package/src/hosted/admin.js +36 -4
- package/src/hosted/app.js +5 -0
- package/src/hosted/board-routes.js +63 -7
- package/src/hosted/clean-worker.js +22 -4
- package/src/hosted/cleaner.js +4 -1
- package/src/hosted/comment-files.js +200 -0
- package/src/hosted/comments.js +68 -15
- package/src/hosted/db.js +32 -0
- package/src/hosted/guest-view.js +9 -0
- package/src/hosted/import.js +213 -18
- package/src/hosted/operator.js +3 -1
- package/src/hosted/projects.js +3 -2
- package/src/hosted/push.js +6 -3
- package/src/hosted/retention.js +18 -0
- package/src/hosted/tenancy.js +1 -0
- package/src/hosted/token-api.js +110 -9
- package/src/image-sniff.js +11 -0
- package/src/mcp.js +48 -3
- package/src/remote/remote-mcp.js +2 -2
- package/src/remote/remote.js +6 -2
- package/src/remote/share.js +77 -7
- package/src/server/app.js +18 -1
- package/src/store.js +119 -33
- package/src/watch.js +4 -0
- package/dist/client/assets/BoardChat-C88k4s-W.js +0 -28
- package/dist/client/assets/ChecksPanel-B54chcLA.js +0 -1
- package/dist/client/assets/History-CVVuuxUK.js +0 -1
- package/dist/client/assets/QuickConnect-D40mj4Ry.js +0 -1
- package/dist/client/assets/index-CwvFfwU0.js +0 -29
- package/dist/client/assets/index-UIYSPHoh.css +0 -2
- package/dist/client/assets/ui-BAGBTB_P.js +0 -41
- package/dist/console/assets/LocalAccountsApp-4MtW1QlZ.js +0 -1
- package/dist/console/assets/LocalConsole-CgKqYa8i.js +0 -1
- package/dist/console/assets/app-update-dialog-S2Yyc7Pw.js +0 -1
- package/dist/console/assets/console-BPmBRIoz.js +0 -51
- package/dist/console/assets/console-DgVrGRMD.css +0 -2
package/src/ci/start.js
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
// Runs `ci.start` (src/ci/settings.js) for `shapewall ci capture --allow-start`:
|
|
2
|
+
// install and build to completion, then the serve command in the background
|
|
3
|
+
// until the site answers. Each command is an argv array run without a shell;
|
|
4
|
+
// the program is looked up on absolute PATH entries only (which.js), so
|
|
5
|
+
// neither a string nor a program inside the repository can be named.
|
|
6
|
+
//
|
|
7
|
+
// It runs only inside a CI job (GITHUB_ACTIONS or CI is "true") and only when
|
|
8
|
+
// the command line says --allow-start: a config in a cloned repository never
|
|
9
|
+
// starts anything on someone's own machine because they ran a Shapewall command.
|
|
10
|
+
|
|
11
|
+
import { spawn } from 'node:child_process'
|
|
12
|
+
import { absoluteProgram } from '../which.js'
|
|
13
|
+
|
|
14
|
+
// Tokens the job has that the project's own commands never need.
|
|
15
|
+
const WITHHELD = [
|
|
16
|
+
'GITHUB_TOKEN',
|
|
17
|
+
'SHAPEWALL_GITHUB_TOKEN',
|
|
18
|
+
'ACTIONS_RUNTIME_TOKEN',
|
|
19
|
+
'ACTIONS_ID_TOKEN_REQUEST_TOKEN',
|
|
20
|
+
'ACTIONS_ID_TOKEN_REQUEST_URL',
|
|
21
|
+
'SHAPEWALL_TOKEN',
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
export const inCi = (env = process.env) => env.GITHUB_ACTIONS === 'true' || env.CI === 'true'
|
|
25
|
+
|
|
26
|
+
// Why ci.start may not run here, or null when it may.
|
|
27
|
+
export function startRefusal({ allowStart, env = process.env, start }) {
|
|
28
|
+
if (!start) return 'the config has no "ci.start" (the install, build and serve commands); add it, or capture a URL with --url'
|
|
29
|
+
if (!allowStart)
|
|
30
|
+
return 'ci.start runs only with --allow-start, which the workflow passes; Shapewall never runs commands from a config on its own'
|
|
31
|
+
if (!inCi(env))
|
|
32
|
+
return 'ci.start runs only inside a CI job (GITHUB_ACTIONS or CI set to "true"); on your own machine, start the site yourself and pass --url'
|
|
33
|
+
return null
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function commandEnv(env = process.env) {
|
|
37
|
+
const out = { ...env }
|
|
38
|
+
for (const name of WITHHELD) delete out[name]
|
|
39
|
+
return out
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
const describe = (argv) => argv.map((arg) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : JSON.stringify(arg))).join(' ')
|
|
43
|
+
|
|
44
|
+
function launch(argv, { cwd, env, log, detached }) {
|
|
45
|
+
const program = absoluteProgram(argv[0], env)
|
|
46
|
+
if (!program) throw new Error(`"${argv[0]}" is not on PATH (ci.start names programs, looked up on absolute PATH entries only)`)
|
|
47
|
+
const child = spawn(program, argv.slice(1), { cwd, env, shell: false, detached, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true })
|
|
48
|
+
const relay = (stream) => {
|
|
49
|
+
let rest = ''
|
|
50
|
+
stream.setEncoding('utf8')
|
|
51
|
+
stream.on('data', (chunk) => {
|
|
52
|
+
const lines = (rest + chunk).split('\n')
|
|
53
|
+
rest = lines.pop()
|
|
54
|
+
for (const line of lines) log(` | ${line.slice(0, 500)}`)
|
|
55
|
+
})
|
|
56
|
+
stream.on('end', () => rest && log(` | ${rest.slice(0, 500)}`))
|
|
57
|
+
}
|
|
58
|
+
relay(child.stdout)
|
|
59
|
+
relay(child.stderr)
|
|
60
|
+
return child
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
// A whole process group, so `npm start` does not leave its server behind.
|
|
64
|
+
function kill(child, signal) {
|
|
65
|
+
try {
|
|
66
|
+
if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal)
|
|
67
|
+
else child.kill(signal)
|
|
68
|
+
} catch {
|
|
69
|
+
/* already gone */
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function runToEnd(argv, { cwd, env, log, timeout }) {
|
|
74
|
+
return new Promise((resolve, reject) => {
|
|
75
|
+
let child
|
|
76
|
+
try {
|
|
77
|
+
child = launch(argv, { cwd, env, log, detached: process.platform !== 'win32' })
|
|
78
|
+
} catch (error) {
|
|
79
|
+
reject(error)
|
|
80
|
+
return
|
|
81
|
+
}
|
|
82
|
+
const timer = setTimeout(() => {
|
|
83
|
+
kill(child, 'SIGKILL')
|
|
84
|
+
reject(new Error(`${describe(argv)} did not finish within ${Math.round(timeout / 1000)} s`))
|
|
85
|
+
}, timeout)
|
|
86
|
+
child.on('error', (error) => {
|
|
87
|
+
clearTimeout(timer)
|
|
88
|
+
reject(new Error(`${describe(argv)} did not start: ${error.message}`))
|
|
89
|
+
})
|
|
90
|
+
child.on('exit', (code, signal) => {
|
|
91
|
+
clearTimeout(timer)
|
|
92
|
+
if (code === 0) resolve()
|
|
93
|
+
else reject(new Error(`${describe(argv)} failed (${signal ? `signal ${signal}` : `exit code ${code}`})`))
|
|
94
|
+
})
|
|
95
|
+
})
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
|
|
99
|
+
|
|
100
|
+
// Waits until `url` answers with any status below 500. `isDead()` stops the
|
|
101
|
+
// wait early (the serve command exited). Throws on timeout.
|
|
102
|
+
export async function waitForUrl(url, { timeout = 180000, interval = 1000, fetchImpl = globalThis.fetch, isDead = () => null } = {}) {
|
|
103
|
+
const until = Date.now() + timeout
|
|
104
|
+
let last = 'no answer yet'
|
|
105
|
+
for (;;) {
|
|
106
|
+
const dead = isDead()
|
|
107
|
+
if (dead) throw new Error(`the serve command exited before ${url} answered (${dead})`)
|
|
108
|
+
try {
|
|
109
|
+
const response = await fetchImpl(url, { redirect: 'manual', signal: AbortSignal.timeout(Math.min(10000, timeout)) })
|
|
110
|
+
await response.body?.cancel().catch(() => {})
|
|
111
|
+
if (response.status < 500) return response.status
|
|
112
|
+
last = `HTTP ${response.status}`
|
|
113
|
+
} catch (error) {
|
|
114
|
+
last = error.cause?.code || error.name || 'no answer'
|
|
115
|
+
}
|
|
116
|
+
if (Date.now() >= until) throw new Error(`${url} did not answer within ${Math.round(timeout / 1000)} s (${last})`)
|
|
117
|
+
await sleep(interval)
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
// Runs install and build, starts serve and waits for `url`. Returns { stop }.
|
|
122
|
+
export async function startSite(start, { cwd, url, env = process.env, log = () => {}, fetchImpl } = {}) {
|
|
123
|
+
const childEnv = commandEnv(env)
|
|
124
|
+
for (const step of ['install', 'build']) {
|
|
125
|
+
if (!start[step]) continue
|
|
126
|
+
log(`ci.start.${step}: ${describe(start[step])} (in ${cwd})`)
|
|
127
|
+
await runToEnd(start[step], { cwd, env: childEnv, log, timeout: start.timeout })
|
|
128
|
+
}
|
|
129
|
+
log(`ci.start.serve: ${describe(start.serve)} (in ${cwd})`)
|
|
130
|
+
const server = launch(start.serve, { cwd, env: childEnv, log, detached: process.platform !== 'win32' })
|
|
131
|
+
let exited = null
|
|
132
|
+
server.on('exit', (code, signal) => (exited = signal ? `signal ${signal}` : `exit code ${code}`))
|
|
133
|
+
server.on('error', (error) => (exited = error.message))
|
|
134
|
+
const stop = async () => {
|
|
135
|
+
if (exited) return
|
|
136
|
+
kill(server, 'SIGTERM')
|
|
137
|
+
for (let waited = 0; waited < 5000 && !exited; waited += 100) await sleep(100)
|
|
138
|
+
if (!exited) kill(server, 'SIGKILL')
|
|
139
|
+
}
|
|
140
|
+
try {
|
|
141
|
+
await waitForUrl(url, { timeout: start.timeout, fetchImpl, isDead: () => exited })
|
|
142
|
+
} catch (error) {
|
|
143
|
+
await stop()
|
|
144
|
+
throw error
|
|
145
|
+
}
|
|
146
|
+
log(`${url} is up`)
|
|
147
|
+
return { stop }
|
|
148
|
+
}
|
|
@@ -0,0 +1,262 @@
|
|
|
1
|
+
// The pull request comment, rendered from summary.json (src/ci/compare.js).
|
|
2
|
+
// `shapewall ci capture-compare` writes it as summary.md; `shapewall ci
|
|
3
|
+
// comment` renders it again with the links it knows by then (the workflow
|
|
4
|
+
// artifact, and image URLs when ci.images is "branch").
|
|
5
|
+
//
|
|
6
|
+
// Everything in it that came from the repository (page titles, paths, error
|
|
7
|
+
// text) is plain text: markdown, HTML and @mentions are neutralised, so a
|
|
8
|
+
// config in a pull request cannot put markup or pings in the comment.
|
|
9
|
+
|
|
10
|
+
export const COMMENT_MARKER = '<!-- shapewall-ci -->'
|
|
11
|
+
export const ROWS_MAX = 50
|
|
12
|
+
const FAILURES_MAX = 20
|
|
13
|
+
// GitHub refuses comments over 65536 characters.
|
|
14
|
+
export const BODY_MAX = 60000
|
|
15
|
+
|
|
16
|
+
const plural = (count, word, many = `${word}s`) => `${count} ${count === 1 ? word : many}`
|
|
17
|
+
|
|
18
|
+
// One table cell or line of plain text: no markdown, HTML, mention or link.
|
|
19
|
+
// A zero-width space (U+200B) breaks every @ (mentions, and GitHub's email
|
|
20
|
+
// and mailto:/xmpp: autolinks), "://" and "www." (GitHub's bare autolinks).
|
|
21
|
+
export function plain(value, max = 120) {
|
|
22
|
+
return String(value ?? '')
|
|
23
|
+
.replace(/[\r\n\t]+/g, ' ')
|
|
24
|
+
.slice(0, max)
|
|
25
|
+
.replace(/[\\`*_{}[\]()#+!|<>~]/g, (char) => `\\${char}`)
|
|
26
|
+
.replace(/@/g, '@')
|
|
27
|
+
.replace(/:\/\//g, '://')
|
|
28
|
+
.replace(/(www)\./gi, '$1.')
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// ---- Reading a summary.json back --------------------------------------------
|
|
32
|
+
//
|
|
33
|
+
// `shapewall ci comment` reads summary.json from the workflow artifact, which
|
|
34
|
+
// the pull request's own code could have written. normalizeSummary() keeps
|
|
35
|
+
// only what the comment uses, each field checked: counts are safe
|
|
36
|
+
// non-negative integers, ratios finite numbers in [0, 1], statuses and sides
|
|
37
|
+
// from their known values, image paths in the shape compare.js writes, and
|
|
38
|
+
// strings capped (and still passed through plain() when rendered). Anything
|
|
39
|
+
// else: null, and the comment says the result could not be read.
|
|
40
|
+
|
|
41
|
+
const SHOT_STATUSES = new Set(['unchanged', 'changed', 'new', 'removed', 'failed'])
|
|
42
|
+
const TOTAL_KEYS = [
|
|
43
|
+
'pages',
|
|
44
|
+
'changedPages',
|
|
45
|
+
'shots',
|
|
46
|
+
'changedShots',
|
|
47
|
+
'unchangedShots',
|
|
48
|
+
'failedShots',
|
|
49
|
+
'newPages',
|
|
50
|
+
'removedPages',
|
|
51
|
+
'pagesNotCompared',
|
|
52
|
+
]
|
|
53
|
+
const IMAGE_KEYS = ['before', 'after', 'diff', 'beforeThumb', 'afterThumb', 'diffThumb']
|
|
54
|
+
const IMAGE_PATH_RE = /^images\/[a-z0-9][a-z0-9.-]{0,100}\/[a-z.]{1,40}\.png$/
|
|
55
|
+
const SHOTS_MAX = 5000
|
|
56
|
+
const FAILURES_READ_MAX = 1000
|
|
57
|
+
|
|
58
|
+
class Unreadable extends Error {}
|
|
59
|
+
const unreadable = () => {
|
|
60
|
+
throw new Unreadable()
|
|
61
|
+
}
|
|
62
|
+
const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
|
|
63
|
+
const count = (value) => (Number.isSafeInteger(value) && value >= 0 ? value : unreadable())
|
|
64
|
+
const unit = (value) => (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1 ? value : unreadable())
|
|
65
|
+
const flag = (value) => (typeof value === 'boolean' ? value : unreadable())
|
|
66
|
+
const text = (value, max, { optional = false } = {}) => {
|
|
67
|
+
if (value === null || value === undefined) return optional ? null : unreadable()
|
|
68
|
+
return typeof value === 'string' ? value.slice(0, max) : unreadable()
|
|
69
|
+
}
|
|
70
|
+
const size = (value) => {
|
|
71
|
+
if (value === null || value === undefined) return null
|
|
72
|
+
return isObject(value) ? { width: count(value.width), height: count(value.height) } : unreadable()
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function cleanShot(raw) {
|
|
76
|
+
if (!isObject(raw) || !SHOT_STATUSES.has(raw.status)) unreadable()
|
|
77
|
+
let images = null
|
|
78
|
+
if (raw.images !== null && raw.images !== undefined) {
|
|
79
|
+
if (!isObject(raw.images)) unreadable()
|
|
80
|
+
images = {}
|
|
81
|
+
for (const key of IMAGE_KEYS) {
|
|
82
|
+
const value = raw.images[key]
|
|
83
|
+
if (value === undefined) continue
|
|
84
|
+
if (typeof value !== 'string' || !IMAGE_PATH_RE.test(value)) unreadable()
|
|
85
|
+
images[key] = value
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
return {
|
|
89
|
+
page: text(raw.page, 200),
|
|
90
|
+
title: text(raw.title, 300, { optional: true }),
|
|
91
|
+
path: text(raw.path, 500, { optional: true }),
|
|
92
|
+
viewport: text(raw.viewport, 64),
|
|
93
|
+
viewportSize: size(raw.viewportSize),
|
|
94
|
+
status: raw.status,
|
|
95
|
+
changed: flag(raw.changed),
|
|
96
|
+
ratio: unit(raw.ratio),
|
|
97
|
+
changedPixels: count(raw.changedPixels ?? 0),
|
|
98
|
+
totalPixels: count(raw.totalPixels ?? 0),
|
|
99
|
+
dimensionsChanged: flag(raw.dimensionsChanged ?? false),
|
|
100
|
+
base: size(raw.base),
|
|
101
|
+
head: size(raw.head),
|
|
102
|
+
images,
|
|
103
|
+
error: text(raw.error, 2000, { optional: true }),
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function cleanFailure(raw) {
|
|
108
|
+
if (!isObject(raw) || ![null, undefined, 'base', 'head'].includes(raw.side)) unreadable()
|
|
109
|
+
return {
|
|
110
|
+
side: raw.side ?? null,
|
|
111
|
+
page: text(raw.page, 200, { optional: true }),
|
|
112
|
+
viewport: text(raw.viewport, 64, { optional: true }),
|
|
113
|
+
error: text(raw.error, 2000, { optional: true }) || '',
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// A parsed summary.json, checked field by field: the clean summary, or null.
|
|
118
|
+
export function normalizeSummary(raw) {
|
|
119
|
+
try {
|
|
120
|
+
if (!isObject(raw) || !isObject(raw.totals) || !Array.isArray(raw.shots)) return null
|
|
121
|
+
const failures = raw.failures ?? []
|
|
122
|
+
if (!Array.isArray(failures) || raw.shots.length > SHOTS_MAX || failures.length > FAILURES_READ_MAX) return null
|
|
123
|
+
const totals = {}
|
|
124
|
+
for (const key of TOTAL_KEYS) totals[key] = count(raw.totals[key] ?? 0)
|
|
125
|
+
return {
|
|
126
|
+
schema: raw.schema,
|
|
127
|
+
version: raw.version,
|
|
128
|
+
threshold: unit(raw.threshold),
|
|
129
|
+
totals,
|
|
130
|
+
failures: failures.map(cleanFailure),
|
|
131
|
+
shots: raw.shots.map(cleanShot),
|
|
132
|
+
}
|
|
133
|
+
} catch (error) {
|
|
134
|
+
if (error instanceof Unreadable) return null
|
|
135
|
+
throw error
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
export function percent(ratio) {
|
|
140
|
+
const value = ratio * 100
|
|
141
|
+
if (value > 0 && value < 0.01) return '<0.01%'
|
|
142
|
+
return `${value.toFixed(2)}%`
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
function screen(shot) {
|
|
146
|
+
const size = shot.viewportSize ? ` ${shot.viewportSize.width}x${shot.viewportSize.height}` : ''
|
|
147
|
+
return `${plain(shot.viewport, 32)}${size}`
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
function changeText(shot) {
|
|
151
|
+
if (shot.status === 'new') return 'new page'
|
|
152
|
+
if (shot.status === 'removed') return 'page removed'
|
|
153
|
+
let text = percent(shot.ratio)
|
|
154
|
+
if (shot.dimensionsChanged && shot.base && shot.head)
|
|
155
|
+
text += ` (size ${shot.base.width}x${shot.base.height} to ${shot.head.width}x${shot.head.height})`
|
|
156
|
+
return text
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function pageCell(shot) {
|
|
160
|
+
const title = plain(shot.title || shot.page, 80)
|
|
161
|
+
return shot.path ? `${title} (${plain(shot.path, 80)})` : title
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// The headline: "Shapewall: 4 of 23 pages changed".
|
|
165
|
+
export function headline(summary) {
|
|
166
|
+
const { totals } = summary
|
|
167
|
+
const sideFailed = summary.failures.some((failure) => failure.page === null)
|
|
168
|
+
if (sideFailed && !totals.changedPages) return 'Shapewall: capture failed'
|
|
169
|
+
if (!totals.changedPages) return `Shapewall: no visual changes on ${plural(totals.pages, 'page')}`
|
|
170
|
+
return `Shapewall: ${totals.changedPages} of ${plural(totals.pages, 'page')} changed`
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
// `imageUrl(path)`: a URL for a file of the result folder (images branch), or
|
|
174
|
+
// null for links only. `artifactUrl`: the workflow artifact with the images.
|
|
175
|
+
// `runUrl`: the workflow run, for "see the log".
|
|
176
|
+
export function renderSummary(summary, { artifactUrl = null, runUrl = null, imageUrl = null, note = null } = {}) {
|
|
177
|
+
const { totals } = summary
|
|
178
|
+
const lines = [COMMENT_MARKER]
|
|
179
|
+
const title = headline(summary)
|
|
180
|
+
const changed = summary.shots.filter((shot) => shot.changed)
|
|
181
|
+
const failed = summary.failures
|
|
182
|
+
const quiet = !changed.length && !failed.length
|
|
183
|
+
if (quiet) lines.push('<details>', `<summary>${title}</summary>`, '')
|
|
184
|
+
else lines.push(`### ${title}`, '')
|
|
185
|
+
|
|
186
|
+
if (changed.length) {
|
|
187
|
+
lines.push('| Page | Screen size | Pixels changed |', '| --- | --- | --- |')
|
|
188
|
+
for (const shot of changed.slice(0, ROWS_MAX)) lines.push(`| ${pageCell(shot)} | ${screen(shot)} | ${changeText(shot)} |`)
|
|
189
|
+
if (changed.length > ROWS_MAX) lines.push('', `And ${plural(changed.length - ROWS_MAX, 'more changed shot')} in summary.json.`)
|
|
190
|
+
lines.push('')
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
if (imageUrl && changed.length) {
|
|
194
|
+
lines.push('<details open>', '<summary>Before, after and diff</summary>', '')
|
|
195
|
+
for (const shot of changed.slice(0, ROWS_MAX)) {
|
|
196
|
+
const images = shot.images || {}
|
|
197
|
+
const cell = (label, thumb, full) =>
|
|
198
|
+
images[thumb] ? `[})](${imageUrl(images[full] || images[thumb])})` : ' '
|
|
199
|
+
lines.push(`**${pageCell(shot)}**, ${screen(shot)}`, '', '| Before | After | Diff |', '| --- | --- | --- |')
|
|
200
|
+
lines.push(
|
|
201
|
+
`| ${cell('before', 'beforeThumb', 'before')} | ${cell('after', 'afterThumb', 'after')} | ${cell('diff', 'diffThumb', 'diff')} |`,
|
|
202
|
+
'',
|
|
203
|
+
)
|
|
204
|
+
}
|
|
205
|
+
lines.push('</details>', '')
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
if (failed.length) {
|
|
209
|
+
lines.push(`**Not captured** (${plural(failed.length, 'problem')}):`, '')
|
|
210
|
+
for (const failure of failed.slice(0, FAILURES_MAX)) {
|
|
211
|
+
const where = failure.page ? `${plain(failure.page, 64)} ${plain(failure.viewport, 32)}` : 'every page'
|
|
212
|
+
const side = failure.side === 'base' ? 'before' : failure.side === 'head' ? 'after' : 'compare'
|
|
213
|
+
lines.push(`- ${where} (${side}): ${plain(failure.error, 300)}`)
|
|
214
|
+
}
|
|
215
|
+
if (failed.length > FAILURES_MAX) lines.push(`- and ${failed.length - FAILURES_MAX} more in summary.json`)
|
|
216
|
+
lines.push('')
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
const facts = [`${plural(totals.shots, 'shot')} compared`]
|
|
220
|
+
if (totals.unchangedShots) facts.push(`${totals.unchangedShots} unchanged`)
|
|
221
|
+
if (totals.newPages) facts.push(plural(totals.newPages, 'new page'))
|
|
222
|
+
if (totals.removedPages) facts.push(plural(totals.removedPages, 'removed page'))
|
|
223
|
+
if (totals.pagesNotCompared) facts.push(`${plural(totals.pagesNotCompared, 'page')} left out by the page limit`)
|
|
224
|
+
facts.push(`a shot counts as changed from ${percent(summary.threshold)} of its pixels`)
|
|
225
|
+
lines.push(`${facts.join(', ')}.`)
|
|
226
|
+
const links = []
|
|
227
|
+
if (changed.length && artifactUrl) links.push(`[Before, after and diff images](${artifactUrl}) (the "shapewall-ci" artifact of this run)`)
|
|
228
|
+
if (runUrl) links.push(`[the workflow run](${runUrl})`)
|
|
229
|
+
if (links.length) lines.push('', `${links.join(', ')}.`)
|
|
230
|
+
if (note) lines.push('', plain(note, 300))
|
|
231
|
+
lines.push(
|
|
232
|
+
'',
|
|
233
|
+
'<sub>Turn this off: delete .github/workflows/shapewall.yml, set "ci": { "enabled": false } in shapewall.config.json, or put [skip shapewall] in the pull request title.</sub>',
|
|
234
|
+
)
|
|
235
|
+
if (quiet) lines.push('', '</details>')
|
|
236
|
+
let body = `${lines.join('\n')}\n`
|
|
237
|
+
if (body.length > BODY_MAX) body = `${body.slice(0, BODY_MAX)}\n\n(cut short; the full list is in summary.json)\n`
|
|
238
|
+
return body
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
// The comment when summary.json is there but not one Shapewall wrote as it
|
|
242
|
+
// should be (normalizeSummary said null): nothing from it is shown.
|
|
243
|
+
export function renderUnreadable({ runUrl = null } = {}) {
|
|
244
|
+
return [
|
|
245
|
+
COMMENT_MARKER,
|
|
246
|
+
'### Shapewall: the result could not be read',
|
|
247
|
+
'',
|
|
248
|
+
`The capture result (summary.json) is not in the shape Shapewall writes, so none of it is shown here.${runUrl ? ` See [the workflow run](${runUrl}).` : ''}`,
|
|
249
|
+
'',
|
|
250
|
+
].join('\n')
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// The comment when no summary.json exists: the capture step itself failed.
|
|
254
|
+
export function renderMissing({ runUrl = null } = {}) {
|
|
255
|
+
return [
|
|
256
|
+
COMMENT_MARKER,
|
|
257
|
+
'### Shapewall: capture failed',
|
|
258
|
+
'',
|
|
259
|
+
`No result was written, so nothing was compared.${runUrl ? ` The log of [the workflow run](${runUrl}) says what failed.` : ''}`,
|
|
260
|
+
'',
|
|
261
|
+
].join('\n')
|
|
262
|
+
}
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
// The GitHub Actions workflow `shapewall init --ci` writes to
|
|
2
|
+
// .github/workflows/shapewall.yml. It pins this Shapewall's version and the
|
|
3
|
+
// Playwright version it captures with, so the job runs what was tested here.
|
|
4
|
+
|
|
5
|
+
import fs from 'node:fs'
|
|
6
|
+
|
|
7
|
+
export const WORKFLOW_FILE = '.github/workflows/shapewall.yml'
|
|
8
|
+
|
|
9
|
+
const PACKAGE = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'))
|
|
10
|
+
|
|
11
|
+
export function workflowYaml({ version = PACKAGE.version, playwright = PACKAGE.dependencies.playwright } = {}) {
|
|
12
|
+
return `# Shapewall: capture on every pull request.
|
|
13
|
+
#
|
|
14
|
+
# On each pull request (and each push to it) this job captures the pages in
|
|
15
|
+
# shapewall.config.json twice, before (the base branch) and after (the pull
|
|
16
|
+
# request), compares them pixel by pixel and keeps one comment on the pull
|
|
17
|
+
# request up to date, such as "Shapewall: 4 of 23 pages changed", with a table
|
|
18
|
+
# and a link to the before, after and diff images. It never fails the pull
|
|
19
|
+
# request: capture problems are reported in the comment.
|
|
20
|
+
#
|
|
21
|
+
# Two modes. Pick one with SHAPEWALL_PREVIEW_URL below.
|
|
22
|
+
#
|
|
23
|
+
# Build and serve (SHAPEWALL_PREVIEW_URL empty, the default): the job checks
|
|
24
|
+
# out the base branch and the pull request side by side and, in each, runs
|
|
25
|
+
# the install, build and serve commands from "ci.start" in the config, waits
|
|
26
|
+
# for "ci.start.url" to answer and captures it. Example config:
|
|
27
|
+
# "ci": { "start": { "install": ["npm", "ci"], "build": ["npm", "run", "build"],
|
|
28
|
+
# "serve": ["npm", "start"], "url": "http://127.0.0.1:3000" } }
|
|
29
|
+
#
|
|
30
|
+
# Preview URL: set SHAPEWALL_PREVIEW_URL to the deploy preview of this pull
|
|
31
|
+
# request. The job waits until it answers, then compares it with
|
|
32
|
+
# SHAPEWALL_BASE_URL (empty: "baseUrl" in the config, such as production).
|
|
33
|
+
#
|
|
34
|
+
# Turn it off: delete this file; or set "ci": { "enabled": false } in
|
|
35
|
+
# shapewall.config.json; or put [skip shapewall] in a pull request title.
|
|
36
|
+
# Guide: https://shapewall.com/docs/pull-requests
|
|
37
|
+
|
|
38
|
+
name: Shapewall
|
|
39
|
+
|
|
40
|
+
on:
|
|
41
|
+
# pull_request only: a fork's pull request then runs with a read-only token
|
|
42
|
+
# and no secrets. Never use pull_request_target for this workflow.
|
|
43
|
+
pull_request:
|
|
44
|
+
types: [opened, synchronize, reopened]
|
|
45
|
+
|
|
46
|
+
# Least privilege: the capture job, which builds and runs the pull request's
|
|
47
|
+
# code, can only read. Only the comment job, which runs no code from the pull
|
|
48
|
+
# request, can write the one comment.
|
|
49
|
+
permissions:
|
|
50
|
+
contents: read
|
|
51
|
+
|
|
52
|
+
# One run per pull request: a new push cancels the run still going.
|
|
53
|
+
concurrency:
|
|
54
|
+
group: shapewall-\${{ github.event.pull_request.number }}
|
|
55
|
+
cancel-in-progress: true
|
|
56
|
+
|
|
57
|
+
jobs:
|
|
58
|
+
shapewall:
|
|
59
|
+
name: Shapewall capture
|
|
60
|
+
# Skip: put [skip shapewall] anywhere in the pull request title.
|
|
61
|
+
if: \${{ !contains(github.event.pull_request.title, '[skip shapewall]') }}
|
|
62
|
+
runs-on: ubuntu-latest
|
|
63
|
+
timeout-minutes: 25
|
|
64
|
+
permissions:
|
|
65
|
+
contents: read
|
|
66
|
+
outputs:
|
|
67
|
+
enabled: \${{ steps.gate.outputs.enabled }}
|
|
68
|
+
artifact-url: \${{ steps.upload.outputs.artifact-url }}
|
|
69
|
+
env:
|
|
70
|
+
SHAPEWALL: shapewall@${version}
|
|
71
|
+
PLAYWRIGHT: playwright@${playwright}
|
|
72
|
+
# Preview URL mode: the deploy preview of this pull request; empty for build and serve mode.
|
|
73
|
+
# Netlify-style deploy previews:
|
|
74
|
+
# SHAPEWALL_PREVIEW_URL: https://deploy-preview-\${{ github.event.pull_request.number }}--YOUR-SITE.netlify.app
|
|
75
|
+
# Vercel branch URLs (the branch name, lower case, with "/" as "-"; check one in your Vercel dashboard):
|
|
76
|
+
# SHAPEWALL_PREVIEW_URL: https://YOUR-PROJECT-git-\${{ github.head_ref }}-YOUR-TEAM.vercel.app
|
|
77
|
+
SHAPEWALL_PREVIEW_URL: ''
|
|
78
|
+
# Preview URL mode: what to compare with (empty: "baseUrl" in the config).
|
|
79
|
+
SHAPEWALL_BASE_URL: ''
|
|
80
|
+
HEAD_DIR: \${{ github.workspace }}/head
|
|
81
|
+
BASE_DIR: \${{ github.workspace }}/base
|
|
82
|
+
OUT: \${{ github.workspace }}/shapewall-ci
|
|
83
|
+
steps:
|
|
84
|
+
- name: Check out the pull request
|
|
85
|
+
uses: actions/checkout@v4
|
|
86
|
+
with:
|
|
87
|
+
path: head
|
|
88
|
+
persist-credentials: false
|
|
89
|
+
|
|
90
|
+
- name: Check out the base branch (build and serve mode)
|
|
91
|
+
if: env.SHAPEWALL_PREVIEW_URL == ''
|
|
92
|
+
uses: actions/checkout@v4
|
|
93
|
+
with:
|
|
94
|
+
ref: \${{ github.event.pull_request.base.sha }}
|
|
95
|
+
path: base
|
|
96
|
+
persist-credentials: false
|
|
97
|
+
|
|
98
|
+
- uses: actions/setup-node@v4
|
|
99
|
+
with:
|
|
100
|
+
node-version: 22
|
|
101
|
+
|
|
102
|
+
# The pinned tools go in the runner's temp folder, installed from there:
|
|
103
|
+
# the pull request's .npmrc and package.json have no say, and every
|
|
104
|
+
# later step calls them by absolute path from that folder.
|
|
105
|
+
- name: Install Shapewall and Playwright (outside the checkout)
|
|
106
|
+
working-directory: \${{ runner.temp }}
|
|
107
|
+
env:
|
|
108
|
+
NPM_CONFIG_USERCONFIG: /dev/null
|
|
109
|
+
run: |
|
|
110
|
+
mkdir -p shapewall-tools
|
|
111
|
+
cd shapewall-tools
|
|
112
|
+
printf '{ "private": true }\\n' > package.json
|
|
113
|
+
npm install --no-audit --no-fund --ignore-scripts --registry https://registry.npmjs.org/ "$SHAPEWALL" "$PLAYWRIGHT"
|
|
114
|
+
echo "SW=$PWD/node_modules/.bin/shapewall" >> "$GITHUB_ENV"
|
|
115
|
+
echo "PW=$PWD/node_modules/.bin/playwright" >> "$GITHUB_ENV"
|
|
116
|
+
|
|
117
|
+
# "ci": { "enabled": false } in the config, or [skip shapewall] in the title, stops here.
|
|
118
|
+
- name: Is Shapewall on for this pull request?
|
|
119
|
+
id: gate
|
|
120
|
+
continue-on-error: true
|
|
121
|
+
working-directory: \${{ runner.temp }}
|
|
122
|
+
run: '"$SW" ci enabled --config "$HEAD_DIR/shapewall.config.json"'
|
|
123
|
+
|
|
124
|
+
- name: Cache the browser download
|
|
125
|
+
if: steps.gate.outputs.enabled == 'true'
|
|
126
|
+
id: browser-cache
|
|
127
|
+
uses: actions/cache@v4
|
|
128
|
+
with:
|
|
129
|
+
path: ~/.cache/ms-playwright
|
|
130
|
+
key: shapewall-chromium-\${{ runner.os }}-${playwright}
|
|
131
|
+
|
|
132
|
+
- name: Install Chromium and its system libraries
|
|
133
|
+
continue-on-error: true
|
|
134
|
+
if: steps.gate.outputs.enabled == 'true' && steps.browser-cache.outputs.cache-hit != 'true'
|
|
135
|
+
working-directory: \${{ runner.temp }}
|
|
136
|
+
run: '"$PW" install --with-deps chromium'
|
|
137
|
+
|
|
138
|
+
- name: Install the system libraries Chromium needs (browser from the cache)
|
|
139
|
+
continue-on-error: true
|
|
140
|
+
if: steps.gate.outputs.enabled == 'true' && steps.browser-cache.outputs.cache-hit == 'true'
|
|
141
|
+
working-directory: \${{ runner.temp }}
|
|
142
|
+
run: '"$PW" install-deps chromium'
|
|
143
|
+
|
|
144
|
+
# Preview URL mode.
|
|
145
|
+
- name: Wait for the deploy preview
|
|
146
|
+
if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL != ''
|
|
147
|
+
continue-on-error: true
|
|
148
|
+
working-directory: \${{ runner.temp }}
|
|
149
|
+
run: '"$SW" ci wait --url "$SHAPEWALL_PREVIEW_URL" --timeout 600'
|
|
150
|
+
|
|
151
|
+
- name: Capture and compare (preview URL mode)
|
|
152
|
+
if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL != ''
|
|
153
|
+
continue-on-error: true
|
|
154
|
+
working-directory: \${{ runner.temp }}
|
|
155
|
+
run: '"$SW" ci capture-compare --config "$HEAD_DIR/shapewall.config.json" --base-url "$SHAPEWALL_BASE_URL" --head-url "$SHAPEWALL_PREVIEW_URL" --out "$OUT/result"'
|
|
156
|
+
|
|
157
|
+
# Build and serve mode: ci.start runs only here, because of --allow-start,
|
|
158
|
+
# in the checkout --checkout names.
|
|
159
|
+
- name: Capture the base branch (build and serve mode)
|
|
160
|
+
if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
|
|
161
|
+
continue-on-error: true
|
|
162
|
+
working-directory: \${{ runner.temp }}
|
|
163
|
+
run: '"$SW" ci capture --config "$HEAD_DIR/shapewall.config.json" --allow-start --checkout "$BASE_DIR" --out "$OUT/base"'
|
|
164
|
+
|
|
165
|
+
- name: Capture the pull request (build and serve mode)
|
|
166
|
+
if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
|
|
167
|
+
continue-on-error: true
|
|
168
|
+
working-directory: \${{ runner.temp }}
|
|
169
|
+
run: '"$SW" ci capture --config "$HEAD_DIR/shapewall.config.json" --allow-start --checkout "$HEAD_DIR" --out "$OUT/head"'
|
|
170
|
+
|
|
171
|
+
- name: Compare (build and serve mode)
|
|
172
|
+
if: steps.gate.outputs.enabled == 'true' && env.SHAPEWALL_PREVIEW_URL == ''
|
|
173
|
+
continue-on-error: true
|
|
174
|
+
working-directory: \${{ runner.temp }}
|
|
175
|
+
run: '"$SW" ci capture-compare --config "$HEAD_DIR/shapewall.config.json" --base-dir "$OUT/base" --head-dir "$OUT/head" --out "$OUT/result"'
|
|
176
|
+
|
|
177
|
+
# The comment job reads the config from here: it never checks out the pull request.
|
|
178
|
+
- name: Keep the config with the result
|
|
179
|
+
if: always() && steps.gate.outputs.enabled == 'true'
|
|
180
|
+
continue-on-error: true
|
|
181
|
+
run: mkdir -p "$OUT/result" && cp "$HEAD_DIR/shapewall.config.json" "$OUT/result/shapewall.config.json"
|
|
182
|
+
|
|
183
|
+
- name: Keep the images as a workflow artifact
|
|
184
|
+
id: upload
|
|
185
|
+
if: always() && steps.gate.outputs.enabled == 'true'
|
|
186
|
+
continue-on-error: true
|
|
187
|
+
uses: actions/upload-artifact@v4
|
|
188
|
+
with:
|
|
189
|
+
name: shapewall-ci
|
|
190
|
+
path: shapewall-ci/result
|
|
191
|
+
retention-days: 14
|
|
192
|
+
if-no-files-found: ignore
|
|
193
|
+
|
|
194
|
+
comment:
|
|
195
|
+
name: Shapewall comment
|
|
196
|
+
needs: shapewall
|
|
197
|
+
# No checkout and no code from the pull request: the result is data.
|
|
198
|
+
if: always() && needs.shapewall.outputs.enabled == 'true'
|
|
199
|
+
runs-on: ubuntu-latest
|
|
200
|
+
timeout-minutes: 10
|
|
201
|
+
# For "ci.images": "branch" (public repositories only) also set contents: write.
|
|
202
|
+
permissions:
|
|
203
|
+
contents: read
|
|
204
|
+
pull-requests: write
|
|
205
|
+
env:
|
|
206
|
+
SHAPEWALL: shapewall@${version}
|
|
207
|
+
steps:
|
|
208
|
+
- uses: actions/setup-node@v4
|
|
209
|
+
with:
|
|
210
|
+
node-version: 22
|
|
211
|
+
|
|
212
|
+
- name: Download the result
|
|
213
|
+
continue-on-error: true
|
|
214
|
+
uses: actions/download-artifact@v4
|
|
215
|
+
with:
|
|
216
|
+
name: shapewall-ci
|
|
217
|
+
path: \${{ runner.temp }}/shapewall-result
|
|
218
|
+
|
|
219
|
+
- name: Install Shapewall
|
|
220
|
+
working-directory: \${{ runner.temp }}
|
|
221
|
+
env:
|
|
222
|
+
NPM_CONFIG_USERCONFIG: /dev/null
|
|
223
|
+
run: |
|
|
224
|
+
mkdir -p shapewall-tools
|
|
225
|
+
cd shapewall-tools
|
|
226
|
+
printf '{ "private": true }\\n' > package.json
|
|
227
|
+
npm install --no-audit --no-fund --ignore-scripts --registry https://registry.npmjs.org/ "$SHAPEWALL"
|
|
228
|
+
echo "SW=$PWD/node_modules/.bin/shapewall" >> "$GITHUB_ENV"
|
|
229
|
+
|
|
230
|
+
- name: Comment on the pull request
|
|
231
|
+
continue-on-error: true
|
|
232
|
+
working-directory: \${{ runner.temp }}
|
|
233
|
+
env:
|
|
234
|
+
GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
|
|
235
|
+
ARTIFACT_URL: \${{ needs.shapewall.outputs.artifact-url }}
|
|
236
|
+
run: '"$SW" ci comment --config "$RUNNER_TEMP/shapewall-result/shapewall.config.json" --dir "$RUNNER_TEMP/shapewall-result" --artifact-url "$ARTIFACT_URL"'
|
|
237
|
+
`
|
|
238
|
+
}
|