vimonkey 0.0.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Beorn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# vimonkey
+
+Fuzz testing and chaos streams for [Vitest](https://vitest.dev/).
+
+## Fuzz Testing
+
+Async generators with auto-shrinking, regression cases, and seeded RNG.
+
+```typescript
+import { test, gen, take } from "vimonkey"
+
+test.fuzz("cursor stays in bounds", async () => {
+  for await (const key of take(gen(["j", "k", "h", "l"]), 100)) {
+    await handle.press(key)
+    expect(getCursor()).toBeGreaterThanOrEqual(0)
+  }
+  // On failure: auto-shrinks to minimal repro, saves to __fuzz_cases__/
+})
+```
+
+Generators support uniform arrays, weighted tuples, sync/async picker functions, and multi-value returns.
+
+## Chaos Streams
+
+Composable async iterable transformers that simulate unreliable delivery.
+
+```typescript
+import { chaos, drop, reorder } from "vimonkey/chaos"
+
+const chaotic = chaos(
+  source,
+  [
+    { type: "drop", params: { rate: 0.2 } },
+    { type: "reorder", params: { windowSize: 5 } },
+    { type: "duplicate", params: { rate: 0.1 } },
+  ],
+  rng,
+)
+```
+
+Built-in transformers: `drop`, `reorder`, `duplicate`, `burst`, `initGap`, `delay`. Extend with custom registries.
+
+## Install
+
+```bash
+npm install vimonkey
+```
+
+## Exports
+
+```typescript
+import { test, gen, take } from "vimonkey" // Fuzz testing
+import { chaos, drop, reorder } from "vimonkey/chaos" // Chaos streams
+import { viMonkeyPlugin } from "vimonkey/plugin" // Vitest plugin
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "vimonkey",
-  "version": "0.0.1",
-  "description": "Reserved",
-  "license": "MIT"
-}
+  "version": "0.2.1",
+  "description": "Fuzz testing with auto-shrinking and composable chaos stream transformers for Vitest",
+  "keywords": [
+    "async-generator",
+    "auto-shrink",
+    "chaos",
+    "chaos-engineering",
+    "delta-debugging",
+    "fuzz",
+    "fuzzing",
+    "property-based-testing",
+    "seeded-random",
+    "shrinking",
+    "stream-transformer",
+    "testing",
+    "vitest",
+    "vitest-plugin"
+  ],
+  "homepage": "https://github.com/beorn/vimonkey",
+  "bugs": {
+    "url": "https://github.com/beorn/vimonkey/issues"
+  },
+  "license": "MIT",
+  "author": "Beorn",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beorn/vimonkey.git"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "module": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./src/plugin.ts",
+    "./fuzz": "./src/fuzz/index.ts",
+    "./chaos": "./src/chaos/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "debug": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=4.0.0"
+  },
+  "engines": {
+    "node": ">=23.6.0"
+  }
+}

package/src/chaos/index.ts

@@ -0,0 +1,180 @@
+/**
+ * Chaos stream transformers for fuzz testing
+ *
+ * Composable async iterable transformers that sit between gen() and take()
+ * to simulate unreliable delivery: dropped messages, reordering, duplicates,
+ * bursts, delays, and gaps.
+ *
+ * @example
+ * ```typescript
+ * import { gen, take } from "vimonkey"
+ * import { drop, reorder, chaos } from "vimonkey/chaos"
+ *
+ * const base = gen(picker)
+ * const chaotic = reorder(drop(base, 0.2, rng), 5, rng)
+ * for await (const event of take(chaotic, 100)) { ... }
+ * ```
+ */
+
+import type { SeededRandom } from "../random.js"
+
+// ---------------------------------------------------------------------------
+// Individual transformers
+// ---------------------------------------------------------------------------
+
+/**
+ * Skip items with probability `rate`.
+ * Simulates message loss, queue overflow, network drops.
+ */
+export async function* drop<T>(source: AsyncIterable<T>, rate: number, rng: SeededRandom): AsyncGenerator<T> {
+  for await (const item of source) {
+    if (!rng.bool(rate)) yield item
+  }
+}
+
+/**
+ * Buffer up to `windowSize` items, shuffle, yield when buffer is full.
+ * Simulates out-of-order delivery, non-deterministic event ordering.
+ */
+export async function* reorder<T>(source: AsyncIterable<T>, windowSize: number, rng: SeededRandom): AsyncGenerator<T> {
+  const buffer: T[] = []
+  for await (const item of source) {
+    buffer.push(item)
+    if (buffer.length >= windowSize) {
+      const shuffled = rng.shuffle(buffer)
+      buffer.length = 0
+      for (const e of shuffled) yield e
+    }
+  }
+  if (buffer.length > 0) {
+    const shuffled = rng.shuffle(buffer)
+    for (const e of shuffled) yield e
+  }
+}
+
+/**
+ * With probability `rate`, yield the item twice.
+ * Simulates duplicate delivery, at-least-once semantics.
+ */
+export async function* duplicate<T>(source: AsyncIterable<T>, rate: number, rng: SeededRandom): AsyncGenerator<T> {
+  for await (const item of source) {
+    yield item
+    if (rng.bool(rate)) yield item
+  }
+}
+
+/**
+ * Collect `burstSize` items, then yield them all at once.
+ * Simulates bursty delivery, batched network packets.
+ */
+export async function* burst<T>(source: AsyncIterable<T>, burstSize: number): AsyncGenerator<T> {
+  const buffer: T[] = []
+  for await (const item of source) {
+    buffer.push(item)
+    if (buffer.length >= burstSize) {
+      for (const e of buffer) yield e
+      buffer.length = 0
+    }
+  }
+  for (const e of buffer) yield e
+}
+
+/**
+ * Skip the first `count` items.
+ * Simulates missed events during initialization, late subscriber.
+ */
+export async function* initGap<T>(source: AsyncIterable<T>, count: number): AsyncGenerator<T> {
+  let skipped = 0
+  for await (const item of source) {
+    if (skipped < count) {
+      skipped++
+      continue
+    }
+    yield item
+  }
+}
+
+/**
+ * Add a random delay before yielding each item.
+ * Simulates slow I/O, network latency, disk delays.
+ */
+export async function* delay<T>(
+  source: AsyncIterable<T>,
+  minMs: number,
+  maxMs: number,
+  rng: SeededRandom,
+): AsyncGenerator<T> {
+  for await (const item of source) {
+    const ms = rng.int(minMs, maxMs)
+    await new Promise((resolve) => setTimeout(resolve, ms))
+    yield item
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Combinator
+// ---------------------------------------------------------------------------
+
+/** Configuration for a chaos transformer in the pipeline */
+export interface ChaosConfig {
+  type: string
+  params: Record<string, unknown>
+}
+
+/** Registry of transformer factories keyed by config type */
+export type ChaosRegistry<T> = Record<
+  string,
+  (source: AsyncIterable<T>, params: Record<string, unknown>, rng: SeededRandom) => AsyncIterable<T>
+>
+
+/** Built-in transformer registry (works for any T) */
+const BUILTIN_REGISTRY: ChaosRegistry<unknown> = {
+  drop: (s, p, rng) => drop(s, (p.rate as number) ?? 0.2, rng),
+  reorder: (s, p, rng) => reorder(s, (p.windowSize as number) ?? 5, rng),
+  duplicate: (s, p, rng) => duplicate(s, (p.rate as number) ?? 0.3, rng),
+  burst: (s, p) => burst(s, (p.burstSize as number) ?? 10),
+  initGap: (s, p) => initGap(s, (p.count as number) ?? 5),
+  delay: (s, p, rng) => delay(s, (p.minMs as number) ?? 1, (p.maxMs as number) ?? 5, rng),
+}
+
+/**
+ * Compose multiple chaos transformer configs into a single async iterable pipeline.
+ *
+ * Uses built-in transformers by default. Pass a custom `registry` to add
+ * domain-specific transformers (e.g., FS-specific atomicSave, coalesce).
+ *
+ * @example
+ * ```typescript
+ * const chaotic = chaos(source, [
+ *   { type: "drop", params: { rate: 0.2 } },
+ *   { type: "reorder", params: { windowSize: 5 } },
+ * ], rng)
+ * ```
+ *
+ * @example Custom registry
+ * ```typescript
+ * const chaotic = chaos(source, configs, rng, {
+ *   ...builtinChaosRegistry,
+ *   atomic_save: (s, p, rng) => atomicSave(s, p.rate, rng),
+ * })
+ * ```
+ */
+export function chaos<T>(
+  source: AsyncIterable<T>,
+  configs: ChaosConfig[],
+  rng: SeededRandom,
+  registry?: ChaosRegistry<T>,
+): AsyncIterable<T> {
+  const reg = registry ?? (BUILTIN_REGISTRY as ChaosRegistry<T>)
+  let pipeline = source
+  for (const config of configs) {
+    const factory = reg[config.type]
+    if (factory) {
+      pipeline = factory(pipeline, config.params, rng)
+    }
+  }
+  return pipeline
+}
+
+/** Re-export the built-in registry for extension */
+export const builtinChaosRegistry: ChaosRegistry<unknown> = BUILTIN_REGISTRY

package/src/env.ts

@@ -0,0 +1,63 @@
+/**
+ * TEST_SYS environment handling
+ *
+ * Controls the implementation used during tests:
+ * - fake: Use fake/mock implementations (fast, isolated)
+ * - real:mem: Real implementation with in-memory storage
+ * - real:disk: Real implementation with temporary disk storage
+ */
+
+export type TestSys = "fake" | "real:mem" | "real:disk"
+
+const VALID_VALUES: TestSys[] = ["fake", "real:mem", "real:disk"]
+
+/**
+ * Get the current TEST_SYS value
+ *
+ * @returns The test system type, defaults to 'fake'
+ *
+ * @example
+ * ```typescript
+ * import { getTestSys } from 'vimonkey'
+ *
+ * const sys = getTestSys()
+ * if (sys === 'fake') {
+ *   // use mock
+ * } else if (sys === 'real:mem') {
+ *   // use real with in-memory storage
+ * } else {
+ *   // use real with disk storage
+ * }
+ * ```
+ */
+export function getTestSys(): TestSys {
+  const value = process.env.TEST_SYS
+
+  if (!value) {
+    return "fake"
+  }
+
+  if (!VALID_VALUES.includes(value as TestSys)) {
+    console.warn(
+      `Invalid TEST_SYS value: "${value}". ` + `Valid values: ${VALID_VALUES.join(", ")}. ` + `Defaulting to "fake".`,
+    )
+    return "fake"
+  }
+
+  return value as TestSys
+}
+
+/**
+ * Check if running with real implementation
+ */
+export function isRealSys(): boolean {
+  const sys = getTestSys()
+  return sys === "real:mem" || sys === "real:disk"
+}
+
+/**
+ * Check if running with disk storage
+ */
+export function isDiskSys(): boolean {
+  return getTestSys() === "real:disk"
+}

package/src/fuzz/context.ts

@@ -0,0 +1,59 @@
+/**
+ * Fuzz test context using AsyncLocalStorage for auto-tracking
+ *
+ * When running inside test.fuzz(), take() automatically records
+ * yielded values for shrinking and regression testing.
+ */
+import { AsyncLocalStorage } from "node:async_hooks"
+
+export interface FuzzContext {
+  /** Recorded history of yielded values */
+  history: unknown[]
+  /** If replaying, the sequence to replay */
+  replaySequence: unknown[] | null
+  /** Current index in replay sequence */
+  replayIndex: number
+  /** The seed used for this test run */
+  seed: number
+}
+
+/** AsyncLocalStorage for fuzz test context */
+export const fuzzContext = new AsyncLocalStorage<FuzzContext>()
+
+/**
+ * Create a new fuzz context
+ */
+export function createFuzzContext(seed: number): FuzzContext {
+  return {
+    history: [],
+    replaySequence: null,
+    replayIndex: 0,
+    seed,
+  }
+}
+
+/**
+ * Create a replay context from a saved sequence
+ */
+export function createReplayContext(sequence: unknown[], seed: number): FuzzContext {
+  return {
+    history: [],
+    replaySequence: sequence,
+    replayIndex: 0,
+    seed,
+  }
+}
+
+/**
+ * Check if we're currently in a fuzz context
+ */
+export function isInFuzzContext(): boolean {
+  return fuzzContext.getStore() !== undefined
+}
+
+/**
+ * Get the current fuzz context or undefined
+ */
+export function getFuzzContext(): FuzzContext | undefined {
+  return fuzzContext.getStore()
+}

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"