ttsc 0.3.1 → 0.4.0-dev.20260424

package/shim/tspath/shim.go

@@ -0,0 +1,165 @@
+
+// Code generated by packages/ttsc/tools/gen_shims. DO NOT EDIT.
+
+package tspath
+
+import "github.com/microsoft/typescript-go/internal/tspath"
+import _ "unsafe"
+
+var AllSupportedExtensions = tspath.AllSupportedExtensions
+var AllSupportedExtensionsWithJson = tspath.AllSupportedExtensionsWithJson
+//go:linkname ChangeAnyExtension github.com/microsoft/typescript-go/internal/tspath.ChangeAnyExtension
+func ChangeAnyExtension(path string, ext string, extensions []string, ignoreCase bool) string
+//go:linkname ChangeExtension github.com/microsoft/typescript-go/internal/tspath.ChangeExtension
+func ChangeExtension(path string, newExtension string) string
+//go:linkname ChangeFullExtension github.com/microsoft/typescript-go/internal/tspath.ChangeFullExtension
+func ChangeFullExtension(path string, newExtension string) string
+//go:linkname CombinePaths github.com/microsoft/typescript-go/internal/tspath.CombinePaths
+func CombinePaths(firstPath string, paths ...string) string
+//go:linkname CompareNumberOfDirectorySeparators github.com/microsoft/typescript-go/internal/tspath.CompareNumberOfDirectorySeparators
+func CompareNumberOfDirectorySeparators(path1 string, path2 string) int
+//go:linkname ComparePaths github.com/microsoft/typescript-go/internal/tspath.ComparePaths
+func ComparePaths(a string, b string, options tspath.ComparePathsOptions) int
+//go:linkname ComparePathsCaseInsensitive github.com/microsoft/typescript-go/internal/tspath.ComparePathsCaseInsensitive
+func ComparePathsCaseInsensitive(a string, b string, currentDirectory string) int
+//go:linkname ComparePathsCaseSensitive github.com/microsoft/typescript-go/internal/tspath.ComparePathsCaseSensitive
+func ComparePathsCaseSensitive(a string, b string, currentDirectory string) int
+type ComparePathsOptions = tspath.ComparePathsOptions
+//go:linkname ContainsIgnoredPath github.com/microsoft/typescript-go/internal/tspath.ContainsIgnoredPath
+func ContainsIgnoredPath(path string) bool
+//go:linkname ContainsPath github.com/microsoft/typescript-go/internal/tspath.ContainsPath
+func ContainsPath(parent string, child string, options tspath.ComparePathsOptions) bool
+//go:linkname ConvertToRelativePath github.com/microsoft/typescript-go/internal/tspath.ConvertToRelativePath
+func ConvertToRelativePath(absoluteOrRelativePath string, options tspath.ComparePathsOptions) string
+const DirectorySeparator = tspath.DirectorySeparator
+//go:linkname EnsurePathIsNonModuleName github.com/microsoft/typescript-go/internal/tspath.EnsurePathIsNonModuleName
+func EnsurePathIsNonModuleName(path string) string
+//go:linkname EnsureTrailingDirectorySeparator github.com/microsoft/typescript-go/internal/tspath.EnsureTrailingDirectorySeparator
+func EnsureTrailingDirectorySeparator(path string) string
+const ExtensionCjs = tspath.ExtensionCjs
+const ExtensionCts = tspath.ExtensionCts
+const ExtensionDcts = tspath.ExtensionDcts
+const ExtensionDmts = tspath.ExtensionDmts
+const ExtensionDts = tspath.ExtensionDts
+//go:linkname ExtensionIsOneOf github.com/microsoft/typescript-go/internal/tspath.ExtensionIsOneOf
+func ExtensionIsOneOf(ext string, extensions []string) bool
+//go:linkname ExtensionIsTs github.com/microsoft/typescript-go/internal/tspath.ExtensionIsTs
+func ExtensionIsTs(ext string) bool
+const ExtensionJs = tspath.ExtensionJs
+const ExtensionJson = tspath.ExtensionJson
+const ExtensionJsx = tspath.ExtensionJsx
+const ExtensionMjs = tspath.ExtensionMjs
+const ExtensionMts = tspath.ExtensionMts
+const ExtensionTs = tspath.ExtensionTs
+const ExtensionTsBuildInfo = tspath.ExtensionTsBuildInfo
+const ExtensionTsx = tspath.ExtensionTsx
+var ExtensionsNotSupportingExtensionlessResolution = tspath.ExtensionsNotSupportingExtensionlessResolution
+//go:linkname FileExtensionIs github.com/microsoft/typescript-go/internal/tspath.FileExtensionIs
+func FileExtensionIs(path string, extension string) bool
+//go:linkname FileExtensionIsOneOf github.com/microsoft/typescript-go/internal/tspath.FileExtensionIsOneOf
+func FileExtensionIsOneOf(path string, extensions []string) bool
+//go:linkname GetAnyExtensionFromPath github.com/microsoft/typescript-go/internal/tspath.GetAnyExtensionFromPath
+func GetAnyExtensionFromPath(path string, extensions []string, ignoreCase bool) string
+//go:linkname GetBaseFileName github.com/microsoft/typescript-go/internal/tspath.GetBaseFileName
+func GetBaseFileName(path string) string
+//go:linkname GetCanonicalFileName github.com/microsoft/typescript-go/internal/tspath.GetCanonicalFileName
+func GetCanonicalFileName(fileName string, useCaseSensitiveFileNames bool) string
+//go:linkname GetCommonParents github.com/microsoft/typescript-go/internal/tspath.GetCommonParents
+func GetCommonParents(paths []string, minComponents int, getPathComponents func(path string, currentDirectory string) []string, options tspath.ComparePathsOptions) (parents []string, ignored map[string]struct{})
+//go:linkname GetDeclarationEmitExtensionForPath github.com/microsoft/typescript-go/internal/tspath.GetDeclarationEmitExtensionForPath
+func GetDeclarationEmitExtensionForPath(path string) string
+//go:linkname GetDeclarationFileExtension github.com/microsoft/typescript-go/internal/tspath.GetDeclarationFileExtension
+func GetDeclarationFileExtension(fileName string) string
+//go:linkname GetDirectoryPath github.com/microsoft/typescript-go/internal/tspath.GetDirectoryPath
+func GetDirectoryPath(path string) string
+//go:linkname GetEncodedRootLength github.com/microsoft/typescript-go/internal/tspath.GetEncodedRootLength
+func GetEncodedRootLength(path string) int
+//go:linkname GetNormalizedAbsolutePath github.com/microsoft/typescript-go/internal/tspath.GetNormalizedAbsolutePath
+func GetNormalizedAbsolutePath(fileName string, currentDirectory string) string
+//go:linkname GetNormalizedAbsolutePathWithoutRoot github.com/microsoft/typescript-go/internal/tspath.GetNormalizedAbsolutePathWithoutRoot
+func GetNormalizedAbsolutePathWithoutRoot(fileName string, currentDirectory string) string
+//go:linkname GetNormalizedPathComponents github.com/microsoft/typescript-go/internal/tspath.GetNormalizedPathComponents
+func GetNormalizedPathComponents(path string, currentDirectory string) []string
+//go:linkname GetPathComponents github.com/microsoft/typescript-go/internal/tspath.GetPathComponents
+func GetPathComponents(path string, currentDirectory string) []string
+//go:linkname GetPathComponentsRelativeTo github.com/microsoft/typescript-go/internal/tspath.GetPathComponentsRelativeTo
+func GetPathComponentsRelativeTo(from string, to string, options tspath.ComparePathsOptions) []string
+//go:linkname GetPathFromPathComponents github.com/microsoft/typescript-go/internal/tspath.GetPathFromPathComponents
+func GetPathFromPathComponents(pathComponents []string) string
+//go:linkname GetPossibleOriginalInputExtensionForExtension github.com/microsoft/typescript-go/internal/tspath.GetPossibleOriginalInputExtensionForExtension
+func GetPossibleOriginalInputExtensionForExtension(path string) []string
+//go:linkname GetRelativePathFromDirectory github.com/microsoft/typescript-go/internal/tspath.GetRelativePathFromDirectory
+func GetRelativePathFromDirectory(fromDirectory string, to string, options tspath.ComparePathsOptions) string
+//go:linkname GetRelativePathFromFile github.com/microsoft/typescript-go/internal/tspath.GetRelativePathFromFile
+func GetRelativePathFromFile(from string, to string, options tspath.ComparePathsOptions) string
+//go:linkname GetRelativePathToDirectoryOrUrl github.com/microsoft/typescript-go/internal/tspath.GetRelativePathToDirectoryOrUrl
+func GetRelativePathToDirectoryOrUrl(directoryPathOrUrl string, relativeOrAbsolutePath string, isAbsolutePathAnUrl bool, options tspath.ComparePathsOptions) string
+//go:linkname GetRootLength github.com/microsoft/typescript-go/internal/tspath.GetRootLength
+func GetRootLength(path string) int
+//go:linkname HasExtension github.com/microsoft/typescript-go/internal/tspath.HasExtension
+func HasExtension(fileName string) bool
+//go:linkname HasImplementationTSFileExtension github.com/microsoft/typescript-go/internal/tspath.HasImplementationTSFileExtension
+func HasImplementationTSFileExtension(path string) bool
+//go:linkname HasJSFileExtension github.com/microsoft/typescript-go/internal/tspath.HasJSFileExtension
+func HasJSFileExtension(path string) bool
+//go:linkname HasJSONFileExtension github.com/microsoft/typescript-go/internal/tspath.HasJSONFileExtension
+func HasJSONFileExtension(path string) bool
+//go:linkname HasTSFileExtension github.com/microsoft/typescript-go/internal/tspath.HasTSFileExtension
+func HasTSFileExtension(path string) bool
+//go:linkname HasTrailingDirectorySeparator github.com/microsoft/typescript-go/internal/tspath.HasTrailingDirectorySeparator
+func HasTrailingDirectorySeparator(path string) bool
+//go:linkname IsDeclarationFileName github.com/microsoft/typescript-go/internal/tspath.IsDeclarationFileName
+func IsDeclarationFileName(fileName string) bool
+//go:linkname IsDiskPathRoot github.com/microsoft/typescript-go/internal/tspath.IsDiskPathRoot
+func IsDiskPathRoot(path string) bool
+//go:linkname IsDynamicFileName github.com/microsoft/typescript-go/internal/tspath.IsDynamicFileName
+func IsDynamicFileName(fileName string) bool
+//go:linkname IsExternalModuleNameRelative github.com/microsoft/typescript-go/internal/tspath.IsExternalModuleNameRelative
+func IsExternalModuleNameRelative(moduleName string) bool
+//go:linkname IsRootedDiskPath github.com/microsoft/typescript-go/internal/tspath.IsRootedDiskPath
+func IsRootedDiskPath(path string) bool
+//go:linkname IsUrl github.com/microsoft/typescript-go/internal/tspath.IsUrl
+func IsUrl(path string) bool
+//go:linkname IsVolumeCharacter github.com/microsoft/typescript-go/internal/tspath.IsVolumeCharacter
+func IsVolumeCharacter(char byte) bool
+//go:linkname NormalizePath github.com/microsoft/typescript-go/internal/tspath.NormalizePath
+func NormalizePath(path string) string
+//go:linkname NormalizeSlashes github.com/microsoft/typescript-go/internal/tspath.NormalizeSlashes
+func NormalizeSlashes(path string) string
+type Path = tspath.Path
+//go:linkname PathIsAbsolute github.com/microsoft/typescript-go/internal/tspath.PathIsAbsolute
+func PathIsAbsolute(path string) bool
+//go:linkname PathIsRelative github.com/microsoft/typescript-go/internal/tspath.PathIsRelative
+func PathIsRelative(path string) bool
+//go:linkname RemoveExtension github.com/microsoft/typescript-go/internal/tspath.RemoveExtension
+func RemoveExtension(path string, extension string) string
+//go:linkname RemoveFileExtension github.com/microsoft/typescript-go/internal/tspath.RemoveFileExtension
+func RemoveFileExtension(path string) string
+//go:linkname RemoveTrailingDirectorySeparator github.com/microsoft/typescript-go/internal/tspath.RemoveTrailingDirectorySeparator
+func RemoveTrailingDirectorySeparator(path string) string
+//go:linkname RemoveTrailingDirectorySeparators github.com/microsoft/typescript-go/internal/tspath.RemoveTrailingDirectorySeparators
+func RemoveTrailingDirectorySeparators(path string) string
+//go:linkname ResolvePath github.com/microsoft/typescript-go/internal/tspath.ResolvePath
+func ResolvePath(path string, paths ...string) string
+//go:linkname ResolveTripleslashReference github.com/microsoft/typescript-go/internal/tspath.ResolveTripleslashReference
+func ResolveTripleslashReference(moduleName string, containingFile string) string
+//go:linkname SplitVolumePath github.com/microsoft/typescript-go/internal/tspath.SplitVolumePath
+func SplitVolumePath(path string) (volume string, rest string, ok bool)
+//go:linkname StartsWithDirectory github.com/microsoft/typescript-go/internal/tspath.StartsWithDirectory
+func StartsWithDirectory(fileName string, directoryName string, useCaseSensitiveFileNames bool) bool
+var SupportedDeclarationExtensions = tspath.SupportedDeclarationExtensions
+var SupportedJSExtensions = tspath.SupportedJSExtensions
+var SupportedJSExtensionsFlat = tspath.SupportedJSExtensionsFlat
+var SupportedTSExtensions = tspath.SupportedTSExtensions
+var SupportedTSExtensionsFlat = tspath.SupportedTSExtensionsFlat
+var SupportedTSExtensionsWithJson = tspath.SupportedTSExtensionsWithJson
+var SupportedTSExtensionsWithJsonFlat = tspath.SupportedTSExtensionsWithJsonFlat
+var SupportedTSImplementationExtensions = tspath.SupportedTSImplementationExtensions
+//go:linkname ToFileNameLowerCase github.com/microsoft/typescript-go/internal/tspath.ToFileNameLowerCase
+func ToFileNameLowerCase(fileName string) string
+//go:linkname ToPath github.com/microsoft/typescript-go/internal/tspath.ToPath
+func ToPath(fileName string, basePath string, useCaseSensitiveFileNames bool) tspath.Path
+//go:linkname TryExtractTSExtension github.com/microsoft/typescript-go/internal/tspath.TryExtractTSExtension
+func TryExtractTSExtension(fileName string) string
+//go:linkname TryGetExtensionFromPath github.com/microsoft/typescript-go/internal/tspath.TryGetExtensionFromPath
+func TryGetExtensionFromPath(p string) string

package/shim/vfs/cachedvfs/extra-shim.json

@@ -0,0 +1,4 @@
+{
+  "ExtraMethods": {},
+  "ExtraFields": {}
+}

package/shim/vfs/cachedvfs/go.mod

@@ -0,0 +1,5 @@
+module github.com/microsoft/typescript-go/shim/vfs/cachedvfs
+
+go 1.26
+
+require github.com/microsoft/typescript-go v0.0.0-20260408193441-2a5e1cf9fe22

package/shim/vfs/cachedvfs/shim.go

@@ -0,0 +1,12 @@
+
+// Code generated by packages/ttsc/tools/gen_shims. DO NOT EDIT.
+
+package cachedvfs
+
+import "github.com/microsoft/typescript-go/internal/vfs"
+import "github.com/microsoft/typescript-go/internal/vfs/cachedvfs"
+import _ "unsafe"
+
+type FS = cachedvfs.FS
+//go:linkname From github.com/microsoft/typescript-go/internal/vfs/cachedvfs.From
+func From(fs vfs.FS) *cachedvfs.FS

package/shim/vfs/extra-shim.json

@@ -0,0 +1,4 @@
+{
+  "ExtraMethods": {},
+  "ExtraFields": {}
+}

package/shim/vfs/go.mod

@@ -0,0 +1,5 @@
+module github.com/microsoft/typescript-go/shim/vfs
+
+go 1.26
+
+require github.com/microsoft/typescript-go v0.0.0-20260408193441-2a5e1cf9fe22

package/shim/vfs/osvfs/extra-shim.json

@@ -0,0 +1,4 @@
+{
+  "ExtraMethods": {},
+  "ExtraFields": {}
+}

package/shim/vfs/osvfs/go.mod

@@ -0,0 +1,5 @@
+module github.com/microsoft/typescript-go/shim/vfs/osvfs
+
+go 1.26
+
+require github.com/microsoft/typescript-go v0.0.0-20260408193441-2a5e1cf9fe22

package/shim/vfs/osvfs/shim.go

@@ -0,0 +1,13 @@
+
+// Code generated by packages/ttsc/tools/gen_shims. DO NOT EDIT.
+
+package osvfs
+
+import "github.com/microsoft/typescript-go/internal/vfs"
+import _ "github.com/microsoft/typescript-go/internal/vfs/osvfs"
+import _ "unsafe"
+
+//go:linkname FS github.com/microsoft/typescript-go/internal/vfs/osvfs.FS
+func FS() vfs.FS
+//go:linkname GetGlobalTypingsCacheLocation github.com/microsoft/typescript-go/internal/vfs/osvfs.GetGlobalTypingsCacheLocation
+func GetGlobalTypingsCacheLocation() string

package/shim/vfs/shim.go

@@ -0,0 +1,19 @@
+
+// Code generated by packages/ttsc/tools/gen_shims. DO NOT EDIT.
+
+package vfs
+
+import "github.com/microsoft/typescript-go/internal/vfs"
+
+type DirEntry = vfs.DirEntry
+type Entries = vfs.Entries
+var ErrClosed = vfs.ErrClosed
+var ErrExist = vfs.ErrExist
+var ErrInvalid = vfs.ErrInvalid
+var ErrNotExist = vfs.ErrNotExist
+var ErrPermission = vfs.ErrPermission
+type FS = vfs.FS
+type FileInfo = vfs.FileInfo
+var SkipAll = vfs.SkipAll
+var SkipDir = vfs.SkipDir
+type WalkDirFunc = vfs.WalkDirFunc

package/src/api.ts

@@ -0,0 +1,416 @@
+/**
+ * Programmatic API for ttsc.
+ *
+ * This module is the TypeScript surface bundler adapters (unplugin, vite,
+ * webpack, rollup, esbuild, rspack, farm, next/swc, bun) consume. Everything
+ * here is a thin wrapper around the Go binary resolved by `platform.ts` —
+ * adapters never have to spawn the process themselves.
+ *
+ * Contract:
+ *
+ * - `transform()` emits one file's rewritten JS, returning the text.
+ * - `build()` runs the whole project (tsgo + ttsc rewrite + --emit).
+ * - `check()` runs the analysis pass without emitting (CI gate use).
+ * - `version()` returns the binary's version banner for user-agent logs.
+ *
+ * All helpers accept a `binary` override so tests can point at a specific
+ * executable without touching PATH or node_modules.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { type ResolveOptions, installHint, resolveBinary } from "./platform";
+import {
+  type TtscPlugin,
+  applyPluginTransforms,
+  loadProjectPlugins,
+} from "./plugin";
+import {
+  type ProjectPluginConfig,
+  resolveProjectConfig,
+  resolveProjectRoot,
+} from "./project";
+
+/**
+ * Options shared by every API call. `binary` takes precedence over platform
+ * resolution; `cwd` defaults to `process.cwd()`; `env` layers on top of the
+ * current process env.
+ */
+export interface CommonOptions extends ResolveOptions {
+  /** Absolute path to an already-resolved ttsc binary. Skips 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 ProjectPluginConfig[] | 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;
+}
+
+/** Options for `transform()`. */
+export interface TransformOptions extends CommonOptions {
+  /** 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;
+}
+
+/** Options for `build()`. */
+export interface BuildOptions extends CommonOptions {
+  /** 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;
+}
+
+/** Options for `check()`. */
+export type CheckOptions = Omit<BuildOptions, "emit">;
+
+/**
+ * Resolve the binary or throw a user-friendly error. Extracted so every API
+ * helper shares the same failure mode.
+ */
+function resolveOrThrow(opts: CommonOptions): string {
+  if (
+    opts.binary &&
+    path.isAbsolute(opts.binary) &&
+    fs.existsSync(opts.binary)
+  ) {
+    return opts.binary;
+  }
+  const bin = resolveBinary(opts);
+  if (!bin) {
+    throw new Error(installHint(opts));
+  }
+  return bin;
+}
+
+/** Merge spawn env without clobbering unrelated vars. */
+function mergeEnv(extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  if (!extra) return process.env;
+  return { ...process.env, ...extra };
+}
+
+function spawnBinary(
+  binary: string,
+  args: readonly string[],
+  options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    encoding?: BufferEncoding;
+  },
+) {
+  const viaNode = shouldSpawnViaNode(binary);
+  if (!viaNode) {
+    ensureExecutable(binary);
+  }
+  return spawnSync(
+    viaNode ? process.execPath : binary,
+    viaNode ? [binary, ...args] : [...args],
+    {
+      cwd: options.cwd,
+      env: options.env,
+      encoding: options.encoding,
+      maxBuffer: 1024 * 1024 * 256,
+      windowsHide: true,
+    },
+  );
+}
+
+function shouldSpawnViaNode(binary: string): boolean {
+  return /\.(?:[cm]?js|ts)$/i.test(binary);
+}
+
+function ensureExecutable(binary: string): void {
+  if (process.platform === "win32") {
+    return;
+  }
+  try {
+    const mode = fs.statSync(binary).mode & 0o777;
+    if ((mode & 0o111) !== 0) {
+      return;
+    }
+    fs.chmodSync(binary, mode | 0o755);
+  } catch {
+    /* keep the original spawn error path */
+  }
+}
+
+function outputText(value: string | Buffer | null | undefined): string {
+  if (value == null) {
+    return "";
+  }
+  return typeof value === "string" ? value : value.toString("utf8");
+}
+
+/**
+ * Transform a single .ts file and return the rewritten JS as a string.
+ *
+ * Intended for bundler per-file transforms (unplugin `transform()`). The caller
+ * passes the absolute path; ttsc loads the enclosing tsconfig, compiles with
+ * tsgo, and returns the rewritten JS.
+ *
+ * Throws when the binary exits non-zero — the error includes stderr so bundler
+ * error overlays surface the real cause.
+ */
+export function transform(options: TransformOptions): string {
+  const execution = resolveExecutionContext(options);
+  const sourceFile = realpathIfExists(
+    path.isAbsolute(options.file)
+      ? options.file
+      : path.resolve(options.cwd ?? process.cwd(), options.file),
+  );
+  const args = [
+    "transform",
+    "--file=" + sourceFile,
+    "--tsconfig=" + execution.tsconfig,
+    "--rewrite-mode=" + execution.nativeMode,
+  ];
+
+  const res = spawnBinary(execution.bin, args, {
+    cwd: options.cwd,
+    env: mergeEnv(options.env),
+    encoding: "utf8",
+  });
+  if (res.error) {
+    throw new Error(
+      "ttsc.transform: failed to spawn " +
+        execution.bin +
+        ": " +
+        res.error.message,
+    );
+  }
+  if (res.status !== 0) {
+    throw new Error(
+      "ttsc.transform exited " + res.status + "\n" + (res.stderr || ""),
+    );
+  }
+  const transformed = finalizeTransformText(
+    execution.plugins,
+    {
+      command: "transform",
+      cwd: execution.cwd,
+      projectRoot: execution.projectRoot,
+      sourceFile,
+      tsconfig: execution.tsconfig,
+    },
+    outputText(res.stdout),
+  );
+  if (options.out) {
+    fs.mkdirSync(path.dirname(options.out), { recursive: true });
+    fs.writeFileSync(options.out, transformed, "utf8");
+  }
+  return transformed;
+}
+
+function realpathIfExists(file: string): string {
+  try {
+    return fs.realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+/** Result of `build()`. Non-zero `status` means the build failed. */
+export interface BuildResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * Run `ttsc` against a tsconfig. Returns once the binary exits so the caller
+ * can decide how to surface diagnostics. Does not throw on non-zero exit —
+ * bundler pipelines often want to continue and collect errors.
+ */
+export function build(options: BuildOptions = {}): BuildResult {
+  const execution = resolveExecutionContext(options);
+  const args = [
+    "build",
+    "--tsconfig=" + execution.tsconfig,
+    "--rewrite-mode=" + execution.nativeMode,
+  ];
+  if (options.emit === true) args.push("--emit");
+  else if (options.emit === false) args.push("--noEmit");
+  if (options.outDir) args.push("--outDir=" + options.outDir);
+  if (options.quiet === false) args.push("--verbose");
+  else if (options.quiet === true) args.push("--quiet");
+  const needsManifest = options.emit !== false && execution.plugins.length > 0;
+  const manifest = needsManifest ? createTempManifestPath() : null;
+  if (manifest) args.push("--manifest=" + manifest);
+
+  const res = spawnBinary(execution.bin, args, {
+    cwd: options.cwd,
+    env: mergeEnv(options.env),
+    encoding: "utf8",
+  });
+  if (res.error) {
+    throw new Error(
+      "ttsc.build: failed to spawn " + execution.bin + ": " + res.error.message,
+    );
+  }
+  if ((res.status ?? 1) === 0 && manifest) {
+    try {
+      const emittedFiles = JSON.parse(
+        fs.readFileSync(manifest, "utf8"),
+      ) as string[];
+      applyBuildPlugins(execution.plugins, execution, emittedFiles);
+    } finally {
+      fs.rmSync(path.dirname(manifest), { recursive: true, force: true });
+    }
+  }
+  return {
+    status: res.status ?? 1,
+    stdout: outputText(res.stdout),
+    stderr: outputText(res.stderr),
+  };
+}
+
+/**
+ * Run `ttsc check` (build without emit) — CI gate / pre-commit hook use.
+ * Resolves with an exit-code record; does not throw.
+ */
+export function check(options: CheckOptions = {}): BuildResult {
+  return build({ ...options, emit: false });
+}
+
+/** Ask the binary for its version banner. Handy for user-agent strings. */
+export function version(options: CommonOptions = {}): string {
+  const bin = resolveOrThrow(options);
+  const res = spawnBinary(bin, ["version"], {
+    encoding: "utf8",
+  });
+  if (res.error || res.status !== 0) {
+    throw new Error(
+      "ttsc.version: failed: " + (outputText(res.stderr) || res.error?.message),
+    );
+  }
+  return outputText(res.stdout).trim();
+}
+
+/**
+ * Promise-facing variant of `transform()`. The plugin host keeps the transform
+ * pipeline synchronous so plugin modules can stay dependency-free, but many
+ * adapter surfaces still prefer a Promise-returning function.
+ */
+export function transformAsync(options: TransformOptions): Promise<string> {
+  return Promise.resolve().then(() => transform(options));
+}
+
+interface ExecutionContext {
+  bin: string;
+  cwd: string;
+  nativeMode: string;
+  plugins: readonly TtscPlugin[];
+  projectRoot: string;
+  tsconfig: string;
+}
+
+function resolveExecutionContext(
+  options: CommonOptions & { tsconfig?: string },
+): ExecutionContext {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const fallbackBinary =
+    options.binary &&
+    path.isAbsolute(options.binary) &&
+    fs.existsSync(options.binary)
+      ? options.binary
+      : resolveBinary(options);
+  const tsconfig = resolveProjectConfig({
+    cwd,
+    tsconfig: options.tsconfig,
+  });
+  const projectRoot = resolveProjectRoot({ cwd, tsconfig });
+  const loaded = loadProjectPlugins({
+    binary: fallbackBinary ?? "",
+    cwd,
+    entries: options.plugins,
+    tsconfig,
+  });
+  const bin = options.binary ?? loaded.nativeBinary ?? fallbackBinary;
+  if (!bin) {
+    throw new Error(installHint(options));
+  }
+  return {
+    bin,
+    cwd,
+    nativeMode: options.rewriteMode ?? loaded.nativeMode,
+    plugins: loaded.plugins.filter((plugin) => plugin.transformOutput),
+    projectRoot,
+    tsconfig,
+  };
+}
+
+function finalizeTransformText(
+  plugins: readonly TtscPlugin[],
+  context: Omit<Parameters<typeof applyPluginTransforms>[1], "code">,
+  text: string,
+): string {
+  if (plugins.length === 0) {
+    return text;
+  }
+  return applyPluginTransforms(plugins, {
+    ...context,
+    code: text,
+  });
+}
+
+function applyBuildPlugins(
+  plugins: readonly TtscPlugin[],
+  execution: ExecutionContext,
+  emittedFiles: readonly string[],
+): void {
+  if (plugins.length === 0) {
+    return;
+  }
+  for (const file of emittedFiles) {
+    if (!isJavaScriptOutput(file) || !fs.existsSync(file)) {
+      continue;
+    }
+    const current = fs.readFileSync(file, "utf8");
+    const next = applyPluginTransforms(plugins, {
+      code: current,
+      command: "build",
+      cwd: execution.cwd,
+      outputFile: file,
+      projectRoot: execution.projectRoot,
+      tsconfig: execution.tsconfig,
+    });
+    if (next !== current) {
+      fs.writeFileSync(file, next, "utf8");
+    }
+  }
+}
+
+function isJavaScriptOutput(file: string): boolean {
+  return /\.(?:[cm]?js)$/i.test(file);
+}
+
+function createTempManifestPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ttsc-build-"));
+  return path.join(dir, "manifest.json");
+}