@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/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
+ }