tool-ast-grep-rules

ast-grep ルール作成ガイド

ast-grep は tree-sitter を使用してコードを AST に解析し、正確なパターンマッチングを可能にします。ルールは YAML で定義し、コードの lint、検索、書き換えに使用します。

クイックスタート

id: no-console-log
language: JavaScript
rule:
  pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)
message: Replace console.log with logger

プロジェクト設定

プロジェクトレベルのスキャンには、sgconfig.yml 設定ファイルが必要です。

# sgconfig.yml (project root)
ruleDirs:
  - rules          # Rule directory, recursively loads all .yml files

一般的なプロジェクト構成：

my-project/
├── sgconfig.yml
├── rules/
│   ├── no-console.yml
│   └── custom/
│       └── team-rules.yml
└── src/

プロジェクトをスキャンするには：

ast-grep scan              # Automatically finds sgconfig.yml
ast-grep scan --config path/to/sgconfig.yml  # Specify config

注：ast-grep scan コマンドには sgconfig.yml が必要ですが、ast-grep run -p は単独で使用できます。

ルールのワークフロー

Lint ルール（一般的）

修正は行わずにチェックだけを行います。CI／エディターのヒントに使用します。

# rules/no-console-log.yml
id: no-console-log
language: JavaScript
severity: warning
message: Avoid console.log in production code
rule:
  pattern: console.log($$$ARGS)

確認：

ast-grep scan -r rules/no-console-log.yml src/

書き換えルール（任意）

自動修正が必要な場合は、fix を追加します。

id: no-console-log
language: JavaScript
severity: warning
message: Replace console.log with logger
rule:
  pattern: console.log($$$ARGS)
fix: logger.log($$$ARGS)

修正を適用：

ast-grep scan -r rules/no-console-log.yml --update-all src/

開発ワークフロー

- [ ] 1. Explore pattern with CLI: ast-grep -p 'pattern' src/
- [ ] 2. Create rule file (.yml)
- [ ] 3. Verify: ast-grep scan -r rule.yml src/
- [ ] 4. If false positives → add constraints → re-verify

AST 構造をデバッグ：

ast-grep -p 'console.log($ARG)' --debug-query ast

基本構文

要素	構文	例
単一ノード	$VAR	console.log($MSG)
複数ノード	$$$ARGS	fn($$$ARGS)
同じ内容	同じ名前を使用	$A == $A
キャプチャしない	$_VAR	$_FN($_FN)

コアルールのクイックリファレンス

種類	用途	例
pattern	コード構造にマッチ	pattern: if ($COND) {}
kind	AST ノードの種類にマッチ	kind: function_declaration
all	すべての条件にマッチ	all: [pattern: X, kind: Y]
any	いずれかの条件にマッチ	any: [pattern: var $A, pattern: let $A]
not	マッチを除外	not: {pattern: safe_call()}
has	子ノードを持つ必要がある	has: {kind: return_statement}
inside	祖先ノード内にある必要がある	inside: {kind: class_body}

詳細リファレンス

構文の完全ガイド：rule-syntax.md を参照してください。

• アトミックルール（pattern、kind、regex、nthChild、range）
• 複合ルール（all、any、not、matches）
• 関係ルール（has、inside、follows、precedes）
• Transform と fixConfig

言語固有のパターン：common-patterns.md を参照してください。

• JavaScript／TypeScript の例
• Python の例
• Go と Rust の例

サポート対象言語

Bash、C、Cpp、CSharp、Css、Elixir、Go、Haskell、Hcl、Html、Java、JavaScript、Json、Kotlin、Lua、Nix、Php、Python、Ruby、Rust、Scala、Solidity、Swift、Tsx、TypeScript、Yaml