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

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

# 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

magellan watch --root <DIR> --db <FILE> [--debounce-ms <N>] [--scan-initial]

Watch a directory for source file changes and index them into the database.

status

magellan status --db <FILE>

Show database statistics.

$ magellan status --db ./magellan.db
files: 30
symbols: 349
references: 262

files

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

magellan query --db <FILE> --file <PATH> [--kind <KIND>]

List symbols in a file, optionally filtered by kind.

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

magellan find --db <FILE> --name <NAME> [--path <PATH>]

Find a symbol by name.

$ magellan find --db ./magellan.db --name main
Found "main":
  File:     /path/to/src/main.rs
  Kind:     Function
  Location: Line 229, Column 0

refs

magellan refs --db <FILE> --name <NAME> --path <PATH> [--direction <in|out>]

Show incoming or outgoing calls for a symbol.

$ 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

magellan verify --root <DIR> --db <FILE>

Compare database state vs filesystem and report differences.

Exit codes: 0 = up to date, 1 = issues found

export

magellan export --db <FILE>

Export all graph data to JSON format.

Supported Languages

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

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