flake-monster 0.1.0

package/src/core/manifest.js

@@ -0,0 +1,137 @@
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const MANIFEST_VERSION = 1;
+const MANIFEST_FILENAME = 'manifest.json';
+
+/**
+ * Tracks all injections for reliable removal and reporting.
+ * Stored at .flake-monster/manifest.json (or inside a workspace).
+ */
+export class Manifest {
+  constructor() {
+    this.version = MANIFEST_VERSION;
+    this.createdAt = new Date().toISOString();
+    this.seed = null;
+    this.mode = null;
+    this.files = {};
+    this.runtimeFiles = [];
+  }
+
+  /**
+   * Record injection results for a file.
+   * @param {string} relativePath - path relative to project/workspace root
+   * @param {string} adapterId - e.g. "javascript"
+   * @param {string} originalHash - hash of original source
+   * @param {string} modifiedHash - hash of modified source
+   * @param {Object} result - InjectionResult from adapter
+   */
+  addFile(relativePath, adapterId, originalHash, modifiedHash, result) {
+    this.files[relativePath] = {
+      adapter: adapterId,
+      originalHash,
+      modifiedHash,
+      injections: result.points,
+      runtimeImportAdded: result.runtimeNeeded,
+    };
+  }
+
+  /**
+   * Add a runtime file that was copied into the project/workspace.
+   * @param {string} relativePath
+   */
+  addRuntimeFile(relativePath) {
+    if (!this.runtimeFiles.includes(relativePath)) {
+      this.runtimeFiles.push(relativePath);
+    }
+  }
+
+  /** Get all tracked file entries. */
+  getFiles() {
+    return this.files;
+  }
+
+  /** Get the total number of injections across all files. */
+  getTotalInjections() {
+    let total = 0;
+    for (const entry of Object.values(this.files)) {
+      total += entry.injections.length;
+    }
+    return total;
+  }
+
+  /**
+   * Check if a file's current content matches what we wrote during injection.
+   * @param {string} currentHash
+   * @param {string} relativePath
+   * @returns {boolean}
+   */
+  isFileUnmodified(relativePath, currentHash) {
+    const entry = this.files[relativePath];
+    if (!entry) return false;
+    return entry.modifiedHash === currentHash;
+  }
+
+  /**
+   * Save manifest to disk.
+   * @param {string} dirPath - directory to write manifest.json in
+   */
+  async save(dirPath) {
+    const filePath = join(dirPath, MANIFEST_FILENAME);
+    await mkdir(dirname(filePath), { recursive: true });
+    const data = {
+      version: this.version,
+      createdAt: this.createdAt,
+      seed: this.seed,
+      mode: this.mode,
+      files: this.files,
+      runtimeFiles: this.runtimeFiles,
+    };
+    await writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  /**
+   * Load manifest from disk. Returns null if no manifest exists.
+   * @param {string} dirPath
+   * @returns {Promise<Manifest|null>}
+   */
+  static async load(dirPath) {
+    const filePath = join(dirPath, MANIFEST_FILENAME);
+    try {
+      const raw = await readFile(filePath, 'utf-8');
+      const data = JSON.parse(raw);
+      const manifest = new Manifest();
+      manifest.version = data.version;
+      manifest.createdAt = data.createdAt;
+      manifest.seed = data.seed;
+      manifest.mode = data.mode;
+      manifest.files = data.files || {};
+      manifest.runtimeFiles = data.runtimeFiles || [];
+      return manifest;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Delete manifest file.
+   * @param {string} dirPath
+   */
+  static async delete(dirPath) {
+    try {
+      await unlink(join(dirPath, MANIFEST_FILENAME));
+    } catch {
+      // Already gone
+    }
+  }
+}
+
+/**
+ * Compute SHA-256 hash of a string (for file content tracking).
+ * @param {string} content
+ * @returns {string}
+ */
+export function hashContent(content) {
+  return 'sha256:' + createHash('sha256').update(content, 'utf-8').digest('hex');
+}

package/src/core/parsers/index.js

@@ -0,0 +1,40 @@
+import { parseJestOutput } from './jest.js';
+import { parseNodeTestOutput } from './node-test.js';
+import { parseTapOutput } from './tap.js';
+
+const parsers = {
+  jest: parseJestOutput,
+  'node-test': parseNodeTestOutput,
+  tap: parseTapOutput,
+};
+
+/**
+ * Auto-detect the test runner from the command string.
+ * Returns parser key; defaults to 'tap' as a universal fallback.
+ */
+export function detectRunner(testCommand) {
+  if (testCommand.includes('jest') || testCommand.includes('react-scripts test')) {
+    return 'jest';
+  }
+  if (testCommand.includes('node --test') || testCommand.includes('node:test')) {
+    return 'node-test';
+  }
+  return 'tap';
+}
+
+/**
+ * Parse test runner output using the specified or auto-detected runner.
+ * Returns normalized { parsed, tests, totalPassed, totalFailed, totalSkipped }.
+ */
+export function parseTestOutput(runner, stdout) {
+  const parserFn = parsers[runner];
+  if (!parserFn) {
+    return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+  }
+
+  try {
+    return parserFn(stdout);
+  } catch {
+    return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+  }
+}

package/src/core/parsers/jest.js

@@ -0,0 +1,52 @@
+/**
+ * Parses Jest JSON output (from `jest --json`).
+ *
+ * Jest JSON schema:
+ * {
+ *   testResults: [{
+ *     testFilePath: string,
+ *     testResults: [{
+ *       fullName: string,
+ *       status: "passed" | "failed" | "pending",
+ *       duration: number (ms),
+ *       failureMessages: string[]
+ *     }]
+ *   }]
+ * }
+ */
+export function parseJestOutput(stdout) {
+  try {
+    const data = JSON.parse(stdout);
+    if (!data.testResults || !Array.isArray(data.testResults)) {
+      return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+    }
+
+    const tests = [];
+    for (const suite of data.testResults) {
+      const file = suite.testFilePath || '';
+      for (const t of suite.testResults || []) {
+        const status =
+          t.status === 'passed' ? 'passed' :
+          t.status === 'failed' ? 'failed' : 'skipped';
+
+        tests.push({
+          name: t.fullName || t.title || '',
+          file,
+          status,
+          durationMs: t.duration ?? null,
+          failureMessage: t.failureMessages?.length ? t.failureMessages.join('\n') : null,
+        });
+      }
+    }
+
+    return {
+      parsed: true,
+      tests,
+      totalPassed: tests.filter(t => t.status === 'passed').length,
+      totalFailed: tests.filter(t => t.status === 'failed').length,
+      totalSkipped: tests.filter(t => t.status === 'skipped').length,
+    };
+  } catch {
+    return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+  }
+}

package/src/core/parsers/node-test.js

@@ -0,0 +1,64 @@
+/**
+ * Parses node:test JSON reporter output (NDJSON).
+ *
+ * Each line is a JSON object with:
+ *   type: "test:pass" | "test:fail" | "test:start" | "test:plan" | ...
+ *   data: { name, nesting, details: { duration_ms, error? }, file? }
+ *
+ * We only care about "test:pass" and "test:fail" events.
+ * Filter to leaf tests: nesting > 0, or nesting === 0 if no nested tests exist.
+ */
+export function parseNodeTestOutput(stdout) {
+  try {
+    const lines = stdout.split('\n').filter(l => l.trim());
+    const events = [];
+
+    for (const line of lines) {
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // skip non-JSON lines (e.g. stderr mixed in)
+      }
+    }
+
+    const testEvents = events.filter(
+      e => e.type === 'test:pass' || e.type === 'test:fail'
+    );
+
+    if (testEvents.length === 0) {
+      return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+    }
+
+    // Determine which events are leaf tests (not describe blocks).
+    // Describe blocks at nesting 0 have child tests at nesting > 0.
+    // If ALL events are nesting 0, they're individual tests (no describes).
+    const maxNesting = Math.max(...testEvents.map(e => e.data?.nesting ?? 0));
+    const leafEvents = maxNesting > 0
+      ? testEvents.filter(e => (e.data?.nesting ?? 0) > 0)
+      : testEvents;
+
+    const tests = leafEvents.map(e => {
+      const d = e.data || {};
+      const status = e.type === 'test:pass' ? 'passed' : 'failed';
+      const error = d.details?.error;
+
+      return {
+        name: d.name || '',
+        file: d.file || '',
+        status,
+        durationMs: d.details?.duration_ms ?? null,
+        failureMessage: error ? (error.message || String(error)) : null,
+      };
+    });
+
+    return {
+      parsed: true,
+      tests,
+      totalPassed: tests.filter(t => t.status === 'passed').length,
+      totalFailed: tests.filter(t => t.status === 'failed').length,
+      totalSkipped: tests.filter(t => t.status === 'skipped').length,
+    };
+  } catch {
+    return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+  }
+}

package/src/core/parsers/tap.js

@@ -0,0 +1,92 @@
+/**
+ * Parses TAP version 13 output.
+ *
+ * TAP lines:
+ *   ok N - description
+ *   not ok N - description
+ *   ok N - description # skip reason
+ *   ok N - description # todo reason
+ *   --- (YAML diagnostic block start)
+ *   ... (YAML diagnostic block end)
+ *   1..N (plan line, ignored)
+ *   TAP version 13 (version line, ignored)
+ */
+export function parseTapOutput(stdout) {
+  try {
+    const lines = stdout.split('\n');
+    const tests = [];
+    let inYaml = false;
+    let yamlLines = [];
+    let yamlMessage = null;
+
+    const TEST_LINE = /^(ok|not ok)\s+(\d+)?\s*-?\s*(.*)/;
+    const DIRECTIVE = /#\s*(skip|todo)\b/i;
+
+    for (const line of lines) {
+      if (inYaml) {
+        if (line.trim() === '...') {
+          // End YAML block, attach to last failed test
+          if (tests.length > 0 && tests[tests.length - 1].status === 'failed') {
+            tests[tests.length - 1].failureMessage =
+              yamlMessage || yamlLines.join('\n') || null;
+          }
+          inYaml = false;
+          yamlLines = [];
+          yamlMessage = null;
+          continue;
+        }
+        const trimmed = line.trim();
+        yamlLines.push(trimmed);
+        const msgMatch = trimmed.match(/^message:\s*['"]?(.*?)['"]?\s*$/);
+        if (msgMatch) {
+          yamlMessage = msgMatch[1];
+        }
+        continue;
+      }
+
+      if (line.trim() === '---' && tests.length > 0) {
+        inYaml = true;
+        continue;
+      }
+
+      const match = line.match(TEST_LINE);
+      if (!match) continue;
+
+      const ok = match[1] === 'ok';
+      const description = match[3] || '';
+
+      const directiveMatch = description.match(DIRECTIVE);
+      let status;
+      let name = description;
+
+      if (directiveMatch) {
+        status = 'skipped';
+        name = description.slice(0, description.indexOf('#')).trim();
+      } else {
+        status = ok ? 'passed' : 'failed';
+      }
+
+      tests.push({
+        name,
+        file: null,
+        status,
+        durationMs: null,
+        failureMessage: null,
+      });
+    }
+
+    if (tests.length === 0) {
+      return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+    }
+
+    return {
+      parsed: true,
+      tests,
+      totalPassed: tests.filter(t => t.status === 'passed').length,
+      totalFailed: tests.filter(t => t.status === 'failed').length,
+      totalSkipped: tests.filter(t => t.status === 'skipped').length,
+    };
+  } catch {
+    return { parsed: false, tests: [], totalPassed: 0, totalFailed: 0, totalSkipped: 0 };
+  }
+}

package/src/core/profile.js

@@ -0,0 +1,72 @@
+const VALID_MODES = ['light', 'medium', 'hardcore'];
+const VALID_DISTRIBUTIONS = ['uniform'];
+
+/**
+ * FlakeProfile resolves mode settings and delay distribution config.
+ * Passed to adapters as part of injection options.
+ */
+export class FlakeProfile {
+  /**
+   * @param {Object} options
+   * @param {string} [options.mode='medium']
+   * @param {number} [options.minDelayMs=0]
+   * @param {number} [options.maxDelayMs=50]
+   * @param {string} [options.distribution='uniform']
+   * @param {boolean} [options.skipTryCatch=false]
+   * @param {boolean} [options.skipGenerators=true]
+   */
+  constructor(options = {}) {
+    this.mode = options.mode || 'medium';
+    this.minDelayMs = options.minDelayMs ?? 0;
+    this.maxDelayMs = options.maxDelayMs ?? 50;
+    this.distribution = options.distribution || 'uniform';
+    this.skipTryCatch = options.skipTryCatch ?? false;
+    this.skipGenerators = options.skipGenerators ?? true;
+
+    if (!VALID_MODES.includes(this.mode)) {
+      throw new Error(`Invalid mode "${this.mode}". Must be one of: ${VALID_MODES.join(', ')}`);
+    }
+    if (!VALID_DISTRIBUTIONS.includes(this.distribution)) {
+      throw new Error(`Invalid distribution "${this.distribution}". Must be one of: ${VALID_DISTRIBUTIONS.join(', ')}`);
+    }
+    if (this.minDelayMs < 0) throw new Error('minDelayMs must be >= 0');
+    if (this.maxDelayMs < this.minDelayMs) throw new Error('maxDelayMs must be >= minDelayMs');
+  }
+
+  /**
+   * Build the inject options object to pass to a language adapter.
+   * @param {string} filePath - relative file path
+   * @param {number} seed - integer seed for this run
+   * @returns {Object}
+   */
+  toInjectOptions(filePath, seed) {
+    return {
+      filePath,
+      mode: this.mode,
+      seed,
+      delayConfig: {
+        minMs: this.minDelayMs,
+        maxMs: this.maxDelayMs,
+        distribution: this.distribution,
+      },
+      skipTryCatch: this.skipTryCatch,
+      skipGenerators: this.skipGenerators,
+    };
+  }
+
+  /**
+   * Create a FlakeProfile from a merged config object.
+   * @param {Object} config
+   * @returns {FlakeProfile}
+   */
+  static fromConfig(config) {
+    return new FlakeProfile({
+      mode: config.mode,
+      minDelayMs: config.minDelayMs,
+      maxDelayMs: config.maxDelayMs,
+      distribution: config.distribution,
+      skipTryCatch: config.skipTryCatch,
+      skipGenerators: config.skipGenerators,
+    });
+  }
+}

package/src/core/reporter.js

@@ -0,0 +1,75 @@
+/**
+ * Formats test run results for terminal output.
+ */
+export class Reporter {
+  constructor({ quiet = false } = {}) {
+    this.quiet = quiet;
+  }
+
+  log(...args) {
+    if (!this.quiet) console.log(...args);
+  }
+
+  /**
+   * Print a summary of all test runs.
+   * @param {Object[]} results - Array of per-run results
+   *   Each: { runIndex, seed, exitCode, stdout, stderr, durationMs, workspacePath, kept }
+   * @param {number} totalRuns
+   */
+  summarize(results, totalRuns) {
+    if (this.quiet) return;
+    console.log('\n--- FlakeMonster Results ---\n');
+
+    const failures = [];
+
+    for (const r of results) {
+      const status = r.exitCode === 0 ? 'PASS' : 'FAIL';
+      const dur = (r.durationMs / 1000).toFixed(1);
+      let line = `  Run ${r.runIndex + 1}/${totalRuns}: ${status} (seed=${r.seed}, ${dur}s)`;
+
+      if (r.exitCode !== 0 && r.kept) {
+        line += `\n    Workspace kept: ${r.workspacePath}`;
+      }
+
+      console.log(line);
+
+      if (r.exitCode !== 0) {
+        failures.push(r);
+      }
+    }
+
+    const passed = results.filter((r) => r.exitCode === 0).length;
+    const failed = results.length - passed;
+
+    console.log(`\n  Summary: ${passed}/${totalRuns} passed, ${failed}/${totalRuns} failed`);
+
+    if (failures.length > 0) {
+      const seeds = failures.map((f) => f.seed).join(', ');
+      console.log(`  Failing seeds: ${seeds}`);
+      console.log(`\n  Reproduce a failure:`);
+      console.log(`    flake-monster test --runs 1 --seed ${failures[0].seed} --cmd "<your test command>"`);
+    } else {
+      console.log('\n  No flakes detected in this run.');
+    }
+
+    console.log('');
+  }
+
+  /**
+   * Print a single run result in real-time (during execution).
+   * @param {Object} result
+   * @param {number} totalRuns
+   */
+  printRunResult(result, totalRuns) {
+    if (this.quiet) return;
+    const status = result.exitCode === 0 ? 'PASS' : 'FAIL';
+    const dur = (result.durationMs / 1000).toFixed(1);
+    let line = `  Run ${result.runIndex + 1}/${totalRuns}: ${status} (seed=${result.seed}, ${dur}s)`;
+
+    if (result.exitCode !== 0 && result.kept) {
+      line += ` — workspace kept`;
+    }
+
+    console.log(line);
+  }
+}

package/src/core/seed.js

@@ -0,0 +1,59 @@
+/**
+ * Mulberry32 seeded PRNG.
+ * Returns a function that produces floats in [0, 1) deterministically.
+ * @param {number} seed - 32-bit integer seed
+ * @returns {() => number}
+ */
+export function createRng(seed) {
+  return function () {
+    seed |= 0;
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Simple string hash (DJB2). Returns an unsigned 32-bit integer.
+ * @param {string} str
+ * @returns {number}
+ */
+export function hashString(str) {
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+  }
+  return hash >>> 0;
+}
+
+/**
+ * Derive a sub-seed from a base seed + string context.
+ * Each (file, function, index) combination gets a distinct but deterministic seed.
+ * @param {number} baseSeed
+ * @param {string} context - e.g. "src/user.js:loadUser:0"
+ * @returns {number}
+ */
+export function deriveSeed(baseSeed, context) {
+  return (baseSeed + hashString(context)) | 0;
+}
+
+/**
+ * Generate a random seed when user passes --seed auto.
+ * @returns {number}
+ */
+export function randomSeed() {
+  return Math.floor(Math.random() * 0xffffffff);
+}
+
+/**
+ * Parse seed from CLI input. Returns a numeric seed.
+ * @param {string|number} input - "auto" or a numeric string/number
+ * @returns {number}
+ */
+export function parseSeed(input) {
+  if (input === 'auto') return randomSeed();
+  const n = Number(input);
+  if (Number.isNaN(n)) throw new Error(`Invalid seed: ${input}`);
+  return n | 0;
+}