ttsc 0.30.3 → 0.31.0

package/cmd/ttsc/api_compile.go

@@ -18,12 +18,19 @@ import (
   cwdutil "github.com/samchon/ttsc/packages/ttsc/internal/cwd"
 )
 
+// apiCompileResult is the in-memory compilation envelope. Output is keyed by
+// the shared project-relative path convention rather than native separators.
 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"`
+
+  // Output remains present when diagnostics accompany partial emission.
+  Output map[string]string `json:"output"`
+
+  // EmittedSources records actual JavaScript writes using absolute native output
+  // paths and generation-time physical source paths. Empty rows preserve unknown
+  // ownership; the empty object means no JavaScript write succeeded.
+  EmittedSources map[string][]string `json:"emittedSources"`
 }
 
 // apiCompileDiagnostic mirrors the public TypeScript-side diagnostic DTO.
@@ -31,58 +38,77 @@ 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 is null for a diagnostic without an authored source location.
+  File *string `json:"file"`
 
-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")
-  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
-  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
-  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
-  // See cmd/ttsc/build.go's filterHostArgs call for the rationale.
-  if err := fs.Parse(filterHostArgs(args)); err != nil {
-    return 2
-  }
+  Category string `json:"category"`
+  Code     int32  `json:"code"`
 
-  cwd, err := cwdutil.Resolve(*cwdOverride, getwd)
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
-    return 2
-  }
+  // Start is an optional byte offset, not a UTF-16 character offset.
+  Start *int `json:"start,omitempty"`
 
-  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
-  if err != nil {
-    fmt.Fprintf(stderr, "ttsc: %v\n", err)
-    return 2
-  }
+  // Length is the optional byte extent associated with Start.
+  Length *int `json:"length,omitempty"`
+
+  // Line is one-based; absent means no authored line is available.
+  Line int `json:"line,omitempty"`
+
+  // Character preserves the driver's one-based byte column despite its
+  // TypeScript-style JSON name. It is not an LSP character position.
+  Character int `json:"character,omitempty"`
+
+  MessageText string `json:"messageText"`
+}
 
-  prog, diags, err := driver.LoadProgram(cwd, *tsconfigPath, driver.LoadProgramOptions{
-    ForceEmit:          true,
-    SemanticConfigPath: os.Getenv(driver.SemanticConfigPathEnv),
-    SingleThreaded:     *singleThreaded,
-    Checkers:           *checkers,
-    TsgoArgs:           tsgoArgs,
-  })
+// runAPICompile prepares an API request, loads its actual compiler generation
+// and writes the compile response.
+//
+// The real preparation owns native argv/cwd errors and the ForceEmit policy.
+// This wrapper loads once, reports load errors and retains a nonnil Program
+// until the borrowed response operation finishes. Deferred Close releases that
+// acquired checker lease on every response return.
+//
+// The response owner emits actual compiler output to memory and serializes its
+// original diagnostics/provenance envelope; the wrapper returns that
+// operation's status.
+func runAPICompile(args []string) int {
+  request, code := prepareAPICompileInvocation(args)
+  if code != 0 {
+    return code
+  }
+  cwd := request.cwd
+  prog, diags, err := driver.LoadProgram(cwd, request.tsconfigPath, request.options)
   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()...)
   }
+  return writeCompiledProgramResponse(prog, diags, cwd)
+}
 
+// writeCompiledProgramResponse borrows a Program while it emits the actual
+// memory-backed result and serializes the existing JSON envelope. The caller
+// owns Close after every consumer; this operation neither reloads nor closes it.
+// Preparation separately preserves the original ForceEmit:true policy.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain attached to the owning operation and its callers.
+// Common: Principled implementation: The borrowed actual Program supplies diagnostics, memory emission and the existing provenance-backed JSON envelope; the wrapper still loads with ForceEmit true and owns Close.
+// Common: Clear and simple design: The wrapper owns flag parsing/load/lease cleanup while this operation owns the unchanged emit and serialization sequence.
+// Common: Prohibited implementation shortcuts: No emitted result or diagnostic is replayed, NoEmit option flipped, loader mocked or status fabricated; nil Program and partial diagnostic envelopes preserve the original branches.
+// Common: Meaningful documentation: Native prose states borrowing, original loader policy and caller cleanup after all consumers.
+// Portability: OS-neutral implementation: Existing native project keys and JSON writers retain their original path/byte ownership; no shell, process or path policy is introduced.
+// Performance: Efficient algorithms: Actual EmitAll and one JSON encoding do the same compiler/output work as before; memory-map/provenance processing scales with actual emitted bytes and paths.
+// Performance: Reuse equivalent work: A load owner may reuse one immutable Program for this real memory emission and read-only source-envelope consumer. It does not claim the compile and transform wrappers have equal raw loader options.
+// Performance: Bound retention and release resources: The load owner holds its checker lease through all borrowed consumers and closes once. This operation retains local output/provenance/diagnostic data until encoding returns, with no independent output byte ceiling.
+func writeCompiledProgramResponse(prog *driver.Program, diags []driver.Diagnostic, cwd string) int {
+  if prog != nil {
+    diags = append(diags, prog.Diagnostics()...)
+  }
   output := map[string]string{}
+  emittedSources := map[string][]string{}
   if prog != nil {
     rewrites := driver.NewRewriteSet()
     // Capture WriteFile output in a map keyed by project-relative paths. This
@@ -93,24 +119,33 @@ func runAPICompile(args []string) int {
         return nil
       },
     )
+    writeFile, snapshot, err := prog.NewEmitProvenanceRecorder(writeFile)
+    if err != nil {
+      fmt.Fprintf(stderr, "ttsc api-compile: provenance failed: %v\n", err)
+      return 3
+    }
     _, 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...)
+    emittedSources = snapshot()
   }
 
   result := apiCompileResult{
-    Diagnostics: make([]apiCompileDiagnostic, 0, len(diags)),
-    Output:      output,
+    Diagnostics:    make([]apiCompileDiagnostic, 0, len(diags)),
+    Output:         output,
+    EmittedSources: emittedSources,
   }
   for _, diag := range diags {
     result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))
   }
 
-  data, _ := json.Marshal(result)
-  fmt.Fprintln(stdout, string(data))
+  if err := json.NewEncoder(stdout).Encode(result); err != nil {
+    fmt.Fprintf(stderr, "ttsc api-compile: write result: %v\n", err)
+    return 3
+  }
   if driver.CountErrors(diags) > 0 {
     return 2
   }
@@ -120,6 +155,11 @@ func runAPICompile(args []string) int {
 // toAPICompileDiagnostic converts an internal driver.Diagnostic into the
 // JSON-serialisable form returned by the api-compile command. Category is
 // lowercased to match the TypeScript Language Service convention.
+//
+// Warning maps to warning and every other severity maps to error. Source
+// metadata is copied with its driver byte units and one-based positions; the
+// JSON Character name introduces no UTF-16 conversion. An absent source file
+// becomes null, while optional offset/extent pointers retain their given state.
 func toAPICompileDiagnostic(diag driver.Diagnostic) apiCompileDiagnostic {
   var file *string
   if diag.File != "" {
@@ -151,3 +191,83 @@ func toAPICompileDiagnostic(diag driver.Diagnostic) apiCompileDiagnostic {
 func apiOutputKey(cwd, fileName string) string {
   return driver.TransformOutputKey(cwd, fileName)
 }
+
+// prepareAPICompileLoadOptions is the exact policy constructor consumed by
+// runAPICompile after native flag parsing and forwarded-argument decoding.
+// Borrowed-operation tests do not claim their shared Program has transform's
+// different NoEmit option; this real construction path keeps that distinction.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain attached to the owning operation and its callers.
+// Common: Principled implementation: The real runAPICompile parse path consumes this exact ForceEmit true load policy and forwards all previously parsed threading, semantic-config and tsgo arguments unchanged.
+// Common: Clear and simple design: One value constructor separates load policy from borrowed emission/serialization.
+// Common: Prohibited implementation shortcuts: The constructor replaces a literal struct in the product caller; no test-only expected map, fake loader or public export bypasses policy.
+// Common: Meaningful documentation: Native prose states the production caller and the deliberate difference from ForceNoEmit transform loading.
+// Portability: OS-neutral implementation: The value carries existing native-path strings and argv tokens without rewriting separators or shell syntax.
+// Performance: Efficient algorithms: A fixed-size options value is constructed in constant work; the parsed argument slice is forwarded without rescanning.
+// Performance: Reuse equivalent work: This pure value construction creates no compiler result cache; the synchronous caller consumes its own parsed inputs.
+// Performance: Bound retention and release resources: Strings and the parsed argument slice are borrowed until synchronous LoadProgram consumption; no checker lease, process or resident history is acquired.
+func prepareAPICompileLoadOptions(semanticConfigPath string, singleThreaded bool, checkers int, tsgoArgs []string) driver.LoadProgramOptions {
+  return driver.LoadProgramOptions{ForceEmit: true, SemanticConfigPath: semanticConfigPath, SingleThreaded: singleThreaded, Checkers: checkers, TsgoArgs: tsgoArgs}
+}
+
+// prepareAPICompileInvocation parses the original native API argv and returns its exact cwd, selected config and loader policy.
+// The real wrapper consumes this operation directly; tests observe preparation
+// separately from actual loaded compiler work and never replay a command result.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain with the owning operation and its actual callers.
+// Common: Principled implementation: Original flags, cwd resolution, diagnostic branches and status/stream ownership remain in this actual production path.
+// Common: Clear and simple design: Preparation and loaded-program work have explicit separate owners; no hidden second compiler producer is added.
+// Common: Prohibited implementation shortcuts: No loader is mocked, public export invented, option difference hidden, source result fabricated or previous status returned as an actual invocation.
+// Common: Meaningful documentation: Native prose identifies actual wrapper consumption, borrowing boundaries and independent preparation versus compiler observations.
+// Portability: OS-neutral implementation: Existing native cwd/path and argument-array semantics remain; no symlink, shell, forced separator or filesystem-case policy is introduced.
+// Performance: Efficient algorithms: Native flag parsing scales with argv; loaded compiler/output work remains in the existing driver and JSON/emit owners.
+// Performance: Reuse equivalent work: No request or command-result cache is retained. Immutable input sharing belongs to a local test family with separately declared selected configurations and load modes.
+// Performance: Bound retention and release resources: One FlagSet and decoded argv/options value transfer to the synchronous caller; no Program lease or process is acquired during preparation.
+func prepareAPICompileInvocation(args []string) (apiCommandRequest, 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")
+  singleThreaded := fs.Bool("singleThreaded", false, "run TypeScript-Go single-threaded")
+  checkers := fs.Int("checkers", 0, "type-checker pool size (0 = TypeScript-Go default)")
+  tsgoArgsRaw := fs.String("tsgo-args", "", "JSON array of forwarded tsgo CLI flags")
+  // See cmd/ttsc/build.go's filterHostArgs call for the rationale.
+  if err := fs.Parse(filterHostArgs(args)); err != nil {
+    return apiCommandRequest{}, 2
+  }
+
+  cwd, err := cwdutil.Resolve(*cwdOverride, getwd)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return apiCommandRequest{}, 2
+  }
+
+  tsgoArgs, err := decodeTsgoArgs(*tsgoArgsRaw)
+  if err != nil {
+    fmt.Fprintf(stderr, "ttsc: %v\n", err)
+    return apiCommandRequest{}, 2
+  }
+
+  return apiCommandRequest{cwd: cwd, tsconfigPath: *tsconfigPath, options: prepareAPICompileLoadOptions(os.Getenv(driver.SemanticConfigPathEnv), *singleThreaded, *checkers, tsgoArgs)}, 0
+}
+
+// apiCommandRequest carries the existing resolved API invocation until its
+// synchronous LoadProgram call. It owns no compiler lease or cached response.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds describe the request carrier consumed by the real wrapper.
+// Common: Principled implementation: The selected cwd/config and loader policy retain compile ForceEmit versus transform ForceNoEmit; the wrappers consume these exact values for real LoadProgram calls.
+// Common: Clear and simple design: One value carries prepared command intent across synchronous load and response ownership; no hidden dispatch or compiler producer is introduced.
+// Common: Prohibited implementation shortcuts: The carrier contains actual parsed values, never fabricated output, cached status, mocked loader or a public test-only API.
+// Common: Meaningful documentation: Native prose identifies policy distinctions and the wrapper's Program lease ownership.
+// Portability: OS-neutral implementation: Native cwd/config strings and argv are forwarded without shell, symlink or forced-separator conversion.
+// Performance: Efficient algorithms: Fields transfer in constant-size value copies; the forwarded argv slice is not retraversed or compiled by this carrier.
+// Performance: Reuse equivalent work: Each preparation creates invocation-local intent; the carrier stores no global cache or previous command result.
+// Performance: Bound retention and release resources: Referenced argv remains owned by the synchronous request lifetime; the carrier acquires no checker lease, process or independently retained resource.
+type apiCommandRequest struct {
+  cwd          string
+  tsconfigPath string
+  options      driver.LoadProgramOptions
+}

package/cmd/ttsc/api_compile_branches_test.go

@@ -1,29 +1,63 @@
 package main
 
 import (
+  "encoding/json"
   "errors"
+  "slices"
   "strings"
   "testing"
 
   "github.com/samchon/ttsc/packages/ttsc/driver"
 )
 
+// apiCompileApplyErrorPlugin is the independently failing linked Program hook fixture.
+//
+// The owning branch test registers this actual implementation and declares
+// one transform manifest entry. The zero-field value carries no expected
+// response or compiler state; ApplyProgram owns its literal fixture error.
+//
+// Native private fixture grounds remain with the test; no fake public API
+// or unsupported exported-host Evidence annotation is added.
+// Common: Principled implementation: The actual driver registry receives this ProgramPlugin implementation for the command's real linked apply/emit failure branch.
+// Common: Clear and simple design: A zero-field type supplies only the failing hook method and retains no auxiliary fixture state.
+// Common: Prohibited implementation shortcuts: The test exercises a real registered hook rather than injecting a cached status or manufactured command stderr.
+// Common: Meaningful documentation: Native prose identifies registration, manifest pairing and the separate literal error owner.
+// Applicability: This empty carrier owns no processing algorithm, native OS boundary, reusable work or resource lease; the branch test owns registry/environment cleanup.
 type apiCompileApplyErrorPlugin struct{}
 
+// ApplyProgram returns the literal api compile apply boom fixture cause.
+//
+// The real command's emission path invokes the registered hook. This fixture
+// fails without altering its borrowed Program; the wrapper must propagate
+// its independently authored cause and returned failure status.
+//
+// Native fixture grounds describe this actual hook, without Evidence tags.
+// Common: Principled implementation: Returning the authored error exercises the actual linked hook error propagation used by the owning command test.
+// Common: Clear and simple design: The fixture constructs one fixed error without inspecting or mutating the borrowed Program.
+// Common: Prohibited implementation shortcuts: Neither wrapper output nor status is supplied by this fixture; assertions observe the command's own handling.
+// Common: Meaningful documentation: Native prose states the exact error contribution and borrowed Program non-mutation.
+// Applicability: The fixed in-process error return performs no native OS operation, processing traversal, reuse coordination or resource acquisition; its command caller owns the Program lease.
 func (apiCompileApplyErrorPlugin) ApplyProgram(*driver.Program, driver.PluginContext) error {
   return errors.New("api compile apply boom")
 }
 
-// TestAPICompileBranches verifies api-compile handles parse, cwd, diagnostic, and emit failures.
+// TestAPICompileBranches verifies API compile setup, diagnostic and linked 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.
+// The real wrapper returns usage/setup status two. One independently invalid
+// assignment is prepared through the real compile loader policy; its single
+// Program supplies both actual compile and transform JSON writers. A registered
+// ApplyProgram hook supplies a separate actual emission failure.
 //
-// 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.
+// 1. Exercise incomplete flags and an injected failing cwd reader.
+// 2. Load missing and invalid-type fixture configurations, and check warning conversion.
+// 3. Register an actual failing linked hook and assert status three with its literal cause.
+//
+// @evidence contracts/testing.md#behavioral-verification Direct runAPICompile observes setup status two, cwd/config causes and linked emit status three. Actual compile preparation/load and response writers retain TS2322 failure status/diagnostics and publish the failed Program's source, type-only graph edge and completeness; toAPICompileDiagnostic separately returns literal warning category.
+// @evidence contracts/testing.md#independent-expectations Literal statuses, cwd boom, tsconfig not found, warning and api compile apply boom come from independent malformed inputs and authored hook errors. The incomplete-flag check only observes status, and JSON diagnostics presence does not certify every diagnostic.
+// @evidence contracts/testing.md#distinguishing-cases Incomplete argv, cwd reader error, missing config, invalid assignment, warning category and linked apply failure distinguish separate wrapper branches; valid API emission is owned by the aggregate command-operation family.
+// @evidence contracts/testing.md#execution-ownership Owning-private command adapters and real driver Programs execute synchronously in this Go test, with no child or native artifact build. The invalid-type Program is loaded once, borrowed by two actual JSON writers and closed before the linked-failure state; cleanup also closes it on early failure. This does not certify transform's distinct ForceNoEmit loader policy. captureCommand restores streams/cwd seam; other wrappers close their acquired Programs; TempDir and Setenv restore fixtures/environment. A cleanup reset clears the test-registered entry after all consumers; it does not restore an inherited registry snapshot.
 func TestAPICompileBranches(t *testing.T) {
+  t.Setenv(driver.LinkedPluginsEnv, "")
   code, _, _ := captureCommand(t, func() int {
     return runAPICompile([]string{"--cwd"})
   })
@@ -49,23 +83,76 @@ func TestAPICompileBranches(t *testing.T) {
 
   writeCommandProjectFile(t, root, "tsconfig.json", `{
   "compilerOptions": { "module": "commonjs", "target": "es2020", "strict": true },
-  "files": ["index.ts"]
+  "files": ["index.ts", "mytype.ts"]
 }
 `)
-  writeCommandProjectFile(t, root, "index.ts", `const value: number = "text";
+  writeCommandProjectFile(t, root, "index.ts", `const value: number = "not-a-number";
 export { value };
+import type { MyType } from "./mytype";
+export const typed: MyType = { id: "x" };
 `)
+  writeCommandProjectFile(t, root, "mytype.ts", "export interface MyType { id: string }\n")
+  var failedProgram *driver.Program
+  var failedInitial []driver.Diagnostic
+  t.Cleanup(func() {
+    if failedProgram != nil {
+      if err := failedProgram.Close(); err != nil {
+        t.Errorf("failed API Program Close: %v", err)
+      }
+    }
+  })
   code, out, _ := captureCommand(t, func() int {
-    return runAPICompile([]string{"--cwd", root, "--tsconfig", "tsconfig.json"})
+    request, status := prepareAPICompileInvocation([]string{"--cwd", root, "--tsconfig", "tsconfig.json"})
+    if status != 0 {
+      return status
+    }
+    var err error
+    failedProgram, failedInitial, err = driver.LoadProgram(request.cwd, request.tsconfigPath, request.options)
+    if err != nil {
+      t.Fatal(err)
+    }
+    if failedProgram == nil {
+      t.Fatal("semantic failure must retain its actual Program")
+    }
+    return writeCompiledProgramResponse(failedProgram, failedInitial, request.cwd)
   })
   if code != 2 || !strings.Contains(out, `"diagnostics"`) {
     t.Fatalf("diagnostic compile mismatch: code=%d stdout=%q", code, out)
   }
+  transformCode, transformedOutput, _ := captureCommand(t, func() int {
+    return writeTransformedProgramResponse(failedProgram, failedInitial, root)
+  })
+  if transformCode != 2 {
+    t.Errorf("failed Program transform response status = %d, want 2", transformCode)
+  }
+  var transformed apiTransformResult
+  if err := json.Unmarshal([]byte(transformedOutput), &transformed); err != nil {
+    t.Fatal(err)
+  }
+  if !strings.Contains(transformed.TypeScript["index.ts"], `const value: number = "not-a-number"`) || !strings.Contains(transformed.TypeScript["mytype.ts"], "interface MyType") {
+    t.Error("failed native response omitted original source")
+  }
+  if transformed.Graph == nil || !slices.Equal(transformed.Graph.Edges["index.ts"], []string{"mytype.ts"}) {
+    t.Errorf("failed native response omitted type-only graph: %#v", transformed.Graph)
+  }
+  if len(transformed.Diagnostics) != 1 || transformed.Diagnostics[0].Code != 2322 {
+    t.Errorf("failed native response diagnostics = %#v", transformed.Diagnostics)
+  }
+  complete := append([]string{}, transformed.DependenciesComplete...)
+  slices.Sort(complete)
+  if !slices.Equal(complete, []string{"index.ts", "mytype.ts"}) {
+    t.Errorf("failed native completeness = %v", complete)
+  }
+  if err := failedProgram.Close(); err != nil {
+    t.Fatal(err)
+  }
+  failedProgram = nil
   if got := toAPICompileDiagnostic(driver.Diagnostic{Severity: driver.SeverityWarning}).Category; got != "warning" {
     t.Fatalf("warning category mismatch: %q", got)
   }
 
   resetCommandLinkedPluginRegistry()
+  t.Cleanup(resetCommandLinkedPluginRegistry)
   driver.RegisterPlugin(apiCompileApplyErrorPlugin{})
   t.Setenv(driver.LinkedPluginsEnv, `[{"name":"error","stage":"transform","config":{}}]`)
   writeCommandProjectFile(t, root, "index.ts", `export const value = 1;