gotreesitter: 純Goのtree-sitterランタイム

純Goのtree-sitterランタイム

gotreesitterはtree-sitter解析ランタイムの純Go実装です。CGoを使わず、Cツールチェーンも不要なため、Goがサポートする任意のGOOS/GOARCHターゲット（wasip1を含む）にクロスコンパイルできます。パッケージはCランタイムと同じパーステーブル形式を読み込みます。ts2goが上流のparser.cファイルから文法テーブルを抽出し、バイナリblobに圧縮し、初回使用時にデシリアライズします。レジストリには206の文法が同梱されています。インストールは'go get github.com/odvcencio/gotreesitter'です。

CGoを排除する動機

READMEは、既存のGo向けtree-sitterバインディングはすべてCGoに依存しており、それによって3つの問題が生じると説明しています。クロスコンパイルにはターゲットごとにCクロスツールチェーンが必要です。例えば、LinuxからGOOS=wasip1、GOARCH=arm64をビルドする場合や、MSYS2/MinGWを持たないWindowsターゲットではリンクできません。CIイメージにはgccと文法のCソースが必要で、Cコンパイラを持たない下流ユーザーでは'go install'が失敗します。加えて、Goのレース検出器、カバレッジ計測、ファザーはCGo境界を越えて見ることができないため、CランタイムやFFIマーシャリングのバグは'go test -race'では見えません。gotreesitterはC依存を完全に排除し、パーサー、レキサー、クエリエンジン、インクリメンタルリパース、アリーナアロケーター、外部スキャナー、ツリーカーソルをすべてGoで実装しています。文法blobだけが入力です。

パース、部分木、インクリメンタルリパース

デフォルトのパースメソッドはtree-sitterの部分木動作を維持します。タイムアウト、キャンセルフラグ、トークンソースのEOF、またはパーサー安全制限がパースを途中で止めた場合、返されたツリーは停止理由を記録し、エラーはnilのままです。出力を失敗させたい場合は、ParseStrictなどの厳密なバリアントがErrParseStoppedEarlyを返します。インクリメンタルリパースはTree.EditとInputEditレコードを使い、ParseIncrementalは古いツリーのスパインを走査し、編集領域を特定し、変更されていない内容を参照で再利用します。nil-editの場合、単桁ナノ秒でゼロ割り当てを返します。READMEは、この再利用が絶対的なO(edit)保証ではないと述べています。長さやポイントが変わる編集では、後続ノード数に線形に増える兄弟オフセット維持が必要です。内部の非トップレベル部分木の再利用はまだリリースされていません。UTF-16入力はコードユニット座標でサポートされています。

クエリ、ハイライト、コード解析ヘルパー

クエリエンジンは完全なS式パターン言語をサポートしています。構造的量化子、選択、フィールド制約、否定フィールド、アンカー、およびすべての標準述語を含みます。tsqueryは.scmファイルから型安全なGoラッパーを生成します。ハイライターとタガーAPIは範囲とタグを生成します。ホットなインデックスパスのために、ExtractDefinitionSpans、ExtractCalls、ExtractHeritageのようなワンパス抽出器は、一般的なGo、JavaScript、TypeScript/TSX、Python、Starlark、Javaの定義と呼び出しをカバーします。EnclosingDefinitionはオフセットを含む定義を見つけます。READMEは、これらのヘルパーはサポートされていない言語や曖昧な形状を保守的にスキップすると述べています。

サポートされる言語と注入パース

レジストリには206の文法が同梱されており、すべてスモークサンプルでエラーのないパースツリーを生成します。各LangEntryにはQualityフィールドがあります。fullはすべてのスキャナーとレクサーコンポーネントが存在することを意味し、partialは外部スキャナーが欠落していること、noneはパースできないことを示します。119の文法には手書きのGo外部スキャナーがあり、7つには手書きのGoトークンソースがあります。注入パーサーは、HTML+JS+CSS、Markdown+コードフェンス、Vue/Svelteテンプレートのような多言語ドキュメントを処理し、静的および動的な言語検出、再帰的なネスト注入、子ツリー再利用を伴うインクリメンタルリパースをサポートします。

アーキテクチャ: パーサー、レクサー、スキャナー、メモリ

パーサーはテーブル駆動のLR(1)で、GLRフォールバックを備えています。(state, symbol)ペアが複数のアクションにマップされると、パーサーはスタックをフォークし、すべての代替を並行して探索します。レクサーには2つの経路があります。文法レクステーブルから生成されたDFAと、DFAでは不十分な言語のための手書きGoトークンソースです。119の外部スキャナーは上流Cスキャナーの手書きGo実装です。ノードはGC圧力を減らすためにスラブベースのアリーナから割り当てられます。クエリエンジンはS式パターンコンパイラで、述語評価とストリーミングカーソルを備えています。リライターはソースレベルの編集を収集し、原子的に適用します。文法ロードはts2goを使用してパーステーブルを抽出し、圧縮blobにシリアライズし、LRUキャッシュで遅延ロードします。

ビルド構成、テスト、既知の制限

プロジェクトは文法埋め込みのためのビルドタグを提供しています。デフォルト（すべて埋め込み）、grammar_set_core（厳選セット）、grammar_subset（言語ごとのタグ）、grammar_blobs_external（ランタイムにディレクトリからblobをロード）です。キャッシュチューニング環境変数が文書化されています。テストはDockerベースのパリティハーネスで行われます。READMEはOOM診断中にホスト側で多言語スイープを行わないよう警告しています。既知の制限には、Cに対するフルパーススループット（READMEはv0.40.0レシートの具体的な比率を記載: 幾何平均4.851050x C、中央値合計5.472406x C）と、入力複雑度に上限を課すGLR安全キャップが含まれます。現在のリリースはv0.49.0で、ロードマップは公開Parser.Parseを1.5x C以下にすることを目指していますが、それは将来の目標であり、現在の結果ではありません。

gotreesitterの使いどころは、Goプログラム内でtree-sitterの構文木を扱い、外部のNodeやPythonプロセスを増やしたくない場面です。READMEが示すParser、Language、Tree、Node、QueryなどのAPIを使い、入力ソースから構文木を作って必要なノードを走査します。対応文法は別パッケージとして取り込む設計で、文法の生成物とGo側のランタイムを同じ版で管理する必要があります。

導入時はgo.modの依存版を固定し、READMEのサンプルにあるparser初期化、SetLanguage、Parse、RootNodeの流れを小さな入力で確認します。tree-sitter本体のC実装や文法パッケージを含む場合は、CGO、ビルド環境、クロスコンパイルの扱いが実運用の境界になります。純Goを掲げる範囲、生成済み文法の配布方法、queryの互換性をリリースごとに確認できないなら、既存の公式バインディングから置き換える判断は急がない方がよいでしょう。

編集部の結論

Goの中でtree-sitterの構文木とQueryを扱い、外部ランタイムを避けたい開発者には適した方向です。文法生成物、CGO、クロスコンパイルの条件を管理できない環境では導入負担が増えます。ParseからRootNode走査までを固定した入力で確認し、使用する文法パッケージの版を揃えてください。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes