@orkestrel/probe 0.0.11 → 0.0.12

package/dist/src/server/index.js

@@ -4,7 +4,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { attempt, compileGuard, compileSchema, isArray, isRecord, schemaToParameters } from "@orkestrel/contract";
-import { CLAIM_SHAPE, LINT_DEADLINE, PROBE_DEADLINE, PROBE_KEYS, ProbeError, computeReceipt, createDestroyedError, formatCheck, formatReceipt, formatSpecification, formatVerdict, isClaim, isDraft, isProbeError, isVerdict, matchesSpecification } from "../core/index.js";
+import { CLAIM_SHAPE, LINT_DEADLINE, PROBE_DEADLINE, PROBE_KEYS, PROBE_SPECIFICATIONS, ProbeError, RUNTIME_PLUGIN, computeReceipt, createDestroyedError, formatCheck, formatReceipt, formatSpecification, formatVerdict, isClaim, isDraft, isProbeError, isVerdict, matchesSpecification } from "../core/index.js";
 import { Emitter } from "@orkestrel/emitter";
 import { createQueue } from "@orkestrel/queue";
 import { createTimeout } from "@orkestrel/timeout";
@@ -37,6 +37,64 @@ function normalizePath(path) {
 	return path.replaceAll("\\", "/");
 }
 /**
+* Reads the condition code a native fault carries.
+*
+* @remarks
+* A caller catches `unknown`, so every reading of a caught value's own property calls into code
+* this package does not own: a proxy whose `has` trap throws and a value whose `code` getter throws
+* both arrive here. The read is guarded, so a fault that refuses inspection reports no code rather
+* than raising a second fault over the first. A `code` the host reports as anything other than a
+* string is no code this package compares against, so it reports none either.
+*
+* One reading serves every site that classifies a native fault, so a host condition is admitted the
+* same way wherever it is read.
+*
+* @param error - The caught value to read
+* @returns The fault's `code` when it carries a string one; `undefined` otherwise
+*
+* @example
+* ```ts
+* readFaultCode(Object.assign(new Error('no such file'), { code: 'ENOENT' })) // 'ENOENT'
+* readFaultCode(new Error('the runtime stage was destroyed')) // undefined
+* readFaultCode('ENOENT') // undefined
+* ```
+*/
+function readFaultCode(error) {
+	if (typeof error !== "object" || error === null) return void 0;
+	const fault = error;
+	const reading = attempt(() => "code" in fault ? fault.code : void 0);
+	if (!reading.success) return void 0;
+	return typeof reading.value === "string" ? reading.value : void 0;
+}
+/**
+* Reports whether one path resolves outside the root it is read against.
+*
+* @remarks
+* Containment decides which paths a claim may reach and which absolute paths a digest may rewrite,
+* so one reading serves every site that asks the question. A target resolving to the root itself is
+* contained, and each caller decides on its own what that empty relative path means for it.
+*
+* The test reads the relative path rather than a string prefix of the root, so a sibling directory
+* whose name begins with the root's own text is outside rather than beneath it. An absolute
+* relative path is the answer a host returns for two paths on different volumes, which no root
+* contains.
+*
+* @param root - The root the target is read against
+* @param target - The path to test, absolute or root-relative
+* @returns True if the target resolves outside the root; false otherwise
+*
+* @example
+* ```ts
+* escapesRoot('/srv/checkout', 'src/core/greeting.ts') // false
+* escapesRoot('/srv/checkout', '../secrets.env') // true
+* escapesRoot('/srv/checkout', '/srv/checkout-backup/secrets.env') // true
+* ```
+*/
+function escapesRoot(root, target) {
+	const path = relative(resolve(root), resolve(root, target));
+	return path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);
+}
+/**
 * Resolves a path inside a target workspace and rejects traversal outside it.
 *
 * @remarks
@@ -64,7 +122,7 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 	const root = resolve(workspace);
 	const file = resolve(root, target);
 	const path = relative(root, file);
-	if (path === "" || path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path)) throw new ProbeError(`Path escapes the workspace: ${target}`, {
+	if (path === "" || escapesRoot(root, file)) throw new ProbeError(`Path escapes the workspace: ${target}`, {
 		origin: "claimant",
 		code: "refused",
 		context: { path: target }
@@ -77,18 +135,16 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 			descendant = resolve(descendant, segment);
 			const outcome = attempt(() => lstatSync(descendant));
 			if (!outcome.success) {
-				const error = outcome.error;
-				if (typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) break;
-				throw error;
+				const code = readFaultCode(outcome.error);
+				if (code === "ENOENT" || code === "ENOTDIR") break;
+				throw outcome.error;
 			}
 			if (outcome.value.isSymbolicLink()) throw new ProbeError(`Path crosses a symbolic link: ${target}`, {
 				origin: "workspace",
 				code: "refused",
 				context: { path: target }
 			});
-			const resolved = realpathSync(descendant);
-			const remainder = relative(canonical, resolved);
-			if (remainder === ".." || remainder.startsWith(`..${sep}`) || isAbsolute(remainder)) throw new ProbeError(`Path escapes the workspace: ${target}`, {
+			if (escapesRoot(canonical, realpathSync(descendant))) throw new ProbeError(`Path escapes the workspace: ${target}`, {
 				origin: "claimant",
 				code: "refused",
 				context: { path: target }
@@ -96,7 +152,8 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 		}
 	} catch (error) {
 		if (error instanceof ProbeError) throw error;
-		const claimant = typeof error === "object" && error !== null && "code" in error && (error.code === "ENAMETOOLONG" || error.code === "ERR_INVALID_ARG_VALUE");
+		const code = readFaultCode(error);
+		const claimant = code === "ENAMETOOLONG" || code === "ERR_INVALID_ARG_VALUE";
 		throw new ProbeError(`The workspace path cannot be inspected: ${target}`, {
 			origin: claimant ? "claimant" : "workspace",
 			code: claimant ? "refused" : "malformed",
@@ -176,7 +233,7 @@ function overwriteFile(file, text) {
 *
 * @param file - The path whose creation failed
 * @param error - The fault the failed operation raised
-* @returns True when the fault means the host refuses this name; false otherwise
+* @returns True if the fault means the host refuses this name; false otherwise
 *
 * @example
 * ```ts
@@ -189,11 +246,7 @@ function overwriteFile(file, text) {
 * ```
 */
 function isRefusedName(file, error) {
-	if (typeof error !== "object" || error === null) return false;
-	const fault = error;
-	const reading = attempt(() => "code" in fault ? fault.code : void 0);
-	if (!reading.success) return false;
-	const code = reading.value;
+	const code = readFaultCode(error);
 	if (code === "ENAMETOOLONG") return true;
 	if (code === "ERR_INVALID_ARG_VALUE") return file.includes("\0");
 	if (code !== "ENOENT") return false;
@@ -288,7 +341,7 @@ function resolveWorkspaceModule(workspace, specifier) {
 	const outcome = attempt(() => createRequire(resolve(workspace, "package.json")).resolve(specifier));
 	if (outcome.success) return outcome.value;
 	const error = outcome.error;
-	const missing = typeof error === "object" && error !== null && "code" in error && error.code === "MODULE_NOT_FOUND";
+	const missing = readFaultCode(error) === "MODULE_NOT_FOUND";
 	throw new ProbeError(`The workspace cannot resolve ${specifier}`, {
 		origin: "workspace",
 		code: missing ? "missing" : "malformed",
@@ -303,7 +356,7 @@ function loadWorkspaceModule(workspace, specifier) {
 	});
 	if (outcome.success) return outcome.value;
 	const error = outcome.error;
-	const missing = typeof error === "object" && error !== null && "code" in error && error.code === "MODULE_NOT_FOUND";
+	const missing = readFaultCode(error) === "MODULE_NOT_FOUND";
 	throw new ProbeError(`The workspace cannot load ${specifier}`, {
 		origin: "workspace",
 		code: missing ? "missing" : "malformed",
@@ -341,7 +394,8 @@ function readWorkspaceManifest(workspace, name) {
 	const reading = attempt(() => readFileSync(path, "utf8"));
 	if (!reading.success) {
 		const error = reading.error;
-		const missing = typeof error === "object" && error !== null && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+		const code = readFaultCode(error);
+		const missing = code === "ENOENT" || code === "ENOTDIR";
 		throw new ProbeError(`${name} does not publish a readable manifest`, {
 			origin: "workspace",
 			code: missing ? "missing" : "malformed",
@@ -485,23 +539,24 @@ function inferDocumentLanguage(path) {
 	return "typescript";
 }
 /**
-* Creates a fresh sibling identity while preserving a test's resolution directory.
+* Builds the fresh sibling path a revision's file is written at, preserving the test's resolution
+* directory.
 *
 * @param workspace - The target workspace root
 * @param path - The workspace-relative test path
 * @param revision - The fresh revision identity
-* @returns An absolute sibling file path
+* @returns The absolute sibling path
 *
 * @example
 * ```ts
 * relativeWorkspaceFile(
 * 	'/srv/checkout',
-* 	createRevisionFile('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
+* 	buildRevisionPath('/srv/checkout', 'tmp/probe/greeting.test.ts', '4821-9f0c'),
 * )
 * // 'tmp/probe/greeting.test.probe-4821-9f0c.ts'
 * ```
 */
-function createRevisionFile(workspace, path, revision) {
+function buildRevisionPath(workspace, path, revision) {
 	const file = resolveWorkspaceFile(workspace, path);
 	const extension = extname(file);
 	return `${extension === "" ? file : file.slice(0, -extension.length)}.probe-${revision}${extension}`;
@@ -510,7 +565,7 @@ function createRevisionFile(workspace, path, revision) {
 * Reports whether a path is a workspace module Vitest can cache.
 *
 * @param path - The candidate file path
-* @returns True for script, TypeScript, Vue, and JSON modules; false otherwise
+* @returns True if the path is a script, TypeScript, Vue, or JSON module; false otherwise
 *
 * @example
 * ```ts
@@ -637,7 +692,7 @@ function normalizeValue(workspace, value) {
 		if (!isAbsolute(value)) return value;
 		const path = relative(root, resolve(value));
 		if (path === "") return ".";
-		if (path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path)) return value;
+		if (escapesRoot(root, value)) return value;
 		return normalizePath(path);
 	}
 	if (isArray(value)) return value.map((entry) => normalizeValue(workspace, entry));
@@ -823,11 +878,11 @@ var Overlay = class {
 };
 //#endregion
 //#region package.json
-var version = "0.0.11";
+var version = "0.0.12";
 var peerDependencies = {
-	"oxlint": "^1.77.0",
-	"typescript": "^6.0.0",
-	"vitest": "^4.1.0"
+	"oxlint": "^1.80.0",
+	"typescript": "^6.0.3",
+	"vitest": "^4.1.11"
 };
 //#endregion
 //#region src/server/stages/LintStage.ts
@@ -877,7 +932,6 @@ var LintStage = class {
 	#closing;
 	#progress = 0;
 	#revision = 0;
-	#destroyed = false;
 	/**
 	* Starts warming the target workspace's Oxlint language server.
 	*
@@ -899,12 +953,11 @@ var LintStage = class {
 	}
 	destroy() {
 		if (this.#closing !== void 0) return this.#closing;
-		this.#destroyed = true;
 		this.#closing = guardStage(this.stage, this.#destroy());
 		return this.#closing;
 	}
 	async #inspect(subject, options) {
-		if (this.#destroyed) throw createDestroyedError("lint stage");
+		if (this.#closing !== void 0) throw createDestroyedError("lint stage");
 		if (options === void 0) throw new ProbeError("The lint stage inspects only under a bound its caller supplies", {
 			origin: "claimant",
 			code: "refused",
@@ -912,7 +965,7 @@ var LintStage = class {
 		});
 		const started = performance.now();
 		const client = await this.#warmed();
-		if (this.#destroyed) throw createDestroyedError("lint stage");
+		if (this.#closing !== void 0) throw createDestroyedError("lint stage");
 		const issues = [];
 		for (const draft of [...subject.files, subject.test]) issues.push(...await this.#document(client, draft, options.signal));
 		return {
@@ -997,7 +1050,7 @@ var LintStage = class {
 		});
 	}
 	#translate(error, path) {
-		if (this.#destroyed) return createDestroyedError("lint stage");
+		if (this.#closing !== void 0) return createDestroyedError("lint stage");
 		const ending = this.#ending;
 		if (ending !== void 0) return this.#fault(`The Oxlint language server exited with ${ending}`, error, path);
 		if (error instanceof Error) return error;
@@ -1052,6 +1105,11 @@ var LintStage = class {
 * The runtime overlay leaves bare specifier resolution to Vite: it replaces a bare import only
 * after Vite resolves that import to a covered file. The type stage overlays the declared test
 * path, while this stage executes a generated sibling and overlays only the candidate files.
+* This stage mints its overlay with the default exact-match sensitivity, because it declares no
+* file-name case sensitivity to Vite. A covered path whose spelling an importer wrote differs from
+* the recorded candidate path is therefore served by whatever answers first, and `#misses` reports
+* it as `The workspace configuration served this module before the runtime overlay` with origin
+* `workspace` rather than leaving it answered silently.
 *
 * Vite retains one unresolved URL for every specification path, so the stage replaces its whole
 * Vitest service after 64 specifications rather than deleting from each map that service owns. Any
@@ -1100,7 +1158,6 @@ var RuntimeStage = class {
 	#specifications = 0;
 	#closing;
 	#progress = 0;
-	#destroyed = false;
 	/**
 	* Starts warming the target workspace's Vitest service.
 	*
@@ -1122,16 +1179,15 @@ var RuntimeStage = class {
 	}
 	destroy() {
 		if (this.#closing !== void 0) return this.#closing;
-		this.#destroyed = true;
 		this.#closing = guardStage(this.stage, this.#destroy());
 		return this.#closing;
 	}
 	async #inspect(subject) {
-		if (this.#destroyed) throw createDestroyedError("runtime stage");
+		if (this.#closing !== void 0) throw createDestroyedError("runtime stage");
 		const started = performance.now();
 		const exitCode = process.exitCode;
 		const vitest = await this.#runner();
-		if (this.#destroyed) throw createDestroyedError("runtime stage");
+		if (this.#closing !== void 0) throw createDestroyedError("runtime stage");
 		const project = this.#project(vitest, subject.test.path);
 		if ("message" in project) return {
 			stage: this.stage,
@@ -1273,7 +1329,7 @@ var RuntimeStage = class {
 		return {
 			...config,
 			plugins: [...config.plugins ?? [], {
-				name: "orkestrel-runtime-overlay",
+				name: RUNTIME_PLUGIN,
 				enforce: "pre",
 				resolveId: this.#resolve.bind(this),
 				load: this.#load.bind(this)
@@ -1315,7 +1371,7 @@ var RuntimeStage = class {
 		let generated;
 		const outcome = attempt(() => {
 			const revision = `${process.pid}-${randomUUID()}`;
-			const file = createRevisionFile(this.#workspace, test.path, revision);
+			const file = buildRevisionPath(this.#workspace, test.path, revision);
 			generated = file;
 			const target = relative(this.#workspace, file);
 			resolveWorkspaceFile(this.#workspace, target, true);
@@ -1373,7 +1429,7 @@ var RuntimeStage = class {
 				path
 			}
 		});
-		if (!project.vite.config.plugins.some((plugin) => plugin.name === "orkestrel-runtime-overlay")) return {
+		if (!project.vite.config.plugins.some((plugin) => plugin.name === RUNTIME_PLUGIN)) return {
 			origin: "workspace",
 			path,
 			message: `The runtime stage cannot instrument the string-declared Vitest project ${name} because its configuration carries no runtime overlay plugin`
@@ -1462,14 +1518,14 @@ var RuntimeStage = class {
 	}
 	#runner() {
 		const current = this.#vitest;
-		if (current !== void 0 && this.#specifications < 64) return current;
+		if (current !== void 0 && this.#specifications < PROBE_SPECIFICATIONS) return current;
 		if (current !== void 0) return this.#store(this.#replace(current));
 		const runner = loadWorkspaceModule(this.#workspace, "vitest/node");
-		return this.#store(this.#specifications < 64 ? this.#warm(runner.createVitest) : this.#replace(void 0, runner.createVitest));
+		return this.#store(this.#specifications < PROBE_SPECIFICATIONS ? this.#warm(runner.createVitest) : this.#replace(void 0, runner.createVitest));
 	}
 	async #replace(current, create) {
 		if (current !== void 0) await (await current).close();
-		if (this.#destroyed) throw createDestroyedError("runtime stage");
+		if (this.#closing !== void 0) throw createDestroyedError("runtime stage");
 		const runner = create ?? loadWorkspaceModule(this.#workspace, "vitest/node").createVitest;
 		const replacement = await this.#warm(runner);
 		this.#specifications = 0;
@@ -1547,7 +1603,7 @@ var RuntimeStage = class {
 			process.kill(id, 0);
 			return true;
 		} catch (error) {
-			return error instanceof Error && "code" in error && error.code === "EPERM";
+			return readFaultCode(error) === "EPERM";
 		}
 	}
 	*#walk() {
@@ -1720,7 +1776,6 @@ var TypeStage = class {
 	#recycled;
 	#closing;
 	#progress = 0;
-	#destroyed = false;
 	/**
 	* Starts warming the target workspace's TypeScript service.
 	*
@@ -1774,15 +1829,14 @@ var TypeStage = class {
 	}
 	destroy() {
 		if (this.#closing !== void 0) return this.#closing;
-		this.#destroyed = true;
 		this.#closing = guardStage(this.stage, this.#destroy());
 		return this.#closing;
 	}
 	async #inspect(subject, project) {
-		if (this.#destroyed) throw createDestroyedError("type stage");
+		if (this.#closing !== void 0) throw createDestroyedError("type stage");
 		const started = performance.now();
 		const typescript = await this.#typescript;
-		if (this.#destroyed) throw createDestroyedError("type stage");
+		if (this.#closing !== void 0) throw createDestroyedError("type stage");
 		const selections = subject.files.map((draft) => ({
 			draft,
 			path: resolveWorkspaceFile(this.#workspace, draft.path)
@@ -1826,9 +1880,9 @@ var TypeStage = class {
 		}
 	}
 	async #resolve(project) {
-		if (this.#destroyed) throw createDestroyedError("type stage");
+		if (this.#closing !== void 0) throw createDestroyedError("type stage");
 		const typescript = await this.#typescript;
-		if (this.#destroyed) throw createDestroyedError("type stage");
+		if (this.#closing !== void 0) throw createDestroyedError("type stage");
 		const resolved = resolveWorkspaceFile(this.#workspace, project);
 		this.#progress += 1;
 		this.#service(typescript, project);
@@ -1871,7 +1925,7 @@ var TypeStage = class {
 	}
 	async #unblock() {
 		await setTimeout(0);
-		if (this.#destroyed) throw createDestroyedError("type stage");
+		if (this.#closing !== void 0) throw createDestroyedError("type stage");
 	}
 	#record(draft, overlay) {
 		overlay.set(resolveWorkspaceFile(this.#workspace, draft.path), draft.text);
@@ -2059,7 +2113,6 @@ var Probe = class {
 	#typeTail = Promise.resolve();
 	#arming;
 	#closing;
-	#destroyed = false;
 	/**
 	* Resolves the target toolchain and starts warming the resident stages.
 	*
@@ -2109,7 +2162,7 @@ var Probe = class {
 			this.#support();
 			this.#admit(claim);
 			await this.#ready();
-			if (this.#destroyed) throw createDestroyedError("probe");
+			if (this.#closing !== void 0) throw createDestroyedError("probe");
 			const started = performance.now();
 			const id = randomUUID();
 			const project = await this.#resolve(claim);
@@ -2143,7 +2196,6 @@ var Probe = class {
 	}
 	destroy() {
 		if (this.#closing !== void 0) return this.#closing;
-		this.#destroyed = true;
 		this.#closing = this.#destroy();
 		return this.#closing;
 	}
@@ -2153,7 +2205,7 @@ var Probe = class {
 			await attempt;
 			return;
 		} catch (error) {
-			if (this.#destroyed) throw error;
+			if (this.#closing !== void 0) throw error;
 		}
 		if (this.#arming === attempt) {
 			this.#arming = this.#arm();
@@ -2205,8 +2257,8 @@ var Probe = class {
 	}
 	async #boot(created) {
 		const revision = `${process.pid}-${randomUUID()}`;
-		const typeDependency = createRevisionFile(this.#workspace, "tmp/probe/arm-type.ts", revision);
-		const runtimeDependency = createRevisionFile(this.#workspace, "tmp/probe/arm-runtime.ts", revision);
+		const typeDependency = buildRevisionPath(this.#workspace, "tmp/probe/arm-type.ts", revision);
+		const runtimeDependency = buildRevisionPath(this.#workspace, "tmp/probe/arm-runtime.ts", revision);
 		const typeModule = basename(typeDependency, ".ts");
 		const runtimeModule = basename(runtimeDependency, ".ts");
 		const typeTest = {
@@ -2347,7 +2399,7 @@ var Probe = class {
 		}
 	}
 	async #recycle(stage) {
-		if (this.#destroyed) return false;
+		if (this.#closing !== void 0) return false;
 		const timeout = createTimeout({ ms: this.#deadline });
 		timeout.start();
 		try {
@@ -2355,7 +2407,7 @@ var Probe = class {
 		} catch {} finally {
 			timeout.clear();
 		}
-		if (this.#destroyed) return false;
+		if (this.#closing !== void 0) return false;
 		if (stage === this.#type) {
 			this.#type = new TypeStage(this.#workspace);
 			return true;
@@ -2413,13 +2465,17 @@ var Probe = class {
 	}
 	async #destroy() {
 		try {
-			await this.#arming;
-		} catch {}
-		await Promise.all([
-			this.#destroyStage(this.#type),
-			this.#destroyStage(this.#lint),
-			this.#destroyStage(this.#runtime)
-		]);
+			try {
+				await this.#arming;
+			} catch {}
+			await Promise.all([
+				this.#destroyStage(this.#type),
+				this.#destroyStage(this.#lint),
+				this.#destroyStage(this.#runtime)
+			]);
+		} finally {
+			this.#emitter.destroy();
+		}
 	}
 	async #destroyStage(stage) {
 		try {
@@ -2636,6 +2692,6 @@ var ProbeServer = class {
 	}
 };
 //#endregion
-export { LintStage, Overlay, Probe, ProbeServer, RuntimeStage, TypeStage, captureListeners, computeDigest, createRevisionFile, describeUnknown, findRefusedPaths, guardStage, inferDocumentLanguage, inferTestProject, inferTypeProject, isRefusedName, loadWorkspaceModule, matchesWorkspaceModule, normalizePath, normalizeValue, overwriteFile, readWorkspaceManifest, relativeWorkspaceFile, relativeWorkspaceMessage, releaseListeners, resolveWorkspaceBinary, resolveWorkspaceFile, resolveWorkspaceModule };
+export { LintStage, Overlay, Probe, ProbeServer, RuntimeStage, TypeStage, buildRevisionPath, captureListeners, computeDigest, describeUnknown, escapesRoot, findRefusedPaths, guardStage, inferDocumentLanguage, inferTestProject, inferTypeProject, isRefusedName, loadWorkspaceModule, matchesWorkspaceModule, normalizePath, normalizeValue, overwriteFile, readFaultCode, readWorkspaceManifest, relativeWorkspaceFile, relativeWorkspaceMessage, releaseListeners, resolveWorkspaceBinary, resolveWorkspaceFile, resolveWorkspaceModule };
 
 //# sourceMappingURL=index.js.map