ast-grep-find

AST-Grep Find

構文を理解した構造的なコード検索です。関数呼び出し、インポート、クラス定義などのパターンを検索できます。テキストだけの検索ではありません。

使用するタイミング

• コードのパターンを検索する（文字列やコメントは無視します）
• 関数呼び出し、クラス定義、インポートを検索する
• AST の精度でコードをリファクタリングする
• コードベース全体で変数や関数の名前を変更する

使い方

パターンを検索する

uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "import asyncio" --language python

特定のディレクトリを検索する

uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "async def \$FUNC(\$\$\$)" --language python --path "./src"

パターンをリファクタリング／置換する

uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "console.log(\$MSG)" --replace "logger.info(\$MSG)" \
    --language javascript

ドライラン（変更をプレビューする）

uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "print(\$X)" --replace "logger.info(\$X)" \
    --language python --dry-run

パラメーター

パラメーター	説明
--pattern	検索する AST パターン（必須）
--language	言語：python、javascript、typescript、go など
--path	検索するディレクトリ（デフォルト：.）
--glob	ファイルの glob パターン（例：**/*.py）
--replace	リファクタリング用の置換パターン
--dry-run	変更を適用せずにプレビューします
--context	前後に表示する行数（デフォルト：2）

パターン構文

構文	意味
$NAME	単一のノード（変数、式）に一致
$$$	複数のノード（引数、文）に一致
$_	任意の単一ノードに一致（ワイルドカード）

例

# Find all function definitions
uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "def \$FUNC(\$\$\$):" --language python

# Find console.log calls
uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "console.log(\$\$\$)" --language javascript

# Replace print with logging
uv run python -m runtime.harness scripts/ast_grep_find.py \
    --pattern "print(\$X)" --replace "logging.info(\$X)" \
    --language python --dry-run

morph/warpgrep との比較

ツール	最適な用途
ast-grep	構造的なパターン（コードの構文を理解します）
warpgrep	高速なテキスト／正規表現検索（grep より 20 倍高速）

構文を認識した一致が必要な場合は ast-grep を使用します。速度を優先する場合は warpgrep を使用します。

必要な MCP サーバー

mcp_config.json に ast-grep サーバーが必要です。