Mirage

Path-Aware Code Intelligence Engine for Rust

"An agent may only speak if it can reference a graph artifact."

⚠️ Requires Magellan

Mirage requires Magellan to function.

Magellan provides the AST-based control flow graph (CFG) data that Mirage analyzes. You must run magellan watch on your codebase before using Mirage.

# Install Magellan first
cargo install magellan

# Watch your project (builds CFG)
magellan watch --root ./src --db .codemcp/codegraph.db

# Now Mirage can analyze
mirage status

The Code Intelligence Toolset

Mirage is part of a coordinated toolset built on sqlitegraph. All tools share a common SQLite graph database and are designed to work together for AI-assisted code understanding.

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Magellan   │ ───► │  llmgrep    │ ───► │   Mirage    │
│(Symbols &   │      │ (Semantic   │      │(CFG & Paths)│
│  Call Graph)│      │  Search)    │      │             │
└─────────────┘      └─────────────┘      └─────────────┘
       │                    │                     │
       └────────────────────┴─────────────────────┘
                     │
              ┌──────▼──────┐
              │ sqlitegraph │
              │  (Database) │
              └─────────────┘
                     │
              ┌──────▼──────┐
              │   splice    │
              │(Edit using  │
              │   spans)    │
              └─────────────┘

What is Mirage?

Mirage analyzes control-flow graphs extracted by Magellan to answer questions like:

• What execution paths exist through this function?
• What code MUST execute on any path from entry to exit?
• Which blocks are unreachable (dead code)?
• What is the impact of changing this code?

What Mirage is NOT

• ❌ A search tool (use llmgrep)
• ❌ An embedding or semantic search tool
• ❌ A linter or static analysis tool
• ❌ A code completion engine
• ❌ A call graph indexer (use Magellan)

What Mirage IS

• ✅ CFG analysis from Magellan's AST-based data
• ✅ Path enumeration with BLAKE3 caching
• ✅ Dominance analysis (dominators, post-dominators, frontiers)
• ✅ Loop detection (natural loops within functions)
• ✅ Dead code detection (unreachable blocks)
• ✅ Impact analysis (blast zones, program slicing)
• ✅ Inter-procedural analysis (hotspots, call graph condensation)

Installation

cargo install mirage-analyzer

The binary is installed as mirage:

mirage --help

Or build from source:

git clone https://github.com/oldnordic/mirage
cd mirage
cargo install --path .

Quick Start

1. Install the Toolset

# Install all tools for complete workflow
cargo install magellan        # Call graph & CFG extraction (REQUIRED)
cargo install llmgrep         # Semantic search
cargo install mirage-analyzer # Path-aware analysis
cargo install splice          # Precision editing

2. Index Your Project

# Magellan watches your source and builds CFG
magellan watch --root ./src --db .codemcp/codegraph.db

Magellan will:

1. Parse your source code with tree-sitter
2. Build AST-based control flow graphs for each function
3. Store everything in a SQLite database

3. Analyze with Mirage

# Check database status
mirage status

# Show all execution paths through a function
mirage paths --function "my_crate::main"

# Find unreachable code
mirage unreachable

# Visualize control flow
mirage cfg --function "my_crate::main" --format dot | dot -Tpng -o cfg.png

CLI Commands

Global Options

Examples

Path Enumeration

# All paths through a function
mirage paths --function "my_crate::process"

# Only error-returning paths
mirage paths --function "my_crate::process" --show-errors

# Limit exploration depth
mirage paths --function "my_crate::process" --max-length 10

# JSON output for scripting
mirage paths --function "my_crate::process" --output json | jq '.paths[].path_id'

Dominance Analysis

# Show dominance tree
mirage dominators --function "my_crate::process"

# What MUST execute before this block?
mirage dominators --function "my_crate::process" --must-pass-through 5

# Post-dominators (what must execute after)
mirage dominators --function "my_crate::process" --post

# Inter-procedural (call graph level)
mirage dominators --function "my_crate::main" --inter-procedural

Impact Analysis

# What does this block affect?
mirage blast-zone --function "my_crate::process" --block-id 0

# What affects this function? (backward slice)
mirage slice --symbol "my_crate::process" --direction backward

# What does this function affect? (forward slice)
mirage slice --symbol "my_crate::process" --direction forward

# High-risk functions
mirage hotspots --entry main --top 10

Database Schema

Mirage extends the Magellan database with:

The default database location is .codemcp/codegraph.db. This is shared with Magellan.

Requirements

• Rust 1.77+
• Magellan — Required for CFG extraction

  cargo install magellan
  magellan watch --root ./src --db .codemcp/codegraph.db
  

• sqlitegraph — Included automatically as dependency

License

GPL-3.0-or-later

Related Projects

• sqlitegraph — Graph database library
• Magellan — Call graph indexer
• llmgrep — Semantic search
• splice — Precision editing