@kongyo2/ts-comment-scanner 1.7.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 +13 -8
- package/README.md +13 -8
- package/dist/args.d.ts +2 -1
- package/dist/args.d.ts.map +1 -1
- package/dist/directives.d.ts +27 -9
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +391 -164
- package/dist/directives.js.map +1 -1
- package/dist/docblock.d.ts +7 -0
- package/dist/docblock.d.ts.map +1 -0
- package/dist/docblock.js +51 -0
- package/dist/docblock.js.map +1 -0
- package/dist/remove.d.ts +6 -4
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +185 -28
- package/dist/remove.js.map +1 -1
- package/dist/run.d.ts +0 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +7 -5
- package/dist/run.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 +4 -2
- package/src/args.ts +1 -1
- package/src/directives.ts +424 -170
- package/src/docblock.ts +49 -0
- package/src/remove.ts +198 -30
- package/src/run.ts +11 -10
- package/src/scanner.ts +18 -5
package/src/docblock.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The pragma keys of a docblock, read the way jest-docblock (v30.5.0, the
|
|
3
|
+
* version prettier main pins) reads them. Prettier's `--require-pragma` and
|
|
4
|
+
* `--check-ignore-pragma` modes run the file's leading docblock through
|
|
5
|
+
* jest-docblock (prettier `src/language-js/pragma.js`), so the regexes below
|
|
6
|
+
* are jest-docblock's own and its quirks carry over:
|
|
7
|
+
*
|
|
8
|
+
* - `/*` single-star comments are docblocks too (`\/\*\*?`).
|
|
9
|
+
* - The gutter strip removes spaces, ONE star and one optional space per line
|
|
10
|
+
* (`(\r?\n|^) *\* ?`), so a tab before the star, or a doubled star, leaves
|
|
11
|
+
* the line's `@` off the line start and the pragma unrecognised.
|
|
12
|
+
* - Only spaces may precede the `@`; a tab defeats it as well.
|
|
13
|
+
* - The docblock regex spells line breaks as `\r?\n`, so a U+2028 or U+2029
|
|
14
|
+
* anywhere in the comment stops it from being extracted at all.
|
|
15
|
+
*
|
|
16
|
+
* Prettier normalises CR and CRLF to LF before parsing (`normalizeEndOfLine`
|
|
17
|
+
* in `src/common/end-of-line.js`), and so does this port. jest-docblock's
|
|
18
|
+
* remaining steps — folding a value continued on the next line into its key
|
|
19
|
+
* and trimming the text — only shape the values, never which keys exist: a
|
|
20
|
+
* continuation line starts with something other than `@`, so it was never a
|
|
21
|
+
* key, and the key line it joins stays a key. They are left out, which also
|
|
22
|
+
* spares long docblocks the one-pass-per-continuation-line loop.
|
|
23
|
+
*/
|
|
24
|
+
const DOCBLOCK = /^\s*(\/\*\*?(.|\r?\n)*?\*\/)/;
|
|
25
|
+
const COMMENT_START = /^\/\*\*?/;
|
|
26
|
+
const COMMENT_END = /\*\/$/;
|
|
27
|
+
const GUTTER = /(\r?\n|^) *\* ?/g;
|
|
28
|
+
const PROPERTY = /(?:^|\r?\n) *@(\S+) *([^\n\r]*)/g;
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* The pragma keys of the docblock that opens the text (`format` for a
|
|
32
|
+
* `@format` line), in order of first appearance, or an empty list when the
|
|
33
|
+
* text does not open with a docblock jest-docblock would extract.
|
|
34
|
+
*/
|
|
35
|
+
export function docblockPragmas(text: string): string[] {
|
|
36
|
+
const match = DOCBLOCK.exec(text.replaceAll(/\r\n?/g, "\n"));
|
|
37
|
+
if (!match) return [];
|
|
38
|
+
const docblock = (match[0] as string)
|
|
39
|
+
.trimStart()
|
|
40
|
+
.replace(COMMENT_START, "")
|
|
41
|
+
.replace(COMMENT_END, "")
|
|
42
|
+
.replaceAll(GUTTER, "$1");
|
|
43
|
+
const keys: string[] = [];
|
|
44
|
+
for (const property of docblock.matchAll(PROPERTY)) {
|
|
45
|
+
const key = property[1] as string;
|
|
46
|
+
if (!keys.includes(key)) keys.push(key);
|
|
47
|
+
}
|
|
48
|
+
return keys;
|
|
49
|
+
}
|
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
|
|
@@ -92,7 +94,7 @@ export function removeComments(source: string, options: RemoveOptions = {}): Rem
|
|
|
92
94
|
}
|
|
93
95
|
removed = removed.filter((comment) => comment !== blocker);
|
|
94
96
|
kept.push(blocker);
|
|
95
|
-
kept.sort(
|
|
97
|
+
kept.sort(byStart);
|
|
96
98
|
}
|
|
97
99
|
}
|
|
98
100
|
|
|
@@ -100,6 +102,11 @@ function unexpectedResult(): Error {
|
|
|
100
102
|
return new Error("comment removal produced an unexpected result; refusing to continue");
|
|
101
103
|
}
|
|
102
104
|
|
|
105
|
+
/** Sort comparator for document order: comments are ordered by where they start. */
|
|
106
|
+
function byStart(a: Comment, b: Comment): number {
|
|
107
|
+
return a.start - b.start;
|
|
108
|
+
}
|
|
109
|
+
|
|
103
110
|
/**
|
|
104
111
|
* Compares the spliced output's comments against the comments meant to
|
|
105
112
|
* survive, in document order (removal never reorders them). Throws when the
|
|
@@ -118,7 +125,7 @@ function firstChangedSurvivor(
|
|
|
118
125
|
kept: Comment[],
|
|
119
126
|
skipped: Comment[],
|
|
120
127
|
): Comment | undefined {
|
|
121
|
-
const expected = [...kept, ...skipped].sort(
|
|
128
|
+
const expected = [...kept, ...skipped].sort(byStart);
|
|
122
129
|
if (actual.length !== expected.length) {
|
|
123
130
|
throw unexpectedResult();
|
|
124
131
|
}
|
|
@@ -139,17 +146,17 @@ function firstChangedSurvivor(
|
|
|
139
146
|
* The placement bits the position-dependent directives care about, derived
|
|
140
147
|
* without a parse: the comment is the file's first comment when nothing but
|
|
141
148
|
* whitespace (or a shebang) precedes it — any earlier comment's text keeps
|
|
142
|
-
* the slice non-blank — and it sits at the file start when it begins
|
|
143
|
-
*
|
|
144
|
-
* comments never moves a comment across the first token, so the
|
|
145
|
-
* 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.
|
|
146
153
|
*/
|
|
147
154
|
function positionalPlacement(text: string, comment: Comment): DirectivePlacement {
|
|
148
155
|
const shebangLength = /^#!.*/.exec(text)?.[0].length ?? 0;
|
|
149
156
|
return {
|
|
150
157
|
header: false,
|
|
151
158
|
firstComment: isBlank(text.slice(shebangLength, comment.start)),
|
|
152
|
-
fileStart: comment.start ===
|
|
159
|
+
fileStart: comment.start === bunMarkerOffset(text),
|
|
153
160
|
};
|
|
154
161
|
}
|
|
155
162
|
|
|
@@ -189,18 +196,27 @@ function isProtected(comment: Comment, options: RemoveOptions): boolean {
|
|
|
189
196
|
* under a surviving next-line directive (`@ts-expect-error`,
|
|
190
197
|
* `eslint-disable-next-line`, ...). Dropping such a line would shift the
|
|
191
198
|
* following code up, silently changing which line the directive applies to —
|
|
192
|
-
* 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.
|
|
193
204
|
*
|
|
194
|
-
* The
|
|
195
|
-
* removable comments (`/* one */ /* two */`) vanishes just the same,
|
|
196
|
-
* comment on it has to stay. Runs to a fixpoint because a
|
|
197
|
-
* comment can itself be a next-line directive shielding further
|
|
198
|
-
* 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).
|
|
199
210
|
*/
|
|
200
211
|
function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comment[], skipped: Comment[]): Comment[] {
|
|
201
212
|
const lineOffsets = lineStartOffsets(source);
|
|
202
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);
|
|
203
217
|
const shieldedLines = new Set<number>();
|
|
218
|
+
const blockingLines = new Set<number>();
|
|
219
|
+
const shieldedGaps: Array<readonly [number, number]> = [];
|
|
204
220
|
const processed = new Set<Comment>();
|
|
205
221
|
let stillRemoved = removed;
|
|
206
222
|
|
|
@@ -209,11 +225,28 @@ function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comm
|
|
|
209
225
|
for (const comment of [...kept, ...skipped]) {
|
|
210
226
|
if (processed.has(comment)) continue;
|
|
211
227
|
processed.add(comment);
|
|
212
|
-
|
|
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;
|
|
213
246
|
// A trailing formatter or scanner suppression (`a = [1]; // oxfmt-ignore`,
|
|
214
247
|
// `secret(); // nosemgrep`) targets its own line, so it shields nothing
|
|
215
248
|
// below it.
|
|
216
|
-
if (TRAILING_TARGETS_OWN_LINE.has(
|
|
249
|
+
if (TRAILING_TARGETS_OWN_LINE.has(directive) && !occupiesWholeLines(source, comment)) {
|
|
217
250
|
continue;
|
|
218
251
|
}
|
|
219
252
|
// Counted pragmas like `c8 ignore next 3` cover several lines.
|
|
@@ -229,29 +262,138 @@ function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comm
|
|
|
229
262
|
return added;
|
|
230
263
|
};
|
|
231
264
|
|
|
232
|
-
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 => {
|
|
233
272
|
let changed = false;
|
|
234
273
|
for (const line of shieldedLines) {
|
|
235
274
|
const group = vanishingLineGroup(source, line, lineOffsets, stillRemoved);
|
|
236
275
|
if (group === undefined) continue;
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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);
|
|
240
289
|
changed = true;
|
|
241
290
|
}
|
|
242
291
|
return changed;
|
|
243
292
|
};
|
|
244
293
|
|
|
245
294
|
collectShields();
|
|
246
|
-
while (
|
|
295
|
+
while (protectShields()) {
|
|
247
296
|
if (!collectShields()) break;
|
|
248
297
|
}
|
|
249
298
|
if (stillRemoved.length !== removed.length) {
|
|
250
|
-
kept.sort(
|
|
299
|
+
kept.sort(byStart);
|
|
251
300
|
}
|
|
252
301
|
return stillRemoved;
|
|
253
302
|
}
|
|
254
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
|
+
|
|
255
397
|
/**
|
|
256
398
|
* The removal candidates that would make the given line disappear: every
|
|
257
399
|
* non-whitespace character of the line lies inside one of them, so splicing
|
|
@@ -290,6 +432,36 @@ const TRAILING_TARGETS_OWN_LINE = new Set([
|
|
|
290
432
|
"nosemgrep",
|
|
291
433
|
]);
|
|
292
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
|
+
|
|
293
465
|
// Directives that target the line or node directly below them. File- and
|
|
294
466
|
// range-scoped pragmas (`c8 ignore start`, `istanbul ignore file`, ...) are
|
|
295
467
|
// absent: they do not target the following line, so they never shield it.
|
|
@@ -320,12 +492,9 @@ const NEXT_LINE_DIRECTIVES = new Set([
|
|
|
320
492
|
// Directives that hang off the node or line directly below them: a
|
|
321
493
|
// whole-line comment between them and their target would change what
|
|
322
494
|
// they apply to, so the line below stays shielded.
|
|
323
|
-
"ts-prune-ignore-next",
|
|
324
495
|
"million-ignore",
|
|
325
496
|
"@million-skip",
|
|
326
497
|
"@million-jsx-skip",
|
|
327
|
-
"@deno-types",
|
|
328
|
-
"@ts-types",
|
|
329
498
|
"deepcode-ignore",
|
|
330
499
|
"skipcq",
|
|
331
500
|
"lgtm",
|
|
@@ -343,7 +512,6 @@ const NEXT_LINE_DIRECTIVES = new Set([
|
|
|
343
512
|
"$FlowIgnore",
|
|
344
513
|
"pragma-allowlist-nextline-secret",
|
|
345
514
|
"cspell:disable-next",
|
|
346
|
-
"GraphQL",
|
|
347
515
|
"HTML",
|
|
348
516
|
]);
|
|
349
517
|
|
package/src/run.ts
CHANGED
|
@@ -15,7 +15,7 @@ import {
|
|
|
15
15
|
type CollectOptions,
|
|
16
16
|
} from "./files.js";
|
|
17
17
|
import { changedFiles } from "./git.js";
|
|
18
|
-
import { removeComments } from "./remove.js";
|
|
18
|
+
import { removeComments, type RemoveResult } from "./remove.js";
|
|
19
19
|
import { count, formatGitHub, formatJson, formatText } from "./report.js";
|
|
20
20
|
import { getVersion } from "./version.js";
|
|
21
21
|
import type { Comment, FileScanResult } from "./types.js";
|
|
@@ -25,7 +25,7 @@ export interface CliIO {
|
|
|
25
25
|
err: (text: string) => void;
|
|
26
26
|
}
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
const HELP_TEXT = `Usage: ts-comment-scanner [options] [paths...]
|
|
29
29
|
|
|
30
30
|
Detect, report and clean up comments across a TypeScript project.
|
|
31
31
|
|
|
@@ -122,12 +122,16 @@ export async function run(argv: string[], io: CliIO): Promise<number> {
|
|
|
122
122
|
const total = results.reduce((sum, result) => sum + result.comments.length, 0);
|
|
123
123
|
return options.failOnComment && total > 0 ? 1 : 0;
|
|
124
124
|
} catch (error) {
|
|
125
|
-
|
|
126
|
-
io.err(`ts-comment-scanner: ${message}\n`);
|
|
125
|
+
io.err(`ts-comment-scanner: ${errorMessage(error)}\n`);
|
|
127
126
|
return 2;
|
|
128
127
|
}
|
|
129
128
|
}
|
|
130
129
|
|
|
130
|
+
/** The message of a thrown value; collaborators can throw non-Error values, which are stringified. */
|
|
131
|
+
function errorMessage(error: unknown): string {
|
|
132
|
+
return error instanceof Error ? error.message : String(error);
|
|
133
|
+
}
|
|
134
|
+
|
|
131
135
|
/**
|
|
132
136
|
* Collects the input files, narrowed to the files git reports changed when
|
|
133
137
|
* --diff is set. git runs in the repository containing the first input path
|
|
@@ -210,11 +214,9 @@ function filterDirectives(results: FileScanResult[], mode: DirectiveMode): FileS
|
|
|
210
214
|
}));
|
|
211
215
|
}
|
|
212
216
|
|
|
213
|
-
|
|
217
|
+
/** One file's removal outcome: the comment tallies removeComments reports, keyed by the file they came from. */
|
|
218
|
+
interface FileRemoval extends Pick<RemoveResult, "removed" | "kept" | "skipped"> {
|
|
214
219
|
file: string;
|
|
215
|
-
removed: Comment[];
|
|
216
|
-
kept: Comment[];
|
|
217
|
-
skipped: Comment[];
|
|
218
220
|
}
|
|
219
221
|
|
|
220
222
|
async function runRemove(options: CliOptions, collectOptions: CollectOptions, io: CliIO): Promise<number> {
|
|
@@ -243,8 +245,7 @@ async function runRemove(options: CliOptions, collectOptions: CollectOptions, io
|
|
|
243
245
|
}
|
|
244
246
|
return { file, removed: result.removed, kept: result.kept, skipped: result.skipped };
|
|
245
247
|
} catch (error) {
|
|
246
|
-
|
|
247
|
-
return { file, failure: `${file}: ${message}` };
|
|
248
|
+
return { file, failure: `${file}: ${errorMessage(error)}` };
|
|
248
249
|
}
|
|
249
250
|
});
|
|
250
251
|
|
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,
|