@awarebydefault/display-case 1.0.0

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

@@ -0,0 +1,159 @@
+import { afterEach, describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import { checkTokens } from './tokens-check'
+
+// A minimal config whose only token source of truth is `tokens.css`. `extra`
+// splices additional config fields (e.g. a tokens allowlist) into the literal.
+const config = (extra = '') =>
+  `export default { title: 'Fixture', roots: ['**/*.case.tsx'], globalStyles: ['tokens.css']${extra} }\n`
+
+describe('checkTokens', () => {
+  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 })
+  })
+
+  test('passes when every reference resolves to a defined token', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root { --color-bg: #fff; }',
+      'button.css': '.b { background: var(--color-bg); }',
+    })
+    const { violations, definedCount } = await checkTokens(dir)
+    expect(violations).toEqual([])
+    expect(definedCount).toBeGreaterThanOrEqual(1)
+  })
+
+  test('flags a reference to an undefined token', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root { --color-bg: #fff; }',
+      'button.css': '.b { color: var(--mystery); }', // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toHaveLength(1)
+    expect(violations[0].token).toBe('--mystery')
+    expect(violations[0].hadFallback).toBe(false)
+    expect(violations[0].file.endsWith('button.css')).toBe(true)
+  })
+
+  test('reports the 1-based line and column of the token', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{--a:1;}',
+      'x.css': 'a{color:1;}\nb{fill:var(--missing);}', // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toHaveLength(1)
+    expect(violations[0].line).toBe(2)
+    // `b{fill:` is 7 chars, `var(` opens at col 8, `--missing` begins at col 12.
+    expect(violations[0].column).toBe(12)
+  })
+
+  test('a fallback value does not excuse an undefined token', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{}',
+      'x.css': '.a{color:var(--ghost, #6b7280);}', // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toHaveLength(1)
+    expect(violations[0].token).toBe('--ghost')
+    expect(violations[0].hadFallback).toBe(true)
+  })
+
+  test('an allow-listed token name is treated as defined', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(`, tokens: { allow: ['--host-bg'] }`),
+      'tokens.css': ':root{}',
+      'x.css': '.a{background:var(--host-bg);}', // allow: unknown-token
+    })
+    const { violations, definedCount } = await checkTokens(dir)
+    expect(violations).toEqual([])
+    expect(definedCount).toBeGreaterThanOrEqual(1)
+  })
+
+  test('an `allow: unknown-token` comment suppresses on the same or preceding line', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{}',
+      'same.css': '.a{color:var(--x);} /* allow: unknown-token */',
+      'above.css': '/* allow: unknown-token */\n.a{color:var(--y);}',
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toEqual([])
+  })
+
+  test('a var() inside a CSS comment is not treated as a reference', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{}',
+      'x.css': '/* var(--commented) */\n.a{color:red;}', // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toEqual([])
+  })
+
+  test('a var() inside a JS string literal is a real reference', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{}',
+      'x.tsx': `export const s = { color: 'var(--js-token)' }\n`, // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations.map((v) => v.token)).toContain('--js-token')
+  })
+
+  test('an inline-style object key defines a token for the whole package', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{}',
+      'comp.tsx': `export const x = { style: { '--ring': 'red' } }\n`,
+      'comp.css': '.a{outline-color:var(--ring);}',
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toEqual([])
+  })
+
+  test('resolves a reference whose definition lives in a different file', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{ --shared: 2px; }',
+      'a.css': '.a{ gap: var(--shared); }', // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations).toEqual([])
+  })
+
+  test('sorts violations by file, then line, then column', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{}',
+      'b.css': '.a{color:var(--p);}', // allow: unknown-token
+      'a.css': '.a{color:var(--q);}\n.b{color:var(--r);}', // allow: unknown-token
+    })
+    const { violations } = await checkTokens(dir)
+    expect(violations.map((v) => v.token)).toEqual(['--q', '--r', '--p'])
+  })
+
+  test('reports the number of scanned files', async () => {
+    const dir = await setup({
+      'display-case.config.ts': config(),
+      'tokens.css': ':root{--a:1;}',
+      'x.css': '.a{color:var(--a);}', // allow: unknown-token
+    })
+    const { scannedFiles } = await checkTokens(dir)
+    // config.ts + tokens.css + x.css (tokens.css is reached via both the glob
+    // and globalStyles, but the path set dedups it).
+    expect(scannedFiles).toBe(3)
+  })
+})

package/src/checks/tokens-check.ts

@@ -0,0 +1,162 @@
+import { resolve } from 'node:path'
+import { Glob } from 'bun'
+import { resolveConfig } from '../core/discovery'
+import { blankComments } from './check-text'
+
+/**
+ * Static design-token conformance check for a Display-Case-ingested package.
+ *
+ * Display Case already knows the two halves of a package's token contract:
+ *   - DEFINITIONS — the `globalStyles` CSS it injects into every preview
+ *     (`--name: …` declarations), plus any custom properties a component sets at
+ *     runtime via an inline `style={{ '--name': … }}` object.
+ *   - REFERENCES — every `var(--name…)` in the package's own source (component
+ *     CSS/TSX and the `.case.tsx` files).
+ *
+ * This pass flags any `var(--name)` whose name is neither defined in the package
+ * nor explicitly allow-listed. It catches the class of bug where a component
+ * borrows a foreign design system's token name (e.g. a shadcn-style
+ * `var(--muted-foreground, #6b7280)`) that never resolves and silently falls
+ * back to a hardcoded value — well-formed CSS, but a vocabulary violation that
+ * breaks theming and contrast.
+ *
+ * Intentionally opinionated: a `var(--x, fallback)` reference is still flagged
+ * even though the fallback makes it valid CSS. The whole point is to require
+ * every reference to resolve within *this* package's declared vocabulary.
+ *
+ * Static and browser-free — pure parse, so it is cheap enough to gate on commit.
+ */
+
+export interface TokenViolation {
+  /** Absolute path to the file containing the reference. */
+  file: string
+  /** 1-based line number. */
+  line: number
+  /** 1-based column of the `--token`. */
+  column: number
+  /** The unresolved custom-property name, e.g. `--muted-foreground`. */
+  token: string
+  /** True when the reference carried a fallback (`var(--x, …)`). */
+  hadFallback: boolean
+}
+
+export interface TokenCheckResult {
+  pkgDir: string
+  scannedFiles: number
+  definedCount: number
+  violations: TokenViolation[]
+}
+
+// `var(` then a custom property, capturing a following comma (⇒ has fallback).
+const REF_RE = /var\(\s*(--[A-Za-z0-9_-]+)\s*(,)?/g
+// A CSS custom-property *declaration*: `--name:` at a value-position boundary.
+// The boundary excludes `var(--name)` (preceded by `(`) and JS object keys
+// (preceded by a quote), so only genuine definitions are harvested.
+const CSS_DEF_RE = /(?:^|[\s;{,])(--[A-Za-z0-9_-]+)\s*:/g
+// An inline-style definition in JS/TSX: a quoted object key, e.g.
+// `style={{ '--ring': color }}`. These set the property at runtime.
+const JS_DEF_RE = /['"`](--[A-Za-z0-9_-]+)['"`]\s*:/g
+// Per-reference escape hatch (mirrors the repo's `allow: <reason>` convention).
+const ESCAPE_RE = /allow:\s*unknown-token/
+
+interface ScannedFile {
+  path: string
+  /** Comment-blanked text (offsets + line breaks preserved). */
+  clean: string
+  /** Original, unmodified lines — used only for the escape-comment lookup. */
+  rawLines: string[]
+  isCss: boolean
+}
+
+function collectDefs(file: ScannedFile, into: Set<string>): void {
+  const re = file.isCss ? CSS_DEF_RE : JS_DEF_RE
+  re.lastIndex = 0
+  for (let m = re.exec(file.clean); m; m = re.exec(file.clean)) {
+    into.add(m[1])
+  }
+}
+
+function collectRefs(
+  file: ScannedFile,
+  defined: Set<string>,
+  out: TokenViolation[],
+): void {
+  const cleanLines = file.clean.split('\n')
+  cleanLines.forEach((line, idx) => {
+    REF_RE.lastIndex = 0
+    for (let m = REF_RE.exec(line); m; m = REF_RE.exec(line)) {
+      const token = m[1]
+      if (defined.has(token)) continue
+      // Escape may sit on the reference line or the line directly above it.
+      const raw = file.rawLines[idx] ?? ''
+      const above = idx > 0 ? (file.rawLines[idx - 1] ?? '') : ''
+      if (ESCAPE_RE.test(raw) || ESCAPE_RE.test(above)) continue
+      out.push({
+        file: file.path,
+        line: idx + 1,
+        column: m.index + m[0].indexOf(token) + 1,
+        token,
+        hadFallback: m[2] === ',',
+      })
+    }
+  })
+}
+
+/**
+ * Run the token-reference conformance pass over one ingested package.
+ * Resolves the package's Display Case config to learn `globalStyles` (token
+ * definitions) and scans the whole package source tree for definitions +
+ * references.
+ */
+export async function checkTokens(pkgDir: string): Promise<TokenCheckResult> {
+  const { config } = await resolveConfig(pkgDir)
+
+  // Gather the files that hold definitions and/or references: the configured
+  // global stylesheets (token source of truth) plus all package source.
+  const paths = new Set<string>()
+  for (const rel of config.globalStyles ?? []) paths.add(resolve(pkgDir, rel))
+  const glob = new Glob('**/*.{css,ts,tsx}')
+  for await (const match of glob.scan({ cwd: pkgDir, absolute: true })) {
+    if (
+      match.includes('/node_modules/') ||
+      match.includes('/.display-case/') ||
+      match.includes('/dist/')
+    ) {
+      continue
+    }
+    paths.add(match)
+  }
+
+  const files: ScannedFile[] = []
+  for (const path of paths) {
+    if (!(await Bun.file(path).exists())) continue
+    const text = await Bun.file(path).text()
+    const isCss = path.endsWith('.css')
+    files.push({
+      path,
+      clean: blankComments(text, isCss),
+      rawLines: text.split('\n'),
+      isCss,
+    })
+  }
+
+  // Pass 1 — every defined token across the whole package (definitions may live
+  // in a different file than the reference), seeded with the config allowlist.
+  const defined = new Set<string>(config.tokens?.allow ?? [])
+  for (const file of files) collectDefs(file, defined)
+
+  // Pass 2 — flag references to names the package never defines.
+  const violations: TokenViolation[] = []
+  for (const file of files) collectRefs(file, defined, violations)
+  violations.sort(
+    (a, b) =>
+      a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column,
+  )
+
+  return {
+    pkgDir,
+    scannedFiles: files.length,
+    definedCount: defined.size,
+    violations,
+  }
+}

package/src/cli.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { AGENT_TARGETS, DEFAULT_AGENT } from './commands/agents'
+import { getManifest, startDisplayCase } from './server/server'
+
+// Display Case is Bun-native at *runtime*, not just at install time: discovery,
+// bundling, and serving all use Bun's built-in bundler and `Bun.serve`. Running
+// the CLI under Node fails deep inside with an opaque `Bun is not defined`, so
+// detect it up front and point the user at Bun.
+if (typeof globalThis.Bun === 'undefined') {
+  console.error(
+    'display-case requires the Bun runtime (https://bun.sh).\n' +
+      'Run it with Bun — e.g. `bunx @awarebydefault/display-case .` or `bun run display-case` — not Node.',
+  )
+  process.exit(1)
+}
+
+/**
+ * Display Case CLI.
+ *
+ *   display-case <pkgDir> [--port=N]        start the dev server
+ *   display-case <pkgDir> --print-manifest  print the manifest JSON and exit
+ *   display-case check <pkgDir> [--a11y] [--visual] [--tokens] [--structure] [--ssr] [--update] [--strict] [--only=ids] [--changed[=ref]] [--port=N]
+ *   display-case init <pkgDir> [--agent=claude] [--with-visual] [--dry-run] [--json]
+ *   display-case uninstall <pkgDir> [--agent=claude] [--dry-run] [--json]
+ *
+ * With no phase flag, `check` runs all phases. Naming any phase flag runs only
+ * the named phase(s) — e.g. `--tokens` runs the (browser-free) token check alone.
+ * `init`/`uninstall` scaffold (or remove) AI-agent integration in the repo.
+ */
+
+const argv = process.argv.slice(2)
+
+function flag(name: string): boolean {
+  return argv.includes(`--${name}`)
+}
+function option(name: string): string | undefined {
+  return argv.find((a) => a.startsWith(`--${name}=`))?.split('=')[1]
+}
+function positionals(): string[] {
+  return argv.filter((a) => !a.startsWith('--'))
+}
+
+const CONFIG_FILE = 'display-case.config.ts'
+
+function fail(message: string): never {
+  console.error(message)
+  process.exit(1)
+}
+
+/** Nearest ancestor of `start` (inclusive) containing a config, or null. */
+function discoverConfigDir(start: string): string | null {
+  let dir = resolve(start)
+  for (let i = 0; i < 24; i++) {
+    if (existsSync(join(dir, CONFIG_FILE))) return dir
+    const parent = resolve(dir, '..')
+    if (parent === dir) return null
+    dir = parent
+  }
+  return null
+}
+
+/**
+ * Resolve the package directory to operate on.
+ *
+ * - An explicit target (`display-case apps/foo`) is used as given and
+ *   must contain a `display-case.config.ts` — a wrong directory fails loudly
+ *   rather than serving an empty showcase.
+ * - The default (no argument, or `.`) discovers the nearest config by walking up
+ *   from the current directory, so it works from a package root *or* any
+ *   subdirectory. The bare form is identical to `.` — there is no separate
+ *   "no-argument" mode to reason about.
+ *
+ * Resolution, the `.display-case/` build cache, and repo-relative paths all
+ * anchor to the resolved package, so running from a git worktree keeps
+ * everything inside that worktree and two checkouts never share a cache. The
+ * one rule: run it from inside the package (any depth), or pass the path
+ * explicitly — don't rely on a process cwd that points elsewhere.
+ */
+function resolvePkgDir(arg: string | undefined): string {
+  if (arg && arg !== '.') {
+    const dir = resolve(arg)
+    if (!existsSync(join(dir, CONFIG_FILE))) {
+      fail(`No ${CONFIG_FILE} in ${dir} — is that a Display Case package?`)
+    }
+    return dir
+  }
+
+  const here = discoverConfigDir(process.cwd())
+  if (here) return here
+  fail(
+    `No ${CONFIG_FILE} found in ${process.cwd()} or any parent directory.\n` +
+      `Run from inside a Display Case package, or pass <pkgDir> explicitly.`,
+  )
+}
+
+// An explicit `--port` wins; otherwise honor `DISPLAY_CASE_PORT` (the dev
+// orchestrator sets this per-worktree so two checkouts don't collide), falling
+// back to the server's own default. `startDisplayCase` treats the chosen port as
+// preferred and bumps off a busy one, so this never hard-fails on a clash.
+const portArg = option('port') ?? process.env.DISPLAY_CASE_PORT
+const port = portArg ? Number(portArg) : undefined
+
+if (argv[0] === 'init' || argv[0] === 'uninstall') {
+  const pkgDir = resolve(positionals()[1] ?? '.')
+  const agent = option('agent') ?? DEFAULT_AGENT
+  if (!AGENT_TARGETS[agent]) {
+    console.error(
+      `Unsupported agent "${agent}". Supported: ${Object.keys(AGENT_TARGETS).join(', ')}.`,
+    )
+    process.exit(1)
+  }
+  const { runInit, runUninstall, report } = await import('./commands/init')
+  // init may set up the visual toolchain: explicit --with-visual, or an
+  // interactive prompt when attached to a TTY (never in --json/--dry-run).
+  let withVisual = flag('with-visual')
+  if (
+    argv[0] === 'init' &&
+    !withVisual &&
+    process.stdin.isTTY &&
+    !flag('json') &&
+    !flag('dry-run')
+  ) {
+    const answer = prompt(
+      'Set up visual-regression checking (Playwright + pixelmatch + pngjs)? [y/N]',
+    )
+    withVisual = /^y(es)?$/i.test(answer?.trim() ?? '')
+  }
+  const opts = {
+    agent,
+    dryRun: flag('dry-run'),
+    json: flag('json'),
+    withVisual,
+  }
+  const result = await (argv[0] === 'init' ? runInit : runUninstall)(
+    pkgDir,
+    opts,
+  )
+  report(result)
+} else if (argv[0] === 'check') {
+  const pkgDir = resolvePkgDir(positionals()[1])
+  const { runChecks } = await import('./checks/check')
+  const { resolveConfig } = await import('./core/discovery')
+  const { config } = await resolveConfig(pkgDir)
+  // A named phase flag ⇒ run only the named phase(s). With no phase flag, run
+  // every phase except those a config opts out of via `check.defaultPhases`.
+  const explicit = {
+    tokens: flag('tokens'),
+    a11y: flag('a11y'),
+    visual: flag('visual'),
+    structure: flag('structure'),
+    ssr: flag('ssr'),
+  }
+  const anyExplicit =
+    explicit.tokens ||
+    explicit.a11y ||
+    explicit.visual ||
+    explicit.structure ||
+    explicit.ssr
+  const defaults = config.check?.defaultPhases ?? {}
+  const runs = (phase: keyof typeof explicit): boolean =>
+    explicit[phase] || (!anyExplicit && defaults[phase] !== false)
+  // Change-scoping for the render phases (a11y/visual): `--only=<ids/globs>`
+  // restricts to named components; `--changed[=<ref>]` restricts to components
+  // whose import closure touches a file changed since <ref> (default the base
+  // branch, overridable via DISPLAY_CASE_BASE_REF). Both are no-ops for the
+  // static phases. See src/core/affected.ts.
+  const onlyValue = option('only')
+  const changedActive = flag('changed') || option('changed') !== undefined
+  const ok = await runChecks(pkgDir, {
+    a11y: runs('a11y'),
+    visual: runs('visual'),
+    tokens: runs('tokens'),
+    structure: runs('structure'),
+    ssr: runs('ssr'),
+    update: flag('update'),
+    strict: flag('strict'),
+    only: onlyValue ? onlyValue.split(',').filter(Boolean) : undefined,
+    changedRef: changedActive
+      ? (option('changed') ??
+        process.env.DISPLAY_CASE_BASE_REF ??
+        'origin/main')
+      : undefined,
+    port,
+  })
+  process.exit(ok ? 0 : 1)
+} else if (argv[0] === 'publish') {
+  const pkgDir = resolvePkgDir(positionals()[1])
+  const { publish } = await import('./commands/publish')
+  const isStatic = flag('static')
+  console.log('Building deployable showcase…')
+  const { out } = await publish(pkgDir, {
+    out: option('out'),
+    base: option('base'),
+    static: isStatic,
+  })
+  console.log(`\n  Published → ${out}`)
+  console.log(
+    isStatic
+      ? '  Static export written — serve the directory with any static host.'
+      : `  Run it:  (cd ${out} && bun install && bun server.ts)   — or build the Dockerfile.`,
+  )
+  process.exit(0)
+} else {
+  const pkgDir = resolvePkgDir(positionals()[0])
+
+  if (flag('print-manifest')) {
+    const manifest = await getManifest(pkgDir)
+    console.log(JSON.stringify(manifest, null, 2))
+    process.exit(0)
+  }
+
+  // `--dev` enables live reload of the Display Case app itself (chrome,
+  // components, primer) — see StartOptions.dev.
+  const server = await startDisplayCase(pkgDir, { port, dev: flag('dev') })
+  console.log(`\n  Display Case → ${server.url}\n`)
+}

package/src/commands/agents.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from 'bun:test'
+import { AGENT_TARGETS, DEFAULT_AGENT } from './agents'
+
+describe('agent targets', () => {
+  test('DEFAULT_AGENT points at a registered target', () => {
+    expect(AGENT_TARGETS[DEFAULT_AGENT]).toBeDefined()
+    expect(AGENT_TARGETS[DEFAULT_AGENT].id).toBe(DEFAULT_AGENT)
+  })
+
+  test('the claude target declares launch, skills, and instruction locations', () => {
+    const t = AGENT_TARGETS.claude
+    expect(t.id).toBe('claude')
+    expect(t.launchConfigPath).toBe('.claude/launch.json')
+    expect(t.skillsDir).toBe('.claude/skills')
+    expect(t.instructionsFiles).toEqual(['AGENTS.md', 'CLAUDE.md'])
+  })
+
+  test('every target’s id matches its registry key', () => {
+    for (const [key, target] of Object.entries(AGENT_TARGETS)) {
+      expect(target.id).toBe(key)
+      expect(target.instructionsFiles.length).toBeGreaterThan(0)
+    }
+  })
+})

package/src/commands/agents.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-agent conventions for where launch config, skills, and instructions live.
+ * Adding a new agent is data, not control flow — `init`/`uninstall` are
+ * agent-agnostic and read everything they need from the selected target.
+ */
+export interface AgentTarget {
+  id: string
+  /** Launch/run configuration file, relative to the repo root. */
+  launchConfigPath: string
+  /** Directory the agent loads skills from, relative to the repo root. */
+  skillsDir: string
+  /**
+   * Candidate instruction files in priority order; the first that exists is
+   * used, else the first is created.
+   */
+  instructionsFiles: string[]
+}
+
+export const AGENT_TARGETS: Record<string, AgentTarget> = {
+  claude: {
+    id: 'claude',
+    launchConfigPath: '.claude/launch.json',
+    skillsDir: '.claude/skills',
+    instructionsFiles: ['AGENTS.md', 'CLAUDE.md'],
+  },
+}
+
+export const DEFAULT_AGENT = 'claude'