finderscope

finderscopev0.4.0MIT

Turn V8 CPU and heap profiles into short, ranked reports with runnable next commands for coding agents.

インストール

npm install finderscope

• GitHub のソースコード
• 使っているツール: archstrict, nukadoko, stryker-agent-reporter
• このツールを使っているツール: autospawn

finderscope は、V8 のプロファイル (.cpuprofile、.heapprofile、.heapsnapshot) を、コーディングエージェントが 1 回で読み切れる短い順位付きのレポートに変換します。 レポートの最後にある do: の行が、次に実行するコマンドを示します。 レポートの要約では、エージェントが編集できる関数を、その関数が引き起こしたコストの順に並べます。 各サンプルは、自分のコードの中で最も深い位置にある関数に割り当てられます。 そのため、依存パッケージの中で費やした時間は、それを呼び出した自分のコードのコストとして数えます。

特徴

• コマンドのプロファイリング。 finderscope run -- <command> はコマンドをプロファイリングし、プロファイルと子プロセスの出力を一時ディレクトリに残します。 レポートの全文は report.txt に、--json を付けると report.json に書き出します。
• 自分のコードを優先。 own は、エージェントが編集できる実際のソースを指します。 各行には、関数の自己時間と、パッケージなどほかの領域への呼び出しのうち大きいもの 3 つが並びます。 JavaScript のファイルを初めて読み込む import() や require() は、静的な import と同じくモジュールの読み込みとして数えます。 モジュールの読み込みが CPU プロファイルの半分以上を占めると、要約に note: が付きます。
• 掘り下げるためのコマンド。 top、callers、callees、lines は、レポートに表示されたとおりの関数のキーか、1 つの関数にだけ一致する名前を受け取ります。 検索に失敗すると、最も近いキーを使った、そのまま実行できるコマンドを 3 つまで表示します。
• 時間範囲。 timeline は CPU プロファイルを 20 個の等しい区間に分けます。 --from と --to を付けると、どのレポートも 1 つの時間範囲に絞り込めます。
• メモリ。 run --heap はヒープのプロファイルを記録し、run --heap-snapshot は heapUsed が最大値を更新するたびにスナップショットを書き出します。 retainers <snapshot> <constructor-or-#id> は、あるオブジェクトを保持しているものを示します。
• 比較と JSON。 finderscope diff <before> <after> は 2 つのプロファイルを比較します。 --json のレポートには、最上位に unit があり、CPU プロファイルなら "us"、ヒープのプロファイルなら "bytes" が入ります。

エージェントでの使い方

パッケージには、プロファイリングの短い手順を書いたスキルが含まれています。

1. finderscope run -- <command> を実行します。
2. 修正候補と、最後にある do: の行を読みます。
3. finderscope lines などの do: のコマンドを実行し、続けて callers や callees でコストの出どころをたどります。
4. 変更の後、finderscope diff で変更前と変更後のプロファイルを比較します。

do: のコマンドの引数はすべてシングルクォートで囲まれるので、パスに何が含まれていても sh -c でそのまま動きます。

はじめかた

npm install --save-dev finderscope
npx finderscope run -- node app.js