@effected/tsconfig-json 0.12.1 → 0.13.0

package/CompilerOptions.js

@@ -3,7 +3,7 @@ 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
+* internal — 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({
@@ -12,7 +12,7 @@ const caseInsensitiveLiterals = (literals) => Schema.String.pipe(Schema.decodeTo
 })));
 /**
 * `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
+* 6.0; `es3` has no literal (a removed value — a `target: "es3"` value fails
 * decode against this schema rather than silently passing through, since
 * `target` itself is a live, typed field).
 *
@@ -94,7 +94,7 @@ const ModuleDetection = caseInsensitiveLiterals([
 ]);
 /**
 * `compilerOptions.lib` member values — the complete TS 6.0.3 set, lowercase
-* canonical, per R1.2.
+* canonical.
 *
 * @public
 */
@@ -215,10 +215,10 @@ const IgnoreDeprecations = Schema.Literals(["5.0", "6.0"]);
 */
 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.
+* `compilerOptions`, decoded as every live boolean, string, path, array,
+* record, number and enum field — each `optionalKey` — intersected with a
+* passthrough record so unknown and removed keys survive decode and re-encode
+* untouched, which keeps the schema tolerant of newer compiler options.
 *
 * @public
 */

package/CompilerOptionsFromProgrammatic.js

@@ -14,7 +14,7 @@ const encodeOut = (encoded) => TsEnumCodec.encodeCompilerOptions(encoded);
 * the three in one object, and `lib` entries in any of their three spellings
 * (`"esnext"`, `"lib.esnext.d.ts"`, an absolute path to the lib file) — producing
 * validated {@link (CompilerOptions:namespace).Type} with canonical lowercase enum
-* strings and short-form `lib`. Unknown and dead keys pass through, exactly as
+* strings and short-form `lib`. Unknown and removed keys pass through, exactly as
 * {@link (CompilerOptions:variable)} itself allows. Decoding is idempotent on
 * already-canonical input.
 *

package/README.md

@@ -7,10 +7,10 @@
 
 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 prerelease. 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
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line 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
@@ -39,7 +39,7 @@ Requires Node.js >=24.11.0. `effect` v4, `@effected/jsonc` and `@effected/walker
 
 All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
 
-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.
+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 core's `Path.layer` plus an in-memory volume from `@effected/memfs` — no platform package installed.
 
 ## Quick start
 

package/ResolvedTsconfig.js

@@ -1,7 +1,7 @@
 //#region src/ResolvedTsconfig.ts
 const CONFIG_DIR_TEMPLATE = `\${configDir}`;
 const CONFIG_DIR_TEMPLATE_LOWER = CONFIG_DIR_TEMPLATE.toLowerCase();
-/** A value is `${configDir}`-prefixed if its leading token matches case-insensitively (E5). */
+/** A value is `${configDir}`-prefixed if its leading token matches case-insensitively. */
 const startsWithConfigDir = (value) => value.slice(0, CONFIG_DIR_TEMPLATE.length).toLowerCase() === CONFIG_DIR_TEMPLATE_LOWER;
 const normalizeSlashes = (p) => p.replace(/\\/g, "/");
 /** POSIX `dirname` over the normalized path; a rootless path yields `"."`. */
@@ -51,10 +51,10 @@ const PATH_STRING_KEYS = [
 ];
 const PATH_LIST_KEYS = ["typeRoots", "rootDirs"];
 /**
-* Apply `transform` to every path-typed compilerOptions surface: the R1.4 path
+* Apply `transform` to every path-typed compilerOptions surface: the path
 * strings and path lists, and — when `includePathsValues` — the `paths` record's
-* values (E5's final phase substitutes those; E5's parse phase leaves them
-* verbatim). Non-string values pass through untouched (forward tolerance).
+* values (the final `${configDir}` phase substitutes those; the parse phase
+* leaves them verbatim). Non-string values pass through untouched (forward tolerance).
 */
 const transformCompilerOptionPaths = (co, transform, includePathsValues) => {
 	const out = { ...co };
@@ -119,7 +119,7 @@ const extractPassthrough = (source, consumed) => {
 	}
 	return out;
 };
-/** Re-root one inherited `files`/`include`/`exclude` entry, exempting absolute and `${configDir}` entries (E4). */
+/** Re-root one inherited `files`/`include`/`exclude` entry, exempting absolute and `${configDir}` entries. */
 const rerootEntry = (prefix, entry) => {
 	if (startsWithConfigDir(entry) || isAbsolutePath(entry)) return entry;
 	return prefix === "" ? entry : `${prefix}/${entry}`;
@@ -211,25 +211,25 @@ const substituteConfigDir = (resolved, finalDir) => {
 var ResolvedTsconfig = class {
 	constructor() {}
 	/**
-	* Absolutize a config's path-typed options (E5) against its own
+	* Absolutize a config's path-typed options against its own
 	* `configDir`, using the injected `join` (`Path.Path.resolve` at the call
 	* site — so an already-absolute value is preserved). `${configDir}`-prefixed
 	* values are exempt (resolved later, in
 	* {@link (ResolvedTsconfig:class).substituteConfigDir}), and `paths`
 	* VALUES stay verbatim. Only `compilerOptions` path surfaces are touched;
-	* `files`/`include`/`exclude` are re-rooted at merge time instead (E4).
+	* `files`/`include`/`exclude` are re-rooted at merge time instead.
 	*/
 	static absolutize = absolutize;
 	/**
-	* Fold one more-derived config onto the accumulated base (E4), derived
-	* winning. The loader (Task 8) applies this across the resolution chain,
+	* Fold one more-derived config onto the accumulated base, derived
+	* winning. The loader applies this across the resolution chain,
 	* own config last. `derivedPath` is the derived config's absolute
 	* normalized path, from which the re-rooting frame and `pathsBase` are
 	* computed.
 	*/
 	static merge = merge;
 	/**
-	* The E5 final phase: replace a leading `${configDir}` token
+	* The final phase: replace a leading `${configDir}` token
 	* (case-insensitive, leading position only) with `finalDir` — the
 	* top-level extending config's directory — across every eligible
 	* surface: compilerOptions path options, `paths` values,

package/TsEnumCodec.js

@@ -2,9 +2,9 @@ import { Option } from "effect";
 
 //#region src/TsEnumCodec.ts
 /**
-* Builds a family's forward/reverse maps from its R1.6 row order. The
+* Builds a family's forward/reverse maps from its row order. The
 * reverse map overwrites on every duplicate value, so the last-listed name
-* for a value is canonical — exactly R1.6's alias/canonical rule.
+* for a value is canonical.
 */
 const buildTable = (rows) => {
 	const forward = /* @__PURE__ */ new Map();
@@ -101,7 +101,7 @@ const normalizeLibReference = (lib) => {
 	const withoutPrefix = base.startsWith("lib.") ? base.slice(4) : base;
 	return withoutPrefix.endsWith(".d.ts") ? withoutPrefix.slice(0, -5) : withoutPrefix;
 };
-/** `compilerOptions` keys whose values are one of the R1.6 enum families. */
+/** `compilerOptions` keys whose values are one of the enum families. */
 const COMPILER_OPTION_ENUM_KEYS = [
 	["target", "target"],
 	["module", "module"],
@@ -139,7 +139,7 @@ const decodeCompilerOptions = (numeric) => {
 };
 /**
 * The string↔numeric enum codec for `compilerOptions` / `watchOptions`
-* families, per R1.6. Plain data: every lookup is a synchronous map read
+* families. Plain data: every lookup is a synchronous map read
 * returning `Option.Option`, never a thrown error.
 *
 * @public
@@ -169,8 +169,8 @@ var TsEnumCodec = class {
 	/**
 	* Encodes a decoded `compilerOptions` object into the
 	* numeric-enum-shaped {@link ProgrammaticCompilerOptions} form
-	* `ts.CompilerOptions` (and `@typescript/vfs`'s `TsEnvironment`) expect:
-	* every R1.6 enum family becomes its numeric value, and `lib` entries
+	* `ts.CompilerOptions` (and `@typescript/vfs`'s virtual environment) expect:
+	* every enum family becomes its numeric value, and `lib` entries
 	* become the file-name form (`lib.esnext.d.ts`) — see the module banner
 	* for the evidence. Every other key (booleans, strings, arrays, unknown
 	* passthrough keys) is copied through untouched.
@@ -189,7 +189,7 @@ var TsEnumCodec = class {
 	* Decodes a numeric-enum-shaped `compilerOptions` object (as produced by
 	* {@link TsEnumCodec.encodeCompilerOptions} or read off a live
 	* `ts.CompilerOptions`) back into the string-enum shape this package's
-	* schemas use: every R1.6 enum family becomes its canonical string, and
+	* schemas use: every enum family becomes its canonical string, and
 	* `lib` entries become the short form. A numeric value with no table
 	* entry — a future TS enum member — is left as-is (passthrough, never an
 	* error) — which is why the return type stays the wider

package/TsconfigDiscovery.js

@@ -11,6 +11,18 @@ const findNearest = (start, options) => Effect.gen(function* () {
 /**
 * Nearest-config upward discovery for `tsconfig.json`.
 *
+* @example
+* ```ts
+* import { TsconfigDiscovery } from "@effected/tsconfig-json";
+* import { Effect, Option } from "effect";
+*
+* // Requires `FileSystem` and `Path` in `R`; provide them from a platform layer.
+* const program = Effect.gen(function* () {
+* 	const found = yield* TsconfigDiscovery.findNearest(process.cwd());
+* 	return Option.getOrUndefined(found);
+* });
+* ```
+*
 * @public
 */
 var TsconfigDiscovery = class {

package/TsconfigJson.js

@@ -38,14 +38,14 @@ const FallbackPolling = caseInsensitiveLiterals([
 ]);
 /**
 * One `references[]` entry: `path` is required and non-empty; every other key
-* is preserved verbatim (per R1.5).
+* is preserved verbatim.
 *
 * @public
 */
 const Reference = Schema.StructWithRest(Schema.Struct({ path: Schema.String.check(Schema.isMinLength(1)) }), [Schema.Record(Schema.String, Schema.Unknown)]);
 /**
-* `watchOptions` — the three enum fields (R1.2), the two live booleans/arrays
-* (R1.5), and a passthrough record (schemastore's `force` is phantom).
+* `watchOptions` — the three enum fields, the two live booleans/arrays,
+* and a passthrough record (schemastore's `force` is phantom).
 *
 * @public
 */
@@ -58,7 +58,7 @@ const WatchOptions = Schema.StructWithRest(Schema.Struct({
 	excludeFiles: Schema.optionalKey(Schema.Array(Schema.String))
 }), [Schema.Record(Schema.String, Schema.Unknown)]);
 /**
-* `typeAcquisition` — per R1.5.
+* `typeAcquisition` — the automatic type-acquisition settings, with unknown keys preserved.
 *
 * @public
 */
@@ -69,7 +69,7 @@ const TypeAcquisition = Schema.StructWithRest(Schema.Struct({
 	disableFilenameBasedTypeAcquisition: Schema.optionalKey(Schema.Boolean)
 }), [Schema.Record(Schema.String, Schema.Unknown)]);
 /**
-* The tsconfig.json document: every typed top-level field (R1.1) optional,
+* The tsconfig.json document: every typed top-level field optional,
 * plus a passthrough record so unrecognized keys (`buildOptions`, `ts-node`,
 * …) survive decode and re-encode untouched — tsc itself silently ignores
 * unknown top-level keys, and this schema follows suit.
@@ -91,10 +91,9 @@ const TsconfigJson = Schema.StructWithRest(Schema.Struct({
 /**
 * Decodes a JSONC-encoded tsconfig.json document straight into
 * {@link (TsconfigJson:variable)}. Bound once at module top level —
-* `Jsonc.schema` is schema-producing, and this is the shared instance (the
-* house `FromString` idiom, R3.3; `TsconfigJson` is a `Schema.StructWithRest`
-* value rather than a `Schema.Class`, so the codec is a sibling export, not a
-* static).
+* `Jsonc.schema` is schema-producing, and this is the shared instance
+* (`TsconfigJson` is a `Schema.StructWithRest` value rather than a
+* `Schema.Class`, so the codec is a sibling export, not a static).
 *
 * @public
 */
@@ -102,8 +101,8 @@ const TsconfigJsonFromString = Jsonc.schema(TsconfigJson);
 /**
 * Raised when a tsconfig.json document fails to parse or decode. `path` is
 * the file path when the failure is file-bound, and the empty string
-* otherwise (e.g. decoding an in-memory string). The loader (Task 8) wraps
-* file-bound decode failures in this error; this module only declares it.
+* otherwise (e.g. decoding an in-memory string). `TsconfigLoader` wraps
+* file-bound decode failures in this error.
 *
 * @public
 */

package/TsconfigLoader.js

@@ -132,6 +132,18 @@ const compilerOptions = Effect.fn("TsconfigLoader.compilerOptions")(function* (c
 * merge -\> `${configDir}` pipeline, and {@link TsconfigLoader.compilerOptions}
 * projects the resolved result down to its merged `compilerOptions`.
 *
+* @example
+* ```ts
+* import { TsconfigLoader } from "@effected/tsconfig-json";
+* import { Effect } from "effect";
+*
+* // Requires `FileSystem` and `Path` in `R`; provide them from a platform layer.
+* const program = Effect.gen(function* () {
+* 	const resolved = yield* TsconfigLoader.resolve("./tsconfig.json");
+* 	return resolved.compilerOptions.target;
+* });
+* ```
+*
 * @public
 */
 var TsconfigLoader = class {
@@ -147,10 +159,10 @@ var TsconfigLoader = class {
 	/**
 	* Resolve a tsconfig.json and its full `extends` chain into a
 	* {@link (ResolvedTsconfig:interface)}: load and decode each config,
-	* absolutize its path options (E5), resolve `extends` depth-first with
-	* per-branch cycle and depth guards (E1-E3, E6), fold the chain
-	* own-config-last (E4), then substitute a leading `${configDir}` once
-	* against the top config's directory (E5 final phase). `configPath` +
+	* absolutize its path options, resolve `extends` depth-first with
+	* per-branch cycle and depth guards, fold the chain
+	* own-config-last, then substitute a leading `${configDir}` once
+	* against the top config's directory. `configPath` +
 	* `extendedPaths` come back base-most first, own config last. Every
 	* failure is a typed error — `TsconfigParseError` (a malformed file,
 	* carrying that file's path), `TsconfigExtendsError` (a broken chain), or

package/index.d.ts

@@ -2,7 +2,7 @@ import { Effect, FileSystem, Option, Path, PlatformError, Schema } from "effect"
 //#region src/CompilerOptions.d.ts
 /**
  * `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
+ * 6.0; `es3` has no literal (a removed value — a `target: "es3"` value fails
  * decode against this schema rather than silently passing through, since
  * `target` itself is a live, typed field).
  *
@@ -36,16 +36,16 @@ export declare const NewLine: Schema.decodeTo<Schema.Literals<readonly ["crlf",
 export declare const ModuleDetection: Schema.decodeTo<Schema.Literals<readonly ["auto", "legacy", "force"]>, Schema.String, never, never>;
 /**
  * `compilerOptions.lib` member values — the complete TS 6.0.3 set, lowercase
- * canonical, per R1.2.
+ * canonical.
  *
  * @public
  */
 export declare const Lib: 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>;
 /**
- * `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.
+ * `compilerOptions`, decoded as every live boolean, string, path, array,
+ * record, number and enum field — each `optionalKey` — intersected with a
+ * passthrough record so unknown and removed keys survive decode and re-encode
+ * untouched, which keeps the schema tolerant of newer compiler options.
  *
  * @public
  */
@@ -212,7 +212,7 @@ interface ProgrammaticRecord {
  * the three in one object, and `lib` entries in any of their three spellings
  * (`"esnext"`, `"lib.esnext.d.ts"`, an absolute path to the lib file) — producing
  * validated {@link (CompilerOptions:namespace).Type} with canonical lowercase enum
- * strings and short-form `lib`. Unknown and dead keys pass through, exactly as
+ * strings and short-form `lib`. Unknown and removed keys pass through, exactly as
  * {@link (CompilerOptions:variable)} itself allows. Decoding is idempotent on
  * already-canonical input.
  *
@@ -280,7 +280,7 @@ export declare const WatchDirectory: Schema.decodeTo<Schema.Literals<readonly ["
 export declare const FallbackPolling: Schema.decodeTo<Schema.Literals<readonly ["fixedinterval", "priorityinterval", "dynamicpriority", "fixedchunksize"]>, Schema.String, never, never>;
 /**
  * One `references[]` entry: `path` is required and non-empty; every other key
- * is preserved verbatim (per R1.5).
+ * is preserved verbatim.
  *
  * @public
  */
@@ -307,8 +307,8 @@ export declare namespace Reference {
   type Encoded = typeof Reference.Encoded;
 }
 /**
- * `watchOptions` — the three enum fields (R1.2), the two live booleans/arrays
- * (R1.5), and a passthrough record (schemastore's `force` is phantom).
+ * `watchOptions` — the three enum fields, the two live booleans/arrays,
+ * and a passthrough record (schemastore's `force` is phantom).
  *
  * @public
  */
@@ -340,7 +340,7 @@ export declare namespace WatchOptions {
   type Encoded = typeof WatchOptions.Encoded;
 }
 /**
- * `typeAcquisition` — per R1.5.
+ * `typeAcquisition` — the automatic type-acquisition settings, with unknown keys preserved.
  *
  * @public
  */
@@ -370,7 +370,7 @@ export declare namespace TypeAcquisition {
   type Encoded = typeof TypeAcquisition.Encoded;
 }
 /**
- * The tsconfig.json document: every typed top-level field (R1.1) optional,
+ * The tsconfig.json document: every typed top-level field optional,
  * plus a passthrough record so unrecognized keys (`buildOptions`, `ts-node`,
  * …) survive decode and re-encode untouched — tsc itself silently ignores
  * unknown top-level keys, and this schema follows suit.
@@ -539,10 +539,9 @@ export declare namespace TsconfigJson {
 /**
  * Decodes a JSONC-encoded tsconfig.json document straight into
  * {@link (TsconfigJson:variable)}. Bound once at module top level —
- * `Jsonc.schema` is schema-producing, and this is the shared instance (the
- * house `FromString` idiom, R3.3; `TsconfigJson` is a `Schema.StructWithRest`
- * value rather than a `Schema.Class`, so the codec is a sibling export, not a
- * static).
+ * `Jsonc.schema` is schema-producing, and this is the shared instance
+ * (`TsconfigJson` is a `Schema.StructWithRest` value rather than a
+ * `Schema.Class`, so the codec is a sibling export, not a static).
  *
  * @public
  */
@@ -556,8 +555,8 @@ declare const TsconfigParseError_base: Schema.Class<TsconfigParseError, Schema.T
 /**
  * Raised when a tsconfig.json document fails to parse or decode. `path` is
  * the file path when the failure is file-bound, and the empty string
- * otherwise (e.g. decoding an in-memory string). The loader (Task 8) wraps
- * file-bound decode failures in this error; this module only declares it.
+ * otherwise (e.g. decoding an in-memory string). `TsconfigLoader` wraps
+ * file-bound decode failures in this error.
  *
  * @public
  */
@@ -568,7 +567,7 @@ export declare class TsconfigParseError extends TsconfigParseError_base {
 //#region src/ResolvedTsconfig.d.ts
 /**
  * The result of resolving a tsconfig.json's full `extends` chain: the merged
- * compiler options and inherited settings, flattened per R2/E4, with enough
+ * compiler options and inherited settings, flattened the way tsc does, with enough
  * provenance for the consumer (`configPath`, `extendedPaths`, and `pathsBase`,
  * the directory of the config that declared `paths`). Unknown top-level keys
  * survive as passthrough via the index signature.
@@ -596,7 +595,7 @@ export interface ResolvedTsconfig {
   readonly typeAcquisition?: TypeAcquisition.Type;
   /** `compileOnSave`, inherited only when own is undefined and the inherited value is truthy. */
   readonly compileOnSave?: boolean;
-  /** The directory of the config that declared `paths` (E4), against which `paths` values resolve. */
+  /** The directory of the config that declared `paths`, against which `paths` values resolve. */
   readonly pathsBase?: string;
   /** Unknown top-level keys, preserved through the merge (forward tolerance). */
   readonly [key: string]: unknown;
@@ -612,25 +611,25 @@ export interface ResolvedTsconfig {
 export declare class ResolvedTsconfig {
   private constructor();
   /**
-   * Absolutize a config's path-typed options (E5) against its own
+   * Absolutize a config's path-typed options against its own
    * `configDir`, using the injected `join` (`Path.Path.resolve` at the call
    * site — so an already-absolute value is preserved). `${configDir}`-prefixed
    * values are exempt (resolved later, in
    * {@link (ResolvedTsconfig:class).substituteConfigDir}), and `paths`
    * VALUES stay verbatim. Only `compilerOptions` path surfaces are touched;
-   * `files`/`include`/`exclude` are re-rooted at merge time instead (E4).
+   * `files`/`include`/`exclude` are re-rooted at merge time instead.
    */
   static readonly absolutize: (doc: TsconfigJson.Type, configDir: string, join: (a: string, b: string) => string) => TsconfigJson.Type;
   /**
-   * Fold one more-derived config onto the accumulated base (E4), derived
-   * winning. The loader (Task 8) applies this across the resolution chain,
+   * Fold one more-derived config onto the accumulated base, derived
+   * winning. The loader applies this across the resolution chain,
    * own config last. `derivedPath` is the derived config's absolute
    * normalized path, from which the re-rooting frame and `pathsBase` are
    * computed.
    */
   static readonly merge: (base: ResolvedTsconfig, derived: TsconfigJson.Type, derivedPath: string) => ResolvedTsconfig;
   /**
-   * The E5 final phase: replace a leading `${configDir}` token
+   * The final phase: replace a leading `${configDir}` token
    * (case-insensitive, leading position only) with `finalDir` — the
    * top-level extending config's directory — across every eligible
    * surface: compilerOptions path options, `paths` values,
@@ -729,6 +728,18 @@ interface FindNearestOptions {
 /**
  * Nearest-config upward discovery for `tsconfig.json`.
  *
+ * @example
+ * ```ts
+ * import { TsconfigDiscovery } from "@effected/tsconfig-json";
+ * import { Effect, Option } from "effect";
+ *
+ * // Requires `FileSystem` and `Path` in `R`; provide them from a platform layer.
+ * const program = Effect.gen(function* () {
+ * 	const found = yield* TsconfigDiscovery.findNearest(process.cwd());
+ * 	return Option.getOrUndefined(found);
+ * });
+ * ```
+ *
  * @public
  */
 export declare class TsconfigDiscovery {
@@ -775,6 +786,18 @@ export declare class TsconfigExtendsError extends TsconfigExtendsError_base {
  * merge -\> `${configDir}` pipeline, and {@link TsconfigLoader.compilerOptions}
  * projects the resolved result down to its merged `compilerOptions`.
  *
+ * @example
+ * ```ts
+ * import { TsconfigLoader } from "@effected/tsconfig-json";
+ * import { Effect } from "effect";
+ *
+ * // Requires `FileSystem` and `Path` in `R`; provide them from a platform layer.
+ * const program = Effect.gen(function* () {
+ * 	const resolved = yield* TsconfigLoader.resolve("./tsconfig.json");
+ * 	return resolved.compilerOptions.target;
+ * });
+ * ```
+ *
  * @public
  */
 export declare class TsconfigLoader {
@@ -936,10 +959,10 @@ export declare class TsconfigLoader {
   /**
    * Resolve a tsconfig.json and its full `extends` chain into a
    * {@link (ResolvedTsconfig:interface)}: load and decode each config,
-   * absolutize its path options (E5), resolve `extends` depth-first with
-   * per-branch cycle and depth guards (E1-E3, E6), fold the chain
-   * own-config-last (E4), then substitute a leading `${configDir}` once
-   * against the top config's directory (E5 final phase). `configPath` +
+   * absolutize its path options, resolve `extends` depth-first with
+   * per-branch cycle and depth guards, fold the chain
+   * own-config-last, then substitute a leading `${configDir}` once
+   * against the top config's directory. `configPath` +
    * `extendedPaths` come back base-most first, own config last. Every
    * failure is a typed error — `TsconfigParseError` (a malformed file,
    * carrying that file's path), `TsconfigExtendsError` (a broken chain), or
@@ -1200,8 +1223,7 @@ export declare class TsconfigLoaderSync {
 //#endregion
 //#region src/TsEnumCodec.d.ts
 /**
- * The nine `compilerOptions` / `watchOptions` enum families this codec knows,
- * per R1.6.
+ * The nine `compilerOptions` / `watchOptions` enum families this codec knows.
  *
  * @public
  */
@@ -1290,7 +1312,7 @@ interface ProgrammaticCompilerOptions {
 }
 /**
  * The string↔numeric enum codec for `compilerOptions` / `watchOptions`
- * families, per R1.6. Plain data: every lookup is a synchronous map read
+ * families. Plain data: every lookup is a synchronous map read
  * returning `Option.Option`, never a thrown error.
  *
  * @public
@@ -1320,8 +1342,8 @@ export declare class TsEnumCodec {
   /**
    * Encodes a decoded `compilerOptions` object into the
    * numeric-enum-shaped {@link ProgrammaticCompilerOptions} form
-   * `ts.CompilerOptions` (and `@typescript/vfs`'s `TsEnvironment`) expect:
-   * every R1.6 enum family becomes its numeric value, and `lib` entries
+   * `ts.CompilerOptions` (and `@typescript/vfs`'s virtual environment) expect:
+   * every enum family becomes its numeric value, and `lib` entries
    * become the file-name form (`lib.esnext.d.ts`) — see the module banner
    * for the evidence. Every other key (booleans, strings, arrays, unknown
    * passthrough keys) is copied through untouched.
@@ -1340,7 +1362,7 @@ export declare class TsEnumCodec {
    * Decodes a numeric-enum-shaped `compilerOptions` object (as produced by
    * {@link TsEnumCodec.encodeCompilerOptions} or read off a live
    * `ts.CompilerOptions`) back into the string-enum shape this package's
-   * schemas use: every R1.6 enum family becomes its canonical string, and
+   * schemas use: every enum family becomes its canonical string, and
    * `lib` entries become the short form. A numeric value with no table
    * entry — a future TS enum member — is left as-is (passthrough, never an
    * error) — which is why the return type stays the wider

package/internal/extendsTarget.js

@@ -4,8 +4,8 @@ import { Jsonc } from "@effected/jsonc";
 
 //#region src/internal/extendsTarget.ts
 /**
-* The `extends` target-resolution engine (E1 relative/rooted, E2 bare-specifier
-* node_modules lookup). Every input reaching {@link resolveExports} is an
+* The `extends` target-resolution engine (relative/rooted specifiers and the bare-specifier
+* `node_modules` lookup). Every input reaching {@link resolveExports} is an
 * untrusted `package.json` `exports` map, so every recursive surface carries a
 * depth guard, every untrusted map read goes through `Object.hasOwn`, dunder
 * keys are skipped, and substituted maps are built with `Object.create(null)` —
@@ -155,7 +155,7 @@ const readManifest = (fs, manifestPath) => Effect.gen(function* () {
 /** Read an own property of an untrusted record, guarding dunder keys and inherited members. */
 const ownProp = (record, key) => !DUNDER_KEYS.has(key) && Object.hasOwn(record, key) ? record[key] : void 0;
 /**
-* Resolve E1 relative/rooted targets: the exact file wins verbatim (even
+* Resolve relative/rooted targets: the exact file wins verbatim (even
 * extensionless); otherwise, if the target does not already end in `.json`, the
 * `.json`-appended path is tried. There is no directory fallback.
 */
@@ -206,8 +206,8 @@ const tryCandidate = (fs, path, dir, pkg, subpath) => Effect.gen(function* () {
 });
 /**
 * Resolve an `extends` target to an absolute config path. Relative and rooted
-* specifiers (E1) resolve against the extending config's directory; bare
-* specifiers (E2) walk up the ancestor `node_modules` chain, skipping ancestors
+* specifiers resolve against the extending config's directory; bare
+* specifiers walk up the ancestor `node_modules` chain, skipping ancestors
 * named `node_modules`, and resolve against the first package found.
 *
 * Absence is `Option.none()`; a malformed manifest is coerced to an empty one

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/tsconfig-json",
-	"version": "0.12.1",
+	"version": "0.13.0",
 	"private": false,
 	"description": "Composable tsconfig.json handling for Effect: schemas, extends-chain resolution, and config discovery.",
 	"keywords": [
@@ -39,9 +39,10 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.14.0",
-		"@effected/walker": "^0.14.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/glob": "^0.10.0",
+		"@effected/jsonc": "^0.15.0",
+		"@effected/walker": "^0.15.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"