vimonkey 0.0.1 → 0.2.0

package/src/fuzz/gen.ts

@@ -0,0 +1,157 @@
+/**
+ * Ergonomic generator API for fuzz testing
+ *
+ * gen(picker) creates an infinite async generator from a picker.
+ * take(generator, n) limits iterations and auto-tracks in test.fuzz().
+ */
+
+import { createSeededRandom, weightedPickFromTuples, type SeededRandom } from "../random.js"
+import { fuzzContext } from "./context.js"
+
+/**
+ * Picker context passed to picker functions
+ */
+export interface PickerContext {
+  /** Seeded random number generator */
+  random: SeededRandom
+  /** Current iteration (0-indexed) */
+  iteration: number
+}
+
+/**
+ * Result type for picker functions - can return single value, array, or iterable
+ */
+type PickerResult<T> = T | T[] | Iterable<T>
+
+/**
+ * Sync picker function
+ */
+type SyncPickerFn<T> = (ctx: PickerContext) => PickerResult<T>
+
+/**
+ * Async picker function (for AI mode)
+ */
+type AsyncPickerFn<T> = (ctx: PickerContext) => Promise<PickerResult<T>>
+
+/**
+ * Picker types:
+ * - T[] - random from array
+ * - [number, T][] - weighted random (pairs of [weight, value])
+ * - (ctx) => T | T[] | Iterable<T> - sync function
+ * - (ctx) => Promise<T | T[] | Iterable<T>> - async function
+ */
+export type Picker<T> = T[] | [number, T][] | SyncPickerFn<T> | AsyncPickerFn<T>
+
+/**
+ * Type guard for weighted tuples
+ */
+function isWeightedTuple<T>(picker: unknown): picker is [number, T][] {
+  return Array.isArray(picker) && picker.length > 0 && Array.isArray(picker[0]) && typeof picker[0][0] === "number"
+}
+
+/**
+ * Type guard for iterables (excluding strings)
+ */
+function isIterable<T>(value: unknown): value is Iterable<T> {
+  return value !== null && typeof value === "object" && Symbol.iterator in value && typeof value !== "string"
+}
+
+/**
+ * Flatten picker result: single value, array, or iterable → individual items
+ */
+function* flatten<T>(result: PickerResult<T>): Generator<T> {
+  if (Array.isArray(result)) {
+    for (const item of result) yield item
+  } else if (isIterable(result)) {
+    for (const item of result) yield item
+  } else {
+    yield result
+  }
+}
+
+/**
+ * Create a picker function from various picker specs
+ */
+function createPicker<T>(
+  picker: Picker<T>,
+  random: SeededRandom,
+): (ctx: PickerContext) => PickerResult<T> | Promise<PickerResult<T>> {
+  // Function picker - use as-is
+  if (typeof picker === "function") {
+    return picker
+  }
+
+  // Weighted tuple picker
+  if (isWeightedTuple<T>(picker)) {
+    const items = picker
+    return () => weightedPickFromTuples(items, random.float())
+  }
+
+  // Array picker - random from array
+  return () => picker[Math.floor(random.float() * picker.length)]!
+}
+
+/**
+ * Create an infinite async generator from a picker
+ *
+ * @example
+ * // Random from array
+ * gen(['j', 'k', 'h', 'l'])
+ *
+ * @example
+ * // Weighted random
+ * gen([[40, 'j'], [40, 'k'], [20, 'Enter']])
+ *
+ * @example
+ * // Custom picker function
+ * gen(({ random }) => random.pick(['j', 'k']))
+ *
+ * @example
+ * // Picker returns array (flattened)
+ * gen(() => ['j', 'j', 'Enter'])  // yields: j, j, Enter, j, j, Enter, ...
+ */
+export async function* gen<T>(picker: Picker<T>, seed?: number): AsyncGenerator<T> {
+  // Use context seed if available, otherwise provided seed or Date.now()
+  const ctx = fuzzContext.getStore()
+  const random = createSeededRandom(seed ?? ctx?.seed ?? Date.now())
+  const pick = createPicker(picker, random)
+  let iteration = 0
+
+  while (true) {
+    const pickerCtx: PickerContext = { random, iteration: iteration++ }
+    const result = await pick(pickerCtx)
+    yield* flatten(result)
+  }
+}
+
+/**
+ * Limit an async generator to n iterations
+ *
+ * When running inside test.fuzz(), automatically tracks yielded values
+ * for shrinking and regression testing.
+ *
+ * @example
+ * for await (const key of take(gen(['j', 'k']), 100)) {
+ *   await handle.press(key)
+ * }
+ */
+export async function* take<T>(generator: AsyncIterable<T>, n: number): AsyncGenerator<T> {
+  const ctx = fuzzContext.getStore()
+  let i = 0
+
+  // Replay mode: yield from saved sequence instead of generator
+  if (ctx?.replaySequence) {
+    while (i < n && ctx.replayIndex < ctx.replaySequence.length) {
+      yield ctx.replaySequence[ctx.replayIndex++] as T
+      i++
+    }
+    return
+  }
+
+  // Normal mode: yield from generator, optionally record
+  for await (const item of generator) {
+    if (i++ >= n) break
+    ctx?.history.push(item) // Track if in fuzz context
+    yield item
+  }
+}

package/src/fuzz/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Fuzz testing API
+ *
+ * @example
+ * ```typescript
+ * import { test, gen, take, createSeededRandom } from 'vimonkey/fuzz'
+ *
+ * // Simple random from array
+ * test('navigation', async () => {
+ *   const handle = await run(<Board />, { cols: 80, rows: 24 })
+ *   for await (const key of take(gen(['j','k','h','l']), 100)) {
+ *     await handle.press(key)
+ *     expect(handle.locator('[data-cursor]').count()).toBe(1)
+ *   }
+ * })
+ *
+ * // Weighted random
+ * test('weighted', async () => {
+ *   for await (const key of take(gen([[40,'j'], [40,'k'], [20,'Enter']]), 100)) {
+ *     await handle.press(key)
+ *   }
+ * })
+ *
+ * // Stateful with closure
+ * test('stateful', async () => {
+ *   const handle = await app.run(<Board />)
+ *   const random = createSeededRandom(Date.now())
+ *
+ *   const keys = async function*() {
+ *     while (true) {
+ *       const state = handle.store.getState()
+ *       yield state.cursor === 0 ? random.pick(['j','l']) : random.pick(['j','k','h','l'])
+ *     }
+ *   }
+ *
+ *   for await (const key of take(keys(), 100)) {
+ *     await handle.press(key)
+ *   }
+ * })
+ *
+ * // With auto-tracking and shrinking
+ * test.fuzz('cursor invariants', async () => {
+ *   for await (const key of take(gen(['j','k']), 100)) {
+ *     await handle.press(key)
+ *     expect(...)  // On failure: shrinks, saves to __fuzz_cases__/
+ *   }
+ * })
+ * ```
+ */
+
+// Core API
+export { gen, take, type Picker, type PickerContext } from "./gen.js"
+
+// test.fuzz wrapper
+export { test, FuzzError, type FuzzTestOptions } from "./test-fuzz.js"
+export { describe, expect, it, beforeAll, afterAll, beforeEach, afterEach } from "./test-fuzz.js"
+
+// Context (for advanced use)
+export {
+  fuzzContext,
+  getFuzzContext,
+  isInFuzzContext,
+  createFuzzContext,
+  createReplayContext,
+  type FuzzContext,
+} from "./context.js"
+
+// Shrinking (for advanced use)
+export { shrinkSequence, formatShrinkResult, type ShrinkOptions, type ShrinkResult } from "./shrink.js"
+
+// Regression (for advanced use)
+export {
+  saveCase,
+  loadCases,
+  loadCasesForTest,
+  deleteCase,
+  clearCases,
+  getFuzzCasesDir,
+  type SavedCase,
+} from "./regression.js"
+
+// Re-export random utilities
+export {
+  createSeededRandom,
+  weightedPickFromTuples,
+  parseSeed,
+  parseRepeats,
+  deriveSeeds,
+  type SeededRandom,
+} from "../random.js"

package/src/fuzz/regression.ts

@@ -0,0 +1,115 @@
+/**
+ * Regression testing - save and load failing sequences
+ *
+ * Failing fuzz test sequences are saved to __fuzz_cases__/ directory
+ * like Jest/Vitest snapshots. On subsequent runs, saved sequences
+ * are replayed first to ensure bugs don't regress.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, unlinkSync } from "node:fs"
+import { dirname, join, basename } from "node:path"
+
+/** Failure case saved to disk */
+export interface SavedCase {
+  /** Test name */
+  test: string
+  /** Seed used for generation */
+  seed: number
+  /** Minimal failing sequence */
+  sequence: unknown[]
+  /** Error message */
+  error: string
+  /** When the failure was recorded */
+  timestamp: string
+  /** Original sequence length before shrinking */
+  originalLength?: number
+}
+
+/**
+ * Get the __fuzz_cases__ directory path for a test file
+ */
+export function getFuzzCasesDir(testFilePath: string): string {
+  const dir = dirname(testFilePath)
+  const file = basename(testFilePath)
+  return join(dir, "__fuzz_cases__", file)
+}
+
+/**
+ * Generate a filename for a saved case
+ */
+function getCaseFilename(testName: string): string {
+  // Sanitize test name for filesystem
+  const safe = testName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 50)
+  const timestamp = Date.now()
+  return `${safe}-${timestamp}.json`
+}
+
+/**
+ * Save a failing case to __fuzz_cases__/
+ */
+export function saveCase(testFilePath: string, testName: string, failure: SavedCase): string {
+  const dir = getFuzzCasesDir(testFilePath)
+  mkdirSync(dir, { recursive: true })
+
+  const filename = getCaseFilename(testName)
+  const filepath = join(dir, filename)
+
+  writeFileSync(filepath, JSON.stringify(failure, null, 2))
+  return filepath
+}
+
+/**
+ * Load all saved cases for a test file
+ */
+export function loadCases(testFilePath: string): SavedCase[] {
+  const dir = getFuzzCasesDir(testFilePath)
+  if (!existsSync(dir)) return []
+
+  const cases: SavedCase[] = []
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith(".json")) continue
+    try {
+      const content = readFileSync(join(dir, file), "utf-8")
+      cases.push(JSON.parse(content) as SavedCase)
+    } catch {
+      // Skip invalid files
+    }
+  }
+  return cases
+}
+
+/**
+ * Load saved cases for a specific test name
+ */
+export function loadCasesForTest(testFilePath: string, testName: string): SavedCase[] {
+  return loadCases(testFilePath).filter((c) => c.test === testName)
+}
+
+/**
+ * Delete a saved case (when bug is fixed)
+ */
+export function deleteCase(testFilePath: string, filename: string): void {
+  const dir = getFuzzCasesDir(testFilePath)
+  const filepath = join(dir, filename)
+  if (existsSync(filepath)) {
+    unlinkSync(filepath)
+  }
+}
+
+/**
+ * Clear all saved cases for a test file
+ */
+export function clearCases(testFilePath: string): void {
+  const dir = getFuzzCasesDir(testFilePath)
+  if (!existsSync(dir)) return
+
+  for (const file of readdirSync(dir)) {
+    if (file.endsWith(".json")) {
+      unlinkSync(join(dir, file))
+    }
+  }
+}

package/src/fuzz/shrink.ts

@@ -0,0 +1,115 @@
+/**
+ * Shrinking - find minimal failing sequence via delta debugging
+ *
+ * Uses binary search to reduce a failing sequence to the smallest
+ * subsequence that still triggers the failure.
+ */
+
+export interface ShrinkOptions {
+  /** Maximum shrinking attempts (default: 100) */
+  maxAttempts?: number
+  /** Minimum sequence length to try (default: 1) */
+  minLength?: number
+}
+
+export interface ShrinkResult<T> {
+  /** Original sequence */
+  original: T[]
+  /** Shrunk (minimal) sequence */
+  shrunk: T[]
+  /** Number of shrinking attempts made */
+  attempts: number
+  /** Whether shrinking found a smaller sequence */
+  reduced: boolean
+}
+
+/**
+ * Shrink a failing sequence to its minimal form
+ *
+ * Uses delta debugging algorithm:
+ * 1. Try removing first half - if still fails, keep only first half
+ * 2. Try removing second half - if still fails, keep only second half
+ * 3. Try removing individual elements from start/end
+ * 4. Repeat until no reduction possible
+ *
+ * @param sequence - The original failing sequence
+ * @param runTest - Function that returns true if sequence passes, false if fails
+ * @param options - Shrinking options
+ */
+export async function shrinkSequence<T>(
+  sequence: T[],
+  runTest: (seq: T[]) => Promise<boolean>,
+  options: ShrinkOptions = {},
+): Promise<ShrinkResult<T>> {
+  const { maxAttempts = 100, minLength = 1 } = options
+
+  let current = [...sequence]
+  let attempts = 0
+  let changed = true
+
+  while (changed && attempts < maxAttempts && current.length > minLength) {
+    changed = false
+
+    // Try removing first half
+    if (current.length > 1) {
+      const half = Math.ceil(current.length / 2)
+      const secondHalf = current.slice(half)
+      attempts++
+
+      if (secondHalf.length >= minLength && !(await runTest(secondHalf))) {
+        // Second half alone still fails
+        current = secondHalf
+        changed = true
+        continue
+      }
+    }
+
+    // Try removing second half
+    if (current.length > 1) {
+      const half = Math.floor(current.length / 2)
+      const firstHalf = current.slice(0, half)
+      attempts++
+
+      if (firstHalf.length >= minLength && !(await runTest(firstHalf))) {
+        // First half alone still fails
+        current = firstHalf
+        changed = true
+        continue
+      }
+    }
+
+    // Try removing individual elements
+    for (let i = 0; i < current.length && attempts < maxAttempts; i++) {
+      const without = [...current.slice(0, i), ...current.slice(i + 1)]
+      attempts++
+
+      if (without.length >= minLength && !(await runTest(without))) {
+        // Removing element i still fails
+        current = without
+        changed = true
+        break
+      }
+    }
+  }
+
+  return {
+    original: sequence,
+    shrunk: current,
+    attempts,
+    reduced: current.length < sequence.length,
+  }
+}
+
+/**
+ * Format shrink result for display
+ */
+export function formatShrinkResult<T>(result: ShrinkResult<T>): string {
+  const reduction = result.original.length - result.shrunk.length
+  const percent = Math.round((reduction / result.original.length) * 100)
+
+  if (!result.reduced) {
+    return `Could not reduce sequence (${result.original.length} steps, ${result.attempts} attempts)`
+  }
+
+  return `Shrunk from ${result.original.length} to ${result.shrunk.length} steps (${percent}% reduction, ${result.attempts} attempts)`
+}