@kongyo2/ts-comment-scanner 1.3.0 → 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/files.ts ADDED
@@ -0,0 +1,304 @@
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
+ /** Directory names that are never traversed. Default: node_modules, .git */
16
+ ignoreDirs?: string[];
17
+ /**
18
+ * Glob patterns for files and directories to skip (picomatch syntax).
19
+ * Patterns without a slash match against base names, e.g. `*.test.ts`.
20
+ * Explicitly listed input files bypass these patterns.
21
+ */
22
+ ignore?: string[];
23
+ }
24
+
25
+ type IgnoreMatcher = (path: string, root: string) => boolean;
26
+
27
+ export async function collectFiles(inputs: string[], options: CollectOptions = {}): Promise<string[]> {
28
+ const extensions = normalizeExtensions(options.extensions ?? DEFAULT_EXTENSIONS);
29
+ const ignoreDirs = new Set(options.ignoreDirs ?? DEFAULT_IGNORE_DIRS);
30
+ const isIgnored = buildIgnoreMatcher(options.ignore ?? []);
31
+ // Keyed by the resolved path so different spellings of one file (relative vs
32
+ // absolute, `.` segments, case on Windows) collapse into a single entry; the
33
+ // first spelling seen is the one reported.
34
+ const found = new Map<string, string>();
35
+ const remember = (path: string): void => {
36
+ const key = canonicalKey(path);
37
+ if (!found.has(key)) found.set(key, path);
38
+ };
39
+
40
+ await Promise.all(
41
+ inputs.map(async (rawInput) => {
42
+ if (rawInput === "") {
43
+ // normalize("") would resolve to "." and silently widen the scan.
44
+ throw new Error("empty path is not a valid input");
45
+ }
46
+ const input = normalize(rawInput);
47
+ const info = await statInput(input);
48
+ if (info.isDirectory()) {
49
+ // Directory inputs are themselves subject to the ignore patterns;
50
+ // only explicitly listed files bypass them.
51
+ if (!isIgnored(input, input)) {
52
+ await walk(input, { extensions, ignoreDirs, isIgnored, root: input, visited: new Set() }, remember);
53
+ }
54
+ } else {
55
+ remember(input);
56
+ }
57
+ }),
58
+ );
59
+
60
+ return [...found.values()].sort();
61
+ }
62
+
63
+ function canonicalKey(path: string): string {
64
+ const resolved = resolve(path);
65
+ // Windows paths are case-insensitive; a case-folded key keeps `Foo.ts` and
66
+ // `foo.ts` from being treated as two files.
67
+ return process.platform === "win32" ? resolved.toLowerCase() : resolved;
68
+ }
69
+
70
+ async function statInput(input: string): Promise<Stats> {
71
+ try {
72
+ return await stat(input);
73
+ } catch (error) {
74
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") {
75
+ throw new Error(`path not found: ${input}`, { cause: error });
76
+ }
77
+ throw error;
78
+ }
79
+ }
80
+
81
+ interface WalkContext {
82
+ extensions: string[];
83
+ ignoreDirs: Set<string>;
84
+ isIgnored: IgnoreMatcher;
85
+ /** Top-level directory this walk started from; ignore globs also match relative to it. */
86
+ root: string;
87
+ /** Real paths of directories already walked, so symlink cycles and diamonds terminate. */
88
+ visited: Set<string>;
89
+ }
90
+
91
+ async function walk(dir: string, context: WalkContext, remember: (path: string) => void): Promise<void> {
92
+ let real: string;
93
+ try {
94
+ real = await realpath(dir);
95
+ } catch {
96
+ return; // the directory vanished mid-walk
97
+ }
98
+ if (context.visited.has(real)) return;
99
+ context.visited.add(real);
100
+
101
+ const entries = await readdir(dir, { withFileTypes: true });
102
+
103
+ await Promise.all(
104
+ entries.map(async (entry) => {
105
+ const full = join(dir, entry.name);
106
+ let isDirectory = entry.isDirectory();
107
+ let isFile = entry.isFile();
108
+ if (entry.isSymbolicLink()) {
109
+ // Symlinks are followed, matching how explicitly listed inputs are
110
+ // stat()ed; the visited set above keeps cycles from recursing forever.
111
+ try {
112
+ const info = await stat(full);
113
+ isDirectory = info.isDirectory();
114
+ isFile = info.isFile();
115
+ } catch {
116
+ return; // broken symlink
117
+ }
118
+ }
119
+ if (isDirectory) {
120
+ if (!context.ignoreDirs.has(entry.name) && !context.isIgnored(full, context.root)) {
121
+ await walk(full, context, remember);
122
+ }
123
+ } else if (isFile && hasExtension(entry.name, context.extensions) && !context.isIgnored(full, context.root)) {
124
+ remember(full);
125
+ }
126
+ }),
127
+ );
128
+ }
129
+
130
+ function normalizeExtensions(extensions: string[]): string[] {
131
+ return extensions.map((extension) => {
132
+ const withDot = extension.startsWith(".") ? extension : `.${extension}`;
133
+ return withDot.toLowerCase();
134
+ });
135
+ }
136
+
137
+ /** Suffix match so compound extensions like `.d.ts` work; `extname` would only see `.ts`. */
138
+ function hasExtension(name: string, extensions: string[]): boolean {
139
+ const lower = name.toLowerCase();
140
+ return extensions.some((extension) => lower.endsWith(extension));
141
+ }
142
+
143
+ function buildIgnoreMatcher(patterns: string[]): IgnoreMatcher {
144
+ if (patterns.length === 0) return () => false;
145
+
146
+ // Gitignore-like split: patterns without a slash match base names, patterns
147
+ // with a slash match whole paths. (picomatch's `basename` option would apply
148
+ // to every pattern, breaking path globs, so two matchers are needed.)
149
+ const matchers: Array<(path: string) => boolean> = [];
150
+ const byBasename = patterns.filter((pattern) => !pattern.includes("/"));
151
+ const byPath = patterns.filter((pattern) => pattern.includes("/"));
152
+ if (byBasename.length > 0) matchers.push(picomatch(byBasename, { dot: true, basename: true }));
153
+ if (byPath.length > 0) matchers.push(picomatch(byPath, { dot: true }));
154
+ const match = (path: string): boolean => matchers.some((matcher) => matcher(path));
155
+
156
+ // Anchored patterns like `src/legacy/**` are tried against the path as
157
+ // spelled, relative to the scanned root, and relative to the working
158
+ // directory, so they work regardless of where the scan was started from.
159
+ return (path, root) => {
160
+ if (match(toPosix(path))) return true;
161
+ return relativeMatches(root, path, match) || relativeMatches(process.cwd(), path, match);
162
+ };
163
+ }
164
+
165
+ function relativeMatches(base: string, path: string, match: (path: string) => boolean): boolean {
166
+ const relativePath = relative(base, path);
167
+ if (relativePath === "" || isAbsolute(relativePath)) return false;
168
+ // Only a leading `..` *segment* means "outside the base": a directory that
169
+ // merely starts with two dots (`..hidden`) is inside it and must still be
170
+ // matched against the ignore globs.
171
+ if (relativePath === ".." || relativePath.startsWith(`..${sep}`)) return false;
172
+ return match(toPosix(relativePath));
173
+ }
174
+
175
+ function toPosix(path: string): string {
176
+ return sep === "/" ? path : path.split(sep).join("/");
177
+ }
178
+
179
+ export function isJsxFile(file: string): boolean {
180
+ const lower = file.toLowerCase();
181
+ return lower.endsWith(".tsx") || lower.endsWith(".jsx");
182
+ }
183
+
184
+ export type FileEncoding = "utf8" | "utf16le" | "utf16be";
185
+
186
+ export interface FileText {
187
+ /** Decoded content with any byte-order mark stripped. */
188
+ text: string;
189
+ encoding: FileEncoding;
190
+ /** Whether the file carried a byte-order mark. */
191
+ bom: boolean;
192
+ /**
193
+ * Whether re-encoding `text` reproduces the original bytes exactly. False
194
+ * for invalid UTF-8 (decoded with replacement characters), truncated
195
+ * UTF-16 and other undecodable input; such files must not be rewritten.
196
+ */
197
+ lossless: boolean;
198
+ }
199
+
200
+ /**
201
+ * Decodes a source file. UTF-16 (either endianness) is recognised by its
202
+ * byte-order mark; everything else is treated as UTF-8. Positions reported by
203
+ * the scanner are relative to the decoded, BOM-stripped text, matching
204
+ * editors, GitHub annotations and the removal report.
205
+ */
206
+ export function decodeFileText(data: Buffer): FileText {
207
+ let encoding: FileEncoding = "utf8";
208
+ let bom = false;
209
+ let body = data;
210
+ if (data.length >= 2 && data[0] === 0xff && data[1] === 0xfe) {
211
+ encoding = "utf16le";
212
+ bom = true;
213
+ body = data.subarray(2);
214
+ } else if (data.length >= 2 && data[0] === 0xfe && data[1] === 0xff) {
215
+ encoding = "utf16be";
216
+ bom = true;
217
+ body = data.subarray(2);
218
+ } else if (data.length >= 3 && data[0] === 0xef && data[1] === 0xbb && data[2] === 0xbf) {
219
+ bom = true;
220
+ body = data.subarray(3);
221
+ }
222
+ const text = encoding === "utf16be" ? decodeUtf16Be(body) : body.toString(encoding);
223
+ const lossless = encodeFileText(text, { encoding, bom }).equals(data);
224
+ return { text, encoding, bom, lossless };
225
+ }
226
+
227
+ function decodeUtf16Be(body: Buffer): string {
228
+ // swap16() refuses odd-length buffers; drop the dangling byte the same way
229
+ // the LE decoder does and let the lossless round-trip flag the truncation.
230
+ const even = body.length % 2 === 0 ? body : body.subarray(0, body.length - 1);
231
+ return Buffer.from(even).swap16().toString("utf16le");
232
+ }
233
+
234
+ /** Re-encodes decoded text in the encoding (and BOM) it was read with. */
235
+ export function encodeFileText(text: string, target: { encoding: FileEncoding; bom: boolean }): Buffer {
236
+ if (target.encoding === "utf16le") {
237
+ return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text, "utf16le")]);
238
+ }
239
+ if (target.encoding === "utf16be") {
240
+ return Buffer.concat([Buffer.from([0xfe, 0xff]), Buffer.from(text, "utf16le").swap16()]);
241
+ }
242
+ const bom = target.bom ? Buffer.from([0xef, 0xbb, 0xbf]) : Buffer.alloc(0);
243
+ return Buffer.concat([bom, Buffer.from(text, "utf8")]);
244
+ }
245
+
246
+ export async function readFileText(file: string): Promise<FileText> {
247
+ return decodeFileText(await readFile(file));
248
+ }
249
+
250
+ /**
251
+ * Replaces a file's content atomically: the data is written to a temporary
252
+ * sibling, flushed, and renamed into place, so a crash, full disk or write
253
+ * error can never leave the target truncated. Symlinks are followed (the
254
+ * link's target is replaced, not the link) and the file mode is preserved.
255
+ */
256
+ export async function writeFileAtomic(file: string, data: Buffer): Promise<void> {
257
+ const target = await realpath(file);
258
+ const mode = (await stat(target)).mode;
259
+ const temp = join(dirname(target), `.${basename(target)}.${randomUUID()}.tmp`);
260
+ try {
261
+ const handle = await open(temp, "wx", mode);
262
+ try {
263
+ await handle.writeFile(data);
264
+ await handle.sync();
265
+ } finally {
266
+ await handle.close();
267
+ }
268
+ // open()'s mode is filtered through the umask; restore the original exactly.
269
+ await chmod(temp, mode & 0o7777);
270
+ await rename(temp, target);
271
+ } catch (error) {
272
+ await rm(temp, { force: true }).catch(() => undefined);
273
+ throw error;
274
+ }
275
+ }
276
+
277
+ export async function scanFile(file: string): Promise<FileScanResult> {
278
+ const { text } = await readFileText(file);
279
+ return { file, comments: scanComments(text, { jsx: isJsxFile(file) }) };
280
+ }
281
+
282
+ export async function scanPaths(inputs: string[], options: CollectOptions = {}): Promise<FileScanResult[]> {
283
+ const files = await collectFiles(inputs, options);
284
+ return mapLimit(files, FILE_CONCURRENCY, scanFile);
285
+ }
286
+
287
+ export const FILE_CONCURRENCY = 16;
288
+
289
+ /** Concurrency-limited map that keeps input order and starts work as slots free up. */
290
+ export async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
291
+ const results = new Array<R>(items.length);
292
+ let nextIndex = 0;
293
+
294
+ const claimNext = async (): Promise<void> => {
295
+ const index = nextIndex;
296
+ nextIndex += 1;
297
+ if (index >= items.length) return;
298
+ results[index] = await fn(items[index] as T);
299
+ return claimNext();
300
+ };
301
+
302
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, claimNext));
303
+ return results;
304
+ }
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";