@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.
- package/README.md +240 -52
- package/dist/args.d.ts.map +1 -1
- package/dist/args.js +23 -19
- package/dist/args.js.map +1 -1
- package/dist/astgrep.d.ts +5 -3
- package/dist/astgrep.d.ts.map +1 -1
- package/dist/astgrep.js +10 -12
- 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 +21 -3
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +31 -23
- package/dist/directives.js.map +1 -1
- package/dist/files.d.ts +7 -3
- package/dist/files.d.ts.map +1 -1
- package/dist/files.js +129 -82
- package/dist/files.js.map +1 -1
- package/dist/imports.d.ts.map +1 -1
- package/dist/imports.js +14 -8
- 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/jsx.d.ts.map +1 -1
- package/dist/jsx.js +5 -6
- package/dist/jsx.js.map +1 -1
- package/dist/lines.d.ts +24 -5
- package/dist/lines.d.ts.map +1 -1
- package/dist/lines.js +50 -16
- package/dist/lines.js.map +1 -1
- package/dist/ranges.d.ts +8 -0
- package/dist/ranges.d.ts.map +1 -1
- package/dist/ranges.js +12 -0
- package/dist/ranges.js.map +1 -1
- package/dist/remove.d.ts +18 -14
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +69 -630
- package/dist/remove.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +21 -28
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts +34 -0
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +137 -31
- package/dist/scanner.js.map +1 -1
- package/dist/shields.d.ts +72 -0
- package/dist/shields.d.ts.map +1 -0
- package/dist/shields.js +624 -0
- package/dist/shields.js.map +1 -0
- package/dist/splice.d.ts +42 -11
- package/dist/splice.d.ts.map +1 -1
- package/dist/splice.js +189 -56
- package/dist/splice.js.map +1 -1
- package/package.json +2 -1
- package/src/args.ts +21 -21
- package/src/astgrep.ts +11 -13
- package/src/containers.ts +128 -0
- package/src/coverage.ts +110 -0
- package/src/directives.ts +38 -20
- package/src/files.ts +169 -91
- package/src/imports.ts +15 -8
- package/src/index.ts +1 -0
- package/src/jsx.ts +5 -6
- package/src/lines.ts +55 -14
- package/src/ranges.ts +17 -0
- package/src/remove.ts +82 -730
- package/src/run.ts +22 -34
- package/src/scanner.ts +180 -32
- package/src/shields.ts +701 -0
- 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
|
-
|
|
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
|
|
62
|
-
|
|
63
|
-
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
|
|
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
|
|
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
|
|
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(
|
|
106
|
+
return await runRemove(files, options, io);
|
|
119
107
|
}
|
|
120
108
|
|
|
121
|
-
const
|
|
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
|
|
145
|
-
const files = await collectFiles(options.paths,
|
|
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(
|
|
226
|
-
const
|
|
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
|
-
|
|
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,
|
|
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
|
|
33
|
-
|
|
34
|
-
|
|
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:
|
|
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
|
|
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(
|
|
135
|
+
jsxTextSpans.push({ start: node.getFullStart(), end: node.getEnd() });
|
|
87
136
|
}
|
|
88
137
|
collect(ts.getLeadingCommentRanges(source, node.getFullStart()));
|
|
89
|
-
|
|
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
|
|
98
|
-
//
|
|
99
|
-
|
|
100
|
-
jsxTextSpans.sort((a, b) => a
|
|
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
|
|
165
|
-
|
|
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
|