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)    │
              └─────────────┘

Tool	Purpose	Repository	Install
sqlitegraph	Graph database foundation	github.com/oldnordic/sqlitegraph	`cargo add sqlitegraph`
Magellan	Call graph indexing, symbol navigation	github.com/oldnordic/magellan	`cargo install magellan`
llmgrep	Semantic code search	github.com/oldnordic/llmgrep	`cargo install llmgrep`
Mirage	CFG analysis, path enumeration	github.com/oldnordic/mirage	`cargo install mirage-analyzer`
splice	Precision code editing	github.com/oldnordic/splice	`cargo install splice`

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

Quick Install (SQLite Backend)

cargo install splice

This installs splice with the SQLite backend (default).

Backend Selection

splice supports two database backends via compile-time feature flags. Choose your backend based on your needs (see Which Backend Should I Use? for guidance).

SQLite Backend (Default)

The SQLite backend is stable and recommended for most users.

# Install from crates.io (SQLite backend)
cargo install splice

# Build from source (SQLite backend)
git clone https://github.com/oldnordic/splice
cd splice
cargo build --release
cp target/release/splice ~/.local/bin/

# Explicit SQLite feature
cargo build --release --features sqlite

Native-V2 Backend

The native-v2 backend uses an embedded Rust database for improved performance and is ideal for large-scale projects.

# Install with native-v2 backend
cargo install splice --features native-v2 --no-default-features

# Build from source (native-v2 backend)
git clone https://github.com/oldnordic/splice
cd splice
cargo build --release --features native-v2 --no-default-features
cp target/release/splice ~/.local/bin/

Note: The --no-default-features flag is required for native-v2 builds to exclude the SQLite default.

Platform Features

Platform support is controlled via feature flags:

Platform	Feature	Default
Linux/macOS	`unix`	Yes
Windows	`windows`	No

Build for specific platforms:

# Build for Windows (with SQLite backend)
cargo build --release --features windows

# Build for Windows (with native-v2 backend)
cargo build --release --features native-v2,windows --no-default-features

For installation on Windows:

# Install on Windows (SQLite backend)
cargo install splice --features windows

# Install on Windows (native-v2 backend)
cargo install splice --features native-v2,windows --no-default-features

Which Backend Should I Use?

splice supports two database backends for storing code graph data: SQLite (default) and native-v2 (opt-in). Both backends provide full functionality, but they have different characteristics that may make one more suitable for your use case.

Backend Comparison

Aspect	SQLite Backend	Native-V2 Backend
Feature flag	`--features sqlite` (default)	`--features native-v2`
Database format	SQLite format 3	Custom key-value format
Default behavior	Default backend	Opt-in (must enable feature)
File size	Larger (2-3x for large codebases)	~70% smaller
Symbol lookup	Table scan (O(n))	O(1) KV get
File listing	JOIN query	Prefix scan
Graph traversal	Row-by-row iteration	Clustered adjacency
Performance	Good for small/medium codebases	2-100x faster for large codebases
Snapshot support	Manual export/import	Native snapshot/restore system
Tools compatibility	All SQLiteGraph tools	All SQLiteGraph tools
Maturity	Stable, battle-tested	Stable (v2.5.0+)

Feature Availability

Feature	SQLite	Native-V2
Basic operations (patch, delete, rename)	✅	✅
Graph algorithms (reachable, cycles, dead-code)	✅	✅
Snapshot capture	✅ (v2.5.0, manual export)	✅ (v2.5.0, native)
Database restore	⚠️ Manual import	✅ Native restore
Batch operations with rollback	⚠️ Limited	✅ Full support (v2.5.0)
Magellan compatibility	✅ Full	✅ Full

Choose SQLite If:

✅ You're just getting started with splice
✅ You need maximum compatibility with standard SQLite tools
✅ You work with small to medium codebases (<100K LOC)
✅ You prefer battle-tested, stable defaults
✅ You want to inspect database with standard SQLite tools (sqlite3, DB Browser)

Choose Native-V2 If:

✅ You work with large codebases (100K+ LOC)
✅ You need faster graph operations and symbol lookups
✅ You want smaller database file sizes for CI/CD storage
✅ You need native snapshot/restore for rollback workflows
✅ You use batch operations with transaction safety
✅ You want the latest performance optimizations

Migrating Between Backends

If you want to switch backends, see the Native-V2 Migration Guide for detailed instructions. The migration process preserves all your graph data and ensures no loss of information.

Note: New databases created with native-v2 support enabled will use the native-v2 format by default, even if the sqlite feature is also enabled.

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

Command	Description
`patch`	Replace function bodies, class definitions with validation
`delete`	Remove symbol definitions and all references
`apply-files`	Multi-file pattern replacement with AST confirmation
`rename`	Cross-file symbol rename using Magellan ReferenceFact

Graph Algorithm Commands

Command	Description
`reachable`	Show caller/callee chains and affected files
`dead-code`	Find unused symbols from entry points
`cycles`	Find circular dependencies in call graph
`condense`	Collapse SCCs to DAG for dependency analysis
`slice`	Forward/backward program slicing

Query Commands (Magellan)

Command	Description
`status`	Display database statistics
`find`	Locate symbols by name or symbol_id
`refs`	Show callers/callees for a symbol
`files`	List indexed files
`export`	Export graph data (JSON, JSONL, CSV)

Utility Commands

Command	Description
`undo`	Restore files from backup manifest
`log`	Query execution audit trail
`explain`	Get detailed explanations for error codes
`validate-proof`	Validate refactoring proof files

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

Language	Extensions	Patch	Delete	Validation
Rust	`.rs`	Full	Full	`cargo check`
Python	`.py`	Full	Basic	`python -m py_compile`
C	`.c`, `.h`	Full	Basic	`gcc -fsyntax-only`
C++	`.cpp`, `.hpp`, `.cc`, `.cxx`	Full	Basic	`g++ -fsyntax-only`
Java	`.java`	Full	Basic	`javac`
JavaScript	`.js`, `.mjs`, `.cjs`	Full	Basic	`node --check`
TypeScript	`.ts`, `.tsx`	Full	Basic	`tsc --noEmit`

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

splice 2.5.0