README.md

# 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

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

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

### 2. Search the graph

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

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

```bash
python -m pytest tests/ -v
```

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

## License

MIT