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

🔥 重要：LLM のコンテキスト用にコードを分析する場合は、必ず --format ai を使用してください。これは最もトークン効率の高い形式です（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. LLM には必ず --format ai を使用する： トークン効率が重要です
3. まずファジー検索を使う： デフォルトのファジーマッチングのほうが柔軟です
4. リファクタリング前に確認する： 変更前に cm callers と cm tests を実行します
5. 適切なツールを使う： 構造／呼び出しには CodeMapper、テキスト検索には ripgrep を使います

トラブルシューティング

シンボルが見つからない場合

• ファイル拡張子を確認します。cm stats . でインデックス対象を確認できます
• ファジー検索（デフォルト）と --exact を試します

クエリが遅い場合

• 初回実行時にキャッシュが構築されます（約10秒）
• 2回目以降はキャッシュが使用されます（約0.5秒）

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.5秒
• 大規模リポジトリ（1000ファイル以上）：高速モードが自動的に有効になります

キャッシュの場所：プロジェクトルートの .codemapper/（自動管理）