ttsc 0.11.0-dev.20260518-2 → 0.12.0

package/README.md

@@ -1,12 +1,12 @@
 # `ttsc`
 
-![banner of ttsc](https://raw.githubusercontent.com/samchon/ttsc/refs/heads/master/assets/og.jpg)
+![banner of ttsc](https://ttsc.dev/og.jpg)
 
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/samchon/ttsc/blob/master/LICENSE)
 [![NPM Version](https://img.shields.io/npm/v/ttsc.svg)](https://www.npmjs.com/package/ttsc)
 [![NPM Downloads](https://img.shields.io/npm/dm/ttsc.svg)](https://www.npmjs.com/package/ttsc)
 [![Build Status](https://github.com/samchon/ttsc/workflows/test/badge.svg)](https://github.com/samchon/ttsc/actions?query=workflow%3Atest)
-[![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://github.com/samchon/ttsc/tree/master/docs)
+[![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://ttsc.dev/docs)
 [![Discord Badge](https://img.shields.io/badge/discord-samchon-d91965?style=flat&labelColor=5866f2&logo=discord&logoColor=white&link=https://discord.gg/E94XhzrUCZ)](https://discord.gg/E94XhzrUCZ)
 
 A `typescript-go` toolchain for compiler-powered plugins and type-safe execution.
@@ -15,17 +15,19 @@ A `typescript-go` toolchain for compiler-powered plugins and type-safe execution
 - **`ttsx`**: execute TypeScript with type checking.
   - native TypeScript-Go execution instead of transpile-only runners.
   - type checking that `tsx` does not provide.
+- **`@ttsc/lint`**: replaces `eslint` and `prettier`.
+  - lint violations as TS compile errors.
+  - format autofixes via `ttsc format`.
 - **plugin support**: compiler-powered libraries, such as `typia`.
-  - `@ttsc/lint`: lint violations as TS compile errors.
 
 ## Setup
 
 ### Install
 
-Install the native TypeScript preview package with `ttsc`:
+Install `ttsc`, `@ttsc/lint`, and the native TypeScript preview package:
 
 ```bash
-npm install -D ttsc @typescript/native-preview
+npm install -D ttsc @ttsc/lint @typescript/native-preview
 ```
 
 ### Commands
@@ -44,6 +46,23 @@ npx ttsc --noEmit
 npx ttsc --watch
 ```
 
+Rewrite source files in place with the `@ttsc/lint` format rules:
+
+```bash
+npx ttsc format
+```
+
+### Editor
+
+Install the VS Code extension to see lint and plugin diagnostics live as you type:
+
+```bash
+npm install -D @ttsc/vscode
+npx ttsc-vscode
+```
+
+See [`@ttsc/vscode`](https://github.com/samchon/ttsc/tree/master/packages/vscode) for requirements, settings, and uninstall.
+
 ### Bundlers
 
 Use `@ttsc/unplugin` when a bundler owns your build.
@@ -51,7 +70,7 @@ Use `@ttsc/unplugin` when a bundler owns your build.
 It runs `ttsc` plugins inside supported bundlers.
 
 ```bash
-npm install -D ttsc @typescript/native-preview
+npm install -D ttsc @ttsc/lint @typescript/native-preview
 npm install -D @ttsc/unplugin
 ```
 
@@ -150,12 +169,12 @@ console.log(matched); // true
 `ttsc` ships a few small utility plugins in this repository.
 
 - [`@ttsc/banner`](https://github.com/samchon/ttsc/tree/master/packages/banner): adds `@packageDocumentation` JSDoc banners.
-- [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): reports lint violations as TypeScript compile errors.
+- [`@ttsc/lint`](https://github.com/samchon/ttsc/tree/master/packages/lint): lints and formats TypeScript source.
 - [`@ttsc/paths`](https://github.com/samchon/ttsc/tree/master/packages/paths): rewrites source path aliases so JS and declaration emit receive relative imports.
 - [`@ttsc/strip`](https://github.com/samchon/ttsc/tree/master/packages/strip): removes configured calls and `debugger` statements.
 - [`@ttsc/unplugin`](https://github.com/samchon/ttsc/tree/master/packages/unplugin): runs `ttsc` plugins inside bundlers supported by `unplugin`.
 
-Plugin authors should start from the [`Guide Documents`](https://github.com/samchon/ttsc/tree/master/docs).
+Plugin authors should start from the [`Guide Documents`](https://ttsc.dev/docs).
 
 Ecosystem plugins are listed below; PRs adding `ttsc` plugins are welcome.
 

package/cmd/ttsc/api_compile.go

@@ -7,25 +7,24 @@
 package main
 
 import (
-  "encoding/json"
-  "flag"
-  "fmt"
-  "os"
-  "path/filepath"
-  "strings"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"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"
-  cwdutil "github.com/samchon/ttsc/packages/ttsc/internal/cwd"
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+	cwdutil "github.com/samchon/ttsc/packages/ttsc/internal/cwd"
 )
 
 type apiCompileResult struct {
-  // 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"`
+	// 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.
@@ -33,113 +32,109 @@ type apiCompileResult struct {
 // `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, err := cwdutil.Resolve(*cwdOverride, os.Getwd)
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
-    return 2
-  }
+	cwd, err := cwdutil.Resolve(*cwdOverride, getwd)
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc: %v\n", err)
+		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()
-    // 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...)
-  }
+	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, _ := json.Marshal(result)
+	fmt.Fprintln(stdout, string(data))
+	if driver.CountErrors(diags) > 0 {
+		return 2
+	}
+	return 0
 }
 
 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 {
-  // 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 && !isOutsideRelativePath(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 && !isOutsideRelativePath(rel) {
+		return filepath.ToSlash(rel)
+	}
+	return filepath.ToSlash(fileName)
 }
 
 func isOutsideRelativePath(rel string) bool {
-  return rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator))
+	return rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator))
 }

package/cmd/ttsc/api_compile_branches_test.go

@@ -0,0 +1,81 @@
+package main
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+type apiCompileApplyErrorPlugin struct{}
+
+func (apiCompileApplyErrorPlugin) ApplyProgram(*driver.Program, driver.PluginContext) error {
+	return errors.New("api compile apply boom")
+}
+
+/**
+ * Verifies api-compile handles parse, cwd, diagnostic, and emit failures.
+ *
+ * The JSON API path is used by the JS wrapper, so its command entrypoint must
+ * return stable status codes for wrapper misuse, project diagnostics, and
+ * linked transform failures.
+ *
+ * 1. Exercise bad flags and a failing cwd resolver.
+ * 2. Compile missing and type-invalid projects.
+ * 3. Assert linked ApplyProgram errors surface through the emit branch.
+ */
+func TestAPICompileBranches(t *testing.T) {
+	code, _, _ := captureCommand(t, func() int {
+		return runAPICompile([]string{"--cwd"})
+	})
+	if code != 2 {
+		t.Fatalf("bad flag status mismatch: %d", code)
+	}
+
+	code, _, errText := captureCommand(t, func() int {
+		getwd = failGetwd
+		return runAPICompile(nil)
+	})
+	if code != 2 || !strings.Contains(errText, "cwd boom") {
+		t.Fatalf("cwd error mismatch: code=%d stderr=%q", code, errText)
+	}
+
+	root := t.TempDir()
+	code, _, errText = captureCommand(t, func() int {
+		return runAPICompile([]string{"--cwd", root, "--tsconfig", "missing.json"})
+	})
+	if code != 2 || !strings.Contains(errText, "tsconfig not found") {
+		t.Fatalf("missing config mismatch: code=%d stderr=%q", code, errText)
+	}
+
+	writeCommandProjectFile(t, root, "tsconfig.json", `{
+  "compilerOptions": { "module": "commonjs", "target": "es2020", "strict": true },
+  "files": ["index.ts"]
+}
+`)
+	writeCommandProjectFile(t, root, "index.ts", `const value: number = "text";
+export { value };
+`)
+	code, out, _ := captureCommand(t, func() int {
+		return runAPICompile([]string{"--cwd", root, "--tsconfig", "tsconfig.json"})
+	})
+	if code != 2 || !strings.Contains(out, `"diagnostics"`) {
+		t.Fatalf("diagnostic compile mismatch: code=%d stdout=%q", code, out)
+	}
+	if got := toAPICompileDiagnostic(driver.Diagnostic{Severity: driver.SeverityWarning}).Category; got != "warning" {
+		t.Fatalf("warning category mismatch: %q", got)
+	}
+
+	resetCommandLinkedPluginRegistry()
+	driver.RegisterPlugin(apiCompileApplyErrorPlugin{})
+	t.Setenv(driver.LinkedPluginsEnv, `[{"name":"error","stage":"transform","config":{}}]`)
+	writeCommandProjectFile(t, root, "index.ts", `export const value = 1;
+`)
+	code, _, errText = captureCommand(t, func() int {
+		return runAPICompile([]string{"--cwd", root, "--tsconfig", "tsconfig.json"})
+	})
+	if code != 3 || !strings.Contains(errText, "api compile apply boom") {
+		t.Fatalf("emit error mismatch: code=%d stderr=%q", code, errText)
+	}
+}

package/cmd/ttsc/api_transform.go

@@ -7,69 +7,64 @@
 package main
 
 import (
-  "encoding/json"
-  "flag"
-  "fmt"
-  "os"
+	"encoding/json"
+	"flag"
+	"fmt"
 
-  "github.com/samchon/ttsc/packages/ttsc/driver"
-  cwdutil "github.com/samchon/ttsc/packages/ttsc/internal/cwd"
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+	cwdutil "github.com/samchon/ttsc/packages/ttsc/internal/cwd"
 )
 
 type apiTransformResult struct {
-  // 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"`
+	// 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, err := cwdutil.Resolve(*cwdOverride, os.Getwd)
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
-    return 2
-  }
+	cwd, err := cwdutil.Resolve(*cwdOverride, getwd)
+	if err != nil {
+		fmt.Fprintf(stderr, "ttsc: %v\n", err)
+		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, _ := json.Marshal(result)
+	fmt.Fprintln(stdout, string(data))
+	if driver.CountErrors(diags) > 0 {
+		return 2
+	}
+	return 0
 }

package/cmd/ttsc/api_transform_branches_test.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+/**
+ * Verifies api-transform rejects invalid command and project setup.
+ *
+ * Source-to-source API callers need the same stable wrapper diagnostics as the
+ * compile API, but without touching emit. These branches are command-frontdoor
+ * behavior rather than TypeScript-Go internals.
+ *
+ * 1. Pass an incomplete flag.
+ * 2. Force cwd resolution to fail.
+ * 3. Point the API at a missing tsconfig.
+ */
+func TestAPITransformBranches(t *testing.T) {
+	code, _, _ := captureCommand(t, func() int {
+		return runAPITransform([]string{"--cwd"})
+	})
+	if code != 2 {
+		t.Fatalf("bad flag status mismatch: %d", code)
+	}
+
+	code, _, errText := captureCommand(t, func() int {
+		getwd = failGetwd
+		return runAPITransform(nil)
+	})
+	if code != 2 || !strings.Contains(errText, "cwd boom") {
+		t.Fatalf("cwd error mismatch: code=%d stderr=%q", code, errText)
+	}
+
+	code, _, errText = captureCommand(t, func() int {
+		return runAPITransform([]string{"--cwd", t.TempDir(), "--tsconfig", "missing.json"})
+	})
+	if code != 2 || !strings.Contains(errText, "tsconfig not found") {
+		t.Fatalf("missing config mismatch: code=%d stderr=%q", code, errText)
+	}
+}