@kongyo2/ts-comment-scanner 1.3.0 → 1.5.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.en.md +23 -8
- package/README.md +21 -6
- package/dist/directives.d.ts +31 -1
- package/dist/directives.d.ts.map +1 -1
- package/dist/directives.js +127 -34
- package/dist/directives.js.map +1 -1
- package/dist/files.d.ts +43 -1
- package/dist/files.d.ts.map +1 -1
- package/dist/files.js +215 -26
- package/dist/files.js.map +1 -1
- package/dist/git.js +6 -6
- package/dist/git.js.map +1 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/remove.d.ts +11 -2
- package/dist/remove.d.ts.map +1 -1
- package/dist/remove.js +226 -45
- package/dist/remove.js.map +1 -1
- package/dist/report.d.ts.map +1 -1
- package/dist/report.js +24 -2
- package/dist/report.js.map +1 -1
- package/dist/run.d.ts.map +1 -1
- package/dist/run.js +86 -16
- package/dist/run.js.map +1 -1
- package/dist/scanner.d.ts.map +1 -1
- package/dist/scanner.js +43 -43
- package/dist/scanner.js.map +1 -1
- package/package.json +11 -5
- package/src/args.ts +198 -0
- package/src/cli.ts +12 -0
- package/src/directives.ts +516 -0
- package/src/files.ts +370 -0
- package/src/git.ts +72 -0
- package/src/index.ts +19 -0
- package/src/remove.ts +515 -0
- package/src/report.ts +106 -0
- package/src/run.ts +317 -0
- package/src/scanner.ts +104 -0
- package/src/types.ts +19 -0
- package/src/version.ts +7 -0
package/src/remove.ts
ADDED
|
@@ -0,0 +1,515 @@
|
|
|
1
|
+
import { activePositionalDirectives, isLegalComment, type DirectivePlacement } from "./directives.js";
|
|
2
|
+
import { scanComments } from "./scanner.js";
|
|
3
|
+
import type { Comment } from "./types.js";
|
|
4
|
+
|
|
5
|
+
export interface RemoveOptions {
|
|
6
|
+
jsx?: boolean;
|
|
7
|
+
/** Also remove compiler/linter directive comments. Default: false (kept for safety). */
|
|
8
|
+
removeDirectives?: boolean;
|
|
9
|
+
/** Also remove license/legal comments. Default: false (kept for safety). */
|
|
10
|
+
removeLegal?: boolean;
|
|
11
|
+
/** Extra predicate: return false to leave a comment out of the removal entirely. */
|
|
12
|
+
shouldRemove?: (comment: Comment) => boolean;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface RemoveResult {
|
|
16
|
+
/** Source with the removed comments spliced out. */
|
|
17
|
+
code: string;
|
|
18
|
+
removed: Comment[];
|
|
19
|
+
/**
|
|
20
|
+
* Comments kept because they are protected: directives, license headers,
|
|
21
|
+
* comments whose removal would shift code under a next-line directive, and
|
|
22
|
+
* comments whose removal would move a position-dependent directive
|
|
23
|
+
* (prettier's first-comment pragma, Bun's file-start marker) into effect.
|
|
24
|
+
*/
|
|
25
|
+
kept: Comment[];
|
|
26
|
+
/** Comments excluded from removal by the `shouldRemove` predicate. */
|
|
27
|
+
skipped: Comment[];
|
|
28
|
+
changed: boolean;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Removes comments from TypeScript source without touching code.
|
|
33
|
+
*
|
|
34
|
+
* Safety properties:
|
|
35
|
+
* - AST-based ranges: strings, template literals and regexes are never affected.
|
|
36
|
+
* - Directives (`@ts-expect-error`, `eslint-disable`, ...) and license headers are
|
|
37
|
+
* kept by default, since deleting them changes build/lint behaviour.
|
|
38
|
+
* - Surviving comments keep their directive semantics: when deleting a leading
|
|
39
|
+
* comment would newly activate a position-dependent directive in a kept
|
|
40
|
+
* comment (prettier's `@format` docblock pragma counts only as the file's
|
|
41
|
+
* first comment, Bun's `// @bun` only at the very start), the leading
|
|
42
|
+
* comment is kept instead.
|
|
43
|
+
* - A space is inserted where removing a block comment would merge two tokens,
|
|
44
|
+
* and a line break is kept where the comment acted as one (ASI stays intact).
|
|
45
|
+
* - A leading byte-order mark is preserved. Reported positions index into the
|
|
46
|
+
* `source` string exactly as `scanComments(source)` reports them (a BOM
|
|
47
|
+
* counts as its first character).
|
|
48
|
+
* - The result is re-scanned; if the remaining comments do not match the kept
|
|
49
|
+
* set, an error is thrown instead of returning corrupted output.
|
|
50
|
+
*/
|
|
51
|
+
export function removeComments(source: string, options: RemoveOptions = {}): RemoveResult {
|
|
52
|
+
const jsx = options.jsx === true;
|
|
53
|
+
const comments = scanComments(source, { jsx });
|
|
54
|
+
|
|
55
|
+
let removed: Comment[] = [];
|
|
56
|
+
const kept: Comment[] = [];
|
|
57
|
+
const skipped: Comment[] = [];
|
|
58
|
+
for (const comment of comments) {
|
|
59
|
+
if (options.shouldRemove?.(comment) === false) {
|
|
60
|
+
skipped.push(comment);
|
|
61
|
+
} else if (isProtected(comment, options)) {
|
|
62
|
+
kept.push(comment);
|
|
63
|
+
} else {
|
|
64
|
+
removed.push(comment);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
for (;;) {
|
|
69
|
+
removed = shieldNextLineDirectives(source, removed, kept, skipped);
|
|
70
|
+
|
|
71
|
+
if (removed.length === 0) {
|
|
72
|
+
return { code: source, removed, kept, skipped, changed: false };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const code = spliceKeepingBom(source, removed);
|
|
76
|
+
const survivor = firstChangedSurvivor(source, code, scanComments(code, { jsx }), kept, skipped);
|
|
77
|
+
if (survivor === undefined) {
|
|
78
|
+
return { code, removed, kept, skipped, changed: true };
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
// A surviving comment changed meaning: with everything before it deleted
|
|
82
|
+
// it became the file's first comment (or its very first bytes), turning a
|
|
83
|
+
// previously inert positional directive live. Re-protect the removal
|
|
84
|
+
// candidate closest before it and try again: that comment then keeps
|
|
85
|
+
// holding the survivor away from the activating position, exactly as the
|
|
86
|
+
// input did. (Looping, because the re-protected comment can itself be a
|
|
87
|
+
// next-line directive that shields further lines.)
|
|
88
|
+
const blocker = closestRemovalBefore(removed, survivor);
|
|
89
|
+
if (blocker === undefined) {
|
|
90
|
+
throw unexpectedResult();
|
|
91
|
+
}
|
|
92
|
+
removed = removed.filter((comment) => comment !== blocker);
|
|
93
|
+
kept.push(blocker);
|
|
94
|
+
kept.sort((a, b) => a.start - b.start);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function unexpectedResult(): Error {
|
|
99
|
+
return new Error("comment removal produced an unexpected result; refusing to continue");
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Compares the spliced output's comments against the comments meant to
|
|
104
|
+
* survive, in document order (removal never reorders them). Throws when the
|
|
105
|
+
* texts themselves differ (the output would be corrupted) and returns the
|
|
106
|
+
* first surviving comment whose directive semantics changed, or undefined
|
|
107
|
+
* when the output is exactly as expected. Besides the canonical directive
|
|
108
|
+
* name, the position-dependent pragmas are compared on their own: a comment
|
|
109
|
+
* can carry an inert `@format` underneath the directive an earlier rule
|
|
110
|
+
* already named (an eslint config block, say), and that pragma going live
|
|
111
|
+
* must not hide behind the unchanged name.
|
|
112
|
+
*/
|
|
113
|
+
function firstChangedSurvivor(
|
|
114
|
+
source: string,
|
|
115
|
+
code: string,
|
|
116
|
+
actual: Comment[],
|
|
117
|
+
kept: Comment[],
|
|
118
|
+
skipped: Comment[],
|
|
119
|
+
): Comment | undefined {
|
|
120
|
+
const expected = [...kept, ...skipped].sort((a, b) => a.start - b.start);
|
|
121
|
+
if (actual.length !== expected.length) {
|
|
122
|
+
throw unexpectedResult();
|
|
123
|
+
}
|
|
124
|
+
for (const [index, comment] of expected.entries()) {
|
|
125
|
+
const survivor = actual[index] as Comment;
|
|
126
|
+
if (survivor.text !== comment.text) {
|
|
127
|
+
throw unexpectedResult();
|
|
128
|
+
}
|
|
129
|
+
if (survivor.directive !== comment.directive) return comment;
|
|
130
|
+
const before = activePositionalDirectives(comment.kind, comment.text, positionalPlacement(source, comment));
|
|
131
|
+
const after = activePositionalDirectives(survivor.kind, survivor.text, positionalPlacement(code, survivor));
|
|
132
|
+
if (before.join("\n") !== after.join("\n")) return comment;
|
|
133
|
+
}
|
|
134
|
+
return undefined;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The placement bits the position-dependent directives care about, derived
|
|
139
|
+
* without a parse: the comment is the file's first comment when nothing but
|
|
140
|
+
* whitespace (or a shebang) precedes it — any earlier comment's text keeps
|
|
141
|
+
* the slice non-blank — and it sits at the file start when it begins at
|
|
142
|
+
* offset zero. Header status needs the token structure, but removing
|
|
143
|
+
* comments never moves a comment across the first token, so the positional
|
|
144
|
+
* check does not consult it.
|
|
145
|
+
*/
|
|
146
|
+
function positionalPlacement(text: string, comment: Comment): DirectivePlacement {
|
|
147
|
+
const shebangLength = /^#!.*/.exec(text)?.[0].length ?? 0;
|
|
148
|
+
return {
|
|
149
|
+
header: false,
|
|
150
|
+
firstComment: isBlank(text.slice(shebangLength, comment.start)),
|
|
151
|
+
fileStart: comment.start === 0,
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** The removal candidate that starts closest before the comment, if any. */
|
|
156
|
+
function closestRemovalBefore(removals: readonly Comment[], comment: Comment): Comment | undefined {
|
|
157
|
+
let closest: Comment | undefined;
|
|
158
|
+
for (const removal of removals) {
|
|
159
|
+
if (removal.start < comment.start) closest = removal;
|
|
160
|
+
}
|
|
161
|
+
return closest;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Splices the removals out of the source, restoring the byte-order mark when
|
|
166
|
+
* dropping a comment-only first line took it along: the mark is an encoding
|
|
167
|
+
* artifact, not line content.
|
|
168
|
+
*/
|
|
169
|
+
function spliceKeepingBom(source: string, removals: readonly Comment[]): string {
|
|
170
|
+
if (!source.startsWith("\uFEFF")) return splice(source, removals);
|
|
171
|
+
// The splicing itself works on the BOM-less body (with ranges shifted to
|
|
172
|
+
// match) so its line handling never sees the mark, then the mark is
|
|
173
|
+
// re-attached; this keeps `\uFEFF// gone\n...` from losing the mark with
|
|
174
|
+
// the dropped line.
|
|
175
|
+
const body = source.slice(1);
|
|
176
|
+
const shifted = removals.map((comment) => ({ ...comment, start: comment.start - 1, end: comment.end - 1 }));
|
|
177
|
+
return `\uFEFF${splice(body, shifted)}`;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
function isProtected(comment: Comment, options: RemoveOptions): boolean {
|
|
181
|
+
if (comment.directive !== undefined && options.removeDirectives !== true) return true;
|
|
182
|
+
if (isLegalComment(comment.text) && options.removeLegal !== true) return true;
|
|
183
|
+
return false;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Re-protects comments whose removal would delete a physical line sitting
|
|
188
|
+
* under a surviving next-line directive (`@ts-expect-error`,
|
|
189
|
+
* `eslint-disable-next-line`, ...). Dropping such a line would shift the
|
|
190
|
+
* following code up, silently changing which line the directive applies to —
|
|
191
|
+
* and with it the compiler or linter behaviour.
|
|
192
|
+
*
|
|
193
|
+
* The check works on whole lines, not single comments: a line holding several
|
|
194
|
+
* removable comments (`/* one */ /* two */`) vanishes just the same, so every
|
|
195
|
+
* comment on it has to stay. Runs to a fixpoint because a re-protected
|
|
196
|
+
* comment can itself be a next-line directive shielding further lines (when
|
|
197
|
+
* directives are being removed selectively).
|
|
198
|
+
*/
|
|
199
|
+
function shieldNextLineDirectives(source: string, removed: Comment[], kept: Comment[], skipped: Comment[]): Comment[] {
|
|
200
|
+
const lineOffsets = lineStartOffsets(source);
|
|
201
|
+
const totalLines = lineOffsets.length;
|
|
202
|
+
const shieldedLines = new Set<number>();
|
|
203
|
+
const processed = new Set<Comment>();
|
|
204
|
+
let stillRemoved = removed;
|
|
205
|
+
|
|
206
|
+
const collectShields = (): boolean => {
|
|
207
|
+
let added = false;
|
|
208
|
+
for (const comment of [...kept, ...skipped]) {
|
|
209
|
+
if (processed.has(comment)) continue;
|
|
210
|
+
processed.add(comment);
|
|
211
|
+
if (comment.directive === undefined || !isNextLineDirective(comment.directive)) continue;
|
|
212
|
+
// A trailing formatter or scanner suppression (`a = [1]; // oxfmt-ignore`,
|
|
213
|
+
// `secret(); // nosemgrep`) targets its own line, so it shields nothing
|
|
214
|
+
// below it.
|
|
215
|
+
if (TRAILING_TARGETS_OWN_LINE.has(comment.directive) && !occupiesWholeLines(source, comment)) {
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
// Counted pragmas like `c8 ignore next 3` cover several lines.
|
|
219
|
+
for (let offset = 1; offset <= shieldedLineCount(comment); offset += 1) {
|
|
220
|
+
const line = comment.endLine + offset;
|
|
221
|
+
if (line > totalLines) break;
|
|
222
|
+
if (!shieldedLines.has(line)) {
|
|
223
|
+
shieldedLines.add(line);
|
|
224
|
+
added = true;
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
}
|
|
228
|
+
return added;
|
|
229
|
+
};
|
|
230
|
+
|
|
231
|
+
const protectShieldedLines = (): boolean => {
|
|
232
|
+
let changed = false;
|
|
233
|
+
for (const line of shieldedLines) {
|
|
234
|
+
const group = vanishingLineGroup(source, line, lineOffsets, stillRemoved);
|
|
235
|
+
if (group === undefined) continue;
|
|
236
|
+
const grouped = new Set(group);
|
|
237
|
+
stillRemoved = stillRemoved.filter((comment) => !grouped.has(comment));
|
|
238
|
+
kept.push(...group);
|
|
239
|
+
changed = true;
|
|
240
|
+
}
|
|
241
|
+
return changed;
|
|
242
|
+
};
|
|
243
|
+
|
|
244
|
+
collectShields();
|
|
245
|
+
while (protectShieldedLines()) {
|
|
246
|
+
if (!collectShields()) break;
|
|
247
|
+
}
|
|
248
|
+
if (stillRemoved.length !== removed.length) {
|
|
249
|
+
kept.sort((a, b) => a.start - b.start);
|
|
250
|
+
}
|
|
251
|
+
return stillRemoved;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* The removal candidates that would make the given line disappear: every
|
|
256
|
+
* non-whitespace character of the line lies inside one of them, so splicing
|
|
257
|
+
* them out deletes the physical line. Returns undefined when the line
|
|
258
|
+
* survives (it holds code, a kept comment, or nothing to remove at all).
|
|
259
|
+
*/
|
|
260
|
+
function vanishingLineGroup(
|
|
261
|
+
source: string,
|
|
262
|
+
line: number,
|
|
263
|
+
lineOffsets: readonly number[],
|
|
264
|
+
removals: readonly Comment[],
|
|
265
|
+
): Comment[] | undefined {
|
|
266
|
+
// collectShields never shields a line beyond the last one, so the offset exists.
|
|
267
|
+
const lineStart = lineOffsets[line - 1] as number;
|
|
268
|
+
const lineEnd = lineOffsets[line] ?? source.length;
|
|
269
|
+
const group = removals.filter((comment) => comment.start < lineEnd && comment.end > lineStart);
|
|
270
|
+
if (group.length === 0) return undefined;
|
|
271
|
+
for (let index = lineStart; index < lineEnd; index += 1) {
|
|
272
|
+
if (isBlank(source[index] as string)) continue;
|
|
273
|
+
if (!group.some((comment) => comment.start <= index && index < comment.end)) return undefined;
|
|
274
|
+
}
|
|
275
|
+
return group;
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
/** Start offset of every line, numbered the way the scanner numbers them. */
|
|
279
|
+
function lineStartOffsets(source: string): number[] {
|
|
280
|
+
const starts = [0];
|
|
281
|
+
for (let index = 0; index < source.length; index += 1) {
|
|
282
|
+
const char = source[index] as string;
|
|
283
|
+
if (char === "\r") {
|
|
284
|
+
starts.push(source[index + 1] === "\n" ? (index += 1) + 1 : index + 1);
|
|
285
|
+
} else if (char === "\n" || char === "\u2028" || char === "\u2029") {
|
|
286
|
+
starts.push(index + 1);
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
return starts;
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
// These suppressions only apply to the following node/line when they stand on
|
|
293
|
+
// their own line — trailing after code they target (at most) their own line.
|
|
294
|
+
// Other next-line directives (`@ts-ignore`, `no-dd-sa`, ...) target the next
|
|
295
|
+
// line even when they trail code.
|
|
296
|
+
const TRAILING_TARGETS_OWN_LINE = new Set([
|
|
297
|
+
"prettier-ignore",
|
|
298
|
+
"oxfmt-ignore",
|
|
299
|
+
"dprint-ignore",
|
|
300
|
+
"lgtm",
|
|
301
|
+
"codeql",
|
|
302
|
+
"skipcq",
|
|
303
|
+
"nosemgrep",
|
|
304
|
+
]);
|
|
305
|
+
|
|
306
|
+
// File- and range-scoped pragmas (`c8 ignore start`, `istanbul ignore file`,
|
|
307
|
+
// ...) do not target the following line, so they never shield it.
|
|
308
|
+
function isNextLineDirective(name: string): boolean {
|
|
309
|
+
return (
|
|
310
|
+
name.endsWith("-next-line") ||
|
|
311
|
+
[
|
|
312
|
+
"@ts-ignore",
|
|
313
|
+
"@ts-expect-error",
|
|
314
|
+
"biome-ignore",
|
|
315
|
+
"deno-lint-ignore",
|
|
316
|
+
"deno-fmt-ignore",
|
|
317
|
+
"deno-coverage-ignore",
|
|
318
|
+
"prettier-ignore",
|
|
319
|
+
"oxfmt-ignore",
|
|
320
|
+
"dprint-ignore",
|
|
321
|
+
"rome-ignore",
|
|
322
|
+
"istanbul-ignore",
|
|
323
|
+
"istanbul-ignore-next",
|
|
324
|
+
"istanbul-ignore-if",
|
|
325
|
+
"istanbul-ignore-else",
|
|
326
|
+
"c8-ignore",
|
|
327
|
+
"c8-ignore-next",
|
|
328
|
+
"c8-ignore-if",
|
|
329
|
+
"c8-ignore-else",
|
|
330
|
+
"v8-ignore",
|
|
331
|
+
"v8-ignore-next",
|
|
332
|
+
"v8-ignore-if",
|
|
333
|
+
"v8-ignore-else",
|
|
334
|
+
"node:coverage-ignore",
|
|
335
|
+
// Directives that hang off the node or line directly below them: a
|
|
336
|
+
// whole-line comment between them and their target would change what
|
|
337
|
+
// they apply to, so the line below stays shielded.
|
|
338
|
+
"ts-prune-ignore-next",
|
|
339
|
+
"million-ignore",
|
|
340
|
+
"@million-skip",
|
|
341
|
+
"@million-jsx-skip",
|
|
342
|
+
"@deno-types",
|
|
343
|
+
"@ts-types",
|
|
344
|
+
"deepcode-ignore",
|
|
345
|
+
"skipcq",
|
|
346
|
+
"lgtm",
|
|
347
|
+
"codeql",
|
|
348
|
+
"nosemgrep",
|
|
349
|
+
"no-dd-sa",
|
|
350
|
+
"datadog-disable",
|
|
351
|
+
"noinspection",
|
|
352
|
+
"language-injection",
|
|
353
|
+
"@next-codemod-error",
|
|
354
|
+
"@next-codemod-ignore",
|
|
355
|
+
"$FlowFixMe",
|
|
356
|
+
"$FlowExpectedError",
|
|
357
|
+
"$FlowIssue",
|
|
358
|
+
"$FlowIgnore",
|
|
359
|
+
"pragma-allowlist-nextline-secret",
|
|
360
|
+
"cspell:disable-next",
|
|
361
|
+
"GraphQL",
|
|
362
|
+
"HTML",
|
|
363
|
+
].includes(name)
|
|
364
|
+
);
|
|
365
|
+
}
|
|
366
|
+
|
|
367
|
+
// The coverage pragmas that actually parse a line count after `ignore next`
|
|
368
|
+
// (c8 / v8-to-istanbul, Vitest's ast-v8-to-istanbul, and Node's test-runner
|
|
369
|
+
// coverage). Everything else — `@ts-expect-error`, `eslint-disable-next-line`
|
|
370
|
+
// and friends — covers exactly one line, no matter what prose like
|
|
371
|
+
// "we ignore next 3 legacy calls" appears in the reason text.
|
|
372
|
+
const COUNTED_NEXT_LINE = new Set(["istanbul-ignore-next", "c8-ignore-next", "v8-ignore-next", "node:coverage-ignore"]);
|
|
373
|
+
|
|
374
|
+
/** Number of following lines a next-line pragma covers (`c8 ignore next 3` → 3). */
|
|
375
|
+
function shieldedLineCount(comment: Comment): number {
|
|
376
|
+
if (comment.directive === undefined || !COUNTED_NEXT_LINE.has(comment.directive)) return 1;
|
|
377
|
+
const match = /\bignore\s+next\s+(\d+)\b/.exec(comment.text);
|
|
378
|
+
return match ? Math.max(1, Number(match[1])) : 1;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
/**
|
|
382
|
+
* True when nothing but whitespace shares the comment's first and last lines.
|
|
383
|
+
* Lines are delimited by any ECMAScript line terminator, matching how the
|
|
384
|
+
* scanner numbers them (a lone `\r`, U+2028 and U+2029 count too).
|
|
385
|
+
*/
|
|
386
|
+
function occupiesWholeLines(source: string, comment: Comment): boolean {
|
|
387
|
+
for (let index = comment.start - 1; index >= 0; index -= 1) {
|
|
388
|
+
const char = source[index] as string;
|
|
389
|
+
if (LINE_TERMINATOR.test(char)) break;
|
|
390
|
+
if (!isBlank(char)) return false;
|
|
391
|
+
}
|
|
392
|
+
for (let index = comment.end; index < source.length; index += 1) {
|
|
393
|
+
const char = source[index] as string;
|
|
394
|
+
if (LINE_TERMINATOR.test(char)) break;
|
|
395
|
+
if (!isBlank(char)) return false;
|
|
396
|
+
}
|
|
397
|
+
return true;
|
|
398
|
+
}
|
|
399
|
+
|
|
400
|
+
const isBlank = (text: string): boolean => /^\s*$/.test(text);
|
|
401
|
+
|
|
402
|
+
const isHorizontalSpace = (char: string | undefined): boolean => char === " " || char === "\t";
|
|
403
|
+
|
|
404
|
+
const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
|
|
405
|
+
|
|
406
|
+
// Every ECMAScript line break the way the scanner counts them: CRLF as one
|
|
407
|
+
// break, then lone LF / CR and the U+2028/U+2029 separators.
|
|
408
|
+
const NEXT_LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/g;
|
|
409
|
+
|
|
410
|
+
/** End offset (exclusive) of the last line break in the chunk, or -1 when it has none. */
|
|
411
|
+
function lastLineBreakEnd(chunk: string): number {
|
|
412
|
+
for (let index = chunk.length - 1; index >= 0; index -= 1) {
|
|
413
|
+
if (LINE_TERMINATOR.test(chunk[index] as string)) return index + 1;
|
|
414
|
+
}
|
|
415
|
+
return -1;
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
/**
|
|
419
|
+
* Splices sorted, non-overlapping comment ranges out of the source, tidying lines.
|
|
420
|
+
* Output is accumulated as segments with incremental line-state tracking, so the
|
|
421
|
+
* work stays linear in the source size even for comment-dense files.
|
|
422
|
+
*/
|
|
423
|
+
function splice(source: string, removals: readonly Comment[]): string {
|
|
424
|
+
const segments: string[] = [];
|
|
425
|
+
let cursor = 0;
|
|
426
|
+
/** Whether the output's current (unterminated) line is all whitespace so far. */
|
|
427
|
+
let lineIsBlank = true;
|
|
428
|
+
/** Last character of the output so far ("" while empty). */
|
|
429
|
+
let lastChar = "";
|
|
430
|
+
|
|
431
|
+
const push = (chunk: string): void => {
|
|
432
|
+
if (chunk === "") return;
|
|
433
|
+
segments.push(chunk);
|
|
434
|
+
const breakEnd = lastLineBreakEnd(chunk);
|
|
435
|
+
lineIsBlank = breakEnd === -1 ? lineIsBlank && isBlank(chunk) : isBlank(chunk.slice(breakEnd));
|
|
436
|
+
lastChar = chunk.slice(-1);
|
|
437
|
+
};
|
|
438
|
+
|
|
439
|
+
/** Deletes everything the output holds after its last line break. */
|
|
440
|
+
const dropCurrentLine = (): void => {
|
|
441
|
+
while (segments.length > 0) {
|
|
442
|
+
const last = segments[segments.length - 1] as string;
|
|
443
|
+
const breakEnd = lastLineBreakEnd(last);
|
|
444
|
+
if (breakEnd === -1) {
|
|
445
|
+
segments.pop();
|
|
446
|
+
continue;
|
|
447
|
+
}
|
|
448
|
+
segments[segments.length - 1] = last.slice(0, breakEnd);
|
|
449
|
+
lineIsBlank = true;
|
|
450
|
+
lastChar = last.charAt(breakEnd - 1);
|
|
451
|
+
return;
|
|
452
|
+
}
|
|
453
|
+
lineIsBlank = true;
|
|
454
|
+
lastChar = "";
|
|
455
|
+
};
|
|
456
|
+
|
|
457
|
+
/** Deletes trailing spaces/tabs of the output's current line. */
|
|
458
|
+
const trimLineEnd = (): void => {
|
|
459
|
+
while (segments.length > 0) {
|
|
460
|
+
const last = segments[segments.length - 1] as string;
|
|
461
|
+
let end = last.length;
|
|
462
|
+
while (end > 0 && isHorizontalSpace(last[end - 1])) end -= 1;
|
|
463
|
+
if (end === 0) {
|
|
464
|
+
segments.pop();
|
|
465
|
+
continue;
|
|
466
|
+
}
|
|
467
|
+
if (end < last.length) segments[segments.length - 1] = last.slice(0, end);
|
|
468
|
+
lastChar = (segments[segments.length - 1] as string).slice(-1);
|
|
469
|
+
return;
|
|
470
|
+
}
|
|
471
|
+
lastChar = "";
|
|
472
|
+
};
|
|
473
|
+
|
|
474
|
+
for (const comment of removals) {
|
|
475
|
+
push(source.slice(cursor, comment.start));
|
|
476
|
+
cursor = comment.end;
|
|
477
|
+
|
|
478
|
+
NEXT_LINE_BREAK.lastIndex = cursor;
|
|
479
|
+
const lineBreak = NEXT_LINE_BREAK.exec(source);
|
|
480
|
+
const contentEnd = lineBreak === null ? source.length : lineBreak.index;
|
|
481
|
+
const lineEnd = lineBreak === null ? source.length : lineBreak.index + lineBreak[0].length;
|
|
482
|
+
const restContent = source.slice(cursor, contentEnd);
|
|
483
|
+
|
|
484
|
+
if (lineIsBlank && isBlank(restContent)) {
|
|
485
|
+
// The comment occupied whole line(s): drop them entirely.
|
|
486
|
+
dropCurrentLine();
|
|
487
|
+
cursor = lineEnd;
|
|
488
|
+
} else if (isBlank(restContent)) {
|
|
489
|
+
// Trailing comment after code: trim the gap, keep the line break.
|
|
490
|
+
trimLineEnd();
|
|
491
|
+
push(source.slice(contentEnd, lineEnd));
|
|
492
|
+
cursor = lineEnd;
|
|
493
|
+
} else if (!lineIsBlank && LINE_TERMINATOR.test(comment.text)) {
|
|
494
|
+
// Code on both sides of a block comment that spans lines. Per ECMA-262
|
|
495
|
+
// such a comment acts as a line terminator for semicolon insertion, so
|
|
496
|
+
// replace it with a real line break (matching the file's style) instead
|
|
497
|
+
// of merging the lines.
|
|
498
|
+
trimLineEnd();
|
|
499
|
+
push(comment.text.includes("\r\n") ? "\r\n" : "\n");
|
|
500
|
+
} else {
|
|
501
|
+
// Inline comment with code after it on the same line.
|
|
502
|
+
const next = source.charAt(cursor);
|
|
503
|
+
if (lastChar !== "" && !isBlank(lastChar) && !isBlank(next)) {
|
|
504
|
+
// `a/* x */b` would merge tokens: keep them apart.
|
|
505
|
+
push(" ");
|
|
506
|
+
} else if (lastChar === "" || isBlank(lastChar)) {
|
|
507
|
+
// Collapse the horizontal whitespace that followed the comment.
|
|
508
|
+
while (cursor < lineEnd && isHorizontalSpace(source[cursor])) cursor += 1;
|
|
509
|
+
}
|
|
510
|
+
}
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
segments.push(source.slice(cursor));
|
|
514
|
+
return segments.join("");
|
|
515
|
+
}
|
package/src/report.ts
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { Buffer } from "node:buffer";
|
|
2
|
+
import type { Comment, FileScanResult } from "./types.js";
|
|
3
|
+
|
|
4
|
+
/** Formats `3 comments`, `1 file`, ... with naive pluralization. */
|
|
5
|
+
export function count(value: number, noun: string): string {
|
|
6
|
+
return `${value} ${noun}${value === 1 ? "" : "s"}`;
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
function renderComments(results: FileScanResult[], renderLine: (file: string, comment: Comment) => string): string {
|
|
10
|
+
const lines: string[] = [];
|
|
11
|
+
let total = 0;
|
|
12
|
+
let fileCount = 0;
|
|
13
|
+
|
|
14
|
+
for (const { file, comments } of results) {
|
|
15
|
+
if (comments.length === 0) continue;
|
|
16
|
+
fileCount += 1;
|
|
17
|
+
for (const comment of comments) {
|
|
18
|
+
lines.push(renderLine(file, comment));
|
|
19
|
+
total += 1;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
if (total === 0) {
|
|
24
|
+
return "No comments found.";
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
lines.push("", `${count(total, "comment")} across ${count(fileCount, "file")}`);
|
|
28
|
+
return lines.join("\n");
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function formatText(results: FileScanResult[]): string {
|
|
32
|
+
return renderComments(results, (file, comment) => {
|
|
33
|
+
const tag = comment.directive === undefined ? "" : ` [${comment.directive}]`;
|
|
34
|
+
return `${file}:${comment.line}:${comment.column} [${comment.kind}]${tag} ${preview(comment.text)}`;
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
function preview(text: string): string {
|
|
39
|
+
// Split on every ECMAScript line terminator so exotic breaks (lone \r,
|
|
40
|
+
// U+2028/U+2029) cannot leak raw control characters into terminal output.
|
|
41
|
+
return text
|
|
42
|
+
.split(/\r\n|[\n\r\u2028\u2029]/)
|
|
43
|
+
.map((line) => line.trim())
|
|
44
|
+
.join(" ")
|
|
45
|
+
.trim();
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export function formatJson(results: FileScanResult[]): string {
|
|
49
|
+
const files = results.filter((result) => result.comments.length > 0);
|
|
50
|
+
const comments = files.reduce((sum, file) => sum + file.comments.length, 0);
|
|
51
|
+
const directives = files.reduce(
|
|
52
|
+
(sum, file) => sum + file.comments.filter((comment) => comment.directive !== undefined).length,
|
|
53
|
+
0,
|
|
54
|
+
);
|
|
55
|
+
|
|
56
|
+
return JSON.stringify({ summary: { files: files.length, comments, directives }, files }, null, 2);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Formats results as GitHub Actions workflow commands so each comment shows up
|
|
61
|
+
* as an annotation on the corresponding file and line in CI.
|
|
62
|
+
* See https://docs.github.com/actions/reference/workflow-commands-for-github-actions
|
|
63
|
+
*/
|
|
64
|
+
export function formatGitHub(results: FileScanResult[]): string {
|
|
65
|
+
return renderComments(results, annotation);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
function annotation(file: string, comment: Comment): string {
|
|
69
|
+
const title =
|
|
70
|
+
comment.directive === undefined ? `${comment.kind} comment` : `${comment.kind} comment (${comment.directive})`;
|
|
71
|
+
const properties = [`file=${escapeProperty(file)}`, `line=${comment.line}`, `endLine=${comment.endLine}`];
|
|
72
|
+
if (comment.line === comment.endLine) {
|
|
73
|
+
// The scanner's endColumn is exclusive, GitHub's annotation columns are
|
|
74
|
+
// inclusive (a 6-character token at columns 5–10 is reported end_column
|
|
75
|
+
// 10 by the Checks API), so the last covered column is endColumn - 1.
|
|
76
|
+
properties.push(`col=${comment.column}`, `endColumn=${comment.endColumn - 1}`);
|
|
77
|
+
}
|
|
78
|
+
properties.push(`title=${escapeProperty(title)}`);
|
|
79
|
+
return `::notice ${properties.join(",")}::${escapeData(truncateAnnotationMessage(comment.text))}`;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
// GitHub rejects annotation messages over 64 KiB; truncate on a code-point
|
|
83
|
+
// boundary with room to spare so huge comments still annotate.
|
|
84
|
+
const MAX_ANNOTATION_MESSAGE_BYTES = 60_000;
|
|
85
|
+
const TRUNCATION_SUFFIX = "… (truncated)";
|
|
86
|
+
|
|
87
|
+
function truncateAnnotationMessage(text: string): string {
|
|
88
|
+
if (Buffer.byteLength(text, "utf8") <= MAX_ANNOTATION_MESSAGE_BYTES) return text;
|
|
89
|
+
let bytes = 0;
|
|
90
|
+
let end = 0;
|
|
91
|
+
for (const char of text) {
|
|
92
|
+
const size = Buffer.byteLength(char, "utf8");
|
|
93
|
+
if (bytes + size > MAX_ANNOTATION_MESSAGE_BYTES) break;
|
|
94
|
+
bytes += size;
|
|
95
|
+
end += char.length;
|
|
96
|
+
}
|
|
97
|
+
return `${text.slice(0, end)}${TRUNCATION_SUFFIX}`;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function escapeData(value: string): string {
|
|
101
|
+
return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function escapeProperty(value: string): string {
|
|
105
|
+
return escapeData(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
|
|
106
|
+
}
|