@tsdoctor/vfs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @tsdoctor/vfs
+
+[![npm](https://img.shields.io/npm/v/@tsdoctor%2Fvfs?label=npm&color=cb3837)](https://www.npmjs.com/package/@tsdoctor/vfs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 6.0](https://img.shields.io/badge/TypeScript-6.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+The virtual TypeScript project behind a documentation build: the `Vfs` currency type, declaration-backed virtual packages, `@typescript/vfs` environments over them, and the compiler-option resolution that decides how code in those environments type-checks.
+
+## Why @tsdoctor/vfs
+
+Tooling that type-checks code samples needs a TypeScript project that never touches disk — a map of paths to sources, a synthetic `package.json` so module resolution behaves like the real thing, and a language service built over both. Two independent concerns need exactly that substrate: fetching third-party declarations from a registry, and reconstructing declarations from an API model. This package is the substrate they share, so neither has to depend on the other.
+
+It owns the compiler options too, and that pairing is deliberate. Options arrive in two spellings: the tsconfig one a user writes (`target: "es2022"`), and the programmatic one the compiler takes (`ts.ScriptTarget.ES2022`). A build that converts between them in more than one place will eventually disagree with itself. Here the conversion happens once, options a documentation tool cannot act on are rejected at the boundary instead of cast through it, and the environment that consumes them lives next door.
+
+`@tsdoctor/registry` builds on it to resolve external package types; `@tsdoctor/model` builds on it to turn an API Extractor model into a virtual package.
+
+## Install
+
+```bash
+npm install @tsdoctor/vfs effect @effected/tsconfig-json
+```
+
+```bash
+pnpm add @tsdoctor/vfs effect @effected/tsconfig-json
+```
+
+Requires Node.js >=24.11.0. This is an ESM-only package. `effect` and `@effected/tsconfig-json` are required peers — the compiler-option schemas are built from the kit's own field definitions, so they load with the entry point. `typescript` and `@typescript/vfs` are optional and needed only by `TsEnvironment.make`, which imports them lazily:
+
+```bash
+# for TsEnvironment.make
+npm install typescript @typescript/vfs
+```
+
+A consumer that only builds and merges VFS maps never loads the compiler.
+
+## What you get
+
+### The VFS substrate
+
+- **`Vfs`** — the currency type: a `Map<string, string>` of `node_modules/`-prefixed paths to file contents. Every loading operation produces one and every TypeScript integration consumes one.
+- **`mergeVfs` / `prefixVfs`** — combine maps left to right (later wins on a path collision), and root one package's entries under `node_modules/<name>/`.
+- **`isTypeDefinition`** — whether a path names a declaration file. The single spelling of that predicate.
+- **`VirtualPackage`** — a named, versioned set of declaration entries that renders to a `Vfs` with a synthetic `package.json`. `create` for a single `index.d.ts`, `createMultiEntry` for one declaration file per entry point behind a synthetic `exports` map. Subclass-friendly, which is how an API-model-backed package is built on top of it.
+- **`TsEnvironment.make`** — a `@typescript/vfs` `VirtualTypeScriptEnvironment` over a `Vfs` plus the TypeScript default libs. Takes options in the tsconfig spelling and converts internally, so a caller needs no compile-time dependency on `typescript`. A missing optional peer fails as a typed **`TsEnvironmentError`** rather than crashing at import.
+
+### Compiler-option resolution
+
+- **`TypeResolutionCompilerOptions`** — the whitelist of options allowed to influence how an example type-checks, picked from `@effected/tsconfig-json`'s own field schemas rather than restated. Passing through options the tool does not understand would let an unrelated build setting silently change a documentation build.
+- **`decodeCompilerOptions`** — decode untrusted input in either spelling and narrow it to the whitelist, returning a `Result` that fails on a value the compiler cannot act on instead of casting it through.
+- **`toProgrammaticCompilerOptions`** — the one conversion from the tsconfig spelling to the compiler's numeric enums. Fingerprint the encoded value, not the decoded one, or two spellings of the same configuration build two identical environments under different keys.
+- **`parseTsConfig`** — read a `tsconfig.json` into whitelisted options, with `extends` chain resolution (package specifiers included), JSONC parsing and relative paths owned by `@effected/tsconfig-json`. Failures raise **`TsConfigParseError`** carrying the config path.
+- **`DEFAULT_COMPILER_OPTIONS`** — the documentation defaults: ESNext target and module, bundler resolution, non-strict, `skipLibCheck`, and a `lib` covering ESNext plus DOM. Held in the tsconfig spelling, the same one users write.
+- **`mergeCompilerOptions`** — layer one option set over another, later winning per key. Arrays (`lib`, `types`) are replaced wholesale rather than concatenated, matching TypeScript's own `extends` semantics.
+- **`resolveTypeScriptConfig`** — the full cascade: defaults, then a global config, then a per-API one, each level loading its `tsconfig` before merging its inline `compilerOptions` on top. `resolveTypeScriptConfigSingle` resolves one level synchronously (path-based `tsconfig` only); `resolveTypeScriptConfigSingleAsync` also accepts a `tsconfig` given as a loader function.
+- **`TypeScriptConfig` / `CompilerOptionsInput`** — how a caller points at configuration, and the deliberately loose shape their inline options arrive in before decoding. Two types rather than one, so untrusted input and decoded output cannot be confused at a call site.
+
+## Quick start
+
+Build a virtual package from declaration text, resolve the compiler options an example should be checked under, and type-check against both.
+
+```ts
+import { Effect } from "effect";
+import { TsEnvironment, VirtualPackage, mergeVfs, resolveTypeScriptConfig } from "@tsdoctor/vfs";
+
+const vfs = mergeVfs(
+  VirtualPackage.create(
+    "my-types",
+    "1.0.0",
+    "export declare const answer: number;\nexport interface User { readonly id: string }\n",
+  ).toVfs(),
+);
+console.log([...vfs.keys()]);
+// ["node_modules/my-types/package.json", "node_modules/my-types/index.d.ts"]
+
+// Defaults, then the project's tsconfig, then an inline override on top.
+const compilerOptions = await resolveTypeScriptConfig(process.cwd(), { tsconfig: "tsconfig.json" }, {
+  compilerOptions: { strict: true },
+});
+
+const program = Effect.gen(function* () {
+  const environment = yield* TsEnvironment.make({ vfs, compilerOptions, projectRoot: "/docs" });
+  environment.createFile("/docs/sample.ts", 'import { answer } from "my-types";\nexport const x: number = answer;\n');
+  return environment.languageService.getSemanticDiagnostics("/docs/sample.ts");
+});
+
+console.log((await Effect.runPromise(program)).length);
+// diagnostic count — 0 when the sample type-checks against the virtual package
+```
+
+`resolveTypeScriptConfig` returns the tsconfig spelling, which is what `TsEnvironment.make` takes; nothing in this example needs to import `typescript`.
+
+## Provenance
+
+Extracted from `@tsdoctor/registry`, which had no internal consumer for the VFS half while `@tsdoctor/model` needed it. Hosting these types in the registry would have forced a dependency in one direction or the other — the registry onto an API model it does not read, or the model onto the registry's CDN and cache stack it does not use. The registry kept its own job, fetching and caching external package types into a `Vfs`, and shed the `typescript`, `@typescript/vfs` and `@effected/tsconfig-json` peers along with the environment builder. The compiler-option resolution came from the RSPress adapter, where it sat beside the environment it configures.
+
+## License
+
+[MIT](LICENSE)

package/TsEnvironment.js

@@ -0,0 +1,95 @@
+import { isTypeDefinition } from "./Vfs.js";
+import { Effect, Schema } from "effect";
+
+//#region src/TsEnvironment.ts
+/**
+* Raised when building a virtual TypeScript environment fails — including
+* when the optional `typescript` / `@typescript/vfs` /
+* `@effected/tsconfig-json` peers are not installed.
+*
+* @public
+*/
+var TsEnvironmentError = class extends Schema.TaggedError()("TsEnvironmentError", { 
+/** The underlying failure, preserved structurally. */
+cause: Schema.Defect() }) {
+	get message() {
+		return "Failed to create the virtual TypeScript environment";
+	}
+};
+/**
+* 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
+*/
+var TsEnvironment = class {
+	constructor() {}
+	/** Build a `VirtualTypeScriptEnvironment` over a {@link Vfs}. */
+	static make(options) {
+		return Effect.gen(function* () {
+			const [tsModule, tsVfs, { TsEnumCodec }] = yield* Effect.tryPromise({
+				try: () => Promise.all([
+					import("typescript"),
+					import("@typescript/vfs"),
+					import("@effected/tsconfig-json")
+				]),
+				catch: (cause) => new TsEnvironmentError({ cause })
+			});
+			return yield* Effect.try({
+				try: () => {
+					const typescript = tsModule.default;
+					const projectRoot = options.projectRoot ?? process.cwd();
+					const compilerOptions = TsEnumCodec.encodeCompilerOptions(options.compilerOptions);
+					const executing = typescript.sys?.getExecutingFilePath?.();
+					const libDirectory = executing === void 0 ? void 0 : executing.slice(0, Math.max(executing.lastIndexOf("/"), executing.lastIndexOf("\\")));
+					const system = new Map(tsVfs.createDefaultMapFromNodeModules(compilerOptions, typescript, libDirectory));
+					const rootFiles = [];
+					for (const [path, content] of options.vfs) {
+						const rooted = path.startsWith("/") ? path : `${projectRoot}/${path}`;
+						system.set(rooted, content);
+						if (isTypeDefinition(rooted)) rootFiles.push(rooted);
+					}
+					const sys = tsVfs.createFSBackedSystem(system, projectRoot, typescript, libDirectory);
+					return tsVfs.createVirtualTypeScriptEnvironment(sys, rootFiles, typescript, compilerOptions);
+				},
+				catch: (cause) => new TsEnvironmentError({ cause })
+			});
+		}).pipe(Effect.withSpan("TsEnvironment.make"));
+	}
+};
+
+//#endregion
+export { TsEnvironment, TsEnvironmentError };

package/TsconfigParser.js

@@ -0,0 +1,98 @@
+import { decodeCompilerOptions } from "./TypeResolutionOptions.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { TsconfigLoaderSync } from "@effected/tsconfig-json";
+import { Result } from "effect";
+
+//#region src/TsconfigParser.ts
+/**
+* Reading a `tsconfig.json` into the compiler options the plugin consumes.
+*
+* @remarks
+* A thin adapter over `@effected/tsconfig-json`'s `TsconfigLoaderSync`, which
+* owns `extends` chain resolution (including package specifiers), JSONC
+* parsing and relative-path handling. This module used to hand-roll all three
+* over TypeScript's `parseJsonConfigFileContent`.
+*
+* **The loader returns the tsconfig SPELLING, not the programmatic one.**
+* `target` is `"es2025"` rather than `ts.ScriptTarget.ES2025`, and `lib` is
+* `["esnext"]` rather than `["lib.esnext.d.ts"]`. That is fine, and it is why
+* the normalization seam had to land first: `toProgrammaticCompilerOptions`
+* (`twoslash-transformer.ts`) converts at ONE place, and
+* {@link TypeResolutionCompilerOptions} accepts both spellings by design. Do
+* not convert here — a second conversion site is exactly the drift that made
+* three of four resolution paths load zero lib files once already.
+*
+* @packageDocumentation
+*/
+/**
+* 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
+*/
+var TsConfigParseError = class extends Error {
+	configPath;
+	cause;
+	constructor(configPath, message, cause) {
+		super(`Failed to parse tsconfig at ${configPath}: ${message}`);
+		this.configPath = configPath;
+		this.cause = cause;
+		this.name = "TsConfigParseError";
+	}
+};
+/**
+* The sync host the kit loader reads through.
+*
+* @remarks
+* `node:path` satisfies `SyncPath` verbatim. The filesystem half is two
+* functions, so no shim module is needed.
+*/
+const syncHost = {
+	fileSystem: {
+		exists: existsSync,
+		readFile: (filePath) => readFileSync(filePath, "utf8")
+	},
+	path
+};
+/**
+* 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
+*/
+function parseTsConfig(configPath, projectRoot) {
+	const absolutePath = path.isAbsolute(configPath) ? configPath : path.resolve(projectRoot, configPath);
+	if (!existsSync(absolutePath)) throw new TsConfigParseError(absolutePath, "File not found");
+	let options;
+	try {
+		options = TsconfigLoaderSync.compilerOptions(absolutePath, syncHost);
+	} catch (error) {
+		throw new TsConfigParseError(absolutePath, error instanceof Error ? error.message : String(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/TypeResolutionOptions.js

@@ -0,0 +1,98 @@
+import { CompilerOptions, CompilerOptionsFromProgrammatic, TsEnumCodec } from "@effected/tsconfig-json";
+import { Result, Schema } from "effect";
+
+//#region src/TypeResolutionOptions.ts
+const fields = CompilerOptions.schema.fields;
+/**
+* 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
+*/
+const TypeResolutionCompilerOptions = Schema.Struct({
+	target: fields.target,
+	module: fields.module,
+	moduleResolution: fields.moduleResolution,
+	jsx: fields.jsx,
+	lib: fields.lib,
+	types: fields.types,
+	typeRoots: fields.typeRoots,
+	strict: fields.strict,
+	skipLibCheck: fields.skipLibCheck,
+	esModuleInterop: fields.esModuleInterop,
+	allowSyntheticDefaultImports: fields.allowSyntheticDefaultImports
+});
+/** The whitelisted keys, for narrowing a decoded `CompilerOptions`. */
+const KEYS = Object.keys(TypeResolutionCompilerOptions.fields);
+/**
+* Narrow a decoded `CompilerOptions` to the whitelist.
+*
+* @remarks
+* Empty `lib` / `types` arrays are **dropped rather than passed through**:
+* `lib: []` REPLACES the default library set with nothing (arrays are replaced
+* wholesale, not merged), which would type-check every example against no
+* globals at all. An absent key inherits the default; an empty one does not.
+*/
+const narrow = (decoded) => {
+	const out = {};
+	for (const key of KEYS) {
+		const value = decoded[key];
+		if (value === void 0) continue;
+		if (Array.isArray(value) && value.length === 0) continue;
+		out[key] = value;
+	}
+	return out;
+};
+/**
+* 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
+*/
+const decodeCompilerOptions = (input) => Result.map(Schema.decodeUnknownResult(CompilerOptionsFromProgrammatic)(input), (decoded) => narrow(decoded));
+/**
+* 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
+*/
+const toProgrammaticCompilerOptions = (options) => TsEnumCodec.encodeCompilerOptions(options);
+
+//#endregion
+export { TypeResolutionCompilerOptions, decodeCompilerOptions, toProgrammaticCompilerOptions };

package/TypeScriptConfig.js

@@ -0,0 +1,226 @@
+import { decodeCompilerOptions } from "./TypeResolutionOptions.js";
+import { TsConfigParseError, parseTsConfig } from "./TsconfigParser.js";
+import { Result } from "effect";
+
+//#region src/TypeScriptConfig.ts
+/**
+* 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
+*/
+const DEFAULT_COMPILER_OPTIONS = {
+	target: "esnext",
+	module: "esnext",
+	moduleResolution: "bundler",
+	lib: ["esnext", "dom"],
+	strict: false,
+	skipLibCheck: true,
+	esModuleInterop: true,
+	allowSyntheticDefaultImports: true
+};
+/**
+* Merge two TypeResolutionCompilerOptions objects.
+* Properties from `override` take precedence over `base`.
+*
+* @param base - Base compiler options
+* @param override - Options to merge on top (takes precedence)
+* @returns Merged options
+*
+* @example
+* ```ts
+* const base = { target: 99, lib: ["ESNext"] };
+* const override = { lib: ["ESNext", "DOM"], strict: true };
+* const merged = mergeCompilerOptions(base, override);
+* // Result: { target: 99, lib: ["ESNext", "DOM"], strict: true }
+* ```
+*/
+/**
+* Decode user-supplied compiler options, failing loudly.
+*
+* @remarks
+* The values reaching here are whatever a consumer wrote in their config, in
+* either spelling. A value the enum tables cannot map is REJECTED rather than
+* passed through: degrading to a default would type-check every example
+* against a configuration the user did not ask for, and say nothing about it.
+* `layers/type-environment.ts` turns this throw into a `ConfigValidationError`,
+* which reaches the `issues.json` artifact.
+*/
+function decodeInput(input, source) {
+	const decoded = decodeCompilerOptions(input);
+	if (Result.isFailure(decoded)) throw new TsConfigParseError(source, decoded.failure.message, decoded.failure);
+	return decoded.success;
+}
+/**
+* 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
+*/
+function mergeCompilerOptions(base, override) {
+	if (!override) return { ...base };
+	const merged = { ...base };
+	for (const [key, value] of Object.entries(override)) if (value !== void 0) merged[key] = value;
+	return merged;
+}
+/**
+* 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
+*/
+function resolveTypeScriptConfigSingle(config, projectRoot) {
+	if (!config) return {};
+	let options = {};
+	if (config.tsconfig && typeof config.tsconfig !== "function") {
+		const tsconfigPath = String(config.tsconfig);
+		try {
+			options = parseTsConfig(tsconfigPath, projectRoot);
+		} catch (error) {
+			if (error instanceof TsConfigParseError) throw error;
+			throw new TsConfigParseError(tsconfigPath, error instanceof Error ? error.message : String(error), error);
+		}
+	}
+	if (config.compilerOptions) options = mergeCompilerOptions(options, decodeInput(config.compilerOptions, "compilerOptions"));
+	return options;
+}
+/**
+* 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
+*/
+async function resolveTypeScriptConfigSingleAsync(config, projectRoot) {
+	if (!config) return {};
+	let options = {};
+	if (config.tsconfig) {
+		if (typeof config.tsconfig === "function") options = decodeInput(await config.tsconfig(), "tsconfig()");
+		else {
+			const tsconfigPath = String(config.tsconfig);
+			try {
+				options = parseTsConfig(tsconfigPath, projectRoot);
+			} catch (error) {
+				if (error instanceof TsConfigParseError) throw error;
+				throw new TsConfigParseError(tsconfigPath, error instanceof Error ? error.message : String(error), error);
+			}
+		}
+	}
+	if (config.compilerOptions) options = mergeCompilerOptions(options, decodeInput(config.compilerOptions, "compilerOptions"));
+	return options;
+}
+/**
+* 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
+*/
+async function resolveTypeScriptConfig(projectRoot, global, api) {
+	let options = { ...DEFAULT_COMPILER_OPTIONS };
+	const globalOptions = await resolveTypeScriptConfigSingleAsync(global, projectRoot);
+	options = mergeCompilerOptions(options, globalOptions);
+	const apiOptions = await resolveTypeScriptConfigSingleAsync(api, projectRoot);
+	options = mergeCompilerOptions(options, apiOptions);
+	return options;
+}
+
+//#endregion
+export { DEFAULT_COMPILER_OPTIONS, mergeCompilerOptions, resolveTypeScriptConfig, resolveTypeScriptConfigSingle, resolveTypeScriptConfigSingleAsync };