@kongyo2/ts-comment-scanner 1.21.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 (61) hide show
  1. package/README.md +240 -52
  2. package/dist/astgrep.d.ts +4 -2
  3. package/dist/astgrep.d.ts.map +1 -1
  4. package/dist/astgrep.js +7 -4
  5. package/dist/astgrep.js.map +1 -1
  6. package/dist/containers.d.ts +48 -0
  7. package/dist/containers.d.ts.map +1 -0
  8. package/dist/containers.js +82 -0
  9. package/dist/containers.js.map +1 -0
  10. package/dist/coverage.d.ts +45 -0
  11. package/dist/coverage.d.ts.map +1 -0
  12. package/dist/coverage.js +92 -0
  13. package/dist/coverage.js.map +1 -0
  14. package/dist/directives.d.ts +13 -3
  15. package/dist/directives.d.ts.map +1 -1
  16. package/dist/directives.js +6 -5
  17. package/dist/directives.js.map +1 -1
  18. package/dist/files.d.ts +5 -0
  19. package/dist/files.d.ts.map +1 -1
  20. package/dist/files.js +103 -41
  21. package/dist/files.js.map +1 -1
  22. package/dist/index.d.ts +1 -1
  23. package/dist/index.d.ts.map +1 -1
  24. package/dist/index.js +1 -1
  25. package/dist/index.js.map +1 -1
  26. package/dist/lines.d.ts +11 -0
  27. package/dist/lines.d.ts.map +1 -1
  28. package/dist/lines.js +30 -0
  29. package/dist/lines.js.map +1 -1
  30. package/dist/remove.d.ts +16 -12
  31. package/dist/remove.d.ts.map +1 -1
  32. package/dist/remove.js +51 -638
  33. package/dist/remove.js.map +1 -1
  34. package/dist/run.d.ts.map +1 -1
  35. package/dist/run.js +11 -10
  36. package/dist/run.js.map +1 -1
  37. package/dist/scanner.d.ts +29 -0
  38. package/dist/scanner.d.ts.map +1 -1
  39. package/dist/scanner.js +122 -5
  40. package/dist/scanner.js.map +1 -1
  41. package/dist/shields.d.ts +72 -0
  42. package/dist/shields.d.ts.map +1 -0
  43. package/dist/shields.js +624 -0
  44. package/dist/shields.js.map +1 -0
  45. package/dist/splice.d.ts +40 -15
  46. package/dist/splice.d.ts.map +1 -1
  47. package/dist/splice.js +185 -69
  48. package/dist/splice.js.map +1 -1
  49. package/package.json +2 -1
  50. package/src/astgrep.ts +7 -5
  51. package/src/containers.ts +128 -0
  52. package/src/coverage.ts +110 -0
  53. package/src/directives.ts +16 -5
  54. package/src/files.ts +147 -53
  55. package/src/index.ts +1 -0
  56. package/src/lines.ts +33 -1
  57. package/src/remove.ts +58 -748
  58. package/src/run.ts +11 -10
  59. package/src/scanner.ts +160 -5
  60. package/src/shields.ts +701 -0
  61. 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 with JSX enabled. Removal
60
- keeps directives and license headers unless explicitly requested, so builds
61
- and linters keep working; --keep protects the markers only a project's own
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 src
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
- jsx: isJsxFile(file),
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 jsx = options.jsx === true;
38
- const fileName = jsx ? "module.tsx" : "module.ts";
39
- const scriptKind = jsx ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
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 = node.getChildren(sourceFile).filter((child) => !ts.isJSDoc(child));
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
- collect(ts.getTrailingCommentRanges(source, node.getEnd()));
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