ttsc 0.7.0 → 0.7.1

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;
+  }
+}

package/src/launcher/internal/runTtsc.ts

@@ -4,13 +4,14 @@ import * as path from "node:path";
 
 import { resolveBinary } from "../../compiler/internal/resolveBinary";
 import { runBuild } from "../../compiler/internal/runBuild";
-import { runTransform } from "../../compiler/internal/runTransform";
+import { runSingleFileEmit } from "../../compiler/internal/runSingleFileEmit";
 import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
 import type { TtscBuildOptions } from "../../structures/internal/TtscBuildOptions";
-import type { TtscTransformOptions } from "../../structures/internal/TtscTransformOptions";
 import { getCompilerVersionText } from "./getCompilerVersionText";
 
-export function runTtsc(argv: readonly string[] = process.argv.slice(2)): number {
+export function runTtsc(
+  argv: readonly string[] = process.argv.slice(2),
+): number {
   try {
     if (argv.length === 0) {
       return runCompatibleBuild([], false);
@@ -34,8 +35,6 @@ export function runTtsc(argv: readonly string[] = process.argv.slice(2)): number
         return runCompatibleBuild(rest, true);
       case "clean":
         return runClean(rest);
-      case "transform":
-        return runTransformCommand(rest);
       case "demo":
         return delegateToNative(argv);
       case "-p":
@@ -83,15 +82,6 @@ function runCompatibleBuild(
   return result.status;
 }
 
-function runTransformCommand(argv: readonly string[]): number {
-  const options = parseTransformArgs(argv);
-  const text = runTransform(options);
-  if (!options.out) {
-    process.stdout.write(text);
-  }
-  return 0;
-}
-
 function runClean(argv: readonly string[]): number {
   const options = parseCleanArgs(argv);
   const cwd = path.resolve(options.cwd ?? process.cwd());
@@ -216,10 +206,7 @@ function parseCleanArgs(argv: readonly string[]) {
   return { cwd, tsconfig };
 }
 
-function parseBuildArgs(
-  argv: readonly string[],
-  checkOnly: boolean,
-) {
+function parseBuildArgs(argv: readonly string[], checkOnly: boolean) {
   let binary: string | undefined;
   let cwd: string | undefined;
   let emit: boolean | undefined = checkOnly ? false : undefined;
@@ -306,64 +293,6 @@ function parseBuildArgs(
   };
 }
 
-function parseTransformArgs(argv: readonly string[]): TtscTransformOptions {
-  let binary: string | undefined;
-  let cwd: string | undefined;
-  let file: string | undefined;
-  let out: string | undefined;
-  let tsconfig: string | undefined;
-
-  const rest = [...argv];
-  while (rest.length !== 0) {
-    const current = rest.shift()!;
-    switch (current) {
-      case "--binary":
-        binary = takeValue(current, rest);
-        break;
-      case "--cwd":
-        cwd = takeValue(current, rest);
-        break;
-      case "--file":
-        file = takeValue(current, rest);
-        break;
-      case "--out":
-        out = takeValue(current, rest);
-        break;
-      case "--tsconfig":
-      case "--project":
-        tsconfig = takeValue(current, rest);
-        break;
-      default:
-        if (current.startsWith("--binary=")) {
-          binary = current.slice("--binary=".length);
-        } else if (current.startsWith("--cwd=")) {
-          cwd = current.slice("--cwd=".length);
-        } else if (current.startsWith("--file=")) {
-          file = current.slice("--file=".length);
-        } else if (current.startsWith("--out=")) {
-          out = current.slice("--out=".length);
-        } else if (current.startsWith("--tsconfig=")) {
-          tsconfig = current.slice("--tsconfig=".length);
-        } else if (current.startsWith("--project=")) {
-          tsconfig = current.slice("--project=".length);
-        } else {
-          throw new Error(`ttsc: unknown option ${current}`);
-        }
-        break;
-    }
-  }
-  if (!file) {
-    throw new Error("ttsc: transform requires --file");
-  }
-  return {
-    binary,
-    cwd,
-    file,
-    out,
-    tsconfig,
-  };
-}
-
 function printHelp(): void {
   process.stdout.write(
     [
@@ -375,7 +304,6 @@ function printHelp(): void {
       "  ttsc --watch",
       "  ttsc --noEmit",
       "  ttsc clean [options]",
-      "  ttsc transform --file <path> [options]",
       "  ttsc version",
       "  ttsc --help",
       "",
@@ -390,7 +318,6 @@ function printHelp(): void {
       "  --outDir <dir>         Override compilerOptions.outDir for this invocation",
       "  --quiet                Keep build output quiet (default)",
       "  --verbose              Print the build summary and emitted files",
-      "  --out <path>           Write transform output to a file instead of stdout",
       "  --binary <path>        Use an explicit tsgo binary",
       "",
       "Plugin contract:",
@@ -416,7 +343,7 @@ function runSingleFile(options: ReturnType<typeof parseBuildArgs>): number {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const file = path.resolve(cwd, options.files[0]!);
   const out = resolveSingleFileOut(file, cwd, options.outDir);
-  const text = runTransform({
+  const text = runSingleFileEmit({
     binary: options.binary,
     cwd,
     file,

package/src/structures/ITtscCompilerTransformation.ts

@@ -0,0 +1,46 @@
+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 namespace ITtscCompilerTransformation {
+  /** Successful source-to-source transformation result. */
+  export 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. */
+  export 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. */
+  export interface IException {
+    /** Indicates that transformation could not complete normally. */
+    type: "exception";
+
+    /** Raw error thrown by the ttsc host. */
+    error: unknown;
+  }
+}

package/src/structures/TtscPluginStage.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/src/structures/index.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/src/structures/internal/TtscCommonOptions.ts

@@ -1,6 +1,6 @@
 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/src/structures/internal/{TtscTransformOptions.ts → TtscSingleFileEmitOptions.ts}

@@ -1,12 +1,12 @@
 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;