module-migration-tool/README.zh-CN.md

分析项目文件依赖并迁移到新项目的工具

# 模块迁移工具

[English](https://gitee.com/little_fat_brother_in_turpan/module-migration-tool/blob/master/README.md) | [中文](https://gitee.com/little_fat_brother_in_turpan/module-migration-tool/blob/master/README.zh-CN.md)

这是一个帮助将大型项目中的一部分代码迁移出来，形成独立小项目的工具。工具会分析入口文件（或目录）的所有依赖，并递归查找所有相关文件，然后将它们复制到新的目标目录中，保持原有的目录结构。

这个工具能够帮助开发者快速从大型项目中提取部分代码，同时保持所有依赖关系完整，对于需要将单体应用拆分为微前端或微服务架构的团队特别有用。工具设计考虑了可扩展性，可以轻松添加对新文件类型的支持或自定义依赖分析规则。

## 功能特点

- ✅ 分析 JavaScript/TypeScript 文件的静态依赖关系
- ✅ 分析 Vue 单文件组件的依赖
- ✅ 分析 CSS/SCSS/LESS 文件中的引用
- ✅ 自动处理相对路径导入
- ✅ 支持别名路径解析（如`@/components`）
- ✅ 自动检测项目配置（如 tsconfig.json 中的路径别名）
- ✅ 保持原始目录结构
- ✅ 生成依赖关系可视化报告
- ✅ 支持单文件或整个目录作为入口点

## 安装

```bash
# 全局安装，也可以采用npx执行
npm install -g module-migration-tool

# 或在项目中本地安装
npm install module-migration-tool --save-dev


```

或克隆仓库并手动安装：

```bash
# 克隆仓库
git clone <repository-url>

# 进入项目目录
cd migration-tool

# 安装依赖
npm install

# 创建全局链接（可选）
npm link
```

## 使用流程

使用该工具的基本步骤如下：

1. 指定源项目路径
2. 指定入口文件/目录
3. 指定目标路径
4. 工具会自动分析依赖并复制所有必要的文件

你可以通过命令行参数或配置文件自定义工具的行为，如指定要忽略的路径、配置别名路径映射等。

## 使用方法

### 命令行使用

npx 执行

```bash
# 基本用法
npx module-migrate --source <源目录> --entry <入口文件/目录> --target <目标目录>
```

当全局安装后，你可以使用 `migrate` 或 `module-migrate` 命令：

```bash
# 基本用法
module-migrate --source <源目录> --entry <入口文件/目录> --target <目标目录>

# 示例
module-migrate --source ./my-project/src --entry ./my-project/src/components/Feature --target ./new-project
```

如果是本地安装：

```bash
npx module-migrate --source <源目录> --entry <入口文件/目录> --target <目标目录>
```

直接使用 Node.js：

```bash
node src/index.js --source <源目录> --entry <入口文件/目录> --target <目标目录>
```

### 命令行参数

| 参数          | 简写 | 描述              | 默认值         |
| ------------- | ---- | ----------------- | -------------- |
| `--source`    | `-s` | 源项目路径        | ./src          |
| `--entry`     | `-e` | 入口文件/目录路径 | ./src/index.js |
| `--target`    | `-t` | 目标路径          | ./dist         |
| `--config`    | `-c` | 配置文件路径      | -              |
| `--no-report` | -    | 不生成依赖报告    | false          |
| `--verbose`   | `-v` | 显示详细日志      | false          |

### 使用配置文件

你可以创建一个配置文件来自定义工具行为，然后通过`--config`参数指定：

```js
// migrate.config.js
module.exports = {
  // 支持的文件扩展名
  extensions: [".js", ".jsx", ".ts", ".tsx", ".vue", ".css"],
  // 忽略的路径
  ignorePaths: ["node_modules", "dist", "test"],
  // 路径别名配置
  alias: {
    "@": "./src",
    "@components": "./src/components",
  },
  // 分析选项
  analysis: {
    includeCss: true,
    includeJson: false,
    includeImages: false,
  },
}
```

使用配置文件启动工具：

```bash
node src/index.js --config ./migrate.config.js
```

## 依赖分析报告

工具会生成一个 HTML 格式的依赖关系报告，可以直接在浏览器中打开查看。报告包含：

- 文件依赖关系图：可视化展示文件间的依赖关系
- 文件总数和依赖总数统计：快速了解项目规模
- 文件路径搜索功能：方便查找特定文件
- 依赖项展开/折叠功能：灵活浏览依赖树

## 架构设计

该项目采用模块化设计，主要包含以下模块：

- **分析器模块**: 负责分析不同类型文件的依赖关系
  - JavaScript/TypeScript 分析器
  - CSS 分析器
  - Vue 单文件组件分析器
- **解析器模块**: 负责解析各种导入路径
  - 路径解析器
  - 别名解析器
- **报告生成器**: 生成可视化的依赖关系报告
- **工具函数**: 文件操作、配置管理等通用功能

## 核心模块说明

项目由以下核心模块组成，每个模块负责特定的功能：

### 分析器模块 (analyzers)

- **功能**: 分析不同类型文件中的依赖关系
- **核心文件**:
  - `jsAnalyzer.js`: 分析 JavaScript/TypeScript 文件中的 import/require 语句
  - `cssAnalyzer.js`: 分析 CSS 文件中的 @import 和 url() 引用
  - `vueAnalyzer.js`: 分析 Vue 单文件组件中的依赖
  - `index.js`: 分析器统一入口，根据文件类型选择合适的分析器

### 解析器模块 (resolvers)

- **功能**: 解析各种类型的导入路径
- **核心文件**:
  - `pathResolver.js`: 处理相对路径、绝对路径解析
  - `aliasResolver.js`: 处理路径别名解析（如 @/components）
  - `index.js`: 路径解析统一入口

### 报告生成器 (reporters)

- **功能**: 生成可视化的依赖关系报告
- **核心文件**:
  - `htmlReporter.js`: 生成 HTML 格式的依赖图报告
  - `index.js`: 报告生成统一入口

### 工具函数 (utils)

- **功能**: 提供通用功能支持
- **核心文件**:
  - `fileUtils.js`: 文件操作工具（复制文件、确保目录存在等）
  - `configUtils.js`: 配置管理（合并配置、检测项目配置等）

### 核心逻辑模块

- **migrator.js**: 迁移工具核心类，协调各模块工作，实现主迁移逻辑
- **index.js**: 程序入口，处理命令行参数，提供用户界面

## 项目结构

```
migration-tool/
├── config/
│   └── default.js         # 默认配置
├── src/
│   ├── analyzers/         # 依赖分析模块
│   │   ├── index.js       # 分析器入口
│   │   ├── jsAnalyzer.js  # JS/TS 文件分析器
│   │   ├── cssAnalyzer.js # CSS 文件分析器
│   │   └── vueAnalyzer.js # Vue 文件分析器
│   ├── resolvers/         # 路径解析模块
│   │   ├── index.js       # 解析器入口
│   │   ├── pathResolver.js  # 基础路径解析
│   │   └── aliasResolver.js # 别名路径解析
│   ├── utils/             # 工具函数
│   │   ├── fileUtils.js   # 文件操作工具
│   │   └── configUtils.js # 配置工具
│   ├── reporters/         # 报告生成器
│   │   ├── index.js       # 报告器入口
│   │   └── htmlReporter.js # HTML 报告生成器
│   ├── migrator.js        # 迁移核心类
│   └── index.js           # 程序入口
├── test/                  # 用于测试代码
├── package.json           # 项目配置
└── README.md              # 项目说明
```

## 注意事项

- 工具主要处理相对路径和配置的别名路径导入，对于第三方库的导入会自动忽略
- 如果项目使用了特殊的路径解析策略，可能需要在配置文件中自定义别名配置
- 处理大型项目时可能需要较长时间，请耐心等待
- 对于某些复杂的动态导入或非常规的导入方式可能无法识别

## 开发与扩展

### 添加对新文件类型的支持

如果需要支持新的文件类型，可以在`src/analyzers`目录下创建新的分析器，实现`analyzeFile`方法，然后在`src/analyzers/index.js`中注册该分析器。

### 自定义报告格式

如需自定义依赖报告格式，可以修改`src/reporters/htmlReporter.js`文件或实现一个全新的报告生成器，例如 JSON 或 Markdown 格式。

## 许可证

MIT