@orkestrel/probe 0.0.1 → 0.0.3

package/dist/src/server/index.d.cts

@@ -187,6 +187,43 @@ export declare interface Inspection {
     readonly claim: Claim;
 }
 
+/**
+ * Reports whether a fault means the host refuses the name a caller supplied for a file to create.
+ *
+ * @remarks
+ * A host reports one refusal with a code of its own and several unrelated conditions with one
+ * shared code, so the code alone does not separate a name the host will not accept from a file
+ * that is merely absent. `ENAMETOOLONG` names the refusal outright. `ERR_INVALID_ARG_VALUE` names
+ * every argument Node rejects, so it names the refusal only for a path carrying the NUL byte Node
+ * refuses; the same code arrives for a bad `flag` and a bad encoding, which say nothing about the
+ * name. An `ENOENT` raised while the parent stats as a directory names the refusal too, because an
+ * ordinary absent file beneath an existing directory would have been created instead; a Windows
+ * host reports an overlong component and a character its filesystem reserves that way. Measured on
+ * 2026-08-21 on Windows 11 with Node v24.18.1 over NTFS, `writeFileSync` reported `ENOENT` for a
+ * 300-character final component and never reported `ENAMETOOLONG`.
+ *
+ * This reads the fault the host reported rather than applying a length or character policy of its
+ * own, so a host that accepts a name another host refuses is not second-guessed and no platform
+ * branch decides the answer. Every read of the fault is guarded, so it is total over every value a
+ * published caller can supply: a proxy whose `has` trap throws, a value whose `code` getter throws,
+ * a fault carrying no code, and a parent this host cannot stat each report false.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	writeFileSync('tmp/probe/greeting\0.test.ts', '')
+ * } catch (error) {
+ * 	isRefusedName('tmp/probe/greeting\0.test.ts', error) // true
+ * }
+ * isRefusedName('tmp/probe/greeting.test.ts', new Error('the runtime stage was destroyed')) // false
+ * ```
+ */
+export declare function isRefusedName(file: string, error: unknown): boolean;
+
 /**
  * Inspects virtual documents through one resident Oxlint language server.
  *
@@ -728,11 +765,12 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * as a path string, into which the stage can install no overlay, and a specification path that
  * crosses a symbolic link, whose existing components this host cannot inspect, or whose directory
  * the target tree blocks probe from creating. An `origin: 'instrument'` issue names this package's
- * own machinery: a specification it could not write after its directory exists, or one it could
- * not run, evict, or delete, in each case for a reason the target tree does not own, and a run
- * that reported no test. An unmapped caller test and a test whose named project is absent are claimant failures with
- * `code: 'missing'`, thrown rather than reported, because a test that never ran is no evidence
- * about the candidate.
+ * own machinery: a specification it could not write after its directory exists and the host did not
+ * refuse the caller's own name, or one it could not run, evict, or delete, in each case for a
+ * reason the target tree does not own, and a run that reported no test. An unmapped caller test and
+ * a test whose named project is absent are claimant failures with `code: 'missing'`, and a declared
+ * test path the host refuses to create is a claimant failure with `code: 'refused'`. Each is thrown
+ * rather than reported, because a test that never ran is no evidence about the candidate.
  *
  * The write path's physical-containment guarantee covers the claim inputs and the target tree as
  * inspected. A concurrent process that mutates a path component between the final inspection and

package/dist/src/server/index.d.ts

@@ -187,6 +187,43 @@ export declare interface Inspection {
     readonly claim: Claim;
 }
 
+/**
+ * Reports whether a fault means the host refuses the name a caller supplied for a file to create.
+ *
+ * @remarks
+ * A host reports one refusal with a code of its own and several unrelated conditions with one
+ * shared code, so the code alone does not separate a name the host will not accept from a file
+ * that is merely absent. `ENAMETOOLONG` names the refusal outright. `ERR_INVALID_ARG_VALUE` names
+ * every argument Node rejects, so it names the refusal only for a path carrying the NUL byte Node
+ * refuses; the same code arrives for a bad `flag` and a bad encoding, which say nothing about the
+ * name. An `ENOENT` raised while the parent stats as a directory names the refusal too, because an
+ * ordinary absent file beneath an existing directory would have been created instead; a Windows
+ * host reports an overlong component and a character its filesystem reserves that way. Measured on
+ * 2026-08-21 on Windows 11 with Node v24.18.1 over NTFS, `writeFileSync` reported `ENOENT` for a
+ * 300-character final component and never reported `ENAMETOOLONG`.
+ *
+ * This reads the fault the host reported rather than applying a length or character policy of its
+ * own, so a host that accepts a name another host refuses is not second-guessed and no platform
+ * branch decides the answer. Every read of the fault is guarded, so it is total over every value a
+ * published caller can supply: a proxy whose `has` trap throws, a value whose `code` getter throws,
+ * a fault carrying no code, and a parent this host cannot stat each report false.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * try {
+ * 	writeFileSync('tmp/probe/greeting\0.test.ts', '')
+ * } catch (error) {
+ * 	isRefusedName('tmp/probe/greeting\0.test.ts', error) // true
+ * }
+ * isRefusedName('tmp/probe/greeting.test.ts', new Error('the runtime stage was destroyed')) // false
+ * ```
+ */
+export declare function isRefusedName(file: string, error: unknown): boolean;
+
 /**
  * Inspects virtual documents through one resident Oxlint language server.
  *
@@ -728,11 +765,12 @@ export declare function resolveWorkspaceModule(workspace: string, specifier: str
  * as a path string, into which the stage can install no overlay, and a specification path that
  * crosses a symbolic link, whose existing components this host cannot inspect, or whose directory
  * the target tree blocks probe from creating. An `origin: 'instrument'` issue names this package's
- * own machinery: a specification it could not write after its directory exists, or one it could
- * not run, evict, or delete, in each case for a reason the target tree does not own, and a run
- * that reported no test. An unmapped caller test and a test whose named project is absent are claimant failures with
- * `code: 'missing'`, thrown rather than reported, because a test that never ran is no evidence
- * about the candidate.
+ * own machinery: a specification it could not write after its directory exists and the host did not
+ * refuse the caller's own name, or one it could not run, evict, or delete, in each case for a
+ * reason the target tree does not own, and a run that reported no test. An unmapped caller test and
+ * a test whose named project is absent are claimant failures with `code: 'missing'`, and a declared
+ * test path the host refuses to create is a claimant failure with `code: 'refused'`. Each is thrown
+ * rather than reported, because a test that never ran is no evidence about the candidate.
  *
  * The write path's physical-containment guarantee covers the claim inputs and the target tree as
  * inspected. A concurrent process that mutates a path component between the final inspection and

package/dist/src/server/index.js

@@ -106,6 +106,53 @@ function resolveWorkspaceFile(workspace, target, mutate = false) {
 	return file;
 }
 /**
+* Reports whether a fault means the host refuses the name a caller supplied for a file to create.
+*
+* @remarks
+* A host reports one refusal with a code of its own and several unrelated conditions with one
+* shared code, so the code alone does not separate a name the host will not accept from a file
+* that is merely absent. `ENAMETOOLONG` names the refusal outright. `ERR_INVALID_ARG_VALUE` names
+* every argument Node rejects, so it names the refusal only for a path carrying the NUL byte Node
+* refuses; the same code arrives for a bad `flag` and a bad encoding, which say nothing about the
+* name. An `ENOENT` raised while the parent stats as a directory names the refusal too, because an
+* ordinary absent file beneath an existing directory would have been created instead; a Windows
+* host reports an overlong component and a character its filesystem reserves that way. Measured on
+* 2026-08-21 on Windows 11 with Node v24.18.1 over NTFS, `writeFileSync` reported `ENOENT` for a
+* 300-character final component and never reported `ENAMETOOLONG`.
+*
+* This reads the fault the host reported rather than applying a length or character policy of its
+* own, so a host that accepts a name another host refuses is not second-guessed and no platform
+* branch decides the answer. Every read of the fault is guarded, so it is total over every value a
+* published caller can supply: a proxy whose `has` trap throws, a value whose `code` getter throws,
+* a fault carrying no code, and a parent this host cannot stat each report false.
+*
+* @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
+*
+* @example
+* ```ts
+* try {
+* 	writeFileSync('tmp/probe/greeting\0.test.ts', '')
+* } catch (error) {
+* 	isRefusedName('tmp/probe/greeting\0.test.ts', error) // true
+* }
+* isRefusedName('tmp/probe/greeting.test.ts', new Error('the runtime stage was destroyed')) // false
+* ```
+*/
+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;
+	if (code === "ENAMETOOLONG") return true;
+	if (code === "ERR_INVALID_ARG_VALUE") return file.includes("\0");
+	if (code !== "ENOENT") return false;
+	const parent = attempt(() => statSync(dirname(file), { throwIfNoEntry: false }));
+	return parent.success && parent.value !== void 0 && parent.value.isDirectory();
+}
+/**
 * Projects an absolute tool path into the workspace-relative form issues expose.
 *
 * @param workspace - The target workspace root
@@ -638,11 +685,11 @@ var Overlay = class {
 };
 //#endregion
 //#region package.json
-var version = "0.0.1";
+var version = "0.0.3";
 var peerDependencies = {
-	"oxlint": "^1.77.0",
-	"typescript": "^6.0.0",
-	"vitest": "^4.1.0"
+	"oxlint": "^1.79.0",
+	"typescript": "^6.0.3",
+	"vitest": "^4.1.11"
 };
 //#endregion
 //#region src/server/stages/LintStage.ts
@@ -1026,11 +1073,12 @@ var LintStage = class {
 * as a path string, into which the stage can install no overlay, and a specification path that
 * crosses a symbolic link, whose existing components this host cannot inspect, or whose directory
 * the target tree blocks probe from creating. An `origin: 'instrument'` issue names this package's
-* own machinery: a specification it could not write after its directory exists, or one it could
-* not run, evict, or delete, in each case for a reason the target tree does not own, and a run
-* that reported no test. An unmapped caller test and a test whose named project is absent are claimant failures with
-* `code: 'missing'`, thrown rather than reported, because a test that never ran is no evidence
-* about the candidate.
+* own machinery: a specification it could not write after its directory exists and the host did not
+* refuse the caller's own name, or one it could not run, evict, or delete, in each case for a
+* reason the target tree does not own, and a run that reported no test. An unmapped caller test and
+* a test whose named project is absent are claimant failures with `code: 'missing'`, and a declared
+* test path the host refuses to create is a claimant failure with `code: 'refused'`. Each is thrown
+* rather than reported, because a test that never ran is no evidence about the candidate.
 *
 * The write path's physical-containment guarantee covers the claim inputs and the target tree as
 * inspected. A concurrent process that mutates a path component between the final inspection and
@@ -1093,7 +1141,7 @@ var RuntimeStage = class {
 				elapsed: Math.round(performance.now() - started),
 				issues: [specification]
 			};
-			const file = specification;
+			const file = sep === "\\" ? normalizePath(specification) : specification;
 			this.#specifications += 1;
 			this.#revisions.add(file);
 			let issues = [];
@@ -1243,9 +1291,11 @@ var RuntimeStage = class {
 	}
 	#specification(test) {
 		let creating = false;
+		let generated;
 		const outcome = attempt(() => {
 			const revision = `${process.pid}-${randomUUID()}`;
 			const file = createRevisionFile(this.#workspace, test.path, revision);
+			generated = file;
 			const target = relative(this.#workspace, file);
 			resolveWorkspaceFile(this.#workspace, target, true);
 			creating = true;
@@ -1268,6 +1318,15 @@ var RuntimeStage = class {
 			},
 			cause: outcome.error.cause
 		});
+		if (!creating && generated !== void 0 && isRefusedName(generated, outcome.error)) throw new ProbeError(`The runtime stage cannot write a specification beside a test path the host refuses (${describeUnknown(outcome.error)})`, {
+			origin: "claimant",
+			code: "refused",
+			context: {
+				stage: this.stage,
+				path: test.path
+			},
+			cause: outcome.error
+		});
 		return {
 			origin: outcome.error instanceof ProbeError && outcome.error.origin === "workspace" || creating ? "workspace" : "instrument",
 			path: test.path,
@@ -1366,8 +1425,9 @@ var RuntimeStage = class {
 		for (const [path, digest] of modules) this.#modules.set(path, digest);
 	}
 	#invalidate(vitest, path) {
-		vitest.invalidateFile(path);
-		vitest.watcher.invalidates.add(path);
+		const id = sep === "\\" ? normalizePath(path) : path;
+		vitest.invalidateFile(id);
+		vitest.watcher.invalidates.add(id);
 	}
 	#snapshot() {
 		const modules = /* @__PURE__ */ new Map();
@@ -1717,8 +1777,9 @@ var TypeStage = class {
 		const path = resolveWorkspaceFile(this.#workspace, project);
 		const existing = this.#services.get(path);
 		if (existing !== void 0) return existing;
-		const config = typescript.readConfigFile(path, typescript.sys.readFile);
-		if (config.error !== void 0) throw new ProbeError(typescript.flattenDiagnosticMessageText(config.error.messageText, "\n"), {
+		const spelling = normalizePath(path);
+		const config = typescript.readConfigFile(spelling, typescript.sys.readFile);
+		if (config.error !== void 0) throw new ProbeError(this.#translate(typescript, config.error.messageText, path), {
 			origin: "workspace",
 			code: "malformed",
 			context: {
@@ -1726,8 +1787,8 @@ var TypeStage = class {
 				project
 			}
 		});
-		const parsed = typescript.parseJsonConfigFileContent(config.config, typescript.sys, dirname(path), void 0, path);
-		if (parsed.errors.length > 0) throw new ProbeError(typescript.flattenDiagnosticMessageText(parsed.errors[0]?.messageText ?? "", "\n"), {
+		const parsed = typescript.parseJsonConfigFileContent(config.config, typescript.sys, dirname(spelling), void 0, spelling);
+		if (parsed.errors.length > 0) throw new ProbeError(this.#translate(typescript, parsed.errors[0]?.messageText, path), {
 			origin: "workspace",
 			code: "malformed",
 			context: {
@@ -1737,25 +1798,56 @@ var TypeStage = class {
 		});
 		this.#options.set(path, parsed.options);
 		this.#files.set(path, parsed.fileNames);
-		const service = typescript.createLanguageService({
-			getCompilationSettings: () => this.#options.get(path) ?? {},
-			getScriptFileNames: () => [...this.#files.get(path) ?? [], ...this.#overlay.paths],
-			getScriptVersion: (file) => this.#version(file),
-			getScriptSnapshot: (file) => this.#snapshot(typescript, file),
-			getCurrentDirectory: () => this.#workspace,
-			getDefaultLibFileName: (options) => typescript.getDefaultLibFilePath(options),
-			fileExists: (file) => this.#overlay.text(file) !== void 0 || typescript.sys.fileExists(file),
-			readFile: (file) => this.#overlay.text(file) ?? typescript.sys.readFile(file),
+		const host = {
+			getCompilationSettings: this.#compilationSettings.bind(this, path),
+			getScriptFileNames: this.#scriptFiles.bind(this, path),
+			getScriptVersion: this.#version.bind(this),
+			getScriptSnapshot: this.#snapshot.bind(this, typescript),
+			getCurrentDirectory: this.#directory.bind(this),
+			getDefaultLibFileName: this.#defaultLibrary.bind(this, typescript),
+			fileExists: this.#fileExists.bind(this, typescript),
+			readFile: this.#readFile.bind(this, typescript),
 			readDirectory: typescript.sys.readDirectory,
-			directoryExists: (directory) => typescript.sys.directoryExists(directory) || this.#overlay.covers(directory),
+			directoryExists: this.#directoryExists.bind(this, typescript),
 			getDirectories: typescript.sys.getDirectories,
-			useCaseSensitiveFileNames: () => typescript.sys.useCaseSensitiveFileNames,
-			getNewLine: () => typescript.sys.newLine
-		});
+			useCaseSensitiveFileNames: this.#caseSensitive.bind(this, typescript),
+			getNewLine: this.#newline.bind(this, typescript)
+		};
+		const service = typescript.createLanguageService(host);
 		this.#services.set(path, service);
 		if (!this.#resident.has(path)) this.#recycle(path);
 		return service;
 	}
+	#compilationSettings(path) {
+		return this.#options.get(path) ?? {};
+	}
+	#scriptFiles(path) {
+		return [...this.#files.get(path) ?? [], ...this.#overlay.paths];
+	}
+	#directory() {
+		return this.#workspace;
+	}
+	#defaultLibrary(typescript, options) {
+		return typescript.getDefaultLibFilePath(options);
+	}
+	#fileExists(typescript, file) {
+		return this.#overlay.text(file) !== void 0 || typescript.sys.fileExists(file);
+	}
+	#readFile(typescript, file) {
+		return this.#overlay.text(file) ?? typescript.sys.readFile(file);
+	}
+	#directoryExists(typescript, directory) {
+		return typescript.sys.directoryExists(directory) || this.#overlay.covers(directory);
+	}
+	#caseSensitive(typescript) {
+		return typescript.sys.useCaseSensitiveFileNames;
+	}
+	#newline(typescript) {
+		return typescript.sys.newLine;
+	}
+	#translate(typescript, message, path) {
+		return normalizePath(typescript.flattenDiagnosticMessageText(message, "\n")).replaceAll(normalizePath(path), relativeWorkspaceFile(this.#workspace, path));
+	}
 	#configure(service, project) {
 		const path = resolveWorkspaceFile(this.#workspace, project);
 		if (this.#diagnostics.has(path)) return;
@@ -1882,17 +1974,17 @@ var Probe = class {
 		this.#typeQueue = createQueue({
 			concurrency: 1,
 			retries: 0,
-			handler: (inspection) => this.#inspectStage(this.#type, this.#type.progress, this.#type.inspect(inspection.subject, inspection.claim.project), inspection.claim)
+			handler: this.#inspectType.bind(this)
 		});
 		this.#lintQueue = createQueue({
 			concurrency: 1,
 			retries: 0,
-			handler: (inspection) => this.#inspectStage(this.#lint, this.#lint.progress, this.#lint.inspect(inspection.subject), inspection.claim)
+			handler: this.#inspectLint.bind(this)
 		});
 		this.#runtimeQueue = createQueue({
 			concurrency: 1,
 			retries: 0,
-			handler: (inspection) => this.#inspectStage(this.#runtime, this.#runtime.progress, this.#runtime.inspect(inspection.subject), inspection.claim)
+			handler: this.#inspectRuntime.bind(this)
 		});
 		this.#arming = this.#arm();
 		this.#arming.catch(() => {});
@@ -2092,6 +2184,15 @@ var Probe = class {
 		for (const pending of admitted) pending.catch(() => {});
 		return Promise.all(admitted);
 	}
+	#inspectType(inspection) {
+		return this.#inspectStage(this.#type, this.#type.progress, this.#type.inspect(inspection.subject, inspection.claim.project), inspection.claim);
+	}
+	#inspectLint(inspection) {
+		return this.#inspectStage(this.#lint, this.#lint.progress, this.#lint.inspect(inspection.subject), inspection.claim);
+	}
+	#inspectRuntime(inspection) {
+		return this.#inspectStage(this.#runtime, this.#runtime.progress, this.#runtime.inspect(inspection.subject), inspection.claim);
+	}
 	async #inspectStage(stage, progress, operation, claim) {
 		const timeout = createTimeout({ ms: this.#deadline });
 		timeout.start();
@@ -2276,19 +2377,9 @@ var ProbeServer = class {
 		const tools = createToolManager();
 		tools.add(createTool({
 			name: "prove",
-			description: "Proves a claim with type, lint, and runtime evidence.",
+			description: "Answers whether a TypeScript edit compiles, lints, and passes its test in this workspace — call it before relying on such a claim, instead of reasoning or writing a throwaway probe. Supply the edit you believe is correct and an edit that must break with the stage it breaks at; the closing line is a receipt only when the case ran clean and the control broke exactly at its declared stage, and no receipt otherwise. For a performance claim, measure before proving: write a guarded bench block — if (import.meta.env.MODE === 'benchmark') — beside the probe test, run the workspace bench script, and record only magnitudes; a settled ratio then proves here as an ordinary runtime claim.",
 			parameters,
-			execute: async (input) => {
-				if (!isClaim(input)) {
-					const refused = findRefusedPaths(input);
-					throw new ProbeError(refused.length === 0 ? "The prove tool requires a claim matching the advertised schema" : `The prove tool refuses ${refused.join(", ")}: a draft path must stay inside the workspace, which the advertised schema does not constrain`, {
-						origin: "claimant",
-						code: "refused",
-						context: { value: input }
-					});
-				}
-				return this.#probe.prove(input);
-			}
+			execute: this.#prove.bind(this)
 		}));
 		return createMCPServer({
 			identity: {
@@ -2296,26 +2387,38 @@ var ProbeServer = class {
 				version
 			},
 			tools,
-			execution: async ({ call }) => {
-				const result = await tools.execute(call);
-				if (!result.success) return result;
-				if (!isVerdict(result.value)) throw new ProbeError("The prove tool returned an invalid verdict", {
-					origin: "instrument",
-					code: "malformed",
-					context: { value: result.value }
-				});
-				return {
-					resultType: "complete",
-					content: [{
-						type: "text",
-						text: formatVerdict(result.value)
-					}]
-				};
-			}
+			execution: this.#execute.bind(this)
 		});
 	}
+	async #prove(input) {
+		if (!isClaim(input)) {
+			const refused = findRefusedPaths(input);
+			throw new ProbeError(refused.length === 0 ? "The prove tool requires a claim matching the advertised schema" : `The prove tool refuses ${refused.join(", ")}: a draft path must stay inside the workspace, which the advertised schema does not constrain`, {
+				origin: "claimant",
+				code: "refused",
+				context: { value: input }
+			});
+		}
+		return this.#probe.prove(input);
+	}
+	async #execute(context) {
+		const result = await context.tools.execute(context.call);
+		if (!result.success) return result;
+		if (!isVerdict(result.value)) throw new ProbeError("The prove tool returned an invalid verdict", {
+			origin: "instrument",
+			code: "malformed",
+			context: { value: result.value }
+		});
+		return {
+			resultType: "complete",
+			content: [{
+				type: "text",
+				text: formatVerdict(result.value)
+			}]
+		};
+	}
 };
 //#endregion
-export { LintStage, Overlay, Probe, ProbeServer, RuntimeStage, TypeStage, captureListeners, computeDigest, createRevisionFile, describeUnknown, findRefusedPaths, inferDocumentLanguage, inferTestProject, inferTypeProject, loadWorkspaceModule, matchesWorkspaceModule, normalizePath, normalizeValue, parseContentLength, readWorkspaceManifest, relativeWorkspaceFile, releaseListeners, resolveWorkspaceBinary, resolveWorkspaceFile, resolveWorkspaceModule };
+export { LintStage, Overlay, Probe, ProbeServer, RuntimeStage, TypeStage, captureListeners, computeDigest, createRevisionFile, describeUnknown, findRefusedPaths, inferDocumentLanguage, inferTestProject, inferTypeProject, isRefusedName, loadWorkspaceModule, matchesWorkspaceModule, normalizePath, normalizeValue, parseContentLength, readWorkspaceManifest, relativeWorkspaceFile, releaseListeners, resolveWorkspaceBinary, resolveWorkspaceFile, resolveWorkspaceModule };
 
 //# sourceMappingURL=index.js.map