vimonkey 0.2.2 → 0.2.3

package/src/fuzz/shrink.ts

@@ -1,115 +0,0 @@
-/**
- * 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

@@ -1,241 +0,0 @@
-/**
- * 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

@@ -1,37 +0,0 @@
-/**
- * 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

@@ -1,96 +0,0 @@
-/**
- * @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

package/src/random.ts

@@ -1,181 +0,0 @@
-/**
- * Seeded random number generator
- *
- * Uses a Linear Congruential Generator (LCG) for reproducible random sequences.
- * Ported from km's chaos testing infrastructure.
- */
-
-export interface SeededRandom {
-  /** Get the current seed */
-  seed: number
-
-  /** Generate a random integer in [min, max] inclusive */
-  int(min: number, max: number): number
-
-  /** Generate a random float in [0, 1) */
-  float(): number
-
-  /** Pick a random element from an array */
-  pick<T>(array: readonly T[]): T
-
-  /** Pick a random element with weights */
-  weightedPick<T extends string>(items: readonly T[], weights: Partial<Record<T, number>>): T
-
-  /** Shuffle an array (returns new array) */
-  shuffle<T>(array: readonly T[]): T[]
-
-  /** Generate a random array */
-  array<T>(length: number, generator: () => T): T[]
-
-  /** Generate a random boolean with given probability of true */
-  bool(probability?: number): boolean
-
-  /** Fork the RNG (create independent stream) */
-  fork(): SeededRandom
-}
-
-// Linear Congruential Generator constants (same as glibc's rand()).
-// Full period of 2^31. See Numerical Recipes §7.1 or Knuth TAOCP Vol 2 §3.2.1.
-const LCG_A = 1103515245 // multiplier
-const LCG_C = 12345 // increment
-const LCG_M = 2 ** 31 // modulus (2^31)
-
-/**
- * Pick a random element from weighted tuples using a pre-generated random float.
- *
- * @param tuples - Array of [weight, value] pairs
- * @param rand - Random float in [0, 1)
- * @returns The selected value
- */
-export function weightedPickFromTuples<T>(tuples: readonly (readonly [number, T])[], rand: number): T {
-  let total = 0
-  for (const [w] of tuples) total += w
-  let r = rand * total
-  for (const [weight, value] of tuples) {
-    r -= weight
-    if (r <= 0) return value
-  }
-  return tuples[tuples.length - 1]![1]
-}
-
-/**
- * Create a seeded random number generator
- *
- * @param seed - Initial seed (uses Date.now() if not provided)
- * @returns Seeded random number generator
- *
- * @example
- * ```typescript
- * const random = createSeededRandom(12345)
- *
- * // Same seed = same sequence
- * random.int(0, 100)  // always 47 with seed 12345
- * random.pick(['a', 'b', 'c'])  // always 'b' with seed 12345
- * ```
- */
-export function createSeededRandom(seed?: number): SeededRandom {
-  let state = seed ?? Date.now()
-
-  function next(): number {
-    state = (LCG_A * state + LCG_C) % LCG_M
-    return state
-  }
-
-  const random: SeededRandom = {
-    get seed() {
-      return state
-    },
-
-    float(): number {
-      return next() / LCG_M
-    },
-
-    int(min: number, max: number): number {
-      return Math.floor(random.float() * (max - min + 1)) + min
-    },
-
-    pick<T>(array: readonly T[]): T {
-      if (array.length === 0) {
-        throw new Error("Cannot pick from empty array")
-      }
-      return array[random.int(0, array.length - 1)]!
-    },
-
-    weightedPick<T extends string>(items: readonly T[], weights: Partial<Record<T, number>>): T {
-      const tuples: [number, T][] = items.map((item) => [weights[item] ?? 1, item])
-      return weightedPickFromTuples(tuples, random.float())
-    },
-
-    shuffle<T>(array: readonly T[]): T[] {
-      const result = [...array]
-      for (let i = result.length - 1; i > 0; i--) {
-        const j = random.int(0, i)
-        ;[result[i], result[j]] = [result[j]!, result[i]!]
-      }
-      return result
-    },
-
-    array<T>(length: number, generator: () => T): T[] {
-      return Array.from({ length }, generator)
-    },
-
-    bool(probability = 0.5): boolean {
-      return random.float() < probability
-    },
-
-    fork(): SeededRandom {
-      // Use current state to seed new generator
-      return createSeededRandom(next())
-    },
-  }
-
-  return random
-}
-
-/**
- * Parse seed from environment or generate random
- */
-export function parseSeed(source: "env" | "random" = "env"): number {
-  if (source === "env") {
-    const envSeed = process.env.FUZZ_SEED
-    if (envSeed) {
-      const parsed = parseInt(envSeed, 10)
-      if (!isNaN(parsed)) {
-        return parsed
-      }
-      console.warn(`Invalid FUZZ_SEED: "${envSeed}", using random seed`)
-    }
-  }
-  return Date.now()
-}
-
-/**
- * Parse FUZZ_REPEATS from environment (default: 1)
- *
- * Controls how many times each test.fuzz() test runs with different seeds.
- * Use FUZZ_REPEATS=10000 for CI nightly runs.
- */
-export function parseRepeats(): number {
-  const env = process.env.FUZZ_REPEATS
-  if (env) {
-    const parsed = parseInt(env, 10)
-    if (!isNaN(parsed) && parsed > 0) {
-      return parsed
-    }
-    console.warn(`Invalid FUZZ_REPEATS: "${env}", using 1`)
-  }
-  return 1
-}
-
-/**
- * Derive N unique seeds from a base seed using LCG
- */
-export function deriveSeeds(baseSeed: number, count: number): number[] {
-  const seeds: number[] = []
-  let state = baseSeed
-  for (let i = 0; i < count; i++) {
-    state = (LCG_A * state + LCG_C) % LCG_M
-    seeds.push(state)
-  }
-  return seeds
-}