@mycodemap/mycodemap 0.1.0 → 0.2.0

package/docs/archive/comprehensive_test_report.md

@@ -0,0 +1,337 @@
+# CodeMap 综合测试报告
+
+**测试时间**: 2026年3月  
+**测试场景**: 5个核心功能场景  
+**测试目录**: /data/codemap  
+**项目规模**: 104个TypeScript文件，28,878行代码  
+
+---
+
+## 1. 执行摘要
+
+### 1.1 测试覆盖范围
+
+| 场景  | 测试功能                | 对比工具               | 测试重点                   |
+|-------|-------------------------|------------------------|----------------------------|
+| 场景1 | 符号搜索 (-s/-S)        | grep/rg                | 精确/模糊匹配、类型识别     |
+| 场景2 | 模块依赖分析 (deps)     | grep/rg                | 双向依赖、循环检测、排名统计 |
+| 场景3 | 影响范围分析 (impact)   | grep                   | 传递依赖、风险评估          |
+| 场景4 | 复杂度分析 (complexity) | ESLint/SonarQube(理论) | 圈复杂度、可维护性指数      |
+| 场景5 | 查询与JSON输出 (query)  | grep/rg                | 多模式查询、结构化输出      |
+
+### 1.2 关键发现总结
+
+**✅ 核心优势**:
+- **语义化理解**: 识别符号类型（interface/class/function），区分定义和引用
+- **独有功能**: 传递依赖分析、循环依赖检测、风险评估
+- **结构化输出**: JSON格式支持，便于工具链集成
+- **双向分析**: 同时查看依赖和被依赖关系
+
+**❌ 关键问题**:
+- **性能严重落后**: 比rg/grep慢60-300倍
+- **搜索算法缺陷**: 符号搜索遗漏关键类（如GitAnalyzer）
+- **指标计算错误**: 可维护性指数全部为100（完全不可用）
+- **re-export遗漏**: 未检测通过re-export模式的依赖
+
+### 1.3 整体评分
+
+| 评估维度   | 评分       | 权重     | 加权得分   |
+|------------|------------|----------|------------|
+| 功能完整性 | ⭐⭐⭐⭐ (4/5) | 25%      | 1.0        |
+| 准确性     | ⭐⭐⭐ (3/5)  | 25%      | 0.75       |
+| 性能       | ⭐⭐ (2/5)   | 20%      | 0.4        |
+| 易用性     | ⭐⭐⭐⭐ (4/5) | 15%      | 0.6        |
+| 输出质量   | ⭐⭐⭐⭐ (4/5) | 15%      | 0.6        |
+| **总分**   |            | **100%** | **3.35/5** |
+
+**综合评级**: ⭐⭐⭐ (良好，有显著改进空间)
+
+---
+
+## 2. CodeMap 优势（按场景）
+
+### 场景1: 符号搜索
+
+| 优势         | 说明                                   |
+|--------------|----------------------------------------|
+| 符号类型识别 | 自动识别interface/variable/class等类型 |
+| 导出信息     | 显示符号是否导出，便于理解模块API       |
+| 结构化输出   | 带类型标签的清晰格式                   |
+| 去重能力     | 符号级去重，避免重复显示                |
+
+### 场景2: 模块依赖分析
+
+| 优势         | 说明                         | 独有性 |
+|--------------|------------------------------|--------|
+| 双向依赖     | 同时显示导入(⬇️)和被导入(⬆️) | ✅ 独有 |
+| 循环依赖检测 | 一键检测项目中的循环依赖     | ✅ 独有 |
+| 依赖排名     | 自动按依赖数排名Top 20       | ✅ 独有 |
+| 模块分类     | 自动区分source/test类型      | ✅ 独有 |
+
+### 场景3: 影响范围分析
+
+| 优势         | 说明                                | 独有性 |
+|--------------|-------------------------------------|--------|
+| 传递依赖分析 | 显示间接影响的所有模块（距离标记）    | ✅ 独有 |
+| 风险评估     | 量化风险等级（极高/高/中/低）         | ✅ 独有 |
+| 零误报率     | 依赖识别准确率100%，grep误报率20-60% | ✅ 优势 |
+| 可视化树     | 树形结构展示依赖关系                | ✅ 独有 |
+
+### 场景4: 复杂度分析
+
+| 优势     | 说明                     |
+|----------|--------------------------|
+| 执行速度 | 0.6-0.8秒完成全项目分析  |
+| 快速概览 | 快速识别最复杂的15个文件 |
+| 风险分级 | 高/中/低风险分级展示     |
+| JSON支持 | 便于CI/CD集成            |
+
+### 场景5: 查询与JSON输出
+
+| 优势       | 说明                            |
+|------------|---------------------------------|
+| 多模式查询 | 符号/模块/依赖/模糊搜索四种模式 |
+| 语义化理解 | 理解代码结构，非纯文本匹配       |
+| 边界处理   | 空结果、特殊字符处理得当         |
+| 中文本地化 | 友好的中文错误提示和帮助        |
+
+---
+
+## 3. 发现的问题清单（按优先级）
+
+### P0 - 严重问题（阻碍使用）
+
+| 优先级 | 问题                     | 影响场景 | 修复难度 | 详细说明                                                                  |
+|--------|--------------------------|----------|----------|---------------------------------------------------------------------------|
+| P0     | **符号搜索严重遗漏**     | 场景1, 5 | 高       | 搜索"Analyzer"未找到`GitAnalyzer`类，只返回不相关变量；子串匹配算法存在缺陷 |
+| P0     | **可维护性指数计算错误** | 场景4    | 中       | 所有104个文件显示为100，计算公式`171 - 5.2*ln(loc) - 0.23*cyc`实现有误     |
+| P0     | **性能严重落后**         | 所有场景 | 高       | 比rg慢60-300倍：符号搜索70倍、依赖分析200倍、影响分析80倍                    |
+| P0     | **re-export依赖遗漏**    | 场景2, 3 | 中       | 未检测`export { foo } from './module'`模式的依赖关系                      |
+
+### P1 - 中等问题（影响体验）
+
+| 优先级 | 问题                         | 影响场景 | 修复难度 | 详细说明                                                       |
+|--------|------------------------------|----------|----------|----------------------------------------------------------------|
+| P1     | **圈复杂度估算而非精确计算** | 场景4    | 中       | 基于`functions + classes + 1`估算，非真正分析控制流语句         |
+| P1     | **认知复杂度过于简化**       | 场景4    | 中       | 仅`cyclomatic * 1.5`，未考虑嵌套深度、递归等因素                 |
+| P1     | **JSON details字段非结构化** | 场景5    | 低       | "定义于 src/types/index.ts:154"为自然语言，需正则解析           |
+| P1     | **大小写处理不一致**         | 场景1, 5 | 低       | 搜索"ModuleInfo"返回"moduleInfo"变量，但"cache"搜索又区分大小写 |
+| P1     | **路径扩展名不一致**         | 场景2    | 低       | 显示`.js`而非源代码`.ts`扩展名                                 |
+| P1     | **依赖查询结果重复**         | 场景5    | 低       | `query -d`同时返回dependency和import类型，内容重复              |
+| P1     | **命令输出格式不一致**       | 场景5    | 低       | `deps -j`和`query -d -j`返回完全不同的JSON结构                 |
+
+### P2 - 轻微问题（改进建议）
+
+| 优先级 | 问题                     | 影响场景 | 修复难度 | 详细说明                              |
+|--------|--------------------------|----------|----------|---------------------------------------|
+| P2     | **缺少函数级复杂度详情** | 场景4    | 中       | 仅文件级分析，无法定位具体复杂函数     |
+| P2     | **缺少正则表达式支持**   | 场景5    | 低       | 模糊搜索仅支持子字符串，不支持regex    |
+| P2     | **dependents使用内部ID** | 场景2, 5 | 低       | 返回"iucg3n"等ID而非路径，可读性差     |
+| P2     | **风险等级阈值跳跃**     | 场景3    | 低       | 13和38依赖都被归为"极高"，缺少中间等级 |
+| P2     | **缺少代码上下文**       | 场景1    | 低       | 不像rg显示匹配行的代码片段            |
+| P2     | **缺少传递依赖深度控制** | 场景2, 3 | 低       | 不支持`--depth`参数限制依赖深度       |
+| P2     | **复杂度数据未存储**     | 场景4    | 低       | codemap.json中complexity字段为空对象  |
+
+---
+
+## 4. 与传统工具对比总结
+
+### 4.1 速度对比
+
+| 场景       | CodeMap | rg     | grep   | 速度比 (rg/CodeMap) |
+|------------|---------|--------|--------|---------------------|
+| 符号搜索   | 0.538s  | 0.008s | 0.003s | 67x / 179x          |
+| 模糊搜索   | 0.642s  | 0.007s | -      | 91x                 |
+| 模块依赖   | 0.658s  | 0.003s | -      | 219x                |
+| 影响分析   | 0.800s  | 0.010s | -      | 80x                 |
+| 复杂度分析 | 0.673s  | N/A    | N/A    | -                   |
+| 查询(平均) | 0.583s  | 0.007s | 0.003s | 83x / 194x          |
+
+### 4.2 功能对比
+
+| 场景           | CodeMap 优势                     | CodeMap 劣势                   | 推荐工具                       |
+|----------------|----------------------------------|--------------------------------|--------------------------------|
+| **符号搜索**   | 符号类型识别、导出信息、结构化输出 | 速度慢、结果数量有限、遗漏类定义 | 查找定义用CodeMap，快速搜索用rg |
+| **模块依赖**   | 双向分析、循环检测、排名统计       | 速度慢、路径显示不一致          | 依赖分析用CodeMap，快速查看用rg |
+| **影响分析**   | 传递依赖、风险评估、零误报         | 遗漏re-export、速度慢           | 影响分析必用CodeMap            |
+| **复杂度分析** | 速度极快、风险分级                | 指标计算错误、缺少函数级详情    | 目前不推荐用于质量门禁         |
+| **查询输出**   | JSON结构化、多模式查询            | 速度慢、缺少正则支持            | API集成用CodeMap，实时搜索用rg  |
+
+### 4.3 准确性对比
+
+| 场景         | CodeMap 准确率 | grep/rg 准确率 | 说明                      |
+|--------------|----------------|----------------|---------------------------|
+| 直接依赖识别 | 100%           | 40-80%         | CodeMap几乎零误报         |
+| 传递依赖识别 | 独有功能       | 无法完成       | CodeMap独有优势           |
+| 符号类型识别 | 部分问题       | 不支持         | CodeMap能识别类型但有遗漏 |
+| 循环依赖检测 | 独有功能       | 几乎不可行     | CodeMap一键检测           |
+
+### 4.4 综合推荐
+
+| 需求         | 推荐工具             | 原因                                  |
+|--------------|----------------------|---------------------------------------|
+| 快速文本搜索 | **rg/grep**          | 速度快60-300倍，无需索引               |
+| 符号定义查找 | **CodeMap**          | 结构化输出，带类型信息（需修复搜索算法） |
+| 依赖分析     | **CodeMap**          | 双向分析、循环检测、传递依赖            |
+| 影响范围评估 | **CodeMap**          | 独有传递依赖分析，风险评估             |
+| 复杂度监控   | **ESLint/SonarQube** | CodeMap指标计算不准确                 |
+| CI/CD集成    | **CodeMap**          | JSON输出便于自动化（需修复格式问题）    |
+| IDE插件开发  | **CodeMap**          | 语义化查询，结构化输出                 |
+
+---
+
+## 5. 修复计划
+
+### 阶段1: P0问题修复（2-3周）
+
+| 序号 | 修复项            | 具体措施                                                            | 预期效果                 |
+|------|-------------------|---------------------------------------------------------------------|--------------------------|
+| 1.1  | 修复符号搜索算法  | 实现正确的子串匹配；确保"Analyzer"匹配"GitAnalyzer"；检查索引查询逻辑 | 搜索准确性提升至99%+     |
+| 1.2  | 修复可维护性指数  | 修正计算公式；参考Microsoft Maintainability Index标准                | 指标恢复参考价值         |
+| 1.3  | 实现缓存机制      | 添加内存缓存；支持守护进程模式；增量索引更新                          | 性能提升5-10倍           |
+| 1.4  | 支持re-export检测 | 解析`export { } from`和`export * from`语法                          | 依赖分析完整性提升至100% |
+
+### 阶段2: P1问题修复（1-2周）
+
+| 序号 | 修复项               | 具体措施                                                      | 预期效果       |
+|------|----------------------|---------------------------------------------------------------|----------------|
+| 2.1  | 实现精确圈复杂度计算 | 基于AST分析if/for/while/case/catch等控制流语句                | 指标准确性提升 |
+| 2.2  | 改进认知复杂度算法   | 参考SonarQube实现，考虑嵌套深度和递归                          | 算法专业性提升 |
+| 2.3  | 结构化JSON输出       | 添加`location: {file, line, column}`对象；分离`isExported`字段 | API可用性提升  |
+| 2.4  | 统一大小写处理       | 添加`--case-sensitive`选项；默认大小写敏感                     | 行为一致性     |
+| 2.5  | 修复路径显示         | 默认显示`.ts`路径；添加`--build-paths`选项显示`.js`            | 用户体验提升   |
+| 2.6  | 统一命令输出格式     | 统一`deps`和`query -d`的JSON结构                              | API一致性      |
+
+### 阶段3: P2功能增强（2-4周）
+
+| 序号 | 增强项               | 具体措施                                  | 预期效果               |
+|------|----------------------|-------------------------------------------|------------------------|
+| 3.1  | 函数级复杂度分析     | 添加`--detail`选项显示函数级复杂度        | 支持代码审查           |
+| 3.2  | 正则搜索支持         | 添加`--regex`选项                         | 查询灵活性提升         |
+| 3.3  | 修复dependents可读性 | 返回模块路径而非内部ID                    | 输出可读性提升         |
+| 3.4  | 细化风险等级         | 增加阈值等级：0-2低/3-10中/11-25高/26+极高 | 风险评估更精确         |
+| 3.5  | 添加代码上下文       | 显示匹配行的代码片段（类似rg）              | 调试便利性提升         |
+| 3.6  | 支持依赖深度控制     | 添加`--depth`参数限制传递依赖深度         | 性能与灵活性平衡       |
+| 3.7  | 预计算复杂度数据     | 在generate阶段计算并存储复杂度数据        | complexity命令性能提升 |
+
+### 修复时间表
+
+```
+周次:  1    2    3    4    5    6    7    8
+      ├────P0修复────┤
+                     ├────P1修复────┤
+                                    ├────P2增强────┤
+```
+
+**里程碑**:
+- **W3**: P0问题修复完成，发布v0.1.1
+- **W5**: P1问题修复完成，发布v0.1.2
+- **W8**: P2功能增强完成，发布v0.2.0
+
+---
+
+## 6. 使用建议
+
+### 6.1 推荐使用场景
+
+| 场景               | 使用方式                | 示例命令                                                               |
+|--------------------|-------------------------|------------------------------------------------------------------------|
+| **重构前影响分析** | 必用impact命令          | `npx codemap impact -f src/core/analyzer.ts --transitive`                |
+| **依赖架构审查**   | 必用deps命令            | `npx codemap deps -m "src/parser"`                                       |
+| **循环依赖检测**   | 必用cycles命令          | `npx codemap cycles`                                                     |
+| **发布前风险评估** | impact + complexity组合 | `npx codemap impact -f changed.ts && npx codemap complexity -f changed.ts` |
+| **IDE插件开发**    | query + JSON输出        | `npx codemap query -s "SymbolName" -j`                                   |
+| **CI/CD依赖检查**  | deps + cycles           | `npx codemap deps && npx codemap cycles`                                   |
+
+### 6.2 不推荐/需谨慎场景
+
+| 场景                   | 原因            | 替代方案                  |
+|------------------------|-----------------|---------------------------|
+| 纯文本快速搜索         | 速度慢100-300倍 | 使用`rg`或`grep`          |
+| 高频实时监控           | 性能瓶颈        | 使用`rg`或文件系统监听    |
+| 复杂度质量门禁         | 指标计算不准确  | 使用ESLint或SonarQube     |
+| 代码审查中定位复杂函数 | 缺少函数级详情  | 使用ESLint complexity规则 |
+
+### 6.3 混合使用策略
+
+```bash
+# 场景1: 快速定位符号定义，然后理解上下文
+npx codemap query -s "ModuleInfo" -j           # 获取定义位置和类型
+rg -n "ModuleInfo" src/ -A 3 -B 1            # 查看代码上下文
+
+# 场景2: 分析变更影响范围
+npx codemap impact -f src/core/analyzer.ts --transitive   # 获取传递依赖
+rg -l "analyzer" src/                                   # 快速文本验证
+
+# 场景3: 依赖分析 + 复杂度检查
+npx codemap deps -m "src/core"                 # 分析模块依赖
+npx codemap complexity -f src/core/analyzer.ts # 检查复杂度（仅供参考）
+eslint src/core/analyzer.ts --rule 'complexity: [error, 10]'  # 精确复杂度检查
+```
+
+### 6.4 配置文件建议
+
+建议创建`codemap.config.json`:
+
+```json
+{
+  "query": {
+    "defaultLimit": 20,
+    "caseSensitive": true
+  },
+  "deps": {
+    "showBuildPaths": false,
+    "maxDepth": 5
+  },
+  "complexity": {
+    "cyclomaticThresholds": { "low": 10, "medium": 20, "high": 30 },
+    "excludePatterns": ["*.test.ts", "*.spec.ts"]
+  },
+  "output": {
+    "defaultFormat": "human",
+    "jsonLocationStructured": true
+  }
+}
+```
+
+---
+
+## 7. 附录
+
+### 7.1 测试原始数据
+
+| 指标       | 数值       |
+|------------|------------|
+| 总文件数   | 104        |
+| 总行数     | 28,878     |
+| 总模块数   | 104        |
+| 总导出     | 378        |
+| 总类型     | 70         |
+| 总依赖关系 | 350        |
+| 高风险文件 | 6 (5.8%)   |
+| 中风险文件 | 15 (14.4%) |
+| 低风险文件 | 83 (79.8%) |
+
+### 7.2 发现的符号清单
+
+| 符号名                     | 类型      | 位置                                           |
+|----------------------------|-----------|------------------------------------------------|
+| `ModuleInfo`               | interface | src/types/index.ts:154                         |
+| `GitAnalyzer`              | class     | src/orchestrator/git-analyzer.ts:121           |
+| `ComplexityAnalyzerPlugin` | class     | src/plugins/built-in/complexity-analyzer.ts:96 |
+| `analyze`                  | function  | src/core/analyzer.ts                           |
+| `LRUCache`                 | class     | src/cache/lru-cache.ts                         |
+
+### 7.3 参考文档
+
+- 场景1详细报告: `/data/codemap/test-report-symbol-search.md`
+- 场景2详细报告: `/data/codemap/test-reports/scenario-2-deps-analysis.md`
+- 场景3详细报告: `/data/codemap/test_scenario_3_impact_analysis_report.md`
+- 场景4详细报告: `/data/codemap/test-scenario-4-complexity-analysis.md`
+- 场景5详细报告: `/data/codemap/test_report_scenario5.md`
+
+---
+
+*报告生成时间: 2026-03-02*  
+*报告生成者: 测试协调员*  
+*版本: v1.0*