@kongyo2/ts-comment-scanner 1.11.1 → 1.17.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.
- package/dist/astgrep.d.ts +51 -0
- package/dist/astgrep.d.ts.map +1 -0
- package/dist/astgrep.js +85 -0
- package/dist/astgrep.js.map +1 -0
- package/dist/directives.d.ts +32 -4
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +241 -95
- package/dist/directives.js.map +1 -1
- package/dist/imports.d.ts +36 -0
- package/dist/imports.d.ts.map +1 -0
- package/dist/imports.js +119 -0
- package/dist/imports.js.map +1 -0
- package/dist/remove.d.ts +14 -7
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +254 -81
- package/dist/remove.js.map +1 -1
- package/dist/scanner.d.ts +6 -11
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +79 -23
- package/dist/scanner.js.map +1 -1
- package/dist/splice.d.ts.map +1 -1
- package/dist/splice.js +19 -9
- package/dist/splice.js.map +1 -1
- package/package.json +1 -1
- package/src/astgrep.ts +115 -0
- package/src/directives.ts +275 -99
- package/src/imports.ts +145 -0
- package/src/remove.ts +318 -86
- package/src/scanner.ts +87 -24
- package/src/splice.ts +19 -9
package/src/directives.ts
CHANGED
|
@@ -34,6 +34,14 @@ interface DirectiveRule {
|
|
|
34
34
|
* `^\s?Stryker` on the comment value, JSLint's no-space-after-marker rule).
|
|
35
35
|
*/
|
|
36
36
|
rawText?: boolean;
|
|
37
|
+
/**
|
|
38
|
+
* Match against the comment's value — the text between its markers,
|
|
39
|
+
* neither split into lines nor trimmed — for tools that trim the value
|
|
40
|
+
* themselves, so the pattern spells out the whitespace they skip
|
|
41
|
+
* (JavaScript's `\s`, with U+0085 for the Rust and Go tools, whose
|
|
42
|
+
* whitespace takes in the next-line character).
|
|
43
|
+
*/
|
|
44
|
+
value?: boolean;
|
|
37
45
|
/**
|
|
38
46
|
* Skip `/**`-opened block comments: the datadog analyzer skips only
|
|
39
47
|
* whitespace before its marker, so a leading `*` defeats it.
|
|
@@ -41,8 +49,9 @@ interface DirectiveRule {
|
|
|
41
49
|
notDocblock?: boolean;
|
|
42
50
|
/**
|
|
43
51
|
* Match content lines verbatim, without stripping JSDoc `*` prefixes, for
|
|
44
|
-
* tools that compare the literal comment value (
|
|
45
|
-
* trimmed body, so `/**
|
|
52
|
+
* tools that compare the literal comment value (stylelint takes the first
|
|
53
|
+
* token of the trimmed body, so `/** stylelint-disable */` is NOT a
|
|
54
|
+
* command to it).
|
|
46
55
|
*/
|
|
47
56
|
keepStars?: boolean;
|
|
48
57
|
/**
|
|
@@ -92,34 +101,69 @@ const JSX_PRAGMAS: ReadonlyMap<string, string> = new Map(
|
|
|
92
101
|
// typescript-strict-plugin's two pragmas; the capture is the `-ignore` suffix.
|
|
93
102
|
const tsStrictName = (match: RegExpExecArray): string => (match[1] === undefined ? "@ts-strict" : "@ts-strict-ignore");
|
|
94
103
|
|
|
104
|
+
/**
|
|
105
|
+
* The name of a coverage hint, from the tool and the mode its rule captures
|
|
106
|
+
* (one pair per alternative): `<tool>-ignore-<mode>`, except that Node's
|
|
107
|
+
* `ignore next` keeps the plain `node:coverage-ignore`, as the line-counted
|
|
108
|
+
* pragma it is to Node, and its `disable`/`enable` go without `ignore`.
|
|
109
|
+
*/
|
|
110
|
+
function coverageName(match: RegExpExecArray): string {
|
|
111
|
+
const [tool, mode] = match.slice(1).filter((group) => group !== undefined) as [string, string];
|
|
112
|
+
if (tool !== "node:coverage") return `${tool}-ignore-${mode}`;
|
|
113
|
+
if (mode.endsWith("next")) return "node:coverage-ignore";
|
|
114
|
+
return mode === "disable" || mode === "enable" ? `node:coverage-${mode}` : `node:coverage-ignore-${mode}`;
|
|
115
|
+
}
|
|
116
|
+
|
|
95
117
|
const RULES: DirectiveRule[] = [
|
|
96
|
-
// ESLint and oxlint. ESLint
|
|
118
|
+
// ESLint and oxlint. ESLint takes the label from the trimmed comment value
|
|
97
119
|
// (`[a-z]+(?:-[a-z]+)*` followed by whitespace or the end) and honours only
|
|
98
120
|
// `eslint-disable-line`/`-next-line` in `//` comments; oxlint reads all four
|
|
99
121
|
// commands, and its own prefix, from comments of either kind, under the
|
|
100
122
|
// same boundary. A JSDoc star in front of the label defeats both, and so
|
|
101
|
-
// does a glued suffix (`eslint-disable-foo`, `eslint-disable:foo`).
|
|
102
|
-
|
|
103
|
-
//
|
|
104
|
-
//
|
|
105
|
-
//
|
|
106
|
-
//
|
|
107
|
-
//
|
|
108
|
-
{
|
|
109
|
-
pattern:
|
|
123
|
+
// does a glued suffix (`eslint-disable-foo`, `eslint-disable:foo`). oxlint
|
|
124
|
+
// trims and splits on Rust's whitespace, which adds U+0085 to what `\s`
|
|
125
|
+
// matches, so a next-line character may stand around the label too, on a
|
|
126
|
+
// line of its own in front of it included — hence the match on the whole
|
|
127
|
+
// value. Bun's linter ports both readings (all labels, U+0085 included, in
|
|
128
|
+
// its oxlint mode), and oxc's React Compiler trims the same way before it
|
|
129
|
+
// looks for a react-hooks rule.
|
|
130
|
+
{
|
|
131
|
+
pattern: /^[\s\u0085]*((?:eslint|oxlint)-(?:disable(?:-next-line|-line)?|enable))(?=[\s\u0085]|$)/,
|
|
132
|
+
value: true,
|
|
133
|
+
name: (match) => match[1] as string,
|
|
134
|
+
},
|
|
135
|
+
// React Compiler (babel-plugin-react-compiler) skips the functions a
|
|
136
|
+
// suppression of its react-hooks rules covers. It searches every comment
|
|
137
|
+
// value for `eslint-disable-next-line ` or `eslint-disable ` with one of
|
|
138
|
+
// the rules right after that one space, anywhere in the text — JSDoc blocks
|
|
139
|
+
// and mid-text mentions included. Its `eslint-enable` pattern never takes
|
|
140
|
+
// effect: the range is closed in the loop pass that found its
|
|
141
|
+
// `eslint-disable`, before a later comment is read. (The compiler's Rust
|
|
142
|
+
// port and Bun's and oxc's ports only read a value that opens with the
|
|
143
|
+
// suppression, which the rule above already names.)
|
|
144
|
+
{
|
|
145
|
+
pattern: /eslint-(disable(?:-next-line)?) react-hooks\/(?:exhaustive-deps|rules-of-hooks)/,
|
|
110
146
|
rawText: true,
|
|
111
147
|
name: (match) => `eslint-${match[1] as string}`,
|
|
112
148
|
},
|
|
113
|
-
// ESLint
|
|
114
|
-
//
|
|
115
|
-
//
|
|
116
|
-
|
|
117
|
-
|
|
149
|
+
// ESLint's other labels, read from block comments only. ESLint 10 reports
|
|
150
|
+
// `/* eslint-env */` comments as no longer supported, and ESLint 9 warns of
|
|
151
|
+
// them in flat config. The label alone makes a configuration comment:
|
|
152
|
+
// ESLint lists a bare `/* eslint */`, `/* global */` or `/* exported */`
|
|
153
|
+
// with the others and warns of it under noInlineConfig. Same boundary as
|
|
154
|
+
// above.
|
|
155
|
+
{ pattern: /^[\s\u0085]*(eslint-env)(?=[\s\u0085]|$)/, blockOnly: true, keepStars: true, name: "eslint-env" },
|
|
156
|
+
// ESLint 8 and 9's eslintrc mode instead find `eslint-env` with a regex over
|
|
157
|
+
// the whole file text, /\/\*\s*eslint-env\s.+?(?:\*\/|$)/gsu, so a
|
|
158
|
+
// `/* eslint-env mocha */` written inside any comment — `// see /*
|
|
159
|
+
// eslint-env mocha */`, or after other text in a block comment — enables
|
|
160
|
+
// the environment as well.
|
|
161
|
+
{ pattern: /\/\*\s*eslint-env\s/, rawText: true, name: "eslint-env" },
|
|
162
|
+
{ pattern: /^[\s\u0085]*eslint(?=[\s\u0085]|$)/, name: "eslint", blockOnly: true, keepStars: true },
|
|
118
163
|
{
|
|
119
|
-
pattern: /^(globals?|exported)\s
|
|
164
|
+
pattern: /^[\s\u0085]*(globals?|exported)(?=[\s\u0085]|$)/,
|
|
120
165
|
name: (match) => match[1] as string,
|
|
121
166
|
blockOnly: true,
|
|
122
|
-
joinLines: true,
|
|
123
167
|
keepStars: true,
|
|
124
168
|
},
|
|
125
169
|
// TSLint (legacy): tslint:(enable|disable)(-line|-next-line)? ending at a
|
|
@@ -164,14 +208,13 @@ const RULES: DirectiveRule[] = [
|
|
|
164
208
|
name: "rome-ignore",
|
|
165
209
|
anyLine: true,
|
|
166
210
|
},
|
|
167
|
-
// ast-grep
|
|
168
|
-
//
|
|
169
|
-
//
|
|
170
|
-
//
|
|
171
|
-
// it to the rules named.
|
|
172
|
-
//
|
|
173
|
-
|
|
174
|
-
{ pattern: /^\P{Alphabetic}*ast-grep-ignore/u, rawText: true, name: "ast-grep-ignore" },
|
|
211
|
+
// ast-grep (`is_suppression_comment` in its `combined.rs`) reads a comment
|
|
212
|
+
// holding `ast-grep-ignore` as a suppression: anywhere in the text up to
|
|
213
|
+
// 0.45.2, and since 0.45.3 only where its first alphabetic character starts
|
|
214
|
+
// the marker, so that a word in front makes it prose. `: rule-id, ...`
|
|
215
|
+
// limits it to the rules named. What it covers depends on where it stands
|
|
216
|
+
// (see astgrep.ts), whatever directive names the comment.
|
|
217
|
+
{ pattern: /ast-grep-ignore/, rawText: true, name: "ast-grep-ignore" },
|
|
175
218
|
// Deno. deno_lint compares the first whitespace-delimited token of the
|
|
176
219
|
// trimmed comment text with the directive, so a JSDoc star in front defeats
|
|
177
220
|
// it; `deno-lint-ignore` may be a block comment (the only form inside JSX
|
|
@@ -196,16 +239,17 @@ const RULES: DirectiveRule[] = [
|
|
|
196
239
|
// `configurationComment` prefix cannot be known here, so only the default
|
|
197
240
|
// marker is matched.
|
|
198
241
|
{ pattern: /^\S+/, keepStars: true, name: (match) => stylelintDirective(match[0]) },
|
|
199
|
-
// Formatter suppressions (prettier, and oxfmt which
|
|
200
|
-
// isPrettierIgnoreComment compares `comment.value.trim()` with
|
|
201
|
-
// string, for line and block comments alike,
|
|
202
|
-
//
|
|
203
|
-
//
|
|
204
|
-
// `
|
|
205
|
-
//
|
|
206
|
-
//
|
|
207
|
-
|
|
208
|
-
{ pattern: /^
|
|
242
|
+
// Formatter suppressions (prettier, and oxfmt, which honours both markers).
|
|
243
|
+
// Prettier's isPrettierIgnoreComment compares `comment.value.trim()` with
|
|
244
|
+
// the exact string, for line and block comments alike, and oxfmt's
|
|
245
|
+
// `is_suppression_marker` compares the value trimmed of Rust's whitespace,
|
|
246
|
+
// which takes in U+0085 — so the marker must be the whole value:
|
|
247
|
+
// hyphenated lookalikes (`oxfmt-ignore-more`) and prose stay ordinary, and
|
|
248
|
+
// so do `prettier-ignore-start`/`-end`, which prettier only reads in
|
|
249
|
+
// Markdown. The literal comparison also means a JSDoc `*` before the marker
|
|
250
|
+
// (`/** prettier-ignore */`) leaves the comment ordinary.
|
|
251
|
+
{ pattern: /^[\s\u0085]*prettier-ignore[\s\u0085]*$/, value: true, name: "prettier-ignore" },
|
|
252
|
+
{ pattern: /^[\s\u0085]*oxfmt-ignore[\s\u0085]*$/, value: true, name: "oxfmt-ignore" },
|
|
209
253
|
// dprint, and `deno fmt`, which runs dprint's TypeScript plugin with
|
|
210
254
|
// `deno-fmt-ignore`/`deno-fmt-ignore-file` as its comment texts. The file
|
|
211
255
|
// pragma is a starts-with check on the file's leading comments, after only
|
|
@@ -265,34 +309,59 @@ const RULES: DirectiveRule[] = [
|
|
|
265
309
|
blockOnly: true,
|
|
266
310
|
name: "beautify",
|
|
267
311
|
},
|
|
268
|
-
// Coverage
|
|
269
|
-
// next-
|
|
270
|
-
//
|
|
271
|
-
//
|
|
272
|
-
//
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
// must never spell a range pragma out: the v8 provider finds one on any line
|
|
284
|
-
// of this file too, and would drop the rest of it from coverage.
|
|
285
|
-
{
|
|
286
|
-
pattern: /^node:coverage\s+(?:ignore\s+(start|stop)(?=\W|$)|(disable|enable|ignore)\b)/,
|
|
287
|
-
name: (match) =>
|
|
288
|
-
match[1] === undefined ? `node:coverage-${match[2] as string}` : `node:coverage-ignore-${match[1]}`,
|
|
312
|
+
// Coverage hints, named for the tool and the mode (see coverageName) so
|
|
313
|
+
// that consumers can tell the next-node hints (`next`, `if`, `else`) from
|
|
314
|
+
// the file and range ones. Each coverage tool reads them its own way, and
|
|
315
|
+
// a comment counts when one of them reads it. Comments in this file must
|
|
316
|
+
// never open with a hint, nor spell a range hint out on any line: Vitest's
|
|
317
|
+
// v8 provider would read them here too and change this file's coverage.
|
|
318
|
+
//
|
|
319
|
+
// ast-v8-to-istanbul (Vitest's v8 provider) cuts `/**` or `/*`, then a
|
|
320
|
+
// `//`, off the comment and wants the tool, `ignore` and a mode at the
|
|
321
|
+
// start of what is left, with any whitespace between, line breaks
|
|
322
|
+
// included; a JSDoc star in front of the hint on a later line defeats it.
|
|
323
|
+
{
|
|
324
|
+
pattern: /^\/(?:\/|\*\*?(?:\/\/)?)\s*(istanbul|[cv]8|node:coverage)\s+ignore\s+(if|else|next|file)(?=\W|$)/,
|
|
325
|
+
rawText: true,
|
|
326
|
+
name: coverageName,
|
|
289
327
|
},
|
|
290
|
-
//
|
|
291
|
-
//
|
|
328
|
+
// istanbul-lib-instrument (nyc, babel-plugin-istanbul, Vitest's istanbul
|
|
329
|
+
// provider) matches the comment value the same way but cuts no JSDoc star;
|
|
330
|
+
// its swc port, swc-plugin-coverage-instrument, takes Rust's whitespace,
|
|
331
|
+
// U+0085 included.
|
|
292
332
|
{
|
|
293
|
-
pattern:
|
|
294
|
-
|
|
295
|
-
|
|
333
|
+
pattern: /^[\s\u0085]*(istanbul)[\s\u0085]+ignore[\s\u0085]+(if|else|next|file)(?=\W|$)/,
|
|
334
|
+
value: true,
|
|
335
|
+
name: coverageName,
|
|
336
|
+
},
|
|
337
|
+
// monocart-coverage-reports trims the value and wants `v8 ignore` or
|
|
338
|
+
// `c8 ignore`, one space between, then a mode as the prefix of what
|
|
339
|
+
// follows past any whitespace, so `nextLine` is `next` and `stopwatch` a
|
|
340
|
+
// range hint; after `node:coverage`, `disable`, `enable` or `ignore next`.
|
|
341
|
+
{
|
|
342
|
+
pattern: /^\/[/*]\s*(?:([cv]8) ignore\s*(next|start|stop)|(node:coverage)\s*(disable|enable|ignore next))/,
|
|
343
|
+
rawText: true,
|
|
344
|
+
name: coverageName,
|
|
345
|
+
},
|
|
346
|
+
// c8 (v8-to-istanbul) and Node's test runner search every line for the
|
|
347
|
+
// block comment with single spaces in it, so it counts inside another
|
|
348
|
+
// comment too: `foo(); // see /* c8 ... */` exempts the call's line.
|
|
349
|
+
{
|
|
350
|
+
pattern:
|
|
351
|
+
/\/\* (?:([cv]8|node:coverage) ignore (next)|([cv]8) ignore (start|stop)|(node:coverage) (disable|enable))/,
|
|
352
|
+
rawText: true,
|
|
353
|
+
name: coverageName,
|
|
354
|
+
},
|
|
355
|
+
// ast-v8-to-istanbul and Vitest's istanbul provider find the ranges with a
|
|
356
|
+
// text search over every line, after any other text, and split the lines
|
|
357
|
+
// at `\n` alone, so a lone CR or U+2028 can stand between the words. The
|
|
358
|
+
// istanbul provider wants no boundary after the mode: `startup` opens a
|
|
359
|
+
// range to it.
|
|
360
|
+
{
|
|
361
|
+
pattern:
|
|
362
|
+
/(?:(istanbul)(?:[^\S\r\n]|\r(?!\n))+ignore(?:[^\S\r\n]|\r(?!\n))+(start|stop)|([cv]8|node:coverage)(?:[^\S\r\n]|\r(?!\n))+ignore(?:[^\S\r\n]|\r(?!\n))+(start|stop)(?=\W|$))/,
|
|
363
|
+
rawText: true,
|
|
364
|
+
name: coverageName,
|
|
296
365
|
},
|
|
297
366
|
// type-coverage: substring match in any comment. There is no ignore-file
|
|
298
367
|
// comment — file-level ignores are a CLI option only.
|
|
@@ -346,9 +415,12 @@ const RULES: DirectiveRule[] = [
|
|
|
346
415
|
name: (match) => `$Flow${match[1]}`,
|
|
347
416
|
},
|
|
348
417
|
// React Compiler also skips a component under a Flow suppression of its
|
|
349
|
-
// `react-rule-*` errors, found anywhere in a comment.
|
|
418
|
+
// `react-rule-*` errors, found anywhere in a comment. After `FlowFixMe`,
|
|
419
|
+
// babel-plugin-react-compiler takes `\w*`, and oxc's Rust port (in
|
|
420
|
+
// oxc-transform-react) any letter or digit, non-ASCII ones included
|
|
421
|
+
// (`char::is_alphanumeric`).
|
|
350
422
|
{
|
|
351
|
-
pattern: /\$(?:(FlowFixMe)\
|
|
423
|
+
pattern: /\$(?:(FlowFixMe)[\p{Alphabetic}\p{N}_]*|(FlowExpectedError|FlowIssue))\[react-rule/u,
|
|
352
424
|
rawText: true,
|
|
353
425
|
name: (match) => `$${match[1] ?? match[2]}`,
|
|
354
426
|
},
|
|
@@ -359,19 +431,44 @@ const RULES: DirectiveRule[] = [
|
|
|
359
431
|
},
|
|
360
432
|
// Bundlers. webpack's gate regex requires the colon to follow the key
|
|
361
433
|
// immediately and evaluates the body as an object literal, which JSDoc
|
|
362
|
-
// stars break. Turbopack reads the whole
|
|
363
|
-
//
|
|
364
|
-
//
|
|
434
|
+
// stars break. Turbopack reads the whole comment as one `key: value` pair
|
|
435
|
+
// instead, split at its first colon and trimmed of Rust's whitespace,
|
|
436
|
+
// which takes in U+0085 — so blanks and line breaks may stand before the
|
|
437
|
+
// colon — and honours webpackIgnore and webpackExports as well as its own
|
|
438
|
+
// keys.
|
|
365
439
|
{ pattern: /^webpack[A-Z][A-Za-z]+:/, name: "webpack-magic-comment", keepStars: true },
|
|
366
440
|
{
|
|
367
|
-
pattern: /^(?:turbopack[A-Z][A-Za-z]+|webpack(?:Ignore|Exports))\s*:/,
|
|
441
|
+
pattern: /^[\s\u0085]*(?:turbopack[A-Z][A-Za-z]+|webpack(?:Ignore|Exports))[\s\u0085]*:/,
|
|
442
|
+
value: true,
|
|
368
443
|
name: "turbopack-magic-comment",
|
|
369
|
-
keepStars: true,
|
|
370
444
|
},
|
|
371
|
-
//
|
|
372
|
-
//
|
|
373
|
-
//
|
|
374
|
-
|
|
445
|
+
// Rspack reads block comments only, and has found the keys three ways. 1.x
|
|
446
|
+
// pulls `webpack<Name>: value` pairs out of the text wherever they stand —
|
|
447
|
+
// glued to other words, behind prose or JSDoc stars — with any whitespace
|
|
448
|
+
// before the colon, U+0085 included. 2.0 parses the whole comment as an
|
|
449
|
+
// object literal, so a key may be quoted. Since 2.1 the `rspack` prefix
|
|
450
|
+
// works too (`rspackChunkName`, `rspackIgnore`), and the text is parsed
|
|
451
|
+
// from the first key, quoted or not, that no word character (Rust's
|
|
452
|
+
// Unicode `\w`) precedes. The value is not checked: Rspack 2 leaves a
|
|
453
|
+
// `new URL()` alone when its ignore key holds anything but a boolean.
|
|
454
|
+
{
|
|
455
|
+
pattern:
|
|
456
|
+
/webpack[A-Z][A-Za-z]+[\s\u0085]*:|(?<![\p{Alphabetic}\p{M}\p{Nd}\p{Pc}\p{Join_Control}])(?:rspack[A-Z][A-Za-z]+|(["'])(?:webpack|rspack)[A-Z][A-Za-z]+\1)[\s\u0085]*:/u,
|
|
457
|
+
rawText: true,
|
|
458
|
+
blockOnly: true,
|
|
459
|
+
name: "rspack-magic-comment",
|
|
460
|
+
},
|
|
461
|
+
// Vite tests the source of an `import()` call (or of a `new URL()` or
|
|
462
|
+
// worker argument) against /\/\*\s*@vite-ignore\s*\*\// (hasViteIgnoreRE
|
|
463
|
+
// in importAnalysis), so the block comment counts inside another comment
|
|
464
|
+
// too (`// see /* @vite-ignore */`). Rolldown, which Vite 8 builds with,
|
|
465
|
+
// leaves an import unbundled when a comment inside it opens with `@vite`
|
|
466
|
+
// after ASCII whitespace (oxc's `is_vite`), line comments and trailing
|
|
467
|
+
// words included (`// @vite-ignore`, `/* @vite-ignore: computed */`).
|
|
468
|
+
// Only `@vite-ignore` itself is taken from that reading, so comments that
|
|
469
|
+
// open by naming an `@vitejs/` or `@vitest/` package stay ordinary.
|
|
470
|
+
{ pattern: /\/\*\s*@vite-ignore\s*\*\//, rawText: true, name: "@vite-ignore" },
|
|
471
|
+
{ pattern: /^[ \t\n\f\r]*@vite-ignore/, value: true, name: "@vite-ignore" },
|
|
375
472
|
// Terser/Rollup annotations: a bare substring search over any comment kind,
|
|
376
473
|
// so leading or trailing words keep the annotation active.
|
|
377
474
|
{ pattern: /[#@]__(?:PURE|NO_SIDE_EFFECTS|INLINE|NOINLINE|KEY|MANGLE_PROP)__/, anyLine: true },
|
|
@@ -444,17 +541,23 @@ const RULES: DirectiveRule[] = [
|
|
|
444
541
|
},
|
|
445
542
|
// Test runners. Jest reads these from the file's leading docblock, but
|
|
446
543
|
// Vitest (which also honours the @jest- spellings) matches the pragma with
|
|
447
|
-
// a bare regex over the whole file
|
|
448
|
-
//
|
|
544
|
+
// a bare regex over the whole file (detectCodeBlock in its
|
|
545
|
+
// test-helpers.ts), so any comment kind and position can be active, and the
|
|
546
|
+
// whitespace after the tag runs onto later lines of a block comment, which
|
|
547
|
+
// may hold the value on a line of its own. The environment is `[\w-]+` up
|
|
548
|
+
// to a word boundary, so it holds a word character; the options are
|
|
549
|
+
// whatever follows on that line, parsed as JSON. A JSDoc star there fails
|
|
550
|
+
// the whole run, and a bare `/* …-options */` counts too: only the first
|
|
551
|
+
// match is read, so it hides any later options.
|
|
449
552
|
{
|
|
450
|
-
pattern: /@((?:jest|vitest)-environment)\s+[\w-]/,
|
|
553
|
+
pattern: /@((?:jest|vitest)-environment)\s+[\w-]*\w/,
|
|
554
|
+
rawText: true,
|
|
451
555
|
name: (match) => `@${match[1]}`,
|
|
452
|
-
anyLine: true,
|
|
453
556
|
},
|
|
454
557
|
{
|
|
455
|
-
pattern: /@((?:jest|vitest)-environment-options)\s
|
|
558
|
+
pattern: /@((?:jest|vitest)-environment-options)\s+./,
|
|
559
|
+
rawText: true,
|
|
456
560
|
name: (match) => `@${match[1]}`,
|
|
457
|
-
anyLine: true,
|
|
458
561
|
},
|
|
459
562
|
// Jest itself reads the two @jest- pragmas from the docblock opening the
|
|
460
563
|
// file, through jest-docblock (`docblock.parse(docblock.extract(source))`
|
|
@@ -475,6 +578,11 @@ const RULES: DirectiveRule[] = [
|
|
|
475
578
|
// whole file, so the tag has to follow a `//` or a `*` — any of the
|
|
476
579
|
// comment's — with only whitespace between.
|
|
477
580
|
{ pattern: /(?:\/\/|\*)\s*@module-tag\s+[\w/-]*\w/, rawText: true, name: "@module-tag" },
|
|
581
|
+
// Vitest runs a file that its `includeSource` globs match as a test file
|
|
582
|
+
// when the text holds `import.meta.vitest` anywhere, comments included
|
|
583
|
+
// (isInSourceTestCode in its globProjectFiles.ts): deleting the only
|
|
584
|
+
// mention drops the file, and the tests it registers, from the run.
|
|
585
|
+
{ pattern: /import\.meta\.vitest/, rawText: true, name: "import.meta.vitest" },
|
|
478
586
|
// SonarQube/SonarCloud (SonarJS): the comment value, minus ONE leading `*`,
|
|
479
587
|
// trimmed, has to START with NOSONAR, case-insensitively; any suffix keeps
|
|
480
588
|
// it active. A star-prefixed line inside a block comment does not count.
|
|
@@ -547,13 +655,22 @@ const RULES: DirectiveRule[] = [
|
|
|
547
655
|
{ pattern: /^[/*#-]*\s*#?(region|endregion)\b/, rawText: true, name: (match) => `#${match[1] as string}` },
|
|
548
656
|
// ESLint's no-fallthrough (in eslint:recommended) accepts a case that falls
|
|
549
657
|
// through when the last comment before the next case matches
|
|
550
|
-
// /falls?\s?through/iu anywhere in its value
|
|
551
|
-
// `/* falls through */` accept
|
|
552
|
-
//
|
|
553
|
-
//
|
|
554
|
-
//
|
|
658
|
+
// /falls?\s?through/iu anywhere in its value (unless the value is an ESLint
|
|
659
|
+
// directive); oxlint's port and JSHint's `/* falls through */` accept
|
|
660
|
+
// narrower forms of the same words, and deno_lint any comment there holding
|
|
661
|
+
// `fallthrough`, `falls through` or `fall through`, directives included.
|
|
662
|
+
// ESLint's and oxlint's default-case, and typescript-eslint's
|
|
663
|
+
// switch-exhaustiveness-check (and tsgolint's port of it), accept a final
|
|
664
|
+
// comment that is exactly `no default`, in any case — trimmed of Rust's or
|
|
665
|
+
// Go's whitespace, U+0085 included, by oxlint and tsgolint. Both only count
|
|
666
|
+
// in front of the code those rules read them before (see
|
|
667
|
+
// SWITCH_CLAUSE_SLOTS), so the same words elsewhere are prose.
|
|
555
668
|
{ pattern: /falls?\s?through/iu, rawText: true, name: "fallthrough" },
|
|
556
|
-
{
|
|
669
|
+
{
|
|
670
|
+
pattern: /^\/(?:\/[\s\u0085]*no default[\s\u0085]*|\*[\s\u0085]*no default[\s\u0085]*\*\/)$/iu,
|
|
671
|
+
rawText: true,
|
|
672
|
+
name: "no-default",
|
|
673
|
+
},
|
|
557
674
|
];
|
|
558
675
|
|
|
559
676
|
// tsc 6 (the JavaScript compiler) reads triple-slash directives with
|
|
@@ -600,9 +717,10 @@ export interface DirectivePlacement {
|
|
|
600
717
|
fileStart: boolean;
|
|
601
718
|
/**
|
|
602
719
|
* The comment sits where ast-grep's suppression comment applies to the
|
|
603
|
-
* whole file: it
|
|
604
|
-
* it) and whatever follows it starts two or more
|
|
605
|
-
* nothing does. Left out, the comment is
|
|
720
|
+
* whole file: it opens tree-sitter's first row (nothing but whitespace
|
|
721
|
+
* before it) and whatever follows it starts two or more rows further down,
|
|
722
|
+
* or nothing does (see isFileWidePosition). Left out, the comment is
|
|
723
|
+
* assumed not to.
|
|
606
724
|
*/
|
|
607
725
|
fileWide?: boolean;
|
|
608
726
|
/**
|
|
@@ -620,6 +738,24 @@ export interface DirectivePlacement {
|
|
|
620
738
|
* (oxlint). Left out, nextToken decides.
|
|
621
739
|
*/
|
|
622
740
|
noDefaultSlot?: boolean;
|
|
741
|
+
/**
|
|
742
|
+
* The comment sits inside a block that holds no statements — a function
|
|
743
|
+
* body, a class static block, any other `{}` block — or inside a `switch`
|
|
744
|
+
* with no clauses. The linters' empty-block rules count any comment there as
|
|
745
|
+
* the block's content and leave the block unreported (see EMPTY_BLOCK). In
|
|
746
|
+
* an empty class static block, the stretch between `static` and the opening
|
|
747
|
+
* brace counts too: oxlint's no-empty-static-block reads its comments from
|
|
748
|
+
* the keyword on. Left out, the comment is assumed not to.
|
|
749
|
+
*/
|
|
750
|
+
emptyBlock?: boolean;
|
|
751
|
+
/**
|
|
752
|
+
* The file holds no code: nothing but empty statements, blocks holding only
|
|
753
|
+
* those, and a directive prologue (`"use strict";`). The no-empty-file
|
|
754
|
+
* rules of oxlint and eslint-plugin-unicorn report such a file unless one
|
|
755
|
+
* of its line comments opens with `///` (see EMPTY_FILE). Left out, the
|
|
756
|
+
* file is assumed to hold code.
|
|
757
|
+
*/
|
|
758
|
+
emptyFile?: boolean;
|
|
623
759
|
/**
|
|
624
760
|
* The token that follows the comment past any further comments (`case`,
|
|
625
761
|
* `}`, an identifier, ...), or `""` when only comments follow: a coarser
|
|
@@ -700,6 +836,24 @@ const SWITCH_CLAUSE_SLOTS: ReadonlyMap<
|
|
|
700
836
|
["no-default", { slot: (placement) => placement.noDefaultSlot, tokens: new Set(["}"]) }],
|
|
701
837
|
]);
|
|
702
838
|
|
|
839
|
+
// ESLint's no-empty and no-empty-static-block (both in eslint:recommended)
|
|
840
|
+
// and no-empty-function leave a block alone once a comment sits inside it, as
|
|
841
|
+
// do typescript-eslint's no-empty-function, oxlint's and deno_lint's ports
|
|
842
|
+
// and Biome's noEmptyBlockStatements: whatever it says, such a comment is
|
|
843
|
+
// what keeps an empty block, function body or switch from being reported
|
|
844
|
+
// (see DirectivePlacement.emptyBlock). It is named for that when no rule
|
|
845
|
+
// names it. Every comment of the block gets the name, so removing some of
|
|
846
|
+
// them never changes what the others are called.
|
|
847
|
+
const EMPTY_BLOCK = "empty-block";
|
|
848
|
+
|
|
849
|
+
// unicorn's no-empty-file (in eslint-plugin-unicorn's recommended config, and
|
|
850
|
+
// among oxlint's default correctness rules) leaves a file that holds no code
|
|
851
|
+
// alone while any of its line comments has a value opening with `/` — a
|
|
852
|
+
// triple-slash directive to the rule, `/// <reference>` or not (see
|
|
853
|
+
// DirectivePlacement.emptyFile). Every such comment of the file gets the name
|
|
854
|
+
// when no rule names it, as with EMPTY_BLOCK.
|
|
855
|
+
const EMPTY_FILE = "empty-file";
|
|
856
|
+
|
|
703
857
|
function isActiveAt(name: string, placement: DirectivePlacement): boolean {
|
|
704
858
|
if (FILE_START_ONLY_DIRECTIVES.has(name)) return placement.fileStart;
|
|
705
859
|
if (FIRST_COMMENT_ONLY_DIRECTIVES.has(name)) return placement.firstComment;
|
|
@@ -750,7 +904,10 @@ const FLOW_BLOCK_SUPPRESSION = /^\/\*[ \t\r\n*]*@ts-(ignore|expect-error)(?![\w-
|
|
|
750
904
|
* honours in certain positions (header pragmas, prettier's docblock pragma,
|
|
751
905
|
* `// @bun`) are skipped elsewhere — and the remaining rules still run, so a
|
|
752
906
|
* live directive later in the same comment (`// deno-lint-ignore-file
|
|
753
|
-
* nosemgrep` in mid-file) is not masked by a positionally dead one.
|
|
907
|
+
* nosemgrep` in mid-file) is not masked by a positionally dead one. A comment
|
|
908
|
+
* no rule names is still `empty-block` where the placement puts it inside an
|
|
909
|
+
* empty block, and a `///` line comment `empty-file` in a file that holds no
|
|
910
|
+
* code.
|
|
754
911
|
*/
|
|
755
912
|
export function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined {
|
|
756
913
|
const at = placement ?? ANY_PLACEMENT;
|
|
@@ -783,7 +940,9 @@ export function detectDirective(kind: CommentKind, text: string, placement?: Dir
|
|
|
783
940
|
if (match.opening) return match.name;
|
|
784
941
|
mention ??= match.name;
|
|
785
942
|
}
|
|
786
|
-
return mention;
|
|
943
|
+
if (mention !== undefined) return mention;
|
|
944
|
+
if (at.emptyBlock === true) return EMPTY_BLOCK;
|
|
945
|
+
return at.emptyFile === true && kind === "line" && text.startsWith("///") ? EMPTY_FILE : undefined;
|
|
787
946
|
}
|
|
788
947
|
|
|
789
948
|
/**
|
|
@@ -804,6 +963,8 @@ function isMatchActiveAt(match: RuleMatch, placement: DirectivePlacement): boole
|
|
|
804
963
|
function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
|
|
805
964
|
const lines = contentLines(kind, text, false);
|
|
806
965
|
const literalLines = kind === "block" ? contentLines(kind, text, true) : lines;
|
|
966
|
+
// The comment's value: the text past `//`, or between `/*` and `*/`.
|
|
967
|
+
const value = kind === "line" ? text.slice(2) : text.replace(/^\/\*/, "").replace(/\*\/$/, "");
|
|
807
968
|
// Where the raw text's content begins, past the comment opener, stars and
|
|
808
969
|
// blanks.
|
|
809
970
|
const contentStart = (/^[/*\s]*/.exec(text) as RegExpExecArray)[0].length;
|
|
@@ -816,15 +977,21 @@ function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
|
|
|
816
977
|
const candidates =
|
|
817
978
|
rule.rawText === true
|
|
818
979
|
? [text]
|
|
819
|
-
: rule.
|
|
820
|
-
?
|
|
821
|
-
: rule.
|
|
822
|
-
?
|
|
823
|
-
:
|
|
980
|
+
: rule.value === true
|
|
981
|
+
? [value]
|
|
982
|
+
: rule.anyLine === true
|
|
983
|
+
? ruleLines
|
|
984
|
+
: rule.joinLines === true
|
|
985
|
+
? [ruleLines.join(" ")]
|
|
986
|
+
: ruleLines.slice(0, 1);
|
|
824
987
|
for (const [index, line] of candidates.entries()) {
|
|
825
988
|
const match = rule.pattern.exec(line);
|
|
826
989
|
if (!match) continue;
|
|
827
|
-
|
|
990
|
+
// A match in the raw text or the value (two characters in, past the
|
|
991
|
+
// opener) opens the comment when only stars and blanks precede it; one
|
|
992
|
+
// in the content lines when it starts the first of them.
|
|
993
|
+
const rawIndex = rule.rawText === true ? match.index : rule.value === true ? match.index + 2 : undefined;
|
|
994
|
+
const opening = rawIndex === undefined ? index === 0 && match.index === 0 : rawIndex <= contentStart;
|
|
828
995
|
const name =
|
|
829
996
|
typeof rule.name === "string" ? rule.name : typeof rule.name === "function" ? rule.name(match) : match[0];
|
|
830
997
|
if (name === undefined) continue;
|
|
@@ -835,11 +1002,20 @@ function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
|
|
|
835
1002
|
}
|
|
836
1003
|
|
|
837
1004
|
// ast-grep suppresses the whole file from a suppression comment in the
|
|
838
|
-
// file-wide position (see DirectivePlacement.fileWide), and only
|
|
839
|
-
//
|
|
1005
|
+
// file-wide position (see DirectivePlacement.fileWide), and only a row from
|
|
1006
|
+
// one anywhere else — so a comment moving into that position changes its
|
|
840
1007
|
// reach.
|
|
841
1008
|
const FILE_WIDE_SUPPRESSIONS: ReadonlySet<string> = new Set(["ast-grep-ignore"]);
|
|
842
1009
|
|
|
1010
|
+
/**
|
|
1011
|
+
* Whether some ast-grep release reads the comment as a suppression. A
|
|
1012
|
+
* comment named for another directive can carry one too (`// @ts-ignore
|
|
1013
|
+
* ast-grep-ignore`), so the removal asks this rather than the name.
|
|
1014
|
+
*/
|
|
1015
|
+
export function carriesAstGrepSuppression(text: string): boolean {
|
|
1016
|
+
return text.includes("ast-grep-ignore");
|
|
1017
|
+
}
|
|
1018
|
+
|
|
843
1019
|
/**
|
|
844
1020
|
* The position-dependent directives (prettier's first-comment pragmas, Jest's
|
|
845
1021
|
* docblock pragmas, Deno's coverage file pragma, Bun's file-start marker,
|