@vitest-agent/engine 0.1.0

package/testing.js

@@ -0,0 +1,243 @@
+import { DataReader } from "./services/DataReader.js";
+import { DataStore } from "./services/DataStore.js";
+import { PROJECT_MIGRATIONS } from "./migrations/index.js";
+import { DataStoreTestLayer, makeTestLayer } from "./testing/layers.js";
+import { Agent, AgentId, AgentNotFoundError, AgentReport, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, ChatId, CoverageBaselines, CoverageReport, DataStoreError, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, RegistrationConflictError, TddTaskAlreadyEndedError, TddTaskNotFoundError, TrendEntry, TrendRecord } from "@vitest-agent/sdk";
+import { Effect, Layer } from "effect";
+
+//#region src/testing/index.ts
+/** @public */
+function empty(filename) {
+	return makeTestLayer(filename);
+}
+/** @public */
+function singlePassingRun(filename) {
+	const base = makeTestLayer(filename);
+	const seed = Effect.gen(function* () {
+		const store = yield* DataStore;
+		yield* store.writeSettings("hash-preset-spr", {
+			vitestVersion: "5.0.0",
+			pool: "forks"
+		}, {});
+		const runId = yield* store.writeRun({
+			invocationId: "inv-preset-spr-1",
+			project: "default",
+			settingsHash: "hash-preset-spr",
+			timestamp: "2026-01-01T00:00:00.000Z",
+			commitSha: null,
+			branch: null,
+			reason: "passed",
+			duration: 1200,
+			total: 3,
+			passed: 3,
+			failed: 0,
+			skipped: 0,
+			scoped: false
+		});
+		const fileId = yield* store.ensureFile("src/math.test.ts");
+		const [moduleId] = yield* store.writeModules(runId, [{
+			fileId,
+			relativeModuleId: "src/math.test.ts",
+			state: "passed",
+			duration: 1200
+		}]);
+		yield* store.writeTestCases(moduleId, [
+			{
+				name: "adds two numbers",
+				fullName: "math > adds two numbers",
+				state: "passed",
+				duration: 400
+			},
+			{
+				name: "subtracts two numbers",
+				fullName: "math > subtracts two numbers",
+				state: "passed",
+				duration: 400
+			},
+			{
+				name: "multiplies two numbers",
+				fullName: "math > multiplies two numbers",
+				state: "passed",
+				duration: 400
+			}
+		]);
+	});
+	return Layer.effectDiscard(seed).pipe(Layer.provideMerge(base));
+}
+/** @public */
+function withFailures(filename) {
+	const base = makeTestLayer(filename);
+	const seed = Effect.gen(function* () {
+		const store = yield* DataStore;
+		yield* store.writeSettings("hash-preset-wf", {
+			vitestVersion: "5.0.0",
+			pool: "forks"
+		}, {});
+		const runId = yield* store.writeRun({
+			invocationId: "inv-preset-wf-1",
+			project: "default",
+			settingsHash: "hash-preset-wf",
+			timestamp: "2026-01-01T00:00:00.000Z",
+			commitSha: null,
+			branch: null,
+			reason: "failed",
+			duration: 1500,
+			total: 4,
+			passed: 2,
+			failed: 2,
+			skipped: 0,
+			scoped: false
+		});
+		const fileId = yield* store.ensureFile("src/parser.test.ts");
+		const [moduleId] = yield* store.writeModules(runId, [{
+			fileId,
+			relativeModuleId: "src/parser.test.ts",
+			state: "failed",
+			duration: 1500
+		}]);
+		yield* store.writeTestCases(moduleId, [
+			{
+				name: "parses valid input",
+				fullName: "parser > parses valid input",
+				state: "passed",
+				duration: 300
+			},
+			{
+				name: "parses nested structure",
+				fullName: "parser > parses nested structure",
+				state: "passed",
+				duration: 300
+			},
+			{
+				name: "rejects empty input",
+				fullName: "parser > rejects empty input",
+				state: "failed",
+				duration: 450
+			},
+			{
+				name: "rejects malformed input",
+				fullName: "parser > rejects malformed input",
+				state: "failed",
+				duration: 450
+			}
+		]);
+	});
+	return Layer.effectDiscard(seed).pipe(Layer.provideMerge(base));
+}
+/** @public */
+function flaky(filename) {
+	const base = makeTestLayer(filename);
+	const seed = Effect.gen(function* () {
+		const store = yield* DataStore;
+		yield* store.writeSettings("hash-preset-flaky", {
+			vitestVersion: "5.0.0",
+			pool: "forks"
+		}, {});
+		const runId1 = yield* store.writeRun({
+			invocationId: "inv-preset-flaky-1",
+			project: "default",
+			settingsHash: "hash-preset-flaky",
+			timestamp: "2026-01-01T00:00:00.000Z",
+			commitSha: null,
+			branch: null,
+			reason: "failed",
+			duration: 800,
+			total: 2,
+			passed: 1,
+			failed: 1,
+			skipped: 0,
+			scoped: false
+		});
+		const fileId = yield* store.ensureFile("src/async.test.ts");
+		const [moduleId1] = yield* store.writeModules(runId1, [{
+			fileId,
+			relativeModuleId: "src/async.test.ts",
+			state: "failed",
+			duration: 800
+		}]);
+		yield* store.writeTestCases(moduleId1, [{
+			name: "resolves within timeout",
+			fullName: "async > resolves within timeout",
+			state: "failed",
+			duration: 500
+		}, {
+			name: "rejects on error",
+			fullName: "async > rejects on error",
+			state: "passed",
+			duration: 300
+		}]);
+		yield* store.writeHistory("default", "async > resolves within timeout", "src/async.test.ts", runId1, "2025-12-31T23:00:00.000Z", "passed", 500, false, 0, null);
+		yield* store.writeHistory("default", "async > resolves within timeout", "src/async.test.ts", runId1, "2026-01-01T00:00:00.000Z", "failed", 500, false, 0, null);
+		yield* store.writeHistory("default", "async > rejects on error", "src/async.test.ts", runId1, "2026-01-01T00:00:00.000Z", "passed", 300, false, 0, null);
+		const runId2 = yield* store.writeRun({
+			invocationId: "inv-preset-flaky-2",
+			project: "default",
+			settingsHash: "hash-preset-flaky",
+			timestamp: "2026-01-01T01:00:00.000Z",
+			commitSha: null,
+			branch: null,
+			reason: "passed",
+			duration: 700,
+			total: 2,
+			passed: 2,
+			failed: 0,
+			skipped: 0,
+			scoped: false
+		});
+		const [moduleId2] = yield* store.writeModules(runId2, [{
+			fileId,
+			relativeModuleId: "src/async.test.ts",
+			state: "passed",
+			duration: 700
+		}]);
+		yield* store.writeTestCases(moduleId2, [{
+			name: "resolves within timeout",
+			fullName: "async > resolves within timeout",
+			state: "passed",
+			duration: 400
+		}, {
+			name: "rejects on error",
+			fullName: "async > rejects on error",
+			state: "passed",
+			duration: 300
+		}]);
+		yield* store.writeHistory("default", "async > resolves within timeout", "src/async.test.ts", runId2, "2026-01-01T01:00:00.000Z", "passed", 400, false, 0, null);
+		yield* store.writeHistory("default", "async > rejects on error", "src/async.test.ts", runId2, "2026-01-01T01:00:00.000Z", "passed", 300, false, 0, null);
+	});
+	return Layer.effectDiscard(seed).pipe(Layer.provideMerge(base));
+}
+/** @public */
+function withTddTask(filename) {
+	const base = makeTestLayer(filename);
+	const seed = Effect.gen(function* () {
+		const store = yield* DataStore;
+		const sessionId = yield* store.writeSession({
+			chatId: "chat-preset-tdd",
+			project: "default",
+			cwd: "/workspace",
+			agentKind: "main",
+			startedAt: "2026-01-01T00:00:00.000Z"
+		});
+		const tddTaskId = yield* store.writeTddTask({
+			sessionId,
+			goal: "Implement the parser feature",
+			startedAt: "2026-01-01T00:00:00.000Z"
+		});
+		const goal = yield* store.createGoal({
+			tddTaskId,
+			goal: "Handle edge cases"
+		});
+		yield* store.createBehavior({
+			goalId: goal.id,
+			behavior: "rejects empty input"
+		});
+		yield* store.createBehavior({
+			goalId: goal.id,
+			behavior: "rejects null input"
+		});
+	});
+	return Layer.effectDiscard(seed).pipe(Layer.provideMerge(base));
+}
+
+//#endregion
+export { Agent, AgentId, AgentNotFoundError, AgentReport, BehaviorDetail, BehaviorNotFoundError, BehaviorRow, BehaviorStatus, CacheManifest, ChatId, CoverageBaselines, CoverageReport, DataReader, DataStore, DataStoreError, DataStoreTestLayer, FileCoverageReport, GoalDetail, GoalNotFoundError, GoalRow, GoalStatus, HistoryRecord, IdempotencyHit, IllegalStatusTransitionError, PROJECT_MIGRATIONS, RegistrationConflictError, TddTaskAlreadyEndedError, TddTaskNotFoundError, TrendEntry, TrendRecord, empty, flaky, makeTestLayer, singlePassingRun, withFailures, withTddTask };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.1"
+    }
+  ]
+}

package/utils/ensure-migrated.js

@@ -0,0 +1,47 @@
+import { LoggerLive } from "../layers/LoggerLive.js";
+import { NodePlatformLayer, makeSqliteStack } from "../platform.js";
+import { Effect, Layer } from "effect";
+import { SqlClient } from "effect/unstable/sql/SqlClient";
+
+//#region src/utils/ensure-migrated.ts
+const GLOBAL_KEY = Symbol.for("vitest-agent/migration-promises");
+const getCache = () => {
+	const g = globalThis;
+	let cache = g[GLOBAL_KEY];
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		g[GLOBAL_KEY] = cache;
+	}
+	return cache;
+};
+/**
+* Ensure the SQLite database at `dbPath` is migrated. Runs migrations at
+* most once per dbPath in the current process; concurrent calls share the
+* same in-flight promise. Subsequent calls (after the first resolves) are
+* no-ops.
+* @public
+*/
+function ensureMigrated(dbPath, logLevel, logFile) {
+	const cache = getCache();
+	const cached = cache.get(dbPath);
+	if (cached) return cached;
+	const { SqliteLayer, MigratorLayer } = makeSqliteStack(dbPath);
+	const program = Effect.gen(function* () {
+		yield* SqlClient;
+	}).pipe(Effect.provide(MigratorLayer), Effect.provide(Layer.merge(SqliteLayer, NodePlatformLayer)), Effect.provide(LoggerLive(logLevel, logFile)));
+	const promise = Effect.runPromise(program);
+	cache.set(dbPath, promise);
+	promise.catch(() => {});
+	return promise;
+}
+/**
+* Reset the migration cache. Test-only.
+*
+* @internal
+*/
+function _resetMigrationCacheForTesting() {
+	getCache().clear();
+}
+
+//#endregion
+export { _resetMigrationCacheForTesting, ensureMigrated };

package/utils/failure-signature.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+
+//#region src/utils/failure-signature.ts
+const ASSERTION_REGEX = /(toBe|toEqual|toContain|toMatch|toThrow|toBeNull|toBeUndefined|toBeTruthy|toBeFalsy|toBeGreaterThan|toBeLessThan|toBeInstanceOf|toBeCloseTo|toHaveBeenCalled|toHaveBeenCalledWith|toHaveProperty|toHaveLength)\s*\(([^)]*)\)/;
+const typeTagOf = (literal) => {
+	const trimmed = literal.trim();
+	if (trimmed === "" || trimmed === ")") return "";
+	if (/^\d+(\.\d+)?$/.test(trimmed)) return "<number>";
+	if (/^["'`]/.test(trimmed)) return "<string>";
+	if (/^(true|false)$/.test(trimmed)) return "<boolean>";
+	if (/^null$/.test(trimmed)) return "<null>";
+	if (/^undefined$/.test(trimmed)) return "<undefined>";
+	if (/^[{[]/.test(trimmed)) return "<object>";
+	return "<expr>";
+};
+/** @public */
+const normalizeAssertionShape = (message) => {
+	if (typeof message !== "string") return "";
+	const match = message.match(ASSERTION_REGEX);
+	if (match === null) return null;
+	const matcher = match[1];
+	const arg = typeTagOf(match[2]);
+	return arg === "" ? matcher : `${matcher}(${arg})`;
+};
+/** @public */
+const computeFailureSignature = (input) => {
+	const shape = normalizeAssertionShape(input.assertion_message) ?? "<unknown>";
+	const lineCoord = input.top_frame_function_boundary_line !== null ? `fb:${input.top_frame_function_boundary_line}` : input.top_frame_raw_line !== void 0 ? `raw:${Math.floor(input.top_frame_raw_line / 10) * 10}` : "raw:?";
+	const key = `${input.error_name}|${shape}|${input.top_frame_function_name}|${lineCoord}`;
+	return createHash("sha256").update(key).digest("hex").substring(0, 16);
+};
+
+//#endregion
+export { computeFailureSignature, normalizeAssertionShape };

package/utils/resolve-data-path.js

@@ -0,0 +1,64 @@
+import { VitestAgentConfigFile } from "../services/Config.js";
+import { resolveProjectKeyFromCwd } from "./resolve-project-key-from-cwd.js";
+import { VitestAgentConfig, normalizeWorkspaceKey } from "@vitest-agent/sdk";
+import { Effect, FileSystem } from "effect";
+import { AppDirs } from "@effected/xdg";
+import { join } from "node:path";
+
+//#region src/utils/resolve-data-path.ts
+/**
+* Filename of the SQLite database that stores all reporter data.
+* @public
+*/
+const DATABASE_FILENAME = "data.db";
+/**
+* Resolve the absolute path to the SQLite database for `projectDir`.
+*
+* The directory containing the database is ensured to exist before the
+* function returns, so callers can open the database immediately without
+* needing to create parent directories. The SQLite driver creates the file
+* but not its parent.
+*
+* Precedence (highest first):
+*
+* 1. `options.cacheDir` — programmatic override.
+* 2. `cacheDir` from `vitest-agent.config.toml`.
+* 3. `<XDG data>/<normalized projectKey from config>/data.db`.
+* 4. `<XDG data>/<projectKey resolved from cwd's package.json>/data.db`.
+*    Source 4 prefers `repository.url` (canonicalized to `host__path`),
+*    falling back to the normalized `name`. This matches the sidecar
+*    CLI's `_internal register-agent` resolver so the reporter and
+*    sidecar always write to the same `data.db`.
+*
+* The XDG data directory is namespaced via `AppDirs` (typically
+* `$XDG_DATA_HOME/vitest-agent`, defaulting to
+* `~/.local/share/vitest-agent`).
+*
+* The path is a function of identity, not filesystem layout. When no
+* `package.json` is reachable from `projectDir`, the cwd basename is used
+* as the final fallback so the function never throws on identity lookup.
+*
+* @param projectDir - Absolute path inside the user's workspace.
+* @param options - Optional programmatic overrides.
+* @public
+*/
+const resolveDataPath = (projectDir, options = {}) => Effect.gen(function* () {
+	const fs = yield* FileSystem.FileSystem;
+	if (options.cacheDir) {
+		yield* fs.makeDirectory(options.cacheDir, { recursive: true });
+		return join(options.cacheDir, DATABASE_FILENAME);
+	}
+	const loaded = yield* (yield* VitestAgentConfigFile).loadOrDefault(new VitestAgentConfig({}));
+	if (loaded.cacheDir) {
+		yield* fs.makeDirectory(loaded.cacheDir, { recursive: true });
+		return join(loaded.cacheDir, DATABASE_FILENAME);
+	}
+	const dataRoot = yield* (yield* AppDirs).ensureData;
+	const key = loaded.projectKey ? normalizeWorkspaceKey(loaded.projectKey) : resolveProjectKeyFromCwd(projectDir);
+	const dir = join(dataRoot, key);
+	yield* fs.makeDirectory(dir, { recursive: true });
+	return join(dir, DATABASE_FILENAME);
+});
+
+//#endregion
+export { DATABASE_FILENAME, resolveDataPath };

package/utils/resolve-project-key-from-cwd.js

@@ -0,0 +1,52 @@
+import { gitUrlToProjectKey, normalizeWorkspaceKey } from "@vitest-agent/sdk";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+//#region src/utils/resolve-project-key-from-cwd.ts
+const PACKAGE_JSON = "package.json";
+const findNearestPackageJson = (startDir) => {
+	let dir = startDir;
+	while (true) {
+		const candidate = join(dir, PACKAGE_JSON);
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+};
+const readRepositoryUrl = (parsed) => {
+	const repo = parsed.repository;
+	if (typeof repo === "string" && repo.trim().length > 0) return repo.trim();
+	if (repo !== null && typeof repo === "object" && "url" in repo && typeof repo.url === "string") {
+		const url = repo.url.trim();
+		return url.length > 0 ? url : null;
+	}
+	return null;
+};
+/**
+* Compute the project key for a workspace by reading `package.json`
+* fields directly. Returns the canonical `host__path` form when a git
+* remote URL is present, otherwise the normalized package name.
+*
+* Always returns a non-empty string — falls back to the cwd basename
+* (or `"anonymous-project"`) so callers don't have to handle the
+* empty case.
+* @public
+*/
+const resolveProjectKeyFromCwd = (cwd) => {
+	const pkgPath = findNearestPackageJson(cwd);
+	if (pkgPath !== null) try {
+		const parsed = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		const repoUrl = readRepositoryUrl(parsed);
+		if (repoUrl !== null) {
+			const key = gitUrlToProjectKey(repoUrl);
+			if (key !== null) return key;
+		}
+		if (typeof parsed.name === "string" && parsed.name.length > 0) return normalizeWorkspaceKey(parsed.name);
+	} catch {}
+	const basename = cwd.split("/").filter((segment) => segment.length > 0).pop() ?? "anonymous-project";
+	return normalizeWorkspaceKey(basename);
+};
+
+//#endregion
+export { resolveProjectKeyFromCwd };

package/utils/resolve-workspace-key.js

@@ -0,0 +1,41 @@
+import { normalizeWorkspaceKey } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+import { WorkspaceDiscovery, WorkspaceRootNotFoundError } from "@effected/workspaces";
+
+//#region src/utils/resolve-workspace-key.ts
+/**
+* Resolve the normalized workspace key for the workspace containing
+* `projectDir`.
+*
+* The key is the root `package.json`'s `name`, normalized via
+* `normalizeWorkspaceKey`. This becomes the directory segment under
+* `$XDG_DATA_HOME/vitest-agent/` where the SQLite database lives.
+*
+* Fails with `WorkspaceRootNotFoundError` when no root workspace is
+* discoverable. `WorkspacePackage.name` is enforced non-empty by
+* `@effected/workspaces`'s schema, so a successful root lookup always yields a
+* usable name.
+*
+* Discovery is anchored at `projectDir` per call via `listPackagesIn`, not at
+* the `WorkspaceDiscovery` layer's `cwd`: patterns, member manifests and names
+* are read from beneath `projectDir`'s own root, so one long-lived layer
+* answers correctly for a git worktree, a nested repository, or an unrelated
+* project. Fails with the library's `WorkspaceRootNotFoundError` when
+* `projectDir` sits in no workspace at all; results are memoized per resolved
+* root, so many directories in one workspace share a single discovery.
+*
+* @param projectDir - Absolute path inside the workspace. Typically the
+*   reporter's resolved `projectDir` (CLAUDE_PROJECT_DIR or process.cwd()).
+* @public
+*/
+const resolveWorkspaceKey = (projectDir) => Effect.gen(function* () {
+	const root = (yield* (yield* WorkspaceDiscovery).listPackagesIn(projectDir)).find((pkg) => pkg.isRootWorkspace);
+	if (!root) return yield* Effect.fail(new WorkspaceRootNotFoundError({
+		searchPath: projectDir,
+		markers: []
+	}));
+	return normalizeWorkspaceKey(root.name);
+});
+
+//#endregion
+export { resolveWorkspaceKey };

package/version.js

@@ -0,0 +1,6 @@
+//#region src/version.ts
+/** Build-time injected package version (see architecture.md D36). @public */
+const CURRENT_ENGINE_VERSION = "0.1.0";
+
+//#endregion
+export { CURRENT_ENGINE_VERSION };