@kongyo2/ts-comment-scanner 1.18.0 → 1.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/imports.ts CHANGED
@@ -1,24 +1,38 @@
1
1
  import ts from "typescript";
2
- import { LINE_TERMINATOR } from "./lines.js";
2
+ import { LINE_BREAK } from "./lines.js";
3
3
  import { firstIndexAtOrAfter, type Range } from "./ranges.js";
4
4
 
5
- type ImportSorter = "typescript" | "dprint" | "biome";
5
+ type ImportSorter = "typescript" | "dprint";
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";
6
14
 
7
15
  /**
8
16
  * The gap in front of an import or export declaration that an import sorter
9
17
  * reads to tell whether the declaration starts a new group, which it sorts
10
- * and merges apart from the group before it: the declaration's leading
11
- * 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.
12
23
  */
13
24
  export interface ImportGroupGap extends Range {
14
25
  /** The sorters that start a new group at the declaration after the gap. */
15
26
  splits: ImportSorter[];
27
+ /** The linters that find the empty line they want in the gap. */
28
+ spaced: ImportLinter[];
16
29
  }
17
30
 
18
31
  /**
19
- * The gaps the import sorters read, in document order — one for every
20
- * declaration past the first of a run a sorter sorts, so that the same
21
- * 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:
22
36
  *
23
37
  * - TypeScript's organizeImports (`groupByNewlineContiguous` in tsc 6 and in
24
38
  * tsc 7's port; tsserver and VS Code, prettier-plugin-organize-imports)
@@ -36,54 +50,227 @@ export interface ImportGroupGap extends Range {
36
50
  * A declaration a `dprint-ignore` comment exempts ends dprint's run, and
37
51
  * stays in it here, which only reads more gaps. `deno fmt`, which runs the
38
52
  * plugin, keeps the order.
39
- * - Biome's organizeImports (`assist/source/organizeImports`, on by default,
40
- * and enforced by `biome check` and `biome ci`) sorts chunks of adjacent
41
- * imports, and of adjacent `export … from`s and local `export { … }`s, in
42
- * the file and in each ambient module, and starts a new chunk at a
43
- * declaration whose leading trivia holds a detached comment (see
44
- * detachedComments); a blank line alone starts none. Bare imports end its
45
- * chunks unless its `sortBareImports` option sorts them too, and are read
46
- * here either way.
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.
64
+ *
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.
47
70
  */
48
71
  export function importGroupGaps(
49
72
  source: string,
50
73
  sourceFile: ts.SourceFile,
51
74
  comments: readonly Range[],
52
75
  ): ImportGroupGap[] {
53
- const readers = new Map<ts.Statement, Set<ImportSorter>>();
54
- const read = (declaration: ts.Statement, sorter: ImportSorter): void => {
55
- const sorters = readers.get(declaration) ?? new Set();
56
- sorters.add(sorter);
57
- readers.set(declaration, sorters);
58
- };
76
+ const sorters = new Map<ts.Statement, Set<ImportSorter>>();
77
+ const linters = new Map<ts.Statement, Set<ImportLinter>>();
59
78
  for (const statements of [sourceFile.statements, ...ambientModuleBodies(sourceFile)]) {
60
- 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
+ }
61
82
  }
62
83
  for (const run of exportRuns(sourceFile.statements)) {
63
- for (const declaration of run.slice(1)) read(declaration, "typescript");
84
+ for (const declaration of run.slice(1)) addReader(sorters, declaration, "typescript");
64
85
  }
65
- for (const declaration of adjacentOfOneKind(sourceFile.statements, dprintKind)) read(declaration, "dprint");
66
- for (const statements of [sourceFile.statements, ...ambientModuleBodies(sourceFile)]) {
67
- for (const declaration of adjacentOfOneKind(statements, biomeKind)) read(declaration, "biome");
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");
68
92
  }
69
- return [...readers]
70
- .sort(([a], [b]) => a.pos - b.pos)
71
- .map(([declaration, sorters]) => {
72
- const gap = { start: declaration.pos, end: declaration.getStart(sourceFile) };
73
- const splits = [...sorters].filter((sorter) => STARTS_GROUP[sorter](source, gap, comments));
74
- return { ...gap, splits };
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
+ .sort((a, b) => a.pos - b.pos)
98
+ .map((statement) => {
99
+ const gap = { start: statement.pos, end: gapEnd(statement, sourceFile) };
100
+ const splits = [...(sorters.get(statement) ?? [])].filter((sorter) =>
101
+ STARTS_GROUP[sorter](source, gap, comments),
102
+ );
103
+ const spaced = [...(linters.get(statement) ?? [])].filter((linter) => FINDS_EMPTY_LINE[linter](source, gap));
104
+ return { ...gap, splits, spaced };
75
105
  });
76
106
  }
77
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);
113
+ }
114
+
78
115
  // Whether the sorter starts a new group at the declaration after the gap.
79
116
  const STARTS_GROUP: Readonly<
80
117
  Record<ImportSorter, (source: string, gap: Range, comments: readonly Range[]) => boolean>
81
118
  > = {
82
119
  typescript: (source, gap, comments) => newLineTrivia(source, gap, comments) >= 2,
83
120
  dprint: (source, gap) => source.slice(gap.start, gap.end).split("\n").length > 2,
84
- biome: (source, gap, comments) => detachedComments(source, gap, comments).length > 0,
85
121
  };
86
122
 
123
+ // Whether the linter finds its empty line in the gap: two line breaks or
124
+ // more, those inside comments included.
125
+ const FINDS_EMPTY_LINE: Readonly<Record<ImportLinter, (source: string, gap: Range) => boolean>> = {
126
+ eslint: (source, gap) => source.slice(gap.start, gap.end).split(LINE_BREAK).length > 2,
127
+ oxlint: (source, gap) => source.slice(gap.start, gap.end).split("\n").length > 2,
128
+ };
129
+
130
+ /**
131
+ * Where the gap in front of the statement ends: at its first token, or at the
132
+ * first decorator of a class, which the linters measure the class from —
133
+ * past an `export` in front of it, too.
134
+ */
135
+ function gapEnd(statement: ts.Statement, sourceFile: ts.SourceFile): number {
136
+ const decorator = ts.isClassDeclaration(statement) ? ts.getDecorators(statement)?.[0] : undefined;
137
+ return (decorator ?? statement).getStart(sourceFile);
138
+ }
139
+
140
+ /**
141
+ * The statements the newline-after-import rules measure from the statement
142
+ * before them: the ones after an import that are none (see isImport), and,
143
+ * where `requires` asks, the ones after a statement holding a require that
144
+ * hold none (see holdsRequire).
145
+ */
146
+ function statementsAfterImports(statements: readonly ts.Statement[], requires: boolean): ts.Statement[] {
147
+ const holding = statements.map((statement) => requires && holdsRequire(statement));
148
+ return statements.filter(
149
+ (statement, index) =>
150
+ index > 0 &&
151
+ ((isImport(statements[index - 1] as ts.Statement) && !isImport(statement)) ||
152
+ (holding[index - 1] === true && !holding[index])),
153
+ );
154
+ }
155
+
156
+ /** Whether the linters read the statement as an import: an import declaration, or an `import x = …` not exported. */
157
+ function isImport(statement: ts.Statement): boolean {
158
+ return (
159
+ ts.isImportDeclaration(statement) ||
160
+ (ts.isImportEqualsDeclaration(statement) &&
161
+ statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) !== true)
162
+ );
163
+ }
164
+
165
+ /**
166
+ * Whether the statement holds a call eslint-plugin-import reads as a require
167
+ * (see isRequireCall) outside the nodes it looks for none in: functions with
168
+ * a body, blocks, object literals and decorators, which it counts as levels.
169
+ * A class static block is no block to it, a method's computed name lies
170
+ * outside its function, an object literal that an assignment destructures
171
+ * into is a pattern, no object (see isAssignmentTarget), and overloads and
172
+ * the other function-likes without a body are no functions, so the defaults
173
+ * of their parameters count, though tsc rejects them. oxlint stops at the
174
+ * same nodes among a call's ancestors and at functions without a body, and
175
+ * takes only the global `require`, called without parentheses around it or
176
+ * its string; the requires it leaves out are read for it all the same, as
177
+ * eslint-plugin-import reads the gaps after them anyway. Walked without
178
+ * recursion, as the deeply nested expressions of generated code need, and
179
+ * over the syntax tree alone, so that removing comments never changes which
180
+ * statements hold one.
181
+ */
182
+ function holdsRequire(statement: ts.Statement): boolean {
183
+ const pending: ts.Node[] = [statement];
184
+ for (let node = pending.pop(); node !== undefined; node = pending.pop()) {
185
+ if (ts.isCallExpression(node) && isRequireCall(node)) return true;
186
+ if (ts.isFunctionLike(node) && "body" in node && node.body !== undefined) {
187
+ if (node.name !== undefined && ts.isComputedPropertyName(node.name)) pending.push(node.name);
188
+ continue;
189
+ }
190
+ if (
191
+ (ts.isBlock(node) && !ts.isClassStaticBlockDeclaration(node.parent)) ||
192
+ (ts.isObjectLiteralExpression(node) && !isAssignmentTarget(node)) ||
193
+ ts.isDecorator(node)
194
+ ) {
195
+ continue;
196
+ }
197
+ // forEachChild stops at a callback that returns a value, so this one returns none.
198
+ ts.forEachChild(node, (child) => {
199
+ pending.push(child);
200
+ });
201
+ }
202
+ return false;
203
+ }
204
+
205
+ /**
206
+ * Whether the object literal is what an assignment destructures into — the
207
+ * left of an `=`, the target of a `for … of` or `for … in`, or an element, a
208
+ * rest or a property's value in one — which ESTree reads as a pattern.
209
+ */
210
+ function isAssignmentTarget(literal: ts.ObjectLiteralExpression): boolean {
211
+ let node: ts.Node = literal;
212
+ for (;;) {
213
+ const parent = node.parent;
214
+ if (ts.isBinaryExpression(parent)) {
215
+ return parent.operatorToken.kind === ts.SyntaxKind.EqualsToken && parent.left === node;
216
+ }
217
+ if (ts.isForOfStatement(parent) || ts.isForInStatement(parent)) return parent.initializer === node;
218
+ if (ts.isArrayLiteralExpression(parent) || ts.isSpreadElement(parent)) {
219
+ node = parent;
220
+ } else if (ts.isPropertyAssignment(parent) && parent.initializer === node) {
221
+ node = parent.parent;
222
+ } else {
223
+ return false;
224
+ }
225
+ }
226
+ }
227
+
228
+ /**
229
+ * Whether the call is a require to eslint-plugin-import: `require` with a
230
+ * single string literal, the parentheses around either part aside, as
231
+ * ESLint's parsers drop them.
232
+ */
233
+ function isRequireCall(call: ts.CallExpression): boolean {
234
+ const callee = unparenthesized(call.expression);
235
+ const [argument] = call.arguments;
236
+ return (
237
+ ts.isIdentifier(callee) &&
238
+ callee.text === "require" &&
239
+ call.arguments.length === 1 &&
240
+ ts.isStringLiteral(unparenthesized(argument as ts.Expression))
241
+ );
242
+ }
243
+
244
+ function unparenthesized(expression: ts.Expression): ts.Expression {
245
+ let inner = expression;
246
+ while (ts.isParenthesizedExpression(inner)) inner = inner.expression;
247
+ return inner;
248
+ }
249
+
250
+ /**
251
+ * The statements of every module and namespace body in the file (`declare
252
+ * module "m" { … }`, `declare global { … }`, `namespace N { … }`, the ones
253
+ * nested in them included), whose imports eslint-plugin-import reads too:
254
+ * an `import x = N.y` is at home in a namespace.
255
+ */
256
+ function moduleBodies(statements: readonly ts.Statement[]): Array<readonly ts.Statement[]> {
257
+ const bodies: Array<readonly ts.Statement[]> = [];
258
+ const pending: Array<readonly ts.Statement[]> = [statements];
259
+ for (let list = pending.pop(); list !== undefined; list = pending.pop()) {
260
+ for (const statement of list) {
261
+ if (!ts.isModuleDeclaration(statement)) continue;
262
+ // `namespace A.B { … }` nests the declaration of B in A's.
263
+ let body = statement.body;
264
+ while (body !== undefined && ts.isModuleDeclaration(body)) body = body.body;
265
+ if (body === undefined) continue;
266
+ const inner = (body as ts.ModuleBlock).statements;
267
+ bodies.push(inner);
268
+ pending.push(inner);
269
+ }
270
+ }
271
+ return bodies;
272
+ }
273
+
87
274
  /** The statements past the first of each run of adjacent ones that `kindOf` puts in one kind. */
88
275
  function adjacentOfOneKind(
89
276
  statements: readonly ts.Statement[],
@@ -98,9 +285,7 @@ function adjacentOfOneKind(
98
285
  /**
99
286
  * The statements of the ambient modules (`declare module "m" { … }`,
100
287
  * `declare global { … }`) at the top of the file, whose imports
101
- * organizeImports sorts too (it leaves their exports in one run), and whose
102
- * imports and exports Biome sorts. Biome sorts those of a `namespace` too,
103
- * where no import or export declaration is valid TypeScript.
288
+ * organizeImports sorts too (it leaves their exports in one run).
104
289
  */
105
290
  function ambientModuleBodies(sourceFile: ts.SourceFile): Array<ts.NodeArray<ts.Statement>> {
106
291
  return sourceFile.statements.flatMap((statement) =>
@@ -151,46 +336,6 @@ function dprintKind(statement: ts.Statement): "imports" | "exports" | undefined
151
336
  return ts.isExportDeclaration(statement) && statement.moduleSpecifier !== undefined ? "exports" : undefined;
152
337
  }
153
338
 
154
- /** What Biome sorts the statement among: imports, exports (`export … from`s and local `export { … }`s), or neither. */
155
- function biomeKind(statement: ts.Statement): "imports" | "exports" | undefined {
156
- if (ts.isImportDeclaration(statement)) return "imports";
157
- return ts.isExportDeclaration(statement) ? "exports" : undefined;
158
- }
159
-
160
- // An empty line as Biome reads one: a line break right after another, of its
161
- // `\r\n`, `\n`, `\r`, U+2028 and U+2029 each, so the CR of a CRLF is never one
162
- // on its own. A line holding spaces or tabs is no empty line to it.
163
- const EMPTY_LINE = /(?:\r\n|\r(?!\n)|[\n\u2028\u2029])[\n\r\u2028\u2029]/;
164
-
165
- /**
166
- * The comments that Biome's organizeImports reads as detached in front of the
167
- * declaration after the gap, and that start a new chunk there
168
- * (`has_detached_leading_comment`): those of the declaration's leading
169
- * trivia that an empty line comes after, outside comments. The leading trivia
170
- * starts at the first line break outside comments; the comments in front of
171
- * it trail the token before the gap.
172
- */
173
- export function detachedComments<T extends Range>(source: string, gap: Range, comments: readonly T[]): T[] {
174
- const leading: T[] = [];
175
- let detached = 0;
176
- let inLeadingTrivia = false;
177
- let from = gap.start;
178
- for (
179
- let index = firstIndexAtOrAfter(comments, gap.start, (comment) => comment.start);
180
- (comments[index]?.start ?? gap.end) < gap.end;
181
- index += 1
182
- ) {
183
- const comment = comments[index] as T;
184
- const text = source.slice(from, comment.start);
185
- if (EMPTY_LINE.test(text)) detached = leading.length;
186
- inLeadingTrivia ||= LINE_TERMINATOR.test(text);
187
- if (inLeadingTrivia) leading.push(comment);
188
- from = comment.end;
189
- }
190
- if (EMPTY_LINE.test(source.slice(from, gap.end))) detached = leading.length;
191
- return leading.slice(0, detached);
192
- }
193
-
194
339
  /** The line breaks TypeScript's scanner reads as NewLineTrivia in the gap, past its (sorted) comments. */
195
340
  function newLineTrivia(source: string, gap: Range, comments: readonly Range[]): number {
196
341
  let count = 0;
package/src/remove.ts CHANGED
@@ -6,10 +6,10 @@ import {
6
6
  isLegalComment,
7
7
  type DirectivePlacement,
8
8
  } from "./directives.js";
9
- import { detachedComments, type ImportGroupGap } from "./imports.js";
9
+ import type { ImportGroupGap } from "./imports.js";
10
10
  import type { JsxContainer } from "./jsx.js";
11
11
  import { LINE_TERMINATOR, isBlank, lineStartOffsets } from "./lines.js";
12
- import { firstIndexAtOrAfter, rangeAt, type Range } from "./ranges.js";
12
+ import { firstIndexAtOrAfter, type Range } from "./ranges.js";
13
13
  import { analyzeSource } from "./scanner.js";
14
14
  import { applyEdits, blankLineEdits, type Edit } from "./splice.js";
15
15
  import type { Comment } from "./types.js";
@@ -42,12 +42,10 @@ export interface RemoveResult {
42
42
  * its row decide which node it trails), comments whose removal would shift
43
43
  * code under a next-line directive or join another line to one a directive
44
44
  * covers, or that sit between a directive and the code it reaches past
45
- * them for (or the JSX sibling it applies to), comments whose removal
45
+ * them for (or the JSX sibling it applies to), and comments whose removal
46
46
  * would move a position-dependent directive
47
47
  * (prettier's first-comment pragma, Deno's coverage file pragma, Bun's
48
- * file-start marker) into effect, and comments whose removal would join
49
- * two groups of imports or exports that TypeScript's organizeImports,
50
- * dprint or Biome sorts apart, or split one.
48
+ * file-start marker) into effect.
51
49
  */
52
50
  kept: Comment[];
53
51
  /** Comments excluded from removal by the `shouldRemove` predicate. */
@@ -80,10 +78,12 @@ export interface RemoveResult {
80
78
  * go with it: no pile-up of blank lines where a comment stood between two
81
79
  * of them, and at the start or end of the file or of a block only the blank
82
80
  * lines already against that edge stay.
83
- * - Imports and exports stay in the groups the import sorters read: where
84
- * deleting a comment would join two groups that TypeScript's
85
- * organizeImports, dprint or Biome sorts apart, or split one, the comment
86
- * stays.
81
+ * - Imports and exports stay in the groups TypeScript's organizeImports and
82
+ * dprint sort apart: where deleting the comments between two groups would
83
+ * leave no empty line between them, an empty line takes their place. So it
84
+ * does where deleting the comments after an import or a require would
85
+ * bring the code after it up to the line below, keeping the empty line the
86
+ * newline-after-import rules of eslint-plugin-import and oxlint want.
87
87
  * - A leading byte-order mark is preserved. Reported positions index into the
88
88
  * `source` string exactly as `scanComments(source)` reports them (a BOM
89
89
  * counts as its first character).
@@ -124,6 +124,10 @@ export function removeComments(source: string, options: RemoveOptions = {}): Rem
124
124
  // marker; when that changes a survivor's meaning, the attempt is repeated
125
125
  // without the collapse before any removal is given up.
126
126
  let tidyBlankLines = true;
127
+ // The removals that leave an empty line in their place, holding two groups
128
+ // of imports or exports apart, or the code after the imports two lines
129
+ // below them (see gapHolders).
130
+ const holders = new Set<Comment>();
127
131
 
128
132
  for (;;) {
129
133
  const shielding = shieldNextLineDirectives(source, removed, kept, skipped, context);
@@ -135,7 +139,7 @@ export function removeComments(source: string, options: RemoveOptions = {}): Rem
135
139
 
136
140
  const removing = new Set(removed);
137
141
  search.track(new Set(containers.filter((container) => container.comments.every((c) => removing.has(c)))));
138
- const edits = removalEdits(removed, containerOf, search.droppable);
142
+ const edits = removalEdits(removed, containerOf, search.droppable, holders);
139
143
  const deletions = edits.filter((edit) => edit.replacement === undefined);
140
144
  const blankEdits = tidyBlankLines ? blankLineEdits(source, deletions, comments, shielding.lines, analysis.jsx) : [];
141
145
  const code = editKeepingBom(source, [...edits, ...blankEdits].sort(byStart));
@@ -143,16 +147,13 @@ export function removeComments(source: string, options: RemoveOptions = {}): Rem
143
147
 
144
148
  if (search.adjust(changedSegments(analysis.jsx.segments, output.jsx.segments))) continue;
145
149
 
146
- // Where the output joins two groups of imports or exports, or splits one,
147
- // a sorter would sort them differently: the removal that does it is
148
- // re-protected, and the attempt repeated.
149
- const holders = importGroupHolders(source, comments, analysis.importGroups, output.importGroups, removed);
150
- if (holders.length > 0) {
151
- const holding = new Set(holders);
152
- removed = removed.filter((comment) => !holding.has(comment));
153
- kept.push(...holders);
154
- kept.sort(byStart);
155
- tidyBlankLines = true;
150
+ // Where the output joins two groups of imports or exports that a sorter
151
+ // sorts apart, or loses the empty line a linter finds after the imports,
152
+ // a removal in the gap leaves an empty line in its place, and the attempt
153
+ // is repeated.
154
+ const holding = gapHolders(source, analysis.importGroups, output.importGroups, removed, holders);
155
+ if (holding.length > 0) {
156
+ for (const holder of holding) holders.add(holder);
156
157
  continue;
157
158
  }
158
159
 
@@ -257,117 +258,44 @@ function closestRemovalBefore(removals: readonly Comment[], comment: Comment): C
257
258
  }
258
259
 
259
260
  /**
260
- * The removals to re-protect so that the output starts exactly the groups of
261
- * imports and exports the source starts. The gaps belong to the same
262
- * declarations in both texts, since removing comments leaves the statements
263
- * as they are. Where the output joins two groups at a gap for some sorter,
264
- * the removal holding the gap open stays (see joiningRemoval, and
265
- * detachedRemoval for Biome's chunks); where it splits one there, the
266
- * multi-line comment a line break took the place of stays (see
267
- * partingRemoval).
261
+ * The removals that are to leave an empty line in their place (see
262
+ * Edit.blankLine), so that the output starts every group of imports and
263
+ * exports the source starts, and keeps every empty line the linters find
264
+ * after its imports. The gaps belong to the same statements in both texts,
265
+ * since removing comments leaves the statements as they are. Where the
266
+ * output joins two groups at a gap, or a linter no longer finds its empty
267
+ * line there, the deleted comments took the gap's line breaks along, and the
268
+ * last of them that held any — one spanning lines, or one on a line below
269
+ * the token the gap follows — leaves an empty line, which starts a group for
270
+ * both sorters and is the empty line both linters want. A group the output
271
+ * starts where the source starts none can stand, for both parts of a sorted
272
+ * group are sorted, and so can an empty line only the output has.
268
273
  */
269
- function importGroupHolders(
274
+ function gapHolders(
270
275
  source: string,
271
- comments: readonly Comment[],
272
276
  before: readonly ImportGroupGap[],
273
277
  after: readonly ImportGroupGap[],
274
278
  removals: readonly Comment[],
279
+ holders: ReadonlySet<Comment>,
275
280
  ): Comment[] {
276
281
  if (before.length !== after.length) throw unexpectedResult();
277
- const holders = new Set<Comment>();
278
- const hold = (holder: Comment | undefined): void => {
279
- if (holder === undefined) throw unexpectedResult();
280
- holders.add(holder);
281
- };
282
+ const found: Comment[] = [];
282
283
  for (const [index, gap] of before.entries()) {
283
- const splits = (after[index] as ImportGroupGap).splits;
284
- const joined = gap.splits.filter((sorter) => !splits.includes(sorter));
285
- const parted = splits.some((sorter) => !gap.splits.includes(sorter));
286
- if (joined.length === 0 && !parted) continue;
284
+ const { splits, spaced } = after[index] as ImportGroupGap;
285
+ const intact =
286
+ gap.splits.every((sorter) => splits.includes(sorter)) && gap.spaced.every((linter) => spaced.includes(linter));
287
+ if (intact) continue;
287
288
  const inGap = removals.filter((comment) => comment.start >= gap.start && comment.end <= gap.end);
288
- // TypeScript and dprint count the gap's line breaks, Biome reads its comments.
289
- const linesJoined = joined.filter((sorter) => sorter !== "biome");
290
- if (linesJoined.length > 0) hold(joiningRemoval(source, gap, inGap, linesJoined.includes("typescript")));
291
- if (joined.includes("biome")) hold(detachedRemoval(source, gap, comments, inGap));
292
- if (parted) hold(partingRemoval(source, gap, inGap, removals));
289
+ // An empty line in the gap already starts a group for both sorters and
290
+ // is the empty line both linters want.
291
+ if (inGap.some((comment) => holders.has(comment))) throw unexpectedResult();
292
+ const holder = inGap.findLast(
293
+ (comment) => comment.endLine > comment.line || LINE_TERMINATOR.test(source.slice(gap.start, comment.start)),
294
+ );
295
+ if (holder === undefined) throw unexpectedResult();
296
+ found.push(holder);
293
297
  }
294
- return [...holders];
295
- }
296
-
297
- /**
298
- * The removal that Biome's chunk boundary at the gap rests on: the last of
299
- * the gap's detached comments that goes (see detachedComments). Kept, it is
300
- * detached again, for the empty line after it stays: the removals past it all
301
- * come after the gap's last empty line, and a run of blank lines keeps the
302
- * ones in front of its first vanishing line (see blankLineEdits).
303
- */
304
- function detachedRemoval(
305
- source: string,
306
- gap: Range,
307
- comments: readonly Comment[],
308
- inGap: readonly Comment[],
309
- ): Comment | undefined {
310
- return detachedComments(source, gap, comments).findLast((comment) => inGap.includes(comment));
311
- }
312
-
313
- /**
314
- * The removal in the gap whose deletion takes line breaks out of it: one
315
- * spanning lines, or one on a line below the token the gap follows. When only
316
- * dprint joins the groups, it counted line breaks inside a comment, and the
317
- * first comment spanning lines stays: the removals after it then trail it
318
- * and go without their line breaks, while in front of a later one a line
319
- * break would take their place. Otherwise the last of them that ends above
320
- * the declaration's line stays, holding a line of its own with the line break
321
- * TypeScript counts and the line dprint counts; failing that, the last of
322
- * them, which still keeps the declaration's line down.
323
- */
324
- function joiningRemoval(
325
- source: string,
326
- gap: Range,
327
- inGap: readonly Comment[],
328
- typescriptJoins: boolean,
329
- ): Comment | undefined {
330
- const breaking = inGap.filter(
331
- (comment) => comment.endLine > comment.line || LINE_TERMINATOR.test(source.slice(gap.start, comment.start)),
332
- );
333
- const spanning = typescriptJoins ? undefined : breaking.find((comment) => comment.endLine > comment.line);
334
- return (
335
- spanning ??
336
- breaking.findLast((comment) => LINE_TERMINATOR.test(source.slice(comment.end, gap.end))) ??
337
- breaking.at(-1)
338
- );
339
- }
340
-
341
- /**
342
- * The removal in the gap that a line break takes the place of (see
343
- * applyEdits): a multi-line comment with something that survives the
344
- * removals in front of it on its first line, and anything after it on its
345
- * last line — the token before the gap and the declaration after it count.
346
- * Its own line breaks are no NewLineTrivia to TypeScript, but the one put in
347
- * its place is.
348
- */
349
- function partingRemoval(
350
- source: string,
351
- gap: Range,
352
- inGap: readonly Comment[],
353
- removals: readonly Comment[],
354
- ): Comment | undefined {
355
- // Whether the line holds what `stands` accepts, from `from` on, stepping by `step` until `to`.
356
- const onLine = (from: number, to: number, step: 1 | -1, stands: (index: number) => boolean): boolean => {
357
- for (let index = from; index !== to; index += step) {
358
- if (LINE_TERMINATOR.test(source[index] as string)) return false;
359
- if (stands(index)) return true;
360
- }
361
- return true;
362
- };
363
- const content = (index: number): boolean => !isBlank(source[index] as string);
364
- const survivor = (index: number): boolean => content(index) && rangeAt(removals, index) === undefined;
365
- return inGap.findLast(
366
- (comment) =>
367
- comment.endLine > comment.line &&
368
- onLine(comment.start - 1, gap.start - 1, -1, survivor) &&
369
- onLine(comment.end, gap.end, 1, content),
370
- );
298
+ return found;
371
299
  }
372
300
 
373
301
  /**
@@ -485,17 +413,22 @@ function skippableRanges(
485
413
  return ranges;
486
414
  }
487
415
 
488
- /** The edits that remove the comments: one per comment, or one per container going with its braces. */
416
+ /**
417
+ * The edits that remove the comments: one per comment, or one per container
418
+ * going with its braces. A holder of a gap around the imports (see
419
+ * gapHolders) leaves an empty line in its place.
420
+ */
489
421
  function removalEdits(
490
422
  removed: readonly Comment[],
491
423
  containerOf: ReadonlyMap<Comment, Container>,
492
424
  droppable: ReadonlySet<Container>,
425
+ holders: ReadonlySet<Comment>,
493
426
  ): Edit[] {
494
427
  const edits: Edit[] = [];
495
428
  for (const comment of removed) {
496
429
  const container = containerOf.get(comment);
497
430
  if (container === undefined || !droppable.has(container) || container.mode === "keep") {
498
- edits.push({ start: comment.start, end: comment.end });
431
+ edits.push({ start: comment.start, end: comment.end, blankLine: holders.has(comment) });
499
432
  } else if (comment === container.comments[0]) {
500
433
  edits.push(
501
434
  container.mode === "drop"
package/src/scanner.ts CHANGED
@@ -20,7 +20,11 @@ export interface SourceAnalysis {
20
20
  jsx: JsxLayout;
21
21
  /** What stands in front of each comment carrying an ast-grep suppression (see precedingNode). */
22
22
  preceding: ReadonlyMap<Comment, PrecedingNode>;
23
- /** The gaps in front of the import and export declarations the import sorters group (see importGroupGaps). */
23
+ /**
24
+ * The gaps in front of the import and export declarations the import
25
+ * sorters group, and in front of the statements after the imports, where
26
+ * the linters want an empty line (see importGroupGaps).
27
+ */
24
28
  importGroups: ImportGroupGap[];
25
29
  }
26
30