Initial commit
This commit is contained in:
Zhongwei Li
623
commands/migration-helper.md
Normal file
623
commands/migration-helper.md
Normal file
@@ -0,0 +1,623 @@
|
||||
---
|
||||
allowed-tools: Bash, Read, Write, Edit, Grep, Glob
|
||||
description: ClaudeForge code migration assistant for framework upgrades, version migrations, and codebase transformations.
|
||||
---
|
||||
|
||||
# ClaudeForge Migration Helper
|
||||
|
||||
ClaudeForge intelligent migration system that automates complex framework upgrades, version migrations, and codebase transformations with comprehensive AST analysis, automated codemods, and risk-free migration strategies.
|
||||
|
||||
## Purpose
|
||||
|
||||
Transform framework and version migrations from risky manual refactoring to intelligent, automated processes that ensure code quality, backward compatibility, and minimal downtime across large-scale codebases.
|
||||
|
||||
## Features
|
||||
|
||||
- **Framework Migration**: Automated migration between frameworks (React, Vue, Angular, etc.)
|
||||
- **Version Upgrades**: Intelligent version upgrade paths with breaking change detection
|
||||
- **Codemod Generation**: Custom codemod creation using AST transformations
|
||||
- **Breaking Change Analysis**: Comprehensive detection of breaking changes and deprecations
|
||||
- **Migration Planning**: Risk assessment and phased migration strategy generation
|
||||
- **Rollback Support**: Automated rollback procedures with version control integration
|
||||
- **Testing Integration**: Automated test generation and validation during migration
|
||||
- **Documentation**: Migration guides and change logs with team communication templates
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/migration-helper [migration-type] [options]
|
||||
```
|
||||
|
||||
Target: $ARGUMENTS (if specified, otherwise analyze current project)
|
||||
|
||||
### Migration Commands
|
||||
|
||||
**Framework Version Upgrade:**
|
||||
```bash
|
||||
/migration-helper upgrade --framework=react --from=16.8 --to=18.2
|
||||
```
|
||||
Performs comprehensive version upgrade including:
|
||||
- Breaking change detection and analysis
|
||||
- Deprecated API identification and replacement
|
||||
- New feature adoption recommendations
|
||||
- Package.json dependency updates
|
||||
- Lock file regeneration
|
||||
- Migration script generation with rollback support
|
||||
|
||||
**Framework Migration:**
|
||||
```bash
|
||||
/migration-helper migrate --from=vue2 --to=react --strategy=incremental
|
||||
```
|
||||
Migrates between frameworks with:
|
||||
- Component structure transformation
|
||||
- State management migration (Vuex → Redux/Context)
|
||||
- Template syntax to JSX conversion
|
||||
- Lifecycle method mapping
|
||||
- Router configuration migration
|
||||
- Build tool configuration updates
|
||||
|
||||
**Library Replacement:**
|
||||
```bash
|
||||
/migration-helper replace --library=moment --with=date-fns --preserve-behavior
|
||||
```
|
||||
Replaces libraries maintaining behavior:
|
||||
- API usage pattern detection
|
||||
- Automated code transformation
|
||||
- Test case updates
|
||||
- Import statement rewriting
|
||||
- Type definition updates
|
||||
- Behavior validation tests
|
||||
|
||||
### Codemod Operations
|
||||
|
||||
**Custom Codemod Generation:**
|
||||
```bash
|
||||
/migration-helper codemod --pattern="class components" --transform="functional" --scope=src/
|
||||
```
|
||||
Generates and applies codemods with:
|
||||
- AST-based pattern matching
|
||||
- Safe transformation rules
|
||||
- Dry-run preview with diff output
|
||||
- Selective file application
|
||||
- Transformation validation
|
||||
- Rollback checkpoints
|
||||
|
||||
**AST Transformation:**
|
||||
```bash
|
||||
/migration-helper transform --ast-query="CallExpression[callee.name='require']" --replace-with="import"
|
||||
```
|
||||
Performs AST-level transformations:
|
||||
- Complex syntax tree queries
|
||||
- Multi-file transformations
|
||||
- Scope-aware replacements
|
||||
- Type-safe transformations
|
||||
- Formatting preservation
|
||||
- Comment retention
|
||||
|
||||
**Breaking Change Detection:**
|
||||
```bash
|
||||
/migration-helper analyze --version-from=3.0 --version-to=4.0 --report=detailed
|
||||
```
|
||||
Analyzes breaking changes with:
|
||||
- API signature change detection
|
||||
- Deprecated feature usage scanning
|
||||
- Type incompatibility identification
|
||||
- Runtime behavior changes
|
||||
- Configuration format changes
|
||||
- Impact severity assessment
|
||||
|
||||
### Migration Strategies
|
||||
|
||||
**Incremental Migration:**
|
||||
```bash
|
||||
/migration-helper plan --strategy=incremental --duration=4-weeks --risk-level=low
|
||||
```
|
||||
Creates phased migration plan with:
|
||||
- Module-by-module migration sequence
|
||||
- Dual-version compatibility layer
|
||||
- Feature flag integration
|
||||
- Progressive rollout timeline
|
||||
- Risk mitigation strategies
|
||||
- Team coordination schedule
|
||||
|
||||
**Big Bang Migration:**
|
||||
```bash
|
||||
/migration-helper plan --strategy=big-bang --cutover-date=2024-03-15 --backup-plan
|
||||
```
|
||||
Plans complete migration with:
|
||||
- Comprehensive preparation checklist
|
||||
- Parallel environment setup
|
||||
- Cutover procedure documentation
|
||||
- Rollback decision criteria
|
||||
- Post-migration validation
|
||||
- Emergency response procedures
|
||||
|
||||
**Strangler Fig Pattern:**
|
||||
```bash
|
||||
/migration-helper strangler --routes-first --proxy-config --parallel-run
|
||||
```
|
||||
Implements strangler fig migration:
|
||||
- Route-level migration strategy
|
||||
- Proxy configuration for dual systems
|
||||
- Parallel execution with comparison
|
||||
- Gradual traffic shifting
|
||||
- Legacy system decommissioning plan
|
||||
- Data synchronization strategy
|
||||
|
||||
## Migration Methodologies
|
||||
|
||||
### React Migration Patterns
|
||||
|
||||
**Class to Functional Components:**
|
||||
```javascript
|
||||
// Before: Class component with lifecycle
|
||||
class UserProfile extends React.Component {
|
||||
state = { user: null, loading: true };
|
||||
|
||||
componentDidMount() {
|
||||
this.fetchUser(this.props.userId);
|
||||
}
|
||||
|
||||
componentDidUpdate(prevProps) {
|
||||
if (prevProps.userId !== this.props.userId) {
|
||||
this.fetchUser(this.props.userId);
|
||||
}
|
||||
}
|
||||
|
||||
fetchUser = async (userId) => {
|
||||
const user = await api.getUser(userId);
|
||||
this.setState({ user, loading: false });
|
||||
};
|
||||
|
||||
render() {
|
||||
return this.state.loading ? <Spinner /> : <User data={this.state.user} />;
|
||||
}
|
||||
}
|
||||
|
||||
// After: Functional component with hooks
|
||||
function UserProfile({ userId }) {
|
||||
const [user, setUser] = useState(null);
|
||||
const [loading, setLoading] = useState(true);
|
||||
|
||||
useEffect(() => {
|
||||
let cancelled = false;
|
||||
|
||||
async function fetchUser() {
|
||||
const userData = await api.getUser(userId);
|
||||
if (!cancelled) {
|
||||
setUser(userData);
|
||||
setLoading(false);
|
||||
}
|
||||
}
|
||||
|
||||
fetchUser();
|
||||
return () => { cancelled = true; };
|
||||
}, [userId]);
|
||||
|
||||
return loading ? <Spinner /> : <User data={user} />;
|
||||
}
|
||||
```
|
||||
|
||||
**Context API Migration:**
|
||||
```javascript
|
||||
// Legacy Context API
|
||||
const ThemeContext = React.createContext();
|
||||
|
||||
class ThemeProvider extends React.Component {
|
||||
static childContextTypes = {
|
||||
theme: PropTypes.object
|
||||
};
|
||||
|
||||
getChildContext() {
|
||||
return { theme: this.props.theme };
|
||||
}
|
||||
}
|
||||
|
||||
// Modern Context API
|
||||
const ThemeContext = React.createContext();
|
||||
|
||||
function ThemeProvider({ children, theme }) {
|
||||
return (
|
||||
<ThemeContext.Provider value={theme}>
|
||||
{children}
|
||||
</ThemeContext.Provider>
|
||||
);
|
||||
}
|
||||
|
||||
function useTheme() {
|
||||
const theme = useContext(ThemeContext);
|
||||
if (!theme) throw new Error('useTheme must be used within ThemeProvider');
|
||||
return theme;
|
||||
}
|
||||
```
|
||||
|
||||
### Vue Migration Patterns
|
||||
|
||||
**Vue 2 to Vue 3 Composition API:**
|
||||
```javascript
|
||||
// Vue 2 Options API
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
count: 0,
|
||||
user: null
|
||||
};
|
||||
},
|
||||
|
||||
computed: {
|
||||
doubleCount() {
|
||||
return this.count * 2;
|
||||
}
|
||||
},
|
||||
|
||||
methods: {
|
||||
increment() {
|
||||
this.count++;
|
||||
}
|
||||
},
|
||||
|
||||
async mounted() {
|
||||
this.user = await api.fetchUser();
|
||||
}
|
||||
};
|
||||
|
||||
// Vue 3 Composition API
|
||||
import { ref, computed, onMounted } from 'vue';
|
||||
|
||||
export default {
|
||||
setup() {
|
||||
const count = ref(0);
|
||||
const user = ref(null);
|
||||
|
||||
const doubleCount = computed(() => count.value * 2);
|
||||
|
||||
function increment() {
|
||||
count.value++;
|
||||
}
|
||||
|
||||
onMounted(async () => {
|
||||
user.value = await api.fetchUser();
|
||||
});
|
||||
|
||||
return { count, user, doubleCount, increment };
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Angular Migration Patterns
|
||||
|
||||
**AngularJS to Angular:**
|
||||
```typescript
|
||||
// AngularJS Controller
|
||||
angular.module('app').controller('UserController', function($scope, UserService) {
|
||||
$scope.users = [];
|
||||
|
||||
UserService.getUsers().then(function(users) {
|
||||
$scope.users = users;
|
||||
});
|
||||
|
||||
$scope.deleteUser = function(userId) {
|
||||
UserService.delete(userId).then(function() {
|
||||
$scope.users = $scope.users.filter(u => u.id !== userId);
|
||||
});
|
||||
};
|
||||
});
|
||||
|
||||
// Angular Component
|
||||
@Component({
|
||||
selector: 'app-user-list',
|
||||
template: `
|
||||
<div *ngFor="let user of users$ | async">
|
||||
{{ user.name }}
|
||||
<button (click)="deleteUser(user.id)">Delete</button>
|
||||
</div>
|
||||
`
|
||||
})
|
||||
export class UserListComponent implements OnInit {
|
||||
users$: Observable<User[]>;
|
||||
|
||||
constructor(private userService: UserService) {}
|
||||
|
||||
ngOnInit() {
|
||||
this.users$ = this.userService.getUsers();
|
||||
}
|
||||
|
||||
deleteUser(userId: string) {
|
||||
this.userService.delete(userId).pipe(
|
||||
switchMap(() => this.userService.getUsers())
|
||||
).subscribe(users => this.users$ = of(users));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Codemod Tools Integration
|
||||
|
||||
### jscodeshift Usage
|
||||
|
||||
**Custom Codemod Example:**
|
||||
```javascript
|
||||
// transform-class-to-hooks.js
|
||||
module.exports = function transformer(file, api) {
|
||||
const j = api.jscodeshift;
|
||||
const root = j(file.source);
|
||||
|
||||
// Find class components
|
||||
root.find(j.ClassDeclaration, {
|
||||
superClass: {
|
||||
type: 'MemberExpression',
|
||||
object: { name: 'React' },
|
||||
property: { name: 'Component' }
|
||||
}
|
||||
}).forEach(path => {
|
||||
const componentName = path.value.id.name;
|
||||
|
||||
// Extract state
|
||||
const stateProperties = extractState(path);
|
||||
|
||||
// Extract lifecycle methods
|
||||
const effects = extractEffects(path);
|
||||
|
||||
// Generate functional component
|
||||
const functionalComponent = buildFunctionalComponent(
|
||||
componentName,
|
||||
stateProperties,
|
||||
effects
|
||||
);
|
||||
|
||||
j(path).replaceWith(functionalComponent);
|
||||
});
|
||||
|
||||
return root.toSource({ quote: 'single' });
|
||||
};
|
||||
```
|
||||
|
||||
**Running Codemods:**
|
||||
```bash
|
||||
# Apply transformation
|
||||
npx jscodeshift -t transform-class-to-hooks.js src/components
|
||||
|
||||
# Dry run to preview changes
|
||||
npx jscodeshift -t transform.js src/ --dry --print
|
||||
|
||||
# Transform with TypeScript parser
|
||||
npx jscodeshift -t transform.js src/ --parser=tsx
|
||||
```
|
||||
|
||||
### ts-migrate Integration
|
||||
|
||||
**TypeScript Migration:**
|
||||
```bash
|
||||
# Initialize TypeScript migration
|
||||
npx ts-migrate init
|
||||
|
||||
# Add TypeScript configs
|
||||
npx ts-migrate-server --config-file tsconfig.json
|
||||
|
||||
# Rename files to .ts/.tsx
|
||||
npx ts-migrate rename src/
|
||||
|
||||
# Add @ts-expect-error comments
|
||||
npx ts-migrate migrate src/
|
||||
|
||||
# Run type checking and fix
|
||||
npx tsc --noEmit && npx ts-migrate reignore src/
|
||||
```
|
||||
|
||||
### AST Explorer Integration
|
||||
|
||||
**Interactive Transformation Development:**
|
||||
- Real-time AST visualization at astexplorer.net
|
||||
- Test transformations before production use
|
||||
- Support for multiple parsers (babel, typescript, flow)
|
||||
- jscodeshift template generation
|
||||
- Share transformations with team
|
||||
|
||||
## Migration Planning Framework
|
||||
|
||||
### Risk Assessment Matrix
|
||||
|
||||
**Risk Categories:**
|
||||
```
|
||||
High Risk:
|
||||
- Breaking changes in core dependencies
|
||||
- Major framework version jumps (e.g., React 16 → 18)
|
||||
- Database schema migrations
|
||||
- Authentication/security changes
|
||||
- Payment processing updates
|
||||
|
||||
Medium Risk:
|
||||
- Minor version upgrades with deprecations
|
||||
- State management library changes
|
||||
- Build tool migrations
|
||||
- UI library updates
|
||||
- Testing framework changes
|
||||
|
||||
Low Risk:
|
||||
- Patch version updates
|
||||
- Development dependency updates
|
||||
- Code style/linting changes
|
||||
- Documentation updates
|
||||
- Internal utility refactoring
|
||||
```
|
||||
|
||||
### Migration Checklist
|
||||
|
||||
**Pre-Migration Phase:**
|
||||
- [ ] Comprehensive test coverage (minimum 80%)
|
||||
- [ ] Feature freeze on affected modules
|
||||
- [ ] Full database backup and restore test
|
||||
- [ ] Dependency audit and vulnerability scan
|
||||
- [ ] Performance baseline measurements
|
||||
- [ ] Rollback procedure documentation
|
||||
- [ ] Team training and knowledge transfer
|
||||
- [ ] Communication plan to stakeholders
|
||||
|
||||
**Migration Phase:**
|
||||
- [ ] Branch protection and code freeze
|
||||
- [ ] Automated migration script execution
|
||||
- [ ] Incremental commit strategy
|
||||
- [ ] Continuous integration pipeline validation
|
||||
- [ ] Manual QA testing of critical paths
|
||||
- [ ] Performance regression testing
|
||||
- [ ] Security vulnerability scanning
|
||||
- [ ] Documentation updates
|
||||
|
||||
**Post-Migration Phase:**
|
||||
- [ ] Production deployment with canary release
|
||||
- [ ] Real-time monitoring and alerting
|
||||
- [ ] User acceptance testing
|
||||
- [ ] Performance comparison with baseline
|
||||
- [ ] Legacy code cleanup
|
||||
- [ ] Post-mortem and lessons learned
|
||||
- [ ] Knowledge base article creation
|
||||
- [ ] Celebration of successful migration
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Automated Testing
|
||||
|
||||
**Migration Test Suite:**
|
||||
```javascript
|
||||
describe('Migration: Class to Hooks', () => {
|
||||
it('preserves component behavior', () => {
|
||||
const { container: before } = render(<ClassComponent />);
|
||||
const { container: after } = render(<HooksComponent />);
|
||||
expect(before.innerHTML).toBe(after.innerHTML);
|
||||
});
|
||||
|
||||
it('maintains state management', () => {
|
||||
const { getByText } = render(<HooksComponent />);
|
||||
fireEvent.click(getByText('Increment'));
|
||||
expect(getByText('Count: 1')).toBeInTheDocument();
|
||||
});
|
||||
|
||||
it('handles lifecycle equivalents', async () => {
|
||||
const fetchMock = jest.fn().mockResolvedValue({ data: 'test' });
|
||||
render(<HooksComponent fetch={fetchMock} />);
|
||||
await waitFor(() => expect(fetchMock).toHaveBeenCalled());
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
**Visual Regression Testing:**
|
||||
```javascript
|
||||
// Chromatic integration
|
||||
describe('Visual Regression', () => {
|
||||
it('matches previous component appearance', async () => {
|
||||
await page.goto('http://localhost:6006/iframe.html?id=migrated-component');
|
||||
const screenshot = await page.screenshot();
|
||||
expect(screenshot).toMatchImageSnapshot({
|
||||
failureThreshold: 0.01,
|
||||
failureThresholdType: 'percent'
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Manual Testing Guides
|
||||
|
||||
**Critical Path Testing:**
|
||||
```markdown
|
||||
## User Authentication Flow
|
||||
1. Navigate to login page
|
||||
2. Enter valid credentials
|
||||
3. Verify redirect to dashboard
|
||||
4. Check user profile information
|
||||
5. Test logout functionality
|
||||
|
||||
## Payment Processing
|
||||
1. Add items to cart
|
||||
2. Proceed to checkout
|
||||
3. Enter payment information
|
||||
4. Verify payment confirmation
|
||||
5. Check order history
|
||||
|
||||
## Data Export Feature
|
||||
1. Navigate to export page
|
||||
2. Select date range
|
||||
3. Choose export format
|
||||
4. Download file
|
||||
5. Verify file contents
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions Migration Workflow
|
||||
|
||||
```yaml
|
||||
name: Framework Migration
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
migration_type:
|
||||
description: 'Migration type'
|
||||
required: true
|
||||
type: choice
|
||||
options:
|
||||
- react-upgrade
|
||||
- vue-migration
|
||||
- angular-update
|
||||
|
||||
jobs:
|
||||
migrate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Setup Node.js
|
||||
uses: actions/setup-node@v3
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: Create migration branch
|
||||
run: |
|
||||
git checkout -b migration/${{ github.event.inputs.migration_type }}-$(date +%Y%m%d)
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
- name: Run migration scripts
|
||||
run: npm run migrate:${{ github.event.inputs.migration_type }}
|
||||
|
||||
- name: Run tests
|
||||
run: npm test
|
||||
|
||||
- name: Build project
|
||||
run: npm run build
|
||||
|
||||
- name: Commit changes
|
||||
run: |
|
||||
git config user.name "Migration Bot"
|
||||
git config user.email "bot@example.com"
|
||||
git add .
|
||||
git commit -m "chore: automated migration - ${{ github.event.inputs.migration_type }}"
|
||||
|
||||
- name: Create pull request
|
||||
uses: peter-evans/create-pull-request@v5
|
||||
with:
|
||||
title: "Migration: ${{ github.event.inputs.migration_type }}"
|
||||
body: |
|
||||
## Automated Migration
|
||||
|
||||
Migration type: ${{ github.event.inputs.migration_type }}
|
||||
Date: $(date)
|
||||
|
||||
### Changes
|
||||
- Framework/library updates
|
||||
- Code transformations via codemods
|
||||
- Test suite updates
|
||||
|
||||
### Testing Required
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tests pass
|
||||
- [ ] Manual QA complete
|
||||
- [ ] Performance benchmarks reviewed
|
||||
branch: migration/${{ github.event.inputs.migration_type }}-$(date +%Y%m%d)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**ClaudeForge Migration Helper** - Intelligent framework migration with automated codemods, comprehensive testing, and risk-free transformation strategies for modern development teams.
|
||||
Reference in New Issue
Block a user