@vitest-agent/plugin 2.2.1 → 2.2.2

package/README.md

@@ -9,7 +9,7 @@ Vitest plugin that turns your test suite into a live data source for LLM coding
 ## Features
 
 - **`AgentPlugin`** — drop into `vitest.config.ts`; auto-detects human, agent and CI executors and adapts console output accordingly
-- **Project discovery** — `AgentPlugin.discover()` scans workspace packages, returns `{ projects, tags }` ready for `test.projects` and `test.tags`; classification tags apply at collection time, so every test declaration form inherits them, including wrapper testers like `@effect/vitest`'s `it.effect`
+- **Project discovery** — `AgentPlugin.discover()` scans workspace packages, returns `{ projects, tags }` ready for `test.projects` and `test.tags`; classification tags apply at collection time, so every test declaration form inherits them, including wrapper testers like `@effect/vitest`'s `it.effect`; a package that looks test-shaped but ends up with no project warns on stderr instead of silently running nothing
 - **Coverage presets** — `COVERAGE_LEVELS` and `COVERAGE_LEVELS_PER_FILE` return dual-output `{ thresholds, coverageTargets }` objects; `COVERAGE_AUTOUPDATE` tolerance functions plug into Vitest's native `autoUpdate`
 - **Failure classification** — persists per-test errors, computes failure signatures, classifies tests as stable, new-failure, persistent, flaky or recovered across runs
 - **Custom reporters** — pass any `VitestAgentReporterFactory` as the `reporter` option; the default wires `DefaultVitestAgentReporter` from `@vitest-agent/reporter`

package/index.d.ts

@@ -351,6 +351,19 @@ declare namespace AgentPlugin {
    * Designed for use in Vitest `globalSetup` files to run build steps or
    * other preparatory scripts without polluting agent stdout.
    *
+   * Concurrent invocations of the same command from the same workspace
+   * (e.g. two `vitest` runs started in one checkout at once) serialize
+   * through a file-based advisory lock (issue #191): the first caller
+   * runs the command; a concurrent caller blocks until the lock frees,
+   * then skips its own run when the winner's build is still fresh
+   * (`DEFAULT_BUILT_RECENTLY_MS`) rather than repeating it.
+   *
+   * Serialization is best-effort by design: a waiter that is still
+   * blocked after `DEFAULT_LOCK_WAIT_TIMEOUT_MS` gives up and runs the
+   * command anyway, unserialized, rather than hanging the caller's test
+   * run forever. See `utils/run-script-lock.ts` for that escape valve
+   * and for the two-tier (pid probe, then age) stale-takeover rule.
+   *
    * On failure the captured stderr and stdout are written to their respective
    * streams before rethrowing, so the error is still visible to humans and
    * surfaced in CI logs.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/plugin",
-	"version": "2.2.1",
+	"version": "2.2.2",
 	"private": false,
 	"description": "Vitest plugin for the vitest-agent ecosystem: owns persistence, classification, baselines, trends, and dispatches rendering to a configurable reporter.",
 	"keywords": [
@@ -41,13 +41,13 @@
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-beta.107",
 		"@effect/sql-sqlite-node": "4.0.0-beta.107",
-		"@effected/workspaces": "^0.11.2",
-		"@vitest-agent/cli": "2.1.1",
-		"@vitest-agent/mcp": "2.1.4",
-		"@vitest-agent/reporter": "2.0.19",
-		"@vitest-agent/sdk": "2.2.1",
+		"@effected/workspaces": "^0.12.0",
+		"@vitest-agent/cli": "2.1.2",
+		"@vitest-agent/mcp": "2.2.0",
+		"@vitest-agent/reporter": "2.0.20",
+		"@vitest-agent/sdk": "2.3.0",
 		"effect": "4.0.0-beta.107",
-		"magic-string": "^1.1.0"
+		"magic-string": "^1.2.0"
 	},
 	"peerDependencies": {
 		"@vitest/coverage-istanbul": "^4.1.0",

package/plugin.js

@@ -7,6 +7,7 @@ import { DefaultDiscoverStrategy } from "./utils/discover-strategy.js";
 import { discoverProjects } from "./utils/discover-projects.js";
 import { injectTags } from "./utils/inject-tags.js";
 import { isBenignViteSourceMapWarning } from "./utils/is-benign-vite-source-map-warning.js";
+import { DEFAULT_BUILT_RECENTLY_MS, DEFAULT_LOCK_STALE_MS, DEFAULT_LOCK_WAIT_TIMEOUT_MS, acquireRunScriptLock, markRunScriptDone, parseLockTimingOverride, releaseRunScriptLock } from "./utils/run-script-lock.js";
 import { stripConsoleReporters } from "./utils/strip-console-reporters.js";
 import { execSync } from "node:child_process";
 import { AgentConsoleMode, CiConsoleMode, CoverageLevel, EnvironmentDetector, EnvironmentDetectorLive, HumanConsoleMode, SRC_DIR, TEST_DIR, formatFatalError, isTestFileName, resolveLogLevel } from "@vitest-agent/sdk";
@@ -37,7 +38,8 @@ function resolveConsoleMode(options, executor, _env) {
 		if (executor === "human" && Schema.is(HumanConsoleMode)(override)) return override;
 		if (executor === "agent" && Schema.is(AgentConsoleMode)(override)) return override;
 		if (executor !== "human" && executor !== "agent" && Schema.is(CiConsoleMode)(override)) return override;
-		process.stderr.write(`[vitest-agent:plugin] ignoring invalid VITEST_AGENT_CONSOLE="${override}" for ${executor} executor\n`);
+		const accepted = executor === "human" ? HumanConsoleMode.literals : executor === "agent" ? AgentConsoleMode.literals : CiConsoleMode.literals;
+		process.stderr.write(`[vitest-agent:plugin] ignoring invalid VITEST_AGENT_CONSOLE="${override}" for ${executor} executor; accepted for ${executor}: ${accepted.join(" | ")}\n`);
 	}
 	const console = options.console;
 	if (executor === "human") return console?.human ?? "passthrough";
@@ -98,7 +100,7 @@ const aggregatedReporterByVitest = /* @__PURE__ */ new WeakSet();
 *
 * @public
 */
-const CURRENT_PLUGIN_VERSION = "2.2.1";
+const CURRENT_PLUGIN_VERSION = "2.2.2";
 const TEST_FILE_DIR_RE = new RegExp(`/(?:${SRC_DIR}|${TEST_DIR})/`);
 const isTestFile = (id) => isTestFileName(id) && TEST_FILE_DIR_RE.test(id);
 /**
@@ -308,14 +310,37 @@ function makeDiscoverBuilder(options) {
 		});
 	}
 	_AgentPlugin.discover = discover;
+	/**
+	* Parses a `VITEST_AGENT_RUNSCRIPT_*` override env var, falling back to
+	* `fallback` for anything that is not a whole positive integer at or above
+	* `minimum`. Test-support: lets the concurrency e2e suite use short timeouts
+	* instead of the production-sized defaults — but a typo there (`"200ms"`,
+	* `"-1"`, `"0"`) must degrade to the default rather than to an
+	* instantly-stale lock or a busy-spinning waiter.
+	*/
+	function readRunScriptLockEnvOverride(name, fallback, minimum = 1) {
+		return parseLockTimingOverride(process.env[name], fallback, minimum);
+	}
 	function runScript(command) {
+		const lock = acquireRunScriptLock({
+			cwd: process.cwd(),
+			command,
+			staleMs: readRunScriptLockEnvOverride("VITEST_AGENT_RUNSCRIPT_LOCK_STALE_MS", DEFAULT_LOCK_STALE_MS),
+			waitTimeoutMs: readRunScriptLockEnvOverride("VITEST_AGENT_RUNSCRIPT_LOCK_WAIT_TIMEOUT_MS", DEFAULT_LOCK_WAIT_TIMEOUT_MS),
+			pollMs: readRunScriptLockEnvOverride("VITEST_AGENT_RUNSCRIPT_LOCK_POLL_MS", 200, 10),
+			builtRecentlyMs: readRunScriptLockEnvOverride("VITEST_AGENT_RUNSCRIPT_BUILT_RECENTLY_MS", DEFAULT_BUILT_RECENTLY_MS)
+		});
+		if (lock.recentlyBuilt) return;
 		try {
 			execSync(command, { stdio: "pipe" });
+			markRunScriptDone(lock);
 		} catch (error) {
 			const execError = error;
 			if (execError.stderr?.length) process.stderr.write(execError.stderr);
 			if (execError.stdout?.length) process.stdout.write(execError.stdout);
 			throw error;
+		} finally {
+			releaseRunScriptLock(lock);
 		}
 	}
 	_AgentPlugin.runScript = runScript;

package/utils/discover-projects.js

@@ -1,5 +1,6 @@
 import { toPosixPath } from "./to-posix-path.js";
 import { DefaultDiscoverStrategy } from "./discover-strategy.js";
+import { isTestShapedPackage } from "./is-test-shaped-package.js";
 import { NON_DISCOVERABLE_DIRS, SRC_DIR, TEST_DIR } from "@vitest-agent/sdk";
 import { isAbsolute, join, normalize, relative } from "node:path";
 import { readdir, stat } from "node:fs/promises";
@@ -8,6 +9,24 @@ import { nodeSyncOps } from "@effected/workspaces/node-sync";
 
 //#region src/utils/discover-projects.ts
 const DISCOVERY_LAST_SCAN_SYMBOL = Symbol.for("vitest-agent:discovery:last-scan-at");
+const warnedDeclinedPackagePaths = /* @__PURE__ */ new Set();
+async function warnIfDeclinedPackageIsTestShaped(pkg) {
+	const normPath = normalize(pkg.path);
+	if (warnedDeclinedPackagePaths.has(normPath)) return;
+	warnedDeclinedPackagePaths.add(normPath);
+	let testShaped;
+	try {
+		testShaped = await isTestShapedPackage(pkg.path);
+	} catch (error) {
+		warnedDeclinedPackagePaths.delete(normPath);
+		throw error;
+	}
+	if (!testShaped) {
+		warnedDeclinedPackagePaths.delete(normPath);
+		return;
+	}
+	process.stderr.write(`[vitest-agent] warning: package "${pkg.name}" has a ${TEST_DIR}/ directory or ${SRC_DIR}/ test files, but its tests were not wired into a Vitest project. Run \`npx vitest-agent agent check-test-path <path>\` to diagnose why.\n`);
+}
 function recordDiscoveryScanTimestamp() {
 	globalThis[DISCOVERY_LAST_SCAN_SYMBOL] = (/* @__PURE__ */ new Date()).toISOString();
 }
@@ -107,6 +126,7 @@ async function discoverProjects(options) {
 			workspaceRoot: root
 		});
 		if (config !== null) configs.push(config);
+		else await warnIfDeclinedPackageIsTestShaped(pkg);
 		workspaceNames.add(pkg.name);
 		workspacePaths.add(normalize(pkg.path));
 	}

package/utils/is-test-shaped-package.js

@@ -0,0 +1,40 @@
+import { findTestFiles } from "./find-test-files.js";
+import { SRC_DIR, TEST_DIR, TEST_FILE_GLOB_SUFFIX } from "@vitest-agent/sdk";
+import { join } from "node:path";
+import { stat } from "node:fs/promises";
+
+//#region src/utils/is-test-shaped-package.ts
+async function isDirectory(p) {
+	try {
+		return (await stat(p)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+/**
+* True when `pkgPath` looks like it was meant to hold tests: a `__test__/`
+* directory exists at the package root (regardless of what's inside it), or
+* `src/` contains at least one file matching the discoverable test-file
+* naming convention (`TEST_FILE_GLOB_SUFFIX`).
+*
+* Reuses `SRC_DIR` / `TEST_DIR` / `TEST_FILE_GLOB_SUFFIX` from
+* `@vitest-agent/sdk`'s `utils/test-location.ts` — the single source of
+* truth for the test-layout rule — and the existing `findTestFiles` walker,
+* rather than re-deriving the shape independently.
+*
+* A `__test__/` directory counts on existence alone, not on matching file
+* content: the failure mode this predicate exists to catch (issue #229) IS a
+* `__test__/` directory whose files don't match the naming convention (wrong
+* suffix, wrong extension, typo) — `DefaultDiscoverStrategy.buildProject`
+* already declined those packages by finding zero matching files, so
+* requiring a match here would make the predicate blind to exactly the case
+* it needs to catch.
+* @internal
+*/
+async function isTestShapedPackage(pkgPath) {
+	if (await isDirectory(join(pkgPath, TEST_DIR))) return true;
+	return (await findTestFiles(pkgPath, [`${SRC_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`])).length > 0;
+}
+
+//#endregion
+export { isTestShapedPackage };

package/utils/run-script-lock.js

@@ -0,0 +1,268 @@
+import { createHash, randomBytes } from "node:crypto";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+//#region src/utils/run-script-lock.ts
+/**
+* File-based advisory lock backing `AgentPlugin.runScript` (issue #191,
+* sub-item B). Two concurrent `vitest` invocations in one checkout used
+* to both run the `globalSetup` build and race — this lock serializes
+* them: the first process to acquire the lock runs the command and
+* marks a "done" timestamp on success; a concurrent process polls,
+* and once the marker is fresh enough (`builtRecentlyMs`) it trusts
+* the winner's build and skips its own.
+*
+* A stale-lock takeover exists because a process that crashed or was
+* killed mid-build leaves the lock file behind forever otherwise —
+* every future `vitest` invocation would hang. Takeover is a two-tier
+* rule, never age alone:
+*
+* 1. The lock file records the owner's pid. Once the lock is older
+*    than `staleMs`, that pid is probed with `process.kill(pid, 0)`.
+*    A live owner (probe succeeds, or fails `EPERM` — the process
+*    exists but belongs to another user) is NEVER taken over, no
+*    matter how old the lock is: a slow-but-live build must not have
+*    its lock stolen and the command double-run.
+* 2. Only a dead owner (`ESRCH`), or a lock file whose owner record is
+*    missing/corrupt (in which case age is all we have to go on),
+*    is taken over.
+*
+* Release is ownership-gated for the same reason: `acquireRunScriptLock`
+* stamps a random per-acquisition nonce into the lock file, and
+* `releaseRunScriptLock` deletes the file only when the nonce on disk is
+* still its own. Without that, an original owner that lost its lock to a
+* takeover would delete the *takeover* owner's lock in its `finally`,
+* letting a third process in while the second is still building.
+*
+* A generous `waitTimeoutMs` safety valve exists so a genuinely slow
+* (but still live) build doesn't hang the waiter forever either: past
+* that timeout the waiter gives up, `acquireRunScriptLock` returns
+* `{ acquired: false, recentlyBuilt: false }`, and the caller
+* (`AgentPlugin.runScript`) goes ahead and runs its own command
+* unserialized. That reproduces the original race for that one pair of
+* processes rather than blocking indefinitely — a deliberate,
+* documented escape valve, not an oversight.
+*
+* @packageDocumentation
+*/
+/**
+* A build whose owning process is *gone* and whose lock is older than
+* this is presumed abandoned (crashed process, killed job) and taken
+* over. Age alone never triggers a takeover — the recorded pid is
+* probed first, and a live owner keeps its lock past this age (see the
+* module doc comment). One minute comfortably covers the `globalSetup`
+* build steps this lock is built for; the pid probe is what protects
+* the longer ones.
+*/
+const DEFAULT_LOCK_STALE_MS = 6e4;
+/** How long a waiter sleeps between polls of an active lock. */
+const DEFAULT_LOCK_POLL_MS = 200;
+/** How long a waiter blocks before giving up and running its own build independently. */
+const DEFAULT_LOCK_WAIT_TIMEOUT_MS = 6e5;
+/** A done-marker fresher than this is trusted without re-running the command. */
+const DEFAULT_BUILT_RECENTLY_MS = 3e4;
+/**
+* Strictly parses a millisecond timing supplied through one of the
+* `VITEST_AGENT_RUNSCRIPT_*` env overrides, falling back to `fallback`
+* for anything that is not a whole positive integer at or above
+* `minimum`.
+*
+* `Number.parseInt` is deliberately not used on its own: it happily
+* accepts `"200ms"` (→ 200) and `"-1"` (→ a negative stale window,
+* which makes every lock instantly stale) and `"0"` for a poll interval
+* (a tight spin loop). An unusable override falls back to the default
+* rather than silently degrading the lock.
+*
+* @public
+*/
+function parseLockTimingOverride(raw, fallback, minimum = 1) {
+	if (raw === void 0) return fallback;
+	const trimmed = raw.trim();
+	if (!/^\d+$/.test(trimmed)) return fallback;
+	const parsed = Number.parseInt(trimmed, 10);
+	if (!Number.isSafeInteger(parsed) || parsed < minimum) return fallback;
+	return parsed;
+}
+/**
+* Resolves the directory `runScript` locks and done-markers live in:
+* `XDG_DATA_HOME` when set (matching `@vitest-agent/sdk`'s `data.db`
+* resolution convention), else the same `~/.local/share` fallback that
+* convention documents.
+*
+* @public
+*/
+function resolveRunScriptLockDir(env = process.env, home = homedir()) {
+	const xdg = env.XDG_DATA_HOME;
+	const base = xdg !== void 0 && xdg.length > 0 ? xdg : join(home, ".local", "share");
+	return join(base, "vitest-agent", "runscript-locks");
+}
+/**
+* Deterministic, filesystem-safe key for one (workspace, command) pair
+* so different `globalSetup` commands in the same checkout don't share
+* a lock, while repeat invocations of the *same* command in the *same*
+* workspace do.
+*/
+function computeLockKey(cwd, command) {
+	return createHash("sha256").update(`${cwd}\n${command}`).digest("hex").slice(0, 16);
+}
+/** Reads the owner record from a lock file. Returns `null` when the file is missing, unreadable, or not a well-formed owner record (e.g. observed mid-write by its creator). */
+function readLockOwner(lockPath) {
+	let raw;
+	try {
+		raw = readFileSync(lockPath, "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed?.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid <= 0) return null;
+		if (typeof parsed.nonce !== "string" || parsed.nonce.length === 0) return null;
+		return {
+			pid: parsed.pid,
+			nonce: parsed.nonce,
+			startedAt: String(parsed.startedAt ?? "")
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Signal-0 liveness probe. `EPERM` means the process exists but is
+* owned by another user — still alive, and emphatically not ours to
+* take over. Anything else (`ESRCH`) means it is gone.
+*/
+function isProcessAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (err) {
+		return err.code === "EPERM";
+	}
+}
+function defaultSleep(ms) {
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function isRecentlyBuilt(doneMarkerPath, builtRecentlyMs) {
+	try {
+		return Date.now() - statSync(doneMarkerPath).mtimeMs < builtRecentlyMs;
+	} catch {
+		return false;
+	}
+}
+function lockAgeMs(lockPath) {
+	try {
+		return Date.now() - statSync(lockPath).mtimeMs;
+	} catch {
+		return null;
+	}
+}
+/**
+* Acquires (or observes) the advisory lock for one (cwd, command) pair.
+* Blocks the calling thread (via `sleep`) while another process holds
+* a non-stale lock, up to `waitTimeoutMs`.
+*
+* @public
+*/
+function acquireRunScriptLock(options) {
+	const { cwd, command, lockDir = resolveRunScriptLockDir(), staleMs = DEFAULT_LOCK_STALE_MS, waitTimeoutMs = DEFAULT_LOCK_WAIT_TIMEOUT_MS, pollMs = 200, builtRecentlyMs = DEFAULT_BUILT_RECENTLY_MS, sleep = defaultSleep } = options;
+	mkdirSync(lockDir, { recursive: true });
+	const key = computeLockKey(cwd, command);
+	const lockPath = join(lockDir, `${key}.lock`);
+	const doneMarkerPath = join(lockDir, `${key}.done`);
+	const deadline = Date.now() + waitTimeoutMs;
+	for (;;) {
+		if (isRecentlyBuilt(doneMarkerPath, builtRecentlyMs)) return {
+			lockPath,
+			doneMarkerPath,
+			acquired: false,
+			recentlyBuilt: true,
+			ownerNonce: null
+		};
+		let fd = null;
+		try {
+			fd = openSync(lockPath, "wx");
+		} catch (err) {
+			if (err.code !== "EEXIST") throw err;
+		}
+		if (fd !== null) {
+			const ownerNonce = randomBytes(12).toString("hex");
+			const record = {
+				pid: process.pid,
+				nonce: ownerNonce,
+				startedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			try {
+				writeSync(fd, JSON.stringify(record));
+			} catch (err) {
+				try {
+					rmSync(lockPath, { force: true });
+				} catch {}
+				throw err;
+			} finally {
+				try {
+					closeSync(fd);
+				} catch {}
+			}
+			return {
+				lockPath,
+				doneMarkerPath,
+				acquired: true,
+				recentlyBuilt: false,
+				ownerNonce
+			};
+		}
+		const age = lockAgeMs(lockPath);
+		if (age !== null && age > staleMs) {
+			const owner = readLockOwner(lockPath);
+			if (owner === null || !isProcessAlive(owner.pid)) {
+				try {
+					rmSync(lockPath, { force: true });
+				} catch {}
+				continue;
+			}
+		}
+		if (Date.now() > deadline) return {
+			lockPath,
+			doneMarkerPath,
+			acquired: false,
+			recentlyBuilt: false,
+			ownerNonce: null
+		};
+		sleep(pollMs);
+	}
+}
+/**
+* Releases a lock this process acquired. No-op when `lock.acquired` is
+* `false` (this process never owned it), and — critically — also a
+* no-op when the lock file on disk no longer carries this
+* acquisition's nonce: that means the lock was taken over and now
+* belongs to somebody else's in-flight build. Deleting it there would
+* admit a third process while the second is still running the command.
+*
+* @public
+*/
+function releaseRunScriptLock(lock) {
+	if (!lock.acquired || lock.ownerNonce === null) return;
+	const owner = readLockOwner(lock.lockPath);
+	if (owner === null || owner.nonce !== lock.ownerNonce) return;
+	try {
+		rmSync(lock.lockPath, { force: true });
+	} catch {}
+}
+/**
+* Marks a successful build, so a waiter's next `isRecentlyBuilt` check
+* can skip re-running the command. Best-effort: a write failure just
+* means the next process won't short-circuit, not a correctness
+* problem.
+*
+* @public
+*/
+function markRunScriptDone(lock) {
+	try {
+		writeFileSync(lock.doneMarkerPath, String(Date.now()));
+	} catch {}
+}
+
+//#endregion
+export { DEFAULT_BUILT_RECENTLY_MS, DEFAULT_LOCK_STALE_MS, DEFAULT_LOCK_WAIT_TIMEOUT_MS, acquireRunScriptLock, markRunScriptDone, parseLockTimingOverride, releaseRunScriptLock, resolveRunScriptLockDir };