graphlint 0.1.0__tar.gz

graphlint-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-07-01
+
+### Added
+- Initial release
+- AST-based Python source code parsing (classes, functions, methods, variables, fields)
+- Dependency graph construction with 5 edge types (read, write, call, inherit, decorate)
+- 8 built-in entry point detection rules (main, FastAPI, Flask, Django, Click, Typer, Celery, pytest)
+- Custom entry point rules via AST pattern matching
+- 11 warning types (unused_import, dynamic_import, circular_ref, syntax_error, write_only, deprecated_usage, dead_code, type_mismatch, unresolved_ref, unused_variable, file_too_large)
+- Incremental indexing with SHA256-based change detection
+- Adaptive output volume strategy (full, index, truncated)
+- Internationalization (English and Simplified Chinese)
+- CLI interface (`graphlint query`, `graphlint build`, `graphlint config`)
+- Python API (`query()`, `build()`, `configure()`)
+- SQLite persistence with cross-platform file locking
+- Parallel file parsing via ProcessPoolExecutor
+- Configuration management with dot-notation key access
+- Comprehensive test suite (unit, integration, performance)

graphlint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to graphlint
+
+Thank you for your interest in contributing! This document outlines the process for contributing to graphlint.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork locally
+3. Create a virtual environment and install dev dependencies:
+   ```bash
+   python -m venv env
+   source env/bin/activate  # or env/Scripts/activate on Windows
+   pip install -e ".[dev]"
+   ```
+4. Create a branch for your changes
+
+## Development Workflow
+
+- Write code that follows [PEP 8](https://peps.python.org/pep-0008/) style
+- Add type annotations for all public functions and methods
+- Write tests for new functionality
+- Ensure all existing tests pass before submitting a PR
+
+## Running Checks
+
+```bash
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=graphlint
+
+# Type checking
+mypy graphlint/
+
+# Lint
+ruff check graphlint/ tests/
+```
+
+## Pull Request Process
+
+1. Update the README or documentation if your change affects the public API
+2. Add an entry to CHANGELOG.md under the "Unreleased" section
+3. Ensure all checks pass (tests, mypy, ruff)
+4. Submit your pull request with a clear description of the changes
+
+## Code Style
+
+- Use 4 spaces for indentation (no tabs)
+- Maximum line length: 120 characters
+- Use `from __future__ import annotations` for modern type hints
+- Prefer `Optional[X]` over `X | None` for Python 3.9 compatibility
+- Module-level docstrings should briefly describe the module's purpose
+- Public functions and classes should have docstrings
+
+## Questions?
+
+Open an issue on [GitHub](https://github.com/AngelosZou/graphlint/issues) if you have questions or need clarification.

graphlint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yutong Zou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graphlint-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include pyproject.toml
+include README.md
+include docs/zh/README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+
+recursive-include graphlint *.py
+recursive-include docs *.md
+recursive-include tests *.py
+
+prune tests/__pycache__
+prune .graphlint
+prune .pytest_cache

graphlint-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: graphlint
+Version: 0.1.0
+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: Repository, https://github.com/AngelosZou/graphlint
+Project-URL: Issues, https://github.com/AngelosZou/graphlint/issues
+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
+- **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/)
+
+## 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/)

graphlint-0.1.0/README.md

@@ -0,0 +1,152 @@
+# 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)](README.md)
+[![zh](https://img.shields.io/badge/lang-zh--CN-blue.svg)](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
+- **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](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/](docs/) directory:
+
+- [Getting Started](docs/en/guide/getting-started.md)
+- [Agent Integration](docs/en/guide/agent-integration.md)
+- [Configuration Guide](docs/en/guide/configuration.md)
+- [Entry Point Detection](docs/en/guide/entry-detection.md)
+- [Warning Reference](docs/en/guide/warnings.md)
+- [CLI Usage](docs/en/cli/usage.md)
+- [Architecture Overview](docs/en/architecture/overview.md)
+- [Python API](docs/en/api/)
+
+## License
+
+MIT — see [LICENSE](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/)

graphlint-0.1.0/README_PYPI.md

@@ -0,0 +1,152 @@
+# 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
+- **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/)
+
+## 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/)