ttsc 0.6.0 → 0.7.0

package/src/{source-build.ts → plugin/internal/buildSourcePlugin.ts}

@@ -4,29 +4,37 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 
-import type { ITtscBuildSourcePluginOptions } from "./structures/ITtscBuildSourcePluginOptions";
-import type { ITtscResolveGoBinaryOptions } from "./structures/ITtscResolveGoBinaryOptions";
+const GO_MOD_SEARCH_MAX_DEPTH = 3;
 
-export type { ITtscBuildSourcePluginOptions } from "./structures/ITtscBuildSourcePluginOptions";
-export type { ITtscResolveGoBinaryOptions } from "./structures/ITtscResolveGoBinaryOptions";
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "vendor",
+  "lib",
+]);
 
-export function buildSourcePlugin(opts: ITtscBuildSourcePluginOptions): string {
-  const dir = path.isAbsolute(opts.source.dir)
-    ? opts.source.dir
-    : path.resolve(opts.baseDir, opts.source.dir);
-  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
-    throw new Error(
-      `ttsc: plugin "${opts.pluginName}" native.source.dir does not exist: ${dir}`,
-    );
-  }
-  const entry = opts.source.entry ?? ".";
+/** Build one Go source plugin into a cached executable. */
+export function buildSourcePlugin(opts: {
+  source: string;
+  pluginName: string;
+  baseDir: string;
+  cacheDir?: string;
+  label?: string;
+  overlayDirs?: readonly string[];
+  quiet?: boolean;
+  ttscVersion: string;
+  tsgoVersion: string;
+}): string {
+  const { dir, entry, source } = resolveSourceBuildTarget(opts);
   const key = computeCacheKey({
     dir,
     entry,
     ttscVersion: opts.ttscVersion,
     tsgoVersion: opts.tsgoVersion,
   });
-  const root = resolvePluginCacheRoot(opts.baseDir);
+  const root = resolvePluginCacheRoot(opts.baseDir, opts.cacheDir);
   const cacheDir = path.join(root, key);
   const binaryName = process.platform === "win32" ? "plugin.exe" : "plugin";
   const binaryPath = path.join(cacheDir, binaryName);
@@ -34,9 +42,12 @@ export function buildSourcePlugin(opts: ITtscBuildSourcePluginOptions): string {
     return binaryPath;
   }
   fs.mkdirSync(cacheDir, { recursive: true });
-  process.stderr.write(
-    `ttsc: building source plugin "${opts.pluginName}" from ${dir} (this runs once per cache key)\n`,
-  );
+  const label = opts.label ?? "source plugin";
+  if (opts.quiet !== true) {
+    process.stderr.write(
+      `ttsc: building ${label} "${opts.pluginName}" from ${source} (this runs once per cache key)\n`,
+    );
+  }
 
   const scratchDir = path.join(
     root,
@@ -44,7 +55,7 @@ export function buildSourcePlugin(opts: ITtscBuildSourcePluginOptions): string {
   );
   try {
     materializeScratchDir(dir, scratchDir);
-    writeGoWork(scratchDir, findTtscOverlayDirs());
+    writeGoWork(scratchDir, opts.overlayDirs ?? findTtscOverlayDirs());
     const scratchBinaryName =
       process.platform === "win32" ? ".ttsc-plugin.exe" : ".ttsc-plugin";
     runGoBuild(scratchDir, entry, scratchBinaryName, opts.pluginName);
@@ -59,6 +70,66 @@ export function buildSourcePlugin(opts: ITtscBuildSourcePluginOptions): string {
   }
 }
 
+function resolveSourceBuildTarget(opts: {
+  source: string;
+  pluginName: string;
+  baseDir: string;
+}): {
+  dir: string;
+  entry: string;
+  source: string;
+} {
+  const source = path.isAbsolute(opts.source)
+    ? opts.source
+    : path.resolve(opts.baseDir, opts.source);
+  if (!fs.existsSync(source)) {
+    throw new Error(
+      `ttsc: plugin "${opts.pluginName}" source does not exist: ${source}`,
+    );
+  }
+
+  const stat = fs.statSync(source);
+  const packageDir =
+    stat.isFile() && path.basename(source) === "go.mod"
+      ? path.dirname(source)
+      : stat.isDirectory()
+        ? source
+        : null;
+  if (packageDir === null) {
+    throw new Error(
+      `ttsc: plugin "${opts.pluginName}" source must be a Go package directory or go.mod file: ${source}`,
+    );
+  }
+
+  const goMod = findNearestGoMod(packageDir, GO_MOD_SEARCH_MAX_DEPTH);
+  if (goMod === null) {
+    throw new Error(
+      `ttsc: plugin "${opts.pluginName}" source must be inside a Go module with go.mod within ${GO_MOD_SEARCH_MAX_DEPTH} parent directories: ${source}`,
+    );
+  }
+  const dir = path.dirname(goMod);
+  const rel = path.relative(dir, packageDir).replace(/\\/g, "/");
+  return {
+    dir,
+    entry: rel === "" ? "." : `./${rel}`,
+    source,
+  };
+}
+
+function findNearestGoMod(from: string, maxDepth: number): string | null {
+  let current = path.resolve(from);
+  let depth = 0;
+  while (true) {
+    const candidate = path.join(current, "go.mod");
+    if (fs.existsSync(candidate)) return candidate;
+    if (depth >= maxDepth) return null;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+    depth += 1;
+  }
+}
+
 function materializeScratchDir(source: string, scratch: string): void {
   fs.mkdirSync(scratch, { recursive: true });
   fs.cpSync(source, scratch, {
@@ -84,9 +155,7 @@ function writeGoWork(scratchDir: string, useDirs: readonly string[]): void {
   fs.writeFileSync(path.join(scratchDir, "go.work"), goWork, "utf8");
 }
 
-export function sourceBuildWorkspaceReplacements(
-  useDirs: readonly string[],
-): string[] {
+function sourceBuildWorkspaceReplacements(useDirs: readonly string[]): string[] {
   const ttscRoot = useDirs.find((dir) =>
     hasModulePath(dir, "github.com/samchon/ttsc/packages/ttsc"),
   );
@@ -119,19 +188,15 @@ function runGoBuild(
   binaryName: string,
   pluginName: string,
 ): void {
-  const goBinary = resolveGoBinary();
+  const goBinary = resolveGoCompiler();
   ensureExecutableGoToolchain(goBinary);
-  const result = spawnSync(
-    goBinary,
-    ["build", "-o", binaryName, entry],
-    {
-      cwd,
-      encoding: "utf8",
-      env: goBuildEnv(goBinary),
-      maxBuffer: 1024 * 1024 * 64,
-      windowsHide: true,
-    },
-  );
+  const result = spawnSync(goBinary, ["build", "-o", binaryName, entry], {
+    cwd,
+    encoding: "utf8",
+    env: goBuildEnv(goBinary),
+    maxBuffer: 1024 * 1024 * 64,
+    windowsHide: true,
+  });
   if (result.error) {
     if ((result.error as NodeJS.ErrnoException).code === "ENOENT") {
       throw new Error(
@@ -206,23 +271,8 @@ function walkToolFiles(dir: string): string[] {
   return out;
 }
 
-export function goBinaryName(opts: ITtscResolveGoBinaryOptions = {}): string {
-  return (opts.platform ?? process.platform) === "win32" ? "go.exe" : "go";
-}
-
-export function bundledGoPackageRequest(
-  opts: ITtscResolveGoBinaryOptions = {},
-): string {
-  return `@ttsc/${goPlatformKey(opts)}/bin/go/bin/${goBinaryName(opts)}`;
-}
-
-let cachedOverlayDirs: readonly string[] | null = null;
-
 function findTtscOverlayDirs(): readonly string[] {
-  if (cachedOverlayDirs !== null) {
-    return cachedOverlayDirs;
-  }
-  const ttscRoot = path.resolve(__dirname, "..");
+  const ttscRoot = path.resolve(__dirname, "..", "..", "..");
   const dirs: string[] = [];
   if (fs.existsSync(path.join(ttscRoot, "go.mod"))) {
     dirs.push(ttscRoot);
@@ -232,7 +282,6 @@ function findTtscOverlayDirs(): readonly string[] {
     walkForGoMod(shimRoot, dirs);
   }
   dirs.sort();
-  cachedOverlayDirs = dirs;
   return dirs;
 }
 
@@ -259,14 +308,13 @@ function walkForGoMod(dir: string, out: string[]): void {
   }
 }
 
-export function resolvePluginCacheRoot(projectRoot: string): string {
+function resolvePluginCacheRoot(projectRoot: string, cacheDir?: string): string {
+  if (cacheDir) {
+    return path.resolve(cacheDir, "plugins");
+  }
   if (process.env.TTSC_CACHE_DIR) {
     return path.resolve(process.env.TTSC_CACHE_DIR, "plugins");
   }
-  return resolveDefaultPluginCacheRoot(projectRoot);
-}
-
-export function resolveDefaultPluginCacheRoot(projectRoot: string): string {
   const root = path.resolve(projectRoot);
   const nodeModules = path.join(root, "node_modules");
   if (isDirectory(nodeModules)) {
@@ -275,18 +323,6 @@ export function resolveDefaultPluginCacheRoot(projectRoot: string): string {
   return path.join(root, ".ttsc", "plugins");
 }
 
-export function pluginCacheCleanupTargets(projectRoot: string): string[] {
-  const root = path.resolve(projectRoot);
-  const targets = [
-    path.join(root, "node_modules", ".ttsc"),
-    path.join(root, ".ttsc"),
-  ];
-  if (process.env.TTSC_CACHE_DIR) {
-    targets.push(path.resolve(process.env.TTSC_CACHE_DIR, "plugins"));
-  }
-  return [...new Set(targets)];
-}
-
 function isDirectory(candidate: string): boolean {
   try {
     return fs.statSync(candidate).isDirectory();
@@ -295,61 +331,40 @@ function isDirectory(candidate: string): boolean {
   }
 }
 
-function resolveGoBinary(): string {
-  return resolveGoCompiler();
-}
-
-export function resolveGoCompiler(
-  opts: ITtscResolveGoBinaryOptions = {},
-): string {
-  const env = opts.env ?? process.env;
-  const explicit = env.TTSC_GO_BINARY;
+function resolveGoCompiler(): string {
+  const explicit = process.env.TTSC_GO_BINARY;
   if (explicit && explicit.length > 0) return explicit;
 
-  const resolver =
-    opts.resolver ??
-    ((request: string) => createRequire(__filename).resolve(request));
   try {
-    return resolver(bundledGoPackageRequest(opts));
+    return createRequire(__filename).resolve(
+      `@ttsc/${process.platform}-${process.arch}/bin/go/bin/${process.platform === "win32" ? "go.exe" : "go"}`,
+    );
   } catch {
     /* fall through */
   }
 
-  if (opts.localGoLookup) {
-    const local = opts.localGoLookup();
-    if (local) return local;
-  } else {
-    const local = defaultLocalGoBinaryPath(opts);
-    if (local) return local;
-  }
-
-  return "go";
-}
-
-function defaultLocalGoBinaryPath(opts: ITtscResolveGoBinaryOptions): string | null {
-  const candidate = path.resolve(
+  const local = path.resolve(
     __dirname,
     "..",
+    "..",
+    "..",
+    "..",
     "native",
     "go",
     "bin",
-    goBinaryName(opts),
+    process.platform === "win32" ? "go.exe" : "go",
   );
-  return fs.existsSync(candidate) ? candidate : null;
-}
+  if (fs.existsSync(local)) return local;
 
-function goPlatformKey(opts: ITtscResolveGoBinaryOptions = {}): string {
-  return `${opts.platform ?? process.platform}-${opts.arch ?? process.arch}`;
+  return "go";
 }
 
-interface ITtscSourceBuildCacheKeyInput {
+function computeCacheKey(inputs: {
   dir: string;
   entry: string;
   ttscVersion: string;
   tsgoVersion: string;
-}
-
-export function computeCacheKey(inputs: ITtscSourceBuildCacheKeyInput): string {
+}): string {
   const hash = crypto.createHash("sha256");
   hash.update(`ttsc=${inputs.ttscVersion}\n`);
   hash.update(`tsgo=${inputs.tsgoVersion}\n`);
@@ -363,23 +378,14 @@ export function computeCacheKey(inputs: ITtscSourceBuildCacheKeyInput): string {
   return hash.digest("hex").slice(0, 32);
 }
 
-const SKIP_DIRS = new Set([
-  "node_modules",
-  ".git",
-  "dist",
-  "build",
-  "vendor",
-  "lib",
-]);
-
 function collectSourceFiles(root: string): string[] {
   const out: string[] = [];
-  walk(root, root, out);
+  walk(root, out);
   out.sort();
   return out;
 }
 
-function walk(root: string, dir: string, out: string[]): void {
+function walk(dir: string, out: string[]): void {
   let entries: fs.Dirent[];
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -390,7 +396,7 @@ function walk(root: string, dir: string, out: string[]): void {
     if (SKIP_DIRS.has(entry.name)) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      walk(root, full, out);
+      walk(full, out);
       continue;
     }
     if (!entry.isFile()) continue;

package/src/plugin/internal/loadProjectPlugins.ts

@@ -0,0 +1,214 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+
+import { readProjectConfig } from "../../compiler/internal/project/readProjectConfig";
+import type { ITtscPlugin } from "../../structures/ITtscPlugin";
+import type { ITtscPluginFactoryContext } from "../../structures/ITtscPluginFactoryContext";
+import type { ITtscProjectPluginConfig } from "../../structures/ITtscProjectPluginConfig";
+import type { TtscPluginStage } from "../../structures/TtscPluginStage";
+import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
+import type { ITtscParsedProjectConfig } from "../../structures/internal/ITtscParsedProjectConfig";
+import { buildSourcePlugin } from "./buildSourcePlugin";
+
+type TtscPluginFactory<T = ITtscProjectPluginConfig> = (
+  context: ITtscPluginFactoryContext<T>,
+) => ITtscPlugin;
+
+export function loadProjectPlugins(options: {
+  binary: string;
+  cacheDir?: string;
+  cwd?: string;
+  entries?: readonly ITtscProjectPluginConfig[] | false;
+  file?: string;
+  tsconfig?: string;
+}): {
+  nativePlugins: ITtscLoadedNativePlugin[];
+  project: ITtscParsedProjectConfig;
+} {
+  const project = readProjectConfig({
+    cwd: options.cwd,
+    file: options.file,
+    tsconfig: options.tsconfig,
+  });
+  const entries =
+    options.entries === false
+      ? []
+      : [...(options.entries ?? project.compilerOptions.plugins)].filter(
+          (entry) => entry.enabled !== false,
+        );
+  if (entries.length === 0) {
+    return {
+      nativePlugins: [],
+      project,
+    };
+  }
+
+  const context = {
+    binary: options.binary,
+    cwd: path.resolve(options.cwd ?? process.cwd()),
+    projectRoot: project.root,
+    tsconfig: project.path,
+  };
+  const plugins = entries.map((entry) =>
+    loadPluginEntry(entry, { ...context, plugin: entry }),
+  );
+
+  const nativePlugins: ITtscLoadedNativePlugin[] = [];
+  const ttscVersion = readTtscVersion();
+  const tsgoVersion = readTsgoVersion(context.projectRoot);
+  plugins.forEach((plugin, index) => {
+    validatePluginSource(plugin);
+    const binary = buildSourcePlugin({
+      baseDir: context.projectRoot,
+      cacheDir: options.cacheDir,
+      pluginName: plugin.name,
+      source: plugin.source,
+      ttscVersion,
+      tsgoVersion,
+    });
+    nativePlugins.push({
+      binary,
+      config: entries[index]!,
+      name: plugin.name,
+      stage: resolvePluginStage(plugin),
+    });
+  });
+  return {
+    nativePlugins,
+    project,
+  };
+}
+
+function loadPluginEntry(
+  entry: ITtscProjectPluginConfig,
+  context: ITtscPluginFactoryContext,
+): ITtscPlugin {
+  const specifier = entry.transform;
+  if (typeof specifier !== "string" || specifier.length === 0) {
+    throw new Error(`ttsc: plugin entry is missing a string "transform" field`);
+  }
+
+  const request = resolvePluginRequest(specifier, context.projectRoot);
+  const mod = require(request) as {
+    createTtscPlugin?: TtscPluginFactory;
+    default?: ITtscPlugin | TtscPluginFactory;
+  } & Partial<Record<"plugin", ITtscPlugin | TtscPluginFactory>>;
+  const candidate =
+    mod.createTtscPlugin ??
+    mod.default ??
+    mod.plugin ??
+    (mod as unknown as ITtscPlugin | TtscPluginFactory);
+  if (typeof candidate === "function") {
+    const plugin = candidate(context);
+    if (!isTtscPlugin(plugin)) {
+      throw new Error(
+        `ttsc: plugin "${specifier}" does not export a valid ttsc plugin`,
+      );
+    }
+    rejectJsTransformHooks(specifier, plugin);
+    return plugin;
+  }
+  if (isTtscPlugin(candidate)) {
+    rejectJsTransformHooks(specifier, candidate);
+    return candidate;
+  }
+  throw new Error(
+    `ttsc: plugin "${specifier}" does not export a valid ttsc plugin`,
+  );
+}
+
+function isTtscPlugin(value: unknown): value is ITtscPlugin {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { name?: unknown }).name === "string"
+  );
+}
+
+function rejectJsTransformHooks(specifier: string, candidate: object): void {
+  if ("transformSource" in candidate || "transformOutput" in candidate) {
+    throw new Error(
+      `ttsc: plugin "${specifier}" declares unsupported JS transform hooks; ` +
+        "declare a native backend instead",
+    );
+  }
+}
+
+function resolvePluginStage(plugin: ITtscPlugin): TtscPluginStage {
+  if (plugin.stage === undefined) {
+    return "transform";
+  }
+  if (!isPluginStage(plugin.stage)) {
+    throw new Error(
+      `ttsc: plugin "${plugin.name}" requested unsupported stage ${JSON.stringify(plugin.stage)}`,
+    );
+  }
+  return plugin.stage;
+}
+
+function validatePluginSource(plugin: ITtscPlugin): void {
+  if (typeof plugin.source !== "string" || plugin.source.length === 0) {
+    throw new Error(`ttsc: plugin "${plugin.name}" must declare source`);
+  }
+}
+
+function isPluginStage(value: string): value is TtscPluginStage {
+  return value === "transform" || value === "check" || value === "output";
+}
+
+function resolvePluginRequest(specifier: string, projectRoot: string): string {
+  if (path.isAbsolute(specifier)) {
+    return specifier;
+  }
+  if (isRelativePluginSpecifier(specifier)) {
+    return path.resolve(projectRoot, specifier);
+  }
+  return require.resolve(specifier, { paths: [projectRoot] });
+}
+
+function isRelativePluginSpecifier(specifier: string): boolean {
+  return (
+    specifier === "." ||
+    specifier === ".." ||
+    specifier.startsWith("./") ||
+    specifier.startsWith("../") ||
+    specifier.startsWith(".\\") ||
+    specifier.startsWith("..\\")
+  );
+}
+
+let cachedTtscVersion: string | null = null;
+
+function readTtscVersion(): string {
+  if (cachedTtscVersion !== null) {
+    return cachedTtscVersion;
+  }
+  try {
+    const file = path.resolve(__dirname, "..", "..", "..", "package.json");
+    const pkg = JSON.parse(fs.readFileSync(file, "utf8")) as {
+      version?: string;
+    };
+    cachedTtscVersion = pkg.version ?? "0.0.0";
+  } catch {
+    cachedTtscVersion = "0.0.0";
+  }
+  return cachedTtscVersion;
+}
+
+function readTsgoVersion(projectRoot: string): string {
+  try {
+    const projectRequire = createRequire(
+      path.join(projectRoot, "package.json"),
+    );
+    const pkgPath = projectRequire.resolve(
+      "@typescript/native-preview/package.json",
+    );
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
+      version?: string;
+    };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}

package/src/structures/ITtscCompilerContext.ts

@@ -0,0 +1,84 @@
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+
+/**
+ * Constructor context for {@link TtscCompiler}.
+ *
+ * Represents the project environment owned by a programmatic ttsc compiler
+ * instance. The context is fixed when the class is constructed: compile,
+ * prepare, and clean operations all use the same working directory, project
+ * config, native toolchain, environment, cache root, and plugin list.
+ *
+ * Keeping this context immutable prevents one `TtscCompiler` object from
+ * silently compiling different projects across calls. Create another compiler
+ * instance when any of these fields must change.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ITtscCompilerContext {
+  /**
+   * The working directory for this compiler instance.
+   *
+   * Used to discover `tsconfig.json`, resolve relative `tsconfig` paths,
+   * resolve project source files, resolve plugin packages, and resolve relative
+   * cache paths.
+   *
+   * @default process.cwd()
+   */
+  cwd?: string;
+
+  /**
+   * The project configuration file for this compiler instance.
+   *
+   * Relative paths are resolved from {@link ITtscCompilerContext.cwd}. When this
+   * field is omitted, ttsc discovers the nearest owning `tsconfig.json` or
+   * `jsconfig.json` from the working directory.
+   */
+  tsconfig?: string;
+
+  /**
+   * Explicit TypeScript-Go executable for controlled embedding.
+   *
+   * Normal consumers should leave this unset. ttsc resolves the installed or
+   * bundled toolchain needed for each compile path. This field is intended for
+   * tests, pinned toolchains, and embedding environments that need plugin or
+   * CLI-compatible paths to use a specific TypeScript-Go binary.
+   *
+   * The no-plugin in-memory API path is hosted by ttsc's native compiler host
+   * so it can return structured diagnostics and output. Plugin-backed paths
+   * pass this binary through to the TypeScript-Go execution layer.
+   */
+  binary?: string;
+
+  /**
+   * Additional environment variables for child compiler processes.
+   *
+   * Values are merged over `process.env` before ttsc starts TypeScript-Go,
+   * native plugin binaries, or the native compiler host used by
+   * {@link TtscCompiler.compile}.
+   */
+  env?: NodeJS.ProcessEnv;
+
+  /**
+   * Root directory for compiled ttsc artifacts.
+   *
+   * Relative paths are resolved from {@link ITtscCompilerContext.cwd}. When
+   * omitted, ttsc uses its normal cache location: `TTSC_CACHE_DIR` when
+   * present, otherwise `node_modules/.ttsc` or `.ttsc` under the project root.
+   *
+   * The same cache stores source-plugin binaries and the lazily built native
+   * compiler host used for in-memory API compilation.
+   */
+  cacheDir?: string;
+
+  /**
+   * Plugin entries for this compiler instance.
+   *
+   * - `undefined`: read `compilerOptions.plugins` from the project config.
+   * - `false`: ignore project plugins for this compiler instance.
+   * - array: use these plugin entries instead of the project config entries.
+   *
+   * Plugin entries are resolved once per operation from this instance context.
+   * Per-call plugin overrides are intentionally not part of the public API.
+   */
+  plugins?: readonly ITtscProjectPluginConfig[] | false;
+}