@effected/tsconfig-json 0.1.0

package/CompilerOptions.js

@@ -0,0 +1,345 @@
+import { Schema, SchemaTransformation } from "effect";
+
+//#region src/CompilerOptions.ts
+/**
+* Case-insensitive literal-union decode; canonical lowercase encode. Module-
+* internal per the task brief — every exported enum schema below is built
+* from it, but the helper itself is not part of the public surface.
+*/
+const caseInsensitiveLiterals = (literals) => Schema.String.pipe(Schema.decodeTo(Schema.Literals(literals), SchemaTransformation.transform({
+	decode: (s) => s.toLowerCase(),
+	encode: (s) => s
+})));
+/**
+* `compilerOptions.target` — the ECMAScript target. `es5` is deprecated in TS
+* 6.0; `es3` has no literal (dead per R1.3 — a `target: "es3"` value fails
+* decode against this schema rather than silently passing through, since
+* `target` itself is a live, typed field).
+*
+* @public
+*/
+const Target = caseInsensitiveLiterals([
+	"es5",
+	"es6",
+	"es2015",
+	"es2016",
+	"es2017",
+	"es2018",
+	"es2019",
+	"es2020",
+	"es2021",
+	"es2022",
+	"es2023",
+	"es2024",
+	"es2025",
+	"esnext"
+]);
+/**
+* `compilerOptions.module` — the module output format. `none`, `amd`, `umd`
+* and `system` are deprecated in TS 6.0.
+*
+* @public
+*/
+const Module = caseInsensitiveLiterals([
+	"none",
+	"commonjs",
+	"amd",
+	"umd",
+	"system",
+	"es6",
+	"es2015",
+	"es2020",
+	"es2022",
+	"esnext",
+	"node16",
+	"node18",
+	"node20",
+	"nodenext",
+	"preserve"
+]);
+/**
+* `compilerOptions.moduleResolution`. `node10`, `node` and `classic` are
+* deprecated in TS 6.0.
+*
+* @public
+*/
+const ModuleResolution = caseInsensitiveLiterals([
+	"node10",
+	"node",
+	"classic",
+	"node16",
+	"nodenext",
+	"bundler"
+]);
+/**
+* `compilerOptions.jsx`. There is no `none` literal — tsc's option map has
+* only these five.
+*
+* @public
+*/
+const Jsx = caseInsensitiveLiterals([
+	"preserve",
+	"react-native",
+	"react-jsx",
+	"react-jsxdev",
+	"react"
+]);
+/** `compilerOptions.newLine`. @public */
+const NewLine = caseInsensitiveLiterals(["crlf", "lf"]);
+/** `compilerOptions.moduleDetection`. @public */
+const ModuleDetection = caseInsensitiveLiterals([
+	"auto",
+	"legacy",
+	"force"
+]);
+/**
+* `compilerOptions.lib` member values — the complete TS 6.0.3 set, lowercase
+* canonical, per R1.2.
+*
+* @public
+*/
+const Lib = caseInsensitiveLiterals([
+	"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"
+]);
+const IgnoreDeprecations = Schema.Literals(["5.0", "6.0"]);
+/**
+* One `compilerOptions.plugins[]` entry: `name` is required and typed; every
+* other key is preserved verbatim (ts-plugin authors attach arbitrary extra
+* configuration).
+*/
+const PluginEntry = Schema.StructWithRest(Schema.Struct({ name: Schema.String }), [Schema.Record(Schema.String, Schema.Unknown)]);
+/**
+* `compilerOptions`, decoded as every R1.3-live boolean, R1.4 string/path/
+* array/record/number, and R1.2 enum field — each `optionalKey` — intersected
+* with a passthrough record so unknown and dead (R1.3 dead-list) keys survive
+* decode and re-encode untouched, per the forward-tolerance constraint.
+*
+* @public
+*/
+const CompilerOptions = Schema.StructWithRest(Schema.Struct({
+	target: Schema.optionalKey(Target),
+	module: Schema.optionalKey(Module),
+	moduleResolution: Schema.optionalKey(ModuleResolution),
+	jsx: Schema.optionalKey(Jsx),
+	newLine: Schema.optionalKey(NewLine),
+	moduleDetection: Schema.optionalKey(ModuleDetection),
+	lib: Schema.optionalKey(Schema.Array(Lib)),
+	ignoreDeprecations: Schema.optionalKey(IgnoreDeprecations),
+	strict: Schema.optionalKey(Schema.Boolean),
+	noImplicitAny: Schema.optionalKey(Schema.Boolean),
+	strictNullChecks: Schema.optionalKey(Schema.Boolean),
+	strictFunctionTypes: Schema.optionalKey(Schema.Boolean),
+	strictBindCallApply: Schema.optionalKey(Schema.Boolean),
+	strictPropertyInitialization: Schema.optionalKey(Schema.Boolean),
+	strictBuiltinIteratorReturn: Schema.optionalKey(Schema.Boolean),
+	noImplicitThis: Schema.optionalKey(Schema.Boolean),
+	useUnknownInCatchVariables: Schema.optionalKey(Schema.Boolean),
+	/** @deprecated Deprecated in TypeScript 6.0 when set to `false`. */
+	alwaysStrict: Schema.optionalKey(Schema.Boolean),
+	noUnusedLocals: Schema.optionalKey(Schema.Boolean),
+	noUnusedParameters: Schema.optionalKey(Schema.Boolean),
+	exactOptionalPropertyTypes: Schema.optionalKey(Schema.Boolean),
+	noImplicitReturns: Schema.optionalKey(Schema.Boolean),
+	noFallthroughCasesInSwitch: Schema.optionalKey(Schema.Boolean),
+	noUncheckedIndexedAccess: Schema.optionalKey(Schema.Boolean),
+	noImplicitOverride: Schema.optionalKey(Schema.Boolean),
+	noPropertyAccessFromIndexSignature: Schema.optionalKey(Schema.Boolean),
+	allowUnusedLabels: Schema.optionalKey(Schema.Boolean),
+	allowUnreachableCode: Schema.optionalKey(Schema.Boolean),
+	noUncheckedSideEffectImports: Schema.optionalKey(Schema.Boolean),
+	allowJs: Schema.optionalKey(Schema.Boolean),
+	checkJs: Schema.optionalKey(Schema.Boolean),
+	resolveJsonModule: Schema.optionalKey(Schema.Boolean),
+	allowArbitraryExtensions: Schema.optionalKey(Schema.Boolean),
+	allowImportingTsExtensions: Schema.optionalKey(Schema.Boolean),
+	rewriteRelativeImportExtensions: Schema.optionalKey(Schema.Boolean),
+	resolvePackageJsonExports: Schema.optionalKey(Schema.Boolean),
+	resolvePackageJsonImports: Schema.optionalKey(Schema.Boolean),
+	/** @deprecated Deprecated in TypeScript 6.0 when set to `false`. */
+	allowSyntheticDefaultImports: Schema.optionalKey(Schema.Boolean),
+	/** @deprecated Deprecated in TypeScript 6.0 when set to `false`. */
+	esModuleInterop: Schema.optionalKey(Schema.Boolean),
+	preserveSymlinks: Schema.optionalKey(Schema.Boolean),
+	allowUmdGlobalAccess: Schema.optionalKey(Schema.Boolean),
+	verbatimModuleSyntax: Schema.optionalKey(Schema.Boolean),
+	isolatedModules: Schema.optionalKey(Schema.Boolean),
+	isolatedDeclarations: Schema.optionalKey(Schema.Boolean),
+	erasableSyntaxOnly: Schema.optionalKey(Schema.Boolean),
+	forceConsistentCasingInFileNames: Schema.optionalKey(Schema.Boolean),
+	declaration: Schema.optionalKey(Schema.Boolean),
+	declarationMap: Schema.optionalKey(Schema.Boolean),
+	emitDeclarationOnly: Schema.optionalKey(Schema.Boolean),
+	sourceMap: Schema.optionalKey(Schema.Boolean),
+	inlineSourceMap: Schema.optionalKey(Schema.Boolean),
+	inlineSources: Schema.optionalKey(Schema.Boolean),
+	removeComments: Schema.optionalKey(Schema.Boolean),
+	importHelpers: Schema.optionalKey(Schema.Boolean),
+	/** @deprecated Deprecated in TypeScript 6.0. */
+	downlevelIteration: Schema.optionalKey(Schema.Boolean),
+	emitBOM: Schema.optionalKey(Schema.Boolean),
+	noEmit: Schema.optionalKey(Schema.Boolean),
+	noEmitHelpers: Schema.optionalKey(Schema.Boolean),
+	noEmitOnError: Schema.optionalKey(Schema.Boolean),
+	preserveConstEnums: Schema.optionalKey(Schema.Boolean),
+	stripInternal: Schema.optionalKey(Schema.Boolean),
+	experimentalDecorators: Schema.optionalKey(Schema.Boolean),
+	emitDecoratorMetadata: Schema.optionalKey(Schema.Boolean),
+	useDefineForClassFields: Schema.optionalKey(Schema.Boolean),
+	noCheck: Schema.optionalKey(Schema.Boolean),
+	composite: Schema.optionalKey(Schema.Boolean),
+	incremental: Schema.optionalKey(Schema.Boolean),
+	disableSourceOfProjectReferenceRedirect: Schema.optionalKey(Schema.Boolean),
+	disableSolutionSearching: Schema.optionalKey(Schema.Boolean),
+	disableReferencedProjectLoad: Schema.optionalKey(Schema.Boolean),
+	assumeChangesOnlyAffectDirectDependencies: Schema.optionalKey(Schema.Boolean),
+	noErrorTruncation: Schema.optionalKey(Schema.Boolean),
+	noLib: Schema.optionalKey(Schema.Boolean),
+	noResolve: Schema.optionalKey(Schema.Boolean),
+	skipDefaultLibCheck: Schema.optionalKey(Schema.Boolean),
+	skipLibCheck: Schema.optionalKey(Schema.Boolean),
+	diagnostics: Schema.optionalKey(Schema.Boolean),
+	extendedDiagnostics: Schema.optionalKey(Schema.Boolean),
+	listFiles: Schema.optionalKey(Schema.Boolean),
+	listFilesOnly: Schema.optionalKey(Schema.Boolean),
+	listEmittedFiles: Schema.optionalKey(Schema.Boolean),
+	explainFiles: Schema.optionalKey(Schema.Boolean),
+	traceResolution: Schema.optionalKey(Schema.Boolean),
+	preserveWatchOutput: Schema.optionalKey(Schema.Boolean),
+	pretty: Schema.optionalKey(Schema.Boolean),
+	disableSizeLimit: Schema.optionalKey(Schema.Boolean),
+	libReplacement: Schema.optionalKey(Schema.Boolean),
+	stableTypeOrdering: Schema.optionalKey(Schema.Boolean),
+	/** @deprecated Deprecated in TypeScript 6.0. */
+	outFile: Schema.optionalKey(Schema.String),
+	outDir: Schema.optionalKey(Schema.String),
+	rootDir: Schema.optionalKey(Schema.String),
+	declarationDir: Schema.optionalKey(Schema.String),
+	sourceRoot: Schema.optionalKey(Schema.String),
+	mapRoot: Schema.optionalKey(Schema.String),
+	tsBuildInfoFile: Schema.optionalKey(Schema.String),
+	/** @deprecated Deprecated in TypeScript 6.0. */
+	baseUrl: Schema.optionalKey(Schema.String),
+	generateCpuProfile: Schema.optionalKey(Schema.String),
+	generateTrace: Schema.optionalKey(Schema.String),
+	typeRoots: Schema.optionalKey(Schema.Array(Schema.String)),
+	rootDirs: Schema.optionalKey(Schema.Array(Schema.String)),
+	jsxFactory: Schema.optionalKey(Schema.String),
+	jsxFragmentFactory: Schema.optionalKey(Schema.String),
+	jsxImportSource: Schema.optionalKey(Schema.String),
+	reactNamespace: Schema.optionalKey(Schema.String),
+	types: Schema.optionalKey(Schema.Array(Schema.String)),
+	customConditions: Schema.optionalKey(Schema.Array(Schema.String)),
+	moduleSuffixes: Schema.optionalKey(Schema.Array(Schema.String)),
+	paths: Schema.optionalKey(Schema.Record(Schema.String, Schema.Array(Schema.String))),
+	plugins: Schema.optionalKey(Schema.Array(PluginEntry)),
+	maxNodeModuleJsDepth: Schema.optionalKey(Schema.Number)
+}), [Schema.Record(Schema.String, Schema.Unknown)]);
+
+//#endregion
+export { CompilerOptions, Jsx, Lib, Module, ModuleDetection, ModuleResolution, NewLine, Target };

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/PortableTsconfig.js

@@ -0,0 +1,138 @@
+//#region src/PortableTsconfig.ts
+const TSCONFIG_SCHEMA_URL = "https://json.schemastore.org/tsconfig";
+/**
+* Boolean `compilerOptions` preserved in a {@link (PortableTsconfig:interface)}: the
+* strict family, module/interop semantics, checking-depth and lib controls,
+* and language-feature switches — every one type-checking behavior, none of
+* them naming a path or producing a build artifact.
+*/
+const PRESERVED_BOOLEAN_OPTIONS = [
+	"strict",
+	"noImplicitAny",
+	"strictNullChecks",
+	"strictFunctionTypes",
+	"strictBindCallApply",
+	"strictPropertyInitialization",
+	"strictBuiltinIteratorReturn",
+	"noImplicitThis",
+	"useUnknownInCatchVariables",
+	"alwaysStrict",
+	"noUnusedLocals",
+	"noUnusedParameters",
+	"exactOptionalPropertyTypes",
+	"noImplicitReturns",
+	"noFallthroughCasesInSwitch",
+	"noUncheckedIndexedAccess",
+	"noImplicitOverride",
+	"noPropertyAccessFromIndexSignature",
+	"allowUnusedLabels",
+	"allowUnreachableCode",
+	"noUncheckedSideEffectImports",
+	"allowJs",
+	"checkJs",
+	"resolveJsonModule",
+	"allowArbitraryExtensions",
+	"allowImportingTsExtensions",
+	"rewriteRelativeImportExtensions",
+	"resolvePackageJsonExports",
+	"resolvePackageJsonImports",
+	"allowSyntheticDefaultImports",
+	"esModuleInterop",
+	"preserveSymlinks",
+	"allowUmdGlobalAccess",
+	"verbatimModuleSyntax",
+	"isolatedModules",
+	"isolatedDeclarations",
+	"erasableSyntaxOnly",
+	"forceConsistentCasingInFileNames",
+	"useDefineForClassFields",
+	"noLib",
+	"skipDefaultLibCheck",
+	"skipLibCheck",
+	"noCheck",
+	"experimentalDecorators",
+	"emitDecoratorMetadata",
+	"importHelpers",
+	"downlevelIteration",
+	"preserveConstEnums"
+];
+/**
+* Enum-valued `compilerOptions` preserved in a {@link (PortableTsconfig:interface)}: the
+* target/module/moduleResolution/jsx/lib family plus `moduleDetection` and
+* `ignoreDeprecations`. `newLine` is deliberately excluded — pure emit
+* formatting, no bearing on type-checking behavior.
+*/
+const PRESERVED_ENUM_OPTIONS = [
+	"target",
+	"module",
+	"moduleResolution",
+	"jsx",
+	"moduleDetection",
+	"lib",
+	"ignoreDeprecations"
+];
+/**
+* Plain-string `compilerOptions` preserved in a {@link (PortableTsconfig:interface)}: the
+* jsx factory/namespace family. None of these name a filesystem path.
+*/
+const PRESERVED_STRING_OPTIONS = [
+	"jsxFactory",
+	"jsxFragmentFactory",
+	"jsxImportSource",
+	"reactNamespace"
+];
+const PRESERVED_OPTIONS = [
+	...PRESERVED_BOOLEAN_OPTIONS,
+	...PRESERVED_ENUM_OPTIONS,
+	...PRESERVED_STRING_OPTIONS
+];
+/**
+* A `ResolvedTsconfig` carries a string `configPath`, an array `extendedPaths`
+* AND an object `compilerOptions`; a bare `CompilerOptions.Type` never carries
+* all three. Every conjunct is required — `CompilerOptions.Type`'s passthrough
+* index signature tolerates any unrecognized key, so a hostile config file can
+* plant a string `configPath` and even an array `extendedPaths` as passthrough
+* keys on a bare options bag (reachable from forward tolerance). The
+* `compilerOptions` conjunct is what makes the discrimination TOTAL: `make`
+* only branches into `input.compilerOptions` when that value is a non-null
+* object it can safely index, so no crafted bag can steer the filter into a
+* `TypeError` at the `source[key]` loop below. (A bag that fakes all three is
+* then read exactly like a `ResolvedTsconfig` — its `compilerOptions` object
+* is filtered, which is the safe outcome.)
+*/
+const isResolvedTsconfig = (input) => typeof input.configPath === "string" && Array.isArray(input.extendedPaths) && typeof input.compilerOptions === "object" && input.compilerOptions !== null;
+/**
+* Project a {@link (ResolvedTsconfig:interface)} or a bare
+* `CompilerOptions.Type` down to a {@link (PortableTsconfig:interface)}: copy
+* only the allow-listed type-semantics options, force `composite: false` and
+* `noEmit: true` regardless of what the source declared, and stamp `$schema`.
+* Every other key — including every unknown passthrough key the source
+* preserved for forward tolerance — is dropped; this is an allow-list, not a
+* deny-list, so an option this package does not yet classify never leaks onto
+* the portable shape by accident.
+*/
+const make = (input) => {
+	const source = isResolvedTsconfig(input) ? input.compilerOptions : input;
+	const compilerOptions = {};
+	for (const key of PRESERVED_OPTIONS) {
+		const value = source[key];
+		if (value !== void 0) compilerOptions[key] = value;
+	}
+	compilerOptions.composite = false;
+	compilerOptions.noEmit = true;
+	return {
+		$schema: TSCONFIG_SCHEMA_URL,
+		compilerOptions
+	};
+};
+/**
+* The portable-tsconfig filter: {@link (PortableTsconfig:variable).make}
+* narrows a resolved or bare compiler-options object to the allow-listed,
+* machine-independent subset described on {@link (PortableTsconfig:interface)}.
+*
+* @public
+*/
+const PortableTsconfig = { make };
+
+//#endregion
+export { PortableTsconfig };

package/README.md

@@ -0,0 +1,96 @@
+# @effected/tsconfig-json
+
+[![npm](https://img.shields.io/npm/v/@effected%2Ftsconfig-json?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/tsconfig-json)
+[![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 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Composable tsconfig.json handling for Effect: document and compiler-option schemas, `extends`-chain resolution with tsc's own merge semantics, nearest-config discovery and a portable-config filter for virtual TypeScript environments. Every parse is JSONC — comments and trailing commas are legal everywhere, exactly as tsc treats them — and options the schemas do not know pass through decode and encode untouched instead of being dropped.
+
+> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
+> development against a single pinned Effect v4 beta. Packages graduate to
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/tsconfig-json
+
+Reading a tsconfig.json correctly means reproducing what tsc does, and what tsc does is more than `JSON.parse` plus `Object.assign`. An `extends` target resolves like a module: a bare specifier walks ancestor `node_modules` directories, a package's `exports` map can redirect or block it, and a `tsconfig` field in its manifest can point somewhere else entirely. Merging the chain is per-field, path options absolutize against the config that declared them rather than the one you loaded, and `${configDir}` substitutes once at the end against the top config's directory. These rules were extracted from the TypeScript compiler's source and encoded here as data-driven tests, so the resolution you get is the resolution tsc computes.
+
+The package does all of this without importing `typescript`, not even as a type. It works at the string level — `"target": "es2023"` stays a string through schema, merge and discovery — and the version-coupled numeric enum mappings live in `TsEnumCodec` as plain data tables, so converting to the numeric shape a real compiler expects is an explicit final step rather than a dependency you carry everywhere. Malformed input always fails through a typed error channel, and the recursive `extends` walk carries cycle and depth guards, because a config file is untrusted input.
+
+## Install
+
+```bash
+npm install @effected/tsconfig-json @effected/jsonc @effected/walker effect
+```
+
+```bash
+pnpm add @effected/tsconfig-json @effected/jsonc @effected/walker effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4, `@effected/jsonc` and `@effected/walker` are peer dependencies; there are no runtime dependencies of its own.
+
+All IO goes through `FileSystem` and `Path` from `effect` core, not a platform package, so a consumer provides them once at the edge (`@effect/platform-node` on Node, `@effect/platform-bun` on Bun) and a test provides `Path.layer` and `FileSystem.layerNoop` straight from core with nothing else installed.
+
+## Quick start
+
+Resolve a config and its full `extends` chain:
+
+```ts
+import { TsconfigLoader } from "@effected/tsconfig-json";
+import { NodeFileSystem, NodePath } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+
+const PlatformLive = Layer.mergeAll(NodeFileSystem.layer, NodePath.layer);
+
+const resolved = await Effect.runPromise(TsconfigLoader.resolve("./tsconfig.json").pipe(Effect.provide(PlatformLive)));
+
+console.log(resolved.extendedPaths);
+// every config on the extends chain as normalized absolute paths, base-most first and your own config last
+console.log(resolved.compilerOptions);
+// the merged options after folding the whole chain — later configs win per field, paths replaced wholesale
+```
+
+Find the nearest config first when you only have a starting directory:
+
+```ts
+import { TsconfigDiscovery } from "@effected/tsconfig-json";
+import { Effect, Option } from "effect";
+
+const nearest = TsconfigDiscovery.findNearest(process.cwd());
+// Effect<Option<string>, never, FileSystem | Path> — absence is Option.none(), never an error
+```
+
+Hand the result to a real compiler by encoding the enum families to their numeric form, or narrow it to the portable subset a virtual TypeScript environment can safely reuse:
+
+```ts
+import { PortableTsconfig, TsEnumCodec } from "@effected/tsconfig-json";
+
+console.log(TsEnumCodec.encodeCompilerOptions({ target: "es2023", strict: true, lib: ["esnext"] }));
+// { target: 10, strict: true, lib: [ 'lib.esnext.d.ts' ] }
+
+console.log(PortableTsconfig.make(resolved).compilerOptions.noEmit);
+// true — always forced, whatever the source config declared
+```
+
+## Features
+
+- `TsconfigJson` / `TsconfigJsonFromString` — the document schema and its JSONC string codec. Comments and trailing commas are legal in every parse; there is no JSON-strict path.
+- `CompilerOptions` — string-level schemas for `compilerOptions`: enum values decode case-insensitively and encode to canonical lowercase, and unknown or removed options survive a round trip as passthrough.
+- `TsconfigLoader.load` / `TsconfigLoader.resolve` — read and decode one config, or resolve its full `extends` chain depth-first with per-branch cycle stacks (diamond chains are legal), a depth guard and tsc's target resolution for relative, rooted and bare-specifier targets including `exports` maps.
+- `ResolvedTsconfig` — the pure merge engine behind `resolve`: per-field merge semantics, path-option absolutization against the declaring config's directory, final `${configDir}` substitution and `pathsBase` provenance, with no filesystem access at all.
+- `TsconfigDiscovery.findNearest` — the nearest `tsconfig.json` (or any filename via `options.filename`) at or above a starting directory, over `@effected/walker`; one unreadable ancestor cannot hide a config above it.
+- `TsEnumCodec` — the string↔numeric enum tables as plain data with zero `typescript` imports. `encodeCompilerOptions` produces the numeric shape `ts.CompilerOptions` expects, with `lib` entries in the file-name form the compiler resolves verbatim; `decodeCompilerOptions` reverses it.
+- `PortableTsconfig.make` — an allow-list projection down to machine-independent type-semantics options, with `composite: false` and `noEmit: true` forced: the slice a virtual TypeScript environment (Twoslash, API Extractor, an in-memory language service) can safely inherit.
+- Typed failures everywhere: a malformed file is a `TsconfigParseError` carrying its path, a broken chain is a `TsconfigExtendsError` with a `not-found` / `cycle` / `depth` / `empty` reason and the full resolution chain, and IO errors flow through as `PlatformError`. Nothing fails as a defect.
+
+## License
+
+[MIT](LICENSE)