@mycodemap/mycodemap 0.1.1 → 0.2.0

package/docs/archive/plans/2026-03-14-go-language-support-design.md

@@ -0,0 +1,92 @@
+# Go 语言支持设计文档
+
+> 归档时间：2026-03-15
+> 归档原因：迁移遗留计划文档，原位于已停用的 `docs/plans/`，且方案仍未落地。
+> 当前依据：`docs/exec-plans/README.md`；如需重启，请新建到 `docs/exec-plans/active/`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
+**日期**: 2026-03-14
+**目标**: 为 CodeMap 添加 Go 语言分析支持
+**模式**: Fast + Smart（分阶段实现）
+
+## 1. 架构概览
+
+```
+TreeSitterParser (扩展)
+├── 语言检测 → 根据文件扩展名 (.go / .ts / .js)
+├── 动态加载语言模块 → tree-sitter-go / tree-sitter-typescript
+└── 节点提取 → 通过 AST 遍历提取 Import/Export/Symbol
+```
+
+## 2. 核心改动
+
+### 2.1 依赖更新
+
+- 新增：`tree-sitter-go` 包
+
+### 2.2 TreeSitterParser 改造
+
+```typescript
+// 构造函数中根据语言动态加载
+constructor(options: ParserOptions) {
+  this.rootDir = options.rootDir;
+  this.parser = new Parser();
+  // 语言在 parseFile 时根据扩展名动态设置
+}
+
+// 新增语言检测方法
+private detectLanguage(filePath: string): Language {
+  const ext = path.extname(filePath);
+  switch (ext) {
+    case '.go': return Go;
+    case '.ts':
+    case '.tsx': return TypeScript.typescript;
+    case '.js':
+    case '.jsx': return TypeScript.javascript;
+  }
+}
+```
+
+### 2.3 节点类型映射（Go 特有）
+
+| 概念 | TypeScript 节点 | Go 节点 |
+|------|-----------------|---------|
+| 导入 | `import_statement` | `import_declaration` |
+| 导出 | `export_statement` | `exported_decl` |
+| 函数 | `function_declaration` | `function_declaration` |
+| 类型 | `type_alias_declaration` | `type_spec` |
+| 结构体 | `class_declaration` | `struct_type` |
+
+### 2.4 Go 特定逻辑
+
+- 解析 `go.mod` 提取模块名作为顶级依赖
+- 测试文件识别：`_test.go` 后缀 → `type: 'test'`
+
+### 2.5 DefaultParserFactory 更新
+
+```typescript
+getSupportedExtensions(): string[] {
+  return ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.go'];
+}
+```
+
+## 3. 实施步骤（分阶段）
+
+### 第一阶段：基础支持
+1. 安装 `tree-sitter-go` 依赖
+2. 扩展 `TreeSitterParser` 支持语言动态切换
+3. 添加 Go AST 节点映射逻辑
+4. 更新 `DefaultParserFactory` 支持 `.go`
+5. 添加单元测试
+6. 验证功能
+
+### 第二阶段（后续迭代）
+- 复用 `typhonjs-escomplex` 进行 Go 复杂度分析
+- 实现调用图分析
+
+## 4. 风险与注意事项
+
+- Go 的 AST 节点类型与 TypeScript 有差异，需要单独处理
+- 需要确保 tree-sitter-go 版本与 tree-sitter 核心库兼容
+- Go 的 import 路径解析需要考虑模块名（go.mod）的情况

package/docs/{REFACTOR_REQUIREMENTS.md → archive/product-specs/REFACTOR_REQUIREMENTS.md}

@@ -1,5 +1,11 @@
 # CodeMap 编排层重构设计方案 - 需求与用户场景
 
+> 归档时间：2026-03-15
+> 归档原因：历史需求/规格草稿，文档状态仍为“待实施”，已不适合作为当前契约。
+> 当前依据：`ARCHITECTURE.md`、`docs/rules/*`、`src/cli/index.ts`
+> 状态：仅供历史对照，不作为当前执行依据。
+
+
 > 版本: 2.5
 > 日期: 2026-02-28
 > 状态: 待实施（含 CI 门禁设计）
@@ -959,11 +965,11 @@ $ codemap workflow start "实现文件重命名功能"
 
 - 评估报告: `CODEMAP_ASSESSMENT_REPORT.md`
 - 方案对比: `MULTI_TOOL_REFACTOR_OPTIONS.md`
-- 系统架构与功能设计: `REFACTOR_ARCHITECTURE_DESIGN.md`
-- Git 分析器设计: `REFACTOR_GIT_ANALYZER_DESIGN.md` (含 AI 饲料生成器)
-- CI 门禁设计: `CI_GATEWAY_DESIGN.md`
-- 结果融合设计: `REFACTOR_RESULT_FUSION_DESIGN.md`
-- 编排层设计: `REFACTOR_ORCHESTRATOR_DESIGN.md` (含工作流编排器 v2.5 规划)
+- 系统架构与功能设计: `../design-docs/REFACTOR_ARCHITECTURE_OVERVIEW.md`
+- Git 分析器设计: `../design-docs/REFACTOR_GIT_ANALYZER_DESIGN.md` (含 AI 饲料生成器)
+- CI 门禁设计: `../design-docs/CI_GATEWAY_DESIGN.md`
+- 结果融合设计: `../design-docs/REFACTOR_RESULT_FUSION_DESIGN.md`
+- 编排层设计: `../design-docs/REFACTOR_ORCHESTRATOR_DESIGN.md` (含工作流编排器 v2.5 规划)
 
 ### B. 参考资源
 

package/docs/archive/scenario-2-deps-analysis.md

@@ -0,0 +1,353 @@
+# 测试场景 2: 模块依赖分析对比测试
+
+**测试目标**: 对比 `codemap deps` 与手动 `grep` 分析模块依赖的差异
+
+**测试环境**: /data/codemap 目录
+
+---
+
+## 测试 1: 查看 src/parser/index.ts 的依赖树
+
+### 测试目的
+对比 CodeMap 的依赖树展示能力与手动 grep 分析的效果
+
+### CodeMap 执行
+```bash
+npx codemap deps -m "src/parser"
+```
+**执行时间**: 0.658s
+
+**输出**:
+```
+📦 模块: src/parser/index.ts
+──────────────────────────────────────────────────
+
+⬇️  直接依赖 (dependencies):
+   • typescript [source]
+   • fs/promises [source]
+   • path [source]
+   • /data/codemap/src/types/index.js [source]
+   • /data/codemap/src/parser/interfaces/IParser.js [source]
+   • /data/codemap/src/parser/implementations/smart-parser.js [source]
+   • /data/codemap/src/parser/implementations/fast-parser.js [source]
+
+⬆️  被依赖 (dependents):
+   • src/core/analyzer.ts
+──────────────────────────────────────────────────
+   依赖数量: 7
+   被依赖数量: 1
+```
+
+### 传统工具执行
+```bash
+rg -n "import.*from" src/parser/index.ts
+```
+**执行时间**: 0.003s
+
+**输出**:
+```
+5:import ts from 'typescript';
+6:import fs from 'fs/promises';
+7:import path from 'path';
+8:import type { ModuleInfo, ImportInfo, ExportInfo, ModuleSymbol, SymbolKind, DecoratorInfo } from '../types/index.js';
+9:import type { IParser, ParserOptions, ParserMode } from './interfaces/IParser.js';
+10:import { SmartParser } from './implementations/smart-parser.js';
+11:import { FastParser } from './implementations/fast-parser.js';
+```
+
+### 对比分析
+
+| 维度 | CodeMap | 传统工具 (rg) | 结论 |
+|------|---------|---------------|------|
+| 速度 | 0.658s | 0.003s | rg 快 ~200倍 |
+| 依赖方向 | 同时显示导入(⬇️)和被导入(⬆️) | 仅显示导入语句 | CodeMap 更全面 |
+| 准确性 | 显示 .js 扩展名（构建后） | 显示源代码 .ts 扩展名 | rg 更准确反映源代码 |
+| 结构化 | 分类显示，带统计信息 | 原始代码行 | CodeMap 更易读 |
+| 被依赖分析 | ✅ 自动识别 | ❌ 需额外查找 | CodeMap 独有功能 |
+
+### 发现的问题
+1. **路径扩展名不一致**: CodeMap 显示 `.js` 扩展名，而源代码使用 `.ts`，可能造成混淆
+2. **速度差距大**: CodeMap 启动开销明显高于 rg
+
+---
+
+## 测试 2: 查看 src/core/analyzer.ts 的依赖
+
+### 测试目的
+测试复杂模块的依赖分析能力
+
+### CodeMap 执行
+```bash
+npx codemap deps -m "src/core/analyzer"
+```
+**执行时间**: 0.575s
+
+**输出**:
+```
+📦 模块: src/core/analyzer.ts
+──────────────────────────────────────────────────
+
+⬇️  直接依赖 (dependencies):
+   • path [source]
+   • fs/promises [source]
+   • globby [source]
+   • /data/codemap/src/parser/index.js [source]
+   • /data/codemap/src/types/index.js [source]
+   • /data/codemap/src/parser/interfaces/IParser.js [source]
+   • /data/codemap/src/core/global-index.js [source]
+
+⬆️  被依赖 (dependents):
+   • src/watcher/watch-worker.ts
+   • src/core/__tests__/analyzer.test.ts
+   • src/cli/__tests__/generate.test.ts
+   • src/cli/commands/generate.ts
+   • src/cli/commands/watch-foreground.ts
+   • src/cli/commands/__tests__/watch-foreground.test.ts
+──────────────────────────────────────────────────
+   依赖数量: 7
+   被依赖数量: 6
+```
+
+### 传统工具执行
+```bash
+rg -n "import" src/core/analyzer.ts
+```
+**执行时间**: 0.003s
+
+**输出**:
+```
+1:import path from 'path';
+2:import fs from 'fs/promises';
+3:import { globby } from 'globby';
+4:import { parseFile, createParser } from '../parser/index.js';
+5:import type { CodeMap, AnalysisOptions, ModuleInfo, DependencyGraph, ProjectInfo, ProjectSummary } from '../types/index.js';
+6:import type { ParseResult } from '../parser/interfaces/IParser.js';
+7:import { createGlobalIndex, GlobalSymbolIndexBuilder } from './global-index.js';
+142:    imports: result.imports,
+197:        const edgeKey = `${mod.id}->${targetMod.id}:import`;
+204:          type: 'import',
+259:  importerPath: string,
+269:    candidates.push(normalizePath(path.resolve(path.dirname(importerPath), rawDep)));
+```
+
+### 对比分析
+
+| 维度 | CodeMap | 传统工具 (rg) | 结论 |
+|------|---------|---------------|------|
+| 速度 | 0.575s | 0.003s | rg 快 ~190倍 |
+| 误报过滤 | 仅显示 import 语句 | 显示所有包含 "import" 的行 | CodeMap 更准确 |
+| 被依赖识别 | ✅ 自动识别 6 个模块依赖此模块 | ❌ 无法识别 | CodeMap 独有功能 |
+| 类型导入 | 不区分 type import | 显示 type 关键字 | rg 更详细 |
+
+### 发现的问题
+1. **rg 误报问题**: grep 匹配了所有包含 "import" 的行（包括变量名），需要更精确的 pattern
+2. **CodeMap 不区分 import 类型**: 未显示哪些是 type-only import
+
+---
+
+## 测试 3: 完整的依赖统计
+
+### 测试目的
+对比全局依赖统计的能力
+
+### CodeMap 执行
+```bash
+npx codemap deps
+```
+**执行时间**: 0.527s
+
+**输出**:
+```
+📊 项目依赖分析
+──────────────────────────────────────────────────
+
+📦 模块依赖排名 (Top 20):
+   1. src/orchestrator/workflow/workflow-orchestrator.ts
+      依赖: 13, 类型: source
+   2. src/cli/index.ts
+      依赖: 12, 类型: source
+   3. src/cli/commands/analyze.ts
+      依赖: 11, 类型: source
+   4. src/core/analyzer.ts
+      依赖: 7, 类型: source
+   5. src/parser/index.ts
+      依赖: 7, 类型: source
+   ...
+──────────────────────────────────────────────────
+   总模块数: 104
+   有依赖的模块: 104
+   总依赖关系: 350
+```
+
+### 传统工具执行
+```bash
+rg -n "^import|^export" src/ --stats
+```
+**执行时间**: 0.008s
+
+**输出** (部分):
+```
+# 显示所有匹配行，包含文件路径和行号
+# 需要手动统计每个文件的 import 数量
+# 最后给出总体统计:
+130 matches
+13 files contained matches
+52 files searched
+0 bytes printed
+```
+
+### 对比分析
+
+| 维度 | CodeMap | 传统工具 (rg) | 结论 |
+|------|---------|---------------|------|
+| 速度 | 0.527s | 0.008s | rg 快 ~65倍 |
+| 排名统计 | ✅ 自动按依赖数排名 | ❌ 需手动统计 | CodeMap 大幅领先 |
+| 模块分类 | ✅ 区分 source/test | ❌ 需手动过滤 | CodeMap 更智能 |
+| 总计信息 | ✅ 总模块数、依赖关系数 | ⚠️ 仅匹配数 | CodeMap 更有用 |
+| 可扩展性 | JSON 输出支持 | 需管道处理 | CodeMap 更友好 |
+
+### JSON 输出测试
+```bash
+npx codemap deps --json
+```
+
+输出结构化 JSON，包含每个模块的依赖数量，便于程序化处理。
+
+### 发现的问题
+1. **rg 统计困难**: 需要复杂的管道命令才能获得类似统计
+2. **CodeMap 缺少依赖图**: 仅显示数量排名，未展示依赖关系图
+
+---
+
+## 测试 4: 检测循环依赖
+
+### 测试目的
+对比循环依赖检测的能力
+
+### CodeMap 执行
+```bash
+npx codemap cycles
+```
+**执行时间**: 0.677s
+
+**输出**:
+```
+🔄 循环依赖检测
+──────────────────────────────────────────────────
+
+✅ 未检测到循环依赖！
+```
+
+### 传统工具尝试
+手动检测循环依赖需要递归搜索每个依赖的依赖，复杂度极高：
+
+```bash
+# 步骤 1: 获取模块的所有导入
+rg -n "import.*from" src/core/analyzer.ts
+
+# 步骤 2: 对每个导入，检查是否反向依赖
+# 这需要递归执行以下命令 N 次：
+rg -n "import.*from.*analyzer" src/parser/
+rg -n "import.*from.*parser" src/core/
+# ... 以此类推
+```
+
+**复杂度分析**:
+- 对于 N 个模块，平均每个模块 M 个依赖
+- 需要执行 O(N × M) 次搜索
+- 每次搜索可能需要检查多个目录
+- 需要构建完整的依赖图才能检测循环
+
+**手动尝试结果**:
+```bash
+# 尝试检测 ai <-> generator 循环
+rg -n "import.*from.*generator" src/ai/      # 无结果
+rg -n "import.*from.*ai" src/generator/      # 发现 1 条
+# 实际: generator/ai-overview.ts -> ai/subagent-caller.js (单向，非循环)
+```
+
+### 对比分析
+
+| 维度 | CodeMap | 传统工具 (rg) | 结论 |
+|------|---------|---------------|------|
+| 循环检测 | ✅ 一键检测 | ❌ 极其困难 | CodeMap 独有优势 |
+| 算法复杂度 | O(N + E) 图遍历 | O(N² × M²) 搜索 | CodeMap 专业实现 |
+| 准确性 | 构建完整依赖图 | 容易遗漏 | CodeMap 可靠 |
+| 速度 | 0.677s | 可能需要数分钟 | CodeMap 高效 |
+| 可视化 | ✅ 清晰的检测结果 | ❌ 无 | CodeMap 更友好 |
+
+### 发现的问题
+1. **手动检测几乎不可行**: 对于大型项目，手动 grep 几乎无法可靠检测循环依赖
+2. **CodeMap 无循环路径展示**: 检测到循环时，应展示具体循环路径
+
+---
+
+## 综合评估
+
+### 速度对比汇总
+
+| 测试项 | CodeMap | rg | 速度比 (rg/CodeMap) |
+|--------|---------|-----|---------------------|
+| 单模块依赖 | 0.658s | 0.003s | 219x |
+| 复杂模块依赖 | 0.575s | 0.003s | 191x |
+| 全局依赖统计 | 0.527s | 0.008s | 65x |
+| 循环依赖检测 | 0.677s | ~分钟级 | CodeMap 独有 |
+
+### 核心优势对比
+
+| 能力 | CodeMap | rg |
+|------|---------|-----|
+| 双向依赖分析 | ✅ | ❌ |
+| 依赖排名统计 | ✅ | ❌ |
+| 循环依赖检测 | ✅ | ❌ |
+| 结构化输出 | ✅ | ⚠️ |
+| 模块分类 | ✅ | ❌ |
+| 原始代码匹配 | ⚠️ | ✅ |
+| 速度 | ⚠️ | ✅ |
+| 灵活性 | ⚠️ | ✅ |
+
+### 主要发现的问题
+
+1. **性能开销**: CodeMap 有显著的启动/解析开销（~0.6s），不适合频繁调用
+2. **路径显示**: 显示 `.js` 而非 `.ts` 扩展名，与源代码不一致
+3. **缺少传递依赖**: 不支持 `--depth` 选项查看传递依赖树
+4. **循环路径**: 检测到循环时未展示具体路径
+5. **Type Import**: 未区分 `import type` 和普通 `import`
+
+### 改进建议
+
+1. **性能优化**:
+   - 实现缓存机制，避免重复解析
+   - 支持守护进程模式 (daemon mode)
+   - 延迟加载，按需解析
+
+2. **功能增强**:
+   - 添加 `--depth` 参数支持传递依赖分析
+   - 循环检测显示完整路径 (A -> B -> C -> A)
+   - 区分 type-only import
+   - 生成依赖图可视化 (Mermaid/Graphviz)
+
+3. **输出改进**:
+   - 默认显示源代码路径 (.ts)
+   - 添加 `--build-paths` 选项显示构建路径 (.js)
+   - 支持更多输出格式 (CSV, HTML)
+
+---
+
+## 结论
+
+**CodeMap** 在依赖分析的**功能完整性**上大幅领先传统工具：
+- 独有的双向依赖分析
+- 一键循环依赖检测
+- 结构化排名统计
+- 对大型项目不可或缺
+
+**rg** 在**速度和灵活性**上保持优势：
+- 适合快速查找特定模式
+- 适合脚本化处理
+- 无额外依赖
+
+**推荐用法**:
+- 日常开发、CI/CD 中使用 CodeMap 进行依赖分析
+- 快速代码查找仍使用 rg
+- 两者结合，发挥各自优势