@mycodemap/mycodemap 0.4.1 → 0.5.0

package/docs/archive/test-scenario-4-complexity-analysis.md

@@ -0,0 +1,460 @@
+# 测试场景 4: 代码复杂度分析测试报告
+
+## 测试目标
+测试 `codemap complexity` 功能的有效性和实用性，验证其计算准确性、输出质量和实际开发中的价值。
+
+---
+
+## 测试环境
+- **CodeMap 版本**: 0.1.0
+- **测试目录**: /data/codemap
+- **项目规模**: 104 个 TypeScript 文件，28,878 行代码
+- **测试时间**: 2026-03-01
+
+---
+
+## 测试用例 1: 分析整个项目复杂度
+
+### CodeMap 执行
+```bash
+time npx codemap complexity
+```
+
+**输出:**
+```
+📊 项目复杂度分析
+──────────────────────────────────────────────────
+
+🔥 复杂度最高的文件 (Top 15):
+
+   1. src/parser/implementations/smart-parser.ts
+      圈复杂度: 48 高
+      认知复杂度: 72
+      可维护性: 100 高
+
+   2. src/orchestrator/workflow/workflow-orchestrator.ts
+      圈复杂度: 23 高
+      认知复杂度: 35
+      可维护性: 100 高
+
+   3. src/orchestrator/test-linker.ts
+      圈复杂度: 22 高
+      认知复杂度: 33
+      可维护性: 100 高
+
+   ... (共 15 个文件)
+
+📈 项目统计:
+   总文件数: 104
+   平均圈复杂度: 6.24 低
+   平均认知复杂度: 9.72
+   平均可维护性: 100.00 高
+```
+
+**执行时间**: 0.673s (user 0.837s)
+
+---
+
+## 测试用例 2: 分析特定文件复杂度
+
+### 2.1 analyzer.ts
+```bash
+time npx codemap complexity -f src/core/analyzer.ts
+```
+
+**输出:**
+```
+📊 文件复杂度: src/core/analyzer.ts
+──────────────────────────────────────────────────
+
+圈复杂度 (Cyclomatic Complexity):
+   13 中
+   衡量代码中独立路径的数量
+
+认知复杂度 (Cognitive Complexity):
+   20 (越低越好)
+   衡量代码的理解难度
+
+可维护性指数 (Maintainability):
+   100 高
+   0-100，越高越易维护
+
+统计信息:
+   代码行数: 293
+   函数/方法: 13
+   类: 0
+```
+
+**执行时间**: 0.791s
+
+### 2.2 smart-parser.ts
+```bash
+time npx codemap complexity -f src/parser/implementations/smart-parser.ts
+```
+
+**输出:**
+```
+📊 文件复杂度: src/parser/implementations/smart-parser.ts
+──────────────────────────────────────────────────
+
+圈复杂度 (Cyclomatic Complexity):
+   48 高
+   衡量代码中独立路径的数量
+
+认知复杂度 (Cognitive Complexity):
+   72 (越低越好)
+   衡量代码的理解难度
+
+可维护性指数 (Maintainability):
+   100 高
+
+统计信息:
+   代码行数: 1166
+   函数/方法: 47
+   类: 1
+```
+
+**执行时间**: 0.671s
+
+### 2.3 tool-orchestrator.ts
+```bash
+time npx codemap complexity -f src/orchestrator/tool-orchestrator.ts
+```
+
+**输出:**
+```
+📊 文件复杂度: src/orchestrator/tool-orchestrator.ts
+──────────────────────────────────────────────────
+
+圈复杂度 (Cyclomatic Complexity):
+   9 低
+   衡量代码中独立路径的数量
+
+认知复杂度 (Cognitive Complexity):
+   14 (越低越好)
+   衡量代码的理解难度
+
+可维护性指数 (Maintainability):
+   100 高
+
+统计信息:
+   代码行数: 177
+   函数/方法: 8
+   类: 1
+```
+
+**执行时间**: 0.561s
+
+---
+
+## 测试用例 3: JSON 格式输出
+
+```bash
+time npx codemap complexity -j | head -50
+```
+
+**输出:**
+```json
+{
+  "modules": [
+    {
+      "path": "src/index.ts",
+      "cyclomatic": 1,
+      "cognitive": 2,
+      "maintainability": 100,
+      "functions": 0,
+      "classes": 0,
+      "lines": 4
+    },
+    {
+      "path": "src/ai/claude.ts",
+      "cyclomatic": 6,
+      "cognitive": 9,
+      "maintainability": 100,
+      "functions": 5,
+      "classes": 1,
+      "lines": 145
+    }
+    ...
+  ],
+  "summary": {
+    "totalModules": 104,
+    "averageCyclomatic": 6.24,
+    "averageCognitive": 9.72,
+    "averageMaintainability": 100.00
+  }
+}
+```
+
+**执行时间**: 0.554s
+
+---
+
+## 对比分析
+
+### 执行速度对比
+
+| 工具 | 分析整个项目 | 单文件分析 | 备注 |
+|------|-------------|-----------|------|
+| CodeMap | 0.67s | 0.56-0.79s | 基于已有 codemap.json |
+| 理论 ESLint | 5-10s | 1-2s | 需要完整 AST 解析 |
+| 理论 SonarQube | 分钟级 | N/A | 需要服务器支持 |
+
+**结论**: CodeMap 执行速度非常快，因为它直接从已生成的代码地图读取数据，无需重新解析源代码。
+
+### 风险分布分析
+
+| 风险等级 | 圈复杂度阈值 | 文件数量 | 占比 |
+|---------|-------------|---------|------|
+| 高风险 | > 20 | 6 | 5.8% |
+| 中风险 | 10-20 | 15 | 14.4% |
+| 低风险 | ≤ 10 | 83 | 79.8% |
+
+### 高风险文件清单
+
+| 排名 | 文件路径 | 圈复杂度 | 认知复杂度 | 代码行数 |
+|-----|---------|---------|-----------|---------|
+| 1 | smart-parser.ts | 48 | 72 | 1166 |
+| 2 | workflow-orchestrator.ts | 23 | 35 | ~500 |
+| 3 | test-linker.ts | 22 | 33 | ~350 |
+| 4 | cache/index.ts | 21 | 32 | 217 |
+| 5 | parser/index.ts | 21 | 32 | ~300 |
+| 6 | plugin-loader.ts | 21 | 32 | ~280 |
+
+---
+
+## 复杂度计算验证
+
+### 手动验证圈复杂度
+
+**测试函数**: `getModuleComplexity` (src/cli/commands/complexity.ts:64-93)
+
+```typescript
+function getModuleComplexity(module: ModuleInfo): ComplexityInfo {
+  if (module.complexity) {           // +1 (if)
+    return { ... };
+  }
+  
+  const functions = ...;             // 0
+  const classes = ...;               // 0
+  const cyclomatic = Math.max(1, functions + classes);  // 0
+  const cognitive = cyclomatic * 1.5; // 0
+  const loc = module.stats.codeLines; // 0
+  const maintainability = Math.max(0, Math.min(100, ...));  // +1 (条件表达式)
+  
+  return { ... };                     // 0
+}
+```
+
+**预期圈复杂度**: 1 (基础) + 1 (if) = 2
+**CodeMap 显示**: 函数数量为 1，圈复杂度基于 `functions + classes + 1` 估算
+
+### 验证结果
+
+CodeMap 的复杂度计算采用**估算模式**而非精确 AST 分析：
+
+```typescript
+// 从代码中的计算方法
+const functions = module.symbols.filter(s => s.kind === 'function' || s.kind === 'method').length;
+const classes = module.symbols.filter(s => s.kind === 'class').length;
+const cyclomatic = Math.max(1, functions + classes);
+const cognitive = cyclomatic * 1.5;
+```
+
+**问题**: 这种方法只是统计函数和类数量，而非真正分析控制流语句（if/for/while/case等）。
+
+---
+
+## 发现的问题
+
+### 🔴 严重问题
+
+1. **可维护性指数计算错误**
+   - **现象**: 所有 104 个文件的可维护性指数均为 **100**
+   - **原因**: 计算公式 `maintainability = Math.max(0, Math.min(100, 171 - 5.2 * Math.log(loc + 1) - 0.23 * cyclomatic))`
+   - **影响**: 该指标完全失去参考价值
+   - **建议**: 修复计算公式，参考微软的 Maintainability Index 标准
+
+2. **圈复杂度为估算值，非精确计算**
+   - **现象**: smart-parser.ts 有 1582 行代码，47 个函数，圈复杂度显示 48
+   - **计算**: 47 个函数 + 1 = 48，与代码行数无关
+   - **问题**: 没有真正分析控制流语句
+   - **建议**: 基于 AST 分析 if/for/while/case/catch 等语句
+
+### 🟡 中等问题
+
+3. **缺乏函数级别的复杂度详情**
+   - CodeMap 只提供文件级复杂度
+   - 无法识别具体哪个函数复杂度过高
+   - 建议: 增加 `--detail` 选项显示函数级复杂度
+
+4. **认知复杂度计算过于简化**
+   - 当前实现: `cognitive = cyclomatic * 1.5`
+   - 标准认知复杂度应考虑嵌套深度、递归等因素
+   - 建议: 实现 SonarQube 风格的认知复杂度算法
+
+5. **codemap.json 中不存储复杂度数据** ✅ 已修复
+   - 现象: 所有模块的 `complexity` 字段为空对象 `{}`
+   - 修复: 扩展 `calculateComplexity` 方法以支持 `MethodDeclaration` 和 `ArrowFunction`
+   - 验证: smart-parser.ts 现在存储正确的复杂度数据 (cyclomatic: 417)
+   - 复杂度命令现在直接读取 codemap.json 中的数据，无需重新计算
+
+### 🟢 轻微问题
+
+6. **输出格式可以更丰富**
+   - 缺少趋势线图
+   - 缺少与行业标准的对比
+   - 缺少重构建议
+
+7. **复杂度评级阈值可以配置**
+   - 当前阈值: 低(≤10), 中(11-20), 高(21-50), 极高(>50)
+   - 建议: 支持自定义阈值
+
+---
+
+## 与业界标准对比
+
+### 复杂度阈值对比
+
+| 工具/标准 | 低复杂度 | 中复杂度 | 高复杂度 | 极高复杂度 |
+|----------|---------|---------|---------|-----------|
+| CodeMap | ≤ 10 | 11-20 | 21-50 | > 50 |
+| ESLint | - | - | > 20 | - |
+| SonarQube | ≤ 10 | 11-20 | 21-30 | > 30 |
+| McCabe | - | - | > 10 | - |
+
+### 认知复杂度对比
+
+| 工具 | 计算方法 | 嵌套惩罚 | 逻辑运算符处理 |
+|-----|---------|---------|--------------|
+| CodeMap | 圈复杂度的 1.5 倍 | ❌ 无 | ❌ 不处理 |
+| SonarQube | 结构化遍历 | ✅ 有 | ✅ 处理 |
+| ESLint | 不支持 | - | - |
+
+### 可维护性指数对比
+
+| 工具 | 计算公式 | Halstead 指标 | 代码行数 | 圈复杂度 |
+|-----|---------|--------------|---------|---------|
+| CodeMap | 171 - 5.2*ln(loc) - 0.23*cyc | ❌ 无 | ✅ | ✅ |
+| Visual Studio | 标准 MI 公式 | ✅ 有 | ✅ | ✅ |
+| SonarQube | 自定义公式 | ✅ 有 | ✅ | ✅ |
+
+---
+
+## 实际开发中的实用价值评估
+
+### ✅ 优势
+
+1. **快速概览**: 0.6 秒内获得项目整体复杂度分布
+2. **风险识别**: 能够快速定位最复杂的 15 个文件
+3. **简单直观**: 输出格式清晰，非技术人员也能理解
+4. **CI/CD 友好**: JSON 输出便于自动化处理
+
+### ❌ 局限性
+
+1. **无法用于代码审查**: 缺少函数级详情
+2. **无法跟踪趋势**: 不支持历史对比
+3. **无法提供重构建议**: 只显示数值，不指导改进
+4. **指标不可靠**: 可维护性指数全部相同
+
+---
+
+## 改进建议
+
+### 高优先级
+
+1. **修复可维护性指数计算**
+   ```typescript
+   // 建议实现
+   function calculateMI(loc: number, cyclomatic: number, commentRatio: number): number {
+     // 使用标准 Microsoft Maintainability Index 公式
+     const mi = 171 - 5.2 * Math.log2(loc) - 0.23 * cyclomatic - 16.2 * Math.log2(loc);
+     return Math.max(0, Math.min(100, mi + 50 * commentRatio));
+   }
+   ```
+
+2. **实现真正的圈复杂度计算**
+   ```typescript
+   // 在 SmartParser 中实现
+   private calculateCyclomatic(sourceFile: ts.SourceFile): number {
+     let complexity = 1;
+     const visit = (node: ts.Node) => {
+       if (ts.isIfStatement(node) || ts.isWhileStatement(node) ||
+           ts.isForStatement(node) || ts.isCaseClause(node) ||
+           ts.isCatchClause(node) || ts.isConditionalExpression(node)) {
+         complexity++;
+       }
+       ts.forEachChild(node, visit);
+     };
+     visit(sourceFile);
+     return complexity;
+   }
+   ```
+
+3. **存储复杂度数据到 codemap.json**
+   - 在 `generate` 阶段计算并存储
+   - complexity 命令直接读取，无需重新计算
+
+### 中优先级
+
+4. **增加函数级复杂度分析**
+   ```bash
+   npx codemap complexity -f src/core/analyzer.ts --detail
+   ```
+
+5. **支持复杂度趋势分析**
+   ```bash
+   npx codemap complexity --trend --since="2 weeks ago"
+   ```
+
+6. **增加重构建议**
+   - 圈复杂度过高 → 建议提取函数
+   - 认知复杂度过高 → 建议减少嵌套
+   - 可维护性过低 → 建议增加注释
+
+### 低优先级
+
+7. **可视化输出**
+   - HTML 报告
+   - 复杂度热力图
+   - 趋势图表
+
+8. **配置文件支持**
+   ```json
+   // codemap.config.json
+   {
+     "complexity": {
+       "cyclomaticThresholds": { "low": 10, "medium": 20, "high": 30 },
+       "excludePatterns": ["*.test.ts"]
+     }
+   }
+   ```
+
+---
+
+## 总结
+
+| 维度 | 评分 | 说明 |
+|-----|------|------|
+| 执行速度 | ⭐⭐⭐⭐⭐ | 极快，0.6-0.8 秒 |
+| 圈复杂度准确性 | ⭐⭐ | 估算值，非精确计算 |
+| 认知复杂度准确性 | ⭐⭐ | 过于简化 |
+| 可维护性指数准确性 | ⭐ | 全部为 100，完全不可用 |
+| 输出可读性 | ⭐⭐⭐⭐ | 清晰直观 |
+| JSON 输出实用性 | ⭐⭐⭐⭐ | 结构化良好 |
+| 风险识别能力 | ⭐⭐⭐ | 能找出高复杂度文件，但缺少函数级详情 |
+| 实际开发价值 | ⭐⭐⭐ | 适合快速概览，不适合深度分析 |
+
+### 总体评价
+
+CodeMap 的复杂度分析功能适合作为**项目健康度的快速概览工具**，但**不适合用于代码审查或质量门禁**。
+
+**建议**: 
+- 短期：修复可维护性指数计算 bug
+- 中期：实现基于 AST 的精确复杂度计算
+- 长期：增加函数级分析和重构建议
+
+---
+
+*测试报告生成时间: 2026-03-01*
+*测试执行者: CodeMap 测试专家*