@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/files.ts ADDED
@@ -0,0 +1,370 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import type { Stats } from "node:fs";
3
+ import { chmod, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
4
+ import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
5
+ import picomatch from "picomatch";
6
+ import { scanComments } from "./scanner.js";
7
+ import type { FileScanResult } from "./types.js";
8
+
9
+ const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"];
10
+ const DEFAULT_IGNORE_DIRS = ["node_modules", ".git"];
11
+
12
+ export interface CollectOptions {
13
+ /** File extensions to include (with or without a leading dot, case-insensitive). */
14
+ extensions?: string[];
15
+ /**
16
+ * Directory names that are never traversed, input directories included
17
+ * (case-insensitively on Windows). Default: node_modules, .git
18
+ */
19
+ ignoreDirs?: string[];
20
+ /**
21
+ * Glob patterns for files and directories to skip (picomatch syntax).
22
+ * Patterns without a slash match against base names, e.g. `*.test.ts`.
23
+ * Explicitly listed input files bypass these patterns.
24
+ */
25
+ ignore?: string[];
26
+ }
27
+
28
+ type IgnoreMatcher = (path: string, root: string) => boolean;
29
+
30
+ export async function collectFiles(inputs: string[], options: CollectOptions = {}): Promise<string[]> {
31
+ const extensions = normalizeExtensions(options.extensions ?? DEFAULT_EXTENSIONS);
32
+ const ignoreDirs = new Set((options.ignoreDirs ?? DEFAULT_IGNORE_DIRS).map(foldName));
33
+ const isIgnored = buildIgnoreMatcher(options.ignore ?? []);
34
+ // Keyed by the real path so different spellings of one file (relative vs
35
+ // absolute, `.` segments, case on Windows, symlink aliases) collapse into a
36
+ // single entry; the first spelling seen is the one reported.
37
+ const found = new Map<string, string>();
38
+ const remember = (path: string, realPath: string): void => {
39
+ const key = canonicalKey(realPath);
40
+ if (!found.has(key)) found.set(key, path);
41
+ };
42
+
43
+ // Walks remember their discoveries mid-traversal; explicitly listed files
44
+ // are resolved concurrently but remembered afterwards in input order, so
45
+ // which spelling of an aliased file gets reported never depends on
46
+ // filesystem timing.
47
+ const explicitFiles = new Array<{ path: string; real: string } | undefined>(inputs.length);
48
+ await Promise.all(
49
+ inputs.map(async (rawInput, index) => {
50
+ if (rawInput === "") {
51
+ // normalize("") would resolve to "." and silently widen the scan.
52
+ throw new Error("empty path is not a valid input");
53
+ }
54
+ const input = normalize(rawInput);
55
+ const info = await statInput(input);
56
+ if (info.isDirectory()) {
57
+ // Directory inputs are themselves subject to the ignored directory
58
+ // names and the ignore patterns; only explicitly listed files bypass
59
+ // them.
60
+ if (!ignoreDirs.has(foldName(basename(input))) && !isIgnored(input, input)) {
61
+ await walk(input, { extensions, ignoreDirs, isIgnored, root: input, visited: new Set() }, remember);
62
+ }
63
+ } else {
64
+ explicitFiles[index] = { path: input, real: await realpathInput(input) };
65
+ }
66
+ }),
67
+ );
68
+ for (const file of explicitFiles) {
69
+ if (file !== undefined) remember(file.path, file.real);
70
+ }
71
+
72
+ return [...found.values()].sort();
73
+ }
74
+
75
+ function canonicalKey(path: string): string {
76
+ const resolved = resolve(path);
77
+ // Windows paths are case-insensitive; a case-folded key keeps `Foo.ts` and
78
+ // `foo.ts` from being treated as two files.
79
+ return process.platform === "win32" ? resolved.toLowerCase() : resolved;
80
+ }
81
+
82
+ /** Folds directory names the way the platform compares them, matching canonicalKey. */
83
+ function foldName(name: string): string {
84
+ return process.platform === "win32" ? name.toLowerCase() : name;
85
+ }
86
+
87
+ async function statInput(input: string): Promise<Stats> {
88
+ try {
89
+ return await stat(input);
90
+ } catch (error) {
91
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
92
+ throw new Error(`path not found: ${input}`, { cause: error });
93
+ }
94
+ throw error;
95
+ }
96
+ }
97
+
98
+ /** Real path of an explicit input, with the same friendly error statInput gives. */
99
+ async function realpathInput(input: string): Promise<string> {
100
+ try {
101
+ return await realpath(input);
102
+ } catch (error) {
103
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
104
+ throw new Error(`path not found: ${input}`, { cause: error });
105
+ }
106
+ throw error;
107
+ }
108
+ }
109
+
110
+ /**
111
+ * True for the errors a walk may step over: entries that vanished mid-walk
112
+ * (ENOENT, ENOTDIR after a directory was replaced) and symlinks that do not
113
+ * resolve (broken targets, ELOOP cycles). Anything else — permissions, I/O
114
+ * failures — propagates, so a partial scan cannot masquerade as a clean one.
115
+ */
116
+ function isSkippableWalkError(error: unknown): boolean {
117
+ const code = (error as NodeJS.ErrnoException).code;
118
+ return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
119
+ }
120
+
121
+ interface WalkContext {
122
+ extensions: string[];
123
+ ignoreDirs: Set<string>;
124
+ isIgnored: IgnoreMatcher;
125
+ /** Top-level directory this walk started from; ignore globs also match relative to it. */
126
+ root: string;
127
+ /** Real paths of directories already walked, so symlink cycles and diamonds terminate. */
128
+ visited: Set<string>;
129
+ }
130
+
131
+ async function walk(
132
+ dir: string,
133
+ context: WalkContext,
134
+ remember: (path: string, realPath: string) => void,
135
+ ): Promise<void> {
136
+ let real: string;
137
+ try {
138
+ real = await realpath(dir);
139
+ } catch (error) {
140
+ if (isSkippableWalkError(error)) return; // the directory vanished mid-walk
141
+ throw error;
142
+ }
143
+ if (context.visited.has(real)) return;
144
+ context.visited.add(real);
145
+
146
+ const entries = await readdir(dir, { withFileTypes: true });
147
+
148
+ await Promise.all(
149
+ entries.map(async (entry) => {
150
+ const full = join(dir, entry.name);
151
+ let isDirectory = entry.isDirectory();
152
+ let isFile = entry.isFile();
153
+ if (entry.isSymbolicLink()) {
154
+ // Symlinks are followed, matching how explicitly listed inputs are
155
+ // stat()ed; the visited set above keeps cycles from recursing forever.
156
+ try {
157
+ const info = await stat(full);
158
+ isDirectory = info.isDirectory();
159
+ isFile = info.isFile();
160
+ } catch (error) {
161
+ if (isSkippableWalkError(error)) return; // broken symlink
162
+ throw error;
163
+ }
164
+ }
165
+ if (isDirectory) {
166
+ if (!context.ignoreDirs.has(foldName(entry.name)) && !context.isIgnored(full, context.root)) {
167
+ await walk(full, context, remember);
168
+ }
169
+ } else if (isFile && hasExtension(entry.name, context.extensions) && !context.isIgnored(full, context.root)) {
170
+ // Remembered under its real path, so several symlinks to one target
171
+ // (or a link plus the target itself) count — and get rewritten — once.
172
+ let realFile: string;
173
+ try {
174
+ realFile = await realpath(full);
175
+ } catch (error) {
176
+ if (isSkippableWalkError(error)) return; // the file vanished mid-walk
177
+ throw error;
178
+ }
179
+ remember(full, realFile);
180
+ }
181
+ }),
182
+ );
183
+ }
184
+
185
+ function normalizeExtensions(extensions: string[]): string[] {
186
+ return extensions.map((extension) => {
187
+ const withDot = extension.startsWith(".") ? extension : `.${extension}`;
188
+ return withDot.toLowerCase();
189
+ });
190
+ }
191
+
192
+ /** Suffix match so compound extensions like `.d.ts` work; `extname` would only see `.ts`. */
193
+ function hasExtension(name: string, extensions: string[]): boolean {
194
+ const lower = name.toLowerCase();
195
+ return extensions.some((extension) => lower.endsWith(extension));
196
+ }
197
+
198
+ function buildIgnoreMatcher(patterns: string[]): IgnoreMatcher {
199
+ if (patterns.length === 0) return () => false;
200
+
201
+ // Gitignore-like split: patterns without a slash match base names, patterns
202
+ // with a slash match whole paths. (picomatch's `basename` option would apply
203
+ // to every pattern, breaking path globs, so two matchers are needed.)
204
+ const matchers: Array<(path: string) => boolean> = [];
205
+ const byBasename = patterns.filter((pattern) => !pattern.includes("/"));
206
+ const byPath = patterns.filter((pattern) => pattern.includes("/"));
207
+ if (byBasename.length > 0) matchers.push(picomatch(byBasename, { dot: true, basename: true }));
208
+ if (byPath.length > 0) matchers.push(picomatch(byPath, { dot: true }));
209
+ const match = (path: string): boolean => matchers.some((matcher) => matcher(path));
210
+
211
+ // Anchored patterns like `src/legacy/**` are tried against the path as
212
+ // spelled, relative to the scanned root, and relative to the working
213
+ // directory, so they work regardless of where the scan was started from.
214
+ return (path, root) => {
215
+ if (match(toPosix(path))) return true;
216
+ return relativeMatches(root, path, match) || relativeMatches(process.cwd(), path, match);
217
+ };
218
+ }
219
+
220
+ function relativeMatches(base: string, path: string, match: (path: string) => boolean): boolean {
221
+ const relativePath = relative(base, path);
222
+ if (relativePath === "" || isAbsolute(relativePath)) return false;
223
+ // Only a leading `..` *segment* means "outside the base": a directory that
224
+ // merely starts with two dots (`..hidden`) is inside it and must still be
225
+ // matched against the ignore globs.
226
+ if (relativePath === ".." || relativePath.startsWith(`..${sep}`)) return false;
227
+ return match(toPosix(relativePath));
228
+ }
229
+
230
+ function toPosix(path: string): string {
231
+ return sep === "/" ? path : path.split(sep).join("/");
232
+ }
233
+
234
+ export function isJsxFile(file: string): boolean {
235
+ const lower = file.toLowerCase();
236
+ return lower.endsWith(".tsx") || lower.endsWith(".jsx");
237
+ }
238
+
239
+ export type FileEncoding = "utf8" | "utf16le" | "utf16be";
240
+
241
+ export interface FileText {
242
+ /** Decoded content with any byte-order mark stripped. */
243
+ text: string;
244
+ encoding: FileEncoding;
245
+ /** Whether the file carried a byte-order mark. */
246
+ bom: boolean;
247
+ /**
248
+ * Whether re-encoding `text` reproduces the original bytes exactly. False
249
+ * for invalid UTF-8 (decoded with replacement characters), truncated
250
+ * UTF-16 and other undecodable input; such files must not be rewritten.
251
+ */
252
+ lossless: boolean;
253
+ }
254
+
255
+ /**
256
+ * Decodes a source file. UTF-16 (either endianness) is recognised by its
257
+ * byte-order mark; everything else is treated as UTF-8. Positions reported by
258
+ * the scanner are relative to the decoded, BOM-stripped text, matching
259
+ * editors, GitHub annotations and the removal report.
260
+ */
261
+ export function decodeFileText(data: Buffer): FileText {
262
+ let encoding: FileEncoding = "utf8";
263
+ let bom = false;
264
+ let body = data;
265
+ if (data.length >= 2 && data[0] === 0xff && data[1] === 0xfe) {
266
+ encoding = "utf16le";
267
+ bom = true;
268
+ body = data.subarray(2);
269
+ } else if (data.length >= 2 && data[0] === 0xfe && data[1] === 0xff) {
270
+ encoding = "utf16be";
271
+ bom = true;
272
+ body = data.subarray(2);
273
+ } else if (data.length >= 3 && data[0] === 0xef && data[1] === 0xbb && data[2] === 0xbf) {
274
+ bom = true;
275
+ body = data.subarray(3);
276
+ }
277
+ const text = encoding === "utf16be" ? decodeUtf16Be(body) : body.toString(encoding);
278
+ const lossless = encodeFileText(text, { encoding, bom }).equals(data);
279
+ return { text, encoding, bom, lossless };
280
+ }
281
+
282
+ function decodeUtf16Be(body: Buffer): string {
283
+ // swap16() refuses odd-length buffers; drop the dangling byte the same way
284
+ // the LE decoder does and let the lossless round-trip flag the truncation.
285
+ const even = body.length % 2 === 0 ? body : body.subarray(0, body.length - 1);
286
+ return Buffer.from(even).swap16().toString("utf16le");
287
+ }
288
+
289
+ /**
290
+ * Re-encodes decoded text in the encoding (and BOM) it was read with. Note
291
+ * that `bom: false` UTF-16 output cannot be recognised by decodeFileText,
292
+ * which identifies UTF-16 by its byte-order mark — request it only for
293
+ * consumers that expect mark-less UTF-16.
294
+ */
295
+ export function encodeFileText(text: string, target: { encoding: FileEncoding; bom: boolean }): Buffer {
296
+ const body =
297
+ target.encoding === "utf16le"
298
+ ? Buffer.from(text, "utf16le")
299
+ : target.encoding === "utf16be"
300
+ ? Buffer.from(text, "utf16le").swap16()
301
+ : Buffer.from(text, "utf8");
302
+ if (!target.bom) return body;
303
+ const bom =
304
+ target.encoding === "utf16le"
305
+ ? Buffer.from([0xff, 0xfe])
306
+ : target.encoding === "utf16be"
307
+ ? Buffer.from([0xfe, 0xff])
308
+ : Buffer.from([0xef, 0xbb, 0xbf]);
309
+ return Buffer.concat([bom, body]);
310
+ }
311
+
312
+ export async function readFileText(file: string): Promise<FileText> {
313
+ return decodeFileText(await readFile(file));
314
+ }
315
+
316
+ /**
317
+ * Replaces a file's content atomically: the data is written to a temporary
318
+ * sibling, flushed, and renamed into place, so a crash, full disk or write
319
+ * error can never leave the target truncated. Symlinks are followed (the
320
+ * link's target is replaced, not the link) and the file mode is preserved.
321
+ */
322
+ export async function writeFileAtomic(file: string, data: Buffer): Promise<void> {
323
+ const target = await realpath(file);
324
+ const mode = (await stat(target)).mode;
325
+ const temp = join(dirname(target), `.${basename(target)}.${randomUUID()}.tmp`);
326
+ try {
327
+ const handle = await open(temp, "wx", mode);
328
+ try {
329
+ await handle.writeFile(data);
330
+ await handle.sync();
331
+ } finally {
332
+ await handle.close();
333
+ }
334
+ // open()'s mode is filtered through the umask; restore the original exactly.
335
+ await chmod(temp, mode & 0o7777);
336
+ await rename(temp, target);
337
+ } catch (error) {
338
+ await rm(temp, { force: true }).catch(() => undefined);
339
+ throw error;
340
+ }
341
+ }
342
+
343
+ export async function scanFile(file: string): Promise<FileScanResult> {
344
+ const { text } = await readFileText(file);
345
+ return { file, comments: scanComments(text, { jsx: isJsxFile(file) }) };
346
+ }
347
+
348
+ export async function scanPaths(inputs: string[], options: CollectOptions = {}): Promise<FileScanResult[]> {
349
+ const files = await collectFiles(inputs, options);
350
+ return mapLimit(files, FILE_CONCURRENCY, scanFile);
351
+ }
352
+
353
+ export const FILE_CONCURRENCY = 16;
354
+
355
+ /** Concurrency-limited map that keeps input order and starts work as slots free up. */
356
+ export async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
357
+ const results = new Array<R>(items.length);
358
+ let nextIndex = 0;
359
+
360
+ const claimNext = async (): Promise<void> => {
361
+ const index = nextIndex;
362
+ nextIndex += 1;
363
+ if (index >= items.length) return;
364
+ results[index] = await fn(items[index] as T);
365
+ return claimNext();
366
+ };
367
+
368
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, claimNext));
369
+ return results;
370
+ }
package/src/git.ts ADDED
@@ -0,0 +1,72 @@
1
+ import { execFile } from "node:child_process";
2
+ import { realpath } from "node:fs/promises";
3
+ import { resolve } from "node:path";
4
+ import { promisify } from "node:util";
5
+
6
+ const execFileAsync = promisify(execFile);
7
+
8
+ /** --name-only output stays tiny even for huge diffs; this is pure headroom. */
9
+ const MAX_OUTPUT_BYTES = 64 * 1024 * 1024;
10
+
11
+ /**
12
+ * Absolute paths of the working-tree files touched in a git revision range.
13
+ * The range is anything `git diff` accepts as revisions: a single commit-ish
14
+ * compares the working tree against it (`HEAD` covers all uncommitted work,
15
+ * untracked files included), while `a..b` and `a...b` compare commits. Files
16
+ * deleted in the range are omitted because they have no working-tree content
17
+ * left, and renames are reported at their new path.
18
+ */
19
+ export async function changedFiles(range: string, cwd: string = process.cwd()): Promise<string[]> {
20
+ if (range === "" || range.startsWith("-")) {
21
+ // Never let the range reach git where it could parse as an option (--output=...).
22
+ throw new Error(`invalid git revision range: ${JSON.stringify(range)}`);
23
+ }
24
+ const top = (await git(["rev-parse", "--show-toplevel"], cwd)).replace(/\r?\n$/, "");
25
+ const root = await realpath(top);
26
+ // --no-relative pins root-relative output even under diff.relative=true.
27
+ const args = ["diff", "--name-only", "-z", "--no-renames", "--no-relative", "--diff-filter=d", range, "--"];
28
+ const entries = split(await git(args, cwd));
29
+ // A working-tree comparison treats brand-new files as changes too, yet
30
+ // `git diff` never lists them. Runs at the root so the whole repository is
31
+ // covered regardless of cwd; .gitignore still applies.
32
+ if (await comparesWorkingTree(range, cwd)) {
33
+ entries.push(...split(await git(["ls-files", "--others", "--exclude-standard", "--full-name", "-z"], root)));
34
+ }
35
+ return [...new Set(entries)].map((entry) => resolve(root, entry));
36
+ }
37
+
38
+ /**
39
+ * `git diff` compares the working tree only against a lone revision — negated
40
+ * (`^HEAD`) or not; every other shape (`a..b`, `a...b`, `HEAD^!`,
41
+ * multi-parent `HEAD^@`) compares commits. String sniffing cannot tell these
42
+ * apart — `HEAD^!` contains no ".." yet excludes the working tree — so ask
43
+ * rev-parse for the expansion and check for exactly one revision.
44
+ */
45
+ async function comparesWorkingTree(range: string, cwd: string): Promise<boolean> {
46
+ const revs = (await git(["rev-parse", "--revs-only", range, "--"], cwd)).split("\n").filter((line) => line !== "");
47
+ return revs.length === 1;
48
+ }
49
+
50
+ function split(listing: string): string[] {
51
+ return listing.split("\0").filter((entry) => entry !== "");
52
+ }
53
+
54
+ async function git(args: string[], cwd: string): Promise<string> {
55
+ try {
56
+ const { stdout } = await execFileAsync("git", args, { cwd, maxBuffer: MAX_OUTPUT_BYTES });
57
+ return stdout;
58
+ } catch (error) {
59
+ throw new Error(describeFailure(args[0] as string, error), { cause: error });
60
+ }
61
+ }
62
+
63
+ function describeFailure(subcommand: string, error: unknown): string {
64
+ const failure = error as { code?: unknown; stderr?: unknown; message?: unknown };
65
+ if (failure.code === "ENOENT") {
66
+ return "git executable not found (is git installed and on PATH?)";
67
+ }
68
+ const stderr = typeof failure.stderr === "string" ? failure.stderr.trim() : "";
69
+ const newline = stderr.indexOf("\n");
70
+ const detail = stderr === "" ? String(failure.message ?? error) : newline === -1 ? stderr : stderr.slice(0, newline);
71
+ return `git ${subcommand} failed: ${detail}`;
72
+ }
package/src/index.ts ADDED
@@ -0,0 +1,19 @@
1
+ export { scanComments, type ScanOptions } from "./scanner.js";
2
+ export {
3
+ collectFiles,
4
+ decodeFileText,
5
+ encodeFileText,
6
+ isJsxFile,
7
+ readFileText,
8
+ scanFile,
9
+ scanPaths,
10
+ writeFileAtomic,
11
+ type CollectOptions,
12
+ type FileEncoding,
13
+ type FileText,
14
+ } from "./files.js";
15
+ export { changedFiles } from "./git.js";
16
+ export { removeComments, type RemoveOptions, type RemoveResult } from "./remove.js";
17
+ export { detectDirective, isLegalComment, type DirectivePlacement } from "./directives.js";
18
+ export { formatText, formatJson, formatGitHub } from "./report.js";
19
+ export type { Comment, CommentKind, FileScanResult } from "./types.js";