@crab-dev/wake 0.1.20 → 0.1.22

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.1.22
+
+- Added the experimental Wake-native, React-first `wake test` system, `runTests()` and `TestContext`
+  Node APIs, explicit `@crab-dev/wake/test` ESM/CommonJS imports, isolated V8 suite realms, Wake
+  snapshots, function/network mocks, an async clock, projects, sharding, and a token-authenticated
+  crash-isolated test host. ADR 0020 defines the private fast-DOM and system-Chromium boundary;
+  external runner/config/plugin/result compatibility is intentionally outside the contract.
+- Added typed Chromium input and browser screenshot snapshots. `toMatchScreenshot()` stores
+  rendering-profiled PNG baselines and emits received PNG plus self-contained visual-diff artifacts
+  without exposing raw CDP or adding a second browser event consumer.
+
+## 0.1.21
+
+- Added aggregate Wake Docs workspaces with isolated production bundles, deterministic manifests,
+  transactional output commits, one-port lazy/eager development mounts, scoped HMR events, and
+  embedded or standalone workbench presentation.
+- Fixed MDX JSX structure generation by lifting block JSX and splitting mixed paragraphs at AST
+  boundaries, preventing invalid paragraph/block nesting without changing inline JSX or component
+  Markdown children.
+- Fixed constrained, defaulted, and comma-disambiguated generic arrow functions in TSX so Wake
+  parses them as TypeScript instead of emitting cascading JSX diagnostics.
+- Added a TypeScript 7 compatibility gate covering strict type checking, TS/TSX erasure, module
+  extensions, value transforms, and production/development JSX runtime execution.
+- Fixed top-level TypeScript overload signatures so only their implementation is emitted, and
+  removed false runtime dependencies from imports and exports containing only inline `type`
+  specifiers.
+
 ## 0.1.20
 
 - Added a modern interactive terminal console with editable commands, history, Unicode-aware selection, clipboard copy and paste, and safe development-server opening across Rust and npm CLIs.

package/bin/terminal.mjs

@@ -1,5 +1,3 @@
-import clipboard from 'clipboardy'
-import open from 'open'
 import stringWidth from 'string-width'
 
 import {
@@ -15,6 +13,24 @@ const BOLD = '\x1b[1m'
 const DIM = '\x1b[2m'
 const MAX_ACTIVITY = 200
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧']
+const OPTIONAL_CLIPBOARD_MODULE = 'clip' + 'boardy'
+const OPTIONAL_OPEN_MODULE = 'op' + 'en'
+
+const defaultClipboard = {
+  async read() {
+    const { default: clipboard } = await import(OPTIONAL_CLIPBOARD_MODULE)
+    return clipboard.read()
+  },
+  async write(value) {
+    const { default: clipboard } = await import(OPTIONAL_CLIPBOARD_MODULE)
+    return clipboard.write(value)
+  },
+}
+
+async function defaultOpenUrl(value) {
+  const { default: open } = await import(OPTIONAL_OPEN_MODULE)
+  return open(value)
+}
 
 export function supportsColor(stream = process.stderr, env = process.env) {
   return stream.isTTY === true && !Object.hasOwn(env, 'NO_COLOR')
@@ -267,6 +283,7 @@ export function createDashboardState({
     rebuilds: 0,
     startedAt: Date.now(),
     activity: [],
+    workspaceState: undefined,
     scrollFromBottom: 0,
   }
   pushActivity(state, 'info', 'Starting Wake…')
@@ -307,6 +324,17 @@ export function applyDashboardEvent(state, event) {
   } else if (event.type === 'diagnostic') {
     state.status = 'error'
     pushActivity(state, 'error', formatDiagnostic(createUi(false), event.diagnostic).join('\n'))
+  } else if (event.type === 'workspaceState') {
+    state.workspaceState = {
+      total: event.total,
+      loaded: event.loaded,
+      failed: event.failed,
+      current: event.current,
+      failedNames: event.failedNames || [],
+    }
+    if (event.current) {
+      pushActivity(state, 'info', `Loading workspace ${event.current}…`)
+    }
   } else if (event.type === 'closed') {
     state.status = 'stopped'
     pushActivity(state, 'info', 'Wake stopped')
@@ -412,6 +440,14 @@ function activityRows(state, available) {
   return rows.slice(start, end)
 }
 
+function workspaceText(state) {
+  const workspaces = state.workspaceState
+  if (!workspaces) return undefined
+  const current = workspaces.current ? ` · loading ${workspaces.current}` : ''
+  const failed = workspaces.failed ? ` · ${workspaces.failed} failed` : ''
+  return `WORKSPACES  ${workspaces.loaded}/${workspaces.total} loaded${failed}${current}`
+}
+
 function activityRowCount(state) {
   return state.activity.reduce((count, item) => count + String(item.message).split('\n').length, 0)
 }
@@ -442,6 +478,7 @@ function plainFrame(state, width, height, editor = new InputEditor(), notice) {
       boxLine(metricsText(state), width),
       separator(width, 'ACTIVITY'),
     ]
+    if (workspaceText(state)) fixed.splice(-1, 0, boxLine(workspaceText(state), width))
     activityHeight = Math.max(1, height - fixed.length - 2)
   } else {
     fixed = [
@@ -455,6 +492,7 @@ function plainFrame(state, width, height, editor = new InputEditor(), notice) {
       boxLine(metricsText(state), width),
       separator(width, 'ACTIVITY'),
     ]
+    if (workspaceText(state)) fixed.splice(-1, 0, boxLine(workspaceText(state), width))
     activityHeight = Math.max(1, height - fixed.length - 2)
   }
 
@@ -528,8 +566,8 @@ export function createDashboardSession(
     input = process.stdin,
     output = process.stderr,
     ui = createUi(),
-    clipboardAdapter = clipboard,
-    openUrl = open,
+    clipboardAdapter = defaultClipboard,
+    openUrl = defaultOpenUrl,
     env = process.env,
   } = {},
 ) {

package/bin/wake.mjs

@@ -1,19 +1,23 @@
 #!/usr/bin/env node
 
+import { readFileSync, writeFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import {
   build,
   buildLibrary,
   buildDocs,
   bundle,
+  createTestContext,
   generateCssToken,
   generateDocgen,
+  runTests,
   startDevServer,
   startDocsDevServer,
   version,
   WakeError,
 } from '../index.mjs'
 import { parse, tokenize } from '../experimental.mjs'
+import testContextInternal from '../test-context-internal.cjs'
 import {
   applyDashboardEvent,
   createDashboardSession,
@@ -47,6 +51,12 @@ Usage:
   wake docs dev [root] [--mode site|components] [--host HOST] [--port PORT] [--open]
   wake parse <file> [--format auto|human|json]
   wake tokenize <file> [--format auto|human|json]
+  wake test [patterns...] [--root DIR] [--name-pattern TEXT] [--project NAME]
+            [--environment auto|dom|browser] [--watch] [--changed] [--related PATH...]
+            [--coverage] [--update-snapshots] [--serial] [--workers COUNT]
+            [--bail [COUNT]] [--shard INDEX/TOTAL] [--seed SEED] [--shuffle]
+            [--reporter pretty|json|junit] [--output FILE] [--allow-no-tests]
+            [--browser-path FILE] [--headful]
   wake --version
 
 Options:
@@ -89,6 +99,68 @@ function takeOptions(args, name, usage = false) {
   }
 }
 
+function takeVariadicOptions(args, name) {
+  const values = []
+  for (;;) {
+    const index = args.indexOf(name)
+    if (index === -1) return values
+    let end = index + 1
+    while (end < args.length && !args[end].startsWith('-')) end += 1
+    if (end === index + 1) throw testUsageError(`${name} requires at least one value`)
+    values.push(...args.slice(index + 1, end))
+    args.splice(index, end - index)
+  }
+}
+
+function testUsageError(message) {
+  const error = new WakeError('WAKE_TEST_CONFIG', message)
+  error.exitCode = 2
+  return error
+}
+
+function validateTestChoice(value, name, choices) {
+  if (value !== undefined && !choices.includes(value)) {
+    throw testUsageError(`${name} must be one of: ${choices.join(', ')}`)
+  }
+  return value
+}
+
+function parseTestWorkers(value) {
+  if (value === undefined || value === 'auto') return value
+  if (/^[1-9][0-9]*$/.test(value)) {
+    const count = Number(value)
+    if (Number.isSafeInteger(count)) return count
+  }
+  const match = /^([1-9][0-9]?)%$|^(100)%$/.exec(value)
+  if (match) return `${Number(match[1] || match[2])}%`
+  throw testUsageError('--workers requires auto, a positive integer, or 1%-100%')
+}
+
+function takeTestBail(args) {
+  const index = args.indexOf('--bail')
+  if (index === -1) return undefined
+  const candidate = args[index + 1]
+  const hasValue = candidate !== undefined && !candidate.startsWith('-')
+  const value = hasValue ? Number(candidate) : 1
+  args.splice(index, hasValue ? 2 : 1)
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw testUsageError('--bail requires a non-negative integer')
+  }
+  return value
+}
+
+function parseTestShard(value) {
+  if (value === undefined) return undefined
+  const match = /^([1-9][0-9]*)\/([1-9][0-9]*)$/.exec(value)
+  if (!match) throw testUsageError('--shard requires the 1-based INDEX/TOTAL form')
+  const index = Number(match[1])
+  const total = Number(match[2])
+  if (!Number.isSafeInteger(index) || !Number.isSafeInteger(total) || index > total) {
+    throw testUsageError('--shard requires 1 <= INDEX <= TOTAL')
+  }
+  return `${index}/${total}`
+}
+
 function commonOptions(args) {
   return {
     configPath: takeOption(args, '--config'),
@@ -137,6 +209,114 @@ function printResult(ui, result, label, extra = '') {
   printLines(formatBuildResult(ui, result, label, extra))
 }
 
+function formatTestFailure(failure) {
+  let rendered = failure.code ? `${failure.code}: ` : ''
+  rendered += failure.message
+  if (failure.location) {
+    rendered += `\n  at ${failure.location.path}:${failure.location.line}:${failure.location.column}`
+  }
+  if (failure.diff?.unified) rendered += `\n${failure.diff.unified}`
+  if (failure.stack && !rendered.includes(failure.stack)) rendered += `\n${failure.stack}`
+  return rendered
+}
+
+function xmlEscape(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;')
+}
+
+function junitTestReport(result) {
+  const suiteErrors = result.suites.filter((suite) => suite.failures.length > 0).length
+  const pending = result.counts.tests.skipped + result.counts.tests.todo
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<testsuites tests="${result.counts.tests.total + suiteErrors}" failures="${result.counts.tests.failed}" errors="${suiteErrors}" skipped="${pending}" time="${(result.durationMs / 1_000).toFixed(3)}">`,
+  ]
+  for (const suite of result.suites) {
+    const failures = suite.tests.filter((testCase) => testCase.status === 'failed').length
+    const skipped = suite.tests.filter((testCase) => testCase.status === 'skipped' || testCase.status === 'todo').length
+    const suiteError = suite.failures.length > 0 ? 1 : 0
+    lines.push(`  <testsuite name="${xmlEscape(suite.path)}" tests="${suite.tests.length + suiteError}" failures="${failures}" errors="${suiteError}" skipped="${skipped}" time="${(suite.durationMs / 1_000).toFixed(3)}">`)
+    for (const testCase of suite.tests) {
+      const prefix = `    <testcase name="${xmlEscape(testCase.name)}" classname="${xmlEscape(suite.path)}" time="${(testCase.durationMs / 1_000).toFixed(3)}">`
+      if (testCase.status === 'failed') {
+        lines.push(`${prefix}<failure>${xmlEscape(testCase.failures.map(formatTestFailure).join('\n'))}</failure></testcase>`)
+      } else if (testCase.status === 'skipped' || testCase.status === 'todo') {
+        lines.push(`${prefix}<skipped /></testcase>`)
+      } else {
+        lines.push(`${prefix}</testcase>`)
+      }
+    }
+    if (suite.failures.length > 0) {
+      lines.push(`    <testcase name="[suite setup]"><error>${xmlEscape(suite.failures.map(formatTestFailure).join('\n'))}</error></testcase>`)
+    }
+    lines.push('  </testsuite>')
+  }
+  lines.push('</testsuites>')
+  return lines.join('\n')
+}
+
+function printTestRun(result, reporter = 'pretty', output, includeDiagnostics = true) {
+  if (reporter !== 'pretty') {
+    const report = reporter === 'json' ? JSON.stringify(result) : junitTestReport(result)
+    if (output) writeFileSync(output, report)
+    else console.log(report)
+    return
+  }
+  for (const suite of result.suites) {
+    const status = suite.status === 'failed'
+      ? 'FAIL'
+      : suite.status === 'skipped'
+        ? 'SKIP'
+        : 'PASS'
+    console.error(`${status} ${suite.path}`)
+    for (const testCase of suite.tests) {
+      const marker = testCase.status === 'passed'
+        ? '✓'
+        : testCase.status === 'failed'
+          ? '✕'
+          : testCase.status === 'todo'
+            ? '✎'
+            : '○'
+      console.error(`  ${marker} ${testCase.name}`)
+      for (const failure of testCase.failures) {
+        console.error(`    ${formatTestFailure(failure).replaceAll('\n', '\n    ')}`)
+      }
+    }
+    for (const failure of suite.failures) {
+      console.error(`  ${formatTestFailure(failure).replaceAll('\n', '\n  ')}`)
+    }
+  }
+  console.error(`Test Suites: ${result.counts.suites.passed} passed, ${result.counts.suites.failed} failed, ${result.counts.suites.total} total`)
+  console.error(`Tests:       ${result.counts.tests.passed} passed, ${result.counts.tests.failed} failed, ${result.counts.tests.skipped + result.counts.tests.todo} pending, ${result.counts.tests.total} total`)
+  const coverageText = result.artifacts.find((artifact) => artifact.kind === 'coverage-text')
+  if (coverageText) {
+    console.error(readFileSync(coverageText.path, 'utf8').trimEnd())
+  }
+  console.error(`Seed:        ${result.seed}`)
+  console.error(`Time:        ${result.durationMs} ms`)
+  if (result.terminationReason !== 'completed') {
+    console.error(`Termination: ${result.terminationReason}`)
+  }
+  if (includeDiagnostics) {
+    for (const diagnostic of result.diagnostics) {
+      console.error(`${diagnostic.code}: ${diagnostic.message}`)
+    }
+  }
+}
+
+function testResultExitCode(result) {
+  if (result.terminationReason === 'cancelled' || result.terminationReason === 'watch-restart') {
+    return 130
+  }
+  if (['host-crash', 'oom', 'internal-error'].includes(result.terminationReason)) return 2
+  return result.success ? 0 : 1
+}
+
 function metricsFromEvent(event) {
   return {
     modules: event.modules,
@@ -187,6 +367,10 @@ async function runServer(factory, options, command, root, ui, uiMode) {
       applyDashboardEvent(state, { type: 'diagnostic', diagnostic })
       dashboard?.draw()
     }
+    const onWorkspaceState = (event) => {
+      applyDashboardEvent(state, event)
+      dashboard?.draw()
+    }
     const onClosed = () => {
       applyDashboardEvent(state, { type: 'closed' })
       dashboard?.draw()
@@ -194,6 +378,7 @@ async function runServer(factory, options, command, root, ui, uiMode) {
     server.on('rebuildStart', onRebuildStart)
     server.on('rebuilt', onRebuilt)
     server.on('diagnostic', onDiagnostic)
+    server.on('workspaceState', onWorkspaceState)
     server.on('closed', onClosed)
 
     if (!useTui) stopObserving = observeServer(server, ui)
@@ -235,6 +420,7 @@ async function runServer(factory, options, command, root, ui, uiMode) {
       server.off('rebuildStart', onRebuildStart)
       server.off('rebuilt', onRebuilt)
       server.off('diagnostic', onDiagnostic)
+      server.off('workspaceState', onWorkspaceState)
       server.off('closed', onClosed)
     }
   } catch (error) {
@@ -251,6 +437,236 @@ async function runServer(factory, options, command, root, ui, uiMode) {
   }
 }
 
+async function runTestCommand(args) {
+  try {
+    const root = takeOption(args, '--root', true)
+    const namePattern = takeOption(args, '--name-pattern', true)
+    const projects = takeOptions(args, '--project', true)
+    const environment = validateTestChoice(
+      takeOption(args, '--environment', true),
+      '--environment',
+      ['auto', 'dom', 'browser'],
+    )
+    const watch = takeFlag(args, '--watch')
+    const changed = takeFlag(args, '--changed')
+    const related = takeVariadicOptions(args, '--related')
+    const coverage = takeFlag(args, '--coverage')
+    const updateSnapshots = takeFlag(args, '--update-snapshots') ? 'all' : undefined
+    const serial = takeFlag(args, '--serial')
+    const workers = parseTestWorkers(takeOption(args, '--workers', true))
+    const bail = takeTestBail(args)
+    const shard = parseTestShard(takeOption(args, '--shard', true))
+    const seed = takeOption(args, '--seed', true)
+    const shuffle = takeFlag(args, '--shuffle')
+    const reporter = validateTestChoice(
+      takeOption(args, '--reporter', true),
+      '--reporter',
+      ['pretty', 'json', 'junit'],
+    )
+    const output = takeOption(args, '--output', true)
+    const allowNoTests = takeFlag(args, '--allow-no-tests')
+    const browserPath = takeOption(args, '--browser-path', true)
+    const headful = takeFlag(args, '--headful')
+
+    if (changed && related.length > 0) {
+      throw testUsageError('--changed cannot be combined with --related')
+    }
+    if (serial && workers !== undefined) {
+      throw testUsageError('--serial cannot be combined with --workers')
+    }
+    if (output && reporter === undefined) {
+      throw testUsageError('--output requires --reporter json or --reporter junit')
+    }
+    if (output && reporter === 'pretty') {
+      throw testUsageError('--output requires --reporter json or --reporter junit')
+    }
+    if (args.some((argument) => argument.startsWith('-'))) {
+      throw testUsageError(`unknown test arguments: ${args.filter((argument) => argument.startsWith('-')).join(' ')}`)
+    }
+
+    const options = {
+      root,
+      patterns: args.splice(0),
+      namePattern,
+      projects,
+      environment,
+      watch,
+      changed,
+      related,
+      coverage,
+      updateSnapshots,
+      serial,
+      workers,
+      bail,
+      shard,
+      seed,
+      shuffle,
+      reporter,
+      output,
+      allowNoTests,
+      browserPath,
+      headful,
+    }
+    const selectedReporter = reporter || 'pretty'
+
+    if (!watch) {
+      const result = await runTests(options)
+      printTestRun(result, selectedReporter, output)
+      return testResultExitCode(result)
+    }
+
+    const context = await createTestContext(options)
+    let lastExitCode = 0
+    let outputError
+    let finish
+    const finished = new Promise((resolve) => { finish = resolve })
+    let closing
+    const requestClose = () => {
+      closing ||= context.close().catch((error) => {
+        outputError ||= error
+      })
+      return closing
+    }
+    const finishAndClose = (reason) => {
+      finish(reason)
+      void requestClose()
+    }
+    const onSigint = () => finishAndClose('signal')
+    const onSigterm = () => finishAndClose('signal')
+    const onClosed = () => {
+      const fatalError = testContextInternal.getTestContextFatalError(context)
+      if (fatalError) {
+        outputError = fatalError
+        finish('fatal')
+      } else {
+        finish('closed')
+      }
+    }
+    process.once('SIGINT', onSigint)
+    process.once('SIGTERM', onSigterm)
+    context.once('closed', onClosed)
+    context.on('runComplete', (result) => {
+      if (result.terminationReason === 'watch-restart' || result.terminationReason === 'cancelled') {
+        return
+      }
+      lastExitCode = testResultExitCode(result)
+      try {
+        printTestRun(result, selectedReporter, output, false)
+      } catch (error) {
+        outputError = error
+        finish('output-error')
+      }
+    })
+    context.on('diagnostic', (diagnostic) => {
+      console.error(`${diagnostic.code}: ${diagnostic.message}`)
+    })
+    const stdin = process.stdin
+    const interactive = Boolean(stdin.isTTY && stdin.setRawMode)
+    const previousRaw = interactive ? Boolean(stdin.isRaw) : false
+    let prompt
+    const sendControl = (control) => {
+      try {
+        testContextInternal.sendTestWatchControl(context, control)
+      } catch (error) {
+        outputError = error
+        finish('control-error')
+      }
+    }
+    const onWatchKey = (chunk) => {
+      for (const character of chunk.toString('utf8')) {
+        if (character === '\u0003') {
+          finishAndClose('signal')
+          continue
+        }
+        if (prompt) {
+          if (character === '\r' || character === '\n') {
+            process.stdout.write('\n')
+            const value = prompt.value.trim()
+            if (value) sendControl({ type: prompt.type, pattern: value })
+            prompt = undefined
+          } else if (character === '\u001b') {
+            process.stdout.write('\n')
+            prompt = undefined
+          } else if (character === '\b' || character === '\u007f') {
+            if (prompt.value) {
+              prompt.value = prompt.value.slice(0, -1)
+              process.stdout.write('\b \b')
+            }
+          } else if (character >= ' ') {
+            prompt.value += character
+            process.stdout.write(character)
+          }
+          continue
+        }
+        switch (character) {
+          case 'a':
+            sendControl({ type: 'all' })
+            break
+          case 'f':
+            sendControl({ type: 'failed' })
+            break
+          case 'p':
+            prompt = { type: 'path', value: '' }
+            process.stdout.write('\nPath pattern: ')
+            break
+          case 't':
+            prompt = { type: 'name', value: '' }
+            process.stdout.write('\nTest name pattern: ')
+            break
+          case 'u':
+            sendControl({ type: 'updateSnapshots' })
+            break
+          case 'r':
+            sendControl({ type: 'rerun' })
+            break
+          case 'q':
+            finishAndClose('quit')
+            break
+          default:
+        }
+      }
+    }
+    try {
+      context.startWatch()
+      if (interactive) {
+        stdin.setRawMode(true)
+        stdin.resume()
+        stdin.on('data', onWatchKey)
+        console.error('Watch keys: a all · f failed · p path · t name · u snapshots · r rerun · q quit')
+      }
+      // StartWatch schedules the first host-owned run. The JS thread remains free for watch
+      // controls and cancellation even when the suite itself is an infinite loop.
+      const reason = await finished
+      if (closing) await closing
+      if (outputError) throw outputError
+      return reason === 'closed' || reason === 'quit' ? lastExitCode : 130
+    } finally {
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+      context.off('closed', onClosed)
+      if (interactive) {
+        stdin.off('data', onWatchKey)
+        stdin.setRawMode(previousRaw)
+        if (!previousRaw) stdin.pause()
+      }
+      await (closing || context.close())
+    }
+  } catch (error) {
+    if (error && typeof error === 'object') {
+      if (error instanceof WakeError && error.code === 'WAKE_CONFIG') {
+        const mapped = new WakeError('WAKE_TEST_CONFIG', error.message, { cause: error })
+        mapped.exitCode = 2
+        throw mapped
+      }
+      error.exitCode = error.code === 'WAKE_CANCELLED' ? 130 : 2
+      throw error
+    }
+    const wrapped = new WakeError('WAKE_TEST_RUNTIME', String(error))
+    wrapped.exitCode = 2
+    throw wrapped
+  }
+}
+
 export async function runCli(argv = process.argv.slice(2)) {
   const args = [...argv]
   const noColor = takeFlag(args, '--no-color')
@@ -267,6 +683,14 @@ export async function runCli(argv = process.argv.slice(2)) {
   }
 
   const command = args.shift()
+  if (command === 'test') {
+    if (takeFlag(args, '--help') || takeFlag(args, '-h')) {
+      console.log(HELP)
+      return 0
+    }
+    ensureStaticMode(uiMode)
+    return runTestCommand(args)
+  }
   if (command === 'build') {
     ensureStaticMode(uiMode)
     const options = commonOptions(args)