grepai-trace-graph

GrepAI トレースグラフ

このスキルでは、grepai 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 で再帰の深さを制限します。

# Default depth (2 levels)
grepai trace graph "main"

# Deeper analysis (3 levels)
grepai trace graph "main" --depth 3

# Shallow (1 level, same as callees)
grepai trace graph "main" --depth 1

# Very deep (5 levels)
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 は同時に指定できません。

抽出モード

# Fast mode (regex-based)
grepai trace graph "main" --mode fast

# Precise mode (tree-sitter AST)
grepai trace graph "main" --mode precise

使用例

アプリケーションフローの把握

# Map entire application startup
grepai trace graph "main" --depth 4

影響分析

# What depends on this utility function?
grepai trace graph "validateInput" --depth 3

# Full impact of changing database layer
grepai trace graph "executeQuery" --depth 2

コードレビュー

# Is this function too complex?
grepai trace graph "processOrder" --depth 5
# Many nodes = high complexity

ドキュメント作成

# Generate architecture diagram data
grepai trace graph "main" --depth 3 --json > architecture.json

リファクタリング計画

# What would break if we change this?
grepai trace graph "legacyAuth" --depth 3

循環依存への対応

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

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

JSON の場合：

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

大規模なグラフ

非常に大規模なコードベースでは、グラフが複雑になりすぎることがあります。

深さを制限する

# Start shallow
grepai trace graph "main" --depth 2

特定の領域に絞る

# Instead of main, trace specific subsystem
grepai trace graph "authMiddleware" --depth 3

後処理でフィルタリングする

# Get JSON and filter
grepai trace graph "main" --depth 3 --json | jq '...'

グラフの可視化

DOT 形式（Graphviz）にエクスポートする

# Convert JSON to 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

グラフサイズの比較

複雑さの推移を追跡します。

# Get node count
grepai trace graph "main" --depth 3 --json | jq '.stats.nodes'

# Compare before/after refactoring
echo "Before: $(grepai trace graph 'main' --depth 3 --json | jq '.stats.nodes') nodes"
# ... refactoring ...
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. 循環を調査する： 循環依存はコードの問題の兆候です

出力形式

トレースグラフの結果：

🔍 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