ttsc 0.7.0 → 0.7.2

package/src/launcher/internal/prepareExecution.ts

@@ -1,12 +1,14 @@
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 
 import { resolveEmittedJavaScript } from "../../compiler/internal/resolveEmittedJavaScript";
 import { runBuild } from "../../compiler/internal/runBuild";
-import { resolveProjectConfig } from "../../compiler/internal/project/resolveProjectConfig";
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
 import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOptions";
 
 const PROCESS_CACHE_KEY = String(process.pid);
+const MAX_VIRTUAL_PARENT_DEPTH = 3;
 
 /** Build the owning project and locate the emitted JavaScript entry for `ttsx`. */
 export function prepareExecution(
@@ -48,22 +50,42 @@ function createProjectContext(
   filename: string,
   options: NonNullable<Parameters<typeof prepareExecution>[1]>,
 ) {
-  const tsconfig = options.project
-    ? resolveProjectConfig({ cwd, tsconfig: path.resolve(cwd, options.project) })
-    : resolveProjectConfig({ cwd, file: filename });
-  const root = path.dirname(tsconfig);
+  const project = readProjectConfig(
+    options.project
+      ? { cwd, tsconfig: path.resolve(cwd, options.project) }
+      : { cwd, file: filename },
+  );
+  const tsconfig = project.path;
+  const root = project.root;
   const cacheDir =
     options.cacheDir ?? path.join(root, "node_modules", ".cache", "ttsc", "ttsx");
+  const processDir = path.join(cacheDir, "project", PROCESS_CACHE_KEY);
+  const virtualRoot = path.join(processDir, "fs");
   return {
     tsconfig,
     root,
     cacheDir,
-    emitDir: path.join(cacheDir, "project", PROCESS_CACHE_KEY),
+    processDir,
+    virtualRoot,
+    emitDir: project.compilerOptions.outDir
+      ? virtualPath(virtualRoot, project.compilerOptions.outDir)
+      : virtualPath(virtualRoot, resolveRuntimeSourceRoot(project, filename)),
     built: false,
     emittedFiles: undefined as string[] | undefined,
   };
 }
 
+function resolveRuntimeSourceRoot(
+  project: ReturnType<typeof readProjectConfig>,
+  filename: string,
+): string {
+  const rootDir = project.compilerOptions.rootDir;
+  if (typeof rootDir === "string") {
+    return path.isAbsolute(rootDir) ? rootDir : path.resolve(project.root, rootDir);
+  }
+  return path.dirname(filename);
+}
+
 function buildProject(
   context: ReturnType<typeof createProjectContext>,
   options: NonNullable<Parameters<typeof prepareExecution>[1]>,
@@ -71,7 +93,8 @@ function buildProject(
   if (context.built) return;
 
   fs.mkdirSync(context.cacheDir, { recursive: true });
-  fs.rmSync(context.emitDir, { recursive: true, force: true });
+  fs.rmSync(context.processDir, { recursive: true, force: true });
+  fs.mkdirSync(path.dirname(context.emitDir), { recursive: true });
   const result = runBuild({
     binary: options.binary,
     cwd: context.root,
@@ -84,6 +107,7 @@ function buildProject(
     tsconfig: context.tsconfig,
   });
   if (result.status === 0) {
+    linkVirtualProjectLayout(context);
     context.built = true;
     context.emittedFiles =
       result.emittedFiles && result.emittedFiles.length !== 0
@@ -92,7 +116,7 @@ function buildProject(
     return;
   }
 
-  fs.rmSync(context.emitDir, { recursive: true, force: true });
+  fs.rmSync(context.processDir, { recursive: true, force: true });
   const detail = [
     `ttsx: project check failed for ${context.tsconfig}`,
     result.stderr || result.stdout,
@@ -102,6 +126,88 @@ function buildProject(
   throw new Error(detail);
 }
 
+function linkVirtualProjectLayout(
+  context: ReturnType<typeof createProjectContext>,
+): void {
+  for (const directory of collectLinkDirectories(context.root)) {
+    const virtualDirectory = virtualPath(context.virtualRoot, directory);
+    fs.mkdirSync(virtualDirectory, { recursive: true });
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const realEntry = path.join(directory, entry.name);
+      const virtualEntry = path.join(virtualDirectory, entry.name);
+      if (fs.existsSync(virtualEntry)) {
+        continue;
+      }
+      linkVirtualEntry(realEntry, virtualEntry, entry);
+    }
+  }
+}
+
+function linkVirtualEntry(
+  realEntry: string,
+  virtualEntry: string,
+  entry: fs.Dirent,
+): void {
+  if (entry.isDirectory()) {
+    fs.symlinkSync(
+      realEntry,
+      virtualEntry,
+      process.platform === "win32" ? "junction" : undefined,
+    );
+    return;
+  }
+  if (entry.isFile()) {
+    try {
+      fs.linkSync(realEntry, virtualEntry);
+    } catch {
+      fs.copyFileSync(realEntry, virtualEntry);
+    }
+    return;
+  }
+  fs.symlinkSync(realEntry, virtualEntry);
+}
+
+function collectLinkDirectories(projectRoot: string): string[] {
+  const out: string[] = [];
+  let current = projectRoot;
+  for (let depth = 0; depth <= MAX_VIRTUAL_PARENT_DEPTH; depth += 1) {
+    out.push(current);
+    if (
+      depth > 0 &&
+      (fs.existsSync(path.join(current, "pnpm-workspace.yaml")) ||
+        fs.existsSync(path.join(current, ".git")))
+    ) {
+      break;
+    }
+    const parent = path.dirname(current);
+    if (parent === current || isUnsafeVirtualParent(parent)) {
+      break;
+    }
+    current = parent;
+  }
+  return out.reverse();
+}
+
+function isUnsafeVirtualParent(directory: string): boolean {
+  const resolved = path.resolve(directory);
+  const root = path.parse(resolved).root;
+  return (
+    resolved === root ||
+    resolved === path.resolve(os.tmpdir())
+  );
+}
+
+function virtualPath(root: string, absolute: string): string {
+  const parsed = path.parse(path.resolve(absolute));
+  const label =
+    parsed.root === path.sep
+      ? "posix"
+      : parsed.root.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") ||
+        "root";
+  const relative = path.relative(parsed.root, path.resolve(absolute));
+  return path.join(root, label, relative);
+}
+
 function looksLikeESM(output: string): boolean {
   if (
     /\bObject\.defineProperty\(exports\b/.test(output) ||

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;