ReviewOS

also looking at this

stacks/analyticshq

Harden AnalyticsHQ release and dashboard quality

#52
Merged glennmichael123 wants to merge docs/bunpress-product-guide into main
34 files +1236 -340
scripts/validate-visual.tsadded+364-0
Changes to scripts/validate-visual.ts
@@ -0,0 +1,364 @@
1import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
2import { tmpdir } from 'node:os'
3import { join, resolve } from 'node:path'
4
5interface Viewport {
6 name: string
7 width: number
8 height: number
9 mobile: boolean
10}
11
12interface PageAudit {
13 contrast: string[]
14 focusable: number
15 imagesWithoutAlt: number
16 overflow: number
17 undersizedDashboardControls: string[]
18 wrappedDashboardValues: string[]
19 unresolved: boolean
20 unnamedControls: string[]
21}
22
23interface Pending {
24 reject: (error: Error) => void
25 resolve: (value: any) => void
26 timer: ReturnType<typeof setTimeout>
27}
28
29const DIST = resolve('dist')
30const SSR_OUTPUT = resolve('.output')
31const SSR_PAGES = resolve(SSR_OUTPUT, 'server/pages')
32const SSR_PUBLIC = resolve(SSR_OUTPUT, 'public')
33const OUTPUT = resolve('storage/logs/visual-contract')
34const VIEWPORTS: Viewport[] = [
35 { name: 'desktop', width: 1440, height: 1000, mobile: false },
36 { name: 'tablet', width: 768, height: 1024, mobile: false },
37 { name: 'mobile', width: 390, height: 844, mobile: true },
38]
39const THEMES = ['light', 'dark'] as const
40const ROUTE_CANDIDATES = [
41 '/',
42 '/login',
43 '/register',
44 '/dashboard',
45 '/dashboard/commshq',
46 '/reports',
47 '/projects',
48]
49
50function chromePath(): string {
51 const candidates = [
52 process.env.CHROME_PATH,
53 '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
54 '/usr/bin/google-chrome',
55 '/usr/bin/google-chrome-stable',
56 '/usr/bin/chromium',
57 '/usr/bin/chromium-browser',
58 ]
59 const found = candidates.find(candidate => candidate && existsSync(candidate))
60 if (!found) throw new Error('Chrome was not found. Set CHROME_PATH to a Chrome or Chromium executable.')
61 return found
62}
63
64async function waitFor<T>(read: () => Promise<T> | T, timeout = 12_000): Promise<T> {
65 const started = Date.now()
66 let value = await read()
67 while (!value && Date.now() - started < timeout) {
68 await Bun.sleep(100)
69 value = await read()
70 }
71 if (!value) throw new Error(`Timed out after ${timeout}ms`)
72 return value
73}
74
75class Cdp {
76 private id = 0
77 private pending = new Map<number, Pending>()
78
79 constructor(private socket: WebSocket) {
80 socket.addEventListener('message', (event) => {
81 const message = JSON.parse(String(event.data))
82 if (!message.id) return
83 const pending = this.pending.get(message.id)
84 if (!pending) return
85 this.pending.delete(message.id)
86 clearTimeout(pending.timer)
87 if (message.error) pending.reject(new Error(message.error.message))
88 else pending.resolve(message.result)
89 })
90 }
91
92 send(method: string, params: Record<string, any> = {}): Promise<any> {
93 const id = ++this.id
94 return new Promise((resolve, reject) => {
95 const timer = setTimeout(() => {
96 this.pending.delete(id)
97 reject(new Error(`Chrome command timed out: ${method}`))
98 }, 15_000)
99 this.pending.set(id, { reject, resolve, timer })
100 this.socket.send(JSON.stringify({ id, method, params }))
101 })
102 }
103
104 async evaluate<T>(expression: string): Promise<T> {
105 const result = await this.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true })
106 if (result.exceptionDetails)
107 throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text)
108 return result.result?.value as T
109 }
110}
111
112async function connect(url: string): Promise<Cdp> {
113 const socket = new WebSocket(url)
114 await new Promise<void>((resolve, reject) => {
115 socket.addEventListener('open', () => resolve(), { once: true })
116 socket.addEventListener('error', () => reject(new Error('Could not connect to Chrome')), { once: true })
117 })
118 return new Cdp(socket)
119}
120
121function routeName(route: string): string {
122 return route === '/' ? 'home' : route.slice(1).replaceAll('/', '-')
123}
124
125function routeFile(route: string): { kind: 'html' | 'ssr', path: string } | undefined {
126 if (existsSync(DIST)) {
127 const base = route === '/' ? join(DIST, 'index.html') : join(DIST, `${route.slice(1)}.html`)
128 if (existsSync(base)) return { kind: 'html', path: base }
129 const index = join(DIST, route.slice(1), 'index.html')
130 if (existsSync(index)) return { kind: 'html', path: index }
131 }
132
133 const name = route === '/' ? 'index' : route.slice(1).replaceAll('/', '-')
134 const compiled = join(SSR_PAGES, `${name}.compiled.json`)
135 return existsSync(compiled) ? { kind: 'ssr', path: compiled } : undefined
136}
137
138function pageResponse(page: { kind: 'html' | 'ssr', path: string }): Response {
139 if (page.kind === 'html') return new Response(Bun.file(page.path))
140 const compiled = JSON.parse(readFileSync(page.path, 'utf8')) as { html?: string }
141 return new Response(compiled.html || '', { headers: { 'content-type': 'text/html; charset=utf-8' } })
142}
143
144const auditExpression = `(() => {
145 const visible = element => {
146 const style = getComputedStyle(element)
147 const rect = element.getBoundingClientRect()
148 if (element.closest('details:not([open])') && element.tagName !== 'SUMMARY') return false
149 return style.display !== 'none' && style.visibility !== 'hidden' && Number(style.opacity) > 0
150 && rect.width > 0 && rect.height > 0
151 }
152 const label = element => {
153 if (element.getAttribute('aria-label')) return element.getAttribute('aria-label')
154 const labelledBy = element.getAttribute('aria-labelledby')
155 if (labelledBy && labelledBy.split(/\\s+/).some(id => document.getElementById(id)?.textContent?.trim())) return labelledBy
156 if (element.id && document.querySelector('label[for="' + CSS.escape(element.id) + '"]')?.textContent?.trim()) return element.id
157 if (element.closest('label')?.textContent?.trim()) return 'wrapped'
158 if (element.tagName === 'BUTTON' && element.textContent?.trim()) return 'text'
159 if (element.tagName === 'A' && element.textContent?.trim()) return 'text'
160 if (element.getAttribute('title')) return element.getAttribute('title')
161 return ''
162 }
163 const parseRgb = value => {
164 const match = value.match(/rgba?\\(([^)]+)\\)/)
165 if (!match) return null
166 const parts = match[1].split(/[ ,/]+/).filter(Boolean).map(Number)
167 if (parts.length < 3 || parts.some(Number.isNaN)) return null
168 return { r: parts[0], g: parts[1], b: parts[2], a: parts[3] ?? 1 }
169 }
170 const luminance = color => {
171 const channel = value => {
172 const normalized = value / 255
173 return normalized <= 0.03928 ? normalized / 12.92 : ((normalized + 0.055) / 1.055) ** 2.4
174 }
175 return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b)
176 }
177 const background = element => {
178 let current = element
179 while (current) {
180 const color = parseRgb(getComputedStyle(current).backgroundColor)
181 if (color && color.a >= 0.98) return color
182 current = current.parentElement
183 }
184 return { r: 255, g: 255, b: 255, a: 1 }
185 }
186 const controls = [...document.querySelectorAll('a[href], button, input:not([type="hidden"]), select, textarea')].filter(visible)
187 const dashboardControls = [...document.querySelectorAll('.site-switcher, .range-link, .range-tool, .chrome-btn, .ga-row, .goal-form input, .goal-form select, .goal-form button')].filter(visible)
188 const undersizedDashboardControls = dashboardControls.flatMap(element => {
189 const rect = element.getBoundingClientRect()
190 if (rect.width >= 44 && rect.height >= 44) return []
191 const name = element.getAttribute('aria-label') || element.textContent?.trim().replace(/\\s+/g, ' ').slice(0, 32) || element.tagName.toLowerCase()
192 return [name + ' (' + Math.round(rect.width) + 'x' + Math.round(rect.height) + ')']
193 })
194 const wrappedDashboardValues = [...document.querySelectorAll('.kpi-value')].filter(visible).flatMap(element => {
195 const rect = element.getBoundingClientRect()
196 const lineHeight = Number.parseFloat(getComputedStyle(element).lineHeight)
197 return rect.height > lineHeight * 1.5 || element.scrollWidth > element.clientWidth + 1
198 ? [element.textContent?.trim() || 'metric value']
199 : []
200 })
201 const unnamedControls = controls.filter(element => !label(element)).map(element => {
202 const identity = element.id ? '#' + element.id : element.getAttribute('name') ? '[name="' + element.getAttribute('name') + '"]' : ''
203 return element.tagName.toLowerCase() + identity
204 })
205 const contrast = []
206 const textElements = [...document.querySelectorAll('h1, h2, h3, h4, p, label, button, a, summary, span')]
207 for (const element of textElements) {
208 if (!visible(element) || !element.textContent?.trim()) continue
209 if (element.children.length && !['A', 'BUTTON', 'SUMMARY'].includes(element.tagName)) continue
210 const style = getComputedStyle(element)
211 const foreground = parseRgb(style.color)
212 const behind = background(element)
213 if (!foreground || foreground.a < 0.98) continue
214 const lighter = Math.max(luminance(foreground), luminance(behind))
215 const darker = Math.min(luminance(foreground), luminance(behind))
216 const ratio = (lighter + 0.05) / (darker + 0.05)
217 const large = Number.parseFloat(style.fontSize) >= 24 || (Number.parseFloat(style.fontSize) >= 18.66 && Number(style.fontWeight) >= 700)
218 if (ratio + 0.01 < (large ? 3 : 4.5)) {
219 const sample = element.textContent.trim().replace(/\\s+/g, ' ').slice(0, 42)
220 contrast.push(sample + ' (' + ratio.toFixed(2) + ':1)')
221 }
222 if (contrast.length >= 10) break
223 }
224 return {
225 contrast,
226 focusable: controls.length,
227 imagesWithoutAlt: [...document.images].filter(image => !image.hasAttribute('alt')).length,
228 overflow: Math.max(0, document.documentElement.scrollWidth - document.documentElement.clientWidth),
229 undersizedDashboardControls,
230 wrappedDashboardValues,
231 unresolved: document.body.innerText.includes('{⁠{') || document.body.innerText.includes('@if'),
232 unnamedControls,
233 }
234})()`
235
236const dashboardFixtureExpression = `(() => {
237 const fixture = document.createElement('section')
238 fixture.id = 'visual-dashboard-fixture'
239 fixture.setAttribute('aria-hidden', 'true')
240 fixture.style.cssText = 'position:absolute;left:1rem;top:0;width:calc(100vw - 2rem);opacity:0.001;pointer-events:none;z-index:-1'
241 const columns = Array.from({ length: 90 }, (_, index) => '<div class="relative flex-1 ga-col"><div class="ga-tip">Day ' + index + '</div></div>').join('')
242 fixture.innerHTML = '<select class="panel site-switcher" aria-label="Switch site"><option>example.com</option></select><a class="range-link" href="#">24h</a><button class="range-tool">Export</button><a class="chrome-btn" href="#">Account</a><a class="ga-row" href="#">Page row</a><form class="goal-form"><input aria-label="Goal name"></form><section class="grid grid-cols-2"><div class="px-5"><div class="kpi-label">Average visit time</div><div class="text-3xl kpi-value mono">27m 47s</div></div></section><div class="p-5 panel"><div class="relative h-44 w-full ga-chart"><div class="flex absolute inset-0">' + columns + '</div></div></div>'
243 document.body.appendChild(fixture)
244})()`
245
246async function main(): Promise<void> {
247 if (!existsSync(DIST) && !existsSync(SSR_PAGES))
248 throw new Error(`Built site not found at ${DIST} or ${SSR_OUTPUT}. Run bun run build first.`)
249 const routes = ROUTE_CANDIDATES.filter(route => routeFile(route))
250 if (routes.length < 3) throw new Error(`Expected at least three visual routes, found ${routes.join(', ') || 'none'}.`)
251
252 mkdirSync(OUTPUT, { recursive: true })
253 const server = Bun.serve({
254 hostname: '127.0.0.1',
255 port: 0,
256 fetch(request) {
257 const url = new URL(request.url)
258 const route = decodeURIComponent(url.pathname)
259 const page = routeFile(route)
260 if (page) return pageResponse(page)
261 const publicRoot = existsSync(DIST) ? DIST : SSR_PUBLIC
262 const asset = resolve(publicRoot, `.${route}`)
263 const file = asset.startsWith(`${publicRoot}/`) && existsSync(asset) ? asset : undefined
264 return file ? new Response(Bun.file(file)) : new Response('Not found', { status: 404 })
265 },
266 })
267 const profile = mkdtempSync(join(tmpdir(), 'hq-visual-'))
268 const chrome = Bun.spawn([
269 chromePath(),
270 '--headless=new',
271 '--remote-debugging-port=0',
272 `--user-data-dir=${profile}`,
273 '--no-first-run',
274 '--no-default-browser-check',
275 '--disable-background-networking',
276 '--disable-component-update',
277 '--disable-extensions',
278 '--hide-scrollbars',
279 '--no-sandbox',
280 'about:blank',
281 ], { stdout: 'ignore', stderr: 'ignore' })
282
283 const failures: string[] = []
284 let screenshots = 0
285 try {
286 const portFile = join(profile, 'DevToolsActivePort')
287 await waitFor(() => existsSync(portFile), 10_000)
288 const port = Number(readFileSync(portFile, 'utf8').split('\n')[0])
289 const targets = await waitFor(async () => {
290 const items = await fetch(`http://127.0.0.1:${port}/json/list`).then(response => response.json()).catch(() => [])
291 return Array.isArray(items) && items.length ? items : null
292 }) as Array<{ type: string, url: string, webSocketDebuggerUrl: string }>
293 const target = targets.find(item => item.type === 'page' && item.url === 'about:blank') || targets.find(item => item.type === 'page')
294 if (!target) throw new Error('Chrome did not expose a page target.')
295
296 const cdp = await connect(target.webSocketDebuggerUrl)
297 await cdp.send('Page.enable')
298 await cdp.send('Runtime.enable')
299 await cdp.send('Emulation.setScriptExecutionDisabled', { value: true })
300
301 for (const route of routes) {
302 for (const viewport of VIEWPORTS) {
303 await cdp.send('Emulation.setDeviceMetricsOverride', {
304 width: viewport.width,
305 height: viewport.height,
306 deviceScaleFactor: 1,
307 mobile: viewport.mobile,
308 })
309 await cdp.send('Page.navigate', { url: `http://127.0.0.1:${server.port}${route}` })
310 await waitFor(() => cdp.evaluate("document.readyState === 'complete'"))
311 await Bun.sleep(100)
312 for (const theme of THEMES) {
313 await cdp.evaluate(`(() => {
314 const theme = ${JSON.stringify(theme)}
315 document.documentElement.classList.toggle('dark', theme === 'dark')
316 document.documentElement.setAttribute('data-theme', theme)
317 document.documentElement.setAttribute('data-color-mode', theme)
318 document.documentElement.setAttribute('color-mode', theme)
319 })()`)
320 await Bun.sleep(500)
321 if (route === '/dashboard') await cdp.evaluate(dashboardFixtureExpression)
322 const audit = await cdp.evaluate<PageAudit>(auditExpression)
323 if (route === '/dashboard') await cdp.evaluate("document.getElementById('visual-dashboard-fixture')?.remove()")
324 const key = `${route} at ${viewport.name}/${theme}`
325 if (audit.overflow > 1) failures.push(`${key}: ${audit.overflow}px horizontal overflow`)
326 if (viewport.mobile && audit.undersizedDashboardControls.length)
327 failures.push(`${key}: undersized dashboard controls ${audit.undersizedDashboardControls.join(', ')}`)
328 if (viewport.mobile && audit.wrappedDashboardValues.length)
329 failures.push(`${key}: wrapped dashboard metric values ${audit.wrappedDashboardValues.join(', ')}`)
330 if (audit.unresolved) failures.push(`${key}: unresolved template expression is visible`)
331 if (audit.imagesWithoutAlt) failures.push(`${key}: ${audit.imagesWithoutAlt} image(s) have no alt attribute`)
332 if (audit.unnamedControls.length) failures.push(`${key}: unnamed controls ${audit.unnamedControls.join(', ')}`)
333 for (const issue of audit.contrast) failures.push(`${key}: low text contrast ${issue}`)
334
335 if (audit.focusable) {
336 await cdp.evaluate("document.body.setAttribute('tabindex', '-1'); document.body.focus()")
337 await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 })
338 await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 })
339 const focused = await cdp.evaluate("document.activeElement && document.activeElement !== document.body && document.activeElement !== document.documentElement")
340 if (!focused) failures.push(`${key}: Tab did not move focus to a control`)
341 }
342
343 const shot = await cdp.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: true, fromSurface: true })
344 writeFileSync(join(OUTPUT, `${routeName(route)}-${theme}-${viewport.name}.png`), Buffer.from(shot.data, 'base64'))
345 screenshots += 1
346 }
347 }
348 }
349 }
350 finally {
351 chrome.kill()
352 await chrome.exited
353 server.stop(true)
354 rmSync(profile, { force: true, recursive: true })
355 }
356
357 console.log(`Rendered ${routes.length} routes in ${THEMES.length} themes at ${VIEWPORTS.length} viewports and wrote ${screenshots} screenshots.`)
358 if (failures.length) {
359 for (const failure of failures) console.error(`- ${failure}`)
360 process.exit(1)
361 }
362}
363
364await main()