ttsc 0.12.3 → 0.13.0

package/cmd/ttscserver/run_lsp_prefers_tsgo_flag_test.go

@@ -1,11 +1,11 @@
 package main
 
 import (
-	"bytes"
-	"context"
-	"testing"
+  "bytes"
+  "context"
+  "testing"
 
-	"github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
 )
 
 // TestRunLSPPrefersTsgoFlag verifies the native command forwards an explicit
@@ -19,24 +19,24 @@ import (
 // 2. Run runLSP with --stdio, --cwd, and --tsgo.
 // 3. Assert the captured TsgoBinary is the flag value.
 func TestRunLSPPrefersTsgoFlag(t *testing.T) {
-	const expected = "/tmp/tsgo-test-binary"
-	prev := runLSPServer
-	var captured lspserver.LSPServerOptions
-	runLSPServer = func(_ context.Context, opts lspserver.LSPServerOptions) error {
-		captured = opts
-		return nil
-	}
-	defer func() { runLSPServer = prev }()
+  const expected = "/tmp/tsgo-test-binary"
+  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(), "--tsgo", expected}); code != 0 {
-			t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
-		}
-	})
+  outBuf := &bytes.Buffer{}
+  errBuf := &bytes.Buffer{}
+  withIO(t, outBuf, errBuf, nil, func() {
+    if code := runLSP([]string{"--stdio", "--cwd", t.TempDir(), "--tsgo", expected}); code != 0 {
+      t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
+    }
+  })
 
-	if captured.TsgoBinary != expected {
-		t.Fatalf("expected TsgoBinary %q, got %q", expected, captured.TsgoBinary)
-	}
+  if captured.TsgoBinary != expected {
+    t.Fatalf("expected TsgoBinary %q, got %q", expected, captured.TsgoBinary)
+  }
 }

package/cmd/ttscserver/run_lsp_reports_server_error_test.go

@@ -1,13 +1,13 @@
 package main
 
 import (
-	"bytes"
-	"context"
-	"errors"
-	"strings"
-	"testing"
+  "bytes"
+  "context"
+  "errors"
+  "strings"
+  "testing"
 
-	"github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
 )
 
 // TestRunLSPReportsServerError pins the non-cancellation error path in
@@ -19,22 +19,22 @@ import (
 // 2. Run runLSP with --stdio --cwd <tempdir>.
 // 3. Assert exit 1 and the sentinel text on stderr.
 func TestRunLSPReportsServerError(t *testing.T) {
-	sentinel := errors.New("lsp host blew up")
-	prev := runLSPServer
-	runLSPServer = func(_ context.Context, _ lspserver.LSPServerOptions) error {
-		return sentinel
-	}
-	defer func() { runLSPServer = prev }()
+  sentinel := errors.New("lsp host blew up")
+  prev := runLSPServer
+  runLSPServer = func(_ context.Context, _ lspserver.LSPServerOptions) error {
+    return sentinel
+  }
+  defer func() { runLSPServer = prev }()
 
-	outBuf := &bytes.Buffer{}
-	errBuf := &bytes.Buffer{}
-	withIO(t, outBuf, errBuf, nil, func() {
-		if code := runLSP([]string{"--stdio", "--cwd", t.TempDir()}); code != 1 {
-			t.Fatalf("expected exit 1, got %d", code)
-		}
-	})
+  outBuf := &bytes.Buffer{}
+  errBuf := &bytes.Buffer{}
+  withIO(t, outBuf, errBuf, nil, func() {
+    if code := runLSP([]string{"--stdio", "--cwd", t.TempDir()}); code != 1 {
+      t.Fatalf("expected exit 1, got %d", code)
+    }
+  })
 
-	if !strings.Contains(errBuf.String(), sentinel.Error()) {
-		t.Fatalf("expected sentinel on stderr, got: %q", errBuf.String())
-	}
+  if !strings.Contains(errBuf.String(), sentinel.Error()) {
+    t.Fatalf("expected sentinel on stderr, got: %q", errBuf.String())
+  }
 }

package/cmd/ttscserver/run_lsp_uses_tsgo_environment_test.go

@@ -1,11 +1,11 @@
 package main
 
 import (
-	"bytes"
-	"context"
-	"testing"
+  "bytes"
+  "context"
+  "testing"
 
-	"github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
 )
 
 // TestRunLSPUsesTsgoEnvironment verifies TTSC_TSGO_BINARY feeds the native host
@@ -19,26 +19,26 @@ import (
 // 2. Substitute runLSPServer and capture its options.
 // 3. Assert TsgoBinary is populated from the environment.
 func TestRunLSPUsesTsgoEnvironment(t *testing.T) {
-	const expected = "/tmp/tsgo-env-binary"
-	t.Setenv("TTSC_TSGO_BINARY", expected)
+  const expected = "/tmp/tsgo-env-binary"
+  t.Setenv("TTSC_TSGO_BINARY", expected)
 
-	prev := runLSPServer
-	var captured lspserver.LSPServerOptions
-	runLSPServer = func(_ context.Context, opts lspserver.LSPServerOptions) error {
-		captured = opts
-		return nil
-	}
-	defer func() { runLSPServer = prev }()
+  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()}); code != 0 {
-			t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
-		}
-	})
+  outBuf := &bytes.Buffer{}
+  errBuf := &bytes.Buffer{}
+  withIO(t, outBuf, errBuf, nil, func() {
+    if code := runLSP([]string{"--stdio", "--cwd", t.TempDir()}); code != 0 {
+      t.Fatalf("expected exit 0, got %d (stderr=%q)", code, errBuf.String())
+    }
+  })
 
-	if captured.TsgoBinary != expected {
-		t.Fatalf("expected TsgoBinary %q, got %q", expected, captured.TsgoBinary)
-	}
+  if captured.TsgoBinary != expected {
+    t.Fatalf("expected TsgoBinary %q, got %q", expected, captured.TsgoBinary)
+  }
 }

package/cmd/utility-host/main.go

@@ -1,39 +1,46 @@
+// Command utility-host is the Go sidecar invoked by the JavaScript ttsc
+// launcher to host linked transform plugins. It is not meant to be run by
+// end users directly; the JavaScript launcher spawns it with a pre-resolved
+// plugin manifest and a tsconfig path.
 package main
 
 import (
-	"fmt"
-	"os"
+  "fmt"
+  "os"
 
-	"github.com/samchon/ttsc/packages/ttsc/utility"
+  "github.com/samchon/ttsc/packages/ttsc/utility"
 )
 
 func main() {
-	os.Exit(run(os.Args[1:]))
+  os.Exit(run(os.Args[1:]))
 }
 
+// run dispatches the first positional argument to the matching utility command.
+// With no arguments it defaults to RunBuild so the launcher can omit the verb.
 func run(args []string) int {
-	if len(args) == 0 {
-		return utility.RunBuild(nil)
-	}
-	switch args[0] {
-	case "build":
-		return utility.RunBuild(args[1:])
-	case "check":
-		return utility.RunCheck(args[1:])
-	case "transform":
-		return utility.RunTransform(args[1:])
-	case "-h", "--help", "help":
-		printHelp()
-		return 0
-	default:
-		fmt.Fprintf(os.Stderr, "ttsc utility: unknown command %q\n", args[0])
-		fmt.Fprintln(os.Stderr, `ttsc utility: run "help" to see supported commands`)
-		return 2
-	}
+  if len(args) == 0 {
+    return utility.RunBuild(nil)
+  }
+  switch args[0] {
+  case "build":
+    return utility.RunBuild(args[1:])
+  case "check":
+    return utility.RunCheck(args[1:])
+  case "transform":
+    return utility.RunTransform(args[1:])
+  case "-h", "--help", "help":
+    printHelp()
+    return 0
+  default:
+    fmt.Fprintf(os.Stderr, "ttsc utility: unknown command %q\n", args[0])
+    fmt.Fprintln(os.Stderr, `ttsc utility: run "help" to see supported commands`)
+    return 2
+  }
 }
 
+// printHelp writes the utility-host usage summary to stdout.
 func printHelp() {
-	fmt.Fprintln(os.Stdout, `ttsc utility host
+  fmt.Fprintln(os.Stdout, `ttsc utility host
 
 Usage:
   utility-host build --tsconfig=tsconfig.json --plugins-json='[...]'

package/driver/lsp.go

@@ -1,43 +1,85 @@
+// lsp.go re-exports the public LSP surface from internal/lspserver so that
+// downstream consumers (plugins, the VSCode 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.
 package driver
 
 import (
-	"encoding/json"
+  "encoding/json"
 
-	"github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
+  "github.com/samchon/ttsc/packages/ttsc/internal/lspserver"
 )
 
+// LSPPosition is the driver-level alias for lspserver.LSPPosition.
 type LSPPosition = lspserver.LSPPosition
+
+// LSPRange is the driver-level alias for lspserver.LSPRange.
 type LSPRange = lspserver.LSPRange
+
+// LSPDiagnosticSeverity is the driver-level alias for lspserver.LSPDiagnosticSeverity.
 type LSPDiagnosticSeverity = lspserver.LSPDiagnosticSeverity
 
+// LSP diagnostic severity constants forwarded from lspserver.
 const (
-	LSPDiagnosticSeverityError       = lspserver.LSPDiagnosticSeverityError
-	LSPDiagnosticSeverityWarning     = lspserver.LSPDiagnosticSeverityWarning
-	LSPDiagnosticSeverityInformation = lspserver.LSPDiagnosticSeverityInformation
-	LSPDiagnosticSeverityHint        = lspserver.LSPDiagnosticSeverityHint
+  LSPDiagnosticSeverityError       = lspserver.LSPDiagnosticSeverityError
+  LSPDiagnosticSeverityWarning     = lspserver.LSPDiagnosticSeverityWarning
+  LSPDiagnosticSeverityInformation = lspserver.LSPDiagnosticSeverityInformation
+  LSPDiagnosticSeverityHint        = lspserver.LSPDiagnosticSeverityHint
 )
 
+// LSPDiagnostic is the driver-level alias for lspserver.LSPDiagnostic.
 type LSPDiagnostic = lspserver.LSPDiagnostic
+
+// LSPCodeAction is the driver-level alias for lspserver.LSPCodeAction.
 type LSPCodeAction = lspserver.LSPCodeAction
+
+// LSPCommand is the driver-level alias for lspserver.LSPCommand.
 type LSPCommand = lspserver.LSPCommand
+
+// LSPCodeActionContext is the driver-level alias for lspserver.LSPCodeActionContext.
 type LSPCodeActionContext = lspserver.LSPCodeActionContext
+
+// LSPWorkspaceEdit is the driver-level alias for lspserver.LSPWorkspaceEdit.
 type LSPWorkspaceEdit = lspserver.LSPWorkspaceEdit
+
+// LSPTextEdit is the driver-level alias for lspserver.LSPTextEdit.
 type LSPTextEdit = lspserver.LSPTextEdit
+
+// LSPDocumentVersion is the driver-level alias for lspserver.LSPDocumentVersion.
 type LSPDocumentVersion = lspserver.LSPDocumentVersion
+
+// PluginSource is the driver-level alias for lspserver.PluginSource.
+// It is the public seam downstream pipelines implement to contribute
+// diagnostics, code actions, and workspace commands to the LSP proxy.
 type PluginSource = lspserver.PluginSource
+
+// NullPluginSource is the driver-level alias for lspserver.NullPluginSource.
 type NullPluginSource = lspserver.NullPluginSource
 
+// ProxyOptions is the driver-level alias for lspserver.ProxyOptions.
 type ProxyOptions = lspserver.ProxyOptions
+
+// Proxy is the driver-level alias for lspserver.Proxy.
 type Proxy = lspserver.Proxy
 
+// FrameReader is the driver-level alias for lspserver.FrameReader.
 type FrameReader = lspserver.FrameReader
+
+// Envelope is the driver-level alias for lspserver.Envelope.
 type Envelope = lspserver.Envelope
 
+// LSPServerOptions is the driver-level alias for lspserver.LSPServerOptions.
 type LSPServerOptions = lspserver.LSPServerOptions
+
+// LSPUpstreamRunner is the driver-level alias for lspserver.LSPUpstreamRunner.
 type LSPUpstreamRunner = lspserver.LSPUpstreamRunner
 
+// MaxFrameBytes is the maximum byte length of a single JSON-RPC frame
+// the proxy will read without returning ErrFrameTooLarge.
 const MaxFrameBytes = lspserver.MaxFrameBytes
 
+// Sentinel errors forwarded from lspserver.
 var ErrCommandNotHandled = lspserver.ErrCommandNotHandled
 var ErrFrameClosed = lspserver.ErrFrameClosed
 var ErrFrameTooLarge = lspserver.ErrFrameTooLarge
@@ -46,6 +88,7 @@ var ErrLSPUpstreamPanic = lspserver.ErrLSPUpstreamPanic
 var ErrLSPCwdRequired = lspserver.ErrLSPCwdRequired
 var ErrLSPTsgoBinaryRequired = lspserver.ErrLSPTsgoBinaryRequired
 
+// Constructor and utility functions forwarded from lspserver.
 var NewProxy = lspserver.NewProxy
 var NewFrameReader = lspserver.NewFrameReader
 var WriteFrame = lspserver.WriteFrame
@@ -55,6 +98,9 @@ var WithUpstreamRunnerForTest = lspserver.WithUpstreamRunnerForTest
 var RunLSPServer = lspserver.RunLSPServer
 var DenyNpmInstall = lspserver.DenyNpmInstall
 
+// idKeyFromRaw normalizes a raw JSON-RPC id to a string map key. It is
+// exposed here (unexported) so tests can access it via go:linkname without
+// importing the internal package.
 func idKeyFromRaw(raw json.RawMessage) string {
-	return lspserver.IDKeyFromRaw(raw)
+  return lspserver.IDKeyFromRaw(raw)
 }

package/driver/plugins.go

@@ -1,44 +1,48 @@
 package driver
 
 import (
-	"encoding/json"
-	"fmt"
-	"os"
-	"strings"
+  "encoding/json"
+  "fmt"
+  "os"
+  "strings"
 )
 
+// LinkedPluginsEnv is the environment variable ttsc sets to pass the JSON
+// manifest of linked plugins to a natively-linked host binary. The value is
+// a JSON array of PluginEntry objects; an empty or absent value means no
+// linked plugins are active.
 const LinkedPluginsEnv = "TTSC_LINKED_PLUGINS_JSON"
 
 // PluginEntry is the manifest shape ttsc passes to driver-level plugins.
 type PluginEntry struct {
-	Config map[string]any `json:"config"`
-	Name   string         `json:"name"`
-	Stage  string         `json:"stage"`
+  Config map[string]any `json:"config"`
+  Name   string         `json:"name"`
+  Stage  string         `json:"stage"`
 }
 
 // PluginContext is the per-entry context passed to registered linked plugins.
 type PluginContext struct {
-	Cwd      string
-	Entry    PluginEntry
-	Tsconfig string
+  Cwd      string
+  Entry    PluginEntry
+  Tsconfig string
 }
 
 // SourcePreamblePlugin can inject source text before TypeScript-Go parses the
 // project. This is intentionally generic: the driver knows only the registered
 // plugin name and the project plugin manifest.
 type SourcePreamblePlugin interface {
-	SourcePreamble(PluginContext) (string, error)
+  SourcePreamble(PluginContext) (string, error)
 }
 
 // ProgramPlugin can mutate a loaded Program before source output or emit.
 type ProgramPlugin interface {
-	ApplyProgram(*Program, PluginContext) error
+  ApplyProgram(*Program, PluginContext) error
 }
 
 type linkedPluginState struct {
-	cwd      string
-	entries  []PluginEntry
-	tsconfig string
+  cwd      string
+  entries  []PluginEntry
+  tsconfig string
 }
 
 var pluginRegistry []any
@@ -47,76 +51,88 @@ var pluginRegistry []any
 // packages call this from init(); ttsc pairs registrations with linked manifest
 // entries by build order, not by package name.
 func RegisterPlugin(plugin any) {
-	if plugin == nil {
-		panic("driver: RegisterPlugin called with nil plugin")
-	}
-	pluginRegistry = append(pluginRegistry, plugin)
+  if plugin == nil {
+    panic("driver: RegisterPlugin called with nil plugin")
+  }
+  pluginRegistry = append(pluginRegistry, plugin)
 }
 
+// loadLinkedPluginState reads the linked-plugin manifest from the environment
+// and returns the hydrated state. Returns a zero-entry state (not an error)
+// when the environment variable is absent or empty.
 func loadLinkedPluginState(cwd, tsconfigPath string) (linkedPluginState, error) {
-	input := strings.TrimSpace(os.Getenv(LinkedPluginsEnv))
-	if input == "" {
-		return linkedPluginState{cwd: cwd, tsconfig: tsconfigPath}, nil
-	}
-	var entries []PluginEntry
-	if err := json.Unmarshal([]byte(input), &entries); err != nil {
-		return linkedPluginState{}, fmt.Errorf("ttsc driver: invalid %s: %w", LinkedPluginsEnv, err)
-	}
-	return linkedPluginState{
-		cwd:      cwd,
-		entries:  entries,
-		tsconfig: tsconfigPath,
-	}, nil
+  input := strings.TrimSpace(os.Getenv(LinkedPluginsEnv))
+  if input == "" {
+    return linkedPluginState{cwd: cwd, tsconfig: tsconfigPath}, nil
+  }
+  var entries []PluginEntry
+  if err := json.Unmarshal([]byte(input), &entries); err != nil {
+    return linkedPluginState{}, fmt.Errorf("ttsc driver: invalid %s: %w", LinkedPluginsEnv, err)
+  }
+  return linkedPluginState{
+    cwd:      cwd,
+    entries:  entries,
+    tsconfig: tsconfigPath,
+  }, nil
 }
 
+// sourcePreamble calls SourcePreamble on every SourcePreamblePlugin in
+// registration order and concatenates the results. An entry that does not
+// implement SourcePreamblePlugin is silently skipped.
 func (state linkedPluginState) sourcePreamble() (string, error) {
-	var out strings.Builder
-	for index, entry := range state.entries {
-		plugin, ok := registeredPlugin(index)
-		if !ok {
-			return "", fmt.Errorf("ttsc driver: linked plugin entry %d was requested but no linked plugin registered at that position", index)
-		}
-		preamble, ok := plugin.(SourcePreamblePlugin)
-		if !ok {
-			continue
-		}
-		text, err := preamble.SourcePreamble(state.context(entry))
-		if err != nil {
-			return "", err
-		}
-		out.WriteString(text)
-	}
-	return out.String(), nil
+  var out strings.Builder
+  for index, entry := range state.entries {
+    plugin, ok := registeredPlugin(index)
+    if !ok {
+      return "", fmt.Errorf("ttsc driver: linked plugin entry %d was requested but no linked plugin registered at that position", index)
+    }
+    preamble, ok := plugin.(SourcePreamblePlugin)
+    if !ok {
+      continue
+    }
+    text, err := preamble.SourcePreamble(state.context(entry))
+    if err != nil {
+      return "", err
+    }
+    out.WriteString(text)
+  }
+  return out.String(), nil
 }
 
+// apply calls ApplyProgram on every ProgramPlugin in registration order.
+// An entry that does not implement ProgramPlugin is silently skipped.
 func (state linkedPluginState) apply(prog *Program) error {
-	for index, entry := range state.entries {
-		plugin, ok := registeredPlugin(index)
-		if !ok {
-			return fmt.Errorf("ttsc driver: linked plugin entry %d was requested but no linked plugin registered at that position", index)
-		}
-		transform, ok := plugin.(ProgramPlugin)
-		if !ok {
-			continue
-		}
-		if err := transform.ApplyProgram(prog, state.context(entry)); err != nil {
-			return err
-		}
-	}
-	return nil
+  for index, entry := range state.entries {
+    plugin, ok := registeredPlugin(index)
+    if !ok {
+      return fmt.Errorf("ttsc driver: linked plugin entry %d was requested but no linked plugin registered at that position", index)
+    }
+    transform, ok := plugin.(ProgramPlugin)
+    if !ok {
+      continue
+    }
+    if err := transform.ApplyProgram(prog, state.context(entry)); err != nil {
+      return err
+    }
+  }
+  return nil
 }
 
+// registeredPlugin returns the plugin registered at position index, or
+// (nil, false) when the index is out of range. Registration order matches
+// the order of linked Go init() calls.
 func registeredPlugin(index int) (any, bool) {
-	if index < 0 || index >= len(pluginRegistry) {
-		return nil, false
-	}
-	return pluginRegistry[index], true
+  if index < 0 || index >= len(pluginRegistry) {
+    return nil, false
+  }
+  return pluginRegistry[index], true
 }
 
+// context builds the PluginContext the driver passes to each plugin hook.
 func (state linkedPluginState) context(entry PluginEntry) PluginContext {
-	return PluginContext{
-		Cwd:      state.cwd,
-		Entry:    entry,
-		Tsconfig: state.tsconfig,
-	}
+  return PluginContext{
+    Cwd:      state.cwd,
+    Entry:    entry,
+    Tsconfig: state.tsconfig,
+  }
 }