@ttsc/unplugin 0.30.4 → 0.31.1

package/lib/core/transform/tsconfig/createTransformScratchDirectory.mjs

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { DEFAULT_FILESYSTEM_OPERATIONS } from '../filesystem/DEFAULT_FILESYSTEM_OPERATIONS.mjs';
+import { pathIsWithin } from '../filesystem/pathIsWithin.mjs';
+
+/**
+ * Create compiler scratch storage outside the project snapshot and watchers.
+ *
+ * Candidate parents are checked lexically and physically before creation. The
+ * created child's postflight physical address is checked again and returned,
+ * avoiding reuse of the candidate's known lexical parent alias. These path
+ * observations do not pin directory handles or rule out later native
+ * replacement. Failed candidates are skipped only after their owned empty child
+ * is removed.
+ *
+ * @evidence contracts/common.md#principled-implementation Preflight and postflight containment reject observed scratch addresses inside the project; returning the checked child spelling avoids knowingly reusing an unresolved parent alias, without certifying later topology cannot change.
+ * @evidence contracts/common.md#clear-and-simple-design One bounded candidate loop owns creation and immediate rejection cleanup, while the capturing generation owns the lifetime of an accepted directory.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts A failed outside-project check never falls back to project scratch, and rejected child cleanup failures propagate instead of being hidden as another candidate miss.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs explain both identity checks, the returned physical spelling and the ownership condition on skipping a failed candidate; inline comments justify postflight removal.
+ * @evidence contracts/portability.md#os-neutral-implementation Node os and path provide native temporary/home candidates and containment; physical checks use the injected view, while actual random-child creation and removal use native fs without shell commands or blanket case folding.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources Rejected random empty children receive synchronous removal attempts; failure propagates and can leave an artifact rather than silently skipping it. Accepted directory ownership transfers to capture's finally cleanup or its separately retained clock owner. No native directory handle pins these path identities against later replacement.
+ * @evidence contracts/performance.md#efficient-algorithms At most four candidate spellings are deduplicated, with native realpath/containment/path text and up to four random-child allocation/postflight/removal attempts. More than one candidate can allocate successfully before rejection; no project-tree scan or file-byte capture occurs here.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work Scratch allocation is an ownership-bearing effect for one capture and must not be shared merely because two generations select the same candidate parent.
+ */
+function createTransformScratchDirectory(projectRoot, filesystem = DEFAULT_FILESYSTEM_OPERATIONS) {
+    const root = path.resolve(projectRoot);
+    const canonicalRoot = filesystem.realpath(root);
+    const platformTemp = process.platform === "win32" && process.env.LOCALAPPDATA
+        ? path.join(process.env.LOCALAPPDATA, "Temp")
+        : "/tmp";
+    const candidates = [
+        os.tmpdir(),
+        platformTemp,
+        path.dirname(root),
+        os.homedir(),
+    ];
+    const canonicalCandidates = new Set();
+    let failure;
+    for (const candidate of new Set(candidates.map((dir) => path.resolve(dir)))) {
+        if (pathIsWithin(candidate, root))
+            continue;
+        let canonicalCandidate;
+        try {
+            canonicalCandidate = filesystem.realpath(candidate);
+        }
+        catch (error) {
+            failure = error;
+            continue;
+        }
+        if (pathIsWithin(canonicalCandidate, canonicalRoot) ||
+            canonicalCandidates.has(canonicalCandidate)) {
+            continue;
+        }
+        canonicalCandidates.add(canonicalCandidate);
+        let directory;
+        try {
+            directory = fs.mkdtempSync(path.join(canonicalCandidate, "ttsc-unplugin-"));
+        }
+        catch (error) {
+            failure = error;
+            continue;
+        }
+        let canonicalDirectory;
+        try {
+            canonicalDirectory = filesystem.realpath(directory);
+        }
+        catch (error) {
+            // A child this call created and cannot remove is a leak, not a skipped
+            // candidate, so its removal failure propagates.
+            fs.rmdirSync(directory);
+            failure = error;
+            continue;
+        }
+        // Use the postflight canonical spelling from this point onward. Returning
+        // the candidate-relative spelling would let another process retarget its
+        // parent symlink/junction after validation, redirecting compiler writes or
+        // the final recursive removal into the project through that known alias.
+        // The returned path still is not an atomic handle against later replacement.
+        if (!pathIsWithin(canonicalDirectory, canonicalRoot)) {
+            return canonicalDirectory;
+        }
+        // Refuse the result and synchronously remove only our empty random child
+        // through the identity that the postflight check just classified.
+        fs.rmdirSync(canonicalDirectory);
+    }
+    throw (failure ??
+        new Error("ttsc: no temporary directory exists outside the project"));
+}
+
+export { createTransformScratchDirectory };
+//# sourceMappingURL=createTransformScratchDirectory.mjs.map

package/lib/core/transform/tsconfig/createTransformScratchDirectory.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTransformScratchDirectory.mjs","sources":["../../../../src/core/transform/tsconfig/createTransformScratchDirectory.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;AAQA;;;;;;;;;;;;;;;;;;AAkBG;SACa,+BAA+B,CAC7C,WAAmB,EACnB,aAAgD,6BAA6B,EAAA;IAE7E,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IACtC,MAAM,aAAa,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;AAC/C,IAAA,MAAM,YAAY,GAChB,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC;AAC1C,UAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM;UAC1C,MAAM;AACZ,IAAA,MAAM,UAAU,GAAG;QACjB,EAAE,CAAC,MAAM,EAAE;QACX,YAAY;AACZ,QAAA,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;QAClB,EAAE,CAAC,OAAO,EAAE;KACb;AACD,IAAA,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAU;AAC7C,IAAA,IAAI,OAAgB;IACpB,KAAK,MAAM,SAAS,IAAI,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;AAC3E,QAAA,IAAI,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC;YAAE;AACnC,QAAA,IAAI,kBAA0B;AAC9B,QAAA,IAAI;AACF,YAAA,kBAAkB,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;QACrD;QAAE,OAAO,KAAK,EAAE;YACd,OAAO,GAAG,KAAK;YACf;QACF;AACA,QAAA,IACE,YAAY,CAAC,kBAAkB,EAAE,aAAa,CAAC;AAC/C,YAAA,mBAAmB,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAC3C;YACA;QACF;AACA,QAAA,mBAAmB,CAAC,GAAG,CAAC,kBAAkB,CAAC;AAC3C,QAAA,IAAI,SAAiB;AACrB,QAAA,IAAI;AACF,YAAA,SAAS,GAAG,EAAE,CAAC,WAAW,CACxB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAChD;QACH;QAAE,OAAO,KAAK,EAAE;YACd,OAAO,GAAG,KAAK;YACf;QACF;AACA,QAAA,IAAI,kBAA0B;AAC9B,QAAA,IAAI;AACF,YAAA,kBAAkB,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC;QACrD;QAAE,OAAO,KAAK,EAAE;;;AAGd,YAAA,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC;YACvB,OAAO,GAAG,KAAK;YACf;QACF;;;;;;QAMA,IAAI,CAAC,YAAY,CAAC,kBAAkB,EAAE,aAAa,CAAC,EAAE;AACpD,YAAA,OAAO,kBAAkB;QAC3B;;;AAGA,QAAA,EAAE,CAAC,SAAS,CAAC,kBAAkB,CAAC;IAClC;AACA,IAAA,OACE,OAAO;AACP,QAAA,IAAI,KAAK,CAAC,yDAAyD,CAAC;AAExE;;;;"}

package/lib/core/transform/tsconfig/createTransformTsconfig.d.cts

@@ -0,0 +1,48 @@
+import type { ITransformTsconfigState } from "./ITransformTsconfigState.cjs";
+/**
+ * Materialize the tsconfig a transform compile runs against.
+ *
+ * When the adapter adds nothing (no compiler-options overlay and no aliases),
+ * the project's own tsconfig is used unchanged. Otherwise a wrapper that
+ * `extends` it is written into the adapter-owned scratch directory, outside the
+ * project, so it never becomes a project input. The wrapper carries the
+ * overlay, the translated aliases re-stated over the effective `paths`, and
+ * supported inherited `${configDir}` path options and file-selection fields
+ * reanchored so the wrapper does not move their meaning.
+ *
+ * The supplied compiler config directory anchors supported path fields and
+ * plugin addresses (samchon/ttsc#1456). It is the shared selector's best-effort
+ * spelling, not proof every native realpath succeeded or will stay unchanged.
+ *
+ * @param compiler The project's config path and directory as the compiler
+ *   spells them.
+ * @evidence contracts/common.md#principled-implementation The unchanged-config path avoids unnecessary wrapping; a needed wrapper extends the selected compiler config and reanchors supported inherited templates and aliases to its current directory so scratch placement does not move those paths.
+ * @evidence contracts/common.md#clear-and-simple-design Existing alias and normalization helpers construct one overlay, while this operation owns only deciding whether to write and materializing the wrapper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper preserves inherited template semantics instead of adding synthetic baseUrl, rewriting project files or compensating for scratch-directory misanchoring.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the no-overlay path, scratch ownership, inherited configDir behavior and the compiler's physical spelling; inline comments explain why inherited templates are restated.
+ * @evidence contracts/portability.md#os-neutral-implementation The supplied best-effort compiler directory and hostSpelling translate supported native path fields; Node path addresses the owned scratch file, and slash encoding applies to compiler protocol values. Actual fs writes use the native host, not arbitrary injected view semantics or a shell.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Overlay spreads and alias/normalization work depend on option, alias, list
+ *   and target counts/path text. Empty overlay returns the original config;
+ *   otherwise compiler options/template file fields are serialized to B JSON
+ *   bytes and synchronously written, retaining output objects/text until return.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Materializing a fixed filename in one generation's owned scratch directory
+ *   is an ownership-bearing effect, not a reusable result merely because two
+ *   callers supply equal options. Read-state sharing belongs to capture.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A needed wrapper is a retained native artifact in the supplied owned scratch
+ *   directory. Capture owns that directory's later removal, including failed
+ *   or partial native writes; this function neither closes the generation nor
+ *   installs its own cleanup timer. Empty-overlay return creates no artifact.
+ */
+export declare function createTransformTsconfig(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    tsconfig: string;
+}, scratchDirectory: string, state: ITransformTsconfigState, compiler: {
+    configDir: string;
+    tsconfig: string;
+}): {
+    path: string;
+};

package/lib/core/transform/tsconfig/createTransformTsconfig.d.mts

@@ -0,0 +1,48 @@
+import type { ITransformTsconfigState } from "./ITransformTsconfigState.mjs";
+/**
+ * Materialize the tsconfig a transform compile runs against.
+ *
+ * When the adapter adds nothing (no compiler-options overlay and no aliases),
+ * the project's own tsconfig is used unchanged. Otherwise a wrapper that
+ * `extends` it is written into the adapter-owned scratch directory, outside the
+ * project, so it never becomes a project input. The wrapper carries the
+ * overlay, the translated aliases re-stated over the effective `paths`, and
+ * supported inherited `${configDir}` path options and file-selection fields
+ * reanchored so the wrapper does not move their meaning.
+ *
+ * The supplied compiler config directory anchors supported path fields and
+ * plugin addresses (samchon/ttsc#1456). It is the shared selector's best-effort
+ * spelling, not proof every native realpath succeeded or will stay unchanged.
+ *
+ * @param compiler The project's config path and directory as the compiler
+ *   spells them.
+ * @evidence contracts/common.md#principled-implementation The unchanged-config path avoids unnecessary wrapping; a needed wrapper extends the selected compiler config and reanchors supported inherited templates and aliases to its current directory so scratch placement does not move those paths.
+ * @evidence contracts/common.md#clear-and-simple-design Existing alias and normalization helpers construct one overlay, while this operation owns only deciding whether to write and materializing the wrapper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper preserves inherited template semantics instead of adding synthetic baseUrl, rewriting project files or compensating for scratch-directory misanchoring.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the no-overlay path, scratch ownership, inherited configDir behavior and the compiler's physical spelling; inline comments explain why inherited templates are restated.
+ * @evidence contracts/portability.md#os-neutral-implementation The supplied best-effort compiler directory and hostSpelling translate supported native path fields; Node path addresses the owned scratch file, and slash encoding applies to compiler protocol values. Actual fs writes use the native host, not arbitrary injected view semantics or a shell.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Overlay spreads and alias/normalization work depend on option, alias, list
+ *   and target counts/path text. Empty overlay returns the original config;
+ *   otherwise compiler options/template file fields are serialized to B JSON
+ *   bytes and synchronously written, retaining output objects/text until return.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Materializing a fixed filename in one generation's owned scratch directory
+ *   is an ownership-bearing effect, not a reusable result merely because two
+ *   callers supply equal options. Read-state sharing belongs to capture.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A needed wrapper is a retained native artifact in the supplied owned scratch
+ *   directory. Capture owns that directory's later removal, including failed
+ *   or partial native writes; this function neither closes the generation nor
+ *   installs its own cleanup timer. Empty-overlay return creates no artifact.
+ */
+export declare function createTransformTsconfig(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    tsconfig: string;
+}, scratchDirectory: string, state: ITransformTsconfigState, compiler: {
+    configDir: string;
+    tsconfig: string;
+}): {
+    path: string;
+};

package/lib/core/transform/tsconfig/createTransformTsconfig.d.ts

@@ -0,0 +1,48 @@
+import type { ITransformTsconfigState } from "./ITransformTsconfigState";
+/**
+ * Materialize the tsconfig a transform compile runs against.
+ *
+ * When the adapter adds nothing (no compiler-options overlay and no aliases),
+ * the project's own tsconfig is used unchanged. Otherwise a wrapper that
+ * `extends` it is written into the adapter-owned scratch directory, outside the
+ * project, so it never becomes a project input. The wrapper carries the
+ * overlay, the translated aliases re-stated over the effective `paths`, and
+ * supported inherited `${configDir}` path options and file-selection fields
+ * reanchored so the wrapper does not move their meaning.
+ *
+ * The supplied compiler config directory anchors supported path fields and
+ * plugin addresses (samchon/ttsc#1456). It is the shared selector's best-effort
+ * spelling, not proof every native realpath succeeded or will stay unchanged.
+ *
+ * @param compiler The project's config path and directory as the compiler
+ *   spells them.
+ * @evidence contracts/common.md#principled-implementation The unchanged-config path avoids unnecessary wrapping; a needed wrapper extends the selected compiler config and reanchors supported inherited templates and aliases to its current directory so scratch placement does not move those paths.
+ * @evidence contracts/common.md#clear-and-simple-design Existing alias and normalization helpers construct one overlay, while this operation owns only deciding whether to write and materializing the wrapper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper preserves inherited template semantics instead of adding synthetic baseUrl, rewriting project files or compensating for scratch-directory misanchoring.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the no-overlay path, scratch ownership, inherited configDir behavior and the compiler's physical spelling; inline comments explain why inherited templates are restated.
+ * @evidence contracts/portability.md#os-neutral-implementation The supplied best-effort compiler directory and hostSpelling translate supported native path fields; Node path addresses the owned scratch file, and slash encoding applies to compiler protocol values. Actual fs writes use the native host, not arbitrary injected view semantics or a shell.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Overlay spreads and alias/normalization work depend on option, alias, list
+ *   and target counts/path text. Empty overlay returns the original config;
+ *   otherwise compiler options/template file fields are serialized to B JSON
+ *   bytes and synchronously written, retaining output objects/text until return.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Materializing a fixed filename in one generation's owned scratch directory
+ *   is an ownership-bearing effect, not a reusable result merely because two
+ *   callers supply equal options. Read-state sharing belongs to capture.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A needed wrapper is a retained native artifact in the supplied owned scratch
+ *   directory. Capture owns that directory's later removal, including failed
+ *   or partial native writes; this function neither closes the generation nor
+ *   installs its own cleanup timer. Empty-overlay return creates no artifact.
+ */
+export declare function createTransformTsconfig(props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    tsconfig: string;
+}, scratchDirectory: string, state: ITransformTsconfigState, compiler: {
+    configDir: string;
+    tsconfig: string;
+}): {
+    path: string;
+};

package/lib/core/transform/tsconfig/createTransformTsconfig.js

@@ -0,0 +1,76 @@
+'use strict';
+
+var fs = require('node:fs');
+var path = require('node:path');
+var createAliasCompilerOptions = require('../alias/createAliasCompilerOptions.js');
+var hostSpelling = require('../envelope/hostSpelling.js');
+var normalizePath = require('../filesystem/normalizePath.js');
+var normalizeCompilerOptionsForGeneratedTsconfig = require('./normalizeCompilerOptionsForGeneratedTsconfig.js');
+
+/**
+ * Materialize the tsconfig a transform compile runs against.
+ *
+ * When the adapter adds nothing (no compiler-options overlay and no aliases),
+ * the project's own tsconfig is used unchanged. Otherwise a wrapper that
+ * `extends` it is written into the adapter-owned scratch directory, outside the
+ * project, so it never becomes a project input. The wrapper carries the
+ * overlay, the translated aliases re-stated over the effective `paths`, and
+ * supported inherited `${configDir}` path options and file-selection fields
+ * reanchored so the wrapper does not move their meaning.
+ *
+ * The supplied compiler config directory anchors supported path fields and
+ * plugin addresses (samchon/ttsc#1456). It is the shared selector's best-effort
+ * spelling, not proof every native realpath succeeded or will stay unchanged.
+ *
+ * @param compiler The project's config path and directory as the compiler
+ *   spells them.
+ * @evidence contracts/common.md#principled-implementation The unchanged-config path avoids unnecessary wrapping; a needed wrapper extends the selected compiler config and reanchors supported inherited templates and aliases to its current directory so scratch placement does not move those paths.
+ * @evidence contracts/common.md#clear-and-simple-design Existing alias and normalization helpers construct one overlay, while this operation owns only deciding whether to write and materializing the wrapper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper preserves inherited template semantics instead of adding synthetic baseUrl, rewriting project files or compensating for scratch-directory misanchoring.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the no-overlay path, scratch ownership, inherited configDir behavior and the compiler's physical spelling; inline comments explain why inherited templates are restated.
+ * @evidence contracts/portability.md#os-neutral-implementation The supplied best-effort compiler directory and hostSpelling translate supported native path fields; Node path addresses the owned scratch file, and slash encoding applies to compiler protocol values. Actual fs writes use the native host, not arbitrary injected view semantics or a shell.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Overlay spreads and alias/normalization work depend on option, alias, list
+ *   and target counts/path text. Empty overlay returns the original config;
+ *   otherwise compiler options/template file fields are serialized to B JSON
+ *   bytes and synchronously written, retaining output objects/text until return.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Materializing a fixed filename in one generation's owned scratch directory
+ *   is an ownership-bearing effect, not a reusable result merely because two
+ *   callers supply equal options. Read-state sharing belongs to capture.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A needed wrapper is a retained native artifact in the supplied owned scratch
+ *   directory. Capture owns that directory's later removal, including failed
+ *   or partial native writes; this function neither closes the generation nor
+ *   installs its own cleanup timer. Empty-overlay return creates no artifact.
+ */
+function createTransformTsconfig(props, scratchDirectory, state, compiler) {
+    // The adapter's own reading, the effective `paths` among it, spelled the
+    // project as named; the wrapper speaks the compiler's spelling throughout.
+    const spell = hostSpelling.hostSpelling({ physical: compiler.configDir, spelling: path.dirname(props.tsconfig) }, compiler.configDir);
+    const overlay = normalizeCompilerOptionsForGeneratedTsconfig.normalizeCompilerOptionsForGeneratedTsconfig({
+        ...props.compilerOptions,
+        ...createAliasCompilerOptions.createAliasCompilerOptions(props, state.effectivePaths),
+    }, compiler.configDir, spell);
+    if (Object.keys(overlay).length === 0) {
+        return { path: props.tsconfig };
+    }
+    // A `${configDir}` value survives every `extends` hop and binds only at the
+    // final consumer. The scratch wrapper would therefore move it out of the
+    // project even for an unrelated overlay. Re-state only those inherited
+    // values as absolute paths so the wrapper remains semantically transparent.
+    const compilerOptions = {
+        ...state.templateCompilerOptions,
+        ...overlay,
+    };
+    const file = path.join(scratchDirectory, "tsconfig.json");
+    fs.writeFileSync(file, JSON.stringify({
+        extends: normalizePath.normalizePath(compiler.tsconfig),
+        ...state.templateFileSpecs,
+        compilerOptions,
+    }, null, 2), "utf8");
+    return { path: file };
+}
+
+exports.createTransformTsconfig = createTransformTsconfig;
+//# sourceMappingURL=createTransformTsconfig.js.map

package/lib/core/transform/tsconfig/createTransformTsconfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTransformTsconfig.js","sources":["../../../../src/core/transform/tsconfig/createTransformTsconfig.ts"],"sourcesContent":[null],"names":["hostSpelling","normalizeCompilerOptionsForGeneratedTsconfig","createAliasCompilerOptions","normalizePath"],"mappings":";;;;;;;;;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCG;AACG,SAAU,uBAAuB,CACrC,KAIC,EACD,gBAAwB,EACxB,KAA8B,EAC9B,QAAiD,EAAA;;;IAIjD,MAAM,KAAK,GAAGA,yBAAY,CACxB,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,EACxE,QAAQ,CAAC,SAAS,CACnB;IACD,MAAM,OAAO,GAAGC,yFAA4C,CAC1D;QACE,GAAG,KAAK,CAAC,eAAe;AACxB,QAAA,GAAGC,qDAA0B,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC;AAC3D,KAAA,EACD,QAAQ,CAAC,SAAS,EAClB,KAAK,CACN;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE;AACrC,QAAA,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE;IACjC;;;;;AAMA,IAAA,MAAM,eAAe,GAAG;QACtB,GAAG,KAAK,CAAC,uBAAuB;AAChC,QAAA,GAAG,OAAO;KACX;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC;IACzD,EAAE,CAAC,aAAa,CACd,IAAI,EACJ,IAAI,CAAC,SAAS,CACZ;AACE,QAAA,OAAO,EAAEC,2BAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACzC,GAAG,KAAK,CAAC,iBAAiB;QAC1B,eAAe;AAChB,KAAA,EACD,IAAI,EACJ,CAAC,CACF,EACD,MAAM,CACP;AACD,IAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;AACvB;;;;"}

package/lib/core/transform/tsconfig/createTransformTsconfig.mjs

@@ -0,0 +1,74 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createAliasCompilerOptions } from '../alias/createAliasCompilerOptions.mjs';
+import { hostSpelling } from '../envelope/hostSpelling.mjs';
+import { normalizePath } from '../filesystem/normalizePath.mjs';
+import { normalizeCompilerOptionsForGeneratedTsconfig } from './normalizeCompilerOptionsForGeneratedTsconfig.mjs';
+
+/**
+ * Materialize the tsconfig a transform compile runs against.
+ *
+ * When the adapter adds nothing (no compiler-options overlay and no aliases),
+ * the project's own tsconfig is used unchanged. Otherwise a wrapper that
+ * `extends` it is written into the adapter-owned scratch directory, outside the
+ * project, so it never becomes a project input. The wrapper carries the
+ * overlay, the translated aliases re-stated over the effective `paths`, and
+ * supported inherited `${configDir}` path options and file-selection fields
+ * reanchored so the wrapper does not move their meaning.
+ *
+ * The supplied compiler config directory anchors supported path fields and
+ * plugin addresses (samchon/ttsc#1456). It is the shared selector's best-effort
+ * spelling, not proof every native realpath succeeded or will stay unchanged.
+ *
+ * @param compiler The project's config path and directory as the compiler
+ *   spells them.
+ * @evidence contracts/common.md#principled-implementation The unchanged-config path avoids unnecessary wrapping; a needed wrapper extends the selected compiler config and reanchors supported inherited templates and aliases to its current directory so scratch placement does not move those paths.
+ * @evidence contracts/common.md#clear-and-simple-design Existing alias and normalization helpers construct one overlay, while this operation owns only deciding whether to write and materializing the wrapper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The wrapper preserves inherited template semantics instead of adding synthetic baseUrl, rewriting project files or compensating for scratch-directory misanchoring.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain the no-overlay path, scratch ownership, inherited configDir behavior and the compiler's physical spelling; inline comments explain why inherited templates are restated.
+ * @evidence contracts/portability.md#os-neutral-implementation The supplied best-effort compiler directory and hostSpelling translate supported native path fields; Node path addresses the owned scratch file, and slash encoding applies to compiler protocol values. Actual fs writes use the native host, not arbitrary injected view semantics or a shell.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Overlay spreads and alias/normalization work depend on option, alias, list
+ *   and target counts/path text. Empty overlay returns the original config;
+ *   otherwise compiler options/template file fields are serialized to B JSON
+ *   bytes and synchronously written, retaining output objects/text until return.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Materializing a fixed filename in one generation's owned scratch directory
+ *   is an ownership-bearing effect, not a reusable result merely because two
+ *   callers supply equal options. Read-state sharing belongs to capture.
+ * @evidence contracts/performance.md#bound-retention-and-release-resources
+ *   A needed wrapper is a retained native artifact in the supplied owned scratch
+ *   directory. Capture owns that directory's later removal, including failed
+ *   or partial native writes; this function neither closes the generation nor
+ *   installs its own cleanup timer. Empty-overlay return creates no artifact.
+ */
+function createTransformTsconfig(props, scratchDirectory, state, compiler) {
+    // The adapter's own reading, the effective `paths` among it, spelled the
+    // project as named; the wrapper speaks the compiler's spelling throughout.
+    const spell = hostSpelling({ physical: compiler.configDir, spelling: path.dirname(props.tsconfig) }, compiler.configDir);
+    const overlay = normalizeCompilerOptionsForGeneratedTsconfig({
+        ...props.compilerOptions,
+        ...createAliasCompilerOptions(props, state.effectivePaths),
+    }, compiler.configDir, spell);
+    if (Object.keys(overlay).length === 0) {
+        return { path: props.tsconfig };
+    }
+    // A `${configDir}` value survives every `extends` hop and binds only at the
+    // final consumer. The scratch wrapper would therefore move it out of the
+    // project even for an unrelated overlay. Re-state only those inherited
+    // values as absolute paths so the wrapper remains semantically transparent.
+    const compilerOptions = {
+        ...state.templateCompilerOptions,
+        ...overlay,
+    };
+    const file = path.join(scratchDirectory, "tsconfig.json");
+    fs.writeFileSync(file, JSON.stringify({
+        extends: normalizePath(compiler.tsconfig),
+        ...state.templateFileSpecs,
+        compilerOptions,
+    }, null, 2), "utf8");
+    return { path: file };
+}
+
+export { createTransformTsconfig };
+//# sourceMappingURL=createTransformTsconfig.mjs.map

package/lib/core/transform/tsconfig/createTransformTsconfig.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTransformTsconfig.mjs","sources":["../../../../src/core/transform/tsconfig/createTransformTsconfig.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;;;;AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCG;AACG,SAAU,uBAAuB,CACrC,KAIC,EACD,gBAAwB,EACxB,KAA8B,EAC9B,QAAiD,EAAA;;;IAIjD,MAAM,KAAK,GAAG,YAAY,CACxB,EAAE,QAAQ,EAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,EACxE,QAAQ,CAAC,SAAS,CACnB;IACD,MAAM,OAAO,GAAG,4CAA4C,CAC1D;QACE,GAAG,KAAK,CAAC,eAAe;AACxB,QAAA,GAAG,0BAA0B,CAAC,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC;AAC3D,KAAA,EACD,QAAQ,CAAC,SAAS,EAClB,KAAK,CACN;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE;AACrC,QAAA,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE;IACjC;;;;;AAMA,IAAA,MAAM,eAAe,GAAG;QACtB,GAAG,KAAK,CAAC,uBAAuB;AAChC,QAAA,GAAG,OAAO;KACX;IACD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,eAAe,CAAC;IACzD,EAAE,CAAC,aAAa,CACd,IAAI,EACJ,IAAI,CAAC,SAAS,CACZ;AACE,QAAA,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACzC,GAAG,KAAK,CAAC,iBAAiB;QAC1B,eAAe;AAChB,KAAA,EACD,IAAI,EACJ,CAAC,CACF,EACD,MAAM,CACP;AACD,IAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE;AACvB;;;;"}

package/lib/core/transform/tsconfig/isTransformScratchInput.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Whether an input lies lexically in the named disposable transform scratch
+ * tree. An absent scratch root excludes no input. This does not resolve links
+ * or establish physical ownership of an alias outside that spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation An absent scratch address cannot own an input; otherwise native lexical containment tests resolved addresses rather than matching a filename prefix.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-address guard delegates containment to the shared path boundary helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposable input classification follows the actual owned scratch root, not a special basename or expected fixture location.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the disposable lexical boundary, absent-root meaning and physical-alias limitation before separated tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native resolution and the shared containment helper preserve separator, drive and root boundaries without globally folding case or assuming the platform's temporary-directory spelling.
+ * @evidence contracts/performance.md#efficient-algorithms An absent root short-circuits all path work. Otherwise native resolution and lexical relative-path comparison scan the input and scratch spellings, with temporary text sized by their lengths; no filesystem traversal or content read is required.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function isTransformScratchInput(input: string, scratchDirectory: string | undefined): boolean;

package/lib/core/transform/tsconfig/isTransformScratchInput.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Whether an input lies lexically in the named disposable transform scratch
+ * tree. An absent scratch root excludes no input. This does not resolve links
+ * or establish physical ownership of an alias outside that spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation An absent scratch address cannot own an input; otherwise native lexical containment tests resolved addresses rather than matching a filename prefix.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-address guard delegates containment to the shared path boundary helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposable input classification follows the actual owned scratch root, not a special basename or expected fixture location.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the disposable lexical boundary, absent-root meaning and physical-alias limitation before separated tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native resolution and the shared containment helper preserve separator, drive and root boundaries without globally folding case or assuming the platform's temporary-directory spelling.
+ * @evidence contracts/performance.md#efficient-algorithms An absent root short-circuits all path work. Otherwise native resolution and lexical relative-path comparison scan the input and scratch spellings, with temporary text sized by their lengths; no filesystem traversal or content read is required.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function isTransformScratchInput(input: string, scratchDirectory: string | undefined): boolean;

package/lib/core/transform/tsconfig/isTransformScratchInput.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Whether an input lies lexically in the named disposable transform scratch
+ * tree. An absent scratch root excludes no input. This does not resolve links
+ * or establish physical ownership of an alias outside that spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation An absent scratch address cannot own an input; otherwise native lexical containment tests resolved addresses rather than matching a filename prefix.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-address guard delegates containment to the shared path boundary helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposable input classification follows the actual owned scratch root, not a special basename or expected fixture location.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the disposable lexical boundary, absent-root meaning and physical-alias limitation before separated tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native resolution and the shared containment helper preserve separator, drive and root boundaries without globally folding case or assuming the platform's temporary-directory spelling.
+ * @evidence contracts/performance.md#efficient-algorithms An absent root short-circuits all path work. Otherwise native resolution and lexical relative-path comparison scan the input and scratch spellings, with temporary text sized by their lengths; no filesystem traversal or content read is required.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function isTransformScratchInput(input: string, scratchDirectory: string | undefined): boolean;

package/lib/core/transform/tsconfig/isTransformScratchInput.js

@@ -0,0 +1,28 @@
+'use strict';
+
+var path = require('node:path');
+var pathIsWithin = require('../filesystem/pathIsWithin.js');
+
+/**
+ * Whether an input lies lexically in the named disposable transform scratch
+ * tree. An absent scratch root excludes no input. This does not resolve links
+ * or establish physical ownership of an alias outside that spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation An absent scratch address cannot own an input; otherwise native lexical containment tests resolved addresses rather than matching a filename prefix.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-address guard delegates containment to the shared path boundary helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposable input classification follows the actual owned scratch root, not a special basename or expected fixture location.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the disposable lexical boundary, absent-root meaning and physical-alias limitation before separated tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native resolution and the shared containment helper preserve separator, drive and root boundaries without globally folding case or assuming the platform's temporary-directory spelling.
+ * @evidence contracts/performance.md#efficient-algorithms An absent root short-circuits all path work. Otherwise native resolution and lexical relative-path comparison scan the input and scratch spellings, with temporary text sized by their lengths; no filesystem traversal or content read is required.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function isTransformScratchInput(input, scratchDirectory) {
+    return (scratchDirectory !== undefined &&
+        pathIsWithin.pathIsWithin(path.resolve(input), path.resolve(scratchDirectory)));
+}
+
+exports.isTransformScratchInput = isTransformScratchInput;
+//# sourceMappingURL=isTransformScratchInput.js.map

package/lib/core/transform/tsconfig/isTransformScratchInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isTransformScratchInput.js","sources":["../../../../src/core/transform/tsconfig/isTransformScratchInput.ts"],"sourcesContent":[null],"names":["pathIsWithin"],"mappings":";;;;;AAIA;;;;;;;;;;;;;;;AAeG;AACG,SAAU,uBAAuB,CACrC,KAAa,EACb,gBAAoC,EAAA;IAEpC,QACE,gBAAgB,KAAK,SAAS;AAC9B,QAAAA,yBAAY,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAErE;;;;"}

package/lib/core/transform/tsconfig/isTransformScratchInput.mjs

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { pathIsWithin } from '../filesystem/pathIsWithin.mjs';
+
+/**
+ * Whether an input lies lexically in the named disposable transform scratch
+ * tree. An absent scratch root excludes no input. This does not resolve links
+ * or establish physical ownership of an alias outside that spelling.
+ *
+ * @evidence contracts/common.md#principled-implementation An absent scratch address cannot own an input; otherwise native lexical containment tests resolved addresses rather than matching a filename prefix.
+ * @evidence contracts/common.md#clear-and-simple-design One optional-address guard delegates containment to the shared path boundary helper.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Disposable input classification follows the actual owned scratch root, not a special basename or expected fixture location.
+ * @evidence contracts/common.md#meaningful-documentation Native prose states the disposable lexical boundary, absent-root meaning and physical-alias limitation before separated tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Node native resolution and the shared containment helper preserve separator, drive and root boundaries without globally folding case or assuming the platform's temporary-directory spelling.
+ * @evidence contracts/performance.md#efficient-algorithms An absent root short-circuits all path work. Otherwise native resolution and lexical relative-path comparison scan the input and scratch spellings, with temporary text sized by their lengths; no filesystem traversal or content read is required.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Keeps no cache of its own and computes each value once.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+function isTransformScratchInput(input, scratchDirectory) {
+    return (scratchDirectory !== undefined &&
+        pathIsWithin(path.resolve(input), path.resolve(scratchDirectory)));
+}
+
+export { isTransformScratchInput };
+//# sourceMappingURL=isTransformScratchInput.mjs.map

package/lib/core/transform/tsconfig/isTransformScratchInput.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"isTransformScratchInput.mjs","sources":["../../../../src/core/transform/tsconfig/isTransformScratchInput.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAIA;;;;;;;;;;;;;;;AAeG;AACG,SAAU,uBAAuB,CACrC,KAAa,EACb,gBAAoC,EAAA;IAEpC,QACE,gBAAgB,KAAK,SAAS;AAC9B,QAAA,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAErE;;;;"}

package/lib/core/transform/tsconfig/normalizeCompilerOptionsForGeneratedTsconfig.d.cts

@@ -0,0 +1,36 @@
+/**
+ * Reanchor recognized compiler and plugin path fields against `tsconfigDir`.
+ *
+ * The generated tsconfig lives in a temporary directory outside the project, so
+ * a supported relative path (e.g. `"outDir": "../dist"`) that was meaningful
+ * relative to the original tsconfig must be converted to an absolute path
+ * before writing the generated file. Otherwise TypeScript-Go resolves it
+ * against the temp dir.
+ *
+ * `paths` targets are absolutized for the same reason, with the extra twist
+ * that TypeScript-Go rejects bare non-relative targets outright (TS5090) and
+ * has removed `baseUrl` (TS5102), so anchoring them as absolute paths is the
+ * only temp-dir-safe encoding. No synthetic `baseUrl` is ever written.
+ *
+ * @param spell Translation of recognized absolute path fields to the selected
+ *   compiler spelling, which can be best-effort lexical fallback. Arbitrary
+ *   payload fields are not translated. Identity by default
+ *   (samchon/ttsc#1456).
+ * @evidence contracts/common.md#principled-implementation Known compiler path options, paths targets and plugin descriptor/config-file addresses are anchored to the original config directory before the compiler reads a scratch wrapper; unrecognized payload fields are preserved.
+ * @evidence contracts/common.md#clear-and-simple-design A shallow overlay copy separates scalar, list, alias and plugin path boundaries, with existing template and path-specifier helpers owning their grammars.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No unsupported baseUrl or arbitrary plugin-field rewriting compensates for a moved wrapper; only documented path-typed keys are reanchored.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain scratch-relative drift and TypeScript-Go paths constraints, while the private helper documents the plugin keys whose addresses legitimately require normalization.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared config-directory and relative-plugin helpers and Node path interpret supported native forms at the supplied anchor. The supplied spell callback translates recognized addresses without certifying physical lookup; forward slashes encode compiler path-target protocol values.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   The shallow copy scans K option keys; fixed path-key lists still map L list
+ *   entries, A alias keys/T targets and P plugin entries with four recognized
+ *   plugin fields. String/path resolution, target filtering and each supplied
+ *   spell callback add their own costs; output keeps unrelated payload references.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   One current overlay projection coordinates no cross-request result. Equal
+ *   path text alone does not permit suppressing a supplied effectful spell
+ *   callback; generation reading/materialization owners establish broader reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizeCompilerOptionsForGeneratedTsconfig(compilerOptions: Record<string, unknown>, tsconfigDir: string, spell?: (file: string) => string): Record<string, unknown>;

package/lib/core/transform/tsconfig/normalizeCompilerOptionsForGeneratedTsconfig.d.mts

@@ -0,0 +1,36 @@
+/**
+ * Reanchor recognized compiler and plugin path fields against `tsconfigDir`.
+ *
+ * The generated tsconfig lives in a temporary directory outside the project, so
+ * a supported relative path (e.g. `"outDir": "../dist"`) that was meaningful
+ * relative to the original tsconfig must be converted to an absolute path
+ * before writing the generated file. Otherwise TypeScript-Go resolves it
+ * against the temp dir.
+ *
+ * `paths` targets are absolutized for the same reason, with the extra twist
+ * that TypeScript-Go rejects bare non-relative targets outright (TS5090) and
+ * has removed `baseUrl` (TS5102), so anchoring them as absolute paths is the
+ * only temp-dir-safe encoding. No synthetic `baseUrl` is ever written.
+ *
+ * @param spell Translation of recognized absolute path fields to the selected
+ *   compiler spelling, which can be best-effort lexical fallback. Arbitrary
+ *   payload fields are not translated. Identity by default
+ *   (samchon/ttsc#1456).
+ * @evidence contracts/common.md#principled-implementation Known compiler path options, paths targets and plugin descriptor/config-file addresses are anchored to the original config directory before the compiler reads a scratch wrapper; unrecognized payload fields are preserved.
+ * @evidence contracts/common.md#clear-and-simple-design A shallow overlay copy separates scalar, list, alias and plugin path boundaries, with existing template and path-specifier helpers owning their grammars.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No unsupported baseUrl or arbitrary plugin-field rewriting compensates for a moved wrapper; only documented path-typed keys are reanchored.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain scratch-relative drift and TypeScript-Go paths constraints, while the private helper documents the plugin keys whose addresses legitimately require normalization.
+ * @evidence contracts/portability.md#os-neutral-implementation Shared config-directory and relative-plugin helpers and Node path interpret supported native forms at the supplied anchor. The supplied spell callback translates recognized addresses without certifying physical lookup; forward slashes encode compiler path-target protocol values.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   The shallow copy scans K option keys; fixed path-key lists still map L list
+ *   entries, A alias keys/T targets and P plugin entries with four recognized
+ *   plugin fields. String/path resolution, target filtering and each supplied
+ *   spell callback add their own costs; output keeps unrelated payload references.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   One current overlay projection coordinates no cross-request result. Equal
+ *   path text alone does not permit suppressing a supplied effectful spell
+ *   callback; generation reading/materialization owners establish broader reuse.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export declare function normalizeCompilerOptionsForGeneratedTsconfig(compilerOptions: Record<string, unknown>, tsconfigDir: string, spell?: (file: string) => string): Record<string, unknown>;