@kongyo2/ts-comment-scanner 1.20.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 (78) hide show
  1. package/README.md +240 -52
  2. package/dist/args.d.ts.map +1 -1
  3. package/dist/args.js +23 -19
  4. package/dist/args.js.map +1 -1
  5. package/dist/astgrep.d.ts +5 -3
  6. package/dist/astgrep.d.ts.map +1 -1
  7. package/dist/astgrep.js +10 -12
  8. package/dist/astgrep.js.map +1 -1
  9. package/dist/containers.d.ts +48 -0
  10. package/dist/containers.d.ts.map +1 -0
  11. package/dist/containers.js +82 -0
  12. package/dist/containers.js.map +1 -0
  13. package/dist/coverage.d.ts +45 -0
  14. package/dist/coverage.d.ts.map +1 -0
  15. package/dist/coverage.js +92 -0
  16. package/dist/coverage.js.map +1 -0
  17. package/dist/directives.d.ts +21 -3
  18. package/dist/directives.d.ts.map +1 -1
  19. package/dist/directives.js +31 -23
  20. package/dist/directives.js.map +1 -1
  21. package/dist/files.d.ts +7 -3
  22. package/dist/files.d.ts.map +1 -1
  23. package/dist/files.js +129 -82
  24. package/dist/files.js.map +1 -1
  25. package/dist/imports.d.ts.map +1 -1
  26. package/dist/imports.js +14 -8
  27. package/dist/imports.js.map +1 -1
  28. package/dist/index.d.ts +1 -1
  29. package/dist/index.d.ts.map +1 -1
  30. package/dist/index.js +1 -1
  31. package/dist/index.js.map +1 -1
  32. package/dist/jsx.d.ts.map +1 -1
  33. package/dist/jsx.js +5 -6
  34. package/dist/jsx.js.map +1 -1
  35. package/dist/lines.d.ts +24 -5
  36. package/dist/lines.d.ts.map +1 -1
  37. package/dist/lines.js +50 -16
  38. package/dist/lines.js.map +1 -1
  39. package/dist/ranges.d.ts +8 -0
  40. package/dist/ranges.d.ts.map +1 -1
  41. package/dist/ranges.js +12 -0
  42. package/dist/ranges.js.map +1 -1
  43. package/dist/remove.d.ts +18 -14
  44. package/dist/remove.d.ts.map +1 -1
  45. package/dist/remove.js +69 -630
  46. package/dist/remove.js.map +1 -1
  47. package/dist/run.d.ts.map +1 -1
  48. package/dist/run.js +21 -28
  49. package/dist/run.js.map +1 -1
  50. package/dist/scanner.d.ts +34 -0
  51. package/dist/scanner.d.ts.map +1 -1
  52. package/dist/scanner.js +137 -31
  53. package/dist/scanner.js.map +1 -1
  54. package/dist/shields.d.ts +72 -0
  55. package/dist/shields.d.ts.map +1 -0
  56. package/dist/shields.js +624 -0
  57. package/dist/shields.js.map +1 -0
  58. package/dist/splice.d.ts +42 -11
  59. package/dist/splice.d.ts.map +1 -1
  60. package/dist/splice.js +189 -56
  61. package/dist/splice.js.map +1 -1
  62. package/package.json +2 -1
  63. package/src/args.ts +21 -21
  64. package/src/astgrep.ts +11 -13
  65. package/src/containers.ts +128 -0
  66. package/src/coverage.ts +110 -0
  67. package/src/directives.ts +38 -20
  68. package/src/files.ts +169 -91
  69. package/src/imports.ts +15 -8
  70. package/src/index.ts +1 -0
  71. package/src/jsx.ts +5 -6
  72. package/src/lines.ts +55 -14
  73. package/src/ranges.ts +17 -0
  74. package/src/remove.ts +82 -730
  75. package/src/run.ts +22 -34
  76. package/src/scanner.ts +180 -32
  77. package/src/shields.ts +701 -0
  78. package/src/splice.ts +224 -60
package/src/run.ts CHANGED
@@ -6,13 +6,11 @@ import {
6
6
  collectFiles,
7
7
  encodeFileText,
8
8
  foldPathCase,
9
- isJsxFile,
10
- mapLimit,
9
+ mapFiles,
11
10
  readFileText,
12
11
  scanFile,
12
+ scanOptionsFor,
13
13
  writeFileAtomic,
14
- FILE_CONCURRENCY,
15
- type CollectOptions,
16
14
  } from "./files.js";
17
15
  import { changedFiles } from "./git.js";
18
16
  import { removeComments, type RemoveResult } from "./remove.js";
@@ -58,9 +56,10 @@ General:
58
56
  Paths default to the current directory. Directories are scanned recursively,
59
57
  skipping node_modules and .git. Ignore globs without a slash match file names,
60
58
  and a trailing slash (dist/) restricts a glob to directories. JavaScript files
61
- (.js, .jsx, .mjs, .cjs) added with --ext are parsed with JSX enabled. Removal
62
- keeps directives and license headers unless explicitly requested, so builds
63
- 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
64
63
  tooling reads, e.g. --keep "@skipMangle" or --keep "^// INJECT".
65
64
 
66
65
  --diff narrows any scan or removal to files changed in git: a single revision
@@ -71,11 +70,11 @@ cleaning up only the files a coding agent just touched.
71
70
  Exit codes: 0 success, 1 comments reported with --fail-on-comment, 2 error.
72
71
 
73
72
  Examples:
74
- ts-comment-scanner src
75
- ts-comment-scanner --format github --fail-on-comment src
76
- ts-comment-scanner --ignore "**/*.test.ts" --skip-directives src
77
- ts-comment-scanner --remove --dry-run src
78
- 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
79
78
  `;
80
79
 
81
80
  export async function run(argv: string[], io: CliIO): Promise<number> {
@@ -96,30 +95,18 @@ export async function run(argv: string[], io: CliIO): Promise<number> {
96
95
  throw error;
97
96
  }
98
97
 
99
- // A -h/--help the early scan above could not see (e.g. consumed-looking
100
- // spots like `--ignore -- --help`) still means help once parsed as a flag.
101
- if (options.help) {
102
- io.out(HELP_TEXT);
103
- return 0;
104
- }
105
-
106
98
  try {
107
99
  if (options.version) {
108
100
  io.out(`${await getVersion()}\n`);
109
101
  return 0;
110
102
  }
111
103
 
112
- const collectOptions: CollectOptions = {
113
- ignore: options.ignore,
114
- ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
115
- };
116
-
104
+ const files = await collectTargets(options);
117
105
  if (options.remove) {
118
- return await runRemove(options, collectOptions, io);
106
+ return await runRemove(files, options, io);
119
107
  }
120
108
 
121
- const files = await collectTargets(options, collectOptions);
122
- const results = filterDirectives(await mapLimit(files, FILE_CONCURRENCY, scanFile), options.directives);
109
+ const results = filterDirectives(await mapFiles(files, scanFile), options.directives);
123
110
  io.out(`${render(results, options.format)}\n`);
124
111
 
125
112
  const total = results.reduce((sum, result) => sum + result.comments.length, 0);
@@ -141,8 +128,11 @@ function errorMessage(error: unknown): string {
141
128
  * (not the collected files, which could sit in a nested repository), so
142
129
  * scanning another repository's checkout works from anywhere.
143
130
  */
144
- async function collectTargets(options: CliOptions, collectOptions: CollectOptions): Promise<string[]> {
145
- const files = await collectFiles(options.paths, collectOptions);
131
+ async function collectTargets(options: CliOptions): Promise<string[]> {
132
+ const files = await collectFiles(options.paths, {
133
+ ignore: options.ignore,
134
+ ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
135
+ });
146
136
  if (options.diff === undefined) return files;
147
137
 
148
138
  const first = resolve(options.paths[0] as string);
@@ -222,14 +212,12 @@ interface FileRemoval extends Pick<RemoveResult, "removed" | "kept" | "skipped">
222
212
  file: string;
223
213
  }
224
214
 
225
- async function runRemove(options: CliOptions, collectOptions: CollectOptions, io: CliIO): Promise<number> {
226
- const files = await collectTargets(options, collectOptions);
227
-
228
- const outcomes = await mapLimit(files, FILE_CONCURRENCY, async (file) => {
215
+ async function runRemove(files: readonly string[], options: CliOptions, io: CliIO): Promise<number> {
216
+ const outcomes = await mapFiles(files, async (file) => {
229
217
  try {
230
218
  const { text, encoding, bom, lossless } = await readFileText(file);
231
219
  const result = removeComments(text, {
232
- jsx: isJsxFile(file),
220
+ ...scanOptionsFor(file),
233
221
  removeDirectives: options.removeDirectives,
234
222
  removeLegal: options.removeLegal,
235
223
  keep: (comment) => options.keep.some((pattern) => pattern.test(comment.text)),
package/src/scanner.ts CHANGED
@@ -1,13 +1,20 @@
1
1
  import ts from "typescript";
2
2
  import { isFileWidePosition, type PrecedingNode } from "./astgrep.js";
3
- import { bunMarkerOffset, carriesAstGrepSuppression, detectDirective, type DirectivePlacement } from "./directives.js";
3
+ import { bunMarkerOffset, carriesAstGrepSuppression, directiveNames, type DirectivePlacement } from "./directives.js";
4
4
  import { importGroupGaps, type ImportGroupGap } from "./imports.js";
5
5
  import { jsxLayout, type JsxLayout } from "./jsx.js";
6
- import { firstIndexAtOrAfter, rangeAt, type Range } from "./ranges.js";
6
+ import { byStart, firstIndexAtOrAfter, rangeAt, type Range } from "./ranges.js";
7
7
  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[] {
@@ -17,9 +24,36 @@ export function scanComments(source: string, options: ScanOptions = {}): Comment
17
24
  /** A source's comments together with the layout of its JSX children, from a single parse. */
18
25
  export interface SourceAnalysis {
19
26
  comments: Comment[];
27
+ /**
28
+ * Every directive each directive comment carries, its `directive` first
29
+ * (see directiveNames).
30
+ */
31
+ directives: ReadonlyMap<Comment, readonly string[]>;
20
32
  jsx: JsxLayout;
21
33
  /** What stands in front of each comment carrying an ast-grep suppression (see precedingNode). */
22
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>;
23
57
  /**
24
58
  * The gaps in front of the import and export declarations the import
25
59
  * sorters group, and in front of the statements after the imports, where
@@ -29,12 +63,19 @@ export interface SourceAnalysis {
29
63
  }
30
64
 
31
65
  export function analyzeSource(source: string, options: ScanOptions = {}): SourceAnalysis {
32
- const jsx = options.jsx === true;
33
- const fileName = jsx ? "module.tsx" : "module.ts";
34
- 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];
35
76
  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind);
36
77
 
37
- const jsxTextSpans: Array<[number, number]> = [];
78
+ const jsxTextSpans: Range[] = [];
38
79
  const jsxParents: Array<ts.JsxElement | ts.JsxFragment> = [];
39
80
  const ranges: ts.CommentRange[] = [];
40
81
  const seen = new Set<number>();
@@ -48,6 +89,8 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
48
89
  * block, so no two of them overlap.
49
90
  */
50
91
  const emptyBlocks: Range[] = [];
92
+ /** The JSDoc comments of every node tsc attaches some to, in document order. */
93
+ const jsDocs: ts.JSDoc[][] = [];
51
94
 
52
95
  const collect = (found: readonly ts.CommentRange[] | undefined): void => {
53
96
  if (!found) return;
@@ -79,14 +122,24 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
79
122
  // JSDoc nodes start inside the comment text itself; descending into them
80
123
  // would hide the comment (e.g. a trailing JSDoc attached to the
81
124
  // end-of-file token). Treat them as trivia like any other comment.
82
- 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);
83
132
  if (children.length === 0) {
84
133
  tokens.push(node);
85
134
  if (node.kind === ts.SyntaxKind.JsxText) {
86
- jsxTextSpans.push([node.getFullStart(), node.getEnd()]);
135
+ jsxTextSpans.push({ start: node.getFullStart(), end: node.getEnd() });
87
136
  }
88
137
  collect(ts.getLeadingCommentRanges(source, node.getFullStart()));
89
- 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()));
90
143
  continue;
91
144
  }
92
145
  for (let index = children.length - 1; index >= 0; index -= 1) {
@@ -94,33 +147,17 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
94
147
  }
95
148
  }
96
149
 
97
- // JsxText spans never overlap, so a position is inside one exactly when it
98
- // is inside the closest span starting at or before it — found by binary
99
- // search, keeping comment-dense TSX files out of quadratic time.
100
- jsxTextSpans.sort((a, b) => a[0] - b[0]);
101
- const insideJsxText = (pos: number): boolean => {
102
- let low = 0;
103
- let high = jsxTextSpans.length - 1;
104
- let candidate = -1;
105
- while (low <= high) {
106
- const middle = (low + high) >> 1;
107
- if ((jsxTextSpans[middle] as [number, number])[0] <= pos) {
108
- candidate = middle;
109
- low = middle + 1;
110
- } else {
111
- high = middle - 1;
112
- }
113
- }
114
- return candidate >= 0 && pos < (jsxTextSpans[candidate] as [number, number])[1];
115
- };
116
-
117
- const sorted = ranges.filter((range) => !insideJsxText(range.pos)).sort((a, b) => a.pos - b.pos);
150
+ // JsxText spans never overlap, so the one a position is inside is found by
151
+ // binary search, keeping comment-dense TSX files out of quadratic time.
152
+ jsxTextSpans.sort(byStart);
153
+ const sorted = ranges.filter((range) => rangeAt(jsxTextSpans, range.pos) === undefined).sort((a, b) => a.pos - b.pos);
118
154
 
119
155
  // Directive rules with positional requirements (header pragmas, prettier's
120
156
  // first-comment docblock, Bun's file-start marker) get the comment's actual
121
157
  // placement; a shebang does not count as content before the first comment,
122
158
  // matching jest-docblock.
123
159
  const firstTokenStart = sourceFile.getStart(sourceFile);
160
+ const tags = javascript ? typeTags(jsDocs) : NO_TYPE_TAGS;
124
161
  const shebangEnd = ts.getShebang(source)?.length ?? 0;
125
162
  const firstCommentPos = sorted.length > 0 ? (sorted[0] as ts.CommentRange).pos : -1;
126
163
  const bunMarkerPos = bunMarkerOffset(source);
@@ -138,6 +175,7 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
138
175
  let slots: ReturnType<typeof switchSlots> | undefined;
139
176
  const slotsOf = (): ReturnType<typeof switchSlots> => (slots ??= switchSlots(tokenAfter(range.end)));
140
177
  const firstComment = range.pos === firstCommentPos;
178
+ const jsDoc = tags.read.get(range.pos);
141
179
  return {
142
180
  header: range.pos < firstTokenStart,
143
181
  firstComment: firstComment && /^\s*$/.test(source.slice(shebangEnd, range.pos)),
@@ -147,6 +185,7 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
147
185
  fileWide: firstComment && isFileWidePosition(source, range.pos, range.end),
148
186
  emptyBlock: rangeAt(emptyBlocks, range.pos) !== undefined,
149
187
  emptyFile,
188
+ ...(jsDoc === undefined ? {} : { jsDoc }),
150
189
  get fallthroughSlot() {
151
190
  return slotsOf().fallthroughSlot;
152
191
  },
@@ -156,13 +195,15 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
156
195
  };
157
196
  };
158
197
 
198
+ const directives = new Map<Comment, readonly string[]>();
159
199
  const comments = sorted.map((range): Comment => {
160
200
  const kind: CommentKind = range.kind === ts.SyntaxKind.SingleLineCommentTrivia ? "line" : "block";
161
201
  const text = source.slice(range.pos, range.end);
162
202
  const startPosition = sourceFile.getLineAndCharacterOfPosition(range.pos);
163
203
  const endPosition = sourceFile.getLineAndCharacterOfPosition(range.end);
164
- const directive = detectDirective(kind, text, placementOf(range));
165
- return {
204
+ const names = directiveNames(kind, text, placementOf(range));
205
+ const directive = names[0];
206
+ const comment: Comment = {
166
207
  kind,
167
208
  text,
168
209
  start: range.pos,
@@ -173,23 +214,130 @@ export function analyzeSource(source: string, options: ScanOptions = {}): Source
173
214
  endColumn: endPosition.character + 1,
174
215
  ...(directive === undefined ? {} : { directive }),
175
216
  };
217
+ if (directive !== undefined) directives.set(comment, names);
218
+ return comment;
176
219
  });
177
220
 
178
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;
179
227
  for (const [index, comment] of comments.entries()) {
180
228
  if (carriesAstGrepSuppression(comment.text)) {
181
229
  preceding.set(comment, precedingNode(sourceFile, tokens, comments[index - 1], comment.start));
182
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
+ }
183
239
  }
184
240
 
185
241
  return {
186
242
  comments,
243
+ directives,
187
244
  jsx: jsxLayout(source, sourceFile, jsxParents, comments),
188
245
  preceding,
246
+ typed,
247
+ shadows,
248
+ casts,
189
249
  importGroups: importGroupGaps(source, sourceFile, comments),
190
250
  };
191
251
  }
192
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
+
193
341
  /**
194
342
  * What stands in front of the comment at `offset` in tree-sitter's tree.
195
343
  * tree-sitter puts a comment in the innermost node with code on both sides