design-spine 0.1.0 → 0.2.0

package/src/lib/docker.ts

@@ -0,0 +1,196 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Matches package.json engines.bun and the pin in action.yml; a test keeps them in step.
+export const DOCKER_BUN_VERSION = '1.3.13'
+// GitHub's ubuntu-latest is x64, so captures must be too, even on Apple silicon.
+export const DOCKER_PLATFORM = 'linux/amd64'
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+export const imageTag = (playwrightVersion: string, bunVersion = DOCKER_BUN_VERSION): string =>
+  `design-spine-capture:${playwrightVersion}-bun${bunVersion}`
+
+export const dockerfileText = (
+  playwrightVersion: string,
+  bunVersion = DOCKER_BUN_VERSION,
+): string =>
+  `FROM mcr.microsoft.com/playwright:v${playwrightVersion}-noble
+COPY --from=oven/bun:${bunVersion} /usr/local/bin/bun /usr/local/bin/bun
+`
+
+/** Loopback hosts mean the host machine, which a container reaches as host.docker.internal. */
+export function rewriteBaseForDocker(base: string): string {
+  const url = new URL(base)
+  if (!LOOPBACK.has(url.hostname)) return base
+  url.hostname = 'host.docker.internal'
+  const out = url.href
+  const bare = url.pathname === '/' && !url.search && !url.hash
+  return bare && !base.endsWith('/') ? out.slice(0, -1) : out
+}
+
+export function installedPlaywrightVersion(): string {
+  const pkg = createRequire(import.meta.url)('playwright/package.json') as { version: string }
+  return pkg.version
+}
+
+export interface CliLocation {
+  /** Extra `-v` mount for a CLI that lives outside the project root. */
+  mounts: string[]
+  /** CLI path as seen inside the container. */
+  path: string
+}
+
+export function locateCli(root: string, cliFile: string, packageDir: string): CliLocation {
+  const rel = relative(root, cliFile)
+  if (rel && !rel.startsWith('..') && !isAbsolute(rel))
+    return { mounts: [], path: `/work/${rel.split(sep).join('/')}` }
+  return {
+    mounts: ['-v', `${packageDir}:/spine:ro`],
+    path: `/spine/${relative(packageDir, cliFile).split(sep).join('/')}`,
+  }
+}
+
+export interface InnerCapture {
+  manifest: string
+  base: string
+  routes?: string
+  concurrency: string
+}
+
+export function innerCaptureArgs(o: InnerCapture): string[] {
+  return [
+    'capture',
+    '--manifest',
+    o.manifest,
+    '--base',
+    o.base,
+    ...(o.routes ? ['--routes', o.routes] : []),
+    '--concurrency',
+    o.concurrency,
+  ]
+}
+
+export interface RunArgvInput {
+  image: string
+  root: string
+  cli: CliLocation
+  recordedBase: string
+  inner: string[]
+  /** Set on Linux hosts so files written into the project stay owned by the caller. */
+  user?: { uid: number; gid: number }
+  /**
+   * Linux hosts share the host network, so an app bound only to localhost (the usual CI
+   * setup) is reachable without rewriting the URL. Docker Desktop and OrbStack use
+   * host.docker.internal instead.
+   */
+  hostNetwork?: boolean
+}
+
+export function dockerRunArgv(i: RunArgvInput): string[] {
+  return [
+    'run',
+    '--rm',
+    '--platform',
+    DOCKER_PLATFORM,
+    '--init',
+    '--ipc=host',
+    ...(i.user ? ['--user', `${i.user.uid}:${i.user.gid}`, '-e', 'HOME=/tmp'] : []),
+    '-v',
+    `${i.root}:/work`,
+    ...i.cli.mounts,
+    '-w',
+    '/work',
+    ...(i.hostNetwork ? ['--network', 'host'] : ['--add-host=host.docker.internal:host-gateway']),
+    '-e',
+    'PLAYWRIGHT_BROWSERS_PATH=/ms-playwright',
+    '-e',
+    'SPINE_CWD=/work',
+    // The run keeps the URL the host used, so review and reports read the same as a host capture.
+    '-e',
+    `SPINE_RECORDED_BASE_URL=${i.recordedBase}`,
+    '-e',
+    `SPINE_HOST_ROOT=${i.root}`,
+    i.image,
+    'bun',
+    i.cli.path,
+    ...i.inner,
+  ]
+}
+
+function docker(args: string[], opts: { input?: string; quiet?: boolean } = {}) {
+  return spawnSync('docker', args, {
+    input: opts.input,
+    stdio: [
+      opts.input === undefined ? 'ignore' : 'pipe',
+      opts.quiet ? 'ignore' : 'inherit',
+      'inherit',
+    ],
+  })
+}
+
+export function assertDockerReady(): void {
+  const info = spawnSync('docker', ['info'], { stdio: 'ignore' })
+  if ((info.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT')
+    throw new Error('--docker needs the docker CLI, but `docker` is not on PATH.')
+  if (info.status !== 0)
+    throw new Error(
+      '--docker needs a running Docker daemon, but `docker info` failed. Start Docker or OrbStack.',
+    )
+}
+
+export function ensureImage(playwrightVersion: string, log: (s: string) => void): string {
+  const tag = imageTag(playwrightVersion)
+  if (docker(['image', 'inspect', tag], { quiet: true }).status === 0) return tag
+  log(`Building ${tag} (${DOCKER_PLATFORM}), first run only...`)
+  const built = docker(['build', '--platform', DOCKER_PLATFORM, '-t', tag, '-'], {
+    input: dockerfileText(playwrightVersion),
+  })
+  if (built.status !== 0) throw new Error(`docker build failed for ${tag}.`)
+  return tag
+}
+
+export interface DockerCapture extends InnerCapture {
+  root: string
+  /** Base URL as the host sees it, before the loopback rewrite. */
+  hostBase: string
+  log: (s: string) => void
+}
+
+/** Runs `spine capture` inside the pinned Playwright image and resolves to its exit code. */
+export async function captureInDocker(o: DockerCapture): Promise<number> {
+  assertDockerReady()
+  const image = ensureImage(installedPlaywrightVersion(), o.log)
+  const cliFile = realpathSync(fileURLToPath(new URL('../cli.ts', import.meta.url)))
+  const root = realpathSync(o.root)
+  const cli = locateCli(root, cliFile, dirname(dirname(cliFile)))
+  const getuid = process.getuid?.()
+  const linux = process.platform === 'linux'
+  const argv = dockerRunArgv({
+    image,
+    root,
+    cli,
+    recordedBase: o.hostBase,
+    inner: innerCaptureArgs({ ...o, base: linux ? o.base : rewriteBaseForDocker(o.base) }),
+    hostNetwork: linux,
+    user:
+      linux && getuid !== undefined
+        ? { uid: getuid, gid: process.getgid?.() ?? getuid }
+        : undefined,
+  })
+  return await new Promise<number>((done, fail) => {
+    const child = spawn('docker', argv, { stdio: 'inherit' })
+    child.on('error', fail)
+    child.on('close', (code) => done(code ?? 1))
+  })
+}
+
+/** Manifest path relative to the project root, since the container sees the root as /work. */
+export function manifestInRoot(root: string, manifest: string): string {
+  const rel = relative(root, resolve(root, manifest))
+  if (!rel || rel.startsWith('..') || isAbsolute(rel))
+    throw new Error('--docker needs the manifest inside the project root.')
+  return rel.split(sep).join('/')
+}

package/src/lib/routes.ts

@@ -170,6 +170,8 @@ export function draftManifest(
     baseUrl,
     viewports: [390, 1280],
     themes: { light: 'light', dark: 'dark', method: 'localStorage', key: 'theme' },
+    // Motion and unsettled pages are the main source of false diffs; start stable.
+    capture: { animations: 'disabled', stabilityAttempts: 3 },
     initScripts: [],
     routes,
   }

package/src/lib/server.ts

@@ -3,6 +3,8 @@ import { readFileSync, realpathSync } from 'node:fs'
 import { basename, join, resolve, sep } from 'node:path'
 import { PNG } from 'pngjs'
 import UI_PATH from '../ui/index.html' with { type: 'file' }
+import UI_CSS from '../ui/review.css' with { type: 'file' }
+import UI_JS from '../ui/review.js' with { type: 'file' }
 import { buildComparisonAsync } from './comparison.ts'
 import { listRuns, selectRun } from './history.ts'
 import { buildReport } from './report.ts'
@@ -30,6 +32,18 @@ export function startReviewServer(initialRunDir: string, port: number) {
         headers: { 'content-type': 'text/html; charset=utf-8' },
       })
     }
+    if (
+      req.method === 'GET' &&
+      ['/assets/review.css', '/assets/review.js'].includes(url.pathname)
+    ) {
+      const css = url.pathname.endsWith('.css')
+      return new Response(Bun.file(String(css ? UI_CSS : UI_JS)), {
+        headers: {
+          'content-type': css ? 'text/css; charset=utf-8' : 'text/javascript; charset=utf-8',
+          'cache-control': 'no-cache',
+        },
+      })
+    }
     if (req.method === 'GET' && url.pathname === '/api/report') {
       try {
         return new Response(buildReport(runDir, loadRun(runDir), loadReview(runDir)), {

package/src/lib/summary.ts

@@ -0,0 +1,70 @@
+export const SUMMARY_MARKER = '<!-- design-spine -->'
+export const SUMMARY_ROW_CAP = 50
+
+export interface SummaryInput {
+  rows: { id: string; result: string; ratio: string }[]
+  threshold: number
+  policy: string
+  gateReasons: string[]
+  /** Number of failures the CLI counted; it decides pass or fail. */
+  failed: number
+  /** Where reviewers find the full report. */
+  reportArtifact?: string
+}
+
+const RESULTS = [
+  'ok',
+  'CHANGED',
+  'new',
+  'size-changed',
+  'no-capture',
+  'modified-capture',
+  'modified-baseline',
+  'unreadable',
+]
+
+/** Ids and reasons come from user manifests, so neutralise Markdown and HTML. */
+export function escapeMarkdown(text: string): string {
+  return text
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[&\\|<>`]/g, (c) =>
+      c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : `\\${c}`,
+    )
+}
+
+export function buildSummary(input: SummaryInput): string {
+  const { rows, failed } = input
+  const counts = new Map<string, number>()
+  for (const r of rows) counts.set(r.result, (counts.get(r.result) ?? 0) + 1)
+  const kinds = [...RESULTS, ...[...counts.keys()].filter((k) => !RESULTS.includes(k))]
+  const parts = kinds
+    .filter((k) => (counts.get(k) ?? 0) > 0 || k === 'ok')
+    .map((k) => `${counts.get(k) ?? 0} ${escapeMarkdown(k)}`)
+  const lines = [
+    SUMMARY_MARKER,
+    `## Design Spine: ${failed ? 'failed' : 'passed'}`,
+    '',
+    `${rows.length} tiles (${parts.join(', ')}). Policy: ${escapeMarkdown(input.policy)}, threshold ${input.threshold}.`,
+    '',
+  ]
+  const shown = rows.filter((r) => r.result !== 'ok')
+  if (shown.length) {
+    lines.push('| Tile | Result | Ratio |', '| --- | --- | --- |')
+    for (const r of shown.slice(0, SUMMARY_ROW_CAP))
+      lines.push(
+        `| ${escapeMarkdown(r.id)} | ${escapeMarkdown(r.result)} | ${escapeMarkdown(r.ratio)} |`,
+      )
+    if (shown.length > SUMMARY_ROW_CAP) lines.push('', `and ${shown.length - SUMMARY_ROW_CAP} more`)
+    lines.push('')
+  }
+  if (input.gateReasons.length) {
+    lines.push('Strict gate reasons:', '')
+    for (const reason of input.gateReasons) lines.push(`- ${escapeMarkdown(reason)}`)
+    lines.push('')
+  }
+  lines.push(
+    `Full report with screenshots: download the \`${input.reportArtifact ?? 'design-spine-report'}\` artifact from this run.`,
+    '',
+  )
+  return lines.join('\n')
+}