@effected/tsconfig-json 0.2.7 → 0.3.0

package/README.md

@@ -112,7 +112,7 @@ const compilerOptions = TsconfigLoaderSync.compilerOptions("./tsconfig.json", op
 - `TsconfigLoaderSync` — the synchronous facade for sync-only hosts: `load`, `resolve` and `compilerOptions` over consumer-supplied `{ fileSystem, path }` operations, running the same pipeline and throwing the same typed errors.
 - `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.
+- `TsEnumCodec` — the string↔numeric enum tables as plain data with zero `typescript` imports. `encodeCompilerOptions` returns the exported `ProgrammaticCompilerOptions` type — the numeric shape `ts.CompilerOptions` expects, so you hand it to a `ts.CompilerOptions`-shaped API without a cast — 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.
 - `JsxConfig.fromCompilerOptions` — the JSX transform a bundler can configure, projected from decoded options: `react-jsx` / `react-jsxdev` select the automatic runtime with its import source (defaulting to `react`, tsc's own default), `react` selects classic, and `preserve`, `react-native` or an absent `jsx` yield `Option.none()`.
 - 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.

package/TsEnumCodec.js

@@ -135,11 +135,19 @@ const COMPILER_OPTION_ENUM_KEYS = [
 ];
 /**
 * Encodes a decoded `compilerOptions` object into the numeric-enum-shaped
-* 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.
+* {@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
 */

package/index.d.ts

@@ -1026,6 +1026,88 @@ declare const TsconfigLoaderSync: {
  * @public
  */
 type EnumFamily = "target" | "module" | "moduleResolution" | "jsx" | "newLine" | "moduleDetection" | "watchFile" | "watchDirectory" | "fallbackPolling";
+/**
+ * A single value a programmatic `compilerOptions` entry can hold — a
+ * structural transcription of TypeScript's own `CompilerOptionsValue`,
+ * transcribed (not imported) to honor this package's zero-`typescript` rule.
+ *
+ * Transcribed verbatim from `typescript@6.0.3`'s
+ * `node_modules/typescript/lib/typescript.d.ts` (the version `@typescript/vfs@1.6.4`,
+ * the encode target's consumer, pins):
+ *
+ * ```ts
+ * type CompilerOptionsValue = string | number | boolean | (string | number)[]
+ *   | string[] | MapLike<string[]> | PluginImport[] | ProjectReference[]
+ *   | null | undefined;
+ * interface MapLike<T> { [index: string]: T }
+ * interface PluginImport { name: string }
+ * interface ProjectReference { path: string; originalPath?: string; prepend?: boolean; circular?: boolean }
+ * ```
+ *
+ * The one member deliberately omitted is `TsConfigSourceFile` (present only in
+ * the interface's index signature, not `CompilerOptionsValue` itself): it is a
+ * full parsed-AST node the compiler synthesizes, never a value reachable from
+ * JSON, so it cannot appear in options this codec builds. Omitting it keeps the
+ * union a strict structural subset of the compiler's own index-signature value
+ * type, which is what assignability to `ts.CompilerOptions` requires. Arrays
+ * are intentionally mutable (`string[]`, not `readonly string[]`): TypeScript's
+ * mutable array members are not assignable from a `readonly` array, and the one
+ * narrowing below reconciles this with the codec's actual `readonly`-array
+ * outputs.
+ *
+ * @public
+ */
+type ProgrammaticCompilerOptionsValue = string | number | boolean | (string | number)[] | string[] | {
+  readonly [index: string]: string[];
+} | {
+  readonly name: string;
+}[] | {
+  readonly path: string;
+  readonly originalPath?: string;
+  readonly prepend?: boolean;
+  readonly circular?: boolean;
+}[] | null | undefined;
+/**
+ * The shape {@link (TsEnumCodec:variable).encodeCompilerOptions} returns: the
+ * numeric-enum-encoded `compilerOptions` a virtual-TS environment and the
+ * TypeScript compiler API consume programmatically.
+ *
+ * It is deliberately shaped to be assignable to TypeScript's `ts.CompilerOptions`
+ * without naming it (the zero-`typescript` rule), so a consumer handing the
+ * result to `@typescript/vfs`'s `createVirtualTypeScriptEnvironment` /
+ * `createDefaultMapFromNodeModules` or to `ts.createProgram` no longer ends the
+ * pipeline with a cast. Verified assignable to the real `ts.CompilerOptions`
+ * (`typescript@6.0.3`, `@typescript/vfs@1.6.4`) by a compile-time test
+ * (`__test__/TsEnumCodec.assignability.test.ts`).
+ *
+ * What it honestly **claims**: the six enum-family keys read back as `number`
+ * (they are always encoded — a decoded `CompilerOptions.Type` constrains each
+ * to a spelling the codec's tables cover, so the runtime "unknown string passes
+ * through unencoded" branch is unreachable for a well-typed input); `lib` reads
+ * back as `string[]` (the file-name form); every other value is one of the
+ * structural forms `ts.CompilerOptions` accepts.
+ *
+ * What it does **not** prove: that an arbitrary passthrough value carried
+ * through from JSONC (the schema preserves unknown keys as `unknown`) fits
+ * {@link ProgrammaticCompilerOptionsValue}. Neither does `ts.CompilerOptions`:
+ * its own index signature makes the identical unproven claim, and any consumer
+ * feeding parsed tsconfig to `ts.createProgram` relies on it. The single
+ * narrowing that bridges the codec's `unknown`/`readonly` outputs to this type
+ * lives once, at `encodeCompilerOptions`'s return (below), so the assertion is
+ * owned here rather than re-made at every call site.
+ *
+ * @public
+ */
+interface ProgrammaticCompilerOptions {
+  readonly [option: string]: ProgrammaticCompilerOptionsValue;
+  readonly target?: number;
+  readonly module?: number;
+  readonly moduleResolution?: number;
+  readonly jsx?: number;
+  readonly newLine?: number;
+  readonly moduleDetection?: number;
+  readonly lib?: string[];
+}
 /**
  * The string↔numeric enum codec for `compilerOptions` / `watchOptions`
  * families, per R1.6. Plain data: every lookup is a synchronous map read
@@ -1037,9 +1119,9 @@ 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) => Record<string, unknown>;
+  readonly encodeCompilerOptions: (options: CompilerOptions.Type) => ProgrammaticCompilerOptions;
   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, Reference, ResolvedTsconfig, type SyncFileSystem, type SyncPath, Target, TsEnumCodec, TsconfigDiscovery, TsconfigExtendsError, TsconfigJson, TsconfigJsonFromString, TsconfigLoader, TsconfigLoaderSync, type TsconfigLoaderSyncOptions, TsconfigParseError, TypeAcquisition, WatchDirectory, WatchFile, WatchOptions };
+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.2.7",
+	"version": "0.3.0",
 	"private": false,
 	"description": "Composable tsconfig.json handling for Effect: schemas, extends-chain resolution, and config discovery.",
 	"keywords": [