CodeGraph

A 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.

Features

• Multi-language parsing – Python, JavaScript/TypeScript, Go, Java (extensible via tree-sitter)
• Entity extraction – Files, modules, classes, functions, methods
• Relationship inference – Contains, imports, calls, inherits
• Error mapping – Paste a stack trace or error message and instantly locate the offending entity
• Graph queries – Search by name, file, line number, or fuzzy text
• CLI interface – Fast, colorful terminal output via Rich
• JSON export – Save the full graph for external analysis or visualization

Installation

pip install -r requirements.txt

Dependencies: tree-sitter, tree-sitter-python, tree-sitter-javascript, tree-sitter-go, tree-sitter-java, networkx, rich, click, pydantic

Quick Start

1. Build the graph

python -m codegraph build /path/to/your/codebase -o graph.json

2. Search the graph

# Find any entity by name
python -m codegraph find DataProcessor

# Fuzzy search across names and paths
python -m codegraph search helper

# Show file outline
python -m codegraph outline src/core.py

3. Map an error

python -m codegraph map-error "NameError: name 'helper_c' is not defined" \
  --file src/core.py --line 16

Output:

Error Type: name_error
Message: NameError: name 'helper_c' is not defined
Mapped to: 🔩 method process in /app/src/core.py:15
Related entities:
  - 📄 file core.py (/app/src/core.py:1)
  - 🔧 function helper_a (/app/src/utils.py:4)
  - 🔧 function helper_b (/app/src/utils.py:8)
Suggested fix: Check spelling of 'process' or ensure the variable/function is defined before use.

Architecture

codegraph/
├── __init__.py        # Package init
├── models.py          # Pydantic models (Entity, Relationship, ErrorMapping)
├── parser.py          # Multi-language AST parser (tree-sitter)
├── graph_builder.py   # NetworkX graph construction + relationship extraction
├── query_engine.py    # Error mapping, search, navigation APIs
├── cli.py             # Click CLI with Rich output
└── __main__.py        # python -m codegraph entry point

Extending

Add a new language

1. Install the tree-sitter grammar: pip install tree-sitter-<lang>
2. Register it in parser.py (LANG_MAP)
3. Add handler methods: _handle_<lang>_<node_type>

Add a new relationship

1. Define it in models.RelationType
2. Extract it in graph_builder.RelationshipExtractor
3. Query it in query_engine.QueryEngine

Running Tests

python -m pytest tests/ -v

All 9 tests pass covering parser, graph builder, and query engine.

License

MIT