AST-Grep インテグレーション

Abstract Syntax Tree 解析を使用した構造的なコード検索、リント、変換ツール。

クイックリファレンス

AST-Grep とは

AST-Grep (sg) は、構造的なコード検索と変換のための高速なポリグロットツールです。正規表現ベースの検索とは異なり、コード構文を理解し、AST 構造に基づいてパターンをマッチングします。

使用するタイミング

• ネストされた関数呼び出しなど、正規表現でキャプチャできないコードパターンの検索
• セマンティック認識を備えた複数ファイルにわたるコード リファクタリング
• SQL インジェクションや XSS を含む脆弱性パターンのセキュリティスキャン
• API マイグレーションと廃止処理
• 構文レベルでのコードスタイルルール の強制

コアコマンド

パターン検索: sg run に pattern オプションで検索対象となるコードパターンを、lang オプションでプログラミング言語を、ソースディレクトリパスを指定して実行します。

ルールを使用したセキュリティスキャン: sg scan に config オプションで sgconfig.yml ファイルを指定して実行します。

コード変換: sg run に pattern オプションで検索対象となるコードを、rewrite オプションで置換内容を、lang オプションで言語を、ソースディレクトリパスを指定して実行します。

ルールテスト: sg test を実行してルール定義を検証します。

パターン構文の基本

ドル記号の後に変数名を続けた形式($VAR など)は、任意の単一 AST ノードをマッチングし、メタ変数としてキャプチャします。

ドル記号の後に 3 つのドル記号と変数名を続けた形式($$$ARGS など)は、可変長キャプチャを使用して 0 個以上のノードをマッチングします。

ダブルドル記号の後にアンダースコア($$_)は、値が不要な場合に任意の単一ノードを匿名キャプチャします。

サポートされている言語

Python、JavaScript、TypeScript、Go、Rust、Java、Kotlin、C、C++、Ruby、Swift、C#、PHP、Scala、Elixir、Lua、HTML、Vue、Svelte、およびその他 30 以上の言語に対応しています。

---

実装ガイド

インストール

macOS では、brew install ast-grep を使用します。

npm によるクロスプラットフォーム対応の場合は、npm install -g @ast-grep/cli を使用します。

Rust の Cargo では、cargo install ast-grep を使用します。

基本的なパターンマッチング

シンプルなパターン検索

すべての console.log 呼び出しを検索するには、pattern に console.log($MSG) を、lang に javascript を指定して sg を実行します。

すべての Python 関数定義を検索するには、pattern に def $FUNC($$$ARGS): $$$BODY を、lang に python を指定して sg を実行します。

React useState フックを検索するには、pattern に useState($INIT) を、lang に tsx を指定して sg を実行します。

検索/参照のパフォーマンス最適化

AST-Grep は、テキストベースの検索と比較して、コードベースの探索において大幅なパフォーマンス上の利点を提供します。

AST-Grep が探索に高速である理由

• 構造的な理解により、誤検知を排除(関連のない結果が 50～80% 削減されます)
• 構文認識マッチングにより、ファイル全体スキャンを削減
• 複数の正規表現パスではなく、AST を 1 回パスしてスキャン

一般的な探索パターン

パターンにマッチするすべての関数呼び出しを検索:

sg -p 'authenticate($$$)' --lang python -r src/

基底クラスから継承しているすべてのクラスを検索:

sg -p 'class $A extends BaseService' --lang python -r src/

特定のインポートパターンを検索:

sg -p 'import fastapi' --lang python -r src/

React フックの使用箇所を検索:

sg -p 'useState($$)' --lang tsx -r src/

async 関数宣言を検索:

sg -p 'async def $NAME($$$ARGS):' --lang python -r src/

パフォーマンス比較

• grep -r "class.*Service" src/ - すべてのファイルをテキストでスキャン(大規模コードベースで約 10 秒)
• sg -p 'class $X extends Service' --lang python -r src/ - 構造的マッチング(約 2 秒)

Explore エージェントとの統合 Explore エージェントを使用する場合、AST-Grep は以下に対して自動的に優先されます:

• クラス階層分析
• 関数シグネチャマッチング
• インポート依存関係マッピング
• API 使用パターン検出

メタ変数

メタ変数はパターンにマッチングする AST ノードをキャプチャします。

単一ノードのキャプチャは $NAME 構文を使用します。たとえば、pattern const $NAME = require($PATH) はこの変数名とパスをキャプチャします。

可変長キャプチャは $$$ARGS 構文を使用します。たとえば、pattern function $NAME($$$ARGS) は関数名とすべての引数をキャプチャします。

匿名の単一キャプチャは値を参照する必要がない場合は $$_ 構文を使用します。

コード変換

シンプルな書き換え

関数を名前変更するには、pattern に oldFunc($ARGS) を、rewrite に newFunc($ARGS) を、lang に python を指定して sg を実行します。

API 呼び出しを更新するには、pattern に axios.get($URL) を、rewrite に fetch($URL) を、lang に typescript を指定して sg を実行します。

YAML ルールを使用した複雑な変換

以下の構造で YAML ルールファイルを作成します。id フィールドに convert-var-to-const などのユニークなルール識別子を設定します。language を javascript などの対象言語に設定します。rule セクション内で、var $NAME = $VALUE などのマッチング対象パターンを指定します。fix フィールドに const $NAME = $VALUE などの置換パターンを設定します。問題を説明するメッセージを追加し、severity を warning または error に設定します。

sg scan をルールオプションでルールファイルを指定し、ソースディレクトリを指定して実行します。

ルールベースのスキャン

設定ファイル

以下のセクションで sgconfig.yml ファイルを作成します。ruleDirs セクションに ./rules/security や ./rules/quality などのルールファイルを含むディレクトリをリストします。testConfigs セクションでテストファイルパターンを指定します。languageGlobs セクションで言語をファイルパターンにマップします。python を .py ファイルにマップし、typescript を .ts および .tsx ファイルにマップし、javascript を .js および .jsx ファイルにマップします。

セキュリティルール例

SQL インジェクション検出用のセキュリティルールファイルを作成します。id を sql-injection-risk に設定します。language を python に、severity を error に設定します。脆弱性に関する説明的なメッセージを記述します。rule セクション内で、any オペレーターを使用して、パーセント形式の cursor.execute、format メソッドの cursor.execute、f 文字列補間の cursor.execute を含む複数のパターンをマッチングします。fix をパラメータ化クエリの代替案を表示するように設定します。

リレーショナルルール

スコープ付き検索用の Inside ルール

関数宣言の内部にのみ console.log 呼び出しを検索するルールを作成します。pattern を console.log($$$ARGS) に設定し、inside 制約を pattern function $NAME($$$PARAMS) で追加します。

含有チェック用の Has ルール

async 関数で await がない場合を検出するルールを作成します。pattern を async function $NAME($$$PARAMS) に設定し、pattern await $EXPR を含む has ルール を使用した not 制約を含めます。async 関数に await がないことを示すメッセージを追加します。

Follows ルールと Precedes ルール

エラー処理の欠落を検出するルールを作成します。pattern をエラー代入 $ERR := $CALL にマッチングするように設定し、if $ERR != nil エラーハンドリングブロックを確認する follows ルールを使用した not 制約を追加します。

複合ルール

all オペレーターを使用して複数の条件を組み合わせることにより、複雑なルールを作成します。たとえば、pattern useState($INIT) を関数コンポーネント用の inside 制約と useEffect 呼び出し用の not precedes 制約と組み合わせます。

---

高度なパターン

複雑なマルチファイル変換、カスタム言語設定、CI/CD インテグレーションパターン、パフォーマンス最適化のヒントを含む包括的なドキュメントについては、以下のモジュールファイルを参照してください。

パターン構文リファレンスは modules/pattern-syntax.md で利用できます。

セキュリティスキャンルールテンプレートは modules/security-rules.md に記載されています。

一般的なリファクタリングパターンは modules/refactoring-patterns.md で説明されています。

言語固有のパターンは modules/language-specific.md で詳細に説明されています。

Context7 インテグレーション

最新の AST-Grep ドキュメントについては、以下の 2 段階のプロセスに従ってください。

ステップ 1: mcp__context7__resolve-library-id をクエリ ast-grep で使用して、ライブラリ識別子を解決します。

ステップ 2: mcp__context7__get-library-docs を解決されたライブラリ ID で使用して、現在のドキュメントを取得します。

MoAI-ADK インテグレーション

AST-Grep は tool_registry.py の Tool Registry を通じて MoAI-ADK に統合されており、AST_ANALYZER タイプとして、Write/Edit 操作後の自動セキュリティスキャン用の PostToolUse フック、および Bash(sg:) と Bash(ast-grep:) が自動許可される権限があります。

スキャンの実行

MoAI-ADK ルールでスキャンするには、config に .claude/skills/moai-tool-ast-grep/rules/sgconfig.yml を指定して sg scan を実行します。

特定のディレクトリをスキャンするには、config に sgconfig.yml を指定して sg scan を実行し、src/ ディレクトリを指定します。

CI/CD に適した JSON 出力の場合は、config と json フラグを指定して sg scan を実行し、results.json にリダイレクトします。

---

相性の良いツール

• moai-workflow-testing: DDD インテグレーションとテストパターン検出
• moai-foundation-quality: TRUST 5 コンプライアンスとコード品質ゲート
• moai-domain-backend: API パターン検出とセキュリティスキャン
• moai-domain-frontend: React/Vue パターン最適化
• moai-lang-python: Python 固有のセキュリティとスタイルルール
• moai-lang-typescript: TypeScript 型安全性パターン

関連エージェント

• expert-refactoring: AST ベースの大規模リファクタリング
• expert-security: セキュリティ脆弱性スキャン
• manager-quality: コード複雑性分析
• expert-debug: パターンベースのデバッグ

---

リファレンス

詳細については、ast-grep.github.io の AST-Grep 公式ドキュメント、github.com/ast-grep/ast-grep の AST-Grep GitHub リポジトリ、ast-grep.github.io/playground.html のパターンプレイグラウンド、ast-grep.github.io/reference/yaml.html のルール設定リファレンスを参照してください。