Splice

Span-safe refactoring kernel for 7 languages using tree-sitter and SQLiteGraph.

Version: 2.2.2 License: GPL-3.0-or-later

What This Is

Splice is a command-line tool that 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, apply batch changes, perform pattern replacements, query code graphs, and undo operations.

v2.2.2 Features

Splice v2.2.2 delivers a unified CLI interface with Magellan query commands for code discovery alongside span-safe editing:

Unified CLI: Single tool for code graph queries (Magellan) and refactoring (Splice)
Query Commands: status, query, find, refs, files for code graph navigation
Export Command: Export graph data in JSON, JSONL, or CSV formats
Magellan Integration: In-process library delegation for optimal performance
CLI Alignment: --output (human/json/pretty), --db for database path, Magellan-compatible exit codes
Error Handling: SPL-E091 Magellan error code with full error chain preservation

v2.2 Features

Rich Span Extensions: Context, semantic kind, language, checksums, error codes
Rich Span Advanced: Relationships (callers, callees, imports, exports), tool hints
CLI Conventions: -n dry-run, -A/-B/-C context, unified diff, git-style exit codes
Enhanced Errors: SPL-E### codes, severity levels, fuzzy suggestions, splice explain

v2.0 Features

Structured JSON Output: All operations return structured JSON with explicit fields
Span-Aware Metadata: Line and column coordinates in all output
Deterministic Ordering: All operations return sorted results
Validation Hooks: Pre/post-operation checksums verify code integrity
Execution Logging: Complete audit trail in .splice/operations.db
SQLiteGraph v1.0: Native V2 backend for improved performance
Enhanced Safety: Eliminated unwrap() calls, comprehensive error handling

What This Is NOT

An IDE or LSP server - Use Rust Analyzer, IntelliJ, PyCharm, VSCode, or your editor
A general-purpose refactoring tool - Focused on specific operations
A complete solution - It's a focused tool for specific jobs
Production-hardened - Use with version control

What It Does

Edit Commands:

patch: Replace function bodies, class definitions, enum variants with validation (single or batch)
delete: Remove symbol definitions and all references (cross-file, Rust-only)
apply-files: Multi-file pattern replacement with AST confirmation
search: Pattern-based search with glob filtering

Query Commands (Magellan Integration):

status: Display database statistics (files, symbols, references, calls, code_chunks)
query: Query symbols by labels (language, kind) with optional context
find: Locate symbols by name or symbol_id with disambiguation
refs: Show callers/callees for a symbol (bidirectional traversal)
files: List indexed files with optional symbol counts
export: Export graph data (JSON, JSONL, CSV formats)

Utility Commands:

undo: Restore files from backup manifest
plan: Orchestrate multi-step refactors via JSON plans
log: Query execution audit trail from operations.db
explain: Get detailed explanations for error codes

Validation:

Validates syntax with tree-sitter after every operation
Validates compilation with language-specific compilers
Rolls back atomically on any failure

Supported Languages

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

Delete modes:

Full: Finds all references across files (Rust only)
Basic: Deletes definition only, no reference finding (other languages)

Installation

cargo install splice

Or from source:

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

Quick Start

Delete a Symbol (Rust)

Delete a function and all its references:

splice delete --file src/lib.rs --symbol helper --kind function

Output (structured JSON):

{
  "version": "2.0.0",
  "operation_id": "20250118_123456_abc123",
  "operation_type": "delete",
  "status": "success",
  "message": "Deleted 'helper' (3 references + definition) across 2 file(s).",
  "timestamp": "2025-01-18T12:34:56.789Z",
  "result": {
    "symbol": "helper",
    "kind": "function",
    "spans_deleted": 4,
    "files_affected": 2,
    "spans": [
      {
        "file_path": "src/lib.rs",
        "symbol": "helper",
        "kind": "function",
        "byte_start": 120,
        "byte_end": 189,
        "line_start": 5,
        "line_end": 7,
        "col_start": 0,
        "col_end": 1,
        "span_checksum_before": "a1b2c3d4..."
      }
    ]
  }
}

Patch a Symbol (Rust)

Replace a function body:

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

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

Patch a Symbol (Python)

cat > new_calc.py << 'EOF'
def calculate(x: int, y: int) -> int:
    return x * y
EOF

splice patch --file utils.py --symbol calculate --language python --with new_calc.py

Patch a Symbol (TypeScript)

cat > new_fn.ts << 'EOF'
function calculate(x: number, y: number): number {
    return x * y;
}
EOF

splice patch --file src/math.ts --symbol calculate --language type-script --with new_fn.ts

Multi-Step Plan

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

splice plan --file plan.json

Batch Patch

Apply multiple patches at once from a JSON file:

cat > batch.json << 'EOF'
{
  "patches": [
    {
      "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

splice patch --batch batch.json --language rust

Pattern Replace

Replace a pattern across multiple files:

# Replace "42" with "99" in all Python files
splice apply-files --glob "*.py" --find "42" --replace "99"

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

Preview Mode

Inspect changes before applying:

splice patch --file src/lib.rs --symbol foo --with new_foo.rs --preview

Backup and Undo

Create a backup before changes:

splice patch --file src/lib.rs --symbol foo --with new_foo.rs --create-backup --operation-id "my-change"

Restore from backup:

splice undo --manifest .splice-backup/my-change/manifest.json

Query Symbols by Label (Magellan Integration)

# List all available labels
splice query --db code.db --list

# Find all Rust functions
splice query --db code.db --label rust --label fn

# Show code for each result
splice query --db code.db --label struct --show-code

Get Code Chunks (Magellan Integration)

# Get code by byte span without re-reading the file
splice get --db code.db --file src/lib.rs --start 0 --end 100

Query Commands (Magellan Integration)

# Show database statistics
splice status --db code.db

# Find all functions in a file
splice query --db code.db --file src/lib.rs --kind fn

# Find symbol by name
splice find --db code.db --name my_function

# Show call relationships
splice refs --db code.db --name my_function --direction out

# List indexed files
splice files --db code.db --symbols

# Export graph data
splice export --db code.db --format json --file export.json

Commands

splice delete

Remove a symbol definition and all its references.

splice delete --file <PATH> --symbol <NAME> [--kind <KIND>] [--language <LANG>]

Optional Arguments:

--kind <KIND>: Symbol kind filter
--language <LANG>: Language override
--analyzer <MODE>: Validation mode (off, os, path)
--create-backup: Create backup before deleting
--operation-id <ID>: Custom operation ID for auditing
--metadata <JSON>: Optional metadata attachment

Rust-specific features:

Finds references across the entire workspace
Tracks imports and re-exports
Handles shadowing correctly
Cross-file reference resolution

Other languages:

Deletes the symbol definition only
Use with --language flag or auto-detection from file extension

splice patch

Apply a patch to a symbol's span.

splice patch --file <PATH> --symbol <NAME> --with <FILE> [--kind <KIND>] [--language <LANG>]

Optional Arguments:

--kind <KIND>: Symbol kind filter (function, method, class, struct, interface, enum, trait, impl, module, variable, constructor, type-alias)
--language <LANG>: Language override (rust, python, c, cpp, java, java-script, type-script)
--analyzer <MODE>: Validation mode (off, os, path)
--preview: Run in preview mode without modifying files
--batch <FILE>: JSON file describing batch replacements
--create-backup: Create backup before patching
--operation-id <ID>: Custom operation ID for auditing
--metadata <JSON>: Optional metadata attachment

splice apply-files

Apply a pattern replacement to multiple files.

splice apply-files --glob <GLOB> --find <PATTERN> --replace <REPLACEMENT>

Required Arguments:

--glob <GLOB>: Glob pattern for matching files (e.g., tests/**/*.rs, src/**/*.py)
--find <PATTERN>: Text pattern to find
--replace <REPLACEMENT>: Replacement text

Optional Arguments:

--language <LANG>: Language override (auto-detected from extension by default)
--no-validate: Skip validation gates
--create-backup: Create backup before applying
--operation-id <ID>: Custom operation ID for auditing
--metadata <JSON>: Optional metadata attachment

splice undo

Undo a previous operation by restoring from a backup manifest.

splice undo --manifest <PATH>

splice plan

Execute a multi-step refactoring plan.

splice plan --file <PLAN.json>

splice query

Query symbols by labels using Magellan integration.

splice query --db <FILE> [--label <LABEL>]... [--list] [--count] [--show-code]

Optional Arguments:

--db <FILE>: Path to the Magellan database (required)
--label <LABEL>: Label to query (can be specified multiple times for AND semantics)
--list: List all available labels with counts
--count: Count entities with specified label(s)
--show-code: Show source code for each result

Available labels:

Language labels: rust, python, javascript, typescript, c, cpp, java
Symbol kind labels: fn, method, struct, class, enum, interface, module, union, namespace, typealias

splice get

Get code chunks from the database using Magellan integration.

splice get --db <FILE> --file <PATH> --start <N> --end <N>

Required Arguments:

--db <FILE>: Path to the Magellan database
--file <PATH>: File path
--start <N>: Start byte offset
--end <N>: End byte offset

splice status

Display database statistics.

splice status --db <FILE> [--output FORMAT]

Required Arguments:

--db <FILE>: Path to the Magellan database

Optional Arguments:

--output FORMAT: Output format (human, json, pretty) - default: human

splice find

Find symbols by name or symbol_id.

splice find --db <FILE> (--name <NAME> | --symbol-id <ID>) [--ambiguous] [--output FORMAT]

Required Arguments:

--db <FILE>: Path to the Magellan database
--name <NAME>: Symbol name to find
--symbol-id <ID>: 16-character hex symbol ID

Optional Arguments:

--ambiguous: Show all matches for ambiguous names
--output FORMAT: Output format (human, json, pretty)

splice refs

Show callers/callees for a symbol.

splice refs --db <FILE> (--name <NAME> | --path <PATH> --name <NAME>) [--direction DIR] [--output FORMAT]

Required Arguments:

--db <FILE>: Path to the Magellan database
--name <NAME>: Symbol name
--path <PATH>: File path (for disambiguation)

Optional Arguments:

--direction DIR: Relationship direction (in, out, both) - default: both
--output FORMAT: Output format (human, json, pretty)

splice files

List indexed files.

splice files --db <FILE> [--symbols] [--output FORMAT]

Required Arguments:

--db <FILE>: Path to the Magellan database

Optional Arguments:

--symbols: Show symbol counts per file
--output FORMAT: Output format (human, json, pretty)

splice export

Export graph data.

splice export --db <FILE> --format FORMAT --file <PATH>

Required Arguments:

--db <FILE>: Path to the Magellan database
--format FORMAT: Export format (json, jsonl, csv)
--file <PATH>: Output file path

splice log

Query the execution audit trail from .splice/operations.db.

# Show recent operations
splice log

# Filter by operation type
splice log --operation-type patch

# Filter by status
splice log --status success

# Filter by date range
splice log --after "2025-01-01" --before "2025-01-31"

# Query specific execution
splice log --execution-id 20250118_123456_abc123

# Show statistics
splice log --stats

# JSON output for programmatic access
splice log --format json

Optional Arguments:

--operation-type <TYPE>: Filter by operation type (patch, delete, plan, apply-files)
--status <STATUS>: Filter by status (success, failure, partial)
--after <DATE>: Show operations after this date (ISO8601 format)
--before <DATE>: Show operations before this date (ISO8601 format)
--execution-id <ID>: Query specific execution by ID
--format <FORMAT>: Output format (table, json) - default: table
--stats: Show statistics summary instead of individual operations
--limit <N>: Limit number of results (default: 50)

Output Fields:

execution_id: Unique identifier for each operation
operation_type: Type of operation performed
status: Success/failure status
timestamp: ISO8601 timestamp when operation started
duration_ms: Operation duration in milliseconds
command_line: Full command-line invocation
workspace: Working directory path
affected_files: Number of files modified

Documentation

docs/magellan_integration.md - Magellan integration guide (query commands, export formats, LLM usage)
manual.md - Complete user manual
CHANGELOG.md - Version history
docs/DIAGNOSTICS_HUMAN_LLM.md - CLI diagnostics contract for humans and LLMs, including rust-analyzer and multi-language validation output

Requirements

Rust 1.70+ (for building)
Language-specific compilers (for validation):
- Rust: cargo
- Python: python
- C/C++: gcc/g++
- Java: javac
- JavaScript: node
- TypeScript: tsc

Architecture

src/cli/ - CLI argument parsing
src/ingest/ - Symbol parsing for 7 languages
src/graph/ - SQLiteGraph integration with Native V2 backend
src/resolve/ - Symbol resolution and reference finding
src/patch/ - Span-safe replacement + validation + batch operations + pattern replace + backup
src/validate/ - Tree-sitter + compiler validation gates with checksum verification
src/plan/ - JSON plan orchestration with deterministic ordering
src/execution/ - Execution logging audit trail with operations.db
src/output/ - Structured JSON output with v2.0 schema
src/checksum/ - SHA-256 checksum computation for verification hooks

Validation Gates

Every operation passes:

UTF-8 boundary validation
Pre-operation checksum computation (SHA-256)
Tree-sitter reparse (syntax check)
Language-specific compiler check (cargo check, python -m py_compile, etc.)
Post-operation checksum verification
Atomic rollback on any failure

All operations are logged to .splice/operations.db with timestamps, durations, and command-line capture for complete auditability.

Testing

cargo test

Test Coverage: 215+ tests passing, including:

171 unit tests for core functionality
26 Magellan integration tests for all 7 languages
18 cross-language compatibility tests
End-to-end refactoring workflow tests

Feedback

If you use this tool and find a bug or miss a feature that would be useful, drop a line. It's appreciated.

License

GPL-3.0-or-later

Disclaimer

This software modifies source code. Always commit your changes before running Splice.

Integration with Magellan

Splice works best with Magellan for code graph indexing and querying.

Magellan is a code understanding and indexing library that provides:

Multi-language parsing (Rust, Python, C, C++, Java, JavaScript, TypeScript)
Symbol discovery and relationship tracking
Call graph analysis
Fast code graph queries

Links:

When you use Splice's query commands (status, query, find, refs, files, export), you're leveraging Magellan's powerful code graph capabilities through Splice's unified CLI interface.

splice 2.2.2

Splice

What This Is

v2.2.2 Features

v2.2 Features

v2.0 Features

What This Is NOT

What It Does

Supported Languages

Installation

Quick Start

Delete a Symbol (Rust)

Patch a Symbol (Rust)

Patch a Symbol (Python)

Patch a Symbol (TypeScript)

Multi-Step Plan

Batch Patch

Pattern Replace

Preview Mode

Backup and Undo

Query Symbols by Label (Magellan Integration)

Get Code Chunks (Magellan Integration)

Query Commands (Magellan Integration)

Commands

splice delete

splice patch

splice apply-files

splice undo

splice plan

splice query

splice get

splice status

splice find

splice refs

splice files

splice export

splice log

Documentation

Requirements

Architecture

Validation Gates

Testing

Feedback

License

Disclaimer

Integration with Magellan