ttsc 0.7.2 → 0.8.0-dev.20260505

package/README.md

@@ -16,8 +16,7 @@ A `typescript-go` toolchain for compiler-powered transforms and type-safe execut
   - 10x faster than `ts-node`.
   - type checking that `tsx` does not provide.
 - **transformer support**: compiler-powered libraries, such as `typia`.
-
-> `ttsx` (CLI command) can run existing `typescript@6` projects.
+  - `@ttsc/lint`: lint violations as TS compile errors.
 
 ## Setup
 
@@ -41,9 +40,10 @@ npx ttsc --noEmit
 npx ttsc --watch
 ```
 
-Clear cached transformer binaries when developing or debugging a plugin:
+Prebuild or clear cached source-plugin binaries:
 
 ```bash
+npx ttsc prepare
 npx ttsc clean
 ```
 
@@ -141,9 +141,9 @@ It is transformed into dedicated JavaScript:
 
 `ttsc` ships a few small utility plugins in this repository.
 
-- [`@ttsc/banner`](https://github.com/samchon/ttsc/tree/master/packages/banner): adds banner comments to emitted JS and declarations.
+- [`@ttsc/banner`](https://github.com/samchon/ttsc/tree/master/packages/banner): adds `@packageDocumentation` JSDoc banners to JS and declaration emit.
 - [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): type-check + lint in one compile pass, ~20x faster than `eslint` in theory.
-- [`@ttsc/paths`](https://github.com/samchon/ttsc/tree/master/packages/paths): rewrites path aliases in emitted imports.
+- [`@ttsc/paths`](https://github.com/samchon/ttsc/tree/master/packages/paths): rewrites path aliases in JS and declaration imports.
 - [`@ttsc/strip`](https://github.com/samchon/ttsc/tree/master/packages/strip): removes configured calls and `debugger` statements.
 
 Plugin authors should start from the [`Guide Documents`](https://github.com/samchon/ttsc/tree/master/docs).

package/cmd/platform/main.go

@@ -1,73 +1,83 @@
+// Platform helper binary shipped by the per-OS `ttsc-*` packages.
+//
+// The real compiler and runner commands live in the JavaScript launchers so
+// they can resolve the consuming project's `@typescript/native-preview` and
+// plugin descriptors. This binary only supplies version/platform metadata and
+// a tiny demo command for package smoke tests.
 package main
 
 import (
-	"flag"
-	"fmt"
-	"io"
-	"os"
-	"runtime"
-	"strings"
+  "flag"
+  "fmt"
+  "io"
+  "os"
+  "runtime"
+  "strings"
 )
 
 var (
-	version = "0.0.0-dev"
-	commit  = "dev"
-	date    = "unknown"
+  // These values are overwritten by release builds through -ldflags. The
+  // defaults keep local `go run` and fixture builds deterministic.
+  version = "0.0.0-dev"
+  commit  = "dev"
+  date    = "unknown"
 )
 
 var (
-	stdout io.Writer = os.Stdout
-	stderr io.Writer = os.Stderr
+  // Package-level writers keep CLI tests simple and avoid global os.Stdout /
+  // os.Stderr patching.
+  stdout io.Writer = os.Stdout
+  stderr io.Writer = os.Stderr
 )
 
 func main() {
-	os.Exit(run(os.Args[1:]))
+  os.Exit(run(os.Args[1:]))
 }
 
 func run(args []string) int {
-	if len(args) == 0 {
-		printHelp(stdout)
-		return 0
-	}
+  if len(args) == 0 {
+    printHelp(stdout)
+    return 0
+  }
 
-	switch args[0] {
-	case "-h", "--help", "help":
-		printHelp(stdout)
-		return 0
-	case "-v", "--version", "version":
-		printVersion(stdout)
-		return 0
-	case "demo":
-		return runDemo(args[1:])
-	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",
-			args[0],
-		)
-		return 2
-	default:
-		fmt.Fprintf(stderr, "ttsc platform helper: unknown command %q\n", args[0])
-		fmt.Fprintln(stderr, `ttsc platform helper: run "ttsc --help" through the JavaScript CLI for compiler usage.`)
-		return 2
-	}
+  switch args[0] {
+  case "-h", "--help", "help":
+    printHelp(stdout)
+    return 0
+  case "-v", "--version", "version":
+    printVersion(stdout)
+    return 0
+  case "demo":
+    return runDemo(args[1:])
+  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",
+      args[0],
+    )
+    return 2
+  default:
+    fmt.Fprintf(stderr, "ttsc platform helper: unknown command %q\n", args[0])
+    fmt.Fprintln(stderr, `ttsc platform helper: run "ttsc --help" through the JavaScript CLI for compiler usage.`)
+    return 2
+  }
 }
 
 func printVersion(w io.Writer) {
-	fmt.Fprintf(
-		w,
-		"ttsc platform helper %s (commit %s, built %s, %s/%s, go %s)\n",
-		version,
-		commit,
-		date,
-		runtime.GOOS,
-		runtime.GOARCH,
-		runtime.Version(),
-	)
+  fmt.Fprintf(
+    w,
+    "ttsc platform helper %s (commit %s, built %s, %s/%s, go %s)\n",
+    version,
+    commit,
+    date,
+    runtime.GOOS,
+    runtime.GOARCH,
+    runtime.Version(),
+  )
 }
 
 func printHelp(w io.Writer) {
-	fmt.Fprintln(w, strings.TrimSpace(`
+  fmt.Fprintln(w, strings.TrimSpace(`
 ttsc platform helper.
 
 This binary is a small compatibility helper shipped by @ttsc platform packages.
@@ -82,37 +92,37 @@ Usage:
 }
 
 func runDemo(args []string) int {
-	fs := flag.NewFlagSet("demo", flag.ContinueOnError)
-	fs.SetOutput(stderr)
-	typ := fs.String("type", "string", "atomic type to simulate")
-	if err := fs.Parse(args); err != nil {
-		return 2
-	}
+  fs := flag.NewFlagSet("demo", flag.ContinueOnError)
+  fs.SetOutput(stderr)
+  typ := fs.String("type", "string", "atomic type to simulate")
+  if err := fs.Parse(args); err != nil {
+    return 2
+  }
 
-	arrow, err := demoArrow(*typ)
-	if err != nil {
-		fmt.Fprintf(stderr, "ttsc platform helper demo: %v\n", err)
-		return 2
-	}
+  arrow, err := demoArrow(*typ)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc platform helper demo: %v\n", err)
+    return 2
+  }
 
-	fmt.Fprintf(stdout, "// demo<%s> -> emitted by ttsc platform helper %s\n", *typ, version)
-	fmt.Fprintln(stdout, arrow)
-	return 0
+  fmt.Fprintf(stdout, "// demo<%s> -> emitted by ttsc platform helper %s\n", *typ, version)
+  fmt.Fprintln(stdout, arrow)
+  return 0
 }
 
 func demoArrow(name string) (string, error) {
-	switch strings.ToLower(name) {
-	case "any":
-		return "(input) => true", nil
-	case "boolean":
-		return `(input) => "boolean" === typeof input`, nil
-	case "number":
-		return `(input) => "number" === typeof input`, nil
-	case "bigint":
-		return `(input) => "bigint" === typeof input`, nil
-	case "string", "":
-		return `(input) => "string" === typeof input`, nil
-	default:
-		return "", fmt.Errorf("unknown --type value %q (want: string|number|boolean|bigint|any)", name)
-	}
+  switch strings.ToLower(name) {
+  case "any":
+    return "(input) => true", nil
+  case "boolean":
+    return `(input) => "boolean" === typeof input`, nil
+  case "number":
+    return `(input) => "number" === typeof input`, nil
+  case "bigint":
+    return `(input) => "bigint" === typeof input`, nil
+  case "string", "":
+    return `(input) => "string" === typeof input`, nil
+  default:
+    return "", fmt.Errorf("unknown --type value %q (want: string|number|boolean|bigint|any)", name)
+  }
 }

package/cmd/ttsc/api_compile.go

@@ -1,134 +1,151 @@
+// JSON API adapter for in-process-style project compilation.
+//
+// `api-compile` is consumed by the TypeScript wrapper when it needs a stable,
+// machine-readable result from the native compiler host. The command always
+// emits into memory and serializes diagnostics plus output text; it never
+// writes generated files into the caller's project tree.
 package main
 
 import (
-	"encoding/json"
-	"flag"
-	"fmt"
-	"os"
-	"path/filepath"
-	"strings"
+  "encoding/json"
+  "flag"
+  "fmt"
+  "os"
+  "path/filepath"
+  "strings"
 
-	shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
+  shimcompiler "github.com/microsoft/typescript-go/shim/compiler"
 
-	"github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
 type apiCompileResult struct {
-	Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
-	Output      map[string]string      `json:"output"`
+  // Diagnostics is omitted only when the compiler produced no diagnostics.
+  // Output is still returned in diagnostic cases because TypeScript-Go may
+  // produce partial emit text before a build-failing error is reported.
+  Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
+  Output      map[string]string      `json:"output"`
 }
 
+// apiCompileDiagnostic mirrors the public TypeScript-side diagnostic DTO.
+// The JSON keys intentionally use TypeScript naming (`messageText`,
+// `character`) instead of Go naming so callers can pass the data through
+// without remapping.
 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"`
+  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
-	}
+  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
-	}
+  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()...)
-	}
+  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...)
-	}
+  output := map[string]string{}
+  if prog != nil {
+    rewrites := driver.NewRewriteSet()
+    // Capture WriteFile output in a map keyed by project-relative paths. This
+    // gives the JS API a deterministic object and avoids touching outDir.
+    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))
-	}
+  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
+  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
+  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,
-	}
+  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)
+  // Relative keys are the API contract for files inside the project. Absolute
+  // keys are preserved for uncommon compiler outputs outside cwd.
+  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

@@ -1,64 +1,72 @@
+// JSON API adapter for source-level transformation results.
+//
+// `api-transform` returns the TypeScript source files that TypeScript-Go
+// parsed for the owning project. It is the no-emit companion to api-compile:
+// diagnostics are still collected, but the result surface is TypeScript text
+// rather than emitted JavaScript.
 package main
 
 import (
-	"encoding/json"
-	"flag"
-	"fmt"
+  "encoding/json"
+  "flag"
+  "fmt"
 
-	"github.com/samchon/ttsc/packages/ttsc/driver"
+  "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
 type apiTransformResult struct {
-	Diagnostics []apiCompileDiagnostic `json:"diagnostics,omitempty"`
-	TypeScript  map[string]string      `json:"typescript"`
+  // TypeScript contains every non-library source file visible through the
+  // Program facade, keyed the same way api-compile keys emitted files.
+  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
-	}
+  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
-	}
+  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()...)
-	}
+  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))
-	}
+  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
+  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
 }