ttsc 0.5.0 → 0.6.0-dev.20250430

package/src/source-build.ts

@@ -4,17 +4,13 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 
-import type { TtscNativeSource } from "./native";
+import type { ITtscBuildSourcePluginOptions } from "./structures/ITtscBuildSourcePluginOptions";
+import type { ITtscResolveGoBinaryOptions } from "./structures/ITtscResolveGoBinaryOptions";
 
-export interface BuildSourcePluginOptions {
-  source: TtscNativeSource;
-  pluginName: string;
-  baseDir: string;
-  ttscVersion: string;
-  tsgoVersion: string;
-}
+export type { ITtscBuildSourcePluginOptions } from "./structures/ITtscBuildSourcePluginOptions";
+export type { ITtscResolveGoBinaryOptions } from "./structures/ITtscResolveGoBinaryOptions";
 
-export function buildSourcePlugin(opts: BuildSourcePluginOptions): string {
+export function buildSourcePlugin(opts: ITtscBuildSourcePluginOptions): string {
   const dir = path.isAbsolute(opts.source.dir)
     ? opts.source.dir
     : path.resolve(opts.baseDir, opts.source.dir);
@@ -81,10 +77,42 @@ function writeGoWork(scratchDir: string, useDirs: readonly string[]): void {
   for (const dir of useDirs) {
     useLines.push(`\t${dir.replace(/\\/g, "/")}`);
   }
-  const goWork = `go 1.26\n\nuse (\n${useLines.join("\n")}\n)\n`;
+  const replaceLines = sourceBuildWorkspaceReplacements(useDirs);
+  const replaceBlock =
+    replaceLines.length === 0 ? "" : `\n\n${replaceLines.join("\n")}\n`;
+  const goWork = `go 1.26\n\nuse (\n${useLines.join("\n")}\n)${replaceBlock}`;
   fs.writeFileSync(path.join(scratchDir, "go.work"), goWork, "utf8");
 }
 
+export function sourceBuildWorkspaceReplacements(
+  useDirs: readonly string[],
+): string[] {
+  const ttscRoot = useDirs.find((dir) =>
+    hasModulePath(dir, "github.com/samchon/ttsc/packages/ttsc"),
+  );
+  if (!ttscRoot) {
+    return [];
+  }
+  return [
+    `replace github.com/samchon/ttsc/packages/ttsc v0.0.0 => ${ttscRoot.replace(/\\/g, "/")}`,
+  ];
+}
+
+function hasModulePath(dir: string, modulePath: string): boolean {
+  try {
+    const goMod = fs.readFileSync(path.join(dir, "go.mod"), "utf8");
+    return new RegExp(`^module\\s+${escapeRegExp(modulePath)}\\s*$`, "m").test(
+      goMod,
+    );
+  } catch {
+    return false;
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function runGoBuild(
   cwd: string,
   entry: string,
@@ -178,20 +206,12 @@ function walkToolFiles(dir: string): string[] {
   return out;
 }
 
-export interface ResolveGoBinaryOptions {
-  arch?: string;
-  env?: NodeJS.ProcessEnv;
-  localGoLookup?: () => string | null;
-  platform?: NodeJS.Platform;
-  resolver?: (request: string) => string;
-}
-
-export function goBinaryName(opts: ResolveGoBinaryOptions = {}): string {
+export function goBinaryName(opts: ITtscResolveGoBinaryOptions = {}): string {
   return (opts.platform ?? process.platform) === "win32" ? "go.exe" : "go";
 }
 
 export function bundledGoPackageRequest(
-  opts: ResolveGoBinaryOptions = {},
+  opts: ITtscResolveGoBinaryOptions = {},
 ): string {
   return `@ttsc/${goPlatformKey(opts)}/bin/go/bin/${goBinaryName(opts)}`;
 }
@@ -280,7 +300,7 @@ function resolveGoBinary(): string {
 }
 
 export function resolveGoCompiler(
-  opts: ResolveGoBinaryOptions = {},
+  opts: ITtscResolveGoBinaryOptions = {},
 ): string {
   const env = opts.env ?? process.env;
   const explicit = env.TTSC_GO_BINARY;
@@ -306,7 +326,7 @@ export function resolveGoCompiler(
   return "go";
 }
 
-function defaultLocalGoBinaryPath(opts: ResolveGoBinaryOptions): string | null {
+function defaultLocalGoBinaryPath(opts: ITtscResolveGoBinaryOptions): string | null {
   const candidate = path.resolve(
     __dirname,
     "..",
@@ -318,18 +338,18 @@ function defaultLocalGoBinaryPath(opts: ResolveGoBinaryOptions): string | null {
   return fs.existsSync(candidate) ? candidate : null;
 }
 
-function goPlatformKey(opts: ResolveGoBinaryOptions = {}): string {
+function goPlatformKey(opts: ITtscResolveGoBinaryOptions = {}): string {
   return `${opts.platform ?? process.platform}-${opts.arch ?? process.arch}`;
 }
 
-interface KeyInputs {
+interface ITtscSourceBuildCacheKeyInput {
   dir: string;
   entry: string;
   ttscVersion: string;
   tsgoVersion: string;
 }
 
-export function computeCacheKey(inputs: KeyInputs): string {
+export function computeCacheKey(inputs: ITtscSourceBuildCacheKeyInput): string {
   const hash = crypto.createHash("sha256");
   hash.update(`ttsc=${inputs.ttscVersion}\n`);
   hash.update(`tsgo=${inputs.tsgoVersion}\n`);

package/src/structures/ITtscBuildOptions.ts

@@ -0,0 +1,19 @@
+import type { ITtscCommonOptions } from "./ITtscCommonOptions";
+
+export interface ITtscBuildOptions extends ITtscCommonOptions {
+  /** Path to tsconfig.json. Default: `tsconfig.json`. */
+  tsconfig?: string;
+  /**
+   * Emit override. `true` forces emit, `false` forces noEmit, `undefined`
+   * follows tsconfig.
+   */
+  emit?: boolean;
+  /** Override compilerOptions.outDir for this invocation. */
+  outDir?: string;
+  /** Suppress the per-call summary banner. Default: `true`. */
+  quiet?: boolean;
+  /** @internal Caller already ran diagnostics and accepts responsibility. */
+  skipDiagnosticsCheck?: boolean;
+  /** @internal Force `tsgo --listEmittedFiles` for caller-side output discovery. */
+  forceListEmittedFiles?: boolean;
+}

package/src/structures/ITtscBuildResult.ts

@@ -0,0 +1,6 @@
+export interface ITtscBuildResult {
+  emittedFiles?: string[];
+  status: number;
+  stdout: string;
+  stderr: string;
+}

package/src/structures/ITtscBuildSourcePluginOptions.ts

@@ -0,0 +1,9 @@
+import type { ITtscNativeSource } from "./ITtscNativeSource";
+
+export interface ITtscBuildSourcePluginOptions {
+  source: ITtscNativeSource;
+  pluginName: string;
+  baseDir: string;
+  ttscVersion: string;
+  tsgoVersion: string;
+}

package/src/structures/ITtscCacheKeyInput.ts

@@ -0,0 +1,7 @@
+export interface ITtscCacheKeyInput {
+  file: string;
+  tsconfig: string;
+  version: string;
+  mode?: string;
+  extra?: readonly string[];
+}

package/src/structures/ITtscCheckOptions.ts

@@ -0,0 +1,3 @@
+import type { ITtscBuildOptions } from "./ITtscBuildOptions";
+
+export type ITtscCheckOptions = Omit<ITtscBuildOptions, "emit">;

package/src/structures/ITtscCommonOptions.ts

@@ -0,0 +1,23 @@
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+import type { ITtscResolveOptions } from "./ITtscResolveOptions";
+
+export interface ITtscCommonOptions extends ITtscResolveOptions {
+  /** Absolute path to an already-resolved tsgo binary. Skips package resolution. */
+  binary?: string;
+  /** Working directory passed to the child process. */
+  cwd?: string;
+  /** Extra environment variables; merged onto `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Override project plugin loading. `false` disables tsconfig plugins; an
+   * array replaces the tsconfig `compilerOptions.plugins` list.
+   */
+  plugins?: readonly ITtscProjectPluginConfig[] | false;
+  /**
+   * Override the native rewrite backend. Defaults to the loaded plugin mode.
+   *
+   * @deprecated Prefer plugin-declared `native.mode`; this override is for
+   *   low-level tests and migration probes.
+   */
+  rewriteMode?: string;
+}

package/src/structures/ITtscLoadPluginsOptions.ts

@@ -0,0 +1,9 @@
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+
+export interface ITtscLoadPluginsOptions {
+  binary: string;
+  cwd?: string;
+  entries?: readonly ITtscProjectPluginConfig[] | false;
+  file?: string;
+  tsconfig?: string;
+}

package/src/structures/ITtscLoadedNativePlugin.ts

@@ -0,0 +1,8 @@
+import type { ITtscNativeBackend } from "./ITtscNativeBackend";
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+
+export interface ITtscLoadedNativePlugin {
+  backend: ITtscNativeBackend;
+  config: ITtscProjectPluginConfig;
+  name: string;
+}

package/src/structures/ITtscLoadedPlugins.ts

@@ -0,0 +1,12 @@
+import type { ITtscLoadedNativePlugin } from "./ITtscLoadedNativePlugin";
+import type { ITtscParsedProjectConfig } from "./ITtscParsedProjectConfig";
+import type { ITtscPlugin } from "./ITtscPlugin";
+
+export interface ITtscLoadedPlugins {
+  compatibilityFallback: boolean;
+  nativeBinary: string | null;
+  nativeBinaries: string[];
+  nativePlugins: ITtscLoadedNativePlugin[];
+  plugins: ITtscPlugin[];
+  project: ITtscParsedProjectConfig;
+}

package/src/structures/ITtscNativeBackend.ts

@@ -0,0 +1,11 @@
+import type { ITtscNativePluginContractVersion } from "./ITtscNativePluginContractVersion";
+import type { ITtscNativeRewriteMode } from "./ITtscNativeRewriteMode";
+import type { ITtscNativeSource } from "./ITtscNativeSource";
+
+export interface ITtscNativeBackend {
+  mode: ITtscNativeRewriteMode;
+  binary?: string;
+  source?: ITtscNativeSource;
+  contractVersion?: ITtscNativePluginContractVersion;
+  capabilities?: readonly string[];
+}

package/src/structures/ITtscNativePluginContractVersion.ts

@@ -0,0 +1 @@
+export type ITtscNativePluginContractVersion = 1;

package/src/structures/ITtscNativePluginShape.ts

@@ -0,0 +1,9 @@
+import type { ITtscNativeBackend } from "./ITtscNativeBackend";
+import type { ITtscNativeRewriteMode } from "./ITtscNativeRewriteMode";
+
+export interface ITtscNativePluginShape {
+  name: string;
+  native?: ITtscNativeBackend;
+  nativeMode?: ITtscNativeRewriteMode;
+  nativeBinary?: string;
+}

package/src/structures/ITtscNativeRewriteMode.ts

@@ -0,0 +1 @@
+export type ITtscNativeRewriteMode = string;

package/src/structures/ITtscNativeSource.ts

@@ -0,0 +1,4 @@
+export interface ITtscNativeSource {
+  dir: string;
+  entry?: string;
+}

package/src/structures/ITtscParsedProjectConfig.ts

@@ -0,0 +1,10 @@
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+
+export interface ITtscParsedProjectConfig {
+  compilerOptions: {
+    outDir?: string;
+    plugins: ITtscProjectPluginConfig[];
+  } & Record<string, unknown>;
+  path: string;
+  root: string;
+}

package/src/structures/ITtscPlugin.ts

@@ -0,0 +1,11 @@
+import type { ITtscNativeBackend } from "./ITtscNativeBackend";
+import type { ITtscNativeRewriteMode } from "./ITtscNativeRewriteMode";
+
+export interface ITtscPlugin {
+  name: string;
+  native?: ITtscNativeBackend;
+  /** @deprecated Use `native.mode` instead. */
+  nativeMode?: ITtscNativeRewriteMode;
+  /** @deprecated Use `native.binary` instead. */
+  nativeBinary?: string;
+}

package/src/structures/ITtscPluginFactory.ts

@@ -0,0 +1,7 @@
+import type { ITtscPlugin } from "./ITtscPlugin";
+import type { ITtscPluginFactoryContext } from "./ITtscPluginFactoryContext";
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+
+export type ITtscPluginFactory<T = ITtscProjectPluginConfig> = (
+  context: ITtscPluginFactoryContext<T>,
+) => ITtscPlugin;

package/src/structures/ITtscPluginFactoryContext.ts

@@ -0,0 +1,9 @@
+import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
+
+export interface ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
+  binary: string;
+  cwd: string;
+  plugin: T;
+  projectRoot: string;
+  tsconfig: string;
+}

package/src/structures/ITtscPluginModule.ts

@@ -0,0 +1,4 @@
+import type { ITtscPlugin } from "./ITtscPlugin";
+import type { ITtscPluginFactory } from "./ITtscPluginFactory";
+
+export type ITtscPluginModule = ITtscPlugin | ITtscPluginFactory;

package/src/structures/ITtscPreparedExecution.ts

@@ -0,0 +1,5 @@
+export interface ITtscPreparedExecution {
+  emitDir: string;
+  entryFile: string;
+  moduleKind: "cjs" | "esm";
+}

package/src/structures/ITtscProjectLocatorOptions.ts

@@ -0,0 +1,5 @@
+export interface ITtscProjectLocatorOptions {
+  cwd?: string;
+  file?: string;
+  tsconfig?: string;
+}

package/src/structures/ITtscProjectPluginConfig.ts

@@ -0,0 +1,5 @@
+export interface ITtscProjectPluginConfig {
+  enabled?: boolean;
+  transform?: string;
+  [key: string]: unknown;
+}

package/src/structures/ITtscRegisterOptions.ts

@@ -0,0 +1,7 @@
+import type { ITtscCommonOptions } from "./ITtscCommonOptions";
+
+export interface ITtscRegisterOptions extends ITtscCommonOptions {
+  cacheDir?: string;
+  project?: string;
+  extensions?: readonly string[];
+}

package/src/structures/ITtscResolveGoBinaryOptions.ts

@@ -0,0 +1,7 @@
+export interface ITtscResolveGoBinaryOptions {
+  arch?: string;
+  env?: NodeJS.ProcessEnv;
+  localGoLookup?: () => string | null;
+  platform?: NodeJS.Platform;
+  resolver?: (request: string) => string;
+}

package/src/structures/ITtscResolveOptions.ts

@@ -0,0 +1,20 @@
+export interface ITtscResolveOptions {
+  /**
+   * Override `require.resolve` for testing. Takes a module request string and
+   * returns an absolute path (or throws).
+   */
+  resolver?: (request: string) => string;
+  /** Override `process.platform` for testing. */
+  platform?: NodeJS.Platform;
+  /** Override `process.arch` for testing. */
+  arch?: string;
+  /** Override `process.env` for testing. */
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Override the package-local scan used for the local `native/ttsc-native`
+   * fallback. Returns an absolute path if present, else null.
+   */
+  localBinaryLookup?: () => string | null;
+  /** Override the module directory used to resolve the package-local binary. */
+  moduleDir?: string;
+}

package/src/structures/ITtscResolvedTsgo.ts

@@ -0,0 +1,8 @@
+export interface ITtscResolvedTsgo {
+  binary: string;
+  gitHead?: string;
+  packageJson: string;
+  packageRoot: string;
+  platformPackageJson?: string;
+  version: string;
+}

package/src/structures/ITtscTransformOptions.ts

@@ -0,0 +1,13 @@
+import type { ITtscCommonOptions } from "./ITtscCommonOptions";
+
+export interface ITtscTransformOptions extends ITtscCommonOptions {
+  /** Path to the .ts file to transform. Absolute or `cwd`-relative. */
+  file: string;
+  /** Path to the tsconfig owning `file`. Default: `tsconfig.json`. */
+  tsconfig?: string;
+  /**
+   * When provided, the binary writes JS directly to this path instead of piping
+   * stdout. Useful when the emitted text is large.
+   */
+  out?: string;
+}

package/src/structures/ITtscTsgoResolveOptions.ts

@@ -0,0 +1,14 @@
+export interface ITtscTsgoResolveOptions {
+  /** Absolute path to an explicit tsgo-compatible binary. */
+  binary?: string;
+  /** Project directory used for node_modules resolution. */
+  cwd?: string;
+  /** Environment variables used for explicit binary overrides. */
+  env?: NodeJS.ProcessEnv;
+  /** Override process.platform for tests. */
+  platform?: NodeJS.Platform;
+  /** Override process.arch for tests. */
+  arch?: string;
+  /** Override package resolution for tests. */
+  resolver?: (request: string) => string;
+}

package/src/tsgo.ts

@@ -2,39 +2,21 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 
-export interface TsgoResolveOptions {
-  /** Absolute path to an explicit tsgo-compatible binary. */
-  binary?: string;
-  /** Project directory used for node_modules resolution. */
-  cwd?: string;
-  /** Environment variables used for explicit binary overrides. */
-  env?: NodeJS.ProcessEnv;
-  /** Override process.platform for tests. */
-  platform?: NodeJS.Platform;
-  /** Override process.arch for tests. */
-  arch?: string;
-  /** Override package resolution for tests. */
-  resolver?: (request: string) => string;
-}
+import type { ITtscResolvedTsgo } from "./structures/ITtscResolvedTsgo";
+import type { ITtscTsgoResolveOptions } from "./structures/ITtscTsgoResolveOptions";
 
-export interface ResolvedTsgo {
-  binary: string;
-  gitHead?: string;
-  packageJson: string;
-  packageRoot: string;
-  platformPackageJson?: string;
-  version: string;
-}
+export type { ITtscResolvedTsgo } from "./structures/ITtscResolvedTsgo";
+export type { ITtscTsgoResolveOptions } from "./structures/ITtscTsgoResolveOptions";
 
 export function nativePreviewPlatformPackage(
-  opts: TsgoResolveOptions = {},
+  opts: ITtscTsgoResolveOptions = {},
 ): string {
   return `@typescript/native-preview-${opts.platform ?? process.platform}-${
     opts.arch ?? process.arch
   }`;
 }
 
-export function resolveTsgo(opts: TsgoResolveOptions = {}): ResolvedTsgo {
+export function resolveTsgo(opts: ITtscTsgoResolveOptions = {}): ITtscResolvedTsgo {
   const env = opts.env ?? process.env;
   const explicit = opts.binary ?? env.TTSC_TSGO_BINARY;
   if (explicit) {

package/test/source-build.test.ts

@@ -12,6 +12,7 @@ const {
   resolveDefaultPluginCacheRoot,
   resolveGoCompiler,
   resolvePluginCacheRoot,
+  sourceBuildWorkspaceReplacements,
 } = require("../src/source-build.ts");
 
 function withTempSourceDir(files: Record<string, string>): string {
@@ -149,6 +150,18 @@ test("bundled Go package request follows platform package layout", () => {
   );
 });
 
+test("sourceBuildWorkspaceReplacements pins the ttsc module for source plugins", () => {
+  const ttscRoot = withTempSourceDir({
+    "go.mod": "module github.com/samchon/ttsc/packages/ttsc\n\ngo 1.26\n",
+  });
+  const otherRoot = withTempSourceDir({
+    "go.mod": "module example.com/other\n\ngo 1.26\n",
+  });
+  assert.deepEqual(sourceBuildWorkspaceReplacements([otherRoot, ttscRoot]), [
+    `replace github.com/samchon/ttsc/packages/ttsc v0.0.0 => ${ttscRoot.replace(/\\/g, "/")}`,
+  ]);
+});
+
 test("resolvePluginCacheRoot prefers project node_modules cache", () => {
   const root = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-local-cache-"));
   fs.mkdirSync(path.join(root, "node_modules"));