ttsc 0.7.0 → 0.7.2

package/lib/structures/ITtscCompilerTransformation.d.ts

@@ -0,0 +1,35 @@
+import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
+/**
+ * Result of a TypeScript source-to-source transformation operation.
+ *
+ * This mirrors `embed-typescript`'s `IEmbedTypeScriptTransformation` model.
+ * Unlike {@link ITtscCompilerResult}, this contract is not an emit contract:
+ * the `typescript` map must contain TypeScript source text, not generated
+ * JavaScript, declaration files, or source maps.
+ */
+export type ITtscCompilerTransformation = ITtscCompilerTransformation.ISuccess | ITtscCompilerTransformation.IFailure | ITtscCompilerTransformation.IException;
+export declare namespace ITtscCompilerTransformation {
+    /** Successful source-to-source transformation result. */
+    interface ISuccess {
+        /** Indicates that transformation completed without diagnostics. */
+        type: "success";
+        /** Transformed TypeScript source text keyed by project file path. */
+        typescript: Record<string, string>;
+    }
+    /** Source-to-source transformation result that completed with diagnostics. */
+    interface IFailure {
+        /** Indicates that transformation completed with diagnostics. */
+        type: "failure";
+        /** Transformed or partially transformed TypeScript source text. */
+        typescript: Record<string, string>;
+        /** Diagnostics reported during transformation. */
+        diagnostics: ITtscCompilerDiagnostic[];
+    }
+    /** Unexpected host-level error during transformation. */
+    interface IException {
+        /** Indicates that transformation could not complete normally. */
+        type: "exception";
+        /** Raw error thrown by the ttsc host. */
+        error: unknown;
+    }
+}

package/lib/structures/ITtscCompilerTransformation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ITtscCompilerTransformation.js.map

package/lib/structures/ITtscCompilerTransformation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITtscCompilerTransformation.js","sourceRoot":"","sources":["../../src/structures/ITtscCompilerTransformation.ts"],"names":[],"mappings":""}

package/lib/structures/TtscPluginStage.d.ts

@@ -1,10 +1,13 @@
 /**
  * Pipeline stage where a plugin's lazily built Go sidecar participates.
  *
- * - `"transform"`: owns the TypeScript-Go emit pass. This is the default and
- *   is the right stage for compiler-transform plugins such as typia-style
- *   source rewrites. A transform sidecar receives the ordered plugin manifest
- *   and is responsible for producing the project's emitted output.
+ * - `"transform"`: owns the TypeScript transform/emit pass. This is the
+ *   default and is the right stage for compiler-transform plugins such as
+ *   typia-style source rewrites. During compilation, a transform sidecar
+ *   produces the project's emitted output. During
+ *   {@link TtscCompiler.transform}, the same sidecar may expose a
+ *   source-to-source `transform` command that returns transformed TypeScript
+ *   text.
  * - `"check"`: runs before emit and reports diagnostics only. Use this for
  *   lint or validation plugins that should fail the compile before JavaScript
  *   or declaration output is generated.

package/lib/structures/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./ITtscCompilerContext";
 export * from "./ITtscCompilerDiagnostic";
 export * from "./ITtscCompilerResult";
+export * from "./ITtscCompilerTransformation";
 export * from "./ITtscPlugin";
 export * from "./ITtscPluginFactoryContext";
 export * from "./ITtscProjectPluginConfig";

package/lib/structures/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ITtscCompilerContext"), exports);
 __exportStar(require("./ITtscCompilerDiagnostic"), exports);
 __exportStar(require("./ITtscCompilerResult"), exports);
+__exportStar(require("./ITtscCompilerTransformation"), exports);
 __exportStar(require("./ITtscPlugin"), exports);
 __exportStar(require("./ITtscPluginFactoryContext"), exports);
 __exportStar(require("./ITtscProjectPluginConfig"), exports);

package/lib/structures/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,4DAA0C;AAC1C,wDAAsC;AACtC,gDAA8B;AAC9B,8DAA4C;AAC5C,6DAA2C;AAC3C,oDAAkC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/structures/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,4DAA0C;AAC1C,wDAAsC;AACtC,gEAA8C;AAC9C,gDAA8B;AAC9B,8DAA4C;AAC5C,6DAA2C;AAC3C,oDAAkC"}

package/lib/structures/internal/TtscCommonOptions.d.ts

@@ -1,5 +1,5 @@
 import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
-/** Internal options shared by the CLI build, transform, and runtime paths. */
+/** Internal options shared by the CLI build, single-file emit, and runtime paths. */
 export interface TtscCommonOptions {
     /**
      * Explicit TypeScript-Go executable.

package/lib/structures/internal/{TtscTransformOptions.d.ts → TtscSingleFileEmitOptions.d.ts}

@@ -1,11 +1,11 @@
 import type { TtscCommonOptions } from "./TtscCommonOptions";
-/** Internal options for transforming one source file through the CLI path. */
-export interface TtscTransformOptions extends TtscCommonOptions {
-    /** Source file to transform. Absolute paths and `cwd`-relative paths work. */
+/** Internal options for emitting one source file through the file-argument path. */
+export interface TtscSingleFileEmitOptions extends TtscCommonOptions {
+    /** Source file to emit. Absolute paths and `cwd`-relative paths work. */
     file: string;
     /** Project config owning `file`; discovered from `file` when omitted. */
     tsconfig?: string;
-    /** Optional output file path. Omit to return emitted text from stdout. */
+    /** Optional output file path. */
     out?: string;
     /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
     quiet?: boolean;

package/lib/structures/internal/{TtscTransformOptions.js → TtscSingleFileEmitOptions.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=TtscTransformOptions.js.map
+//# sourceMappingURL=TtscSingleFileEmitOptions.js.map

package/lib/structures/internal/TtscSingleFileEmitOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TtscSingleFileEmitOptions.js","sourceRoot":"","sources":["../../../src/structures/internal/TtscSingleFileEmitOptions.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttsc",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "General-purpose TypeScript-Go compiler, plugin host, and runtime.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -31,13 +31,13 @@
     "rimraf": "^6.1.2"
   },
   "optionalDependencies": {
-    "@ttsc/linux-x64": "0.7.0",
-    "@ttsc/linux-arm": "0.7.0",
-    "@ttsc/darwin-arm64": "0.7.0",
-    "@ttsc/linux-arm64": "0.7.0",
-    "@ttsc/darwin-x64": "0.7.0",
-    "@ttsc/win32-x64": "0.7.0",
-    "@ttsc/win32-arm64": "0.7.0"
+    "@ttsc/linux-x64": "0.7.2",
+    "@ttsc/linux-arm": "0.7.2",
+    "@ttsc/linux-arm64": "0.7.2",
+    "@ttsc/darwin-x64": "0.7.2",
+    "@ttsc/darwin-arm64": "0.7.2",
+    "@ttsc/win32-x64": "0.7.2",
+    "@ttsc/win32-arm64": "0.7.2"
   },
   "sideEffects": false,
   "files": [

package/src/TtscCompiler.ts

@@ -4,10 +4,12 @@ import * as path from "node:path";
 import { compileProjectInMemory } from "./compiler/internal/compileProjectInMemory";
 import { resolveProjectConfig } from "./compiler/internal/project/resolveProjectConfig";
 import { resolveBinary } from "./compiler/internal/resolveBinary";
+import { transformProjectInMemory } from "./compiler/internal/transformProjectInMemory";
 import { loadProjectPlugins } from "./plugin/internal/loadProjectPlugins";
 import type { ITtscCompilerContext } from "./structures/ITtscCompilerContext";
 import type { ITtscCompilerDiagnostic } from "./structures/ITtscCompilerDiagnostic";
 import type { ITtscCompilerResult } from "./structures/ITtscCompilerResult";
+import type { ITtscCompilerTransformation } from "./structures/ITtscCompilerTransformation";
 import type { TtscBuildResult } from "./structures/internal/TtscBuildResult";
 
 /**
@@ -28,6 +30,8 @@ import type { TtscBuildResult } from "./structures/internal/TtscBuildResult";
  *   context.
  * - {@link TtscCompiler.compile}: compile the configured project and return a
  *   structured result instead of terminal text.
+ * - {@link TtscCompiler.transform}: transform the configured project and
+ *   return an embed-style transformation result.
  */
 export class TtscCompiler {
   private readonly context: ITtscCompilerContext;
@@ -116,6 +120,28 @@ export class TtscCompiler {
     return runProject(() => compileProjectInMemory(this.compilerContext()));
   }
 
+  /**
+   * Transform the configured project and return TypeScript text by file path.
+   *
+   * This is the source-to-source API for plugin authors. It must not return
+   * JavaScript emit, declaration files, or source maps; those artifacts belong
+   * to {@link TtscCompiler.compile}. A transform sidecar is expected to write
+   * JSON shaped as `{ "typescript": { "src/file.ts": "..." } }` to stdout.
+   * When no transform sidecar is configured, ttsc returns the TypeScript files
+   * loaded by the TypeScript-Go Program together with normal diagnostics.
+   *
+   * The returned shape mirrors `embed-typescript`'s transformation API:
+   * `success` and `failure` carry a `typescript` map, while unexpected host
+   * errors return `exception`.
+   *
+   * @returns Transformation result containing TypeScript text or diagnostics.
+   */
+  public transform(): ITtscCompilerTransformation {
+    return runTransformation(() =>
+      transformProjectInMemory(this.compilerContext()),
+    );
+  }
+
   private compilerContext(): ITtscCompilerContext {
     return {
       ...this.context,
@@ -186,6 +212,11 @@ interface ProjectResult {
   result: TtscBuildResult;
 }
 
+interface ProjectTransformation {
+  result: TtscBuildResult;
+  typescript: Record<string, string>;
+}
+
 function runProject(task: () => ProjectResult): ITtscCompilerResult {
   try {
     return toCompilerResult(task());
@@ -197,6 +228,19 @@ function runProject(task: () => ProjectResult): ITtscCompilerResult {
   }
 }
 
+function runTransformation(
+  task: () => ProjectTransformation,
+): ITtscCompilerTransformation {
+  try {
+    return toCompilerTransformation(task());
+  } catch (error) {
+    return {
+      error: normalizeError(error),
+      type: "exception",
+    };
+  }
+}
+
 function toCompilerResult(project: ProjectResult): ITtscCompilerResult {
   const { output, result } = project;
   if (result.status === 0 && result.diagnostics.length === 0) {
@@ -229,6 +273,26 @@ function createProcessDiagnostic(
   };
 }
 
+function toCompilerTransformation(
+  project: ProjectTransformation,
+): ITtscCompilerTransformation {
+  const { result, typescript } = project;
+  if (result.status === 0 && result.diagnostics.length === 0) {
+    return {
+      type: "success",
+      typescript,
+    };
+  }
+  return {
+    diagnostics:
+      result.diagnostics.length === 0
+        ? [createProcessDiagnostic(result)]
+        : result.diagnostics,
+    type: "failure",
+    typescript,
+  };
+}
+
 function normalizeError(error: unknown): unknown {
   if (!(error instanceof Error)) {
     return error;

package/src/compiler/internal/{runTransform.ts → runSingleFileEmit.ts}

@@ -2,16 +2,18 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import type { TtscTransformOptions } from "../../structures/internal/TtscTransformOptions";
+import type { TtscSingleFileEmitOptions } from "../../structures/internal/TtscSingleFileEmitOptions";
 import { resolveProjectConfig } from "./project/resolveProjectConfig";
 import { resolveEmittedJavaScript } from "./resolveEmittedJavaScript";
 import { runBuild } from "./runBuild";
 
-/** Transform one source file by emitting its project into a temporary directory. */
-export function runTransform(options: TtscTransformOptions): string {
+/** Emit one source file by building its project into a temporary directory. */
+export function runSingleFileEmit(options: TtscSingleFileEmitOptions): string {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const sourceFile = realpathIfExists(
-    path.isAbsolute(options.file) ? options.file : path.resolve(cwd, options.file),
+    path.isAbsolute(options.file)
+      ? options.file
+      : path.resolve(cwd, options.file),
   );
   const tsconfig = resolveProjectConfig({
     cwd,
@@ -19,7 +21,7 @@ export function runTransform(options: TtscTransformOptions): string {
     tsconfig: options.tsconfig,
   });
   const projectRoot = path.dirname(tsconfig);
-  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-transform-"));
+  const outDir = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-single-file-"));
   try {
     const result = runBuild({
       ...options,
@@ -31,7 +33,7 @@ export function runTransform(options: TtscTransformOptions): string {
     });
     if (result.status !== 0) {
       throw new Error(
-        "ttsc transform exited " +
+        "ttsc single-file emit exited " +
           result.status +
           "\n" +
           (result.stderr || result.stdout),
@@ -44,7 +46,9 @@ export function runTransform(options: TtscTransformOptions): string {
       sourceFile,
     });
     if (emitted === null) {
-      throw new Error(`ttsc transform: no output produced for ${sourceFile}`);
+      throw new Error(
+        `ttsc single-file emit: no output produced for ${sourceFile}`,
+      );
     }
     const transformed = fs.readFileSync(emitted, "utf8");
     if (options.out) {

package/src/compiler/internal/transformProjectInMemory.ts

@@ -0,0 +1,368 @@
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { loadProjectPlugins } from "../../plugin/internal/loadProjectPlugins";
+import type { ITtscCompilerContext } from "../../structures/ITtscCompilerContext";
+import type { ITtscCompilerDiagnostic } from "../../structures/ITtscCompilerDiagnostic";
+import type { ITtscProjectPluginConfig } from "../../structures/ITtscProjectPluginConfig";
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
+import type { TtscBuildResult } from "../../structures/internal/TtscBuildResult";
+import { buildNativeCompiler } from "./buildNativeCompiler";
+import { readProjectConfig } from "./project/readProjectConfig";
+import { resolveBinary } from "./resolveBinary";
+import { resolveTsgo } from "./resolveTsgo";
+
+/** Transform a project and capture TypeScript source output in memory. */
+export function transformProjectInMemory(options: ITtscCompilerContext): {
+  result: TtscBuildResult;
+  typescript: Record<string, string>;
+} {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const project = readProjectConfig({
+    cwd,
+    tsconfig: options.tsconfig,
+  });
+  if (configuredPlugins(options, project).length !== 0) {
+    return transformProjectWithPlugins(options, cwd, project);
+  }
+  return transformProjectWithNativeHost(options, project);
+}
+
+function configuredPlugins(
+  options: ITtscCompilerContext,
+  project: ITtscParsedProjectConfig,
+): ITtscProjectPluginConfig[] {
+  if (options.plugins === false) {
+    return [];
+  }
+  const entries = options.plugins ?? project.compilerOptions.plugins;
+  return entries.filter((entry) => entry.enabled !== false);
+}
+
+function transformProjectWithNativeHost(
+  options: ITtscCompilerContext,
+  project: ITtscParsedProjectConfig,
+): {
+  result: TtscBuildResult;
+  typescript: Record<string, string>;
+} {
+  const binary = buildNativeCompiler({
+    cacheBaseDir: project.root,
+    cacheDir: options.cacheDir,
+    packageRoot: packageRootDir(),
+  });
+  const res = spawnNative(
+    binary,
+    ["api-transform", "--cwd", project.root, "--tsconfig", project.path],
+    {
+      cwd: project.root,
+      env: { ...process.env, ...options.env },
+    },
+  );
+  if (res.error) {
+    throw new Error(
+      `ttsc: failed to spawn native compiler host ${binary}: ${res.error.message}`,
+    );
+  }
+
+  const output = parseNativeTransformOutput(
+    outputText(res.stdout),
+    outputText(res.stderr),
+  );
+  return {
+    result: {
+      diagnostics: output.diagnostics,
+      status: res.status ?? 1,
+      stdout: "",
+      stderr: outputText(res.stderr),
+    },
+    typescript: output.typescript,
+  };
+}
+
+function transformProjectWithPlugins(
+  options: ITtscCompilerContext,
+  cwd: string,
+  project: ITtscParsedProjectConfig,
+): {
+  result: TtscBuildResult;
+  typescript: Record<string, string>;
+} {
+  const loaded = loadProjectPlugins({
+    binary: resolveBinary(options) ?? "",
+    cacheDir: options.cacheDir ?? options.env?.TTSC_CACHE_DIR,
+    cwd,
+    entries: options.plugins,
+    tsconfig: project.path,
+  });
+  const checks = loaded.nativePlugins.filter(
+    (plugin) => plugin.stage === "check",
+  );
+  const transformers = loaded.nativePlugins.filter(
+    (plugin) => plugin.stage === "transform",
+  );
+  const checked = runNativeChecks(
+    options,
+    project,
+    loaded.nativePlugins,
+    checks,
+  );
+  if (checked.status !== 0) {
+    return {
+      result: checked,
+      typescript: {},
+    };
+  }
+  if (transformers.length === 0) {
+    return transformProjectWithNativeHost(options, project);
+  }
+  assertSingleTransformHost(transformers);
+
+  const plugin = transformers[0]!;
+  const res = spawnNative(
+    plugin.binary,
+    createNativeTransformArgs(project, transformers),
+    {
+      cwd: project.root,
+      env: nativePluginEnv(options, project.root),
+    },
+  );
+  if (res.error) {
+    throw new Error(
+      `ttsc.transform: failed to spawn ${plugin.binary}: ${res.error.message}`,
+    );
+  }
+  const output = parseNativeTransformOutput(
+    outputText(res.stdout),
+    outputText(res.stderr),
+  );
+  return {
+    result: {
+      diagnostics: output.diagnostics,
+      status: res.status ?? 1,
+      stdout: "",
+      stderr: outputText(res.stderr),
+    },
+    typescript: output.typescript,
+  };
+}
+
+function runNativeChecks(
+  options: ITtscCompilerContext,
+  project: ITtscParsedProjectConfig,
+  nativePlugins: readonly ITtscLoadedNativePlugin[],
+  checks: readonly ITtscLoadedNativePlugin[],
+): TtscBuildResult {
+  let result: TtscBuildResult = {
+    diagnostics: [],
+    status: 0,
+    stdout: "",
+    stderr: "",
+  };
+  for (const plugin of checks) {
+    const res = spawnNative(
+      plugin.binary,
+      createNativeCheckArgs(project, nativePlugins),
+      {
+        cwd: project.root,
+        env: nativePluginEnv(options, project.root),
+      },
+    );
+    if (res.error) {
+      throw new Error(
+        `ttsc.transform.check: failed to spawn ${plugin.binary}: ${res.error.message}`,
+      );
+    }
+    result = appendBuildResult(result, {
+      diagnostics: [],
+      status: res.status ?? 1,
+      stdout: outputText(res.stdout),
+      stderr: outputText(res.stderr),
+    });
+    if (result.status !== 0) {
+      return result;
+    }
+  }
+  return result;
+}
+
+function createNativeTransformArgs(
+  project: ITtscParsedProjectConfig,
+  plugins: readonly ITtscLoadedNativePlugin[],
+): string[] {
+  return [
+    "transform",
+    "--tsconfig=" + project.path,
+    "--plugins-json=" + serializeNativePlugins(plugins),
+    "--cwd=" + project.root,
+  ];
+}
+
+function createNativeCheckArgs(
+  project: ITtscParsedProjectConfig,
+  plugins: readonly ITtscLoadedNativePlugin[],
+): string[] {
+  return [
+    "check",
+    "--tsconfig=" + project.path,
+    "--plugins-json=" + serializeNativePlugins(plugins),
+    "--cwd=" + project.root,
+  ];
+}
+
+function serializeNativePlugins(
+  plugins: readonly ITtscLoadedNativePlugin[],
+): string {
+  return JSON.stringify(
+    plugins.map((plugin) => ({
+      config: plugin.config,
+      name: plugin.name,
+      stage: plugin.stage,
+    })),
+  );
+}
+
+function assertSingleTransformHost(
+  plugins: readonly ITtscLoadedNativePlugin[],
+): void {
+  const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
+  if (binaries.length > 1) {
+    throw new Error(
+      "ttsc: multiple transform native backends cannot share one source-to-source pass",
+    );
+  }
+}
+
+function appendBuildResult(
+  left: TtscBuildResult,
+  right: TtscBuildResult,
+): TtscBuildResult {
+  return {
+    diagnostics: [...left.diagnostics, ...right.diagnostics],
+    status: right.status !== 0 ? right.status : left.status,
+    stdout: left.stdout + right.stdout,
+    stderr: left.stderr + right.stderr,
+  };
+}
+
+function nativePluginEnv(
+  options: ITtscCompilerContext,
+  projectRoot: string,
+): NodeJS.ProcessEnv {
+  const tsgo = resolveTsgo({ ...options, cwd: projectRoot });
+  return {
+    ...process.env,
+    TTSC_NODE_BINARY: process.env.TTSC_NODE_BINARY ?? process.execPath,
+    TTSC_TSGO_BINARY: process.env.TTSC_TSGO_BINARY ?? tsgo.binary,
+    TTSC_TTSX_BINARY:
+      process.env.TTSC_TTSX_BINARY ??
+      path.join(__dirname, "..", "..", "launcher", "ttsx.js"),
+    ...options.env,
+  };
+}
+
+function spawnNative(
+  binary: string,
+  args: readonly string[],
+  options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+  },
+) {
+  const viaNode = /\.(?:[cm]?js|ts)$/i.test(binary);
+  if (!viaNode) {
+    ensureExecutable(binary);
+  }
+  return spawnSync(
+    viaNode ? process.execPath : binary,
+    viaNode ? [binary, ...args] : [...args],
+    {
+      cwd: options.cwd,
+      encoding: "utf8",
+      env: options.env,
+      maxBuffer: 1024 * 1024 * 256,
+      windowsHide: true,
+    },
+  );
+}
+
+function ensureExecutable(binary: string): void {
+  if (process.platform === "win32") {
+    return;
+  }
+  try {
+    const mode = fs.statSync(binary).mode & 0o777;
+    if ((mode & 0o111) !== 0) {
+      return;
+    }
+    fs.chmodSync(binary, mode | 0o755);
+  } catch {
+    /* keep the original spawn error path */
+  }
+}
+
+function outputText(value: string | Buffer | null | undefined): string {
+  if (value == null) {
+    return "";
+  }
+  return typeof value === "string" ? value : value.toString("utf8");
+}
+
+function parseNativeTransformOutput(
+  stdout: string,
+  stderr: string,
+): {
+  diagnostics: ITtscCompilerDiagnostic[];
+  typescript: Record<string, string>;
+} {
+  try {
+    const parsed = JSON.parse(stdout) as {
+      diagnostics?: ITtscCompilerDiagnostic[];
+      typescript?: Record<string, string>;
+    };
+    if (!isTextRecord(parsed.typescript)) {
+      throw new Error(
+        "ttsc: native transform host did not return a TypeScript source map",
+      );
+    }
+    return {
+      diagnostics: Array.isArray(parsed.diagnostics) ? parsed.diagnostics : [],
+      typescript: parsed.typescript,
+    };
+  } catch (error) {
+    if (error instanceof Error && !(error instanceof SyntaxError)) {
+      throw error;
+    }
+    throw new Error(
+      (stderr || stdout).trim() ||
+        "ttsc: native transform host returned no output",
+    );
+  }
+}
+
+function isTextRecord(value: unknown): value is Record<string, string> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Object.values(value).every((entry) => typeof entry === "string")
+  );
+}
+
+function packageRootDir(): string {
+  let current = path.resolve(__dirname);
+  while (true) {
+    if (
+      fs.existsSync(path.join(current, "package.json")) &&
+      fs.existsSync(path.join(current, "go.mod"))
+    ) {
+      return fs.realpathSync.native?.(current) ?? fs.realpathSync(current);
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      throw new Error("ttsc: package root not found for native compiler build");
+    }
+    current = parent;
+  }
+}