@kongyo2/ts-comment-scanner 1.9.0 → 1.10.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/src/scanner.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import ts from "typescript";
2
2
  import { bunMarkerOffset, detectDirective, type DirectivePlacement } from "./directives.js";
3
+ import { jsxLayout, type JsxLayout } from "./jsx.js";
3
4
  import type { Comment, CommentKind } from "./types.js";
4
5
 
5
6
  export interface ScanOptions {
@@ -7,12 +8,23 @@ export interface ScanOptions {
7
8
  }
8
9
 
9
10
  export function scanComments(source: string, options: ScanOptions = {}): Comment[] {
11
+ return analyzeSource(source, options).comments;
12
+ }
13
+
14
+ /** A source's comments together with the layout of its JSX children, from a single parse. */
15
+ export interface SourceAnalysis {
16
+ comments: Comment[];
17
+ jsx: JsxLayout;
18
+ }
19
+
20
+ export function analyzeSource(source: string, options: ScanOptions = {}): SourceAnalysis {
10
21
  const jsx = options.jsx === true;
11
22
  const fileName = jsx ? "module.tsx" : "module.ts";
12
23
  const scriptKind = jsx ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
13
24
  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind);
14
25
 
15
26
  const jsxTextSpans: Array<[number, number]> = [];
27
+ const jsxParents: Array<ts.JsxElement | ts.JsxFragment> = [];
16
28
  const ranges: ts.CommentRange[] = [];
17
29
  const seen = new Set<number>();
18
30
 
@@ -31,6 +43,7 @@ export function scanComments(source: string, options: ScanOptions = {}): Comment
31
43
  const pending: ts.Node[] = [sourceFile];
32
44
  while (pending.length > 0) {
33
45
  const node = pending.pop() as ts.Node;
46
+ if (ts.isJsxElement(node) || ts.isJsxFragment(node)) jsxParents.push(node);
34
47
  // JSDoc nodes start inside the comment text itself; descending into them
35
48
  // would hide the comment (e.g. a trailing JSDoc attached to the
36
49
  // end-of-file token). Treat them as trivia like any other comment.
@@ -96,7 +109,7 @@ export function scanComments(source: string, options: ScanOptions = {}): Comment
96
109
  nextToken: nextTokens[index] as string,
97
110
  });
98
111
 
99
- return sorted.map((range, index) => {
112
+ const comments = sorted.map((range, index): Comment => {
100
113
  const kind: CommentKind = range.kind === ts.SyntaxKind.SingleLineCommentTrivia ? "line" : "block";
101
114
  const text = source.slice(range.pos, range.end);
102
115
  const startPosition = sourceFile.getLineAndCharacterOfPosition(range.pos);
@@ -114,4 +127,6 @@ export function scanComments(source: string, options: ScanOptions = {}): Comment
114
127
  ...(directive === undefined ? {} : { directive }),
115
128
  };
116
129
  });
130
+
131
+ return { comments, jsx: jsxLayout(source, sourceFile, jsxParents, comments) };
117
132
  }
package/src/splice.ts ADDED
@@ -0,0 +1,317 @@
1
+ import { LINE_BREAK, LINE_TERMINATOR, isBlank, lineStartOffsets } from "./lines.js";
2
+ import { firstIndexAtOrAfter, rangeAt, type Range } from "./ranges.js";
3
+
4
+ /** One change to the source: a range to delete (tidying its line) or to replace verbatim. */
5
+ export interface Edit extends Range {
6
+ /** Text put in place of the range as is; without it the range is deleted and its line tidied. */
7
+ replacement?: string;
8
+ /**
9
+ * The range is a JSX expression container. Nothing is ever inserted in
10
+ * its place — not even a space to keep its neighbours apart — because
11
+ * those neighbours are JSX text and tags, not tokens.
12
+ */
13
+ jsx?: boolean;
14
+ }
15
+
16
+ const isHorizontalSpace = (char: string | undefined): boolean => char === " " || char === "\t";
17
+
18
+ // Brackets never merge with what follows them, nor punctuation with what
19
+ // precedes it, so removing a comment between them needs no space to keep
20
+ // the tokens apart, and the whitespace that only held the comment off them
21
+ // can go: `f(/* a *​/ x)` becomes `f(x)` and `{/* empty *​/}` becomes `{}`.
22
+ const OPENING_BRACKETS = "([{";
23
+ const CLOSING_PUNCTUATION = ")]},;";
24
+
25
+ /** Whether `before` and `after`, about to meet where a comment was, need a space between them. */
26
+ function needsSpace(before: string, after: string): boolean {
27
+ return !OPENING_BRACKETS.includes(before) && !CLOSING_PUNCTUATION.includes(after);
28
+ }
29
+
30
+ // A global copy of the line-break matcher, so exec() can resume from a removal's end offset.
31
+ const NEXT_LINE_BREAK = new RegExp(LINE_BREAK.source, "g");
32
+
33
+ /** End offset (exclusive) of the last line break in the chunk, or -1 when it has none. */
34
+ function lastLineBreakEnd(chunk: string): number {
35
+ for (let index = chunk.length - 1; index >= 0; index -= 1) {
36
+ if (LINE_TERMINATOR.test(chunk[index] as string)) return index + 1;
37
+ }
38
+ return -1;
39
+ }
40
+
41
+ /**
42
+ * Applies sorted, non-overlapping edits to the source, tidying the lines of
43
+ * deleted ranges. Output is accumulated as segments with incremental
44
+ * line-state tracking, so the work stays linear in the source size even for
45
+ * comment-dense files.
46
+ */
47
+ export function applyEdits(source: string, edits: readonly Edit[]): string {
48
+ const segments: string[] = [];
49
+ let cursor = 0;
50
+ /** Whether the output's current (unterminated) line is all whitespace so far. */
51
+ let lineIsBlank = true;
52
+ /** Last character of the output so far ("" while empty). */
53
+ let lastChar = "";
54
+
55
+ const push = (chunk: string): void => {
56
+ if (chunk === "") return;
57
+ segments.push(chunk);
58
+ const breakEnd = lastLineBreakEnd(chunk);
59
+ lineIsBlank = breakEnd === -1 ? lineIsBlank && isBlank(chunk) : isBlank(chunk.slice(breakEnd));
60
+ lastChar = chunk.slice(-1);
61
+ };
62
+
63
+ /** Deletes everything the output holds after its last line break. */
64
+ const dropCurrentLine = (): void => {
65
+ while (segments.length > 0) {
66
+ const last = segments[segments.length - 1] as string;
67
+ const breakEnd = lastLineBreakEnd(last);
68
+ if (breakEnd === -1) {
69
+ segments.pop();
70
+ continue;
71
+ }
72
+ segments[segments.length - 1] = last.slice(0, breakEnd);
73
+ lineIsBlank = true;
74
+ lastChar = last.charAt(breakEnd - 1);
75
+ return;
76
+ }
77
+ lineIsBlank = true;
78
+ lastChar = "";
79
+ };
80
+
81
+ /**
82
+ * Deletes trailing spaces/tabs of the output's current line. Only called
83
+ * while that line holds code, which the trimming stops at.
84
+ */
85
+ const trimLineEnd = (): void => {
86
+ for (;;) {
87
+ const last = segments[segments.length - 1] as string;
88
+ let end = last.length;
89
+ while (end > 0 && isHorizontalSpace(last[end - 1])) end -= 1;
90
+ if (end > 0) {
91
+ segments[segments.length - 1] = last.slice(0, end);
92
+ lastChar = last.charAt(end - 1);
93
+ return;
94
+ }
95
+ segments.pop();
96
+ }
97
+ };
98
+
99
+ /** Offset of the first character at or after `from` that is not a space or tab. */
100
+ const skipSpaces = (from: number): number => {
101
+ let index = from;
102
+ while (isHorizontalSpace(source[index])) index += 1;
103
+ return index;
104
+ };
105
+
106
+ for (const edit of edits) {
107
+ push(source.slice(cursor, edit.start));
108
+ cursor = edit.end;
109
+ if (edit.replacement !== undefined) {
110
+ push(edit.replacement);
111
+ continue;
112
+ }
113
+
114
+ NEXT_LINE_BREAK.lastIndex = cursor;
115
+ const lineBreak = NEXT_LINE_BREAK.exec(source);
116
+ const contentEnd = lineBreak === null ? source.length : lineBreak.index;
117
+ const lineEnd = lineBreak === null ? source.length : lineBreak.index + lineBreak[0].length;
118
+ const restContent = source.slice(cursor, contentEnd);
119
+ const deleted = source.slice(edit.start, edit.end);
120
+
121
+ if (lineIsBlank && isBlank(restContent)) {
122
+ // The range occupied whole line(s): drop them entirely.
123
+ dropCurrentLine();
124
+ cursor = lineEnd;
125
+ } else if (isBlank(restContent)) {
126
+ // Trailing after code: trim the gap, keep the line break.
127
+ trimLineEnd();
128
+ push(source.slice(contentEnd, lineEnd));
129
+ cursor = lineEnd;
130
+ } else if (!lineIsBlank && LINE_TERMINATOR.test(deleted) && needsSpace(lastChar, source.charAt(cursor))) {
131
+ // Code on both sides of a range that spans lines. Per ECMA-262 a
132
+ // multi-line comment acts as a line terminator for semicolon
133
+ // insertion, so a real line break (matching the file's style) takes
134
+ // its place instead of merging the lines. (Right after an opening
135
+ // bracket or before closing punctuation a line terminator changes
136
+ // nothing, so a multi-line comment there goes without one.)
137
+ trimLineEnd();
138
+ push(deleted.includes("\r\n") ? "\r\n" : "\n");
139
+ } else if (lastChar !== "" && !isBlank(lastChar)) {
140
+ // Code right before the range, more on the same line after it.
141
+ if (edit.jsx === true) continue;
142
+ const next = source.charAt(cursor);
143
+ if (!isBlank(next)) {
144
+ // `a/* x *​/b` would merge tokens: keep them apart.
145
+ if (needsSpace(lastChar, next)) push(" ");
146
+ } else if (OPENING_BRACKETS.includes(lastChar)) {
147
+ // `(/* x *​/ a` — the space only held the comment off the code.
148
+ cursor = skipSpaces(cursor);
149
+ }
150
+ } else {
151
+ // Whitespace (or the line start) right before the range: the
152
+ // whitespace after it collapses into that.
153
+ cursor = skipSpaces(cursor);
154
+ if (edit.jsx !== true && !lineIsBlank && CLOSING_PUNCTUATION.includes(source.charAt(cursor))) {
155
+ // `a /* x *​/)` — the space before only held the comment off the code.
156
+ trimLineEnd();
157
+ }
158
+ }
159
+ }
160
+
161
+ segments.push(source.slice(cursor));
162
+ return segments.join("");
163
+ }
164
+
165
+ /** Where blocks open and close besides brackets: JSX tags, whose children are laid out like a block's. */
166
+ export interface BlockTags {
167
+ /** Offsets just past every opening tag. */
168
+ openingTagEnds: ReadonlySet<number>;
169
+ /** Offsets of every closing tag. */
170
+ closingTagStarts: ReadonlySet<number>;
171
+ }
172
+
173
+ type LineKind = "vanishing" | "blank" | "code";
174
+
175
+ /**
176
+ * Deletions of the blank lines that removing whole comment lines would pile
177
+ * up. Where comment-only lines vanish, the blank lines around them close
178
+ * ranks: two paragraphs that a comment stood between, each separated from it
179
+ * by a blank line, end up separated by two. Every run of blank and vanishing
180
+ * lines is therefore trimmed to as many blank lines as the widest gap it
181
+ * held — never more than the source had in one place, never fewer than it
182
+ * had on either side — except at the start or end of the file, or of a
183
+ * block (an opening bracket ending the line before, a closing one starting
184
+ * the line after, or JSX tags), where only the blank lines that already sat
185
+ * against that edge stay: the ones on the far side of the comment merely
186
+ * separated the comment from the code.
187
+ *
188
+ * `deletions` are the ranges about to be deleted, sorted; a line vanishes
189
+ * when every non-whitespace character on it is deleted. Blank lines hold
190
+ * nothing but spaces and tabs (a lone vertical tab or no-break space is
191
+ * content to tsc 7) and lie outside every comment. `shieldedLines` are
192
+ * lines a surviving next-line directive reaches (1-based): the blank lines
193
+ * among them stay, so no code moves into the directive's reach.
194
+ */
195
+ export function blankLineEdits(
196
+ source: string,
197
+ deletions: readonly Range[],
198
+ comments: readonly Range[],
199
+ shieldedLines: ReadonlySet<number>,
200
+ tags: BlockTags,
201
+ ): Edit[] {
202
+ const offsets = lineStartOffsets(source);
203
+ // A final line break ends the last line rather than opening an empty one.
204
+ const lineCount =
205
+ offsets.length > 1 && offsets[offsets.length - 1] === source.length ? offsets.length - 1 : offsets.length;
206
+ const lineStart = (line: number): number => offsets[line] as number;
207
+ const lineContentEnd = (line: number): number =>
208
+ endOfContent(source, lineStart(line), offsets[line + 1] ?? source.length);
209
+
210
+ const kinds: LineKind[] = [];
211
+ for (let line = 0; line < lineCount; line += 1) {
212
+ kinds.push(
213
+ lineKind(source, lineStart(line), offsets[line + 1] ?? source.length, lineContentEnd(line), deletions, comments),
214
+ );
215
+ }
216
+
217
+ /** Offset of the first (or last) character on the line that survives the deletions and is not whitespace. */
218
+ const survivingEdge = (line: number, fromEnd: boolean): number | undefined => {
219
+ const start = lineStart(line);
220
+ const end = lineContentEnd(line);
221
+ for (let step = 0; step < end - start; step += 1) {
222
+ const index = fromEnd ? end - 1 - step : start + step;
223
+ if (!isBlank(source[index] as string) && rangeAt(deletions, index) === undefined) return index;
224
+ }
225
+ return undefined;
226
+ };
227
+ const opensBlock = (line: number): boolean => {
228
+ const index = survivingEdge(line, true);
229
+ return (
230
+ index !== undefined &&
231
+ rangeAt(comments, index) === undefined &&
232
+ (OPENING_BRACKETS.includes(source[index] as string) || tags.openingTagEnds.has(index + 1))
233
+ );
234
+ };
235
+ // (A line's first surviving character is never inside a comment unless it
236
+ // is the comment's opening slash, so no comment check is needed here.)
237
+ const closesBlock = (line: number): boolean => {
238
+ const index = survivingEdge(line, false);
239
+ return index !== undefined && (")]}".includes(source[index] as string) || tags.closingTagStarts.has(index));
240
+ };
241
+
242
+ const edits: Edit[] = [];
243
+ let line = 0;
244
+ while (line < lineCount) {
245
+ if (kinds[line] === "code") {
246
+ line += 1;
247
+ continue;
248
+ }
249
+ const first = line;
250
+ const blanks: number[] = [];
251
+ // Blank lines between consecutive vanishing lines, from before the first to after the last.
252
+ const gaps = [0];
253
+ for (; line < lineCount && kinds[line] !== "code"; line += 1) {
254
+ if (kinds[line] === "vanishing") {
255
+ gaps.push(0);
256
+ } else {
257
+ blanks.push(line);
258
+ gaps[gaps.length - 1] = (gaps[gaps.length - 1] as number) + 1;
259
+ }
260
+ }
261
+ if (gaps.length === 1) continue;
262
+
263
+ const leading = gaps[0] as number;
264
+ const trailing = gaps[gaps.length - 1] as number;
265
+ const atStart = first === 0;
266
+ const atEnd = line === lineCount;
267
+ let keep: number;
268
+ if (atStart || atEnd) {
269
+ keep = atEnd ? (atStart ? 0 : trailing) : leading;
270
+ } else {
271
+ const opens = opensBlock(first - 1);
272
+ const closes = closesBlock(line);
273
+ if (opens && closes) keep = Math.min(leading, trailing);
274
+ else if (opens) keep = leading;
275
+ else if (closes) keep = trailing;
276
+ else keep = gaps.reduce((widest, gap) => Math.max(widest, gap));
277
+ }
278
+ for (const [position, blank] of blanks.entries()) {
279
+ if (shieldedLines.has(blank + 1)) keep = Math.max(keep, position + 1);
280
+ }
281
+ for (const blank of blanks.slice(keep)) {
282
+ edits.push({ start: lineStart(blank), end: lineContentEnd(blank) });
283
+ }
284
+ }
285
+ return edits;
286
+ }
287
+
288
+ /** Offset where the line's content ends, before its line break (CRLF counts as one). */
289
+ function endOfContent(source: string, start: number, end: number): number {
290
+ if (end - start >= 2 && source[end - 2] === "\r" && source[end - 1] === "\n") return end - 2;
291
+ if (end > start && LINE_TERMINATOR.test(source[end - 1] as string)) return end - 1;
292
+ return end;
293
+ }
294
+
295
+ function lineKind(
296
+ source: string,
297
+ start: number,
298
+ end: number,
299
+ contentEnd: number,
300
+ deletions: readonly Range[],
301
+ comments: readonly Range[],
302
+ ): LineKind {
303
+ // Sorted, non-overlapping ranges end in ascending order too, so the first
304
+ // one ending past the line start is the only candidate for touching it.
305
+ const touches = (ranges: readonly Range[]): boolean => {
306
+ const range = ranges[firstIndexAtOrAfter(ranges, start + 1, (candidate) => candidate.end)];
307
+ return range !== undefined && range.start < end;
308
+ };
309
+ if (touches(deletions)) {
310
+ let covered = true;
311
+ for (let index = start; index < contentEnd && covered; index += 1) {
312
+ covered = isBlank(source[index] as string) || rangeAt(deletions, index) !== undefined;
313
+ }
314
+ if (covered) return "vanishing";
315
+ }
316
+ return /^[ \t]*$/.test(source.slice(start, contentEnd)) && !touches(comments) ? "blank" : "code";
317
+ }