# Magellan
A deterministic codebase mapping tool. Watches source files, extracts AST-level facts, and builds a searchable graph database of symbols and references.
## What Magellan Does
- Watches directories for file changes (Create/Modify/Delete)
- Extracts AST-level facts: functions, classes, methods, enums, modules
- Tracks symbol references: function calls and type references
- Persists everything to a sqlitegraph database
- Handles errors gracefully - keeps running even when files are unreadable
- Shuts down cleanly on SIGINT/SIGTERM
## What Magellan Does NOT Do
- No semantic analysis or type checking
- No LSP server or language features
- No async runtimes or background thread pools
- No config files
- No web APIs or network services
- No automatic database cleanup
## Installation
```bash
git clone https://github.com/feanor/magellan
cd magellan
cargo build --release
# Binary will be at target/release/magellan
```
### Requirements
- Rust 1.70+
- Linux/macOS (signal handling uses Unix signals)
- SQLite 3 (via sqlitegraph dependency)
## Quick Start
```bash
# Start watching a project with initial scan
magellan watch --root /path/to/project --db /path/to/magellan.db --scan-initial
# Check status
magellan status --db /path/to/magellan.db
# List all indexed files
magellan files --db /path/to/magellan.db
# Query symbols in a file
magellan query --db /path/to/magellan.db --file /path/to/file.rs
# Find a symbol by name
magellan find --db /path/to/magellan.db --name main
# Show call references
magellan refs --db /path/to/magellan.db --name main --path /path/to/file.rs --direction out
# Export to JSON
magellan export --db /path/to/magellan.db > codegraph.json
```
## Commands
### watch
```bash
magellan watch --root <DIR> --db <FILE> [--debounce-ms <N>] [--scan-initial]
```
Watch a directory for source file changes and index them into the database.
| `--root <DIR>` | Directory to watch recursively (required) |
| `--db <FILE>` | Path to sqlitegraph database (required) |
| `--debounce-ms <N>` | Debounce delay in milliseconds (default: 500) |
| `--scan-initial` | Scan directory for source files on startup |
### status
```bash
magellan status --db <FILE>
```
Show database statistics.
```
$ magellan status --db ./magellan.db
files: 30
symbols: 349
references: 262
```
### files
```bash
magellan files --db <FILE>
```
List all indexed files.
```
$ magellan files --db ./magellan.db
30 indexed files:
/path/to/src/main.rs
/path/to/src/lib.rs
...
```
### query
```bash
magellan query --db <FILE> --file <PATH> [--kind <KIND>]
```
List symbols in a file, optionally filtered by kind.
| `--db <FILE>` | Path to database (required) |
| `--file <PATH>` | File path to query (required) |
| `--kind <KIND>` | Filter by symbol kind (optional) |
Valid kinds: Function, Method, Class, Interface, Enum, Module, Union, Namespace, TypeAlias
```
$ magellan query --db ./magellan.db --file src/main.rs --kind Function
/path/to/src/main.rs:
Line 13: Function print_usage
Line 64: Function parse_args
```
### find
```bash
magellan find --db <FILE> --name <NAME> [--path <PATH>]
```
Find a symbol by name.
| `--db <FILE>` | Path to database (required) |
| `--name <NAME>` | Symbol name to find (required) |
| `--path <PATH>` | Limit search to specific file (optional) |
```
$ magellan find --db ./magellan.db --name main
Found "main":
File: /path/to/src/main.rs
Kind: Function
Location: Line 229, Column 0
```
### refs
```bash
magellan refs --db <FILE> --name <NAME> --path <PATH> [--direction <in|out>]
```
Show incoming or outgoing calls for a symbol.
| `--db <FILE>` | Path to database (required) |
| `--name <NAME>` | Symbol name (required) |
| `--path <PATH>` | File path containing the symbol (required) |
| `--direction <in|out>` | Show incoming (in) or outgoing (out) calls (default: in) |
```
$ magellan refs --db ./magellan.db --name parse_args --path src/main.rs --direction in
Calls TO "parse_args":
From: main (Function) at /path/to/src/main.rs:237
```
### verify
```bash
magellan verify --root <DIR> --db <FILE>
```
Compare database state vs filesystem and report differences.
Exit codes: 0 = up to date, 1 = issues found
### export
```bash
magellan export --db <FILE>
```
Export all graph data to JSON format.
## Supported Languages
| Rust | .rs | tree-sitter-rust |
| C | .c, .h | tree-sitter-c |
| C++ | .cpp, .cc, .cxx, .hpp, .h | tree-sitter-cpp |
| Java | .java | tree-sitter-java |
| JavaScript | .js, .mjs | tree-sitter-javascript |
| TypeScript | .ts, .tsx | tree-sitter-typescript |
| Python | .py | tree-sitter-python |
## Database Schema
**Nodes:**
- `File` - path, hash, timestamps
- `Symbol` - name, kind, byte spans, line/column
- `Reference` - file, referenced symbol, location
- `Call` - file, caller, callee, location
**Edges:**
- `DEFINES` - File -> Symbol
- `REFERENCES` - Reference -> Symbol
- `CALLS` - Symbol -> Symbol
**Symbol Kinds:**
Function, Method, Class, Interface, Enum, Module, Union, Namespace, TypeAlias, Unknown
## Error Handling
Magellan continues processing even when individual files fail:
- Permission errors are logged and skipped
- Files with invalid syntax are skipped
- Database write errors cause exit (requires manual intervention)
## Architecture
```
src/
├── main.rs # CLI entry point
├── lib.rs # Public API
├── watcher.rs # Filesystem watcher
├── indexer.rs # Event coordination
├── ingest/
│ ├── mod.rs # Parser dispatcher
│ ├── detect.rs # Language detection
│ ├── rust.rs # Rust parser
│ ├── c.rs # C parser
│ ├── cpp.rs # C++ parser
│ ├── java.rs # Java parser
│ ├── javascript.rs # JavaScript parser
│ ├── typescript.rs # TypeScript parser
│ └── python.rs # Python parser
├── query_cmd.rs # Query command
├── find_cmd.rs # Find command
├── refs_cmd.rs # Refs command
├── verify_cmd.rs # Verify CLI handler
├── watch_cmd.rs # Watch CLI handler
└── graph/
├── mod.rs # CodeGraph API
├── schema.rs # Node/edge types
├── files.rs # File operations
├── symbols.rs # Symbol operations
├── references.rs # Reference operations
├── calls.rs # Call graph operations
└── ...
```
## Testing
```bash
cargo test
```
Test coverage: 172+ tests across 25+ test suites. All tests pass in <15 seconds.
## Current Status
**Version:** 0.2.0
**Status:** Stable
**Known Limitations:**
- Name-based reference matching (has false positives)
- No cross-crate/cross-file resolution
- No incremental parsing
- Single-threaded event processing
## License
GPL-3.0-or-later
## Dependencies
- notify - Filesystem watching
- tree-sitter - AST parsing
- sqlitegraph - Graph persistence
- signal-hook - Signal handling
- walkdir - Directory scanning