moai-tool-ast-grep

AST-Grep の統合

抽象構文木解析を使用した、構造的なコード検索、Lint、変換ツールです。

クイックリファレンス

AST-Grep とは

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

使用する場面

• ネストされた関数呼び出しなど、正規表現では捉えられないコードパターンの検索
• セマンティクスを認識しながら、複数のファイルにまたがるコードをリファクタリングする場合
• SQL インジェクションや XSS などの脆弱性パターンを含む、セキュリティスキャン
• API の移行と非推奨への対応
• 構文レベルでのコードスタイルルールの適用

主なコマンド

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

ルールを使ったセキュリティスキャン：sgconfig.yml ファイルを指定する config オプションを付けて、sg scan を実行します。

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

ルールのテスト：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) は、関数名とすべての引数をキャプチャします。

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

コード変換

シンプルな書き換え

関数の名前を変更するには、パターンに oldFunc($ARGS)、書き換えに newFunc($ARGS)、言語に python を指定して sg を実行します。

API 呼び出しを更新するには、パターンに axios.get($URL)、書き換えに fetch($URL)、言語に typescript を指定して sg を実行します。

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

次の構造で YAML ルールファイルを作成します。id フィールドには、convert-var-to-const などの一意なルール識別子を設定します。language には、javascript などの対象言語を設定します。rule セクションでは、var $NAME = $VALUE などの照合するパターンを指定します。fix フィールドには、const $NAME = $VALUE などの置換パターンを設定します。問題の説明を記載したメッセージを追加し、重要度を warning または error に設定します。

rule オプションにルールファイルを指定し、ソースディレクトリを指定して 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-string 補間を使う cursor.execute など、複数のパターンに一致させます。fix には、パラメーター化クエリを使う代替方法を示します。

関係ルール

スコープ内検索のための Inside ルール

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

Contains チェックのための Has ルール

await を含まない非同期関数を検索するルールを作成します。パターンを async function $NAME($$$PARAMS) に設定し、パターンが await $EXPR の has ルールを含む not 制約を追加します。await を含まない非同期関数であることを示すメッセージを追加します。

Follows および Precedes ルール

エラー処理の欠落を検出するルールを作成します。エラーの代入 $ERR := $CALL に一致するパターンを設定し、follows ルールで if $ERR != nil のエラー処理ブロックを確認する not 制約を追加します。

複合ルール

all 演算子を使って複数の条件を組み合わせ、複雑なルールを作成します。たとえば、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：解決したライブラリ ID を使用して mcp__context7__get-library-docs を呼び出し、最新のドキュメントを取得します。

MoAI-ADK との統合

AST-Grep は、Tool Registry を通じて MoAI-ADK に統合されています。internal/hook/registry.go では AST_ANALYZER タイプとして登録され、Write/Edit 操作後に自動でセキュリティスキャンを実行する PostToolUse Hook があり、Permissions では Bash(sg:*) と Bash(ast-grep:*) が自動的に許可されます。

スキャンの実行

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

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

CI/CD に適した JSON 出力を取得するには、設定と 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 公式ドキュメント（ast-grep.github.io）、AST-Grep GitHub リポジトリ（github.com/ast-grep/ast-grep）、パターンプレイグラウンド（ast-grep.github.io/playground.html）、ルール設定リファレンス（ast-grep.github.io/reference/yaml.html）をご覧ください。