Metadata-Version: 2.4
Name: graphlint
Version: 0.1.3
Summary: A static analysis tool for identifying dead code in a codebase. It provides Python API and CLI for use by agents.
Author-email: Yutong Zou <yutong.zou.24@alumni.ucl.ac.uk>
License-Expression: MIT
Project-URL: Homepage, https://github.com/AngelosZou/graphlint
Project-URL: Documentation, https://github.com/AngelosZou/graphlint#readme
Project-URL: Repository, https://github.com/AngelosZou/graphlint
Project-URL: Issues, https://github.com/AngelosZou/graphlint/issues
Project-URL: Changelog, https://github.com/AngelosZou/graphlint/blob/main/CHANGELOG.md
Keywords: graph,dependency-graph,code-analysis,dead-code,circular-dependency,import-checker,static-analysis,lint
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Dynamic: license-file

# graphlint

[![PyPI](https://img.shields.io/pypi/v/graphlint)](https://pypi.org/project/graphlint/)
[![Python](https://img.shields.io/pypi/pyversions/graphlint)](https://pypi.org/project/graphlint/)
[![License](https://img.shields.io/pypi/l/graphlint)](https://github.com/AngelosZou/graphlint/blob/main/LICENSE)

[![en](https://img.shields.io/badge/lang-en-red.svg)](https://github.com/AngelosZou/graphlint/blob/main/README.md)
[![zh](https://img.shields.io/badge/lang-zh--CN-blue.svg)](https://github.com/AngelosZou/graphlint/blob/main/docs/zh/README.md)

**Dead code detection for AI-generated Python 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 Python 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.

## Features

- **Dead code detection** — finds components unreachable from any entry point via graph traversal
- **AST parsing** — extracts classes, functions, methods, variables, and fields
- **Dependency graph** — builds directed edges: `read`, `write`, `call`, `inherit`, `decorate`
- **Entry point detection** — 10 built-in rules (main, FastAPI, Flask, Django, Click, Typer, Celery, pytest, plus package and test entries) and custom rules
- **Warning detection** — 11 warning types including circular references, unused imports, write-only variables, and more
- **Incremental indexing** — SHA256-based change detection parses only modified files, with mtime-based fast-path stamp for zero-cost no-op rebuilds
- **Python API + CLI** — integrate into any Tool, CI pipeline, or let agents self-analyze and self-clean
- **Zero runtime dependencies** — only requires the Python standard library

## Installation

```bash
pip install graphlint
```

**Requirements:** Python >= 3.9

## Quick Start

### Agent Integration

Graphlint provides a command to inject its usage prompt into your AI coding tools at the **global level**, so every project automatically has graphlint's guidance:

```bash
# Install graphlint prompt into agent tools (opencode, cursor, codex, cc)
graphlint install

# Remove graphlint prompt from agent tools
graphlint uninstall
```

Run `graphlint install` and select the tools you use — the prompt (usage scenarios, essential commands, and parameters) will be added to their global configuration. For details, see [Agent Integration](https://github.com/AngelosZou/graphlint/blob/main/docs/en/guide/agent-integration.md).

### CLI

```bash
# 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

# Rebuild index
graphlint build --force

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

### 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)
```

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

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

## 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/](https://github.com/AngelosZou/graphlint/tree/main/docs/) directory:

- [Getting Started](https://github.com/AngelosZou/graphlint/blob/main/docs/en/guide/getting-started.md)
- [Agent Integration](https://github.com/AngelosZou/graphlint/blob/main/docs/en/guide/agent-integration.md)
- [Configuration Guide](https://github.com/AngelosZou/graphlint/blob/main/docs/en/guide/configuration.md)
- [Entry Point Detection](https://github.com/AngelosZou/graphlint/blob/main/docs/en/guide/entry-detection.md)
- [Warning Reference](https://github.com/AngelosZou/graphlint/blob/main/docs/en/guide/warnings.md)
- [CLI Usage](https://github.com/AngelosZou/graphlint/blob/main/docs/en/cli/usage.md)
- [Architecture Overview](https://github.com/AngelosZou/graphlint/blob/main/docs/en/architecture/overview.md)
- [Python API](https://github.com/AngelosZou/graphlint/tree/main/docs/en/api/)

## Limitations

- **Static analysis only** — currently, graphlint performs static analysis and cannot detect runtime linkage such as `getattr`, `importlib.import_module()`, or other dynamic dispatch patterns, which may result in false positives.
- **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). This is not a concern for small projects — a codebase with 60 Python files completes in about 1 second.

## License

MIT — see [LICENSE](https://github.com/AngelosZou/graphlint/blob/main/LICENSE) for details.

## Links

- [GitHub Repository](https://github.com/AngelosZou/graphlint)
- [Issue Tracker](https://github.com/AngelosZou/graphlint/issues)
- [PyPI Package](https://pypi.org/project/graphlint/)
