@kongyo2/ts-comment-scanner 1.2.1 → 1.4.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/run.ts ADDED
@@ -0,0 +1,283 @@
1
+ import { realpathSync } from "node:fs";
2
+ import { stat } from "node:fs/promises";
3
+ import { basename, dirname, join, resolve } from "node:path";
4
+ import { parseArgs, UsageError, type CliOptions, type DirectiveMode } from "./args.js";
5
+ import {
6
+ collectFiles,
7
+ encodeFileText,
8
+ isJsxFile,
9
+ mapLimit,
10
+ readFileText,
11
+ scanFile,
12
+ writeFileAtomic,
13
+ FILE_CONCURRENCY,
14
+ type CollectOptions,
15
+ } from "./files.js";
16
+ import { changedFiles } from "./git.js";
17
+ import { removeComments } from "./remove.js";
18
+ import { count, formatGitHub, formatJson, formatText } from "./report.js";
19
+ import { getVersion } from "./version.js";
20
+ import type { Comment, FileScanResult } from "./types.js";
21
+
22
+ export interface CliIO {
23
+ out: (text: string) => void;
24
+ err: (text: string) => void;
25
+ }
26
+
27
+ export const HELP_TEXT = `Usage: ts-comment-scanner [options] [paths...]
28
+
29
+ Detect, report and clean up comments across a TypeScript project.
30
+
31
+ Output:
32
+ --format <fmt> Output format: text, json or github (default: text)
33
+ --json Shorthand for --format json
34
+
35
+ Filtering:
36
+ --ignore <glob> Skip files/directories matching the glob (repeatable)
37
+ --ext <list> Comma-separated extensions to scan (default: .ts,.tsx,.mts,.cts)
38
+ --diff <range> Only files git reports changed in the revision range
39
+ --skip-directives Hide compiler/linter directives (@ts-ignore, eslint-disable, ...)
40
+ --only-directives Report only compiler/linter directives
41
+
42
+ CI:
43
+ --fail-on-comment Exit with code 1 when any comment is reported
44
+
45
+ Removal:
46
+ --remove Delete the reported comments from the files (in place)
47
+ --dry-run With --remove: show what would be removed, change nothing
48
+ --remove-directives With --remove: also delete directive comments
49
+ --remove-legal With --remove: also delete license/legal comments
50
+
51
+ General:
52
+ -h, --help Show this help
53
+ -v, --version Print the version number
54
+
55
+ Paths default to the current directory. Directories are scanned recursively,
56
+ skipping node_modules and .git. Removal keeps directives and license headers
57
+ unless explicitly requested, so builds and linters keep working.
58
+
59
+ --diff narrows any scan or removal to files changed in git: a single revision
60
+ compares the working tree against it (HEAD covers all uncommitted work,
61
+ untracked files included), while main..HEAD compares two commits. Handy for
62
+ cleaning up only the files a coding agent just touched.
63
+
64
+ Exit codes: 0 success, 1 comments reported with --fail-on-comment, 2 error.
65
+
66
+ Examples:
67
+ ts-comment-scanner src
68
+ ts-comment-scanner --format github --fail-on-comment src
69
+ ts-comment-scanner --ignore "**/*.test.ts" --skip-directives src
70
+ ts-comment-scanner --remove --dry-run src
71
+ ts-comment-scanner --remove --diff main..HEAD
72
+ `;
73
+
74
+ export async function run(argv: string[], io: CliIO): Promise<number> {
75
+ // Help always wins, even on an otherwise-invalid command line.
76
+ if (wantsHelp(argv)) {
77
+ io.out(HELP_TEXT);
78
+ return 0;
79
+ }
80
+
81
+ let options: CliOptions;
82
+ try {
83
+ options = parseArgs(argv);
84
+ } catch (error) {
85
+ if (error instanceof UsageError) {
86
+ io.err(`ts-comment-scanner: ${error.message}\nTry 'ts-comment-scanner --help' for usage.\n`);
87
+ return 2;
88
+ }
89
+ throw error;
90
+ }
91
+
92
+ // A -h/--help the early scan above could not see (e.g. consumed-looking
93
+ // spots like `--ignore -- --help`) still means help once parsed as a flag.
94
+ if (options.help) {
95
+ io.out(HELP_TEXT);
96
+ return 0;
97
+ }
98
+
99
+ try {
100
+ if (options.version) {
101
+ io.out(`${await getVersion()}\n`);
102
+ return 0;
103
+ }
104
+
105
+ const collectOptions: CollectOptions = {
106
+ ignore: options.ignore,
107
+ ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
108
+ };
109
+
110
+ if (options.remove) {
111
+ return await runRemove(options, collectOptions, io);
112
+ }
113
+
114
+ const files = await collectTargets(options, collectOptions);
115
+ const results = filterDirectives(await mapLimit(files, FILE_CONCURRENCY, scanFile), options.directives);
116
+ io.out(`${render(results, options.format)}\n`);
117
+
118
+ const total = results.reduce((sum, result) => sum + result.comments.length, 0);
119
+ return options.failOnComment && total > 0 ? 1 : 0;
120
+ } catch (error) {
121
+ const message = error instanceof Error ? error.message : String(error);
122
+ io.err(`ts-comment-scanner: ${message}\n`);
123
+ return 2;
124
+ }
125
+ }
126
+
127
+ /**
128
+ * Collects the input files, narrowed to the files git reports changed when
129
+ * --diff is set. git runs in the repository containing the first input path
130
+ * (not the collected files, which could sit in a nested repository), so
131
+ * scanning another repository's checkout works from anywhere.
132
+ */
133
+ async function collectTargets(options: CliOptions, collectOptions: CollectOptions): Promise<string[]> {
134
+ const files = await collectFiles(options.paths, collectOptions);
135
+ if (options.diff === undefined) return files;
136
+
137
+ const first = resolve(options.paths[0] as string);
138
+ const anchor = (await stat(first)).isDirectory() ? first : dirname(first);
139
+ const changed = new Set((await changedFiles(options.diff, anchor)).map(caseFold));
140
+ // Realpath only the directory part: spellings through symlinked directories
141
+ // then compare equal, while a tracked symlink still matches the path git
142
+ // reports it at instead of dereferencing to its target.
143
+ return files.filter((file) => changed.has(caseFold(join(realpathSync(dirname(file)), basename(file)))));
144
+ }
145
+
146
+ /**
147
+ * Windows paths are case-insensitive, but git reports the case a file was
148
+ * tracked with; folding both sides keeps `Foo.ts` in the --diff scope when
149
+ * the scan found it as `foo.ts`.
150
+ */
151
+ function caseFold(path: string): string {
152
+ return process.platform === "win32" ? path.toLowerCase() : path;
153
+ }
154
+
155
+ /** True when -h/--help appears before any `--` separator. */
156
+ function wantsHelp(argv: string[]): boolean {
157
+ for (const arg of argv) {
158
+ if (arg === "--") return false;
159
+ if (arg === "-h" || arg === "--help") return true;
160
+ }
161
+ return false;
162
+ }
163
+
164
+ function render(results: FileScanResult[], format: CliOptions["format"]): string {
165
+ if (format === "json") return formatJson(results);
166
+ if (format === "github") return formatGitHub(results);
167
+ return formatText(results);
168
+ }
169
+
170
+ function inScope(comment: Comment, mode: DirectiveMode): boolean {
171
+ if (mode === "skip") return comment.directive === undefined;
172
+ if (mode === "only") return comment.directive !== undefined;
173
+ return true;
174
+ }
175
+
176
+ function filterDirectives(results: FileScanResult[], mode: DirectiveMode): FileScanResult[] {
177
+ if (mode === "include") return results;
178
+ return results.map((result) => ({
179
+ file: result.file,
180
+ comments: result.comments.filter((comment) => inScope(comment, mode)),
181
+ }));
182
+ }
183
+
184
+ interface FileRemoval {
185
+ file: string;
186
+ removed: Comment[];
187
+ kept: Comment[];
188
+ skipped: Comment[];
189
+ }
190
+
191
+ async function runRemove(options: CliOptions, collectOptions: CollectOptions, io: CliIO): Promise<number> {
192
+ const files = await collectTargets(options, collectOptions);
193
+
194
+ const outcomes = await mapLimit(files, FILE_CONCURRENCY, async (file) => {
195
+ try {
196
+ const { text, encoding, bom, lossless } = await readFileText(file);
197
+ const result = removeComments(text, {
198
+ jsx: isJsxFile(file),
199
+ removeDirectives: options.removeDirectives,
200
+ removeLegal: options.removeLegal,
201
+ shouldRemove: (comment) => inScope(comment, options.directives),
202
+ });
203
+ if (result.changed) {
204
+ if (!lossless) {
205
+ // Re-encoding would not reproduce the original bytes (invalid
206
+ // UTF-8, truncated UTF-16, ...): rewriting the file would corrupt
207
+ // content outside the comments. Reported for --dry-run too, so the
208
+ // preflight fails the same way the real removal would.
209
+ throw new Error("file is not valid UTF-8 or UTF-16; refusing to modify it");
210
+ }
211
+ if (!options.dryRun) {
212
+ await writeFileAtomic(file, encodeFileText(result.code, { encoding, bom }));
213
+ }
214
+ }
215
+ return { file, removed: result.removed, kept: result.kept, skipped: result.skipped };
216
+ } catch (error) {
217
+ const message = error instanceof Error ? error.message : String(error);
218
+ return { file, failure: `${file}: ${message}` };
219
+ }
220
+ });
221
+
222
+ const removals: FileRemoval[] = [];
223
+ const failures: string[] = [];
224
+ for (const outcome of outcomes) {
225
+ if ("failure" in outcome) {
226
+ failures.push(outcome.failure);
227
+ } else if (outcome.removed.length > 0 || outcome.kept.length > 0 || outcome.skipped.length > 0) {
228
+ removals.push(outcome);
229
+ }
230
+ }
231
+
232
+ io.out(`${renderRemoval(removals, options)}\n`);
233
+ for (const failure of failures) {
234
+ io.err(`ts-comment-scanner: ${failure}\n`);
235
+ }
236
+ return failures.length > 0 ? 2 : 0;
237
+ }
238
+
239
+ function renderRemoval(removals: FileRemoval[], options: CliOptions): string {
240
+ const totalRemoved = removals.reduce((sum, entry) => sum + entry.removed.length, 0);
241
+ const totalKept = removals.reduce((sum, entry) => sum + entry.kept.length, 0);
242
+ const totalSkipped = removals.reduce((sum, entry) => sum + entry.skipped.length, 0);
243
+ const changedEntries = removals.filter((entry) => entry.removed.length > 0);
244
+ const keptNote = totalKept > 0 ? ` Kept ${count(totalKept, "protected comment")}.` : "";
245
+ // Directives held back by --skip-directives are invisible in the removal
246
+ // counts; say how many were left untouched so "removed N" is not mistaken
247
+ // for "the files are now comment-free".
248
+ const skippedNote = totalSkipped > 0 ? ` Skipped ${count(totalSkipped, "comment")} (--skip-directives).` : "";
249
+
250
+ if (options.format === "json") {
251
+ return JSON.stringify(
252
+ {
253
+ summary: {
254
+ files: changedEntries.length,
255
+ removed: totalRemoved,
256
+ kept: totalKept,
257
+ skipped: totalSkipped,
258
+ dryRun: options.dryRun,
259
+ },
260
+ files: removals,
261
+ },
262
+ null,
263
+ 2,
264
+ );
265
+ }
266
+
267
+ if (totalRemoved === 0) {
268
+ return `No removable comments found.${keptNote}${skippedNote}`;
269
+ }
270
+
271
+ const verb = options.dryRun ? "would remove" : "removed";
272
+ const lines = changedEntries.map((entry) => {
273
+ const kept = entry.kept.length > 0 ? ` (kept ${entry.kept.length})` : "";
274
+ return `${entry.file}: ${verb} ${entry.removed.length}${kept}`;
275
+ });
276
+
277
+ const sentenceVerb = verb.charAt(0).toUpperCase() + verb.slice(1);
278
+ lines.push(
279
+ "",
280
+ `${sentenceVerb} ${count(totalRemoved, "comment")} across ${count(changedEntries.length, "file")}.${keptNote}${skippedNote}`,
281
+ );
282
+ return lines.join("\n");
283
+ }
package/src/scanner.ts ADDED
@@ -0,0 +1,104 @@
1
+ import ts from "typescript";
2
+ import { detectDirective, type DirectivePlacement } from "./directives.js";
3
+ import type { Comment, CommentKind } from "./types.js";
4
+
5
+ export interface ScanOptions {
6
+ jsx?: boolean;
7
+ }
8
+
9
+ export function scanComments(source: string, options: ScanOptions = {}): Comment[] {
10
+ const jsx = options.jsx === true;
11
+ const fileName = jsx ? "module.tsx" : "module.ts";
12
+ const scriptKind = jsx ? ts.ScriptKind.TSX : ts.ScriptKind.TS;
13
+ const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKind);
14
+
15
+ const jsxTextSpans: Array<[number, number]> = [];
16
+ const ranges: ts.CommentRange[] = [];
17
+ const seen = new Set<number>();
18
+
19
+ const collect = (found: readonly ts.CommentRange[] | undefined): void => {
20
+ if (!found) return;
21
+ for (const range of found) {
22
+ if (seen.has(range.pos)) continue;
23
+ seen.add(range.pos);
24
+ ranges.push(range);
25
+ }
26
+ };
27
+
28
+ // Iterative depth-first walk: generated or minified sources nest thousands
29
+ // of expressions deep, where a recursive visitor overflows the call stack
30
+ // even though the parse itself succeeded.
31
+ const pending: ts.Node[] = [sourceFile];
32
+ while (pending.length > 0) {
33
+ const node = pending.pop() as ts.Node;
34
+ // JSDoc nodes start inside the comment text itself; descending into them
35
+ // would hide the comment (e.g. a trailing JSDoc attached to the
36
+ // end-of-file token). Treat them as trivia like any other comment.
37
+ const children = node.getChildren(sourceFile).filter((child) => !ts.isJSDoc(child));
38
+ if (children.length === 0) {
39
+ if (node.kind === ts.SyntaxKind.JsxText) {
40
+ jsxTextSpans.push([node.getFullStart(), node.getEnd()]);
41
+ }
42
+ collect(ts.getLeadingCommentRanges(source, node.getFullStart()));
43
+ collect(ts.getTrailingCommentRanges(source, node.getEnd()));
44
+ continue;
45
+ }
46
+ for (let index = children.length - 1; index >= 0; index -= 1) {
47
+ pending.push(children[index] as ts.Node);
48
+ }
49
+ }
50
+
51
+ // JsxText spans never overlap, so a position is inside one exactly when it
52
+ // is inside the closest span starting at or before it — found by binary
53
+ // search, keeping comment-dense TSX files out of quadratic time.
54
+ jsxTextSpans.sort((a, b) => a[0] - b[0]);
55
+ const insideJsxText = (pos: number): boolean => {
56
+ let low = 0;
57
+ let high = jsxTextSpans.length - 1;
58
+ let candidate = -1;
59
+ while (low <= high) {
60
+ const middle = (low + high) >> 1;
61
+ if ((jsxTextSpans[middle] as [number, number])[0] <= pos) {
62
+ candidate = middle;
63
+ low = middle + 1;
64
+ } else {
65
+ high = middle - 1;
66
+ }
67
+ }
68
+ return candidate >= 0 && pos < (jsxTextSpans[candidate] as [number, number])[1];
69
+ };
70
+
71
+ const sorted = ranges.filter((range) => !insideJsxText(range.pos)).sort((a, b) => a.pos - b.pos);
72
+
73
+ // Directive rules with positional requirements (header pragmas, prettier's
74
+ // first-comment docblock, Bun's file-start marker) get the comment's actual
75
+ // placement; a shebang does not count as content before the first comment,
76
+ // matching jest-docblock.
77
+ const firstTokenStart = sourceFile.getStart(sourceFile);
78
+ const shebangEnd = ts.getShebang(source)?.length ?? 0;
79
+ const firstCommentPos = sorted.length > 0 ? (sorted[0] as ts.CommentRange).pos : -1;
80
+ const placementOf = (pos: number): DirectivePlacement => ({
81
+ header: pos < firstTokenStart,
82
+ firstComment: pos === firstCommentPos && /^\s*$/.test(source.slice(shebangEnd, pos)),
83
+ fileStart: pos === 0,
84
+ });
85
+
86
+ return sorted.map((range) => {
87
+ const kind: CommentKind = range.kind === ts.SyntaxKind.SingleLineCommentTrivia ? "line" : "block";
88
+ const text = source.slice(range.pos, range.end);
89
+ const startPosition = sourceFile.getLineAndCharacterOfPosition(range.pos);
90
+ const endPosition = sourceFile.getLineAndCharacterOfPosition(range.end);
91
+ const directive = detectDirective(kind, text, placementOf(range.pos));
92
+ return {
93
+ kind,
94
+ text,
95
+ start: range.pos,
96
+ end: range.end,
97
+ line: startPosition.line + 1,
98
+ column: startPosition.character + 1,
99
+ endLine: endPosition.line + 1,
100
+ endColumn: endPosition.character + 1,
101
+ ...(directive === undefined ? {} : { directive }),
102
+ };
103
+ });
104
+ }
package/src/types.ts ADDED
@@ -0,0 +1,19 @@
1
+ export type CommentKind = "line" | "block";
2
+
3
+ export interface Comment {
4
+ kind: CommentKind;
5
+ text: string;
6
+ start: number;
7
+ end: number;
8
+ line: number;
9
+ column: number;
10
+ endLine: number;
11
+ endColumn: number;
12
+ /** Canonical name of the compiler/linter directive this comment represents, if any. */
13
+ directive?: string;
14
+ }
15
+
16
+ export interface FileScanResult {
17
+ file: string;
18
+ comments: Comment[];
19
+ }
package/src/version.ts ADDED
@@ -0,0 +1,7 @@
1
+ import { readFile } from "node:fs/promises";
2
+
3
+ export async function getVersion(): Promise<string> {
4
+ const url = new URL("../package.json", import.meta.url);
5
+ const pkg = JSON.parse(await readFile(url, "utf8")) as { version: string };
6
+ return pkg.version;
7
+ }