@gabjauf/vitest-dse 0.1.0

package/babel-plugin.js

@@ -0,0 +1,209 @@
+"use strict";
+
+/**
+ * Babel plugin for DSE instrumentation.
+ *
+ * Rewrites every JS operation that can involve symbolic values into a call
+ * on the global __DSE__ dispatcher:
+ *
+ *   a + b          → __DSE__.B(iid, '+', a, b)
+ *   !a             → __DSE__.U(iid, '!', a)
+ *   obj[key]       → __DSE__.G(iid, obj, key)
+ *   obj[key] = v   → __DSE__.P(iid, obj, key, v)
+ *   if (cond)      → if (__DSE__.C(iid, cond))
+ *   f(a, b)        → __DSE__.I(iid, f, undefined, [a, b])
+ *   obj.m(a)       → __DSE__.I(iid, obj.m, obj, [a])
+ *
+ * Notes:
+ * - path.skip() is intentionally NOT called after replacements so that
+ *   nested expressions (including arrow function bodies in arguments) are
+ *   also instrumented.
+ * - Re-entry into __DSE__.*() calls is blocked at the top of each handler.
+ *
+ * Options:
+ *   nextIid(line, col)  — function returning a unique integer per instrumented site;
+ *                         receives the 1-based line and 0-based column from the AST.
+ */
+module.exports = function dseBabelPlugin({ types: t }) {
+  function dseCall(method, args) {
+    return t.callExpression(
+      t.memberExpression(t.identifier("__DSE__"), t.identifier(method)),
+      args
+    );
+  }
+
+  function iidLit(iid) {
+    return t.numericLiteral(iid);
+  }
+
+  /** True if the node is a __DSE__.*(…) call — skip re-instrumentation. */
+  function isDseCall(node) {
+    return (
+      t.isCallExpression(node) &&
+      t.isMemberExpression(node.callee) &&
+      t.isIdentifier(node.callee.object, { name: "__DSE__" })
+    );
+  }
+
+  /** Extract [line, col] from a Babel AST node's start location. */
+  function nodeLoc(node) {
+    const start = node.loc?.start;
+    return [start?.line ?? null, start?.column ?? null];
+  }
+
+  return {
+    visitor: {
+      // ── Binary operators: a OP b → __DSE__.B(iid, 'OP', a, b) ────────────
+      BinaryExpression(path, state) {
+        if (isDseCall(path.node)) return;
+        const [l, c] = nodeLoc(path.node);
+        const iid = state.opts.nextIid(l, c);
+        path.replaceWith(
+          dseCall("B", [
+            iidLit(iid),
+            t.stringLiteral(path.node.operator),
+            path.node.left,
+            path.node.right,
+          ])
+        );
+        // Do NOT call path.skip() — Babel must continue visiting operands
+        // so that nested binary expressions and member accesses are also rewritten.
+      },
+
+      // ── Unary operators: OP a → __DSE__.U(iid, 'OP', a) ─────────────────
+      UnaryExpression(path, state) {
+        if (path.node.operator === "void" || path.node.operator === "delete") return;
+        if (isDseCall(path.node)) return;
+        const [l, c] = nodeLoc(path.node);
+        const iid = state.opts.nextIid(l, c);
+        path.replaceWith(
+          dseCall("U", [
+            iidLit(iid),
+            t.stringLiteral(path.node.operator),
+            path.node.argument,
+          ])
+        );
+      },
+
+      // ── Property reads: obj.f / obj[k] → __DSE__.G(iid, obj, key) ────────
+      MemberExpression(path, state) {
+        // Skip: callee of a call we're about to handle
+        if (
+          path.parentPath.isCallExpression() &&
+          path.parentPath.node.callee === path.node
+        ) return;
+        // Skip: LHS of assignment
+        if (
+          path.parentPath.isAssignmentExpression() &&
+          path.parentPath.node.left === path.node
+        ) return;
+        // Skip: already a __DSE__ member
+        if (t.isIdentifier(path.node.object, { name: "__DSE__" })) return;
+
+        const [l, c] = nodeLoc(path.node);
+        const iid = state.opts.nextIid(l, c);
+        const key = path.node.computed
+          ? path.node.property
+          : t.stringLiteral(path.node.property.name);
+
+        path.replaceWith(dseCall("G", [iidLit(iid), path.node.object, key]));
+      },
+
+      // ── Property writes: obj.f = v → __DSE__.P(iid, obj, key, v) ─────────
+      AssignmentExpression(path, state) {
+        if (!t.isMemberExpression(path.node.left)) return;
+        if (path.node.operator !== "=") return;
+        if (isDseCall(path.node)) return;
+
+        const [l, c] = nodeLoc(path.node);
+        const iid = state.opts.nextIid(l, c);
+        const member = path.node.left;
+        const key = member.computed
+          ? member.property
+          : t.stringLiteral(member.property.name);
+
+        path.replaceWith(
+          dseCall("P", [iidLit(iid), member.object, key, path.node.right])
+        );
+      },
+
+      // ── Branch conditions ─────────────────────────────────────────────────
+      IfStatement(path, state) {
+        const [l, c] = nodeLoc(path.node.test);
+        path.node.test = dseCall("C", [iidLit(state.opts.nextIid(l, c)), path.node.test]);
+      },
+      WhileStatement(path, state) {
+        const [l, c] = nodeLoc(path.node.test);
+        path.node.test = dseCall("C", [iidLit(state.opts.nextIid(l, c)), path.node.test]);
+      },
+      DoWhileStatement(path, state) {
+        const [l, c] = nodeLoc(path.node.test);
+        path.node.test = dseCall("C", [iidLit(state.opts.nextIid(l, c)), path.node.test]);
+      },
+      ForStatement(path, state) {
+        if (path.node.test) {
+          const [l, c] = nodeLoc(path.node.test);
+          path.node.test = dseCall("C", [iidLit(state.opts.nextIid(l, c)), path.node.test]);
+        }
+      },
+      ConditionalExpression(path, state) {
+        const [l, c] = nodeLoc(path.node.test);
+        path.node.test = dseCall("C", [iidLit(state.opts.nextIid(l, c)), path.node.test]);
+      },
+
+      // Logical expressions short-circuit — treat like binary operators
+      LogicalExpression(path, state) {
+        if (isDseCall(path.node)) return;
+        const [l, c] = nodeLoc(path.node);
+        const iid = state.opts.nextIid(l, c);
+        path.replaceWith(
+          dseCall("B", [
+            iidLit(iid),
+            t.stringLiteral(path.node.operator),
+            path.node.left,
+            path.node.right,
+          ])
+        );
+      },
+
+      // ── Function calls: f(a,b) → __DSE__.I(iid, f, undefined, [a,b]) ────
+      CallExpression(path, state) {
+        // Skip already-instrumented __DSE__.*() calls to prevent infinite loops
+        if (isDseCall(path.node)) return;
+        // Skip require() — must remain a static call so Vite can scan dependencies
+        if (t.isIdentifier(path.node.callee, { name: "require" })) return;
+
+        const [l, c] = nodeLoc(path.node);
+        const iid = state.opts.nextIid(l, c);
+        const callee = path.node.callee;
+        let fn, thisArg;
+
+        if (t.isMemberExpression(callee) &&
+            !t.isIdentifier(callee.object, { name: "__DSE__" })) {
+          const keyNode = callee.computed
+            ? callee.property
+            : t.stringLiteral(callee.property.name);
+          // G iid uses the callee's location (the method reference, not the call site)
+          const [gl, gc] = nodeLoc(callee);
+          const objIid = state.opts.nextIid(gl, gc);
+          fn = dseCall("G", [iidLit(objIid), callee.object, keyNode]);
+          thisArg = callee.object;
+        } else {
+          fn = callee;
+          thisArg = t.identifier("undefined");
+        }
+
+        path.replaceWith(
+          dseCall("I", [
+            iidLit(iid),
+            fn,
+            thisArg,
+            t.arrayExpression(path.node.arguments),
+          ])
+        );
+        // Do NOT call path.skip() — Babel must continue visiting the arguments
+        // so arrow functions passed as callbacks are fully instrumented.
+      },
+    },
+  };
+};

package/coverage.js

@@ -0,0 +1,56 @@
+"use strict";
+
+/**
+ * Babel-friendly coverage tracker.
+ *
+ * Uses iids generated by the Babel plugin (simple integers) rather than
+ * Jalangi2's sid+iid pairs. Maps each iid to a { file, line, col } entry
+ * that was recorded at transform time.
+ */
+class BabelCoverage {
+  /**
+   * @param {Map<number, {file: string, line: number, col: number}>} iidMap
+   */
+  constructor(iidMap) {
+    this._iidMap = iidMap;
+    this._touched = new Set();
+    this._conditionals = new Map(); // iid → { true: bool, false: bool }
+  }
+
+  touch(iid) {
+    this._touched.add(iid);
+  }
+
+  touch_cnd(iid, result) {
+    this._touched.add(iid);
+    if (!this._conditionals.has(iid)) {
+      this._conditionals.set(iid, { true: false, false: false });
+    }
+    this._conditionals.get(iid)[String(result)] = true;
+  }
+
+  reset() {
+    this._touched.clear();
+    this._conditionals.clear();
+  }
+
+  end() {
+    const touched = [];
+    for (const iid of this._touched) {
+      const loc = this._iidMap?.get(iid);
+      if (loc) touched.push(loc);
+    }
+    return { touched };
+  }
+
+  /** Return the last touched iid (used by ExpoSE's search strategy). */
+  last() {
+    let last = -1;
+    for (const iid of this._touched) {
+      if (iid > last) last = iid;
+    }
+    return last;
+  }
+}
+
+module.exports = { BabelCoverage };

package/iid-registry.js

@@ -0,0 +1,45 @@
+"use strict";
+
+/**
+ * Single source of truth for iid assignment across the two instrumentation
+ * paths (Vite transform hook in plugin.js and Module._extensions hook in
+ * setup.js).
+ *
+ * Backed by process.* so all module instances share the same counter and map,
+ * even inside Vitest's vm-isolated contexts where `global` is per-context.
+ *
+ * iid (integer) → { file: string, line: number|null, col: number|null }
+ */
+
+if (process.__DSE_IID_COUNTER__ === undefined) process.__DSE_IID_COUNTER__ = 0;
+if (!process.__DSE_IID_MAP__) process.__DSE_IID_MAP__ = new Map();
+
+/**
+ * Allocate the next iid and record its source location.
+ * @param {string} file  Absolute path of the file being instrumented.
+ * @param {number|null} line  1-based line number from the AST node.
+ * @param {number|null} col   0-based column from the AST node.
+ * @returns {number} The allocated iid.
+ */
+function nextIid(file, line, col) {
+  const iid = process.__DSE_IID_COUNTER__++;
+  process.__DSE_IID_MAP__.set(iid, {
+    file,
+    line: line ?? null,
+    col:  col  ?? null,
+  });
+  return iid;
+}
+
+/** Return the live iid→location map (mutated by nextIid). */
+function getIidMap() {
+  return process.__DSE_IID_MAP__;
+}
+
+/** Reset counter and map (useful in tests). */
+function resetRegistry() {
+  process.__DSE_IID_COUNTER__ = 0;
+  process.__DSE_IID_MAP__ = new Map();
+}
+
+module.exports = { nextIid, getIidMap, resetRegistry };

package/index.js

@@ -0,0 +1,323 @@
+"use strict";
+
+/**
+ * vitest-dse — DSE-powered property testing for Vitest.
+ *
+ * Two APIs:
+ *
+ * 1. Low-level: dse(config, opts?) → Violation[]
+ *    Run symbolic execution and get violations back as a plain array.
+ *    Use with Vitest's native test() + expect():
+ *
+ *      test("abs never returns negative", () => {
+ *        const v = dse({
+ *          fn: (x) => x >= 0 ? x : x,
+ *          symbols: { x: { default: -1 } },
+ *          args: ["x"],
+ *          assert: (r) => r >= 0,
+ *        });
+ *        expect(v).toHaveLength(1);
+ *        expect(v[0].input.x).toBeLessThan(0);
+ *      });
+ *
+ * 2. High-level: symbolicTest(name, config, opts?) — wraps test() for you.
+ *    Kept for backwards compatibility.
+ */
+
+const path = require("path");
+const { setCurrentState } = require("./runtime");
+const { BabelCoverage } = require("./coverage");
+const { getIidMap } = require("./iid-registry");
+
+// Vitest injects `test` as a global in the test environment
+/* global test */
+
+const analyserBin = process.env.DSE_ANALYSER_BIN ||
+  path.join(path.dirname(require.resolve("@gabjauf/expose-analyser/package.json")), "bin");
+const SymbolicStateModule = require(path.join(analyserBin, "SymbolicState"));
+const SymbolicState = SymbolicStateModule.default || SymbolicStateModule;
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Build the initial concrete input from symbols' default values. */
+function initialInput(symbols) {
+  const input = { _bound: 0 };
+  for (const [name, cfg] of Object.entries(symbols)) {
+    input[name] = cfg.default;
+  }
+  return input;
+}
+
+/** Extract concrete values for display in error messages. */
+function concretizeInput(input, state) {
+  const out = {};
+  for (const [k, v] of Object.entries(input)) {
+    if (k === "_bound") continue;
+    out[k] = state ? state.getConcrete(v) : v;
+  }
+  return out;
+}
+
+/** Recursively replace ConcolicValues with their concrete counterparts.
+ *  ConcolicValues are detected by their { concrete, symbolic } shape. */
+function deepConcretize(value) {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "object" && "concrete" in value && "symbolic" in value) {
+    return deepConcretize(value.concrete);
+  }
+  if (Array.isArray(value)) return value.map(deepConcretize);
+  if (typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = deepConcretize(v);
+    return out;
+  }
+  return value;
+}
+
+function formatViolations(violations) {
+  const lines = [`DSE found ${violations.length} violation(s):`];
+  for (const { input, result, error } of violations) {
+    if (error) {
+      lines.push(`  input=${JSON.stringify(input)}  threw: ${error}`);
+    } else {
+      lines.push(`  input=${JSON.stringify(input)}  result=${JSON.stringify(result)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// ── Core DSE loop ──────────────────────────────────────────────────────────────
+
+/**
+ * Run DSE on a function and return all violations found.
+ *
+ * @param {object} config
+ *   fn      — function under test (instrumented by the Babel plugin)
+ *   symbols — { name: { default, min?, max? } }
+ *   args    — ordered list of symbol names to pass as fn arguments
+ *   assert  — (result) => boolean  (must be in an instrumented file)
+ * @param {object} [opts]
+ *   maxPaths — path budget (default 200)
+ * @returns {Array<{ input, result } | { input, error }>}
+ */
+function dse(config, opts = {}) {
+  const maxPaths = opts.maxPaths ?? 200;
+  const { fn, symbols, assert: assertFn } = config;
+  const args = config.args ?? Object.keys(symbols);
+
+  const violations = [];
+  const violationKeys = new Set(); // deduplicate by concrete input
+  const queue = [initialInput(symbols)];
+  const visited = new Set();
+
+  while (queue.length > 0 && visited.size < maxPaths) {
+    const input = queue.shift();
+
+    const bound = input._bound;
+    if (!Number.isInteger(bound) || bound < 0) {
+      throw new Error(
+        `DSE internal error: input._bound must be a non-negative integer, got ${JSON.stringify(bound)}.`
+      );
+    }
+
+    const key = JSON.stringify(input);
+    if (visited.has(key)) continue;
+    visited.add(key);
+
+    const symInput = Object.assign({}, input);
+    const state = new SymbolicState(symInput, null);
+    state.coverage = new BabelCoverage(getIidMap());
+
+    for (const [symName, cfg] of Object.entries(symbols)) {
+      const concreteVal = typeof input[symName] === "number" ? input[symName] : cfg.default;
+      const sym = state.createSymbolicValue(symName, concreteVal);
+      symInput[symName] = sym;
+
+      if (cfg.min != null) {
+        const geq = state.binary(">=", sym, cfg.min);
+        const geq_s = state.asSymbolic(geq);
+        if (geq_s) state.pushCondition(geq_s, true);
+      }
+      if (cfg.max != null) {
+        const leq = state.binary("<=", sym, cfg.max);
+        const leq_s = state.asSymbolic(leq);
+        if (leq_s) state.pushCondition(leq_s, true);
+      }
+    }
+
+    setCurrentState(state);
+    try {
+      const result = fn(...args.map((a) => symInput[a]));
+
+      if (assertFn) {
+        const assertCond = assertFn(result);
+
+        if (!state.isSymbolic(assertCond)) {
+          console.warn(
+            `[vitest-dse] Warning: assert callback is running concretely ` +
+            `(returned a plain ${typeof assertCond}, not a ConcolicValue). ` +
+            `DSE cannot explore assertion violations. ` +
+            `Ensure assert is defined in a file covered by the instrumentation filter.`
+          );
+        }
+
+        const assertPassed = state.getConcrete(assertCond);
+
+        if (!assertPassed) {
+          const concreteInput = concretizeInput(input, state);
+          const vKey = JSON.stringify(concreteInput);
+          if (!violationKeys.has(vKey)) {
+            violationKeys.add(vKey);
+            violations.push({ input: concreteInput, result: deepConcretize(result) });
+          }
+        }
+
+        const assertSym = state.asSymbolic(assertCond);
+        if (assertSym) state.pushCondition(assertSym);
+      }
+    } catch (e) {
+      const concreteInput = concretizeInput(input, state);
+      const vKey = JSON.stringify(concreteInput);
+      if (!violationKeys.has(vKey)) {
+        violationKeys.add(vKey);
+        violations.push({ input: concreteInput, error: String(e) });
+      }
+    } finally {
+      setCurrentState(null);
+    }
+
+    state.alternatives((childInputs) => {
+      for (const { input: alt } of childInputs) {
+        if (!visited.has(JSON.stringify(alt))) queue.push(alt);
+      }
+    });
+  }
+
+  if (queue.length > 0 && visited.size >= maxPaths) {
+    console.warn(
+      `[vitest-dse] Budget exhausted: explored ${visited.size} paths ` +
+      `(maxPaths=${maxPaths}, ${queue.length} remaining). ` +
+      `The property has NOT been fully verified. Increase opts.maxPaths to explore further.`
+    );
+  }
+
+  runConcreteVariants(config, violations, violationKeys);
+
+  return violations;
+}
+
+// ── Concrete type-variant pass ─────────────────────────────────────────────────
+
+/**
+ * Default wrong-type values tried when opts.anyType is true.
+ * Covers the most common runtime type bugs: null/undefined, wrong primitive, array, object.
+ */
+const DEFAULT_TYPE_VARIANTS = [null, undefined, "", "string", NaN, [], {}];
+
+/**
+ * Run the function concretely (no symbolic state) for each (symbol, typeVariant) pair.
+ * Each variant replaces one symbol; all others stay at their default values.
+ * Violations (assert failures or exceptions) are added to the shared violations/keys sets.
+ */
+function runConcreteVariants(config, violations, violationKeys) {
+  const { fn, symbols, assert: assertFn } = config;
+  const args = config.args ?? Object.keys(symbols);
+
+  for (const [symName, cfg] of Object.entries(symbols)) {
+    const variants = cfg.typeVariants === "any" ? DEFAULT_TYPE_VARIANTS : (cfg.typeVariants ?? []);
+    for (const variantVal of variants) {
+      const concreteInput = {};
+      for (const [n, c] of Object.entries(symbols)) {
+        concreteInput[n] = n === symName ? variantVal : c.default;
+      }
+
+      const vKey = JSON.stringify(concreteInput);
+      if (violationKeys.has(vKey)) continue;
+
+      try {
+        const result = fn(...args.map((a) => concreteInput[a]));
+        if (assertFn) {
+          const passed = assertFn(result); // concrete bool — no symbolic state
+          if (!passed) {
+            violationKeys.add(vKey);
+            violations.push({ input: concreteInput, result: deepConcretize(result) });
+          }
+        }
+      } catch (e) {
+        violationKeys.add(vKey);
+        violations.push({ input: concreteInput, error: String(e) });
+      }
+    }
+  }
+}
+
+// ── High-level wrapper (backwards compatible) ──────────────────────────────────
+
+/**
+ * Wrap dse() in a Vitest test with built-in expectation checks.
+ *
+ * @param {string} name
+ * @param {object} config  — same as dse()
+ * @param {object} [opts]
+ *   maxPaths            — path budget (default 200)
+ *   timeout             — Vitest timeout ms (default 120 000)
+ *   expectErrors        — number (exact) | [min,max] | { min?, max? }  (default 0)
+ *   expectCounterexamples — array of partial input specs that must appear in violations
+ */
+function symbolicTest(name, config, opts = {}) {
+  const timeout = opts.timeout ?? 120_000;
+
+  test(name, () => {
+    const violations = dse(config, opts);
+
+    // ── expectErrors check ────────────────────────────────────────────────────
+    const expectErrors = opts.expectErrors ?? 0;
+    let eMin, eMax;
+    if (Array.isArray(expectErrors)) {
+      [eMin, eMax] = expectErrors;
+    } else if (typeof expectErrors === "object" && expectErrors !== null) {
+      eMin = expectErrors.min ?? 0;
+      eMax = expectErrors.max ?? Infinity;
+    } else {
+      eMin = eMax = expectErrors;
+    }
+
+    const n = violations.length;
+    if (n < eMin || n > eMax) {
+      const rangeStr = eMin === eMax ? `${eMin}` : `[${eMin}, ${eMax === Infinity ? "∞" : eMax}]`;
+      const msg = eMin === 0 && eMax === 0
+        ? formatViolations(violations)
+        : `Expected ${rangeStr} violation(s), DSE found ${n}.\n` +
+          (n > 0 ? formatViolations(violations) : "No violations found.");
+      throw new Error(msg);
+    }
+
+    // ── expectCounterexamples check ───────────────────────────────────────────
+    for (const spec of (opts.expectCounterexamples ?? [])) {
+      const found = violations.some(({ input }) =>
+        Object.entries(spec).every(([k, v]) => input[k] === v)
+      );
+      if (!found) {
+        const foundInputs = violations.map(({ input }) => JSON.stringify(input)).join(", ") || "none";
+        throw new Error(
+          `DSE did not find expected counterexample ${JSON.stringify(spec)}.\n` +
+          `Violations found: ${foundInputs}`
+        );
+      }
+    }
+  }, timeout);
+}
+
+// ── Violation filter helpers ───────────────────────────────────────────────────
+
+/** Violations where the function threw an exception. */
+function exceptions(violations) {
+  return violations.filter((v) => v.error !== undefined);
+}
+
+/** Violations where the assert property failed (no exception). */
+function assertFailures(violations) {
+  return violations.filter((v) => v.result !== undefined);
+}
+
+module.exports = { dse, symbolicTest, exceptions, assertFailures };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@gabjauf/vitest-dse",
+  "version": "0.1.0",
+  "description": "DSE-powered property testing for Vitest using ExpoSE engine + Babel instrumentation",
+  "license": "MIT",
+  "keywords": ["vitest", "symbolic-execution", "property-testing", "dse", "expose"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ExpoSEJS/ExpoSE.git",
+    "directory": "lib/vitest-dse"
+  },
+  "scripts": {
+    "prepublishOnly": "npm pack --dry-run"
+  },
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./plugin": "./plugin.js",
+    "./setup": "./setup.js"
+  },
+  "files": [
+    "index.js",
+    "plugin.js",
+    "setup.js",
+    "runtime.js",
+    "babel-plugin.js",
+    "iid-registry.js",
+    "coverage.js"
+  ],
+  "peerDependencies": {
+    "@babel/core": ">=7",
+    "@babel/preset-typescript": ">=7",
+    "@babel/types": ">=7",
+    "@gabjauf/expose-analyser": ">=1",
+    "vitest": ">=1"
+  },
+  "dependencies": {
+    "vite": ">=4"
+  }
+}

package/plugin.js

@@ -0,0 +1,70 @@
+"use strict";
+
+/**
+ * Vite plugin wrapping the DSE Babel instrumentation.
+ *
+ * Usage in vitest.config.symbolic.js:
+ *   const { dsePlugin } = require('@gabjauf/vitest-dse/plugin');
+ *   module.exports = { plugins: [dsePlugin({ include: ['src/**'] })] }
+ *
+ * Options:
+ *   include  — array of minimatch patterns; files that match are instrumented
+ *   exclude  — array of patterns to always skip (default: node_modules + vitest-dse itself)
+ */
+
+const babel = require("@babel/core");
+const dseBabelPlugin = require("./babel-plugin.js");
+const { nextIid } = require("./iid-registry.js");
+const path = require("path");
+const { createFilter } = require("vite");
+
+function dsePlugin(opts = {}) {
+  const include = opts.include ?? ["src/**", "tests/**"];
+  const exclude = opts.exclude ?? [];
+
+  const filter = createFilter(include, [
+    "**/node_modules/**",
+    ...exclude,
+  ]);
+
+  return {
+    name: "vitest-dse",
+
+    transform(code, id) {
+      if (!filter(id)) return null;
+
+      // Skip non-JS/TS files
+      if (!/\.[cm]?[jt]sx?$/.test(id)) return null;
+
+      const filename = id;
+      let result;
+      try {
+        result = babel.transformSync(code, {
+          filename,
+          presets: [
+            ["@babel/preset-typescript", { allExtensions: true }],
+          ],
+          plugins: [
+            [
+              dseBabelPlugin,
+              {
+                // Capture filename in closure; babel-plugin passes (line, col)
+                nextIid: (line, col) => nextIid(filename, line, col),
+              },
+            ],
+          ],
+          sourceMaps: true,
+          configFile: false,
+          babelrc: false,
+        });
+      } catch (e) {
+        this.warn(`vitest-dse: failed to instrument ${path.relative(process.cwd(), id)}: ${e.message}`);
+        return null;
+      }
+
+      return { code: result.code, map: result.map };
+    },
+  };
+}
+
+module.exports = { dsePlugin };

package/runtime.js

@@ -0,0 +1,237 @@
+"use strict";
+
+/**
+ * DSE Runtime — exposes __DSE__ as a process global.
+ *
+ * When a SymbolicState is active (set via setCurrentState), every __DSE__
+ * method delegates to the state for symbolic reasoning.
+ *
+ * When no state is active (null), all methods fall through to their concrete
+ * implementations so that regular (non-symbolic) code still works.
+ */
+
+const path = require("path");
+
+// Resolve from Analyser/bin (compiled CJS)
+const analyserBin = path.join(__dirname, "../../Analyser/bin");
+
+const SymbolicStateModule = require(path.join(analyserBin, "SymbolicState"));
+const SymbolicState = SymbolicStateModule.default || SymbolicStateModule;
+
+const { ConcolicValue } = require(path.join(analyserBin, "Values/WrappedValue"));
+const { isNative } = require(path.join(analyserBin, "Utilities/IsNative"));
+const ModelBuilder = require(path.join(analyserBin, "Models/Models"));
+
+// ── State management ──────────────────────────────────────────────────────────
+
+// Store state on global so all module instances (Vitest creates several) share one reference.
+function setCurrentState(state) {
+  process.__DSE_STATE__ = state;
+  process.__DSE_MODELS__ = state ? (ModelBuilder.default || ModelBuilder)(state) : null;
+}
+
+function getCurrentState() {
+  return process.__DSE_STATE__ ?? null;
+}
+
+// ── Concrete fallbacks ─────────────────────────────────────────────────────────
+
+function concreteBinary(op, left, right) {
+  switch (op) {
+    case "+":   return left + right;
+    case "-":   return left - right;
+    case "*":   return left * right;
+    case "/":   return left / right;
+    case "%":   return left % right;
+    case "**":  return left ** right;
+    case "<":   return left < right;
+    case "<=":  return left <= right;
+    case ">":   return left > right;
+    case ">=":  return left >= right;
+    case "==":  return left == right;  // eslint-disable-line eqeqeq
+    case "===": return left === right;
+    case "!=":  return left != right;  // eslint-disable-line eqeqeq
+    case "!==": return left !== right;
+    case "&&":  return left && right;
+    case "||":  return left || right;
+    case "??":  return left ?? right;
+    case "&":   return left & right;
+    case "|":   return left | right;
+    case "^":   return left ^ right;
+    case "<<":  return left << right;
+    case ">>":  return left >> right;
+    case ">>>": return left >>> right;
+    case "in":          return left in right;
+    case "instanceof":  return left instanceof right;
+    default:
+      throw new TypeError(`[vitest-dse] Unsupported binary operator: ${op}`);
+  }
+}
+
+function concreteUnary(op, arg) {
+  switch (op) {
+    case "!":      return !arg;
+    case "-":      return -arg;
+    case "+":      return +arg;
+    case "~":      return ~arg;
+    case "typeof": return typeof arg;
+    default:
+      throw new TypeError(`[vitest-dse] Unsupported unary operator: ${op}`);
+  }
+}
+
+// ── __DSE__ global ─────────────────────────────────────────────────────────────
+
+const __DSE__ = {
+  /**
+   * Binary operator: a OP b
+   */
+  B(iid, op, left, right) {
+    if (!process.__DSE_STATE__) return concreteBinary(op, left, right);
+    process.__DSE_STATE__.coverage.touch(iid);
+    return process.__DSE_STATE__.binary(op, left, right);
+  },
+
+  /**
+   * Unary operator: OP a
+   */
+  U(iid, op, arg) {
+    if (!process.__DSE_STATE__) return concreteUnary(op, arg);
+    process.__DSE_STATE__.coverage.touch(iid);
+    return process.__DSE_STATE__.unary(op, arg);
+  },
+
+  /**
+   * Property read: obj[key]
+   */
+  G(iid, base, offset) {
+    if (!process.__DSE_STATE__) {
+      const b = base;
+      return b == null ? undefined : b[offset];
+    }
+    process.__DSE_STATE__.coverage.touch(iid);
+
+    const base_c = process.__DSE_STATE__.getConcrete(base);
+
+    // SymbolicObject field read
+    const { SymbolicObject } = require(path.join(analyserBin, "Values/SymbolicObject"));
+    if (base instanceof SymbolicObject) {
+      return base.getField(process.__DSE_STATE__, process.__DSE_STATE__.getConcrete(offset));
+    }
+
+    // Symbolic string offset on concrete object
+    if (!process.__DSE_STATE__.isSymbolic(base) && process.__DSE_STATE__.isSymbolic(offset) && typeof process.__DSE_STATE__.getConcrete(offset) === "string") {
+      const offset_c = process.__DSE_STATE__.getConcrete(offset);
+      for (const idx in base_c) {
+        const test = process.__DSE_STATE__.binary("==", idx, offset);
+        if (process.__DSE_STATE__.asSymbolic(test)) process.__DSE_STATE__.pushCondition(process.__DSE_STATE__.asSymbolic(test));
+      }
+      return base_c[offset_c];
+    }
+
+    // Symbolic array index on concrete array
+    if (!process.__DSE_STATE__.isSymbolic(base) && process.__DSE_STATE__.isSymbolic(offset) &&
+        Array.isArray(base_c) && typeof process.__DSE_STATE__.getConcrete(offset) === "number") {
+      for (let i = 0; i < base_c.length; i++) {
+        process.__DSE_STATE__.assertEqual(i, offset);
+      }
+      return base_c[process.__DSE_STATE__.getConcrete(offset)];
+    }
+
+    // Symbolic base: use symbolicField
+    const result_s = process.__DSE_STATE__.isSymbolic(base)
+      ? process.__DSE_STATE__.symbolicField(base_c, process.__DSE_STATE__.asSymbolic(base), process.__DSE_STATE__.getConcrete(offset), process.__DSE_STATE__.asSymbolic(offset))
+      : undefined;
+    const result_c = base_c == null ? undefined : base_c[process.__DSE_STATE__.getConcrete(offset)];
+
+    return result_s ? new ConcolicValue(result_c, result_s) : result_c;
+  },
+
+  /**
+   * Property write: obj[key] = val
+   * Returns the value (assignment expression result).
+   */
+  P(iid, base, offset, val) {
+    if (!process.__DSE_STATE__) {
+      if (base != null) base[offset] = val;
+      return val;
+    }
+    process.__DSE_STATE__.coverage.touch(iid);
+
+    const base_c = process.__DSE_STATE__.getConcrete(base);
+    const offset_c = process.__DSE_STATE__.getConcrete(offset);
+    const val_c = process.__DSE_STATE__.getConcrete(val);
+
+    const { SymbolicObject } = require(path.join(analyserBin, "Values/SymbolicObject"));
+    if (base instanceof SymbolicObject) {
+      return base.setField(process.__DSE_STATE__, offset_c, val);
+    }
+
+    // For symbolic arrays with typed elements, track field updates
+    if (process.__DSE_STATE__.isSymbolic(base) && Array.isArray(base_c) && process.__DSE_STATE__.arrayType(base) === typeof val_c) {
+      const newArr = base_c.slice();
+      newArr[offset_c] = val_c;
+      const newSym = process.__DSE_STATE__.asSymbolic(base).setField(process.__DSE_STATE__.ctx.mkRealToInt(process.__DSE_STATE__.asSymbolic(offset)), process.__DSE_STATE__.asSymbolic(val));
+      const result = new ConcolicValue(newArr, newSym);
+      if (base_c) base_c[offset_c] = val_c;
+      return result;
+    }
+
+    if (base_c != null) base_c[offset_c] = val_c;
+    return val;
+  },
+
+  /**
+   * Branch condition (if/while/for/ternary)
+   */
+  C(iid, cond) {
+    if (!process.__DSE_STATE__) return !!cond;
+    process.__DSE_STATE__.coverage.touch_cnd(iid, !!process.__DSE_STATE__.getConcrete(cond));
+    return process.__DSE_STATE__.conditional(cond);
+  },
+
+  /**
+   * Function invocation: fn.apply(thisArg, args)
+   */
+  I(iid, fn, thisArg, args) {
+    if (!process.__DSE_STATE__) {
+      const f = fn;
+      const t = thisArg;
+      return f == null ? undefined : f.apply(t, args);
+    }
+    process.__DSE_STATE__.coverage.touch(iid);
+
+    const fn_c = process.__DSE_STATE__.getConcrete(fn);
+    const thisArg_c = process.__DSE_STATE__.getConcrete(thisArg);
+
+    if (fn_c == null) {
+      throw new TypeError("__DSE__.I: called non-function");
+    }
+
+    // Check for a registered model
+    const fn_model = process.__DSE_MODELS__ ? process.__DSE_MODELS__.get(fn_c) : null;
+
+    if (fn_model) {
+      // The Model registry wraps each handler as: function mdl() { return _mdl.call(null, this, arguments); }
+      // So models are called via fn_model.apply(thisArg, args):
+      //   this  → base (receiver)
+      //   arguments[i] → args[i] (call arguments, possibly ConcolicValues)
+      return fn_model.apply(thisArg, args);
+    }
+
+    // Native function without model: concretize symbolic args
+    if (isNative(fn_c)) {
+      const concreteArgs = args.map(a => process.__DSE_STATE__.getConcrete(a));
+      const concreteThis = process.__DSE_STATE__.getConcrete(thisArg);
+      return fn_c.apply(concreteThis, concreteArgs);
+    }
+
+    // User function: call with wrapped args (symbolic values pass through)
+    return fn_c.apply(thisArg_c, args);
+  },
+};
+
+// Register as a global so instrumented code can access it without importing
+global.__DSE__ = __DSE__;
+
+module.exports = { setCurrentState, getCurrentState, __DSE__ };

package/setup.js

@@ -0,0 +1,78 @@
+"use strict";
+
+/**
+ * Vitest setupFile — must run before any test file.
+ *
+ * 1. Registers __DSE__ as a global so instrumented code can call it.
+ * 2. Patches Module._extensions to run our Babel transform on every CJS .js
+ *    file that matches the include patterns, using the shared iid-registry so
+ *    iids assigned here and by the Vite plugin (plugin.js) never collide.
+ *
+ * Include patterns are read from DSE_INCLUDE_PATTERNS (a JSON-encoded string
+ * array set by vitest.config.symbolic.js) so the filter always matches what
+ * the Vite plugin was configured with.
+ */
+
+require("./runtime");
+
+const Module = require("module");
+const fs = require("fs");
+const babel = require("@babel/core");
+const dseBabelPlugin = require("./babel-plugin.js");
+const { nextIid } = require("./iid-registry.js");
+const { createFilter } = require("vite");
+
+// ── Filter configuration ───────────────────────────────────────────────────
+// Read patterns from the env var set by vitest.config.symbolic.js so this
+// file and the Vite plugin always agree on what to instrument.
+const include = process.env.DSE_INCLUDE_PATTERNS
+  ? JSON.parse(process.env.DSE_INCLUDE_PATTERNS)
+  : ["src/**", "tests/examples/**"]; // fallback for standalone use
+
+const filter = createFilter(include, [
+  "**/node_modules/**",
+]);
+
+// ── Module._extensions hook ────────────────────────────────────────────────
+
+function instrumentAndLoad(mod, filename, fallback) {
+  if (!filter(filename)) return fallback(mod, filename);
+
+  const source = fs.readFileSync(filename, "utf8");
+
+  // If the file was already transformed by the Vite plugin (i.e. it came
+  // through the Vite transform pipeline before being require()'d), skip it
+  // to avoid double-instrumentation.
+  if (source.includes("__DSE__")) return fallback(mod, filename);
+
+  let result;
+  try {
+    result = babel.transformSync(source, {
+      filename,
+      presets: [
+        ["@babel/preset-typescript", { allExtensions: true }],
+      ],
+      plugins: [
+        [
+          dseBabelPlugin,
+          {
+            nextIid: (line, col) => nextIid(filename, line, col),
+          },
+        ],
+      ],
+      sourceMaps: "inline",
+      configFile: false,
+      babelrc: false,
+    });
+  } catch (e) {
+    return fallback(mod, filename);
+  }
+
+  mod._compile(result.code, filename);
+}
+
+const originalJsLoader = Module._extensions[".js"];
+Module._extensions[".js"] = (mod, filename) => instrumentAndLoad(mod, filename, originalJsLoader);
+
+const originalTsLoader = Module._extensions[".ts"] || originalJsLoader;
+Module._extensions[".ts"] = (mod, filename) => instrumentAndLoad(mod, filename, originalTsLoader);