Jelly(JavaScript / TypeScript の静的コールグラフ解析ツール)

概要#

• 開発元は Aarhus 大学(Anders Møller ら)。ライセンスは BSD-3-Clause
• npm install -g @cs-au-dk/jelly で入る。Node.js 22 以上が必要
• 出力は -j cg.json(JSON)、-m cg.html(可視化 HTML)、--compare-callgraphs(動的コールグラフとの比較)
• リリースは 2023-02 の v0.5.0 から 2〜4 か月に 1 回。GitHub の open issue は 3 件で、実用規模のユーザー報告は少ない
• 関連論文: ACG(ICSE 2013)、TAPIR(OOPSLA 2020)、JAM(ISSTA 2021)、Approximate Interpretation(PLDI 2024)、Indirection-Bounding(ECOOP 2024)

セットアップ要件#

• README は NODE_OPTIONS=--max-old-space-size=8192 を例として示す。Linux では vm.max_map_count の引き上げ(sysctl -w vm.max_map_count=524288)も案内されており、依存関係ごと解析するとヒープを大量に消費する
• 入力はエントリーファイルかディレクトリ。tsconfig.json は要らない
• --ignore-dependencies を付けないと、エントリーから到達できる node_modules 内のファイルも解析する。依存込みで解析するならインストール済みの node_modules が実質必要
• 対象拡張子は .js / .es / .mjs / .cjs / .ts / .tsx と shebang 付きファイル。.d.ts と minify / bundle 済みファイルは除外(node_modules 内の minified は含む)
• --max-indirections / --timeout で途中終了し、部分結果(unsound(実際に起こりうる関係を解析結果が取りこぼしうる性質))を得られる
• モノレポ / workspace への言及は README にない。--include-packages / --exclude-packages でパッケージ単位の絞り込みはできる

出力形式(-j cg.json)#

src/typings/callgraph.ts の型定義に基づく構造。

1
entries   : [string]                    // エントリーファイル(basedir 相対)
2
files     : [string]                    // インデックスがノード ID
3
functions : { index → { file, start, end } }
4
calls     : { index → { file, start, end } }   // コールサイト
5
fun2fun   : [[callerFn, calleeFn]]
6
call2fun  : [[callSite, calleeFn]]

関数レベルの粒度で、コールサイトから関数へのエッジと関数から関数へのエッジを両方持つ。resolved / unresolved の区別や soundness のマーカーは型定義上存在しない。

jelly-server は stdin / stdout で Content-Length 区切りの JSON-RPC を話し、callgraph などのコマンドを受ける。

解析方式と TypeScript の扱い#

分析の核は flow-insensitive・context-insensitive な field-based points-to(変数や参照がどのオブジェクトを指しうるかを調べる解析) 解析。TypeScript ファイルは @babel/parser でパースし、型注釈を落として ECMAScript として処理する。TypeScript の型情報(型ガード、条件型、decorator)は解析に使われない。

つまり「型で解決できるディスパッチ」も points-to で処理する。ts-morph のように TypeChecker から解決する方式とは得意領域が異なる。前者はコールバックやイベント経由の暗黙エッジを追う設計で、後者は明示的な呼び出しを型から確実に解決する設計になる(比較は TypeScript コールグラフの静的抽出)。

精度の公表値#

completeness 38.8% という低さは、eval や動的プロパティアクセスなど ECMAScript の動的性質への対応限界を示す。

ライブラリとして組み込めるか#

package.json に exports も main もなく、bin に jelly と jelly-server があるだけ。import { analyze } from '@cs-au-dk/jelly' に相当する公開 API は存在しない。

組み込みの選択肢は 2 つ。

1. jelly -j cg.json を子プロセスとして起動し、JSON を読む
2. jelly-server を起動し、stdin / stdout の JSON-RPC で話す

どちらも利用者に --max-old-space-size 付きの実行環境を求めることになる。nuanced-dev/jellycg(Nuanced 社のフォーク)は npm 公開の自動化と関数位置情報のトラッキング API を足していたが、2025-10 を最終コミットとして 2026-03-05 にアーカイブされた。

公式に認めている限界#

• README が “intentionally not fully soundly” と明記。Node.js 標準ライブラリは unknown code として扱う
• 依存込みの解析は時間がかかる。--max-indirections / --timeout が回避策
• npm run pkg で作るバイナリは NodeProf 連携の動的コールグラフ構築に対応しない
• Node.js 20 以下では動かない

使いどころ#

• 暗黙エッジ(コールバック・イベント経由)まで含めた recall を重視する解析、研究用途、動的コールグラフとの比較 → Jelly
• 明示的な呼び出しを型から確実に解決し、ライブラリとして自分のツールに組み込む → ts-morph で自作

関連#

• TypeScript コールグラフの静的抽出(ts-morph と解決の難所)
• コールグラフの可視化(毛玉を避ける Focus+Context と描画ライブラリ)

更新履歴#

• 2026-06-20: 初版(ローカル調査ノート)
• 2026-10-17: Wiki へ移植、概念ページとして再構成