graphlint

English | 锟斤拷锟斤拷锟斤拷锟斤拷

Dead code detection for AI-generated codebases.

AI agents generate code rapidly, leaving behind dead and redundant code that pollutes the LLM's context window and dilutes attention. Graphlint analyzes your codebase's dependency graph to identify entry points and detect dead code 锟斤拷 components unreachable from any entry point 锟斤拷 so agents can self-clean and keep the codebase lean.

Supported Languages

Language	Status	Parser	Features
Python (.py)	Built-in	ast (stdlib)	Decorators, type annotations, dynamic imports, framework-aware entry detection
Rust (.rs)	Built-in (opt-in deps)	tree-sitter	Attribute macros, traits, pub visibility, macro_rules!
C# (.cs)	Built-in (opt-in deps)	tree-sitter	Partial classes, properties/indexers/events, attributes, .csproj awareness, test framework entries
C (.c .h)	Built-in (opt-in deps)	tree-sitter	struct/union/enum members, typedefs, macros, #include tracking, per-TU static linkage, library entry mode
TypeScript / JavaScript (.ts .tsx .js .jsx .mts .cts .mjs .cjs)	Built-in (opt-in deps)	tree-sitter	JSX/React components, Next.js pages, NestJS decorators, Jest/Vitest tests, import/export analysis

Install optional language support:

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 and tree-sitter-c
pip install graphlint[typescript]  # adds tree-sitter + tree-sitter-typescript + tree-sitter-javascript

Features

• Dead code detection 锟斤拷 finds components unreachable from any entry point via graph traversal
• Multi-language support 锟斤拷 Python, Rust, C#, C, TypeScript, and JavaScript backends via a language adapter abstraction; Python uses stdlib ast, the others use tree-sitter
• Language-specific awareness 锟斤拷 Python decorators, Rust attribute macros (#[tokio::main], #[test]), C# attributes ([Fact], [HttpGet]), C translation-unit scope (static internal linkage, per-TU header statics) and library entry mode, TS/JS JSX elements and ES module imports/exports, trait implementations, pub/public visibility, partial classes, and more
• AST/CST parsing 锟斤拷 extracts functions, methods, structs, enums, traits, impls, macros, classes, properties, indexers, events, variables, and fields; aware of type annotations, destructured variables, and generics
• Dependency graph 锟斤拷 builds directed edges: read, write, call, inherit, decorate
• Entry point detection 锟斤拷 37 built-in rules covering Python frameworks (FastAPI, Flask, Django, Click, Typer, Celery, pytest), Rust conventions (main, async runtimes, WASM, proc macros, FFI, tests, pub API), .NET conventions (console, xUnit, NUnit, MSTest, Web API, Minimal API, Generic Host, WinForms, WPF), C conventions (main/WinMain/wWinMain/DllMain/_tmain, test files, library mode via external-linkage symbols), and TS/JS conventions (main, module index, CLI/server listen, Next.js pages, NestJS decorators, React JSX, Jest/Vitest tests) plus custom rules
• Configurable entry templates 锟斤拷 add custom entry rules via ast_pattern prefixes including 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), and more
• --public-as-entry flag 锟斤拷 treat all public items (Rust pub, C# public, C external-linkage symbols) as entry points for library analysis
• Warning detection 锟斤拷 11 warning types including circular references, unused imports, write-only variables, and more
• Incremental updates 锟斤拷 after initial full scan, only changed files are re-indexed; delta-aware reachability analysis avoids full-graph recomputation; incompatible index schema versions are auto-detected and rebuilt
• Python API + CLI 锟斤拷 integrate into any Tool, CI pipeline, or let agents self-analyze and self-clean

Installation

pip install graphlint

Requirements: Python >= 3.9

For Rust support (.rs files), install the optional tree-sitter dependencies:

pip install graphlint[rust]

For C# support (.cs files), install the optional tree-sitter dependencies:

pip install graphlint[csharp]

For C support (.c / .h files), install the optional tree-sitter dependencies:

pip install graphlint[c]

For TypeScript/JavaScript support (.ts .tsx .js .jsx .mts .cts .mjs .cjs files), install the optional tree-sitter dependencies:

pip install graphlint[typescript]

Quick Start

Agent Integration

Graphlint installs its usage guidance into your AI coding tools at the global level:

# Install the graphlint skill (~/.agents/skills/graphlint/SKILL.md) 锟斤拷 default, recommended
graphlint install
graphlint install --targets all      # also ~/.claude/skills/graphlint/SKILL.md

# Install the DeepSeek Harness plugin (recommended in DSH 锟斤拷 tool-based integration)
graphlint install dsh --profile web

# Inject the prompt into agent config files (opencode, cursor, codex, cc)
graphlint install prompt

# Copy the prompt to clipboard for manual paste into your agent
graphlint prompt

# Remove installed skills / prompts
graphlint uninstall

All channels derive from one canonical skill document shipped in the package (graphlint/skill.md), so the skill file, the injected prompt and the DeepSeek Harness plugin's graphlint skill can never drift apart. For details, see Agent Integration. For tools you'd like native support for, feel free to submit an issue 锟斤拷 these requests are typically handled quickly.

DeepSeek Harness Plugin

A plugin bundle for the DeepSeek Harness plugin ecosystem ships in this repository under integrations/dsh:

• Tools 锟斤拷 graphlint_query (dependency-graph queries with structured results), graphlint_build (index build as a background job, polled with job_output), graphlint_config (show/get/set for .graphlint/config.json).
• Skill 锟斤拷 a graphlint skill teaches the agent when and how to use the tools.
• Safety 锟斤拷 tools default to the session working directory and hard-refuse any root outside it, so an accidental high-level scan cannot block a turn.

Install the bundle from npm:

dsh plugin --profile web add dsh-graphlint

Then restart dsh web. To link a local checkout instead (development):

# 1. Clone the repository and build the bundle (requires Node.js >= 20)
git clone https://github.com/AngelosZou/graphlint.git
cd graphlint/integrations/dsh
npm install
npm run build

# 2. Link the bundle into a profile (run from the repository root)
cd ..
dsh plugin --profile web add link:./integrations/dsh

# 3. Restart dsh web

CLI

# Find dead code in current directory
graphlint query --warn-types "dead_code"

# Full analysis with JSON output
graphlint query --json

# View a specific graph detail
graphlint query -g 1 --detail full

# Exit non-zero when dead code or circular refs found (for CI)
graphlint query --json --fail-on dead_code,circular_ref

# Treat all public items as entry points (library analysis mode)
graphlint query --public-as-entry

# Rebuild index
graphlint build --force

# Configure
graphlint config show
graphlint config set --key lang --value en

Exit Codes

Code	Meaning
0	Success 锟斤拷 no warnings matched --fail-on
1	Error 锟斤拷 invalid parameters, exception, or config error
2	Warnings found 锟斤拷 --fail-on matched specified warning types

Use --fail-on with a comma-separated list of warning types to make graphlint query return exit code 2 when matching warnings are found. This enables CI pipeline integration without blocking on non-critical warnings.

Graphlint is static-analysis based and cannot recognize certain Python dynamic references (e.g., getattr, importlib), which may produce unexpected exit codes. Only use --fail-on for CI blocking behavior when you're confident in your configuration. Agents are better suited for logic that requires contextual judgment. See Limitations for details.

Python API

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)

Warning Types

Warning	Description
unused_import	Imported module or name is never used
dynamic_import	Dynamic import via importlib or __import__
circular_ref	Circular dependency between functions/classes
syntax_error	File contains a syntax error
write_only	Variable is written but never read
deprecated_usage	Usage of a deprecated function/class
dead_code	Component unreachable from any entry point
type_mismatch	Suspicious type annotations
unresolved_ref	Reference to an undefined name
unused_variable	Variable is defined but never used
file_too_large	File exceeds the configured size limit

Development

# 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/

Configuration

Graphlint stores its configuration in .graphlint/config.json within the analyzed directory. Use graphlint config commands to manage settings, or edit the file directly.

See graphlint config show for the full default configuration.

Documentation

Full documentation is available in the docs/ directory:

• Getting Started
• Agent Integration
• Configuration Guide
• Entry Point Detection
• Warning Reference
• CLI Usage
• Architecture Overview
• Python API

Limitations

• Static analysis only 锟斤拷 graphlint performs static analysis and cannot detect runtime linkage such as getattr, importlib, or dynamic dispatch patterns, which may result in false positives. This primarily affects Python; Rust's static dispatch model produces fewer false positives. Mitigation: add custom entry rules matching your codebase's conventions. For example, graphlint's own codebase uses function_def:_detect_* and function_def:visit_* patterns to prevent functions discovered via getattr from being flagged as dead.
• Python dynamic imports 锟斤拷 due to Python's dynamic import mechanisms (importlib, getattr, metaclasses, etc.), the default entry templates may produce false positives in codebases that rely heavily on runtime dispatch. Users should tune the entry_rules configuration to match their project's conventions.
• Rust macro expansion 锟斤拷 tree-sitter parses unexpanded source; procedural macros and macro_rules! bodies appear as opaque token trees. Some macro-generated call paths may be missed. #[derive] attributes are partially recognized via implicit inherit edges.
• C# partial classes & reflection 锟斤拷 tree-sitter parses each .cs file independently; partial class fragments are merged into a single logical node via part_of edges, but members called only through reflection (Activator.CreateInstance, DI container registration) may be missed, similar to Python's dynamic import limitations.
• --public-as-entry scope 锟斤拷 this flag applies to languages with public visibility declarations (Rust pub, C# public). It has no effect on Python files. Toggling this flag triggers a full re-index. For long-term library analysis, prefer enabling the rust_pub_api entry rule via graphlint config to persist the setting.
• Large codebase build time 锟斤拷 on a large codebase with 700+ .py files, 1,000+ classes, and 14,000+ functions, a full rebuild takes approximately 200 seconds (actual performance depends on hardware). Small projects (~60 files) complete in ~1 second. This cost is one-time, after the initial full scan, subsequent queries use incremental updates.

License

MIT 锟斤拷 see LICENSE for details.

Links

• GitHub Repository
• Issue Tracker
• PyPI Package