AngelosZou/graphlint

graphlint

PyPI
Python
License

面向 AI 生成代码库的死代码检测。

AI 智能体会快速生成代码，留下死代码和冗余代码，污染 LLM 的上下文窗口并稀释注意力。Graphlint 分析代码库的依赖图，识别入口点并检测死代码——即从任何入口点都无法到达的组件——以便智能体能够自我清理并保持代码库精简。

支持的语言

| 语言 | 状态 | 解析器 | 特性 |
|----------|--------|--------|----------|
| Python（.py） | 内置 | ast（标准库） | 装饰器、类型注解、动态导入、框架感知的入口检测 |
| Rust（.rs） | 内置（可选依赖） | tree-sitter | 属性宏、trait、pub 可见性、macro_rules! |
| C#（.cs） | 内置（可选依赖） | tree-sitter | 分部类、属性/索引器/事件、特性、.csproj 感知、测试框架入口 |
| C / C++（.c .h .cpp .cc .cxx .hpp .hh .hxx） | 内置（可选依赖） | tree-sitter | struct/union/enum 成员、typedef、宏、#include 跟踪、按 TU 的 static 链接、C 库入口模式、C++ 类/命名空间/模板、跨 TU 成员调用解析 |
| TypeScript / JavaScript（.ts .tsx .js .jsx .mts .cts .mjs .cjs） | 内置（可选依赖） | tree-sitter | JSX/React 组件、Next.js 页面、NestJS 装饰器、Jest/Vitest 测试、导入/导出分析 |

安装可选语言支持：

pip install graphlint[rust]        # adds tree-sitter and tree-sitter-rust
pip install graphlint[csharp]      # adds tree-sitter and tree-sitter-c-sharp
pip install graphlint[c]           # adds tree-sitter + tree-sitter-c + tree-sitter-cpp (C/C++)
pip install graphlint[typescript]  # adds tree-sitter + tree-sitter-typescript + tree-sitter-javascript

C/C++ 由单一统一的 C/C++ 分析器进行分析，该分析器负责 .c .h .cpp
.cc .cxx .hpp .hh .hxx。它对 C 文件使用 tree-sitter-c，对 C++ 文件使用 tree-sitter-cpp，
并根据包含该 .h 的翻译单元（TU）的语言来路由 .h
—— 与 C/C++ 编译器的做法完全一致。额外的一个 graphlint[c] 会同时安装
这两个语法。

特性

- 死代码检测 —— 通过图遍历找出从任何入口点都无法到达的组件
- 多语言支持 —— 通过语言适配器抽象支持 Python、Rust、C#、C/C++（统一）、TypeScript 和 JavaScript 后端；Python 使用标准库 ast，其他使用 tree-sitter
- 语言特定感知 — Python 装饰器、Rust 属性宏（#[tokio::main]、#[test]）、C# 特性（[Fact]、[HttpGet]）、C 翻译单元作用域（static 内部链接、每个 TU 头文件中的 static）和库入口模式、C++ 类/命名空间/模板、enum class 成员以及跨 TU 成员调用解析、TS/JS JSX 元素和 ES 模块导入/导出、trait 实现、pub/public 可见性、分部类等
- AST/CST 解析 — 提取函数、方法、结构体、枚举、trait、impl、宏、类、属性、索引器、事件、变量和字段；感知类型注解、解构变量和泛型
- 依赖图 — 构建有向边：read、write、call、inherit、decorate
- 入口点检测 — 内置规则覆盖 Python 框架（FastAPI、Flask、Django、Click、Typer、Celery、pytest）、Rust 约定（main、异步运行时、WASM、过程宏、FFI、测试、pub API）、.NET 约定（控制台、xUnit、NUnit、MSTest、Web API、Minimal API、Generic Host、WinForms、WPF）、C/C++ 约定（C 的 main/WinMain/wWinMain/DllMain/_tmain 和 C++ 的自由 main、class_definition: 模式、按约定的 test_file，以及通过外部链接符号的 C 库模式）和 TS/JS 约定（main、模块索引、CLI/服务器监听、Next.js 页面、NestJS 装饰器、React JSX、Jest/Vitest 测试）以及自定义规则
- 可配置入口模板 — 通过 ast_pattern 前缀添加自定义入口规则，包括 function_call:、function_def:、decorator:、class_definition:（C#）、file_match:、file_is_program（C#）、visibility:pub（Rust）、visibility:public（C#）、trait_impl:（Rust）、macro_def:（Rust）、jsx_element:（TypeScript）、export:（TypeScript）等
- --public-as-entry 标志 — 将所有公共项（Rust pub、C# public、C 外部链接符号）视为入口点以进行库分析
- 警告检测 — 11 种警告类型，包括循环引用、未使用的导入、只写变量等
- 增量更新 — 初始全量扫描后，仅重新索引已更改的文件；增量感知的可达性分析避免全图重新计算；不兼容的索引模式版本会被自动检测并重建
- Python API + CLI — 集成到任何 Tool、CI 流水线中，或让代理自我分析和自我清理

安装

pip install graphlint

要求： Python >= 3.9

对于 Rust 支持（.rs 文件），安装可选的 tree-sitter 依赖：

pip install graphlint[rust]

对于 C# 支持（.cs 文件），安装可选的 tree-sitter 依赖：

pip install graphlint[csharp]

对于 C/C++ 支持（.c .h .cpp .cc .cxx .hpp .hh .hxx 文件），安装可选的 tree-sitter 依赖（一个额外项同时覆盖两种语法）：

pip install graphlint[c]   # adds tree-sitter + tree-sitter-c + tree-sitter-cpp (C/C++)
对于 TypeScript/JavaScript 支持（.ts .tsx .js .jsx .mts .cts .mjs .cjs 文件），请安装可选的 tree-sitter 依赖：

pip install graphlint[typescript]

快速开始

智能体集成

Graphlint 会在全局级别将其使用指南安装到你的 AI 编码工具中：

安装 graphlint 技能（~/.agents/skills/graphlint/SKILL.md）——默认，推荐
graphlint install
graphlint install --targets all      # 同时安装到 ~/.claude/skills/graphlint/SKILL.md

安装 DeepSeek Harness 插件（在 DSH 中推荐——基于工具的集成）
graphlint install dsh --profile web

将提示词注入到智能体配置文件中（opencode、cursor、codex、cc）
graphlint install prompt

将提示词复制到剪贴板，以便手动粘贴到你的智能体中
graphlint prompt

移除已安装的技能 / 提示词
graphlint uninstall

所有渠道都源自包中随附的同一份规范技能文档（graphlint/skill.md），因此技能文件、注入的提示词以及 DeepSeek Harness 插件的 graphlint 技能永远不会出现偏差。有关详细信息，请参阅 智能体集成。如果你希望某些工具获得原生支持，欢迎提交 issue——这些请求通常会很快得到处理。

DeepSeek Harness 插件

本仓库的 integrations/dsh 下随附了一个用于 DeepSeek Harness 插件生态系统的插件包：

- 工具 —— graphlint_query（带结构化结果的依赖图查询）、graphlint_build（作为后台任务构建索引，通过 job_output 轮询）、graphlint_config（对 .graphlint/config.json 执行 show/get/set）。
- 技能 —— 一个 graphlint 技能，教会智能体何时以及如何使用这些工具。
- 安全性 —— 工具默认以会话工作目录为根，并硬性拒绝该目录之外的任何根路径，因此意外的高层级扫描不会阻塞一轮对话。

从 npm 安装该插件包：

dsh plugin --profile web add dsh-graphlint

然后重启 dsh web。若要改为链接本地检出（用于开发）：

1. 克隆仓库并构建插件包（需要 Node.js >= 20）
git clone https://github.com/AngelosZou/graphlint.git
cd graphlint/integrations/dsh
npm install
npm run build

2. 将插件包链接到某个 profile 中（从仓库根目录运行）
cd ..
dsh plugin --profile web add link:./integrations/dsh

3. 重启 dsh web

CLI

查找当前目录中的死代码
graphlint query --warn-types "dead_code"

完整分析并输出 JSON
graphlint query --json

查看特定图的详细信息
graphlint query -g 1 --detail full

当发现死代码或循环引用时以非零状态退出（用于 CI）
graphlint query --json --fail-on dead_code,circular_ref

将所有公共项视为入口点（库分析模式）
graphlint query --public-as-entry

重建索引
graphlint build --force
配置
graphlint config show
graphlint config set --key lang --value en

退出码

| 代码 | 含义 |
|------|---------|
| 0 | 成功 — 没有警告匹配 --fail-on |
| 1 | 错误 — 参数无效、异常或配置错误 |
| 2 | 发现警告 — --fail-on 匹配到指定的警告类型 |

将 --fail-on 与以逗号分隔的警告类型列表一起使用，可使 graphlint query 在发现匹配的警告时返回退出码 2。这样就能集成到 CI 流水线中，而不会因非关键警告而阻塞。

Graphlint 基于静态分析，无法识别某些 Python 动态引用（例如 getattr、importlib），这可能会产生意外的退出码。只有在您对自己的配置有信心时，才使用 --fail-on 来实现 CI 阻塞行为。对于需要上下文判断的逻辑，智能体（Agent）更为合适。详情请参阅局限性。

Python API
python
from graphlint.api import query

Find dead code components
result = query(warn_types="dead_code", json_output=True)

Full dependency graph analysis
result = query(include_tests=True, json_output=True)

警告类型

| 警告 | 描述 |
|---------|-------------|
| unused_import | 导入的模块或名称从未被使用 |
| dynamic_import | 通过 importlib 或 __import__ 进行的动态导入 |
| circular_ref | 函数/类之间的循环依赖 |
| syntax_error | 文件包含语法错误 |
| write_only | 变量被写入但从未被读取 |
| deprecated_usage | 使用了已弃用的函数/类 |
| dead_code | 组件无法从任何入口点到达 |
| type_mismatch | 可疑的类型注解 |
| unresolved_ref | 对未定义名称的引用 |
| unused_variable | 变量被定义但从未被使用 |
| file_too_large | 文件超过配置的大小限制 |

开发
bash
Clone the repository
git clone https://github.com/AngelosZou/graphlint.git
cd graphlint

Create a virtual environment
python -m venv env
env/Scripts/activate  # Windows
source env/bin/activate  # Unix

Install dev dependencies
pip install -e ".[dev]"

Run tests
pytest

Run with coverage
pytest --cov=graphlint

Run type checking
mypy graphlint/

Run linting
ruff check graphlint/ tests/

配置

Graphlint 将其配置存储在被分析目录中的 .graphlint/config.json 内。使用 graphlint config 命令来管理设置，或直接编辑该文件。

运行 graphlint config show 可查看完整的默认配置。

文档

完整文档可在 docs/ 目录中找到：

- 入门指南
- 智能体集成
- 配置指南
- 入口点检测
- 警告参考
- CLI 用法
- 架构概览
- Python API

局限性

- 仅限静态分析 —— graphlint 执行静态分析，无法检测诸如 getattr、importlib 或动态分派模式之类的运行时链接，这可能导致误报。这主要影响 Python；Rust 的静态分派模型产生的误报较少。缓解措施： 添加与你的代码库约定相匹配的自定义入口规则。例如，graphlint 自身的代码库使用 function_def:_detect_ 和 function_def:visit_ 模式，以防止通过 getattr 发现的函数被标记为死代码。
- Python 动态导入 —— 由于 Python 的动态导入机制（importlib、getattr、元类等），默认入口模板在严重依赖运行时分派的代码库中可能产生误报。用户应调整 entry_rules 配置以匹配其项目的约定。
- Rust 宏展开 —— tree-sitter 解析未展开的源代码；过程宏和 macro_rules! 主体以不透明的 token 树形式出现。某些由宏生成的调用路径可能会被遗漏。#[derive] 属性通过隐式的 inherit 边被部分识别。
- C# 分部类与反射 —— tree-sitter 独立解析每个 .cs 文件；分部类片段通过 part_of 边合并为单个逻辑节点，但仅通过反射（Activator.CreateInstance、DI 容器注册）调用的成员可能会被遗漏，这与 Python 的动态导入局限性类似。
- C/C++ 静态分析限制 —— 成员调用跨翻译单元进行类型感知解析（通过项目范围的类→方法索引），但没有虚函数/重载/动态分派：通过 Base* 指针进行的调用会静态解析为基类的方法，因此仅通过该方式到达的派生类重写可能被报告为死代码。预处理器被视为纯 AST（#if 从不求值，宏不展开）；函数指针间接调用目标不被追踪；头文件中的 static 符号是每个翻译单元独立的。纯虚（= 0）接口方法免于死代码检测（由虚表分派）。C 函数参数不被建模为节点，因此与调用方局部变量同名的参数可能按扁平名称解析。
- --public-as-entry 作用范围 —— 此标志适用于具有 public 可见性声明的语言（Rust pub、C# public）。它对 Python 文件没有影响。切换此标志会触发完整重新索引。对于长期库分析，建议通过 graphlint config 启用 rust_pub_api 入口规则以持久化该设置。
- 大型代码库构建时间 —— 在拥有 700+ 个 .py 文件、1,000+ 个类和 14,000+ 个函数的大型代码库上，完整重建大约需要 200 秒（实际性能取决于硬件）。小型项目（约 60 个文件）约 1 秒完成。此成本是一次性的，在初始完整扫描之后，后续查询使用增量更新。

许可证
MIT — 详情请参阅 LICENSE。

链接

- GitHub 仓库
- 问题追踪器
- PyPI 包