fix(typescript): document tsc_test for typecheck-only

Author: alexeagle

packages/typescript/index.docs.bzl

@@ -51,6 +51,20 @@ Then call it, using the [`npm_package_bin`](Built-ins#npm_package_bin) documenta
 Here is an example:
 https://github.com/bazelbuild/rules_nodejs/blob/3.2.2/internal/node/test/BUILD.bazel#L491-L507
 
+### tsc_test
+
+`tsc_test` is generated alongside `tsc`.
+It is identical, except that Bazel treats it as a test target, producing only an exit code
+rather than files to be consumed by other steps in the build.
+
+This can be used for a build with `--noEmit`, so that TypeScript is purely used for
+type-checking and not for producing any build outputs.
+
+To use it, add the load statement `load("@npm//typescript:index.bzl", "tsc_test")` to your BUILD file.
+(Possibly replacing `@npm` with the name of the repository where you installed dependencies)
+
+See example in https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/tsc_test
+
 ### ts_project
 
 `ts_project` simply runs `tsc --project`, with Bazel knowing which outputs to expect based on the TypeScript compiler options,
@@ -150,6 +164,10 @@ your editor references, or `extends` from it, to keep consistent settings for th
 
 Anything you do with TypeScript is possible with `ts_project`, including json imports, type-checking only,
 transpile only, outdir, rootdir, and so on.
+
+> To use `ts_project` for typecheck-only, you'll still need to use --declaration so that .d.ts files are produced.
+> Alternatively, see the `tsc_test` rule documented above.
+
 See many examples in our test cases:
 https://github.com/bazelbuild/rules_nodejs/tree/stable/packages/typescript/test/ts_project
 """

packages/typescript/test/tsc_test/BUILD.bazel

@@ -0,0 +1,12 @@
+load("@npm//typescript:index.bzl", "tsc_test")
+
+# Bazel only runs actions as required to produce requested outputs.
+# If we don't want TypeScript to emit anything at all, even .d.ts files,
+# then we can't make it a build step as it will never run.
+# Instead we invoke the bare `tsc` binary as a *_test rule, so that Bazel
+# always runs it to produce an exit code.
+tsc_test(
+    name = "typecheck_only",
+    args = ["$(location check_me.ts)"],
+    data = ["check_me.ts"],
+)

packages/typescript/test/tsc_test/check_me.ts

@@ -0,0 +1,11 @@
+export const a: string = 'a'
+
+// Uncomment this last line to observe the typecheck_only test fails:
+// FAIL: //packages/typescript/test/tsc_test:typecheck_only
+// (see execroot/build_bazel_rules_nodejs/bazel-out/k8-fastbuild/testlogs/packages/typescript/test/tsc_test/typecheck_only/test.log)
+// INFO: From Testing //packages/typescript/test/tsc_test:typecheck_only:
+// ==================== Test output for //packages/typescript/test/tsc_test:typecheck_only:
+// packages/typescript/test/tsc_test/check_me.ts(11,14): error TS2322: Type 'string' is not assignable to type 'number'.
+// ================================================================================
+
+// export const b: number = 'b'