splice

Precision Code Editing with Graph Algorithm Analysis

Span-safe refactoring kernel for 7 languages with Magellan code graph integration.

⚠️ Requires Magellan

splice requires Magellan for full functionality.

Magellan provides the code graph database that splice uses for cross-file operations, impact analysis, and graph algorithms. You must run magellan watch on your codebase before using splice's advanced features.

# Install Magellan first
cargo install magellan

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

# Now splice can perform graph-aware operations
splice reachable --symbol main --path src/main.rs --db .codemcp/codegraph.db

The Code Intelligence Toolset

splice 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 and transformation.

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

What is splice?

splice performs byte-accurate, AST-validated refactoring operations on code in 7 languages: Rust, Python, C, C++, Java, JavaScript, and TypeScript. It can replace function bodies, delete symbols, perform cross-file rename, analyze code graphs, and generate refactoring proofs.

What splice is NOT

• ❌ A code indexer (use Magellan)
• ❌ A semantic search tool (use llmgrep)
• ❌ A CFG analysis tool (use Mirage)
• ❌ An IDE or LSP server (use rust-analyzer, IntelliJ, PyCharm, VSCode)

What splice IS

• ✅ Span-safe code editing with byte-accurate replacements
• ✅ Cross-file symbol rename using Magellan ReferenceFact data
• ✅ Graph algorithm analysis (reachability, dead-code, cycles, condense, slice)
• ✅ Proof-based refactoring with machine-checkable behavioral equivalence
• ✅ Multi-language validation (tree-sitter + compiler gates)
• ✅ Backup and rollback with automatic checksum verification

Installation

cargo install splice

Or build from source:

git clone https://github.com/oldnordic/splice
cd splice
cargo build --release
cp target/release/splice ~/.local/bin/

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 database
magellan watch --root ./src --db .codemcp/codegraph.db

3. Edit with Splice

# Patch a function body
cat > new_func.rs << 'EOF'
pub fn process(data: &str) -> Result<String> {
    Ok(data.to_uppercase())
}
EOF

splice patch --file src/lib.rs --symbol process --with new_func.rs --db .codemcp/codegraph.db

# Preview before applying
splice patch --file src/lib.rs --symbol process --with new_func.rs --preview --json

# Cross-file rename
splice rename --symbol <id> --file src/lib.rs --to new_name

# Impact analysis
splice reachable --symbol main --path src/main.rs --max-depth 3
splice dead-code --entry main --path src/main.rs
splice cycles

Commands

Edit Commands

Graph Algorithm Commands

Query Commands (Magellan)

Utility Commands

Examples

Cross-File Rename with Preview

# Find symbol ID first
splice find --name my_function --path src/lib.rs --db .codemcp/codegraph.db

# Preview rename (no changes)
splice rename --symbol <id> --file src/lib.rs --to new_name --preview --json

# Apply rename with backup
splice rename --symbol <id> --file src/lib.rs --to new_name

# Generate proof for audit trail
splice rename --symbol <id> --file src/lib.rs --to new_name --proof

Impact Analysis Before Refactoring

# See what code is reachable from a symbol
splice reachable --symbol main --path src/main.rs --max-depth 3 --output json

# Find dead code from main entry point
splice dead-code --entry main --path src/main.rs --exclude-public

# Detect circular dependencies
splice cycles --show-members --max-cycles 20

# Slice forward from a target (what it affects)
splice slice --target <id> --direction forward --max-distance 5

Patch with Preview

# Create replacement
cat > new_greet.rs << 'EOF'
pub fn greet(name: &str) -> String {
    format!("Hi, {}!", name)
}
EOF

# Preview with JSON output
splice patch --file src/lib.rs --symbol greet --with new_greet.rs --preview --json

# Output:
# {
#   "status": "ok",
#   "message": "Previewed patch 'greet' at bytes 0..42 (dry-run)",
#   "data": {
#     "symbol": "greet",
#     "preview_report": {
#       "file": "src/lib.rs",
#       "line_start": 1,
#       "line_end": 3,
#       "lines_added": 3,
#       "lines_removed": 3,
#       "bytes_added": 45,
#       "bytes_removed": 42
#     },
#     "files": [{"file": "src/lib.rs"}]
#   }
# }

Batch Pattern Replacement

# Replace across multiple files
splice apply-files --glob "src/**/*.rs" --find "old_func" --replace "new_func"

# With validation and backup
splice apply-files --glob "tests/**/*.rs" --find "42" --replace "99" --create-backup

Supported Languages

Requirements

• Magellan 2.1.0+ — Required for code graph operations

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

• sqlitegraph 1.4.2+ — Included automatically

Documentation

• splice <command> --help — Built-in usage examples
• MANUAL.md — Complete CLI reference manual
• CHANGELOG.md — Version history
• docs/examples/rename_examples.md — Cross-file rename examples
• docs/examples/graph_algorithm_examples.md — Graph algorithm usage
• docs/examples/proof_examples.md — Proof-based refactoring

License

GPL-3.0-only. See LICENSE.md.

Related Projects

• sqlitegraph — Graph database library
• Magellan — Call graph indexer
• llmgrep — Semantic code search
• Mirage — CFG analysis