この回から使うサンプル

PART 04〜06 では、Spring Boot 風の注文サービスを解析対象にする。わざと「空の catch」や「System.out.println」を入れてあるので、PART 06 のチェッカーで引っかかるようになっている。

sample/src/main/java/com/example/order/OrderService.java
package com.example.order;

import java.util.List;
import java.util.ArrayList;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {

    private final OrderRepository repository;
    private final MailSender mailSender;

    public OrderService(OrderRepository repository, MailSender mailSender) {
        this.repository = repository;
        this.mailSender = mailSender;
    }

    @Transactional
    public Order placeOrder(String customerId, List<Item> items) {
        Order order = new Order(customerId);
        for (Item item : items) {
            if (item.getQuantity() > 0) {
                if (item.isInStock()) {
                    order.addItem(item);
                } else {
                    System.out.println("在庫切れ: " + item.getName());
                }
            }
        }
        repository.save(order);
        try {
            mailSender.send(customerId, "ご注文ありがとうございます");
        } catch (Exception e) {
        }
        return order;
    }

    public List<Order> findOrders(String customerId) {
        return repository.findByCustomerId(customerId);
    }
}

Query の基本形

Query は、PART 03 で見た S 式と同じ形で書く。取り出したいノードの後ろに @名前 を付けると、そのノードが キャプチャ として返ってくる。

Query
(method_declaration
  name: (identifier) @method.name)

これは「method_declaration で、name フィールドが identifier のもの」に一致し、その identifier を method.name という名前で返す、という意味になる。パターンに書かなかった子(修飾子や本体)は、あってもなくても一致する。

クラス名・メソッド・フィールドをまとめて取り出すスクリプトを書いてみる。

query_basic.py
import sys
from tree_sitter import Query, QueryCursor
from ts_common import JAVA, parse_file, text

QUERY = Query(JAVA, r"""
(class_declaration
  name: (identifier) @class.name)

(method_declaration
  type: (_) @method.return
  name: (identifier) @method.name
  parameters: (formal_parameters) @method.params)

(field_declaration
  type: (_) @field.type
  declarator: (variable_declarator
    name: (identifier) @field.name))
""")

src, tree = parse_file(sys.argv[1])
cursor = QueryCursor(QUERY)

# captures(): キャプチャ名ごとにノードの一覧が返る
captures = cursor.captures(tree.root_node)
for name in ("class.name", "method.name", "field.name"):
    print(name, [text(n) for n in captures.get(name, [])])

print("---")
# matches(): 1つのパターンに一致した組をまとめて返す
for pattern_index, m in cursor.matches(tree.root_node):
    if pattern_index == 1:
        print(f"method {text(m['method.name'][0])}"
              f"{text(m['method.params'][0])} -> {text(m['method.return'][0])}")
    elif pattern_index == 2:
        print(f"field  {text(m['field.name'][0])} : {text(m['field.type'][0])}")
PowerShell / bash
python query_basic.py sample/src/main/java/com/example/order/OrderService.java
実行結果
class.name ['OrderService']
method.name ['placeOrder', 'findOrders']
field.name ['repository', 'mailSender']
---
field  repository : OrderRepository
field  mailSender : MailSender
method placeOrder(String customerId, List<Item> items) -> Order
method findOrders(String customerId) -> List<Order>

3つのパターンを1つの Query にまとめて書けること、type: (_) の (_) が「どんな名前付きノードでもよい」というワイルドカードであることがポイントだ。戻り値の型は integral_type のときも generic_type(List<Order>)のときもあるので、ワイルドカードで受けている。

💡 コンストラクタが出てこない理由

出力にコンストラクタ OrderService(...) がないのは、Java の文法ではコンストラクタが method_declaration ではなく constructor_declaration という別のノード型だからだ。両方を取りたいときは次の節の「選択」[ ] を使う。

captures と matches の違い

Query を実行するのは QueryCursor で、結果の受け取り方が2通りある。

メソッド戻り値向いている用途
captures(node){キャプチャ名: [Node, ...]} の辞書。ノードはソース上の位置順「メソッド名を全部」のように、キャプチャを1種類ずつ使う
matches(node)[(パターン番号, {キャプチャ名: [Node, ...]}), ...] のリスト「メソッド名と、その引数と戻り値」のように、同じ一致に属する複数のキャプチャを組で使う

captures() では、method.name の一覧と method.params の一覧が別々に返ってくるので、どの名前とどの引数が組なのかは自分で位置を比べないとわからない。matches() なら1件の一致ごとに辞書が返るので組がずれない。パターン番号(0始まり)は Query の中でパターンを書いた順番で、上の例では 1 がメソッド、2 がフィールドに当たる。

⚠️ 0.25 で API が変わった

0.24 以前は query.captures(node) のように Query 自体にメソッドがあった。0.25 からは QueryCursor(query).captures(node) に移っている。ネットの古いサンプルが AttributeError になる場合は、ここを疑う。

パターンの書き方

実務でよく使う書き方を表にまとめる。

書き方意味例
(_)任意の名前付きノードtype: (_) @t
_任意のノード(名前なしノードも含む)(binary_expression operator: _ @op)
"文字列"名前なしノード(記号・キーワード)(assignment_expression operator: "+=")
[ A B ]選択(A または B)[(method_declaration) (constructor_declaration)] @m
? / * / +0か1回/0回以上/1回以上object: (_)? @obj
.アンカー(最初の子・最後の子・隣接)(class_body . (field_declaration) @first)
!fieldそのフィールドを持たない(method_declaration !body) = 本体のない abstract メソッド
; コメントQuery 内のコメント; System.out の呼び出し

たとえばメソッドとコンストラクタの名前を両方取るなら、選択を使って次のように書ける。

Query
[
  (method_declaration      name: (identifier) @name)
  (constructor_declaration name: (identifier) @name)
]
結果(captures の name)
['OrderService', 'placeOrder', 'findOrders']

述語で絞り込む

形だけでなく「名前が System のもの」のようにテキストで絞り込みたいときは、パターンの後ろに 述語 を書く。述語を付けるときは、パターン全体をもう1組の括弧で囲む。

述語意味
(#eq? @a "文字列") / (#eq? @a @b)テキストが一致する(キャプチャ同士の比較もできる)
(#not-eq? @a "文字列")一致しない
(#match? @a "正規表現")正規表現に一致する(部分一致。全体一致させるなら ^...$)
(#not-match? @a "正規表現")正規表現に一致しない
(#any-of? @a "x" "y" ...)いずれかと一致する

System.out.println の呼び出し・@Transactional 付きのメソッド・find で始まるメソッドを探す例だ。

query_predicate.py
import sys
from tree_sitter import Query, QueryCursor
from ts_common import JAVA, parse_file, text

QUERY = Query(JAVA, r"""
; System.out.println(...) の呼び出し
((method_invocation
   object: (field_access
     object: (identifier) @_sys
     field: (identifier) @_out)
   name: (identifier) @_m) @println
 (#eq? @_sys "System")
 (#eq? @_out "out")
 (#match? @_m "^print(ln)?$"))

; @Transactional が付いたメソッド
(method_declaration
  (modifiers
    (marker_annotation name: (identifier) @_ann))
  name: (identifier) @tx.method
  (#eq? @_ann "Transactional"))

; find で始まるメソッド
((method_declaration name: (identifier) @finder)
 (#match? @finder "^find"))
""")

src, tree = parse_file(sys.argv[1])
caps = QueryCursor(QUERY).captures(tree.root_node)
for n in caps.get("println", []):
    print(f"println  line {n.start_point.row + 1}: {text(n)}")
for n in caps.get("tx.method", []):
    print("transactional:", text(n))
for n in caps.get("finder", []):
    print("finder:", text(n))
実行結果
println  line 27: System.out.println("在庫切れ: " + item.getName())
transactional: placeOrder
finder: findOrders
  • System.out.println(...) は、object が field_access(System.out)、name が println の method_invocation になっている。@println は呼び出し全体に付けたキャプチャなので、出力には引数まで含めた全体が出る
  • 引数なしのアノテーション @Transactional は marker_annotation、引数付きの @GetMapping("/x") は annotation という別のノード型になる。両方を見たいなら [(marker_annotation) (annotation)] と選択で書く
  • 述語の判定のためだけに使うキャプチャには、@_sys のように _ を付けて区別しておくと読みやすい(結果の辞書には含まれるので、使わずに無視する)

💡 grep との違いをもう一度

この Query は、コメントや文字列リテラルの中に System.out.println と書かれていても一致しない。System .out. println(...) のように空白や改行が入っていても一致する。PART 01 で挙げた grep の弱点が、構文木を相手にすることで自然に消えている。

Query のエラーと確かめ方

Query の文法が間違っていたり、文法に存在しないノード型・フィールド名を書いたりすると、Query(...) を作った時点で QueryError になる。位置まで教えてくれるので、typo はすぐ見つかる。

Python
Query(JAVA, "(method_declaration nme: (identifier))")
実行結果
QueryError: Invalid field name at row 0, column 20: nme

ノードの親子関係が文法上ありえない Query も、作成時に Impossible pattern として弾かれる。たとえば (field_declaration name: (identifier)) は、PART 03 で見たように名前が declarator の下にあるのでエラーになる。

やっかいなのは、文法上はありうるが、実際の木とは形が違う Query だ。これはエラーにならず、ただ0件になる。たとえば System.out.println を探すつもりで ((method_invocation object: (identifier) name: (identifier) @n) (#eq? @n "println")) と書くと、object は identifier ではなく field_access(System.out)なので1件も一致しない。結果が空だったら、まず dump_tree.py で実物の木を確認するのが近道だ。

✅ Query は別ファイルに置いてもよい

パターンが増えてきたら、queries/java_calls.scm のような .scm ファイルに分け、Query(JAVA, Path("queries/java_calls.scm").read_text()) で読み込むと管理しやすい。エディタ用の文法パッケージに入っている highlights.scm なども同じ形式で書かれており、書き方の参考になる。

✅ 次の記事では…

PART 05 では、ここまでの部品を組み合わせて、プロジェクト一式から型・メソッド・メソッド呼び出し・import を抽出し、JSONL とクラス間の依存グラフ(Mermaid)を出力する。

→ PART 05 — 実践:呼び出し・依存の抽出へ