Mirage

Version: 1.10.1

Path-aware code intelligence engine for Rust. Analyzes control-flow graphs from Magellan databases.

Purpose

Mirage reads Magellan code graphs and provides control-flow analysis:

• Path enumeration through functions
• Dominance and post-dominance analysis
• Natural loop detection
• Dead code detection
• Call graph cycle detection
• Inter-procedural reachability (with depth-aware blast zone analysis)
• Source document listing from graph memory tables
• Semantic entry point discovery — find functions by natural-language query via HNSW embeddings

Technical Architecture

Reads Magellan-managed code graphs directly — no separate Mirage index.

Analyses

• Path enumeration through functions
• Dominance, post-dominance, dominance frontiers
• Natural loop detection
• Dead / unreachable code detection
• Call graph cycle detection
• Interprocedural reachability with depth-aware blast zone (blast-zone)
• Hotspot detection (interprocedural by default)
• Pattern matching — if/else, match arms
• Semantic entry point discovery via HNSW embeddings (natural-language query)

Output formats — human · json · pretty · dot

Keyword index: control-flow graph · CFG · path enumeration · dominance · post-dominance · natural loops · dead code · call graph cycles · interprocedural reachability · blast radius · hotspots · pattern matching · HNSW · Rust

Quick Start

# Install
cargo install mirage-analyzer

# Index your codebase with Magellan first
magellan watch --root ./src --db .magellan/magellan.db

# Analyze CFG
mirage --db .magellan/magellan.db paths --function "main"
mirage --db .magellan/magellan.db cfg --function "process"
mirage --db .magellan/magellan.db cycles
mirage --db .magellan/magellan.db docs --kind wiki

# Semantic entry point discovery (requires `magellan embed --db <db>` first)
mirage --db .magellan/magellan.db paths --semantic-query "error handling in the parser"

Backends

Mirage supports Magellan's database formats:

Backend	File Extension	Feature Flag	Status
SQLite	.db	backend-sqlite	Default
Geometric	.geo	backend-geometric	Supported

Note: The SQLite backend is now default. Install with:

# Default (SQLite)
cargo install mirage-analyzer

# Geometric backend only
cargo install mirage-analyzer --features backend-geometric --no-default-features

Requirements

• Magellan SQLite .db databases with schema v20 support (minimum CFG-compatible schema remains v7)
• Rust 1.70+
• Magellan database (.db) created by magellan watch

Database Location: Default is a Magellan-managed .db file such as .magellan/magellan.db (auto-discovered). Legacy .magellan/mirage.db paths are still accepted.

Documentation

• MANUAL.md — Command reference
• ARCHITECTURE.md — Design and integration
• API_INTEGRATION.md — Magellan contract
• INVARIANTS.md — Behavioral guarantees
• CHANGELOG.md — Version history

License

GPL-3.0. See LICENSE.