feat: add option followTsOrganizeImports for order rule

.changeset/clear-bikes-jog.md

@@ -0,0 +1,5 @@
+---
+"eslint-plugin-import-x": minor
+---
+
+feat: add option `followTsOrganizeImports` for `order` rule

docs/rules/order.md

@@ -109,6 +109,7 @@ This rule supports the following options (none of which are required):
 - [`sortTypesGroup`][7]
 - [`newlines-between-types`][27]
 - [`consolidateIslands`][25]
+- [`followTsOrganizeImports`][26]
 
 ---
 
@@ -958,6 +959,17 @@ import type { G } from './aaa.js'
 import type { H } from './bbb'
 ```
 
+### `followTsOrganizeImports`
+
+Valid values: `boolean` \
+Default: `false`
+
+> [!CAUTION]
+>
+> Currently, `followTsOrganizeImports` defaults to `false`. However, in a later update, the default might change to `true`.
+
+When set to `true`, this option will align the behavior with [TypeScript's LSP Organize Imports][34] feature. This only has an effect if no manual `groups` are defined.
+
 ## Related
 
 - [`import-x/external-module-folders`][29]
@@ -984,10 +996,12 @@ import type { H } from './bbb'
 [22]: https://prettier.io
 [23]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-5.html#type-modifiers-on-import-names
 [25]: #consolidateislands
+[26]: #followtsorganizeimports
 [27]: #newlines-between-types
 [28]: ../../README.md#importinternal-regex
 [29]: ../../README.md#importexternal-module-folders
 [30]: #alphabetize
 [31]: https://webpack.js.org/guides/tree-shaking#mark-the-file-as-side-effect-free
 [32]: #distinctgroup
 [33]: #named
+[34]: https://code.visualstudio.com/docs/typescript/typescript-refactoring#_organize-imports

src/rules/order.ts

@@ -53,6 +53,15 @@ const defaultGroups = [
   'index',
 ] as const
 
+const defaultGroupsTsOrganizeImports = [
+  'private',
+  'external',
+  'builtin',
+  'parent',
+  'index',
+  'sibling',
+] as const
+
 // REPORTING AND FIXING
 
 function reverse(array: ImportEntryWithRank[]): ImportEntryWithRank[] {
@@ -824,6 +833,7 @@ function getRequireBlock(node: TSESTree.Node) {
 const types: ImportType[] = [
   'builtin',
   'external',
+  'private',
   'internal',
   'unknown',
   'parent',
@@ -1149,6 +1159,7 @@ export interface Options {
   pathGroups?: PathGroup[]
   sortTypesGroup?: boolean
   warnOnUnassignedImports?: boolean
+  followTsOrganizeImports?: boolean
 }
 
 type MessageId =
@@ -1271,6 +1282,11 @@ export default createRule<[Options?], MessageId>({
             type: 'boolean',
             default: false,
           },
+          followTsOrganizeImports: {
+            type: 'boolean',
+            // TODO: switch default to true in next major
+            default: false,
+          },
         },
         additionalProperties: false,
         dependencies: {
@@ -1388,8 +1404,19 @@ export default createRule<[Options?], MessageId>({
       const { pathGroups, maxPosition } = convertPathGroupsForRanks(
         options.pathGroups || [],
       )
+      if (options.followTsOrganizeImports && options.groups) {
+        // TODO: remove warning when default of followTsOrganizeImports switched to true
+        // because then the user potentially knows what they are doing
+        // and the warning is not needed anymore
+        console.warn(
+          'If you have defined your own `groups` in `order`, `followTsOrganizeImports: true` has no effect.',
+        )
+      }
       const { groups, omittedTypes } = convertGroupsToRanks(
-        options.groups || defaultGroups,
+        options.groups ||
+          (options.followTsOrganizeImports
+            ? defaultGroupsTsOrganizeImports
+            : defaultGroups),
       )
       ranks = {
         groups,

src/utils/import-type.ts

@@ -88,6 +88,11 @@ export function isScopedMain(name: string) {
   return !!name && scopedMainRegExp.test(name)
 }
 
+function isPrivate(name: string) {
+  // see https://nodejs.org/api/packages.html#imports
+  return name.startsWith('#')
+}
+
 function isRelativeToParent(name: string) {
   return /^\.\.$|^\.\.[/\\]/.test(name)
 }
@@ -158,6 +163,9 @@ function typeTest(
     if (isBuiltIn(name, settings, path)) {
       return 'builtin'
     }
+    if (isPrivate(name)) {
+      return 'private'
+    }
     if (isRelativeToParent(name)) {
       return 'parent'
     }

test/rules/order.spec.ts

@@ -4809,6 +4809,64 @@ describe('TypeScript', () => {
             },
           ],
         }),
+        // By default it should order same as TS LSP (issue-286)
+        tValid({
+          code: `import { internA } from "#a";
+import { scopeA } from "@a/a";
+import a from 'a';
+import 'format.css';
+import fs from 'node:fs';
+import path from "path";
+import index from './';
+import { localA } from "./a";
+import sibling from './foo';
+`,
+          ...parserConfig,
+          options: [
+            {
+              followTsOrganizeImports: true,
+            },
+          ],
+        }),
+        // test for explicit followTsOrganizeImports=false
+        tValid({
+          code: `import 'format.css';
+import fs from 'node:fs';
+import path from "path";
+import a from 'a';
+import { scopeA } from "@a/a";
+import { localA } from "./a";
+import sibling from './foo';
+import index from './';
+import { internA } from "#a";
+`,
+          ...parserConfig,
+          options: [
+            {
+              followTsOrganizeImports: false,
+            },
+          ],
+        }),
+        // manual `groups` always take precedence over `followTsOrganizeImports`
+        tValid({
+          code: `import 'format.css';
+import a from 'a';
+import { scopeA } from "@a/a";
+import index from './';
+import fs from 'node:fs';
+import path from "path";
+import { localA } from "./a";
+import sibling from './foo';
+import { internA } from "#a";
+`,
+          ...parserConfig,
+          options: [
+            {
+              groups: ['external', 'internal', 'index'],
+              followTsOrganizeImports: true,
+            },
+          ],
+        }),
       ],
       invalid: [
         // Option alphabetize: {order: 'asc'}
@@ -5192,6 +5250,30 @@ describe('TypeScript', () => {
             // { message: '`node:fs/promises` import should occur before import of `express`' },
           ],
         }),
+        // By default it should order same as TS LSP (issue-286)
+        tInvalid({
+          code: `import { scopeA } from "@a/a";
+import fs from 'node:fs';
+import path from "path";
+import { localA } from "./a";
+import { internA } from "#a";
+`,
+          output: `import { internA } from "#a";
+import { scopeA } from "@a/a";
+import fs from 'node:fs';
+import path from "path";
+import { localA } from "./a";
+`,
+          ...parserConfig,
+          options: [
+            {
+              followTsOrganizeImports: true,
+            },
+          ],
+          errors: [
+            createOrderError(['`#a` import', 'before', 'import of `@a/a`']),
+          ],
+        }),
       ],
     })
   }