feat: add generate_trace option to run TypeScript with `--generateTra…

…ce` (#765)

docs/troubleshooting.md

@@ -177,3 +177,7 @@ Possible solutions:
 ```
 
 * Use pnpm workspaces and `npm_package`/`npm_link_package` in between the `ts_project` rule and the `webpack` rule, so that the loader finds files under the `node_modules` tree like it would with third-party npm packages.
+
+
+# Troubleshooting performance issues 
+Running your build with `--@aspect_rules_ts//ts:generate_tsc_trace` causes the `ts_project` rule to run with the `generate_trace` option enabled. This generates a profile that can be analyzed to understand TypeScript compilation performance. The trace files will be written in `bazel-bin/<package>/<target>_trace/`. To analyze it use ChromeDevTools or [@typescript/analyze-trace](https://www.npmjs.com/package/@typescript/analyze-trace). See the [TypeScript documentation](https://github.com/microsoft/TypeScript-wiki/blob/main/Performance-Tracing.md) for more information.

examples/generate_trace/BUILD.bazel

@@ -0,0 +1,6 @@
+load("@aspect_rules_ts//ts:defs.bzl", "ts_project")
+
+ts_project(
+    name = "lib",
+    generate_trace = True,
+)

examples/generate_trace/a.ts

@@ -0,0 +1 @@
+export const a: string = 'a'

examples/generate_trace/tsconfig.json

@@ -0,0 +1 @@
+{}

ts/BUILD.bazel

@@ -87,6 +87,12 @@ bool_flag(
     visibility = ["//visibility:public"],
 )
 
+bool_flag(
+    name = "generate_tsc_trace",
+    build_setting_default = False,
+    visibility = ["//visibility:public"],
+)
+
 # Note, users could use a Transition to make a subgraph of their depgraph opt-in to skipLibCheck.
 config_setting(
     name = "skip_lib_check.always",
@@ -119,12 +125,23 @@ config_setting(
     },
 )
 
+config_setting(
+    name = "generate_tsc_trace_flag",
+    flag_values = {
+        ":generate_tsc_trace": "true",
+    },
+)
+
 options(
     name = "options",
     default_to_tsc_transpiler = select({
         ":default_to_tsc_transpiler_flag": True,
         "//conditions:default": False,
     }),
+    generate_tsc_trace = select({
+        ":generate_tsc_trace_flag": True,
+        "//conditions:default": False,
+    }),
     skip_lib_check = select(
         {
             "@aspect_rules_ts//ts:skip_lib_check.always": True,

ts/defs.bzl

@@ -52,6 +52,7 @@ def ts_project(
         transpiler = None,
         declaration_transpiler = None,
         ts_build_info_file = None,
+        generate_trace = None,
         tsc = _tsc,
         tsc_worker = _tsc_worker,
         validate = True,
@@ -239,6 +240,9 @@ def ts_project(
             Instructs Bazel *not* to expect `.js` or `.js.map` outputs for `.ts` sources.
         ts_build_info_file: The user-specified value of `tsBuildInfoFile` from the tsconfig.
             Helps Bazel to predict the path where the .tsbuildinfo output is written.
+        generate_trace: Whether to generate a trace file for TypeScript compiler performance analysis.
+            When enabled, creates a trace directory containing performance tracing information that can be
+            loaded in chrome://tracing. Use the `--@aspect_rules_ts//ts:generate_tsc_trace` flag to enable this by default.
 
         supports_workers: Whether the "Persistent Worker" protocol is enabled.
             This uses a custom `tsc` compiler to make rebuilds faster.
@@ -468,6 +472,7 @@ def ts_project(
         source_map = source_map,
         declaration_map = declaration_map,
         ts_build_info_file = ts_build_info_file,
+        generate_trace = generate_trace,
         out_dir = out_dir,
         root_dir = root_dir,
         js_outs = tsc_js_outs,

ts/private/options.bzl

@@ -13,7 +13,7 @@ Please read https://docs.aspect.build/rules/aspect_rules_ts/docs/transpiler
 
 OptionsInfo = provider(
     doc = "Internal: Provider that carries verbosity and global worker support information.",
-    fields = ["args", "default_to_tsc_transpiler", "verbose", "supports_workers"],
+    fields = ["args", "default_to_tsc_transpiler", "verbose", "supports_workers", "generate_tsc_trace"],
 )
 
 def _options_impl(ctx):
@@ -47,6 +47,7 @@ def _options_impl(ctx):
         args = args,
         supports_workers = ctx.attr.supports_workers,
         default_to_tsc_transpiler = ctx.attr.default_to_tsc_transpiler,
+        generate_tsc_trace = ctx.attr.generate_tsc_trace,
     )
 
 options = rule(
@@ -56,5 +57,6 @@ options = rule(
         "verbose": attr.bool(),
         "supports_workers": attr.bool(),
         "skip_lib_check": attr.bool(),
+        "generate_tsc_trace": attr.bool(),
     },
 )

ts/private/ts_lib.bzl

@@ -162,6 +162,9 @@ COMPILER_OPTION_ATTRS = {
     "ts_build_info_file": attr.string(
         doc = "https://www.typescriptlang.org/tsconfig#tsBuildInfoFile",
     ),
+    "generate_trace": attr.bool(
+        doc = "https://www.typescriptlang.org/tsconfig/#generateTrace",
+    ),
 }
 
 # tsc knows how to produce the following kinds of output files.

ts/private/ts_project.bzl

@@ -196,6 +196,8 @@ See https://github.com/aspect-build/rules_ts/issues/361 for more details.
         common_args.extend(["--tsBuildInfoFile", to_output_relative_path(ctx.outputs.buildinfo_out)])
         outputs.append(ctx.outputs.buildinfo_out)
 
+    should_generate_tsc_trace = options.generate_tsc_trace or ctx.attr.generate_trace
+
     output_sources = js_outs + map_outs + assets_outs + ctx.files.pretranspiled_js
     output_types = typings_outs + typing_maps_outs + ctx.files.pretranspiled_dts
 
@@ -241,16 +243,24 @@ See https://github.com/aspect-build/rules_ts/issues/361 for more details.
     #  or
     #  - not invoking tsc for output files at all
     if ctx.attr.isolated_typecheck or not (use_tsc_for_js or use_tsc_for_dts):
+        typecheck_outputs = []
+
         # The type-checking action still need to produce some output, so we output the stdout
         # to a .typecheck file that ends up in the typecheck output group.
         typecheck_output = ctx.actions.declare_file(ctx.attr.name + ".typecheck")
         typecheck_outs.append(typecheck_output)
+        typecheck_outputs.append(typecheck_output)
 
         typecheck_arguments = ctx.actions.args()
         typecheck_arguments.add_all(common_args)
 
         typecheck_arguments.add("--noEmit")
 
+        if should_generate_tsc_trace:
+            tsc_trace_dir = ctx.actions.declare_directory(ctx.attr.name + "_trace")
+            typecheck_outputs.append(tsc_trace_dir)
+            typecheck_arguments.add_all(["--generateTrace", to_output_relative_path(tsc_trace_dir)])
+
         env = {
             "BAZEL_BINDIR": ctx.bin_dir.path,
         }
@@ -271,7 +281,7 @@ See https://github.com/aspect-build/rules_ts/issues/361 for more details.
             executable = executable,
             inputs = transitive_inputs_depset,
             arguments = [typecheck_arguments],
-            outputs = [typecheck_output],
+            outputs = typecheck_outputs,
             mnemonic = "TsProjectCheck",
             execution_requirements = execution_requirements,
             resource_set = resource_set(ctx.attr),
@@ -302,6 +312,11 @@ See https://github.com/aspect-build/rules_ts/issues/361 for more details.
             # Not emitting declarations
             tsc_emit_arguments.add("--declaration", "false")
 
+        if should_generate_tsc_trace and not ctx.attr.isolated_typecheck:
+            tsc_trace_dir = ctx.actions.declare_directory(ctx.attr.name + "_trace")
+            outputs.append(tsc_trace_dir)
+            tsc_emit_arguments.add_all(["--generateTrace", to_output_relative_path(tsc_trace_dir)])
+
         inputs_depset = inputs if ctx.attr.isolated_typecheck else transitive_inputs_depset
 
         if supports_workers: