ttsc 0.6.0 → 0.7.0

package/src/structures/ITtscCompilerDiagnostic.ts

@@ -0,0 +1,91 @@
+/**
+ * Diagnostic information from the ttsc TypeScript-Go compiler.
+ *
+ * Represents standardized diagnostic information produced during a
+ * TypeScript-Go compilation. This interface provides a simplified and
+ * consistent representation of TypeScript's diagnostic structure without
+ * requiring callers to depend on TypeScript-Go's internal Go types or parse
+ * terminal output.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export interface ITtscCompilerDiagnostic {
+  /**
+   * The filename where the diagnostic originated, or null if not
+   * file-specific.
+   *
+   * Global diagnostics such as invalid compiler options or host-level failures
+   * are reported with `null` because they are not tied to a single source file.
+   */
+  file: string | null;
+
+  /**
+   * The severity category of the diagnostic.
+   *
+   * Values follow TypeScript's diagnostic categories: error, warning,
+   * suggestion, and message.
+   */
+  category: ITtscCompilerDiagnostic.Category;
+
+  /**
+   * The error code or identifier associated with this diagnostic.
+   *
+   * TypeScript diagnostics normally use numeric codes such as `2322`. Native
+   * plugins may use stable string identifiers for plugin-defined diagnostics.
+   */
+  code: number | string;
+
+  /**
+   * The starting position of the issue in the source file, if available.
+   *
+   * TypeScript-Go reports this as a zero-based character offset. It is omitted
+   * for global diagnostics or messages that do not expose a source offset.
+   */
+  start?: number;
+
+  /**
+   * The length of the problematic section in the source file, if available.
+   *
+   * Omitted when TypeScript-Go or a native plugin reports only a point
+   * location, or when the diagnostic is not tied to a source file.
+   */
+  length?: number;
+
+  /**
+   * 1-based line number where the diagnostic starts, if available.
+   *
+   * This follows TypeScript's display convention rather than TypeScript-Go's
+   * zero-based internal line index.
+   */
+  line?: number;
+
+  /**
+   * 1-based character (column) position where the diagnostic starts, if
+   * available.
+   *
+   * This follows TypeScript's display convention rather than TypeScript-Go's
+   * zero-based internal column index.
+   */
+  character?: number;
+
+  /**
+   * The human-readable diagnostic message describing the issue.
+   *
+   * Message chains are flattened into text so callers do not need to depend on
+   * TypeScript-Go's internal diagnostic representation.
+   */
+  messageText: string;
+}
+
+export namespace ITtscCompilerDiagnostic {
+  /**
+   * Possible severity categories for diagnostics.
+   *
+   * - `"warning"`: issues that might cause problems but do not necessarily
+   *   prevent compilation.
+   * - `"error"`: issues that prevent successful compilation.
+   * - `"suggestion"`: recommendations for code improvement.
+   * - `"message"`: informational notes without warning or error severity.
+   */
+  export type Category = "warning" | "error" | "suggestion" | "message";
+}

package/src/structures/ITtscCompilerResult.ts

@@ -0,0 +1,94 @@
+import type { ITtscCompilerDiagnostic } from "./ITtscCompilerDiagnostic";
+
+/**
+ * Result of a ttsc TypeScript-Go compilation operation.
+ *
+ * Represents the possible outcomes of {@link TtscCompiler.compile}, which can
+ * be either a successful compilation, a compilation that completed with
+ * diagnostics, or an unexpected host error during the compilation process.
+ *
+ * This type follows the legacy `embed-typescript` result model, but stores all
+ * emitted text artifacts in {@link ITtscCompilerResult.ISuccess.output} and
+ * {@link ITtscCompilerResult.IFailure.output}. TypeScript-Go may emit
+ * JavaScript, declaration files, source maps, and declaration maps from one
+ * compile operation, so the public result is not limited to JavaScript.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export type ITtscCompilerResult =
+  | ITtscCompilerResult.ISuccess
+  | ITtscCompilerResult.IFailure
+  | ITtscCompilerResult.IException;
+
+export namespace ITtscCompilerResult {
+  /**
+   * Represents a successful ttsc compilation result.
+   *
+   * This interface is returned when TypeScript-Go completes without
+   * diagnostics, containing every text output captured from the native
+   * compiler host's `WriteFile` callback.
+   */
+  export interface ISuccess {
+    /**
+     * Indicates that the compilation was successful.
+     */
+    type: "success";
+
+    /**
+     * The generated compiler output.
+     *
+     * A record mapping project-relative output file paths to their generated
+     * text content. This includes JavaScript, declaration files, source maps,
+     * declaration maps, and any other text artifact emitted through
+     * TypeScript-Go's `WriteFile` callback.
+     */
+    output: Record<string, string>;
+  }
+
+  /**
+   * Represents a ttsc compilation that completed but had diagnostics.
+   *
+   * This interface is returned when the compiler reports errors, warnings, or
+   * other diagnostics during normal compilation. It contains both structured
+   * diagnostic information and any output that was still generated despite the
+   * diagnostics.
+   */
+  export interface IFailure {
+    /**
+     * Indicates that compilation completed with diagnostics.
+     */
+    type: "failure";
+
+    /**
+     * Array of diagnostic messages describing the compilation issues.
+     */
+    diagnostics: ITtscCompilerDiagnostic[];
+
+    /**
+     * Any compiler output that was generated despite the diagnostics.
+     *
+     * This may be partial or empty depending on the severity of the issues and
+     * how far TypeScript-Go progressed before returning diagnostics.
+     */
+    output: Record<string, string>;
+  }
+
+  /**
+   * Represents an unexpected error during the compilation process.
+   *
+   * This interface is returned when ttsc cannot prepare, build, or spawn the
+   * native compiler host. Normal TypeScript diagnostics are represented by
+   * {@link IFailure}; this variant is reserved for host-level exceptions.
+   */
+  export interface IException {
+    /**
+     * Indicates that an unexpected host error occurred.
+     */
+    type: "exception";
+
+    /**
+     * The error that was thrown while preparing or running the compiler host.
+     */
+    error: unknown;
+  }
+}

package/src/structures/ITtscPlugin.ts

@@ -1,11 +1,58 @@
-import type { ITtscNativeBackend } from "./ITtscNativeBackend";
-import type { ITtscNativeRewriteMode } from "./ITtscNativeRewriteMode";
+import type { TtscPluginStage } from "./TtscPluginStage";
 
+/**
+ * Runtime descriptor returned by a ttsc plugin module.
+ *
+ * A JavaScript plugin entry in `compilerOptions.plugins[]` is only the loading
+ * point. After ttsc resolves that JavaScript module, the module must return an
+ * `ITtscPlugin` descriptor either directly, as `default`, as `plugin`, or from
+ * `createTtscPlugin(context)`.
+ *
+ * The descriptor tells ttsc which Go command package implements the native
+ * sidecar and where that sidecar participates in the TypeScript-Go pipeline.
+ * ttsc then builds the Go source lazily with the bundled Go toolchain and
+ * passes the original project plugin config to the sidecar through
+ * `--plugins-json`.
+ */
 export interface ITtscPlugin {
+  /**
+   * Stable plugin name used in diagnostics, build messages, and native plugin
+   * manifests.
+   *
+   * Keep this stable across releases. Native sidecars and downstream tooling
+   * can use the name to select their own config from the ordered
+   * `--plugins-json` payload.
+   */
   name: string;
-  native?: ITtscNativeBackend;
-  /** @deprecated Use `native.mode` instead. */
-  nativeMode?: ITtscNativeRewriteMode;
-  /** @deprecated Use `native.binary` instead. */
-  nativeBinary?: string;
+
+  /**
+   * Go command package directory, or a `go.mod` file, that ttsc lazily builds.
+   *
+   * ttsc accepts source only. It does not accept a prebuilt binary path: the
+   * package-local Go compiler builds this source into the ttsc plugin cache on
+   * demand.
+   *
+   * Directory sources search upward at most 3 parent directories for `go.mod`;
+   * direct `go.mod` sources build the module root as `.`.
+   *
+   * Common layouts:
+   *
+   * - `source: "src"` when the plugin package keeps its Go command in `src`.
+   * - `source: "plugin"` when the repository has a dedicated Go plugin folder.
+   * - `source: "lib"` only when the published package intentionally ships Go
+   *   source under `lib` instead of compiled JavaScript.
+   * - `source: "go.mod"` when the module root itself is the command package.
+   */
+  source: string;
+
+  /**
+   * Pipeline stage implemented by the sidecar.
+   *
+   * Omit this field for normal compiler-transform plugins. Explicit stages are
+   * intended for tools that only validate (`"check"`) or rewrite already
+   * emitted files (`"output"`).
+   *
+   * @default "transform"
+   */
+  stage?: TtscPluginStage;
 }

package/src/structures/ITtscPluginFactoryContext.ts

@@ -1,9 +1,60 @@
 import type { ITtscProjectPluginConfig } from "./ITtscProjectPluginConfig";
 
+/**
+ * Project context passed to `createTtscPlugin()` factories.
+ *
+ * Plugin packages may export a static {@link ITtscPlugin} descriptor when the
+ * descriptor never depends on the consuming project. Export a
+ * `createTtscPlugin(context)` factory instead when the descriptor needs to
+ * inspect the original plugin config, the resolved tsconfig path, or the
+ * project root.
+ *
+ * The factory runs in Node.js while ttsc is loading `compilerOptions.plugins`.
+ * It should only create the descriptor. Heavy validation and TypeScript-Go
+ * work belong in the Go sidecar selected by {@link ITtscPlugin.source}.
+ */
 export interface ITtscPluginFactoryContext<T = ITtscProjectPluginConfig> {
+  /**
+   * Absolute ttsc native helper binary selected for this invocation.
+   *
+   * This is the package's own native helper, not the plugin sidecar and not the
+   * JavaScript launcher. Most plugins do not need it; it is provided for
+   * advanced factories that need to derive behavior from the active ttsc
+   * native host.
+   */
   binary: string;
+
+  /**
+   * Current working directory requested by the caller.
+   *
+   * This is the cwd used for project discovery and relative command-line
+   * inputs. It can differ from {@link ITtscPluginFactoryContext.projectRoot}
+   * when the caller points at a tsconfig in another directory.
+   */
   cwd: string;
+
+  /**
+   * Original `compilerOptions.plugins[]` entry that loaded this plugin.
+   *
+   * ttsc reserves `transform` and `enabled`. Every other property is
+   * plugin-owned config and is later serialized unchanged into the native
+   * sidecar manifest.
+   */
   plugin: T;
+
+  /**
+   * Directory containing the resolved tsconfig/jsconfig.
+   *
+   * Relative plugin module specifiers and plugin source paths are resolved from
+   * this directory, matching TypeScript plugin config behavior.
+   */
   projectRoot: string;
+
+  /**
+   * Absolute path to the resolved tsconfig/jsconfig.
+   *
+   * Factories can use this to select descriptor variants for monorepos or
+   * multiple project configs without reparsing command-line arguments.
+   */
   tsconfig: string;
 }

package/src/structures/ITtscProjectPluginConfig.ts

@@ -1,5 +1,48 @@
+/**
+ * Raw `compilerOptions.plugins[]` entry read from tsconfig/jsconfig.
+ *
+ * This is the project-facing config shape that users write in
+ * `tsconfig.json`. ttsc deliberately keeps it open-ended because plugin
+ * packages own their own config fields.
+ *
+ * ttsc interprets only two properties:
+ *
+ * - `transform`: the JavaScript module specifier used to load the plugin
+ *   descriptor or factory.
+ * - `enabled`: an opt-out switch that keeps the config entry in the file while
+ *   preventing ttsc from loading it.
+ *
+ * Every other property is preserved as plugin config. After ttsc loads and
+ * builds the plugin, the original entry is serialized into the native sidecar
+ * manifest so Go code can read exactly the same plugin-specific options.
+ */
 export interface ITtscProjectPluginConfig {
+  /**
+   * Set to `false` to keep the entry while disabling it for ttsc.
+   *
+   * This is useful for sharing one tsconfig across environments while turning
+   * selected plugins on or off without deleting their config.
+   */
   enabled?: boolean;
+
+  /**
+   * Plugin module specifier, relative path, or absolute path to load.
+   *
+   * Relative paths are resolved from the resolved project root, which is the
+   * directory containing the active tsconfig/jsconfig. Package specifiers are
+   * resolved with Node's package resolution from that same project root.
+   *
+   * The loaded JavaScript module must export an {@link ITtscPlugin} descriptor
+   * or a `createTtscPlugin(context)` factory. The Go implementation itself is
+   * declared by the descriptor's {@link ITtscPlugin.source} field.
+   */
   transform?: string;
+
+  /**
+   * Plugin-specific config passed through unchanged to the native sidecar.
+   *
+   * ttsc does not validate these fields. Plugin packages should document their
+   * own config contract and validate it inside their factory or Go sidecar.
+   */
   [key: string]: unknown;
 }

package/src/structures/TtscPluginStage.ts

@@ -0,0 +1,15 @@
+/**
+ * Pipeline stage where a plugin's lazily built Go sidecar participates.
+ *
+ * - `"transform"`: owns the TypeScript-Go emit pass. This is the default and
+ *   is the right stage for compiler-transform plugins such as typia-style
+ *   source rewrites. A transform sidecar receives the ordered plugin manifest
+ *   and is responsible for producing the project's emitted output.
+ * - `"check"`: runs before emit and reports diagnostics only. Use this for
+ *   lint or validation plugins that should fail the compile before JavaScript
+ *   or declaration output is generated.
+ * - `"output"`: runs after emit for each emitted output file. Use this for
+ *   post-processing plugins such as banner insertion, import-path rewriting,
+ *   or output stripping that operate on `.js`, `.d.ts`, or map files.
+ */
+export type TtscPluginStage = "transform" | "check" | "output";

package/src/structures/index.ts

@@ -0,0 +1,7 @@
+export * from "./ITtscCompilerContext";
+export * from "./ITtscCompilerDiagnostic";
+export * from "./ITtscCompilerResult";
+export * from "./ITtscPlugin";
+export * from "./ITtscPluginFactoryContext";
+export * from "./ITtscProjectPluginConfig";
+export * from "./TtscPluginStage";

package/src/structures/internal/ITtscLoadedNativePlugin.ts

@@ -0,0 +1,14 @@
+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/src/structures/internal/ITtscParsedProjectConfig.ts

@@ -0,0 +1,16 @@
+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/src/structures/internal/ITtscProjectLocatorOptions.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/src/structures/internal/TtscBuildOptions.ts

@@ -0,0 +1,19 @@
+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/src/structures/internal/TtscBuildResult.ts

@@ -0,0 +1,15 @@
+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/src/structures/internal/TtscCommonOptions.ts

@@ -0,0 +1,28 @@
+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/src/structures/internal/TtscTransformOptions.ts

@@ -0,0 +1,15 @@
+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;
+}