ttsc 0.13.1 → 0.14.0-dev.20260528.1

package/README.md

@@ -57,7 +57,8 @@ npx ttsc format
 
 ### Editor
 
-Install the VS Code extension to see lint and plugin diagnostics live as you type:
+Install the VS Code extension for live TypeScript-Go editor features plus
+saved-state ttsc plugin diagnostics and actions:
 
 ```bash
 npm install -D @ttsc/vscode
@@ -143,11 +144,12 @@ interface IMember {
 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 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 typia from "typia";
 import { v4 } from "uuid";
+
 const matched = (() => {
   const _io0 = (input) =>
     "string" === typeof input.id &&
@@ -167,6 +169,34 @@ const matched = (() => {
 console.log(matched); // true
 ```
 
+## Programmatic API
+
+Embed `ttsc` from another Node tool with the `TtscCompiler` class:
+
+```ts
+import { TtscCompiler } from "ttsc";
+
+const compiler = new TtscCompiler({ cwd: "./project" });
+const result = compiler.compile();
+
+if (result.type === "success") {
+  for (const [path, text] of Object.entries(result.output)) {
+    // path is project-relative ("dist/index.js", "dist/index.d.ts", ...)
+    console.log(path, text.length);
+  }
+} else if (result.type === "failure") {
+  for (const d of result.diagnostics) {
+    console.error(`${d.file}:${d.line}:${d.character} ${d.messageText}`);
+  }
+}
+```
+
+See the [Programmatic API guide](https://ttsc.dev/docs/ttsc/api) for the full
+lifecycle, plugin overrides, and patterns. For browser embedding, see
+[`@ttsc/wasm`](https://github.com/samchon/ttsc/tree/master/packages/wasm) and
+the higher-level [`@ttsc/playground`](https://github.com/samchon/ttsc/tree/master/packages/playground)
+package.
+
 ### List of Plugins
 
 `ttsc` ships a few small utility plugins in this repository.

package/cmd/ttscserver/main.go

@@ -1,7 +1,8 @@
 // Command ttscserver is the Go LSP host shipped by ttsc. It wraps the
 // project-selected TypeScript-Go LSP server process and proxies traffic
-// between the editor and that server, splicing ttsc-plugin diagnostics,
-// code actions, and ttsc-owned executeCommand handling into the same stream.
+// between the editor and that server. The JavaScript launcher resolves project
+// plugins first and passes an LSP manifest so this command can merge plugin
+// diagnostics, code actions, and ttsc-owned executeCommand handling.
 //
 // The JavaScript launcher (`packages/ttsc/src/launcher/ttscserver.ts`)
 // resolves the native binary and forwards stdio so editors can spawn
@@ -86,8 +87,13 @@ func runLSP(args []string) int {
   fs.SetOutput(stderr)
   stdioFlag := fs.Bool("stdio", false, "communicate with the editor over stdin/stdout")
   cwdFlag := fs.String("cwd", "", "project root (defaults to process cwd)")
+  tsconfigFlag := fs.String("tsconfig", "tsconfig.json", "project tsconfig path")
   tsgoFlag := fs.String("tsgo", "", "absolute tsgo binary path (defaults to TTSC_TSGO_BINARY)")
-  progressDelayFlag := fs.Duration("progress-delay", 250*time.Millisecond, "delay before showing tsgo's progress UI")
+  progressDelayFlag := fs.Duration("progress-delay", 250*time.Millisecond, "accepted for compatibility; ignored by the external tsgo LSP process")
+  suppressExecuteCommandProviderFlag := fs.Bool("suppress-execute-command-provider", false, "do not advertise ttsc executeCommand ids during initialize")
+  suppressExecuteCommandIDsFlag := fs.String("suppress-execute-command-ids", "", "comma-separated ttsc executeCommand ids to omit during initialize")
+  executeCommandIDPrefixFlag := fs.String("execute-command-id-prefix", "", "prefix to apply to advertised executeCommand ids")
+  _ = fs.String("clientProcessId", "", "ignored VSCode language-client compatibility flag")
   if err := fs.Parse(args); err != nil {
     return 2
   }
@@ -114,14 +120,28 @@ func runLSP(args []string) int {
     tsgoBinary = strings.TrimSpace(os.Getenv("TTSC_TSGO_BINARY"))
   }
 
-  err := runLSPServer(ctx, lspserver.LSPServerOptions{
-    In:            stdin,
-    Out:           stdout,
-    Err:           stderr,
-    Cwd:           cwd,
-    TsgoBinary:    tsgoBinary,
-    Source:        lspserver.NullPluginSource{},
-    ProgressDelay: *progressDelayFlag,
+  source, err := lspserver.NewNativePluginSource(lspserver.NativePluginSourceOptions{
+    Cwd:          cwd,
+    Err:          stderr,
+    ManifestJSON: os.Getenv("TTSC_LSP_PLUGINS_JSON"),
+    Tsconfig:     strings.TrimSpace(*tsconfigFlag),
+  })
+  if err != nil {
+    fmt.Fprintf(stderr, "ttscserver: %v\n", err)
+    return 2
+  }
+
+  err = runLSPServer(ctx, lspserver.LSPServerOptions{
+    In:                             stdin,
+    Out:                            stdout,
+    Err:                            stderr,
+    Cwd:                            cwd,
+    TsgoBinary:                     tsgoBinary,
+    Source:                         source,
+    SuppressExecuteCommandProvider: *suppressExecuteCommandProviderFlag,
+    SuppressedExecuteCommandIDs:    splitCSV(*suppressExecuteCommandIDsFlag),
+    ExecuteCommandIDPrefix:         strings.TrimSpace(*executeCommandIDPrefixFlag),
+    ProgressDelay:                  *progressDelayFlag,
   })
   if err != nil && !errors.Is(err, context.Canceled) {
     fmt.Fprintf(stderr, "ttscserver: %v\n", err)
@@ -155,14 +175,36 @@ Usage:
 Options:
   --stdio              Communicate with the editor over stdin/stdout.
   --cwd <dir>          Project root used as the tsgo server working directory.
+  --tsconfig <path>    Project config path used by ttsc plugin sidecars.
   --tsgo <path>        Absolute tsgo binary path (defaults to TTSC_TSGO_BINARY).
-  --progress-delay D   Accepted for compatibility; tsgo currently owns this value.
+  --suppress-execute-command-provider
+                       Do not advertise ttsc executeCommand ids during initialize.
+  --suppress-execute-command-ids <ids>
+                       Comma-separated executeCommand ids to omit during initialize.
+  --execute-command-id-prefix <prefix>
+                       Prefix advertised executeCommand ids for multi-client hosts.
+  --progress-delay D   Accepted for compatibility; currently ignored by the external tsgo LSP process.
 
 Typical embedding:
   Editors spawn ttscserver via the JavaScript launcher (resolves the
   per-platform native binary and passes the project tsgo path) and exchange
   LSP messages over stdio. The upstream tsgo server provides hover,
-  completion, definitions, and diagnostics; ttsc merges plugin diagnostics,
-  code actions, and ttsc-owned executeCommand handlers into the same stream.
+  completion, definitions, and diagnostics. LSP-capable ttsc sidecars are
+  discovered by the JavaScript launcher and merged into the same stream.
 `))
 }
+
+func splitCSV(value string) []string {
+  if value == "" {
+    return nil
+  }
+  fields := strings.Split(value, ",")
+  out := make([]string, 0, len(fields))
+  for _, field := range fields {
+    trimmed := strings.TrimSpace(field)
+    if trimmed != "" {
+      out = append(out, trimmed)
+    }
+  }
+  return out
+}

package/cmd/ttscserver/run_lsp_forwards_execute_command_advertisement_flags_test.go

@@ -0,0 +1,55 @@
+package main
+
+import (
+  "bytes"
+  "context"
+  "reflect"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+)
+
+// TestRunLSPForwardsExecuteCommandAdvertisementFlags verifies the native
+// command passes executeCommand registration controls into the LSP host.
+//
+// The VS Code extension relies on these flags to suppress wrapper-owned command
+// ids and namespace custom plugin commands per project root. Parsing the flags
+// in the command is not enough; this pins the handoff into LSPServerOptions.
+//
+// 1. Substitute the runLSPServer seam and capture its options.
+// 2. Run runLSP with suppression and prefix flags.
+// 3. Assert the captured LSPServerOptions carry the parsed values.
+func TestRunLSPForwardsExecuteCommandAdvertisementFlags(t *testing.T) {
+  prev := runLSPServer
+  var captured lspserver.LSPServerOptions
+  runLSPServer = func(_ context.Context, opts lspserver.LSPServerOptions) error {
+    captured = opts
+    return nil
+  }
+  defer func() { runLSPServer = prev }()
+
+  outBuf := &bytes.Buffer{}
+  errBuf := &bytes.Buffer{}
+  withIO(t, outBuf, errBuf, nil, func() {
+    if code := runLSP([]string{
+      "--stdio",
+      "--cwd", t.TempDir(),
+      "--suppress-execute-command-provider",
+      "--suppress-execute-command-ids", " ttsc.lint.fixAll, ttsc.format.document ,, ",
+      "--execute-command-id-prefix", " ttsc.vscode.root. ",
+    }); code != 0 {
+      t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
+    }
+  })
+
+  if !captured.SuppressExecuteCommandProvider {
+    t.Fatal("expected SuppressExecuteCommandProvider to be true")
+  }
+  expectedIDs := []string{"ttsc.lint.fixAll", "ttsc.format.document"}
+  if !reflect.DeepEqual(captured.SuppressedExecuteCommandIDs, expectedIDs) {
+    t.Fatalf("expected suppressed ids %#v, got %#v", expectedIDs, captured.SuppressedExecuteCommandIDs)
+  }
+  if captured.ExecuteCommandIDPrefix != "ttsc.vscode.root." {
+    t.Fatalf("expected trimmed execute command prefix, got %q", captured.ExecuteCommandIDPrefix)
+  }
+}

package/cmd/ttscserver/run_lsp_uses_native_plugin_manifest_source_test.go

@@ -0,0 +1,45 @@
+package main
+
+import (
+  "bytes"
+  "context"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+)
+
+// TestRunLSPUsesNativePluginManifestSource verifies the command wires the
+// launcher-provided plugin manifest into the proxy source.
+//
+// A previous implementation always passed NullPluginSource, so editor sessions
+// could never receive ttsc plugin diagnostics or commands. This test pins the
+// command-level seam without starting tsgo: the JavaScript launcher owns plugin
+// discovery, and the Go command must turn its manifest into a NativePluginSource.
+//
+// 1. Set TTSC_LSP_PLUGINS_JSON to an empty but valid manifest.
+// 2. Substitute runLSPServer and capture its LSPServerOptions.
+// 3. Run `ttscserver --stdio` against a temp cwd.
+// 4. Assert Source is the native sidecar-backed implementation.
+func TestRunLSPUsesNativePluginManifestSource(t *testing.T) {
+  t.Setenv("TTSC_LSP_PLUGINS_JSON", `{"plugins":[],"lspPlugins":[]}`)
+
+  prev := runLSPServer
+  var captured lspserver.LSPServerOptions
+  runLSPServer = func(_ context.Context, opts lspserver.LSPServerOptions) error {
+    captured = opts
+    return nil
+  }
+  defer func() { runLSPServer = prev }()
+
+  outBuf := &bytes.Buffer{}
+  errBuf := &bytes.Buffer{}
+  withIO(t, outBuf, errBuf, nil, func() {
+    if code := runLSP([]string{"--stdio", "--cwd", t.TempDir(), "--tsconfig", "tsconfig.app.json"}); code != 0 {
+      t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
+    }
+  })
+
+  if _, ok := captured.Source.(*lspserver.NativePluginSource); !ok {
+    t.Fatalf("expected NativePluginSource, got %T", captured.Source)
+  }
+}

package/driver/lsp.go

@@ -1,5 +1,5 @@
 // lsp.go re-exports the public LSP surface from internal/lspserver so that
-// downstream consumers (plugins, the VSCode extension, tests) import only the
+// downstream consumers (plugins, the VS Code extension, tests) import only the
 // driver package rather than reaching into the internal package directly. All
 // symbols are type aliases or var assignments so they are interchangeable with
 // the originals at the call site.
@@ -57,6 +57,21 @@ type PluginSource = lspserver.PluginSource
 // NullPluginSource is the driver-level alias for lspserver.NullPluginSource.
 type NullPluginSource = lspserver.NullPluginSource
 
+// NativePluginManifest is the driver-level alias for lspserver.NativePluginManifest.
+type NativePluginManifest = lspserver.NativePluginManifest
+
+// NativePluginConfigEntry is the driver-level alias for lspserver.NativePluginConfigEntry.
+type NativePluginConfigEntry = lspserver.NativePluginConfigEntry
+
+// NativeLSPPluginEntry is the driver-level alias for lspserver.NativeLSPPluginEntry.
+type NativeLSPPluginEntry = lspserver.NativeLSPPluginEntry
+
+// NativePluginSourceOptions is the driver-level alias for lspserver.NativePluginSourceOptions.
+type NativePluginSourceOptions = lspserver.NativePluginSourceOptions
+
+// NativePluginSource is the driver-level alias for lspserver.NativePluginSource.
+type NativePluginSource = lspserver.NativePluginSource
+
 // ProxyOptions is the driver-level alias for lspserver.ProxyOptions.
 type ProxyOptions = lspserver.ProxyOptions
 
@@ -79,6 +94,10 @@ type LSPUpstreamRunner = lspserver.LSPUpstreamRunner
 // the proxy will read without returning ErrFrameTooLarge.
 const MaxFrameBytes = lspserver.MaxFrameBytes
 
+// MaxHeaderBytes is the maximum byte length of a JSON-RPC frame header block
+// the proxy will read without returning ErrFrameTooLarge.
+const MaxHeaderBytes = lspserver.MaxHeaderBytes
+
 // Sentinel errors forwarded from lspserver.
 var ErrCommandNotHandled = lspserver.ErrCommandNotHandled
 var ErrFrameClosed = lspserver.ErrFrameClosed
@@ -90,6 +109,7 @@ var ErrLSPTsgoBinaryRequired = lspserver.ErrLSPTsgoBinaryRequired
 
 // Constructor and utility functions forwarded from lspserver.
 var NewProxy = lspserver.NewProxy
+var NewNativePluginSource = lspserver.NewNativePluginSource
 var NewFrameReader = lspserver.NewFrameReader
 var WriteFrame = lspserver.WriteFrame
 var ParseEnvelope = lspserver.ParseEnvelope

package/internal/lspserver/lsp_frame.go

@@ -1,7 +1,8 @@
 // JSON-RPC Content-Length framing as used by LSP over stdio. ttscserver
 // wraps tsgo's LSP server but sits between it and the editor so it can
 // merge plugin diagnostics into outgoing publishDiagnostics and inject
-// ttsc-owned code actions. Both legs of the proxy work on raw bytes.
+// ttsc-owned code actions and executeCommand results. Both legs of the
+// proxy work on raw bytes.
 //
 // Headers are preserved when read so callers that inspect Content-Type
 // or vendor-specific headers can react to them; outgoing frames written
@@ -23,11 +24,11 @@ import (
 // shut down a pump loop without surfacing an error to the editor.
 var ErrFrameClosed = errors.New("lsp: frame stream closed")
 
-// ErrFrameTooLarge reports that a peer announced a Content-Length above
-// the safety cap. ttscserver bounds the value defensively so a confused
-// editor or compromised pipe cannot drive the proxy OOM with a single
-// gigabyte-scale header.
-var ErrFrameTooLarge = errors.New("lsp: frame body exceeds maximum size")
+// ErrFrameTooLarge reports that a peer sent a header block or announced a
+// Content-Length above the safety cap. ttscserver bounds both defensively so a
+// confused editor or compromised pipe cannot drive the proxy OOM with a single
+// gigabyte-scale frame.
+var ErrFrameTooLarge = errors.New("lsp: frame exceeds maximum size")
 
 // MaxFrameBytes caps Content-Length to 64 MiB. The largest payload the
 // LSP base protocol routinely produces is workspace symbol responses
@@ -35,6 +36,11 @@ var ErrFrameTooLarge = errors.New("lsp: frame body exceeds maximum size")
 // editor traffic while still capping attacker-supplied lengths.
 const MaxFrameBytes = 64 << 20
 
+// MaxHeaderBytes caps the LSP header block to 64 KiB. Real LSP traffic carries
+// only Content-Length plus occasional Content-Type, so anything larger is a
+// malformed peer rather than useful protocol data.
+const MaxHeaderBytes = 64 << 10
+
 // FrameReader decodes Content-Length-framed JSON-RPC messages from r. It
 // is intentionally permissive about extra headers (we forward whatever the
 // peer sent) and strict about the Content-Length value because tsgo's
@@ -56,13 +62,27 @@ func (fr *FrameReader) Read() (headers string, body []byte, err error) {
   var headerBuf strings.Builder
   contentLength := -1
   for {
-    line, lineErr := fr.br.ReadString('\n')
-    if lineErr != nil {
-      if lineErr == io.EOF && headerBuf.Len() == 0 && line == "" {
+    var lineBuf strings.Builder
+    for {
+      chunk, lineErr := fr.br.ReadSlice('\n')
+      if len(chunk) != 0 {
+        if headerBuf.Len()+lineBuf.Len()+len(chunk) > MaxHeaderBytes {
+          return "", nil, fmt.Errorf("%w (header got more than %d bytes)", ErrFrameTooLarge, MaxHeaderBytes)
+        }
+        lineBuf.Write(chunk)
+      }
+      if lineErr == nil {
+        break
+      }
+      if errors.Is(lineErr, bufio.ErrBufferFull) {
+        continue
+      }
+      if lineErr == io.EOF && headerBuf.Len() == 0 && lineBuf.Len() == 0 {
         return "", nil, ErrFrameClosed
       }
       return "", nil, fmt.Errorf("lsp: header read: %w", lineErr)
     }
+    line := lineBuf.String()
     trimmed := strings.TrimRight(line, "\r\n")
     if trimmed == "" {
       break
@@ -107,7 +127,7 @@ func parseContentLength(line string) (int, bool) {
 
 // WriteFrame serializes body with a Content-Length header to w. The header
 // uses CRLF line endings to match the LSP base protocol exactly so editors
-// that strict-parse the header block (notably VSCode's client) accept the
+// that strict-parse the header block (notably VS Code's client) accept the
 // message without warnings.
 func WriteFrame(w io.Writer, body []byte) error {
   header := fmt.Sprintf("Content-Length: %d\r\n\r\n", len(body))