splice 2.8.0

Span-safe refactoring kernel for 7 languages with Magellan code graph integration
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132

# splice

[![Crates.io](https://img.shields.io/crates/v/splice)](https://crates.io/crates/splice)
[![Documentation](https://docs.rs/splice/badge.svg)](https://docs.rs/splice)

**Version:** 2.8.0

Span-safe refactoring kernel for 7 languages. Byte-accurate code editing with graph algorithm analysis.

**Positioning:** Precision editing tool for codebases indexed by Magellan. Use for cross-file rename, impact analysis, and verified refactoring.

## Purpose

**splice edits code with graph-aware safety.** Built for:

- **Developers** — Cross-file rename, safe refactoring with rollback
- **Grounded Assistants** — Byte-accurate edits with proof-based verification
- **Tooling** — Scriptable transformations with AST validation

## Features

- **Span-safe editing** — Byte-accurate replacements with tree-sitter validation
- **Cross-file rename** — Symbol rename across entire codebase
- **Graph algorithms** — Reachability, dead-code, cycles, condense, slice
- **Impact analysis** — Blast zone detection before editing
- **Proof-based refactoring** — Machine-checkable behavioral equivalence
- **Code completion** — Grounded, import-aware suggestions using Magellan database
  - Cross-file symbol resolution via import tracking
  - Distinguishes local vs imported symbols with source tracking
  - Token filtering and enhanced ranking for imported symbols
  - Performance: low-millisecond internal query time on indexed project databases
- **7 languages** — Rust, Python, C, C++, Java, JavaScript, TypeScript
- **Library API** — Use as a Rust crate for programmatic refactoring (forge, agents)

## Quick Start

```bash
# Install
cargo install splice

# Requires Magellan database (create first)
magellan watch --root ./src --db .magellan/splice.db

# Check status
splice status --db .magellan/splice.db

# Find reachable code from main
splice reachable --symbol main --path src/main.rs --db .magellan/splice.db

# Cross-file rename
splice rename --symbol old_name --to new_name --path src/lib.rs --db .magellan/splice.db

# Code completion (import-aware)
splice complete --file src/lib.rs --line 27 --column 8 --db .magellan/splice.db --max-results 10
```

## Library Usage

Splice exposes a library API for programmatic use. Add to `Cargo.toml`:

```toml
[dependencies]
splice = { version = "2.8", default-features = false, features = ["sqlite"] }
```

### High-Level API (forge integration)

```rust
use splice::forge;

// Patch a symbol with new content (resolves via SymbolNavigator)
let result = forge::patch_symbol_in_file(
    Path::new("src/lib.rs"),
    "my_function",
    "pub fn my_function() -> i32 { 42 }",
    Path::new(".magellan/myproject.db"),
)?;

// Rename across all files
let result = forge::rename_symbol_across_files("old_name", "new_name", db_path)?;

// Preview without writing
let preview = forge::preview_patch_symbol(file, symbol, content, db)?;

// Resolve symbol to byte span
let span = forge::resolve_symbol_span(file, symbol, db)?;
```

### Low-Level API

```rust
use splice::patch::{replace_span, apply_patch_with_validation, SpanReplacement};
use splice::graph::rename::{apply_replacements_in_file, group_references_by_file};
use splice::workspace::{find_workspace_root, detect_project_language};
use splice::verify::{pre_verify_patch, post_verify_patch};
```

## Installation

```bash
cargo install splice
```

## Backends

| Feature | Description | File | Best For |
|---------|-------------|------|----------|
| (default) | SQLite backend | `.db` | Compatibility |
| `geometric` | Geometric analysis backend (no-op) | `.geo` | Reserved for future use |

## Requirements

- **[Magellan](https://github.com/oldnordic/magellan)** 4.2+ — Required for code graph
- **[sqlitegraph](https://crates.io/crates/sqlitegraph)** 3.0.3+ — Included automatically

## Documentation

- **[MANUAL.md](MANUAL.md)** — Complete command reference and examples
- **[CHANGELOG.md](CHANGELOG.md)** — Version history
- **[docs/API.md](docs/API.md)** — Library API reference
- **[docs/completion.md](docs/completion.md)** — Code completion feature documentation

## What splice Does NOT Do

- Index code (use [Magellan](https://github.com/oldnordic/magellan))
- Search code (use [llmgrep](https://github.com/oldnordic/llmgrep))
- CFG analysis (use [Mirage](https://github.com/oldnordic/mirage))
- Type checking (use Compiler/LSP)

## License

GPL-3.0. See [LICENSE](LICENSE).