@tsdoctor/vfs 0.1.0

package/Vfs.js

@@ -0,0 +1,47 @@
+//#region src/Vfs.ts
+/**
+* Merge VFS maps left to right into a new map; later entries win on path
+* collisions.
+*
+* @example
+* ```ts
+* import { mergeVfs } from "@tsdoctor/vfs";
+*
+* const combined = mergeVfs(vfsA, vfsB);
+* ```
+*
+* @public
+*/
+const mergeVfs = (...maps) => {
+	const out = /* @__PURE__ */ new Map();
+	for (const map of maps) for (const [path, content] of map) out.set(path, content);
+	return out;
+};
+/**
+* Prefix every path in `entries` with `node_modules/<name>/`, normalizing
+* away leading slashes.
+*
+* @public
+*/
+const prefixVfs = (name, entries) => {
+	const out = /* @__PURE__ */ new Map();
+	for (const [path, content] of entries) out.set(`node_modules/${name}/${path.replace(/^\/+/, "")}`, content);
+	return out;
+};
+/**
+* Whether a path names a TypeScript declaration file.
+*
+* @remarks
+* The single spelling of this predicate. `TsEnvironment` uses it to pick a
+* VFS map's root files, and `@tsdoctor/registry`'s module resolution uses it
+* to decide whether a resolved path is a declaration. Two spellings of "is
+* this a `.d.ts`" would be free to drift, and the drift would be silent — a
+* root file quietly missing from a TypeScript environment degrades hovers
+* without producing an error.
+*
+* @public
+*/
+const isTypeDefinition = (filePath) => filePath.endsWith(".d.ts") || filePath.endsWith(".d.mts") || filePath.endsWith(".d.cts");
+
+//#endregion
+export { isTypeDefinition, mergeVfs, prefixVfs };

package/VirtualPackage.js

@@ -0,0 +1,126 @@
+import { Effect, FileSystem, Schema } from "effect";
+
+//#region 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.
+*
+* @remarks
+* Useful when you have locally generated `.d.ts` files — API Extractor
+* output, hand-written ambient declarations — and want them in the same VFS
+* `TypeRegistry` builds from remote packages. Instances are transient: they
+* are never persisted to the disk cache.
+*
+* The class is deliberately subclass-friendly (the rspress consumer extends
+* it): construct via `VirtualPackage.make(...)` or the statics, and extend
+* with `class Mine extends VirtualPackage { ... }`.
+*
+* @example
+* ```ts
+* import { VirtualPackage } from "@tsdoctor/vfs";
+*
+* const pkg = VirtualPackage.create("@my-org/api-types", "1.0.0", "export interface User { id: string }");
+* const vfs = pkg.toVfs();
+* // node_modules/@my-org/api-types/package.json, node_modules/@my-org/api-types/index.d.ts
+* ```
+*
+* @public
+*/
+var VirtualPackage = class VirtualPackage extends Schema.Class("VirtualPackage")({
+	/** The package name (e.g. `"@my-org/api-types"`). */
+	name: Schema.String,
+	/** The package version. */
+	version: Schema.String,
+	/** Entry file names (e.g. `"index.d.ts"`) mapped to declaration source. */
+	entries: Schema.ReadonlyMap(Schema.String, Schema.String)
+}) {
+	/**
+	* Single-entry factory: a virtual package whose sole entry point is
+	* `index.d.ts`.
+	*/
+	static create(name, version, declarations) {
+		return VirtualPackage.make({
+			name,
+			version,
+			entries: /* @__PURE__ */ new Map([["index.d.ts", declarations]])
+		});
+	}
+	/**
+	* Multi-entry factory: one `.d.ts` per entry point, exposed through a
+	* synthetic `exports` map.
+	*
+	* @remarks
+	* An empty entries map is developer wiring, not input — it would produce a
+	* package whose `types` points at a file that does not exist — so it
+	* throws at construction (defect posture), as does an entry set whose
+	* names collide after extension normalization (see
+	* {@link VirtualPackage.toVfs}).
+	*/
+	static createMultiEntry(name, version, entries) {
+		if (entries.size === 0) throw new Error(`VirtualPackage.createMultiEntry: "${name}" needs at least one entry file`);
+		return VirtualPackage.make({
+			name,
+			version,
+			entries
+		});
+	}
+	/**
+	* Load a single `.d.ts` file from disk as a virtual package with one
+	* `index.d.ts` entry.
+	*
+	* @remarks
+	* Reads through the platform-agnostic `FileSystem` service; the
+	* `PlatformError` surfaces typed.
+	*/
+	static fromFile(name, version, filePath) {
+		return Effect.gen(function* () {
+			const content = yield* (yield* FileSystem.FileSystem).readFileString(filePath);
+			return VirtualPackage.create(name, version, content);
+		}).pipe(Effect.withSpan("VirtualPackage.fromFile"));
+	}
+	/**
+	* The package's {@link Vfs}: a synthetic `package.json` plus every entry
+	* file, each path prefixed `node_modules/<name>/`.
+	*
+	* @remarks
+	* The `package.json` uses `types` for a single entry and an `exports` map
+	* for multiple entries, so TypeScript module resolution works against the
+	* generated VFS.
+	*/
+	toVfs() {
+		const vfs = /* @__PURE__ */ new Map();
+		const prefix = `node_modules/${this.name}`;
+		vfs.set(`${prefix}/package.json`, this.toPackageJson());
+		for (const [fileName, content] of this.entries) {
+			if (fileName === "package.json") throw new Error(`VirtualPackage: "${this.name}" cannot define package.json as an entry`);
+			vfs.set(`${prefix}/${fileName}`, content);
+		}
+		return vfs;
+	}
+	toPackageJson() {
+		if (this.entries.size === 0) throw new Error(`VirtualPackage: "${this.name}" has no entry files — nothing to point types at`);
+		const manifest = {
+			name: this.name,
+			version: this.version
+		};
+		if (this.entries.size === 1) {
+			const [only] = this.entries.keys();
+			manifest.types = only ?? "index.d.ts";
+		} else {
+			manifest.exports = {};
+			const sources = /* @__PURE__ */ new Map();
+			for (const fileName of this.entries.keys()) {
+				const baseName = fileName.replace(/\.d\.(m|c)?ts$/, "");
+				const key = baseName === "index" ? "." : `./${baseName}`;
+				const previous = sources.get(key);
+				if (previous !== void 0) throw new Error(`VirtualPackage: "${this.name}" entries "${previous}" and "${fileName}" both normalize to the export key "${key}"`);
+				sources.set(key, fileName);
+				manifest.exports[key] = { types: `./${fileName}` };
+			}
+		}
+		return JSON.stringify(manifest, null, 2);
+	}
+};
+
+//#endregion
+export { VirtualPackage };

package/index.d.ts

@@ -0,0 +1,505 @@
+import { CompilerOptions, ProgrammaticCompilerOptions } from "@effected/tsconfig-json";
+import { Effect, FileSystem, PlatformError, Result, Schema } from "effect";
+import { VirtualTypeScriptEnvironment } from "@typescript/vfs";
+import { PathLike } from "node:fs";
+//#region src/TypeResolutionOptions.d.ts
+/**
+ * The compiler options that may influence how a documentation example
+ * type-checks.
+ *
+ * @remarks
+ * Deliberately a **whitelist**, picked from `@effected/tsconfig-json`'s
+ * `CompilerOptions` rather than restated. Everything here reaches the
+ * TypeScript environment, and passing through options the tool does not
+ * understand would let a consumer's unrelated build setting silently change
+ * how their examples type-check.
+ *
+ * Picking from the kit's own field schemas is what keeps this a policy
+ * statement rather than a second definition of tsconfig: the accepted values,
+ * their spellings and their case-insensitivity are the kit's to own, and this
+ * module owns only the choice of WHICH options are in scope.
+ *
+ * @public
+ */
+declare const TypeResolutionCompilerOptions: Schema.Struct<{
+  readonly target: Schema.optionalKey<Schema.decodeTo<Schema.Literals<readonly ["es5", "es6", "es2015", "es2016", "es2017", "es2018", "es2019", "es2020", "es2021", "es2022", "es2023", "es2024", "es2025", "esnext"]>, Schema.String, never, never>>;
+  readonly module: Schema.optionalKey<Schema.decodeTo<Schema.Literals<readonly ["none", "commonjs", "amd", "umd", "system", "es6", "es2015", "es2020", "es2022", "esnext", "node16", "node18", "node20", "nodenext", "preserve"]>, Schema.String, never, never>>;
+  readonly moduleResolution: Schema.optionalKey<Schema.decodeTo<Schema.Literals<readonly ["node10", "node", "classic", "node16", "nodenext", "bundler"]>, Schema.String, never, never>>;
+  readonly jsx: Schema.optionalKey<Schema.decodeTo<Schema.Literals<readonly ["preserve", "react-native", "react-jsx", "react-jsxdev", "react"]>, Schema.String, never, never>>;
+  readonly lib: Schema.optionalKey<Schema.$Array<Schema.decodeTo<Schema.Literals<readonly ["es5", "es6", "es7", "es2015", "es2016", "es2017", "es2018", "es2019", "es2020", "es2021", "es2022", "es2023", "es2024", "es2025", "esnext", "dom", "dom.iterable", "dom.asynciterable", "webworker", "webworker.importscripts", "webworker.iterable", "webworker.asynciterable", "scripthost", "es2015.core", "es2015.collection", "es2015.generator", "es2015.iterable", "es2015.promise", "es2015.proxy", "es2015.reflect", "es2015.symbol", "es2015.symbol.wellknown", "es2016.array.include", "es2016.intl", "es2017.arraybuffer", "es2017.date", "es2017.object", "es2017.sharedmemory", "es2017.string", "es2017.intl", "es2017.typedarrays", "es2018.asyncgenerator", "es2018.asynciterable", "es2018.intl", "es2018.promise", "es2018.regexp", "es2019.array", "es2019.object", "es2019.string", "es2019.symbol", "es2019.intl", "es2020.bigint", "es2020.date", "es2020.promise", "es2020.sharedmemory", "es2020.string", "es2020.symbol.wellknown", "es2020.intl", "es2020.number", "es2021.promise", "es2021.string", "es2021.weakref", "es2021.intl", "es2022.array", "es2022.error", "es2022.intl", "es2022.object", "es2022.string", "es2022.regexp", "es2023.array", "es2023.collection", "es2023.intl", "es2024.arraybuffer", "es2024.collection", "es2024.object", "es2024.promise", "es2024.regexp", "es2024.sharedmemory", "es2024.string", "es2025.collection", "es2025.float16", "es2025.intl", "es2025.iterator", "es2025.promise", "es2025.regexp", "esnext.asynciterable", "esnext.symbol", "esnext.bigint", "esnext.weakref", "esnext.object", "esnext.regexp", "esnext.string", "esnext.float16", "esnext.iterator", "esnext.promise", "esnext.array", "esnext.collection", "esnext.date", "esnext.decorators", "esnext.disposable", "esnext.error", "esnext.intl", "esnext.sharedmemory", "esnext.temporal", "esnext.typedarrays", "decorators", "decorators.legacy"]>, Schema.String, never, never>>>;
+  readonly types: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly typeRoots: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly strict: Schema.optionalKey<Schema.Boolean>;
+  readonly skipLibCheck: Schema.optionalKey<Schema.Boolean>;
+  readonly esModuleInterop: Schema.optionalKey<Schema.Boolean>;
+  readonly allowSyntheticDefaultImports: Schema.optionalKey<Schema.Boolean>;
+}>;
+/**
+ * The decoded whitelist: canonical tsconfig spellings, every field optional.
+ *
+ * @public
+ */
+type TypeResolutionCompilerOptions = typeof TypeResolutionCompilerOptions.Type;
+/**
+ * Decode compiler options written in either spelling into the whitelist.
+ *
+ * @remarks
+ * Accepts the tsconfig spelling a user writes (`target: "es2025"`, and
+ * case-insensitively `lib: ["ESNext", "DOM"]`) and the programmatic spelling a
+ * caller holding `ts.CompilerOptions` has (`target: ts.ScriptTarget.ES2025`),
+ * because a consumer configuring a documentation build in TypeScript
+ * reasonably produces either.
+ *
+ * **Fails rather than guesses.** A value with no entry in the enum tables — a
+ * numeric target from a future TypeScript, a misspelled module kind — is
+ * rejected on the error channel instead of being passed through. Degrading to
+ * a default here would type-check every example against a configuration the
+ * user did not ask for, and produce confidently wrong output with no error:
+ * the failure mode this seam exists to prevent.
+ *
+ * @public
+ */
+declare const decodeCompilerOptions: (input: unknown) => Result.Result<TypeResolutionCompilerOptions, Schema.SchemaError>;
+/**
+ * Convert whitelisted options to the numeric-enum form the TypeScript compiler
+ * takes.
+ *
+ * @remarks
+ * The ONE conversion site between the tsconfig spelling and the programmatic
+ * one. Two consequences follow from it being single:
+ *
+ * - Any environment fingerprint MUST be computed on the ENCODED value.
+ *   Otherwise `{lib:["ESNext"]}` and `{lib:["lib.esnext.d.ts"]}` build two
+ *   identical TypeScript environments under different keys.
+ * - There is no cast here. The whitelist is a subset of the kit's own
+ *   `CompilerOptions`, so it is assignable to the encoder by construction —
+ *   which is precisely what a hand-rolled options type could not be.
+ *
+ * @public
+ */
+declare const toProgrammaticCompilerOptions: (options: TypeResolutionCompilerOptions) => ProgrammaticCompilerOptions;
+//#endregion
+//#region src/TsconfigParser.d.ts
+/**
+ * Error thrown when tsconfig.json parsing fails.
+ *
+ * @remarks
+ * Retained as the plugin's own type rather than surfacing the kit's
+ * `TsconfigParseError`/`TsconfigExtendsError` directly: the adapter's
+ * `typescript-config.ts` branches on `instanceof TsConfigParseError` to decide
+ * whether a failure is already reported, and both kit errors mean the same
+ * thing to that caller. It now also carries a decode failure from
+ * {@link decodeCompilerOptions}, which is the same thing again: a tsconfig
+ * this tool cannot act on.
+ *
+ * @public
+ */
+declare class TsConfigParseError extends Error {
+  readonly configPath: string;
+  readonly cause?: unknown | undefined;
+  constructor(configPath: string, message: string, cause?: unknown | undefined);
+}
+/**
+ * Parse a `tsconfig.json` and extract the compiler options used for type
+ * resolution.
+ *
+ * @param configPath - Path to tsconfig.json (relative or absolute)
+ * @param projectRoot - Project root directory for resolving relative paths
+ * @returns The declared compiler options, in the tsconfig spelling
+ * @throws TsConfigParseError if the config cannot be read or parsed
+ *
+ * @example
+ * ```ts
+ * const options = parseTsConfig("tsconfig.json", "/path/to/project");
+ * // Returns: { target: "es2025", module: "nodenext", lib: ["esnext"], ... }
+ * ```
+ *
+ * @public
+ */
+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.
+ */
+/**
+ * A virtual file system: file paths (prefixed `node_modules/<package>/`)
+ * mapped to their string contents.
+ *
+ * @remarks
+ * This is the value every loading operation produces and every TypeScript
+ * integration consumes. Maps from multiple packages merge with {@link mergeVfs};
+ * `@typescript/vfs` consumes the merged map directly (see `TsEnvironment`).
+ *
+ * @public
+ */
+type Vfs = Map<string, string>;
+/**
+ * Merge VFS maps left to right into a new map; later entries win on path
+ * collisions.
+ *
+ * @example
+ * ```ts
+ * import { mergeVfs } from "@tsdoctor/vfs";
+ *
+ * const combined = mergeVfs(vfsA, vfsB);
+ * ```
+ *
+ * @public
+ */
+declare const mergeVfs: (...maps: ReadonlyArray<ReadonlyMap<string, string>>) => Vfs;
+/**
+ * Prefix every path in `entries` with `node_modules/<name>/`, normalizing
+ * away leading slashes.
+ *
+ * @public
+ */
+declare const prefixVfs: (name: string, entries: ReadonlyMap<string, string>) => Vfs;
+/**
+ * Whether a path names a TypeScript declaration file.
+ *
+ * @remarks
+ * The single spelling of this predicate. `TsEnvironment` uses it to pick a
+ * VFS map's root files, and `@tsdoctor/registry`'s module resolution uses it
+ * to decide whether a resolved path is a declaration. Two spellings of "is
+ * this a `.d.ts`" would be free to drift, and the drift would be silent — a
+ * root file quietly missing from a TypeScript environment degrades hovers
+ * without producing an error.
+ *
+ * @public
+ */
+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;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Raised when building a virtual TypeScript environment fails — including
+ * when the optional `typescript` / `@typescript/vfs` /
+ * `@effected/tsconfig-json` peers are not installed.
+ *
+ * @public
+ */
+declare class TsEnvironmentError extends TsEnvironmentError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link TsEnvironment.make}.
+ *
+ * @public
+ */
+interface TsEnvironmentOptions {
+  /** The virtual file system to typecheck against. */
+  readonly vfs: Vfs;
+  /**
+   * Compiler options for the language service, in tsconfig JSON form
+   * (`{ target: "es2022" }`, not `ts.ScriptTarget.ES2022`). Enum-valued
+   * fields are converted to the compiler's numeric enums internally, so this
+   * type has no dependency on the `typescript` package.
+   */
+  readonly compilerOptions: CompilerOptions.Type;
+  /**
+   * The directory VFS paths are rooted under and the filesystem fallback
+   * root. Defaults to `process.cwd()` (which v3 hardcoded).
+   */
+  readonly projectRoot?: string;
+}
+/**
+ * The `@typescript/vfs` seam: builds a `VirtualTypeScriptEnvironment` over a
+ * {@link Vfs} plus the TypeScript default lib files.
+ *
+ * @remarks
+ * The ONLY module touching the optional `typescript` / `@typescript/vfs` /
+ * `@effected/tsconfig-json` peers, and it loads all three lazily inside
+ * {@link TsEnvironment.make} — a consumer that never calls it never loads
+ * the compiler, and a missing peer fails typed as
+ * {@link TsEnvironmentError} instead of crashing at import time. Keep every
+ * one of them behind that dynamic `import()`: a static value import here is
+ * reachable from `index.ts`, so it would turn an omitted optional peer into
+ * an `ERR_MODULE_NOT_FOUND` on the entry graph for consumers who never
+ * touch this module. Only the type-only `CompilerOptions` import is safe
+ * statically, because it erases. The underlying `createDefaultMapFromNodeModules` /
+ * `createFSBackedSystem` read the real filesystem through TypeScript's own
+ * `sys`, outside the Effect `FileSystem` service — accepted and documented;
+ * this module is why the package is integrated tier on its own surface.
+ *
+ * No cache map (v3's `createTypeScriptCache` returned a one-entry `Map`
+ * keyed by `JSON.stringify(compilerOptions)`): a consumer that wants keyed
+ * reuse holds its own map.
+ *
+ * `VirtualTypeScriptEnvironment` is deliberately not re-exported — import
+ * the type from `@typescript/vfs`, which consumers of this module already
+ * declare.
+ *
+ * @example
+ * ```ts
+ * import { TsEnvironment } from "@tsdoctor/vfs";
+ *
+ * const environment = TsEnvironment.make({
+ *   vfs,
+ *   compilerOptions: { strict: true, target: "es2022" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class TsEnvironment {
+  private constructor();
+  /** Build a `VirtualTypeScriptEnvironment` over a {@link Vfs}. */
+  static make(options: TsEnvironmentOptions): Effect.Effect<VirtualTypeScriptEnvironment, TsEnvironmentError>;
+}
+//#endregion
+//#region src/TypeScriptConfig.d.ts
+/**
+ * How a caller points at TypeScript configuration: a `tsconfig.json`, inline
+ * compiler options, or both.
+ *
+ * @remarks
+ * When both are given the tsconfig is loaded first and the inline options merge
+ * on top, so a caller can adopt a project's configuration and override one
+ * field without restating it.
+ *
+ * @public
+ */
+interface TypeScriptConfig {
+  /**
+   * A `tsconfig.json` path, or a function returning compiler options.
+   *
+   * @remarks
+   * The function's options are **user input**, so they are typed loosely and
+   * decoded rather than trusted: a caller writing configuration in TypeScript
+   * may reasonably return either the tsconfig spelling (`target: "es2025"`) or
+   * the programmatic one (`target: ts.ScriptTarget.ES2025`).
+   */
+  tsconfig?: PathLike | (() => Promise<CompilerOptionsInput>);
+  /** User-supplied compiler options, in either spelling. Decoded, not trusted. */
+  compilerOptions?: CompilerOptionsInput;
+}
+/**
+ * Compiler options as a user may write them, before decoding.
+ *
+ * @remarks
+ * Deliberately loose. `@tsdoctor/vfs`'s `decodeCompilerOptions` is what turns
+ * this into a `TypeResolutionCompilerOptions`, accepting either spelling
+ * and REJECTING a value it cannot map rather than passing it through. This type
+ * exists so the untrusted shape and the decoded one cannot be confused at a
+ * call site — the previous single type was both, and user input reached the
+ * compiler through a cast.
+ *
+ * @public
+ */
+type CompilerOptionsInput = Readonly<Record<string, unknown>>;
+/**
+ * Default TypeScript compiler options for Twoslash and type resolution.
+ *
+ * These defaults are optimized for documentation:
+ * - Modern ES targets (ESNext)
+ * - Bundler module resolution for broad compatibility
+ * - Lenient settings (non-strict) since docs often show simplified examples
+ * - Skip lib checks for faster processing
+ *
+ * @remarks
+ * Numeric values correspond to TypeScript enums:
+ * - target: 99 = ESNext
+ * - module: 99 = ESNext
+ * - moduleResolution: 100 = Bundler
+ *
+ * @public
+ */
+declare const DEFAULT_COMPILER_OPTIONS: TypeResolutionCompilerOptions;
+/**
+ * Merge one set of compiler options over another, later winning per key.
+ *
+ * @remarks
+ * Arrays (`lib`, `types`) are REPLACED wholesale rather than concatenated,
+ * matching TypeScript's own `extends` semantics: declaring `lib` means "these
+ * libraries", not "these as well as the defaults".
+ *
+ * @param base - the options to start from
+ * @param override - the options to layer on top, or `undefined` for a copy of `base`
+ * @returns a new object; neither argument is mutated
+ *
+ * @public
+ */
+declare function mergeCompilerOptions(base: TypeResolutionCompilerOptions, override: TypeResolutionCompilerOptions | undefined): TypeResolutionCompilerOptions;
+/**
+ * Resolve a single TypeScriptConfig to compiler options (sync version).
+ * Only handles path-based tsconfig - use resolveTypeScriptConfigSingleAsync for function-based.
+ *
+ * Follows the priority cascade:
+ * 1. Parse tsconfig.json if specified (path only, not function)
+ * 2. Merge compilerOptions on top
+ *
+ * @param config - TypeScript config with optional tsconfig path and/or compilerOptions
+ * @param projectRoot - Project root for resolving relative tsconfig paths
+ * @returns Resolved compiler options (not merged with defaults)
+ *
+ * @example
+ * ```ts
+ * // Just tsconfig
+ * resolveTypeScriptConfigSingle({ tsconfig: "tsconfig.json" }, "/project");
+ *
+ * // Just compilerOptions
+ * resolveTypeScriptConfigSingle({ compilerOptions: { target: "esnext" } }, "/project");
+ *
+ * // Both (compilerOptions override tsconfig)
+ * resolveTypeScriptConfigSingle({
+ *   tsconfig: "tsconfig.json",
+ *   compilerOptions: { strict: false }
+ * }, "/project");
+ * ```
+ *
+ * @public
+ */
+declare function resolveTypeScriptConfigSingle(config: TypeScriptConfig | undefined, projectRoot: string): TypeResolutionCompilerOptions;
+/**
+ * Resolve a single TypeScriptConfig to compiler options (async version).
+ * Handles both path-based and function-based tsconfig.
+ *
+ * Follows the priority cascade:
+ * 1. Load tsconfig (from path or function)
+ * 2. Merge compilerOptions on top
+ *
+ * @param config - TypeScript config with optional tsconfig path/function and/or compilerOptions
+ * @param projectRoot - Project root for resolving relative tsconfig paths
+ * @returns Promise resolving to compiler options (not merged with defaults)
+ *
+ * @example
+ * ```ts
+ * // Path-based tsconfig
+ * await resolveTypeScriptConfigSingleAsync({ tsconfig: "tsconfig.json" }, "/project");
+ *
+ * // Function-based tsconfig
+ * await resolveTypeScriptConfigSingleAsync({
+ *   tsconfig: async () => ({ target: 99, lib: ["ESNext"] })
+ * }, "/project");
+ *
+ * // Both (compilerOptions override tsconfig)
+ * await resolveTypeScriptConfigSingleAsync({
+ *   tsconfig: async () => ({ target: 99 }),
+ *   compilerOptions: { strict: false }
+ * }, "/project");
+ * ```
+ *
+ * @public
+ */
+declare function resolveTypeScriptConfigSingleAsync(config: TypeScriptConfig | undefined, projectRoot: string): Promise<TypeResolutionCompilerOptions>;
+/**
+ * Resolve TypeScript compiler options from a cascade of configurations (async).
+ *
+ * Resolution order (later levels override earlier):
+ * 1. DEFAULT_COMPILER_OPTIONS (sensible defaults)
+ * 2. Global config
+ * 3. API-level config
+ *
+ * At each level, if a TypeScriptConfig has both `tsconfig` and `compilerOptions`,
+ * the tsconfig is loaded first, then compilerOptions are merged on top.
+ *
+ * @param projectRoot - Project root directory for resolving relative paths
+ * @param global - Global plugin TypeScript configuration
+ * @param api - API-level TypeScript configuration
+ * @returns Promise resolving to fully resolved compiler options
+ *
+ * @example
+ * ```ts
+ * // Simple global config
+ * const options = await resolveTypeScriptConfig("/project", {
+ *   tsconfig: "tsconfig.json"
+ * });
+ *
+ * // With async tsconfig loader
+ * const options = await resolveTypeScriptConfig("/project", {
+ *   tsconfig: async () => ({ target: 99, lib: ["ESNext"] })
+ * });
+ *
+ * // With API override
+ * const options = await resolveTypeScriptConfig(
+ *   "/project",
+ *   { tsconfig: "tsconfig.json" },
+ *   { compilerOptions: { strict: false } }
+ * );
+ * ```
+ *
+ * @public
+ */
+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;
+  /** The package version. */
+  readonly version: Schema.String;
+  /** Entry file names (e.g. `"index.d.ts"`) mapped to declaration source. */
+  readonly entries: Schema.$ReadonlyMap<Schema.String, Schema.String>;
+}>, {}>;
+/**
+ * A synthetic npm package built from locally supplied TypeScript declaration
+ * content, for inclusion in a {@link Vfs} without fetching from the CDN.
+ *
+ * @remarks
+ * Useful when you have locally generated `.d.ts` files — API Extractor
+ * output, hand-written ambient declarations — and want them in the same VFS
+ * `TypeRegistry` builds from remote packages. Instances are transient: they
+ * are never persisted to the disk cache.
+ *
+ * The class is deliberately subclass-friendly (the rspress consumer extends
+ * it): construct via `VirtualPackage.make(...)` or the statics, and extend
+ * with `class Mine extends VirtualPackage { ... }`.
+ *
+ * @example
+ * ```ts
+ * import { VirtualPackage } from "@tsdoctor/vfs";
+ *
+ * const pkg = VirtualPackage.create("@my-org/api-types", "1.0.0", "export interface User { id: string }");
+ * const vfs = pkg.toVfs();
+ * // node_modules/@my-org/api-types/package.json, node_modules/@my-org/api-types/index.d.ts
+ * ```
+ *
+ * @public
+ */
+declare class VirtualPackage extends VirtualPackage_base {
+  /**
+   * Single-entry factory: a virtual package whose sole entry point is
+   * `index.d.ts`.
+   */
+  static create(name: string, version: string, declarations: string): VirtualPackage;
+  /**
+   * Multi-entry factory: one `.d.ts` per entry point, exposed through a
+   * synthetic `exports` map.
+   *
+   * @remarks
+   * An empty entries map is developer wiring, not input — it would produce a
+   * package whose `types` points at a file that does not exist — so it
+   * throws at construction (defect posture), as does an entry set whose
+   * names collide after extension normalization (see
+   * {@link VirtualPackage.toVfs}).
+   */
+  static createMultiEntry(name: string, version: string, entries: ReadonlyMap<string, string>): VirtualPackage;
+  /**
+   * Load a single `.d.ts` file from disk as a virtual package with one
+   * `index.d.ts` entry.
+   *
+   * @remarks
+   * Reads through the platform-agnostic `FileSystem` service; the
+   * `PlatformError` surfaces typed.
+   */
+  static fromFile(name: string, version: string, filePath: string): Effect.Effect<VirtualPackage, PlatformError.PlatformError, FileSystem.FileSystem>;
+  /**
+   * The package's {@link Vfs}: a synthetic `package.json` plus every entry
+   * file, each path prefixed `node_modules/<name>/`.
+   *
+   * @remarks
+   * The `package.json` uses `types` for a single entry and an `exports` map
+   * for multiple entries, so TypeScript module resolution works against the
+   * generated VFS.
+   */
+  toVfs(): Vfs;
+  private toPackageJson;
+}
+//#endregion
+export { type CompilerOptionsInput, DEFAULT_COMPILER_OPTIONS, TsConfigParseError, TsEnvironment, TsEnvironmentError, type TsEnvironmentOptions, TypeResolutionCompilerOptions, type TypeScriptConfig, type Vfs, VirtualPackage, decodeCompilerOptions, isTypeDefinition, mergeCompilerOptions, mergeVfs, parseTsConfig, prefixVfs, resolveTypeScriptConfig, resolveTypeScriptConfigSingle, resolveTypeScriptConfigSingleAsync, toProgrammaticCompilerOptions };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,8 @@
+import { TypeResolutionCompilerOptions, decodeCompilerOptions, toProgrammaticCompilerOptions } from "./TypeResolutionOptions.js";
+import { TsConfigParseError, parseTsConfig } from "./TsconfigParser.js";
+import { isTypeDefinition, mergeVfs, prefixVfs } from "./Vfs.js";
+import { TsEnvironment, TsEnvironmentError } from "./TsEnvironment.js";
+import { DEFAULT_COMPILER_OPTIONS, mergeCompilerOptions, resolveTypeScriptConfig, resolveTypeScriptConfigSingle, resolveTypeScriptConfigSingleAsync } from "./TypeScriptConfig.js";
+import { VirtualPackage } from "./VirtualPackage.js";
+
+export { DEFAULT_COMPILER_OPTIONS, TsConfigParseError, TsEnvironment, TsEnvironmentError, TypeResolutionCompilerOptions, VirtualPackage, decodeCompilerOptions, isTypeDefinition, mergeCompilerOptions, mergeVfs, parseTsConfig, prefixVfs, resolveTypeScriptConfig, resolveTypeScriptConfigSingle, resolveTypeScriptConfigSingleAsync, toProgrammaticCompilerOptions };