@kongyo2/ts-comment-scanner 1.19.0 → 1.21.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 (59) hide show
  1. package/README.md +2 -2
  2. package/dist/args.d.ts.map +1 -1
  3. package/dist/args.js +23 -19
  4. package/dist/args.js.map +1 -1
  5. package/dist/astgrep.d.ts +1 -1
  6. package/dist/astgrep.d.ts.map +1 -1
  7. package/dist/astgrep.js +3 -8
  8. package/dist/astgrep.js.map +1 -1
  9. package/dist/directives.d.ts +8 -0
  10. package/dist/directives.d.ts.map +1 -1
  11. package/dist/directives.js +27 -20
  12. package/dist/directives.js.map +1 -1
  13. package/dist/files.d.ts +2 -3
  14. package/dist/files.d.ts.map +1 -1
  15. package/dist/files.js +45 -60
  16. package/dist/files.js.map +1 -1
  17. package/dist/imports.d.ts +34 -10
  18. package/dist/imports.d.ts.map +1 -1
  19. package/dist/imports.js +202 -28
  20. package/dist/imports.js.map +1 -1
  21. package/dist/jsx.d.ts.map +1 -1
  22. package/dist/jsx.js +5 -6
  23. package/dist/jsx.js.map +1 -1
  24. package/dist/lines.d.ts +13 -5
  25. package/dist/lines.d.ts.map +1 -1
  26. package/dist/lines.js +20 -16
  27. package/dist/lines.js.map +1 -1
  28. package/dist/ranges.d.ts +8 -0
  29. package/dist/ranges.d.ts.map +1 -1
  30. package/dist/ranges.js +12 -0
  31. package/dist/ranges.js.map +1 -1
  32. package/dist/remove.d.ts +10 -7
  33. package/dist/remove.d.ts.map +1 -1
  34. package/dist/remove.js +254 -219
  35. package/dist/remove.js.map +1 -1
  36. package/dist/run.d.ts.map +1 -1
  37. package/dist/run.js +11 -19
  38. package/dist/run.js.map +1 -1
  39. package/dist/scanner.d.ts +10 -1
  40. package/dist/scanner.d.ts.map +1 -1
  41. package/dist/scanner.js +15 -26
  42. package/dist/scanner.js.map +1 -1
  43. package/dist/splice.d.ts +6 -0
  44. package/dist/splice.d.ts.map +1 -1
  45. package/dist/splice.js +22 -5
  46. package/dist/splice.js.map +1 -1
  47. package/package.json +1 -1
  48. package/src/args.ts +21 -21
  49. package/src/astgrep.ts +4 -8
  50. package/src/directives.ts +24 -17
  51. package/src/files.ts +43 -59
  52. package/src/imports.ts +229 -28
  53. package/src/jsx.ts +5 -6
  54. package/src/lines.ts +23 -14
  55. package/src/ranges.ts +17 -0
  56. package/src/remove.ts +287 -235
  57. package/src/run.ts +11 -24
  58. package/src/scanner.ts +25 -28
  59. package/src/splice.ts +29 -6
package/src/args.ts CHANGED
@@ -29,6 +29,8 @@ export class UsageError extends Error {
29
29
 
30
30
  const FORMATS: readonly OutputFormat[] = ["text", "json", "github"];
31
31
  const DIRECTIVE_CONFLICT = "--skip-directives and --only-directives cannot be combined";
32
+ const EXT_REQUIRED = "option --ext requires at least one extension";
33
+ const DIFF_REQUIRED = "option --diff requires a git revision range (e.g. HEAD or main..HEAD)";
32
34
 
33
35
  export function parseArgs(argv: string[]): CliOptions {
34
36
  const paths: string[] = [];
@@ -56,13 +58,24 @@ export function parseArgs(argv: string[]): CliOptions {
56
58
  }
57
59
 
58
60
  const [flag, inlineValue] = splitFlag(arg);
59
- const readValue = (): string => {
61
+ /**
62
+ * The option's value, given inline or as the next argument. A forgotten
63
+ * value must not swallow the next flag: `--ignore --dry-run` would turn a
64
+ * preview into an in-place removal. So a next argument starting with `-`
65
+ * is refused with `refusal`; a value that does start with `-` can still
66
+ * be given inline, as `--keep=-x`.
67
+ */
68
+ const readValue = (refusal = `option ${flag} requires a value`): string => {
60
69
  if (inlineValue !== undefined) return inlineValue;
61
70
  const next = argv[index + 1];
62
71
  if (next === undefined) throw new UsageError(`option ${flag} requires a value`);
72
+ if (next.startsWith("-")) throw new UsageError(refusal);
63
73
  index += 1;
64
74
  return next;
65
75
  };
76
+ /** The refusal for an option whose value may start with `-`, which then goes inline. */
77
+ const inlineForDash = (value: string, placeholder: string): string =>
78
+ `option ${flag} requires ${value} (use ${flag}=${placeholder} for one starting with "-")`;
66
79
  const rejectValue = (): void => {
67
80
  if (inlineValue !== undefined) throw new UsageError(`option ${flag} does not take a value`);
68
81
  };
@@ -85,27 +98,23 @@ export function parseArgs(argv: string[]): CliOptions {
85
98
  format = "json";
86
99
  break;
87
100
  case "--ignore": {
88
- const value = readValue();
101
+ const value = readValue(inlineForDash("a glob pattern", "<glob>"));
89
102
  if (value === "") throw new UsageError("option --ignore requires a glob pattern");
90
103
  ignore.push(value);
91
104
  break;
92
105
  }
93
106
  case "--ext": {
94
- const parsed = readValue()
107
+ const parsed = readValue(EXT_REQUIRED)
95
108
  .split(",")
96
109
  .map((extension) => extension.trim())
97
110
  .filter((extension) => extension !== "");
98
- if (parsed.length === 0) {
99
- throw new UsageError("option --ext requires at least one extension");
100
- }
111
+ if (parsed.length === 0) throw new UsageError(EXT_REQUIRED);
101
112
  extensions.push(...parsed);
102
113
  break;
103
114
  }
104
115
  case "--diff": {
105
- const value = readValue();
106
- if (value === "" || value.startsWith("-")) {
107
- throw new UsageError("option --diff requires a git revision range (e.g. HEAD or main..HEAD)");
108
- }
116
+ const value = readValue(DIFF_REQUIRED);
117
+ if (value === "" || value.startsWith("-")) throw new UsageError(DIFF_REQUIRED);
109
118
  diff = value;
110
119
  break;
111
120
  }
@@ -135,18 +144,9 @@ export function parseArgs(argv: string[]): CliOptions {
135
144
  rejectValue();
136
145
  removeLegal = true;
137
146
  break;
138
- case "--keep": {
139
- // A forgotten pattern must not swallow the next flag: `--keep --dry-run`
140
- // would turn a preview into an in-place removal. A pattern that does
141
- // start with `-` can still be given inline, as `--keep=-x`.
142
- if (inlineValue === undefined && argv[index + 1]?.startsWith("-") === true) {
143
- throw new UsageError(
144
- `option ${flag} requires a regular expression (use ${flag}=<regex> for one starting with "-")`,
145
- );
146
- }
147
- keep.push(parsePattern(flag, readValue()));
147
+ case "--keep":
148
+ keep.push(parsePattern(flag, readValue(inlineForDash("a regular expression", "<regex>"))));
148
149
  break;
149
- }
150
150
  case "--dry-run":
151
151
  rejectValue();
152
152
  dryRun = true;
package/src/astgrep.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { LINE_TERMINATOR } from "./lines.js";
2
- import { firstIndexAtOrAfter, type Range } from "./ranges.js";
1
+ import { LINE_TERMINATOR, lineIndexAt, lineStartOffsets } from "./lines.js";
2
+ import type { Range } from "./ranges.js";
3
3
 
4
4
  /**
5
5
  * Where ast-grep's suppression comments apply (`get_suppression_kind` in its
@@ -35,11 +35,7 @@ function lineFeedCount(text: string): number {
35
35
 
36
36
  /** Start offset of every tree-sitter row: the text's start and each offset just past a line feed. */
37
37
  export function rowStartOffsets(text: string): number[] {
38
- const starts = [0];
39
- for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1)) {
40
- starts.push(index + 1);
41
- }
42
- return starts;
38
+ return lineStartOffsets(text, /\n/);
43
39
  }
44
40
 
45
41
  /** What stands in front of a comment in tree-sitter's tree, which ast-grep reads a suppression's reach from. */
@@ -89,7 +85,7 @@ export function astGrepReach(
89
85
  comment: Range,
90
86
  preceding: PrecedingNode,
91
87
  ): AstGrepReach {
92
- const rowOf = (offset: number): number => firstIndexAtOrAfter(rowStarts, offset + 1, (start) => start) - 1;
88
+ const rowOf = (offset: number): number => lineIndexAt(rowStarts, offset);
93
89
  const rowStart = (row: number): number => rowStarts[row] ?? text.length;
94
90
  const breaks = (unit: Range): boolean => LINE_TERMINATOR.test(text.slice(unit.start, unit.end));
95
91
  const row = rowOf(comment.start);
package/src/directives.ts CHANGED
@@ -910,39 +910,46 @@ const FLOW_BLOCK_SUPPRESSION = /^\/\*[ \t\r\n*]*@ts-(ignore|expect-error)(?![\w-
910
910
  * code.
911
911
  */
912
912
  export function detectDirective(kind: CommentKind, text: string, placement?: DirectivePlacement): string | undefined {
913
+ return directiveNames(kind, text, placement)[0];
914
+ }
915
+
916
+ /**
917
+ * Every directive the comment carries that is live at the placement, the
918
+ * name detectDirective reports first. A comment can carry several: what a
919
+ * removal has to leave in place for each of them (`// cspell:ignore foo --
920
+ * falls through`, read as a fall-through comment where it is the last
921
+ * comment before a `case`) must not hide behind the name.
922
+ */
923
+ export function directiveNames(kind: CommentKind, text: string, placement?: DirectivePlacement): string[] {
913
924
  const at = placement ?? ANY_PLACEMENT;
925
+ const names: string[] = [];
914
926
  if (kind === "line") {
915
927
  const tripleSlash = tripleSlashDirective(text);
916
- if (tripleSlash !== undefined && isActiveAt(tripleSlash, at)) return tripleSlash;
928
+ if (tripleSlash !== undefined && isActiveAt(tripleSlash, at)) names.push(tripleSlash);
917
929
  const suppression = TS_LINE_SUPPRESSION.exec(text) ?? FLOW_LINE_SUPPRESSION.exec(text);
918
- if (suppression) {
919
- return `@ts-${suppression[1]}`;
920
- }
930
+ if (suppression) names.push(`@ts-${suppression[1]}`);
921
931
  const checkPragma = TS6_LINE_CHECK_PRAGMA.exec(text) ?? TS7_LINE_CHECK_PRAGMA.exec(text);
922
932
  if (checkPragma) {
923
933
  const name = `@ts-${checkPragma[1]?.toLowerCase()}`;
924
- if (isActiveAt(name, at)) return name;
934
+ if (isActiveAt(name, at)) names.push(name);
925
935
  }
926
936
  } else {
927
937
  const suppression = TS_BLOCK_SUPPRESSION.exec(lastLine(text)) ?? FLOW_BLOCK_SUPPRESSION.exec(text);
928
- if (suppression) {
929
- return `@ts-${suppression[1]}`;
930
- }
938
+ if (suppression) names.push(`@ts-${suppression[1]}`);
931
939
  }
932
940
 
933
941
  // A directive that opens the comment names it, however the comment goes on
934
942
  // to mention other tools' markers (`// nosemgrep: ... @jsx h` stays a
935
- // Semgrep suppression, with the next-line shield that goes with it); only
936
- // without one does a marker found after other text name the comment.
937
- let mention: string | undefined;
943
+ // Semgrep suppression); only without one does a marker found after other
944
+ // text name the comment.
945
+ const mentions: string[] = [];
938
946
  for (const match of ruleMatches(kind, text)) {
939
- if (!isMatchActiveAt(match, at)) continue;
940
- if (match.opening) return match.name;
941
- mention ??= match.name;
947
+ if (isMatchActiveAt(match, at)) (match.opening ? names : mentions).push(match.name);
942
948
  }
943
- if (mention !== undefined) return mention;
944
- if (at.emptyBlock === true) return EMPTY_BLOCK;
945
- return at.emptyFile === true && kind === "line" && text.startsWith("///") ? EMPTY_FILE : undefined;
949
+ names.push(...mentions);
950
+ if (names.length > 0) return [...new Set(names)];
951
+ if (at.emptyBlock === true) return [EMPTY_BLOCK];
952
+ return at.emptyFile === true && kind === "line" && text.startsWith("///") ? [EMPTY_FILE] : [];
946
953
  }
947
954
 
948
955
  /**
package/src/files.ts CHANGED
@@ -1,5 +1,4 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import type { Dirent, Stats } from "node:fs";
3
2
  import { chmod, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
4
3
  import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
5
4
  import picomatch from "picomatch";
@@ -54,16 +53,15 @@ export async function collectFiles(inputs: string[], options: CollectOptions = {
54
53
  throw new Error("empty path is not a valid input");
55
54
  }
56
55
  const input = normalize(rawInput);
57
- const info = await statInput(input);
56
+ const info = await withFriendlyNotFound(input, () => stat(input));
58
57
  if (info.isDirectory()) {
59
58
  // Directory inputs are themselves subject to the ignored directory
60
59
  // names and the ignore patterns; only explicitly listed files bypass
61
60
  // them.
62
- if (!ignoreDirs.has(foldPathCase(basename(input))) && !isIgnored(input, input, true)) {
63
- await walk(input, { extensions, ignoreDirs, isIgnored, root: input, visited: new Set() }, remember);
64
- }
61
+ const context: WalkContext = { extensions, ignoreDirs, isIgnored, root: input, visited: new Set() };
62
+ if (entersDirectory(context, input, basename(input))) await walk(input, context, remember);
65
63
  } else {
66
- explicitFiles[index] = { path: input, real: await realpathInput(input) };
64
+ explicitFiles[index] = { path: input, real: await withFriendlyNotFound(input, () => realpath(input)) };
67
65
  }
68
66
  }),
69
67
  );
@@ -88,16 +86,7 @@ export function foldPathCase(path: string): string {
88
86
  return process.platform === "win32" ? path.toLowerCase() : path;
89
87
  }
90
88
 
91
- async function statInput(input: string): Promise<Stats> {
92
- return withFriendlyNotFound(input, () => stat(input));
93
- }
94
-
95
- /** Real path of an explicit input, with the same friendly error statInput gives. */
96
- async function realpathInput(input: string): Promise<string> {
97
- return withFriendlyNotFound(input, () => realpath(input));
98
- }
99
-
100
- /** Runs the lookup, reporting a missing path under the name the user spelled it with. */
89
+ /** Runs the lookup of an explicit input, reporting a missing path under the name the user spelled it with. */
101
90
  async function withFriendlyNotFound<T>(input: string, lookup: () => Promise<T>): Promise<T> {
102
91
  try {
103
92
  return await lookup();
@@ -110,14 +99,20 @@ async function withFriendlyNotFound<T>(input: string, lookup: () => Promise<T>):
110
99
  }
111
100
 
112
101
  /**
113
- * True for the errors a walk may step over: entries that vanished mid-walk
114
- * (ENOENT, ENOTDIR after a directory was replaced) and symlinks that do not
115
- * resolve (broken targets, ELOOP cycles). Anything else — permissions, I/O
116
- * failures — propagates, so a partial scan cannot masquerade as a clean one.
102
+ * Runs a lookup of the walk, undefined when it fails with an error the walk
103
+ * may step over: entries that vanished mid-walk (ENOENT, ENOTDIR after a
104
+ * directory was replaced) and symlinks that do not resolve (broken targets,
105
+ * ELOOP cycles). Anything else — permissions, I/O failures — propagates, so
106
+ * a partial scan cannot masquerade as a clean one.
117
107
  */
118
- function isSkippableWalkError(error: unknown): boolean {
119
- const code = (error as NodeJS.ErrnoException).code;
120
- return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
108
+ async function unlessSkippable<T>(lookup: () => Promise<T>): Promise<T | undefined> {
109
+ try {
110
+ return await lookup();
111
+ } catch (error) {
112
+ const code = (error as NodeJS.ErrnoException).code;
113
+ if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP") return undefined;
114
+ throw error;
115
+ }
121
116
  }
122
117
 
123
118
  interface WalkContext {
@@ -130,28 +125,23 @@ interface WalkContext {
130
125
  visited: Set<string>;
131
126
  }
132
127
 
128
+ /** 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);
131
+ }
132
+
133
133
  async function walk(
134
134
  dir: string,
135
135
  context: WalkContext,
136
136
  remember: (path: string, realPath: string) => void,
137
137
  ): Promise<void> {
138
- let real: string;
139
- try {
140
- real = await realpath(dir);
141
- } catch (error) {
142
- if (isSkippableWalkError(error)) return; // the directory vanished mid-walk
143
- throw error;
144
- }
138
+ const real = await unlessSkippable(() => realpath(dir));
139
+ if (real === undefined) return; // the directory vanished mid-walk
145
140
  if (context.visited.has(real)) return;
146
141
  context.visited.add(real);
147
142
 
148
- let entries: Dirent[];
149
- try {
150
- entries = await readdir(dir, { withFileTypes: true });
151
- } catch (error) {
152
- if (isSkippableWalkError(error)) return; // the directory vanished after it resolved
153
- throw error;
154
- }
143
+ const entries = await unlessSkippable(() => readdir(dir, { withFileTypes: true }));
144
+ if (entries === undefined) return; // the directory vanished after it resolved
155
145
 
156
146
  await Promise.all(
157
147
  entries.map(async (entry) => {
@@ -161,19 +151,13 @@ async function walk(
161
151
  if (entry.isSymbolicLink()) {
162
152
  // Symlinks are followed, matching how explicitly listed inputs are
163
153
  // stat()ed; the visited set above keeps cycles from recursing forever.
164
- try {
165
- const info = await stat(full);
166
- isDirectory = info.isDirectory();
167
- isFile = info.isFile();
168
- } catch (error) {
169
- if (isSkippableWalkError(error)) return; // broken symlink
170
- throw error;
171
- }
154
+ const info = await unlessSkippable(() => stat(full));
155
+ if (info === undefined) return; // broken symlink
156
+ isDirectory = info.isDirectory();
157
+ isFile = info.isFile();
172
158
  }
173
159
  if (isDirectory) {
174
- if (!context.ignoreDirs.has(foldPathCase(entry.name)) && !context.isIgnored(full, context.root, true)) {
175
- await walk(full, context, remember);
176
- }
160
+ if (entersDirectory(context, full, entry.name)) await walk(full, context, remember);
177
161
  } else if (
178
162
  isFile &&
179
163
  hasExtension(entry.name, context.extensions) &&
@@ -181,13 +165,8 @@ async function walk(
181
165
  ) {
182
166
  // Remembered under its real path, so several symlinks to one target
183
167
  // (or a link plus the target itself) count — and get rewritten — once.
184
- let realFile: string;
185
- try {
186
- realFile = await realpath(full);
187
- } catch (error) {
188
- if (isSkippableWalkError(error)) return; // the file vanished mid-walk
189
- throw error;
190
- }
168
+ const realFile = await unlessSkippable(() => realpath(full));
169
+ if (realFile === undefined) return; // the file vanished mid-walk
191
170
  remember(full, realFile);
192
171
  }
193
172
  }),
@@ -385,14 +364,19 @@ export async function scanFile(file: string): Promise<FileScanResult> {
385
364
  }
386
365
 
387
366
  export async function scanPaths(inputs: string[], options: CollectOptions = {}): Promise<FileScanResult[]> {
388
- const files = await collectFiles(inputs, options);
389
- return mapLimit(files, FILE_CONCURRENCY, scanFile);
367
+ return mapFiles(await collectFiles(inputs, options), scanFile);
390
368
  }
391
369
 
392
- export const FILE_CONCURRENCY = 16;
370
+ /** How many files are read and processed at once. */
371
+ const FILE_CONCURRENCY = 16;
372
+
373
+ /** Maps the files through `fn`, FILE_CONCURRENCY at a time, with the results in the files' order. */
374
+ export function mapFiles<R>(files: readonly string[], fn: (file: string) => Promise<R>): Promise<R[]> {
375
+ return mapLimit(files, FILE_CONCURRENCY, fn);
376
+ }
393
377
 
394
378
  /** Concurrency-limited map that keeps input order and starts work as slots free up. */
395
- export async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
379
+ async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
396
380
  const results = new Array<R>(items.length);
397
381
  let nextIndex = 0;
398
382
 
package/src/imports.ts CHANGED
@@ -1,23 +1,38 @@
1
1
  import ts from "typescript";
2
- import { firstIndexAtOrAfter, type Range } from "./ranges.js";
2
+ import { LINE_BREAK } from "./lines.js";
3
+ import { byStart, firstIndexAtOrAfter, type Range } from "./ranges.js";
3
4
 
4
5
  type ImportSorter = "typescript" | "dprint";
5
6
 
7
+ /**
8
+ * The linters whose newline-after-import rule wants an empty line between
9
+ * the imports and the code after them: eslint-plugin-import ("eslint"),
10
+ * whose rule eslint-plugin-import-x and eslint-plugin-import-lite carry
11
+ * over, and oxlint, which ports it ("oxlint").
12
+ */
13
+ type ImportLinter = "eslint" | "oxlint";
14
+
6
15
  /**
7
16
  * The gap in front of an import or export declaration that an import sorter
8
17
  * reads to tell whether the declaration starts a new group, which it sorts
9
- * and merges apart from the group before it: the declaration's leading
10
- * trivia, from the end of the token before it to its first token.
18
+ * and merges apart from the group before it, or in front of the statement
19
+ * after an import that a linter reads to tell whether an empty line ends the
20
+ * imports: the statement's leading trivia, from the end of the token before
21
+ * it to its first token — for a class, to its first decorator, which the
22
+ * linters measure from, past an `export` in front of it.
11
23
  */
12
24
  export interface ImportGroupGap extends Range {
13
25
  /** The sorters that start a new group at the declaration after the gap. */
14
26
  splits: ImportSorter[];
27
+ /** The linters that find the empty line they want in the gap. */
28
+ spaced: ImportLinter[];
15
29
  }
16
30
 
17
31
  /**
18
- * The gaps the import sorters read, in document order — one for every
19
- * declaration past the first of a run a sorter sorts, so that the same
20
- * declarations have gaps however the comments around them change:
32
+ * The gaps the import sorters and linters read, in document order — one for
33
+ * every declaration past the first of a run a sorter sorts, and one for every
34
+ * statement a linter measures from the import before it, so that the same
35
+ * statements have gaps however the comments around them change:
21
36
  *
22
37
  * - TypeScript's organizeImports (`groupByNewlineContiguous` in tsc 6 and in
23
38
  * tsc 7's port; tsserver and VS Code, prettier-plugin-organize-imports)
@@ -35,38 +50,66 @@ export interface ImportGroupGap extends Range {
35
50
  * A declaration a `dprint-ignore` comment exempts ends dprint's run, and
36
51
  * stays in it here, which only reads more gaps. `deno fmt`, which runs the
37
52
  * plugin, keeps the order.
53
+ * - The newline-after-import rules (see ImportLinter), with their default
54
+ * options, want the statement after an import declaration, or after an
55
+ * `import x = …` that is not exported, to start two or more lines below
56
+ * the import's end, unless it is one of those itself — so a comment line
57
+ * in between holds one of the lines. In the file's own statements they
58
+ * want the same after a statement holding a require (see holdsRequire),
59
+ * unless the next one holds one too. eslint-plugin-import counts the line
60
+ * breaks its parsers number lines by, U+2028 and U+2029 included, and reads
61
+ * the imports in the bodies of modules and namespaces as well (see
62
+ * moduleBodies); oxlint counts line feeds alone, in the file's own
63
+ * statements.
38
64
  *
39
- * Both start a group at an empty line, which is what removal leaves where it
40
- * deletes the comments that held two groups apart. Biome's organizeImports
41
- * starts a chunk only at a comment that an empty line follows, never at the
42
- * empty line alone, so no layout without the comment keeps its chunks apart,
43
- * and they are not read.
65
+ * The sorters start a group at an empty line, and the linters find theirs
66
+ * there, which is what removal leaves where it deletes the comments that held
67
+ * a gap open. Biome's organizeImports starts a chunk only at a comment that
68
+ * an empty line follows, never at the empty line alone, so no layout without
69
+ * the comment keeps its chunks apart, and they are not read.
44
70
  */
45
71
  export function importGroupGaps(
46
72
  source: string,
47
73
  sourceFile: ts.SourceFile,
48
74
  comments: readonly Range[],
49
75
  ): ImportGroupGap[] {
50
- const readers = new Map<ts.Statement, Set<ImportSorter>>();
51
- const read = (declaration: ts.Statement, sorter: ImportSorter): void => {
52
- const sorters = readers.get(declaration) ?? new Set();
53
- sorters.add(sorter);
54
- readers.set(declaration, sorters);
55
- };
76
+ const sorters = new Map<ts.Statement, Set<ImportSorter>>();
77
+ const linters = new Map<ts.Statement, Set<ImportLinter>>();
56
78
  for (const statements of [sourceFile.statements, ...ambientModuleBodies(sourceFile)]) {
57
- for (const declaration of statements.filter(ts.isImportDeclaration).slice(1)) read(declaration, "typescript");
79
+ for (const declaration of statements.filter(ts.isImportDeclaration).slice(1)) {
80
+ addReader(sorters, declaration, "typescript");
81
+ }
58
82
  }
59
83
  for (const run of exportRuns(sourceFile.statements)) {
60
- for (const declaration of run.slice(1)) read(declaration, "typescript");
84
+ for (const declaration of run.slice(1)) addReader(sorters, declaration, "typescript");
61
85
  }
62
- for (const declaration of adjacentOfOneKind(sourceFile.statements, dprintKind)) read(declaration, "dprint");
63
- return [...readers]
64
- .sort(([a], [b]) => a.pos - b.pos)
65
- .map(([declaration, sorters]) => {
66
- const gap = { start: declaration.pos, end: declaration.getStart(sourceFile) };
67
- const splits = [...sorters].filter((sorter) => STARTS_GROUP[sorter](source, gap, comments));
68
- return { ...gap, splits };
69
- });
86
+ for (const declaration of adjacentOfOneKind(sourceFile.statements, dprintKind)) {
87
+ addReader(sorters, declaration, "dprint");
88
+ }
89
+ for (const statement of statementsAfterImports(sourceFile.statements, true)) {
90
+ addReader(linters, statement, "eslint");
91
+ addReader(linters, statement, "oxlint");
92
+ }
93
+ for (const statements of moduleBodies(sourceFile.statements)) {
94
+ for (const statement of statementsAfterImports(statements, false)) addReader(linters, statement, "eslint");
95
+ }
96
+ return [...new Set([...sorters.keys(), ...linters.keys()])]
97
+ .map((statement) => {
98
+ const gap = { start: statement.pos, end: gapEnd(statement, sourceFile) };
99
+ const splits = [...(sorters.get(statement) ?? [])].filter((sorter) =>
100
+ STARTS_GROUP[sorter](source, gap, comments),
101
+ );
102
+ const spaced = [...(linters.get(statement) ?? [])].filter((linter) => FINDS_EMPTY_LINE[linter](source, gap));
103
+ return { ...gap, splits, spaced };
104
+ })
105
+ .sort(byStart);
106
+ }
107
+
108
+ /** Records that the tool reads the gap in front of the statement. */
109
+ function addReader<T>(readers: Map<ts.Statement, Set<T>>, statement: ts.Statement, reader: T): void {
110
+ const statementReaders = readers.get(statement) ?? new Set();
111
+ statementReaders.add(reader);
112
+ readers.set(statement, statementReaders);
70
113
  }
71
114
 
72
115
  // Whether the sorter starts a new group at the declaration after the gap.
@@ -74,9 +117,167 @@ const STARTS_GROUP: Readonly<
74
117
  Record<ImportSorter, (source: string, gap: Range, comments: readonly Range[]) => boolean>
75
118
  > = {
76
119
  typescript: (source, gap, comments) => newLineTrivia(source, gap, comments) >= 2,
77
- dprint: (source, gap) => source.slice(gap.start, gap.end).split("\n").length > 2,
120
+ dprint: holdsTwoBreaks("\n"),
78
121
  };
79
122
 
123
+ // Whether the linter finds its empty line in the gap.
124
+ const FINDS_EMPTY_LINE: Readonly<Record<ImportLinter, (source: string, gap: Range) => boolean>> = {
125
+ eslint: holdsTwoBreaks(LINE_BREAK),
126
+ oxlint: holdsTwoBreaks("\n"),
127
+ };
128
+
129
+ /**
130
+ * Whether a gap holds two line breaks or more, those inside comments
131
+ * included, to a tool that counts what `lineBreak` matches as one.
132
+ */
133
+ function holdsTwoBreaks(lineBreak: string | RegExp): (source: string, gap: Range) => boolean {
134
+ return (source, gap) => source.slice(gap.start, gap.end).split(lineBreak).length > 2;
135
+ }
136
+
137
+ /**
138
+ * Where the gap in front of the statement ends: at its first token, or at the
139
+ * first decorator of a class, which the linters measure the class from —
140
+ * past an `export` in front of it, too.
141
+ */
142
+ function gapEnd(statement: ts.Statement, sourceFile: ts.SourceFile): number {
143
+ const decorator = ts.isClassDeclaration(statement) ? ts.getDecorators(statement)?.[0] : undefined;
144
+ return (decorator ?? statement).getStart(sourceFile);
145
+ }
146
+
147
+ /**
148
+ * The statements the newline-after-import rules measure from the statement
149
+ * before them: the ones after an import that are none (see isImport), and,
150
+ * where `requires` asks, the ones after a statement holding a require that
151
+ * hold none (see holdsRequire).
152
+ */
153
+ function statementsAfterImports(statements: readonly ts.Statement[], requires: boolean): ts.Statement[] {
154
+ const holding = statements.map((statement) => requires && holdsRequire(statement));
155
+ return statements.filter(
156
+ (statement, index) =>
157
+ index > 0 &&
158
+ ((isImport(statements[index - 1] as ts.Statement) && !isImport(statement)) ||
159
+ (holding[index - 1] === true && !holding[index])),
160
+ );
161
+ }
162
+
163
+ /** Whether the linters read the statement as an import: an import declaration, or an `import x = …` not exported. */
164
+ function isImport(statement: ts.Statement): boolean {
165
+ return (
166
+ ts.isImportDeclaration(statement) ||
167
+ (ts.isImportEqualsDeclaration(statement) &&
168
+ statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) !== true)
169
+ );
170
+ }
171
+
172
+ /**
173
+ * Whether the statement holds a call eslint-plugin-import reads as a require
174
+ * (see isRequireCall) outside the nodes it looks for none in: functions with
175
+ * a body, blocks, object literals and decorators, which it counts as levels.
176
+ * A class static block is no block to it, a method's computed name lies
177
+ * outside its function, an object literal that an assignment destructures
178
+ * into is a pattern, no object (see isAssignmentTarget), and overloads and
179
+ * the other function-likes without a body are no functions, so the defaults
180
+ * of their parameters count, though tsc rejects them. oxlint stops at the
181
+ * same nodes among a call's ancestors and at functions without a body, and
182
+ * takes only the global `require`, called without parentheses around it or
183
+ * its string; the requires it leaves out are read for it all the same, as
184
+ * eslint-plugin-import reads the gaps after them anyway. Walked without
185
+ * recursion, as the deeply nested expressions of generated code need, and
186
+ * over the syntax tree alone, so that removing comments never changes which
187
+ * statements hold one.
188
+ */
189
+ function holdsRequire(statement: ts.Statement): boolean {
190
+ const pending: ts.Node[] = [statement];
191
+ for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
192
+ if (ts.isCallExpression(node) && isRequireCall(node)) return true;
193
+ if (ts.isFunctionLike(node) && "body" in node && node.body !== undefined) {
194
+ if (node.name !== undefined && ts.isComputedPropertyName(node.name)) pending.push(node.name);
195
+ continue;
196
+ }
197
+ if (
198
+ (ts.isBlock(node) && !ts.isClassStaticBlockDeclaration(node.parent)) ||
199
+ (ts.isObjectLiteralExpression(node) && !isAssignmentTarget(node)) ||
200
+ ts.isDecorator(node)
201
+ ) {
202
+ continue;
203
+ }
204
+ // forEachChild stops at a callback that returns a value, so this one returns none.
205
+ ts.forEachChild(node, (child) => {
206
+ pending.push(child);
207
+ });
208
+ }
209
+ return false;
210
+ }
211
+
212
+ /**
213
+ * Whether the object literal is what an assignment destructures into — the
214
+ * left of an `=`, the target of a `for … of` or `for … in`, or an element, a
215
+ * rest or a property's value in one — which ESTree reads as a pattern.
216
+ */
217
+ function isAssignmentTarget(literal: ts.ObjectLiteralExpression): boolean {
218
+ let node: ts.Node = literal;
219
+ for (;;) {
220
+ const parent = node.parent;
221
+ if (ts.isBinaryExpression(parent)) {
222
+ return parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === node;
223
+ }
224
+ if (ts.isForOfStatement(parent) || ts.isForInStatement(parent)) return parent.initializer === node;
225
+ if (ts.isArrayLiteralExpression(parent) || ts.isSpreadElement(parent)) {
226
+ node = parent;
227
+ } else if (ts.isPropertyAssignment(parent) && parent.initializer === node) {
228
+ node = parent.parent;
229
+ } else {
230
+ return false;
231
+ }
232
+ }
233
+ }
234
+
235
+ /**
236
+ * Whether the call is a require to eslint-plugin-import: `require` with a
237
+ * single string literal, the parentheses around either part aside, as
238
+ * ESLint's parsers drop them.
239
+ */
240
+ function isRequireCall(call: ts.CallExpression): boolean {
241
+ const callee = unparenthesized(call.expression);
242
+ const [argument] = call.arguments;
243
+ return (
244
+ ts.isIdentifier(callee) &&
245
+ callee.text === "require" &&
246
+ call.arguments.length === 1 &&
247
+ ts.isStringLiteral(unparenthesized(argument as ts.Expression))
248
+ );
249
+ }
250
+
251
+ function unparenthesized(expression: ts.Expression): ts.Expression {
252
+ let inner = expression;
253
+ while (ts.isParenthesizedExpression(inner)) inner = inner.expression;
254
+ return inner;
255
+ }
256
+
257
+ /**
258
+ * The statements of every module and namespace body in the file (`declare
259
+ * module "m" { … }`, `declare global { … }`, `namespace N { … }`, the ones
260
+ * nested in them included), whose imports eslint-plugin-import reads too:
261
+ * an `import x = N.y` is at home in a namespace.
262
+ */
263
+ function moduleBodies(statements: readonly ts.Statement[]): Array<readonly ts.Statement[]> {
264
+ const bodies: Array<readonly ts.Statement[]> = [];
265
+ const pending: Array<readonly ts.Statement[]> = [statements];
266
+ for (let list = pending.pop(); list !== undefined; list = pending.pop()) {
267
+ for (const statement of list) {
268
+ if (!ts.isModuleDeclaration(statement)) continue;
269
+ // `namespace A.B { … }` nests the declaration of B in A's.
270
+ let body = statement.body;
271
+ while (body !== undefined && ts.isModuleDeclaration(body)) body = body.body;
272
+ if (body === undefined) continue;
273
+ const inner = (body as ts.ModuleBlock).statements;
274
+ bodies.push(inner);
275
+ pending.push(inner);
276
+ }
277
+ }
278
+ return bodies;
279
+ }
280
+
80
281
  /** The statements past the first of each run of adjacent ones that `kindOf` puts in one kind. */
81
282
  function adjacentOfOneKind(
82
283
  statements: readonly ts.Statement[],