grepai-trace-callers

GrepAI Trace Callers

このスキルでは、grepai trace callers を使用して、特定の関数またはメソッドを呼び出すコードの場所をすべて見つける方法を説明します。

このスキルを使用するタイミング

• リファクタリングの前に関数の使用箇所をすべて見つける
• 関数の依存関係を理解する
• 変更前に影響を分析する
• コードを移動・調査する

Trace Callers とは？

grepai trace callers は、**「この関数を呼び出しているのはどこですか？」**に答えます。

func Login(user, pass) {...}
        ↑
        │
┌───────┴───────────────────┐
│   Who calls Login()?      │
├───────────────────────────┤
│ • HandleAuth (auth.go:42) │
│ • TestLogin (test.go:15)  │
│ • CLI (main.go:88)        │
└───────────────────────────┘

基本的な使い方

grepai trace callers "FunctionName"

例

grepai trace callers "Login"

出力：

🔍 Callers of "Login"

Found 3 callers:

1. HandleAuth
   File: handlers/auth.go:42
   Context: user.Login(ctx, credentials)

2. TestLoginSuccess
   File: handlers/auth_test.go:15
   Context: result := Login(testUser, testPass)

3. RunCLI
   File: cmd/main.go:88
   Context: err := auth.Login(username, password)

JSON 出力

プログラムから使用する場合：

grepai trace callers "Login" --json

出力：

{
  "query": "Login",
  "mode": "callers",
  "count": 3,
  "results": [
    {
      "file": "handlers/auth.go",
      "line": 42,
      "caller": "HandleAuth",
      "context": "user.Login(ctx, credentials)"
    },
    {
      "file": "handlers/auth_test.go",
      "line": 15,
      "caller": "TestLoginSuccess",
      "context": "result := Login(testUser, testPass)"
    },
    {
      "file": "cmd/main.go",
      "line": 88,
      "caller": "RunCLI",
      "context": "err := auth.Login(username, password)"
    }
  ]
}

コンパクトな JSON（AI 向けに最適化）

grepai trace callers "Login" --json --compact

出力：

{
  "q": "Login",
  "m": "callers",
  "c": 3,
  "r": [
    {"f": "handlers/auth.go", "l": 42, "fn": "HandleAuth"},
    {"f": "handlers/auth_test.go", "l": 15, "fn": "TestLoginSuccess"},
    {"f": "cmd/main.go", "l": 88, "fn": "RunCLI"}
  ]
}

TOON 出力（v0.26.0+）

TOON 形式は JSON よりトークン数を約 50% 削減できます。

grepai trace callers "Login" --toon

出力：

callers[3]:
  - call_site:
      context: "user.Login(ctx, credentials)"
      file: handlers/auth.go
      line: 42
    symbol:
      name: HandleAuth
      ...

注： --json と --toon は同時に指定できません。

抽出モード

GrepAI には 2 つの抽出モードがあります。

高速モード（デフォルト）

正規表現パターンを使用します。高速で、依存関係もありません。

grepai trace callers "Login" --mode fast

高精度モード

tree-sitter AST パーサーを使用します。より正確ですが、tree-sitter が必要です。

grepai trace callers "Login" --mode precise

比較

モード	速度	精度	依存関係
fast	⚡⚡⚡	良好	なし
precise	⚡⚡	優秀	tree-sitter

設定

.grepai/config.yaml で trace を設定します。

trace:
  mode: fast  # fast or precise

  enabled_languages:
    - .go
    - .js
    - .ts
    - .py
    - .php
    - .rs

  exclude_patterns:
    - "*_test.go"
    - "*.spec.ts"

対応言語

言語	拡張子
Go	.go
JavaScript	.js, .jsx
TypeScript	.ts, .tsx
Python	.py
PHP	.php
C/C++	.c, .h, .cpp, .hpp, .cc, .cxx
Rust	.rs
Zig	.zig
C#	.cs
Java	.java
Pascal/Delphi	.pas, .dpr

使用例

リファクタリング前

# Find all usages before renaming
grepai trace callers "getUserById"

# Check impact of changing signature
grepai trace callers "processPayment"

コードベースの理解

# Who uses this core function?
grepai trace callers "validateToken"

# Find entry points to a module
grepai trace callers "initialize"

デバッグ

# Where is this function called from?
grepai trace callers "problematicFunction"

コードレビュー

# Verify function usage before approving changes
grepai trace callers "deprecatedMethod"

よくある名前への対処

関数名が一般的な場合、無関係なコードが結果に含まれることがあります。

問題

grepai trace callers "get"  # Too common, many false positives

解決策

1. より具体的な名前を使用します。

grepai trace callers "getUserProfile"

2. パスで結果を絞り込みます。

grepai trace callers "get" --json | jq '.results[] | select(.file | contains("auth"))'

セマンティック検索との併用

包括的に理解するには、併用してください。

# Find what Login does (semantic)
grepai search "user login authentication"

# Find who uses Login (trace)
grepai trace callers "Login"

スクリプトの例

Bash

# Count callers
grepai trace callers "MyFunction" --json | jq '.count'

# Get caller function names
grepai trace callers "MyFunction" --json | jq -r '.results[].caller'

# Get file paths only
grepai trace callers "MyFunction" --json | jq -r '.results[].file' | sort -u

Python

import subprocess
import json

result = subprocess.run(
    ['grepai', 'trace', 'callers', 'Login', '--json'],
    capture_output=True,
    text=True
)

data = json.loads(result.stdout)
print(f"Found {data['count']} callers of Login:")
for r in data['results']:
    print(f"  - {r['caller']} in {r['file']}:{r['line']}")

よくある問題

❌ 問題： 呼び出し元が見つからない ✅ 解決策：

• 関数名のスペルを確認します（大文字と小文字は区別されます）
• ファイルの種類が enabled_languages に含まれていることを確認します
• grepai watch を実行してシンボルインデックスを更新します

❌ 問題： 誤検出が多すぎる ✅ 解決策：

• より具体的な関数名を使用します
• 設定に除外パターンを追加します
• jq で結果を絞り込みます

❌ 問題： 一部の呼び出し元が見つからない ✅ 解決策：

• 精度を高めるために --mode precise を試します
• ファイルが無視パターンに含まれているか確認します

ベストプラクティス

1. 正確な関数名を使用する： 大文字と小文字は区別されます
2. シンボルインデックスを確認する： 先に grepai watch を実行します
3. スクリプトでは JSON を使用する： 解析が簡単です
4. 検索と併用する： セマンティック検索と trace を組み合わせると全体像を把握できます
5. 大量の結果を絞り込む： jq または grep を使用します

出力形式

Trace callers の結果：

🔍 Callers of "Login"

Mode: fast
Language files scanned: 245

Found 3 callers:

1. HandleAuth
   File: handlers/auth.go:42
   Context: user.Login(ctx, credentials)

2. TestLoginSuccess
   File: handlers/auth_test.go:15
   Context: result := Login(testUser, testPass)

3. RunCLI
   File: cmd/main.go:88
   Context: err := auth.Login(username, password)

Tip: Use --json for machine-readable output
     Use --mode precise for more accurate results