# Upstream Refactor Tracking System

## Purpose

This system tracks framework refactoring operations (class renames, method renames) performed on files in `/app/RSpade` so that when users update their framework copy, these refactors can be automatically applied to their RSX application code.

## How It Works

### Recording Refactors (Current Implementation)

When framework developers execute refactoring commands that modify files in `/app/RSpade`:

- `rsx:refactor:rename_php_class OldClass NewClass`
- `rsx:refactor:rename_php_class_function ClassName old_method new_method`

The command calls `UpstreamRefactorLog::log_refactor()` which:

1. Records the full command to a `refactor.list` file in the same directory as the refactored file
2. Includes timestamp for tracking when the refactor was performed
3. Only logs refactors for files in `app/RSpade/` (framework code, not user code)

Example `refactor.list` file in `/app/RSpade/Core/`:
```
[2025-10-07 02:00:00] rsx:refactor:rename_php_class Old_Manifest New_Manifest
[2025-10-07 02:15:30] rsx:refactor:rename_php_class_function Rsx get_route get_current_route
```

### Applying Refactors (Future Implementation)

**Command**: `php artisan rsx:refactor:apply_upstream_refactors`

This command will:

1. **Scan all `refactor.list` files** in `/app/RSpade` directories
2. **Read previously applied refactors** from `/rsx/.upstream_refactors.list`
3. **Diff the operations** to find new refactors that haven't been applied yet
4. **Execute each new refactor** with a special `--rsx-only` flag that:
   - Only modifies files in `/rsx/` directory (user application code)
   - Does NOT modify the source class in `/app/RSpade/`
   - Does NOT modify other framework files
5. **Record executed refactors** to `/rsx/.upstream_refactors.list`
6. **Commit to git** so changes persist across framework updates

### Example Workflow

**Framework Developer** (working in `/app/RSpade`):
```bash
# Rename a core framework class
php artisan rsx:refactor:rename_php_class Old_Controller New_Controller

# This automatically logs to /app/RSpade/Core/Controller/refactor.list:
# [2025-10-07 02:00:00] rsx:refactor:rename_php_class Old_Controller New_Controller
```

**End User** (after pulling framework update):
```bash
# Apply all new framework refactors to their application
php artisan rsx:refactor:apply_upstream_refactors

# Command finds new refactor operations in app/RSpade/*/refactor.list
# Applies them ONLY to files in /rsx/ directory
# Records applied operations to /rsx/.upstream_refactors.list
```

## File Locations

- **Refactor logs**: `/app/RSpade/{directory}/refactor.list` (distributed with framework)
- **Applied refactors**: `/rsx/.upstream_refactors.list` (user-specific, committed to user's git)
- **Implementation**: `/app/RSpade/UpstreamRefactorLog.php`

## Benefits

1. **Seamless framework updates** - Users automatically get class/method renames applied to their code
2. **No breaking changes** - Refactors are applied incrementally as users update
3. **Trackable history** - Both framework and user have logs of what was refactored
4. **Git-friendly** - Applied refactors are committed, preventing re-application
5. **Safe isolation** - Framework refactors never touch user code until explicitly applied

## Future Enhancements

- `--dry-run` flag to preview refactors before applying
- `--skip` flag to skip specific refactors
- `--force` flag to re-apply already-applied refactors
- Conflict detection when user has customized framework classes
- Rollback capability for problematic refactors