@ttsc/unplugin 0.30.4 → 0.31.0

package/src/core/transform/tsconfig/createTransformTsconfig.ts

@@ -0,0 +1,98 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { createAliasCompilerOptions } from "../alias/createAliasCompilerOptions";
+import { hostSpelling } from "../envelope/hostSpelling";
+import { normalizePath } from "../filesystem/normalizePath";
+import type { ITransformTsconfigState } from "./ITransformTsconfigState";
+import { normalizeCompilerOptionsForGeneratedTsconfig } from "./normalizeCompilerOptionsForGeneratedTsconfig";
+
+/**
+ * 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 function createTransformTsconfig(
+  props: {
+    aliasPaths: Record<string, string[]>;
+    compilerOptions: Record<string, unknown>;
+    tsconfig: string;
+  },
+  scratchDirectory: string,
+  state: ITransformTsconfigState,
+  compiler: { configDir: string; tsconfig: string },
+): { path: string } {
+  // 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 };
+}

package/src/core/transform/tsconfig/isTransformScratchInput.ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+
+import { pathIsWithin } from "../filesystem/pathIsWithin";
+
+/**
+ * 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 function isTransformScratchInput(
+  input: string,
+  scratchDirectory: string | undefined,
+): boolean {
+  return (
+    scratchDirectory !== undefined &&
+    pathIsWithin(path.resolve(input), path.resolve(scratchDirectory))
+  );
+}

package/src/core/transform/tsconfig/normalizeCompilerOptionsForGeneratedTsconfig.ts

@@ -0,0 +1,114 @@
+import path from "node:path";
+import { isRelativePluginSpecifier } from "ttsc/tsconfig";
+
+import { CONFIG_DIR_TEMPLATE_LIST_OPTIONS } from "../../tsconfig/CONFIG_DIR_TEMPLATE_LIST_OPTIONS";
+import { CONFIG_DIR_TEMPLATE_SCALAR_OPTIONS } from "../../tsconfig/CONFIG_DIR_TEMPLATE_SCALAR_OPTIONS";
+import { absolutizePathsTarget } from "../../tsconfig/absolutizePathsTarget";
+import { resolveConfigDirTemplatePath } from "../../tsconfig/resolveConfigDirTemplatePath";
+import { readPaths } from "../alias/readPaths";
+
+/**
+ * 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 function normalizeCompilerOptionsForGeneratedTsconfig(
+  compilerOptions: Record<string, unknown>,
+  tsconfigDir: string,
+  spell: (file: string) => string = (file) => file,
+): Record<string, unknown> {
+  const output = { ...compilerOptions };
+  // Scalar path fields: resolve each against the original tsconfig directory.
+  for (const key of CONFIG_DIR_TEMPLATE_SCALAR_OPTIONS) {
+    if (typeof output[key] === "string") {
+      output[key] = spell(
+        resolveConfigDirTemplatePath(tsconfigDir, output[key]),
+      );
+    }
+  }
+  // Array path fields: resolve each element individually.
+  for (const key of CONFIG_DIR_TEMPLATE_LIST_OPTIONS) {
+    if (Array.isArray(output[key])) {
+      output[key] = output[key].map((entry) =>
+        typeof entry === "string"
+          ? spell(resolveConfigDirTemplatePath(tsconfigDir, entry))
+          : entry,
+      );
+    }
+  }
+  const paths = readPaths(output.paths);
+  if (Object.keys(paths).length !== 0) {
+    output.paths = Object.fromEntries(
+      Object.entries(paths).map(([key, targets]) => [
+        key,
+        targets.map((target) =>
+          spell(absolutizePathsTarget(tsconfigDir, target)).replace(/\\/g, "/"),
+        ),
+      ]),
+    );
+  }
+  if (Array.isArray(output.plugins)) {
+    output.plugins = output.plugins.map((entry) =>
+      normalizePluginConfigForGeneratedTsconfig(entry, tsconfigDir, spell),
+    );
+  }
+  return output;
+}
+
+/**
+ * Absolutize the relative path-typed keys of one plugin entry before it is
+ * written into the generated temp-dir tsconfig: `config`/`source`/`transform`
+ * are the descriptor-resolution keys, and `configFile` is the config-file
+ * override accepted by the shipped utility plugins (`@ttsc/banner`,
+ * `@ttsc/strip`, `@ttsc/lint`). Left relative, each would resolve against the
+ * temp directory instead of the project.
+ */
+function normalizePluginConfigForGeneratedTsconfig(
+  entry: unknown,
+  tsconfigDir: string,
+  spell: (file: string) => string,
+): unknown {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    return entry;
+  }
+  const output: Record<string, unknown> = { ...entry };
+  for (const key of ["config", "configFile", "source", "transform"]) {
+    const value = output[key];
+    if (typeof value === "string" && isRelativePluginSpecifier(value)) {
+      output[key] = spell(path.resolve(tsconfigDir, value));
+    } else if (typeof value === "string" && path.isAbsolute(value)) {
+      output[key] = spell(value);
+    }
+  }
+  return output;
+}

package/src/core/transform/tsconfig/readTransformTsconfigState.ts

@@ -0,0 +1,75 @@
+import { readEffectiveTsconfigPaths } from "../../tsconfig/readEffectiveTsconfigPaths";
+import { readEffectiveTsconfigTemplateCompilerOptions } from "../../tsconfig/readEffectiveTsconfigTemplateCompilerOptions";
+import { readEffectiveTsconfigTemplateFileSpecs } from "../../tsconfig/readEffectiveTsconfigTemplateFileSpecs";
+import { readProjectMembershipPolicy } from "../../tsconfig/readProjectMembershipPolicy";
+import { readTsconfigSourceSnapshot } from "../../tsconfig/readTsconfigSourceSnapshot";
+import { hashText } from "../utils/hashText";
+import type { ITransformTsconfigState } from "./ITransformTsconfigState";
+
+/**
+ * Assemble membership and wrapper-dependent views with a config-chain digest.
+ * Readers make separate native observations; the digest is a composite for
+ * capture's before/after comparison, not one atomic config-chain snapshot.
+ *
+ * @param compilerConfigDir The project's config directory as the compiler
+ *   spells it, which the wrapper's re-stated `${configDir}` values are anchored
+ *   at (samchon/ttsc#1456); the config's own directory as named when absent.
+ * @evidence contracts/common.md#principled-implementation Membership policy is always read; materialized wrappers additionally combine effective paths/templates and separately observed source bytes into capture's before/after digest. Digest equality compares those observations without proving the filesystem never changed between reads.
+ * @evidence contracts/common.md#clear-and-simple-design Existing readers own configuration interpretation; this operation assembles the required views and skips wrapper-only work when no wrapper is needed.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The signature includes source bytes as well as derived views, rather than letting a quiet watcher or one unchanged option stand in for the entire configuration chain.
+ * @evidence contracts/common.md#meaningful-documentation The native comment identifies wrapper-dependent state, and the parameter paragraph explains why inherited template resolution uses compiler spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation Existing readers own native resolution and filesystem observations; the optional compilerConfigDir is a supplied best-effort template anchor, not certified physical identity or proof adapter and compiler spellings coincide.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Membership is one reader pass. Materialization additionally invokes paths,
+ *   compiler-template, file-template and raw-source readers with separate parse
+ *   transactions, then serializes and hashes B composite bytes. Config depth,
+ *   package/native lookup, source bytes and derived option/spec counts drive
+ *   cost; no-loop assembly does not erase those repeated delegated passes.
+ * @evidence contracts/performance.md#reuse-equivalent-work
+ *   One returned bundle serves membership, wrapper construction and capture's
+ *   digest comparison. Reader-local transactions share their option queries,
+ *   without claiming a shared parse transaction across these views. A later
+ *   before/after question creates a fresh bundle rather than retaining old bytes.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function readTransformTsconfigState(
+  tsconfig: string,
+  materializesConfig: boolean,
+  compilerConfigDir?: string,
+): ITransformTsconfigState {
+  const membershipPolicy = readProjectMembershipPolicy(tsconfig);
+  if (!materializesConfig) {
+    return {
+      effectivePaths: {},
+      membershipPolicy,
+      templateCompilerOptions: {},
+      templateFileSpecs: {},
+    };
+  }
+  const effectivePaths = readEffectiveTsconfigPaths(tsconfig);
+  const templateCompilerOptions = readEffectiveTsconfigTemplateCompilerOptions(
+    tsconfig,
+    compilerConfigDir,
+  );
+  const templateFileSpecs = readEffectiveTsconfigTemplateFileSpecs(
+    tsconfig,
+    compilerConfigDir,
+  );
+  const sources = readTsconfigSourceSnapshot(tsconfig);
+  return {
+    effectivePaths,
+    membershipPolicy,
+    signature: hashText(
+      JSON.stringify({
+        effectivePaths,
+        membershipPolicy,
+        sources,
+        templateCompilerOptions,
+        templateFileSpecs,
+      }),
+    ),
+    templateCompilerOptions,
+    templateFileSpecs,
+  };
+}

package/src/core/transform/tsconfig/resolveProjectSelection.ts

@@ -0,0 +1,77 @@
+import path from "node:path";
+
+import { discoverNearestProjectTsconfig } from "../../discovery/discoverNearestProjectTsconfig";
+import { selectReferencedProject } from "../../tsconfig/selectReferencedProject";
+import { DEFAULT_FILESYSTEM_OPERATIONS } from "../filesystem/DEFAULT_FILESYSTEM_OPERATIONS";
+import type { TtscTransformFilesystemOperations } from "../filesystem/TtscTransformFilesystemOperations";
+
+/**
+ * Select the transform tsconfig and consulted routing spellings for `file`.
+ *
+ * An explicit `tsconfig` is returned as-is (absolute) or resolved from
+ * `process.cwd()` (relative), and decides alone. Otherwise the nearest ancestor
+ * `tsconfig.json` proven to be a file is the starting point, and a solution
+ * config's `references` are followed to the project whose root-file selection
+ * admits the file (samchon/ttsc#1397). With no ancestor config the answer is
+ * `<cwd>/tsconfig.json`; the compiler will error if that file does not exist,
+ * which is the correct behavior for a mis-configured project.
+ *
+ * When discovery finds a config, nearer candidates not observed as files are
+ * retained too. That can mean absence, another kind or unavailable metadata: a
+ * `tsconfig.json` appearing beside the file re-routes it to another project,
+ * and nothing else it read would change (samchon/ttsc#1543). With no discovered
+ * config, the cwd fallback returns no consulted ancestor spellings, avoiding
+ * registration of machine-wide ancestors. This result does not provide
+ * observation proof or a watch for every failed discovery candidate.
+ *
+ * @evidence contracts/common.md#principled-implementation Explicit selection bypasses discovery. A discovered config follows referenced root-file admission and retains passed-over nonfile candidates; the no-config cwd fallback deliberately returns no consulted ancestors rather than certifying those unknown or absent paths unchanged.
+ * @evidence contracts/common.md#clear-and-simple-design Three direct branches separate explicit selection, discovered reference selection and no-config fallback; existing helpers own discovery and reference traversal.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The fallback address is the caller's cwd config, not a fixture-specific project or successful existence proof. Discovered-route passed-over spellings remain explicit; downstream consumers must distinguish spellings from actual selection observations.
+ * @evidence contracts/common.md#meaningful-documentation Native paragraphs explain relative explicit anchoring, reference selection, the missing-config fallback and why absent nearer candidates are consulted inputs.
+ * @evidence contracts/portability.md#os-neutral-implementation Node isAbsolute/dirname/resolution establish native anchors. Supplied discovery operations control its candidate dialect/checks, while referenced selection uses the native config readers and compiler policy; those views must agree, and injection does not replace all downstream native reads.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Explicit selection does path text work only. Implicit discovery visits D
+ *   ancestors/native stat candidates and filters/copies their references;
+ *   referenced selection adds reachable-config/source-byte/spec matching work,
+ *   despite this wrapper delegating its graph traversal.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Discovery is a current routing question and this operation stores no
+ *   cross-request selection. Referenced config-entry caching and generation
+ *   reuse qualification remain with their own observed-input owners.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function resolveProjectSelection(
+  file: string,
+  tsconfig?: string,
+  filesystem: TtscTransformFilesystemOperations = DEFAULT_FILESYSTEM_OPERATIONS,
+): { consulted: string[]; tsconfig: string } {
+  if (tsconfig !== undefined) {
+    return {
+      consulted: [],
+      tsconfig: path.isAbsolute(tsconfig)
+        ? tsconfig
+        : path.resolve(process.cwd(), tsconfig),
+    };
+  }
+  const discovery = discoverNearestProjectTsconfig(
+    path.dirname(file),
+    filesystem,
+  );
+  const passedOver = discovery.candidates
+    .filter((candidate) => !candidate.fileExists)
+    .map((candidate) => candidate.file);
+  if (discovery.file !== undefined) {
+    const selection = selectReferencedProject(file, discovery.file);
+    return {
+      consulted: [...passedOver, ...selection.consulted],
+      tsconfig: selection.tsconfig,
+    };
+  }
+  // With no config at all the walk reached the volume root, and watching
+  // every ancestor up to it would watch directories far outside any project.
+  return {
+    consulted: [],
+    tsconfig: path.resolve(process.cwd(), "tsconfig.json"),
+  };
+}

package/src/core/transform/tsconfig/transformScratchEnvironment.ts

@@ -0,0 +1,36 @@
+/**
+ * The environment a compile runs under: the host's own, with `TEMP`, `TMP`, and
+ * `TMPDIR` naming the compile's scratch directory. Consumers honoring these
+ * variables use that temporary root; explicit paths or overridden child
+ * environments are not confined by these settings.
+ *
+ * Capture hands this copy to the compiler as `env` (samchon/ttsc#1488);
+ * applying it to workers and inherited child environments belongs to the
+ * compiler host. This function leaves the host's own environment unchanged.
+ *
+ * @param directory The compile's scratch directory.
+ * @evidence contracts/common.md#principled-implementation A copied environment preserves host settings and supplies three temporary-root overrides to capture's compiler request. This routes cooperating consumers, not arbitrary plugin writes or independently overridden child environments.
+ * @evidence contracts/common.md#clear-and-simple-design One environment object expresses the child-process override without mutating process globals or introducing platform-specific execution wrappers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Temporary routing changes only the launched compile's environment, avoiding global monkeypatches or project-local scratch that would contaminate watched inputs.
+ * @evidence contracts/common.md#meaningful-documentation The native paragraphs identify the child-process propagation boundary and explicitly distinguish it from changing the host environment.
+ * @evidence contracts/portability.md#os-neutral-implementation All three native temporary-directory variables receive the same owned directory, covering Windows and Unix child consumers without constructing shell syntax or mutating the host environment.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   The spread enumerates K process environment keys/values into a fresh object
+ *   before three assignments. Key/value text and native environment retrieval
+ *   contribute costs; absence of an explicit loop is not constant work.
+ * @evidenceExclude contracts/performance.md#reuse-equivalent-work
+ *   Each call copies current host settings and one owner's temporary address;
+ *   equal directory strings do not prove unchanged environment observations.
+ * @evidenceExclude contracts/performance.md#bound-retention-and-release-resources
+ *   Acquires no handle, timer or retained state of its own.
+ */
+export function transformScratchEnvironment(
+  directory: string,
+): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    TEMP: directory,
+    TMP: directory,
+    TMPDIR: directory,
+  };
+}

package/src/core/transform/utils/createTransformResult.ts

@@ -0,0 +1,58 @@
+import type { TtscTransformResult } from "../TtscTransformResult";
+import type { TtscTransformedOutput } from "../envelope/TtscTransformedOutput";
+import { resolveTransformSourceMap } from "./resolveTransformSourceMap";
+
+/**
+ * Build the unplugin transform result, or `undefined` when the transform
+ * produced no changes.
+ *
+ * Returning `undefined` instead of `{ code: source }` lets the bundler skip the
+ * unnecessary module update and preserves the original source map. A changed
+ * module carries the envelope's source map when it describes the delivered
+ * text, so the bundler can map the transformed text back to the author's lines.
+ * Otherwise it carries none rather than a map that would point at the wrong
+ * lines.
+ *
+ * @param file Absolute path of the transformed module.
+ * @param source Text the bundler delivered for the module.
+ * @param output The envelope's entry for the module.
+ * @evidence contracts/common.md#principled-implementation
+ *   Equal delivered/emitted text needs no update; changed text carries a map
+ *   only after its source content is matched to what this host delivered.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   The operation owns the optional result shape and delegates map validation
+ *   to resolveTransformSourceMap rather than mixing host-specific map policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   Dropping an unverifiable map preserves the existing mapless contract;
+ *   it does not substitute fabricated locations to satisfy a known example.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain no-change and mismatched-source effects, and
+ *   tagged parameters follow the documentation guidance's prose separation.
+ * @evidence contracts/portability.md#os-neutral-implementation
+ *   The absolute native module path is passed to the shared map resolver,
+ *   which resolves sources and observes actual filesystem aliases and case
+ *   policy before emitting forward-slash source-map paths.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Equal code avoids map processing entirely. Changed code compares supplied
+ *   text and, when a map exists, delegates one source-list normalization and
+ *   identity search; cost grows with text and source-path lengths and native
+ *   identity observations, rather than remaining constant at this wrapper.
+ * @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 function createTransformResult(
+  file: string,
+  source: string,
+  output: TtscTransformedOutput,
+): TtscTransformResult | undefined {
+  if (source === output.code) {
+    return undefined;
+  }
+  const map =
+    output.map === undefined
+      ? undefined
+      : resolveTransformSourceMap(file, source, output.map);
+  return map === undefined ? { code: output.code } : { code: output.code, map };
+}

package/src/core/transform/utils/hashText.ts

@@ -0,0 +1,32 @@
+import crypto from "node:crypto";
+
+/**
+ * SHA-256 hex digest of text or bytes.
+ *
+ * The single content fingerprint every generation proof uses, so hashes
+ * recorded at capture and recomputed during validation are always comparable.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Node's SHA-256 hashes strings as UTF-8 and Buffer bytes directly; hex
+ *   supplies the uniform content fingerprint generation readers compare.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One helper owns algorithm and encoding selection for content evidence.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The digest is computed from supplied contents rather than expected results.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose names algorithm, encoding and shared validation purpose with
+ *   a blank acknowledgment separator following documentation guidance.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Hashes bytes with node:crypto; no path or OS-specific behaviour.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   One native SHA-256 update scans the supplied UTF-8 text or bytes once;
+ *   the digest has fixed size. No intermediate byte copy is required for a
+ *   Buffer, and no historical content is retained by this helper.
+ * @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 function hashText(input: string | Buffer): string {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}

package/src/core/transform/utils/inlineSourceMap.ts

@@ -0,0 +1,42 @@
+import type { TtscTransformResult } from "../TtscTransformResult";
+
+/**
+ * A transform result's code with its source map appended as an inline
+ * `sourceMappingURL` comment.
+ *
+ * Esbuild's `onLoad` and Bun's plugin `onLoad` take only `contents`, with no
+ * separate map. esbuild reads a trailing inline source map from loaded contents
+ * and composes it into the bundle's map. A result without a map is returned as
+ * its bare code.
+ *
+ * @param result The transform result to hand to a contents-only host.
+ * @returns The contents to return from the host's `onLoad`.
+ * @evidence contracts/common.md#principled-implementation
+ *   JSON encoded as UTF-8 base64 gives contents-only hosts an inline v3 map;
+ *   a line boundary prevents the directive from joining the final source line.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   This helper adapts an already-validated result without owning map validation.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The data URI and directive use source-map conventions, not host internals.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native paragraphs explain why Bun/esbuild need an inline map and why absence
+ *   returns bare code, with prose separated from tags per documentation guidance.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Performs no filesystem, path or process operation of its own.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   With no map, returns the existing code. Otherwise one JSON serialization
+ *   and UTF-8/base64 encoding cost linear time and temporary space in map
+ *   size; appending the directive also accounts for the delivered code length.
+ * @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 function inlineSourceMap(result: TtscTransformResult): string {
+  if (result.map === undefined) {
+    return result.code;
+  }
+  const json = JSON.stringify(result.map);
+  const separator = result.code.endsWith("\n") ? "" : "\n";
+  return `${result.code}${separator}//# sourceMappingURL=data:application/json;charset=utf-8;base64,${Buffer.from(json, "utf8").toString("base64")}\n`;
+}

package/src/core/transform/utils/isDeclarationFile.ts

@@ -0,0 +1,44 @@
+/**
+ * Returns `true` for every declaration-file spelling TypeScript-Go accepts.
+ * Besides the standard `.d.ts`, `.d.mts`, and `.d.cts` forms, TypeScript-Go
+ * treats an arbitrary-extension source such as `styles.d.css.ts` as a
+ * declaration file too.
+ *
+ * @evidence contracts/common.md#principled-implementation
+ *   Taking the basename after separator normalization prevents directory names
+ *   containing .d. from classifying source; suffixes cover module declaration
+ *   forms and the arbitrary-extension .d.*.ts convention.
+ * @evidence contracts/common.md#clear-and-simple-design
+ *   One basename classifier owns the declaration spelling policy for adapters.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts
+ *   The suffix branches express compiler declaration conventions rather than
+ *   paths from a particular project or test.
+ * @evidence contracts/common.md#meaningful-documentation
+ *   Native prose explains the non-obvious arbitrary-extension form and separator
+ *   handling; tags are separated as documentation guidance requires.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation
+ *   Classifies module identifier basenames with both protocol separators;
+ *   it does not infer native filesystem identity or case sensitivity.
+ * @evidence contracts/performance.md#efficient-algorithms
+ *   Separator normalization and basename extraction take linear time and
+ *   temporary space in identifier length. Fixed suffix checks inspect the
+ *   basename, without traversing directories or constructing per-call patterns.
+ * @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 function isDeclarationFile(id: string): boolean {
+  // Module ids can cross process/platform boundaries (for example, a Windows
+  // id inspected by a POSIX host). TypeScript-Go normalizes both separators
+  // before taking the basename, so a `.d.` directory component must not turn
+  // an ordinary source into a declaration file.
+  const normalized = id.replaceAll("\\", "/");
+  const base = normalized.slice(normalized.lastIndexOf("/") + 1);
+  return (
+    base.endsWith(".d.ts") ||
+    base.endsWith(".d.mts") ||
+    base.endsWith(".d.cts") ||
+    (base.endsWith(".ts") && base.includes(".d."))
+  );
+}