@effected/tsconfig-json 0.3.1 → 0.3.3

package/PortableTsconfig.js

@@ -101,16 +101,6 @@ const PRESERVED_OPTIONS = [
 * 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 = {};
@@ -126,13 +116,27 @@ const make = (input) => {
 	};
 };
 /**
-* The portable-tsconfig filter: {@link (PortableTsconfig:variable).make}
+* The portable-tsconfig filter: {@link (PortableTsconfig:class).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 };
+var PortableTsconfig = class {
+	constructor() {}
+	/**
+	* 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.
+	*/
+	static make = make;
+};
 
 //#endregion
 export { PortableTsconfig };

package/README.md

@@ -104,6 +104,47 @@ const compilerOptions = TsconfigLoaderSync.compilerOptions("./tsconfig.json", op
 
 `load` and `resolve` have the same synchronous forms. Failures are the async pipeline's own typed errors thrown as themselves — `TsconfigParseError`, `TsconfigExtendsError` or a `PlatformError` wrapping whatever your `readFile` threw — never a fiber-failure wrapper.
 
+## TypeScript 7 and the classic compiler API
+
+TypeScript 7's native `tsc` ships a version-only stub as its `.` export — there is no JS compiler API behind it. A package that drives the typechecker as a library (`@typescript/vfs`, the language service, the Program API) can neither type against nor runtime-load a TypeScript 7 install, and the obvious fix of pinning the dev `typescript` back to 6 forfeits the native `tsc` and leaves toolchain peers on `^7` unmet. The recipe that keeps both starts here, because this package is what removes the compile-time half of the dependency.
+
+1. Type against the tsconfig JSON form, not the compiler. Public option types use `CompilerOptions.Type` — `{ target: "es2022" }`, strings all the way down — so nothing in `src` or the tests imports `typescript`, not even as a type. The dev `typescript` stays on 7, native `tsc --noEmit` still runs the typecheck, and the toolchain's `^7` peer stays satisfied.
+2. Convert at a single runtime seam. `TsEnumCodec.encodeCompilerOptions` maps the string form to the numeric enums a real compiler expects and returns `ProgrammaticCompilerOptions`, the shape a `ts.CompilerOptions`-typed API takes without a cast. Only that one call site knows a compiler exists.
+3. Alias a classic install for the test runtime, where the JS API is genuinely needed: a dev-only `"typescript-classic": "npm:typescript@^6.0.3"` plus a vitest `resolve.alias` mapping `typescript` to it. The consumer-facing peer stays an optional `^6` — runtime-only, for callers of the compiler-touching module.
+4. Pass `tsLibDirectory` explicitly when you drive `@typescript/vfs`. It locates `lib.*.d.ts` through `require.resolve("typescript")`, which under this setup resolves the TypeScript 7 install, and that install has no lib directory: the map comes back **empty**, silently, with no error to follow. Derive the directory from the module you actually loaded.
+
+```json
+{
+  "devDependencies": {
+    "typescript-classic": "npm:typescript@^6.0.3"
+  }
+}
+```
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: { alias: { typescript: "typescript-classic" } },
+});
+```
+
+```ts
+import { dirname } from "node:path";
+import { TsEnumCodec } from "@effected/tsconfig-json";
+import { createDefaultMapFromNodeModules } from "@typescript/vfs";
+import ts from "typescript";
+
+const fsMap = createDefaultMapFromNodeModules(
+  TsEnumCodec.encodeCompilerOptions({ target: "es2023", lib: ["esnext"] }),
+  ts,
+  dirname(ts.sys.getExecutingFilePath()),
+);
+
+console.log(fsMap.size);
+// the lib files the loaded compiler ships; drop the third argument and this is 0
+```
+
 ## 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.

package/ResolvedTsconfig.js

@@ -72,16 +72,6 @@ const transformCompilerOptionPaths = (co, transform, includePathsValues) => {
 	}
 	return out;
 };
-/**
-* Absolutize a config's path-typed options (E5) 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:variable).substituteConfigDir}), and
-* `paths` VALUES stay verbatim. Only `compilerOptions` path surfaces are
-* touched; `files`/`include`/`exclude` are re-rooted at merge time instead (E4).
-*
-* @public
-*/
 const absolutize = (doc, configDir, join) => {
 	const co = doc.compilerOptions;
 	if (co === void 0) return doc;
@@ -153,14 +143,6 @@ const mergeWatchOptions = (base, derived) => {
 		...derived
 	};
 };
-/**
-* Fold one more-derived config onto the accumulated base (E4), derived winning.
-* The loader (Task 8) 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.
-*
-* @public
-*/
 const merge = (base, derived, derivedPath) => {
 	const finalDir = dirname(derivedPath);
 	const baseDir = dirname(base.configPath);
@@ -202,15 +184,6 @@ const substituteWatchExcludes = (wo, substitute) => {
 	}
 	return out;
 };
-/**
-* The E5 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, `files`/`include`/`exclude`, and `watchOptions`'
-* `excludeDirectories`/`excludeFiles`. Every other field is left untouched.
-*
-* @public
-*/
 const substituteConfigDir = (resolved, finalDir) => {
 	const substitute = (value) => startsWithConfigDir(value) ? finalDir + value.slice(CONFIG_DIR_TEMPLATE.length) : value;
 	const compilerOptions = transformCompilerOptionPaths(resolved.compilerOptions, substitute, true);
@@ -229,16 +202,42 @@ const substituteConfigDir = (resolved, finalDir) => {
 };
 /**
 * The pure extends-merge engine: parse-time path absolutization
-* ({@link (ResolvedTsconfig:variable).absolutize}), the per-field merge fold
-* ({@link (ResolvedTsconfig:variable).merge}), and the `${configDir}` final
-* phase ({@link (ResolvedTsconfig:variable).substituteConfigDir}).
+* ({@link (ResolvedTsconfig:class).absolutize}), the per-field merge fold
+* ({@link (ResolvedTsconfig:class).merge}), and the `${configDir}` final
+* phase ({@link (ResolvedTsconfig:class).substituteConfigDir}).
 *
 * @public
 */
-const ResolvedTsconfig = {
-	absolutize,
-	merge,
-	substituteConfigDir
+var ResolvedTsconfig = class {
+	constructor() {}
+	/**
+	* Absolutize a config's path-typed options (E5) 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).
+	*/
+	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,
+	* 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
+	* (case-insensitive, leading position only) with `finalDir` — the
+	* top-level extending config's directory — across every eligible
+	* surface: compilerOptions path options, `paths` values,
+	* `files`/`include`/`exclude`, and `watchOptions`'
+	* `excludeDirectories`/`excludeFiles`. Every other field is left
+	* untouched.
+	*/
+	static substituteConfigDir = substituteConfigDir;
 };
 
 //#endregion

package/TsEnumCodec.js

@@ -94,31 +94,8 @@ const TABLES = {
 		["fixedchunksize", 3]
 	])
 };
-/**
-* Encodes a family's canonical (or alias) string spelling to its numeric
-* form. `Option.none()` for a string with no table entry — never guessed.
-*
-* @public
-*/
 const encode = (family, value) => Option.fromNullishOr(TABLES[family].forward.get(value));
-/**
-* Decodes a family's numeric value to its canonical string spelling.
-* `Option.none()` for a numeric value with no table entry (a future TS enum
-* member) — never guessed.
-*
-* @public
-*/
 const decode = (family, value) => Option.fromNullishOr(TABLES[family].reverse.get(value));
-/**
-* Normalizes any spelling of a `lib` reference — the plain short name
-* (`esnext`), the on-disk file name (`lib.esnext.d.ts`), or an absolute path
-* to one (`/…/typescript/lib/lib.dom.iterable.d.ts`) — to the canonical
-* lowercase short name (`esnext`, `dom.iterable`). Strips a leading
-* directory, the `lib.` prefix and the `.d.ts` suffix; idempotent on an
-* already-short name.
-*
-* @public
-*/
 const normalizeLibReference = (lib) => {
 	const base = (lib.split("/").pop() ?? lib).toLowerCase();
 	const withoutPrefix = base.startsWith("lib.") ? base.slice(4) : base;
@@ -133,24 +110,6 @@ const COMPILER_OPTION_ENUM_KEYS = [
 	["newLine", "newLine"],
 	["moduleDetection", "moduleDetection"]
 ];
-/**
-* 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 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.
-*
-* The return carries this package's single narrowing from the codec's internal
-* `Record<string, unknown>` (whose values include the schema's `unknown`
-* passthrough and its `readonly` arrays) to {@link ProgrammaticCompilerOptions}
-* — see that type's docs for why the package owns this one assertion instead of
-* leaving every consumer to cast. Runtime behavior is unchanged; only the
-* declared return type narrows.
-*
-* @public
-*/
 const encodeCompilerOptions = (options) => {
 	const source = options;
 	const result = { ...source };
@@ -165,20 +124,6 @@ const encodeCompilerOptions = (options) => {
 	if (Array.isArray(lib)) result.lib = lib.map((entry) => typeof entry === "string" ? `lib.${normalizeLibReference(entry)}.d.ts` : entry);
 	return result;
 };
-/**
-* Decodes a numeric-enum-shaped `compilerOptions` object (as produced by
-* {@link (TsEnumCodec:variable).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
-* `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 `Record<string, unknown>`
-* rather than {@link (CompilerOptions:variable).Type}: an unmappable
-* passthrough value would violate that narrower type's contract. Every other
-* key is copied through untouched.
-*
-* @public
-*/
 const decodeCompilerOptions = (numeric) => {
 	const result = { ...numeric };
 	for (const [key, family] of COMPILER_OPTION_ENUM_KEYS) {
@@ -199,12 +144,61 @@ const decodeCompilerOptions = (numeric) => {
 *
 * @public
 */
-const TsEnumCodec = {
-	encode,
-	decode,
-	normalizeLibReference,
-	encodeCompilerOptions,
-	decodeCompilerOptions
+var TsEnumCodec = class {
+	constructor() {}
+	/**
+	* Encodes a family's canonical (or alias) string spelling to its numeric
+	* form. `Option.none()` for a string with no table entry — never guessed.
+	*/
+	static encode = encode;
+	/**
+	* Decodes a family's numeric value to its canonical string spelling.
+	* `Option.none()` for a numeric value with no table entry (a future TS
+	* enum member) — never guessed.
+	*/
+	static decode = decode;
+	/**
+	* Normalizes any spelling of a `lib` reference — the plain short name
+	* (`esnext`), the on-disk file name (`lib.esnext.d.ts`), or an absolute
+	* path to one (`/…/typescript/lib/lib.dom.iterable.d.ts`) — to the
+	* canonical lowercase short name (`esnext`, `dom.iterable`). Strips a
+	* leading directory, the `lib.` prefix and the `.d.ts` suffix; idempotent
+	* on an already-short name.
+	*/
+	static normalizeLibReference = normalizeLibReference;
+	/**
+	* 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
+	* 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.
+	*
+	* @remarks
+	* The return carries this package's single narrowing from the codec's
+	* internal `Record<string, unknown>` (whose values include the schema's
+	* `unknown` passthrough and its `readonly` arrays) to
+	* {@link ProgrammaticCompilerOptions} — see that type's docs for why the
+	* package owns this one assertion instead of leaving every consumer to
+	* cast. Runtime behavior is unchanged; only the declared return type
+	* narrows.
+	*/
+	static encodeCompilerOptions = encodeCompilerOptions;
+	/**
+	* 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
+	* `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
+	* `Record<string, unknown>` rather than
+	* {@link (CompilerOptions:namespace).Type}: an unmappable passthrough
+	* value would violate that narrower type's contract. Every other key is
+	* copied through untouched.
+	*/
+	static decodeCompilerOptions = decodeCompilerOptions;
 };
 
 //#endregion

package/TsconfigDiscovery.js

@@ -2,16 +2,6 @@ import { Effect, Path } from "effect";
 import { Walker } from "@effected/walker";
 
 //#region src/TsconfigDiscovery.ts
-/**
-* Find the nearest `tsconfig.json` (or `options.filename`) at or above
-* `start`, ascending toward the filesystem root. Absence — nowhere on the
-* chain, or every candidate unreadable — is `Option.none()`, never an error;
-* discovery is best-effort per `Walker.findUpward`'s absorption posture, and a
-* permission-denied probe on one directory does not hide a config file above
-* it.
-*
-* @public
-*/
 const findNearest = (start, options) => Effect.gen(function* () {
 	const path = yield* Path.Path;
 	const filename = options?.filename ?? "tsconfig.json";
@@ -23,7 +13,18 @@ const findNearest = (start, options) => Effect.gen(function* () {
 *
 * @public
 */
-const TsconfigDiscovery = { findNearest };
+var TsconfigDiscovery = class {
+	constructor() {}
+	/**
+	* Find the nearest `tsconfig.json` (or `options.filename`) at or above
+	* `start`, ascending toward the filesystem root. Absence — nowhere on the
+	* chain, or every candidate unreadable — is `Option.none()`, never an
+	* error; discovery is best-effort per `Walker.findUpward`'s absorption
+	* posture, and a permission-denied probe on one directory does not hide a
+	* config file above it.
+	*/
+	static findNearest = findNearest;
+};
 
 //#endregion
 export { TsconfigDiscovery };

package/TsconfigLoader.js

@@ -58,14 +58,6 @@ const loadAbs = (abs) => Effect.gen(function* () {
 		cause
 	})));
 });
-/**
-* Read one config file and decode it through {@link TsconfigJsonFromString}. A
-* decode failure is wrapped in a {@link TsconfigParseError} carrying the file's
-* absolute path; a `PlatformError` from the read flows through untranslated. No
-* `extends` resolution — {@link TsconfigLoader.resolve} drives that.
-*
-* @public
-*/
 const load = Effect.fn("TsconfigLoader.load")(function* (configPath) {
 	const path = yield* Path.Path;
 	return yield* loadAbs(normalizeSlashes(path.resolve(configPath)));
@@ -119,19 +111,6 @@ const collect = (configPath, chain) => Effect.gen(function* () {
 	});
 	return layers;
 });
-/**
-* 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` + `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 a
-* `PlatformError` from IO — never a defect.
-*
-* @public
-*/
 const resolve = Effect.fn("TsconfigLoader.resolve")(function* (configPath) {
 	const path = yield* Path.Path;
 	const topAbs = normalizeSlashes(path.resolve(configPath));
@@ -144,14 +123,6 @@ const resolve = Effect.fn("TsconfigLoader.resolve")(function* (configPath) {
 	for (const entry of layers) acc = ResolvedTsconfig.merge(acc, entry.doc, entry.path);
 	return ResolvedTsconfig.substituteConfigDir(acc, path.dirname(topAbs));
 });
-/**
-* Resolve a tsconfig.json's full `extends` chain and project out the merged
-* `compilerOptions` — a thin projection of {@link TsconfigLoader.resolve} for
-* the common "just give me the effective options" query. Same pipeline, same
-* typed failures.
-*
-* @public
-*/
 const compilerOptions = Effect.fn("TsconfigLoader.compilerOptions")(function* (configPath) {
 	return (yield* resolve(configPath)).compilerOptions;
 });
@@ -163,10 +134,36 @@ const compilerOptions = Effect.fn("TsconfigLoader.compilerOptions")(function* (c
 *
 * @public
 */
-const TsconfigLoader = {
-	load,
-	resolve,
-	compilerOptions
+var TsconfigLoader = class {
+	constructor() {}
+	/**
+	* Read one config file and decode it through {@link TsconfigJsonFromString}.
+	* A decode failure is wrapped in a {@link TsconfigParseError} carrying the
+	* file's absolute path; a `PlatformError` from the read flows through
+	* untranslated. No `extends` resolution — {@link TsconfigLoader.resolve}
+	* drives that.
+	*/
+	static load = load;
+	/**
+	* 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` +
+	* `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
+	* a `PlatformError` from IO — never a defect.
+	*/
+	static resolve = resolve;
+	/**
+	* Resolve a tsconfig.json's full `extends` chain and project out the
+	* merged `compilerOptions` — a thin projection of
+	* {@link TsconfigLoader.resolve} for the common "just give me the
+	* effective options" query. Same pipeline, same typed failures.
+	*/
+	static compilerOptions = compilerOptions;
 };
 
 //#endregion

package/TsconfigLoaderSync.js

@@ -67,30 +67,8 @@ const runWith = (options, effect) => {
 	if (Result.isSuccess(defect)) throw defect.success;
 	throw Cause.squash(exit.cause);
 };
-/**
-* {@link TsconfigLoader.load}, synchronously: read and decode one config file
-* through the consumer-supplied operations. Throws `TsconfigParseError` or a
-* `PlatformError` — the async pipeline's exact typed failures.
-*
-* @public
-*/
 const load = (configPath, options) => runWith(options, TsconfigLoader.load(configPath));
-/**
-* {@link TsconfigLoader.resolve}, synchronously: the full load -\> extends -\>
-* merge -\> `${configDir}` pipeline through the consumer-supplied operations.
-* Throws `TsconfigParseError`, `TsconfigExtendsError` or a `PlatformError` —
-* the async pipeline's exact typed failures.
-*
-* @public
-*/
 const resolve = (configPath, options) => runWith(options, TsconfigLoader.resolve(configPath));
-/**
-* {@link TsconfigLoader.compilerOptions}, synchronously: resolve the full
-* `extends` chain and project out the merged `compilerOptions`. Throws the
-* same typed failures as {@link TsconfigLoaderSync.resolve}.
-*
-* @public
-*/
 const compilerOptions = (configPath, options) => resolve(configPath, options).compilerOptions;
 /**
 * The synchronous tsconfig.json loader facade: the {@link TsconfigLoader}
@@ -121,10 +99,29 @@ const compilerOptions = (configPath, options) => resolve(configPath, options).co
 *
 * @public
 */
-const TsconfigLoaderSync = {
-	load,
-	resolve,
-	compilerOptions
+var TsconfigLoaderSync = class {
+	constructor() {}
+	/**
+	* {@link TsconfigLoader.load}, synchronously: read and decode one config
+	* file through the consumer-supplied operations. Throws
+	* `TsconfigParseError` or a `PlatformError` — the async pipeline's exact
+	* typed failures.
+	*/
+	static load = load;
+	/**
+	* {@link TsconfigLoader.resolve}, synchronously: the full load -\>
+	* extends -\> merge -\> `${configDir}` pipeline through the
+	* consumer-supplied operations. Throws `TsconfigParseError`,
+	* `TsconfigExtendsError` or a `PlatformError` — the async pipeline's exact
+	* typed failures.
+	*/
+	static resolve = resolve;
+	/**
+	* {@link TsconfigLoader.compilerOptions}, synchronously: resolve the full
+	* `extends` chain and project out the merged `compilerOptions`. Throws
+	* the same typed failures as {@link TsconfigLoaderSync.resolve}.
+	*/
+	static compilerOptions = compilerOptions;
 };
 
 //#endregion

package/index.d.ts

@@ -550,17 +550,43 @@ interface ResolvedTsconfig {
 }
 /**
  * The pure extends-merge engine: parse-time path absolutization
- * ({@link (ResolvedTsconfig:variable).absolutize}), the per-field merge fold
- * ({@link (ResolvedTsconfig:variable).merge}), and the `${configDir}` final
- * phase ({@link (ResolvedTsconfig:variable).substituteConfigDir}).
+ * ({@link (ResolvedTsconfig:class).absolutize}), the per-field merge fold
+ * ({@link (ResolvedTsconfig:class).merge}), and the `${configDir}` final
+ * phase ({@link (ResolvedTsconfig:class).substituteConfigDir}).
  *
  * @public
  */
-declare const ResolvedTsconfig: {
-  readonly absolutize: (doc: TsconfigJson.Type, configDir: string, join: (a: string, b: string) => string) => TsconfigJson.Type;
-  readonly merge: (base: ResolvedTsconfig, derived: TsconfigJson.Type, derivedPath: string) => ResolvedTsconfig;
-  readonly substituteConfigDir: (resolved: ResolvedTsconfig, finalDir: string) => ResolvedTsconfig;
-};
+declare class ResolvedTsconfig {
+  private constructor();
+  /**
+   * Absolutize a config's path-typed options (E5) 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).
+   */
+  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,
+   * 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
+   * (case-insensitive, leading position only) with `finalDir` — the
+   * top-level extending config's directory — across every eligible
+   * surface: compilerOptions path options, `paths` values,
+   * `files`/`include`/`exclude`, and `watchOptions`'
+   * `excludeDirectories`/`excludeFiles`. Every other field is left
+   * untouched.
+   */
+  static readonly substituteConfigDir: (resolved: ResolvedTsconfig, finalDir: string) => ResolvedTsconfig;
+}
 //#endregion
 //#region src/PortableTsconfig.d.ts
 /**
@@ -578,15 +604,27 @@ interface PortableTsconfig {
   readonly compilerOptions: Record<string, unknown>;
 }
 /**
- * The portable-tsconfig filter: {@link (PortableTsconfig:variable).make}
+ * The portable-tsconfig filter: {@link (PortableTsconfig:class).make}
  * narrows a resolved or bare compiler-options object to the allow-listed,
  * machine-independent subset described on {@link (PortableTsconfig:interface)}.
  *
  * @public
  */
-declare const PortableTsconfig: {
-  readonly make: (input: ResolvedTsconfig | CompilerOptions.Type) => PortableTsconfig;
-};
+declare class PortableTsconfig {
+  private constructor();
+  /**
+   * 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.
+   */
+  static readonly make: (input: ResolvedTsconfig | CompilerOptions.Type) => PortableTsconfig;
+}
 //#endregion
 //#region src/TsconfigDiscovery.d.ts
 /**
@@ -605,9 +643,18 @@ interface FindNearestOptions {
  *
  * @public
  */
-declare const TsconfigDiscovery: {
-  readonly findNearest: (start: string, options?: FindNearestOptions) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem | Path.Path>;
-};
+declare class TsconfigDiscovery {
+  private constructor();
+  /**
+   * Find the nearest `tsconfig.json` (or `options.filename`) at or above
+   * `start`, ascending toward the filesystem root. Absence — nowhere on the
+   * chain, or every candidate unreadable — is `Option.none()`, never an
+   * error; discovery is best-effort per `Walker.findUpward`'s absorption
+   * posture, and a permission-denied probe on one directory does not hide a
+   * config file above it.
+   */
+  static readonly findNearest: (start: string, options?: FindNearestOptions) => Effect.Effect<Option.Option<string>, never, FileSystem.FileSystem | Path.Path>;
+}
 //#endregion
 //#region src/TsconfigLoader.d.ts
 declare const TsconfigExtendsError_base: Schema.Class<TsconfigExtendsError, Schema.TaggedStruct<"TsconfigExtendsError", {
@@ -642,8 +689,16 @@ declare class TsconfigExtendsError extends TsconfigExtendsError_base {
  *
  * @public
  */
-declare const TsconfigLoader: {
-  readonly load: (configPath: string) => Effect.Effect<{
+declare class TsconfigLoader {
+  private constructor();
+  /**
+   * Read one config file and decode it through {@link TsconfigJsonFromString}.
+   * A decode failure is wrapped in a {@link TsconfigParseError} carrying the
+   * file's absolute path; a `PlatformError` from the read flows through
+   * untranslated. No `extends` resolution — {@link TsconfigLoader.resolve}
+   * drives that.
+   */
+  static readonly load: (configPath: string) => Effect.Effect<{
     readonly [x: string]: unknown;
     readonly compilerOptions?: {
       readonly [x: string]: unknown;
@@ -790,8 +845,26 @@ declare const TsconfigLoader: {
     readonly compileOnSave?: boolean | undefined;
     readonly $schema?: string | undefined;
   }, PlatformError.PlatformError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
-  readonly resolve: (configPath: string) => Effect.Effect<ResolvedTsconfig, PlatformError.PlatformError | TsconfigExtendsError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
-  readonly compilerOptions: (configPath: string) => Effect.Effect<{
+  /**
+   * 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` +
+   * `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
+   * a `PlatformError` from IO — never a defect.
+   */
+  static readonly resolve: (configPath: string) => Effect.Effect<ResolvedTsconfig, PlatformError.PlatformError | TsconfigExtendsError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
+  /**
+   * Resolve a tsconfig.json's full `extends` chain and project out the
+   * merged `compilerOptions` — a thin projection of
+   * {@link TsconfigLoader.resolve} for the common "just give me the
+   * effective options" query. Same pipeline, same typed failures.
+   */
+  static readonly compilerOptions: (configPath: string) => Effect.Effect<{
     readonly [x: string]: unknown;
     readonly target?: "es2015" | "es2016" | "es2017" | "es2018" | "es2019" | "es2020" | "es2021" | "es2022" | "es2023" | "es2024" | "es2025" | "es5" | "es6" | "esnext" | undefined;
     readonly module?: "amd" | "commonjs" | "es2015" | "es2020" | "es2022" | "es6" | "esnext" | "node16" | "node18" | "node20" | "nodenext" | "none" | "preserve" | "system" | "umd" | undefined;
@@ -909,7 +982,7 @@ declare const TsconfigLoader: {
     }[] | undefined;
     readonly maxNodeModuleJsDepth?: number | undefined;
   }, PlatformError.PlatformError | TsconfigExtendsError | TsconfigParseError, FileSystem.FileSystem | Path.Path>;
-};
+}
 //#endregion
 //#region src/TsconfigLoaderSync.d.ts
 /**
@@ -1012,11 +1085,30 @@ interface TsconfigLoaderSyncOptions {
  *
  * @public
  */
-declare const TsconfigLoaderSync: {
-  readonly load: (configPath: string, options: TsconfigLoaderSyncOptions) => TsconfigJson.Type;
-  readonly resolve: (configPath: string, options: TsconfigLoaderSyncOptions) => ResolvedTsconfig;
-  readonly compilerOptions: (configPath: string, options: TsconfigLoaderSyncOptions) => CompilerOptions.Type;
-};
+declare class TsconfigLoaderSync {
+  private constructor();
+  /**
+   * {@link TsconfigLoader.load}, synchronously: read and decode one config
+   * file through the consumer-supplied operations. Throws
+   * `TsconfigParseError` or a `PlatformError` — the async pipeline's exact
+   * typed failures.
+   */
+  static readonly load: (configPath: string, options: TsconfigLoaderSyncOptions) => TsconfigJson.Type;
+  /**
+   * {@link TsconfigLoader.resolve}, synchronously: the full load -\>
+   * extends -\> merge -\> `${configDir}` pipeline through the
+   * consumer-supplied operations. Throws `TsconfigParseError`,
+   * `TsconfigExtendsError` or a `PlatformError` — the async pipeline's exact
+   * typed failures.
+   */
+  static readonly resolve: (configPath: string, options: TsconfigLoaderSyncOptions) => ResolvedTsconfig;
+  /**
+   * {@link TsconfigLoader.compilerOptions}, synchronously: resolve the full
+   * `extends` chain and project out the merged `compilerOptions`. Throws
+   * the same typed failures as {@link TsconfigLoaderSync.resolve}.
+   */
+  static readonly compilerOptions: (configPath: string, options: TsconfigLoaderSyncOptions) => CompilerOptions.Type;
+}
 //#endregion
 //#region src/TsEnumCodec.d.ts
 /**
@@ -1068,7 +1160,7 @@ type ProgrammaticCompilerOptionsValue = string | number | boolean | (string | nu
   readonly circular?: boolean;
 }[] | null | undefined;
 /**
- * The shape {@link (TsEnumCodec:variable).encodeCompilerOptions} returns: the
+ * The shape {@link TsEnumCodec.encodeCompilerOptions} returns: the
  * numeric-enum-encoded `compilerOptions` a virtual-TS environment and the
  * TypeScript compiler API consume programmatically.
  *
@@ -1115,13 +1207,62 @@ interface ProgrammaticCompilerOptions {
  *
  * @public
  */
-declare const TsEnumCodec: {
-  readonly encode: (family: EnumFamily, value: string) => Option.Option<number>;
-  readonly decode: (family: EnumFamily, value: number) => Option.Option<string>;
-  readonly normalizeLibReference: (lib: string) => string;
-  readonly encodeCompilerOptions: (options: CompilerOptions.Type) => ProgrammaticCompilerOptions;
-  readonly decodeCompilerOptions: (numeric: Readonly<Record<string, unknown>>) => Record<string, unknown>;
-};
+declare class TsEnumCodec {
+  private constructor();
+  /**
+   * Encodes a family's canonical (or alias) string spelling to its numeric
+   * form. `Option.none()` for a string with no table entry — never guessed.
+   */
+  static readonly encode: (family: EnumFamily, value: string) => Option.Option<number>;
+  /**
+   * Decodes a family's numeric value to its canonical string spelling.
+   * `Option.none()` for a numeric value with no table entry (a future TS
+   * enum member) — never guessed.
+   */
+  static readonly decode: (family: EnumFamily, value: number) => Option.Option<string>;
+  /**
+   * Normalizes any spelling of a `lib` reference — the plain short name
+   * (`esnext`), the on-disk file name (`lib.esnext.d.ts`), or an absolute
+   * path to one (`/…/typescript/lib/lib.dom.iterable.d.ts`) — to the
+   * canonical lowercase short name (`esnext`, `dom.iterable`). Strips a
+   * leading directory, the `lib.` prefix and the `.d.ts` suffix; idempotent
+   * on an already-short name.
+   */
+  static readonly normalizeLibReference: (lib: string) => string;
+  /**
+   * 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
+   * 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.
+   *
+   * @remarks
+   * The return carries this package's single narrowing from the codec's
+   * internal `Record<string, unknown>` (whose values include the schema's
+   * `unknown` passthrough and its `readonly` arrays) to
+   * {@link ProgrammaticCompilerOptions} — see that type's docs for why the
+   * package owns this one assertion instead of leaving every consumer to
+   * cast. Runtime behavior is unchanged; only the declared return type
+   * narrows.
+   */
+  static readonly encodeCompilerOptions: (options: CompilerOptions.Type) => ProgrammaticCompilerOptions;
+  /**
+   * 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
+   * `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
+   * `Record<string, unknown>` rather than
+   * {@link (CompilerOptions:namespace).Type}: an unmappable passthrough
+   * value would violate that narrower type's contract. Every other key is
+   * copied through untouched.
+   */
+  static readonly decodeCompilerOptions: (numeric: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+}
 //#endregion
 export { CompilerOptions, type EnumFamily, FallbackPolling, type FindNearestOptions, Jsx, JsxConfig, Lib, Module, ModuleDetection, ModuleResolution, NewLine, PortableTsconfig, type ProgrammaticCompilerOptions, type ProgrammaticCompilerOptionsValue, Reference, ResolvedTsconfig, type SyncFileSystem, type SyncPath, Target, TsEnumCodec, TsconfigDiscovery, TsconfigExtendsError, TsconfigJson, TsconfigJsonFromString, TsconfigLoader, TsconfigLoaderSync, type TsconfigLoaderSyncOptions, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions };
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/tsconfig-json",
-	"version": "0.3.1",
+	"version": "0.3.3",
 	"private": false,
 	"description": "Composable tsconfig.json handling for Effect: schemas, extends-chain resolution, and config discovery.",
 	"keywords": [
@@ -40,7 +40,7 @@
 	},
 	"peerDependencies": {
 		"@effected/jsonc": "~0.5.1",
-		"@effected/walker": "~0.3.2",
+		"@effected/walker": "~0.3.3",
 		"effect": "4.0.0-beta.101"
 	},
 	"engines": {