Gossiphs

Gossiphs = Gossip Graphs

ヒント

AI 対応：あらゆる AI アシスタントでコードの関係性を分析するには、gossiphs skill を使用してください。

以下も利用できます：Python SDK と MCP Server

「セットアップ不要」で「圧倒的に高速」なコードファイル関係性分析ツールです。tree-sitter と git の履歴に基づいています。

概要

Gossiphs は、コミット履歴と、コードベース内の変数宣言および参照の関係性を分析し、コードファイルの関係図を作成できます。

また、各ファイルで宣言されている内容を開発者が検索できるため、コードベース全体を通じてその参照を自由に検索し、より複雑な分析を実行できます。

graph TD
    A[main.py] --- S1[func_main] --- B[module_a.py]
    A --- S2[Handler] --- C[module_b.py]
    B --- S3[func_util] --- D[utils.py]
    C --- S3[func_util] --- D
    A --- S4[func_init] --- E[module_c.py]
    E --- S5[process] --- F[module_d.py]
    E --- S6[Processor] --- H[module_e.py]
    H --- S7[transform] --- I[module_f.py]
    I --- S3[func_util] --- D

対応言語

コストを抑えられる Tree-Sitter Query に基づいて、対応言語を拡大しています。ご興味があれば、貢献のセクションをご覧ください。

言語	状態
Rust	✅
Python	✅
TypeScript	✅
JavaScript	✅
Golang	✅
Java	✅
Kotlin	✅
Swift	✅
C#	✅

ルールファイルはこちらで確認できます。

使い方

Python

pip install gossiphs

30 行以内で networkx を使ってコードベースを分析できます。

import networkx as nx
from gossiphs import GraphConfig, create_graph, Graph

config = GraphConfig()
config.project_path = "../.."
graph: Graph = create_graph(config)

nx_graph = nx.DiGraph()

for each_file in graph.files():
    nx_graph.add_node(each_file, metadata=graph.file_metadata(each_file))

    related_files = graph.related_files(each_file)
    for each_related_file in related_files:
        related_symbols = set(each_symbol.symbol.name for each_symbol in each_related_file.related_symbols)

        nx_graph.add_edge(
            each_file,
            each_related_file.name,
            related_symbols=list(related_symbols)
        )

print(f"NetworkX graph created with {nx_graph.number_of_nodes()} nodes and {nx_graph.number_of_edges()} edges.")

for src, dest, data in nx_graph.edges(data=True):
    print(f"{src} -> {dest}, related symbols: {data['related_symbols']}")

出力：

NetworkX graph created with 13 nodes and 27 edges.
src/server.rs -> src/main.rs, related symbols: ['server_main']
src/main.rs -> src/graph.rs, related symbols: ['default']
src/main.rs -> examples/mini.rs, related symbols: ['default']
src/main.rs -> src/server.rs, related symbols: ['main']
src/symbol.rs -> src/graph.rs, related symbols: ['link_file_to_symbol', 'list_references', 'list_references_by_definition', 'id', 'enhance_symbol_to_symbol', 'add_file', 'add_symbol', 'list_definitions', 'list_symbols', 'new', 'link_symbol_to_symbol', 'get_symbol']
...

その他の例はこちらで確認できます。

その他

CLI と追加の使用方法も用意しており、CSV ファイルを直接エクスポートしたり、HTTP サービスを起動したりできます。

使用方法のページをご覧ください。

目標と動機

ヒント

次の特徴を備えたファイル関係性インデックスを作成します。

• 低コスト
• 許容できる精度
• ほぼあらゆるコードリポジトリで使える高い汎用性

コードナビゲーションは興味深い分野であり、次のようなさまざまな領域で重要な役割を果たします。

• IDE での開発プロセスにおけるコンテキストの提示。
• ウェブサイトでのコード閲覧の利便性向上。
• 継続的インテグレーション（CI）システムにおけるコード変更の影響分析。
• …

これまで、LSP/LSIF 技術や Github の Stack-Graphs のような手法を影響分析に適用しようと試み、さまざまな課題に直面してきました。私たちのニーズには Stack-Graphs に近い手法が最も期待に合っています。しかし、課題は明らかです。言語ごとに高度に特化したルールを作成する必要があり、私たちにとっては大きな投資となります。これほど高精度なデータは必要としていないためです。

現在 stack-graphs が直面している課題に対して、一定のトレードオフを行い、期待する目標をある程度達成することを目指しています。

• リポジトリ固有の設定が不要：追加設定なしで、ほとんどの言語やリポジトリに適用できます。
• 拡張コストが低い：言語のルール追加にかかるコストを抑えられます。
• 許容できる精度：ある程度の精度を犠牲にしていますが、それでも許容できる水準を維持したいと考えています。

仕組み

Gossiphs は、定義と参照のシンボルを相互に結び付けるグラフを構築します。

1. インポートとエクスポートの抽出：各ファイルのインポートとエクスポートを特定します。
2. ノードの接続：定義ノードと参照ノードの候補間の接続を確立します。
3. コミット履歴によるエッジの精緻化：コミット履歴を利用して、ノード間の関係を精緻化します。

stack-graphs とは異なり、非常に複雑なスコープ解析を省略し、代わりにコミット履歴を使ってエッジを精緻化する方法を採用しました。 このアプローチにより、ルール記述の複雑さを大幅に軽減できます。各ファイルでどの種類のシンボルをエクスポートまたはインポートするかをルールで指定するだけです。

精度とのトレードオフは確かにありますが、利点は明らかです。

1. 精度への影響は最小限：実際のシナリオでは、精度の低下は想像するほど大きくありません。
2. コミット履歴の関連性：コミット履歴を使ってコードの各部分の影響を反映する方法は、私たちの目的によく合っています。
3. 言語サポート：大多数のプログラミング言語を簡単にサポートでき、さまざまな種類のリポジトリにおける解析ニーズを満たせます。

精度

静的解析には、動的バインディングなどの限界があります。 そのため、LSP が提供する精度には及ばない可能性が高いですが、主な用途においては十分な精度を提供できます。

精度を示すために使用している方法は、結果を LSP/LSIF の結果と比較することです。静的推論で、LSP のようにすべての参照関係を取得するのはほぼ不可能であることは認めざるを得ません。

さらに、独自のニーズに合わせて、tfidf などの別の方法を組み合わせ、より複雑な要件を満たすよう結果を処理できます。

Repo	Gossiphs による LSP エッジのカバー率
https://github.com/go-gorm/gorm	442/499 = 88.5 %
https://github.com/gin-gonic/gin	238/252 = 94.4%

貢献

このプロジェクトはまだ非常に初期の実験段階にあります。興味がある方は、issue を通じてご意見をお寄せください。短期的には、より多くの言語をより適切にサポートすることを目指しています。

必要な作業は次のとおりです。

1. src/rule.rs のルールを編集します
2. src/extractor.rs でテストします
3. src/graph.rs で自分のリポジトリを使って試します

Tree-sitter Playground は便利なツールです。

ライセンス

Apache 2.0