ttsc 0.6.0 → 0.7.1

package/cmd/platform/main.go

@@ -39,7 +39,7 @@ func run(args []string) int {
 		return 0
 	case "demo":
 		return runDemo(args[1:])
-	case "build", "check", "transform":
+	case "build", "check":
 		fmt.Fprintf(
 			stderr,
 			"ttsc platform helper: %s is provided by the JavaScript ttsc CLI using the consuming project's @typescript/native-preview, or by a plugin-selected native sidecar.\n",

package/cmd/ttsc/api_compile.go

@@ -0,0 +1,134 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+type apiCompileResult struct {
+	Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
+	Output      map[string]string      `json:"output"`
+}
+
+type apiCompileDiagnostic struct {
+	File        *string `json:"file"`
+	Category    string  `json:"category"`
+	Code        int32   `json:"code"`
+	Start       *int    `json:"start,omitempty"`
+	Length      *int    `json:"length,omitempty"`
+	Line        int     `json:"line,omitempty"`
+	Character   int     `json:"character,omitempty"`
+	MessageText string  `json:"messageText"`
+}
+
+func runAPICompile(args []string) int {
+	fs := flag.NewFlagSet("api-compile", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
+	cwdOverride := fs.String("cwd", "", "override the working directory")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+
+	cwd, ok := resolveBuildCwd(*cwdOverride)
+	if !ok {
+		return 2
+	}
+
+	prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
+		ForceEmit: true,
+	})
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc api-compile: %v\n", err)
+		return 2
+	}
+	if prog != nil {
+		defer prog.Close()
+		diags = append(diags, prog.Diagnostics()...)
+	}
+
+	output := map[string]string{}
+	if prog != nil {
+		rewrites := driver.NewRewriteSet()
+		writeFile := shimcompiler.WriteFile(
+			func(fileName, text string, _ *shimcompiler.WriteFileData) error {
+				output[apiOutputKey(cwd, fileName)] = text
+				return nil
+			},
+		)
+		_, emitDiags, err := prog.EmitAll(rewrites, writeFile)
+		if err != nil {
+			fmt.Fprintf(stderr, "ttsc api-compile: emit failed: %v\n", err)
+			return 3
+		}
+		diags = append(diags, emitDiags...)
+	}
+
+	result := apiCompileResult{
+		Diagnostics: make([]apiCompileDiagnostic, 0, len(diags)),
+		Output:      output,
+	}
+	for _, diag := range diags {
+		result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))
+	}
+
+	data, err := json.Marshal(result)
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc api-compile: result marshal failed: %v\n", err)
+		return 3
+	}
+	fmt.Fprintln(stdout, string(data))
+	if driver.CountErrors(diags) > 0 {
+		return 2
+	}
+	return 0
+}
+
+func resolveBuildCwd(cwdOverride string) (string, bool) {
+	if cwdOverride != "" {
+		return cwdOverride, true
+	}
+	cwd, err := os.Getwd()
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc: could not get working directory: %v\n", err)
+		return "", false
+	}
+	return cwd, true
+}
+
+func toAPICompileDiagnostic(diag driver.Diagnostic) apiCompileDiagnostic {
+	var file *string
+	if diag.File != "" {
+		value := diag.File
+		file = &value
+	}
+	category := "error"
+	if diag.Severity == driver.SeverityWarning {
+		category = "warning"
+	}
+	return apiCompileDiagnostic{
+		File:        file,
+		Category:    category,
+		Code:        diag.Code,
+		Start:       diag.Start,
+		Length:      diag.Length,
+		Line:        diag.Line,
+		Character:   diag.Column,
+		MessageText: diag.Message,
+	}
+}
+
+func apiOutputKey(cwd, fileName string) string {
+	if rel, err := filepath.Rel(cwd, fileName); err == nil && !strings.HasPrefix(rel, "..") {
+		return filepath.ToSlash(rel)
+	}
+	return filepath.ToSlash(fileName)
+}

package/cmd/ttsc/api_transform.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+type apiTransformResult struct {
+	Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
+	TypeScript  map[string]string      `json:"typescript"`
+}
+
+func runAPITransform(args []string) int {
+	fs := flag.NewFlagSet("api-transform", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	tsconfigPath := fs.String("tsconfig", "tsconfig.json", "path to tsconfig.json")
+	cwdOverride := fs.String("cwd", "", "override the working directory")
+	if err := fs.Parse(args); err != nil {
+		return 2
+	}
+
+	cwd, ok := resolveBuildCwd(*cwdOverride)
+	if !ok {
+		return 2
+	}
+
+	prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
+		ForceNoEmit: true,
+	})
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc api-transform: %v\n", err)
+		return 2
+	}
+	typescript := map[string]string{}
+	if prog != nil {
+		defer prog.Close()
+		for _, file := range prog.SourceFiles() {
+			typescript[apiOutputKey(cwd, file.FileName())] = file.Text()
+		}
+		diags = append(diags, prog.Diagnostics()...)
+	}
+
+	result := apiTransformResult{
+		Diagnostics: make([]apiCompileDiagnostic, 0, len(diags)),
+		TypeScript:  typescript,
+	}
+	for _, diag := range diags {
+		result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))
+	}
+
+	data, err := json.Marshal(result)
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc api-transform: result marshal failed: %v\n", err)
+		return 3
+	}
+	fmt.Fprintln(stdout, string(data))
+	if driver.CountErrors(diags) > 0 {
+		return 2
+	}
+	return 0
+}

package/cmd/ttsc/build.go

@@ -28,7 +28,6 @@ func runBuild(args []string) int {
 	noEmit := fs.Bool("noEmit", false, "force analysis-only run with no file writes")
 	outDir := fs.String("outDir", "", "override compilerOptions.outDir for this build")
 	manifestPath := fs.String("manifest", "", "write emitted file list as JSON to this path")
-	rewriteMode := fs.String("rewrite-mode", "none", "native rewrite backend id")
 	if err := fs.Parse(args); err != nil {
 		return 2
 	}
@@ -71,13 +70,8 @@ func runBuild(args []string) int {
 
 	rewrites := driver.NewRewriteSet()
 	shouldEmit := !prog.ParsedConfig.ParsedConfig.CompilerOptions.NoEmit.IsTrue()
-	if *rewriteMode != "none" {
-		fmt.Fprintf(stderr, "ttsc: rewrite backend %q is not built into the standalone ttsc binary\n", *rewriteMode)
-		fmt.Fprintln(stderr, "ttsc: run through the JS host with the matching compiler plugin so it can select the consumer-provided native binary")
-		return 2
-	}
 	if !*quiet {
-		fmt.Fprintf(stdout, "// ttsc: tsconfig=%s cwd=%s sites=%d emit=%v rewrite=%s\n", *tsconfigPath, cwd, 0, shouldEmit, *rewriteMode)
+		fmt.Fprintf(stdout, "// ttsc: tsconfig=%s cwd=%s sites=%d emit=%v\n", *tsconfigPath, cwd, 0, shouldEmit)
 	}
 
 	if shouldEmit {

package/cmd/ttsc/main.go

@@ -4,8 +4,8 @@
 //   - Report version and platform (`ttsc --version`).
 //   - Exercise a native rewrite backend end-to-end (`ttsc demo --type=string`)
 //     so smoke tests can verify the Go binary really runs.
-//   - Host the native project build, check, and single-file transform paths used
-//     by plugin-selected sidecars and smoke tests.
+//   - Host the native project build and check paths used by plugin-selected
+//     sidecars and smoke tests.
 //
 // Everything below is deliberately dependency-free so that the standalone binary
 // stays small and its behavior is trivial to audit.
@@ -54,15 +54,14 @@ func run(args []string) int {
 		return runDemo(args[1:])
 	case "build":
 		return runBuild(args[1:])
+	case "api-compile":
+		return runAPICompile(args[1:])
+	case "api-transform":
+		return runAPITransform(args[1:])
 	case "check":
 		// `ttsc check` runs the analyze pipeline without emitting JS — useful
 		// in CI and pre-commit hooks that only need schema validation.
 		return runBuild(append([]string{"--noEmit"}, args[1:]...))
-	case "transform":
-		// Single-file transform for bundler plugin integration (unplugin,
-		// vite, esbuild, webpack, …). Emits only the requested file's JS to
-		// stdout or a chosen path — no project-wide write.
-		return runTransform(args[1:])
 	case "-p", "--project":
 		if len(args) < 2 {
 			fmt.Fprintln(stderr, "ttsc: -p/--project requires a path argument")
@@ -135,13 +134,11 @@ Usage:
   ttsc -p tsconfig.json
   ttsc --watch
   ttsc --noEmit
-  ttsc transform --file=src/main.ts
 
 Project build:
   ttsc compiles the current tsconfig.json, matching the tsc/tsgo shape.
   build         Compatibility alias for the same project build lane.
   check         Compatibility alias for --noEmit validation.
-  transform     Emit a single file's rewritten JS (bundler plugin hook).
   demo          Run a native backend smoke pipeline with synthetic input.
   version       Print version, build info, and platform.
   help          Show this help.
@@ -153,15 +150,8 @@ Build options:
   --noEmit          Force analysis-only run even when tsconfig would emit.
   --quiet           Suppress the per-call summary banner (default).
   --verbose         Print the per-call summary banner and emitted file list.
-  --rewrite-mode=M  Native rewrite backend id.
   --manifest=FILE   Write emitted file paths as JSON to FILE after build --emit.
 
-Transform options:
-  --file=PATH       Absolute or cwd-relative path of the .ts file to transform.
-  --tsconfig=FILE   tsconfig.json owning --file (default: tsconfig.json).
-  --out=PATH        Write output JS to PATH. Default: stdout.
-  --rewrite-mode=M  Native rewrite backend id.
-
 Demo options:
   --type=T          Atomic TypeScript type to simulate. One of:
                       string, number, boolean, bigint, any (default: string).
@@ -171,13 +161,9 @@ Examples:
   ttsc
   ttsc -p ./tsconfig.json
   ttsc --noEmit
-  ttsc transform --file=src/main.ts
   ttsc demo --type=number
 
 Integration guide (bundlers):
-  - vite / webpack / rollup / esbuild: shell out to "ttsc transform" per file,
-    forward stdout as the bundler transform result. A bundler adapter can wrap
-    this command without depending on the Go internals.
   - Next.js / Nuxt / Bun: "ttsc" in your pipeline replaces tsc and
     the rewritten .js feeds the runtime directly.
   - Monorepo / pnpm workspace: share one ttsc binary via a root script;

package/driver/program.go

@@ -30,6 +30,9 @@ type Diagnostic struct {
 	File     string
 	Line     int
 	Column   int
+	Code     int32
+	Start    *int
+	Length   *int
 	Message  string
 	Severity Severity
 	raw      *ast.Diagnostic
@@ -72,6 +75,7 @@ func NewLintDiagnostic(
 	}
 	lint := shimdiagnosticwriter.NewLintDiagnostic(file, pos, end, code, cat, message)
 	d := Diagnostic{
+		Code:     code,
 		Message:  message,
 		Severity: severity,
 		lint:     lint,
@@ -79,6 +83,9 @@ func NewLintDiagnostic(
 	if file != nil {
 		d.File = file.FileName()
 		if pos >= 0 {
+			length := end - pos
+			d.Start = &pos
+			d.Length = &length
 			line, col := shimscanner.GetECMALineAndByteOffsetOfPosition(file, pos)
 			d.Line = line + 1
 			d.Column = col + 1
@@ -187,8 +194,8 @@ type Program struct {
 }
 
 // LoadProgramOptions controls tsconfig overrides applied before tsgo creates
-// the program. `ForceEmit` is used by `ttsc --emit` and `ttsc transform`
-// so runtime compilation still works when the project defaults to `noEmit`.
+// the program. `ForceEmit` is used by `ttsc --emit` and runtime compilation
+// so execution still works when the project defaults to `noEmit`.
 type LoadProgramOptions struct {
 	ForceEmit   bool
 	ForceNoEmit bool
@@ -388,10 +395,13 @@ func convertDiagnostics(in []*ast.Diagnostic) []Diagnostic {
 		if d == nil {
 			continue
 		}
-		diag := Diagnostic{Message: d.String(), raw: d}
+		diag := Diagnostic{Code: d.Code(), Message: d.String(), raw: d}
 		if file := d.File(); file != nil {
 			diag.File = file.FileName()
 			if pos := d.Pos(); pos >= 0 {
+				length := d.Len()
+				diag.Start = &pos
+				diag.Length = &length
 				line, col := shimscanner.GetECMALineAndByteOffsetOfPosition(file, pos)
 				diag.Line = line + 1
 				diag.Column = col + 1

package/lib/TtscCompiler.d.ts

@@ -0,0 +1,96 @@
+import type { ITtscCompilerContext } from "./structures/ITtscCompilerContext";
+import type { ITtscCompilerResult } from "./structures/ITtscCompilerResult";
+import type { ITtscCompilerTransformation } from "./structures/ITtscCompilerTransformation";
+/**
+ * Programmatic compiler host for the `ttsc` TypeScript-Go pipeline.
+ *
+ * `TtscCompiler` is the root JavaScript API exported by the `ttsc` package.
+ * It represents one resolved project context: a working directory, an optional
+ * project config path, an optional native toolchain override, an environment,
+ * a cache root, and a plugin list. Those values are captured by the
+ * constructor and are intentionally not replaceable per method call.
+ *
+ * The class exposes only the operations that make sense for an embedded
+ * compiler host:
+ *
+ * - {@link TtscCompiler.prepare}: build configured Go source plugins into the
+ *   cache before a later compile.
+ * - {@link TtscCompiler.clean}: remove the cache owned by this compiler
+ *   context.
+ * - {@link TtscCompiler.compile}: compile the configured project and return a
+ *   structured result instead of terminal text.
+ * - {@link TtscCompiler.transform}: transform the configured project and
+ *   return an embed-style transformation result.
+ */
+export declare class TtscCompiler {
+    private readonly context;
+    constructor(context?: ITtscCompilerContext);
+    /**
+     * Build every configured source plugin into the instance cache.
+     *
+     * This method loads the project plugin descriptors, resolves their
+     * {@link ITtscPlugin.source} paths, and compiles those Go command packages
+     * into the ttsc cache. It is useful when a host application wants to pay the
+     * lazy build cost before the first compile call.
+     *
+     * `prepare()` is not a project check. It does not create a TypeScript-Go
+     * Program, does not run diagnostics, and does not emit output files.
+     *
+     * @returns Compiled native plugin binary paths.
+     */
+    prepare(): string[];
+    /**
+     * Remove compiled cache artifacts for this compiler instance.
+     *
+     * When the constructor received `cacheDir`, this method removes exactly that
+     * directory. Otherwise it removes the default ttsc cache locations for the
+     * resolved project root, plus the `TTSC_CACHE_DIR/plugins` cache when that
+     * environment variable is active.
+     *
+     * The cache target comes from the constructor context. Create another
+     * `TtscCompiler` instance to clean another project or another cache root.
+     *
+     * @returns Cache directories that were removed.
+     */
+    clean(): string[];
+    /**
+     * Compile the configured project.
+     *
+     * The public API does not write emitted files into the caller's project tree.
+     * For projects without plugins, ttsc uses its native TypeScript-Go host's
+     * `WriteFile` callback to capture output in memory. For projects with
+     * native plugins, ttsc runs the plugin pipeline against a temporary output
+     * directory, reads the generated text artifacts, and removes the temporary
+     * directory before returning.
+     *
+     * The result uses an `embed-typescript`-style discriminated union:
+     * `success` for clean compiles, `failure` for normal compiler diagnostics,
+     * and `exception` for host setup or process failures.
+     *
+     * @returns Structured compilation result containing diagnostics or output.
+     */
+    compile(): ITtscCompilerResult;
+    /**
+     * Transform the configured project and return TypeScript text by file path.
+     *
+     * This is the source-to-source API for plugin authors. It must not return
+     * JavaScript emit, declaration files, or source maps; those artifacts belong
+     * to {@link TtscCompiler.compile}. A transform sidecar is expected to write
+     * JSON shaped as `{ "typescript": { "src/file.ts": "..." } }` to stdout.
+     * When no transform sidecar is configured, ttsc returns the TypeScript files
+     * loaded by the TypeScript-Go Program together with normal diagnostics.
+     *
+     * The returned shape mirrors `embed-typescript`'s transformation API:
+     * `success` and `failure` carry a `typescript` map, while unexpected host
+     * errors return `exception`.
+     *
+     * @returns Transformation result containing TypeScript text or diagnostics.
+     */
+    transform(): ITtscCompilerTransformation;
+    private compilerContext;
+    private resolveProjectExecution;
+    private resolveCleanProjectRoot;
+    private resolveCwd;
+    private resolveCacheDir;
+    private resolvePluginCacheDir;
+}