@kongyo2/ts-comment-scanner 1.8.0 → 1.9.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/remove.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { activePositionalDirectives, isLegalComment, type DirectivePlacement } from "./directives.js";
1
+ import { activePositionalDirectives, bunMarkerOffset, isLegalComment, type DirectivePlacement } from "./directives.js";
2
2
  import { LINE_BREAK, LINE_TERMINATOR, isBlank, lineStartOffsets } from "./lines.js";
3
3
  import { scanComments } from "./scanner.js";
4
4
  import type { Comment } from "./types.js";
@@ -19,9 +19,11 @@ export interface RemoveResult {
19
19
  removed: Comment[];
20
20
  /**
21
21
  * Comments kept because they are protected: directives, license headers,
22
- * comments whose removal would shift code under a next-line directive, and
22
+ * comments whose removal would shift code under a next-line directive or
23
+ * that sit between a directive and the code it reaches past them for, and
23
24
  * comments whose removal would move a position-dependent directive
24
- * (prettier's first-comment pragma, Bun's file-start marker) into effect.
25
+ * (prettier's first-comment pragma, Deno's coverage file pragma, Bun's
26
+ * file-start marker) into effect.
25
27
  */
26
28
  kept: Comment[];
27
29
  /** Comments excluded from removal by the `shouldRemove` predicate. */
@@ -39,8 +41,8 @@ export interface RemoveResult {
39
41
  * - Surviving comments keep their directive semantics: when deleting a leading
40
42
  * comment would newly activate a position-dependent directive in a kept
41
43
  * comment (prettier's `@format` docblock pragma counts only as the file's
42
- * first comment, Bun's `// @bun` only at the very start), the leading
43
- * comment is kept instead.
44
+ * first comment, Bun's `// @bun` only at the very start or right after a
45
+ * shebang line), the leading comment is kept instead.
44
46
  * - A space is inserted where removing a block comment would merge two tokens,
45
47
  * and a line break is kept where the comment acted as one (ASI stays intact).
46
48
  * - A leading byte-order mark is preserved. Reported positions index into the
@@ -144,17 +146,17 @@ function firstChangedSurvivor(
144
146
  * The placement bits the position-dependent directives care about, derived
145
147
  * without a parse: the comment is the file's first comment when nothing but
146
148
  * whitespace (or a shebang) precedes it — any earlier comment's text keeps
147
- * the slice non-blank — and it sits at the file start when it begins at
148
- * offset zero. Header status needs the token structure, but removing
149
- * comments never moves a comment across the first token, so the positional
150
- * check does not consult it.
149
+ * the slice non-blank — and it sits at the file start when it begins where
150
+ * Bun reads its marker. Header status needs the token structure, but
151
+ * removing comments never moves a comment across the first token, so the
152
+ * positional check does not consult it.
151
153
  */
152
154
  function positionalPlacement(text: string, comment: Comment): DirectivePlacement {
153
155
  const shebangLength = /^#!.*/.exec(text)?.[0].length ?? 0;
154
156
  return {
155
157
  header: false,
156
158
  firstComment: isBlank(text.slice(shebangLength, comment.start)),
157
- fileStart: comment.start === 0,
159
+ fileStart: comment.start === bunMarkerOffset(text),
158
160
  };
159
161
  }
160
162
 
@@ -194,18 +196,27 @@ function isProtected(comment: Comment, options: RemoveOptions): boolean {
194
196
  * under a surviving next-line directive (`@ts-expect-error`,
195
197
  * `eslint-disable-next-line`, ...). Dropping such a line would shift the
196
198
  * following code up, silently changing which line the directive applies to —
197
- * and with it the compiler or linter behaviour.
199
+ * and with it the compiler or linter behaviour. Directives whose tools reach
200
+ * further get more: below a tsc suppression the first line each compiler
201
+ * cannot step over stays, and between a directive that only counts as the
202
+ * last comment before its target (`@deno-types`, ...) and that target every
203
+ * comment stays.
198
204
  *
199
- * The check works on whole lines, not single comments: a line holding several
200
- * removable comments (`/* one *​/ /* two *​/`) vanishes just the same, so every
201
- * comment on it has to stay. Runs to a fixpoint because a re-protected
202
- * comment can itself be a next-line directive shielding further lines (when
203
- * directives are being removed selectively).
205
+ * The line checks work on whole lines, not single comments: a line holding
206
+ * several removable comments (`/* one *​/ /* two *​/`) vanishes just the same,
207
+ * so every comment on it has to stay. Runs to a fixpoint because a
208
+ * re-protected comment can itself be a next-line directive shielding further
209
+ * lines (when directives are being removed selectively).
204
210
  */
205
211
  function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comment[], skipped: Comment[]): Comment[] {
206
212
  const lineOffsets = lineStartOffsets(source);
207
213
  const totalLines = lineOffsets.length;
214
+ // Where the code after a directive starts does not depend on which comments
215
+ // go, so it is looked up among all of them.
216
+ const allComments = [...removed, ...kept, ...skipped].sort(byStart);
208
217
  const shieldedLines = new Set<number>();
218
+ const blockingLines = new Set<number>();
219
+ const shieldedGaps: Array<readonly [number, number]> = [];
209
220
  const processed = new Set<Comment>();
210
221
  let stillRemoved = removed;
211
222
 
@@ -214,11 +225,28 @@ function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comm
214
225
  for (const comment of [...kept, ...skipped]) {
215
226
  if (processed.has(comment)) continue;
216
227
  processed.add(comment);
217
- if (comment.directive === undefined || !isNextLineDirective(comment.directive)) continue;
228
+ const directive = comment.directive;
229
+ if (directive === undefined) continue;
230
+ if (LAST_COMMENT_DIRECTIVES.has(directive)) {
231
+ const codeStart = codeStartAfter(source, comment.end, allComments);
232
+ if (codeStart > comment.end && codeStart < source.length) {
233
+ shieldedGaps.push([comment.end, codeStart]);
234
+ added = true;
235
+ }
236
+ continue;
237
+ }
238
+ if (TSC_SUPPRESSIONS.has(directive)) {
239
+ for (const line of firstBlockingLines(source, comment, lineOffsets, allComments)) {
240
+ if (blockingLines.has(line)) continue;
241
+ blockingLines.add(line);
242
+ added = true;
243
+ }
244
+ }
245
+ if (!isNextLineDirective(directive)) continue;
218
246
  // A trailing formatter or scanner suppression (`a = [1]; // oxfmt-ignore`,
219
247
  // `secret(); // nosemgrep`) targets its own line, so it shields nothing
220
248
  // below it.
221
- if (TRAILING_TARGETS_OWN_LINE.has(comment.directive) && !occupiesWholeLines(source, comment)) {
249
+ if (TRAILING_TARGETS_OWN_LINE.has(directive) && !occupiesWholeLines(source, comment)) {
222
250
  continue;
223
251
  }
224
252
  // Counted pragmas like `c8 ignore next 3` cover several lines.
@@ -234,21 +262,37 @@ function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comm
234
262
  return added;
235
263
  };
236
264
 
237
- const protectShieldedLines = (): boolean => {
265
+ const protect = (group: readonly Comment[]): void => {
266
+ const grouped = new Set(group);
267
+ stillRemoved = stillRemoved.filter((comment) => !grouped.has(comment));
268
+ kept.push(...group);
269
+ };
270
+
271
+ const protectShields = (): boolean => {
238
272
  let changed = false;
239
273
  for (const line of shieldedLines) {
240
274
  const group = vanishingLineGroup(source, line, lineOffsets, stillRemoved);
241
275
  if (group === undefined) continue;
242
- const grouped = new Set(group);
243
- stillRemoved = stillRemoved.filter((comment) => !grouped.has(comment));
244
- kept.push(...group);
276
+ protect(group);
277
+ changed = true;
278
+ }
279
+ for (const line of blockingLines) {
280
+ const group = lineOpeningGroup(source, line, lineOffsets, stillRemoved);
281
+ if (group === undefined) continue;
282
+ protect(group);
283
+ changed = true;
284
+ }
285
+ for (const [from, to] of shieldedGaps) {
286
+ const group = stillRemoved.filter((comment) => comment.start >= from && comment.start < to);
287
+ if (group.length === 0) continue;
288
+ protect(group);
245
289
  changed = true;
246
290
  }
247
291
  return changed;
248
292
  };
249
293
 
250
294
  collectShields();
251
- while (protectShieldedLines()) {
295
+ while (protectShields()) {
252
296
  if (!collectShields()) break;
253
297
  }
254
298
  if (stillRemoved.length !== removed.length) {
@@ -257,6 +301,99 @@ function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comm
257
301
  return stillRemoved;
258
302
  }
259
303
 
304
+ /**
305
+ * Offset of the first character at or after `from` that is neither
306
+ * whitespace nor inside one of the (sorted, non-overlapping) comments, or the
307
+ * source length when only comments follow. `from` lies past the start of at
308
+ * least one comment (the directive the search is for); when the closest of
309
+ * them runs past `from` — a block comment opened on the directive's line —
310
+ * the search resumes at its end.
311
+ */
312
+ function codeStartAfter(source: string, from: number, comments: readonly Comment[]): number {
313
+ let next = firstIndexAtOrAfter(comments, from, (comment) => comment.start);
314
+ let index = Math.max(from, (comments[next - 1] as Comment).end);
315
+ while (index < source.length) {
316
+ const comment = comments[next];
317
+ if (comment !== undefined && comment.start === index) {
318
+ index = comment.end;
319
+ next += 1;
320
+ } else if (isBlank(source[index] as string)) {
321
+ index += 1;
322
+ } else {
323
+ return index;
324
+ }
325
+ }
326
+ return source.length;
327
+ }
328
+
329
+ /** Index of the first item whose key is at least `value`, by binary search over ascending keys. */
330
+ function firstIndexAtOrAfter<T>(items: readonly T[], value: number, key: (item: T) => number): number {
331
+ let low = 0;
332
+ let high = items.length;
333
+ while (low < high) {
334
+ const middle = (low + high) >> 1;
335
+ if (key(items[middle] as T) < value) low = middle + 1;
336
+ else high = middle;
337
+ }
338
+ return low;
339
+ }
340
+
341
+ /**
342
+ * For each TypeScript compiler, the first line between a tsc suppression and
343
+ * the code on the lines below it that the compiler does not step over, if
344
+ * any. Looking for the line a suppression applies to, a compiler skips the
345
+ * lines it reads as blank or as a `//` comment (see TSC_PASSABLE_LINES); any
346
+ * other line — one opening with a block comment, say — ends the search,
347
+ * leaving the suppression without a target for that compiler. Deleting that
348
+ * line would let the suppression reach the code instead, so it has to stay.
349
+ * The two compilers can stop at different lines: a line holding only a
350
+ * vertical tab stops tsc 7, while tsc 6 searches on to the next line it
351
+ * cannot pass.
352
+ */
353
+ function firstBlockingLines(
354
+ source: string,
355
+ comment: Comment,
356
+ lineOffsets: readonly number[],
357
+ comments: readonly Comment[],
358
+ ): number[] {
359
+ // A suppression applies from the line below it on, so code sharing its line
360
+ // (`/* @ts-ignore */ foo();`) does not end the search.
361
+ const codeStart = codeStartAfter(source, lineOffsets[comment.endLine] ?? source.length, comments);
362
+ if (codeStart >= source.length) return [];
363
+ const codeLine = firstIndexAtOrAfter(lineOffsets, codeStart + 1, (offset) => offset);
364
+ const found: number[] = [];
365
+ for (const passable of TSC_PASSABLE_LINES) {
366
+ for (let line = comment.endLine + 1; line < codeLine; line += 1) {
367
+ if (!passable.test(source.slice(lineOffsets[line - 1], lineOffsets[line]))) {
368
+ found.push(line);
369
+ break;
370
+ }
371
+ }
372
+ }
373
+ return found;
374
+ }
375
+
376
+ /**
377
+ * The removal candidates on the given line when one of them opens it (holds
378
+ * its first non-whitespace character), so that splicing them out would
379
+ * change how the line starts. Returns undefined when a surviving comment
380
+ * opens the line instead, or nothing on it is to be removed.
381
+ */
382
+ function lineOpeningGroup(
383
+ source: string,
384
+ line: number,
385
+ lineOffsets: readonly number[],
386
+ removals: readonly Comment[],
387
+ ): Comment[] | undefined {
388
+ // A blocking line always lies above the code line, so the next offset exists.
389
+ const lineStart = lineOffsets[line - 1] as number;
390
+ const lineEnd = lineOffsets[line] as number;
391
+ const group = removals.filter((comment) => comment.start < lineEnd && comment.end > lineStart);
392
+ let first = lineStart;
393
+ while (first < lineEnd && isBlank(source[first] as string)) first += 1;
394
+ return group.some((comment) => comment.start <= first && first < comment.end) ? group : undefined;
395
+ }
396
+
260
397
  /**
261
398
  * The removal candidates that would make the given line disappear: every
262
399
  * non-whitespace character of the line lies inside one of them, so splicing
@@ -295,6 +432,36 @@ const TRAILING_TARGETS_OWN_LINE = new Set([
295
432
  "nosemgrep",
296
433
  ]);
297
434
 
435
+ // The suppressions tsc looks past blank and `//` lines for (see
436
+ // firstBlockingLines). They stay next-line directives as well: Flow, which
437
+ // honours them in TypeScript files, applies them to the very next line.
438
+ const TSC_SUPPRESSIONS = new Set(["@ts-ignore", "@ts-expect-error"]);
439
+
440
+ // The lines each compiler steps over on its way up from a diagnostic to a
441
+ // suppression, matched against the whole line, line break included. tsc 6
442
+ // trims the line and accepts nothing or a `//` comment; tsc 7 accepts only
443
+ // spaces and tabs before the line break or the `//`.
444
+ const TSC_PASSABLE_LINES = [/^\s*(?:\/\/|$)/, /^[ \t]*(?:[\r\n]|\/\/)/];
445
+
446
+ // Directives that only count while no other comment sits between them and
447
+ // their target: deno_graph reads `@deno-types`/`@ts-types` from the last
448
+ // comment before an import, ts-prune and graphql-tag-pluck from the closest
449
+ // leading comment, and ESLint's no-fallthrough and default-case from the last
450
+ // comment before the next case or the closing brace. Deleting the comments in
451
+ // that gap would newly activate such a directive, so the whole gap is
452
+ // shielded — trailing comments in front of the code included. With no code
453
+ // left there is nothing to target, and the switch-clause comments are only
454
+ // detected in front of the `case`, `default` or `}` their rules read them
455
+ // before.
456
+ const LAST_COMMENT_DIRECTIVES = new Set([
457
+ "@deno-types",
458
+ "@ts-types",
459
+ "ts-prune-ignore-next",
460
+ "GraphQL",
461
+ "fallthrough",
462
+ "no-default",
463
+ ]);
464
+
298
465
  // Directives that target the line or node directly below them. File- and
299
466
  // range-scoped pragmas (`c8 ignore start`, `istanbul ignore file`, ...) are
300
467
  // absent: they do not target the following line, so they never shield it.
@@ -325,12 +492,9 @@ const NEXT_LINE_DIRECTIVES = new Set([
325
492
  // Directives that hang off the node or line directly below them: a
326
493
  // whole-line comment between them and their target would change what
327
494
  // they apply to, so the line below stays shielded.
328
- "ts-prune-ignore-next",
329
495
  "million-ignore",
330
496
  "@million-skip",
331
497
  "@million-jsx-skip",
332
- "@deno-types",
333
- "@ts-types",
334
498
  "deepcode-ignore",
335
499
  "skipcq",
336
500
  "lgtm",
@@ -348,7 +512,6 @@ const NEXT_LINE_DIRECTIVES = new Set([
348
512
  "$FlowIgnore",
349
513
  "pragma-allowlist-nextline-secret",
350
514
  "cspell:disable-next",
351
- "GraphQL",
352
515
  "HTML",
353
516
  ]);
354
517
 
package/src/scanner.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import ts from "typescript";
2
- import { detectDirective, type DirectivePlacement } from "./directives.js";
2
+ import { bunMarkerOffset, detectDirective, type DirectivePlacement } from "./directives.js";
3
3
  import type { Comment, CommentKind } from "./types.js";
4
4
 
5
5
  export interface ScanOptions {
@@ -77,18 +77,31 @@ export function scanComments(source: string, options: ScanOptions = {}): Comment
77
77
  const firstTokenStart = sourceFile.getStart(sourceFile);
78
78
  const shebangEnd = ts.getShebang(source)?.length ?? 0;
79
79
  const firstCommentPos = sorted.length > 0 ? (sorted[0] as ts.CommentRange).pos : -1;
80
- const placementOf = (pos: number): DirectivePlacement => ({
80
+ const bunMarkerPos = bunMarkerOffset(source);
81
+ // The token after each comment, past the comments that follow it (`""` when
82
+ // only comments do): walking back from the last comment, a gap holding code
83
+ // supplies its first token and a blank one passes on the next comment's.
84
+ const nextTokens: string[] = [];
85
+ let following = "";
86
+ for (let index = sorted.length - 1; index >= 0; index -= 1) {
87
+ const gapEnd = sorted[index + 1]?.pos ?? source.length;
88
+ const gap = source.slice((sorted[index] as ts.CommentRange).end, gapEnd);
89
+ following = /^\s*([A-Za-z_$][\w$]*|\S)/.exec(gap)?.[1] ?? following;
90
+ nextTokens[index] = following;
91
+ }
92
+ const placementOf = (pos: number, index: number): DirectivePlacement => ({
81
93
  header: pos < firstTokenStart,
82
94
  firstComment: pos === firstCommentPos && /^\s*$/.test(source.slice(shebangEnd, pos)),
83
- fileStart: pos === 0,
95
+ fileStart: pos === bunMarkerPos,
96
+ nextToken: nextTokens[index] as string,
84
97
  });
85
98
 
86
- return sorted.map((range) => {
99
+ return sorted.map((range, index) => {
87
100
  const kind: CommentKind = range.kind === ts.SyntaxKind.SingleLineCommentTrivia ? "line" : "block";
88
101
  const text = source.slice(range.pos, range.end);
89
102
  const startPosition = sourceFile.getLineAndCharacterOfPosition(range.pos);
90
103
  const endPosition = sourceFile.getLineAndCharacterOfPosition(range.end);
91
- const directive = detectDirective(kind, text, placementOf(range.pos));
104
+ const directive = detectDirective(kind, text, placementOf(range.pos, index));
92
105
  return {
93
106
  kind,
94
107
  text,