describe-me 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Łotysz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,34 @@
+# describe-me
+
+The viewer and CLI of [describe-me](https://github.com/grzehub/describe-me):
+living component documentation generated from the Vitest tests you already have.
+`describe` blocks become the sidebar, each `it` is a story, each step is a frame
+you can scrub through.
+
+It reads the `.describe-me/` directory that `@describe-me/vitest`'s reporter
+writes, and replays the snapshots in a sandboxed iframe.
+
+## Install
+
+```sh
+pnpm add -D describe-me @describe-me/vitest @describe-me/react
+```
+
+## Usage
+
+```sh
+describe-me dev                  # viewer on http://localhost:6006, live while vitest --watch runs
+describe-me build --out docs     # self-contained static site: viewer + __data/
+```
+
+| Flag     | Default            | Meaning                           |
+| -------- | ------------------ | --------------------------------- |
+| `--data` | `.describe-me`     | The directory the reporter wrote. |
+| `--out`  | `describe-me-dist` | Output directory for `build`.     |
+| `--port` | `6006`             | Port for `dev`.                   |
+
+The static site uses relative URLs, so it works from a sub-path such as
+GitHub Pages.
+
+See the [root README](https://github.com/grzehub/describe-me#readme) for the
+full picture.

package/bin/describe-me.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Committed entry point, so pnpm can link the binary at install time, before
+// the CLI is compiled. The real code lives in dist-cli/ (built by `pnpm build`).
+import '../dist-cli/main.js'

package/dist-cli/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-cli/main.js

@@ -0,0 +1,25 @@
+import { parseArgs } from './parse-args.js';
+import { runBuild } from './run-build.js';
+import { runDev } from './run-dev.js';
+const USAGE = `describe-me — living component docs from your tests
+
+  describe-me dev   [--data .describe-me] [--port 6006]   viewer with live updates
+  describe-me build [--data .describe-me] [--out describe-me-dist]   static site
+`;
+/** Entry point of the `describe-me` binary. */
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.command === 'help') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (options.command === 'build') {
+        await runBuild(options.data, options.out);
+        return;
+    }
+    await runDev(options.data, options.port);
+}
+main().catch((error) => {
+    process.stderr.write(`describe-me: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist-cli/parse-args.d.ts

@@ -0,0 +1,12 @@
+export type Command = 'dev' | 'build' | 'help';
+export interface CliOptions {
+    command: Command;
+    /** Directory written by the reporter. */
+    data: string;
+    /** Output directory for `build`. */
+    out: string;
+    /** Port for `dev`. */
+    port: number;
+}
+/** Turn `describe-me <command> [--data dir] [--out dir] [--port n]` into options with defaults. */
+export declare function parseArgs(argv: string[]): CliOptions;

package/dist-cli/parse-args.js

@@ -0,0 +1,29 @@
+import { parseArgs as parseNodeArgs } from 'node:util';
+function commandFrom(positional, help) {
+    if (help || positional === undefined) {
+        return 'help';
+    }
+    if (positional === 'build') {
+        return 'build';
+    }
+    return 'dev';
+}
+/** Turn `describe-me <command> [--data dir] [--out dir] [--port n]` into options with defaults. */
+export function parseArgs(argv) {
+    const { values, positionals } = parseNodeArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            data: { type: 'string', default: '.describe-me' },
+            out: { type: 'string', default: 'describe-me-dist' },
+            port: { type: 'string', default: '6006' },
+            help: { type: 'boolean', short: 'h', default: false },
+        },
+    });
+    return {
+        command: commandFrom(positionals[0], values.help),
+        data: values.data,
+        out: values.out,
+        port: Number(values.port),
+    };
+}

package/dist-cli/run-build.d.ts

@@ -0,0 +1,2 @@
+/** Produce a self-contained static site: the viewer plus the data directory under `__data/`. */
+export declare function runBuild(data: string, out: string): Promise<void>;

package/dist-cli/run-build.js

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+import { build } from 'vite';
+import { viewerRoot } from './viewer-root.js';
+/** Produce a self-contained static site: the viewer plus the data directory under `__data/`. */
+export async function runBuild(data, out) {
+    process.env.DESCRIBE_ME_DIR = resolve(data);
+    const root = viewerRoot();
+    await build({
+        root,
+        configFile: resolve(root, 'vite.config.ts'),
+        build: { outDir: resolve(out), emptyOutDir: true },
+    });
+}

package/dist-cli/run-dev.d.ts

@@ -0,0 +1,2 @@
+/** Start the viewer against a data directory, with live updates as the reporter rewrites it. */
+export declare function runDev(data: string, port: number): Promise<void>;

package/dist-cli/run-dev.js

@@ -0,0 +1,15 @@
+import { resolve } from 'node:path';
+import { createServer } from 'vite';
+import { viewerRoot } from './viewer-root.js';
+/** Start the viewer against a data directory, with live updates as the reporter rewrites it. */
+export async function runDev(data, port) {
+    process.env.DESCRIBE_ME_DIR = resolve(data);
+    const root = viewerRoot();
+    const server = await createServer({
+        root,
+        configFile: resolve(root, 'vite.config.ts'),
+        server: { port },
+    });
+    await server.listen();
+    server.printUrls();
+}

package/dist-cli/viewer-root.d.ts

@@ -0,0 +1,2 @@
+/** The package directory that holds `index.html`, `src/` and `vite.config.ts`. */
+export declare function viewerRoot(): string;

package/dist-cli/viewer-root.js

@@ -0,0 +1,5 @@
+import { fileURLToPath } from 'node:url';
+/** The package directory that holds `index.html`, `src/` and `vite.config.ts`. */
+export function viewerRoot() {
+    return fileURLToPath(new URL('..', import.meta.url));
+}

package/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>describe-me</title>
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "describe-me",
+  "version": "0.1.0",
+  "description": "Living component documentation generated from your Vitest tests: viewer and CLI",
+  "keywords": [
+    "vitest",
+    "storybook",
+    "component documentation",
+    "visual testing",
+    "testing",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Grzegorz Łotysz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grzehub/describe-me.git",
+    "directory": "packages/viewer"
+  },
+  "homepage": "https://grzehub.github.io/describe-me/",
+  "bugs": "https://github.com/grzehub/describe-me/issues",
+  "type": "module",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "describe-me": "./bin/describe-me.js"
+  },
+  "files": [
+    "bin",
+    "dist-cli",
+    "index.html",
+    "src",
+    "vite.config.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "rrweb-snapshot": "^2.1.6",
+    "vite": "^8.3.0",
+    "@describe-me/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22"
+  },
+  "scripts": {
+    "build": "rimraf dist-cli && tsc -p tsconfig.cli.json",
+    "dev": "node dist-cli/main.js dev --data ../../examples/react-basic/.describe-me"
+  }
+}

package/src/coverage.ts

@@ -0,0 +1,75 @@
+import type { ComponentDoc, ManifestTest, PropDoc } from '@describe-me/core/types'
+
+/** One value of an enumerable prop, and whether the tests in scope produced it. */
+export interface CoverageEntry {
+  label: string
+  covered: boolean
+  isDefault: boolean
+}
+
+/** What the props table shows for one prop of one component. */
+export interface PropCoverage {
+  prop: PropDoc
+  entries: CoverageEntry[]
+  /** Tests that passed the prop at least once. Only meaningful without entries. */
+  passedIn: number
+  testsTotal: number
+}
+
+/** The manifest keeps literal types as source text, so `'primary'` arrives quoted. */
+function unquote(text: string): string {
+  for (const quote of ["'", '"']) {
+    if (text.length > 1 && text.startsWith(quote) && text.endsWith(quote)) {
+      return text.slice(1, -1)
+    }
+  }
+
+  return text
+}
+
+/** The props of every `render` frame of one test; frames without props are ignored. */
+function renderProps(test: ManifestTest): Record<string, unknown>[] {
+  const passed: Record<string, unknown>[] = []
+  for (const frame of test.frames) {
+    const props = frame.kind === 'render' ? frame.meta?.props : undefined
+    if (props && typeof props === 'object' && !Array.isArray(props)) {
+      passed.push(props as Record<string, unknown>)
+    }
+  }
+
+  return passed
+}
+
+function wasPassed(passed: Record<string, unknown>[], name: string, label: string): boolean {
+  return passed.some((props) => name in props && String(props[name]) === label)
+}
+
+function entriesFor(prop: PropDoc, passed: Record<string, unknown>[]): CoverageEntry[] {
+  if (prop.kind !== 'literals' && prop.kind !== 'boolean') {
+    return []
+  }
+
+  // Omitting the prop exercises its default, so it covers the matching value.
+  const omitted = passed.some((props) => !(prop.name in props))
+
+  return (prop.values ?? []).map((value) => {
+    const label = unquote(value)
+    const isDefault = prop.defaultValue !== undefined && unquote(prop.defaultValue) === label
+    const covered = wasPassed(passed, prop.name, label) || (isDefault && omitted)
+
+    return { label, covered, isDefault }
+  })
+}
+
+/** How well a set of tests exercises a component's props, prop by prop. */
+export function computeCoverage(doc: ComponentDoc, tests: ManifestTest[]): PropCoverage[] {
+  const perTest = tests.map((test) => renderProps(test))
+  const passed = perTest.flat()
+
+  return doc.props.map((prop) => ({
+    prop,
+    entries: entriesFor(prop, passed),
+    passedIn: perTest.filter((frames) => frames.some((props) => prop.name in props)).length,
+    testsTotal: tests.length,
+  }))
+}

package/src/data.ts

@@ -0,0 +1,54 @@
+import type { rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
+import type { Manifest } from '@describe-me/core/types'
+import { allTests, currentTest, state } from './state.js'
+import { rerender } from './rerender.js'
+
+/** rrweb's serialized document node; the package does not re-export the type. */
+type SerializedNode = Parameters<typeof rebuildIntoSandboxedIframe>[0]
+
+const snapshotCache = new Map<string, Promise<SerializedNode>>()
+
+/**
+ * Fetch the manifest and repaint, but only if it differs from the one on
+ * screen. Polling an unchanged static site must not re-render or drop caches.
+ */
+export async function loadManifest(): Promise<void> {
+  const response = await fetch('__data/manifest.json', { cache: 'no-store' })
+  if (!response.ok) {
+    throw new Error(`manifest: ${response.status}`)
+  }
+
+  const next = (await response.json()) as Manifest
+  if (state.manifest?.generatedAt === next.generatedAt) {
+    return
+  }
+
+  state.manifest = next
+  snapshotCache.clear()
+  if (!currentTest()) {
+    const first = allTests(state.manifest)[0]
+    state.testId = first?.id ?? null
+    state.frame = 0
+  }
+
+  const test = currentTest()
+  if (test) {
+    state.frame = Math.min(state.frame, Math.max(0, test.frames.length - 1))
+  }
+
+  rerender()
+}
+
+/** Fetch one serialized DOM, memoized until the next manifest load. */
+export function loadSnapshot(path: string): Promise<SerializedNode> {
+  let pending = snapshotCache.get(path)
+  if (!pending) {
+    pending = fetch(`__data/${path}`, { cache: 'no-store' }).then(
+      (response) => response.json() as Promise<SerializedNode>,
+    )
+
+    snapshotCache.set(path, pending)
+  }
+
+  return pending
+}

package/src/el.ts

@@ -0,0 +1,25 @@
+/** Terse `createElement`: attributes, event listeners (by event name), children. */
+export function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  attrs: Record<string, string | boolean | ((e: Event) => void)> = {},
+  ...children: (Node | string | null | undefined | false)[]
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag)
+  for (const [key, value] of Object.entries(attrs)) {
+    if (typeof value === 'function') {
+      node.addEventListener(key, value)
+    } else if (value === true) {
+      node.setAttribute(key, '')
+    } else if (value !== false) {
+      node.setAttribute(key, value)
+    }
+  }
+
+  for (const child of children) {
+    if (child) {
+      node.append(child)
+    }
+  }
+
+  return node
+}

package/src/header.ts

@@ -0,0 +1,31 @@
+import { el } from './el.js'
+import { allTests, state } from './state.js'
+
+/** Wordmark, pass/fail counts and the time of the last run. */
+export function renderHeader(): HTMLElement {
+  const manifest = state.manifest
+  const tests = manifest ? allTests(manifest) : []
+  const passed = tests.filter((test) => test.state === 'passed').length
+  const failed = tests.filter((test) => test.state === 'failed').length
+  const summary = el('span', { class: 'summary' })
+  summary.append(
+    el('b', {}, String(tests.length)),
+    ' tests · ',
+    el('b', {}, String(passed)),
+    ' passed',
+  )
+
+  if (failed) {
+    summary.append(' · ', el('b', { class: 'fail' }, String(failed)), ' failed')
+  }
+
+  const wm = el('span', { class: 'wordmark' }, 'describe', el('span', { class: 'me' }, '-me'))
+  const when = manifest ? new Date(manifest.generatedAt).toLocaleTimeString() : '…'
+  return el(
+    'header',
+    { class: 'header' },
+    wm,
+    summary,
+    el('span', { class: 'right live' }, `updated ${when}`),
+  )
+}

package/src/inspector.ts

@@ -0,0 +1,86 @@
+import { el } from './el.js'
+import { currentTest, state } from './state.js'
+import { valueCell } from './value-cell.js'
+
+/** Right-hand pane: test status, component props, current frame, errors. */
+export function renderInspector(): HTMLElement {
+  const test = currentTest()
+  const aside = el('aside', { class: 'inspector' })
+  if (!test) {
+    return aside
+  }
+
+  const frame = test.frames[state.frame]
+  const props =
+    (frame?.meta?.props as Record<string, unknown> | undefined) ?? test.component?.props ?? {}
+
+  const status = el('section', {}, el('h3', {}, 'test'))
+  status.append(
+    el(
+      'div',
+      { class: 'status' },
+      el('span', { class: `dot ${test.state}` }),
+      test.state,
+      test.duration != null
+        ? el('span', { class: 'hint' }, `${Math.round(test.duration)}ms`)
+        : null,
+    ),
+  )
+
+  aside.append(status)
+
+  if (test.component) {
+    const table = el('table', { class: 'kv' })
+    for (const [key, value] of Object.entries(props)) {
+      table.append(el('tr', {}, el('td', {}, key), el('td', {}, valueCell(value))))
+    }
+
+    if (!Object.keys(props).length) {
+      table.append(el('tr', {}, el('td', {}, el('span', { class: 'hint' }, 'no props'))))
+    }
+
+    aside.append(el('section', {}, el('h3', {}, `component · ${test.component.name}`), table))
+  }
+
+  if (frame) {
+    aside.append(
+      el(
+        'section',
+        {},
+        el('h3', {}, `frame ${state.frame + 1} / ${test.frames.length}`),
+        el('div', {}, frame.label),
+        el('div', { class: 'hint' }, `${frame.kind} · ${frame.at}ms into the test`),
+      ),
+    )
+  }
+
+  if (test.errors?.length) {
+    const sec = el('section', {}, el('h3', {}, 'errors'))
+    for (const error of test.errors) {
+      sec.append(el('pre', { class: 'err' }, error.message))
+    }
+
+    aside.append(sec)
+  }
+
+  aside.append(
+    el(
+      'section',
+      {},
+      el(
+        'div',
+        { class: 'hint' },
+        el('kbd', {}, '←'),
+        ' ',
+        el('kbd', {}, '→'),
+        ' frames · ',
+        el('kbd', {}, '↑'),
+        ' ',
+        el('kbd', {}, '↓'),
+        ' tests',
+      ),
+    ),
+  )
+
+  return aside
+}

package/src/keyboard.ts

@@ -0,0 +1,58 @@
+import { rerender } from './rerender.js'
+import { testsInScope } from './scope.js'
+import { allTests, currentTest, select, state, writeHash } from './state.js'
+
+/** In the overview, ↑ ↓ jump into the scope: the first or the last test it holds. */
+function onSuiteKey(event: KeyboardEvent, key: string): void {
+  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') {
+    return
+  }
+
+  const tests = testsInScope(key)
+  const next = event.key === 'ArrowDown' ? tests[0] : tests[tests.length - 1]
+  if (next) {
+    select(next.id)
+  }
+
+  event.preventDefault()
+}
+
+/** ← → step through frames, ↑ ↓ through tests. */
+export function onKey(event: KeyboardEvent): void {
+  if (!state.manifest) {
+    return
+  }
+
+  if (state.suiteKey) {
+    onSuiteKey(event, state.suiteKey)
+    return
+  }
+
+  const test = currentTest()
+  if (!test) {
+    return
+  }
+
+  if (event.key === 'ArrowRight' && state.frame < test.frames.length - 1) {
+    state.frame++
+    writeHash()
+    rerender()
+  }
+
+  if (event.key === 'ArrowLeft' && state.frame > 0) {
+    state.frame--
+    writeHash()
+    rerender()
+  }
+
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    const tests = allTests(state.manifest)
+    const index = tests.findIndex((candidate) => candidate.id === test.id)
+    const next = tests[index + (event.key === 'ArrowDown' ? 1 : -1)]
+    if (next) {
+      select(next.id)
+    }
+
+    event.preventDefault()
+  }
+}

package/src/main-panel.ts

@@ -0,0 +1,69 @@
+import { el } from './el.js'
+import { rerender } from './rerender.js'
+import { paintFrame } from './stage.js'
+import { currentTest, state, writeHash } from './state.js'
+
+/** Breadcrumbs, viewport buttons, the replay stage and the frame timeline. */
+export function renderMain(): HTMLElement {
+  const test = currentTest()
+  const frame = test?.frames[state.frame]
+
+  const crumbs = el('div', { class: 'crumbs' })
+  if (test) {
+    for (const part of test.path) {
+      crumbs.append(el('span', {}, part), el('span', { class: 'sep' }, '›'))
+    }
+
+    crumbs.append(el('span', { class: 'cur' }, test.name))
+  }
+
+  const tools = el('div', { class: 'tools' })
+  for (const width of ['auto', '768', '375'] as const) {
+    tools.append(
+      el(
+        'button',
+        {
+          class: state.width === width ? 'on' : '',
+          click: () => {
+            state.width = width
+            rerender()
+          },
+        },
+        width === 'auto' ? '100%' : `${width}px`,
+      ),
+    )
+  }
+
+  crumbs.append(tools)
+
+  const stage = el('div', { class: 'stage' })
+  if (frame) {
+    void paintFrame(stage, frame)
+  } else {
+    stage.append(
+      el('div', { class: 'empty' }, test ? 'no frames recorded for this test' : 'select a test'),
+    )
+  }
+
+  const timeline = el('div', { class: 'timeline' })
+  test?.frames.forEach((timelineFrame, i) => {
+    timeline.append(
+      el(
+        'button',
+        {
+          class: `frame ${timelineFrame.kind}${i === state.frame ? ' active' : ''}`,
+          click: () => {
+            state.frame = i
+            writeHash()
+            rerender()
+          },
+        },
+        el('span', { class: 'k' }, timelineFrame.kind),
+        el('span', {}, timelineFrame.label),
+        el('span', { class: 't' }, `${timelineFrame.at}ms`),
+      ),
+    )
+  })
+
+  return el('main', { class: 'main' }, crumbs, stage, timeline)
+}