ttsc 0.6.0 → 0.7.0

package/lib/structures/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ITtscCompilerContext"), exports);
+__exportStar(require("./ITtscCompilerDiagnostic"), exports);
+__exportStar(require("./ITtscCompilerResult"), exports);
+__exportStar(require("./ITtscPlugin"), exports);
+__exportStar(require("./ITtscPluginFactoryContext"), exports);
+__exportStar(require("./ITtscProjectPluginConfig"), exports);
+__exportStar(require("./TtscPluginStage"), exports);
+//# sourceMappingURL=index.js.map

package/lib/structures/index.js.map

@@ -0,0 +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"}

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

@@ -0,0 +1,13 @@
+import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
+import type { TtscPluginStage } from "../TtscPluginStage";
+/** Native sidecar selected and built from one plugin descriptor. */
+export interface ITtscLoadedNativePlugin {
+    /** Executable produced by the lazy Go source build cache. */
+    binary: string;
+    /** Original tsconfig plugin entry passed unchanged to the sidecar. */
+    config: ITtscProjectPluginConfig;
+    /** Stable plugin name used in diagnostics and native manifests. */
+    name: string;
+    /** Pipeline stage where the sidecar participates. */
+    stage: TtscPluginStage;
+}

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

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

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

@@ -0,0 +1,15 @@
+import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
+/** Resolved project config subset used inside the ttsc host. */
+export interface ITtscParsedProjectConfig {
+    /** Compiler options after extends inheritance has been applied. */
+    compilerOptions: {
+        /** Absolute output directory when configured. */
+        outDir?: string;
+        /** Project plugin entries after inheritance resolution. */
+        plugins: ITtscProjectPluginConfig[];
+    } & Record<string, unknown>;
+    /** Absolute path to the resolved tsconfig/jsconfig. */
+    path: string;
+    /** Directory containing the resolved tsconfig/jsconfig. */
+    root: string;
+}

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

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

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

@@ -0,0 +1,9 @@
+/** Inputs for locating the tsconfig/jsconfig that owns an invocation. */
+export interface ITtscProjectLocatorOptions {
+    /** Working directory for relative paths and upward config discovery. */
+    cwd?: string;
+    /** Source file used as the starting point for nearest-config discovery. */
+    file?: string;
+    /** Explicit tsconfig/jsconfig path. */
+    tsconfig?: string;
+}

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

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

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

@@ -0,0 +1,18 @@
+import type { TtscCommonOptions } from "./TtscCommonOptions";
+/** Internal options for a TypeScript-Go project build. */
+export interface TtscBuildOptions extends TtscCommonOptions {
+    /** Project config file to compile. Relative paths are resolved from `cwd`. */
+    tsconfig?: string;
+    /**
+     * Emit override for the current call.
+     *
+     * - `true`: force file writes even when the project has `noEmit`.
+     * - `false`: force diagnostics/check-only behavior.
+     * - `undefined`: follow the resolved tsconfig exactly.
+     */
+    emit?: boolean;
+    /** Per-call TypeScript-Go `outDir` override. */
+    outDir?: string;
+    /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
+    quiet?: boolean;
+}

package/lib/structures/{ITtscBuildOptions.js → internal/TtscBuildOptions.js}

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

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

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

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

@@ -0,0 +1,14 @@
+import type { ITtscCompilerDiagnostic } from "../ITtscCompilerDiagnostic";
+/** Internal result captured from TypeScript-Go or native plugin sidecars. */
+export interface TtscBuildResult {
+    /** Structured diagnostics collected from compiler output. */
+    diagnostics: ITtscCompilerDiagnostic[];
+    /** Files written by the build when emitted-file listing was requested. */
+    emittedFiles?: string[];
+    /** Process-style exit status. `0` means success. */
+    status: number;
+    /** Captured stdout from TypeScript-Go or native plugin sidecars. */
+    stdout: string;
+    /** Captured stderr from TypeScript-Go or native plugin sidecars. */
+    stderr: string;
+}

package/lib/structures/{ITtscCheckOptions.js → internal/TtscBuildResult.js}

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

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

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

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

@@ -0,0 +1,27 @@
+import type { ITtscProjectPluginConfig } from "../ITtscProjectPluginConfig";
+/** Internal options shared by the CLI build, transform, and runtime paths. */
+export interface TtscCommonOptions {
+    /**
+     * Explicit TypeScript-Go executable.
+     *
+     * When supplied, ttsc skips package-based tsgo resolution and shells out to
+     * this binary directly.
+     */
+    binary?: string;
+    /** Working directory for config discovery and relative file paths. */
+    cwd?: string;
+    /** Environment variables merged over `process.env` for child processes. */
+    env?: NodeJS.ProcessEnv;
+    /** Explicit root directory for compiled source-plugin cache artifacts. */
+    cacheDir?: string;
+    /** Normalize compiler output so diagnostics can be parsed structurally. */
+    structuredDiagnostics?: boolean;
+    /**
+     * Override project plugin loading for this invocation.
+     *
+     * - `false`: ignore `compilerOptions.plugins` completely.
+     * - array: use these plugin entries instead of the project config entries.
+     * - `undefined`: use the project config entries as written.
+     */
+    plugins?: readonly ITtscProjectPluginConfig[] | false;
+}

package/lib/structures/{ITtscNativeSource.js → internal/TtscCommonOptions.js}

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

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

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

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

@@ -0,0 +1,14 @@
+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. */
+    file: string;
+    /** Project config owning `file`; discovered from `file` when omitted. */
+    tsconfig?: string;
+    /** Optional output file path. Omit to return emitted text from stdout. */
+    out?: string;
+    /** Suppress summary banners from ttsc/native sidecars. Defaults to `true`. */
+    quiet?: boolean;
+    /** Normalize compiler output so diagnostics can be parsed structurally. */
+    structuredDiagnostics?: boolean;
+}

package/lib/structures/internal/TtscTransformOptions.js

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ttsc",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "General-purpose TypeScript-Go compiler, plugin host, and runtime.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -27,17 +27,17 @@
   "homepage": "https://github.com/samchon/ttsc",
   "devDependencies": {
     "@types/node": "^25.3.0",
-    "@typescript/native-preview": "7.0.0-dev.20260429.1",
+    "@typescript/native-preview": "7.0.0-dev.20260430.1",
     "rimraf": "^6.1.2"
   },
   "optionalDependencies": {
-    "@ttsc/linux-x64": "0.6.0",
-    "@ttsc/darwin-x64": "0.6.0",
-    "@ttsc/darwin-arm64": "0.6.0",
-    "@ttsc/win32-x64": "0.6.0",
-    "@ttsc/linux-arm64": "0.6.0",
-    "@ttsc/win32-arm64": "0.6.0",
-    "@ttsc/linux-arm": "0.6.0"
+    "@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"
   },
   "sideEffects": false,
   "files": [

package/src/TtscCompiler.ts

@@ -0,0 +1,241 @@
+import * as fs from "node:fs";
+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 { 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 { TtscBuildResult } from "./structures/internal/TtscBuildResult";
+
+/**
+ * Programmatic compiler host for the `ttsc` TypeScript-Go pipeline.
+ *
+ * `TtscCompiler` is the root JavaScript API exported by the `ttsc` package.
+ * It represents one resolved project context: a working directory, an optional
+ * project config path, an optional native toolchain override, an environment,
+ * a cache root, and a plugin list. Those values are captured by the
+ * constructor and are intentionally not replaceable per method call.
+ *
+ * The class exposes only the operations that make sense for an embedded
+ * compiler host:
+ *
+ * - {@link TtscCompiler.prepare}: build configured Go source plugins into the
+ *   cache before a later compile.
+ * - {@link TtscCompiler.clean}: remove the cache owned by this compiler
+ *   context.
+ * - {@link TtscCompiler.compile}: compile the configured project and return a
+ *   structured result instead of terminal text.
+ */
+export class TtscCompiler {
+  private readonly context: ITtscCompilerContext;
+
+  public constructor(context: ITtscCompilerContext = {}) {
+    this.context = {
+      ...context,
+      env: context.env ? { ...context.env } : undefined,
+      plugins: Array.isArray(context.plugins)
+        ? [...context.plugins]
+        : context.plugins,
+    };
+  }
+
+  /**
+   * Build every configured source plugin into the instance cache.
+   *
+   * This method loads the project plugin descriptors, resolves their
+   * {@link ITtscPlugin.source} paths, and compiles those Go command packages
+   * into the ttsc cache. It is useful when a host application wants to pay the
+   * lazy build cost before the first compile call.
+   *
+   * `prepare()` is not a project check. It does not create a TypeScript-Go
+   * Program, does not run diagnostics, and does not emit output files.
+   *
+   * @returns Compiled native plugin binary paths.
+   */
+  public prepare(): string[] {
+    const execution = this.resolveProjectExecution();
+    const loaded = loadProjectPlugins({
+      binary: resolveBinary(this.compilerContext()) ?? "",
+      cacheDir: this.resolvePluginCacheDir(),
+      cwd: execution.cwd,
+      entries: this.context.plugins,
+      tsconfig: execution.tsconfig,
+    });
+    return loaded.nativePlugins.map((plugin) => plugin.binary);
+  }
+
+  /**
+   * Remove compiled cache artifacts for this compiler instance.
+   *
+   * When the constructor received `cacheDir`, this method removes exactly that
+   * directory. Otherwise it removes the default ttsc cache locations for the
+   * resolved project root, plus the `TTSC_CACHE_DIR/plugins` cache when that
+   * environment variable is active.
+   *
+   * The cache target comes from the constructor context. Create another
+   * `TtscCompiler` instance to clean another project or another cache root.
+   *
+   * @returns Cache directories that were removed.
+   */
+  public clean(): string[] {
+    const cacheDir = this.resolveCacheDir();
+    if (cacheDir !== undefined) {
+      return removeExistingDirectories([cacheDir]);
+    }
+
+    const envCacheDir =
+      this.context.env?.TTSC_CACHE_DIR ?? process.env.TTSC_CACHE_DIR;
+    const projectRoot = this.resolveCleanProjectRoot();
+    return removeExistingDirectories([
+      ...(envCacheDir ? [path.resolve(envCacheDir, "plugins")] : []),
+      path.join(projectRoot, "node_modules", ".ttsc"),
+      path.join(projectRoot, ".ttsc"),
+    ]);
+  }
+
+  /**
+   * Compile the configured project.
+   *
+   * The public API does not write emitted files into the caller's project tree.
+   * For projects without plugins, ttsc uses its native TypeScript-Go host's
+   * `WriteFile` callback to capture output in memory. For projects with
+   * native plugins, ttsc runs the plugin pipeline against a temporary output
+   * directory, reads the generated text artifacts, and removes the temporary
+   * directory before returning.
+   *
+   * The result uses an `embed-typescript`-style discriminated union:
+   * `success` for clean compiles, `failure` for normal compiler diagnostics,
+   * and `exception` for host setup or process failures.
+   *
+   * @returns Structured compilation result containing diagnostics or output.
+   */
+  public compile(): ITtscCompilerResult {
+    return runProject(() => compileProjectInMemory(this.compilerContext()));
+  }
+
+  private compilerContext(): ITtscCompilerContext {
+    return {
+      ...this.context,
+      cacheDir: this.resolveCacheDir(),
+    };
+  }
+
+  private resolveProjectExecution(): {
+    cwd: string;
+    projectRoot: string;
+    tsconfig: string;
+  } {
+    const cwd = this.resolveCwd();
+    const tsconfig = resolveProjectConfig({
+      cwd,
+      tsconfig: this.context.tsconfig,
+    });
+    return {
+      cwd,
+      projectRoot: path.dirname(tsconfig),
+      tsconfig,
+    };
+  }
+
+  private resolveCleanProjectRoot(): string {
+    try {
+      return this.resolveProjectExecution().projectRoot;
+    } catch (error) {
+      if (this.context.tsconfig) {
+        throw error;
+      }
+      return this.resolveCwd();
+    }
+  }
+
+  private resolveCwd(): string {
+    return path.resolve(this.context.cwd ?? process.cwd());
+  }
+
+  private resolveCacheDir(): string | undefined {
+    if (!this.context.cacheDir) {
+      return undefined;
+    }
+    return path.isAbsolute(this.context.cacheDir)
+      ? this.context.cacheDir
+      : path.resolve(this.resolveCwd(), this.context.cacheDir);
+  }
+
+  private resolvePluginCacheDir(): string | undefined {
+    return this.resolveCacheDir() ?? this.context.env?.TTSC_CACHE_DIR;
+  }
+}
+
+function removeExistingDirectories(directories: readonly string[]): string[] {
+  const removed: string[] = [];
+  for (const directory of [...new Set(directories)]) {
+    if (!fs.existsSync(directory)) {
+      continue;
+    }
+    fs.rmSync(directory, { recursive: true, force: true });
+    removed.push(directory);
+  }
+  return removed;
+}
+
+interface ProjectResult {
+  output: Record<string, string>;
+  result: TtscBuildResult;
+}
+
+function runProject(task: () => ProjectResult): ITtscCompilerResult {
+  try {
+    return toCompilerResult(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) {
+    return {
+      output,
+      type: "success",
+    };
+  }
+  return {
+    diagnostics:
+      result.diagnostics.length === 0
+        ? [createProcessDiagnostic(result)]
+        : result.diagnostics,
+    output,
+    type: "failure",
+  };
+}
+
+function createProcessDiagnostic(
+  result: TtscBuildResult,
+): ITtscCompilerDiagnostic {
+  const messageText =
+    (result.stderr || result.stdout).trim() ||
+    `ttsc exited with status ${result.status}`;
+  return {
+    category: "error",
+    code: "TTSC_PROCESS",
+    file: null,
+    messageText,
+  };
+}
+
+function normalizeError(error: unknown): unknown {
+  if (!(error instanceof Error)) {
+    return error;
+  }
+  return {
+    message: error.message,
+    name: error.name,
+    stack: error.stack,
+  };
+}

package/src/compiler/internal/buildNativeCompiler.ts

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { buildSourcePlugin } from "../../plugin/internal/buildSourcePlugin";
+
+/** Build the native ttsc compiler host used by in-memory API compilation. */
+export function buildNativeCompiler(options: {
+  cacheBaseDir: string;
+  cacheDir?: string;
+  packageRoot: string;
+}): string {
+  return buildSourcePlugin({
+    baseDir: options.cacheBaseDir,
+    cacheDir: options.cacheDir,
+    label: "compiler host",
+    overlayDirs: [],
+    pluginName: "ttsc",
+    quiet: true,
+    source: path.join(options.packageRoot, "cmd", "ttsc"),
+    ttscVersion: readOwnPackageVersion(options.packageRoot),
+    tsgoVersion: readGoModuleVersion(options.packageRoot),
+  });
+}
+
+function readOwnPackageVersion(packageRoot: string): string {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"),
+    ) as { version?: unknown };
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function readGoModuleVersion(packageRoot: string): string {
+  try {
+    const goMod = fs.readFileSync(path.join(packageRoot, "go.mod"), "utf8");
+    return goMod;
+  } catch {
+    return "unknown";
+  }
+}