@data-vegle/rbxts-go 0.0.0-stage → 1.0.0

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 (220) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +181 -2
  3. package/README.rbxtsgo.md +169 -0
  4. package/THIRD_PARTY_NOTICES.md +745 -0
  5. package/cli/cli.go +454 -0
  6. package/compile/compile.go +388 -0
  7. package/compile/declarations.go +221 -0
  8. package/compile/incremental.go +349 -0
  9. package/compile/times.go +9 -0
  10. package/docs/plugin-api.md +239 -0
  11. package/go.mod +20 -0
  12. package/go.sum +24 -0
  13. package/internal/difftest/difftest.go +530 -0
  14. package/internal/plugintest/plugintest.go +181 -0
  15. package/luau/create.go +351 -0
  16. package/luau/doc.go +71 -0
  17. package/luau/globals.go +178 -0
  18. package/luau/jsnum.go +188 -0
  19. package/luau/kinds.go +128 -0
  20. package/luau/list.go +227 -0
  21. package/luau/nodes.go +479 -0
  22. package/luau/operators.go +46 -0
  23. package/luau/render.go +134 -0
  24. package/luau/render_expressions.go +264 -0
  25. package/luau/render_fields.go +81 -0
  26. package/luau/render_indexable.go +81 -0
  27. package/luau/render_state.go +134 -0
  28. package/luau/render_statements.go +235 -0
  29. package/luau/render_util.go +296 -0
  30. package/luau/solve_temp_ids.go +212 -0
  31. package/luau/typeguards.go +175 -0
  32. package/luau/util.go +184 -0
  33. package/luau/visit.go +138 -0
  34. package/npm/index.d.ts +3 -0
  35. package/npm/rbxts-go.sh +187 -0
  36. package/package.json +45 -5
  37. package/patches/typescript/0001-checker-exports.patch +40 -0
  38. package/patches/typescript/0002-iterable-arity.patch +15 -0
  39. package/patches/typescript/0003-context-sensitive-this.patch +15 -0
  40. package/patches/typescript/0004-printer-keep-parse-tree-parentheses.patch +26 -0
  41. package/pluginapi/host.go +31 -0
  42. package/pluginapi/pluginapi.go +153 -0
  43. package/plugins/LICENSE-rbxts-transformer-setget +18 -0
  44. package/plugins/apply.go +342 -0
  45. package/plugins/config.go +431 -0
  46. package/plugins/fallback.go +84 -0
  47. package/plugins/fixemit.go +60 -0
  48. package/plugins/native.go +262 -0
  49. package/plugins/session.go +223 -0
  50. package/plugins/setget.go +478 -0
  51. package/project/copy.go +333 -0
  52. package/project/include/Promise.lua +2068 -0
  53. package/project/include/RuntimeLib.lua +260 -0
  54. package/project/nodepath/nodepath.go +917 -0
  55. package/project/pathtranslator/pathtranslator.go +214 -0
  56. package/project/project.go +498 -0
  57. package/project/rojoresolver/json.go +248 -0
  58. package/project/rojoresolver/rojoresolver.go +559 -0
  59. package/project/shared/constants.go +83 -0
  60. package/project/shared/diagnostic.go +238 -0
  61. package/project/shared/diagnostics.go +388 -0
  62. package/project/shared/elapsed.go +14 -0
  63. package/project/shared/eol_other.go +6 -0
  64. package/project/shared/eol_windows.go +4 -0
  65. package/project/shared/kleur.go +40 -0
  66. package/project/shared/util.go +183 -0
  67. package/scripts/build-with-plugins.sh +130 -0
  68. package/scripts/setup-third-party.sh +75 -0
  69. package/transformer/add_index_diagnostics.go +21 -0
  70. package/transformer/add_one_if_array_type.go +15 -0
  71. package/transformer/array_binding_pattern_contains_hoists.go +25 -0
  72. package/transformer/assert_never.go +24 -0
  73. package/transformer/assignment.go +64 -0
  74. package/transformer/call_macros.go +70 -0
  75. package/transformer/check_variable_hoist.go +125 -0
  76. package/transformer/clean_module_name.go +28 -0
  77. package/transformer/constructor_macros.go +122 -0
  78. package/transformer/convert_to_indexable_expression.go +12 -0
  79. package/transformer/create_binary_from_operator.go +86 -0
  80. package/transformer/create_continue_statements.go +68 -0
  81. package/transformer/create_get_service.go +15 -0
  82. package/transformer/create_hoist_declaration.go +27 -0
  83. package/transformer/create_import_expression.go +220 -0
  84. package/transformer/create_string_from_literal.go +195 -0
  85. package/transformer/create_truthiness_checks.go +63 -0
  86. package/transformer/create_type_check.go +9 -0
  87. package/transformer/ensure_transform_order.go +53 -0
  88. package/transformer/expression_chain.go +27 -0
  89. package/transformer/expression_might_mutate.go +60 -0
  90. package/transformer/find_constructor.go +15 -0
  91. package/transformer/fixup_whitespace_and_decode_entities.go +377 -0
  92. package/transformer/get_accessor_for_binding_type.go +160 -0
  93. package/transformer/get_add_iterable_to_array_builder.go +363 -0
  94. package/transformer/get_assignable_value.go +15 -0
  95. package/transformer/get_constant_value_literal.go +20 -0
  96. package/transformer/get_declared_variables.go +34 -0
  97. package/transformer/get_extends_node.go +23 -0
  98. package/transformer/get_flags.go +21 -0
  99. package/transformer/get_kind_name.go +18 -0
  100. package/transformer/get_original_symbol_of_node.go +16 -0
  101. package/transformer/get_source_file_from_module_specifier.go +68 -0
  102. package/transformer/get_statements.go +12 -0
  103. package/transformer/has_multiple_definitions.go +18 -0
  104. package/transformer/hoist_functions_past_final_statement.go +43 -0
  105. package/transformer/identifier_macros.go +17 -0
  106. package/transformer/is_blocked_by_try_statement.go +19 -0
  107. package/transformer/is_method.go +104 -0
  108. package/transformer/is_symbol_mutable.go +26 -0
  109. package/transformer/is_symbol_of_value.go +11 -0
  110. package/transformer/is_used_as_statement.go +25 -0
  111. package/transformer/is_valid_method_index_without_call.go +36 -0
  112. package/transformer/macro_manager.go +92 -0
  113. package/transformer/object_accessor.go +32 -0
  114. package/transformer/offset.go +58 -0
  115. package/transformer/pointer.go +53 -0
  116. package/transformer/property_call_macros.go +1035 -0
  117. package/transformer/state.go +606 -0
  118. package/transformer/transform_array_assignment_pattern.go +65 -0
  119. package/transformer/transform_array_binding_pattern.go +49 -0
  120. package/transformer/transform_array_literal_expression.go +97 -0
  121. package/transformer/transform_await_expression.go +12 -0
  122. package/transformer/transform_binary_expression.go +221 -0
  123. package/transformer/transform_binding_name.go +25 -0
  124. package/transformer/transform_block.go +14 -0
  125. package/transformer/transform_boolean_literal.go +13 -0
  126. package/transformer/transform_break_statement.go +26 -0
  127. package/transformer/transform_call_expression.go +266 -0
  128. package/transformer/transform_class_constructor.go +125 -0
  129. package/transformer/transform_class_declaration.go +12 -0
  130. package/transformer/transform_class_expression.go +14 -0
  131. package/transformer/transform_class_like_declaration.go +355 -0
  132. package/transformer/transform_conditional_expression.go +70 -0
  133. package/transformer/transform_continue_statement.go +30 -0
  134. package/transformer/transform_decorators.go +253 -0
  135. package/transformer/transform_delete_expression.go +17 -0
  136. package/transformer/transform_do_statement.go +39 -0
  137. package/transformer/transform_element_access_expression.go +114 -0
  138. package/transformer/transform_entity_name.go +21 -0
  139. package/transformer/transform_enum_declaration.go +135 -0
  140. package/transformer/transform_export_assignment.go +57 -0
  141. package/transformer/transform_export_declaration.go +150 -0
  142. package/transformer/transform_expression.go +120 -0
  143. package/transformer/transform_expression_statement.go +71 -0
  144. package/transformer/transform_for_of_statement.go +461 -0
  145. package/transformer/transform_for_statement.go +599 -0
  146. package/transformer/transform_function_declaration.go +84 -0
  147. package/transformer/transform_function_expression.go +48 -0
  148. package/transformer/transform_identifier.go +194 -0
  149. package/transformer/transform_if_statement.go +44 -0
  150. package/transformer/transform_import_declaration.go +146 -0
  151. package/transformer/transform_import_equals_declaration.go +46 -0
  152. package/transformer/transform_import_expression.go +36 -0
  153. package/transformer/transform_initializer.go +22 -0
  154. package/transformer/transform_interpolated_string_part.go +12 -0
  155. package/transformer/transform_jsx.go +41 -0
  156. package/transformer/transform_jsx_attributes.go +110 -0
  157. package/transformer/transform_jsx_children.go +50 -0
  158. package/transformer/transform_jsx_element.go +14 -0
  159. package/transformer/transform_jsx_expression.go +20 -0
  160. package/transformer/transform_jsx_fragment.go +42 -0
  161. package/transformer/transform_jsx_self_closing_element.go +13 -0
  162. package/transformer/transform_jsx_tag_name.go +53 -0
  163. package/transformer/transform_logical.go +160 -0
  164. package/transformer/transform_logical_or_coalescing_assignment_expression.go +103 -0
  165. package/transformer/transform_method_declaration.go +102 -0
  166. package/transformer/transform_module_declaration.go +143 -0
  167. package/transformer/transform_new_expression.go +27 -0
  168. package/transformer/transform_no_substitution_template_literal.go +16 -0
  169. package/transformer/transform_numeric_literal.go +15 -0
  170. package/transformer/transform_object_assignment_pattern.go +86 -0
  171. package/transformer/transform_object_binding_pattern.go +49 -0
  172. package/transformer/transform_object_literal_expression.go +107 -0
  173. package/transformer/transform_omitted_expression.go +9 -0
  174. package/transformer/transform_optional_chain.go +312 -0
  175. package/transformer/transform_parameters.go +124 -0
  176. package/transformer/transform_parenthesized_expression.go +17 -0
  177. package/transformer/transform_property_access_expression.go +37 -0
  178. package/transformer/transform_property_declaration.go +33 -0
  179. package/transformer/transform_property_name.go +20 -0
  180. package/transformer/transform_return_statement.go +83 -0
  181. package/transformer/transform_source_file.go +230 -0
  182. package/transformer/transform_spread_element.go +35 -0
  183. package/transformer/transform_statement.go +84 -0
  184. package/transformer/transform_statement_list.go +90 -0
  185. package/transformer/transform_string_literal.go +22 -0
  186. package/transformer/transform_super_keyword.go +9 -0
  187. package/transformer/transform_switch_statement.go +145 -0
  188. package/transformer/transform_tagged_template_expression.go +34 -0
  189. package/transformer/transform_template_expression.go +35 -0
  190. package/transformer/transform_this_expression.go +33 -0
  191. package/transformer/transform_throw_statement.go +18 -0
  192. package/transformer/transform_try_statement.go +192 -0
  193. package/transformer/transform_type_expression.go +12 -0
  194. package/transformer/transform_unary_expression.go +79 -0
  195. package/transformer/transform_variable_statement.go +178 -0
  196. package/transformer/transform_void_expression.go +13 -0
  197. package/transformer/transform_while_statement.go +34 -0
  198. package/transformer/transform_writable.go +69 -0
  199. package/transformer/transform_yield_expression.go +56 -0
  200. package/transformer/type_guards.go +30 -0
  201. package/transformer/types.go +381 -0
  202. package/transformer/validate_identifier.go +17 -0
  203. package/transformer/validate_method_assignment.go +106 -0
  204. package/transformer/validate_not_any.go +37 -0
  205. package/transformer/wrap_expression_statement.go +20 -0
  206. package/transformer/wrap_return_if_lua_tuple.go +63 -0
  207. package/transformer/wrap_statements_as_generator.go +22 -0
  208. package/tsbridge/affected.go +141 -0
  209. package/tsbridge/config.go +71 -0
  210. package/tsbridge/diagnostics.go +128 -0
  211. package/tsbridge/doc.go +16 -0
  212. package/tsbridge/macros.go +207 -0
  213. package/tsbridge/macrospec.go +30 -0
  214. package/tsbridge/pool.go +142 -0
  215. package/tsbridge/project.go +137 -0
  216. package/tsbridge/reprint.go +99 -0
  217. package/tsbridge/update.go +128 -0
  218. package/watch/poll.go +126 -0
  219. package/watch/session.go +651 -0
  220. package/watch/watch.go +180 -0
@@ -0,0 +1,349 @@
1
+ package compile
2
+
3
+ // Incremental builds: incremental and tsBuildInfoFile. See docs/watch-and-incremental.md for why this has its
4
+ // own format, and for what it reuses from watch mode's reasoning.
5
+
6
+ import (
7
+ "context"
8
+ "crypto/sha256"
9
+ "encoding/hex"
10
+ "encoding/json"
11
+ "fmt"
12
+ "os"
13
+ "runtime"
14
+ "slices"
15
+ "sync"
16
+ "time"
17
+
18
+ "github.com/microsoft/TypeScript/tsc/internal/ast"
19
+ "github.com/microsoft/TypeScript/tsc/internal/tspath"
20
+ "github.com/microsoft/TypeScript/tsc/rbxtsgo/project/nodepath"
21
+ "github.com/microsoft/TypeScript/tsc/rbxtsgo/project/pathtranslator"
22
+ "github.com/microsoft/TypeScript/tsc/rbxtsgo/project/rojoresolver"
23
+ "github.com/microsoft/TypeScript/tsc/rbxtsgo/project/shared"
24
+ "github.com/microsoft/TypeScript/tsc/rbxtsgo/tsbridge"
25
+ )
26
+
27
+ // buildInfoVersion names this format. JS's readBuilderProgram finds no "program" in the file and starts over, so sharing
28
+ // a tsBuildInfoFile with rbxtsc costs a full build each way and nothing else. That was tried, see 0008.
29
+ const buildInfoVersion = "rbxtsgo-1"
30
+
31
+ type outputRecord struct {
32
+ Path string `json:"path"`
33
+ Size int64 `json:"size"`
34
+ ModTime time.Time `json:"modTime"`
35
+ }
36
+
37
+ // fileRecord is one program file as of the last successful build.
38
+ type fileRecord struct {
39
+ // Source is the hash of the file on disk, and Compiled is the hash of what got compiled: the printed text with a
40
+ // plugin, otherwise the same.
41
+ Source string `json:"source"`
42
+ Compiled string `json:"compiled"`
43
+ // Global says this version of the file can reach every file. See tsbridge.AffectedFiles.
44
+ Global bool `json:"global,omitempty"`
45
+ // Imports is where it imports from, in the compiled program.
46
+ Imports []string `json:"imports,omitempty"`
47
+ // Clean says it compiled with no diagnostics. A file with warnings compiles again, so they get shown again.
48
+ Clean bool `json:"clean,omitempty"`
49
+ Outputs []outputRecord `json:"outputs,omitempty"`
50
+ }
51
+
52
+ type buildInfoFile struct {
53
+ Version string `json:"version"`
54
+ Key string `json:"key"`
55
+ Files map[string]*fileRecord `json:"files"`
56
+ }
57
+
58
+ // Incremental is the state of one build's tsBuildInfoFile. A nil one means the project isn't incremental.
59
+ type Incremental struct {
60
+ path string
61
+ key string
62
+ translator *pathtranslator.Translator
63
+ data *shared.ProjectData
64
+ previous *buildInfoFile
65
+ hashes sync.Map // *ast.SourceFile to string
66
+ // sourceHashes is filled from the source program.
67
+ sourceHashes map[string]string
68
+ }
69
+
70
+ // BuildKey is createCompilerHost's contentsToHash, and what TS's builder compares in the compiler options: anything that
71
+ // has to force a rebuild when it changes. It takes the raw text of the configs, so a comment forces one too.
72
+ func BuildKey(data *shared.ProjectData, p *tsbridge.Project, extra string) string {
73
+ hash := sha256.New()
74
+ fmt.Fprintf(hash, "version=%s,", shared.CompilerVersion)
75
+ if exe, err := os.Executable(); err == nil {
76
+ // Upstream's version only changes with a release. Here a rebuilt compiler can give new output with the same one.
77
+ if info, err := os.Stat(exe); err == nil {
78
+ fmt.Fprintf(hash, "exe=%d,%d,", info.Size(), info.ModTime().UnixNano())
79
+ }
80
+ }
81
+ options := data.ProjectOptions
82
+ // None of these change what gets written, and watch mode always has writeOnlyChanged on.
83
+ options.Watch, options.UsePolling, options.Verbose, options.WriteOnlyChanged = false, false, false, false
84
+ fmt.Fprintf(hash, "isPackage=%v,options=%+v,extra=%s,", data.IsPackage, options, extra)
85
+ configs := append([]string{data.TsConfigPath, data.RojoConfigPath, nodepath.Native.Join(nodepath.Native.Dirname(data.NodeModulesPath), "package.json")}, extendedFiles(p)...)
86
+ // What createNodeModulesPathMapping reads: a package's main or types changes generated requires. A package's
87
+ // declarations are program files, which get hashed anyway.
88
+ for _, typeRoot := range p.Options().TypeRoots {
89
+ entries, err := os.ReadDir(string(typeRoot))
90
+ if err != nil {
91
+ continue
92
+ }
93
+ for _, entry := range entries {
94
+ fmt.Fprintf(hash, "package=%s,", entry.Name())
95
+ configs = append(configs, nodepath.Native.Join(string(typeRoot), entry.Name(), "package.json"))
96
+ }
97
+ }
98
+ for _, file := range configs {
99
+ if file == "" {
100
+ continue
101
+ }
102
+ text, _ := os.ReadFile(file)
103
+ fmt.Fprintf(hash, "%d:", len(text))
104
+ hash.Write(text)
105
+ }
106
+ // A Rojo project can nest others in its $path folders, and those decide generated paths too. Reading the project
107
+ // walks those folders, and what it finds is what the compile would use. An error here is the compile's to report.
108
+ if data.RojoConfigPath != "" {
109
+ if resolver, err := rojoresolver.FromPath(data.RojoConfigPath); err == nil {
110
+ fmt.Fprintf(hash, "rojo=%v,%v,", resolver.IsGame, resolver.Partitions())
111
+ }
112
+ }
113
+ return hex.EncodeToString(hash.Sum(nil))
114
+ }
115
+
116
+ func extendedFiles(p *tsbridge.Project) []string {
117
+ var result []string
118
+ for _, file := range p.Config().ExtendedSourceFiles() {
119
+ result = append(result, file.AsString())
120
+ }
121
+ return result
122
+ }
123
+
124
+ // LoadIncremental reads the tsBuildInfoFile. It returns nil when the project has none configured. A file that's missing,
125
+ // damaged or from another compiler is the same as no earlier build.
126
+ func LoadIncremental(data *shared.ProjectData, translator *pathtranslator.Translator, key string) *Incremental {
127
+ if translator.BuildInfoOutputPath == "" {
128
+ return nil
129
+ }
130
+ inc := &Incremental{path: translator.BuildInfoOutputPath, key: key, translator: translator, data: data}
131
+ text, err := os.ReadFile(inc.path)
132
+ if err != nil {
133
+ return inc
134
+ }
135
+ var previous buildInfoFile
136
+ if json.Unmarshal(text, &previous) != nil || previous.Version != buildInfoVersion || previous.Key != key || previous.Files == nil {
137
+ return inc
138
+ }
139
+ inc.previous = &previous
140
+ return inc
141
+ }
142
+
143
+ func (inc *Incremental) hashOf(file *ast.SourceFile) string {
144
+ if known, ok := inc.hashes.Load(file); ok {
145
+ return known.(string)
146
+ }
147
+ sum := sha256.Sum256([]byte(file.Text()))
148
+ hash := hex.EncodeToString(sum[:16])
149
+ inc.hashes.Store(file, hash)
150
+ return hash
151
+ }
152
+
153
+ func (inc *Incremental) hashAll(files []*ast.SourceFile) []string {
154
+ result := make([]string, len(files))
155
+ var wg sync.WaitGroup
156
+ gate := make(chan struct{}, runtime.GOMAXPROCS(0))
157
+ for i, file := range files {
158
+ wg.Add(1)
159
+ gate <- struct{}{}
160
+ go func() {
161
+ defer wg.Done()
162
+ defer func() { <-gate }()
163
+ result[i] = inc.hashOf(file)
164
+ }()
165
+ }
166
+ wg.Wait()
167
+ return result
168
+ }
169
+
170
+ // Unchanged says the sources and options are what the last successful build saw, and its outputs are still in place. If
171
+ // so there is nothing to compile, or even to print. p is the program before any plugin.
172
+ func (inc *Incremental) Unchanged(p *tsbridge.Project) bool {
173
+ if inc == nil {
174
+ return false
175
+ }
176
+ files := p.Program().SourceFiles()
177
+ hashes := inc.hashAll(files)
178
+ inc.sourceHashes = make(map[string]string, len(files))
179
+ for i, file := range files {
180
+ inc.sourceHashes[string(file.PathKey())] = hashes[i]
181
+ }
182
+ if inc.previous == nil || len(inc.previous.Files) != len(files) {
183
+ return false
184
+ }
185
+ for i, file := range files {
186
+ record := inc.previous.Files[string(file.PathKey())]
187
+ if record == nil || record.Source != hashes[i] || (isCompiled(file) && !record.Clean) || !outputsInPlace(record) {
188
+ return false
189
+ }
190
+ }
191
+ return true
192
+ }
193
+
194
+ func isCompiled(file *ast.SourceFile) bool {
195
+ return !file.IsDeclarationFile && !ast.IsJsonSourceFile(file)
196
+ }
197
+
198
+ func outputsInPlace(record *fileRecord) bool {
199
+ for _, output := range record.Outputs {
200
+ info, err := os.Stat(output.Path)
201
+ if err != nil || info.Size() != output.Size || !info.ModTime().Equal(output.ModTime) {
202
+ return false
203
+ }
204
+ }
205
+ return true
206
+ }
207
+
208
+ // Dirty picks the files to compile on project p, the program after any plugin. files are all that a clean build would
209
+ // compile, in order. The others' output is what a clean build would write. See tsbridge.AffectedFiles for why.
210
+ func (inc *Incremental) Dirty(p *tsbridge.Project, files []*ast.SourceFile) []*ast.SourceFile {
211
+ if inc == nil || inc.previous == nil {
212
+ return files
213
+ }
214
+ programFiles := p.Program().SourceFiles()
215
+ hashes := inc.hashAll(programFiles)
216
+ if len(inc.previous.Files) != len(programFiles) {
217
+ return files
218
+ }
219
+ graph := p.ImportGraph()
220
+ var changed []tspath.PathKey
221
+ for i, file := range programFiles {
222
+ record := inc.previous.Files[string(file.PathKey())]
223
+ if record == nil {
224
+ return files
225
+ }
226
+ if record.Compiled != hashes[i] {
227
+ if record.Global || tsbridge.HasGlobalEffects(file) {
228
+ return files
229
+ }
230
+ changed = append(changed, file.PathKey())
231
+ } else if !slices.Equal(record.Imports, keysToStrings(graph[file.PathKey()])) {
232
+ return files
233
+ }
234
+ }
235
+ affected := p.Closure(changed)
236
+ dirty := make([]*ast.SourceFile, 0, len(files))
237
+ for _, file := range files {
238
+ record := inc.previous.Files[string(file.PathKey())]
239
+ if affected[file.PathKey()] || !record.Clean || !outputsInPlace(record) {
240
+ dirty = append(dirty, file)
241
+ }
242
+ }
243
+ return dirty
244
+ }
245
+
246
+ func keysToStrings(keys []tspath.PathKey) []string {
247
+ if len(keys) == 0 {
248
+ return nil
249
+ }
250
+ result := make([]string, len(keys))
251
+ for i, key := range keys {
252
+ result[i] = string(key)
253
+ }
254
+ return result
255
+ }
256
+
257
+ // Save is program.emitBuildInfo(). dirty is what just compiled, and result is how that went: call this after a compile
258
+ // with no errors. Anything else keeps its record. sourceProject is the program before any plugin.
259
+ func (inc *Incremental) Save(sourceProject, compiled *tsbridge.Project, dirty []*ast.SourceFile, result *EmitResult) error {
260
+ if inc == nil {
261
+ return nil
262
+ }
263
+ reported := map[*ast.SourceFile]bool{}
264
+ for _, d := range result.Diagnostics {
265
+ reported[d.File()] = true
266
+ }
267
+ redone := make(map[*ast.SourceFile]bool, len(dirty))
268
+ for _, file := range dirty {
269
+ redone[file] = true
270
+ }
271
+ sourceFiles := sourceProject.Program().FilesByPath()
272
+ programFiles := compiled.Program().SourceFiles()
273
+ hashes := inc.hashAll(programFiles)
274
+ graph := compiled.ImportGraph()
275
+ declaration := compiled.Options().Declaration.IsTrue()
276
+ next := &buildInfoFile{Version: buildInfoVersion, Key: inc.key, Files: make(map[string]*fileRecord, len(programFiles))}
277
+ for i, file := range programFiles {
278
+ path := file.PathKey()
279
+ record := &fileRecord{
280
+ Compiled: hashes[i],
281
+ Global: tsbridge.HasGlobalEffects(file),
282
+ Imports: keysToStrings(graph[path]),
283
+ }
284
+ if source := sourceFiles[path]; source != nil {
285
+ record.Source = inc.hashOf(source)
286
+ }
287
+ var old *fileRecord
288
+ if inc.previous != nil {
289
+ old = inc.previous.Files[string(path)]
290
+ }
291
+ switch {
292
+ case !isCompiled(file):
293
+ case redone[file]:
294
+ record.Clean = !reported[file]
295
+ fsPath := nodepath.Native.Normalize(file.FileName().AsString())
296
+ candidates := []string{inc.translator.GetOutputPath(fsPath)}
297
+ if declaration {
298
+ candidates = append(candidates, inc.translator.GetOutputDeclarationPath(fsPath))
299
+ }
300
+ for _, candidate := range candidates {
301
+ info, err := os.Stat(candidate)
302
+ if err != nil {
303
+ // Upstream writes nothing for a file with no source, and a clean build would agree.
304
+ record.Clean = false
305
+ continue
306
+ }
307
+ record.Outputs = append(record.Outputs, outputRecord{Path: candidate, Size: info.Size(), ModTime: info.ModTime()})
308
+ }
309
+ case old != nil:
310
+ record.Clean = old.Clean
311
+ record.Outputs = old.Outputs
312
+ }
313
+ next.Files[string(path)] = record
314
+ }
315
+ text, err := json.Marshal(next)
316
+ if err != nil {
317
+ return err
318
+ }
319
+ if err := os.MkdirAll(nodepath.Native.Dirname(inc.path), 0o777); err != nil {
320
+ return err
321
+ }
322
+ if err := os.WriteFile(inc.path, text, 0o666); err != nil {
323
+ return err
324
+ }
325
+ inc.previous = next
326
+ return nil
327
+ }
328
+
329
+ // CompileIncremental is CompileFiles for a build: only what Dirty picks, then Save. A nil inc compiles all of files.
330
+ func CompileIncremental(ctx context.Context, c *Context, inc *Incremental, source *tsbridge.Project, files []*ast.SourceFile) (*EmitResult, error) {
331
+ dirty := inc.Dirty(c.Project, files)
332
+ result, err := CompileFiles(ctx, c, dirty)
333
+ if err != nil {
334
+ return nil, err
335
+ }
336
+ // A diagnostic with no file comes from the whole program, and rbxtsc repeats it per file.
337
+ if len(dirty) < len(files) && slices.ContainsFunc(result.Diagnostics, func(d *shared.Diagnostic) bool { return d.File() == nil }) {
338
+ dirty = files
339
+ if result, err = CompileFiles(ctx, c, files); err != nil {
340
+ return nil, err
341
+ }
342
+ }
343
+ if inc != nil && !result.EmitSkipped && !shared.HasErrors(result.Diagnostics) {
344
+ if err := inc.Save(source, c.Project, dirty, result); err != nil {
345
+ return nil, err
346
+ }
347
+ }
348
+ return result, nil
349
+ }
@@ -0,0 +1,9 @@
1
+ package compile
2
+
3
+ import "time"
4
+
5
+ // Times is where one compile's time went. Fill in by passing it in Context.Times.
6
+ type Times struct {
7
+ Program, Copy, State, Prepare, Plugin, Check, Lower, Write, Declarations time.Duration
8
+ FilesTransformed, FilesChecked, FilesLowered int
9
+ }
@@ -0,0 +1,239 @@
1
+ # Native plugins
2
+
3
+ rbxts-go can run TypeScript transformer plugins natively, as Go code, in place of the JavaScript transformers named
4
+ in `compilerOptions.plugins`. Plugins do not live in this repository. A plugin is its own Go module, and a build of
5
+ rbxts-go that includes it is made by compiling the two together (see "Building a compiler with plugins").
6
+
7
+ This file is the contract between rbxts-go (the host) and plugin authors. The built-in setget transformer is not a
8
+ plugin in this sense and is unchanged.
9
+
10
+ ## What a plugin is
11
+
12
+ A plugin does what a `ts.TransformerFactory<ts.SourceFile>` does in roblox-ts: before a file is lowered to Luau, it
13
+ gets the file's syntax tree and returns a new one. The host prints the returned trees back to TypeScript text, makes a
14
+ new program from that text, type-checks it and compiles it, exactly as it already does for setget. A plugin therefore
15
+ never produces Luau, and anything it generates must be valid TypeScript for the checker.
16
+
17
+ Every file is printed, changed or not, as JS does when any transformer is active. Diagnostics of the compile are
18
+ reported at the place in the user's source that the printed text came from, not in the printed text.
19
+
20
+ With incremental builds (`tsBuildInfoFile`), the plugins still run over every file on every build, and `Finish` is
21
+ called, even when no source changed. What is incremental is the compile after them, which goes by the printed text.
22
+ The names and entries of the plugins are part of the build's key, so changing an entry compiles everything again.
23
+
24
+ ## Registering
25
+
26
+ ```go
27
+ package pluginapi // import "github.com/microsoft/TypeScript/tsc/rbxtsgo/pluginapi"
28
+
29
+ // Plugin describes a native plugin. Register it from an init function.
30
+ type Plugin struct {
31
+ // Name is for messages, such as "godawork".
32
+ Name string
33
+ // Transforms are the values of "transform" in compilerOptions.plugins that this plugin replaces, such as
34
+ // "rbxts-transformer-flamework". An entry matches when its "transform" is equal to one of them.
35
+ Transforms []string
36
+ // New is called once per program, before any file is transformed. config is the plugin's entry in
37
+ // compilerOptions.plugins, decoded from JSON (so numbers are float64, objects are map[string]any), including
38
+ // "transform". An error stops the build and is printed as it is.
39
+ New func(host *Host, config map[string]any) (Transformer, error)
40
+ }
41
+
42
+ func Register(plugin Plugin)
43
+ ```
44
+
45
+ `Register` panics, when the compiler starts, on a plugin that could never run: one with no `Name`, no `New` or no
46
+ `Transforms`, or one that claims a `"transform"` that another registered plugin or the built-in setget already has.
47
+
48
+ A build is native when every entry of `compilerOptions.plugins` that has a `"transform"` is either setget or matched
49
+ by a registered plugin. If any entry is matched by nothing, the build is handed to the JS compiler as before, and the
50
+ message names the entries that have no native plugin. An entry listed twice gets `New` twice, and so two
51
+ transformers. The other keys that JS transformers have in their entry (`"type"`, `"import"`, `"after"`) mean nothing
52
+ to the host: they are in `config` like any other key.
53
+
54
+ Setget can be combined with native plugins when it comes first: the built-in option, or its entry before every
55
+ native plugin's entry. It then transforms each file before the plugins, on the same goroutine and with the same
56
+ checker, and the first plugin's `node` is what setget made. The calls setget makes are new nodes with no original,
57
+ so `ctx.Original` gives them back as they are. A setget entry after a native plugin's entry is an error.
58
+
59
+ ## The host
60
+
61
+ ```go
62
+ // Host is what a plugin may read about the build. It is valid for one program.
63
+ type Host struct {
64
+ // Program is the program made from the sources as written, before any plugin ran.
65
+ Program *compiler.Program
66
+ // Options are the normalized compiler options of that program.
67
+ Options *core.CompilerOptions
68
+ // Data is the project data: paths of the project, tsconfig, node_modules, Rojo project, and the project options.
69
+ Data *shared.ProjectData
70
+ // PathTranslator maps source paths to output paths.
71
+ PathTranslator *pathtranslator.Translator
72
+ // RojoResolver is the resolver of the project's Rojo file, as the compiler uses it. Nil when the project has
73
+ // none (a package).
74
+ RojoResolver *rojoresolver.Resolver
75
+ // Files are the files that will be compiled, in program order. They are the files TransformFile is called for.
76
+ Files []*ast.SourceFile
77
+ // Checker is the one checker that every plugin call of this program uses. See "Threads and checkers".
78
+ Checker *checker.Checker
79
+ // Watch is true in watch mode, where the same Transformer value serves several programs: see "Watch mode".
80
+ Watch bool
81
+ }
82
+
83
+ // Warn prints a warning the way the compiler prints its own.
84
+ func (h *Host) Warn(message string)
85
+ ```
86
+
87
+ `Host.Program` is never checked in full: the compile checks the program made from the printed text. So the checker
88
+ works out only what the plugins ask it, and a type error in the user's source does not stop a plugin from running.
89
+ It is reported afterwards, by the compile.
90
+
91
+ ## The transformer
92
+
93
+ ```go
94
+ // Transformer is one plugin's work for one program.
95
+ type Transformer interface {
96
+ // TransformFile returns the tree to compile in place of a file. file is the file as written. node is the file
97
+ // as the plugins before this one left it, which is file itself for the first plugin; it is always a SourceFile
98
+ // node. Return node unchanged when there is nothing to do. The result must be a SourceFile node made with
99
+ // ctx.Factory (or node itself).
100
+ TransformFile(ctx *FileContext, file *ast.SourceFile, node *ast.Node) *ast.Node
101
+ // Finish is called once after every file was transformed without an error, before the compile starts. It is
102
+ // where a plugin writes its own files (a build cache, an id table). An error stops the build.
103
+ Finish() error
104
+ }
105
+
106
+ // FileContext is what a plugin needs while it transforms one file.
107
+ type FileContext struct {
108
+ // Host is the host of the program.
109
+ Host *Host
110
+ // Checker is Host.Checker.
111
+ Checker *checker.Checker
112
+ // EmitContext is the emit context of this file's reprint, shared by every plugin that transforms the file.
113
+ // Nodes must be created through it, so that the printer and later plugins can find what a node was made from.
114
+ EmitContext *printer.EmitContext
115
+ // Factory is EmitContext.Factory: update and create nodes with it.
116
+ Factory *printer.NodeFactory
117
+ }
118
+
119
+ // Original returns the node of the file as written that a node was made from, or the node itself if it is one.
120
+ // It is ts.getOriginalNode: after an earlier plugin rewrote a call, a later plugin finds the call it wants by its
121
+ // original.
122
+ func (c *FileContext) Original(node *ast.Node) *ast.Node
123
+
124
+ // AddDiagnostic reports an error or a warning at a node of the file as written. An error stops the build after
125
+ // every plugin has seen every file, and is printed like a compiler diagnostic. The source text shown is the user's.
126
+ func (c *FileContext) AddDiagnostic(category diagnostics.Category, node *ast.Node, message string)
127
+
128
+ // Exit stops the build at once, printing the lines, as a JS transformer that calls process.exit does.
129
+ func (c *FileContext) Exit(lines ...string)
130
+ ```
131
+
132
+ Rules for `TransformFile`:
133
+
134
+ - Do not change `file` or any node reachable from it. Trees are shared with the checker. Build new nodes with
135
+ `ctx.Factory` (`Update...` for a changed node, `New...` for a new one), as `plugins/setget.go` does.
136
+ - A node created from an existing node must keep the link to it. The factory's `Update...` functions do this; for a
137
+ node made with `New...` that replaces an existing one, call `ctx.EmitContext.SetOriginal(newNode, oldNode)`.
138
+ - Types come from `ctx.Checker`, asked about nodes of the file as written (`ctx.Original(node)`), never about nodes
139
+ the plugin made.
140
+ - A panic in `TransformFile` is reported as an internal error for that file, with the plugin's name, and stops the
141
+ build at once. A panic in `New`, `Update` or `Finish` is reported the same way. `--verbose` adds the stack.
142
+
143
+ What the host does with the rest of `FileContext`:
144
+
145
+ - `AddDiagnostic` takes any node: the place is that of the node of the source it was made from (`ctx.Original`),
146
+ which may be in another file. A node made from nothing puts the diagnostic at the start of the file. The
147
+ diagnostics are printed with the code `TS roblox-ts`, like the compiler's own. With an error, nothing is compiled
148
+ and `Finish` is not called. Warnings alone do not stop anything: they are printed before the compile's diagnostics.
149
+ - `Exit` prints the lines on standard output and ends the build with exit code 1. No other plugin call follows. It
150
+ works by panicking with a value the host recovers, so it does not return, and it must be called on the goroutine
151
+ of the `TransformFile` call. In watch mode the lines are reported as an error and the watcher goes on.
152
+ - After every file went through the plugins without an error, the host prints the trees, and only then calls
153
+ `Finish`. So a tree that cannot be printed stops the build before a plugin writes its files.
154
+
155
+ Package `pluginapi` also exports what the host itself needs to run plugins (`Lookup`, `NewFileContext` and
156
+ `ExitRequest`, in `host.go`). A plugin calls none of it.
157
+
158
+ ## Order
159
+
160
+ Plugins run in the order of their entries in `compilerOptions.plugins`, as in roblox-ts. For each file, the first
161
+ plugin gets the file as written, the next one gets the previous one's result, and so on. All files go through the
162
+ first plugin's `New` before any `TransformFile`, and `New` of every plugin runs before any `TransformFile` of any.
163
+
164
+ ## Threads and checkers
165
+
166
+ Every call to a plugin (`New`, `TransformFile`, `Finish`) happens on one goroutine, and files are transformed one after
167
+ the other in program order. A plugin can keep state between files without locks, and anything that depends on the
168
+ order of files, such as handing out identifiers, is deterministic.
169
+
170
+ All calls use one checker, `Host.Checker`. Types and symbols from it can be kept for the life of the program and
171
+ compared with each other. Do not use any other checker of the program.
172
+
173
+ This is simpler and slower than what the compiler does for its own lowering, which runs one goroutine per checker.
174
+ It is the model JS transformers have, and most of them depend on it.
175
+
176
+ ## Watch mode
177
+
178
+ In watch mode `New` is called once, with `Host.Watch` true, for the first program. For each later program the host
179
+ calls `Update` if the transformer has it, and otherwise calls `New` again:
180
+
181
+ ```go
182
+ // Updater is implemented by transformers that can carry their state to the next program of a watch session.
183
+ type Updater interface {
184
+ // Update prepares the transformer for the next program. changed are the files of the new program whose text
185
+ // differs from the previous program's, or that are new. TransformFile is then called for every file that needs
186
+ // compiling in this cycle, which includes the changed files.
187
+ Update(host *Host, changed []*ast.SourceFile) error
188
+ }
189
+ ```
190
+
191
+ What the host does today, which is more than the above asks of a plugin and can become less:
192
+
193
+ - Every cycle calls `TransformFile` for every file of `Host.Files`, in program order, and then `Finish`. Nothing is
194
+ kept from the last cycle on the plugins' side. Only the compile after it is incremental: a file whose printed text
195
+ did not change is not compiled again.
196
+ - `changed` is worked out against the last program the transformer was given, whether that cycle ended well or not.
197
+ It holds any file of the program, declaration files and JSON files too, so it is not a subset of `Host.Files`.
198
+ - `New` is called again, still with `Host.Watch` true, when the old transformers cannot be trusted or do not fit:
199
+ after a plugin panicked, called `Exit` or returned an error from `New`, `Update` or `Finish`; and after the
200
+ tsconfig, the Rojo project or `package.json` changed, or file events were lost. An error from `AddDiagnostic` is
201
+ not one of these: the same transformers get the next program.
202
+
203
+ ## What a plugin can import
204
+
205
+ A plugin module must have a module path under `github.com/microsoft/TypeScript/tsc/`, because the TypeScript
206
+ compiler's packages are internal to that path. The path must not be under `.../tsc/rbxtsgo` or `.../tsc/internal`,
207
+ which are the compiler's own. It can import:
208
+
209
+ - `github.com/microsoft/TypeScript/tsc/internal/...` (ast, checker, printer, core, scanner, tspath and so on)
210
+ - `github.com/microsoft/TypeScript/tsc/rbxtsgo/pluginapi`
211
+ - the packages of rbxts-go that the `Host` exposes types of: `project/shared`, `project/pathtranslator`,
212
+ `project/rojoresolver`, `project/nodepath`
213
+
214
+ ## Building a compiler with plugins
215
+
216
+ `rbxts-go` built from this repository alone has no plugins. A compiler with plugins is a small `main` package:
217
+
218
+ ```go
219
+ package main
220
+
221
+ import (
222
+ "github.com/microsoft/TypeScript/tsc/rbxtsgo/cli"
223
+
224
+ _ "github.com/microsoft/TypeScript/tsc/godawork" // registers itself in init
225
+ )
226
+
227
+ func main() { cli.Main() }
228
+ ```
229
+
230
+ with a `go.mod` whose `replace` lines point the TypeScript module, rbxts-go and each plugin at their folders.
231
+ `scripts/build-with-plugins.sh -o <output> <plugin folder>...` writes both files into a temporary folder and builds
232
+ it. It reads each plugin's module path from the `go.mod` in its folder, and needs `third_party/` set up
233
+ (`scripts/setup-third-party.sh`). `replace` lines in a plugin's own `go.mod` do not count in that build, so a plugin
234
+ that depends on another local module needs it published or added to the script's `go.mod` by hand.
235
+
236
+ `cli.Run(args) int` is `cli.Main` without the exit, for a `main` that wants to do something before or after.
237
+
238
+ `pluginapi/testdata/testplugin` is a complete small plugin in its own module, and `go test ./pluginapi` builds a
239
+ compiler with it through the script.
package/go.mod ADDED
@@ -0,0 +1,20 @@
1
+ module github.com/microsoft/TypeScript/tsc/rbxtsgo
2
+
3
+ go 1.27
4
+
5
+ require (
6
+ github.com/microsoft/TypeScript/tsc v0.0.0
7
+ golang.org/x/term v0.46.0
8
+ )
9
+
10
+ require (
11
+ github.com/Microsoft/go-winio v0.6.2 // indirect
12
+ github.com/klauspost/compress v1.20.0 // indirect
13
+ github.com/klauspost/cpuid/v2 v2.2.10 // indirect
14
+ github.com/zeebo/xxh3 v1.1.0 // indirect
15
+ golang.org/x/sync v0.23.0 // indirect
16
+ golang.org/x/sys v0.48.0 // indirect
17
+ golang.org/x/text v0.42.0 // indirect
18
+ )
19
+
20
+ replace github.com/microsoft/TypeScript/tsc => ./third_party/typescript/tsc
package/go.sum ADDED
@@ -0,0 +1,24 @@
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/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
4
+ github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
5
+ github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA=
6
+ github.com/klauspost/compress v1.20.0/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI=
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/peter-evans/patience v0.3.0 h1:rX0JdJeepqdQl1Sk9c9uvorjYYzL2TfgLX1adqYm9cA=
10
+ github.com/peter-evans/patience v0.3.0/go.mod h1:Kmxu5sY1NmBLFSStvXjX1wS9mIv7wMcP/ubucyMOAu0=
11
+ github.com/zeebo/assert v1.3.0 h1:g7C04CbJuIDKNPFHmsk4hwZDO5O+kntRxzaUoNXj+IQ=
12
+ github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
13
+ github.com/zeebo/xxh3 v1.1.0 h1:s7DLGDK45Dyfg7++yxI0khrfwq9661w9EN78eP/UZVs=
14
+ github.com/zeebo/xxh3 v1.1.0/go.mod h1:IisAie1LELR4xhVinxWS5+zf1lA4p0MW4T+w+W07F5s=
15
+ golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
16
+ golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
17
+ golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo=
18
+ golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
19
+ golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE=
20
+ golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc=
21
+ golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI=
22
+ golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E=
23
+ gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q=
24
+ gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA=