SplitRS 🦀✂️

A production-ready Rust refactoring tool that intelligently splits large files into maintainable modules

SplitRS uses AST-based analysis to automatically refactor large Rust source files (>1000 lines) into well-organized, compilable modules. It handles complex generics, async functions, Arc/Mutex patterns, and automatically generates correct imports and visibility modifiers.

✨ Features

Core Refactoring

• 🎯 AST-Based Refactoring: Uses syn for accurate Rust parsing
• 🧠 Intelligent Method Clustering: Groups related methods using call graph analysis
• 📦 Auto-Generated Imports: Context-aware use statements with proper paths
• 🔒 Visibility Inference: Automatically applies pub(super), pub(crate), or pub
• 🚀 Complex Type Support: Handles generics, async, Arc/Mutex, nested types
• ⚡ Fast: Processes 1600+ line files in <1 second
• ✅ Production-Tested: Successfully refactored 10,000+ lines of real code

Advanced Features (v0.2.0+)

• ⚙️ Configuration Files: .splitrs.toml support for project-specific settings
• 🎭 Trait Implementation Support: Automatic separation of trait impls into dedicated modules
• 🔗 Type Alias Resolution: Intelligent handling of type aliases in import generation
• 🔍 Circular Dependency Detection: DFS-based cycle detection with Graphviz export
• 👀 Enhanced Preview Mode: Beautiful formatted preview with statistics before refactoring
• 💬 Interactive Mode: Confirmation prompts before file generation
• 🔄 Automatic Rollback Support: Backup creation for safe refactoring
• 📝 Smart Documentation: Auto-generated module docs with trait listings

v0.3.x Features

• 🔬 Macro Analyzer: Detects macro_rules! definitions and #[derive] usage with placement suggestions
• 📊 Metrics Dashboard: Cyclomatic complexity analysis with HTML/JSON/text reports (--metrics)
• 🗂️ Field Access Tracker: Detects field access patterns to prevent broken visibility during splits
• 🔗 Trait Method Tracker: Ensures trait method implementations stay coherent after splitting
• 🖥️ LSP Integration (splitrs-lsp): Language server for real-time refactoring guidance
  • Diagnostics for oversized files and impl blocks
  • Code action Refactor with splitrs (applies a WorkspaceEdit)
  • Hover showing file metrics (LoC, methods, complexity)
  • .splitrs.toml config watch with hot reload

📦 Installation

cargo install splitrs

Or build from source:

git clone https://github.com/cool-japan/splitrs
cd splitrs
cargo build --release

🚀 Quick Start

Basic Usage

# Split a large file into modules
splitrs --input src/large_file.rs --output src/large_file/

# Preview what will be created (no files written)
splitrs --input src/large_file.rs --output src/large_file/ --dry-run

# Interactive mode with confirmation
splitrs --input src/large_file.rs --output src/large_file/ --interactive

Recommended Usage (with impl block splitting)

splitrs \
  --input src/large_file.rs \
  --output src/large_file/ \
  --split-impl-blocks \
  --max-impl-lines 200

Using Configuration Files

Create a .splitrs.toml in your project root:

[splitrs]
max_lines = 1000
max_impl_lines = 500
split_impl_blocks = true

[naming]
type_module_suffix = "_type"
impl_module_suffix = "_impl"

[output]
preserve_comments = true
format_output = true

Then simply run:

splitrs --input src/large_file.rs --output src/large_file/

LSP Integration (Editor Support)

splitrs-lsp is included when you cargo install splitrs (LSP is a default feature).

Add to your editor's LSP config:

Neovim (nvim-lspconfig):

require('lspconfig').splitrs_lsp.setup{}
-- Or manually:
vim.lsp.start({ name = 'splitrs-lsp', cmd = { 'splitrs-lsp' } })

Helix (languages.toml):

[[language]]
name = "rust"
language-servers = ["rust-analyzer", "splitrs-lsp"]

[language-server.splitrs-lsp]
command = "splitrs-lsp"

The LSP server provides:

• 🔴 Diagnostics when files exceed your .splitrs.toml max_lines limit
• ⚡ Code action Refactor with splitrs to split directly from your editor
• ℹ️ Hover at line 1 showing file metrics

To use LSP-only build without the full CLI:

cargo install splitrs --no-default-features --features lsp

📖 Examples

Example 1: Trait Implementations

SplitRS automatically detects and separates trait implementations:

Input: user.rs

pub struct User {
    pub name: String,
    pub age: u32,
}

impl User {
    pub fn new(name: String, age: u32) -> Self { /* ... */ }
}

impl Debug for User { /* ... */ }
impl Display for User { /* ... */ }
impl Clone for User { /* ... */ }
impl Default for User { /* ... */ }

Command:

splitrs --input user.rs --output user/ --dry-run

Output:

user/
├── types.rs         # struct User definition + inherent impl
├── user_traits.rs   # All trait implementations (Debug, Display, Clone, Default)
└── mod.rs          # Module organization

Generated user_traits.rs:

//! # User - Trait Implementations
//!
//! This module contains trait implementations for `User`.
//!
//! ## Implemented Traits
//!
//! - `Debug`
//! - `Display`
//! - `Clone`
//! - `Default`
//!
//! 🤖 Generated with [SplitRS](https://github.com/cool-japan/splitrs)

use super::types::User;

impl Debug for User { /* ... */ }
impl Display for User { /* ... */ }
impl Clone for User { /* ... */ }
impl Default for User { /* ... */ }

Example 2: Basic Refactoring

Input: connection_pool.rs (1660 lines)

pub struct ConnectionPool<T> {
    connections: Arc<Mutex<Vec<T>>>,
    config: PoolConfig,
    // ... 50 fields
}

impl<T: Clone + Send + Sync> ConnectionPool<T> {
    pub fn new(config: PoolConfig) -> Self { ... }
    pub async fn acquire(&self) -> Result<T> { ... }
    pub async fn release(&self, conn: T) -> Result<()> { ... }
    // ... 80 methods
}

Command:

splitrs --input connection_pool.rs --output connection_pool/ --split-impl-blocks

Output: 25 well-organized modules

connection_pool/
├── mod.rs                          # Module organization & re-exports
├── connectionpool_type.rs          # Type definition with proper visibility
├── connectionpool_new_group.rs     # Constructor methods
├── connectionpool_acquire_group.rs # Connection acquisition
├── connectionpool_release_group.rs # Connection release
└── ... (20 more focused modules)

Example 3: Preview Mode

Get detailed information before refactoring:

splitrs --input examples/trait_impl_example.rs --output /tmp/preview -n

Output:

============================================================
DRY RUN - Preview Mode
============================================================

📊 Statistics:
  Original file: 82 lines
  Total modules to create: 4

📁 Module Structure:
  📄 product_traits.rs (2 trait impls)
  📄 user_traits.rs (4 trait impls)
  📄 types.rs (2 types)
  📄 functions.rs (1 items)

💾 Files that would be created:
  📁 /tmp/preview/
    📄 product_traits.rs
    📄 user_traits.rs
    📄 types.rs
    📄 functions.rs
    📄 mod.rs

============================================================
✓ Preview complete - no files were created
============================================================

Example 4: Complex Types

SplitRS correctly handles complex Rust patterns:

// Input
pub struct Cache<K, V>
where
    K: Hash + Eq + Clone,
    V: Clone + Send + Sync + 'static,
{
    data: Arc<RwLock<HashMap<K, V>>>,
    eviction: EvictionPolicy,
}

// Output (auto-generated)
// cache_type.rs
use std::collections::HashMap;
use std::sync::{Arc, RwLock};

pub struct Cache<K, V>
where
    K: Hash + Eq + Clone,
    V: Clone + Send + Sync + 'static,
{
    pub(super) data: Arc<RwLock<HashMap<K, V>>>,
    pub(super) eviction: EvictionPolicy,
}

// cache_insert_group.rs
use super::cache_type::Cache;
use std::collections::HashMap;

impl<K, V> Cache<K, V>
where
    K: Hash + Eq + Clone,
    V: Clone + Send + Sync + 'static,
{
    pub async fn insert(&mut self, key: K, value: V) -> Result<()> {
        // ... implementation
    }
}

🎛️ Command-Line Options

Option	Short	Description	Default
--input <FILE>	-i	Input Rust source file (required)	-
--output <DIR>	-o	Output directory for modules (required)	-
--max-lines <N>	-m	Maximum lines per module	1000
--split-impl-blocks		Split large impl blocks into method groups	false
--max-impl-lines <N>		Maximum lines per impl block before splitting	500
--dry-run	-n	Preview without creating files	false
--interactive	-I	Prompt for confirmation before creating files	false
--config <FILE>	-c	Path to configuration file	.splitrs.toml

Configuration File Options

When using a .splitrs.toml file, you can configure:

[splitrs] section:

• max_lines - Maximum lines per module
• max_impl_lines - Maximum lines per impl block
• split_impl_blocks - Enable impl block splitting

[naming] section:

• type_module_suffix - Suffix for type modules (default: "_type")
• impl_module_suffix - Suffix for impl modules (default: "_impl")
• use_snake_case - Use snake_case for module names (default: true)

[output] section:

• module_doc_template - Template for module documentation
• preserve_comments - Preserve original comments (default: true)
• format_output - Format with prettyplease (default: true)

Command-line arguments always override configuration file settings.

🏗️ How It Works

SplitRS uses a multi-stage analysis pipeline:

1. AST Parsing: Parse input file with syn
2. Scope Analysis: Determine organization strategy and visibility
3. Method Clustering: Build call graph and cluster related methods
4. Type Extraction: Extract types from fields for import generation
5. Module Generation: Generate well-organized modules with correct imports
6. Code Formatting: Format output with prettyplease

Organization Strategies

Inline - Keep impl blocks with type definition:

typename_module.rs
  ├── struct TypeName { ... }
  └── impl TypeName { ... }

Submodule - Split type and impl blocks (recommended for large files):

typename_type.rs       # Type definition
typename_new_group.rs  # Constructor methods
typename_getters.rs    # Getter methods
mod.rs                 # Module organization

Wrapper - Wrap in parent module:

typename/
  ├── type.rs
  ├── methods.rs
  └── mod.rs

📊 Performance

Tested on real-world codebases:

File Size	Lines	Time	Modules Generated
Small	500-1000	<100ms	3-5
Medium	1000-1500	<500ms	5-12
Large	1500-2000	<1s	10-25
Very Large	2000+	<2s	25-40

🧪 Testing

SplitRS includes 269 comprehensive tests covering all analysis components:

# Run all tests (recommended)
cargo nextest run --all-features

# Or with the built-in test runner
cargo test --all-features

# Test on example files
cargo run -- --input examples/large_struct.rs --output /tmp/test_output

📚 Documentation

API Documentation (docs.rs)

Full API documentation is available at docs.rs/splitrs.

Generate documentation locally:

# Generate and open documentation
cargo doc --no-deps --open

# Generate documentation for all features
cargo doc --all-features --no-deps

Module Structure

The codebase is organized into these main modules:

• main.rs - CLI interface, file analysis, and module generation
• config.rs - Configuration file parsing and management (.splitrs.toml)
• method_analyzer.rs - Method dependency analysis and grouping
• import_analyzer.rs - Type usage tracking and import generation
• scope_analyzer.rs - Module scope analysis and visibility inference
• dependency_analyzer.rs - Circular dependency detection and graph visualization

Key Types and Traits

Core Types:

• FileAnalyzer - Main analyzer for processing Rust files
• TypeInfo - Information about a Rust type and its implementations
• Module - Represents a generated module
• Config - Configuration loaded from .splitrs.toml

Analysis Types:

• ImplBlockAnalyzer - Analyzes impl blocks for splitting
• MethodGroup - Groups related methods together
• ImportAnalyzer - Tracks type usage and generates imports
• DependencyGraph - Detects circular dependencies

📚 Use Cases

When to Use SplitRS

✅ Perfect for:

• Files >1000 lines with large impl blocks
• Monolithic modules that need organization
• Legacy code refactoring
• Improving code maintainability

⚠️ Consider Carefully:

• Files with circular dependencies (will generate modules but may need manual fixes)
• Files with heavy macro usage (basic support, may need manual review)

❌ Not Recommended:

• Files <500 lines (probably already well-organized)
• Files with complex conditional compilation (#[cfg])

🔧 Integration

CI/CD Pipeline

# .github/workflows/refactor.yml
name: Auto-refactor
on:
  workflow_dispatch:
    inputs:
      file:
        description: 'File to refactor'
        required: true

jobs:
  refactor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - run: cargo install splitrs
      - run: |
          splitrs --input ${{ github.event.inputs.file }} \
                  --output $(dirname ${{ github.event.inputs.file }})/refactored \
                  --split-impl-blocks
      - uses: peter-evans/create-pull-request@v5
        with:
          title: "Refactor: Split ${{ github.event.inputs.file }}"

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/cool-japan/splitrs
cd splitrs
cargo build
cargo test

Implemented Features (v0.3.1 - Latest)

v0.3.1 Highlights:

• ✅ LSP Integration (splitrs-lsp binary, tower-lsp, diagnostics, code actions, hover, config watch)
• ✅ Batched trait implementations into shared modules to reduce file clutter
• ✅ Accurate line count estimation via prettyplease formatting
• ✅ Conditional lib.rs preservation (writes mod.rs instead of overwriting the crate root)
• ✅ Deduplicated std::collections import handling across split modules

v0.3.0 Highlights:

• ✅ Macro Analyzer (macro_rules! detection, #[derive] tracking, placement suggestions)
• ✅ Metrics Dashboard (cyclomatic complexity, HTML/JSON/text reports)
• ✅ Field access tracking for smarter module splitting
• ✅ Trait method tracking for coherent trait splitting
• ✅ No-unwrap policy compliance (production code)
• ✅ Refactored main.rs into file_analyzer.rs + module_generator.rs
• ✅ Dependencies upgraded (toml 1.0, rayon 1.11)

v0.2.x Features:

• ✅ Configuration file support (.splitrs.toml)
• ✅ Trait implementation separation & trait bound tracking
• ✅ Type alias resolution & circular dependency detection
• ✅ Incremental refactoring with merge strategies
• ✅ Custom naming strategies (snake_case, domain-specific, kebab-case)
• ✅ Workspace-level refactoring with parallel processing (rayon)
• ✅ Enhanced error recovery, rollback support
• ✅ CI/CD templates (GitHub Actions, GitLab CI)
• ✅ Private helper dependency tracking & glob import analysis
• ✅ Comprehensive benchmarking suite (Criterion)

Roadmap to v1.0

Current status: 95% production-ready

Next features (v0.4.0+):

• Macro expansion support (full cargo expand integration)
• Editor plugins (VS Code extension, IntelliJ plugin)

Future enhancements (v0.5.0+):

• Cross-language support exploration
• AI-assisted refactoring

📄 License

Licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).

🙏 Acknowledgments

• Built with syn for Rust parsing
• Formatted with prettyplease
• Developed during the OxiRS refactoring project (32,398 lines refactored)

📞 Resources & Support

• 📖 API Documentation: docs.rs/splitrs
• 📦 Crate: crates.io/crates/splitrs
• 💻 Source Code: github.com/cool-japan/splitrs
• 🐛 Issue Tracker: github.com/cool-japan/splitrs/issues
• 💬 Discussions: github.com/cool-japan/splitrs/discussions

Getting Help

1. Check the docs: Read the API documentation and examples
2. Search issues: Check if your question is already answered in issues
3. Ask questions: Start a discussion
4. Report bugs: Open an issue with a reproducible example

---

Made with ❤️ by the OxiRS team | Star ⭐ us on GitHub!

Sponsorship

SplitRS is developed and maintained by COOLJAPAN OU (Team Kitasan).

If you find SplitRS useful, please consider sponsoring the project to support continued development of the Pure Rust ecosystem.

https://github.com/sponsors/cool-japan

Your sponsorship helps us:

• Maintain and improve the COOLJAPAN ecosystem
• Keep the entire ecosystem (OxiBLAS, OxiFFT, SciRS2, etc.) 100% Pure Rust
• Provide long-term support and security updates