作るものと出力の形

入力は src/ 配下の *.java すべて、出力は次の4種類のレコードを並べた JSONL ファイルだ。JSONL にしておけば、Excel・pandas・jq・DuckDB のどれでも読めるし、あとから別の図に変換するのも簡単になる。

kind中身主な項目
typeクラス・インターフェース・enum・recordpackage、name、annotations、imports
methodメソッドとコンストラクタtype、name、annotations、start/end(行)
callメソッド呼び出しcaller(呼び出し元)、object、object_type(推定した型)、callee
newインスタンス生成caller、type
src配下のJavaファイルから、宣言の収集、呼び出しの収集、型の推定を経てdeps.jsonlを出力し、to_mermaid.pyでクラス間の依存グラフにする流れの図

図1: extract_deps.py と to_mermaid.py の処理の流れ

解析対象には、PART 04 の OrderService に加えて、それを呼ぶコントローラーを用意する。

sample/src/main/java/com/example/web/OrderController.java
package com.example.web;

import com.example.order.Order;
import com.example.order.OrderService;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/orders")
public class OrderController {

    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    @PostMapping
    public Order create(@RequestBody OrderRequest req) {
        validate(req);
        return orderService.placeOrder(req.getCustomerId(), req.getItems());
    }

    @GetMapping("/{customerId}")
    public java.util.List<Order> list(@PathVariable String customerId) {
        return orderService.findOrders(customerId);
    }

    private void validate(OrderRequest req) {
        if (req.getItems().isEmpty()) {
            throw new IllegalArgumentException("items is empty");
        }
    }
}

抽出スクリプトの全体

まず全体を載せ、そのあとで要所を説明する。PART 02 の ts_common.py を同じフォルダに置いて使う。

extract_deps.py
"""Javaソース一式から型・メソッド・呼び出し・import・アノテーションを抽出し JSONL で出力する"""
import json
import sys
from pathlib import Path
from tree_sitter import Query, QueryCursor
from ts_common import JAVA, parser, read_source, text

TYPE_NODES = {"class_declaration", "interface_declaration",
              "enum_declaration", "record_declaration"}
METHOD_NODES = {"method_declaration", "constructor_declaration"}

CALL_QUERY = Query(JAVA, r"""
(method_invocation
  object: (_)? @call.object
  name: (identifier) @call.name) @call
(object_creation_expression
  type: (_) @new.type) @new
""")
HEADER_QUERY = Query(JAVA, r"""
(package_declaration (_) @package)
(import_declaration) @import
""")

def enclosing(node, kinds):
    """node を含む一番内側の kinds 型の祖先を返す"""
    p = node.parent
    while p is not None and p.type not in kinds:
        p = p.parent
    return p

def name_of(node):
    n = node.child_by_field_name("name")
    return text(n) if n else "<anonymous>"

def qualified_type(node):
    """入れ子クラスも Outer.Inner の形にする"""
    names = []
    while node is not None:
        if node.type in TYPE_NODES:
            names.append(name_of(node))
        node = node.parent
    return ".".join(reversed(names))

def import_name(node):
    """'import static a.b.C.*;' -> 'static a.b.C.*'"""
    body = text(node).removeprefix("import").rstrip(";")
    return " ".join(body.split())

VAR_QUERY = Query(JAVA, r"""
(field_declaration
  type: (_) @type
  declarator: (variable_declarator name: (identifier) @name))
(formal_parameter type: (_) @type name: (identifier) @name)
(local_variable_declaration
  type: (_) @type
  declarator: (variable_declarator name: (identifier) @name))
(enhanced_for_statement type: (_) @type name: (identifier) @name)
""")

def var_types(scope):
    """scope 内で宣言された 変数名 -> 型名 の辞書(同名は内側が勝つ前提で後勝ち)"""
    table = {}
    for _, m in QueryCursor(VAR_QUERY).matches(scope):
        table[text(m["name"][0])] = text(m["type"][0])
    return table

def annotations(decl):
    mods = next((c for c in decl.children if c.type == "modifiers"), None)
    if mods is None:
        return []
    return [text(c.child_by_field_name("name")) for c in mods.named_children
            if c.type in ("marker_annotation", "annotation")]

def analyze(path: Path):
    tree = parser.parse(read_source(path))
    root = tree.root_node
    header = QueryCursor(HEADER_QUERY).captures(root)
    package = text(header["package"][0]) if "package" in header else ""
    imports = [import_name(n) for n in
               sorted(header.get("import", []), key=lambda n: n.start_byte)]
    file = path.as_posix()

    if root.has_error:
        yield {"kind": "warning", "file": file, "message": "syntax error"}

    # 型とメソッド
    stack = [root]
    while stack:
        node = stack.pop()
        if node.type in TYPE_NODES:
            yield {"kind": "type", "file": file, "package": package,
                   "name": qualified_type(node), "declaration": node.type,
                   "annotations": annotations(node), "imports": imports,
                   "line": node.start_point.row + 1}
        elif node.type in METHOD_NODES:
            yield {"kind": "method", "file": file,
                   "type": qualified_type(node), "name": name_of(node),
                   "annotations": annotations(node),
                   "start": node.start_point.row + 1,
                   "end": node.end_point.row + 1}
        stack.extend(reversed(node.named_children))

    # 呼び出し(matches で call と object を組で受け取る)
    scope_cache = {}
    def lookup(call, name):
        """フィールド・引数・ローカル変数の宣言から変数の型を推定する"""
        for kinds in (METHOD_NODES, TYPE_NODES):
            scope = enclosing(call, kinds)
            if scope is None:
                continue
            key = scope.id
            if key not in scope_cache:
                scope_cache[key] = var_types(scope)
            if name in scope_cache[key]:
                return scope_cache[key][name]
        return ""

    for _, m in QueryCursor(CALL_QUERY).matches(root):
        call = (m.get("call") or m.get("new"))[0]
        method = enclosing(call, METHOD_NODES)
        caller = (f"{qualified_type(method)}#{name_of(method)}"
                  if method else qualified_type(call) or "<top>")
        if "call" in m:
            obj_node = m["call.object"][0] if "call.object" in m else None
            obj = text(obj_node) if obj_node else ""
            if obj_node is None:
                obj_type = qualified_type(call)      # 自クラスのメソッド
            elif obj_node.type == "identifier":
                obj_type = lookup(call, obj)          # 変数なら宣言から推定
            elif obj_node.type == "this":
                obj_type = qualified_type(call)
            else:
                obj_type = ""                         # 式の戻り値型は分からない
            yield {"kind": "call", "file": file, "caller": caller,
                   "object": obj, "object_type": obj_type,
                   "callee": text(m["call.name"][0]),
                   "line": call.start_point.row + 1}
        else:
            yield {"kind": "new", "file": file, "caller": caller,
                   "type": text(m["new.type"][0]),
                   "line": call.start_point.row + 1}

def main(src_dir, out_path):
    files = sorted(Path(src_dir).rglob("*.java"))
    with open(out_path, "w", encoding="utf-8") as out:
        for f in files:
            for rec in analyze(f):
                out.write(json.dumps(rec, ensure_ascii=False) + "\n")
    print(f"{len(files)} files -> {out_path}")

if __name__ == "__main__":
    main(sys.argv[1], sys.argv[2])
PowerShell / bash
python extract_deps.py sample/src deps.jsonl
実行結果
2 files -> deps.jsonl

出力から一部を抜き出すと次のようになる(実際は1行1件)。

deps.jsonl(抜粋)
{"kind": "type", "file": "sample/src/main/java/com/example/order/OrderService.java", "package": "com.example.order", "name": "OrderService", "declaration": "class_declaration", "annotations": ["Service"], "imports": ["java.util.List", "java.util.ArrayList", "org.springframework.stereotype.Service", "org.springframework.transaction.annotation.Transactional"], "line": 8}
{"kind": "method", "file": "sample/src/main/java/com/example/order/OrderService.java", "type": "OrderService", "name": "OrderService", "annotations": [], "start": 14, "end": 17}
{"kind": "method", "file": "sample/src/main/java/com/example/order/OrderService.java", "type": "OrderService", "name": "placeOrder", "annotations": ["Transactional"], "start": 19, "end": 37}
{"kind": "call", "file": "sample/src/main/java/com/example/order/OrderService.java", "caller": "OrderService#placeOrder", "object": "item", "object_type": "Item", "callee": "getQuantity", "line": 23}
{"kind": "call", "file": "sample/src/main/java/com/example/order/OrderService.java", "caller": "OrderService#placeOrder", "object": "item", "object_type": "Item", "callee": "getName", "line": 27}
{"kind": "call", "file": "sample/src/main/java/com/example/web/OrderController.java", "caller": "OrderController#create", "object": "", "object_type": "OrderController", "callee": "validate", "line": 19}
{"kind": "call", "file": "sample/src/main/java/com/example/web/OrderController.java", "caller": "OrderController#create", "object": "orderService", "object_type": "OrderService", "callee": "placeOrder", "line": 20}
{"kind": "call", "file": "sample/src/main/java/com/example/web/OrderController.java", "caller": "OrderController#validate", "object": "req.getItems()", "object_type": "", "callee": "isEmpty", "line": 29}

宣言の集め方:入れ子クラスと呼び出し元を求める

型とメソッドは、Query を使わずにノードを直接たどって集めている。理由は、どのクラスの中にあるか を正しく求めたいからだ。

  • qualified_type() は、ノードから親へさかのぼり、途中にある型宣言の名前を全部つなぐ。入れ子クラスなら Outer.Inner になる
  • enclosing() は、呼び出しノードから親へさかのぼって、最初に見つかったメソッド(またはコンストラクタ)を返す。これが呼び出し元 caller になる
  • フィールドの初期化式や static 初期化ブロックの中の呼び出しにはメソッドがないので、caller はクラス名だけになる

アノテーションは modifiers の子にある marker_annotation(引数なし)と annotation(引数あり)の両方から name を取っている。@RequestMapping("/orders") が RequestMapping として取れているのはこのためだ。

💡 import の取り方

import org.springframework.web.bind.annotation.*; のようなワイルドカード import は、木の中では scoped_identifier と asterisk の2つのノードに分かれている。子ノードを拾うと * が別の要素になってしまうので、ここでは import_declaration 全体のテキストから import と ; を取り除いている。import static も static a.b.C.method の形で残る。

呼び出しの集め方:matches で組を崩さない

呼び出しは Query で集める。ここで PART 04 の matches() が効いてくる。

Query(CALL_QUERY)
(method_invocation
  object: (_)? @call.object
  name: (identifier) @call.name) @call

object: (_)? の ? は「あってもなくてもよい」という意味で、repository.save(order) も、自クラスのメソッドを呼ぶだけの validate(req) も1つのパターンで拾える。matches() で受け取れば、1件ごとに call・call.object・call.name が組になって返るので、どの呼び出しのレシーバーがどれか取り違えることがない。call.object がない一致は、レシーバーなしの呼び出しだと判断できる。

変数の型を推定する

tree-sitter は型を解決しないので、orderService.placeOrder(...) という呼び出しを見ても、orderService が何型なのかは教えてくれない。そこで、同じメソッドの中、次に同じクラスの中にある変数宣言 から型を探すという簡易的な推定を入れている。

宣言の種類ノード型例
フィールドfield_declarationprivate final OrderService orderService;
引数formal_parameterOrderRequest req
ローカル変数local_variable_declarationOrder order = new Order(customerId);
拡張 for の変数enhanced_for_statementfor (Item item : items)

これだけで、サンプルの呼び出しはほとんど型が付く。結果を「呼び出し元 → 型.メソッド」の形で並べると次のとおりだ。

call レコードの要約
OrderService#placeOrder -> Item . getQuantity ( item )
OrderService#placeOrder -> Item . isInStock ( item )
OrderService#placeOrder -> Order . addItem ( order )
OrderService#placeOrder -> ? . println ( System.out )
OrderService#placeOrder -> Item . getName ( item )
OrderService#placeOrder -> OrderRepository . save ( repository )
OrderService#placeOrder -> MailSender . send ( mailSender )
OrderService#findOrders -> OrderRepository . findByCustomerId ( repository )
OrderController#create -> OrderController . validate (  )
OrderController#create -> OrderService . placeOrder ( orderService )
OrderController#create -> OrderRequest . getCustomerId ( req )
OrderController#create -> OrderRequest . getItems ( req )
OrderController#list -> OrderService . findOrders ( orderService )
OrderController#validate -> OrderRequest . getItems ( req )
OrderController#validate -> ? . isEmpty ( req.getItems() )

? になった2件が、この方法の限界をよく表している。

  • System.out.println:System は変数ではなくクラスで、out はそのフィールドだ。JDK のクラスの中身はソースにないので推定できない
  • req.getItems().isEmpty():レシーバーが 式の結果 なので、getItems() の戻り値の型を知らないと決まらない

⚠️ 推定であって解決ではない

この方法はスコープを「メソッド内 → クラス内」の2段でしか見ておらず、ブロックごとの変数の有効範囲や、同名の変数による隠蔽は考えていない。継承元のフィールドや var で宣言した変数も型が付かない(var は型名として var が入る)。影響調査の「当たりを付ける」用途には十分だが、漏れのない一覧が必要な場面では、PART 07 で紹介する型解決のできるツールと組み合わせてほしい。

依存グラフを Mermaid で描く

JSONL ができれば、図にするのは簡単だ。call レコードをクラス単位に集計し、Mermaid の flowchart を出力する。プロジェクト内で宣言されていない型(ここでは OrderRepository など)は破線にして区別する。

to_mermaid.py
"""deps.jsonl から クラス間の呼び出し関係を Mermaid の flowchart にする"""
import json
import sys
from collections import Counter

known = set()
edges = Counter()
with open(sys.argv[1], encoding="utf-8") as f:
    records = [json.loads(line) for line in f]

for r in records:
    if r["kind"] == "type":
        known.add(r["name"])
for r in records:
    if r["kind"] == "call" and r["object_type"]:
        src = r["caller"].split("#")[0]
        dst = r["object_type"].split("<")[0]       # List<Order> -> List
        if src != dst:
            edges[(src, dst)] += 1

print("flowchart LR")
for (src, dst), n in sorted(edges.items()):
    style = "" if dst in known else ":::external"
    print(f"    {src} -->|{n}| {dst}{style}")
print("    classDef external stroke-dasharray: 4 2")
PowerShell / bash
python to_mermaid.py deps.jsonl > deps.mmd
deps.mmd
flowchart LR
    OrderController -->|3| OrderRequest:::external
    OrderController -->|2| OrderService
    OrderService -->|3| Item:::external
    OrderService -->|1| MailSender:::external
    OrderService -->|1| Order:::external
    OrderService -->|2| OrderRepository:::external
    classDef external stroke-dasharray: 4 2

矢印のラベルは呼び出し回数だ。このテキストを Markdown の ```mermaid ブロックに貼れば、GitHub や VS Code のプレビューでそのまま図になる。Mermaid の書き方は当サイトの Markdown シリーズ PART 04 で、3D で俯瞰する方法は Jarviz による 3D 可視化 で扱っている。JSONL の項目を合わせれば、ここで作ったデータをそれらの入力にも使える。

JSONL を問い合わせる

図にするまでもない質問は、JSONL を直接調べるのが早い。たとえば「OrderService.placeOrder を呼んでいるメソッド」は次の1行でわかる。

Python
import json
calls = [json.loads(l) for l in open("deps.jsonl", encoding="utf-8")]
print({c["caller"] for c in calls
       if c["kind"] == "call" and c["object_type"] == "OrderService" and c["callee"] == "placeOrder"})
実行結果
{'OrderController#create'}

ほかにも、kind == "method" の annotations に PostMapping などがあるものを集めれば API の一覧になり、end - start の大きい順に並べれば長いメソッドの一覧になる。後者は次の PART 06 でチェッカーとして仕立てる。

✅ 次の記事では…

PART 06 では、空の catch・Exception の一括 catch・System.out・深い入れ子・長いメソッドなどを検出する簡易コードチェッカーを作り、CSV 出力と終了コードで CI に組み込めるようにする。

→ PART 06 — 実践:コード品質チェックへ