@awarebydefault/display-case 1.0.0

package/src/checks/check.test.ts

@@ -0,0 +1,194 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { A11yViolation } from '../index'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import { a11yDetailLines, runChecks } from './check'
+
+const CLI = join(import.meta.dir, '..', 'cli.ts')
+
+/**
+ * `a11yDetailLines` turns a violation's per-node detail into the indented lines
+ * the CLI prints — the colour pair / element that makes a finding fixable. It's
+ * pure, so it's the one piece of the a11y output testable without a browser.
+ */
+describe('check: a11y detail formatting', () => {
+  test('color-contrast node renders the measured pair and threshold', () => {
+    const v: A11yViolation = {
+      id: 'color-contrast',
+      help: 'Elements must meet minimum color contrast ratio thresholds',
+      nodes: 1,
+      impact: 'serious',
+      details: [
+        {
+          target: 'span.dcui-eyebrow',
+          html: '<span class="dcui-eyebrow">Tweaks</span>',
+          contrast: {
+            foreground: '#8a8073',
+            background: '#ffffff',
+            ratio: 3.71,
+            required: 4.5,
+            fontSize: '12.0pt',
+            fontWeight: '400',
+          },
+        },
+      ],
+    }
+    expect(a11yDetailLines(v)).toEqual([
+      '      ↳ span.dcui-eyebrow  #8a8073 on #ffffff = 3.71:1 (need 4.5:1)  [12.0pt 400]',
+    ])
+  })
+
+  test('non-contrast node renders the element and first summary line', () => {
+    const v: A11yViolation = {
+      id: 'select-name',
+      help: 'Select element must have an accessible name',
+      nodes: 1,
+      impact: 'critical',
+      details: [
+        {
+          target: 'select.dcui-select-el',
+          html: '<select class="dcui-select-el">',
+          failureSummary: 'Fix any of the following:\n  Element has no name',
+        },
+      ],
+    }
+    expect(a11yDetailLines(v)).toEqual([
+      '      ↳ select.dcui-select-el  Fix any of the following:',
+    ])
+  })
+
+  test('caps the inline list and notes the remainder', () => {
+    const details = Array.from({ length: 10 }, (_, i) => ({
+      target: `x${i}`,
+      html: '',
+      contrast: {
+        foreground: '#000',
+        background: '#fff',
+        ratio: 1,
+        required: 4.5,
+      },
+    }))
+    const lines = a11yDetailLines({
+      id: 'color-contrast',
+      help: 'h',
+      nodes: 10,
+      impact: 'serious',
+      details,
+    })
+    expect(lines).toHaveLength(9)
+    expect(lines.at(-1)).toBe('      ↳ … +2 more node(s)')
+  })
+
+  test('a violation with no detail yields no lines', () => {
+    expect(
+      a11yDetailLines({
+        id: 'x',
+        help: 'h',
+        nodes: 1,
+        impact: null,
+      }),
+    ).toEqual([])
+  })
+})
+
+/**
+ * The structure (and token) phases are static: `runChecks` must not start the
+ * dev server for them, and the CLI must honor `check.defaultPhases`. These are
+ * the only render-free assertions we can make without booting a browser, so the
+ * a11y/visual phases are exercised by the e2e suite, not here.
+ */
+describe('check: structure phase wiring', () => {
+  const dirs: string[] = []
+  const setup = async (files: Record<string, string>) => {
+    const dir = await makeTempDir()
+    dirs.push(dir)
+    await writeFiles(dir, files)
+    return dir
+  }
+  afterEach(async () => {
+    while (dirs.length)
+      await rm(dirs.pop() as string, { recursive: true, force: true })
+  })
+
+  const AllRules = [
+    'case-placard-coverage',
+    'no-orphaned-placard-doc',
+    'primer-present-and-used',
+    'setup-present',
+    'config-paths-exist',
+    'levels-classified',
+    'cases-load',
+    'flow-transitions-resolve',
+    'flow-multi-step',
+    'unique-slugs',
+    'tweak-defaults-valid',
+    'atom-purity',
+    'no-downward-dependency',
+    'composes-lower-level',
+    'level-fit',
+  ]
+  // A config that enables only the named rules (others disabled), so the static
+  // run is deterministic and free of the noisy default-on rules.
+  const cfg = (enabled: string[]) => {
+    const rules = AllRules.map(
+      (id) => `'${id}': ${enabled.includes(id) ? '{}' : 'false'}`,
+    ).join(', ')
+    return `export default { title:'F', roots:['**/*.case.tsx'], check:{ structure:{ rules:{ ${rules} } } } }\n`
+  }
+  const runStructure = (dir: string) =>
+    runChecks(dir, {
+      structure: true,
+      tokens: false,
+      a11y: false,
+      visual: false,
+      ssr: false,
+      update: false,
+    })
+
+  test('structure-only run resolves without starting a server', async () => {
+    const dir = await setup({
+      'display-case.config.ts': cfg(['levels-classified']),
+      'X.case.tsx': `export default { component:'X', cases:{}, isFlow:false, level:'atom' }\n`,
+    })
+    // No port is passed; a structure-only run must not need or start the server.
+    expect(await runStructure(dir)).toBe(true)
+  })
+
+  test('structure-only run returns false on an error finding', async () => {
+    const dir = await setup({
+      'display-case.config.ts': cfg(['levels-classified']),
+      // Unclassified (no level) ⇒ an error-severity finding.
+      'X.case.tsx': `export default { component:'X', cases:{}, isFlow:false }\n`,
+    })
+    expect(await runStructure(dir)).toBe(false)
+  })
+
+  const cli = async (dir: string, args: string[]) => {
+    const proc = Bun.spawn(['bun', CLI, 'check', dir, ...args], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const [out, err] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ])
+    await proc.exited
+    return out + err
+  }
+
+  test('defaultPhases opts a phase out of the bare run but not the explicit one', async () => {
+    // Every phase opted out of the default run, so the bare `check` runs nothing
+    // (and never boots a browser). X is unclassified ⇒ structure errors when run.
+    const dir = await setup({
+      'display-case.config.ts':
+        `export default { title:'F', roots:['**/*.case.tsx'], ` +
+        `check:{ defaultPhases:{ tokens:false, a11y:false, visual:false, structure:false } } }\n`,
+      'X.case.tsx': `export default { component:'X', cases:{}, isFlow:false }\n`,
+    })
+    const bare = await cli(dir, [])
+    expect(bare).not.toContain('structure ✗')
+    const explicit = await cli(dir, ['--structure'])
+    expect(explicit).toContain('structure ✗')
+  })
+})

package/src/checks/check.ts

@@ -0,0 +1,473 @@
+import { mkdir } from 'node:fs/promises'
+import { dirname, extname, join, relative, resolve, sep } from 'node:path'
+import { Glob } from 'bun'
+import { componentClosures } from '../core/affected'
+import { baselineDir, cacheDir, resolveConfig } from '../core/discovery'
+import type { ManifestComponent } from '../core/manifest'
+import type {
+  A11yViolation,
+  CaseContext,
+  DiffFn,
+  DisplayCaseConfig,
+  RenderDriver,
+} from '../index'
+import { startDisplayCase } from '../server/server'
+import { checkSsr } from './ssr-check'
+import { checkStructure } from './structure-check'
+import { checkTokens } from './tokens-check'
+
+/**
+ * Headless a11y + visual-regression runner. The capture/audit driver and the
+ * image diff are pluggable (config `providers`); when unset, the built-in
+ * Playwright/axe + pixelmatch/pngjs defaults are imported lazily — so those
+ * packages are needed only when a default-backed check actually runs.
+ */
+
+const THEMES = ['light', 'dark'] as const
+const VIEWPORT_WIDTH = 1024
+
+const INSTALL_HINT =
+  'Visual/a11y checks need the default toolchain. Install it with ' +
+  '`bun add -d playwright @axe-core/playwright pixelmatch pngjs && bunx playwright install chromium` ' +
+  '(or run `display-case init --with-visual`), or set `providers.driver`/`providers.diff` in display-case.config.ts.'
+
+export interface CheckOptions {
+  a11y: boolean
+  visual: boolean
+  tokens: boolean
+  structure: boolean
+  /** Server-render every case and fail on any that can't pre-render. */
+  ssr: boolean
+  update: boolean
+  /** Treat structure warnings as errors (CLI `--strict`). */
+  strict?: boolean
+  /** Restrict the render phases (a11y/visual) to these component ids or globs. */
+  only?: string[]
+  /** Restrict the render phases to components whose import closure touches a
+   *  file changed since this git ref (CLI `--changed[=ref]`). */
+  changedRef?: string
+  port?: number
+}
+
+interface Target {
+  componentId: string
+  caseId: string
+  theme: (typeof THEMES)[number]
+  renderUrl: string
+}
+
+/** One scanned variant in the written a11y report (only failing variants). */
+interface A11yReportEntry {
+  component: string
+  case: string
+  theme: string
+  violations: A11yViolation[]
+}
+
+/** Cap on per-violation detail lines printed inline; the full set is always in
+ *  the written report. Keeps a noisy run's console readable. */
+const A11Y_DETAIL_CAP = 8
+
+/**
+ * Indented, human-readable detail lines for one violation: the failing element
+ * and, for colour-contrast, the exact measured pair and threshold — the data
+ * that makes a finding fixable without re-running a browser. Pure (no I/O) so
+ * the formatting is unit-tested.
+ */
+export function a11yDetailLines(v: A11yViolation): string[] {
+  const details = v.details ?? []
+  const lines = details.slice(0, A11Y_DETAIL_CAP).map((d) => {
+    const where = d.target || '(element)'
+    if (d.contrast) {
+      const c = d.contrast
+      const font = c.fontSize
+        ? `  [${c.fontSize}${c.fontWeight ? ` ${c.fontWeight}` : ''}]`
+        : ''
+      return `      ↳ ${where}  ${c.foreground} on ${c.background} = ${c.ratio}:1 (need ${c.required}:1)${font}`
+    }
+    const why = (d.failureSummary ?? '').split('\n')[0].trim()
+    return `      ↳ ${where}${why ? `  ${why}` : ''}`
+  })
+  if (details.length > A11Y_DETAIL_CAP) {
+    lines.push(`      ↳ … +${details.length - A11Y_DETAIL_CAP} more node(s)`)
+  }
+  return lines
+}
+
+async function resolveDriver(config: DisplayCaseConfig): Promise<RenderDriver> {
+  if (config.providers?.driver) return await config.providers.driver()
+  try {
+    const { createPlaywrightDriver } = await import(
+      './providers/playwright-driver'
+    )
+    return await createPlaywrightDriver()
+  } catch (err) {
+    throw new Error(
+      `${INSTALL_HINT}\n  (${err instanceof Error ? err.message : String(err)})`,
+    )
+  }
+}
+
+async function resolveDiff(config: DisplayCaseConfig): Promise<DiffFn> {
+  if (config.providers?.diff) return config.providers.diff
+  try {
+    const { pixelmatchDiff } = await import('./providers/pixelmatch-diff')
+    return pixelmatchDiff
+  } catch (err) {
+    throw new Error(
+      `${INSTALL_HINT}\n  (${err instanceof Error ? err.message : String(err)})`,
+    )
+  }
+}
+
+/**
+ * Absolute paths of files changed since `ref`, for `--changed` scoping. Unions
+ * the committed diff since the merge-base (`ref...HEAD`) with the working tree
+ * (`HEAD`), so a local run also sees staged/unstaged edits and CI sees the PR's
+ * commits. Returns an empty list when git is unavailable or `ref` can't be
+ * resolved (e.g. an over-shallow clone) — the caller treats "no changes" as
+ * "nothing affected".
+ */
+async function changedSince(pkgDir: string, ref: string): Promise<string[]> {
+  const top = await Bun.$`git -C ${pkgDir} rev-parse --show-toplevel`
+    .quiet()
+    .nothrow()
+  if (top.exitCode !== 0) return []
+  const root = top.stdout.toString().trim()
+  const names = new Set<string>()
+  for (const range of [`${ref}...HEAD`, 'HEAD']) {
+    const out = await Bun.$`git -C ${root} diff --name-only ${range}`
+      .quiet()
+      .nothrow()
+    if (out.exitCode !== 0) continue
+    for (const line of out.stdout.toString().split('\n')) {
+      if (line.trim()) names.add(resolve(root, line.trim()))
+    }
+  }
+  return [...names]
+}
+
+// Extensions whose change can alter a rendered case (markup, behaviour, style).
+const RENDER_EXTS = new Set(['.tsx', '.ts', '.jsx', '.js', '.css', '.mdx'])
+// Trees under the package that never feed a render (so a change there scopes to
+// nothing): docs, specs, the e2e suite, agent skills, build/CI tooling.
+const NON_RENDER_DIRS =
+  /^(\.github|\.claude|contributing|docs|e2e|skills|scripts|tools|node_modules)(\/|$)/
+
+/** Whether a changed file (absolute) can affect a rendered case. */
+function isRenderRelevant(file: string, pkgRoot: string): boolean {
+  if (file !== pkgRoot && !file.startsWith(pkgRoot + sep)) return false
+  const rel = relative(pkgRoot, file)
+  if (NON_RENDER_DIRS.test(rel)) return false
+  if (/\.(test|spec)\.[tj]sx?$/.test(rel) || /\.test-d\.ts$/.test(rel))
+    return false
+  if (rel.endsWith('.d.ts')) return false
+  return RENDER_EXTS.has(extname(file))
+}
+
+/**
+ * The components affected by the changes since `ref`. Render-irrelevant changes
+ * (docs, specs, tests, tooling) scope to nothing. A render-relevant change is
+ * attributed to a component when it lies in that component's import closure; a
+ * render-relevant change that *no* closure claims — globally-inlined component
+ * CSS, the render pipeline, shared source — conservatively affects every
+ * component, so a regression is never silently skipped.
+ */
+async function changedScope(
+  pkgDir: string,
+  ref: string,
+  comps: { id: string; caseFile: string }[],
+): Promise<Set<string>> {
+  const pkgRoot = resolve(pkgDir)
+  const changed = (await changedSince(pkgDir, ref)).filter((f) =>
+    isRenderRelevant(f, pkgRoot),
+  )
+  if (changed.length === 0) return new Set()
+  const closures = await componentClosures(comps)
+  const claimed = new Set<string>()
+  for (const files of closures.values()) for (const f of files) claimed.add(f)
+  // Any render-relevant change outside every closure ⇒ a global input changed.
+  if (changed.some((f) => !claimed.has(f))) {
+    return new Set(comps.map((c) => c.id))
+  }
+  const changedSet = new Set(changed)
+  const affected = new Set<string>()
+  for (const [id, files] of closures) {
+    for (const f of files) {
+      if (changedSet.has(f)) {
+        affected.add(id)
+        break
+      }
+    }
+  }
+  return affected
+}
+
+export async function runChecks(
+  pkgDir: string,
+  opts: CheckOptions,
+): Promise<boolean> {
+  const { config } = await resolveConfig(pkgDir)
+  const baselines = baselineDir(pkgDir, config)
+
+  // Token conformance is a static parse — run it first, with no browser/server.
+  let tokenViolations = 0
+  if (opts.tokens) {
+    const { violations } = await checkTokens(pkgDir)
+    tokenViolations = violations.length
+    for (const v of violations) {
+      const rel = v.file.startsWith(`${pkgDir}/`)
+        ? v.file.slice(pkgDir.length + 1)
+        : v.file
+      console.error(
+        `  tokens ✗ ${rel}:${v.line}:${v.column} unknown token ${v.token}${v.hadFallback ? ' (fallback does not excuse it)' : ''}`,
+      )
+    }
+  }
+
+  // Structure best-practice checks are also static — no browser/server.
+  let structureErrors = 0
+  let structureWarnings = 0
+  if (opts.structure) {
+    const { findings } = await checkStructure(pkgDir, { strict: opts.strict })
+    for (const f of findings) {
+      const rel = f.file.startsWith(`${pkgDir}/`)
+        ? f.file.slice(pkgDir.length + 1)
+        : f.file
+      const line = `  structure ${f.severity === 'error' ? '✗' : '⚠'} ${rel}: ${f.message} (${f.rule})`
+      if (f.severity === 'error') {
+        structureErrors++
+        console.error(line)
+      } else {
+        structureWarnings++
+        console.warn(line)
+      }
+    }
+  }
+
+  // SSR-safety is a static check too: render every case with `renderToString`
+  // (no browser, no server) and flag any that can't pre-render — a case that
+  // touches a browser-only API during render. Declared-`browserOnly` components
+  // are expected and skipped.
+  let ssrErrors = 0
+  if (opts.ssr) {
+    const { findings, declared } = await checkSsr(pkgDir)
+    for (const f of findings) {
+      ssrErrors++
+      const rel = f.file.startsWith(`${pkgDir}/`)
+        ? f.file.slice(pkgDir.length + 1)
+        : f.file
+      console.error(
+        `  ssr ✗ ${rel}: ${f.component}/${f.case} can't render before scripts (${f.error}). ` +
+          'Move browser APIs into effects/handlers, or declare the component browserOnly.',
+      )
+    }
+    if (declared)
+      console.log(`  ssr: ${declared} case(s) declared browser-only`)
+  }
+
+  const staticErrors = tokenViolations + structureErrors + ssrErrors
+
+  // The browser phases (a11y + visual) are the only ones needing a live render.
+  if (!opts.a11y && !opts.visual) {
+    const ok = staticErrors === 0
+    const warn = structureWarnings ? `, ${structureWarnings} warning(s)` : ''
+    console.log(
+      ok
+        ? `\n  ✓ checks passed${warn}`
+        : `\n  ✗ ${tokenViolations} token violation(s), ${structureErrors} structure error(s), ${ssrErrors} ssr error(s)${warn}`,
+    )
+    return ok
+  }
+
+  const server = await startDisplayCase(pkgDir, { port: opts.port ?? 0 })
+  const base = String(server.url).replace(/\/$/, '')
+  const manifest = await fetch(`${base}/manifest.json`).then((r) => r.json())
+
+  // Resolve the change-scope for the render phases. `null` means no scoping —
+  // every component is checked (the default). Otherwise it is the set of
+  // component ids to check; an empty set short-circuits before any browser work.
+  let scope: Set<string> | null = null
+  if (opts.only || opts.changedRef) {
+    const comps = (manifest.components as ManifestComponent[]).map((c) => ({
+      id: c.id,
+      caseFile: resolve(pkgDir, c.caseFile),
+    }))
+    const sets: Set<string>[] = []
+    if (opts.only) {
+      const globs = opts.only.map((g) => new Glob(g))
+      sets.push(
+        new Set(
+          comps
+            .filter((c) => globs.some((g) => g.match(c.id)))
+            .map((c) => c.id),
+        ),
+      )
+    }
+    if (opts.changedRef) {
+      sets.push(await changedScope(pkgDir, opts.changedRef, comps))
+    }
+    // Both flags present ⇒ a component must satisfy both (intersection).
+    scope = sets[0]
+    for (const s of sets.slice(1)) {
+      const next = new Set<string>()
+      for (const id of scope) if (s.has(id)) next.add(id)
+      scope = next
+    }
+    const basis = [
+      opts.only ? '--only' : null,
+      opts.changedRef ? `--changed=${opts.changedRef}` : null,
+    ]
+      .filter(Boolean)
+      .join(' + ')
+    console.log(
+      `  scope: ${scope.size} of ${comps.length} component(s) (${basis})`,
+    )
+    if (scope.size === 0) {
+      server.stop(true)
+      const ok = staticErrors === 0
+      const warn = structureWarnings ? `, ${structureWarnings} warning(s)` : ''
+      console.log(
+        ok
+          ? `\n  ✓ checks passed — no affected components${warn}`
+          : `\n  ✗ ${tokenViolations} token violation(s), ${structureErrors} structure error(s), ${ssrErrors} ssr error(s)${warn}`,
+      )
+      return ok
+    }
+  }
+
+  const targets: Target[] = []
+  for (const c of manifest.components) {
+    if (scope && !scope.has(c.id)) continue
+    for (const cs of c.cases) {
+      for (const theme of THEMES) {
+        targets.push({
+          componentId: c.id,
+          caseId: cs.id,
+          theme,
+          renderUrl: `${base}${cs.renderUrl}?theme=${theme}`,
+        })
+      }
+    }
+  }
+
+  // Shared scan parameters (also honored by the live in-app surface) so the
+  // panel and this gate agree on what counts as a violation. `enabled` is NOT
+  // consulted here — the gate runs whenever invoked.
+  const a11yThemes = config.a11y?.themes ?? THEMES
+  const a11yExclude = config.a11y?.exclude
+
+  const driver = await resolveDriver(config)
+  const diff = opts.visual ? await resolveDiff(config) : null
+
+  let a11yViolations = 0
+  let visualChanges = 0
+  let recorded = 0
+  const a11yReport: A11yReportEntry[] = []
+
+  try {
+    for (const t of targets) {
+      const ctx: CaseContext = {
+        componentId: t.componentId,
+        caseId: t.caseId,
+        theme: t.theme,
+        width: VIEWPORT_WIDTH,
+      }
+      const page = await driver.open(t.renderUrl, ctx)
+
+      if (opts.a11y && a11yThemes.includes(t.theme)) {
+        const violations = await page.audit({ exclude: a11yExclude })
+        if (violations.length) {
+          a11yReport.push({
+            component: t.componentId,
+            case: t.caseId,
+            theme: t.theme,
+            violations,
+          })
+        }
+        for (const v of violations) {
+          a11yViolations++
+          const sev = v.impact ? `${v.impact} ` : ''
+          console.error(
+            `  a11y ✗ ${t.componentId}/${t.caseId} [${t.theme}] ${sev}${v.id}: ${v.help} (${v.nodes} node(s))`,
+          )
+          for (const line of a11yDetailLines(v)) console.error(line)
+        }
+      }
+
+      if (opts.visual && diff) {
+        const shot = await page.screenshot()
+        const file = join(
+          baselines,
+          t.componentId,
+          `${t.caseId}.${t.theme}.png`,
+        )
+        if (opts.update || !(await Bun.file(file).exists())) {
+          await mkdir(dirname(file), { recursive: true })
+          await Bun.write(file, shot)
+          recorded++
+        } else {
+          const baseline = new Uint8Array(await Bun.file(file).arrayBuffer())
+          const res = await diff(
+            { baseline, actual: shot },
+            { ...ctx, baselinePath: file },
+          )
+          if (res.changed) {
+            visualChanges++
+            if (res.diffImage) {
+              await Bun.write(
+                file.replace(/\.png$/, '.diff.png'),
+                res.diffImage,
+              )
+            }
+            console.error(
+              `  visual ✗ ${t.componentId}/${t.caseId} [${t.theme}] differs from baseline`,
+            )
+          }
+        }
+      }
+
+      await page.dispose()
+    }
+  } finally {
+    await driver.close()
+    server.stop(true)
+  }
+
+  if (opts.visual && recorded) console.log(`  recorded ${recorded} baseline(s)`)
+
+  // Persist the full run (every failing variant, with per-node detail) so an
+  // agent or human can read the exact failing colours/elements later without
+  // re-running the browser. Written under the gitignored cache dir, overwriting
+  // the prior run; a clean run leaves an empty `results` so the file is current.
+  if (opts.a11y) {
+    const reportPath = join(cacheDir(pkgDir), 'a11y', 'last-check.json')
+    await mkdir(dirname(reportPath), { recursive: true })
+    await Bun.write(
+      reportPath,
+      `${JSON.stringify(
+        { scannedAt: Date.now(), total: a11yViolations, results: a11yReport },
+        null,
+        2,
+      )}\n`,
+    )
+    const rel = reportPath.startsWith(`${pkgDir}/`)
+      ? reportPath.slice(pkgDir.length + 1)
+      : reportPath
+    console.log(`  a11y detail → ${rel}${a11yViolations ? '' : ' (clean run)'}`)
+  }
+
+  const ok =
+    a11yViolations === 0 &&
+    visualChanges === 0 &&
+    tokenViolations === 0 &&
+    structureErrors === 0 &&
+    ssrErrors === 0
+  const warn = structureWarnings ? `, ${structureWarnings} warning(s)` : ''
+  console.log(
+    ok
+      ? `\n  ✓ checks passed${warn}`
+      : `\n  ✗ ${a11yViolations} a11y violation(s), ${visualChanges} visual change(s), ${tokenViolations} token violation(s), ${structureErrors} structure error(s), ${ssrErrors} ssr error(s)${warn}`,
+  )
+  return ok
+}