describe-me 0.1.0

package/src/main.ts

@@ -0,0 +1,41 @@
+/// <reference types="vite/client" />
+import { loadManifest } from './data.js'
+import { el } from './el.js'
+import { renderHeader } from './header.js'
+import { onKey } from './keyboard.js'
+import { renderAll } from './render-all.js'
+import { setRerender } from './rerender.js'
+import { readHash } from './state.js'
+
+setRerender(renderAll)
+
+readHash()
+document.addEventListener('keydown', onKey)
+window.addEventListener('hashchange', () => {
+  readHash()
+  renderAll()
+})
+
+loadManifest().catch((err) => {
+  document
+    .getElementById('app')!
+    .replaceChildren(
+      renderHeader(),
+      el(
+        'div',
+        { class: 'stage' },
+        el('div', { class: 'empty' }, `no manifest yet — run vitest first (${String(err)})`),
+      ),
+    )
+})
+
+/** A failed refresh is not worth breaking the page over; the next one may succeed. */
+const refresh = () => loadManifest().catch(() => undefined)
+
+if (import.meta.hot) {
+  // Dev: the Vite plugin pushes an event whenever the reporter rewrites the manifest.
+  import.meta.hot.on('describe-me:update', () => void refresh())
+} else {
+  // Static site: data only changes on redeploy, so a slow poll is plenty.
+  setInterval(() => void refresh(), 60_000)
+}

package/src/overview-inspector.ts

@@ -0,0 +1,101 @@
+import type { ManifestTest } from '@describe-me/core/types'
+import { computeCoverage } from './coverage.js'
+import { el } from './el.js'
+import { componentNamesInScope } from './scope-components.js'
+import { testsInScope } from './scope.js'
+import { state } from './state.js'
+
+interface CoverageTally {
+  total: number
+  covered: number
+  missing: string[]
+}
+
+function tally(tests: ManifestTest[]): CoverageTally {
+  const docs = state.manifest?.components ?? {}
+  const result: CoverageTally = { total: 0, covered: 0, missing: [] }
+
+  for (const name of componentNamesInScope(tests)) {
+    const doc = docs[name]
+    if (!doc) {
+      continue
+    }
+
+    const own = tests.filter((test) => test.component?.name === name)
+    for (const coverage of computeCoverage(doc, own)) {
+      for (const entry of coverage.entries) {
+        result.total++
+        if (entry.covered) {
+          result.covered++
+        } else {
+          result.missing.push(`${coverage.prop.name}: ${entry.label}`)
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+function renderCoverage(tests: ManifestTest[]): HTMLElement {
+  const section = el('section', {}, el('h3', {}, 'coverage'))
+  const counts = tally(tests)
+  if (!counts.total) {
+    section.append(el('div', { class: 'hint' }, 'no enumerable props here'))
+
+    return section
+  }
+
+  section.append(el('div', {}, `${counts.covered} of ${counts.total} values covered`))
+  for (const label of counts.missing) {
+    section.append(el('div', { class: 'missing-line' }, label))
+  }
+
+  return section
+}
+
+function renderTests(tests: ManifestTest[]): HTMLElement {
+  const failed = tests.filter((test) => test.state === 'failed').length
+  const section = el('section', {}, el('h3', {}, 'tests'))
+  section.append(el('div', {}, `${tests.length} in scope`))
+  section.append(
+    el(
+      'div',
+      { class: failed ? 'missing-line' : 'hint' },
+      failed ? `${failed} failed` : 'none failed',
+    ),
+  )
+
+  return section
+}
+
+function renderComponents(tests: ManifestTest[]): HTMLElement {
+  const docs = state.manifest?.components ?? {}
+  const section = el('section', {}, el('h3', {}, 'components'))
+  for (const name of componentNamesInScope(tests)) {
+    section.append(
+      el(
+        'div',
+        { class: 'component-line' },
+        el('span', {}, name),
+        el('span', { class: 'hint' }, docs[name]?.file ?? 'unknown file'),
+      ),
+    )
+  }
+
+  return section
+}
+
+/** The right column while a suite or module is selected: what the tests do and do not cover. */
+export function renderOverviewInspector(): HTMLElement {
+  const aside = el('aside', { class: 'inspector' })
+  const key = state.suiteKey
+  if (!key) {
+    return aside
+  }
+
+  const tests = testsInScope(key)
+  aside.append(renderCoverage(tests), renderTests(tests), renderComponents(tests))
+
+  return aside
+}

package/src/overview.ts

@@ -0,0 +1,92 @@
+import type { ComponentDoc, ManifestTest } from '@describe-me/core/types'
+import { computeCoverage } from './coverage.js'
+import { el } from './el.js'
+import { renderPropsTable } from './props-table.js'
+import { componentNamesInScope } from './scope-components.js'
+import { renderStatesGallery } from './states-gallery.js'
+import { testsInScope } from './scope.js'
+import { state } from './state.js'
+import { parseSuiteKey } from './suite-key.js'
+
+function titleOf(key: string): string {
+  const { moduleId, path } = parseSuiteKey(key)
+
+  return path[path.length - 1] ?? moduleId
+}
+
+function renderHead(key: string, tests: ManifestTest[], docs: Record<string, ComponentDoc>) {
+  const files = componentNamesInScope(tests)
+    .map((name) => docs[name]?.file)
+    .filter((file): file is string => Boolean(file))
+
+  const frames = tests.reduce((sum, test) => sum + test.frames.length, 0)
+  const parts = [...new Set(files), `${tests.length} tests`, `${frames} frames`]
+
+  return el(
+    'div',
+    { class: 'overview-head' },
+    el('h1', {}, titleOf(key)),
+    el('div', { class: 'overview-meta' }, parts.join(' · ')),
+  )
+}
+
+function renderComponent(
+  name: string,
+  doc: ComponentDoc | undefined,
+  tests: ManifestTest[],
+  showName: boolean,
+): HTMLElement {
+  const section = el('section', { class: 'overview-section' })
+  if (showName) {
+    section.append(el('h2', {}, name))
+  }
+
+  section.append(el('h3', {}, 'props'))
+  if (doc) {
+    section.append(renderPropsTable(computeCoverage(doc, tests)))
+  } else {
+    const hint = 'no type information (rerun tests with the latest reporter)'
+    section.append(renderPropsTable([]), el('div', { class: 'hint' }, hint))
+  }
+
+  section.append(
+    el(
+      'h3',
+      {},
+      'states',
+      el('span', { class: 'head-hint' }, '(last frame of every test in scope)'),
+    ),
+    renderStatesGallery(tests),
+  )
+
+  return section
+}
+
+/** The main column while a suite or module is selected: what its tests document. */
+export function renderOverview(): HTMLElement {
+  const main = el('main', { class: 'overview' })
+  const key = state.suiteKey
+  if (!key) {
+    return main
+  }
+
+  const tests = testsInScope(key)
+  const docs = state.manifest?.components ?? {}
+  main.append(renderHead(key, tests, docs))
+
+  // A single component named like the suite would only repeat the page title.
+  const names = componentNamesInScope(tests)
+  const title = titleOf(key)
+
+  for (const name of names) {
+    const own = tests.filter((test) => test.component?.name === name)
+    const showName = names.length > 1 || name !== title
+    main.append(renderComponent(name, docs[name], own, showName))
+  }
+
+  if (!tests.length) {
+    main.append(el('div', { class: 'empty' }, 'no tests here'))
+  }
+
+  return main
+}

package/src/props-table.ts

@@ -0,0 +1,72 @@
+import type { CoverageEntry, PropCoverage } from './coverage.js'
+import { el } from './el.js'
+
+function chip(entry: CoverageEntry): HTMLElement {
+  const mark = entry.covered ? '✓' : '✗'
+  const tone = entry.covered ? 'covered' : 'missing'
+  const node = el('span', { class: `chip ${tone}` }, `${entry.label} ${mark}`)
+  if (entry.isDefault) {
+    node.append(el('span', { class: 'chip-default' }, ' (default)'))
+  }
+
+  return node
+}
+
+function nameCell(coverage: PropCoverage): HTMLElement {
+  return el(
+    'td',
+    { class: 'prop-name', title: coverage.prop.description ?? false },
+    coverage.prop.name,
+    coverage.prop.required ? el('span', { class: 'req' }, '*') : null,
+  )
+}
+
+function coveredCell(coverage: PropCoverage): HTMLElement {
+  const cell = el('td', { class: 'prop-covered' })
+  if (coverage.entries.length) {
+    for (const entry of coverage.entries) {
+      cell.append(chip(entry))
+    }
+
+    return cell
+  }
+
+  if (coverage.passedIn > 0) {
+    const text = `passed in ${coverage.passedIn} of ${coverage.testsTotal} tests`
+    cell.append(el('span', { class: 'hint' }, text))
+
+    return cell
+  }
+
+  cell.append(
+    el('span', { class: coverage.prop.required ? 'chip missing' : 'hint' }, 'never passed'),
+  )
+
+  return cell
+}
+
+/** The props of one component as a table: name, type, and which values the tests covered. */
+export function renderPropsTable(coverage: PropCoverage[]): HTMLElement {
+  const table = el('table', { class: 'kv props' })
+  table.append(el('tr', {}, el('th', {}, 'prop'), el('th', {}, 'type'), el('th', {}, 'covered')))
+
+  for (const item of coverage) {
+    table.append(
+      el(
+        'tr',
+        {},
+        nameCell(item),
+        el('td', { class: 'prop-type' }, item.prop.type),
+        coveredCell(item),
+      ),
+    )
+  }
+
+  if (!coverage.length) {
+    table.append(
+      el('tr', {}, el('td', { colspan: '3' }, el('span', { class: 'hint' }, 'no props'))),
+    )
+  }
+
+  return table
+}

package/src/render-all.ts

@@ -0,0 +1,17 @@
+import { el } from './el.js'
+import { renderHeader } from './header.js'
+import { renderInspector } from './inspector.js'
+import { renderMain } from './main-panel.js'
+import { renderOverview } from './overview.js'
+import { renderOverviewInspector } from './overview-inspector.js'
+import { renderSidebar } from './sidebar.js'
+import { state } from './state.js'
+
+/** Repaint the whole app from `state`: the overview when a suite is selected, else one test. */
+export function renderAll(): void {
+  const app = document.getElementById('app')!
+  const main = state.suiteKey ? renderOverview() : renderMain()
+  const aside = state.suiteKey ? renderOverviewInspector() : renderInspector()
+
+  app.replaceChildren(renderHeader(), el('div', { class: 'body' }, renderSidebar(), main, aside))
+}

package/src/rerender.ts

@@ -0,0 +1,15 @@
+/**
+ * Indirection so that state and data modules can trigger a repaint without
+ * importing the panels that read them (which would be a cycle).
+ */
+let paint: () => void = () => {}
+
+/** Install the repaint function. Called once from the bootstrap. */
+export function setRerender(fn: () => void): void {
+  paint = fn
+}
+
+/** Repaint the whole app. */
+export function rerender(): void {
+  paint()
+}

package/src/scope-components.ts

@@ -0,0 +1,14 @@
+import type { ManifestTest } from '@describe-me/core/types'
+
+/** Distinct component names recorded by a set of tests, in the order they appear. */
+export function componentNamesInScope(tests: ManifestTest[]): string[] {
+  const names: string[] = []
+  for (const test of tests) {
+    const name = test.component?.name
+    if (name && !names.includes(name)) {
+      names.push(name)
+    }
+  }
+
+  return names
+}

package/src/scope.ts

@@ -0,0 +1,17 @@
+import type { ManifestTest } from '@describe-me/core/types'
+import { parseSuiteKey } from './suite-key.js'
+import { state } from './state.js'
+
+/**
+ * The tests a suite key selects: every test of that module whose suite path
+ * starts with the key's path, so a module-level key takes the whole module.
+ */
+export function testsInScope(key: string): ManifestTest[] {
+  const { moduleId, path } = parseSuiteKey(key)
+  const mod = state.manifest?.modules.find((candidate) => candidate.id === moduleId)
+  if (!mod) {
+    return []
+  }
+
+  return mod.tests.filter((test) => path.every((part, index) => test.path[index] === part))
+}

package/src/sidebar.ts

@@ -0,0 +1,62 @@
+import { el } from './el.js'
+import { select, selectSuite, state } from './state.js'
+import { suiteKey } from './suite-key.js'
+import { buildTree, type SuiteNode } from './tree.js'
+
+function scopeButton(label: string, key: string, kind: 'module' | 'suite'): HTMLElement {
+  return el(
+    'button',
+    {
+      class: `${kind}-button${key === state.suiteKey ? ' active' : ''}`,
+      click: () => selectSuite(key),
+      title: `overview of ${label}`,
+    },
+    label,
+  )
+}
+
+function renderSuite(node: SuiteNode, moduleId: string, path: string[]): HTMLElement {
+  const wrap = el('div', { class: 'suite' })
+  if (node.name) {
+    wrap.append(scopeButton(node.name, suiteKey(moduleId, path), 'suite'))
+  }
+
+  for (const test of node.tests) {
+    wrap.append(
+      el(
+        'button',
+        {
+          class: `test${!state.suiteKey && test.id === state.testId ? ' active' : ''}`,
+          click: () => select(test.id),
+          title: test.fullName,
+        },
+        el('span', { class: `dot ${test.state}` }),
+        el('span', {}, test.name),
+        el('span', { class: 'n' }, String(test.frames.length)),
+      ),
+    )
+  }
+
+  for (const child of node.suites.values()) {
+    wrap.append(renderSuite(child, moduleId, [...path, child.name]))
+  }
+
+  return wrap
+}
+
+/** One block per test module, each holding its suite tree. */
+export function renderSidebar(): HTMLElement {
+  const aside = el('aside', { class: 'sidebar' })
+  for (const mod of state.manifest?.modules ?? []) {
+    aside.append(
+      el(
+        'div',
+        { class: 'module' },
+        scopeButton(mod.id, suiteKey(mod.id, []), 'module'),
+        renderSuite(buildTree(mod), mod.id, []),
+      ),
+    )
+  }
+
+  return aside
+}

package/src/stage.ts

@@ -0,0 +1,28 @@
+import { createCache, createMirror, rebuildIntoSandboxedIframe } from 'rrweb-snapshot'
+import type { ManifestFrame } from '@describe-me/core/types'
+import { loadSnapshot } from './data.js'
+import { state } from './state.js'
+
+let paintToken = 0
+
+/** Replay a snapshot into a fresh sandboxed iframe inside `stage`. */
+export async function paintFrame(stage: HTMLElement, frame: ManifestFrame): Promise<void> {
+  const token = ++paintToken
+  const node = await loadSnapshot(frame.snapshot)
+  if (token !== paintToken) {
+    return
+  }
+
+  stage.replaceChildren()
+  const { iframe } = rebuildIntoSandboxedIframe(node, {
+    root: stage,
+    iframeAttributes: { title: 'snapshot' },
+    cache: createCache(),
+    mirror: createMirror(),
+    hackCss: true,
+  })
+
+  if (state.width !== 'auto') {
+    iframe.style.width = `${state.width}px`
+  }
+}

package/src/state.ts

@@ -0,0 +1,71 @@
+import type { Manifest, ManifestTest } from '@describe-me/core/types'
+import { rerender } from './rerender.js'
+
+export interface State {
+  manifest: Manifest | null
+  testId: string | null
+  /** A sidebar suite or module selection; when set, the overview replaces the frame view. */
+  suiteKey: string | null
+  frame: number
+  width: 'auto' | '768' | '375'
+}
+
+export const state: State = {
+  manifest: null,
+  testId: null,
+  suiteKey: null,
+  frame: 0,
+  width: 'auto',
+}
+
+export function readHash(): void {
+  const params = new URLSearchParams(location.hash.slice(1))
+  state.testId = params.get('test')
+  state.suiteKey = params.get('suite')
+  state.frame = Number(params.get('frame') ?? 0) || 0
+}
+
+export function writeHash(): void {
+  const params = new URLSearchParams()
+  if (state.suiteKey) {
+    params.set('suite', state.suiteKey)
+  }
+
+  if (state.testId) {
+    params.set('test', state.testId)
+  }
+
+  if (state.frame) {
+    params.set('frame', String(state.frame))
+  }
+
+  history.replaceState(null, '', `#${params.toString()}`)
+}
+
+export function allTests(manifest: Manifest): ManifestTest[] {
+  return manifest.modules.flatMap((mod) => mod.tests)
+}
+
+export function currentTest(): ManifestTest | null {
+  if (!state.manifest) {
+    return null
+  }
+
+  return allTests(state.manifest).find((test) => test.id === state.testId) ?? null
+}
+
+/** Show one test. Leaving the overview is the whole point, so the suite is cleared. */
+export function select(testId: string, frame = 0): void {
+  state.testId = testId
+  state.suiteKey = null
+  state.frame = frame
+  writeHash()
+  rerender()
+}
+
+/** Show the overview of a suite or module. The selected test is kept, so going back works. */
+export function selectSuite(key: string): void {
+  state.suiteKey = key
+  writeHash()
+  rerender()
+}