auto-import-fix 🚀

一个智能的依赖自动导入工具，让你告别手动添加 import 语句的烦恼！

特性 ✨

• 🔍 智能检测：自动识别未导入的依赖
• 🎯 智能合并：自动合并已有的导入语句
• 🌲 内部依赖：支持项目内文件间依赖分析
• 🛡️ 循环检测：内置循环依赖检测
• 🎨 格式化：高度可定制的导入格式化规则
• 🎭 组件支持：支持 React 和 Antd 组件自动导入
• 📁 相对路径：内部文件引用使用相对路径
• 🔧 幻觉修复：智能修复错误的导入路径
• 🔌 插件系统：内置强大的插件系统，支持自定义扩展

安装 📦

npm install auto-import-fix

快速开始 🚀

基础使用

const autoImport = require('auto-import-fix');

// 准备需要处理的文件
const files = [
  {
    filename: '/project/src/components/MyButton.jsx',
    content: `
function MyButton() {
  return <Button type="primary">Click Me!</Button>;
}
export default MyButton;
`
  }
];

// 定义可用的包信息
const availablePackages = {
  "antd": {
    "Button": {},
    "DatePicker": {
      "RangePicker": {}
    }
  }
};

// 运行自动导入
const result = autoImport(files, availablePackages);
console.log(result[0].content);

// 输出:
// import { Button } from 'antd';
// 
// function MyButton() {
//   return <Button type="primary">Click Me!</Button>;
// }
// export default MyButton;

API 文档 📚

autoImport(files, externalAvailablePackages, options)

参数说明

files Array<FileObject> 必需

• 描述：需要处理的文件列表
• 类型：数组，包含文件对象

FileObject 结构：

{
  filename: string;    // 文件路径（绝对路径）
  content: string;     // 文件内容
}

externalAvailablePackages Object 可选

• 描述：外部可用的包信息
• 类型：对象
• 默认值：{}

options Object 可选

• 描述：配置选项
• 类型：对象
• 默认值：{}

Options 结构：

{
  fixHallucinatedImports?: boolean;  // 是否启用幻觉导入修复，默认 false
  plugins?: Array<Plugin>;           // 插件列表，默认 []
}

返回值

返回值 Array<ResultObject>

• 描述：处理后的文件列表
• 类型：数组，包含结果对象

ResultObject 结构：

{
  filename: string;    // 原文件路径
  content: string;     // 处理后的文件内容
  updated: boolean;    // 是否有更新
}

使用场景 🎯

1. React 组件自动导入

const files = [{
  filename: '/project/src/MyForm.jsx',
  content: `
function MyForm() {
  const [form] = Form.useForm();
  return (
    <Form form={form}>
      <Input placeholder="请输入" />
      <Button type="primary">提交</Button>
    </Form>
  );
}
`
}];

const packages = {
  "antd": {
    "Form": {},
    "Input": {},
    "Button": {}
  }
};

const result = autoImport(files, packages);
// 自动添加: import { Form, Input, Button } from 'antd';

2. 内部文件依赖自动导入

const files = [
  {
    filename: '/project/src/utils/helpers.js',
    content: `
export const formatDate = (date) => {
  return date.toLocaleDateString();
};

export const validateEmail = (email) => {
  return email.includes('@');
};
`
  },
  {
    filename: '/project/src/components/UserForm.jsx',
    content: `
function UserForm() {
  const isValid = validateEmail('[email protected]');
  const today = formatDate(new Date());
  return <div>{today}</div>;
}
`
  }
];

const result = autoImport(files, {});
// 自动添加: import { formatDate, validateEmail } from '../utils/helpers';

3. 幻觉导入修复

const files = [{
  filename: '/project/src/components/UserCard.jsx',
  content: `
// 错误的导入路径
import { formatDate } from '@utils/helpers';  // @ 开头的幻觉路径
import { Button } from '@antd/button';        // 错误的包名
import UserService from './wrong-path/user';  // 错误的相对路径

function UserCard() {
  const date = formatDate(new Date());
  return <Button>{date}</Button>;
}
`
}];

// 启用幻觉导入修复功能
const result = autoImport(files, packages, { 
  fixHallucinatedImports: true 
});

// 修复后的导入语句：
// import { formatDate } from '../utils/helpers';
// import { Button } from 'antd';
// import UserService from '../services/user';

插件系统 🔌

内置插件

Ant Design 图标插件

专门用于处理 @ant-design/icons 图标的智能导入和修复插件。

功能特性：

• 🎯 智能识别：自动识别代码中使用的 Ant Design 图标
• 🔧 错误修复：自动修复错误的图标名称
• 🔍 相似度匹配：基于编辑距离算法找到最相似的正确图标
• 🛡️ 兜底机制：找不到相似图标时使用默认图标
• ⚡ 高性能：优化的算法，支持大量图标的快速处理

使用方法：

// 引入插件
const AntdIconsPlugin = require('auto-import-fix/dist/plugins/antd-icons-plugin');
// 或者 ES6 模块
// import AntdIconsPlugin from 'auto-import-fix/dist/plugins/antd-icons-plugin.esm.js';

// 创建插件实例
const plugin = new AntdIconsPlugin({
  autoFix: true,           // 是否自动修复错误的图标名称
  threshold: 0.6,          // 相似度阈值 (0-1)
  fallbackIcon: 'StarOutlined'  // 兜底图标
});

// 定义可用的图标
const availableIcons = {
  "@ant-design/icons": {
    "UserOutlined": {},
    "HomeOutlined": {},
    "SettingOutlined": {},
    "StarOutlined": {},
    "UpOutlined": {}
  }
};

// 使用插件
const result = autoImport(files, availableIcons, {
  plugins: [plugin]
});

配置选项：

| 选项 | 类型 | 默认值 | 描述 | |------|------|--------|------| | autoFix | boolean | true | 是否自动修复错误的图标名称 | | threshold | number | 0.6 | 相似度匹配阈值，范围 0-1 | | fallbackIcon | string | 'StarOutlined' | 找不到相似图标时的兜底图标 | | debug | boolean | false | 是否输出调试信息 |

支持的修复模式：

1. 自动导入缺失图标

// 输入
function MyComponent() {
  return <UserOutlined />;
}

// 输出
import { UserOutlined } from '@ant-design/icons';

function MyComponent() {
  return <UserOutlined />;
}

2. 修复错误的图标名称

// 输入（错误的图标名）
function MyComponent() {
  return <UserIcon />; // 应该是 UserOutlined
}

// 输出（自动修复）
import { UserOutlined } from '@ant-design/icons';

function MyComponent() {
  return <UserOutlined />;
}

3. 兜底机制

// 输入（完全错误的图标名）
function MyComponent() {
  return <SomeRandomIcon />;
}

// 输出（使用兜底图标）
import { StarOutlined } from '@ant-design/icons';

function MyComponent() {
  return <StarOutlined />;
}

性能特性：

• 支持处理包含数千个图标的大型项目
• 智能缓存机制，避免重复计算
• 优化的编辑距离算法
• 批量处理支持

自定义插件开发

你可以开发自己的插件来扩展功能：

class MyCustomPlugin {
  constructor(options = {}) {
    this.options = options;
  }

  process(context) {
    // context 包含:
    // - filename: 当前文件路径
    // - content: 文件内容
    // - ast: 抽象语法树
    // - newImports: 新的导入语句
    // - availablePackages: 可用包信息
    
    // 在这里实现你的逻辑
    
    // 返回更新后的上下文
    return {
      newImports: updatedImports,
      ast: updatedAst
    };
  }
}

// 使用自定义插件
const myPlugin = new MyCustomPlugin({ option1: 'value1' });
const result = autoImport(files, packages, {
  plugins: [myPlugin]
});

高级功能 🔥

批量处理

const fs = require('fs');
const path = require('path');

// 批量处理整个目录
function processDirectory(dirPath) {
  const files = [];
  
  function readDir(dir) {
    const items = fs.readdirSync(dir);
    items.forEach(item => {
      const fullPath = path.join(dir, item);
      const stat = fs.statSync(fullPath);
      
      if (stat.isDirectory()) {
        readDir(fullPath);
      } else if (/\.(js|jsx|ts|tsx)$/.test(item)) {
        files.push({
          filename: fullPath,
          content: fs.readFileSync(fullPath, 'utf8')
        });
      }
    });
  }
  
  readDir(dirPath);
  return autoImport(files, availablePackages);
}

配置文件支持

创建 auto-import.config.js：

module.exports = {
  availablePackages: {
    "antd": {
      "Button": {},
      "Input": {},
      "Form": {}
    },
    "@ant-design/icons": {
      "UserOutlined": {},
      "HomeOutlined": {}
    }
  },
  options: {
    fixHallucinatedImports: true,
    plugins: [
      new (require('auto-import-fix/dist/plugins/antd-icons-plugin'))({
        autoFix: true,
        threshold: 0.7
      })
    ]
  }
};

使用配置文件：

const config = require('./auto-import.config.js');
const result = autoImport(files, config.availablePackages, config.options);

性能优化 ⚡

• 增量处理：只处理变更的文件
• 并行处理：支持多文件并行处理
• 智能缓存：缓存解析结果，避免重复计算
• 内存优化：大文件流式处理

错误处理 🛠️

try {
  const result = autoImport(files, packages, options);
  
  result.forEach((fileResult, index) => {
    if (fileResult.updated) {
      console.log(`✅ ${fileResult.filename} 已更新`);
    } else {
      console.log(`ℹ️ ${fileResult.filename} 无需更新`);
    }
  });
} catch (error) {
  console.error('❌ 处理失败:', error.message);
}

注意事项 ⚠️

• 📁 文件路径：filename 必须是绝对路径
• 🔄 循环依赖：工具会检测并警告循环依赖
• 📝 文件格式：支持 .js、.jsx、.ts、.tsx 文件
• 🎯 标识符检测：只处理未声明的标识符
• 🔧 语法支持：支持 ES6+、JSX、TypeScript
• 🛡️ 幻觉修复：需要手动启用
• 🔌 插件兼容：确保插件版本兼容

开发指南 👨‍💻

本地开发

# 克隆项目
git clone <repository-url>
cd auto-import-fix

# 安装依赖
npm install

# 运行测试
npm test

# 构建项目
npm run build

# 运行特定测试
npm run test:antd-icons

调试模式

// 启用调试信息
const plugin = new AntdIconsPlugin({ debug: true });
const result = autoImport(files, packages, { plugins: [plugin] });

更新日志 📝

v1.2.0

• ✨ 新增插件系统
• ✨ 新增 Ant Design 图标插件
• 🔧 优化性能和内存使用
• 🐛 修复多个已知问题

v1.1.0

• ✨ 新增幻觉导入修复功能
• 🔧 改进错误处理机制
• 📚 完善文档和示例

v1.0.0

• 🎉 首次发布
• ✨ 基础自动导入功能
• ✨ 内部文件依赖处理
• ✨ 导入语句合并

贡献指南 🤝

我们欢迎所有形式的贡献！

如何贡献

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

开发规范

• 遵循现有的代码风格
• 添加适当的测试用例
• 更新相关文档
• 确保所有测试通过

报告问题

如果你发现了 bug 或有功能建议，请：

1. 检查是否已有相关 issue
2. 提供详细的问题描述
3. 包含复现步骤
4. 提供环境信息

许可证 📄

MIT License - 详见 LICENSE 文件

致谢 🙏

感谢所有贡献者和使用者的支持！

让编码更智能，让开发更高效！ 🚀

如果这个工具对你有帮助，请给我们一个 ⭐️！

有任何问题或建议，欢迎提交 Issue 或 Pull Request！