@kongyo2/ts-comment-scanner 1.21.0 → 1.23.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.
Files changed (66) hide show
  1. package/README.md +240 -52
  2. package/dist/astgrep.d.ts +4 -2
  3. package/dist/astgrep.d.ts.map +1 -1
  4. package/dist/astgrep.js +7 -4
  5. package/dist/astgrep.js.map +1 -1
  6. package/dist/containers.d.ts +48 -0
  7. package/dist/containers.d.ts.map +1 -0
  8. package/dist/containers.js +82 -0
  9. package/dist/containers.js.map +1 -0
  10. package/dist/coverage.d.ts +45 -0
  11. package/dist/coverage.d.ts.map +1 -0
  12. package/dist/coverage.js +92 -0
  13. package/dist/coverage.js.map +1 -0
  14. package/dist/directives.d.ts +13 -3
  15. package/dist/directives.d.ts.map +1 -1
  16. package/dist/directives.js +31 -11
  17. package/dist/directives.js.map +1 -1
  18. package/dist/files.d.ts +5 -0
  19. package/dist/files.d.ts.map +1 -1
  20. package/dist/files.js +103 -41
  21. package/dist/files.js.map +1 -1
  22. package/dist/imports.d.ts +12 -5
  23. package/dist/imports.d.ts.map +1 -1
  24. package/dist/imports.js +33 -10
  25. package/dist/imports.js.map +1 -1
  26. package/dist/index.d.ts +1 -1
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +1 -1
  29. package/dist/index.js.map +1 -1
  30. package/dist/lines.d.ts +11 -0
  31. package/dist/lines.d.ts.map +1 -1
  32. package/dist/lines.js +30 -0
  33. package/dist/lines.js.map +1 -1
  34. package/dist/remove.d.ts +16 -12
  35. package/dist/remove.d.ts.map +1 -1
  36. package/dist/remove.js +51 -638
  37. package/dist/remove.js.map +1 -1
  38. package/dist/run.d.ts.map +1 -1
  39. package/dist/run.js +11 -10
  40. package/dist/run.js.map +1 -1
  41. package/dist/scanner.d.ts +29 -0
  42. package/dist/scanner.d.ts.map +1 -1
  43. package/dist/scanner.js +122 -5
  44. package/dist/scanner.js.map +1 -1
  45. package/dist/shields.d.ts +77 -0
  46. package/dist/shields.d.ts.map +1 -0
  47. package/dist/shields.js +758 -0
  48. package/dist/shields.js.map +1 -0
  49. package/dist/splice.d.ts +40 -15
  50. package/dist/splice.d.ts.map +1 -1
  51. package/dist/splice.js +185 -69
  52. package/dist/splice.js.map +1 -1
  53. package/package.json +6 -5
  54. package/src/astgrep.ts +7 -5
  55. package/src/containers.ts +128 -0
  56. package/src/coverage.ts +110 -0
  57. package/src/directives.ts +45 -11
  58. package/src/files.ts +147 -53
  59. package/src/imports.ts +42 -17
  60. package/src/index.ts +1 -0
  61. package/src/lines.ts +33 -1
  62. package/src/remove.ts +58 -748
  63. package/src/run.ts +11 -10
  64. package/src/scanner.ts +160 -5
  65. package/src/shields.ts +852 -0
  66. package/src/splice.ts +216 -75
package/src/astgrep.ts CHANGED
@@ -74,8 +74,10 @@ export interface AstGrepReach {
74
74
  * when deleted, so those ending on its row in front of it stay, as do those
75
75
  * after it on its row and those touching the row its node starts on; when a
76
76
  * release covers the next row, so do those starting there, and that row's
77
- * lines stay (see nextRow). On the first row, the units after it on the row
78
- * it ends on stay as well: the next node decides whether it covers the file.
77
+ * lines stay (see nextRow). On the first row, the node after the comment
78
+ * decides whether it covers the file: where that node starts less than two
79
+ * rows down, the unit it is stays, since whatever follows it could start
80
+ * further down.
79
81
  * The releases this follows parse with tree-sitter 0.24 or later (ast-grep
80
82
  * 0.31.1 on); before, comments in JSX braces read as standing alone.
81
83
  */
@@ -99,12 +101,12 @@ export function astGrepReach(
99
101
  if (precedingRow !== undefined && precedingRow < row) {
100
102
  breaking.push({ start: rowStart(precedingRow), end: rowStart(precedingRow + 1) });
101
103
  }
102
- const nextNode =
103
- endRow < 2 && opensFirstRow(text, comment.start) ? { start: comment.end, end: rowStart(endRow + 1) } : undefined;
104
+ const next = comment.end + text.slice(comment.end).search(TREE_SITTER_CONTENT);
105
+ const nextNode = opensFirstRow(text, comment.start) && next >= comment.end && next < rowStart(2) ? next : undefined;
104
106
  return {
105
107
  holds: (unit) =>
106
108
  (unit.end > ownRow && unit.end <= comment.start && (unit.start >= preceding.tokenEnd || breaks(unit))) ||
107
- (nextNode !== undefined && unit.start >= nextNode.start && unit.start < nextNode.end) ||
109
+ unit.start === nextNode ||
108
110
  (breaking.some((span) => unit.start < span.end && unit.end >= span.start) && breaks(unit)),
109
111
  nextRow: coversNextRow ? { start: comment.end, end: rowStart(row + 2) } : undefined,
110
112
  };
@@ -0,0 +1,128 @@
1
+ import type { JsxContainer } from "./jsx.js";
2
+ import { LINE_TERMINATOR, isHorizontalSpace, opensItsLine } from "./lines.js";
3
+ import { rangesWithin, type Range } from "./ranges.js";
4
+ import type { Comment } from "./types.js";
5
+
6
+ /**
7
+ * How a comment-only JSX container goes once all its comments do: braces
8
+ * and all; replaced by `{" "}` together with the spaces that held it off its
9
+ * neighbour; or with its braces kept, only the comments going.
10
+ */
11
+ type ContainerMode = "drop" | "space" | "keep";
12
+
13
+ /** A comment-only JSX container (`{/* note *​/}`) with the comments in it. */
14
+ export interface Container extends Range {
15
+ segment: number;
16
+ suspect: boolean;
17
+ /** The comment-only container right after it among the siblings, if any. */
18
+ next: Container | undefined;
19
+ comments: Comment[];
20
+ mode: ContainerMode;
21
+ /** What `{" "}` would replace, when the container shares its line and is held off by spaces. */
22
+ spaceRange: Range | undefined;
23
+ }
24
+
25
+ export function attachContainers(
26
+ source: string,
27
+ layouts: readonly JsxContainer[],
28
+ comments: readonly Comment[],
29
+ ): Container[] {
30
+ const containers = new Map<JsxContainer, Container>();
31
+ for (const layout of layouts) {
32
+ containers.set(layout, {
33
+ start: layout.start,
34
+ end: layout.end,
35
+ segment: layout.segment,
36
+ suspect: layout.suspect,
37
+ next: undefined,
38
+ comments: rangesWithin(comments, layout),
39
+ mode: "drop",
40
+ spaceRange: spaceRange(source, layout),
41
+ });
42
+ }
43
+ for (const [layout, container] of containers) {
44
+ if (layout.next !== undefined) container.next = containers.get(layout.next);
45
+ }
46
+ return [...containers.values()];
47
+ }
48
+
49
+ /**
50
+ * The range `{" "}` would take the place of: a one-line container and the
51
+ * spaces before it when code precedes it on its line (`<b /> {/* x *​/}`), or
52
+ * the spaces after it when it opens its line and code follows. Undefined when
53
+ * no spaces hold it off anything on its line.
54
+ */
55
+ function spaceRange(source: string, container: Range): Range | undefined {
56
+ if (LINE_TERMINATOR.test(source.slice(container.start, container.end))) return undefined;
57
+ let before = container.start;
58
+ while (isHorizontalSpace(source[before - 1])) before -= 1;
59
+ let after = container.end;
60
+ while (isHorizontalSpace(source[after])) after += 1;
61
+
62
+ if (!opensItsLine(source, container)) {
63
+ return before < container.start ? { start: before, end: container.end } : undefined;
64
+ }
65
+ const codeAfter = after < source.length && !LINE_TERMINATOR.test(source[after] as string);
66
+ return codeAfter && after > container.end ? { start: container.start, end: after } : undefined;
67
+ }
68
+
69
+ /**
70
+ * The comments, in document order, with those of every container that
71
+ * `merges` accepts merged into the container itself: one unit spanning its
72
+ * braces in place of the comments inside them.
73
+ */
74
+ export function mergeContainers(
75
+ comments: readonly Comment[],
76
+ containerOf: ReadonlyMap<Comment, Container>,
77
+ merges: (container: Container) => boolean,
78
+ ): Array<Comment | Container> {
79
+ const units: Array<Comment | Container> = [];
80
+ for (const comment of comments) {
81
+ const container = containerOf.get(comment);
82
+ if (container === undefined || !merges(container)) units.push(comment);
83
+ else if (units.at(-1) !== container) units.push(container);
84
+ }
85
+ return units;
86
+ }
87
+
88
+ /** Whether the container's comments are all among the given ones, so that its braces can go with them. */
89
+ export function emptiedBy(container: Container, comments: ReadonlySet<Comment>): boolean {
90
+ return container.comments.every((comment) => comments.has(comment));
91
+ }
92
+
93
+ /**
94
+ * What deleting part of the removal takes out of the source: a single
95
+ * comment, or a comment-only JSX container going braces and all.
96
+ */
97
+ export interface RemovalUnit extends Range {
98
+ comments: readonly Comment[];
99
+ /** The unit is a container's braces, which go with the comments in them. */
100
+ braces: boolean;
101
+ }
102
+
103
+ /**
104
+ * The removals as the edits delete them: a comment-only container whose
105
+ * comments all go — and that is to go braces and all — is one unit spanning
106
+ * its braces, every other comment a unit of its own. Sorted, as the comments.
107
+ */
108
+ export function removalUnits(
109
+ removals: readonly Comment[],
110
+ containerOf: ReadonlyMap<Comment, Container>,
111
+ ): RemovalUnit[] {
112
+ const removing = new Set(removals);
113
+ const units = mergeContainers(
114
+ removals,
115
+ containerOf,
116
+ (container) => container.mode === "drop" && emptiedBy(container, removing),
117
+ );
118
+ return units.map((unit) => ({
119
+ start: unit.start,
120
+ end: unit.end,
121
+ ...("comments" in unit ? { comments: unit.comments, braces: true } : { comments: [unit], braces: false }),
122
+ }));
123
+ }
124
+
125
+ /** The comments the units delete. */
126
+ export function commentsOf(units: readonly RemovalUnit[]): Comment[] {
127
+ return units.flatMap((unit) => unit.comments);
128
+ }
@@ -0,0 +1,110 @@
1
+ import type { CommentKind } from "./types.js";
2
+
3
+ /**
4
+ * How the coverage tools that count lines read an `ignore next` hint. Each
5
+ * reads it its own way, on its own lines:
6
+ *
7
+ * - c8 (v8-to-istanbul's `source.js`) and Node's test runner (its
8
+ * `coverage.js`) search the file's text row by row, a row ending at a line
9
+ * feed alone, for the hint spelled as a block comment with single spaces —
10
+ * wherever that text stands: inside another comment, a string or a
11
+ * template too.
12
+ * - monocart-coverage-reports reads the comments themselves, on lines that
13
+ * every ECMAScript line terminator ends.
14
+ *
15
+ * istanbul and ast-v8-to-istanbul, Vitest's providers, apply the hint to the
16
+ * node after it instead, whatever count follows — ast-v8-to-istanbul only to
17
+ * the node that starts at the very token after the comment (see hintsNextNode).
18
+ */
19
+
20
+ // The text v8-to-istanbul looks for in a row; the form Node reads opens with it too.
21
+ const TEXT_HINT = /\/\* (?:[cv]8|node:coverage) ignore next/g;
22
+ // The count v8-to-istanbul reads right behind it.
23
+ const COUNT = / ([0-9]+)/y;
24
+ // Node's test runner wants the whole comment, a count and its space included.
25
+ const NODE_HINT = /\/\* node:coverage ignore next (\d+ )?\*\//y;
26
+
27
+ /** An `ignore next` hint in the text of a file, as the tools that search the text for it find it. */
28
+ export interface TextHint {
29
+ /** Where the hint's `/*` stands. */
30
+ offset: number;
31
+ /**
32
+ * The rows below its own that v8-to-istanbul ignores for it where the hint
33
+ * opens its row (see opensRow): the count behind it, or one. Anywhere else
34
+ * on a row the hint covers that row alone.
35
+ */
36
+ rows: number;
37
+ /** The rows below its own that Node's test runner ignores for it; none when Node does not read it. */
38
+ nodeRows: number;
39
+ }
40
+
41
+ /** The `ignore next` hints v8-to-istanbul and Node's test runner find in the text. */
42
+ export function textHints(source: string): TextHint[] {
43
+ const hints: TextHint[] = [];
44
+ for (const match of source.matchAll(TEXT_HINT)) {
45
+ COUNT.lastIndex = match.index + match[0].length;
46
+ NODE_HINT.lastIndex = match.index;
47
+ const node = NODE_HINT.exec(source);
48
+ hints.push({
49
+ offset: match.index,
50
+ rows: Number(COUNT.exec(source)?.[1] ?? 1),
51
+ nodeRows: node === null ? 0 : Number(node[1] ?? 1),
52
+ });
53
+ }
54
+ return hints;
55
+ }
56
+
57
+ /**
58
+ * Whether a hint that `prefix` precedes on its row opens the row to
59
+ * v8-to-istanbul, which then counts the rows below it: nothing but non-word
60
+ * characters stands in front of it (`^\W*` in its patterns), so `});` does
61
+ * not keep the hint from counting, and a comment that holds a word does.
62
+ */
63
+ export function opensRow(prefix: string): boolean {
64
+ return /^\W*$/.test(prefix);
65
+ }
66
+
67
+ /**
68
+ * The lines below the comment's last that monocart-coverage-reports ignores
69
+ * for it, or undefined when it reads no `ignore next` from the comment. It
70
+ * wants the trimmed value to open with `v8 ignore`, `c8 ignore` or
71
+ * `node:coverage`, and `next` (`ignore next` for Node's) to open what follows
72
+ * past any whitespace; then it takes the leading integer of the rest as the
73
+ * count (`next3` and `next 3x` count 3), and one line for anything else.
74
+ * Without a count, a block comment that something follows on its line —
75
+ * `trailing`, the rest of that line — covers no line below: the hint is for
76
+ * what follows it there.
77
+ */
78
+ export function monocartLines(kind: CommentKind, text: string, trailing: string): number | undefined {
79
+ const value = (kind === "block" ? text.slice(2, -2) : text.slice(2)).trim();
80
+ const tool = ["v8 ignore", "c8 ignore", "node:coverage"].find((name) => value.startsWith(name));
81
+ if (tool === undefined) return undefined;
82
+ const mode = tool === "node:coverage" ? "ignore next" : "next";
83
+ const rest = value.slice(tool.length).trim();
84
+ if (!rest.startsWith(mode)) return undefined;
85
+ const count = rest.slice(mode.length).trim();
86
+ // (monocart calls parseInt without a radix.)
87
+ if (count !== "") return Math.max(1, Number.parseInt(count) || 1);
88
+ return kind === "block" && trailing.trim() !== "" ? 0 : 1;
89
+ }
90
+
91
+ // What ast-v8-to-istanbul wants at the start of a comment's text, its delimiters cut off.
92
+ const NEXT_NODE_HINT = /^\s*(?:istanbul|[cv]8|node:coverage)\s+ignore\s+(?:if|else|next)(?=\W|$)/;
93
+
94
+ /**
95
+ * Whether ast-v8-to-istanbul, Vitest's v8 provider, reads a hint for the next
96
+ * node from the comment: `ignore next`, `ignore if` or `ignore else` at the
97
+ * start of its text (`getIgnoreHints` in its ignore-hints.ts). It applies
98
+ * such a hint to the node starting at the first token after the comment, so
99
+ * a hint that another comment follows has no target. A hint further into the
100
+ * text (`// see /* c8 ignore next *​/`) is c8's to read, not this tool's.
101
+ */
102
+ export function hintsNextNode(text: string): boolean {
103
+ const value = text
104
+ .replace(/^\/\*\*/, "")
105
+ .replace(/^\/\*/, "")
106
+ .replace(/\*\*\/$/, "")
107
+ .replace(/\*\/$/, "")
108
+ .replace(/^\/\//, "");
109
+ return NEXT_NODE_HINT.test(value);
110
+ }
package/src/directives.ts CHANGED
@@ -82,6 +82,28 @@ function stylelintDirective(token: string): string | undefined {
82
82
  return STYLELINT_COMMANDS.has(command) ? `${STYLELINT_MARKER}${command}` : undefined;
83
83
  }
84
84
 
85
+ // The comment texts dprint's TypeScript plugin takes for its node pragma: its
86
+ // own default, and the one `deno fmt` configures it with.
87
+ const DPRINT_IGNORE_MARKERS = ["dprint-ignore", "deno-fmt-ignore"] as const;
88
+
89
+ /**
90
+ * Whether dprint leaves the node after a comment with this value as it is
91
+ * (`text_has_dprint_ignore` in dprint-core): it looks at the first place the
92
+ * marker stands in the text alone, and wants no letter or digit right after
93
+ * it, and none in the byte right before it — which a character outside ASCII
94
+ * never ends in. So `xdprint-ignore` and `dprint-ignoreé` are no pragmas, and
95
+ * neither is a second marker behind one of them, while `édprint-ignore` is
96
+ * one. Checked against dprint 0.65.0 with its TypeScript plugin 0.101.0.
97
+ */
98
+ function ignoresForDprint(value: string, marker: string): boolean {
99
+ const at = value.indexOf(marker);
100
+ return (
101
+ at !== -1 &&
102
+ !/[A-Za-z0-9]/.test(value.charAt(at - 1)) &&
103
+ !/^[\p{Alphabetic}\p{N}]/u.test(value.slice(at + marker.length))
104
+ );
105
+ }
106
+
85
107
  // Prettier's FORMAT_PRAGMAS and FORMAT_IGNORE_PRAGMAS (its
86
108
  // `src/utilities/pragma/pragma.evaluate.js`): the docblock keys that
87
109
  // --require-pragma looks for and --check-ignore-pragma stops on.
@@ -235,7 +257,7 @@ const RULES: DirectiveRule[] = [
235
257
  // marker or a different case leave the comment inert — as does a JSDoc star
236
258
  // after `/**`, which postcss keeps as comment text (hence keepStars). `//`
237
259
  // comments count too: postcss-scss and postcss-less hand stylelint the same
238
- // trimmed text. Verified against stylelint 17.16. A project-specific
260
+ // trimmed text. Verified against stylelint 17.16 and 18.1. A project-specific
239
261
  // `configurationComment` prefix cannot be known here, so only the default
240
262
  // marker is matched.
241
263
  { pattern: /^\S+/, keepStars: true, name: (match) => stylelintDirective(match[0]) },
@@ -255,17 +277,18 @@ const RULES: DirectiveRule[] = [
255
277
  // pragma is a starts-with check on the file's leading comments, after only
256
278
  // spaces in a `//` comment and any whitespace in a block one, so a tab or a
257
279
  // `/**` docblock star defeats it. The node pragma is a substring bounded by
258
- // non-alphanumerics anywhere in the comment, so a reason may follow — and
259
- // below the header a stray file pragma still counts as one.
280
+ // non-alphanumerics anywhere in the comment (see ignoresForDprint), so a
281
+ // reason may follow — and below the header a stray file pragma still counts
282
+ // as one.
260
283
  {
261
284
  pattern: /^\/(?:\/ *|\*\s*)(dprint|deno-fmt)-ignore-file/,
262
285
  rawText: true,
263
286
  name: (match) => `${match[1] as string}-ignore-file`,
264
287
  },
265
288
  {
266
- pattern: /(?:^|[^\p{L}\p{N}])(dprint|deno-fmt)-ignore(?![\p{L}\p{N}])/u,
267
- name: (match) => `${match[1] as string}-ignore`,
268
- anyLine: true,
289
+ pattern: /(?:dprint|deno-fmt)-ignore/,
290
+ value: true,
291
+ name: (match) => DPRINT_IGNORE_MARKERS.filter((marker) => ignoresForDprint(match.input, marker)),
269
292
  },
270
293
  // Prettier pragma mode (--require-pragma / --check-ignore-pragma). Prettier
271
294
  // reads the pragmas through jest-docblock (its `src/language-js/pragma.js`):
@@ -764,6 +787,16 @@ export interface DirectivePlacement {
764
787
  * `case`, `default` or `}`. Left out too, any position is assumed.
765
788
  */
766
789
  nextToken?: string;
790
+ /**
791
+ * The JSDoc tags tsc reads in the comment (`@typedef`, `@param`, `@returns`,
792
+ * `@template`, ...), which it does in a JavaScript file where the comment
793
+ * is the JSDoc of a node: with `checkJs` they are the file's type
794
+ * annotations, and deleting one changes what the file means to the
795
+ * compiler. Each is a directive under its own name. Left out, the comment
796
+ * is assumed to hold none: in a TypeScript file tsc reads no types from
797
+ * JSDoc.
798
+ */
799
+ jsDoc?: readonly string[];
767
800
  }
768
801
 
769
802
  const ANY_PLACEMENT: DirectivePlacement = { header: true, firstComment: true, fileStart: true };
@@ -905,9 +938,9 @@ const FLOW_BLOCK_SUPPRESSION = /^\/\*[ \t\r\n*]*@ts-(ignore|expect-error)(?![\w-
905
938
  * `// @bun`) are skipped elsewhere — and the remaining rules still run, so a
906
939
  * live directive later in the same comment (`// deno-lint-ignore-file
907
940
  * nosemgrep` in mid-file) is not masked by a positionally dead one. A comment
908
- * no rule names is still `empty-block` where the placement puts it inside an
909
- * empty block, and a `///` line comment `empty-file` in a file that holds no
910
- * code.
941
+ * no rule names is still named for the type tags tsc reads from it in a
942
+ * JavaScript file, `empty-block` where the placement puts it inside an empty
943
+ * block, and a `///` line comment `empty-file` in a file that holds no code.
911
944
  */
912
945
  export function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined {
913
946
  return directiveNames(kind, text, placement)[0];
@@ -941,12 +974,13 @@ export function directiveNames(kind: CommentKind, text: string, placement?: Dire
941
974
  // A directive that opens the comment names it, however the comment goes on
942
975
  // to mention other tools' markers (`// nosemgrep: ... @jsx h` stays a
943
976
  // Semgrep suppression); only without one does a marker found after other
944
- // text name the comment.
977
+ // text name the comment. The type tags of a JSDoc comment come before such
978
+ // mentions too.
945
979
  const mentions: string[] = [];
946
980
  for (const match of ruleMatches(kind, text)) {
947
981
  if (isMatchActiveAt(match, at)) (match.opening ? names : mentions).push(match.name);
948
982
  }
949
- names.push(...mentions);
983
+ names.push(...(at.jsDoc ?? []), ...mentions);
950
984
  if (names.length > 0) return [...new Set(names)];
951
985
  if (at.emptyBlock === true) return [EMPTY_BLOCK];
952
986
  return at.emptyFile === true && kind === "line" && text.startsWith("///") ? [EMPTY_FILE] : [];
package/src/files.ts CHANGED
@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
2
2
  import { chmod, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
3
3
  import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
4
4
  import picomatch from "picomatch";
5
- import { scanComments } from "./scanner.js";
5
+ import { scanComments, type ScanOptions } from "./scanner.js";
6
6
  import type { FileScanResult } from "./types.js";
7
7
 
8
8
  const DEFAULT_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"];
@@ -29,23 +29,28 @@ export interface CollectOptions {
29
29
  type IgnoreMatcher = (path: string, root: string, isDirectory: boolean) => boolean;
30
30
 
31
31
  export async function collectFiles(inputs: string[], options: CollectOptions = {}): Promise<string[]> {
32
- const extensions = normalizeExtensions(options.extensions ?? DEFAULT_EXTENSIONS);
33
- const ignoreDirs = new Set((options.ignoreDirs ?? DEFAULT_IGNORE_DIRS).map(foldPathCase));
34
- const isIgnored = buildIgnoreMatcher(options.ignore ?? []);
32
+ const patterns = options.ignore ?? [];
33
+ const context: WalkContext = {
34
+ extensions: normalizeExtensions(options.extensions ?? DEFAULT_EXTENSIONS),
35
+ ignoreDirs: new Set((options.ignoreDirs ?? DEFAULT_IGNORE_DIRS).map(foldPathCase)),
36
+ isIgnored: buildIgnoreMatcher(patterns),
37
+ pathBlind: patterns.length === 0,
38
+ };
35
39
  // Keyed by the real path so different spellings of one file (relative vs
36
40
  // absolute, `.` segments, case on Windows, symlink aliases) collapse into a
37
41
  // single entry; the first spelling seen is the one reported.
38
42
  const found = new Map<string, string>();
39
- const remember = (path: string, realPath: string): void => {
40
- const key = canonicalKey(realPath);
41
- if (!found.has(key)) found.set(key, path);
43
+ const remember = (file: FoundFile): void => {
44
+ const key = canonicalKey(file.real);
45
+ if (!found.has(key)) found.set(key, file.path);
42
46
  };
43
47
 
44
- // Walks remember their discoveries mid-traversal; explicitly listed files
45
- // are resolved concurrently but remembered afterwards in input order, so
46
- // which spelling of an aliased file gets reported never depends on
47
- // filesystem timing.
48
- const explicitFiles = new Array<{ path: string; real: string } | undefined>(inputs.length);
48
+ // The inputs are looked up concurrently, and the walks and the explicitly
49
+ // listed files are then remembered in a fixed order — the walks' finds
50
+ // first, the listed files after them in input order — so which spelling of
51
+ // an aliased file gets reported never depends on filesystem timing.
52
+ const roots = new Array<Directory | undefined>(inputs.length);
53
+ const explicitFiles = new Array<FoundFile | undefined>(inputs.length);
49
54
  await Promise.all(
50
55
  inputs.map(async (rawInput, index) => {
51
56
  if (rawInput === "") {
@@ -58,15 +63,21 @@ export async function collectFiles(inputs: string[], options: CollectOptions = {
58
63
  // Directory inputs are themselves subject to the ignored directory
59
64
  // names and the ignore patterns; only explicitly listed files bypass
60
65
  // them.
61
- const context: WalkContext = { extensions, ignoreDirs, isIgnored, root: input, visited: new Set() };
62
- if (entersDirectory(context, input, basename(input))) await walk(input, context, remember);
66
+ if (entersDirectory(context, input, basename(input), input)) {
67
+ roots[index] = { path: input, root: input, above: undefined };
68
+ }
63
69
  } else {
64
70
  explicitFiles[index] = { path: input, real: await withFriendlyNotFound(input, () => realpath(input)) };
65
71
  }
66
72
  }),
67
73
  );
74
+ await walk(
75
+ roots.filter((root) => root !== undefined),
76
+ context,
77
+ remember,
78
+ );
68
79
  for (const file of explicitFiles) {
69
- if (file !== undefined) remember(file.path, file.real);
80
+ if (file !== undefined) remember(file);
70
81
  }
71
82
 
72
83
  return [...found.values()].sort();
@@ -119,58 +130,128 @@ interface WalkContext {
119
130
  extensions: string[];
120
131
  ignoreDirs: Set<string>;
121
132
  isIgnored: IgnoreMatcher;
133
+ /**
134
+ * No ignore pattern is set, so what a walk finds in a directory is the same
135
+ * whatever path led to it: the extensions and the ignored directory names
136
+ * go by the entries' own names. With patterns, a file one spelling excludes
137
+ * can be in scope under another (`--ignore "a-link/*.ts"` and a second link
138
+ * to the same directory).
139
+ */
140
+ pathBlind: boolean;
141
+ }
142
+
143
+ /** A directory a walk is to list, under the path the walk reached it by. */
144
+ interface Directory {
145
+ path: string;
122
146
  /** Top-level directory this walk started from; ignore globs also match relative to it. */
123
147
  root: string;
124
- /** Real paths of directories already walked, so symlink cycles and diamonds terminate. */
125
- visited: Set<string>;
148
+ /** The real paths of the directories the walk came down through. */
149
+ above: Ancestors | undefined;
150
+ }
151
+
152
+ interface Ancestors {
153
+ real: string;
154
+ above: Ancestors | undefined;
155
+ }
156
+
157
+ /** A file in scope, under the path a walk or an input spelled it with, and its real path. */
158
+ interface FoundFile {
159
+ path: string;
160
+ real: string;
126
161
  }
127
162
 
128
163
  /** Whether a walk enters the directory: neither its name nor an ignore pattern excludes it. */
129
- function entersDirectory(context: WalkContext, path: string, name: string): boolean {
130
- return !context.ignoreDirs.has(foldPathCase(name)) && !context.isIgnored(path, context.root, true);
164
+ function entersDirectory(context: WalkContext, path: string, name: string, root: string): boolean {
165
+ return !context.ignoreDirs.has(foldPathCase(name)) && !context.isIgnored(path, root, true);
131
166
  }
132
167
 
168
+ /**
169
+ * Walks the directories level by level, handing every file in scope to
170
+ * `remember`. A level's lookups run concurrently, but what they find is taken
171
+ * in the order of the level — the roots in input order, the entries below
172
+ * them by name — so the result, and the spelling a file reached by several
173
+ * paths is remembered under, are the same on every run.
174
+ *
175
+ * Symlinks are followed. A directory a walk came down through is not entered
176
+ * again, which ends the cycles. Where no path can change what a directory
177
+ * holds (see WalkContext.pathBlind), a directory already listed under another
178
+ * path is not listed again either; with ignore patterns, every path to it is
179
+ * walked, and the files found twice collapse in `remember`.
180
+ */
133
181
  async function walk(
134
- dir: string,
182
+ level: readonly Directory[],
135
183
  context: WalkContext,
136
- remember: (path: string, realPath: string) => void,
184
+ remember: (file: FoundFile) => void,
185
+ listed: Set<string> = new Set(),
137
186
  ): Promise<void> {
138
- const real = await unlessSkippable(() => realpath(dir));
139
- if (real === undefined) return; // the directory vanished mid-walk
140
- if (context.visited.has(real)) return;
141
- context.visited.add(real);
187
+ if (level.length === 0) return;
188
+ const reals = await Promise.all(level.map((directory) => unlessSkippable(() => realpath(directory.path))));
189
+ const entered: Array<[Directory, string]> = [];
190
+ for (const [index, directory] of level.entries()) {
191
+ const real = reals[index];
192
+ if (real === undefined) continue; // the directory vanished mid-walk
193
+ if (context.pathBlind ? listed.has(real) : isAbove(directory.above, real)) continue;
194
+ listed.add(real);
195
+ entered.push([directory, real]);
196
+ }
197
+ const listings = await Promise.all(entered.map(([directory, real]) => list(directory, real, context)));
198
+ const next: Directory[] = [];
199
+ for (const listing of listings) {
200
+ for (const entry of listing) {
201
+ if ("real" in entry) remember(entry);
202
+ else next.push(entry);
203
+ }
204
+ }
205
+ await walk(next, context, remember, listed);
206
+ }
142
207
 
143
- const entries = await unlessSkippable(() => readdir(dir, { withFileTypes: true }));
144
- if (entries === undefined) return; // the directory vanished after it resolved
208
+ /** Whether the real path is among those of the directories a walk came down through. */
209
+ function isAbove(ancestors: Ancestors | undefined, real: string): boolean {
210
+ for (let ancestor = ancestors; ancestor !== undefined; ancestor = ancestor.above) {
211
+ if (ancestor.real === real) return true;
212
+ }
213
+ return false;
214
+ }
145
215
 
146
- await Promise.all(
147
- entries.map(async (entry) => {
148
- const full = join(dir, entry.name);
149
- let isDirectory = entry.isDirectory();
150
- let isFile = entry.isFile();
151
- if (entry.isSymbolicLink()) {
152
- // Symlinks are followed, matching how explicitly listed inputs are
153
- // stat()ed; the visited set above keeps cycles from recursing forever.
154
- const info = await unlessSkippable(() => stat(full));
155
- if (info === undefined) return; // broken symlink
156
- isDirectory = info.isDirectory();
157
- isFile = info.isFile();
158
- }
159
- if (isDirectory) {
160
- if (entersDirectory(context, full, entry.name)) await walk(full, context, remember);
161
- } else if (
162
- isFile &&
163
- hasExtension(entry.name, context.extensions) &&
164
- !context.isIgnored(full, context.root, false)
165
- ) {
216
+ /** The files in scope and the directories to enter among the directory's entries, by name. */
217
+ async function list(directory: Directory, real: string, context: WalkContext): Promise<Array<FoundFile | Directory>> {
218
+ const entries = await unlessSkippable(() => readdir(directory.path, { withFileTypes: true }));
219
+ if (entries === undefined) return []; // the directory vanished after it resolved
220
+ const above = { real, above: directory.above };
221
+ const listing = await Promise.all(
222
+ entries
223
+ .sort((a, b) => (a.name < b.name ? -1 : 1))
224
+ .map(async (entry): Promise<FoundFile | Directory | undefined> => {
225
+ const full = join(directory.path, entry.name);
226
+ let isDirectory = entry.isDirectory();
227
+ let isFile = entry.isFile();
228
+ if (entry.isSymbolicLink()) {
229
+ // Symlinks are followed, matching how explicitly listed inputs are
230
+ // stat()ed.
231
+ const info = await unlessSkippable(() => stat(full));
232
+ if (info === undefined) return undefined; // broken symlink
233
+ isDirectory = info.isDirectory();
234
+ isFile = info.isFile();
235
+ }
236
+ if (isDirectory) {
237
+ return entersDirectory(context, full, entry.name, directory.root)
238
+ ? { path: full, root: directory.root, above }
239
+ : undefined;
240
+ }
241
+ if (
242
+ !isFile ||
243
+ !hasExtension(entry.name, context.extensions) ||
244
+ context.isIgnored(full, directory.root, false)
245
+ ) {
246
+ return undefined;
247
+ }
166
248
  // Remembered under its real path, so several symlinks to one target
167
249
  // (or a link plus the target itself) count — and get rewritten — once.
168
250
  const realFile = await unlessSkippable(() => realpath(full));
169
- if (realFile === undefined) return; // the file vanished mid-walk
170
- remember(full, realFile);
171
- }
172
- }),
251
+ return realFile === undefined ? undefined : { path: full, real: realFile }; // the file vanished mid-walk
252
+ }),
173
253
  );
254
+ return listing.filter((entry) => entry !== undefined);
174
255
  }
175
256
 
176
257
  function normalizeExtensions(extensions: string[]): string[] {
@@ -251,16 +332,29 @@ function toPosix(path: string): string {
251
332
  return sep === "/" ? path : path.split(sep).join("/");
252
333
  }
253
334
 
335
+ // The extensions tsc reads as JavaScript, with types in JSDoc.
336
+ const JAVASCRIPT_EXTENSIONS = [".js", ".jsx", ".mjs", ".cjs"];
337
+
254
338
  // TypeScript parses plain JavaScript with the JSX language variant, so `.js`
255
339
  // belongs here: read as TS instead, `<div>http://x</div>` in a React file
256
340
  // becomes a type assertion followed by a phantom `//x` comment.
257
- const JSX_EXTENSIONS = [".tsx", ".jsx", ".js", ".mjs", ".cjs"];
341
+ const JSX_EXTENSIONS = [".tsx", ...JAVASCRIPT_EXTENSIONS];
258
342
 
259
343
  /** True for files whose syntax admits JSX (`.tsx`, `.jsx` and plain JavaScript), case-insensitively. */
260
344
  export function isJsxFile(file: string): boolean {
261
345
  return hasExtension(file, JSX_EXTENSIONS);
262
346
  }
263
347
 
348
+ /** True for JavaScript files (`.js`, `.jsx`, `.mjs`, `.cjs`), case-insensitively. */
349
+ export function isJavaScriptFile(file: string): boolean {
350
+ return hasExtension(file, JAVASCRIPT_EXTENSIONS);
351
+ }
352
+
353
+ /** The scan options a file's extension calls for. */
354
+ export function scanOptionsFor(file: string): ScanOptions {
355
+ return { jsx: isJsxFile(file), javascript: isJavaScriptFile(file) };
356
+ }
357
+
264
358
  export type FileEncoding = "utf8" | "utf16le" | "utf16be";
265
359
 
266
360
  export interface FileText {
@@ -360,7 +454,7 @@ export async function writeFileAtomic(file: string, data: Buffer): Promise<void>
360
454
 
361
455
  export async function scanFile(file: string): Promise<FileScanResult> {
362
456
  const { text } = await readFileText(file);
363
- return { file, comments: scanComments(text, { jsx: isJsxFile(file) }) };
457
+ return { file, comments: scanComments(text, scanOptionsFor(file)) };
364
458
  }
365
459
 
366
460
  export async function scanPaths(inputs: string[], options: CollectOptions = {}): Promise<FileScanResult[]> {