Refactoring Configuration

Refactoring Configuration Guide

Status: ✅ Complete

Last Updated: December 5, 2025

---

Overview

The Refactoring Engine uses YAML configuration files to define language-specific refactoring rules and transformations. This enables unlimited language support without code changes.

Configuration Hierarchy

Configurations are loaded in priority order (highest to lowest):

1. Runtime Overrides - CLI flags, API calls
2. Project-Level Config - ./.agent/refactoring/languages/*.yaml
3. User-Level Config - ~/.ricecoder/refactoring/languages/*.yaml
4. Built-in Config - Bundled with ricecoder-storage
5. Fallback - Generic text-based refactoring

Configuration File Format

Basic Structure

language: rust
extensions:
  - .rs
parser_plugin: tree-sitter-rust

rules:
  - name: "unused_variable"
    pattern: "let \\w+ = .*;"
    refactoring_type: "RemoveUnused"
    enabled: true

transformations:
  - name: "rename_function"
    from_pattern: "fn old_name"
    to_pattern: "fn new_name"
    description: "Rename function from old_name to new_name"

Configuration Fields

Top-Level Fields

Field	Type	Required	Description
language	string	Yes	Language name (e.g., "rust", "typescript", "python")
extensions	array	Yes	File extensions for this language (e.g., [".rs", ".toml"])
parser_plugin	string	No	Tree-sitter parser plugin name
rules	array	No	Refactoring rules for this language
transformations	array	No	Transformation patterns
provider	string	No	Reference to external provider

Rule Fields

Field	Type	Required	Description
name	string	Yes	Rule name (unique within language)
pattern	string	Yes	Pattern to match (regex or AST pattern)
refactoring_type	string	Yes	Type of refactoring (Rename, Extract, Inline, etc.)
enabled	boolean	No	Whether rule is enabled (default: true)
description	string	No	Rule description

Transformation Fields

Field	Type	Required	Description
name	string	Yes	Transformation name
from_pattern	string	Yes	Pattern to match
to_pattern	string	Yes	Replacement pattern
description	string	No	Transformation description

Language-Specific Examples

Rust Configuration

language: rust
extensions:
  - .rs
parser_plugin: tree-sitter-rust

rules:
  - name: "unused_variable"
    pattern: "let \\w+ = .*;"
    refactoring_type: "RemoveUnused"
    enabled: true
  
  - name: "unused_import"
    pattern: "use \\w+;"
    refactoring_type: "RemoveUnused"
    enabled: true

transformations:
  - name: "rename_function"
    from_pattern: "fn {{old_name}}"
    to_pattern: "fn {{new_name}}"
    description: "Rename function"
  
  - name: "extract_method"
    from_pattern: "// Extract this block"
    to_pattern: "self.extracted_method()"
    description: "Extract code block into separate method"

TypeScript Configuration

language: typescript
extensions:
  - .ts
  - .tsx
parser_plugin: tree-sitter-typescript

rules:
  - name: "unused_variable"
    pattern: "let \\w+ = .*;"
    refactoring_type: "RemoveUnused"
    enabled: true
  
  - name: "unused_import"
    pattern: "import .* from .*;"
    refactoring_type: "RemoveUnused"
    enabled: true

transformations:
  - name: "rename_function"
    from_pattern: "function {{old_name}}"
    to_pattern: "function {{new_name}}"
    description: "Rename function"
  
  - name: "rename_class"
    from_pattern: "class {{old_name}}"
    to_pattern: "class {{new_name}}"
    description: "Rename class"

Python Configuration

language: python
extensions:
  - .py
parser_plugin: tree-sitter-python

rules:
  - name: "unused_variable"
    pattern: "\\w+ = .*"
    refactoring_type: "RemoveUnused"
    enabled: true
  
  - name: "unused_import"
    pattern: "import \\w+"
    refactoring_type: "RemoveUnused"
    enabled: true

transformations:
  - name: "rename_function"
    from_pattern: "def {{old_name}}"
    to_pattern: "def {{new_name}}"
    description: "Rename function"
  
  - name: "rename_class"
    from_pattern: "class {{old_name}}"
    to_pattern: "class {{new_name}}"
    description: "Rename class"

Pattern Syntax

Regex Patterns

Use standard regex syntax for text-based matching:

transformations:
  - name: "rename_variable"
    from_pattern: "let (\\w+) ="
    to_pattern: "let new_name ="
    description: "Rename variable"

AST Patterns

Use tree-sitter AST patterns for structural matching:

transformations:
  - name: "extract_method"
    from_pattern: "(function_declaration name: (identifier) @name)"
    to_pattern: "extracted_method"
    description: "Extract method"

Placeholders

Use double-brace placeholders for parameterized patterns:

transformations:
  - name: "rename_function"
    from_pattern: "fn {{old_name}}"
    to_pattern: "fn {{new_name}}"
    description: "Rename function"

Configuration Validation

Configurations are validated on load:

let config = ConfigManager::load_language_config("rust").await?;
config.validate()?;

Validation checks:

• Language name is not empty
• Extensions list is not empty
• Rules have valid patterns
• Transformations have valid patterns
• No duplicate rule names
• No duplicate transformation names

Hot-Reload

Configuration changes are detected and reloaded automatically:

let config_manager = ConfigManager::new();
// Configuration changes are automatically detected and reloaded

Creating Custom Configurations

Project-Level Configuration

Create ./.agent/refactoring/languages/custom.yaml:

language: custom
extensions:
  - .custom
rules:
  - name: "custom_rule"
    pattern: "pattern"
    refactoring_type: "Rename"
    enabled: true

User-Level Configuration

Create ~/.ricecoder/refactoring/languages/custom.yaml:

language: custom
extensions:
  - .custom
rules:
  - name: "custom_rule"
    pattern: "pattern"
    refactoring_type: "Rename"
    enabled: true

Troubleshooting

Configuration Not Loading

1. Check file path is correct
2. Verify YAML syntax is valid
3. Check file permissions
4. Review logs for error messages

Rules Not Applied

1. Verify rule is enabled
2. Check pattern matches your code
3. Verify language is detected correctly
4. Check file extension is in configuration

Performance Issues

1. Simplify patterns to reduce matching time
2. Disable unused rules
3. Use specific patterns instead of broad ones
4. Consider breaking large configurations into smaller ones

See Also

• Refactoring-Engine.md - Main refactoring guide
• Refactoring-Architecture.md - Architecture documentation
• Refactoring-Patterns.md - Pattern guide

---

Last updated: December 5, 2025