@mycodemap/mycodemap 0.4.1 → 0.5.0

package/docs/archive/test_scenario_3_impact_analysis_report.md

@@ -0,0 +1,520 @@
+# 测试场景3：影响范围分析对比测试报告
+
+## 测试概述
+
+**测试目标**: 对比 CodeMap `impact` 命令与手动 `grep` 分析文件变更影响范围的差异
+
+**测试时间**: 2025年3月2日  
+**测试目录**: `/data/codemap`  
+**CodeMap版本**: 本地构建版本
+
+---
+
+## 测试用例 1: src/core/analyzer.ts 影响分析
+
+### 测试目的
+分析核心分析器文件的变更影响范围，对比 CodeMap 的依赖图分析与手动 grep 文本搜索的差异。
+
+### CodeMap 执行 (直接依赖)
+
+```bash
+npx codemap impact -f src/core/analyzer.ts
+```
+
+**执行时间**: 0.539s (real)
+
+**输出**:
+```
+📍 影响分析
+──────────────────────────────────────────────────
+
+目标文件:
+   src/core/analyzer.ts
+   导出: analyze
+
+⬇️  直接依赖该文件的模块 (13):
+   • src/orchestrator/ai-feed-generator.ts
+   • src/orchestrator/result-fusion.ts
+   • src/watcher/watch-worker.ts
+   • src/core/__tests__/analyzer.test.ts
+   • src/cli/__tests__/generate.test.ts
+   • src/cli/commands/ci.ts
+   • src/cli/commands/generate.ts
+   • src/cli/commands/watch-foreground.ts
+   • src/orchestrator/__tests__/ai-feed-generator.test.ts
+   • src/orchestrator/__tests__/git-analyzer.test.ts
+   • src/parser/implementations/tree-sitter-parser.ts
+   • src/plugins/__tests__/complexity-analyzer.test.ts
+   • src/cli/commands/__tests__/watch-foreground.test.ts
+
+⚠️  风险评估:
+   🔴 极高风险 - 该文件是核心依赖，修改将影响大量模块
+   直接影响: 13 个模块
+```
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/core/analyzer.ts --transitive
+```
+
+**执行时间**: 0.698s (real)
+
+**输出**:
+```
+直接依赖该文件的模块 (13):
+   [同上]
+
+🌐 传递依赖 (66):
+       └─► src/cli/index.ts [距离: 3]
+         └─► src/ai/claude.ts [距离: 4]
+         └─► src/ai/codex.ts [距离: 4]
+         ... 还有 46 个
+
+直接影响: 13 个模块
+传递影响: 66 个额外模块
+```
+
+### 传统工具执行
+
+```bash
+rg -l "analyzer|Analyzer" src/ | head -20
+```
+
+**执行时间**: 0.010s (real)
+
+**输出**:
+```
+src/watcher/watch-worker.ts
+src/cli/__tests__/generate.test.ts
+src/cli/commands/__tests__/generate.test.ts
+src/cli/commands/__tests__/watch-foreground.test.ts
+src/plugins/built-in/complexity-analyzer.ts
+src/cli/commands/watch-foreground.ts
+src/core/__tests__/analyzer.test.ts
+src/cli/commands/ci.ts
+src/core/analyzer.ts
+src/cli/commands/generate.ts
+src/plugins/__tests__/complexity-analyzer.test.ts
+src/plugins/index.ts
+src/plugins/plugin-loader.ts
+src/index.ts
+src/orchestrator/ai-feed-generator.ts
+src/orchestrator/index.ts
+src/orchestrator/result-fusion.ts
+src/orchestrator/git-analyzer.ts
+src/orchestrator/__tests__/git-analyzer.test.ts
+src/orchestrator/__tests__/ai-feed-generator.test.ts
+```
+
+**匹配文件总数**: 22 个
+
+### 对比分析
+
+| 维度 | CodeMap Direct | CodeMap Transitive | Grep | 结论 |
+|------|----------------|-------------------|------|------|
+| **执行时间** | 0.54s | 0.70s | 0.01s | Grep 更快 (54-70x) |
+| **直接依赖数** | 13 | 13 | 22 | Grep 包含大量误报 |
+| **传递依赖数** | 未显示 | 66 | N/A | CodeMap 独有功能 |
+| **依赖深度** | ❌ | ✅ (显示距离) | ❌ | CodeMap 传递模式优势 |
+| **风险评估** | ✅ 极高风险 | ✅ 极高风险 | ❌ | CodeMap 独有功能 |
+| **导出信息** | ✅ | ✅ | ❌ | CodeMap 独有功能 |
+| **误报率** | 低 | 低 | 高 (40%) | CodeMap 更准确 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的 "依赖"**:
+```
+src/cli/commands/__tests__/generate.test.ts  (不包含 analyzer 导入)
+src/core/analyzer.ts                          (文件自身)
+src/index.ts                                  ✅ 应该被检测！
+src/orchestrator/git-analyzer.ts              (独立模块，非依赖)
+src/orchestrator/index.ts                     (通过 git-analyzer 导入)
+src/plugins/built-in/complexity-analyzer.ts   (独立模块)
+src/plugins/index.ts                          (通过 complexity-analyzer 导入)
+src/plugins/plugin-loader.ts                  (通过 complexity-analyzer 导入)
+```
+
+**关键发现**: 
+- `src/index.ts` 确实导出了 `analyze` 函数 (`export { analyze } from './core/analyzer.js'`)，但 CodeMap 未检测到这是 analyzer.ts 的依赖
+- Grep 找到的 22 个文件中，约 9 个是误报（文件名含 analyzer 但实际不依赖 core/analyzer.ts）
+- CodeMap 的 13 个直接依赖都是准确的导入关系
+
+---
+
+## 测试用例 2: src/types/index.ts 影响分析
+
+### 测试目的
+分析类型定义文件的变更影响，类型文件通常有大量依赖关系。
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/types/index.ts --transitive
+```
+
+**执行时间**: 0.858s (real)
+
+**输出**:
+```
+📍 影响分析
+
+目标文件:
+   src/types/index.ts
+   导出: SymbolKind, SourceLocation, DecoratorInfo, ... (38 个类型)
+
+⬇️  直接依赖该文件的模块 (38):
+   • src/ai/claude.ts
+   • src/ai/codex.ts
+   • src/ai/provider.ts
+   • src/ai/subagent-caller.ts
+   • src/core/analyzer.ts
+   • src/core/global-index.ts
+   • src/cache/index.ts
+   • src/cache/parse-cache.ts
+   • src/generator/ai-overview.ts
+   • src/generator/context.ts
+   • ... (共38个)
+
+🌐 传递依赖 (41):
+     └─► src/ai/factory.ts [距离: 2]
+     └─► src/ai/index.ts [距离: 2]
+             └─► src/cli/index.ts [距离: 6]
+             └─► ...
+
+⚠️  风险评估:
+   🔴 极高风险 - 该文件是核心依赖，修改将影响大量模块
+   直接影响: 38 个模块
+   传递影响: 41 个额外模块
+```
+
+### 传统工具执行
+
+```bash
+rg -l "from.*types/index|from.*types" src/
+```
+
+**执行时间**: 0.009s (real)
+
+**输出**:
+```
+src/watcher/watch-worker.ts
+src/cli/commands/complexity.ts
+src/cli/commands/analyze.ts
+src/cli/commands/watch-foreground.ts
+src/cli/commands/impact.ts
+src/cli/commands/cycles.ts
+src/cli/commands/ci.ts
+src/cli/commands/generate.ts
+src/cli/commands/deps.ts
+src/cli/commands/workflow.ts
+src/cli/commands/query.ts
+src/worker/index.ts
+src/ai/claude.ts
+src/ai/subagent-caller.ts
+src/ai/provider.ts
+src/ai/codex.ts
+src/ai/index.ts
+... (共66个文件)
+```
+
+**匹配文件总数**: 66 个
+
+### 对比分析
+
+| 维度 | CodeMap | Grep | 结论 |
+|------|---------|------|------|
+| **执行时间** | 0.86s | 0.009s | Grep 快 95x |
+| **匹配文件数** | 38 | 66 | 差异 28 个文件 |
+| **误报/漏报** | 可能遗漏 | 包含非 types/index.ts 导入 | 各有优劣 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的 "依赖" (28 个)**:
+```
+src/ai/index.ts
+src/cli/commands/analyze.ts
+src/cli/commands/ci.ts
+src/cli/commands/workflow.ts
+src/index.ts
+src/orchestrator/adapters/ast-grep-adapter.ts
+src/orchestrator/adapters/base-adapter.ts
+src/orchestrator/adapters/codemap-adapter.ts
+src/orchestrator/confidence.ts
+src/orchestrator/git-analyzer.ts
+src/orchestrator/index.ts
+src/orchestrator/integration/pipeline.test.ts
+src/orchestrator/intent-router.ts
+src/orchestrator/result-fusion.ts
+src/orchestrator/tool-orchestrator.ts
+src/orchestrator/workflow/phase-checkpoint.ts
+src/orchestrator/workflow/types.ts
+src/orchestrator/workflow/workflow-context.ts
+src/orchestrator/workflow/workflow-orchestrator.ts
+... (共28个)
+```
+
+**原因分析**:
+这些文件通过 `src/orchestrator/types.ts` 间接使用类型，而非直接从 `src/types/index.ts` 导入。例如:
+```typescript
+// src/orchestrator/result-fusion.ts
+import type { UnifiedResult, HeatScore } from './types.js';  // 不是 types/index.js
+```
+
+而 `src/orchestrator/types.ts` 自身又从 `src/types/index.ts` 导入，形成间接依赖。
+
+**结论**: 
+- CodeMap 准确识别**直接**依赖 (38个)
+- Grep 捕获了**间接**依赖模式，但也包含了一些误报 (通过 `orchestrator/types` 而非 `types/index`)
+- CodeMap 传递依赖模式 (41个) 补充了间接依赖，总计 79 个影响模块
+
+---
+
+## 测试用例 3: src/cache/lru-cache.ts 影响分析
+
+### 测试目的
+分析具体工具类文件的变更影响，评估叶节点文件的依赖分析。
+
+### CodeMap 执行
+
+```bash
+npx codemap impact -f src/cache/lru-cache.ts
+```
+
+**执行时间**: 0.800s (real)
+
+**输出**:
+```
+📍 影响分析
+
+目标文件:
+   src/cache/lru-cache.ts
+   导出: LRUCache, LRUCacheWithTTL
+
+⬇️  直接依赖该文件的模块 (4):
+   • src/cache/index.ts
+   • src/cache/parse-cache.ts
+   • src/cache/__tests__/lru-cache.test.ts
+   • src/parser/implementations/tree-sitter-parser.ts
+
+⚠️  风险评估:
+   ⚠️  高风险 - 该文件被多个模块依赖，修改需谨慎
+   直接影响: 4 个模块
+```
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/cache/lru-cache.ts --transitive
+```
+
+**传递依赖**: 76 个模块
+
+### 传统工具执行
+
+```bash
+rg -l "lru-cache|LRUCache" src/
+```
+
+**执行时间**: 0.010s (real)
+
+**输出**:
+```
+src/cache/__tests__/lru-cache.test.ts
+src/cache/parse-cache.ts
+src/cache/lru-cache.ts
+src/cache/index.ts
+src/orchestrator/test-linker.ts
+```
+
+**匹配文件总数**: 5 个
+
+### 对比分析
+
+| 维度 | CodeMap Direct | CodeMap Transitive | Grep | 结论 |
+|------|----------------|-------------------|------|------|
+| **执行时间** | 0.80s | ~1.0s | 0.01s | Grep 快 80-100x |
+| **直接依赖数** | 4 | 4 | 5 | Grep 多1个 |
+| **传递依赖数** | 未显示 | 76 | N/A | CodeMap 独有功能 |
+| **风险评估** | ✅ 高风险 | ✅ 高风险 | ❌ | CodeMap 独有 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的**:
+```
+src/orchestrator/test-linker.ts  (仅作为字符串示例提及，无实际导入)
+```
+
+这是一个**误报**: `test-linker.ts` 只是在注释中提到 `lru-cache.test.ts` 作为示例:
+```typescript
+* lru-cache.test.ts → lru-cache.ts
+```
+
+CodeMap 正确地识别了这一点，没有将其列为依赖。
+
+---
+
+## 综合对比分析
+
+### 1. 直接依赖识别
+
+| 测试文件 | CodeMap 直接依赖 | Grep 匹配数 | CodeMap 准确率 | Grep 准确率 |
+|---------|-----------------|------------|----------------|-------------|
+| analyzer.ts | 13 | 22 | 100% | ~41% |
+| types/index.ts | 38 | 66 | 100% | ~58% |
+| lru-cache.ts | 4 | 5 | 100% | ~80% |
+
+**结论**: CodeMap 在直接依赖识别上具有**更高的准确性**，几乎没有误报。
+
+### 2. 传递依赖识别
+
+| 测试文件 | CodeMap 传递依赖 | 手动分析可行性 | 优势 |
+|---------|-----------------|---------------|------|
+| analyzer.ts | 66 | 困难 | 揭示深层影响 |
+| types/index.ts | 41 | 困难 | 跨层级追踪 |
+| lru-cache.ts | 76 | 几乎不可能 | 揭示广泛影响 |
+
+**结论**: CodeMap 的传递依赖分析是**独有功能**，手动几乎无法完成同等分析。
+
+### 3. 风险评估准确性
+
+CodeMap 风险评估分级:
+- 🔴 极高风险: > 20 个直接依赖 (如 types/index.ts: 38个)
+- ⚠️ 高风险: 5-20 个直接依赖
+- ⚠️ 中风险: 1-4 个直接依赖 (如 cycles.ts: 2个)
+- 🟢 低风险: 0 个依赖
+
+**验证**:
+- `src/types/index.ts` (38依赖) → 🔴 极高风险 ✅ 合理
+- `src/cache/lru-cache.ts` (4依赖) → ⚠️ 高风险 ✅ 合理 (虽数量不多但核心功能)
+- `src/cli/commands/cycles.ts` (2依赖) → ⚠️ 中风险 ✅ 合理
+
+### 4. 输出格式实用性
+
+**CodeMap 优势**:
+- 可视化依赖树结构
+- 显示每个依赖的导出内容
+- 距离标记 (传递依赖)
+- 风险等级评估
+- 统计汇总
+
+**Grep 优势**:
+- 简单列表，易于脚本处理
+- 可与其他 Unix 工具链组合
+
+### 5. 性能对比
+
+| 工具 | 平均执行时间 | 相对速度 |
+|------|-------------|---------|
+| CodeMap (direct) | ~0.6s | 1x |
+| CodeMap (transitive) | ~0.8s | 0.75x |
+| ripgrep | ~0.01s | 60-80x |
+
+---
+
+## 发现的问题
+
+### 问题 1: 遗漏 re-export 依赖
+**严重性**: 🔴 高
+
+**描述**: CodeMap 未能检测到通过 re-export 模式依赖的文件。
+
+**示例**: `src/index.ts` 包含:
+```typescript
+export { analyze } from './core/analyzer.js';
+```
+
+但 CodeMap 未将 `src/index.ts` 列为 `analyzer.ts` 的依赖。
+
+**影响**: 修改 analyzer.ts 可能影响所有通过主入口导入的下游用户。
+
+### 问题 2: 对 "高/极高风险" 阈值定义不明确
+**严重性**: 🟡 中
+
+**描述**: 
+- `types/index.ts` (38依赖) → 🔴 极高风险
+- `analyzer.ts` (13依赖) → 🔴 极高风险
+- `lru-cache.ts` (4依赖) → ⚠️ 高风险
+
+阈值跳跃较大，13和38都被归为"极高"，但4就是"高"，缺少中间等级。
+
+### 问题 3: 执行时间较长
+**严重性**: 🟡 中
+
+**描述**: CodeMap 比 ripgrep 慢 60-80 倍。对于大型代码库或频繁查询场景，这可能成为瓶颈。
+
+**建议**: 
+- 提供缓存机制
+- 增量更新依赖图
+- 添加 `--fast` 模式使用简化分析
+
+### 问题 4: 输出格式缺乏机器可读性
+**严重性**: 🟢 低
+
+**描述**: 输出主要是人类可读格式，没有 JSON/YAML 输出选项，不利于脚本集成。
+
+---
+
+## 改进建议
+
+### 1. 增强 re-export 检测
+```typescript
+// 检测以下模式:
+export { foo } from './module';
+export * from './module';
+export { default } from './module';
+```
+
+### 2. 细化风险等级
+```
+🟢 低风险: 0-2 依赖
+🟡 中风险: 3-10 依赖  
+🟠 高风险: 11-25 依赖
+🔴 极高风险: 26+ 依赖
+```
+
+### 3. 添加性能优化选项
+```bash
+npx codemap impact -f file.ts --cached        # 使用缓存
+npx codemap impact -f file.ts --depth 2       # 限制传递深度
+npx codemap impact -f file.ts --json          # 机器可读输出
+```
+
+### 4. 提供 diff 模式
+```bash
+npx codemap impact --compare branch1 branch2  # 对比分支影响
+```
+
+---
+
+## 总结
+
+| 评估维度 | 评分 | 说明 |
+|---------|------|------|
+| 准确性 | ⭐⭐⭐⭐⭐ | 几乎无直接依赖误报 |
+| 完整性 | ⭐⭐⭐⭐ | 遗漏 re-export，其他良好 |
+| 传递分析 | ⭐⭐⭐⭐⭐ | 独有功能，非常有价值 |
+| 风险评估 | ⭐⭐⭐⭐ | 分级合理但阈值可细化 |
+| 性能 | ⭐⭐⭐ | 比 grep 慢，但可接受 |
+| 实用性 | ⭐⭐⭐⭐⭐ | 可视化输出，信息丰富 |
+
+### 最终结论
+
+**CodeMap impact 命令**在影响范围分析上**显著优于**传统 grep 方法:
+
+1. **准确性**: 几乎零误报，而 grep 有 20-60% 的误报率
+2. **传递依赖**: 提供手动几乎无法完成的深层依赖分析
+3. **风险评估**: 量化风险等级，辅助决策
+4. **可视化**: 树形结构直观展示依赖关系
+
+**适用场景**:
+- ✅ 发布前影响评估
+- ✅ 重构前依赖分析  
+- ✅ 代码审查辅助
+- ✅ 架构决策支持
+
+**不适用场景**:
+- ❌ 需要极快速响应的实时监控
+- ❌ 纯文本处理的自动化脚本
+
+**总体推荐**: ⭐⭐⭐⭐⭐ (5/5) - 对于需要准确影响分析的场景强烈推荐使用

package/docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md

@@ -0,0 +1,79 @@
+# Design Contract Template
+
+把下面模板复制到仓库根目录并保存为 `mycodemap.design.md`。
+
+> 目标不是写长篇 PRD，而是把 AI 后续执行需要的**目标、限制、验收标准、显式非目标**写成可验证输入。
+
+## Required Sections
+
+| Section | Required | 作用 |
+|---------|----------|------|
+| `## Goal` | Yes | 定义这次要达成的结果 |
+| `## Constraints` | Yes | 约束技术/产品/时间/兼容性边界 |
+| `## Acceptance Criteria` | Yes | 写成可以验证的结果，而不是模糊愿景 |
+| `## Non-Goals` | Yes | 明确这次不做什么，防止 AI scope drift |
+| `## Context` | No | 补充背景、现状、依赖关系 |
+| `## Open Questions` | No | 记录需要人类决策的问题 |
+| `## Notes` | No | 其他实现前必须知道的信息 |
+
+## Authoring Rules
+
+- 使用清晰 section heading，不要把多个主题揉进同一段。
+- `Acceptance Criteria` 尽量写成可检查的 bullet。
+- `Non-Goals` 不能为空；它是防止越界实现的第一道护栏。
+- 如果某个关键决策尚未确定，写进 `Open Questions`，不要让 AI 自行猜测。
+
+## Copy-Paste Template
+
+```markdown
+# Design Contract: <feature name>
+
+## Goal
+- 这个 feature 最终要解决什么问题？
+- 用户或团队为什么需要它？
+
+## Constraints
+- 必须兼容的现有命令、接口或目录边界
+- 不允许改动的模块 / 风险限制 / 时间限制
+
+## Acceptance Criteria
+- [ ] 可验证结果 1
+- [ ] 可验证结果 2
+- [ ] 可验证结果 3
+
+## Non-Goals
+- 这次明确不做什么
+- 哪些相关问题留到后续 phase
+
+## Context
+- 当前实现现状
+- 相关文件 / 模块 / 文档
+
+## Open Questions
+- 需要人类确认的问题 1
+
+## Notes
+- 其他补充信息
+```
+
+## Minimal Example
+
+```markdown
+# Design Contract: Add design validate command
+
+## Goal
+- 为 human-authored design contract 提供正式的 CLI validate 入口
+
+## Constraints
+- 不扩写 analyze intent
+- 不恢复 workflow 的 commit / ci phases
+
+## Acceptance Criteria
+- [ ] `mycodemap design validate mycodemap.design.md --json` 返回机器可读结果
+- [ ] 缺失 `Acceptance Criteria` section 时返回 blocker diagnostics
+- [ ] README 和 AI docs 能发现该入口
+
+## Non-Goals
+- 不做 design-to-code mapping
+- 不生成 handoff package
+```