@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/README.en.md +11 -8
- package/README.md +11 -8
- package/dist/directives.d.ts +27 -9
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +351 -153
- package/dist/directives.js.map +1 -1
- package/dist/remove.d.ts +6 -4
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +178 -25
- package/dist/remove.js.map +1 -1
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +18 -5
- package/dist/scanner.js.map +1 -1
- package/package.json +1 -1
- package/src/directives.ts +379 -155
- package/src/remove.ts +190 -27
- package/src/scanner.ts +18 -5
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
|
|
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,
|
|
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
|
|
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
|
|
148
|
-
*
|
|
149
|
-
* comments never moves a comment across the first token, so the
|
|
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 ===
|
|
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
|
|
200
|
-
* removable comments (`/* one */ /* two */`) vanishes just the same,
|
|
201
|
-
* comment on it has to stay. Runs to a fixpoint because a
|
|
202
|
-
* comment can itself be a next-line directive shielding further
|
|
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
|
-
|
|
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(
|
|
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
|
|
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
|
-
|
|
243
|
-
|
|
244
|
-
|
|
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 (
|
|
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
|
|
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 ===
|
|
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,
|