Forge Migration Examples

This directory contains example migrations demonstrating the capabilities of the Forge code migration engine. Each example includes before and after code samples showing real-world migration scenarios.

Directory Structure

examples/
├── README.md                                    # This file
├── <migration-name>/
│   ├── README.md                                # Example-specific documentation
│   ├── before/                                  # Original source code
│   │   └── ...
│   ├── after/                                   # Migrated code
│   │   └── ...
│   ├── forge.config.toml                        # Migration configuration
│   └── migration-report.md                      # Generated migration report

Available Examples

Java Migrations

Example	Description	Complexity
java8-spring-to-java21	Spring Boot app from Java 8 to Java 21	Medium
java11-to-java21	Incremental update from Java 11 LTS	Low
javax-to-jakarta	Jakarta EE namespace migration	Low

Cross-Language Migrations

Example	Description	Complexity
php-laravel-to-typescript	Laravel app to TypeScript/Express	High
python-flask-to-typescript	Flask app to TypeScript/Express	High
ruby-rails-to-typescript	Rails app to TypeScript/NestJS	Very High

Frontend Migrations

Example	Description	Complexity
angular-to-react	Angular 12+ to React 18	Very High
vue2-to-vue3	Vue 2 Options API to Vue 3 Composition API	Medium
javascript-to-typescript	Plain JS to TypeScript	Medium

Running Examples

Quick Start

# Navigate to an example
cd examples/java8-spring-to-java21

# Run the migration in dry-run mode
forge migrate --config forge.config.toml --dry-run

# View the diff
forge migrate --config forge.config.toml --diff

# Execute the migration
forge migrate --config forge.config.toml --output ./output

Comparing Results

# Compare your migration output with the expected 'after' directory
forge compare ./output ./after

# Generate a detailed diff report
forge compare ./output ./after --report migration-diff.html

Example Walkthrough

1. Java 8 to Java 21 Migration

This example demonstrates modernizing a Spring Boot application:

Before (Java 8):

public List<User> findActiveUsers(List<User> users) {
    List<User> result = new ArrayList<>();
    for (User user : users) {
        if (user.isActive()) {
            result.add(user);
        }
    }
    return result;
}

After (Java 21):

public List<User> findActiveUsers(List<User> users) {
    return users.stream()
        .filter(User::isActive)
        .toList();
}

Key transformations:

• ✅ Loops → Stream API
• ✅ Anonymous classes → Lambdas
• ✅ Date/Calendar → java.time
• ✅ Data classes → Records
• ✅ instanceof checks → Pattern matching
• ✅ String concatenation → Text blocks
• ✅ Switch statements → Switch expressions

2. PHP Laravel to TypeScript Migration

This example demonstrates converting a Laravel REST API:

Before (PHP/Laravel):

public function index(Request $request): JsonResponse
{
    $users = User::where('active', true)
        ->orderBy('created_at', 'desc')
        ->paginate(15);
    
    return response()->json($users);
}

After (TypeScript/Express):

async index(req: Request, res: Response): Promise<void> {
    const users = await prisma.user.findMany({
        where: { active: true },
        orderBy: { createdAt: 'desc' },
        take: 15,
        skip: (req.query.page as number - 1) * 15,
    });
    
    res.json(users);
}

Key transformations:

• ✅ PHP types → TypeScript types
• ✅ Eloquent ORM → Prisma ORM
• ✅ Laravel routing → Express routes
• ✅ Form requests → Zod validators
• ✅ Blade templates → React components (optional)
• ✅ PHPUnit tests → Vitest tests

Creating Your Own Examples

1. Create a new directory under examples/
2. Add a README.md describing the migration
3. Place original code in before/
4. Run Forge to generate after/
5. Create forge.config.toml with your settings
6. Submit a PR to share with the community

Configuration Reference

Each example includes a forge.config.toml:

[migration]
rule = "java8-to-java21"
source = "./before"
output = "./after"

[options]
# Rule-specific options
var_keyword_strategy = "moderate"
aggressive_record_conversion = false

[verification]
compile_check = true
test_execution = true

Tips for Learning

1. Start Simple: Begin with the java11-to-java21 example
2. Use Dry Run: Always preview changes with --dry-run
3. Read Reports: Check migration-report.md for insights
4. Compare Carefully: Use forge compare to understand changes
5. Customize: Modify options to see different migration strategies

Contributing Examples

We welcome new examples! Please:

1. Choose a realistic, common migration scenario
2. Include working, compilable code
3. Document any prerequisites
4. Explain key transformation decisions
5. Include tests that pass before and after

See CONTRIBUTING.md for detailed guidelines.