Splice

Span-safe refactoring kernel for Rust using SQLiteGraph.

Status: MVP / Proof of Concept Version: 0.1.0 License: GPL-3.0-or-later

What This Is

Splice is a command-line tool that performs byte-accurate, AST-validated replacements of Rust code. Think of it as sed that:

• Understands Rust syntax via tree-sitter
• Validates replacements with tree-sitter reparse
• Validates replacements with cargo check
• Performs atomic rollback on validation failures

What This Is NOT

❌ An IDE - Use Rust Analyzer or IntelliJ Rust ❌ A semantic refactoring tool - It doesn't track cross-file references ❌ A complete solution - It's a focused tool for one specific job ❌ Production-hardened - It's an MVP with known limitations

What It Does Well

✅ Replaces function bodies, struct definitions, enum variants ✅ Validates syntax after every patch ✅ Validates compilation after every patch ✅ Rolls back atomically on any failure ✅ Orchestrates multi-step refactors via JSON plans

Known Limitations

• No cross-file reference tracking (won't find all call sites)
• No persistent database (creates graph on-the-fly for each patch)
• No resume mode for failed plans (partial state must be manually cleaned up)
• No dry-run mode (can't preview without applying)
• No auto-discovery of symbols (you must know exact names)
• Single-file symbol resolution only

Installation

From Source

# Clone repository
git clone https://github.com/oldnordic/splice.git
cd splice

# Build release binary
cargo build --release

# Install to user bin
mkdir -p ~/.local/bin
cp target/release/splice ~/.local/bin/splice

# Add to PATH (add to ~/.bashrc)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

System-Wide Install (Optional)

sudo cp target/release/splice /usr/local/bin/splice

Quick Start

Single Patch

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

# Apply patch
splice patch \
  --file src/lib.rs \
  --symbol greet \
  --kind function \
  --with new_greet.rs

Multi-Step Plan

# Create plan.json
cat > plan.json << 'EOF'
{
  "steps": [
    {
      "file": "src/lib.rs",
      "symbol": "foo",
      "kind": "function",
      "with": "patches/foo.rs"
    },
    {
      "file": "src/lib.rs",
      "symbol": "bar",
      "kind": "function",
      "with": "patches/bar.rs"
    }
  ]
}
EOF

# Execute plan
splice plan --file plan.json

Documentation

• manual.md - Complete user manual with examples and troubleshooting
• QUICKSTART.md - Quick reference card

Requirements

• Rust 1.70+ (for building)
• Cargo workspace (for validation)
• tree-sitter-rust (bundled)
• SQLiteGraph 0.2.4 (local dependency at ../sqlitegraph/sqlitegraph)

Architecture

Modules

• src/cli/ - CLI argument parsing (clap)
• src/ingest/ - Rust file parsing (tree-sitter-rust)
• src/graph/ - SQLiteGraph integration (symbol storage, resolution)
• src/resolve/ - Symbol → byte span resolution
• src/patch/ - Span-safe replacement + validation gates
• src/validate/ - Tree-sitter + cargo check validation
• src/plan/ - JSON plan orchestration
• src/error.rs - Typed error hierarchy

Validation Gates

Every patch passes:

1. UTF-8 boundary validation
2. Tree-sitter reparse (syntax check)
3. Cargo check (compilation check)
4. [Optional] rust-analyzer (lint check)

Development Status

Complete Features:

• ✅ Span-safe byte replacement
• ✅ Tree-sitter validation
• ✅ Cargo check validation
• ✅ Atomic rollback
• ✅ Multi-step plan execution
• ✅ CLI interface

Not Implemented:

• ⛔ Cross-file reference tracking
• ⛔ Persistent symbol database
• ⛔ Resume mode for failed plans
• ⛔ Dry-run mode
• ⛔ Auto-discovery of symbols
• ⛔ Incremental validation

Testing

# Run all tests
cargo test

# Run specific test suite
cargo test --test cli_tests
cargo test --test patch_tests

Test Coverage: 22/22 tests passing

• Plan unit tests: 2/2
• CLI integration tests: 9/9
• Ingest tests: 3/3
• Integration refactor tests: 3/3
• Patch tests: 3/3
• Resolve tests: 2/2

Examples

See the test files for examples:

• tests/cli_tests.rs - CLI integration examples
• tests/patch_tests.rs - Patch validation examples
• tests/integration_refactor.rs - Symbol resolution examples

Contributing

This is an MVP / proof-of-concept. The codebase is feature-complete as of v0.1.0.

Bug reports and PRs are welcome, but please note:

• No new features are planned
• Scope is intentionally limited
• This is not a production refactoring tool

License

GPL-3.0-or-later - See LICENSE file for details

Acknowledgments

Built with:

• tree-sitter - AST parsing
• tree-sitter-rust - Rust grammar
• SQLiteGraph - Code graph storage
• ropey - Safe text editing
• clap - CLI argument parsing

Author

oldnordic

Disclaimer

This is experimental software. Use at your own risk. Always commit your changes before running Splice.