test(formatter/sort-imports): Update comments and tests (#15896)

Follow up of #15831

Author: leaysgur

crates/oxc_formatter/src/ir_transform/mod.rs

@@ -1,3 +1,24 @@
+//! This module contains all IR transforms for sorting and aesthetically features.
+//! Currently, it only includes the `SortImportsTransform`.
+//!
+//! There were several approaches to achieve sorting.
+//! - 1. Sort at the AST level.
+//! - 2. Sort after converting AST to IR (current approach).
+//!
+//! At first glance, the former seems simpler and faster, but in practice, there are inconvenient aspects.
+//!
+//! Sorting requires referencing comments and blank lines while traversing the AST.
+//! Frequent lookups are necessary, and there wasn't a dramatic improvement in speed.
+//!
+//! Additionally, comments are printed in a top-down manner,
+//! and sorting that disrupts this order would complicate the code.
+//!
+//! Despite some overhead, sorting the IR allows us to avoid impacting the existing complex code that converts AST to IR.
+//!
+//! For more details, refer to the experimental PR below.
+//! - <https://github.com/oxc-project/oxc/pull/14647>
+//! - <https://github.com/oxc-project/oxc/pull/14651>
+
 mod sort_imports;
 
 pub use sort_imports::SortImportsTransform;

crates/oxc_formatter/src/ir_transform/sort_imports/mod.rs

@@ -16,6 +16,9 @@ use crate::{
     options,
 };
 
+/// An IR transform that sorts import statements according to specified options.
+/// Heavily inspired by ESLint's `@perfectionist/sort-imports` rule.
+/// <https://perfectionist.dev/rules/sort-imports>
 pub struct SortImportsTransform {
     options: options::SortImports,
     groups: Vec<Vec<GroupName>>,

crates/oxc_formatter/tests/ir_transform/_sort-imports-tests.ref.snap

@@ -2,93 +2,6 @@
 // vim: set filetype=typescript:
 
 describe("misc", () => {
-  it("recognizes Node.js built-in modules with node: prefix", async () => {
-    await valid({
-      code: dedent`
-          import { writeFile } from 'node:fs/promises'
-
-          import { useEffect } from 'react'
-        `,
-      options: [
-        {
-          groups: ["builtin", "external"],
-        },
-      ],
-    });
-
-    await invalid({
-      output: dedent`
-          import { writeFile } from 'node:fs/promises'
-
-          import { useEffect } from 'react'
-        `,
-      code: dedent`
-          import { writeFile } from 'node:fs/promises'
-          import { useEffect } from 'react'
-        `,
-      options: [
-        {
-          groups: ["builtin", "external"],
-        },
-      ],
-    });
-  });
-
-  it("classifies internal pattern side-effects correctly by group priority", async () => {
-    await valid({
-      code: dedent`
-          import { useClient } from '~/hooks/useClient'
-
-          import '~/css/globals.css'
-
-          import '~/data'
-        `,
-      options: [
-        {
-          groups: ["internal", "side-effect-style", "side-effect"],
-        },
-      ],
-    });
-
-    await invalid({
-      output: dedent`
-          import { useClient } from '~/hooks/useClient'
-
-          import '~/css/globals.css'
-
-          import '~/data'
-        `,
-      code: dedent`
-          import { useClient } from '~/hooks/useClient'
-          import '~/data'
-          import '~/css/globals.css'
-        `,
-      options: [
-        {
-          groups: ["internal", "side-effect-style", "side-effect"],
-        },
-      ],
-    });
-  });
-
-  it("treats empty named imports as regular imports not side-effects", async () => {
-    await valid({
-      code: dedent`
-          import {} from 'node:os'
-          import sqlite from 'node:sqlite'
-          import { describe, test } from 'node:test'
-          import { c } from 'c'
-          import 'node:os'
-        `,
-      options: [
-        {
-          groups: ["builtin", "external", "side-effect"],
-        },
-      ],
-    });
-  });
-
-
   describe("validates compatibility between sortSideEffects and groups configuration", () => {
     function createRule(
       groups: Options[0]["groups"],

crates/oxc_formatter/tests/ir_transform/sort_imports.rs

@@ -1613,4 +1613,104 @@ import d from "d";
 import e from "timers";
 "##,
     );
+    // Empty groups
+    assert_format(
+        r#"
+import d from "d";
+import a from "a";
+import * as c from "c";
+import { b1, type b2, b3 as b33 } from "b";
+"#,
+        r#"{
+  "experimentalSortImports": {
+    "groups": []
+  }
+}"#,
+        r#"
+import a from "a";
+import { b1, type b2, b3 as b33 } from "b";
+import * as c from "c";
+import d from "d";
+"#,
+    );
+    assert_format(
+        r#"
+import d from "d";
+import a from "a";
+import * as c from "c";
+import { b1, type b2, b3 as b33 } from "b";
+"#,
+        r#"{
+  "experimentalSortImports": {
+    "groups": [[], []]
+  }
+}"#,
+        r#"
+import a from "a";
+import { b1, type b2, b3 as b33 } from "b";
+import * as c from "c";
+import d from "d";
+"#,
+    );
+    // Node.js built-in modules with node: prefix are classified as builtin group
+    assert_format(
+        r#"
+import { writeFile } from "node:fs/promises";
+import { useEffect } from "react";
+"#,
+        r#"{
+  "experimentalSortImports": {
+    "groups": ["builtin", "external"]
+  }
+}"#,
+        r#"
+import { writeFile } from "node:fs/promises";
+
+import { useEffect } from "react";
+"#,
+    );
+    // Internal pattern side-effects are correctly classified by group priority
+    assert_format(
+        r#"
+import { useClient } from "~/hooks/useClient";
+import "~/data";
+import "~/css/globals.css";
+"#,
+        r#"{
+  "experimentalSortImports": {
+    "groups": ["internal", "side-effect-style", "side-effect"]
+  }
+}"#,
+        r#"
+import { useClient } from "~/hooks/useClient";
+
+import "~/css/globals.css";
+
+import "~/data";
+"#,
+    );
+    // Empty named imports are treated as regular imports not side-effects
+    assert_format(
+        r#"
+import {} from "node:os";
+import sqlite from "node:sqlite";
+import { describe, test } from "node:test";
+import { c } from "c";
+import "node:os";
+"#,
+        r#"{
+  "experimentalSortImports": {
+    "groups": ["builtin", "external", "side-effect"]
+  }
+}"#,
+        r#"
+import {} from "node:os";
+import sqlite from "node:sqlite";
+import { describe, test } from "node:test";
+
+import { c } from "c";
+
+import "node:os";
+"#,
+    );
 }