🔨 ShiftForge

Autonomous Code Migration Assistant - Analyze, transform, and migrate codebases automatically with AI-powered intelligence.

ShiftForge is a CLI tool and local service that automatically generates migration pull requests for framework upgrades, runtime updates, and library migrations. Powered by Claude Sonnet 4.5 for intelligent code analysis and recommendations.

🚀 Portfolio Project - Demonstrating AST transformations, multi-agent AI orchestration, and automated code migration techniques.

🌟 Highlights

• 🤖 AI-Powered Analysis - Claude Sonnet 4.5 provides deep code insights, security analysis, and migration recommendations
• 🎯 AST-Based Transformations - Precise code modifications preserving formatting and comments
• 🔄 Multi-Agent Architecture - Analyzer, Migrator, Validator, and PR Generator agents work autonomously
• ✅ Iterative Validation - Automatically fix issues with test, lint, and type checking
• 📦 Production Ready - TypeScript, comprehensive tests, and extensive documentation

✨ Features

Core Capabilities

• 🔍 Static Code Analysis - Detect framework versions, dependencies, and migration opportunities
• 🤖 AI-Powered Intelligence - Claude Sonnet 4.5 analyzes code for technical debt, security issues, and optimal migration paths
• 🎯 AST-Based Transformations - Precise code modifications using Abstract Syntax Trees (ts-morph, jscodeshift)
• ✅ Automated Validation - Run tests, lints, and type checks with iterative auto-repair
• 📦 PR Generation - Create migration branches with AI-generated, detailed pull request descriptions
• 🌐 MCP Server - REST API for editor integrations and CI/CD pipelines
• 🎨 Interactive Wizard - Step-by-step guided migration with preview and rollback
• ⚡ Parallel Processing - Fast file processing with configurable concurrency

🚀 Supported Migrations

• Node.js - Node 14/16/18 → Node 20
• React - React 17/18 → React 19
• Express → Fastify - Framework migration with API transformations
• More coming soon!

📋 Prerequisites

• Node.js >= 18.0.0
• npm, yarn, or pnpm
• Git repository

🛠️ Installation

# Clone the repository
git clone https://github.com/yourusername/shiftforge.git
cd shiftforge

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

📖 Quick Start

AI-Powered Analysis (Recommended)

Get intelligent insights about your codebase:

# Analyze with AI (requires ANTHROPIC_API_KEY)
shiftforge ai-scan --path ./my-project

# Save full AI report
shiftforge ai-scan --path ./my-project --output ai-report.json

What you get:

• 🔍 Deep code analysis (technical debt, security vulnerabilities, performance issues)
• 🎯 Smart migration suggestions with effort estimates and benefits
• 💡 Actionable recommendations prioritized by impact
• ⚠️ Risk analysis with mitigation strategies

See AI_FEATURES.md for setup instructions and detailed capabilities.

Interactive Wizard

Let ShiftForge guide you through the migration:

shiftforge wizard

The wizard will:

1. Analyze your project
2. Suggest available migrations
3. Let you configure options
4. Preview changes before applying
5. Execute migration with validation
6. Optionally create a PR

CLI Commands

1. Scan - Analyze your codebase

shiftforge scan

# Scan specific directory
shiftforge scan --path ./my-project

# Save analysis to file
shiftforge scan --output analysis.json

2. Run - Execute a migration

# Run migration
shiftforge run --target node20

# Dry run (preview changes)
shiftforge run --target react19 --dry-run

# Auto-fix validation issues
shiftforge run --target fastify --auto-fix

3. Validate - Check for issues

# Run all checks
shiftforge validate

# Attempt auto-fix
shiftforge validate --fix

4. PR - Generate pull request

# Create PR branch
shiftforge pr --title "Migrate to Node 20"

# Push to remote
shiftforge pr --title "Upgrade React to 19" --push

MCP Server

Start the REST API server:

npm run server

Server runs on http://localhost:3000

API Endpoints

POST /analyze - Analyze a project

curl -X POST http://localhost:3000/analyze \
  -H "Content-Type: application/json" \
  -d '{"projectPath": "/path/to/project"}'

POST /suggest - Get migration suggestions

curl -X POST http://localhost:3000/suggest \
  -H "Content-Type: application/json" \
  -d '{"projectPath": "/path/to/project"}'

POST /migrate - Run migration

curl -X POST http://localhost:3000/migrate \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/path/to/project",
    "target": "node20",
    "dryRun": true
  }'

POST /validate - Validate project

curl -X POST http://localhost:3000/validate \
  -H "Content-Type: application/json" \
  -d '{"projectPath": "/path/to/project"}'

📚 Examples

Example 1: Migrate Express to Fastify

# 1. Analyze the project
shiftforge scan

# 2. Preview the migration
shiftforge run --target fastify --dry-run

# 3. Execute the migration
shiftforge run --target fastify

# 4. Validate the changes
shiftforge validate

# 5. Create a PR
shiftforge pr --title "Migrate from Express to Fastify" --push

Before:

const express = require('express');
const app = express();

app.get('/hello', (req, res) => {
  res.json({ message: 'Hello World' });
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

After:

const fastify = require('fastify');
const app = Fastify({ logger: true });

app.get('/hello', (request, reply) => {
  reply.send({ message: 'Hello World' });
});

app.listen({ port: 3000 }, (err, address) => {
  if (err) {
    app.log.error(err);
    process.exit(1);
  }
  console.log('Server running on port 3000');
});

Example 2: Upgrade to Node 20

shiftforge run --target node20

Transformations:

• ✅ Updates package.json engines field
• ✅ Replaces new Buffer() with Buffer.from()
• ✅ Flags deprecated APIs for manual review
• ✅ Updates documentation

Example 3: Migrate React to v19

shiftforge run --target react19 --auto-fix

Transformations:

• ✅ Updates React and ReactDOM imports
• ✅ Replaces ReactDOM.render() with createRoot()
• ✅ Removes unnecessary React imports (new JSX transform)
• ✅ Updates deprecated lifecycle methods
• ✅ Replaces string refs with callback refs

🏗️ Architecture

shiftforge/
├── src/
│   ├── cli/              # CLI commands (scan, run, validate, pr)
│   ├── core/
│   │   ├── analyzer/     # Static analysis engine
│   │   ├── migrator/     # Code transformation engine
│   │   ├── validator/    # Test/lint/type validation
│   │   └── pr-generator/ # Git & PR creation
│   ├── agents/           # LLM agent orchestration (future)
│   ├── transformers/     # Language-specific transforms
│   │   ├── javascript/   # Express→Fastify, Node, React
│   │   ├── typescript/   # TypeScript-specific
│   │   └── java/         # Java migrations (future)
│   ├── server/           # MCP REST API server
│   └── types/            # TypeScript type definitions
├── migrations/           # Migration configurations
└── examples/             # Example projects

🔧 Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run typecheck

# Build
npm run build

🎯 Roadmap

• AI Integration - Claude Sonnet 4.5 for intelligent analysis ✅
• Interactive Wizard - Guided migration experience ✅
• Parallel Processing - Fast concurrent file processing ✅
• Integration Tests - Comprehensive test coverage ✅
• More Migrations
  • Python 2 → Python 3
  • Java 8 → Java 17
  • Vue 2 → Vue 3
  • Webpack → Vite
• GitHub Actions Integration - Automated PR creation in CI
• VS Code Extension - Editor integration
• Custom Migration Rules - User-defined transformations via config
• Rollback Support - One-command rollback on failures
• Codebase Learning - Train on your codebase patterns

💻 Tech Stack

• Language: TypeScript 5.3
• AST Parsing: ts-morph, jscodeshift, @babel/parser
• AI: Anthropic Claude API (Sonnet 4.5)
• CLI: Commander.js, chalk, ora, prompts
• Git: simple-git
• Testing: Jest, ts-jest
• Build: TypeScript compiler

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CODE_OF_CONDUCT.md for community guidelines.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Built with TypeScript, Commander.js, ts-morph, and jscodeshift
• AI powered by Anthropic Claude Sonnet 4.5
• Inspired by Facebook's jscodeshift and Google's Refaster
• AST transformation techniques from the codemods community

📚 Documentation

• AI Features Guide - Complete AI capabilities and setup
• Architecture Documentation - Technical design and decisions
• Quick Start Guide - Get started in 5 minutes
• Contributing Guidelines - How to contribute

---

Built as a portfolio project demonstrating advanced TypeScript, AST manipulation, AI integration, and automated code transformation.