@tsdoctor/vfs 0.4.7 → 0.5.0

package/TsEnvironment.js

@@ -1,7 +1,7 @@
 import { isTypeDefinition } from "./Vfs.js";
 import { Effect, Schema } from "effect";
 
-//#region src/TsEnvironment.ts
+// src/TsEnvironment.ts
 /**
 * Raised when building a virtual TypeScript environment fails — including
 * when the optional `typescript` / `@typescript/vfs` /
@@ -91,5 +91,4 @@ var TsEnvironment = class {
 	}
 };
 
-//#endregion
 export { TsEnvironment, TsEnvironmentError };

package/TsconfigParser.js

@@ -1,10 +1,11 @@
 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";
 
-//#region src/TsconfigParser.ts
+// src/TsconfigParser.ts
 /**
 * Reading a `tsconfig.json` into the compiler options the plugin consumes.
 *
@@ -87,12 +88,11 @@ 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);
 	return decoded.success;
 }
 
-//#endregion
 export { TsConfigParseError, parseTsConfig };

package/TwoslashCache.js

@@ -1,7 +1,9 @@
+import { Result } from "effect";
 import { createHash } from "node:crypto";
 import { gunzipSync, gzipSync } from "node:zlib";
+import { JsoncCanonicalizeOptions, JsoncFingerprint } from "@effected/jsonc";
 
-//#region src/TwoslashCache.ts
+// src/TwoslashCache.ts
 /**
 * Persisted Twoslash result cache.
 *
@@ -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: () => ({
@@ -184,5 +198,4 @@ function decodeTwoslashCache(blob) {
 	}
 }
 
-//#endregion
 export { TWOSLASH_CACHE_FORMAT, decodeTwoslashCache, encodeTwoslashCache, makeTwoslashCache, twoslashBlobKey, twoslashEntryKey, twoslashEnvHash };

package/TypeResolutionOptions.js

@@ -1,7 +1,7 @@
 import { CompilerOptions, CompilerOptionsFromProgrammatic, TsEnumCodec } from "@effected/tsconfig-json";
 import { Result, Schema } from "effect";
 
-//#region src/TypeResolutionOptions.ts
+// src/TypeResolutionOptions.ts
 const fields = CompilerOptions.schema.fields;
 /**
 * The compiler options that may influence how a documentation example
@@ -94,5 +94,4 @@ const decodeCompilerOptions = (input) => Result.map(Schema.decodeUnknownResult(C
 */
 const toProgrammaticCompilerOptions = (options) => TsEnumCodec.encodeCompilerOptions(options);
 
-//#endregion
 export { TypeResolutionCompilerOptions, decodeCompilerOptions, toProgrammaticCompilerOptions };

package/TypeScriptConfig.js

@@ -1,8 +1,9 @@
 import { decodeCompilerOptions } from "./TypeResolutionOptions.js";
 import { TsConfigParseError, parseTsConfig } from "./TsconfigParser.js";
+import { ErrorText } from "@effected/engine";
 import { Result } from "effect";
 
-//#region src/TypeScriptConfig.ts
+// src/TypeScriptConfig.ts
 /**
 * Default TypeScript compiler options for Twoslash and type resolution.
 *
@@ -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);
 			}
 		}
 	}
@@ -222,5 +223,4 @@ async function resolveTypeScriptConfig(projectRoot, global, api) {
 	return options;
 }
 
-//#endregion
 export { DEFAULT_COMPILER_OPTIONS, mergeCompilerOptions, resolveTypeScriptConfig, resolveTypeScriptConfigSingle, resolveTypeScriptConfigSingleAsync };

package/Vfs.js

@@ -1,4 +1,4 @@
-//#region src/Vfs.ts
+// src/Vfs.ts
 /**
 * Merge VFS maps left to right into a new map; later entries win on path
 * collisions.
@@ -43,5 +43,4 @@ const prefixVfs = (name, entries) => {
 */
 const isTypeDefinition = (filePath) => filePath.endsWith(".d.ts") || filePath.endsWith(".d.mts") || filePath.endsWith(".d.cts");
 
-//#endregion
 export { isTypeDefinition, mergeVfs, prefixVfs };

package/VirtualPackage.js

@@ -1,6 +1,6 @@
 import { Effect, FileSystem, Schema } from "effect";
 
-//#region src/VirtualPackage.ts
+// src/VirtualPackage.ts
 /**
 * A synthetic npm package built from locally supplied TypeScript declaration
 * content, for inclusion in a {@link Vfs} without fetching from the CDN.
@@ -122,5 +122,4 @@ var VirtualPackage = class VirtualPackage extends Schema.Class("VirtualPackage")
 	}
 };
 
-//#endregion
 export { VirtualPackage };

package/index.d.ts

@@ -3,7 +3,6 @@ import { Effect, FileSystem, PlatformError, Result, Schema } from "effect";
 import { VirtualTypeScriptEnvironment } from "@typescript/vfs";
 import { TwoslashTypesCache } from "@shikijs/twoslash";
 import { PathLike } from "node:fs";
-//#region src/TypeResolutionOptions.d.ts
 /**
  * The compiler options that may influence how a documentation example
  * type-checks.
@@ -79,8 +78,6 @@ export declare const decodeCompilerOptions: (input: unknown) => Result.Result<Ty
  * @public
  */
 export declare const toProgrammaticCompilerOptions: (options: TypeResolutionCompilerOptions) => ProgrammaticCompilerOptions;
-//#endregion
-//#region src/TsconfigParser.d.ts
 /**
  * Error thrown when tsconfig.json parsing fails.
  *
@@ -97,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
@@ -118,8 +115,6 @@ export declare class TsConfigParseError extends Error {
  * @public
  */
 export declare function parseTsConfig(configPath: string, projectRoot: string): TypeResolutionCompilerOptions;
-//#endregion
-//#region src/Vfs.d.ts
 /**
  * The package's currency type: a virtual file system mapping
  * `node_modules/`-prefixed paths to file contents.
@@ -171,8 +166,6 @@ export declare const prefixVfs: (name: string, entries: ReadonlyMap<string, stri
  * @public
  */
 export declare const isTypeDefinition: (filePath: string) => boolean;
-//#endregion
-//#region src/TsEnvironment.d.ts
 declare const TsEnvironmentError_base: Schema.Class<TsEnvironmentError, Schema.TaggedStruct<"TsEnvironmentError", {
   /** The underlying failure, preserved structurally. */
   readonly cause: Schema.Defect;
@@ -252,8 +245,6 @@ export declare class TsEnvironment {
   /** Build a `VirtualTypeScriptEnvironment` over a {@link Vfs}. */
   static make(options: TsEnvironmentOptions): Effect.Effect<VirtualTypeScriptEnvironment, TsEnvironmentError>;
 }
-//#endregion
-//#region src/TwoslashCache.d.ts
 /**
  * Persisted Twoslash result cache.
  *
@@ -314,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.
  *
@@ -376,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.
@@ -409,8 +406,6 @@ export declare function encodeTwoslashCache(entries: ReadonlyMap<string, Twoslas
  * @public
  */
 export declare function decodeTwoslashCache(blob: Uint8Array): Map<string, TwoslashCacheValue>;
-//#endregion
-//#region src/TypeScriptConfig.d.ts
 /**
  * How a caller points at TypeScript configuration: a `tsconfig.json`, inline
  * compiler options, or both.
@@ -584,8 +579,6 @@ export declare function resolveTypeScriptConfigSingleAsync(config: TypeScriptCon
  * @public
  */
 export declare function resolveTypeScriptConfig(projectRoot: string, global?: TypeScriptConfig, api?: TypeScriptConfig): Promise<TypeResolutionCompilerOptions>;
-//#endregion
-//#region src/VirtualPackage.d.ts
 declare const VirtualPackage_base: Schema.Class<VirtualPackage, Schema.Struct<{
   /** The package name (e.g. `"@my-org/api-types"`). */
   readonly name: Schema.String;
@@ -658,6 +651,5 @@ export declare class VirtualPackage extends VirtualPackage_base {
   toVfs(): Vfs;
   private toPackageJson;
 }
-//#endregion
 export type { CompilerOptionsInput, TsEnvironmentOptions, TwoslashCacheStats, TwoslashCacheValue, TwoslashResultCache, TypeScriptConfig, Vfs };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tsdoctor/vfs",
-	"version": "0.4.7",
+	"version": "0.5.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.10.0",
+		"@effected/jsonc": "^0.21.0"
+	},
 	"peerDependencies": {
-		"@effected/tsconfig-json": "^0.16.0",
+		"@effected/tsconfig-json": "^0.18.0",
 		"@shikijs/twoslash": "^4.4.3",
 		"@typescript/vfs": "^1.6.5",
-		"effect": "^4.0.5",
+		"effect": "^4.0.7",
 		"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"
     }
   ]
 }