@awarebydefault/display-case 1.0.0

package/src/commands/publish.test.ts

@@ -0,0 +1,210 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, readdir, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import type { Manifest } from '../core/manifest'
+import { startProdServer } from '../server/prod-server'
+import { makeTempDir } from '../testing/test-helpers'
+import { type BuildDescriptor, publish } from './publish'
+
+/**
+ * A build dir anchored INSIDE the repo. The published server/static SSR bundle
+ * keeps `react`/`react-dom` external (resolved at runtime), so when we import or
+ * serve it in-process the build must sit where module resolution walks up to the
+ * repo's `node_modules` — a `/tmp` dir has none. (A real deploy installs
+ * `node_modules` alongside the build; this reproduces that.) Gitignored via
+ * `.tmp/`.
+ */
+const REPO = resolve(import.meta.dir, '..', '..')
+async function makeRepoTempDir(): Promise<string> {
+  const base = join(REPO, '.tmp')
+  await mkdir(base, { recursive: true })
+  return mkdtemp(join(base, 'publish-'))
+}
+
+/**
+ * Coverage for the publish / deploy path — previously untested. Two levels,
+ * both Docker-free:
+ *   1. the published *artifacts* (bundle, frozen manifest, generated
+ *      server/Dockerfile, no dev machinery), and
+ *   2. the *served* build booted in-process via `startProdServer`, plus the
+ *      `--static` export.
+ * The containerized deploy path (a real `docker build`) is Docker-gated in
+ * `test/publish-container.test.ts`.
+ *
+ * Published against a minimal fixture for speed and determinism.
+ */
+const FIXTURE = resolve(
+  import.meta.dir,
+  '..',
+  '..',
+  'e2e/fixtures/consumer-plain',
+)
+
+describe('publish: artifacts', () => {
+  let out: string
+  let descriptor: BuildDescriptor
+
+  beforeAll(async () => {
+    out = await makeTempDir()
+    ;({ descriptor } = await publish(FIXTURE, { out }))
+  })
+  afterAll(() => rm(out, { recursive: true, force: true }))
+
+  test('emits content-hashed browser + render bundles', async () => {
+    const assets = await readdir(join(out, 'assets'))
+    expect(assets.some((f) => /^browser-entry-.+\.js$/.test(f))).toBe(true)
+    expect(assets.some((f) => /^render-entry-.+\.js$/.test(f))).toBe(true)
+  })
+
+  test('descriptor: production, a11y disabled, base-prefixed assets', () => {
+    expect(descriptor.title).toBe('Plain Consumer')
+    expect(descriptor.a11y).toBe(false)
+    expect(descriptor.base).toBe('')
+    expect(descriptor.assets.browser).toMatch(
+      /^\/assets\/browser-entry-.+\.js$/,
+    )
+    expect(descriptor.assets.render).toMatch(/^\/assets\/render-entry-.+\.js$/)
+  })
+
+  test('frozen manifest + build descriptor written to disk', async () => {
+    const manifest = (await Bun.file(
+      join(out, 'manifest.json'),
+    ).json()) as Manifest
+    expect(Array.isArray(manifest.components)).toBe(true)
+    expect(manifest.components.length).toBeGreaterThan(0)
+    const dc = (await Bun.file(
+      join(out, 'dc-build.json'),
+    ).json()) as BuildDescriptor
+    expect(dc.a11y).toBe(false)
+  })
+
+  test('SSR renderers are built for the production server', async () => {
+    expect(await Bun.file(join(out, 'server', 'ssr-entry.js')).exists()).toBe(
+      true,
+    )
+  })
+
+  test('generated server.ts uses the prod-server, carries no dev machinery', async () => {
+    const s = await Bun.file(join(out, 'server.ts')).text()
+    expect(s).toContain("from 'display-case/prod-server'")
+    expect(s).toContain('AUTO-GENERATED')
+    expect(s).not.toContain('__livereload')
+  })
+
+  test('generated package.json is a deployable service descriptor', async () => {
+    const pkg = (await Bun.file(join(out, 'package.json')).json()) as {
+      scripts: Record<string, string>
+      dependencies: Record<string, string>
+    }
+    expect(pkg.scripts.start).toBe('bun server.ts')
+    expect(pkg.dependencies['display-case']).toBeDefined()
+    expect(pkg.dependencies.react).toBeDefined()
+    expect(pkg.dependencies['react-dom']).toBeDefined()
+  })
+
+  test('generated Dockerfile builds a Bun service with a health check', async () => {
+    const df = await Bun.file(join(out, 'Dockerfile')).text()
+    expect(df).toContain('FROM oven/bun')
+    expect(df).toContain('bun install --production')
+    expect(df).toContain('/health')
+    expect(df).toContain('CMD ["bun", "server.ts"]')
+  })
+
+  test('--base prefixes the hashed asset URLs for subpath hosting', async () => {
+    const o2 = await makeTempDir()
+    try {
+      const { descriptor: d } = await publish(FIXTURE, {
+        out: o2,
+        base: '/showcase',
+      })
+      expect(d.base).toBe('/showcase')
+      expect(d.assets.browser).toMatch(/^\/showcase\/assets\//)
+    } finally {
+      await rm(o2, { recursive: true, force: true })
+    }
+  })
+})
+
+describe('publish: the served build is a functional showcase', () => {
+  let out: string
+  let descriptor: BuildDescriptor
+  let manifest: Manifest
+  let server: Awaited<ReturnType<typeof startProdServer>>
+  let baseUrl: string
+
+  beforeAll(async () => {
+    out = await makeRepoTempDir()
+    ;({ descriptor } = await publish(FIXTURE, { out }))
+    manifest = (await Bun.file(join(out, 'manifest.json')).json()) as Manifest
+    server = await startProdServer(out, { port: 0 })
+    baseUrl = `http://localhost:${server.port}`
+  })
+  afterAll(async () => {
+    await server?.stop(true)
+    await rm(out, { recursive: true, force: true })
+  })
+
+  test('GET /health returns ok', async () => {
+    const r = await fetch(`${baseUrl}/health`)
+    expect(r.status).toBe(200)
+    expect(await r.text()).toBe('ok')
+  })
+
+  test('the shell is server-rendered, links hashed assets, and has no dev live-reload', async () => {
+    const r = await fetch(`${baseUrl}/`)
+    expect(r.status).toBe(200)
+    const html = await r.text()
+    expect(html).toContain('Plain Consumer') // title server-rendered
+    expect(html).toContain('data-ssr="1"') // content present before scripts
+    expect(html).toContain(descriptor.assets.browser) // hashed bundle linked
+    expect(html).not.toContain('__livereload') // dev SSE stripped
+    expect(html).not.toContain('EventSource')
+    expect(r.headers.get('cache-control')).toContain('no-cache')
+  })
+
+  test('the isolated /render endpoint serves a chrome-free, pre-scripting document', async () => {
+    const c = manifest.components[0]
+    const cs = c.cases[0]
+    const r = await fetch(`${baseUrl}/render/${c.id}/${cs.id}`)
+    expect(r.status).toBe(200)
+    const html = await r.text()
+    expect(html).toContain('data-ssr="1"')
+    expect(html).toContain(descriptor.assets.render)
+    // Chrome-free: the shell's title chrome is absent from the isolated doc.
+    expect(html).not.toContain('Plain Consumer')
+  })
+
+  test('hashed assets are served with immutable caching', async () => {
+    const r = await fetch(`${baseUrl}${descriptor.assets.browser}`)
+    expect(r.status).toBe(200)
+    expect(r.headers.get('cache-control')).toContain('immutable')
+  })
+})
+
+describe('publish: the static export needs no running server', () => {
+  let out: string
+  let descriptor: BuildDescriptor
+  let manifest: Manifest
+
+  beforeAll(async () => {
+    out = await makeRepoTempDir()
+    ;({ descriptor } = await publish(FIXTURE, { out, static: true }))
+    manifest = (await Bun.file(join(out, 'manifest.json')).json()) as Manifest
+  })
+  afterAll(() => rm(out, { recursive: true, force: true }))
+
+  test('writes a complete index.html with the shell pre-rendered', async () => {
+    const html = await Bun.file(join(out, 'index.html')).text()
+    expect(html).toContain('<!doctype html>')
+    expect(html).toContain('Plain Consumer')
+    expect(html).toContain(descriptor.assets.browser)
+  })
+
+  test('writes a complete per-case render document', async () => {
+    const c = manifest.components[0]
+    const cs = c.cases[0]
+    const file = join(out, 'render', c.id, cs.id, 'index.html')
+    expect(await Bun.file(file).exists()).toBe(true)
+    expect(await Bun.file(file).text()).toContain('data-ssr="1"')
+  })
+})

package/src/commands/publish.ts

@@ -0,0 +1,292 @@
+import { mkdir, rm } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import {
+  cacheDir,
+  codegenPrimerEntry,
+  codegenRenderEntry,
+  codegenSsrEntry,
+  codegenSsrPrimerEntry,
+  discoverCaseFiles,
+  resolveConfig,
+} from '../core/discovery'
+import { mdxPlugin } from '../core/mdx-plugin'
+import type { DisplayCaseConfig } from '../index'
+import { getManifest } from '../server/server'
+
+/**
+ * Build a self-contained, hostable showcase: production-bundled assets
+ * (minified, content-hashed, no dev injects) plus a frozen manifest, styles, and
+ * the SSR renderers, written to an output directory that a thin production server
+ * (`prod-server.ts`) serves — or, with `static: true`, a crawl writes complete
+ * HTML files that need no running server. None of the dev machinery (watcher,
+ * live-reload, on-demand a11y, dev endpoints) is carried into the build.
+ */
+
+const HERE = resolve(import.meta.dir, '..')
+const BROWSER_ENTRY = join(HERE, 'ui', 'browser-entry.tsx')
+const CHROME_CSS = join(HERE, 'ui', 'chrome.css')
+const DS_DIR = join(HERE, 'ui', 'design-system', 'tokens')
+const DS_TOKEN_FILES = ['colors.css', 'typography.css', 'spacing.css']
+const COMPONENTS_DIR = join(HERE, 'ui', 'design-system', 'components')
+const PRIMER_CSS = join(HERE, 'ui', 'primer.css')
+
+export interface PublishOptions {
+  /** Output directory (default `<pkgDir>/dist-showcase`). */
+  out?: string
+  /** Base path for hosting under a subpath (e.g. `/showcase`). */
+  base?: string
+  /** Also write a fully-static (server-less) export. */
+  static?: boolean
+}
+
+/** Public env (`BUN_PUBLIC_*`) inlined into the browser bundle, plus a forced
+ *  production NODE_ENV so React builds in production mode. */
+async function buildDefines(pkgDir: string): Promise<Record<string, string>> {
+  const defines: Record<string, string> = {
+    'process.env.NODE_ENV': '"production"',
+  }
+  for (const name of ['.env', '.env.local']) {
+    const file = Bun.file(join(pkgDir, name))
+    if (!(await file.exists())) continue
+    for (const raw of (await file.text()).split('\n')) {
+      const line = raw.trim()
+      if (!line || line.startsWith('#')) continue
+      const eq = line.indexOf('=')
+      if (eq === -1) continue
+      const key = line
+        .slice(0, eq)
+        .replace(/^export\s+/, '')
+        .trim()
+      if (!key.startsWith('BUN_PUBLIC_')) continue
+      let value = line.slice(eq + 1).trim()
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1)
+      }
+      defines[`process.env.${key}`] = JSON.stringify(value)
+    }
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith('BUN_PUBLIC_') && value !== undefined) {
+      defines[`process.env.${key}`] = JSON.stringify(value)
+    }
+  }
+  return defines
+}
+
+async function readDesignTokens(): Promise<string> {
+  const parts = await Promise.all(
+    DS_TOKEN_FILES.map((f) => Bun.file(join(DS_DIR, f)).text()),
+  )
+  return parts.join('\n')
+}
+
+// The Vitrine's own chrome stylesheet — chrome.css + every design-system
+// component's co-located CSS + the primer chrome's CSS, read and concatenated in
+// path-sorted order. Mirrors server.ts; the published documents inline it so the
+// chrome paints before scripts (the components no longer inject at runtime).
+async function readVitrineCss(): Promise<string> {
+  const componentFiles: string[] = []
+  for await (const f of new Bun.Glob('**/*.css').scan({
+    cwd: COMPONENTS_DIR,
+    absolute: true,
+  })) {
+    componentFiles.push(f)
+  }
+  componentFiles.sort()
+  const parts = await Promise.all(
+    [CHROME_CSS, ...componentFiles, PRIMER_CSS].map((f) => Bun.file(f).text()),
+  )
+  return parts.join('\n')
+}
+
+async function readGlobalCss(
+  pkgDir: string,
+  config: DisplayCaseConfig,
+): Promise<string> {
+  const parts: string[] = []
+  for (const rel of config.globalStyles ?? []) {
+    const abs = resolve(pkgDir, rel)
+    if (await Bun.file(abs).exists()) parts.push(await Bun.file(abs).text())
+  }
+  return parts.join('\n')
+}
+
+/** Map a built entry-point's output path back to its logical name. */
+function entryName(path: string): 'browser' | 'render' | 'primer' | null {
+  const b = basename(path)
+  if (b.startsWith('browser-entry')) return 'browser'
+  if (b.startsWith('render-entry')) return 'render'
+  if (b.startsWith('primer-entry')) return 'primer'
+  return null
+}
+
+export interface BuildDescriptor {
+  title: string
+  base: string
+  a11y: false
+  hasPrimer: boolean
+  /** Content-hashed, base-prefixed entry URLs. */
+  assets: { browser: string; render: string; primer: string }
+  tokensCss: string
+  globalCss: string
+  vitrineCss: string
+}
+
+export async function publish(
+  pkgDir: string,
+  opts: PublishOptions = {},
+): Promise<{ out: string; descriptor: BuildDescriptor }> {
+  const out = resolve(opts.out ?? join(pkgDir, 'dist-showcase'))
+  const base = (opts.base ?? '').replace(/\/+$/, '')
+  const { config, configPath } = await resolveConfig(pkgDir)
+
+  await rm(out, { recursive: true, force: true })
+  await mkdir(join(out, 'assets'), { recursive: true })
+  await mkdir(join(out, 'server'), { recursive: true })
+
+  const files = await discoverCaseFiles(pkgDir, config)
+  const primerConfigured = !!config.primer
+  const primerSrc = primerConfigured
+    ? resolve(pkgDir, config.primer as string)
+    : null
+  const hasPrimer = !!primerSrc && (await Bun.file(primerSrc).exists())
+
+  // Codegen the same entries the dev server uses.
+  const renderEntry = await codegenRenderEntry(pkgDir, files, configPath)
+  const primerEntry = hasPrimer
+    ? await codegenPrimerEntry(pkgDir, config.primer as string)
+    : null
+  const ssrEntry = await codegenSsrEntry(pkgDir, files, configPath)
+  const ssrPrimerEntry = hasPrimer
+    ? await codegenSsrPrimerEntry(pkgDir, config.primer as string, configPath)
+    : null
+
+  const defines = await buildDefines(pkgDir)
+
+  // Browser bundle: minified, content-hashed, production React.
+  const browserEntries = [BROWSER_ENTRY, renderEntry]
+  if (primerEntry) browserEntries.push(primerEntry)
+  const browser = await Bun.build({
+    entrypoints: browserEntries,
+    outdir: join(out, 'assets'),
+    target: 'browser',
+    minify: true,
+    sourcemap: 'none',
+    plugins: [mdxPlugin()],
+    define: defines,
+    naming: {
+      entry: '[name]-[hash].[ext]',
+      chunk: '[name]-[hash].[ext]',
+      asset: '[name]-[hash].[ext]',
+    },
+  })
+  if (!browser.success) {
+    for (const log of browser.logs) console.error(log)
+    throw new Error('Display Case publish: browser bundle failed')
+  }
+
+  const assets = { browser: '', render: '', primer: '' }
+  for (const o of browser.outputs) {
+    if (o.kind !== 'entry-point') continue
+    const name = entryName(o.path)
+    if (name) assets[name] = `${base}/assets/${basename(o.path)}`
+  }
+
+  // SSR renderers for the production server: built once (no watching), imported
+  // by `prod-server`. React stays external (resolved at runtime).
+  const ssrEntries = [ssrEntry]
+  if (ssrPrimerEntry) ssrEntries.push(ssrPrimerEntry)
+  const ssr = await Bun.build({
+    entrypoints: ssrEntries,
+    outdir: join(out, 'server'),
+    target: 'bun',
+    plugins: [mdxPlugin()],
+    define: defines,
+    external: [
+      'react',
+      'react-dom',
+      'react-dom/server',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+    ],
+    naming: { entry: '[name].[ext]', chunk: '[name]-[hash].[ext]' },
+  })
+  if (!ssr.success) {
+    for (const log of ssr.logs) console.error(log)
+    throw new Error('Display Case publish: SSR bundle failed')
+  }
+
+  const manifest = await getManifest(pkgDir)
+  const descriptor: BuildDescriptor = {
+    title: config.title,
+    base,
+    a11y: false,
+    hasPrimer,
+    assets,
+    tokensCss: await readDesignTokens(),
+    globalCss: await readGlobalCss(pkgDir, config),
+    vitrineCss: await readVitrineCss(),
+  }
+
+  await Bun.write(
+    join(out, 'manifest.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  )
+  await Bun.write(
+    join(out, 'dc-build.json'),
+    `${JSON.stringify(descriptor, null, 2)}\n`,
+  )
+
+  // A standalone start script + run recipe, so the build deploys like any service.
+  await Bun.write(
+    join(out, 'server.ts'),
+    `// AUTO-GENERATED by display-case publish — do not edit.\n` +
+      `import { startProdServer } from 'display-case/prod-server'\n` +
+      `await startProdServer(import.meta.dir, { port: Number(process.env.PORT) || 3000 })\n`,
+  )
+  await Bun.write(
+    join(out, 'package.json'),
+    `${JSON.stringify(
+      {
+        name: 'display-case-showcase',
+        private: true,
+        type: 'module',
+        scripts: { start: 'bun server.ts' },
+        dependencies: {
+          'display-case': 'latest',
+          react: '^19',
+          'react-dom': '^19',
+        },
+      },
+      null,
+      2,
+    )}\n`,
+  )
+  await Bun.write(
+    join(out, 'Dockerfile'),
+    [
+      'FROM oven/bun:1 AS base',
+      'WORKDIR /app',
+      'COPY . .',
+      'RUN bun install --production',
+      'ENV PORT=3000',
+      'EXPOSE 3000',
+      `HEALTHCHECK CMD bun -e "await fetch('http://localhost:3000/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"`,
+      'CMD ["bun", "server.ts"]',
+      '',
+    ].join('\n'),
+  )
+
+  // Drop the gitignored codegen leftovers out of the published tree's cache.
+  void cacheDir
+
+  if (opts.static) {
+    const { writeStaticExport } = await import('../server/prod-server')
+    await writeStaticExport(out)
+  }
+
+  return { out, descriptor }
+}

package/src/core/affected.test.ts

@@ -0,0 +1,99 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { makeTempDir, writeFiles } from '../testing/test-helpers'
+import { affectedComponents, importClosure } from './affected'
+
+describe('importClosure', () => {
+  let dir: string
+  beforeAll(async () => {
+    dir = await makeTempDir()
+    await writeFiles(dir, {
+      // Button: case → component → styles.css; styles.css → tokens.css.
+      'Button.case.tsx':
+        "import { Button } from './Button'\nexport default Button",
+      'Button.tsx': "import './styles.css'\nimport { tk } from './util'",
+      'styles.css': "@import './tokens.css';\n.b { color: red }",
+      'tokens.css': ':root { --x: 1 }',
+      'util.ts': "import React from 'react'\nexport const tk = 1",
+      // Unrelated island the Button does not import.
+      'Other.tsx': 'export const Other = 1',
+    })
+  })
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  test('follows relative JS and CSS imports transitively', async () => {
+    const closure = await importClosure([join(dir, 'Button.case.tsx')])
+    expect(closure.has(resolve(dir, 'Button.case.tsx'))).toBe(true)
+    expect(closure.has(resolve(dir, 'Button.tsx'))).toBe(true)
+    expect(closure.has(resolve(dir, 'styles.css'))).toBe(true)
+    expect(closure.has(resolve(dir, 'tokens.css'))).toBe(true)
+    expect(closure.has(resolve(dir, 'util.ts'))).toBe(true)
+  })
+
+  test('does not pull in unrelated files or bare specifiers', async () => {
+    const closure = await importClosure([join(dir, 'Button.case.tsx')])
+    expect(closure.has(resolve(dir, 'Other.tsx'))).toBe(false)
+    // `react` is a bare specifier — not traced, so nothing resolves for it.
+    for (const f of closure) expect(f.includes('node_modules')).toBe(false)
+  })
+
+  test('a missing entry contributes only itself', async () => {
+    const ghost = join(dir, 'Nope.case.tsx')
+    const closure = await importClosure([ghost])
+    expect([...closure]).toEqual([resolve(ghost)])
+  })
+})
+
+describe('affectedComponents', () => {
+  let dir: string
+  let components: { id: string; caseFile: string }[]
+  beforeAll(async () => {
+    dir = await makeTempDir()
+    await writeFiles(dir, {
+      'Button.case.tsx': "import './Button'",
+      'Button.tsx': "import './button.css'",
+      'button.css': '.b {}',
+      'Card.case.tsx': "import './Card'",
+      'Card.tsx': "import { tk } from './shared'",
+      'shared.ts': 'export const tk = 1',
+    })
+    components = [
+      { id: 'button', caseFile: resolve(dir, 'Button.case.tsx') },
+      { id: 'card', caseFile: resolve(dir, 'Card.case.tsx') },
+    ]
+  })
+  afterAll(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  test('a changed leaf affects only the component that imports it', async () => {
+    const affected = await affectedComponents(components, [
+      join(dir, 'button.css'),
+    ])
+    expect([...affected]).toEqual(['button'])
+  })
+
+  test('a shared dependency affects every importer', async () => {
+    const affected = await affectedComponents(components, [
+      join(dir, 'shared.ts'),
+    ])
+    expect([...affected]).toEqual(['card'])
+  })
+
+  test('a changed case file affects its own component', async () => {
+    const affected = await affectedComponents(components, [
+      join(dir, 'Card.case.tsx'),
+    ])
+    expect([...affected]).toEqual(['card'])
+  })
+
+  test('an unrelated change affects nothing', async () => {
+    const affected = await affectedComponents(components, [
+      join(dir, 'README.md'),
+    ])
+    expect(affected.size).toBe(0)
+  })
+})