vimonkey 0.2.2 → 0.2.4

package/dist/test-fuzz-ZgFKEVq-.mjs

@@ -0,0 +1,550 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, test } from "vitest";
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+//#region src/random.ts
+const LCG_A = 1103515245;
+const LCG_C = 12345;
+const LCG_M = 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
+*/
+function weightedPickFromTuples(tuples, rand) {
+	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
+* ```
+*/
+function createSeededRandom(seed) {
+	let state = seed ?? Date.now();
+	function next() {
+		state = (LCG_A * state + LCG_C) % LCG_M;
+		return state;
+	}
+	const random = {
+		get seed() {
+			return state;
+		},
+		float() {
+			return next() / LCG_M;
+		},
+		int(min, max) {
+			return Math.floor(random.float() * (max - min + 1)) + min;
+		},
+		pick(array) {
+			if (array.length === 0) throw new Error("Cannot pick from empty array");
+			return array[random.int(0, array.length - 1)];
+		},
+		weightedPick(items, weights) {
+			return weightedPickFromTuples(items.map((item) => [weights[item] ?? 1, item]), random.float());
+		},
+		shuffle(array) {
+			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(length, generator) {
+			return Array.from({ length }, generator);
+		},
+		bool(probability = .5) {
+			return random.float() < probability;
+		},
+		fork() {
+			return createSeededRandom(next());
+		}
+	};
+	return random;
+}
+/**
+* Parse seed from environment or generate random
+*/
+function parseSeed(source = "env") {
+	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.
+*/
+function parseRepeats() {
+	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
+*/
+function deriveSeeds(baseSeed, count) {
+	const seeds = [];
+	let state = baseSeed;
+	for (let i = 0; i < count; i++) {
+		state = (LCG_A * state + LCG_C) % LCG_M;
+		seeds.push(state);
+	}
+	return seeds;
+}
+//#endregion
+//#region src/fuzz/context.ts
+/**
+* Fuzz test context using AsyncLocalStorage for auto-tracking
+*
+* When running inside test.fuzz(), take() automatically records
+* yielded values for shrinking and regression testing.
+*/
+/** AsyncLocalStorage for fuzz test context */
+const fuzzContext = new AsyncLocalStorage();
+/**
+* Create a new fuzz context
+*/
+function createFuzzContext(seed) {
+	return {
+		history: [],
+		replaySequence: null,
+		replayIndex: 0,
+		seed
+	};
+}
+/**
+* Create a replay context from a saved sequence
+*/
+function createReplayContext(sequence, seed) {
+	return {
+		history: [],
+		replaySequence: sequence,
+		replayIndex: 0,
+		seed
+	};
+}
+/**
+* Check if we're currently in a fuzz context
+*/
+function isInFuzzContext() {
+	return fuzzContext.getStore() !== void 0;
+}
+/**
+* Get the current fuzz context or undefined
+*/
+function getFuzzContext() {
+	return fuzzContext.getStore();
+}
+//#endregion
+//#region src/fuzz/gen.ts
+/**
+* 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().
+*/
+/**
+* Type guard for weighted tuples
+*/
+function isWeightedTuple(picker) {
+	return Array.isArray(picker) && picker.length > 0 && Array.isArray(picker[0]) && typeof picker[0][0] === "number";
+}
+/**
+* Type guard for iterables (excluding strings)
+*/
+function isIterable(value) {
+	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(result) {
+	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(picker, random) {
+	if (typeof picker === "function") return picker;
+	if (isWeightedTuple(picker)) {
+		const items = picker;
+		return () => weightedPickFromTuples(items, random.float());
+	}
+	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, ...
+*/
+async function* gen(picker, seed) {
+	const ctx = fuzzContext.getStore();
+	const random = createSeededRandom(seed ?? ctx?.seed ?? Date.now());
+	const pick = createPicker(picker, random);
+	let iteration = 0;
+	while (true) yield* flatten(await pick({
+		random,
+		iteration: iteration++
+	}));
+}
+/**
+* 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)
+* }
+*/
+async function* take(generator, n) {
+	const ctx = fuzzContext.getStore();
+	let i = 0;
+	if (ctx?.replaySequence) {
+		while (i < n && ctx.replayIndex < ctx.replaySequence.length) {
+			yield ctx.replaySequence[ctx.replayIndex++];
+			i++;
+		}
+		return;
+	}
+	for await (const item of generator) {
+		if (i++ >= n) break;
+		ctx?.history.push(item);
+		yield item;
+	}
+}
+//#endregion
+//#region src/fuzz/shrink.ts
+/**
+* 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
+*/
+async function shrinkSequence(sequence, runTest, options = {}) {
+	const { maxAttempts = 100, minLength = 1 } = options;
+	let current = [...sequence];
+	let attempts = 0;
+	let changed = true;
+	while (changed && attempts < maxAttempts && current.length > minLength) {
+		changed = false;
+		if (current.length > 1) {
+			const half = Math.ceil(current.length / 2);
+			const secondHalf = current.slice(half);
+			attempts++;
+			if (secondHalf.length >= minLength && !await runTest(secondHalf)) {
+				current = secondHalf;
+				changed = true;
+				continue;
+			}
+		}
+		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)) {
+				current = firstHalf;
+				changed = true;
+				continue;
+			}
+		}
+		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)) {
+				current = without;
+				changed = true;
+				break;
+			}
+		}
+	}
+	return {
+		original: sequence,
+		shrunk: current,
+		attempts,
+		reduced: current.length < sequence.length
+	};
+}
+/**
+* Format shrink result for display
+*/
+function formatShrinkResult(result) {
+	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)`;
+}
+//#endregion
+//#region src/fuzz/regression.ts
+/**
+* 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.
+*/
+/**
+* Get the __fuzz_cases__ directory path for a test file
+*/
+function getFuzzCasesDir(testFilePath) {
+	return join(dirname(testFilePath), "__fuzz_cases__", basename(testFilePath));
+}
+/**
+* Generate a filename for a saved case
+*/
+function getCaseFilename(testName) {
+	return `${testName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50)}-${Date.now()}.json`;
+}
+/**
+* Save a failing case to __fuzz_cases__/
+*/
+function saveCase(testFilePath, testName, failure) {
+	const dir = getFuzzCasesDir(testFilePath);
+	mkdirSync(dir, { recursive: true });
+	const filepath = join(dir, getCaseFilename(testName));
+	writeFileSync(filepath, JSON.stringify(failure, null, 2));
+	return filepath;
+}
+/**
+* Load all saved cases for a test file
+*/
+function loadCases(testFilePath) {
+	const dir = getFuzzCasesDir(testFilePath);
+	if (!existsSync(dir)) return [];
+	const cases = [];
+	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));
+		} catch {}
+	}
+	return cases;
+}
+/**
+* Load saved cases for a specific test name
+*/
+function loadCasesForTest(testFilePath, testName) {
+	return loadCases(testFilePath).filter((c) => c.test === testName);
+}
+/**
+* Delete a saved case (when bug is fixed)
+*/
+function deleteCase(testFilePath, filename) {
+	const filepath = join(getFuzzCasesDir(testFilePath), filename);
+	if (existsSync(filepath)) unlinkSync(filepath);
+}
+/**
+* Clear all saved cases for a test file
+*/
+function clearCases(testFilePath) {
+	const dir = getFuzzCasesDir(testFilePath);
+	if (!existsSync(dir)) return;
+	for (const file of readdirSync(dir)) if (file.endsWith(".json")) unlinkSync(join(dir, file));
+}
+//#endregion
+//#region src/fuzz/test-fuzz.ts
+/**
+* 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)
+*   }
+* })
+* ```
+*/
+/** Error with fuzz context attached */
+var FuzzError = class extends Error {
+	sequence;
+	seed;
+	originalError;
+	constructor(originalError, info) {
+		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() {
+	const stack = (/* @__PURE__ */ new Error()).stack?.split("\n") ?? [];
+	for (const line of stack) {
+		const match = line.match(/\(([^)]+\.(test|fuzz)\.(ts|tsx|js|jsx)):\d+:\d+\)/);
+		if (match) return match[1];
+		const match2 = line.match(/at\s+([^\s]+\.(test|fuzz)\.(ts|tsx|js|jsx)):\d+:\d+/);
+		if (match2) return match2[1];
+	}
+	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, fn, seed, opts) {
+	const testFilePath = getTestFilePath();
+	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);
+			} catch (error) {
+				throw new FuzzError(error, {
+					original: savedCase.originalLength ?? savedCase.sequence.length,
+					shrunk: savedCase.sequence.length,
+					sequence: savedCase.sequence,
+					seed: savedCase.seed
+				});
+			}
+		}
+	}
+	const ctx = createFuzzContext(seed);
+	try {
+		await fuzzContext.run(ctx, fn);
+	} catch (error) {
+		if (ctx.history.length > 0) {
+			let minimalSequence = ctx.history;
+			let shrinkResult;
+			if (opts.shrink) {
+				const runWithSequence = async (seq) => {
+					const replayCtx = createReplayContext(seq, seed);
+					try {
+						await fuzzContext.run(replayCtx, fn);
+						return true;
+					} catch {
+						return false;
+					}
+				};
+				shrinkResult = await shrinkSequence(ctx.history, runWithSequence, { maxAttempts: opts.maxShrinkAttempts });
+				minimalSequence = shrinkResult.shrunk;
+				console.log(formatShrinkResult(shrinkResult));
+			}
+			if (opts.save) {
+				const filepath = saveCase(testFilePath, name, {
+					test: name,
+					seed,
+					sequence: minimalSequence,
+					error: String(error),
+					timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+					originalLength: ctx.history.length
+				});
+				console.log(`Saved failing case to: ${filepath}`);
+			}
+			throw new FuzzError(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, fn, options = {}) {
+	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) return test(name, testOptions, async () => {
+		await runFuzzBody(name, fn, seed, bodyOpts);
+	});
+	const seeds = deriveSeeds(seed, repeats);
+	for (let i = 0; i < seeds.length; i++) {
+		const s = seeds[i];
+		test(`${name} [seed=${s}]`, testOptions, async () => {
+			await runFuzzBody(name, fn, s, bodyOpts);
+		});
+	}
+}
+const fuzz = (name, fnOrOptions, optionsOrFn) => {
+	if (typeof fnOrOptions === "function") return createFuzzTest(name, fnOrOptions, optionsOrFn);
+	else return createFuzzTest(name, optionsOrFn, fnOrOptions);
+};
+/**
+* Extended test object with fuzz method
+*/
+const test$1 = Object.assign(test, { fuzz });
+//#endregion
+export { getFuzzContext as C, parseRepeats as D, deriveSeeds as E, parseSeed as O, fuzzContext as S, createSeededRandom as T, shrinkSequence as _, beforeEach as a, createFuzzContext as b, it as c, deleteCase as d, getFuzzCasesDir as f, formatShrinkResult as g, saveCase as h, beforeAll as i, weightedPickFromTuples as k, test$1 as l, loadCasesForTest as m, afterAll as n, describe as o, loadCases as p, afterEach as r, expect as s, FuzzError as t, clearCases as u, gen as v, isInFuzzContext as w, createReplayContext as x, take as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vimonkey",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Fuzz testing with auto-shrinking and composable chaos stream transformers for Vitest",
   "keywords": [
     "async-generator",
@@ -23,21 +23,20 @@
     "url": "https://github.com/beorn/vimonkey/issues"
   },
   "license": "MIT",
-  "author": "Beorn",
+  "author": "Bjørn Stabell <bjorn@stabell.org>",
   "repository": {
     "type": "git",
     "url": "https://github.com/beorn/vimonkey.git"
   },
   "files": [
-    "src"
+    "dist"
   ],
   "type": "module",
-  "module": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./plugin": "./src/plugin.ts",
-    "./fuzz": "./src/fuzz/index.ts",
-    "./chaos": "./src/chaos/index.ts"
+    ".": "./dist/index.mjs",
+    "./plugin": "./dist/plugin.mjs",
+    "./fuzz": "./dist/fuzz/index.mjs",
+    "./chaos": "./dist/chaos/index.mjs"
   },
   "publishConfig": {
     "access": "public"
@@ -53,11 +52,27 @@
   "peerDependencies": {
     "vitest": ">=4.0.0"
   },
+  "tsdown": {
+    "clean": true,
+    "dts": false,
+    "entry": [
+      "src/index.ts",
+      "src/plugin.ts",
+      "src/fuzz/index.ts",
+      "src/chaos/index.ts"
+    ],
+    "external": [
+      "vitest",
+      "vitest/node",
+      "debug"
+    ],
+    "format": "esm"
+  },
   "engines": {
     "node": ">=23.6.0"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsdown",
     "test": "vitest",
     "test:run": "vitest run"
   }