@orkestrel/probe 0.0.11 → 0.0.12

package/dist/src/server/index.cjs

@@ -38,6 +38,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 = (0, _orkestrel_contract.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 = (0, node_path.relative)((0, node_path.resolve)(root), (0, node_path.resolve)(root, target));
+	return path === ".." || path.startsWith(`..${node_path.sep}`) || (0, node_path.isAbsolute)(path);
+}
+/**
 * Resolves a path inside a target workspace and rejects traversal outside it.
 *
 * @remarks
@@ -65,7 +123,7 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 	const root = (0, node_path.resolve)(workspace);
 	const file = (0, node_path.resolve)(root, target);
 	const path = (0, node_path.relative)(root, file);
-	if (path === "" || path === ".." || path.startsWith(`..${node_path.sep}`) || (0, node_path.isAbsolute)(path)) throw new _src_core.ProbeError(`Path escapes the workspace: ${target}`, {
+	if (path === "" || escapesRoot(root, file)) throw new _src_core.ProbeError(`Path escapes the workspace: ${target}`, {
 		origin: "claimant",
 		code: "refused",
 		context: { path: target }
@@ -78,18 +136,16 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 			descendant = (0, node_path.resolve)(descendant, segment);
 			const outcome = (0, _orkestrel_contract.attempt)(() => (0, node_fs.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 _src_core.ProbeError(`Path crosses a symbolic link: ${target}`, {
 				origin: "workspace",
 				code: "refused",
 				context: { path: target }
 			});
-			const resolved = (0, node_fs.realpathSync)(descendant);
-			const remainder = (0, node_path.relative)(canonical, resolved);
-			if (remainder === ".." || remainder.startsWith(`..${node_path.sep}`) || (0, node_path.isAbsolute)(remainder)) throw new _src_core.ProbeError(`Path escapes the workspace: ${target}`, {
+			if (escapesRoot(canonical, (0, node_fs.realpathSync)(descendant))) throw new _src_core.ProbeError(`Path escapes the workspace: ${target}`, {
 				origin: "claimant",
 				code: "refused",
 				context: { path: target }
@@ -97,7 +153,8 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 		}
 	} catch (error) {
 		if (error instanceof _src_core.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 _src_core.ProbeError(`The workspace path cannot be inspected: ${target}`, {
 			origin: claimant ? "claimant" : "workspace",
 			code: claimant ? "refused" : "malformed",
@@ -177,7 +234,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
@@ -190,11 +247,7 @@ function overwriteFile(file, text) {
 * ```
 */
 function isRefusedName(file, error) {
-	if (typeof error !== "object" || error === null) return false;
-	const fault = error;
-	const reading = (0, _orkestrel_contract.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;
@@ -289,7 +342,7 @@ function resolveWorkspaceModule(workspace, specifier) {
 	const outcome = (0, _orkestrel_contract.attempt)(() => (0, node_module.createRequire)((0, node_path.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 _src_core.ProbeError(`The workspace cannot resolve ${specifier}`, {
 		origin: "workspace",
 		code: missing ? "missing" : "malformed",
@@ -304,7 +357,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 _src_core.ProbeError(`The workspace cannot load ${specifier}`, {
 		origin: "workspace",
 		code: missing ? "missing" : "malformed",
@@ -342,7 +395,8 @@ function readWorkspaceManifest(workspace, name) {
 	const reading = (0, _orkestrel_contract.attempt)(() => (0, node_fs.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 _src_core.ProbeError(`${name} does not publish a readable manifest`, {
 			origin: "workspace",
 			code: missing ? "missing" : "malformed",
@@ -486,23 +540,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 = (0, node_path.extname)(file);
 	return `${extension === "" ? file : file.slice(0, -extension.length)}.probe-${revision}${extension}`;
@@ -511,7 +566,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
@@ -638,7 +693,7 @@ function normalizeValue(workspace, value) {
 		if (!(0, node_path.isAbsolute)(value)) return value;
 		const path = (0, node_path.relative)(root, (0, node_path.resolve)(value));
 		if (path === "") return ".";
-		if (path === ".." || path.startsWith(`..${node_path.sep}`) || (0, node_path.isAbsolute)(path)) return value;
+		if (escapesRoot(root, value)) return value;
 		return normalizePath(path);
 	}
 	if ((0, _orkestrel_contract.isArray)(value)) return value.map((entry) => normalizeValue(workspace, entry));
@@ -824,11 +879,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
@@ -878,7 +933,6 @@ var LintStage = class {
 	#closing;
 	#progress = 0;
 	#revision = 0;
-	#destroyed = false;
 	/**
 	* Starts warming the target workspace's Oxlint language server.
 	*
@@ -900,12 +954,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 (0, _src_core.createDestroyedError)("lint stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("lint stage");
 		if (options === void 0) throw new _src_core.ProbeError("The lint stage inspects only under a bound its caller supplies", {
 			origin: "claimant",
 			code: "refused",
@@ -913,7 +966,7 @@ var LintStage = class {
 		});
 		const started = performance.now();
 		const client = await this.#warmed();
-		if (this.#destroyed) throw (0, _src_core.createDestroyedError)("lint stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("lint stage");
 		const issues = [];
 		for (const draft of [...subject.files, subject.test]) issues.push(...await this.#document(client, draft, options.signal));
 		return {
@@ -998,7 +1051,7 @@ var LintStage = class {
 		});
 	}
 	#translate(error, path) {
-		if (this.#destroyed) return (0, _src_core.createDestroyedError)("lint stage");
+		if (this.#closing !== void 0) return (0, _src_core.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;
@@ -1053,6 +1106,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
@@ -1101,7 +1159,6 @@ var RuntimeStage = class {
 	#specifications = 0;
 	#closing;
 	#progress = 0;
-	#destroyed = false;
 	/**
 	* Starts warming the target workspace's Vitest service.
 	*
@@ -1123,16 +1180,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 (0, _src_core.createDestroyedError)("runtime stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("runtime stage");
 		const started = performance.now();
 		const exitCode = process.exitCode;
 		const vitest = await this.#runner();
-		if (this.#destroyed) throw (0, _src_core.createDestroyedError)("runtime stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("runtime stage");
 		const project = this.#project(vitest, subject.test.path);
 		if ("message" in project) return {
 			stage: this.stage,
@@ -1274,7 +1330,7 @@ var RuntimeStage = class {
 		return {
 			...config,
 			plugins: [...config.plugins ?? [], {
-				name: "orkestrel-runtime-overlay",
+				name: _src_core.RUNTIME_PLUGIN,
 				enforce: "pre",
 				resolveId: this.#resolve.bind(this),
 				load: this.#load.bind(this)
@@ -1316,7 +1372,7 @@ var RuntimeStage = class {
 		let generated;
 		const outcome = (0, _orkestrel_contract.attempt)(() => {
 			const revision = `${process.pid}-${(0, node_crypto.randomUUID)()}`;
-			const file = createRevisionFile(this.#workspace, test.path, revision);
+			const file = buildRevisionPath(this.#workspace, test.path, revision);
 			generated = file;
 			const target = (0, node_path.relative)(this.#workspace, file);
 			resolveWorkspaceFile(this.#workspace, target, true);
@@ -1374,7 +1430,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 === _src_core.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`
@@ -1463,14 +1519,14 @@ var RuntimeStage = class {
 	}
 	#runner() {
 		const current = this.#vitest;
-		if (current !== void 0 && this.#specifications < 64) return current;
+		if (current !== void 0 && this.#specifications < _src_core.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 < _src_core.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 (0, _src_core.createDestroyedError)("runtime stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("runtime stage");
 		const runner = create ?? loadWorkspaceModule(this.#workspace, "vitest/node").createVitest;
 		const replacement = await this.#warm(runner);
 		this.#specifications = 0;
@@ -1548,7 +1604,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() {
@@ -1721,7 +1777,6 @@ var TypeStage = class {
 	#recycled;
 	#closing;
 	#progress = 0;
-	#destroyed = false;
 	/**
 	* Starts warming the target workspace's TypeScript service.
 	*
@@ -1775,15 +1830,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 (0, _src_core.createDestroyedError)("type stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("type stage");
 		const started = performance.now();
 		const typescript = await this.#typescript;
-		if (this.#destroyed) throw (0, _src_core.createDestroyedError)("type stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("type stage");
 		const selections = subject.files.map((draft) => ({
 			draft,
 			path: resolveWorkspaceFile(this.#workspace, draft.path)
@@ -1827,9 +1881,9 @@ var TypeStage = class {
 		}
 	}
 	async #resolve(project) {
-		if (this.#destroyed) throw (0, _src_core.createDestroyedError)("type stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("type stage");
 		const typescript = await this.#typescript;
-		if (this.#destroyed) throw (0, _src_core.createDestroyedError)("type stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("type stage");
 		const resolved = resolveWorkspaceFile(this.#workspace, project);
 		this.#progress += 1;
 		this.#service(typescript, project);
@@ -1872,7 +1926,7 @@ var TypeStage = class {
 	}
 	async #unblock() {
 		await (0, node_timers_promises.setTimeout)(0);
-		if (this.#destroyed) throw (0, _src_core.createDestroyedError)("type stage");
+		if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("type stage");
 	}
 	#record(draft, overlay) {
 		overlay.set(resolveWorkspaceFile(this.#workspace, draft.path), draft.text);
@@ -2060,7 +2114,6 @@ var Probe = class {
 	#typeTail = Promise.resolve();
 	#arming;
 	#closing;
-	#destroyed = false;
 	/**
 	* Resolves the target toolchain and starts warming the resident stages.
 	*
@@ -2110,7 +2163,7 @@ var Probe = class {
 			this.#support();
 			this.#admit(claim);
 			await this.#ready();
-			if (this.#destroyed) throw (0, _src_core.createDestroyedError)("probe");
+			if (this.#closing !== void 0) throw (0, _src_core.createDestroyedError)("probe");
 			const started = performance.now();
 			const id = (0, node_crypto.randomUUID)();
 			const project = await this.#resolve(claim);
@@ -2144,7 +2197,6 @@ var Probe = class {
 	}
 	destroy() {
 		if (this.#closing !== void 0) return this.#closing;
-		this.#destroyed = true;
 		this.#closing = this.#destroy();
 		return this.#closing;
 	}
@@ -2154,7 +2206,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();
@@ -2206,8 +2258,8 @@ var Probe = class {
 	}
 	async #boot(created) {
 		const revision = `${process.pid}-${(0, node_crypto.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 = (0, node_path.basename)(typeDependency, ".ts");
 		const runtimeModule = (0, node_path.basename)(runtimeDependency, ".ts");
 		const typeTest = {
@@ -2348,7 +2400,7 @@ var Probe = class {
 		}
 	}
 	async #recycle(stage) {
-		if (this.#destroyed) return false;
+		if (this.#closing !== void 0) return false;
 		const timeout = (0, _orkestrel_timeout.createTimeout)({ ms: this.#deadline });
 		timeout.start();
 		try {
@@ -2356,7 +2408,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;
@@ -2414,13 +2466,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 {
@@ -2643,10 +2699,11 @@ exports.Probe = Probe;
 exports.ProbeServer = ProbeServer;
 exports.RuntimeStage = RuntimeStage;
 exports.TypeStage = TypeStage;
+exports.buildRevisionPath = buildRevisionPath;
 exports.captureListeners = captureListeners;
 exports.computeDigest = computeDigest;
-exports.createRevisionFile = createRevisionFile;
 exports.describeUnknown = describeUnknown;
+exports.escapesRoot = escapesRoot;
 exports.findRefusedPaths = findRefusedPaths;
 exports.guardStage = guardStage;
 exports.inferDocumentLanguage = inferDocumentLanguage;
@@ -2658,6 +2715,7 @@ exports.matchesWorkspaceModule = matchesWorkspaceModule;
 exports.normalizePath = normalizePath;
 exports.normalizeValue = normalizeValue;
 exports.overwriteFile = overwriteFile;
+exports.readFaultCode = readFaultCode;
 exports.readWorkspaceManifest = readWorkspaceManifest;
 exports.relativeWorkspaceFile = relativeWorkspaceFile;
 exports.relativeWorkspaceMessage = relativeWorkspaceMessage;