Skip to content

Commit afff498

Browse files
committed
feat(ts-ban-ts-comments): add rule mirrorring typescript-eslint's ban-ts-comments rule
Enabled by default in typescript-flavor configs which may be less likely to have typescript-eslint installed and applied.
1 parent 99d2abf commit afff498

8 files changed

Lines changed: 781 additions & 0 deletions

File tree

‎.README/rules/ts-ban-ts-comment.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# `ts-ban-ts-comment`
2+
3+
Disallows `@ts-<directive>` comments (`@ts-expect-error`, `@ts-ignore`,
4+
`@ts-nocheck`, `@ts-check`) or requires that they be accompanied by a
5+
description, mirroring the behavior of
6+
[`@typescript-eslint/ban-ts-comment`](https://typescript-eslint.io/rules/ban-ts-comment/).
7+
8+
This rule is only recommended for `typescript-flavor` configs (i.e., those
9+
using TypeScript-style JSDoc without an actual TypeScript compiler), since
10+
`typescript` configs are expected to already have `typescript-eslint`
11+
enabled, which offers its own `@typescript-eslint/ban-ts-comment` rule for
12+
this purpose.
13+
14+
Note that when `ts-ignore` is banned (the default), this rule always
15+
suggests replacing `@ts-ignore` with `@ts-expect-error`, since the latter
16+
will itself report an error if the following line turns out not to need
17+
suppressing. However, `@ts-expect-error` requires the following line to
18+
*always* error, so it is unsuitable if, e.g., a codebase is type-checked
19+
against multiple TypeScript versions and the line only errors under some
20+
of them; in that scenario, `@ts-ignore` remains the appropriate choice.
21+
Since the rule cannot detect this (it does not run the type checker), such
22+
codebases should instead configure `ts-ignore` as `false` or
23+
`"allow-with-description"` so the necessary `@ts-ignore` comments are not
24+
reported.
25+
26+
## Options
27+
28+
{"gitdown": "options"}
29+
30+
|||
31+
|---|---|
32+
|Context|everywhere|
33+
|Tags|``|
34+
|Recommended|false, but recommended for `typescript-flavor` configs|
35+
|Settings||
36+
37+
## Failing examples
38+
39+
<!-- assertions-failing tsBanTsComment -->
40+
41+
## Passing examples
42+
43+
<!-- assertions-passing tsBanTsComment -->

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -552,6 +552,7 @@ non-default-recommended fixer).
552552
||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
553553
|:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
554554
||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
555+
|Off in TS; On in TS flavor|| [ts-ban-ts-comment](./docs/rules/ts-ban-ts-comment.md#readme) | Disallows (or requires descriptions for) `@ts-<directive>` comments, mirroring `@typescript-eslint/ban-ts-comment`. |
555556
||:wrench:| [ts-method-signature-style](./docs/rules/ts-method-signature-style.md#readme) | Prefers either function properties or method signatures |
556557
|:heavy_check_mark:|| [ts-no-empty-object-type](./docs/rules/ts-no-empty-object-type.md#readme) | Warns against use of the empty object type |
557558
||:wrench:| [ts-no-unnecessary-template-expression](./docs/rules/ts-no-unnecessary-template-expression.md#readme) | Catches unnecessary template expressions such as string expressions within a template literal. |

‎docs/rules/ts-ban-ts-comment.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
<a name="user-content-ts-ban-ts-comment"></a>
2+
<a name="ts-ban-ts-comment"></a>
3+
# <code>ts-ban-ts-comment</code>
4+
5+
Disallows `@ts-<directive>` comments (`@ts-expect-error`, `@ts-ignore`,
6+
`@ts-nocheck`, `@ts-check`) or requires that they be accompanied by a
7+
description, mirroring the behavior of
8+
[`@typescript-eslint/ban-ts-comment`](https://typescript-eslint.io/rules/ban-ts-comment/).
9+
10+
This rule is only recommended for `typescript-flavor` configs (i.e., those
11+
using TypeScript-style JSDoc without an actual TypeScript compiler), since
12+
`typescript` configs are expected to already have `typescript-eslint`
13+
enabled, which offers its own `@typescript-eslint/ban-ts-comment` rule for
14+
this purpose.
15+
16+
Note that when `ts-ignore` is banned (the default), this rule always
17+
suggests replacing `@ts-ignore` with `@ts-expect-error`, since the latter
18+
will itself report an error if the following line turns out not to need
19+
suppressing. However, `@ts-expect-error` requires the following line to
20+
*always* error, so it is unsuitable if, e.g., a codebase is type-checked
21+
against multiple TypeScript versions and the line only errors under some
22+
of them; in that scenario, `@ts-ignore` remains the appropriate choice.
23+
Since the rule cannot detect this (it does not run the type checker), such
24+
codebases should instead configure `ts-ignore` as `false` or
25+
`"allow-with-description"` so the necessary `@ts-ignore` comments are not
26+
reported.
27+
28+
<a name="user-content-ts-ban-ts-comment-options"></a>
29+
<a name="ts-ban-ts-comment-options"></a>
30+
## Options
31+
32+
A single options object has the following properties.
33+
34+
<a name="user-content-ts-ban-ts-comment-options-minimumdescriptionlength"></a>
35+
<a name="ts-ban-ts-comment-options-minimumdescriptionlength"></a>
36+
### <code>minimumDescriptionLength</code>
37+
38+
A minimum character length for descriptions when `allow-with-description` is enabled. Defaults to `3`.
39+
40+
<a name="user-content-ts-ban-ts-comment-options-ts-check"></a>
41+
<a name="ts-ban-ts-comment-options-ts-check"></a>
42+
### <code>ts-check</code>
43+
44+
Whether (and how) to allow `@ts-check` directives.
45+
46+
<a name="user-content-ts-ban-ts-comment-options-ts-expect-error"></a>
47+
<a name="ts-ban-ts-comment-options-ts-expect-error"></a>
48+
### <code>ts-expect-error</code>
49+
50+
Whether (and how) to allow `@ts-expect-error` directives.
51+
52+
<a name="user-content-ts-ban-ts-comment-options-ts-ignore"></a>
53+
<a name="ts-ban-ts-comment-options-ts-ignore"></a>
54+
### <code>ts-ignore</code>
55+
56+
Whether (and how) to allow `@ts-ignore` directives.
57+
58+
<a name="user-content-ts-ban-ts-comment-options-ts-nocheck"></a>
59+
<a name="ts-ban-ts-comment-options-ts-nocheck"></a>
60+
### <code>ts-nocheck</code>
61+
62+
Whether (and how) to allow `@ts-nocheck` directives.
63+
64+
65+
|||
66+
|---|---|
67+
|Context|everywhere|
68+
|Tags|``|
69+
|Recommended|false, but recommended for `typescript-flavor` configs|
70+
|Settings||
71+
72+
<a name="user-content-ts-ban-ts-comment-failing-examples"></a>
73+
<a name="ts-ban-ts-comment-failing-examples"></a>
74+
## Failing examples
75+
76+
The following patterns are considered problems:
77+
78+
````ts
79+
// @ts-ignore
80+
foo();
81+
// Message: Use "@ts-expect-error" instead of "@ts-ignore", as "@ts-ignore" will do nothing if the following line is error-free.
82+
83+
/* @ts-ignore */
84+
foo();
85+
// Message: Use "@ts-expect-error" instead of "@ts-ignore", as "@ts-ignore" will do nothing if the following line is error-free.
86+
87+
// @ts-nocheck
88+
foo();
89+
// Message: Do not use "@ts-nocheck" because it alters compilation errors.
90+
91+
// @ts-nocheck
92+
// Message: Do not use "@ts-nocheck" because it alters compilation errors.
93+
94+
// @ts-check
95+
foo();
96+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"ts-check":true}]
97+
// Message: Do not use "@ts-check" because it alters compilation errors.
98+
99+
// @ts-expect-error
100+
foo();
101+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"ts-expect-error":true}]
102+
// Message: Do not use "@ts-expect-error" because it alters compilation errors.
103+
104+
// @ts-expect-error
105+
foo();
106+
// Message: Include a description after the "@ts-expect-error" directive to explain why the @ts-expect-error is necessary. The description must be 3 characters or longer.
107+
108+
// @ts-expect-error: TS
109+
foo();
110+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"minimumDescriptionLength":10}]
111+
// Message: Include a description after the "@ts-expect-error" directive to explain why the @ts-expect-error is necessary. The description must be 10 characters or longer.
112+
113+
/*
114+
@ts-expect-error: not matching format text */
115+
foo();
116+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"ts-expect-error":{"descriptionFormat":"^: TS\\d+ because .+$"}}]
117+
// Message: The description for the "@ts-expect-error" directive must match the ^: TS\d+ because .+$ format.
118+
````
119+
120+
121+
122+
<a name="user-content-ts-ban-ts-comment-passing-examples"></a>
123+
<a name="ts-ban-ts-comment-passing-examples"></a>
124+
## Passing examples
125+
126+
The following patterns are not considered problems:
127+
128+
````ts
129+
// A regular comment.
130+
/* Another regular comment. */
131+
function foo () {}
132+
133+
/** JSDoc comment. */
134+
function foo () {}
135+
136+
// @ts-check
137+
foo();
138+
139+
foo();
140+
// @ts-nocheck
141+
142+
// @ts-check
143+
foo();
144+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"ts-check":{}}]
145+
146+
// @ts-ignore
147+
foo();
148+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"ts-ignore":false}]
149+
150+
// @ts-expect-error: Suppress next line
151+
foo();
152+
153+
// @ts-expect-error: TS2345 because reasons
154+
foo();
155+
// "jsdoc/ts-ban-ts-comment": ["error"|"warn", {"ts-expect-error":{"descriptionFormat":"^: TS\\d+ because .+$"}}]
156+
````
157+

‎src/index.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
6969
import sortTags from './rules/sortTags.js';
7070
import tagLines from './rules/tagLines.js';
7171
import textEscaping from './rules/textEscaping.js';
72+
import tsBanTsComment from './rules/tsBanTsComment.js';
7273
import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
7374
import tsNoEmptyObjectType from './rules/tsNoEmptyObjectType.js';
7475
import tsNoUnnecessaryTemplateExpression from './rules/tsNoUnnecessaryTemplateExpression.js';
@@ -270,6 +271,7 @@ index.rules = {
270271
'sort-tags': sortTags,
271272
'tag-lines': tagLines,
272273
'text-escaping': textEscaping,
274+
'ts-ban-ts-comment': tsBanTsComment,
273275
'ts-method-signature-style': tsMethodSignatureStyle,
274276
'ts-no-empty-object-type': tsNoEmptyObjectType,
275277
'ts-no-unnecessary-template-expression': tsNoUnnecessaryTemplateExpression,
@@ -367,6 +369,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
367369
'jsdoc/sort-tags': 'off',
368370
'jsdoc/tag-lines': warnOrError,
369371
'jsdoc/text-escaping': 'off',
372+
'jsdoc/ts-ban-ts-comment': 'off',
370373
'jsdoc/ts-method-signature-style': 'off',
371374
'jsdoc/ts-no-empty-object-type': warnOrError,
372375
'jsdoc/ts-no-unnecessary-template-expression': 'off',
@@ -440,6 +443,7 @@ const createRecommendedTypeScriptFlavorRuleset = (warnOrError, flatName) => {
440443
...ruleset.rules,
441444
/* eslint-disable @stylistic/indent -- Extra indent to avoid use by auto-rule-editing */
442445
'jsdoc/no-undefined-types': 'off',
446+
'jsdoc/ts-ban-ts-comment': warnOrError,
443447
/* eslint-enable @stylistic/indent */
444448
},
445449
};

‎src/rules.d.ts‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3065,6 +3065,66 @@ export interface Rules {
30653065
}
30663066
];
30673067

3068+
/** Disallows (or requires descriptions for) `@ts-<directive>` comments, mirroring `@typescript-eslint/ban-ts-comment`. */
3069+
"jsdoc/ts-ban-ts-comment":
3070+
| []
3071+
| [
3072+
{
3073+
/**
3074+
* A minimum character length for descriptions when `allow-with-description` is enabled. Defaults to `3`.
3075+
*/
3076+
minimumDescriptionLength?: number;
3077+
/**
3078+
* Whether (and how) to allow `@ts-check` directives.
3079+
*/
3080+
"ts-check"?:
3081+
| boolean
3082+
| "allow-with-description"
3083+
| {
3084+
/**
3085+
* A regular expression indicating the format the directive should follow
3086+
*/
3087+
descriptionFormat?: string;
3088+
};
3089+
/**
3090+
* Whether (and how) to allow `@ts-expect-error` directives.
3091+
*/
3092+
"ts-expect-error"?:
3093+
| boolean
3094+
| "allow-with-description"
3095+
| {
3096+
/**
3097+
* A regular expression indicating the format the directive should follow
3098+
*/
3099+
descriptionFormat?: string;
3100+
};
3101+
/**
3102+
* Whether (and how) to allow `@ts-ignore` directives.
3103+
*/
3104+
"ts-ignore"?:
3105+
| boolean
3106+
| "allow-with-description"
3107+
| {
3108+
/**
3109+
* A regular expression indicating the format the directive should follow
3110+
*/
3111+
descriptionFormat?: string;
3112+
};
3113+
/**
3114+
* Whether (and how) to allow `@ts-nocheck` directives.
3115+
*/
3116+
"ts-nocheck"?:
3117+
| boolean
3118+
| "allow-with-description"
3119+
| {
3120+
/**
3121+
* A regular expression indicating the format the directive should follow
3122+
*/
3123+
descriptionFormat?: string;
3124+
};
3125+
}
3126+
];
3127+
30683128
/** Prefers either function properties or method signatures */
30693129
"jsdoc/ts-method-signature-style":
30703130
| []

0 commit comments

Comments
 (0)