@kongyo2/ts-comment-scanner 1.11.0 → 1.15.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
  },
@@ -368,10 +440,17 @@ const RULES: DirectiveRule[] = [
368
440
  name: "turbopack-magic-comment",
369
441
  keepStars: true,
370
442
  },
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" },
443
+ // Vite tests the source of an `import()` call (or of a `new URL()` or
444
+ // worker argument) against /\/\*\s*@vite-ignore\s*\*\// (hasViteIgnoreRE
445
+ // in importAnalysis), so the block comment counts inside another comment
446
+ // too (`// see /* @vite-ignore *​/`). Rolldown, which Vite 8 builds with,
447
+ // leaves an import unbundled when a comment inside it opens with `@vite`
448
+ // after ASCII whitespace (oxc's `is_vite`), line comments and trailing
449
+ // words included (`// @vite-ignore`, `/* @vite-ignore: computed *​/`).
450
+ // Only `@vite-ignore` itself is taken from that reading, so comments that
451
+ // open by naming an `@vitejs/` or `@vitest/` package stay ordinary.
452
+ { pattern: /\/\*\s*@vite-ignore\s*\*\//, rawText: true, name: "@vite-ignore" },
453
+ { pattern: /^[ \t\n\f\r]*@vite-ignore/, value: true, name: "@vite-ignore" },
375
454
  // Terser/Rollup annotations: a bare substring search over any comment kind,
376
455
  // so leading or trailing words keep the annotation active.
377
456
  { pattern: /[#@]__(?:PURE|NO_SIDE_EFFECTS|INLINE|NOINLINE|KEY|MANGLE_PROP)__/, anyLine: true },
@@ -444,17 +523,23 @@ const RULES: DirectiveRule[] = [
444
523
  },
445
524
  // Test runners. Jest reads these from the file's leading docblock, but
446
525
  // 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.
526
+ // a bare regex over the whole file (detectCodeBlock in its
527
+ // test-helpers.ts), so any comment kind and position can be active, and the
528
+ // whitespace after the tag runs onto later lines of a block comment, which
529
+ // may hold the value on a line of its own. The environment is `[\w-]+` up
530
+ // to a word boundary, so it holds a word character; the options are
531
+ // whatever follows on that line, parsed as JSON. A JSDoc star there fails
532
+ // the whole run, and a bare `/* …-options */` counts too: only the first
533
+ // match is read, so it hides any later options.
449
534
  {
450
- pattern: /@((?:jest|vitest)-environment)\s+[\w-]/,
535
+ pattern: /@((?:jest|vitest)-environment)\s+[\w-]*\w/,
536
+ rawText: true,
451
537
  name: (match) => `@${match[1]}`,
452
- anyLine: true,
453
538
  },
454
539
  {
455
- pattern: /@((?:jest|vitest)-environment-options)\s+\S/,
540
+ pattern: /@((?:jest|vitest)-environment-options)\s+./,
541
+ rawText: true,
456
542
  name: (match) => `@${match[1]}`,
457
- anyLine: true,
458
543
  },
459
544
  // Jest itself reads the two @jest- pragmas from the docblock opening the
460
545
  // file, through jest-docblock (`docblock.parse(docblock.extract(source))`
@@ -475,6 +560,11 @@ const RULES: DirectiveRule[] = [
475
560
  // whole file, so the tag has to follow a `//` or a `*` — any of the
476
561
  // comment's — with only whitespace between.
477
562
  { pattern: /(?:\/\/|\*)\s*@module-tag\s+[\w/-]*\w/, rawText: true, name: "@module-tag" },
563
+ // Vitest runs a file that its `includeSource` globs match as a test file
564
+ // when the text holds `import.meta.vitest` anywhere, comments included
565
+ // (isInSourceTestCode in its globProjectFiles.ts): deleting the only
566
+ // mention drops the file, and the tests it registers, from the run.
567
+ { pattern: /import\.meta\.vitest/, rawText: true, name: "import.meta.vitest" },
478
568
  // SonarQube/SonarCloud (SonarJS): the comment value, minus ONE leading `*`,
479
569
  // trimmed, has to START with NOSONAR, case-insensitively; any suffix keeps
480
570
  // it active. A star-prefixed line inside a block comment does not count.
@@ -547,13 +637,22 @@ const RULES: DirectiveRule[] = [
547
637
  { pattern: /^[/*#-]*\s*#?(region|endregion)\b/, rawText: true, name: (match) => `#${match[1] as string}` },
548
638
  // ESLint's no-fallthrough (in eslint:recommended) accepts a case that falls
549
639
  // 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.
640
+ // /falls?\s?through/iu anywhere in its value (unless the value is an ESLint
641
+ // directive); oxlint's port and JSHint's `/* falls through */` accept
642
+ // narrower forms of the same words, and deno_lint any comment there holding
643
+ // `fallthrough`, `falls through` or `fall through`, directives included.
644
+ // ESLint's and oxlint's default-case, and typescript-eslint's
645
+ // switch-exhaustiveness-check (and tsgolint's port of it), accept a final
646
+ // comment that is exactly `no default`, in any case — trimmed of Rust's or
647
+ // Go's whitespace, U+0085 included, by oxlint and tsgolint. Both only count
648
+ // in front of the code those rules read them before (see
649
+ // SWITCH_CLAUSE_SLOTS), so the same words elsewhere are prose.
555
650
  { 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" },
651
+ {
652
+ pattern: /^\/(?:\/[\s\u0085]*no default[\s\u0085]*|\*[\s\u0085]*no default[\s\u0085]*\*\/)$/iu,
653
+ rawText: true,
654
+ name: "no-default",
655
+ },
557
656
  ];
558
657
 
559
658
  // tsc 6 (the JavaScript compiler) reads triple-slash directives with
@@ -600,9 +699,10 @@ export interface DirectivePlacement {
600
699
  fileStart: boolean;
601
700
  /**
602
701
  * 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.
702
+ * whole file: it opens tree-sitter's first row (nothing but whitespace
703
+ * before it) and whatever follows it starts two or more rows further down,
704
+ * or nothing does (see isFileWidePosition). Left out, the comment is
705
+ * assumed not to.
606
706
  */
607
707
  fileWide?: boolean;
608
708
  /**
@@ -620,6 +720,24 @@ export interface DirectivePlacement {
620
720
  * (oxlint). Left out, nextToken decides.
621
721
  */
622
722
  noDefaultSlot?: boolean;
723
+ /**
724
+ * The comment sits inside a block that holds no statements — a function
725
+ * body, a class static block, any other `{}` block — or inside a `switch`
726
+ * with no clauses. The linters' empty-block rules count any comment there as
727
+ * the block's content and leave the block unreported (see EMPTY_BLOCK). In
728
+ * an empty class static block, the stretch between `static` and the opening
729
+ * brace counts too: oxlint's no-empty-static-block reads its comments from
730
+ * the keyword on. Left out, the comment is assumed not to.
731
+ */
732
+ emptyBlock?: boolean;
733
+ /**
734
+ * The file holds no code: nothing but empty statements, blocks holding only
735
+ * those, and a directive prologue (`"use strict";`). The no-empty-file
736
+ * rules of oxlint and eslint-plugin-unicorn report such a file unless one
737
+ * of its line comments opens with `///` (see EMPTY_FILE). Left out, the
738
+ * file is assumed to hold code.
739
+ */
740
+ emptyFile?: boolean;
623
741
  /**
624
742
  * The token that follows the comment past any further comments (`case`,
625
743
  * `}`, an identifier, ...), or `""` when only comments follow: a coarser
@@ -700,6 +818,24 @@ const SWITCH_CLAUSE_SLOTS: ReadonlyMap<
700
818
  ["no-default", { slot: (placement) => placement.noDefaultSlot, tokens: new Set(["}"]) }],
701
819
  ]);
702
820
 
821
+ // ESLint's no-empty and no-empty-static-block (both in eslint:recommended)
822
+ // and no-empty-function leave a block alone once a comment sits inside it, as
823
+ // do typescript-eslint's no-empty-function, oxlint's and deno_lint's ports
824
+ // and Biome's noEmptyBlockStatements: whatever it says, such a comment is
825
+ // what keeps an empty block, function body or switch from being reported
826
+ // (see DirectivePlacement.emptyBlock). It is named for that when no rule
827
+ // names it. Every comment of the block gets the name, so removing some of
828
+ // them never changes what the others are called.
829
+ const EMPTY_BLOCK = "empty-block";
830
+
831
+ // unicorn's no-empty-file (in eslint-plugin-unicorn's recommended config, and
832
+ // among oxlint's default correctness rules) leaves a file that holds no code
833
+ // alone while any of its line comments has a value opening with `/` — a
834
+ // triple-slash directive to the rule, `/// <reference>` or not (see
835
+ // DirectivePlacement.emptyFile). Every such comment of the file gets the name
836
+ // when no rule names it, as with EMPTY_BLOCK.
837
+ const EMPTY_FILE = "empty-file";
838
+
703
839
  function isActiveAt(name: string, placement: DirectivePlacement): boolean {
704
840
  if (FILE_START_ONLY_DIRECTIVES.has(name)) return placement.fileStart;
705
841
  if (FIRST_COMMENT_ONLY_DIRECTIVES.has(name)) return placement.firstComment;
@@ -750,7 +886,10 @@ const FLOW_BLOCK_SUPPRESSION = /^\/\*[ \t\r\n*]*@ts-(ignore|expect-error)(?![\w-
750
886
  * honours in certain positions (header pragmas, prettier's docblock pragma,
751
887
  * `// @bun`) are skipped elsewhere — and the remaining rules still run, so a
752
888
  * live directive later in the same comment (`// deno-lint-ignore-file
753
- * nosemgrep` in mid-file) is not masked by a positionally dead one.
889
+ * nosemgrep` in mid-file) is not masked by a positionally dead one. A comment
890
+ * no rule names is still `empty-block` where the placement puts it inside an
891
+ * empty block, and a `///` line comment `empty-file` in a file that holds no
892
+ * code.
754
893
  */
755
894
  export function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined {
756
895
  const at = placement ?? ANY_PLACEMENT;
@@ -783,7 +922,9 @@ export function detectDirective(kind: CommentKind, text: string, placement?: Dir
783
922
  if (match.opening) return match.name;
784
923
  mention ??= match.name;
785
924
  }
786
- return mention;
925
+ if (mention !== undefined) return mention;
926
+ if (at.emptyBlock === true) return EMPTY_BLOCK;
927
+ return at.emptyFile === true && kind === "line" && text.startsWith("///") ? EMPTY_FILE : undefined;
787
928
  }
788
929
 
789
930
  /**
@@ -804,6 +945,8 @@ function isMatchActiveAt(match: RuleMatch, placement: DirectivePlacement): boole
804
945
  function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
805
946
  const lines = contentLines(kind, text, false);
806
947
  const literalLines = kind === "block" ? contentLines(kind, text, true) : lines;
948
+ // The comment's value: the text past `//`, or between `/*` and `*/`.
949
+ const value = kind === "line" ? text.slice(2) : text.replace(/^\/\*/, "").replace(/\*\/$/, "");
807
950
  // Where the raw text's content begins, past the comment opener, stars and
808
951
  // blanks.
809
952
  const contentStart = (/^[/*\s]*/.exec(text) as RegExpExecArray)[0].length;
@@ -816,15 +959,21 @@ function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
816
959
  const candidates =
817
960
  rule.rawText === true
818
961
  ? [text]
819
- : rule.anyLine === true
820
- ? ruleLines
821
- : rule.joinLines === true
822
- ? [ruleLines.join(" ")]
823
- : ruleLines.slice(0, 1);
962
+ : rule.value === true
963
+ ? [value]
964
+ : rule.anyLine === true
965
+ ? ruleLines
966
+ : rule.joinLines === true
967
+ ? [ruleLines.join(" ")]
968
+ : ruleLines.slice(0, 1);
824
969
  for (const [index, line] of candidates.entries()) {
825
970
  const match = rule.pattern.exec(line);
826
971
  if (!match) continue;
827
- const opening = rule.rawText === true ? match.index <= contentStart : index === 0 && match.index === 0;
972
+ // A match in the raw text or the value (two characters in, past the
973
+ // opener) opens the comment when only stars and blanks precede it; one
974
+ // in the content lines when it starts the first of them.
975
+ const rawIndex = rule.rawText === true ? match.index : rule.value === true ? match.index + 2 : undefined;
976
+ const opening = rawIndex === undefined ? index === 0 && match.index === 0 : rawIndex <= contentStart;
828
977
  const name =
829
978
  typeof rule.name === "string" ? rule.name : typeof rule.name === "function" ? rule.name(match) : match[0];
830
979
  if (name === undefined) continue;
@@ -835,11 +984,20 @@ function* ruleMatches(kind: CommentKind, text: string): Generator<RuleMatch> {
835
984
  }
836
985
 
837
986
  // 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
987
+ // file-wide position (see DirectivePlacement.fileWide), and only a row from
988
+ // one anywhere else — so a comment moving into that position changes its
840
989
  // reach.
841
990
  const FILE_WIDE_SUPPRESSIONS: ReadonlySet<string> = new Set(["ast-grep-ignore"]);
842
991
 
992
+ /**
993
+ * Whether some ast-grep release reads the comment as a suppression. A
994
+ * comment named for another directive can carry one too (`// @ts-ignore
995
+ * ast-grep-ignore`), so the removal asks this rather than the name.
996
+ */
997
+ export function carriesAstGrepSuppression(text: string): boolean {
998
+ return text.includes("ast-grep-ignore");
999
+ }
1000
+
843
1001
  /**
844
1002
  * The position-dependent directives (prettier's first-comment pragmas, Jest's
845
1003
  * docblock pragmas, Deno's coverage file pragma, Bun's file-start marker,