@1adybug/prettier-plugin-sort-imports 0.0.1

package/README.md

@@ -0,0 +1,453 @@
+# Prettier Plugin Import Sorts
+
+[中文文档](https://github.com/1adybug/prettier-plugin-sort-imports/blob/main/README.zh-CN.md)
+
+A powerful Prettier plugin for intelligently grouping and sorting import statements in JavaScript/TypeScript files.
+
+## Features
+
+- ✅ **Smart Sorting**: Support for sorting both import modules and import contents
+- ✅ **Flexible Grouping**: Customizable grouping rules based on module type, path, etc.
+- ✅ **TypeScript Support**: Full support for TypeScript `type` imports
+- ✅ **Comment Preservation**: Comments follow their associated import statements
+- ✅ **Side Effect Handling**: Configurable sorting behavior for side effect imports
+- ✅ **Unused Import Removal**: Optional automatic removal of unused imports
+- ✅ **Factory Function Pattern**: Support for custom functions in configuration files
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install prettier-plugin-import-sorts --save-dev
+```
+
+### Basic Configuration
+
+Add the plugin to your `prettier.config.mjs`:
+
+```javascript
+export default {
+    plugins: ["prettier-plugin-import-sorts"],
+}
+```
+
+### Usage
+
+```bash
+npx prettier --write "src/**/*.{js,ts,jsx,tsx}"
+```
+
+## Usage Examples
+
+### Basic Sorting
+
+```typescript
+
+```
+
+### Custom Grouping and Sorting
+
+```javascript
+// prettier.config.mjs
+import { createPlugin } from "prettier-plugin-import-sorts"
+
+export default {
+    plugins: [
+        createPlugin({
+            // Custom grouping: group by module type
+            getGroup: statement => {
+                if (statement.path.startsWith("react")) return "react"
+                if (!statement.path.startsWith(".")) return "external"
+                return "local"
+            },
+            // Specify group order
+            sortGroup: (a, b) => {
+                const order = ["react", "external", "local"]
+                return order.indexOf(a.name) - order.indexOf(b.name)
+            },
+            // Add blank lines between groups
+            separator: "",
+        }),
+    ],
+}
+```
+
+Result:
+
+```typescript
+import "./styles.css"
+```
+
+## API Documentation
+
+### Type Definitions
+
+#### ImportContent
+
+Definition of import content:
+
+```typescript
+interface ImportContent {
+    /** Name of the imported content */
+    name: string
+    /** Alias of the imported content */
+    alias?: string
+    /** Type of the imported content, only explicitly marked type imports belong to type */
+    type: "type" | "variable"
+}
+```
+
+#### ImportStatement
+
+Definition of import statement:
+
+```typescript
+interface ImportStatement {
+    /** Module path of the import, can be relative or absolute */
+    path: string
+    /** Whether it's an export statement, defaults to false */
+    isExport: boolean
+    /** Whether it's a side effect import, defaults to false */
+    isSideEffect: boolean
+    /** Import contents */
+    importContents: ImportContent[]
+}
+```
+
+#### Group
+
+Group definition:
+
+```typescript
+interface Group {
+    /** Group name, defaults to "default" */
+    name: string
+    /** Whether it's a side effect group, defaults to false */
+    isSideEffect: boolean
+    /** List of import statements in the group */
+    importStatements: ImportStatement[]
+}
+```
+
+#### PluginConfig
+
+Plugin configuration:
+
+```typescript
+interface PluginConfig {
+    /** Custom grouping function */
+    getGroup?: (importStatement: ImportStatement) => string
+    /** Custom group sorting function */
+    sortGroup?: (a: Group, b: Group) => number
+    /** Custom import statement sorting function */
+    sortImportStatement?: (a: ImportStatement, b: ImportStatement) => number
+    /** Custom import content sorting function */
+    sortImportContent?: (a: ImportContent, b: ImportContent) => number
+    /** Separator between groups */
+    separator?: string | ((group: Group, index: number) => string | undefined)
+    /** Whether to sort side effect imports, defaults to false */
+    sortSideEffect?: boolean
+    /** Whether to remove unused imports, defaults to false */
+    removeUnusedImports?: boolean
+}
+```
+
+## Configuration Options
+
+### Method 1: Simple Configuration
+
+Configure basic options via Prettier config file:
+
+```javascript
+export default {
+    plugins: ["prettier-plugin-import-sorts"],
+    importSortSideEffect: false, // Whether to sort side effect imports
+    importSortSeparator: "", // Group separator
+    importSortRemoveUnused: false, // Whether to remove unused imports
+}
+```
+
+### Method 2: Advanced Configuration (Factory Function)
+
+Use `createPlugin` function to pass custom functions:
+
+```javascript
+import { createPlugin } from "prettier-plugin-import-sorts"
+
+export default {
+    plugins: [
+        createPlugin({
+            getGroup: statement => {
+                /* Custom grouping logic */
+            },
+            sortGroup: (a, b) => {
+                /* Custom sorting */
+            },
+            sortImportStatement: (a, b) => {
+                /* Custom sorting */
+            },
+            sortImportContent: (a, b) => {
+                /* Custom sorting */
+            },
+            separator: "",
+            sortSideEffect: true,
+            removeUnusedImports: false,
+        }),
+    ],
+}
+```
+
+### importSortRemoveUnused
+
+Whether to remove unused imports, defaults to `false`.
+
+**Default behavior (false)**: Keeps all imports.
+
+**When enabled (true)**: Automatically analyzes code and removes unused imports.
+
+```typescript
+// Before sorting
+import React, { useState, useEffect } from "react"
+import { Button, Input } from "antd"
+import { helper } from "./utils"
+
+function MyComponent() {
+    const [count, setCount] = useState(0)
+    return <Button>Click me</Button>
+}
+
+// After sorting (with removeUnusedImports enabled)
+import React, { useState } from "react"
+import { Button } from "antd"
+
+function MyComponent() {
+    const [count, setCount] = useState(0)
+    return <Button>Click me</Button>
+}
+```
+
+**Notes**:
+
+- Side effect imports (e.g., `import "./styles.css"`) will not be removed
+- Export statements (e.g., `export { x } from "module"`) will not be removed
+- Analysis is AST-based and identifies actually used identifiers in code
+- Supports identifying JSX components, TypeScript type references, etc.
+
+### importSortSideEffect
+
+Whether to sort side effect imports, defaults to `false`.
+
+**Default behavior (false)**: Side effect imports act as separators, imports between separators are sorted independently.
+
+```typescript
+import "f-side-effect"
+import "f-side-effect"
+```
+
+**When enabled (true)**: Side effect imports also participate in sorting.
+
+```typescript
+import "f-side-effect"
+import "f-side-effect"
+```
+
+### separator
+
+Separator between groups, defaults to `undefined` (no separator).
+
+Can be a string or function:
+
+```javascript
+// String: add blank lines between all groups
+separator: ""
+
+// Function: flexible control
+separator: (group, index) => {
+    // No separator for the first group
+    if (index === 0) return undefined
+    // Add blank lines for other groups
+    return ""
+}
+```
+
+## Default Sorting Rules
+
+### Import Content Sorting
+
+**Default behavior** (when custom `sortImportContent` is not provided):
+
+1. Default imports always come first
+2. Namespace imports (`import * as`) come after default imports
+3. Named imports are sorted by `type` priority, then alphabetically by final import name
+
+```typescript
+
+```
+
+**Custom behavior**:
+
+If a custom `sortImportContent` function is provided, the plugin will **fully follow your sorting logic**:
+
+```javascript
+createPlugin({
+    // Fully alphabetical order, no distinction between type and variable
+    sortImportContent: (a, b) => {
+        const aName = a.alias ?? a.name
+        const bName = b.alias ?? b.name
+        return aName.localeCompare(bName)
+    },
+})
+```
+
+```typescript
+
+```
+
+### Import Statement Sorting
+
+Import statements are sorted alphabetically by module path:
+
+```typescript
+
+```
+
+### Comment Handling
+
+Comments follow the import statements they are attached to:
+
+```typescript
+
+```
+
+## Implementation Details
+
+### Core Modules
+
+#### 1. Type Definitions (`src/types.ts`)
+
+Defines all interface types: ImportContent, ImportStatement, Group, PluginConfig, and various function types.
+
+#### 2. Parser (`src/parser.ts`)
+
+Uses `@babel/parser` to parse source code and extract import/export statements:
+
+- Parse source code into AST
+- Traverse AST to find all import and export statements
+- Identify import types: default import, named import, namespace import, side effect import
+- Identify TypeScript `type` import markers
+- Extract and preserve comments above import statements
+- Record position information of import statements
+
+#### 3. Sorter (`src/sorter.ts`)
+
+Implements grouping and sorting logic:
+
+- Group import statements according to `getGroup` function
+- If `sortSideEffect` is false, treat side effect imports as separators
+- Use various sorting functions to sort groups, import statements, and import contents
+- Support fully customizable sorting logic
+
+#### 4. Formatter (`src/formatter.ts`)
+
+Converts sorted import statements back to code strings:
+
+- Generate corresponding import/export code from `ImportStatement`
+- Handle formatting of default imports, named imports, namespace imports
+- Handle `type` import formatting
+- Insert separators between groups according to `separator` configuration
+- Maintain comment associations
+
+#### 5. Plugin Entry (`src/index.ts`)
+
+Implements Prettier plugin standard interface:
+
+- Extends existing babel/typescript parsers
+- Supports factory function pattern
+- Integrates parser, sorter, formatter
+- Only processes consecutive import statement blocks at the beginning of files
+
+#### 6. Analyzer (`src/analyzer.ts`)
+
+Analyzes identifiers used in code and filters unused imports:
+
+- Uses `@babel/traverse` to traverse AST
+- Collects all identifiers used in code (variables, functions, JSX components, type references, etc.)
+- Filters import statements, keeping only import contents used in code
+- Supports identifying aliases, default imports, namespace imports, etc.
+
+### Tech Stack
+
+- **Build Tool**: rslib
+- **Parser**: @babel/parser
+- **AST Traversal**: @babel/traverse
+- **AST Types**: @babel/types
+- **Plugin System**: Prettier 3.x
+
+### Advantages of Factory Function Pattern
+
+Prettier natively cannot accept functions as configuration parameters (because configurations need to be serializable). This plugin cleverly solves this problem through the factory function pattern:
+
+```javascript
+// Factory function is called in config file, returning a plugin instance
+import { createPlugin } from "prettier-plugin-import-sorts"
+
+export default {
+    plugins: [
+        createPlugin({
+            // Can pass functions!
+            getGroup: statement => {
+                /* ... */
+            },
+        }),
+    ],
+}
+```
+
+This maintains configuration flexibility while not violating Prettier's configuration system limitations.
+
+## Notes
+
+1. **Only processes consecutive import/export statement blocks at the beginning of files**
+    - After encountering non-import/export statements, subsequent imports will not be processed
+
+2. **Supported File Types**
+    - JavaScript: `.js`, `.jsx`, `.mjs`, `.cjs`, `.mjsx`, `.cjsx`
+    - TypeScript: `.ts`, `.tsx`, `.mts`, `.cts`, `.mtsx`, `.ctsx`
+
+3. **Does not support CommonJS `require` statements**
+    - Only supports ES6 module syntax (import/export)
+
+4. **Custom Sorting Functions**
+    - When providing custom `sortImportContent`, the plugin will fully follow your logic
+    - Will not enforce rules like default imports first or types first
+
+## Project Status
+
+✅ **Complete and Ready to Use**
+
+All core features have been implemented and tested. The plugin works properly and can be integrated into any project using Prettier.
+
+### Verified Scenarios
+
+1. ✅ Basic import sorting (alphabetically)
+2. ✅ Side effect imports as separators
+3. ✅ Side effect import sorting (with option enabled)
+4. ✅ Comments follow import statements
+5. ✅ TypeScript type imports prioritized
+6. ✅ Default and namespace import positions
+7. ✅ Mixed imports (default + named)
+8. ✅ Import contents sorted by alias
+9. ✅ Custom sorting logic
+
+## Next Steps (Optional)
+
+1. Add unit tests (using Jest or Vitest)
+2. Add CI/CD configuration
+3. Publish to npm
+4. Add more examples
+5. Support more configuration options (e.g., ignoring specific imports)
+
+## License
+
+MIT