@kongyo2/ts-comment-scanner 1.20.0 → 1.22.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.
Files changed (78) hide show
  1. package/README.md +240 -52
  2. package/dist/args.d.ts.map +1 -1
  3. package/dist/args.js +23 -19
  4. package/dist/args.js.map +1 -1
  5. package/dist/astgrep.d.ts +5 -3
  6. package/dist/astgrep.d.ts.map +1 -1
  7. package/dist/astgrep.js +10 -12
  8. package/dist/astgrep.js.map +1 -1
  9. package/dist/containers.d.ts +48 -0
  10. package/dist/containers.d.ts.map +1 -0
  11. package/dist/containers.js +82 -0
  12. package/dist/containers.js.map +1 -0
  13. package/dist/coverage.d.ts +45 -0
  14. package/dist/coverage.d.ts.map +1 -0
  15. package/dist/coverage.js +92 -0
  16. package/dist/coverage.js.map +1 -0
  17. package/dist/directives.d.ts +21 -3
  18. package/dist/directives.d.ts.map +1 -1
  19. package/dist/directives.js +31 -23
  20. package/dist/directives.js.map +1 -1
  21. package/dist/files.d.ts +7 -3
  22. package/dist/files.d.ts.map +1 -1
  23. package/dist/files.js +129 -82
  24. package/dist/files.js.map +1 -1
  25. package/dist/imports.d.ts.map +1 -1
  26. package/dist/imports.js +14 -8
  27. package/dist/imports.js.map +1 -1
  28. package/dist/index.d.ts +1 -1
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +1 -1
  31. package/dist/index.js.map +1 -1
  32. package/dist/jsx.d.ts.map +1 -1
  33. package/dist/jsx.js +5 -6
  34. package/dist/jsx.js.map +1 -1
  35. package/dist/lines.d.ts +24 -5
  36. package/dist/lines.d.ts.map +1 -1
  37. package/dist/lines.js +50 -16
  38. package/dist/lines.js.map +1 -1
  39. package/dist/ranges.d.ts +8 -0
  40. package/dist/ranges.d.ts.map +1 -1
  41. package/dist/ranges.js +12 -0
  42. package/dist/ranges.js.map +1 -1
  43. package/dist/remove.d.ts +18 -14
  44. package/dist/remove.d.ts.map +1 -1
  45. package/dist/remove.js +69 -630
  46. package/dist/remove.js.map +1 -1
  47. package/dist/run.d.ts.map +1 -1
  48. package/dist/run.js +21 -28
  49. package/dist/run.js.map +1 -1
  50. package/dist/scanner.d.ts +34 -0
  51. package/dist/scanner.d.ts.map +1 -1
  52. package/dist/scanner.js +137 -31
  53. package/dist/scanner.js.map +1 -1
  54. package/dist/shields.d.ts +72 -0
  55. package/dist/shields.d.ts.map +1 -0
  56. package/dist/shields.js +624 -0
  57. package/dist/shields.js.map +1 -0
  58. package/dist/splice.d.ts +42 -11
  59. package/dist/splice.d.ts.map +1 -1
  60. package/dist/splice.js +189 -56
  61. package/dist/splice.js.map +1 -1
  62. package/package.json +2 -1
  63. package/src/args.ts +21 -21
  64. package/src/astgrep.ts +11 -13
  65. package/src/containers.ts +128 -0
  66. package/src/coverage.ts +110 -0
  67. package/src/directives.ts +38 -20
  68. package/src/files.ts +169 -91
  69. package/src/imports.ts +15 -8
  70. package/src/index.ts +1 -0
  71. package/src/jsx.ts +5 -6
  72. package/src/lines.ts +55 -14
  73. package/src/ranges.ts +17 -0
  74. package/src/remove.ts +82 -730
  75. package/src/run.ts +22 -34
  76. package/src/scanner.ts +180 -32
  77. package/src/shields.ts +701 -0
  78. package/src/splice.ts +224 -60
package/src/shields.ts ADDED
@@ -0,0 +1,701 @@
1
+ import { astGrepReach, rowStartOffsets, type AstGrepReach, type PrecedingNode } from "./astgrep.js";
2
+ import { commentsOf, removalUnits, type Container, type RemovalUnit } from "./containers.js";
3
+ import { hintsNextNode, monocartLines, opensRow, textHints } from "./coverage.js";
4
+ import { carriesAstGrepSuppression } from "./directives.js";
5
+ import { closesItsLine, isBlank, lineIndexAt, lineStartOffsets, occupiesWholeLines, opensItsLine } from "./lines.js";
6
+ import { byStart, firstIndexAtOrAfter, rangeAt, type Range } from "./ranges.js";
7
+ import type { Comment } from "./types.js";
8
+
9
+ /** What the shields read of a source besides its text. */
10
+ export interface ShieldContext {
11
+ /** The source's comments, in document order. */
12
+ comments: readonly Comment[];
13
+ /** The comment-only JSX container each comment in one sits in. */
14
+ containerOf: ReadonlyMap<Comment, Container>;
15
+ /** Comments and the containers that may go with theirs, sorted: what code starts after. */
16
+ skippable: readonly Range[];
17
+ /** What stands in front of each comment carrying an ast-grep suppression (see SourceAnalysis). */
18
+ preceding: ReadonlyMap<Comment, PrecedingNode>;
19
+ /** Every directive each directive comment carries (see SourceAnalysis). */
20
+ directives: ReadonlyMap<Comment, readonly string[]>;
21
+ /** The JSDoc comment that keeps the tags of an earlier one off their node (see SourceAnalysis). */
22
+ shadows: ReadonlyMap<Comment, Comment>;
23
+ /** The cast comments a parenthesized expression follows (see SourceAnalysis). */
24
+ casts: ReadonlySet<Comment>;
25
+ }
26
+
27
+ export interface Shielding {
28
+ /** The removals that remain once the comments the directives need are kept. */
29
+ removed: Comment[];
30
+ /**
31
+ * Lines (1-based) that a surviving directive reaches: the ones below a
32
+ * next-line directive, the ones a line directive stands on and the ones a
33
+ * coverage hint counts. Each stays a line of its own (see ShieldedLines).
34
+ */
35
+ lines: Set<number>;
36
+ }
37
+
38
+ /**
39
+ * A stretch between a directive and the code after it in which a comment
40
+ * has to stay, because the directive only counts while none stands there
41
+ * (see NEXT_TOKEN_DIRECTIVES) or while it is the last one in front of that
42
+ * code (see LAST_COMMENT_DIRECTIVES). One comment does: the first for the
43
+ * former, on the directive's own line where one stands there, and the last
44
+ * for the latter.
45
+ */
46
+ interface Gap extends Range {
47
+ stays: "first" | "last";
48
+ /** The line the directive ends on. */
49
+ line: number;
50
+ }
51
+
52
+ /**
53
+ * A directive whose reach depends on what stands in front of it on its row:
54
+ * the tool applies it to the lines `from` to `to` (1-based) when `reaches`
55
+ * accepts the text between the row's start and the directive.
56
+ */
57
+ interface Front {
58
+ rowStart: number;
59
+ at: number;
60
+ reaches: (prefix: string) => boolean;
61
+ from: number;
62
+ to: number;
63
+ }
64
+
65
+ /**
66
+ * Finds what the directives that stay need the removal to leave in place,
67
+ * so that each applies to the same code afterwards, and keeps the comments
68
+ * among it.
69
+ *
70
+ * Most directives reach lines: the line below a next-line directive
71
+ * (`@ts-expect-error`, `eslint-disable-next-line`, ...), the lines a line
72
+ * directive (`eslint-disable-line`, `nosemgrep` after code, ...) stands on,
73
+ * the lines a coverage hint counts. Those lines are shielded: emptied, one
74
+ * stays as an empty line, and none is joined to another — the removal edits
75
+ * see to both (see ShieldedLines), so the comments on them go all the same.
76
+ * Only a comment-only JSX container that would join such a line keeps its
77
+ * comments, as a line break in its place would change what the element
78
+ * renders. To the tools that only a line feed ends a line for (oxlint,
79
+ * Semgrep, ast-grep, c8, Node's test runner), a directive reaches rows that
80
+ * can run over several of those lines, and their lines are shielded as well.
81
+ *
82
+ * Other directives are read with the comments around them, and there a
83
+ * comment has to stay:
84
+ *
85
+ * - below a tsc suppression, the first line each compiler cannot step over
86
+ * in front of the code (see tscReach);
87
+ * - between a directive that only counts as the last comment before its
88
+ * target (`@deno-types`, a fall-through comment, ...), or a coverage hint
89
+ * that ast-v8-to-istanbul only applies to the node right after it, and
90
+ * that target, one comment (see Gap);
91
+ * - in front of a directive that reaches the lines below only where it
92
+ * opens its row, one comment that keeps it from opening it, where those
93
+ * lines hold code (see Front);
94
+ * - a JSX comment container right after a directive in a container
95
+ * (`{/* prettier-ignore *​/}`, which applies to the next sibling);
96
+ * - the last JSDoc comment of a node in JavaScript, where an earlier one
97
+ * that stays holds tags it keeps off the node;
98
+ * - what an ast-grep suppression is keyed to (see astGrepReach).
99
+ *
100
+ * Each directive a comment carries shields what it reaches, whichever one
101
+ * names the comment. Runs to a fixpoint because a comment kept here can
102
+ * itself be a directive (when directives are being removed selectively).
103
+ */
104
+ export function shieldDirectives(
105
+ source: string,
106
+ removed: Comment[],
107
+ kept: Comment[],
108
+ skipped: Comment[],
109
+ context: ShieldContext,
110
+ ): Shielding {
111
+ const lineOffsets = lineStartOffsets(source);
112
+ const totalLines = lineOffsets.length;
113
+ const shieldedLines = new Set<number>();
114
+ const blockingLines = new Set<number>();
115
+ const gaps: Gap[] = [];
116
+ const fronts: Front[] = [];
117
+ const siblingTargets = new Set<Container>();
118
+ const rowTails: Range[] = [];
119
+ const shadows = new Set<Comment>();
120
+ const astGrepReaches: AstGrepReach[] = [];
121
+ const processed = new Set<Comment>();
122
+ // The hints c8 and Node find in the text, until the comment holding one is known to stay.
123
+ let pendingHints = source.includes("ignore next") ? textHints(source) : [];
124
+ // Where a comment tsc reads a suppression from ends: tsc stops there on its
125
+ // way up from a diagnostic, as it does at a line it cannot step over.
126
+ const suppressions = new Map<number, Comment[]>();
127
+ for (const [comment, names] of context.directives) {
128
+ if (names.some((name) => TSC_SUPPRESSIONS.has(name))) {
129
+ suppressions.set(comment.endLine, [...(suppressions.get(comment.endLine) ?? []), comment]);
130
+ }
131
+ }
132
+ let stillRemoved = removed;
133
+ const removing = new Set(removed);
134
+ let units: RemovalUnit[] | undefined;
135
+ const currentUnits = (): RemovalUnit[] => (units ??= removalUnits(stillRemoved, context.containerOf));
136
+ let rows: number[] | undefined;
137
+ const rowOffsets = (): number[] => (rows ??= rowStartOffsets(source));
138
+ /** The (1-based) line holding the offset. */
139
+ const lineOf = (offset: number): number => lineIndexAt(lineOffsets, offset) + 1;
140
+ /** The given (1-based) line, which the shields only name when the source has it, and the units on it. */
141
+ const unitsOnLine = (line: number): LineUnits => {
142
+ const start = lineOffsets[line - 1] as number;
143
+ const end = lineOffsets[line] ?? source.length;
144
+ return { start, end, units: currentUnits().filter((unit) => unit.start < end && unit.end > start) };
145
+ };
146
+ /** Whether the lines (1-based, inclusive, each one the source has) hold nothing but whitespace and comments. */
147
+ const holdNoCode = (from: number, to: number): boolean => {
148
+ const end = lineOffsets[to] ?? source.length;
149
+ for (let index = lineOffsets[from - 1] as number; index < end; index += 1) {
150
+ const comment = rangeAt(context.comments, index);
151
+ if (comment !== undefined) index = comment.end - 1;
152
+ else if (!isBlank(source[index] as string)) return false;
153
+ }
154
+ return true;
155
+ };
156
+
157
+ let added = false;
158
+ const shieldLines = (from: number, to: number): void => {
159
+ for (let line = from; line <= Math.min(to, totalLines); line += 1) {
160
+ if (shieldedLines.has(line)) continue;
161
+ shieldedLines.add(line);
162
+ added = true;
163
+ }
164
+ };
165
+ /** Shields the lines of the rows (0-based, inclusive) that only a line feed ends. */
166
+ const shieldRows = (from: number, to: number): void => {
167
+ const offsets = rowOffsets();
168
+ const start = offsets[from];
169
+ if (start !== undefined) shieldLines(lineOf(start), lineOf((offsets[to + 1] ?? source.length) - 1));
170
+ };
171
+
172
+ /** Collects what one of the directives the comment carries reaches. */
173
+ const shieldReach = (comment: Comment, directive: string): void => {
174
+ const lastComment = isLastCommentDirective(comment, directive);
175
+ const cast = CAST_DIRECTIVES.has(directive) && context.casts.has(comment);
176
+ if (lastComment || cast || (NEXT_TOKEN_DIRECTIVES.has(directive) && hintsNextNode(comment.text))) {
177
+ const codeStart = codeStartAfter(source, comment.end, context.skippable);
178
+ if (codeStart > comment.end && codeStart < source.length) {
179
+ gaps.push({
180
+ start: comment.end,
181
+ end: codeStart,
182
+ stays: lastComment || cast ? "last" : "first",
183
+ line: comment.endLine,
184
+ });
185
+ added = true;
186
+ }
187
+ if (lastComment) return;
188
+ }
189
+ if (TSC_SUPPRESSIONS.has(directive)) {
190
+ const reach = tscReach(source, comment, lineOffsets, context.skippable, (line) =>
191
+ suppressions.get(line)?.map((suppression) => removing.has(suppression)),
192
+ );
193
+ for (const line of reach.blocking) {
194
+ if (blockingLines.has(line)) continue;
195
+ blockingLines.add(line);
196
+ added = true;
197
+ }
198
+ if (reach.target !== undefined) shieldLines(reach.target, reach.target);
199
+ }
200
+ // The row the comment ends on, for the tools that only a line feed ends
201
+ // a line for (oxlint, Semgrep, tree-sitter, c8): a lone CR, U+2028 or
202
+ // U+2029 — a line break to tsc and ESLint — ends no row, so a row can run
203
+ // over several of the lines counted here.
204
+ const endRow = lineIndexAt(rowOffsets(), comment.end - 1);
205
+ // A line directive covers the lines it stands on, which no removal may
206
+ // join to another (see joiningUnits): its rows, to those tools.
207
+ if (coversOwnLine(directive)) shieldRows(lineIndexAt(rowOffsets(), comment.start), endRow);
208
+ if (!isNextLineDirective(directive)) return;
209
+ // In JSX, such a directive in braces applies to the sibling after it,
210
+ // whatever line that is on (prettier leaves the element after
211
+ // `{/* prettier-ignore */}` as is): a comment-only container standing
212
+ // between them has to stay. Range and file pragmas target no sibling.
213
+ const holder = context.containerOf.get(comment);
214
+ if (holder?.next !== undefined && !siblingTargets.has(holder.next)) {
215
+ siblingTargets.add(holder.next);
216
+ added = true;
217
+ }
218
+ // A trailing formatter or scanner suppression (`a = [1]; // oxfmt-ignore`,
219
+ // `secret(); // skipcq`) targets what it trails, not the line below it.
220
+ // In JSX, the container holding the comment is what has to stand on
221
+ // lines of its own.
222
+ if (TRAILING_TARGETS_OWN_LINE.has(directive) && !occupiesWholeLines(source, holder ?? comment)) return;
223
+ const below = rowOffsets()[endRow + 1];
224
+ if (directive === "nosemgrep") {
225
+ // Semgrep reads the rule ids of a `nosemgrep:` off the rest of the row,
226
+ // which runs on where a lone CR or U+2028 ends the comment's line: what
227
+ // stands there is part of the ids it reads.
228
+ const nextLine = lineOffsets[comment.endLine] ?? source.length;
229
+ if (nextLine < (below ?? source.length) && SEMGREP_RULE_IDS.test(comment.text)) {
230
+ rowTails.push({ start: nextLine, end: below ?? source.length });
231
+ added = true;
232
+ }
233
+ // Its reach is a matter of what precedes the marker on its row.
234
+ if (below !== undefined) {
235
+ const rowStart = rowOffsets()[endRow] as number;
236
+ const ownRow = comment.text.slice(comment.text.lastIndexOf("\n") + 1);
237
+ fronts.push({
238
+ rowStart,
239
+ at: Math.max(rowStart, comment.start),
240
+ reaches: (prefix) => SEMGREP_PREVIOUS_LINE.test(prefix + ownRow),
241
+ from: lineOf(below),
242
+ to: lineOf((rowOffsets()[endRow + 2] ?? source.length) - 1),
243
+ });
244
+ added = true;
245
+ }
246
+ return;
247
+ }
248
+ // The line below the directive, and the row below it. oxlint covers the
249
+ // rest of the row a next-line comment ends on as well, up to the end of
250
+ // the row after it (`split_inclusive('\n')` and `lines()` in its
251
+ // `disable_directives.rs`); on the file's last row it covers the rest of
252
+ // the file, which no removal changes.
253
+ shieldLines(comment.endLine + 1, comment.endLine + 1);
254
+ if (below !== undefined) {
255
+ shieldLines(
256
+ OXLINT_NEXT_LINE.has(directive) ? comment.endLine + 1 : lineOf(below),
257
+ lineOf((rowOffsets()[endRow + 2] ?? source.length) - 1),
258
+ );
259
+ }
260
+ if (COUNTED_NEXT_LINE.has(directive)) {
261
+ // monocart counts the lines below the comment's last (see monocartLines).
262
+ const trailing = source.slice(comment.end, lineOffsets[comment.endLine] ?? source.length);
263
+ const counted = monocartLines(comment.kind, comment.text, trailing);
264
+ if (counted !== undefined) shieldLines(comment.endLine + 1, comment.endLine + counted);
265
+ }
266
+ };
267
+
268
+ const collectShields = (): boolean => {
269
+ added = false;
270
+ for (const comment of [...kept, ...skipped]) {
271
+ if (processed.has(comment)) continue;
272
+ processed.add(comment);
273
+ const shadow = context.shadows.get(comment);
274
+ if (shadow !== undefined) shadows.add(shadow);
275
+ if (comment.directive === undefined) continue;
276
+ if (carriesAstGrepSuppression(comment.text)) {
277
+ const reach = astGrepReach(source, rowOffsets(), comment, context.preceding.get(comment) as PrecedingNode);
278
+ astGrepReaches.push(reach);
279
+ if (reach.nextRow !== undefined && reach.nextRow.end > reach.nextRow.start) {
280
+ shieldLines(lineOf(reach.nextRow.start), lineOf(reach.nextRow.end - 1));
281
+ }
282
+ added = true;
283
+ }
284
+ for (const directive of context.directives.get(comment) as readonly string[]) shieldReach(comment, directive);
285
+ }
286
+ // c8 ignores the row holding a hint, wherever on it, and from a hint that
287
+ // opens its row the rows below it that the hint counts; Node's test
288
+ // runner ignores the rows below it wherever it stands. A hint in a
289
+ // comment that goes, goes with it.
290
+ pendingHints = pendingHints.filter((hint) => {
291
+ const holder = rangeAt(context.comments, hint.offset);
292
+ if (holder !== undefined && removing.has(holder)) return true;
293
+ const offsets = rowOffsets();
294
+ const row = lineIndexAt(offsets, hint.offset);
295
+ shieldRows(row, row);
296
+ if (hint.nodeRows > 0) shieldRows(row + 1, row + hint.nodeRows);
297
+ const below = offsets[row + 1];
298
+ if (below !== undefined) {
299
+ fronts.push({
300
+ rowStart: offsets[row] as number,
301
+ at: hint.offset,
302
+ reaches: opensRow,
303
+ from: lineOf(below),
304
+ to: lineOf((offsets[row + hint.rows + 1] ?? source.length) - 1),
305
+ });
306
+ added = true;
307
+ }
308
+ return false;
309
+ });
310
+ return added;
311
+ };
312
+
313
+ /** Takes those of the comments that are still being removed out of the removal and keeps them. */
314
+ const protect = (group: readonly Comment[]): void => {
315
+ const staying = group.filter((comment) => removing.has(comment));
316
+ if (staying.length === 0) return;
317
+ for (const comment of staying) removing.delete(comment);
318
+ stillRemoved = stillRemoved.filter((comment) => removing.has(comment));
319
+ kept.push(...staying);
320
+ units = undefined;
321
+ };
322
+
323
+ /**
324
+ * Shields what a directive reaches below its row where it opens the row,
325
+ * and sees to it that the removal does not make it open one: with the
326
+ * comments in front of it gone, the directive would newly reach those
327
+ * lines. Where they hold no code, that changes nothing as long as they
328
+ * stay lines, so they are shielded as well; where they do, the comment in
329
+ * front that keeps the directive from opening its row stays.
330
+ */
331
+ const settleFront = (front: Front): void => {
332
+ const prefix = source.slice(front.rowStart, front.at);
333
+ if (!front.reaches(prefix)) {
334
+ const inFront = currentUnits().filter((unit) => unit.start < front.at && unit.end > front.rowStart);
335
+ /** The prefix once the units are deleted, all but `staying`. */
336
+ const without = (staying?: RemovalUnit): string => {
337
+ let text = "";
338
+ let cursor = front.rowStart;
339
+ for (const unit of inFront) {
340
+ if (unit === staying) continue;
341
+ text += source.slice(cursor, Math.max(cursor, unit.start));
342
+ cursor = Math.min(front.at, unit.end);
343
+ }
344
+ return text + source.slice(cursor, front.at);
345
+ };
346
+ if (!front.reaches(without())) return;
347
+ if (!holdNoCode(front.from, front.to)) {
348
+ protect((inFront.findLast((unit) => !front.reaches(without(unit))) as RemovalUnit).comments);
349
+ return;
350
+ }
351
+ }
352
+ shieldLines(front.from, front.to);
353
+ };
354
+
355
+ /** Keeps the comment a gap needs, unless one that stays already serves. */
356
+ const settleGap = (gap: Gap): void => {
357
+ const within: Comment[] = [];
358
+ for (
359
+ let index = firstIndexAtOrAfter(context.comments, gap.start, (comment) => comment.start);
360
+ (context.comments[index]?.start ?? gap.end) < gap.end;
361
+ index += 1
362
+ ) {
363
+ within.push(context.comments[index] as Comment);
364
+ }
365
+ const first = within[0];
366
+ if (gap.stays === "last" || first === undefined) {
367
+ protect(within.slice(-1));
368
+ } else {
369
+ // Any comment keeps ast-v8-to-istanbul's hint without a target. One on
370
+ // the hint's own line also keeps monocart from counting a line below
371
+ // the hint (see monocartLines), so where the first stands there, only a
372
+ // comment of that line serves.
373
+ const serving = first.line === gap.line ? within.filter((comment) => comment.line === gap.line) : within;
374
+ if (serving.every((comment) => removing.has(comment))) protect([first]);
375
+ }
376
+ };
377
+
378
+ /** Protects what the shields collected so far hold in place; true when that kept anything. */
379
+ const protectShields = (): boolean => {
380
+ const removingBefore = stillRemoved.length;
381
+ for (const front of fronts) settleFront(front);
382
+ // A comment that would join a shielded line to another leaves its line
383
+ // breaks behind; a container's braces have none to leave without
384
+ // changing what the element renders, so they stay.
385
+ for (const line of currentUnits().some((unit) => unit.braces) ? shieldedLines : []) {
386
+ for (const unit of joiningUnits(source, unitsOnLine(line))) {
387
+ if (unit.braces) protect(unit.comments);
388
+ }
389
+ }
390
+ for (const line of blockingLines) protect(lineOpeningGroup(source, unitsOnLine(line)));
391
+ for (const gap of gaps) settleGap(gap);
392
+ protect([...shadows]);
393
+ for (const target of siblingTargets) protect(target.comments);
394
+ for (const tail of rowTails) {
395
+ protect(commentsOf(currentUnits().filter((unit) => unit.start >= tail.start && unit.start < tail.end)));
396
+ }
397
+ for (const reach of astGrepReaches) protect(commentsOf(currentUnits().filter((unit) => reach.holds(unit))));
398
+ return stillRemoved.length < removingBefore;
399
+ };
400
+
401
+ collectShields();
402
+ while (protectShields()) {
403
+ if (!collectShields()) break;
404
+ }
405
+ if (stillRemoved.length !== removed.length) {
406
+ kept.sort(byStart);
407
+ }
408
+ return { removed: stillRemoved, lines: shieldedLines };
409
+ }
410
+
411
+ /**
412
+ * Offset of the first character at or after `from` that is neither
413
+ * whitespace nor inside one of the (sorted, non-overlapping) ranges, or the
414
+ * source length when only ranges follow. `from` lies past the start of at
415
+ * least one range (the directive the search is for); when the closest of
416
+ * them runs past `from` — a block comment opened on the directive's line —
417
+ * the search resumes at its end.
418
+ */
419
+ function codeStartAfter(source: string, from: number, ranges: readonly Range[]): number {
420
+ let next = firstIndexAtOrAfter(ranges, from, (range) => range.start);
421
+ let index = Math.max(from, (ranges[next - 1] as Range).end);
422
+ while (index < source.length) {
423
+ const range = ranges[next];
424
+ if (range !== undefined && range.start === index) {
425
+ index = range.end;
426
+ next += 1;
427
+ } else if (isBlank(source[index] as string)) {
428
+ index += 1;
429
+ } else {
430
+ return index;
431
+ }
432
+ }
433
+ return source.length;
434
+ }
435
+
436
+ /**
437
+ * What a tsc suppression needs left in place below it. Looking for the
438
+ * suppression a diagnostic falls under, a compiler goes up from the
439
+ * diagnostic's line over the lines it reads as blank or as a `//` comment
440
+ * (see TSC_PASSABLE_LINES) and takes the first suppression it meets. So a
441
+ * suppression applies to the first line below it that the compiler cannot
442
+ * step over:
443
+ *
444
+ * - where that is the line the code below starts on, the line is the
445
+ * suppression's `target`, which no removal may pull more code onto;
446
+ * - where a line in between stops the compiler first — one opening with a
447
+ * block comment, say — the suppression has no target for that compiler,
448
+ * and the line is `blocking`: deleting it would let the suppression reach
449
+ * the code instead;
450
+ * - where another suppression ends on a line in between, that one takes the
451
+ * diagnostics from below, and this one reaches nothing past it. The line
452
+ * is blocking while that suppression is being removed (`suppressions`
453
+ * tells, for a line, whether each suppression ending on it is).
454
+ *
455
+ * The two compilers can stop at different lines: a line holding only a
456
+ * vertical tab stops tsc 7, while tsc 6 searches on to the next line it
457
+ * cannot pass.
458
+ */
459
+ function tscReach(
460
+ source: string,
461
+ comment: Comment,
462
+ lineOffsets: readonly number[],
463
+ ranges: readonly Range[],
464
+ suppressions: (line: number) => boolean[] | undefined,
465
+ ): { blocking: number[]; target: number | undefined } {
466
+ // A suppression applies from the line below it on, so code sharing its line
467
+ // (`/* @ts-ignore */ foo();`) does not end the search.
468
+ const codeStart = codeStartAfter(source, lineOffsets[comment.endLine] ?? source.length, ranges);
469
+ if (codeStart >= source.length) return { blocking: [], target: undefined };
470
+ const codeLine = lineIndexAt(lineOffsets, codeStart) + 1;
471
+ const blocking: number[] = [];
472
+ let target: number | undefined;
473
+ for (const passable of TSC_PASSABLE_LINES) {
474
+ let line = comment.endLine + 1;
475
+ for (; line < codeLine; line += 1) {
476
+ const removing = suppressions(line);
477
+ if (removing === undefined && passable.test(source.slice(lineOffsets[line - 1], lineOffsets[line]))) continue;
478
+ // A suppression that stays stops the compiler whatever is removed.
479
+ if (removing?.includes(false) !== true) blocking.push(line);
480
+ break;
481
+ }
482
+ if (line === codeLine) target = codeLine;
483
+ }
484
+ return { blocking, target };
485
+ }
486
+
487
+ /** A line, from its start to the next line's (past its line break), with the removal units holding part of it. */
488
+ interface LineUnits extends Range {
489
+ units: RemovalUnit[];
490
+ }
491
+
492
+ /**
493
+ * The removals on the given line when one of them opens it (holds its first
494
+ * non-whitespace character), so that deleting them would change how the
495
+ * line starts. None when something that survives opens the line instead, or
496
+ * nothing on it is to be removed.
497
+ */
498
+ function lineOpeningGroup(source: string, line: LineUnits): Comment[] {
499
+ let first = line.start;
500
+ while (first < line.end && isBlank(source[first] as string)) first += 1;
501
+ return line.units.some((unit) => unit.start <= first && first < unit.end) ? commentsOf(line.units) : [];
502
+ }
503
+
504
+ /**
505
+ * The removal units that would join the given line to another: they reach
506
+ * past one of its ends, with something other than whitespace beyond them on
507
+ * the line they run into. Deleting such a comment takes its line breaks
508
+ * along, so what stands beyond it can land on the line, or what stands on
509
+ * the line move off it, and a directive covering the line would cover other
510
+ * code — unless line breaks of its own take its place (see applyEdits).
511
+ */
512
+ function joiningUnits(source: string, line: LineUnits): RemovalUnit[] {
513
+ return line.units.filter(
514
+ (unit) =>
515
+ (unit.end > line.end && !closesItsLine(source, unit)) || (unit.start < line.start && !opensItsLine(source, unit)),
516
+ );
517
+ }
518
+
519
+ // The next-line directives oxlint reads.
520
+ const OXLINT_NEXT_LINE = new Set(["eslint-disable-next-line", "oxlint-disable-next-line"]);
521
+
522
+ /**
523
+ * Whether the directive covers the lines it stands on: the `-line` forms of
524
+ * the suppressions (`eslint-disable-line`, `tslint:disable-line`, ...), the
525
+ * ones that cover the line holding them (see OWN_LINE_DIRECTIVES), and the
526
+ * `ignore next` hints c8 and monocart count lines for (see
527
+ * COUNTED_NEXT_LINE): they ignore the line holding one, from the hint on for
528
+ * monocart, along with the lines below it.
529
+ */
530
+ function coversOwnLine(name: string): boolean {
531
+ return (
532
+ (name.endsWith("-line") && !name.endsWith("-next-line")) ||
533
+ OWN_LINE_DIRECTIVES.has(name) ||
534
+ COUNTED_NEXT_LINE.has(name)
535
+ );
536
+ }
537
+
538
+ // Suppressions that apply to the line holding them: Semgrep's to findings
539
+ // that start on it, CodeQL's `lgtm` to its alerts up to the comment,
540
+ // DeepSource's, SonarQube's, gitleaks', TruffleHog's and detect-secrets' to
541
+ // the line, and codespell's to its words.
542
+ const OWN_LINE_DIRECTIVES = new Set([
543
+ "nosemgrep",
544
+ "lgtm",
545
+ "skipcq",
546
+ "NOSONAR",
547
+ "gitleaks:allow",
548
+ "trufflehog:ignore",
549
+ "pragma-allowlist-secret",
550
+ "codespell:ignore",
551
+ ]);
552
+
553
+ // Semgrep applies a `nosemgrep` to the line below where nothing but
554
+ // non-alphanumerics precede it on its line (`nosem_previous_line_re` in its
555
+ // Nosemgrep.ml): `// nosemgrep: rule-id` and `}); // nosemgrep` cover the next
556
+ // line, `// TODO nosemgrep` and `foo(); // nosemgrep` only their own.
557
+ const SEMGREP_PREVIOUS_LINE = /^[^a-zA-Z0-9]* *nosem(?:grep)?/i;
558
+ // A `nosemgrep` that names the rules it is for.
559
+ const SEMGREP_RULE_IDS = /nosem(?:grep)?[:=]/i;
560
+
561
+ // These suppressions only apply to the following node/line when they stand on
562
+ // their own line — trailing after code they target (at most) their own line.
563
+ // Other next-line directives (`@ts-ignore`, `no-dd-sa`, ...) target the next
564
+ // line even when they trail code.
565
+ const TRAILING_TARGETS_OWN_LINE = new Set([
566
+ "prettier-ignore",
567
+ "oxfmt-ignore",
568
+ "dprint-ignore",
569
+ "lgtm",
570
+ "codeql",
571
+ "skipcq",
572
+ ]);
573
+
574
+ // The suppressions tsc looks past blank and `//` lines for (see tscReach).
575
+ // They stay next-line directives as well: Flow, which honours them in
576
+ // TypeScript files, applies them to the very next line.
577
+ const TSC_SUPPRESSIONS = new Set(["@ts-ignore", "@ts-expect-error"]);
578
+
579
+ // The lines each compiler steps over on its way up from a diagnostic to a
580
+ // suppression, matched against the whole line, line break included. tsc 6
581
+ // trims the line and accepts nothing or a `//` comment; tsc 7 accepts only
582
+ // spaces and tabs before the line break or the `//`.
583
+ const TSC_PASSABLE_LINES = [/^\s*(?:\/\/|$)/, /^[ \t]*(?:[\r\n]|\/\/)/];
584
+
585
+ // Directives that only count while no other comment sits between them and
586
+ // their target: deno_graph reads `@deno-types`/`@ts-types` from the last
587
+ // comment before an import, ts-prune and graphql-tag-pluck from the closest
588
+ // leading comment, and ESLint's no-fallthrough and default-case from the last
589
+ // comment before the next case or the closing brace. JetBrains IDEs take a
590
+ // `noinspection` suppression from the comment right in front of a statement,
591
+ // past whitespace alone (`getStatementToolSuppressedIn` in the platform's
592
+ // SuppressionUtil), and a `language=` injection from the comment in front of
593
+ // the literal. Deleting every comment in that gap would newly activate such a
594
+ // directive, so the last one of them stays, trailing comments in front of
595
+ // the code included. With no code left there is nothing to target, and the
596
+ // switch-clause comments are only detected in front of the `case`, `default`
597
+ // or `}` their rules read them before.
598
+ const LAST_COMMENT_DIRECTIVES = new Set([
599
+ "@deno-types",
600
+ "@ts-types",
601
+ "ts-prune-ignore-next",
602
+ "GraphQL",
603
+ "fallthrough",
604
+ "no-default",
605
+ "noinspection",
606
+ "language-injection",
607
+ ]);
608
+
609
+ function isLastCommentDirective(comment: Comment, directive: string): boolean {
610
+ // `//file:noinspection` suppresses for the whole file, wherever the code is.
611
+ return LAST_COMMENT_DIRECTIVES.has(directive) && !(directive === "noinspection" && /^\/\/file:/.test(comment.text));
612
+ }
613
+
614
+ // The JSDoc type casts prettier keeps the parentheses of (see the rule in
615
+ // directives.ts): it does while nothing but whitespace stands between the
616
+ // comment and the parenthesis (`text.slice(previousCommentEnd, start).trim()`
617
+ // in its parse/postprocess), under its Babel, acorn and meriyah parsers. A
618
+ // comment in between leaves the cast out of effect, and prettier drops
619
+ // redundant parentheses there, so the last comment of that gap stays.
620
+ const CAST_DIRECTIVES = new Set(["@type", "@satisfies"]);
621
+
622
+ // The coverage hints ast-v8-to-istanbul, Vitest's v8 provider, applies to the
623
+ // node that starts at the very token after them, where it reads them (see
624
+ // hintsNextNode): with another comment in between, the hint has no target,
625
+ // and deleting every comment there would bring it into effect. One comment of
626
+ // the gap up to the code stays, on top of the lines below the hint, which c8,
627
+ // Node and monocart count.
628
+ const NEXT_TOKEN_DIRECTIVES = new Set([
629
+ "istanbul-ignore-next",
630
+ "istanbul-ignore-if",
631
+ "istanbul-ignore-else",
632
+ "c8-ignore-next",
633
+ "c8-ignore-if",
634
+ "c8-ignore-else",
635
+ "v8-ignore-next",
636
+ "v8-ignore-if",
637
+ "v8-ignore-else",
638
+ "node:coverage-ignore",
639
+ "node:coverage-ignore-if",
640
+ "node:coverage-ignore-else",
641
+ ]);
642
+
643
+ // Directives that target the line or node directly below them. File- and
644
+ // range-scoped pragmas (`istanbul-ignore-file`, `c8-ignore-start`, ...) are
645
+ // absent: they do not target the following line, so they never shield it.
646
+ // They go by their names here: Vitest's v8 provider reads a range hint
647
+ // spelled out on any line of this file, and would drop the rest of the file
648
+ // from this project's coverage. So are the coverage hints no tool counts
649
+ // lines for — the `istanbul` ones and the `if` and `else` forms, which
650
+ // istanbul and ast-v8-to-istanbul alone read, and apply to a node wherever
651
+ // its line is (see NEXT_TOKEN_DIRECTIVES).
652
+ const NEXT_LINE_DIRECTIVES = new Set([
653
+ "@ts-ignore",
654
+ "@ts-expect-error",
655
+ "biome-ignore",
656
+ "deno-lint-ignore",
657
+ "deno-fmt-ignore",
658
+ "deno-coverage-ignore",
659
+ "prettier-ignore",
660
+ "oxfmt-ignore",
661
+ "dprint-ignore",
662
+ "rome-ignore",
663
+ "c8-ignore-next",
664
+ "v8-ignore-next",
665
+ "node:coverage-ignore",
666
+ // Directives that hang off the node or line directly below them: the line
667
+ // below stays a line, so that no code moves up under them.
668
+ "million-ignore",
669
+ "@million-skip",
670
+ "@million-jsx-skip",
671
+ "deepcode-ignore",
672
+ "skipcq",
673
+ "lgtm",
674
+ "codeql",
675
+ "nosemgrep",
676
+ "no-dd-sa",
677
+ "datadog-disable",
678
+ "@next-codemod-error",
679
+ "@next-codemod-ignore",
680
+ "$FlowFixMe",
681
+ "$FlowExpectedError",
682
+ "$FlowIssue",
683
+ "$FlowIgnore",
684
+ "pragma-allowlist-nextline-secret",
685
+ "cspell:disable-next",
686
+ "HTML",
687
+ ]);
688
+
689
+ function isNextLineDirective(name: string): boolean {
690
+ return name.endsWith("-next-line") || NEXT_LINE_DIRECTIVES.has(name);
691
+ }
692
+
693
+ // The coverage pragmas a line count after `ignore next` applies to: c8
694
+ // (v8-to-istanbul), Node's test-runner coverage and monocart-coverage-reports
695
+ // count lines, each in its own way (see coverage.ts). istanbul and
696
+ // ast-v8-to-istanbul, Vitest's providers, apply the hint to the next node
697
+ // whatever count follows, so `istanbul ignore next 3` covers one line.
698
+ // Everything else — `@ts-expect-error`, `eslint-disable-next-line` and
699
+ // friends — covers exactly one line too, no matter what prose like "we
700
+ // ignore next 3 legacy calls" appears in the reason text.
701
+ const COUNTED_NEXT_LINE = new Set(["c8-ignore-next", "v8-ignore-next", "node:coverage-ignore"]);