f6fac6c4bc
Fix bin/publish: use correct .env path for rspade_system Fix bin/publish script: prevent grep exit code 1 from terminating script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
86 lines
3.5 KiB
Markdown
Executable File
86 lines
3.5 KiB
Markdown
Executable File
# 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
|