@kongyo2/ts-comment-scanner 1.21.0 → 1.23.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.md +240 -52
- package/dist/astgrep.d.ts +4 -2
- package/dist/astgrep.d.ts.map +1 -1
- package/dist/astgrep.js +7 -4
- package/dist/astgrep.js.map +1 -1
- package/dist/containers.d.ts +48 -0
- package/dist/containers.d.ts.map +1 -0
- package/dist/containers.js +82 -0
- package/dist/containers.js.map +1 -0
- package/dist/coverage.d.ts +45 -0
- package/dist/coverage.d.ts.map +1 -0
- package/dist/coverage.js +92 -0
- package/dist/coverage.js.map +1 -0
- package/dist/directives.d.ts +13 -3
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +31 -11
- package/dist/directives.js.map +1 -1
- package/dist/files.d.ts +5 -0
- package/dist/files.d.ts.map +1 -1
- package/dist/files.js +103 -41
- package/dist/files.js.map +1 -1
- package/dist/imports.d.ts +12 -5
- package/dist/imports.d.ts.map +1 -1
- package/dist/imports.js +33 -10
- package/dist/imports.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/lines.d.ts +11 -0
- package/dist/lines.d.ts.map +1 -1
- package/dist/lines.js +30 -0
- package/dist/lines.js.map +1 -1
- package/dist/remove.d.ts +16 -12
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +51 -638
- package/dist/remove.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +11 -10
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts +29 -0
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +122 -5
- package/dist/scanner.js.map +1 -1
- package/dist/shields.d.ts +77 -0
- package/dist/shields.d.ts.map +1 -0
- package/dist/shields.js +758 -0
- package/dist/shields.js.map +1 -0
- package/dist/splice.d.ts +40 -15
- package/dist/splice.d.ts.map +1 -1
- package/dist/splice.js +185 -69
- package/dist/splice.js.map +1 -1
- package/package.json +6 -5
- package/src/astgrep.ts +7 -5
- package/src/containers.ts +128 -0
- package/src/coverage.ts +110 -0
- package/src/directives.ts +45 -11
- package/src/files.ts +147 -53
- package/src/imports.ts +42 -17
- package/src/index.ts +1 -0
- package/src/lines.ts +33 -1
- package/src/remove.ts +58 -748
- package/src/run.ts +11 -10
- package/src/scanner.ts +160 -5
- package/src/shields.ts +852 -0
- package/src/splice.ts +216 -75
package/src/run.ts
CHANGED
|
@@ -6,10 +6,10 @@ import {
|
|
|
6
6
|
collectFiles,
|
|
7
7
|
encodeFileText,
|
|
8
8
|
foldPathCase,
|
|
9
|
-
isJsxFile,
|
|
10
9
|
mapFiles,
|
|
11
10
|
readFileText,
|
|
12
11
|
scanFile,
|
|
12
|
+
scanOptionsFor,
|
|
13
13
|
writeFileAtomic,
|
|
14
14
|
} from "./files.js";
|
|
15
15
|
import { changedFiles } from "./git.js";
|
|
@@ -56,9 +56,10 @@ General:
|
|
|
56
56
|
Paths default to the current directory. Directories are scanned recursively,
|
|
57
57
|
skipping node_modules and .git. Ignore globs without a slash match file names,
|
|
58
58
|
and a trailing slash (dist/) restricts a glob to directories. JavaScript files
|
|
59
|
-
(.js, .jsx, .mjs, .cjs) added with --ext are parsed
|
|
60
|
-
|
|
61
|
-
and
|
|
59
|
+
(.js, .jsx, .mjs, .cjs) added with --ext are parsed as JavaScript, and the
|
|
60
|
+
JSDoc comments tsc reads types from count as directives there. Removal keeps
|
|
61
|
+
directives and license headers unless explicitly requested, so builds and
|
|
62
|
+
linters keep working; --keep protects the markers only a project's own
|
|
62
63
|
tooling reads, e.g. --keep "@skipMangle" or --keep "^// INJECT".
|
|
63
64
|
|
|
64
65
|
--diff narrows any scan or removal to files changed in git: a single revision
|
|
@@ -69,11 +70,11 @@ cleaning up only the files a coding agent just touched.
|
|
|
69
70
|
Exit codes: 0 success, 1 comments reported with --fail-on-comment, 2 error.
|
|
70
71
|
|
|
71
72
|
Examples:
|
|
72
|
-
ts-comment-scanner src
|
|
73
|
-
ts-comment-scanner --format github --fail-on-comment src
|
|
74
|
-
ts-comment-scanner --ignore "**/*.test.ts" --skip-directives src
|
|
75
|
-
ts-comment-scanner --remove --dry-run
|
|
76
|
-
ts-comment-scanner --remove --diff main..HEAD
|
|
73
|
+
npx @kongyo2/ts-comment-scanner src
|
|
74
|
+
npx @kongyo2/ts-comment-scanner --format github --fail-on-comment src
|
|
75
|
+
npx @kongyo2/ts-comment-scanner --ignore "**/*.test.ts" --skip-directives src
|
|
76
|
+
npx @kongyo2/ts-comment-scanner --remove --dry-run --diff HEAD
|
|
77
|
+
npx @kongyo2/ts-comment-scanner --remove --diff main..HEAD
|
|
77
78
|
`;
|
|
78
79
|
|
|
79
80
|
export async function run(argv: string[], io: CliIO): Promise<number> {
|
|
@@ -216,7 +217,7 @@ async function runRemove(files: readonly string[], options: CliOptions, io: CliI
|
|
|
216
217
|
try {
|
|
217
218
|
const { text, encoding, bom, lossless } = await readFileText(file);
|
|
218
219
|
const result = removeComments(text, {
|
|
219
|
-
|
|
220
|
+
...scanOptionsFor(file),
|
|
220
221
|
removeDirectives: options.removeDirectives,
|
|
221
222
|
removeLegal: options.removeLegal,
|
|
222
223
|
keep: (comment) => options.keep.some((pattern) => pattern.test(comment.text)),
|
package/src/scanner.ts
CHANGED
|
@@ -8,6 +8,13 @@ import type { Comment, CommentKind } from "./types.js";
|
|
|
8
8
|
|
|
9
9
|
export interface ScanOptions {
|
|
10
10
|
jsx?: boolean;
|
|
11
|
+
/**
|
|
12
|
+
* The source is JavaScript. It is parsed the way tsc parses a `.js` file —
|
|
13
|
+
* with JSX, and with `a < b > (c)` a comparison, as JavaScript has no type
|
|
14
|
+
* arguments — and the JSDoc tags tsc takes its types from are directives
|
|
15
|
+
* (see DirectivePlacement.jsDoc).
|
|
16
|
+
*/
|
|
17
|
+
javascript?: boolean;
|
|
11
18
|
}
|
|
12
19
|
|
|
13
20
|
export function scanComments(source: string, options: ScanOptions = {}): Comment[] {
|
|
@@ -25,6 +32,28 @@ export interface SourceAnalysis {
|
|
|
25
32
|
jsx: JsxLayout;
|
|
26
33
|
/** What stands in front of each comment carrying an ast-grep suppression (see precedingNode). */
|
|
27
34
|
preceding: ReadonlyMap<Comment, PrecedingNode>;
|
|
35
|
+
/**
|
|
36
|
+
* In JavaScript, the tags tsc reads from each JSDoc comment it takes types
|
|
37
|
+
* from (see typeTags). The names are among the comment's directives; they
|
|
38
|
+
* are listed apart because a `@type` docblock is a directive wherever it
|
|
39
|
+
* stands, to prettier, and only where tsc attaches it to a node here.
|
|
40
|
+
*/
|
|
41
|
+
typed: ReadonlyMap<Comment, readonly string[]>;
|
|
42
|
+
/**
|
|
43
|
+
* In JavaScript, for each JSDoc comment whose tags tsc does not apply to
|
|
44
|
+
* their node because a later JSDoc comment belongs to the same node, that
|
|
45
|
+
* later comment: tsc takes a node's `@type`, `@param` and the like from
|
|
46
|
+
* its last JSDoc comment alone, so deleting that one would bring the
|
|
47
|
+
* earlier comment's tags to bear on the node.
|
|
48
|
+
*/
|
|
49
|
+
shadows: ReadonlyMap<Comment, Comment>;
|
|
50
|
+
/**
|
|
51
|
+
* The JSDoc comments prettier reads as type casts (`@type`, `@satisfies`)
|
|
52
|
+
* that a parenthesized expression follows, past any further comments.
|
|
53
|
+
* Prettier keeps the parentheses only while nothing but whitespace stands
|
|
54
|
+
* between the comment and them (see CAST_DIRECTIVES in shields.ts).
|
|
55
|
+
*/
|
|
56
|
+
casts: ReadonlySet<Comment>;
|
|
28
57
|
/**
|
|
29
58
|
* The gaps in front of the import and export declarations the import
|
|
30
59
|
* sorters group, and in front of the statements after the imports, where
|
|
@@ -34,9 +63,16 @@ export interface SourceAnalysis {
|
|
|
34
63
|
}
|
|
35
64
|
|
|
36
65
|
export function analyzeSource(source: string, options: ScanOptions = {}): SourceAnalysis {
|
|
37
|
-
const
|
|
38
|
-
|
|
39
|
-
|
|
66
|
+
const javascript = options.javascript === true;
|
|
67
|
+
// tsc reads JavaScript with JSX whatever the extension, and takes
|
|
68
|
+
// `f < a > (b)` for a comparison there, where TypeScript reads type
|
|
69
|
+
// arguments: parsed as TypeScript, a regular expression after such a `>`
|
|
70
|
+
// would be a division, and a `//` or `/*` inside it a comment.
|
|
71
|
+
const [fileName, scriptKind] = javascript
|
|
72
|
+
? ["module.js", ts.ScriptKind.JS]
|
|
73
|
+
: options.jsx === true
|
|
74
|
+
? ["module.tsx", ts.ScriptKind.TSX]
|
|
75
|
+
: ["module.ts", ts.ScriptKind.TS];
|
|
40
76
|
const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind);
|
|
41
77
|
|
|
42
78
|
const jsxTextSpans: Range[] = [];
|
|
@@ -53,6 +89,8 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
53
89
|
* block, so no two of them overlap.
|
|
54
90
|
*/
|
|
55
91
|
const emptyBlocks: Range[] = [];
|
|
92
|
+
/** The JSDoc comments of every node tsc attaches some to, in document order. */
|
|
93
|
+
const jsDocs: ts.JSDoc[][] = [];
|
|
56
94
|
|
|
57
95
|
const collect = (found: readonly ts.CommentRange[] | undefined): void => {
|
|
58
96
|
if (!found) return;
|
|
@@ -84,14 +122,24 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
84
122
|
// JSDoc nodes start inside the comment text itself; descending into them
|
|
85
123
|
// would hide the comment (e.g. a trailing JSDoc attached to the
|
|
86
124
|
// end-of-file token). Treat them as trivia like any other comment.
|
|
87
|
-
const children
|
|
125
|
+
const children: ts.Node[] = [];
|
|
126
|
+
const docs: ts.JSDoc[] = [];
|
|
127
|
+
for (const child of node.getChildren(sourceFile)) {
|
|
128
|
+
if (ts.isJSDoc(child)) docs.push(child);
|
|
129
|
+
else children.push(child);
|
|
130
|
+
}
|
|
131
|
+
if (docs.length > 0) jsDocs.push(docs);
|
|
88
132
|
if (children.length === 0) {
|
|
89
133
|
tokens.push(node);
|
|
90
134
|
if (node.kind === ts.SyntaxKind.JsxText) {
|
|
91
135
|
jsxTextSpans.push({ start: node.getFullStart(), end: node.getEnd() });
|
|
92
136
|
}
|
|
93
137
|
collect(ts.getLeadingCommentRanges(source, node.getFullStart()));
|
|
94
|
-
|
|
138
|
+
// A JSX closing tag opens with the one token `</`, which getChildren
|
|
139
|
+
// splits into `<` and `/` — and reads that slash as the start of a
|
|
140
|
+
// comment where another slash follows it (`<//* note */div>`). The
|
|
141
|
+
// comments after the token start past its slash.
|
|
142
|
+
collect(ts.getTrailingCommentRanges(source, opensClosingTag(node) ? node.end + 1 : node.getEnd()));
|
|
95
143
|
continue;
|
|
96
144
|
}
|
|
97
145
|
for (let index = children.length - 1; index >= 0; index -= 1) {
|
|
@@ -109,6 +157,7 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
109
157
|
// placement; a shebang does not count as content before the first comment,
|
|
110
158
|
// matching jest-docblock.
|
|
111
159
|
const firstTokenStart = sourceFile.getStart(sourceFile);
|
|
160
|
+
const tags = javascript ? typeTags(jsDocs) : NO_TYPE_TAGS;
|
|
112
161
|
const shebangEnd = ts.getShebang(source)?.length ?? 0;
|
|
113
162
|
const firstCommentPos = sorted.length > 0 ? (sorted[0] as ts.CommentRange).pos : -1;
|
|
114
163
|
const bunMarkerPos = bunMarkerOffset(source);
|
|
@@ -126,6 +175,7 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
126
175
|
let slots: ReturnType<typeof switchSlots> | undefined;
|
|
127
176
|
const slotsOf = (): ReturnType<typeof switchSlots> => (slots ??= switchSlots(tokenAfter(range.end)));
|
|
128
177
|
const firstComment = range.pos === firstCommentPos;
|
|
178
|
+
const jsDoc = tags.read.get(range.pos);
|
|
129
179
|
return {
|
|
130
180
|
header: range.pos < firstTokenStart,
|
|
131
181
|
firstComment: firstComment && /^\s*$/.test(source.slice(shebangEnd, range.pos)),
|
|
@@ -135,6 +185,7 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
135
185
|
fileWide: firstComment && isFileWidePosition(source, range.pos, range.end),
|
|
136
186
|
emptyBlock: rangeAt(emptyBlocks, range.pos) !== undefined,
|
|
137
187
|
emptyFile,
|
|
188
|
+
...(jsDoc === undefined ? {} : { jsDoc }),
|
|
138
189
|
get fallthroughSlot() {
|
|
139
190
|
return slotsOf().fallthroughSlot;
|
|
140
191
|
},
|
|
@@ -168,10 +219,23 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
168
219
|
});
|
|
169
220
|
|
|
170
221
|
const preceding = new Map<Comment, PrecedingNode>();
|
|
222
|
+
const typed = new Map<Comment, readonly string[]>();
|
|
223
|
+
const shadows = new Map<Comment, Comment>();
|
|
224
|
+
const casts = new Set<Comment>();
|
|
225
|
+
const commentAt = (offset: number): Comment =>
|
|
226
|
+
comments[firstIndexAtOrAfter(comments, offset, (comment) => comment.start)] as Comment;
|
|
171
227
|
for (const [index, comment] of comments.entries()) {
|
|
172
228
|
if (carriesAstGrepSuppression(comment.text)) {
|
|
173
229
|
preceding.set(comment, precedingNode(sourceFile, tokens, comments[index - 1], comment.start));
|
|
174
230
|
}
|
|
231
|
+
const read = tags.read.get(comment.start);
|
|
232
|
+
if (read !== undefined) typed.set(comment, read);
|
|
233
|
+
const shadow = tags.shadows.get(comment.start);
|
|
234
|
+
if (shadow !== undefined) shadows.set(comment, commentAt(shadow));
|
|
235
|
+
if (directives.get(comment)?.some((name) => CAST_TAGS.has(name)) === true) {
|
|
236
|
+
const next = tokenAfter(comment.end);
|
|
237
|
+
if (next.kind === ts.SyntaxKind.OpenParenToken && ts.isParenthesizedExpression(next.parent)) casts.add(comment);
|
|
238
|
+
}
|
|
175
239
|
}
|
|
176
240
|
|
|
177
241
|
return {
|
|
@@ -179,10 +243,101 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
|
|
|
179
243
|
directives,
|
|
180
244
|
jsx: jsxLayout(source, sourceFile, jsxParents, comments),
|
|
181
245
|
preceding,
|
|
246
|
+
typed,
|
|
247
|
+
shadows,
|
|
248
|
+
casts,
|
|
182
249
|
importGroups: importGroupGaps(source, sourceFile, comments),
|
|
183
250
|
};
|
|
184
251
|
}
|
|
185
252
|
|
|
253
|
+
/** Whether the token is the `<` that getChildren makes of the `</` opening a JSX closing tag. */
|
|
254
|
+
function opensClosingTag(token: ts.Node): boolean {
|
|
255
|
+
return (
|
|
256
|
+
token.kind === ts.SyntaxKind.LessThanToken &&
|
|
257
|
+
(ts.isJsxClosingElement(token.parent) || ts.isJsxClosingFragment(token.parent))
|
|
258
|
+
);
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
// The tags prettier's isTypeCastComment looks for (see the JSDoc type cast rule in directives.ts).
|
|
262
|
+
const CAST_TAGS: ReadonlySet<string> = new Set(["@type", "@satisfies"]);
|
|
263
|
+
|
|
264
|
+
// The JSDoc tags tsc reads types from in a JavaScript file, by the name a
|
|
265
|
+
// comment holding one is given. Aliases share a name: `@arg` and `@argument`
|
|
266
|
+
// are `@param`, `@return` is `@returns`, `@augments` is `@extends` and
|
|
267
|
+
// `@constructor` is `@class`. The tags tsc parses and reads nothing from
|
|
268
|
+
// (`@author`, `@deprecated`, `@see`, `@throws`) and the ones it does not know
|
|
269
|
+
// (`@example`, `@default`, ...) are absent: a comment holding only those is
|
|
270
|
+
// documentation.
|
|
271
|
+
const TYPE_TAGS: ReadonlyMap<ts.SyntaxKind, string> = new Map([
|
|
272
|
+
[ts.SyntaxKind.JSDocTypedefTag, "@typedef"],
|
|
273
|
+
[ts.SyntaxKind.JSDocCallbackTag, "@callback"],
|
|
274
|
+
[ts.SyntaxKind.JSDocEnumTag, "@enum"],
|
|
275
|
+
[ts.SyntaxKind.JSDocImportTag, "@import"],
|
|
276
|
+
[ts.SyntaxKind.JSDocOverloadTag, "@overload"],
|
|
277
|
+
[ts.SyntaxKind.JSDocTypeTag, "@type"],
|
|
278
|
+
[ts.SyntaxKind.JSDocSatisfiesTag, "@satisfies"],
|
|
279
|
+
[ts.SyntaxKind.JSDocParameterTag, "@param"],
|
|
280
|
+
[ts.SyntaxKind.JSDocReturnTag, "@returns"],
|
|
281
|
+
[ts.SyntaxKind.JSDocTemplateTag, "@template"],
|
|
282
|
+
[ts.SyntaxKind.JSDocThisTag, "@this"],
|
|
283
|
+
[ts.SyntaxKind.JSDocAugmentsTag, "@extends"],
|
|
284
|
+
[ts.SyntaxKind.JSDocImplementsTag, "@implements"],
|
|
285
|
+
[ts.SyntaxKind.JSDocClassTag, "@class"],
|
|
286
|
+
[ts.SyntaxKind.JSDocPublicTag, "@public"],
|
|
287
|
+
[ts.SyntaxKind.JSDocPrivateTag, "@private"],
|
|
288
|
+
[ts.SyntaxKind.JSDocProtectedTag, "@protected"],
|
|
289
|
+
[ts.SyntaxKind.JSDocReadonlyTag, "@readonly"],
|
|
290
|
+
[ts.SyntaxKind.JSDocOverrideTag, "@override"],
|
|
291
|
+
]);
|
|
292
|
+
|
|
293
|
+
// The tags that declare something of their own — a type, an import, a
|
|
294
|
+
// signature — which tsc binds from every JSDoc comment of a node. The other
|
|
295
|
+
// tags describe the node, and tsc applies those from the node's last JSDoc
|
|
296
|
+
// comment alone (`filterOwnedJSDocTags` in its utilities.ts), though it
|
|
297
|
+
// checks the types of every one, and counts what they refer to as used.
|
|
298
|
+
const DECLARING_TAGS: ReadonlySet<string> = new Set(["@typedef", "@callback", "@enum", "@import", "@overload"]);
|
|
299
|
+
|
|
300
|
+
/** The type tags of JSDoc comments, by the offset the comment starts at. */
|
|
301
|
+
interface TypeTags {
|
|
302
|
+
/** The names of the tags tsc reads from the comment (see TYPE_TAGS). */
|
|
303
|
+
read: ReadonlyMap<number, readonly string[]>;
|
|
304
|
+
/** For a comment holding tags a later one of its node keeps off the node, where that later comment starts. */
|
|
305
|
+
shadows: ReadonlyMap<number, number>;
|
|
306
|
+
}
|
|
307
|
+
|
|
308
|
+
const NO_TYPE_TAGS: TypeTags = { read: new Map(), shadows: new Map() };
|
|
309
|
+
|
|
310
|
+
/**
|
|
311
|
+
* What tsc reads from the JSDoc comments of a JavaScript file, given the
|
|
312
|
+
* comments of every node it attaches some to. A comment no node holds — one
|
|
313
|
+
* in front of a closing brace, or sharing the line of the token before it —
|
|
314
|
+
* is not among them, and tsc reads nothing from it.
|
|
315
|
+
*/
|
|
316
|
+
function typeTags(jsDocs: readonly (readonly ts.JSDoc[])[]): TypeTags {
|
|
317
|
+
const read = new Map<number, readonly string[]>();
|
|
318
|
+
const shadows = new Map<number, number>();
|
|
319
|
+
for (const docs of jsDocs) {
|
|
320
|
+
const last = docs.at(-1) as ts.JSDoc;
|
|
321
|
+
for (const doc of docs) {
|
|
322
|
+
const names = (doc.tags ?? []).flatMap((tag) => typeTagName(tag) ?? []);
|
|
323
|
+
if (names.length > 0) read.set(doc.pos, [...new Set(names)]);
|
|
324
|
+
if (doc !== last && names.some((name) => !DECLARING_TAGS.has(name))) shadows.set(doc.pos, last.pos);
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
return { read, shadows };
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* The name of the tag when tsc reads it. A `@returns` without a type says
|
|
332
|
+
* nothing. A `@param` without one still does: a function with any `@param`
|
|
333
|
+
* tag has the parameters it declares, each required unless its tag says
|
|
334
|
+
* otherwise, where one without takes any number of arguments.
|
|
335
|
+
*/
|
|
336
|
+
function typeTagName(tag: ts.JSDocTag): string | undefined {
|
|
337
|
+
if (ts.isJSDocReturnTag(tag) && tag.typeExpression === undefined) return undefined;
|
|
338
|
+
return TYPE_TAGS.get(tag.kind);
|
|
339
|
+
}
|
|
340
|
+
|
|
186
341
|
/**
|
|
187
342
|
* What stands in front of the comment at `offset` in tree-sitter's tree.
|
|
188
343
|
* tree-sitter puts a comment in the innermost node with code on both sides
|