@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/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 (prettier/oxfmt compare the
45
- * trimmed body, so `/** prettier-ignore *​/` is NOT a suppression to them).
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 10 takes the label from the trimmed comment value
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
- { pattern: /^(?:eslint|oxlint)-(?:disable(?:-next-line|-line)?|enable)(?=\s|$)/, keepStars: true },
103
- // React Compiler (babel-plugin-react-compiler, and Bun's port of it) skips a
104
- // component whose comments suppress its react-hooks rules: it searches each
105
- // comment for `eslint-disable`/`-next-line`/`eslint-enable` followed by one
106
- // of the rules, anywhere in the text — JSDoc blocks and mid-text mentions
107
- // included.
108
- {
109
- pattern: /eslint-(disable(?:-next-line)?|enable)\s[^]*react-hooks\/(?:exhaustive-deps|rules-of-hooks)/,
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 10 reports `/* eslint-env */` comments as no longer supported, and
114
- // ESLint 9's eslintrc mode still applies them; both read block comments
115
- // only, like the configuration comments below.
116
- { pattern: /^eslint-env(?=\s|$)/, blockOnly: true, keepStars: true },
117
- { pattern: /^eslint\s+\S/, name: "eslint", blockOnly: true, joinLines: true, keepStars: true },
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+\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 reads a comment as a suppression when its first alphabetic
168
- // character starts `ast-grep-ignore` (`is_suppression_comment` in its
169
- // `combined.rs`), so the comment marker, stars and other punctuation may
170
- // precede it while a word in front makes it prose; `: rule-id, ...` limits
171
- // it to the rules named. Standing alone it suppresses the next line, after
172
- // code it suppresses the statement it trails, and in the file-wide position
173
- // (on the first line, with the next node two or more lines down) the file.
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 mirrors it). Prettier's
200
- // isPrettierIgnoreComment compares `comment.value.trim()` with the exact
201
- // string, for line and block comments alike, so the marker must be the
202
- // whole comment (joinLines makes `$` span every line): hyphenated
203
- // lookalikes (`oxfmt-ignore-more`) and prose stay ordinary, and so do
204
- // `prettier-ignore-start`/`-end`, which prettier only reads in Markdown.
205
- // keepStars, because the literal comparison also means a JSDoc `*` before
206
- // the marker (`/** prettier-ignore *​/`) leaves the comment ordinary.
207
- { pattern: /^prettier-ignore$/, joinLines: true, keepStars: true },
208
- { pattern: /^oxfmt-ignore$/, joinLines: true, keepStars: true },
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 tools. The mode is part of the name so that consumers can tell
269
- // next-statement pragmas (`next`, `if`, ...) from file/range ones (`file`,
270
- // `start`, `stop`). The c8 CLI (v8-to-istanbul) and Node core only parse
271
- // block comments, but istanbul-lib-instrument and Vitest's v8 provider
272
- // (ast-v8-to-istanbul) honour line comments too, so no rule is block-only.
273
- { pattern: /^istanbul\s+ignore\s+([a-z]+)/, name: (match) => `istanbul-ignore-${match[1]}` },
274
- { pattern: /^istanbul\s+ignore\b/, name: "istanbul-ignore" },
275
- { pattern: /^c8\s+ignore\s+([a-z]+)/, name: (match) => `c8-ignore-${match[1]}` },
276
- { pattern: /^c8\s+ignore\b/, name: "c8-ignore" },
277
- { pattern: /^v8\s+ignore\s+([a-z]+)/, name: (match) => `v8-ignore-${match[1]}` },
278
- { pattern: /^v8\s+ignore\b/, name: "v8-ignore" },
279
- // Node core reads `node:coverage` with `ignore next [N]`, `disable` and
280
- // `enable`; Vitest's v8 provider also takes its `ignore` with `start`/`stop`
281
- // as a range, which gets a range name like the other tools'
282
- // (`node:coverage-ignore` stays the counted next-line pragma). Source text
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
- // ast-v8-to-istanbul finds `ignore start`/`stop` ranges with a plain text
291
- // search over every line, so those count after any other text as well.
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: /(istanbul|[cv]8|node:coverage)\s+ignore\s+(start|stop)(?=\W|$)/,
294
- name: (match) => `${match[1] as string}-ignore-${match[2] as string}`,
295
- anyLine: true,
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)\w*|(FlowExpectedError|FlowIssue))\[react-rule/,
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 trimmed comment as one `key:
363
- // value` pair instead — blanks before the colon allowed — and honours
364
- // webpackIgnore and webpackExports as well as its own keys.
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
- // Vite matches the literal block comment (`/\/\*\s*@vite-ignore\s*\*\//` in
372
- // importAnalysis), so line comments, suffixes and trailing words stay
373
- // ordinary.
374
- { pattern: /^\/\*\s*@vite-ignore\s*\*\/$/, rawText: true, blockOnly: true, name: "@vite-ignore" },
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, so any comment kind and position can be
448
- // active; both regexes require a value after the tag.
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+\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; oxlint's port and JSHint's
551
- // `/* falls through */` accept narrower forms of the same words. ESLint's and
552
- // oxlint's default-case accept a final comment that is exactly `no default`,
553
- // in any case. Both only count in front of the code those rules read them
554
- // before (see SWITCH_CLAUSE_TARGETS), so the same words elsewhere are prose.
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
- { pattern: /^\/(?:\/\s*no default\s*|\*\s*no default\s*\*\/)$/iu, rawText: true, name: "no-default" },
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 starts the file's first line (nothing but whitespace before
604
- * it) and whatever follows it starts two or more lines further down, or
605
- * nothing does. Left out, the comment is assumed not to.
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.anyLine === true
820
- ? ruleLines
821
- : rule.joinLines === true
822
- ? [ruleLines.join(" ")]
823
- : ruleLines.slice(0, 1);
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
- const opening = rule.rawText === true ? match.index <= contentStart : index === 0 && match.index === 0;
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 the next line
839
- // from one anywhere else — so a comment moving into that position changes its
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,