niishantth/codegraph

1# CodeGraph2 3A knowledge-graph powered tool that turns your entire codebase into a queryable, navigable graph. It parses source files using tree-sitter, builds a directed graph of entities (files, classes, functions, methods) and relationships (contains, imports, calls, inherits), and lets you map errors directly to the exact file, function, or code block where they occurred.4 5## Features6 7- **Multi-language parsing** – Python, JavaScript/TypeScript, Go, Java (extensible via tree-sitter)8- **Entity extraction** – Files, modules, classes, functions, methods9- **Relationship inference** – Contains, imports, calls, inherits10- **Error mapping** – Paste a stack trace or error message and instantly locate the offending entity11- **Graph queries** – Search by name, file, line number, or fuzzy text12- **CLI interface** – Fast, colorful terminal output via Rich13- **JSON export** – Save the full graph for external analysis or visualization14 15## Installation16 17```bash18pip install -r requirements.txt19```20 21Dependencies: `tree-sitter`, `tree-sitter-python`, `tree-sitter-javascript`, `tree-sitter-go`, `tree-sitter-java`, `networkx`, `rich`, `click`, `pydantic`22 23## Quick Start24 25### 1. Build the graph26 27```bash28python -m codegraph build /path/to/your/codebase -o graph.json29```30 31### 2. Search the graph32 33```bash34# Find any entity by name35python -m codegraph find DataProcessor36 37# Fuzzy search across names and paths38python -m codegraph search helper39 40# Show file outline41python -m codegraph outline src/core.py42```43 44### 3. Map an error45 46```bash47python -m codegraph map-error "NameError: name 'helper_c' is not defined" \48  --file src/core.py --line 1649```50 51Output:52```53Error Type: name_error54Message: NameError: name 'helper_c' is not defined55Mapped to: 🔩 method process in /app/src/core.py:1556Related entities:57  - 📄 file core.py (/app/src/core.py:1)58  - 🔧 function helper_a (/app/src/utils.py:4)59  - 🔧 function helper_b (/app/src/utils.py:8)60Suggested fix: Check spelling of 'process' or ensure the variable/function is defined before use.61```62 63## Architecture64 65```66codegraph/67├── __init__.py        # Package init68├── models.py          # Pydantic models (Entity, Relationship, ErrorMapping)69├── parser.py          # Multi-language AST parser (tree-sitter)70├── graph_builder.py   # NetworkX graph construction + relationship extraction71├── query_engine.py    # Error mapping, search, navigation APIs72├── cli.py             # Click CLI with Rich output73└── __main__.py        # python -m codegraph entry point74```75 76## Extending77 78### Add a new language79 801. Install the tree-sitter grammar: `pip install tree-sitter-<lang>`812. Register it in `parser.py` (`LANG_MAP`)823. Add handler methods: `_handle_<lang>_<node_type>`83 84### Add a new relationship85 861. Define it in `models.RelationType`872. Extract it in `graph_builder.RelationshipExtractor`883. Query it in `query_engine.QueryEngine`89 90## Running Tests91 92```bash93python -m pytest tests/ -v94```95 96All 9 tests pass covering parser, graph builder, and query engine.97 98## License99 100MIT101