# Cross-File Rename Examples
This document provides comprehensive examples for using Splice's cross-file rename functionality across different programming languages and scenarios.
## Example 1: Simple Function Rename (Rust)
### Setup
Create test project:
```bash
mkdir rename_example && cd rename_example
cargo init --lib
```
**src/lib.rs:**
```rust
pub mod utils;
pub fn main() {
utils::helper_function();
}
```
**src/utils.rs:**
```rust
pub fn helper_function() {
println!("Helper called");
}
pub fn caller() {
helper_function();
}
```
### Ingest and Rename
```bash
# Ingest codebase
splice ingest --root ./src --db .magellan/splice.db
# Find symbol
splice find --name "helper_function" --path "src/utils.rs"
# Output:
# Found symbol "helper_function" in src/utils.rs
# ID: 1a2b3c4d5e6f7g8h
# Kind: function
# Span: (0, 24)
# Preview rename
splice rename \
--symbol 1a2b3c4d5e6f7g8h \
--file src/utils.rs \
--to new_helper_name \
--preview
# Output:
# Will rename "helper_function" to "new_helper_name"
# Found 2 references:
# src/lib.rs:3:10
# src/utils.rs:7:5
# Perform rename
splice rename \
--symbol 1a2b3c4d5e6f7g8h \
--file src/utils.rs \
--to new_helper_name
```
### Result
**src/lib.rs:**
```rust
pub mod utils;
pub fn main() {
utils::new_helper_name();
}
```
**src/utils.rs:**
```rust
pub fn new_helper_name() {
println!("Helper called");
}
pub fn caller() {
new_helper_name();
}
```
## Example 2: Cross-Language Rename (Python)
### Setup
**main.py:**
```python
from utils import process_data
def main():
result = process_data()
return result
```
**utils.py:**
```python
def process_data():
return "processed"
def another_function():
data = process_data()
return data
```
### Rename
```bash
# Ingest the project
splice ingest --root . --db .magellan/splice.db
# Find the symbol
splice find --name "process_data" --path "utils.py"
# Rename across all Python files
splice rename \
--symbol <id> \
--file utils.py \
--to transform_data
```
### Result
Both `main.py` and `utils.py` will have `process_data` replaced with `transform_data` at all reference locations.
## Example 3: Rename with Proof
Generate a machine-checkable proof during rename for audit trail:
```bash
# Generate proof during rename
splice rename \
--symbol <id> \
--file src/utils.rs \
--to new_name \
--proof
# Proof written to .splice/proofs/rename-<timestamp>.json
# Validate proof later
splice validate-proof --proof .splice/proofs/rename-<timestamp>.json
```
### Proof Output
```json
{
"metadata": {
"operation": "rename",
"timestamp": 1736035200,
"splice_version": "2.4.0",
"git_commit": "abc123..."
},
"before": {
"symbols": {
"1a2b3c4d5e6f7g8h": {
"name": "helper_function",
"file_path": "src/utils.rs",
"kind": "function",
"fan_in": 2,
"fan_out": 1
}
}
},
"after": {
"symbols": {
"1a2b3c4d5e6f7g8h": {
"name": "new_name",
"file_path": "src/utils.rs",
"kind": "function",
"fan_in": 2,
"fan_out": 1
}
}
},
"invariants": [
{
"invariant_name": "reference_count_preservation",
"passed": true,
"violations": []
},
{
"invariant_name": "no_orphaned_symbols",
"passed": true,
"violations": []
}
],
"checksums": {
"before_hash": "sha256:...",
"after_hash": "sha256:...",
"proof_hash": "sha256:..."
}
}
```
## Example 4: Handling Ambiguity
When multiple symbols with the same name exist across different files:
### Scenario
You have `helper_function` in both `src/utils.rs` and `src/other.rs`.
```bash
splice rename \
--symbol helper_function \
--file src/utils.rs \
--to new_helper_name
```
### Error Output
```
Error: Multiple symbols found
Please disambiguate:
src/utils.rs:helper_function:function
src/other.rs:helper_function:function
Use symbol ID instead:
splice rename \
--symbol 1a2b3c4d5e6f7g8h \
--file src/utils.rs \
--to new_helper_name
```
### Solution
```bash
# Use the exact symbol ID from find command
splice find --name "helper_function" --path "src/utils.rs"
# Then rename with the ID
splice rename \
--symbol 1a2b3c4d5e6f7g8h \
--file src/utils.rs \
--to new_helper_name
```
## Example 5: Batch Renames with Preview
Before performing multiple renames, use preview mode to verify changes:
```bash
# Preview all renames first
splice rename \
--symbol func_a \
--file src/lib.rs \
--to function_a \
--preview
# Review the diff output
# If satisfied, apply without --preview flag
splice rename \
--symbol func_a \
--file src/lib.rs \
--to function_a
```
## Example 6: Rename in TypeScript Projects
### Setup
**src/utils.ts:**
```typescript
export function calculateTotal(price: number, tax: number): number {
return price + tax;
}
export function displayTotal(total: number): void {
console.log(`Total: ${total}`);
}
```
**src/main.ts:**
```typescript
import { calculateTotal, displayTotal } from './utils';
const total = calculateTotal(100, 10);
displayTotal(total);
```
### Rename
```bash
# Ingest TypeScript files
splice ingest --root ./src --db .magellan/splice.db
# Find and rename
splice find --name "calculateTotal" --path "src/utils.ts"
splice rename \
--symbol <id> \
--file src/utils.ts \
--to computeTotal
```
### Result
Both the export in `utils.ts` and the import in `main.ts` are updated.
## Example 7: Rename Class Names (Java)
### Setup
**Calculator.java:**
```java
public class Calculator {
public int add(int a, int b) {
return a + b;
}
}
**Main.java:**
```java
public class Main {
public static void main(String[] args) {
Calculator calc = new Calculator();
System.out.println(calc.add(5, 3));
}
}
```
### Rename
```bash
splice ingest --root . --db .magellan/splice.db
splice find --name "Calculator" --path "Calculator.java"
splice rename \
--symbol <id> \
--file Calculator.java \
--to MathCalculator
```
## Example 8: CI/CD Integration
### GitHub Actions Workflow
```yaml
name: Rename Validation
on: [pull_request]
jobs:
validate-rename:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Splice
run: cargo install splice
- name: Ingest codebase
run: splice ingest --root ./src --db .magellan/splice.db
- name: Preview rename
run: |
splice rename \
--symbol old_name \
--file src/lib.rs \
--to new_name \
--preview
- name: Validate no breaking changes
run: cargo check
```
## Common Workflows
### Finding Symbol IDs
```bash
# List all symbols in a file
splice query --db .magellan/splice.db --file src/lib.rs
# Find specific symbol by name
splice find --name "my_function" --path "src/lib.rs"
# Get references to understand impact
splice refs --symbol <id> --db .magellan/splice.db
```
### Impact Analysis Before Rename
```bash
# See what will be affected
splice reachable \
--symbol my_function \
--path src/lib.rs \
--max-depth 3 \
--db .magellan/splice.db
# Check for circular dependencies
splice cycles --db .magellan/splice.db
```
### Rollback After Failed Rename
If a rename causes issues, restore from backup:
```bash
# Backups are created automatically at:
# .splice/backups/rename-<timestamp>/
# Restore manually if needed
cp -r .splice/backups/rename-<timestamp>/src/* ./src/
```
## Troubleshooting
### UTF-8 Character Handling
Splice validates UTF-8 boundaries to ensure safe multi-byte character handling:
```bash
# Rename with special characters
splice rename \
--symbol old_name \
--file src/lib.rs \
--to "new_name_with_special_chars"
# UTF-8 validation is automatic
```
### Large Codebases
For large projects, use reachability analysis first:
```bash
# Check impact scope before renaming
splice reachable \
--symbol api_function \
--path src/api.rs \
--max-depth 10 \
--db .magellan/splice.db
# If impact is large, consider phased approach
```
## See Also
- [docs/manual.md](../manual.md) - Complete CLI reference
- [docs/examples/graph_algorithm_examples.md](graph_algorithm_examples.md) - Impact analysis with graph algorithms
- [docs/examples/proof_examples.md](proof_examples.md) - Proof-based refactoring