ast-grep

ast-grep コード検索

自然言語のクエリを ast-grep ルールに変換し、サンプルに対して検証してから、コードベースで実行します。ルール構文の全容（アトミック／リレーショナル／複合ルール、メタ変数、トラブルシューティング、実例）はreferences/rule_reference.mdに記載されています。単純な pattern を超えるものを書く場合は、こちらをお読みください。

前提条件

ast-grep --version が動作する必要があります。インストールされていない場合は、brew install ast-grep（macOS）、npm i -g @ast-grep/cli、または cargo install ast-grep を実行してください。ast-grep を使用してください（sg エイリアスはシステムの sg と競合します）。

ワークフロー

1. 明確化 — 言語は何ですか？一致させる正確な構造は何ですか？含める／除外するエッジケースはありますか？
2. サンプルを作成 — 一致するはずの小さなコード片を書き、一時ファイルに保存します。
3. ルールを作成 — まずは動作する最も単純なものから始め、段階的に複雑にします。
   • 直接的なコード構造には pattern → ノードタイプには kind → リレーショナル（has／inside）→ 複合（all／any／not）。
   • **リレーショナルルールには必ず stopBy: end を追加してください。**これにより、最初に一致しないノードで停止せず、サブツリー全体を走査します。
4. サンプルに対してテストし、一致するまで調整します（下記のデバッグを参照）。
5. 一致するようになったら、コードベースで実行します。

コマンド

目的	コマンド
単純なパターン検索	ast-grep run --pattern 'console.log($ARG)' --lang js .
ルールファイルを使った検索	ast-grep scan --rule rule.yml /path
ファイルを使わないインラインルール	ast-grep scan --inline-rules "$YAML" /path
スニペットに対してルールをテスト	echo '<code>' | ast-grep scan --inline-rules "$YAML" --stdin
kind の値を調べるために AST を確認	ast-grep run --pattern '<code>' --lang js --debug-query=cst

構造化された出力を得るには、上記のいずれかに --json を追加します。--debug-query は cst（すべてのノード）、ast（名前付きノードのみ）、または pattern（ast-grep がパターンをどのように読み取るか）を受け付けます。

単一ノードへの単純な一致には run --pattern を使い、リレーショナルまたは複合ロジックが必要な場合は scan（ルールファイルまたはインライン）を使います。

インラインルールでのエスケープ

シェルは $ を展開するため、二重引用符で囲んだ --inline-rules では \$VAR と記述するか、YAML を一重引用符で囲みます。

ast-grep scan --inline-rules "rule: {pattern: 'console.log(\$ARG)'}" .
ast-grep scan --inline-rules 'rule: {pattern: "console.log($ARG)"}' .

一致しないルールのデバッグ

1. 単純化する — サブルールを、失敗している最小の部分まで削ります。
2. リレーショナルルールに stopBy: end があることを確認します。
3. --debug-query=cst を使って実際のノード構造を読み取り、kind の値を確認します。
4. メタ変数が検出されていることを確認します（リファレンスのメタ変数に関する注記を参照）。

リソース

• references/rule_reference.md — ルール構文の全容と実例。
• ast-grep のドキュメント · オンラインでパターンをテストできるプレイグラウンド。