ttsc 0.8.1 → 0.10.0

package/README.md

@@ -9,13 +9,13 @@
 [![Guide Documents](https://img.shields.io/badge/Guide-Documents-forestgreen)](https://github.com/samchon/ttsc/tree/master/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 transforms and type-safe execution.
+A `typescript-go` toolchain for compiler-powered plugins and type-safe execution.
 
 - **`ttsc`**: build, check, and transform.
 - **`ttsx`**: execute TypeScript with type checking.
-  - 10x faster than `ts-node`.
+  - native TypeScript-Go execution instead of transpile-only runners.
   - type checking that `tsx` does not provide.
-- **transformer support**: compiler-powered libraries, such as `typia`.
+- **plugin support**: compiler-powered libraries, such as `typia`.
   - `@ttsc/lint`: lint violations as TS compile errors.
 
 ## Setup
@@ -25,7 +25,7 @@ A `typescript-go` toolchain for compiler-powered transforms and type-safe execut
 Install the native TypeScript preview package with `ttsc`:
 
 ```bash
-npm i -D ttsc @typescript/native-preview
+npm install -D ttsc @typescript/native-preview
 ```
 
 ### Commands
@@ -48,11 +48,11 @@ npx ttsc --watch
 
 Use `@ttsc/unplugin` when a bundler owns your build.
 
-It runs the same `compilerOptions.plugins` that `ttsc` and `ttsx` use.
+It runs `ttsc` plugins inside supported bundlers.
 
 ```bash
-npm i -D ttsc @typescript/native-preview
-npm i -D @ttsc/unplugin
+npm install -D ttsc @typescript/native-preview
+npm install -D @ttsc/unplugin
 ```
 
 Minimal Vite setup:
@@ -83,30 +83,7 @@ See [`@ttsc/unplugin`](https://github.com/samchon/ttsc/tree/master/packages/unpl
 
 ## Plugins
 
-### Configuration
-
-Add plugin entries under `compilerOptions.plugins` in your `tsconfig.json`.
-
-```json
-{
-  "compilerOptions": {
-    "plugins": [
-      {
-        "transform": "@ttsc/lint",
-        "config": {
-          "no-var": "error",
-          "no-explicit-any": "warning",
-          "no-non-null-assertion": "off"
-        }
-      },
-      { "transform": "@ttsc/paths" },
-      { "transform": "typia/lib/transform" }
-    ]
-  }
-}
-```
-
-The same configuration is used by both `ttsc` and `ttsx` commands.
+Plugins let libraries add compile-time checks, transforms, and type-driven code generation to normal `ttsc` and `ttsx` runs.
 
 ```bash
 # compile
@@ -116,9 +93,7 @@ npx ttsc
 npx ttsx src/index.ts
 ```
 
-This gives compiler-powered libraries one transform path for both build-time and runtime execution.
-
-### What Is a Transform?
+### Transform Example
 
 A transform uses TypeScript types to generate JavaScript before runtime.
 
@@ -143,52 +118,48 @@ interface IMember {
 }
 ```
 
-It is transformed into dedicated JavaScript:
-
-> ```js
-> import typia from "typia";
-> import * as __typia_transform__isFormatEmail from "typia/lib/internal/_isFormatEmail";
-> import * as __typia_transform__isFormatUuid from "typia/lib/internal/_isFormatUuid";
-> import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32";
-> import { v4 } from "uuid";
->
-> const matched = (() => {
->   const _io0 = (input) =>
->     "string" === typeof input.id &&
->     __typia_transform__isFormatUuid._isFormatUuid(input.id) &&
->     "string" === typeof input.email &&
->     __typia_transform__isFormatEmail._isFormatEmail(input.email) &&
->     "number" === typeof input.age &&
->     __typia_transform__isTypeUint32._isTypeUint32(input.age) &&
->     19 < input.age &&
->     input.age <= 100;
->   return (input) =>
->     "object" === typeof input && null !== input && _io0(input);
-> })()({
->   id: v4(),
->   email: "samchon.github@gmail.com",
->   age: 30,
-> });
-> console.log(matched); // true
-> ```
-
-`ttsc` applies this transform at build time; `ttsx` applies the same transform when running the file.
+The transform replaces `typia.is<IMember>()` with dedicated JavaScript checks at build time:
+
+```js
+import * as __typia_transform__isFormatUuid from "typia/lib/internal/_isFormatUuid";
+import * as __typia_transform__isFormatEmail from "typia/lib/internal/_isFormatEmail";
+import * as __typia_transform__isTypeUint32 from "typia/lib/internal/_isTypeUint32";
+import typia from "typia";
+import { v4 } from "uuid";
+const matched = (() => {
+  const _io0 = (input) =>
+    "string" === typeof input.id &&
+    __typia_transform__isFormatUuid._isFormatUuid(input.id) &&
+    "string" === typeof input.email &&
+    __typia_transform__isFormatEmail._isFormatEmail(input.email) &&
+    "number" === typeof input.age &&
+    __typia_transform__isTypeUint32._isTypeUint32(input.age) &&
+    19 < input.age &&
+    input.age <= 100;
+  return (input) => "object" === typeof input && null !== input && _io0(input);
+})()({
+  id: v4(),
+  email: "samchon.github@gmail.com",
+  age: 30,
+});
+console.log(matched); // true
+```
 
 ### List of Plugins
 
 `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 through source preamble insertion.
-- [`@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/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/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 configured `ttsc` source transforms inside bundlers supported by `unplugin`.
+- [`@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).
 
 Ecosystem plugins are listed below; PRs adding `ttsc` plugins are welcome.
 
-- [`@nestia/core`](https://github.com/samchon/nestia): generates NestJS routes, OpenAPI, and SDKs.
+- [`nestia`](https://github.com/samchon/nestia): generates NestJS routes, OpenAPI, and SDKs.
 - [`typia`](https://github.com/samchon/typia): generates validators, serializers, and type-driven runtime code.
 
 ## References

package/cmd/ttsc/api_compile.go

@@ -7,24 +7,25 @@
 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"
+	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.
@@ -32,120 +33,113 @@ 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, ok := resolveBuildCwd(*cwdOverride)
-  if !ok {
-    return 2
-  }
+	cwd, err := cwdutil.Resolve(*cwdOverride, os.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
-}
-
-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
+	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 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 && !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 && !isOutsideRelativePath(rel) {
+		return filepath.ToSlash(rel)
+	}
+	return filepath.ToSlash(fileName)
+}
+
+func isOutsideRelativePath(rel string) bool {
+	return rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator))
 }

package/cmd/ttsc/api_transform.go

@@ -7,66 +7,69 @@
 package main
 
 import (
-  "encoding/json"
-  "flag"
-  "fmt"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
 
-  "github.com/samchon/ttsc/packages/ttsc/driver"
+	"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, ok := resolveBuildCwd(*cwdOverride)
-  if !ok {
-    return 2
-  }
+	cwd, err := cwdutil.Resolve(*cwdOverride, os.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, 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
 }