Gossiphs

Gossiphs = Gossip Graphs

提示

面向 AI：使用 gossiphs skill，在任何 AI 助手中分析代码关系。

另有：Python SDK 和 MCP 服务

“零配置”且“快如闪电”的代码文件关系分析。基于 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