# 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

```yaml
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

```yaml
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

```yaml
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

```yaml
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:

```yaml
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:

```yaml
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:

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

## Configuration Validation

Configurations are validated on load:

```rust
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:

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

## Creating Custom Configurations

### Project-Level Configuration

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

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

```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](./Refactoring-Engine.md) - Main refactoring guide
- [Refactoring-Architecture.md](./Refactoring-Architecture.md) - Architecture documentation
- [Refactoring-Patterns.md](./Refactoring-Patterns.md) - Pattern guide

---

*Last updated: December 5, 2025*