vimonkey 0.0.1 → 0.2.1

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)`
+}

package/src/fuzz/test-fuzz.ts

@@ -0,0 +1,241 @@
+/**
+ * test.fuzz wrapper with auto-tracking, shrinking, and regression
+ *
+ * Usage:
+ * ```typescript
+ * import { test } from 'vimonkey/fuzz'
+ *
+ * test.fuzz('cursor invariants', 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)
+ *   }
+ * })
+ * ```
+ */
+
+import { test as vitestTest, type TestOptions } from "vitest"
+import { fuzzContext, createFuzzContext, createReplayContext, type FuzzContext } from "./context.js"
+import { shrinkSequence, formatShrinkResult } from "./shrink.js"
+import { saveCase, loadCasesForTest, type SavedCase } from "./regression.js"
+import { parseSeed, parseRepeats, deriveSeeds } from "../random.js"
+
+/** Options for test.fuzz */
+export interface FuzzTestOptions extends TestOptions {
+  /** Seed for reproducibility (default: from FUZZ_SEED env or random) */
+  seed?: number
+  /** Whether to shrink failing sequences (default: true) */
+  shrink?: boolean
+  /** Whether to save failing sequences to __fuzz_cases__/ (default: true) */
+  save?: boolean
+  /** Whether to replay saved failing sequences first (default: true) */
+  replay?: boolean
+  /** Maximum shrinking attempts (default: 100) */
+  maxShrinkAttempts?: number
+}
+
+/** Error with fuzz context attached */
+export class FuzzError extends Error {
+  readonly sequence: unknown[]
+  readonly seed: number
+  readonly originalError: Error
+
+  constructor(
+    originalError: Error,
+    info: {
+      original: number
+      shrunk: number
+      sequence: unknown[]
+      seed: number
+    },
+  ) {
+    const msg = `Fuzz test failed after ${info.original} steps (shrunk to ${info.shrunk})
+Minimal failing sequence: ${JSON.stringify(info.sequence)}
+Seed: ${info.seed} (reproduce with FUZZ_SEED=${info.seed})
+
+Original error: ${originalError.message}`
+
+    super(msg)
+    this.name = "FuzzError"
+    this.sequence = info.sequence
+    this.seed = info.seed
+    this.originalError = originalError
+  }
+}
+
+/**
+ * Get the test file path from error stack
+ * This is a heuristic - it looks for .test.ts or .fuzz.ts files
+ */
+function getTestFilePath(): string {
+  const err = new Error()
+  const stack = err.stack?.split("\n") ?? []
+
+  for (const line of stack) {
+    // Look for test file patterns
+    const match = line.match(/\(([^)]+\.(test|fuzz)\.(ts|tsx|js|jsx)):\d+:\d+\)/)
+    if (match) return match[1]!
+
+    // Also try without parentheses
+    const match2 = line.match(/at\s+([^\s]+\.(test|fuzz)\.(ts|tsx|js|jsx)):\d+:\d+/)
+    if (match2) return match2[1]!
+  }
+
+  // Fallback to current working directory
+  return process.cwd() + "/unknown.test.ts"
+}
+
+/**
+ * Run a single fuzz test body with a specific seed.
+ * Handles replay, shrinking, and saving of failing cases.
+ */
+async function runFuzzBody(
+  name: string,
+  fn: () => Promise<void>,
+  seed: number,
+  opts: { shrink: boolean; save: boolean; replay: boolean; maxShrinkAttempts: number },
+) {
+  const testFilePath = getTestFilePath()
+
+  // Replay saved failing sequences first
+  if (opts.replay) {
+    const savedCases = loadCasesForTest(testFilePath, name)
+    for (const savedCase of savedCases) {
+      const replayCtx = createReplayContext(savedCase.sequence, savedCase.seed)
+      try {
+        await fuzzContext.run(replayCtx, fn)
+        // If replay passes, the bug might be fixed - but we still run the main test
+      } catch (error) {
+        // Replay still fails - throw with saved context
+        throw new FuzzError(error as Error, {
+          original: savedCase.originalLength ?? savedCase.sequence.length,
+          shrunk: savedCase.sequence.length,
+          sequence: savedCase.sequence,
+          seed: savedCase.seed,
+        })
+      }
+    }
+  }
+
+  // Run the main fuzz test
+  const ctx = createFuzzContext(seed)
+
+  try {
+    await fuzzContext.run(ctx, fn)
+  } catch (error) {
+    // Test failed - attempt shrinking
+    if (ctx.history.length > 0) {
+      let minimalSequence = ctx.history
+      let shrinkResult
+
+      if (opts.shrink) {
+        // Define the test runner for shrinking
+        const runWithSequence = async (seq: unknown[]) => {
+          const replayCtx = createReplayContext(seq, seed)
+          try {
+            await fuzzContext.run(replayCtx, fn)
+            return true // passed
+          } catch {
+            return false // still fails
+          }
+        }
+
+        shrinkResult = await shrinkSequence(ctx.history, runWithSequence, {
+          maxAttempts: opts.maxShrinkAttempts,
+        })
+        minimalSequence = shrinkResult.shrunk
+
+        // Log shrink result
+        console.log(formatShrinkResult(shrinkResult))
+      }
+
+      // Save failing case
+      if (opts.save) {
+        const savedCase: SavedCase = {
+          test: name,
+          seed,
+          sequence: minimalSequence,
+          error: String(error),
+          timestamp: new Date().toISOString(),
+          originalLength: ctx.history.length,
+        }
+        const filepath = saveCase(testFilePath, name, savedCase)
+        console.log(`Saved failing case to: ${filepath}`)
+      }
+
+      throw new FuzzError(error as Error, {
+        original: ctx.history.length,
+        shrunk: minimalSequence.length,
+        sequence: minimalSequence,
+        seed,
+      })
+    }
+
+    throw error
+  }
+}
+
+/**
+ * Create the test.fuzz wrapper
+ *
+ * When FUZZ_REPEATS > 1, registers multiple vitest tests — one per seed —
+ * so each gets its own result in the reporter and failures are independently
+ * visible. Seeds are deterministically derived from the base seed.
+ */
+function createFuzzTest(name: string, fn: () => Promise<void>, options: FuzzTestOptions = {}) {
+  const {
+    seed = parseSeed("env"),
+    shrink = true,
+    save = true,
+    replay = true,
+    maxShrinkAttempts = 100,
+    ...testOptions
+  } = options
+
+  const repeats = parseRepeats()
+  const bodyOpts = { shrink, save, replay, maxShrinkAttempts }
+
+  if (repeats <= 1) {
+    // Single run (default) — original behavior
+    return vitestTest(name, testOptions, async () => {
+      await runFuzzBody(name, fn, seed, bodyOpts)
+    })
+  }
+
+  // Multiple runs — register one test per seed
+  const seeds = deriveSeeds(seed, repeats)
+  for (let i = 0; i < seeds.length; i++) {
+    const s = seeds[i]!
+    vitestTest(`${name} [seed=${s}]`, testOptions, async () => {
+      await runFuzzBody(name, fn, s, bodyOpts)
+    })
+  }
+}
+
+// Type for the fuzz function
+type FuzzFn = {
+  (name: string, fn: () => Promise<void>, options?: FuzzTestOptions): void
+  (name: string, options: FuzzTestOptions, fn: () => Promise<void>): void
+}
+
+// Create the fuzz function with overloads
+const fuzz: FuzzFn = (
+  name: string,
+  fnOrOptions: (() => Promise<void>) | FuzzTestOptions,
+  optionsOrFn?: FuzzTestOptions | (() => Promise<void>),
+) => {
+  if (typeof fnOrOptions === "function") {
+    return createFuzzTest(name, fnOrOptions, optionsOrFn as FuzzTestOptions)
+  } else {
+    return createFuzzTest(name, optionsOrFn as () => Promise<void>, fnOrOptions)
+  }
+}
+
+/**
+ * Extended test object with fuzz method
+ */
+export const test: typeof vitestTest & { fuzz: typeof fuzz } = Object.assign(vitestTest, { fuzz })
+
+// Re-export vitest test types
+export { describe, expect, it, beforeAll, afterAll, beforeEach, afterEach } from "vitest"

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * vimonkey — Fuzz testing and chaos streams for Vitest
+ */
+
+// Fuzz API (primary)
+export { gen, take, type Picker, type PickerContext } from "./fuzz/gen.js"
+export { test, FuzzError, type FuzzTestOptions } from "./fuzz/test-fuzz.js"
+export { describe, expect, it, beforeAll, afterAll, beforeEach, afterEach } from "./fuzz/test-fuzz.js"
+export {
+  fuzzContext,
+  getFuzzContext,
+  isInFuzzContext,
+  createFuzzContext,
+  createReplayContext,
+  type FuzzContext,
+} from "./fuzz/context.js"
+export { shrinkSequence, formatShrinkResult, type ShrinkOptions, type ShrinkResult } from "./fuzz/shrink.js"
+export {
+  saveCase,
+  loadCases,
+  loadCasesForTest,
+  deleteCase,
+  clearCases,
+  getFuzzCasesDir,
+  type SavedCase,
+} from "./fuzz/regression.js"
+
+// Utilities
+export {
+  createSeededRandom,
+  weightedPickFromTuples,
+  parseSeed,
+  parseRepeats,
+  deriveSeeds,
+  type SeededRandom,
+} from "./random.js"
+export { getTestSys, type TestSys } from "./env.js"

package/src/plugin.ts

@@ -0,0 +1,96 @@
+/**
+ * @todo Planned vitest plugin — stub only. Implement config injection and
+ *       custom CLI mode interception (vitest fuzz, vitest ai, vitest doc).
+ *
+ * Vitest plugin for vimonkey
+ *
+ * @example
+ * ```typescript
+ * // vitest.config.ts
+ * import { defineConfig } from 'vitest/config'
+ * import { viMonkey } from 'vimonkey/plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     viMonkey({
+ *       fuzz: { iterations: 100 },
+ *       ai: { model: 'claude-sonnet' },
+ *       doc: { pattern: '**\/*.test.md' },
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+
+/** Minimal Vite plugin interface — avoids requiring vite as a dependency */
+interface Plugin {
+  name: string
+  config?(): void
+  configureServer?(server: unknown): void
+}
+
+export interface ViMonkeyFuzzOptions {
+  /** Number of actions per test run (default: 100) */
+  iterations?: number
+  /** Seed source: 'env' reads FUZZ_SEED, 'random' generates new (default: 'env') */
+  seed?: "env" | "random"
+  /** Stop after first failure (default: true) */
+  failFast?: boolean
+  /** Shrinking settings */
+  shrink?: {
+    enabled?: boolean
+    maxAttempts?: number
+  }
+}
+
+export interface ViMonkeyAiOptions {
+  /** Model identifier (Vercel AI SDK format) */
+  model?: string
+  /** Temperature for LLM (0 = deterministic) */
+  temperature?: number
+  /** Maximum actions per exploration */
+  maxSteps?: number
+  /** Token budget per file */
+  maxTokens?: number
+  /** Directory to save discovered tests */
+  saveDir?: string
+  /** Use Claude Code provider */
+  provider?: "openai" | "anthropic" | "claude-code"
+}
+
+export interface ViMonkeyDocOptions {
+  /** Glob pattern for mdtest files */
+  pattern?: string
+}
+
+export interface ViMonkeyOptions {
+  /** Fuzz mode configuration */
+  fuzz?: ViMonkeyFuzzOptions
+  /** AI mode configuration */
+  ai?: ViMonkeyAiOptions
+  /** Doc mode configuration (mdtest) */
+  doc?: ViMonkeyDocOptions
+}
+
+/**
+ * Creates the vimonkey plugin for Vitest
+ */
+export function viMonkey(options: ViMonkeyOptions = {}): Plugin {
+  const { fuzz = {}, ai = {}, doc = {} } = options
+
+  return {
+    name: "vimonkey",
+
+    config() {
+      // Configure vitest for custom modes
+      // Returns void for now - will be populated as modes are implemented
+    },
+
+    configureServer(server) {
+      // Handle custom CLI modes: vitest fuzz, vitest ai, vitest doc
+      // Implementation will intercept vitest CLI commands
+    },
+  }
+}
+
+export default viMonkey