ttsc 0.5.0 → 0.6.0-dev.20250430

package/src/platform.ts

@@ -27,36 +27,19 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-export interface ResolveOptions {
-  /**
-   * 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;
-}
+import type { ITtscResolveOptions } from "./structures/ITtscResolveOptions";
+
+export type { ITtscResolveOptions } from "./structures/ITtscResolveOptions";
 
 /** Canonical key `{platform}-{arch}` used in the binary package name. */
-export function platformKey(opts: ResolveOptions = {}): string {
+export function platformKey(opts: ITtscResolveOptions = {}): string {
   const platform = opts.platform ?? process.platform;
   const arch = opts.arch ?? process.arch;
   return `${platform}-${arch}`;
 }
 
 /** Helper binary filename for the current platform (`.exe` on Windows, else none). */
-export function binaryName(opts: ResolveOptions = {}): string {
+export function binaryName(opts: ITtscResolveOptions = {}): string {
   const platform = opts.platform ?? process.platform;
   return platform === "win32" ? "ttsc.exe" : "ttsc";
 }
@@ -66,7 +49,7 @@ export function binaryName(opts: ResolveOptions = {}): string {
  * platform. Separated from actual resolution so we can log the request when
  * the dependency is missing.
  */
-export function platformPackageRequest(opts: ResolveOptions = {}): string {
+export function platformPackageRequest(opts: ITtscResolveOptions = {}): string {
   const key = platformKey(opts);
   const bin = binaryName(opts);
   return `@ttsc/${key}/bin/${bin}`;
@@ -93,7 +76,7 @@ export function isSupported(key: string): boolean {
  * order. Returns `null` when every strategy fails — the launcher then prints
  * the install hint and exits non-zero.
  */
-export function resolveBinary(opts: ResolveOptions = {}): string | null {
+export function resolveBinary(opts: ITtscResolveOptions = {}): string | null {
   const env = opts.env ?? process.env;
 
   // 1. Env override. Absolute path is required; a relative value is ignored so
@@ -126,7 +109,7 @@ export function resolveBinary(opts: ResolveOptions = {}): string | null {
  * Human-readable message shown when no binary can be located. Pure string —
  * the launcher writes it to stderr.
  */
-export function installHint(opts: ResolveOptions = {}): string {
+export function installHint(opts: ITtscResolveOptions = {}): string {
   const key = platformKey(opts);
   const pkg = `@ttsc/${key}`;
   const supported = SUPPORTED_PLATFORMS.join(", ");
@@ -149,7 +132,7 @@ export function installHint(opts: ResolveOptions = {}): string {
   ].join("\n");
 }
 
-function defaultLocalBinaryPath(opts: ResolveOptions): string | null {
+function defaultLocalBinaryPath(opts: ITtscResolveOptions): string | null {
   const root = packageRootDir(opts);
   const candidate = path.resolve(
     root,
@@ -160,7 +143,7 @@ function defaultLocalBinaryPath(opts: ResolveOptions): string | null {
   return fs.existsSync(candidate) ? candidate : null;
 }
 
-function packageRootDir(opts: ResolveOptions = {}): string {
+function packageRootDir(opts: ITtscResolveOptions = {}): string {
   if (opts.moduleDir) {
     return fs.realpathSync.native?.(opts.moduleDir) ?? fs.realpathSync(opts.moduleDir);
   }

package/src/plugin.ts

@@ -2,76 +2,37 @@ import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
 
-import {
-  type NativeRewriteMode,
-  type TtscNativeBackend,
-  resolveNativeBackend,
-} from "./native";
-import {
-  type ParsedProjectConfig,
-  type ProjectPluginConfig,
-  readProjectConfig,
-} from "./project";
+import type { ITtscLoadPluginsOptions } from "./structures/ITtscLoadPluginsOptions";
+import type { ITtscLoadedNativePlugin } from "./structures/ITtscLoadedNativePlugin";
+import type { ITtscLoadedPlugins } from "./structures/ITtscLoadedPlugins";
+import type { ITtscPlugin } from "./structures/ITtscPlugin";
+import type { ITtscPluginFactory } from "./structures/ITtscPluginFactory";
+import type { ITtscPluginFactoryContext } from "./structures/ITtscPluginFactoryContext";
+import type { ITtscPluginModule } from "./structures/ITtscPluginModule";
+import type { ITtscProjectPluginConfig } from "./structures/ITtscProjectPluginConfig";
+import { resolveNativeBackend } from "./native";
+import { readProjectConfig } from "./project";
 import { buildSourcePlugin } from "./source-build";
 
+export type { ITtscLoadPluginsOptions } from "./structures/ITtscLoadPluginsOptions";
+export type { ITtscLoadedNativePlugin } from "./structures/ITtscLoadedNativePlugin";
+export type { ITtscLoadedPlugins } from "./structures/ITtscLoadedPlugins";
 export type {
-  NativePluginContractVersion,
-  NativeRewriteMode,
-  TtscNativeBackend,
-  TtscNativeSource,
+  ITtscNativePluginContractVersion,
+  ITtscNativeRewriteMode,
+  ITtscNativeBackend,
+  ITtscNativeSource,
 } from "./native";
+export type { ITtscPlugin } from "./structures/ITtscPlugin";
+export type { ITtscPluginFactory } from "./structures/ITtscPluginFactory";
+export type { ITtscPluginFactoryContext } from "./structures/ITtscPluginFactoryContext";
+export type { ITtscPluginModule } from "./structures/ITtscPluginModule";
 
-export interface TtscPluginFactoryContext {
-  binary: string;
-  cwd: string;
-  projectRoot: string;
-  tsconfig: string;
-}
-
-export interface TtscPlugin {
-  name: string;
-  native?: TtscNativeBackend;
-  /** @deprecated Use `native.mode` instead. */
-  nativeMode?: NativeRewriteMode;
-  /** @deprecated Use `native.binary` instead. */
-  nativeBinary?: string;
-}
-
-export type TtscPluginFactory = (
-  config: ProjectPluginConfig,
-  context: TtscPluginFactoryContext,
-) => TtscPlugin;
-
-export type TtscPluginModule = TtscPlugin | TtscPluginFactory;
-
-export interface LoadedNativePlugin {
-  backend: TtscNativeBackend;
-  config: ProjectPluginConfig;
-  name: string;
-}
-
-export interface LoadedPlugins {
-  compatibilityFallback: boolean;
-  nativeBinary: string | null;
-  nativeBinaries: string[];
-  nativePlugins: LoadedNativePlugin[];
-  plugins: TtscPlugin[];
-  project: ParsedProjectConfig;
-}
-
-export interface LoadPluginsOptions {
-  binary: string;
-  cwd?: string;
-  entries?: readonly ProjectPluginConfig[] | false;
-  file?: string;
-  tsconfig?: string;
-}
-
-export function definePlugin<T extends TtscPluginModule>(plugin: T): T {
+export function definePlugin<T extends ITtscPluginModule>(plugin: T): T {
   return plugin;
 }
 
-export function loadProjectPlugins(options: LoadPluginsOptions): LoadedPlugins {
+export function loadProjectPlugins(options: ITtscLoadPluginsOptions): ITtscLoadedPlugins {
   const project = readProjectConfig({
     cwd: options.cwd,
     file: options.file,
@@ -94,15 +55,17 @@ export function loadProjectPlugins(options: LoadPluginsOptions): LoadedPlugins {
     };
   }
 
-  const context: TtscPluginFactoryContext = {
+  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));
+  const plugins = entries.map((entry) =>
+    loadPluginEntry(entry, { ...context, plugin: entry }),
+  );
 
-  const nativePlugins: LoadedNativePlugin[] = [];
+  const nativePlugins: ITtscLoadedNativePlugin[] = [];
   const ttscVersion = readTtscVersion();
   const tsgoVersion = readTsgoVersion(context.projectRoot);
   plugins.forEach((plugin, index) => {
@@ -148,9 +111,9 @@ export function loadProjectPlugins(options: LoadPluginsOptions): LoadedPlugins {
 }
 
 function loadPluginEntry(
-  entry: ProjectPluginConfig,
-  context: TtscPluginFactoryContext,
-): TtscPlugin {
+  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`);
@@ -158,16 +121,16 @@ function loadPluginEntry(
 
   const request = resolvePluginRequest(specifier, context.projectRoot);
   const mod = require(request) as {
-    createTtscPlugin?: TtscPluginFactory;
-    default?: TtscPluginModule;
-  } & Partial<Record<"plugin", TtscPluginModule>>;
+    createTtscPlugin?: ITtscPluginFactory;
+    default?: ITtscPluginModule;
+  } & Partial<Record<"plugin", ITtscPluginModule>>;
   const candidate =
     mod.createTtscPlugin ??
     mod.default ??
     mod.plugin ??
-    (mod as unknown as TtscPluginModule);
+    (mod as unknown as ITtscPluginModule);
   if (typeof candidate === "function") {
-    const plugin = candidate(entry, context);
+    const plugin = candidate(context);
     if (!isTtscPlugin(plugin)) {
       throw new Error(
         `ttsc: plugin "${specifier}" does not export a valid ttsc plugin`,
@@ -185,7 +148,7 @@ function loadPluginEntry(
   );
 }
 
-function isTtscPlugin(value: unknown): value is TtscPlugin {
+function isTtscPlugin(value: unknown): value is ITtscPlugin {
   return (
     typeof value === "object" &&
     value !== null &&

package/src/project.ts

@@ -3,26 +3,15 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 
-export interface ProjectLocatorOptions {
-  cwd?: string;
-  file?: string;
-  tsconfig?: string;
-}
-
-export interface ProjectPluginConfig {
-  enabled?: boolean;
-  transform?: string;
-  [key: string]: unknown;
-}
+import type { ITtscCacheKeyInput } from "./structures/ITtscCacheKeyInput";
+import type { ITtscParsedProjectConfig } from "./structures/ITtscParsedProjectConfig";
+import type { ITtscProjectLocatorOptions } from "./structures/ITtscProjectLocatorOptions";
+import type { ITtscProjectPluginConfig } from "./structures/ITtscProjectPluginConfig";
 
-export interface ParsedProjectConfig {
-  compilerOptions: {
-    outDir?: string;
-    plugins: ProjectPluginConfig[];
-  } & Record<string, unknown>;
-  path: string;
-  root: string;
-}
+export type { ITtscCacheKeyInput } from "./structures/ITtscCacheKeyInput";
+export type { ITtscParsedProjectConfig } from "./structures/ITtscParsedProjectConfig";
+export type { ITtscProjectLocatorOptions } from "./structures/ITtscProjectLocatorOptions";
+export type { ITtscProjectPluginConfig } from "./structures/ITtscProjectPluginConfig";
 
 export function resolveWorkingDirectory(cwd?: string): string {
   return path.resolve(cwd ?? process.cwd());
@@ -32,7 +21,7 @@ export function resolveAbsolutePath(cwd: string, target: string): string {
   return path.isAbsolute(target) ? target : path.resolve(cwd, target);
 }
 
-export function resolveProjectConfig(opts: ProjectLocatorOptions = {}): string {
+export function resolveProjectConfig(opts: ITtscProjectLocatorOptions = {}): string {
   const cwd = resolveWorkingDirectory(opts.cwd);
   if (opts.tsconfig) {
     const resolved = resolveAbsolutePath(cwd, opts.tsconfig);
@@ -55,7 +44,7 @@ export function resolveProjectConfig(opts: ProjectLocatorOptions = {}): string {
   return resolveRealPath(found);
 }
 
-export function resolveProjectRoot(opts: ProjectLocatorOptions = {}): string {
+export function resolveProjectRoot(opts: ITtscProjectLocatorOptions = {}): string {
   return path.dirname(resolveProjectConfig(opts));
 }
 
@@ -63,7 +52,7 @@ export function defaultCacheDirectory(projectRoot: string, tool: string): string
   return path.join(projectRoot, "node_modules", ".cache", "ttsc", tool);
 }
 
-export function readProjectConfig(opts: ProjectLocatorOptions = {}): ParsedProjectConfig {
+export function readProjectConfig(opts: ITtscProjectLocatorOptions = {}): ITtscParsedProjectConfig {
   const tsconfig = resolveProjectConfig(opts);
   const root = path.dirname(tsconfig);
   const compilerOptions = readResolvedCompilerOptions(tsconfig);
@@ -78,15 +67,7 @@ export function readProjectConfig(opts: ProjectLocatorOptions = {}): ParsedProje
   };
 }
 
-export interface CacheKeyInput {
-  file: string;
-  tsconfig: string;
-  version: string;
-  mode?: string;
-  extra?: readonly string[];
-}
-
-export function createTransformCacheKey(input: CacheKeyInput): string {
+export function createTransformCacheKey(input: ITtscCacheKeyInput): string {
   const hash = crypto.createHash("sha256");
   hash.update("file\0");
   hash.update(fs.readFileSync(input.file));
@@ -125,11 +106,11 @@ function isDirectory(location: string): boolean {
   }
 }
 
-function isProjectPluginConfig(value: unknown): value is ProjectPluginConfig {
+function isProjectPluginConfig(value: unknown): value is ITtscProjectPluginConfig {
   return typeof value === "object" && value !== null;
 }
 
-interface RawTsconfig {
+interface ITtscRawTsconfig {
   extends?: unknown;
   compilerOptions?: Record<string, unknown> & {
     outDir?: unknown;
@@ -137,10 +118,10 @@ interface RawTsconfig {
   };
 }
 
-interface ResolvedCompilerOptions {
+interface ITtscResolvedCompilerOptions {
   options: Record<string, unknown>;
   outDir?: string;
-  plugins: ProjectPluginConfig[];
+  plugins: ITtscProjectPluginConfig[];
 }
 
 function resolveRealPath(location: string): string {
@@ -154,14 +135,14 @@ function resolveRealPath(location: string): string {
 function readResolvedCompilerOptions(
   tsconfig: string,
   seen: Set<string> = new Set(),
-): ResolvedCompilerOptions {
+): ITtscResolvedCompilerOptions {
   const canonical = resolveRealPath(tsconfig);
   if (seen.has(canonical)) {
     throw new Error(`ttsc: circular tsconfig extends detected: ${canonical}`);
   }
   seen.add(canonical);
 
-  const parsed = parseJsonc(fs.readFileSync(canonical, "utf8")) as RawTsconfig;
+  const parsed = parseJsonc(fs.readFileSync(canonical, "utf8")) as ITtscRawTsconfig;
   const own = parsed.compilerOptions;
   const base =
     typeof parsed.extends === "string"

package/src/runner/cli.ts

@@ -7,11 +7,11 @@ import { version } from "../api";
 import {
   prepareExecution,
   register,
-  type PreparedExecution,
-  type RegisterOptions,
+  type ITtscPreparedExecution,
+  type ITtscRegisterOptions,
 } from "./register";
 
-interface ParsedCLI extends RegisterOptions {
+interface ITtscParsedCLI extends ITtscRegisterOptions {
   entry: string;
   passthrough: string[];
   preload: string[];
@@ -80,7 +80,7 @@ function formatError(error: unknown): string {
   return String(error);
 }
 
-function parseCLI(argv: readonly string[]): ParsedCLI | "help" | "version" {
+function parseCLI(argv: readonly string[]): ITtscParsedCLI | "help" | "version" {
   const preload: string[] = [];
   const passthroughIndex = argv.indexOf("--");
   const head = passthroughIndex === -1 ? [...argv] : [...argv.slice(0, passthroughIndex)];
@@ -199,7 +199,7 @@ function takeValue(flag: string, rest: string[]): string {
   return value;
 }
 
-function runEsmEntry(parsed: ParsedCLI, execution: PreparedExecution, cwd: string): number {
+function runEsmEntry(parsed: ITtscParsedCLI, execution: ITtscPreparedExecution, cwd: string): number {
   fs.mkdirSync(execution.emitDir, { recursive: true });
   rewriteEsmSpecifiers(execution.emitDir);
   fs.writeFileSync(

package/src/runner/register.ts

@@ -1,35 +1,24 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
-import {
-  build,
-  check,
-  type CommonOptions,
-} from "../api";
+import type { ITtscPreparedExecution } from "../structures/ITtscPreparedExecution";
+import type { ITtscRegisterOptions } from "../structures/ITtscRegisterOptions";
+import { build, check } from "../api";
 import {
   defaultCacheDirectory,
   resolveProjectConfig,
   resolveProjectRoot,
 } from "../project";
 
-export interface RegisterOptions extends CommonOptions {
-  cacheDir?: string;
-  project?: string;
-  extensions?: readonly string[];
-}
-
-export interface PreparedExecution {
-  emitDir: string;
-  entryFile: string;
-  moduleKind: "cjs" | "esm";
-}
+export type { ITtscPreparedExecution } from "../structures/ITtscPreparedExecution";
+export type { ITtscRegisterOptions } from "../structures/ITtscRegisterOptions";
 
-type RequireExtension = (module: NodeJS.Module, filename: string) => void;
-type CompilableModule = NodeJS.Module & {
+type ITtscRequireExtension = (module: NodeJS.Module, filename: string) => void;
+type ITtscCompilableModule = NodeJS.Module & {
   _compile(code: string, filename: string): void;
 };
 
-interface ProjectContext {
+interface ITtscRunnerProjectContext {
   cacheDir: string;
   emitDir: string;
   emittedFiles: string[] | null;
@@ -47,15 +36,15 @@ const DEFAULT_EXTENSIONS: readonly string[] = Object.freeze([
 ]);
 
 const PROCESS_CACHE_KEY = String(process.pid);
-const preparedContexts = new Map<string, ProjectContext>();
+const preparedContexts = new Map<string, ITtscRunnerProjectContext>();
 
-export function register(options: RegisterOptions = {}): () => void {
+export function register(options: ITtscRegisterOptions = {}): () => void {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const extensions = [...(options.extensions ?? DEFAULT_EXTENSIONS)];
-  const contextCache = new Map<string, ProjectContext>();
-  const previous = new Map<string, RequireExtension | undefined>();
+  const contextCache = new Map<string, ITtscRunnerProjectContext>();
+  const previous = new Map<string, ITtscRequireExtension | undefined>();
 
-  const getContext = (filename: string): ProjectContext => {
+  const getContext = (filename: string): ITtscRunnerProjectContext => {
     if (options.project) {
       const key = path.resolve(cwd, options.project);
       const cached = contextCache.get(key);
@@ -120,7 +109,7 @@ export function register(options: RegisterOptions = {}): () => void {
     previous.set(extension, require.extensions[extension]);
     require.extensions[extension] = (module: NodeJS.Module, filename: string) => {
       const compiled = compile(filename);
-      (module as CompilableModule)._compile(compiled, filename);
+      (module as ITtscCompilableModule)._compile(compiled, filename);
     };
   }
 
@@ -138,8 +127,8 @@ export function register(options: RegisterOptions = {}): () => void {
 
 export function prepareExecution(
   entryFile: string,
-  options: RegisterOptions = {},
-): PreparedExecution {
+  options: ITtscRegisterOptions = {},
+): ITtscPreparedExecution {
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const context = resolveProjectContext(cwd, entryFile, options);
   ensureProjectDiagnostics(context, options);
@@ -166,8 +155,8 @@ export function prepareExecution(
 }
 
 function storePreparedContext(
-  context: ProjectContext,
-  options: RegisterOptions,
+  context: ITtscRunnerProjectContext,
+  options: ITtscRegisterOptions,
 ): void {
   preparedContexts.set(preparedContextKey(context.tsconfig, context.cacheDir, options), context);
 }
@@ -175,8 +164,8 @@ function storePreparedContext(
 function takePreparedContext(
   tsconfig: string,
   cacheDir: string,
-  options: RegisterOptions,
-): ProjectContext | null {
+  options: ITtscRegisterOptions,
+): ITtscRunnerProjectContext | null {
   const key = preparedContextKey(tsconfig, cacheDir, options);
   const context = preparedContexts.get(key);
   if (!context) {
@@ -189,7 +178,7 @@ function takePreparedContext(
 function preparedContextKey(
   tsconfig: string,
   cacheDir: string,
-  options: RegisterOptions,
+  options: ITtscRegisterOptions,
 ): string {
   return JSON.stringify([
     PROCESS_CACHE_KEY,
@@ -203,7 +192,7 @@ function preparedContextKey(
   ]);
 }
 
-function ensureProjectBuild(context: ProjectContext, options: RegisterOptions): void {
+function ensureProjectBuild(context: ITtscRunnerProjectContext, options: ITtscRegisterOptions): void {
   if (context.emittedFiles !== null) return;
 
   fs.mkdirSync(context.cacheDir, { recursive: true });
@@ -236,9 +225,9 @@ function ensureProjectBuild(context: ProjectContext, options: RegisterOptions):
 }
 
 function readCompiledOutput(
-  context: ProjectContext,
+  context: ITtscRunnerProjectContext,
   filename: string,
-  options: RegisterOptions,
+  options: ITtscRegisterOptions,
 ): string {
   ensureProjectBuild(context, options);
   const emitted = resolveEmittedFile(context, filename);
@@ -251,8 +240,8 @@ function readCompiledOutput(
 function resolveProjectContext(
   cwd: string,
   filename: string,
-  options: RegisterOptions,
-): ProjectContext {
+  options: ITtscRegisterOptions,
+): ITtscRunnerProjectContext {
   if (options.project) {
     const tsconfig = resolveProjectConfig({
       cwd,
@@ -267,8 +256,8 @@ function resolveProjectContext(
 function createProjectContext(
   cwd: string,
   tsconfig: string,
-  options: RegisterOptions,
-): ProjectContext {
+  options: ITtscRegisterOptions,
+): ITtscRunnerProjectContext {
   const root = resolveProjectRoot({ cwd, tsconfig });
   const cacheDir = options.cacheDir ?? defaultCacheDirectory(root, "ttsx");
   return {
@@ -283,8 +272,8 @@ function createProjectContext(
 }
 
 function ensureProjectDiagnostics(
-  context: ProjectContext,
-  options: RegisterOptions,
+  context: ITtscRunnerProjectContext,
+  options: ITtscRegisterOptions,
 ): void {
   if (context.diagnosticsChecked) {
     return;
@@ -310,7 +299,7 @@ function ensureProjectDiagnostics(
   context.diagnosticsChecked = true;
 }
 
-function resolveEmittedFile(context: ProjectContext, filename: string): string | null {
+function resolveEmittedFile(context: ITtscRunnerProjectContext, filename: string): string | null {
   const normalized = path.resolve(filename);
   const cached = context.entryMap.get(normalized);
   if (cached && fs.existsSync(cached)) return cached;
@@ -339,7 +328,7 @@ function resolveEmittedFile(context: ProjectContext, filename: string): string |
 }
 
 function resolveExactEmittedFile(
-  context: ProjectContext,
+  context: ITtscRunnerProjectContext,
   filename: string,
 ): string | null {
   const relative = path.relative(context.root, filename);