@orkestrel/probe 0.0.1 → 0.0.2

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,7 +685,7 @@ var Overlay = class {
 };
 //#endregion
 //#region package.json
-var version = "0.0.1";
+var version = "0.0.2";
 var peerDependencies = {
 	"oxlint": "^1.77.0",
 	"typescript": "^6.0.0",
@@ -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: {
@@ -1756,6 +1817,9 @@ var TypeStage = class {
 		if (!this.#resident.has(path)) this.#recycle(path);
 		return service;
 	}
+	#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;
@@ -2276,7 +2340,7 @@ 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)) {
@@ -2316,6 +2380,6 @@ var ProbeServer = class {
 	}
 };
 //#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