GrepAI Trace Graph

このスキルは grepai trace graph を使用して、すべての依存関係を再帰的に表示する完全なコールグラフを構築することをカバーしています。

このスキルを使うべき場合

• 関数の完全な依存関係をマッピング
• 複雑なコードフローを理解
• 大規模なリファクタリングのための影響分析
• アプリケーションアーキテクチャを可視化

Trace Graph とは

grepai trace graph は再帰的な依存関係ツリーを構築します:

main
├── initialize
│   ├── loadConfig
│   │   └── parseYAML
│   └── connectDB
│       ├── createPool
│       └── ping
├── startServer
│   ├── registerRoutes
│   │   ├── authMiddleware
│   │   └── loggingMiddleware
│   └── listen
└── gracefulShutdown
    └── closeDB

基本的な使い方

grepai trace graph "FunctionName"

例

grepai trace graph "main"

出力:

🔍 Call Graph for "main"

main
├── initialize
│   ├── loadConfig
│   └── connectDB
├── startServer
│   ├── registerRoutes
│   └── listen
└── gracefulShutdown
    └── closeDB

Nodes: 9
Max depth: 3

深さの制御

--depth で再帰の深さを制限します:

# デフォルトの深さ (2レベル)
grepai trace graph "main"

# より深い分析 (3レベル)
grepai trace graph "main" --depth 3

# 浅い (1レベル、callees と同じ)
grepai trace graph "main" --depth 1

# 非常に深い (5レベル)
grepai trace graph "main" --depth 5

深さの例

--depth 1 (callees と同じ):

main
├── initialize
├── startServer
└── gracefulShutdown

--depth 2 (デフォルト):

main
├── initialize
│   ├── loadConfig
│   └── connectDB
├── startServer
│   ├── registerRoutes
│   └── listen
└── gracefulShutdown
    └── closeDB

--depth 3:

main
├── initialize
│   ├── loadConfig
│   │   └── parseYAML
│   └── connectDB
│       ├── createPool
│       └── ping
├── startServer
│   ├── registerRoutes
│   │   ├── authMiddleware
│   │   └── loggingMiddleware
│   └── listen
└── gracefulShutdown
    └── closeDB

JSON 出力

grepai trace graph "main" --depth 2 --json

出力:

{
  "query": "main",
  "mode": "graph",
  "depth": 2,
  "root": {
    "name": "main",
    "file": "cmd/main.go",
    "line": 10,
    "children": [
      {
        "name": "initialize",
        "file": "cmd/main.go",
        "line": 15,
        "children": [
          {
            "name": "loadConfig",
            "file": "config/config.go",
            "line": 20,
            "children": []
          },
          {
            "name": "connectDB",
            "file": "db/db.go",
            "line": 30,
            "children": []
          }
        ]
      },
      {
        "name": "startServer",
        "file": "server/server.go",
        "line": 25,
        "children": [
          {
            "name": "registerRoutes",
            "file": "server/routes.go",
            "line": 10,
            "children": []
          }
        ]
      }
    ]
  },
  "stats": {
    "nodes": 6,
    "max_depth": 2
  }
}

コンパクト JSON

grepai trace graph "main" --depth 2 --json --compact

出力:

{
  "q": "main",
  "d": 2,
  "r": {
    "n": "main",
    "c": [
      {"n": "initialize", "c": [{"n": "loadConfig"}, {"n": "connectDB"}]},
      {"n": "startServer", "c": [{"n": "registerRoutes"}]}
    ]
  },
  "s": {"nodes": 6, "depth": 2}
}

TOON 出力 (v0.26.0+)

TOON フォーマットは JSON より約 50% トークン数が少なくなります:

grepai trace graph "main" --depth 2 --toon

注: --json と --toon は相互排他的です。

抽出モード

# 高速モード (正規表現ベース)
grepai trace graph "main" --mode fast

# 精密モード (tree-sitter AST)
grepai trace graph "main" --mode precise

ユースケース

アプリケーションフローを理解する

# アプリケーション起動全体をマップ
grepai trace graph "main" --depth 4

影響分析

# このユーティリティ関数に何が依存しているか?
grepai trace graph "validateInput" --depth 3

# データベースレイヤー変更の完全な影響
grepai trace graph "executeQuery" --depth 2

コードレビュー

# この関数は複雑すぎないか?
grepai trace graph "processOrder" --depth 5
# ノード数が多い = 高い複雑さ

ドキュメント

# アーキテクチャ図のデータを生成
grepai trace graph "main" --depth 3 --json > architecture.json

リファクタリング計画

# この変更で何が壊れるか?
grepai trace graph "legacyAuth" --depth 3

サイクルの処理

GrepAI は循環依存を検出してマークします:

main
├── processA
│   └── processB
│       └── processA [CYCLE]

JSON の場合:

{
  "name": "processA",
  "cycle": true
}

大規模なグラフ

非常に大規模なコードベースでは、グラフが圧倒的になる可能性があります:

深さを制限

# 浅く開始
grepai trace graph "main" --depth 2

特定の領域に焦点を絞る

# main の代わりに特定のサブシステムをトレース
grepai trace graph "authMiddleware" --depth 3

後処理でフィルタリング

# JSON を取得してフィルタリング
grepai trace graph "main" --depth 3 --json | jq '...'

グラフを可視化

DOT フォーマット (Graphviz) へエクスポート

# JSON を DOT に変換
grepai trace graph "main" --depth 3 --json | python3 << 'EOF'
import json
import sys

data = json.load(sys.stdin)

print("digraph G {")
print("  rankdir=TB;")

def traverse(node, parent=None):
    name = node.get('name') or node.get('n')
    if parent:
        print(f'  "{parent}" -> "{name}";')
    children = node.get('children') or node.get('c') or []
    for child in children:
        traverse(child, name)

traverse(data.get('root') or data.get('r'))
print("}")
EOF

その後、レンダリング:

dot -Tpng graph.dot -o graph.png

Mermaid 図

grepai trace graph "main" --depth 2 --json | python3 << 'EOF'
import json
import sys

data = json.load(sys.stdin)

print("```mermaid")
print("graph TD")

def traverse(node, parent=None):
    name = node.get('name') or node.get('n')
    if parent:
        print(f"  {parent} --> {name}")
    children = node.get('children') or node.get('c') or []
    for child in children:
        traverse(child, name)

traverse(data.get('root') or data.get('r'))
print("```")
EOF

グラフサイズの比較

時系列で複雑さを追跡:

# ノード数を取得
grepai trace graph "main" --depth 3 --json | jq '.stats.nodes'

# リファクタリング前後を比較
echo "Before: $(grepai trace graph 'main' --depth 3 --json | jq '.stats.nodes') nodes"
# ... リファクタリング ...
echo "After: $(grepai trace graph 'main' --depth 3 --json | jq '.stats.nodes') nodes"

よくある問題

❌ 問題: グラフが大きすぎる / タイムアウト ✅ 解決策:

• 深さを減らす: --depth 2
• main ではなく特定の関数をトレース
• --mode fast を使用

❌ 問題: 多くのサイクルが検出される ✅ 解決策: コードに循環依存があることを示しています。リファクタリングを検討してください。

❌ 問題: ブランチが欠落している ✅ 解決策:

• --mode precise を試す
• ファイルがインデックスされているか確認
• 言語が有効化されているか確認

ベストプラクティス

1. 浅く開始: --depth 2 から始めて、必要に応じて増やす
2. 分析を焦点化: 常に main ではなく特定の関数をトレース
3. ドキュメント用にエクスポート: 図を生成するために JSON を使用
4. 時系列で追跡: 複雑さメトリックとしてノード数を監視
5. サイクルを調査: 循環依存はコードの悪い兆候です

出力フォーマット

Trace graph の結果:

🔍 Call Graph for "main"

Depth: 3
Mode: fast

main
├── initialize
│   ├── loadConfig
│   │   └── parseYAML
│   └── connectDB
│       ├── createPool
│       └── ping
├── startServer
│   ├── registerRoutes
│   │   ├── authMiddleware
│   │   └── loggingMiddleware
│   └── listen
└── gracefulShutdown
    └── closeDB

Statistics:
- Total nodes: 12
- Maximum depth reached: 3
- Cycles detected: 0

Tip: Use --json for machine-readable output
     Use --depth N to control recursion depth