codemapper

CodeMapper (cm) - 快速代码分析

概览

CodeMapper（cm）使用 tree-sitter AST 解析，无需数据库即可即时分析代码。毫秒级获取项目结构、查找符号、追踪调用图并分析依赖关系。

**支持的语言：**Python、JavaScript、TypeScript、Rust、Java、Go、C、Markdown

适用场景

在以下情况下使用 CodeMapper：

• ✅ 探索陌生代码库（了解概况、查找结构）
• ✅ 查找符号定义和用法（函数、类、方法）
• ✅ 理解调用图（谁调用了什么、调用路径）
• ✅ 检查测试覆盖情况（查找未经测试的代码）
• ✅ 在符号级别分析 git 变更（破坏性变更）
• ✅ 重构前进行影响分析（了解依赖关系）

请勿用于：

• ❌ 全文搜索（请改用 ripgrep/grep）
• ❌ 运行时分析（请使用分析器）
• ❌ 代码执行（请使用解释器/编译器）

快速开始

# Step 1: Get overview
cm stats .

# Step 2: See file structure (ALWAYS use --format ai for LLMs)
cm map . --level 2 --format ai

# Step 3: Find specific code
cm query <symbol> --format ai

# Step 4: Deep dive into a file
cm inspect ./path/to/file --format ai

🔥 重要提示：分析代码以供大模型使用时，务必使用 --format ai。这是 token 效率最高的格式（可减少 60-80%）。

核心命令

任务	命令
项目概览	cm stats .
文件结构	cm map . --level 2 --format ai
查找符号	cm query <name> --format ai
显示实现	cm query <name> --show-body --format ai
谁调用了它？	cm callers <symbol> --format ai
它调用了什么？	cm callees <symbol> --format ai
调用路径 A→B	cm trace <from> <to> --format ai
查找测试	cm tests <symbol> --format ai
未经测试的代码	cm untested . --format ai
破坏性变更	cm since <commit> --breaking --format ai

**完整命令参考：**阅读 references/command-reference.md

关键工作流

探索未知代码

cm stats .
cm map . --level 2 --format ai
cm query <symbol> --format ai

重构前

cm callers <function> --format ai      # Who depends on this?
cm tests <function> --format ai        # Is it tested?
cm callees <function> --format ai      # What does it depend on?

代码健康检查

cm untested . --format ai                       # What's not tested?
cm since <last_release> --breaking --format ai  # Breaking changes?

**详细工作流：**阅读 references/workflows.md

常见错误

❌ 忘记使用 --format ai

# Bad (verbose, token-heavy)
cm map . --level 2

# Good (compact, LLM-optimized)
cm map . --level 2 --format ai

❌ 使用 grep 查找调用图

# Bad (misses indirect calls, false positives)
grep -r "process_payment"

# Good (accurate AST-based call graph)
cm callers process_payment --format ai

❌ 跳过 stats/map

# Bad (jumping to query without context)
cm query something --format ai

# Good (understand structure first)
cm stats .
cm map . --level 2 --format ai
cm query something --format ai

**更多示例：**阅读 references/common-mistakes.md

最佳实践

1. **始终从概览开始：**先运行 cm stats .，再运行 cm map . --level 2 --format ai
2. **供大模型使用时务必指定 --format ai：**token 效率很重要
3. **先进行模糊搜索：**默认的模糊匹配更宽松
4. **重构前先检查：**变更前运行 cm callers 和 cm tests
5. **使用正确的工具：**CodeMapper 用于结构/调用分析，ripgrep 用于文本搜索

故障排除

找不到符号？

• 检查文件扩展名：cm stats . 会显示已索引的内容
• 尝试模糊搜索（默认）或使用 --exact

查询缓慢？

• 首次运行会构建缓存（约 10s）
• 后续运行会使用缓存（约 0.5s）

Git 命令失败？

• 使用 diff、since、blame、history 时，必须位于 git 仓库中

**详细故障排除说明：**阅读 references/troubleshooting.md

参考文档

• references/command-reference.md - 完整的命令和标志参考
• references/workflows.md - 常见任务的详细工作流模式
• references/common-mistakes.md - 应避免事项的扩展示例
• references/troubleshooting.md - 全面的故障排除指南
• references/integration-examples.md - CI/CD、文档和代码审查模式

性能

• 小型仓库（< 100 个文件）：< 20ms，即时响应
• 中型仓库（100-1000 个文件）：使用缓存时约 0.5s
• 大型仓库（1000 个以上文件）：自动启用快速模式

缓存位置：项目根目录下的 .codemapper/（自动管理）