@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/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";
|