From b877bab7388a906769dbb64e85f3e77aa7588a5e Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Thu, 7 Dec 2023 12:01:17 -0800
Subject: [PATCH] docs: explain which production of ts_project to lint (#76)

* docs: explain which production of ts_project to lint

Fixes #74

* fix: typings not typecheck has to be used
---
 docs/eslint.md  | 25 +++++++++++++++++++++++++
 lint/eslint.bzl | 25 +++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/eslint.md b/docs/eslint.md
index 0993a0e3..ee83297a 100644
--- a/docs/eslint.md
+++ b/docs/eslint.md
@@ -13,6 +13,31 @@ eslint = eslint_aspect(
 )
 ```
 
+### With ts_project
+
+Note, when used with `ts_project` and a custom `transpiler`,
+the macro expands to several targets,
+see https://github.com/aspect-build/rules_ts/blob/main/docs/transpiler.md#macro-expansion.
+
+Since you want to lint the original TypeScript source files, the `ts_project` rule produced
+by the macro is the one you want to lint, so when used with an `eslint_test` you should use
+the `[name]_typings` label:
+
+```
+ts_project(
+    name = "my_ts",
+    transpiler = swc,
+    ...
+)
+
+eslint_test(
+    name = "lint_my_ts",
+    srcs = [":my_ts_typings"],
+)
+```
+
+See the [react example](https://github.com/bazelbuild/examples/blob/b498bb106b2028b531ceffbd10cc89530814a177/frontend/react/src/BUILD.bazel#L86-L92)
+
 
 <a id="eslint_action"></a>
 
diff --git a/lint/eslint.bzl b/lint/eslint.bzl
index 3ea17b67..3f983464 100644
--- a/lint/eslint.bzl
+++ b/lint/eslint.bzl
@@ -10,6 +10,31 @@ eslint = eslint_aspect(
     configs = "@@//path/to:eslintrc",
 )
 ```
+
+### With ts_project
+
+Note, when used with `ts_project` and a custom `transpiler`,
+the macro expands to several targets,
+see https://github.com/aspect-build/rules_ts/blob/main/docs/transpiler.md#macro-expansion.
+
+Since you want to lint the original TypeScript source files, the `ts_project` rule produced
+by the macro is the one you want to lint, so when used with an `eslint_test` you should use
+the `[name]_typings` label:
+
+```
+ts_project(
+    name = "my_ts",
+    transpiler = swc,
+    ...
+)
+
+eslint_test(
+    name = "lint_my_ts",
+    srcs = [":my_ts_typings"],
+)
+```
+
+See the [react example](https://github.com/bazelbuild/examples/blob/b498bb106b2028b531ceffbd10cc89530814a177/frontend/react/src/BUILD.bazel#L86-L92)
 """
 
 load("@aspect_bazel_lib//lib:copy_to_bin.bzl", "COPY_FILE_TO_BIN_TOOLCHAINS", "copy_files_to_bin_actions")