ttsc 0.10.1 → 0.11.0-dev.20260517

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/README.md +8 -0
  2. package/cmd/ttsc/api_compile.go +106 -106
  3. package/cmd/ttsc/api_transform.go +54 -54
  4. package/cmd/ttsc/main.go +103 -103
  5. package/cmd/ttscserver/helpers_test.go +27 -0
  6. package/cmd/ttscserver/main.go +154 -0
  7. package/cmd/ttscserver/run_lsp_reports_getwd_error_test.go +34 -0
  8. package/cmd/ttscserver/run_lsp_reports_server_error_test.go +42 -0
  9. package/driver/lsp_envelope.go +136 -0
  10. package/driver/lsp_frame.go +121 -0
  11. package/driver/lsp_plugin.go +150 -0
  12. package/driver/lsp_proxy.go +394 -0
  13. package/driver/lsp_server.go +197 -0
  14. package/go.mod +4 -0
  15. package/go.sum +4 -0
  16. package/internal/cwd/cwd.go +16 -0
  17. package/lib/TtscCompiler.d.ts +15 -16
  18. package/lib/TtscCompiler.js +15 -16
  19. package/lib/TtscCompiler.js.map +1 -1
  20. package/lib/compiler/internal/compileProjectInMemory.d.ts +4 -1
  21. package/lib/compiler/internal/compileProjectInMemory.js +4 -1
  22. package/lib/compiler/internal/compileProjectInMemory.js.map +1 -1
  23. package/lib/compiler/internal/project/readProjectConfig.js.map +1 -1
  24. package/lib/compiler/internal/runBuild.js +46 -48
  25. package/lib/compiler/internal/runBuild.js.map +1 -1
  26. package/lib/compiler/internal/sharedHostHelpers.d.ts +47 -0
  27. package/lib/compiler/internal/sharedHostHelpers.js +101 -0
  28. package/lib/compiler/internal/sharedHostHelpers.js.map +1 -0
  29. package/lib/compiler/internal/transformProjectInMemory.js +2 -46
  30. package/lib/compiler/internal/transformProjectInMemory.js.map +1 -1
  31. package/lib/defineTtscPlugin.d.ts +18 -0
  32. package/lib/defineTtscPlugin.js +7 -0
  33. package/lib/defineTtscPlugin.js.map +1 -0
  34. package/lib/index.d.ts +4 -3
  35. package/lib/index.js +4 -3
  36. package/lib/index.js.map +1 -1
  37. package/lib/launcher/internal/prepareExecution.js +1 -1
  38. package/lib/launcher/internal/prepareExecution.js.map +1 -1
  39. package/lib/launcher/internal/resolveTtscserverBinary.d.ts +12 -0
  40. package/lib/launcher/internal/resolveTtscserverBinary.js +43 -0
  41. package/lib/launcher/internal/resolveTtscserverBinary.js.map +1 -0
  42. package/lib/launcher/internal/runTtsc.js +47 -8
  43. package/lib/launcher/internal/runTtsc.js.map +1 -1
  44. package/lib/launcher/internal/runTtscserver.d.ts +20 -0
  45. package/lib/launcher/internal/runTtscserver.js +125 -0
  46. package/lib/launcher/internal/runTtscserver.js.map +1 -0
  47. package/lib/launcher/internal/runTtsx.js +1 -1
  48. package/lib/launcher/internal/runTtsx.js.map +1 -1
  49. package/lib/launcher/ttscserver.d.ts +2 -0
  50. package/lib/launcher/ttscserver.js +9 -0
  51. package/lib/launcher/ttscserver.js.map +1 -0
  52. package/lib/plugin/internal/buildSourcePlugin.d.ts +9 -0
  53. package/lib/plugin/internal/buildSourcePlugin.js +197 -2
  54. package/lib/plugin/internal/buildSourcePlugin.js.map +1 -1
  55. package/lib/plugin/internal/loadProjectPlugins.js +137 -10
  56. package/lib/plugin/internal/loadProjectPlugins.js.map +1 -1
  57. package/lib/structures/ITtscCompilerContext.d.ts +1 -1
  58. package/lib/structures/ITtscCompilerDiagnostic.d.ts +3 -3
  59. package/lib/structures/ITtscCompilerResult.d.ts +10 -22
  60. package/lib/structures/ITtscCompilerTransformation.d.ts +2 -2
  61. package/lib/structures/ITtscPlugin.d.ts +37 -4
  62. package/lib/structures/ITtscPlugin.js +0 -4
  63. package/lib/structures/ITtscPlugin.js.map +1 -1
  64. package/lib/structures/ITtscPluginContributor.d.ts +26 -0
  65. package/lib/structures/ITtscPluginContributor.js +3 -0
  66. package/lib/structures/ITtscPluginContributor.js.map +1 -0
  67. package/lib/structures/ITtscPluginFactoryContext.d.ts +5 -5
  68. package/lib/structures/ITtscProjectPluginConfig.d.ts +2 -2
  69. package/lib/structures/TtscPluginStage.d.ts +4 -3
  70. package/lib/structures/index.d.ts +1 -0
  71. package/lib/structures/index.js +1 -0
  72. package/lib/structures/index.js.map +1 -1
  73. package/lib/structures/internal/ITtscLoadedNativePlugin.d.ts +3 -0
  74. package/lib/structures/internal/TtscBuildOptions.d.ts +13 -0
  75. package/lib/structures/internal/TtscCommonOptions.d.ts +5 -2
  76. package/package.json +11 -9
  77. package/shim/ast/shim.go +8 -0
  78. package/shim/checker/shim.go +8 -0
  79. package/shim/lsp/extra-shim.json +4 -0
  80. package/shim/lsp/go.mod +16 -0
  81. package/shim/lsp/go.sum +26 -0
  82. package/shim/lsp/shim.go +42 -0
  83. package/shim/printer/shim.go +5 -5
  84. package/src/TtscCompiler.ts +15 -16
  85. package/src/compiler/internal/compileProjectInMemory.ts +4 -1
  86. package/src/compiler/internal/project/readProjectConfig.ts +0 -1
  87. package/src/compiler/internal/runBuild.ts +46 -58
  88. package/src/compiler/internal/sharedHostHelpers.ts +105 -0
  89. package/src/compiler/internal/transformProjectInMemory.ts +2 -56
  90. package/src/defineTtscPlugin.ts +26 -0
  91. package/src/index.ts +4 -3
  92. package/src/launcher/internal/prepareExecution.ts +1 -1
  93. package/src/launcher/internal/resolveTtscserverBinary.ts +51 -0
  94. package/src/launcher/internal/runTtsc.ts +53 -11
  95. package/src/launcher/internal/runTtscserver.ts +92 -0
  96. package/src/launcher/internal/runTtsx.ts +1 -1
  97. package/src/launcher/ttscserver.ts +8 -0
  98. package/src/plugin/internal/buildSourcePlugin.ts +231 -12
  99. package/src/plugin/internal/loadProjectPlugins.ts +183 -17
  100. package/src/structures/ITtscCompilerContext.ts +1 -1
  101. package/src/structures/ITtscCompilerDiagnostic.ts +3 -3
  102. package/src/structures/ITtscCompilerResult.ts +10 -22
  103. package/src/structures/ITtscCompilerTransformation.ts +2 -2
  104. package/src/structures/ITtscPlugin.ts +37 -11
  105. package/src/structures/ITtscPluginContributor.ts +27 -0
  106. package/src/structures/ITtscPluginFactoryContext.ts +5 -5
  107. package/src/structures/ITtscProjectPluginConfig.ts +2 -2
  108. package/src/structures/TtscPluginStage.ts +4 -3
  109. package/src/structures/index.ts +1 -0
  110. package/src/structures/internal/ITtscLoadedNativePlugin.ts +3 -0
  111. package/src/structures/internal/TtscBuildOptions.ts +13 -0
  112. package/src/structures/internal/TtscCommonOptions.ts +5 -2
  113. package/tools/gen_shims/main.go +29 -9
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "ttsc",
3
- "version": "0.10.1",
3
+ "version": "0.11.0-dev.20260517",
4
4
  "description": "General-purpose TypeScript-Go compiler, plugin host, and runtime.",
5
5
  "main": "lib/index.js",
6
6
  "types": "lib/index.d.ts",
7
7
  "bin": {
8
8
  "ttsc": "lib/launcher/ttsc.js",
9
+ "ttscserver": "lib/launcher/ttscserver.js",
9
10
  "ttsx": "lib/launcher/ttsx.js"
10
11
  },
11
12
  "exports": {
@@ -27,17 +28,17 @@
27
28
  "homepage": "https://github.com/samchon/ttsc",
28
29
  "devDependencies": {
29
30
  "@types/node": "^25.3.0",
30
- "@typescript/native-preview": "7.0.0-dev.20260510.1",
31
+ "@typescript/native-preview": "7.0.0-dev.20260515.1",
31
32
  "rimraf": "^6.1.2"
32
33
  },
33
34
  "optionalDependencies": {
34
- "@ttsc/linux-arm": "0.10.1",
35
- "@ttsc/linux-x64": "0.10.1",
36
- "@ttsc/linux-arm64": "0.10.1",
37
- "@ttsc/darwin-arm64": "0.10.1",
38
- "@ttsc/win32-x64": "0.10.1",
39
- "@ttsc/darwin-x64": "0.10.1",
40
- "@ttsc/win32-arm64": "0.10.1"
35
+ "@ttsc/linux-x64": "0.11.0-dev.20260517",
36
+ "@ttsc/win32-x64": "0.11.0-dev.20260517",
37
+ "@ttsc/darwin-arm64": "0.11.0-dev.20260517",
38
+ "@ttsc/win32-arm64": "0.11.0-dev.20260517",
39
+ "@ttsc/linux-arm": "0.11.0-dev.20260517",
40
+ "@ttsc/linux-arm64": "0.11.0-dev.20260517",
41
+ "@ttsc/darwin-x64": "0.11.0-dev.20260517"
41
42
  },
42
43
  "sideEffects": false,
43
44
  "files": [
@@ -46,6 +47,7 @@
46
47
  "driver",
47
48
  "go.mod",
48
49
  "go.sum",
50
+ "internal",
49
51
  "package.json",
50
52
  "lib",
51
53
  "shim",
package/shim/ast/shim.go CHANGED
@@ -1,3 +1,11 @@
1
+ // gen_shims:hand-maintained
2
+ //
3
+ // This shim file mixes generated re-exports with hand-written `go:linkname`
4
+ // declarations (see GetSourceFileOfNode / GetNodeAtPosition below). gen_shims
5
+ // detects the marker on the first line and skips this file. Remove the marker
6
+ // only if you are intentionally regenerating and willing to re-add the
7
+ // hand-maintained content.
8
+
1
9
  package ast
2
10
 
3
11
  import (
@@ -1,3 +1,11 @@
1
+ // gen_shims:hand-maintained
2
+ //
3
+ // This shim file mixes generated re-exports with hand-written `go:linkname`
4
+ // declarations targeting unexported `*Checker` methods that the @ttsc/lint
5
+ // engine relies on. gen_shims detects the marker on the first line and skips
6
+ // this file. Remove the marker only if you are intentionally regenerating and
7
+ // willing to re-add the hand-maintained content.
8
+
1
9
  package checker
2
10
 
3
11
  import (
@@ -0,0 +1,4 @@
1
+ {
2
+ "ExtraMethods": {},
3
+ "ExtraFields": {}
4
+ }
@@ -0,0 +1,16 @@
1
+ module github.com/microsoft/typescript-go/shim/lsp
2
+
3
+ go 1.26
4
+
5
+ require github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157
6
+
7
+ require (
8
+ github.com/Microsoft/go-winio v0.6.2 // indirect
9
+ github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 // indirect
10
+ github.com/klauspost/cpuid/v2 v2.2.10 // indirect
11
+ github.com/mackerelio/go-osstat v0.2.7 // indirect
12
+ github.com/zeebo/xxh3 v1.1.0 // indirect
13
+ golang.org/x/sync v0.20.0 // indirect
14
+ golang.org/x/sys v0.43.0 // indirect
15
+ golang.org/x/text v0.36.0 // indirect
16
+ )
@@ -0,0 +1,26 @@
1
+ github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
2
+ github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
3
+ github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433 h1:vymEbVwYFP/L05h5TKQxvkXoKxNvTpjxYKdF1Nlwuao=
4
+ github.com/go-json-experiment/json v0.0.0-20260214004413-d219187c3433/go.mod h1:tphK2c80bpPhMOI4v6bIc2xWywPfbqi1Z06+RcrMkDg=
5
+ github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
6
+ github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
7
+ github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
8
+ github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
9
+ github.com/mackerelio/go-osstat v0.2.7 h1:TCavZi10wF49bT6iQZ9eT2keGZQpC69MTDfdJej5e94=
10
+ github.com/mackerelio/go-osstat v0.2.7/go.mod h1:dwpYh5pIPmvk+IEwBKNIWRFMB92mrC08CmXOhDC7nQk=
11
+ github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157 h1:llOMPhKDiQ+UEJiAaQuuWaJOTg5V7tNNTEf9JPWoYSY=
12
+ github.com/microsoft/typescript-go v0.0.0-20260429010842-56ab4af42157/go.mod h1:m8YA0PMC7ti0GW0RI05D6fEcjQeu98XVS+FWF+VDW2k=
13
+ github.com/peter-evans/patience v0.3.0 h1:rX0JdJeepqdQl1Sk9c9uvorjYYzL2TfgLX1adqYm9cA=
14
+ github.com/peter-evans/patience v0.3.0/go.mod h1:Kmxu5sY1NmBLFSStvXjX1wS9mIv7wMcP/ubucyMOAu0=
15
+ github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
16
+ github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
17
+ github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
18
+ github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
19
+ golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
20
+ golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
21
+ golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
22
+ golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
23
+ golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
24
+ golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
25
+ gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
26
+ gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=
@@ -0,0 +1,42 @@
1
+ // gen_shims:hand-maintained
2
+ //
3
+ // Minimal shim of tsgo's internal/lsp package. Hand-written instead of
4
+ // generated so the surface stays narrow: ttscserver embeds the tsgo LSP
5
+ // server unmodified and intercepts traffic at the byte level, so the only
6
+ // types it touches are the opaque Server, its options struct, and the
7
+ // Reader/Writer interfaces that ToReader/ToWriter return. The marker on
8
+ // the first line tells gen_shims to skip this file.
9
+ package lsp
10
+
11
+ import (
12
+ "io"
13
+ _ "unsafe"
14
+
15
+ innerlsp "github.com/microsoft/typescript-go/internal/lsp"
16
+ )
17
+
18
+ // Server is the opaque LSP server type from tsgo. ttscserver does not poke
19
+ // its internals; it only calls Run and (via wrapped Writer) observes the
20
+ // traffic the server emits.
21
+ type Server = innerlsp.Server
22
+
23
+ // ServerOptions mirrors the upstream construction parameters. Fields with
24
+ // internal-package types (e.g. ParseCache *project.ParseCache) are left
25
+ // unset by ttscserver, which is safe because every such field is an
26
+ // optional pointer the upstream constructor accepts as nil.
27
+ type ServerOptions = innerlsp.ServerOptions
28
+
29
+ // Reader / Writer carry framed lsproto.Message values. ttscserver feeds
30
+ // the server through io.Pipe shims of these so it can splice its own
31
+ // JSON-RPC traffic into the same stream the editor speaks.
32
+ type Reader = innerlsp.Reader
33
+ type Writer = innerlsp.Writer
34
+
35
+ //go:linkname NewServer github.com/microsoft/typescript-go/internal/lsp.NewServer
36
+ func NewServer(opts *ServerOptions) *Server
37
+
38
+ //go:linkname ToReader github.com/microsoft/typescript-go/internal/lsp.ToReader
39
+ func ToReader(r io.Reader) Reader
40
+
41
+ //go:linkname ToWriter github.com/microsoft/typescript-go/internal/lsp.ToWriter
42
+ func ToWriter(w io.Writer) Writer
@@ -1,8 +1,8 @@
1
1
  package printer
2
2
 
3
3
  import (
4
- "github.com/microsoft/typescript-go/internal/ast"
5
- innerprinter "github.com/microsoft/typescript-go/internal/printer"
4
+ "github.com/microsoft/typescript-go/internal/ast"
5
+ innerprinter "github.com/microsoft/typescript-go/internal/printer"
6
6
  )
7
7
 
8
8
  type PrintHandlers = innerprinter.PrintHandlers
@@ -11,13 +11,13 @@ type PrinterOptions = innerprinter.PrinterOptions
11
11
  type EmitContext = innerprinter.EmitContext
12
12
 
13
13
  func NewPrinter(options PrinterOptions, handlers PrintHandlers, emitContext *EmitContext) *Printer {
14
- return innerprinter.NewPrinter(options, handlers, emitContext)
14
+ return innerprinter.NewPrinter(options, handlers, emitContext)
15
15
  }
16
16
 
17
17
  func NewEmitContext() *EmitContext {
18
- return innerprinter.NewEmitContext()
18
+ return innerprinter.NewEmitContext()
19
19
  }
20
20
 
21
21
  func EmitSourceFile(p *Printer, sourceFile *ast.SourceFile) string {
22
- return p.EmitSourceFile(sourceFile)
22
+ return p.EmitSourceFile(sourceFile)
23
23
  }
@@ -15,23 +15,22 @@ import type { TtscBuildResult } from "./structures/internal/TtscBuildResult";
15
15
  /**
16
16
  * Programmatic compiler host for the `ttsc` TypeScript-Go pipeline.
17
17
  *
18
- * `TtscCompiler` is the root JavaScript API exported by the `ttsc` package.
19
- * It represents one resolved project context: a working directory, an optional
20
- * project config path, an optional native toolchain override, an environment,
21
- * a cache root, and a plugin list. Those values are captured by the
22
- * constructor and are intentionally not replaceable per method call.
18
+ * `TtscCompiler` is the root JavaScript API exported by the `ttsc` package. It
19
+ * represents one resolved project context: a working directory, an optional
20
+ * project config path, an optional native toolchain override, an environment, a
21
+ * cache root, and a plugin list. Those values are captured by the constructor
22
+ * and are intentionally not replaceable per method call.
23
23
  *
24
24
  * The class exposes only the operations that make sense for an embedded
25
25
  * compiler host:
26
26
  *
27
27
  * - {@link TtscCompiler.prepare}: build configured Go source plugins into the
28
28
  * cache before a later compile.
29
- * - {@link TtscCompiler.clean}: remove the cache owned by this compiler
30
- * context.
29
+ * - {@link TtscCompiler.clean}: remove the cache owned by this compiler context.
31
30
  * - {@link TtscCompiler.compile}: compile the configured project and return a
32
31
  * structured result instead of terminal text.
33
- * - {@link TtscCompiler.transform}: transform the configured project and
34
- * return an embed-style transformation result.
32
+ * - {@link TtscCompiler.transform}: transform the configured project and return an
33
+ * embed-style transformation result.
35
34
  */
36
35
  export class TtscCompiler {
37
36
  private readonly context: ITtscCompilerContext;
@@ -106,14 +105,14 @@ export class TtscCompiler {
106
105
  *
107
106
  * The public API does not write emitted files into the caller's project tree.
108
107
  * For projects without plugins, ttsc uses its native TypeScript-Go host's
109
- * `WriteFile` callback to capture output in memory. For projects with
110
- * native plugins, ttsc runs the plugin pipeline against a temporary output
108
+ * `WriteFile` callback to capture output in memory. For projects with native
109
+ * plugins, ttsc runs the plugin pipeline against a temporary output
111
110
  * directory, reads the generated text artifacts, and removes the temporary
112
111
  * directory before returning.
113
112
  *
114
- * The result uses an `embed-typescript`-style discriminated union:
115
- * `success` for clean compiles, `failure` for normal compiler diagnostics,
116
- * and `exception` for host setup or process failures.
113
+ * The result uses an `embed-typescript`-style discriminated union: `success`
114
+ * for clean compiles, `failure` for normal compiler diagnostics, and
115
+ * `exception` for host setup or process failures.
117
116
  *
118
117
  * @returns Structured compilation result containing diagnostics or output.
119
118
  */
@@ -127,8 +126,8 @@ export class TtscCompiler {
127
126
  * This is the source-to-source API for plugin authors. It must not return
128
127
  * JavaScript emit, declaration files, or source maps; those artifacts belong
129
128
  * to {@link TtscCompiler.compile}. A transform sidecar is expected to write
130
- * JSON shaped as `{ "typescript": { "src/file.ts": "..." } }` to stdout.
131
- * When no transform sidecar is configured, ttsc returns the TypeScript files
129
+ * JSON shaped as `{ "typescript": { "src/file.ts": "..." } }` to stdout. When
130
+ * no transform sidecar is configured, ttsc returns the TypeScript files
132
131
  * loaded by the TypeScript-Go Program together with normal diagnostics.
133
132
  *
134
133
  * The returned shape mirrors `embed-typescript`'s transformation API:
@@ -12,7 +12,10 @@ import { buildNativeCompiler } from "./buildNativeCompiler";
12
12
  import { readProjectConfig } from "./project/readProjectConfig";
13
13
  import { runBuild } from "./runBuild";
14
14
 
15
- /** Compile a project and capture emitted files without writing to the project tree. */
15
+ /**
16
+ * Compile a project and capture emitted files without writing to the project
17
+ * tree.
18
+ */
16
19
  export function compileProjectInMemory(options: ITtscCompilerContext): {
17
20
  output: Record<string, string>;
18
21
  result: TtscBuildResult;
@@ -5,7 +5,6 @@ import path from "node:path";
5
5
  import type { ITtscProjectPluginConfig } from "../../../structures/ITtscProjectPluginConfig";
6
6
  import type { ITtscParsedProjectConfig } from "../../../structures/internal/ITtscParsedProjectConfig";
7
7
  import type { ITtscProjectLocatorOptions } from "../../../structures/internal/ITtscProjectLocatorOptions";
8
-
9
8
  import { resolveProjectConfig } from "./resolveProjectConfig";
10
9
 
11
10
  const PATH_OPTIONS = new Set(["baseUrl", "declarationDir", "rootDir"]);
@@ -12,6 +12,7 @@ import type { TtscCommonOptions } from "../../structures/internal/TtscCommonOpti
12
12
  import { resolveProjectConfig } from "./project/resolveProjectConfig";
13
13
  import { resolveBinary } from "./resolveBinary";
14
14
  import { resolveTsgo } from "./resolveTsgo";
15
+ import { assertSharedHostCompatibility } from "./sharedHostHelpers";
15
16
 
16
17
  /** Merge spawn env without clobbering unrelated vars. */
17
18
  function mergeEnv(extra?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
@@ -105,8 +106,23 @@ export function runBuild(
105
106
  }
106
107
 
107
108
  if (options.emit === false) {
109
+ if (options.format === true) {
110
+ // Format mode is write-only by contract: the lint sidecar
111
+ // already rewrote source files and reported nothing. Running
112
+ // tsgo --noEmit OR a transform compiler afterwards would either
113
+ // surface unrelated type errors as if they were format failures
114
+ // (tsgo path) or apply transform-stage rewrites on top of the
115
+ // formatted source (transform path), both of which break the
116
+ // documented "ttsc format only formats" guarantee. The
117
+ // short-circuit fires before either branch so format mode is a
118
+ // single concern regardless of how many compilers the project
119
+ // configures. Callers that want a recheck or a transform pass
120
+ // after format should run `ttsc check` / `ttsc build` as a
121
+ // separate invocation.
122
+ return checked;
123
+ }
108
124
  if (compilers.length !== 0) {
109
- assertCompilerHostCompatibility(compilers);
125
+ assertSharedHostCompatibility(compilers, "emit");
110
126
  return appendBuildOutput(
111
127
  checked,
112
128
  buildWithNativeCompilerPlugins(options, execution, compilers),
@@ -120,7 +136,7 @@ export function runBuild(
120
136
 
121
137
  let result: TtscBuildResult;
122
138
  if (compilers.length !== 0) {
123
- assertCompilerHostCompatibility(compilers);
139
+ assertSharedHostCompatibility(compilers, "emit");
124
140
  result = appendBuildOutput(
125
141
  checked,
126
142
  buildWithNativeCompilerPlugins(options, execution, compilers),
@@ -142,6 +158,21 @@ export function runBuild(
142
158
  return result;
143
159
  }
144
160
 
161
+ if (options.format === true) {
162
+ // Format mode is write-only by contract — see the matching
163
+ // short-circuit in the with-native-plugins branch above. When no
164
+ // native plugin is loaded there is nothing for `ttsc format` to
165
+ // rewrite, so emit an empty success result rather than falling
166
+ // through to a tsgo pass that would surface unrelated type errors
167
+ // as if they were format failures.
168
+ return {
169
+ diagnostics: [],
170
+ status: 0,
171
+ stdout: "",
172
+ stderr: "",
173
+ };
174
+ }
175
+
145
176
  if (options.emit !== false && options.skipDiagnosticsCheck !== true) {
146
177
  const checked = runTsgo(execution, ["--noEmit"], options);
147
178
  if (checked.status !== 0) {
@@ -297,7 +328,7 @@ function createNativeCheckArgs(
297
328
  options: TtscBuildOptions,
298
329
  ): string[] {
299
330
  const args = [
300
- "check",
331
+ nativeCheckSubcommand(options),
301
332
  "--tsconfig=" + execution.tsconfig,
302
333
  "--plugins-json=" + serializeNativePlugins(execution.nativePlugins),
303
334
  "--cwd=" + execution.projectRoot,
@@ -313,6 +344,18 @@ function createNativeCheckArgs(
313
344
  return args;
314
345
  }
315
346
 
347
+ /**
348
+ * Decide which native plugin subcommand the lint sidecar should run for the
349
+ * current `runBuild` invocation. The launcher selects exactly one of `fix` /
350
+ * `format` / `check` via subcommand dispatch, so at most one of the
351
+ * `options.fix` / `options.format` booleans is true.
352
+ */
353
+ function nativeCheckSubcommand(options: TtscBuildOptions): string {
354
+ if (options.format === true) return "format";
355
+ if (options.fix === true) return "fix";
356
+ return "check";
357
+ }
358
+
316
359
  function serializeNativePlugins(
317
360
  plugins: readonly ITtscLoadedNativePlugin[],
318
361
  ): string {
@@ -394,61 +437,6 @@ export function appendBuildOutput(
394
437
  });
395
438
  }
396
439
 
397
- function assertCompilerHostCompatibility(
398
- plugins: readonly ITtscLoadedNativePlugin[],
399
- ): void {
400
- const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
401
- if (binaries.length <= 1) {
402
- return;
403
- }
404
- if (plugins.every(isFirstPartyUtilityTransformPlugin)) {
405
- return;
406
- }
407
- throw new Error(
408
- "ttsc: multiple compiler native backends cannot share one emit pass; " +
409
- "compose transform libraries through one aggregate native host",
410
- );
411
- }
412
-
413
- function isFirstPartyUtilityTransformPlugin(
414
- plugin: ITtscLoadedNativePlugin,
415
- ): boolean {
416
- if (plugin.stage !== "transform") return false;
417
- if (!firstPartyUtilityPluginNames.has(plugin.name)) return false;
418
- const manifest = readNearestPackageManifest(plugin.source);
419
- return manifest?.name === plugin.name;
420
- }
421
-
422
- const firstPartyUtilityPluginNames = new Set([
423
- "@ttsc/banner",
424
- "@ttsc/paths",
425
- "@ttsc/strip",
426
- ]);
427
-
428
- function readNearestPackageManifest(
429
- source: string,
430
- ): { name?: unknown } | undefined {
431
- try {
432
- let current = fs.statSync(source).isDirectory()
433
- ? source
434
- : path.dirname(source);
435
- for (let i = 0; i < 4; i += 1) {
436
- const manifest = path.join(current, "package.json");
437
- if (fs.existsSync(manifest)) {
438
- return JSON.parse(fs.readFileSync(manifest, "utf8")) as {
439
- name?: unknown;
440
- };
441
- }
442
- const parent = path.dirname(current);
443
- if (parent === current) break;
444
- current = parent;
445
- }
446
- } catch {
447
- return undefined;
448
- }
449
- return undefined;
450
- }
451
-
452
440
  function resolveExecutionContext(
453
441
  options: TtscCommonOptions & { tsconfig?: string },
454
442
  ) {
@@ -0,0 +1,105 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ import type { ITtscLoadedNativePlugin } from "../../structures/internal/ITtscLoadedNativePlugin";
5
+
6
+ /**
7
+ * Names of the first-party utility transform plugins that are allowed to share
8
+ * one compiler emit / one source-to-source pass even when their resolved
9
+ * binaries differ. Each entry must be both name-pinned and manifest-pinned: the
10
+ * plugin must declare itself with one of these names AND its source path must
11
+ * resolve to a `package.json` whose `name` field matches.
12
+ *
13
+ * This whitelist exists because `@ttsc/banner`, `@ttsc/paths`, and
14
+ * `@ttsc/strip` are AST-only mutators that operate on the same
15
+ * `*shimast.SourceFile` graph and do not own emit. They are composed through
16
+ * `packages/ttsc/utility/host.go`, so any one of their binaries can host the
17
+ * shared run. Third-party plugins cannot participate in this fast path; they
18
+ * must opt into composition through the explicit `ITtscPlugin.composes` field.
19
+ */
20
+ export const FIRST_PARTY_UTILITY_PLUGIN_NAMES: ReadonlySet<string> = new Set([
21
+ "@ttsc/banner",
22
+ "@ttsc/paths",
23
+ "@ttsc/strip",
24
+ ]);
25
+
26
+ /**
27
+ * Reports whether the given plugin is a first-party utility transform plugin
28
+ * that may participate in the shared compiler host alongside other first-party
29
+ * utility transforms. Returns `false` for `check`-stage plugins, for unknown
30
+ * names, and for plugins whose `source` does not resolve to a matching
31
+ * `package.json`.
32
+ */
33
+ export function isFirstPartyUtilityTransformPlugin(
34
+ plugin: ITtscLoadedNativePlugin,
35
+ ): boolean {
36
+ if (plugin.stage !== "transform") return false;
37
+ if (!FIRST_PARTY_UTILITY_PLUGIN_NAMES.has(plugin.name)) return false;
38
+ const manifest = readNearestPackageManifest(plugin.source);
39
+ return manifest?.name === plugin.name;
40
+ }
41
+
42
+ /**
43
+ * Walks upward from `source` (a directory or file path) up to four parent
44
+ * levels searching for the nearest `package.json`. Returns the parsed manifest
45
+ * object on success, or `undefined` when no manifest is found or parsing fails.
46
+ * The depth bound mirrors the pre-existing inline implementations in
47
+ * `runBuild.ts` and `transformProjectInMemory.ts`.
48
+ */
49
+ export function readNearestPackageManifest(
50
+ source: string,
51
+ ): { name?: unknown } | undefined {
52
+ try {
53
+ let current = fs.statSync(source).isDirectory()
54
+ ? source
55
+ : path.dirname(source);
56
+ for (let i = 0; i < 4; i += 1) {
57
+ const manifest = path.join(current, "package.json");
58
+ if (fs.existsSync(manifest)) {
59
+ return JSON.parse(fs.readFileSync(manifest, "utf8")) as {
60
+ name?: unknown;
61
+ };
62
+ }
63
+ const parent = path.dirname(current);
64
+ if (parent === current) break;
65
+ current = parent;
66
+ }
67
+ } catch {
68
+ return undefined;
69
+ }
70
+ return undefined;
71
+ }
72
+
73
+ /**
74
+ * Verifies that all transform plugins in `plugins` either resolve to the same
75
+ * native binary (the common case) or are all first-party utility plugins (the
76
+ * shared compiler-host fast path).
77
+ *
78
+ * Two callers exist with subtly different error wording: the build path
79
+ * (`runBuild.ts`) reports "multiple compiler native backends cannot share one
80
+ * emit pass" while the source-to-source path (`transformProjectInMemory.ts`)
81
+ * reports "cannot share one source-to-source pass". The `pass` argument selects
82
+ * the appropriate phrase so the error message remains diagnostic-grade instead
83
+ * of generic.
84
+ */
85
+ export function assertSharedHostCompatibility(
86
+ plugins: readonly ITtscLoadedNativePlugin[],
87
+ pass: "emit" | "source-to-source",
88
+ ): void {
89
+ const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
90
+ if (binaries.length <= 1) {
91
+ return;
92
+ }
93
+ if (plugins.every(isFirstPartyUtilityTransformPlugin)) {
94
+ return;
95
+ }
96
+ const phrase =
97
+ pass === "emit"
98
+ ? "multiple compiler native backends cannot share one emit pass"
99
+ : "multiple transform native backends cannot share one source-to-source pass";
100
+ throw new Error(
101
+ "ttsc: " +
102
+ phrase +
103
+ "; compose transform libraries through one aggregate native host",
104
+ );
105
+ }
@@ -16,6 +16,7 @@ import { readProjectConfig } from "./project/readProjectConfig";
16
16
  import { resolveBinary } from "./resolveBinary";
17
17
  import { resolveTsgo } from "./resolveTsgo";
18
18
  import { appendBuildOutput, normalizeBuildOutput } from "./runBuild";
19
+ import { assertSharedHostCompatibility } from "./sharedHostHelpers";
19
20
 
20
21
  /** Transform a project and capture TypeScript source output in memory. */
21
22
  export function transformProjectInMemory(options: ITtscCompilerContext): {
@@ -123,7 +124,7 @@ function transformProjectWithPlugins(
123
124
  typescript: transformed.typescript,
124
125
  };
125
126
  }
126
- assertTransformHostCompatibility(transformers);
127
+ assertSharedHostCompatibility(transformers, "source-to-source");
127
128
 
128
129
  const plugin = transformers[0]!;
129
130
  const res = spawnNative(
@@ -235,61 +236,6 @@ function serializeNativePlugins(
235
236
  );
236
237
  }
237
238
 
238
- function assertTransformHostCompatibility(
239
- plugins: readonly ITtscLoadedNativePlugin[],
240
- ): void {
241
- const binaries = [...new Set(plugins.map((plugin) => plugin.binary))];
242
- if (binaries.length <= 1) {
243
- return;
244
- }
245
- if (plugins.every(isFirstPartyUtilityTransformPlugin)) {
246
- return;
247
- }
248
- throw new Error(
249
- "ttsc: multiple transform native backends cannot share one source-to-source pass; " +
250
- "compose transform libraries through one aggregate native host",
251
- );
252
- }
253
-
254
- function isFirstPartyUtilityTransformPlugin(
255
- plugin: ITtscLoadedNativePlugin,
256
- ): boolean {
257
- if (plugin.stage !== "transform") return false;
258
- if (!firstPartyUtilityPluginNames.has(plugin.name)) return false;
259
- const manifest = readNearestPackageManifest(plugin.source);
260
- return manifest?.name === plugin.name;
261
- }
262
-
263
- const firstPartyUtilityPluginNames = new Set([
264
- "@ttsc/banner",
265
- "@ttsc/paths",
266
- "@ttsc/strip",
267
- ]);
268
-
269
- function readNearestPackageManifest(
270
- source: string,
271
- ): { name?: unknown } | undefined {
272
- try {
273
- let current = fs.statSync(source).isDirectory()
274
- ? source
275
- : path.dirname(source);
276
- for (let i = 0; i < 4; i += 1) {
277
- const manifest = path.join(current, "package.json");
278
- if (fs.existsSync(manifest)) {
279
- return JSON.parse(fs.readFileSync(manifest, "utf8")) as {
280
- name?: unknown;
281
- };
282
- }
283
- const parent = path.dirname(current);
284
- if (parent === current) break;
285
- current = parent;
286
- }
287
- } catch {
288
- return undefined;
289
- }
290
- return undefined;
291
- }
292
-
293
239
  function nativePluginEnv(
294
240
  options: ITtscCompilerContext,
295
241
  projectRoot: string,
@@ -0,0 +1,26 @@
1
+ import type { ITtscPlugin } from "./structures/ITtscPlugin";
2
+
3
+ /**
4
+ * Identity helper for authoring `ITtscPlugin` descriptors with full literal
5
+ * type preservation.
6
+ *
7
+ * Two call shapes:
8
+ *
9
+ * - Object form: returns the descriptor unchanged but pins its narrowed type so
10
+ * editor tooling and `satisfies` clauses can see exact field values.
11
+ * - Factory form: wraps a `(context) => descriptor` factory so the returned
12
+ * function carries the literal descriptor type through to consumers without
13
+ * forcing a manual `as const`.
14
+ *
15
+ * Pure pass-through at runtime — the function exists to teach TypeScript the
16
+ * const-narrowing the user would otherwise have to spell out.
17
+ */
18
+ export function defineTtscPlugin<const T extends ITtscPlugin>(plugin: T): T;
19
+ export function defineTtscPlugin<TContext, const T extends ITtscPlugin>(
20
+ factory: (context: TContext) => T,
21
+ ): (context: TContext) => T;
22
+ export function defineTtscPlugin(
23
+ value: ITtscPlugin | ((context: unknown) => ITtscPlugin),
24
+ ): ITtscPlugin | ((context: unknown) => ITtscPlugin) {
25
+ return value;
26
+ }
package/src/index.ts CHANGED
@@ -1,11 +1,12 @@
1
1
  /**
2
- * ttsc — public TypeScript entry.
2
+ * Ttsc — public TypeScript entry.
3
3
  *
4
4
  * The package root intentionally exposes only the programmatic compiler class
5
5
  * and the plugin-author contracts. CLI launcher functions, binary resolution,
6
- * project parsing helpers, and native build helpers stay internal so the
7
- * public package surface remains small and stable.
6
+ * project parsing helpers, and native build helpers stay internal so the public
7
+ * package surface remains small and stable.
8
8
  */
9
9
 
10
10
  export * from "./TtscCompiler";
11
+ export * from "./defineTtscPlugin";
11
12
  export * from "./structures/index";