@tsdoctor/vfs 0.4.8 → 0.6.0

package/TsconfigParser.js

@@ -1,6 +1,7 @@
 import { decodeCompilerOptions } from "./TypeResolutionOptions.js";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { ErrorText } from "@effected/engine";
 import { TsconfigLoaderSync } from "@effected/tsconfig-json";
 import { Result } from "effect";
 
@@ -87,7 +88,7 @@ function parseTsConfig(configPath, projectRoot) {
 	try {
 		options = TsconfigLoaderSync.compilerOptions(absolutePath, syncHost);
 	} catch (error) {
-		throw new TsConfigParseError(absolutePath, error instanceof Error ? error.message : String(error), error);
+		throw new TsConfigParseError(absolutePath, ErrorText.describe(error), error);
 	}
 	const decoded = decodeCompilerOptions(options);
 	if (Result.isFailure(decoded)) throw new TsConfigParseError(absolutePath, decoded.failure.message, decoded.failure);

package/TwoslashCache.js

@@ -1,5 +1,7 @@
+import { Result } from "effect";
 import { createHash } from "node:crypto";
 import { gunzipSync, gzipSync } from "node:zlib";
+import { JsoncCanonicalizeOptions, JsoncFingerprint } from "@effected/jsonc";
 
 // src/TwoslashCache.ts
 /**
@@ -62,10 +64,16 @@ import { gunzipSync, gzipSync } from "node:zlib";
 *
 * @public
 */
-const TWOSLASH_CACHE_FORMAT = 1;
-function sha256(input) {
-	return createHash("sha256").update(input).digest("hex");
-}
+const TWOSLASH_CACHE_FORMAT = 2;
+const digest = (bytes) => createHash("sha256").update(bytes).digest();
+/**
+* Compiler options are TypeScript's own plain JSON shape, but a member may be
+* present and `undefined`; those are omitted, as `JSON.stringify` would.
+*/
+const COMPILER_OPTIONS_CANONICALIZATION = JsoncCanonicalizeOptions.make({
+	undefined: "omit",
+	nonFinite: "null"
+});
 /**
 * Fingerprint the type environment a generation is checked against.
 *
@@ -88,28 +96,31 @@ function sha256(input) {
 */
 function twoslashEnvHash(vfs, toolchain) {
 	const hash = createHash("sha256");
-	hash.update(`format:${1}\0toolchain:${toolchain}\0`);
+	hash.update(`format:${2}\0toolchain:${toolchain}\0`);
 	for (const key of [...vfs.keys()].sort()) hash.update(`${key}\0${vfs.get(key) ?? ""}\0`);
 	return hash.digest("hex");
 }
-/** JSON with object keys sorted, so equivalent options hash identically. */
-function stableStringify(value) {
-	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
-	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-	return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
-}
 /**
 * Per-entry key: the code, its language, and the compiler configuration it is
 * checked under.
 *
 * The configuration matters because two APIs on one site may be documented
 * under different `tsconfig`s — the same source checked under different options
-* can produce different types, so it must not share a cache entry.
+* can produce different types, so it must not share a cache entry. The options
+* are folded in through their RFC 8785 canonical form, so key order does not
+* matter.
+*
+* Returns `undefined` when the options cannot be canonicalized (a function or a
+* non-plain object among them): such a block is not cached, rather than keyed
+* on a spelling that could collide with different options.
 *
 * @public
 */
 function twoslashEntryKey(code, lang, compilerOptions) {
-	return sha256(`${lang ?? "ts"}\0${stableStringify(compilerOptions ?? {})}\0${code}`);
+	const options = JsoncFingerprint.canonicalizeResult(compilerOptions ?? {}, COMPILER_OPTIONS_CANONICALIZATION);
+	if (Result.isFailure(options)) return void 0;
+	const key = JsoncFingerprint.hashTextResult(`${lang ?? "ts"}\0${options.success}\0${code}`, digest);
+	return Result.isSuccess(key) ? key.success : void 0;
 }
 /**
 * The cache key a whole generation is stored under. One blob per environment,
@@ -118,7 +129,7 @@ function twoslashEntryKey(code, lang, compilerOptions) {
 * @public
 */
 function twoslashBlobKey(envHash) {
-	return `twoslash/v${1}/${envHash}`;
+	return `twoslash/v${2}/${envHash}`;
 }
 /**
 * Build a synchronous Twoslash cache over an in-memory map, optionally seeded
@@ -133,7 +144,8 @@ function makeTwoslashCache(initial) {
 	let dirty = false;
 	return {
 		read: (code, lang, options) => {
-			const found = map.get(twoslashEntryKey(code, lang, options?.compilerOptions));
+			const key = twoslashEntryKey(code, lang, options?.compilerOptions);
+			const found = key === void 0 ? void 0 : map.get(key);
 			if (found === void 0) {
 				misses += 1;
 				return null;
@@ -142,12 +154,14 @@ function makeTwoslashCache(initial) {
 			return found;
 		},
 		write: (code, data, lang, options) => {
+			const key = twoslashEntryKey(code, lang, options?.compilerOptions);
+			if (key === void 0) return;
 			const value = {
 				nodes: data.nodes,
 				code: data.code,
 				...data.meta?.extension != null ? { meta: { extension: data.meta.extension } } : {}
 			};
-			map.set(twoslashEntryKey(code, lang, options?.compilerOptions), value);
+			map.set(key, value);
 			dirty = true;
 		},
 		stats: () => ({

package/TypeScriptConfig.js

@@ -1,5 +1,6 @@
 import { decodeCompilerOptions } from "./TypeResolutionOptions.js";
 import { TsConfigParseError, parseTsConfig } from "./TsconfigParser.js";
+import { ErrorText } from "@effected/engine";
 import { Result } from "effect";
 
 // src/TypeScriptConfig.ts
@@ -120,7 +121,7 @@ function resolveTypeScriptConfigSingle(config, projectRoot) {
 			options = parseTsConfig(tsconfigPath, projectRoot);
 		} catch (error) {
 			if (error instanceof TsConfigParseError) throw error;
-			throw new TsConfigParseError(tsconfigPath, error instanceof Error ? error.message : String(error), error);
+			throw new TsConfigParseError(tsconfigPath, ErrorText.describe(error), error);
 		}
 	}
 	if (config.compilerOptions) options = mergeCompilerOptions(options, decodeInput(config.compilerOptions, "compilerOptions"));
@@ -168,7 +169,7 @@ async function resolveTypeScriptConfigSingleAsync(config, projectRoot) {
 				options = parseTsConfig(tsconfigPath, projectRoot);
 			} catch (error) {
 				if (error instanceof TsConfigParseError) throw error;
-				throw new TsConfigParseError(tsconfigPath, error instanceof Error ? error.message : String(error), error);
+				throw new TsConfigParseError(tsconfigPath, ErrorText.describe(error), error);
 			}
 		}
 	}

package/index.d.ts

@@ -94,8 +94,8 @@ export declare const toProgrammaticCompilerOptions: (options: TypeResolutionComp
  */
 export declare class TsConfigParseError extends Error {
   readonly configPath: string;
-  readonly cause?: unknown | undefined;
-  constructor(configPath: string, message: string, cause?: unknown | undefined);
+  readonly cause?: unknown;
+  constructor(configPath: string, message: string, cause?: unknown);
 }
 /**
  * Parse a `tsconfig.json` and extract the compiler options used for type
@@ -305,7 +305,7 @@ export declare class TsEnvironment {
  *
  * @public
  */
-export declare const TWOSLASH_CACHE_FORMAT = 1;
+export declare const TWOSLASH_CACHE_FORMAT = 2;
 /**
  * The subset of a Twoslash run that Shiki consumes, and all this cache stores.
  *
@@ -367,11 +367,17 @@ export declare function twoslashEnvHash(vfs: ReadonlyMap<string, string>, toolch
  *
  * The configuration matters because two APIs on one site may be documented
  * under different `tsconfig`s — the same source checked under different options
- * can produce different types, so it must not share a cache entry.
+ * can produce different types, so it must not share a cache entry. The options
+ * are folded in through their RFC 8785 canonical form, so key order does not
+ * matter.
+ *
+ * Returns `undefined` when the options cannot be canonicalized (a function or a
+ * non-plain object among them): such a block is not cached, rather than keyed
+ * on a spelling that could collide with different options.
  *
  * @public
  */
-export declare function twoslashEntryKey(code: string, lang: string | undefined, compilerOptions?: unknown): string;
+export declare function twoslashEntryKey(code: string, lang: string | undefined, compilerOptions?: unknown): string | undefined;
 /**
  * The cache key a whole generation is stored under. One blob per environment,
  * so a changed environment reads as a miss rather than serving stale results.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/vfs",
-	"version": "0.4.8",
+	"version": "0.6.0",
 	"private": false,
 	"description": "Virtual TypeScript projects for documentation tooling: the Vfs currency type, declaration-backed virtual packages, @typescript/vfs environments, and the compiler-option resolution that configures them.",
 	"keywords": [
@@ -36,11 +36,15 @@
 		},
 		"./package.json": "./package.json"
 	},
+	"dependencies": {
+		"@effected/engine": "^0.11.0",
+		"@effected/jsonc": "^0.22.0"
+	},
 	"peerDependencies": {
-		"@effected/tsconfig-json": "^0.17.0",
+		"@effected/tsconfig-json": "^0.19.0",
 		"@shikijs/twoslash": "^4.4.3",
 		"@typescript/vfs": "^1.6.5",
-		"effect": "^4.0.6",
+		"effect": "~4.1.1",
 		"typescript": "^6.0.3"
 	},
 	"peerDependenciesMeta": {

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.60.0"
     }
   ]
 }