ttsc 0.30.3 → 0.31.0

package/cmd/ttsc/cli_contract_helpers_test.go

@@ -0,0 +1,82 @@
+package main
+
+import (
+  "bytes"
+  "os"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// cliContractDiagnostic decodes the diagnostic wire fields observed by these
+// units. Expectations remain literal keys and syntax in each test body.
+//
+// Private wire decoders retain native common grounds rather than unsupported
+// exported-host Evidence annotations. These data carriers do not choose a
+// processing algorithm, coordinate reusable work, own a lease lifecycle or
+// access a native filesystem/process; their consumers own those decisions.
+// Common: Principled implementation: Independently decodes the category and messageText wire fields; these fields permit literal diagnostic assertions without importing the production DTO.
+// Common: Clear and simple design: Two string fields retain the observed JSON spellings; unknown envelope fields remain outside this focused test decoder.
+// Common: Prohibited implementation shortcuts: The category assertion owns its literal error expectation; this representation neither manufactures diagnostics nor defines the product schema.
+// Common: Meaningful documentation: Purpose and focused field coverage are stated; this decoder does not imply full diagnostic-envelope verification.
+type cliContractDiagnostic struct {
+  Category    string `json:"category"`
+  MessageText string `json:"messageText"`
+}
+
+// cliContractCompileResult decodes diagnostics and emitted output text.
+//
+// Private wire decoders retain native common grounds rather than unsupported
+// exported-host Evidence annotations. These data carriers do not choose a
+// processing algorithm, coordinate reusable work, own a lease lifecycle or
+// access a native filesystem/process; their consumers own those decisions.
+// Common: Principled implementation: Independently decodes the optional diagnostic array and output text map so actual response JSON remains separate from literal key/export-syntax expectations.
+// Common: Clear and simple design: The diagnostic slice and output map expose the two independently asserted envelope sections directly.
+// Common: Prohibited implementation shortcuts: The decoder stores actual JSON data only; it contains no expected output, compiler cache or fake emitted-file producer.
+// Common: Meaningful documentation: Native prose identifies optional diagnostics and the focused output observation; extra provenance fields remain outside this decoder.
+type cliContractCompileResult struct {
+  Diagnostics []cliContractDiagnostic `json:"diagnostics,omitempty"`
+  Output      map[string]string       `json:"output"`
+}
+
+// cliContractTransformResult decodes diagnostics and source text.
+//
+// Private wire decoders retain native common grounds rather than unsupported
+// exported-host Evidence annotations. These data carriers do not choose a
+// processing algorithm, coordinate reusable work, own a lease lifecycle or
+// access a native filesystem/process; their consumers own those decisions.
+// Common: Principled implementation: Independently decodes optional diagnostics and TypeScript text keyed by the wire protocol, preserving the source-versus-emission distinction.
+// Common: Clear and simple design: A diagnostic slice and source text map represent the original response assertions without the production envelope type.
+// Common: Prohibited implementation shortcuts: Source declarations are asserted against literal authored syntax rather than copied from the implementation or fabricated by this decoder.
+// Common: Meaningful documentation: Native prose identifies source text and optional diagnostics; graph/host-observation coverage belongs to separate response observers.
+type cliContractTransformResult struct {
+  Diagnostics []cliContractDiagnostic `json:"diagnostics,omitempty"`
+  TypeScript  map[string]string       `json:"typescript"`
+}
+
+// runCLIContractCommand calls the actual owning dispatcher synchronously.
+// Its package-local stream seams capture full stdout/stderr bytes and restore
+// the prior writers and cwd resolver even if dispatch panics. The resolver is
+// the real os.Getwd, and fixture-only dispatch has no linked-plugin manifest.
+// Tests using these process-wide seams must remain sequential.
+//
+// Go Evidence addresses exported declarations only; these private review
+// grounds apply to this helper and its direct dispatcher callees.
+// Common: Principled implementation: run receives the original argv and executes its actual build/API/help/version/alias/error branches; status is returned by the owning operation, never synthesized from a mock.
+// Common: Clear and simple design: One synchronous call owns two stream buffers and a deferred restoration of stdout, stderr and getwd.
+// Common: Prohibited implementation shortcuts: No process is disguised as a unit, public API invented, diagnostic replaced, producer skipped or expected result derived from actual output.
+// Common: Meaningful documentation: Native prose distinguishes owning-private dispatch, real cwd resolution, sequential global seams and full byte capture from OS transport.
+// Portability: OS-neutral implementation: Go writers preserve output bytes; os.Getwd and native fixture paths supply real current-directory semantics without a shell.
+// Performance: Efficient algorithms: Each stream is accumulated once with work proportional to its observed bytes; there is no independent buffer size cap.
+// Performance: Reuse equivalent work: This helper executes each supplied full dispatcher invocation once without replay. Separate aggregate closures explicitly own borrowed operations and shared generations; they do not present a cached status as an invocation.
+// Performance: Bound retention and release resources: Returned stream strings own each invocation's bytes, previous package seams are restored by defer, and t.Setenv restores the manifest after the test. No subprocess or independent command timeout exists here.
+func runCLIContractCommand(t *testing.T, args ...string) (int, string, string) {
+  t.Helper()
+  t.Setenv(driver.LinkedPluginsEnv, "")
+  previousOut, previousErr, previousGetwd := stdout, stderr, getwd
+  var out, errOut bytes.Buffer
+  stdout, stderr, getwd = &out, &errOut, os.Getwd
+  defer func() { stdout, stderr, getwd = previousOut, previousErr, previousGetwd }()
+  code := run(args)
+  return code, out.String(), errOut.String()
+}

package/cmd/ttsc/compiler_argument_cwd_test.go

@@ -0,0 +1,57 @@
+package main
+
+import (
+	"path/filepath"
+	"reflect"
+	"testing"
+
+	"github.com/samchon/ttsc/packages/ttsc/driver"
+)
+
+// TestCompilerArgumentCwdPreparation verifies decoded argv origin at all
+// three real native frontdoor preparation operations.
+//
+// 1. Set paired inherited arguments and their original parsing directory.
+// 2. Prepare build, api-compile and api-transform with each explicit state.
+// 3. Assert explicit argv, deferred nil inheritance and original load policies.
+//
+// @evidence contracts/testing.md#behavioral-verification Actual build, api-compile and api-transform preparations preserve nil deferred inheritance versus explicitly decoded argv, empty cwd and their original force-emit policies; driver loading owns the inherited argument/cwd pair.
+// @evidence contracts/testing.md#independent-expectations Authored explicit JSON payloads independently establish literal slices, including nonnil empty argv. An absent command payload remains nil even when inherited environment exists.
+// @evidence contracts/testing.md#distinguishing-cases All three frontdoors cover inherited, explicit nonempty, explicit [] and absent payload, keeping explicit empty distinct from nil inherited argv.
+// @evidence contracts/testing.md#execution-ownership Pure command preparation executes in this Go unit process with temporary cwd and t.Setenv restoration, without Program acquisition, native host launch or installation.
+func TestCompilerArgumentCwdPreparation(t *testing.T) {
+	root := t.TempDir()
+	a := filepath.Join(root, "A")
+	t.Setenv(driver.TsgoArgsCwdEnv, a)
+	for _, c := range []struct {
+		name, inherited, explicit, cwd string
+		argv                           []string
+	}{
+		{"inherited", `["--strict"]`, "", "", nil},
+		{"explicit", `["--strict"]`, `["--target","es2022"]`, "", []string{"--target", "es2022"}},
+		{"explicit empty", `["--strict"]`, `[]`, "", []string{}},
+		{"absent payload", "", "", "", nil},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			t.Setenv(driver.TsgoArgsEnv, c.inherited)
+			args := []string{"--cwd", root}
+			if c.explicit != "" {
+				args = append(args, "--tsgo-args", c.explicit)
+			}
+			build, buildStatus := prepareBuildInvocation(args)
+			compile, compileStatus := prepareAPICompileInvocation(args)
+			transform, transformStatus := prepareAPITransformInvocation(args)
+			if buildStatus != 0 || compileStatus != 0 || transformStatus != 0 {
+				t.Fatalf("preparation statuses: %d/%d/%d", buildStatus, compileStatus, transformStatus)
+			}
+			if build.options.ForceEmit || build.options.ForceNoEmit || !compile.options.ForceEmit || compile.options.ForceNoEmit || transform.options.ForceEmit || !transform.options.ForceNoEmit {
+				t.Fatal("command preparation changed its original emit policy")
+			}
+			for _, options := range []driver.LoadProgramOptions{build.options, compile.options, transform.options} {
+				if options.TsgoArgsCwd != c.cwd || !reflect.DeepEqual(options.TsgoArgs, c.argv) {
+					t.Fatalf("wrong origin: %#v", options)
+				}
+			}
+		})
+	}
+}

package/cmd/ttsc/filter.go

@@ -1,33 +1,43 @@
 // Argument filtering for cmd/ttsc subcommand parsers.
 //
-// `flag.NewFlagSet(..., flag.ContinueOnError).Parse` exits with non-zero on
-// the first unknown flag it sees, which is exactly the failure mode RCA
-// #4 in `.discussions/cli-parser-rca/report.md` flagged: a forwarded tsgo
-// option from the JS launcher would crash the build before tsgo's own
-// option table got a chance to consume it. Mirror the strategy that
-// `packages/ttsc/utility/host.go` already uses for the utility host —
-// strip flags that the local FlagSet does not declare, swallowing the
-// next token when the unknown flag clearly takes one. The allow-list is
-// the same generated `HostFlagAllowList` shared by both consumers
+// `flag.NewFlagSet(..., flag.ContinueOnError).Parse` returns an error on the
+// first unknown flag it sees, which the command reports as status two. A tsgo
+// option forwarded from the JS launcher would therefore reject the build before
+// tsgo's own option table could consume it. This mirrors the strategy
+// `packages/ttsc/utility/host.go` uses for the utility host: strip flags that
+// the local FlagSet does not declare, swallowing the next token when the
+// unknown flag clearly takes one. The allow-list is the same generated
+// `HostFlagAllowList` shared by both consumers
 // (`packages/ttsc/cmd/ttsc/flags_gen.go` and
 // `packages/ttsc/utility/flags_gen.go`).
 
 package main
 
-import "strings"
+import (
+  "flag"
+  "strings"
+)
 
 // filterHostArgs strips flags that the cmd/ttsc FlagSet does not declare,
 // so a forwarded tsgo option from the JS launcher (e.g. `--strict`) does
-// not make `fs.Parse` exit 2 before the build can hand it to tsgo via
-// `--tsgo-args=<JSON>`. Flags absent from `HostFlagAllowList` are
+// not make `fs.Parse` return an error, reported by the command as status two,
+// before the build can hand it to tsgo via
+// `--tsgo-args=<JSON>`. Flags absent from `HostFlagAllowList` are
 // dropped together with their value token when they clearly take one
 // (no inline `=` and the next token does not start with `-`).
 //
 // The allow-list itself is generated from
-// `packages/ttsc/src/flags/schema.ts` (see `flags_gen.go`); editing it
+// `packages/ttsc/src/flags/FLAG_SCHEMA.ts` (see `flags_gen.go`); editing it
 // means editing the schema and re-running `pnpm format`, not patching
 // this file.
 func filterHostArgs(args []string) []string {
+  return filterDeclaredHostArgs(args, nil)
+}
+
+// filterDeclaredHostArgs supplements the public allow-list with the command's
+// actual local declarations. Private protocol flags need no public schema entry;
+// a nil local set preserves the established public filtering behavior.
+func filterDeclaredHostArgs(args []string, local *flag.FlagSet) []string {
   filtered := make([]string, 0, len(args))
   for i := 0; i < len(args); i++ {
     current := args[i]
@@ -44,6 +54,13 @@ func filterHostArgs(args []string) []string {
     }
     name, hasInlineValue := splitFlagName(current)
     takesValue, ok := HostFlagAllowList[name]
+    if !ok && local != nil {
+      if declared := local.Lookup(name); declared != nil {
+        boolean, isBoolean := declared.Value.(interface{ IsBoolFlag() bool })
+        takesValue = !isBoolean || !boolean.IsBoolFlag()
+        ok = true
+      }
+    }
     if ok {
       filtered = append(filtered, current)
       if takesValue && !hasInlineValue && i+1 < len(args) {
@@ -64,7 +81,7 @@ func filterHostArgs(args []string) []string {
 // (`--foo=value`).
 //
 // Lower-casing is the same normalization `normalizeFlagToken` in
-// `packages/ttsc/src/flags/schema.ts` applies, and the generated
+// `packages/ttsc/src/flags/normalizeFlagToken.ts` applies, and the generated
 // `HostFlagAllowList` keys are produced by it. TypeScript's option parser
 // matches option names case-insensitively, so keying this lookup on the exact
 // spelling would make the Go layer stop recognising a flag the launcher and the

package/cmd/ttsc/filter_resolves_flag_names_case_insensitively_test.go

@@ -5,21 +5,18 @@ import (
   "testing"
 )
 
-// TestFilterHostArgsResolvesFlagNamesCaseInsensitively verifies the host
-// allow-list lookup applies the same flag-name normalization the schema uses
-// when it generates that allow-list.
+// TestFilterHostArgsResolvesFlagNamesCaseInsensitively verifies case-insensitive host filtering preserves known argv and removes unknown values.
 //
-// TypeScript's option parser matches option names case-insensitively, and
-// `normalizeFlagToken` in `packages/ttsc/src/flags/schema.ts` is the one
-// normalization every layer keys off — including `buildGoAllowList`, whose
-// output is `flags_gen.go`. Keying this lookup on the exact spelling while the
-// generated keys are normalized would recreate the split-brain one layer
-// further down: a flag the launcher and the compiler both resolve would be
-// dropped here, silently taking the following token with it.
+// The filter looks up lower-case generated option names but deliberately preserves original token spelling. Exact output argv assertions observe filtering only; they do not prove that the subsequent Go FlagSet accepts an upper-case spelling.
 //
-//  1. A case-variant known flag survives with its value.
-//  2. A case-variant boolean known flag survives and does not eat the next token.
-//  3. An unknown flag is still dropped in every casing, with its value.
+// 1. Filter case-variant value and boolean options.
+// 2. Compare surviving token arrays with literal expectations.
+// 3. Filter an unknown mixed-case option together with its separate value.
+//
+// @evidence contracts/testing.md#behavioral-verification Direct filterHostArgs returns exactly the literal retained argv for upper-case value/boolean keys and removes a mixed-case unknown option plus its value.
+// @evidence contracts/testing.md#independent-expectations Authored input/output arrays distinguish known-name normalization, boolean operand ownership and unknown stripping without generating expected argv from the filter or its allow-list.
+// @evidence contracts/testing.md#distinguishing-cases Known case-variant value, known case-variant boolean and unknown mixed-case value cases contrast preservation and removal; the companion filter test owns inline values and double-dash boundaries.
+// @evidence contracts/testing.md#execution-ownership This portable same-process Go unit calls the actual private argv filter with no fixture, compiler load, installed host or process. Named table subtests retain each input and failure identity; subsequent FlagSet parsing is outside the asserted operation.
 func TestFilterHostArgsResolvesFlagNamesCaseInsensitively(t *testing.T) {
   cases := []struct {
     name string

package/cmd/ttsc/filter_strips_unknown_forwarded_flag_test.go

@@ -5,24 +5,18 @@ import (
   "testing"
 )
 
-// TestFilterHostArgsStripsUnknownForwardedFlag verifies cmd/ttsc's
-// filterHostArgs drops forwarded tsgo options before fs.Parse so the
-// FlagSet does not exit 2.
+// TestFilterHostArgsStripsUnknownForwardedFlag verifies forwarded unknown options are removed while declared argv and double-dash tails survive.
 //
-// `cmd/ttsc/{build,api_compile,api_transform}.go` use
-// `flag.NewFlagSet(..., flag.ContinueOnError)` which exits non-zero on
-// the first unknown flag it sees. The schema-generated allow-list in
-// `flags_gen.go` (`HostFlagAllowList`) feeds this filter so a forwarded
-// `--strict` from the JS launcher reaches the tsgo lane via
-// `--tsgo-args=<JSON>` instead of crashing the build. This pins the
-// behavior RCA #4 flagged as "next likely bug — `cmd/ttsc/build.go:42`
-// uses bare `flag.FlagSet` with no filter and will exit".
+// The filter prevents unknown forwarded options from reaching a local ContinueOnError FlagSet through this argument lane. ContinueOnError returns a parsing error; this unit asserts exact filtering results and does not run the downstream parser or prove forwarded compiler-option delivery.
 //
-//  1. Known flags + values survive (long form and `=` form).
-//  2. Unknown flag with separate value (`--strict true`) is dropped
-//     together with its value.
-//  3. Unknown flag with inline value (`--target=ES2022`) is dropped.
-//  4. `--` separator and everything after survives verbatim.
+// 1. Preserve declared value, inline-value and boolean argv.
+// 2. Remove unknown options with separate and inline values.
+// 3. Preserve double-dash and the entire remaining token tail.
+//
+// @evidence contracts/testing.md#behavioral-verification Direct filterHostArgs produces exact literal argv arrays for known options, unknown separate/inline options and the double-dash tail.
+// @evidence contracts/testing.md#independent-expectations Literal expected arrays follow independently from local host-option ownership and the double-dash boundary; they are not computed from actual output or generated allow-list contents.
+// @evidence contracts/testing.md#distinguishing-cases Positive known-option preservation contrasts unknown value removal, with inline and separate values and a terminal double-dash boundary; case normalization belongs to the companion filter unit.
+// @evidence contracts/testing.md#execution-ownership This portable Go unit calls the actual private filtering operation and keeps four named subcases. It performs no FlagSet parse, native Program load, fixture access or subprocess; downstream command status and tsgo forwarding remain other owners.
 func TestFilterHostArgsStripsUnknownForwardedFlag(t *testing.T) {
   cases := []struct {
     name string

package/cmd/ttsc/flags_gen.go

@@ -1,6 +1,6 @@
 // Code generated by packages/ttsc/scripts/gen-flags.mts. DO NOT EDIT.
 //
-// Source of truth: packages/ttsc/src/flags/schema.ts.
+// Source of truth: packages/ttsc/src/flags/FLAG_SCHEMA.ts.
 // Regenerate with:    pnpm format
 // Verify in CI with:  node packages/ttsc/scripts/check-flags.cjs
 
@@ -10,7 +10,7 @@ package main
 // value is true when the flag carries a separate value token (--flag VALUE
 // or --flag=VALUE) and false when the flag is boolean (--flag).
 //
-// Generated from packages/ttsc/src/flags/schema.ts. Edit the schema, not
+// Generated from packages/ttsc/src/flags/FLAG_SCHEMA.ts. Edit the schema, not
 // this file.
 var HostFlagAllowList = map[string]bool{
   "checkers":       true,

package/cmd/ttsc/helpers_test.go

@@ -9,14 +9,39 @@ import (
   _ "unsafe"
 )
 
-// driverPluginRegistry is a linkname alias for the unexported plugin slice in
-// the driver package, allowing tests to reset registered plugins between cases.
+// driverPluginRegistry aliases the driver's ordered test-visible registration slice.
+//
+// The unsafe linkname binds the actual private registry; it is not a public
+// driver API. Registry-reset tests share this process-global state and remain
+// sequential. A reset clears entries rather than preserving a prior snapshot.
+//
+// Private declarations retain native grounds; unsupported exported-host
+// Evidence annotations are not attached to this linkname fixture.
+// Common: Principled implementation: The linkname points at the actual driver.pluginRegistry rather than a duplicated test-only registry; plugin fixtures use real RegisterPlugin.
+// Common: Clear and simple design: One alias exposes the same ordered []any storage for the test reset operation.
+// Common: Prohibited implementation shortcuts: No public product export or fake registration result is introduced; the compiler/linker coupling to the private registry remains explicit.
+// Common: Meaningful documentation: Native prose states unsafe package coupling, shared-state sequencing and the difference between clearing and snapshot restoration.
+// Applicability: This borrowed registry alias performs no filesystem/process operation, processing algorithm, equivalent-work coordination or independent lease cleanup; tests and reset consumers own those decisions.
 //
 //go:linkname driverPluginRegistry github.com/samchon/ttsc/packages/ttsc/driver.pluginRegistry
 var driverPluginRegistry []any
 
-// captureCommand redirects the package-level stdout/stderr/getwd seams around
-// fn, then returns the exit code and the captured output strings.
+// captureCommand captures complete native stdout/stderr bytes around a real call.
+//
+// The actual fn executes synchronously with package-local writer seams. Its
+// supplied cwd reader is left unchanged unless fn deliberately replaces it;
+// defer restores both streams and getwd even after panic or test Goexit.
+// Tests using these process-global seams must remain sequential.
+//
+// Private helpers retain native review grounds rather than exported-host tags.
+// Common: Principled implementation: The supplied real operation returns its actual status; two buffers preserve every observed stream byte, including successful stderr.
+// Common: Clear and simple design: One synchronous call owns stream capture and one defer restores the three previous package seams.
+// Common: Prohibited implementation shortcuts: The helper neither fabricates status/output nor caches a response; test-specific cwd failures remain explicit inside fn.
+// Common: Meaningful documentation: Native prose identifies full byte capture, sequential global state and real resolver versus test error-reader ownership.
+// Portability: OS-neutral implementation: Go writers preserve native output bytes without shell interpretation, path rewriting or a real child process.
+// Performance: Efficient algorithms: Buffers accumulate each stream with work proportional to actual bytes; there is no independent byte ceiling.
+// Performance: Reuse equivalent work: Each supplied operation executes once; no previous command response is reused.
+// Performance: Bound retention and release resources: Deferred restoration covers normal return, panic and Goexit; returned strings own captured bytes for the caller. Program/fixture/registry/environment cleanup belongs to the tests and command operations.
 func captureCommand(t *testing.T, fn func() int) (int, string, string) {
   t.Helper()
   prevOut, prevErr, prevGetwd := stdout, stderr, getwd
@@ -32,14 +57,36 @@ func captureCommand(t *testing.T, fn func() int) (int, string, string) {
   return code, out.String(), err.String()
 }
 
-// failGetwd is a getwd stub that always returns an error, used to exercise the
-// cwd-resolution failure path in command entrypoints.
+// failGetwd supplies the literal cwd failure used by command-wrapper cases.
+//
+// It is an explicit test reader, not an OS-directory result or a product cwd
+// implementation. Each capture owner restores the previous getwd seam.
+//
+// Private helpers retain native common grounds without unsupported tags.
+// Common: Principled implementation: One independently authored cwd boom error forces the command's real cwd-resolution error branch.
+// Common: Clear and simple design: The reader returns an empty directory string and one fixed error.
+// Common: Prohibited implementation shortcuts: It does not manufacture the wrapper's status or diagnostic; the owning command must propagate the actual supplied cause.
+// Common: Meaningful documentation: Native prose names the fixture error and its capture-owned seam restoration.
+// Applicability: This fixed in-process error reader does no native directory discovery, reusable work, input-processing algorithm or resource acquisition.
 func failGetwd() (string, error) {
   return "", errors.New("cwd boom")
 }
 
-// writeCommandProjectFile writes contents to root/name, creating intermediate
-// directories as needed. Slashes in name are normalised to the OS separator.
+// writeCommandProjectFile materializes authored fixture bytes under a test root.
+//
+// Native Join/FromSlash resolve the caller's fixture path, MkdirAll prepares its
+// parents and WriteFile supplies the actual compiler input. The caller owns
+// the temporary root and any intentional source/config mutation sequence.
+//
+// Private helpers retain native review grounds rather than exported-host tags.
+// Common: Principled implementation: Actual native filesystem writes materialize the caller's authored bytes for real command resolution and compilation.
+// Common: Clear and simple design: One path resolution, parent creation and write implement the fixture operation; errors fail the owning test.
+// Common: Prohibited implementation shortcuts: No expected compiler result is written, source lookup mocked or author input silently synthesized.
+// Common: Meaningful documentation: Native prose identifies authored bytes, mutation/root ownership and actual filesystem error behavior.
+// Portability: OS-neutral implementation: filepath.Join/FromSlash and os directory/file APIs preserve native path spelling and platform semantics without shell commands.
+// Performance: Efficient algorithms: Work scales with path length, actual parent creation and the supplied byte length; the helper adds no directory walk.
+// Performance: Reuse equivalent work: Every explicit fixture write performs its requested mutation; no old materialization is replayed or claimed equivalent.
+// Performance: Bound retention and release resources: The byte conversion is local to synchronous WriteFile, whose native file handle closes before return; TempDir callers own root cleanup and this helper has no output-size bound or retained cache.
 func writeCommandProjectFile(t *testing.T, root, name, contents string) {
   t.Helper()
   file := filepath.Join(root, filepath.FromSlash(name))
@@ -51,8 +98,18 @@ func writeCommandProjectFile(t *testing.T, root, name, contents string) {
   }
 }
 
-// resetCommandLinkedPluginRegistry clears the driver plugin registry so that
-// tests that register plugins do not pollute subsequent test cases.
+// resetCommandLinkedPluginRegistry clears the actual ordered test registry.
+//
+// Registration cases invoke it before setup and through test cleanup after
+// consumers finish. It does not restore inherited entries or close plugin-
+// owned resources; those are separate ownership decisions.
+//
+// Private helpers retain native common grounds without unsupported tags.
+// Common: Principled implementation: Setting the actual linked registry alias to nil prevents previously registered fixture hooks from pairing with later manifest entries.
+// Common: Clear and simple design: One global slice assignment clears all registrations.
+// Common: Prohibited implementation shortcuts: This is explicit test isolation, not fabricated hook output or a public product registration API; prior state preservation is not claimed.
+// Common: Meaningful documentation: Native prose distinguishes clearing, cleanup timing and plugin resource/snapshot limitations.
+// Applicability: This in-process assignment performs no native path/process operation, processing algorithm or equivalent-work coordination. It releases registry references only; caller cleanup owns test lifetime and plugin resources.
 func resetCommandLinkedPluginRegistry() {
   driverPluginRegistry = nil
 }

package/cmd/ttsc/main.go

@@ -1,12 +1,7 @@
 // Command ttsc is the Go CLI entrypoint for ttsc.
 //
-// Current responsibilities:
-//   - Report version and platform (`ttsc --version`).
-//   - Host the native project build and check paths used by plugin-selected
-//     sidecars and smoke tests.
-//
-// Everything below is deliberately dependency-free so that the standalone binary
-// stays small and its behavior is trivial to audit.
+// The dispatcher handles version/help requests and delegates project builds,
+// checks and JSON API requests to their compiler-backed command adapters.
 package main
 
 import (
@@ -32,45 +27,113 @@ var (
   getwd            = os.Getwd
 )
 
+// main runs the actual argv dispatcher and passes its returned status to
+// os.Exit.
+//
+// Command adapters finish their synchronous work and deferred Program cleanup
+// before run returns. Process termination owns the status transport; this
+// entry does not reinterpret the command result.
 func main() {
   os.Exit(run(os.Args[1:]))
 }
 
+// cliCommandKind carries only the actual preparation branch selected by run.
+// It introduces no command result, compiler producer or retained resource.
+// Common: Principled implementation: Values distinguish actual prepared build/help/version/API branches consumed by run; numeric values have no wire meaning.
+// Common: Clear and simple design: One private discriminator accompanies argv and status; it holds no additional dispatch state.
+// Common: Prohibited implementation shortcuts: The actual preparation gate chooses the kind; no fake public API or response cache supplies it.
+// Common: Meaningful documentation: Native prose names actual preparation ownership and absence of wire semantics.
+// Portability: OS-neutral implementation: An in-process scalar introduces no path, stream or process representation.
+// Performance: Efficient algorithms: Reading or copying the kind is constant work without input traversal.
+// Performance: Reuse equivalent work: The kind identifies an operation and does not authorize reuse of a command result.
+// Performance: Bound retention and release resources: The scalar owns no resource, buffer, Program lease or retained history.
+type cliCommandKind uint8
+
+const (
+  commandBuild cliCommandKind = iota
+  commandHelp
+  commandVersion
+  commandAPICompile
+  commandAPITransform
+)
+
+// run consumes the real command preparation and dispatches its selected
+// operation.
+//
+// A preparation error is returned immediately with its original diagnostic.
+// Successful build/API kinds delegate the prepared argv to their owning
+// adapters; help and version write through the supplied package stream and
+// return zero. The dispatcher returns the actual operation status rather than
+// owning a compiler lease itself.
 func run(args []string) int {
+  command, values, code := prepareCommandInvocation(args)
+  if code != 0 {
+    return code
+  }
+  switch command {
+  case commandHelp:
+    printHelp(stdout)
+    return 0
+  case commandVersion:
+    printVersion(stdout)
+    return 0
+  case commandAPICompile:
+    return runAPICompile(values)
+  case commandAPITransform:
+    return runAPITransform(values)
+  default:
+    return runBuild(values)
+  }
+}
+
+// prepareCommandInvocation owns the original verb/alias gate and returns
+// normalized argv to the real run dispatcher. It performs no compiler load.
+// Missing operands and unknown commands still report their original diagnostics.
+//
+// Private Go declarations are not exported Evidence hosts; native grounds
+// stay with this preparation path and its actual run consumer.
+// Common: Principled implementation: Actual verb, flag-shaped, extension and project-alias conditions preserve their original diagnostics, return status and normalized arguments before the real handler loads.
+// Common: Clear and simple design: The real dispatcher consumes one command/argv/status value; tests observe that value separately from an actual compiler operation.
+// Common: Prohibited implementation shortcuts: No duplicate test-side switch substitutes for dispatch, fake public API is introduced or previous compiler status is replayed.
+// Common: Meaningful documentation: Prose names pure preparation, actual run consumption and its retained diagnostic responsibility.
+// Portability: OS-neutral implementation: Arguments remain native values without shell interpretation or forced path separators.
+// Performance: Efficient algorithms: One verb gate and existing argument normalization perform constant branch work plus copied alias/check tail length.
+// Performance: Reuse equivalent work: Equal independently observed normalized arguments may feed one separately named real build; preparation stores no command response.
+// Performance: Bound retention and release resources: Values are synchronous caller-owned arguments; no checker lease, child, filesystem fixture or global cache is acquired.
+func prepareCommandInvocation(args []string) (cliCommandKind, []string, int) {
   if len(args) == 0 {
-    return runBuild(nil)
+    return commandBuild, nil, 0
   }
 
   switch args[0] {
   case "-h", "--help", "help":
-    printHelp(stdout)
-    return 0
+    return commandHelp, nil, 0
   case "-v", "--version", "version":
-    printVersion(stdout)
-    return 0
+    return commandVersion, nil, 0
   case "build":
-    return runBuild(args[1:])
+    return commandBuild, args[1:], 0
   case "api-compile":
-    return runAPICompile(args[1:])
+    return commandAPICompile, args[1:], 0
   case "api-transform":
-    return runAPITransform(args[1:])
+    return commandAPITransform, args[1:], 0
   case "check":
     // `ttsc check` runs the analyze pipeline without emitting JS — useful
     // in CI and pre-commit checks that only need schema validation.
-    return runBuild(append([]string{"--noEmit"}, args[1:]...))
+    return commandBuild, append([]string{"--noEmit"}, args[1:]...), 0
   case "-p", "--project":
-    if len(args) < 2 {
+    normalized, ok := normalizeProjectAliasArguments(args)
+    if !ok {
       fmt.Fprintln(stderr, "ttsc: -p/--project requires a path argument")
-      return 2
+      return commandBuild, nil, 2
     }
-    return runBuild(append([]string{"--tsconfig=" + args[1]}, args[2:]...))
+    return commandBuild, normalized, 0
   default:
     if isBuildAlias(args[0]) {
-      return runBuild(args)
+      return commandBuild, args, 0
     }
     fmt.Fprintf(stderr, "ttsc: unknown command %q\n", args[0])
     fmt.Fprintln(stderr, `ttsc: run "ttsc --help" to see supported commands`)
-    return 2
+    return commandBuild, nil, 2
   }
 }
 
@@ -78,6 +141,10 @@ func run(args []string) int {
 // requiring an explicit "build" verb. Any flag-shaped argument (leading "-")
 // or a TypeScript-project file extension is treated as a build alias, matching
 // the tsc/tsgo invocation convention.
+//
+// This predicate classifies literal argv shape only. Recognizing a .cts operand
+// selects build preparation; it does not establish that the build FlagSet uses
+// that positional token as a tsconfig selector or inspects that file.
 func isBuildAlias(arg string) bool {
   if strings.HasPrefix(arg, "-") {
     return true
@@ -94,6 +161,12 @@ func isBuildAlias(arg string) bool {
   }
 }
 
+// printVersion writes the CLI's build and current Go platform metadata.
+//
+// Linker-populated release values and development defaults share the same
+// format; runtime.GOOS, GOARCH and Version provide the executing Go platform.
+// The caller supplies the writer. This existing presentation path ignores
+// writer errors and does not determine command failure status.
 func printVersion(w io.Writer) {
   fmt.Fprintf(
     w,
@@ -107,6 +180,13 @@ func printVersion(w io.Writer) {
   )
 }
 
+// printHelp writes the supported static command usage through the supplied
+// writer.
+//
+// The authored usage text documents command forms, flags and examples;
+// trimming its surrounding whitespace preserves one presentation format. This
+// existing help path ignores writer errors, and the dispatcher owns the
+// successful help status.
 func printHelp(w io.Writer) {
   fmt.Fprintln(w, strings.TrimSpace(`
 ttsc — standalone typescript-go host.
@@ -146,3 +226,24 @@ Integration guide (bundlers):
     per-package tsconfig.json references work unchanged.
 `))
 }
+
+// normalizeProjectAliasArguments owns the exact -p/--project operand rewrite
+// consumed by run. It never loads a project or returns a cached build status.
+// Both spellings produce the same `--tsconfig=<path>` build argv.
+//
+// Go Evidence addresses exported declarations only; these private native
+// review grounds remain attached to the owning operation and its callers.
+// Common: Principled implementation: The actual preparation gate consumed by run calls this exact -p/--project operand rewrite before real runBuild.
+// Common: Clear and simple design: Missing operand is one boolean outcome and successful normalization is one newly allocated argument slice.
+// Common: Prohibited implementation shortcuts: Literal normalized argv is observed separately from a shared real build; no cached status is presented as an independently executed alias.
+// Common: Meaningful documentation: Native prose distinguishes pure operand normalization from project compilation and identifies the production consumer.
+// Portability: OS-neutral implementation: The config operand is passed as an argument value without native-separator rewriting or shell interpretation.
+// Performance: Efficient algorithms: Tail argument copying is linear in remaining argv length and makes one owning slice.
+// Performance: Reuse equivalent work: Equal literal normalization permits one separately identified real build observation; this helper never reuses a process result.
+// Performance: Bound retention and release resources: The returned normalized slice transfers to the synchronous caller and retains no previous argv or compiler state.
+func normalizeProjectAliasArguments(args []string) ([]string, bool) {
+  if len(args) < 2 {
+    return nil, false
+  }
+  return append([]string{"--tsconfig=" + args[1]}, args[2:]...), true
+}