code-relation-analyzer/README.md

A TypeScript project dependency analysis tool that generates function-level dependency graphs

# Code Relation Analyzer

一个强大的 TypeScript 项目依赖关系分析工具，能够生成交互式的函数级依赖关系图。该工具专为前端开发者、架构师和项目经理设计，通过 AST 解析技术深度分析源码，识别文件间引用、继承关系、函数调用等复杂依赖关系，并生成可视化的 HTML 报告。

## ✨ 核心功能

- 📊 **全面分析**: 分析文件依赖、继承关系、函数调用和参数传递流
- 🎯 **AST 解析**: 基于 TypeScript 编译器 API 进行精确的源码分析
- 🌐 **交互式可视化**: 生成基于 D3.js 的美观依赖关系图
- 🖥️ **命令行界面**: 简单易用的 CLI 工具
- 📱 **响应式设计**: 支持桌面和移动设备
- 🔍 **详细报告**: 导出全面的分析报告
- 🎨 **Vue 支持**: 支持 Vue 单文件组件解析（基于 @vue/compiler-sfc）
- ⚡ **高性能**: 快速分析大型项目，支持缓存机制
- 🔧 **可配置**: 灵活的配置选项，满足不同项目需求

## 📦 安装

### 全局安装

```bash
npm install -g code-relation-analyzer
```

### 本地安装

```bash
npm install --save-dev code-relation-analyzer
```

### 系统要求

- Node.js >= 18.0.0
- TypeScript >= 5.0.0（可选，用于 TypeScript 项目分析）

## 🚀 快速开始

### 基础用法

```bash
# 分析当前目录
code-relation analyze

# 分析指定项目
code-relation analyze ./src

# 生成自定义输出路径的报告
code-relation analyze --output ./analysis-report
```

### 高级选项

```bash
# 包含 node_modules 在分析中
code-relation analyze --include-node-modules

# 设置最大分析深度
code-relation analyze --max-depth 5

# 指定文件匹配模式
code-relation analyze --patterns "**/*.ts,**/*.tsx,**/*.vue"

# 排除特定文件
code-relation analyze --exclude "**/*.test.ts,**/*.spec.ts"
```

### 开发环境使用

```bash
# 克隆仓库
git clone https://github.com/your-org/code-relation-analyzer.git
cd code-relation-analyzer

# 安装依赖
npm install

# 构建项目
npm run build

# 分析示例项目
npm run analyze examples/vue-project/src

# 生成 HTML 报告
node generate-html-report.js
```

## 📊 输出报告

工具会生成一个交互式 HTML 报告，包含多个视图：

### 报告页面

- **📈 项目概览**: 项目统计信息和关键指标
- **📁 文件依赖**: Import/Export 关系网络图
- **🔗 继承关系**: 类和接口的继承层次结构
- **⚡ 函数调用**: 函数间的调用依赖图
- **📊 参数传递**: 组件间的数据流可视化
- **🌐 全局依赖**: 全局变量和工具类的使用分布

### 可视化特性

- **交互式图表**: 支持缩放、拖拽、点击查看详情
- **多层次展示**: 从文件级到函数级的多层次依赖关系
- **智能布局**: 自动优化的图形布局算法
- **实时筛选**: 根据依赖类型、复杂度等条件筛选显示

## 🔧 API 使用

### 基础 API

```typescript
import { analyzeProject } from 'code-relation-analyzer';

const result = await analyzeProject({
  projectPath: './my-project',
  outputPath: './analysis',
  includeNodeModules: false,
  maxDepth: 10,
  filePatterns: ['**/*.ts', '**/*.tsx', '**/*.vue']
});

console.log('项目信息:', result.projectInfo);
console.log('文件依赖:', result.fileDependencies);
console.log('函数调用:', result.functionCalls);
```

### 高级 API

```typescript
import { 
  ProjectAnalyzer, 
  DependencyAnalyzer, 
  VisualizationGenerator 
} from 'code-relation-analyzer';

// 创建分析器实例
const analyzer = new ProjectAnalyzer({
  includeNodeModules: false,
  maxDepth: 15,
  cacheEnabled: true
});

// 执行分析
const analysisResult = await analyzer.analyze('./src');

// 生成可视化
const visualizer = new VisualizationGenerator();
const htmlReport = await visualizer.generateReport(analysisResult);

// 保存报告
await visualizer.saveReport(htmlReport, './output/report.html');
```

## ⚙️ 配置

### 配置文件

在项目根目录创建 `code-relation.config.js` 文件：

```javascript
module.exports = {
  // 基础配置
  includeNodeModules: false,
  maxDepth: 10,
  outputPath: './analysis',
  
  // 文件匹配模式
  filePatterns: [
    '**/*.ts',
    '**/*.tsx', 
    '**/*.js',
    '**/*.jsx',
    '**/*.vue'
  ],
  
  // 排除模式
  excludePatterns: [
    '**/*.test.ts',
    '**/*.spec.ts',
    '**/node_modules/**',
    '**/dist/**',
    '**/*.d.ts'
  ],
  
  // 分析选项
  analysis: {
    // 启用的分析类型
    enabledAnalyzers: [
      'dependency',
      'inheritance', 
      'functionCall',
      'parameterFlow',
      'globalDependency'
    ],
    
    // 复杂度计算
    complexity: {
      maxCyclomaticComplexity: 10,
      maxFunctionLength: 50,
      maxParameterCount: 5
    }
  },
  
  // 可视化配置
  visualization: {
    theme: 'light', // 'light' | 'dark'
    layout: 'force', // 'force' | 'hierarchical' | 'circular'
    nodeSize: 'auto', // 'auto' | 'fixed'
    showLabels: true,
    enableInteraction: true
  },
  
  // 输出配置
  output: {
    format: ['html', 'json'], // 输出格式
    includeSourceMaps: true,
    minify: false
  }
};
```

### 环境变量配置

```bash
# 设置日志级别
export CODE_RELATION_LOG_LEVEL=debug

# 设置缓存目录
export CODE_RELATION_CACHE_DIR=./cache

# 设置最大内存使用
export CODE_RELATION_MAX_MEMORY=4096
```

## 🛠️ 开发指南

### 环境设置

```bash
# 1. 克隆仓库
git clone https://github.com/your-org/code-relation-analyzer.git
cd code-relation-analyzer

# 2. 安装依赖
npm install

# 3. 设置开发环境
npm run setup

# 4. 启动开发模式
npm run dev
```

### 构建和测试

```bash
# 构建项目
npm run build

# 运行测试
npm test

# 运行测试并生成覆盖率报告
npm run test:coverage

# 代码检查
npm run lint

# 修复代码风格问题
npm run lint:fix

# 类型检查
npm run check
```

### 项目结构

```
code-relation-analyzer/
├── src/                    # 源代码
│   ├── cli/               # 命令行接口
│   ├── parser/            # AST 解析器
│   ├── analyzer/          # 依赖分析器
│   ├── visualizer/        # 可视化生成器
│   ├── types/             # 类型定义
│   └── utils/             # 工具函数
├── examples/              # 示例项目
├── templates/             # HTML 模板
├── tests/                 # 测试文件
└── docs/                  # 文档
```

## 🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

### 贡献流程

1. **Fork 仓库**
   ```bash
   # 在 GitHub 上 Fork 项目
   git clone https://github.com/your-username/code-relation-analyzer.git
   ```

2. **创建功能分支**
   ```bash
   git checkout -b feature/amazing-feature
   ```

3. **开发和测试**
   ```bash
   # 进行开发
   npm run dev
   
   # 运行测试
   npm test
   
   # 确保代码质量
   npm run lint
   ```

4. **提交更改**
   ```bash
   git add .
   git commit -m 'feat: add amazing feature'
   ```

5. **推送分支**
   ```bash
   git push origin feature/amazing-feature
   ```

6. **创建 Pull Request**
   - 在 GitHub 上创建 PR
   - 详细描述更改内容
   - 等待代码审查

### 开发规范

- **代码风格**: 使用 ESLint 和 Prettier
- **提交信息**: 遵循 [Conventional Commits](https://conventionalcommits.org/) 规范
- **测试覆盖率**: 新功能需要包含测试，覆盖率不低于 80%
- **文档更新**: 重要功能需要更新相应文档

### 报告问题

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

1. 检查是否已有相关 issue
2. 使用 issue 模板创建新问题
3. 提供详细的复现步骤和环境信息

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源。

```
MIT License

Copyright (c) 2024 Code Relation Analyzer Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## 📞 支持与社区

- 📖 **文档**: [完整文档](https://github.com/your-org/code-relation-analyzer/wiki)
- 🐛 **问题反馈**: [Issue 跟踪器](https://github.com/your-org/code-relation-analyzer/issues)
- 💬 **讨论交流**: [GitHub Discussions](https://github.com/your-org/code-relation-analyzer/discussions)
- 📧 **邮件支持**: support@code-relation-analyzer.com
- 🌟 **更新日志**: [CHANGELOG.md](CHANGELOG.md)

---

**如果这个工具对您有帮助，请给我们一个 ⭐ Star！**