zatsu というツールを作りました。単一ファイルのコード概要を表示する CLI zat のフォークで、リポジトリ全体を対象にできるよう拡張したものです。リポジトリを渡すと、.gitignore を尊重したコンパクトなツリーに各ファイルの公開シンボルの概要をぶら下げて出力します。
作った理由
zat は tree-sitter でファイルの公開シンボルを抽出して概要表示してくれる良いツールですが、対象は単一ファイルです。初めてのリポジトリを開いたとき、まず知りたいのは「どこに何があって、どんな公開 API を持っているか」という全体像で、エディタでファイルを一つずつ開いて回るのは遠回りだし、tree はファイル名しか教えてくれません。そこで zat をフォークして、この概要表示をリポジトリ全体に広げました。
もう一つの動機はコーディングエージェントです。エージェントにリポジトリの全体像を渡すとき、実行のたびに揺れない安定した出力であってほしい。zatsu は決定論的な出力を方針にしていて、人間が雑に眺める用途とエージェントへのコンテキスト供給の両方に使えます。
できること
- ディレクトリモード: ツリー表示に、対応言語のファイルはシンボル概要(関数シグネチャ、構造体フィールド、enum バリアントなど)を行番号付きでぶら下げる
- ファイルモード: 単一ファイルの概要だけを出力
.gitignoreに対応したトラバーサル、--max-depth/--max-linesによる出力の制限
zatsu 自身のリポジトリに実行するとこうなります。
src/
├── lib.rs
│ ├── mod outline; // L1
│ ├── mod repository; // L2
│ └── fn lang_for_ext(ext: &str) -> Option<(Language, &'static str)> // L6-L70
├── outline.rs
│ ├── struct VisibleRange<'a> { // L12-L18
│ │ node: Node<'a>
│ │ start_byte: usize
│ │ ...
│ ├── fn write_outline(...) -> io::Result<()> // L41-L137
│ └── fn parse(source: &str, language: &Language) -> Option<Tree> // L150-L156
...技術構成
Rust 製で、解析は tree-sitter に任せています。言語ごとのシンボル抽出は .scm のクエリファイルで定義していて、現在 JavaScript / TypeScript / Rust / Python / Go / Java / C / C++ / C# / Swift / Kotlin / Haskell / Ruby / Markdown に対応しています。
tree-sitter の概要エンジンと言語ごとのクエリは上流の zat の成果で、zatsu が足したのは .gitignore 対応のトラバーサル、出力の制限、そして決定論的なリポジトリ全体の出力です。
試してみる
brew install shohei81/tap/zatsuCargo や Nix でも入ります。あとはリポジトリで実行するだけです。
zatsu .
zatsu --max-depth 2 --max-lines 100 .
zatsu src/lib.rs # ファイルモードソースは github.com/shohei81/zatsu にあります(GPL-3.0 ライセンス)。