vimonkey 0.2.2 → 0.2.3

package/src/chaos/index.ts

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

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

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

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

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

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