@awarebydefault/display-case 1.0.0

package/src/checks/providers/pixelmatch-diff.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test'
+import { PNG } from 'pngjs'
+import type { CaseContext, DiffResult } from '../../index'
+import { pixelmatchDiff } from './pixelmatch-diff'
+
+// The built-in diff is identity-agnostic, but DiffFn requires the case context;
+// pass a stub and treat the (synchronous) result as a resolved DiffResult.
+const CTX: CaseContext & { baselinePath: string } = {
+  componentId: 'button',
+  caseId: 'default',
+  theme: 'light',
+  width: 320,
+  baselinePath: 'baseline.png',
+}
+const diff = (baseline: Uint8Array, actual: Uint8Array): DiffResult =>
+  pixelmatchDiff({ baseline, actual }, CTX) as DiffResult
+
+/** A solid-colour PNG of the given size, encoded to file bytes. */
+function solidPng(
+  width: number,
+  height: number,
+  rgba: [number, number, number, number],
+): Buffer {
+  const png = new PNG({ width, height })
+  for (let i = 0; i < png.data.length; i += 4) {
+    png.data[i] = rgba[0]
+    png.data[i + 1] = rgba[1]
+    png.data[i + 2] = rgba[2]
+    png.data[i + 3] = rgba[3]
+  }
+  return PNG.sync.write(png)
+}
+
+/** A white PNG with one pixel (0,0) flipped to black. */
+function spottedPng(width: number, height: number): Buffer {
+  const png = new PNG({ width, height })
+  for (let i = 0; i < png.data.length; i += 4) {
+    png.data[i] = 255
+    png.data[i + 1] = 255
+    png.data[i + 2] = 255
+    png.data[i + 3] = 255
+  }
+  png.data[0] = 0
+  png.data[1] = 0
+  png.data[2] = 0
+  return PNG.sync.write(png)
+}
+
+describe('pixelmatchDiff', () => {
+  test('reports no change for identical images', () => {
+    const result = diff(
+      solidPng(4, 4, [255, 255, 255, 255]),
+      solidPng(4, 4, [255, 255, 255, 255]),
+    )
+    expect(result.changed).toBe(false)
+    expect(result.mismatch).toBe(0)
+  })
+
+  test('reports a change with a count and a diff image when pixels differ', () => {
+    const result = diff(solidPng(4, 4, [255, 255, 255, 255]), spottedPng(4, 4))
+    expect(result.changed).toBe(true)
+    expect(result.mismatch).toBeGreaterThan(0)
+    expect(result.diffImage).toBeDefined()
+    // The diff image is itself a valid PNG.
+    expect(() =>
+      PNG.sync.read(Buffer.from(result.diffImage as Uint8Array)),
+    ).not.toThrow()
+  })
+
+  test('treats a size mismatch as changed without diffing pixels', () => {
+    const result = diff(
+      solidPng(4, 4, [255, 255, 255, 255]),
+      solidPng(8, 8, [255, 255, 255, 255]),
+    )
+    expect(result.changed).toBe(true)
+    expect(result.mismatch).toBeUndefined()
+    expect(result.diffImage).toBeUndefined()
+  })
+})

package/src/checks/providers/pixelmatch-diff.ts

@@ -0,0 +1,30 @@
+import pixelmatch from 'pixelmatch'
+import { PNG } from 'pngjs'
+import type { DiffFn } from '../../index'
+
+/**
+ * Built-in image diff: pixelmatch + pngjs. Imported lazily by the check runner
+ * only when no custom diff is configured, so `pixelmatch` and `pngjs` stay
+ * optional dependencies. A size mismatch counts as changed; otherwise any
+ * differing pixel (above a small per-pixel threshold) counts as changed, and a
+ * diff image is returned for the runner to write next to the baseline.
+ */
+
+const PER_PIXEL_THRESHOLD = 0.1
+const DIFF_THRESHOLD = 0 // allowed differing pixels before a case counts as changed
+
+export const pixelmatchDiff: DiffFn = ({ baseline, actual }) => {
+  const a = PNG.sync.read(Buffer.from(baseline))
+  const b = PNG.sync.read(Buffer.from(actual))
+  if (a.width !== b.width || a.height !== b.height) {
+    return { changed: true }
+  }
+  const diff = new PNG({ width: a.width, height: a.height })
+  const mismatch = pixelmatch(a.data, b.data, diff.data, a.width, a.height, {
+    threshold: PER_PIXEL_THRESHOLD,
+  })
+  if (mismatch > DIFF_THRESHOLD) {
+    return { changed: true, mismatch, diffImage: PNG.sync.write(diff) }
+  }
+  return { changed: false, mismatch }
+}

package/src/checks/providers/playwright-driver.ts

@@ -0,0 +1,104 @@
+import { AxeBuilder } from '@axe-core/playwright'
+import { chromium } from 'playwright'
+import type {
+  A11yImpact,
+  A11yNodeDetail,
+  AuditOptions,
+  CaseContext,
+  RenderDriver,
+  RenderedPage,
+} from '../../index'
+
+/** The first numeric run in axe's `expectedContrastRatio` (e.g. `"4.5:1"` → 4.5). */
+function parseRatio(value: unknown): number {
+  const m = /[\d.]+/.exec(String(value ?? ''))
+  return m ? Number(m[0]) : 0
+}
+
+/** Flatten one axe node into our serializable detail: the element + (for
+ *  colour-contrast) the measured pair, so the cache/CLI carry actionable data. */
+function nodeDetail(node: {
+  target?: unknown[]
+  html?: string
+  failureSummary?: string
+  any?: { id: string; data?: unknown }[]
+  all?: { id: string; data?: unknown }[]
+  none?: { id: string; data?: unknown }[]
+}): A11yNodeDetail {
+  const detail: A11yNodeDetail = {
+    target: (node.target ?? []).map((t) => String(t)).join(' '),
+    html: (node.html ?? '').slice(0, 200),
+  }
+  if (node.failureSummary) detail.failureSummary = node.failureSummary
+  const cc = [
+    ...(node.any ?? []),
+    ...(node.all ?? []),
+    ...(node.none ?? []),
+  ].find((c) => c.id === 'color-contrast')
+  const d = cc?.data as Record<string, unknown> | undefined
+  if (d && (d.fgColor || d.bgColor)) {
+    detail.contrast = {
+      foreground: String(d.fgColor),
+      background: String(d.bgColor),
+      ratio: Number(d.contrastRatio),
+      required: parseRatio(d.expectedContrastRatio),
+    }
+    if (d.fontSize) detail.contrast.fontSize = String(d.fontSize)
+    if (d.fontWeight) detail.contrast.fontWeight = String(d.fontWeight)
+  }
+  return detail
+}
+
+/**
+ * Built-in render driver: Playwright Chromium + axe-core. Imported lazily by the
+ * check runner only when no custom driver is configured, so `playwright` and
+ * `@axe-core/playwright` stay optional dependencies.
+ *
+ * Reproduces the previous runner behavior: a fixed 1024×768 viewport, reduced
+ * motion, a wait for the network to settle and fonts to load, and a WCAG 2 A/AA
+ * audit (page-structure best-practice rules are out of scope for fragments).
+ */
+
+const VIEWPORT = { width: 1024, height: 768 }
+const WCAG_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']
+
+export async function createPlaywrightDriver(): Promise<RenderDriver> {
+  const browser = await chromium.launch()
+  const context = await browser.newContext({
+    viewport: VIEWPORT,
+    reducedMotion: 'reduce',
+  })
+
+  return {
+    async open(url: string, _ctx: CaseContext): Promise<RenderedPage> {
+      const page = await context.newPage()
+      await page.goto(url, { waitUntil: 'networkidle' })
+      await page.evaluate(() => document.fonts.ready)
+      return {
+        async screenshot() {
+          return page.screenshot()
+        },
+        async audit(opts?: AuditOptions) {
+          let builder = new AxeBuilder({ page }).withTags(WCAG_TAGS)
+          if (opts?.exclude?.length)
+            builder = builder.disableRules(opts.exclude)
+          const { violations } = await builder.analyze()
+          return violations.map((v) => ({
+            id: v.id,
+            help: v.help,
+            nodes: v.nodes.length,
+            // axe's impact is a string union or null/undefined; normalize.
+            impact: (v.impact ?? null) as A11yImpact | null,
+            details: v.nodes.map(nodeDetail),
+          }))
+        },
+        async dispose() {
+          await page.close()
+        },
+      }
+    },
+    async close() {
+      await browser.close()
+    },
+  }
+}

package/src/checks/ssr-check.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import { checkSsr } from './ssr-check'
+
+// Case fixtures import the real authoring helpers by absolute path so they load
+// from a temp dir outside the workspace's module resolution.
+const DC = join(import.meta.dir, '..', 'index.ts')
+const caseFile = (body: string) =>
+  `import { defineCases } from '${DC}'\nexport default ${body}\n`
+
+const CONFIG = `export default { title: 'F', roots: ['**/*.case.tsx'] }\n`
+
+describe('checkSsr', () => {
+  const dirs: string[] = []
+  const setup = async (files: Record<string, string>) => {
+    const dir = await makeTempDir()
+    dirs.push(dir)
+    await writeFiles(dir, { 'display-case.config.ts': CONFIG, ...files })
+    return dir
+  }
+  afterEach(async () => {
+    while (dirs.length)
+      await rm(dirs.pop() as string, { recursive: true, force: true })
+  })
+
+  test('a case that renders purely passes', async () => {
+    const dir = await setup({
+      'Plain.case.tsx': caseFile(
+        `defineCases('Plain', { Default: () => 'hi' }, { level: 'atom' })`,
+      ),
+    })
+    const { findings, rendered, declared } = await checkSsr(dir)
+    expect(findings).toHaveLength(0)
+    expect(rendered).toBe(1)
+    expect(declared).toBe(0)
+  })
+
+  test('a case that touches a browser API during render is flagged', async () => {
+    const dir = await setup({
+      'Widget.case.tsx': caseFile(
+        `defineCases('Widget', { Win: () => String(window.innerWidth) }, { level: 'atom' })`,
+      ),
+    })
+    const { findings } = await checkSsr(dir)
+    expect(findings).toHaveLength(1)
+    expect(findings[0].component).toBe('Widget')
+    expect(findings[0].case).toBe('Win')
+    expect(findings[0].error).toMatch(/window/)
+    expect(findings[0].file).toMatch(/Widget\.case\.tsx$/)
+  })
+
+  // The complementary property — a browser API used in an *effect* or *handler*
+  // (which never runs on the server) must NOT be flagged — is covered by the
+  // dogfood `ssr` check passing: SelectMenu/TweaksPanel/RenderAddress all reach
+  // for `window`/`getComputedStyle`/`navigator` inside effects and handlers, and
+  // every dogfood case renders server-side cleanly. (It can't be unit-fixtured
+  // here: a hook-using component needs a `react` import, which a temp-dir fixture
+  // outside the workspace can't resolve.)
+
+  test('a component declared browserOnly is skipped, not flagged', async () => {
+    const dir = await setup({
+      'Widget.case.tsx': caseFile(
+        `defineCases('Widget', { Win: () => String(window.innerWidth) }, { level: 'atom', browserOnly: true })`,
+      ),
+    })
+    const { findings, rendered, declared } = await checkSsr(dir)
+    expect(findings).toHaveLength(0)
+    expect(rendered).toBe(0)
+    expect(declared).toBe(1)
+  })
+})

package/src/checks/ssr-check.ts

@@ -0,0 +1,96 @@
+import { renderToString } from 'react-dom/server'
+import { buildCatalog } from '../core/catalog'
+import {
+  discoverCaseFiles,
+  loadModules,
+  resolveConfig,
+} from '../core/discovery'
+import { caseTree, NOOP_GOTO } from '../render/render-node'
+
+/**
+ * The `ssr` check: render every case on the server (`renderToString`, no
+ * browser) and flag any that can't — i.e. that touch a browser-only API
+ * *during render* and throw. This enforces the pre-scripting-rendering best
+ * practice: keep a case's render pure (browser APIs belong in effects and
+ * handlers, which never run on the server). It is the precise, zero-false-
+ * positive counterpart to a static "no browser APIs" lint, because it tests the
+ * one thing that matters — does this case pre-render? — rather than guessing
+ * from syntax whether a `window` reference sits in render or in an effect.
+ *
+ * A component declared `browserOnly` (in its case meta) is expected to need a
+ * browser; its cases are counted as declared, not flagged. The check is static
+ * in spirit (no server, no browser) and runs in the one-shot check process, so
+ * a bare module import is always current.
+ */
+
+export interface SsrFinding {
+  /** Absolute path of the case file the finding is attributed to. */
+  file: string
+  /** Showcased component display name. */
+  component: string
+  /** Case display name. */
+  case: string
+  /** The throw's message (what browser API the render reached). */
+  error: string
+}
+
+export interface SsrCheckResult {
+  findings: SsrFinding[]
+  /** Cases that rendered on the server cleanly. */
+  rendered: number
+  /** Cases skipped because their component is declared `browserOnly`. */
+  declared: number
+}
+
+export async function checkSsr(pkgDir: string): Promise<SsrCheckResult> {
+  const { config } = await resolveConfig(pkgDir)
+  const files = await discoverCaseFiles(pkgDir, config)
+  const { modules } = await loadModules(files)
+
+  // Map a component's display name to its source file and its declared
+  // browser-only flag, so a finding can point at the file and declared
+  // components can be skipped.
+  const byName = new Map(modules.map((m) => [m.module.component, m]))
+  const caseModules = modules.map((m) => m.module)
+  const catalog = buildCatalog(caseModules)
+
+  const findings: SsrFinding[] = []
+  let rendered = 0
+  let declared = 0
+
+  for (const component of catalog) {
+    const loaded = byName.get(component.name)
+    if (!loaded) continue
+    if (loaded.module.browserOnly) {
+      declared += component.cases.length
+      continue
+    }
+    for (const cs of component.cases) {
+      try {
+        renderToString(
+          caseTree(
+            caseModules,
+            config,
+            {
+              componentId: component.id,
+              caseId: cs.id,
+              width: null,
+              tweaks: {},
+            },
+            NOOP_GOTO,
+          ),
+        )
+        rendered++
+      } catch (err) {
+        findings.push({
+          file: loaded.file,
+          component: component.name,
+          case: cs.name,
+          error: err instanceof Error ? err.message : String(err),
+        })
+      }
+    }
+  }
+
+  return { findings, rendered, declared }
+}

package/src/checks/structure-check.cross-package.test.ts

@@ -0,0 +1,165 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { mkdir, rm, symlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { HierarchyLevel, StructureRuleId } from '../index'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import { checkStructure } from './structure-check'
+
+/**
+ * Full cross-package coverage for the composition level-resolver.
+ *
+ * Each test builds two dummy Display-Case "repositories" in a temp dir — a
+ * shared library and a consumer app — and links the library into the app's
+ * `node_modules` so the bare specifier `@dc-fixture/lib` resolves exactly as it
+ * would in a real workspace. The app's component imports from the library, so
+ * the resolver must (1) resolve the bare specifier to the library package, (2)
+ * recognize it as a showcase, (3) follow its barrel re-export to the component
+ * file, and (4) read that component's declared level. Raw case-module objects
+ * are used so the fixtures need no `display-case` import to load.
+ */
+
+const ALL_RULES: StructureRuleId[] = [
+  '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',
+]
+
+// App config enabling only the rule under test (so cross-package findings are
+// isolated from the default-on rules the bare fixtures would otherwise trip).
+const appConfig = (rule: StructureRuleId) => {
+  const rules = ALL_RULES.map(
+    (id) => `'${id}': ${id === rule ? '{}' : 'false'}`,
+  ).join(', ')
+  return `export default { title:'App', roots:['src/**/*.case.tsx'], check:{ structure:{ rules:{ ${rules} } } } }\n`
+}
+
+const caseModule = (component: string, level: HierarchyLevel) =>
+  `export default { component:'${component}', cases:{}, isFlow:false, level:'${level}' }\n`
+
+interface ReposOpts {
+  libLevel: HierarchyLevel
+  appLevel: HierarchyLevel
+  /** 'named' ⇒ followable `export { X } from`; 'star' ⇒ unfollowable `export *`. */
+  barrel: 'named' | 'star'
+  rule: StructureRuleId
+}
+
+describe('checkStructure cross-package resolution', () => {
+  const dirs: string[] = []
+
+  // Build the lib + app repos and link lib into app/node_modules. Returns appDir.
+  const setupRepos = async (o: ReposOpts): Promise<string> => {
+    const root = await makeTempDir()
+    dirs.push(root)
+    const libDir = join(root, 'lib')
+    const appDir = join(root, 'app')
+
+    const barrel =
+      o.barrel === 'named'
+        ? `export { LibThing } from './thing'\n`
+        : `export * from './thing'\n`
+
+    await writeFiles(libDir, {
+      'package.json': JSON.stringify({
+        name: '@dc-fixture/lib',
+        type: 'module',
+        main: './src/index.ts',
+        exports: { '.': './src/index.ts' },
+      }),
+      'display-case.config.ts': `export default { title:'Lib', roots:['src/**/*.case.tsx'] }\n`,
+      'src/index.ts': barrel,
+      'src/thing.tsx': 'export const LibThing = () => null\n',
+      'src/thing.case.tsx': caseModule('LibThing', o.libLevel),
+    })
+
+    await writeFiles(appDir, {
+      'package.json': JSON.stringify({
+        name: '@dc-fixture/app',
+        type: 'module',
+      }),
+      'display-case.config.ts': appConfig(o.rule),
+      'src/cmp.tsx': `import { LibThing } from '@dc-fixture/lib'\nexport const Cmp = () => LibThing\n`,
+      'src/cmp.case.tsx': caseModule('Cmp', o.appLevel),
+    })
+
+    // Link the library into the app's node_modules so the bare specifier resolves.
+    await mkdir(join(appDir, 'node_modules', '@dc-fixture'), {
+      recursive: true,
+    })
+    await symlink(
+      libDir,
+      join(appDir, 'node_modules', '@dc-fixture', 'lib'),
+      'dir',
+    )
+
+    return appDir
+  }
+
+  const findings = async (appDir: string, rule: StructureRuleId) =>
+    (await checkStructure(appDir)).findings.filter((f) => f.rule === rule)
+
+  afterEach(async () => {
+    while (dirs.length)
+      await rm(dirs.pop() as string, { recursive: true, force: true })
+  })
+
+  test('composes-lower-level is satisfied by a lower-level component from another showcase', async () => {
+    const app = await setupRepos({
+      libLevel: 'atom',
+      appLevel: 'molecule',
+      barrel: 'named',
+      rule: 'composes-lower-level',
+    })
+    // The molecule composes nothing locally; only the cross-package atom can
+    // satisfy the rule, so zero findings proves the resolver followed it.
+    expect(await findings(app, 'composes-lower-level')).toHaveLength(0)
+  })
+
+  test('an organism composed only of a foreign atom passes', async () => {
+    const app = await setupRepos({
+      libLevel: 'atom',
+      appLevel: 'organism',
+      barrel: 'named',
+      rule: 'composes-lower-level',
+    })
+    expect(await findings(app, 'composes-lower-level')).toHaveLength(0)
+  })
+
+  test('no-downward-dependency catches a higher-level component from another showcase', async () => {
+    const app = await setupRepos({
+      libLevel: 'organism',
+      appLevel: 'atom',
+      barrel: 'named',
+      rule: 'no-downward-dependency',
+    })
+    const f = await findings(app, 'no-downward-dependency')
+    expect(f).toHaveLength(1)
+    expect(f[0].severity).toBe('error')
+    expect(f[0].message).toContain('organism')
+  })
+
+  test('an unfollowable workspace-showcase import warns, not errors', async () => {
+    const app = await setupRepos({
+      libLevel: 'atom',
+      appLevel: 'molecule',
+      barrel: 'star', // `export *` — the resolver cannot bind the name to a file
+      rule: 'composes-lower-level',
+    })
+    const f = await findings(app, 'composes-lower-level')
+    expect(f).toHaveLength(1)
+    expect(f[0].severity).toBe('warn')
+    expect(f[0].message).toContain('could not be resolved')
+  })
+})