Splice

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

Version: 2.2.3 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.3 Features

Splice v2.2.3 fixes SQLiteGraph 1.2.7 MVCC API compatibility, ensuring the latest dependency versions work correctly:

• 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:

1. UTF-8 boundary validation
2. Pre-operation checksum computation (SHA-256)
3. Tree-sitter reparse (syntax check)
4. Language-specific compiler check (cargo check, python -m py_compile, etc.)
5. Post-operation checksum verification
6. 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:

• Magellan on crates.io
• Magellan on GitHub

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.