Angular Migration Planner

Perform your Angular migrations stress-free with full guidance!

Professional Angular migration companion tool for version upgrades, Nx monorepo refactoring, and technical debt assessment

AI-powered migration auto-fix + Angular schematics (experimental)

🇬🇧 English | 🇫🇷 Français

🎯 What Is This?

A complete Angular migration analysis (AST) AND AI-assisted migration tool for:

• 🔄 Angular Migrations — Plan migrations 17→18, 18→19, 19→20, 20→21 with precise estimates
• 🏢 Nx Monorepo — Analyze multi-app/lib workspaces with per-target breakdown
• 📊 Technical Debt — Identify deprecated APIs, anti-patterns, modernization opportunities
• 💰 Workload Estimation — Calculate time (days/hours/minutes) by priority and risk level
• 🎨 Code Modernization — Detect Signals, Control Flow, Standalone Components opportunities

Perfect for technical teams and tech leads planning Angular upgrades or refactoring.

📸 See the result | 🤖 AI Auto-Fix

🏆 Why Choose This Tool?

Unlike simple regex scanners or manual audits:

• ✅ 88% AST Coverage — Context-aware detection eliminates false positives (ignores comments, strings, migrated code)
• ✅ Cross-File Intelligence — Connects TypeScript ↔ HTML templates (detects @Component + <router-outlet> patterns)
• ✅ Production-Ready — 748 tests passing, TypeScript strict mode, optimized batch processing
• ✅ Time Savings — Auto workload calculation + Gantt timeline = instant migration roadmap
• ✅ Zero Dependencies — Pure AST analysis with ts-morph + @angular/compiler (no external APIs)

🚀 Quick Start

# Navigate to your project
cd path-to-my-project # (if local install)

# Install
npm install -D @silvestv/migration-planificator
npm install -g @silvestv/migration-planificator

# Run directly
npx @silvestv/migration-planificator
npx @silvestv/migration-planificator --project-path=path-to-my-project

CLI Options

--scanner=<mode>        ast | regex | both              [default: ast]
--project-path=<path>   Path to Angular project         [default: .]
--rules=<versions>      18 | [18,19] | all              [default: all]

Examples

# Scan current directory (AST, all rules)
npx @silvestv/migration-planificator

# Comparative scan on Nx workspace
npx @silvestv/migration-planificator --scanner=both --project-path=/workspace/my-app

# Only Angular 17→18 rules
npx @silvestv/migration-planificator --rules=18

# Multiple versions
npx @silvestv/migration-planificator --rules=[18,19,20]

Open Report

open output/index.html   # macOS/Linux
start output/index.html  # Windows

📊 Report Contents

5 HTML files generated in output/ :

• Overview — Project summary, global stats, apps/libs cards
• Workload — Charts (pie, bar, doughnut), Gantt timeline, hierarchy tree, real-time editing, filters
• Migration Guide — Step-by-step checklist per rule
• Rules Overview — All 119 rules with detection status
• Delta (both mode) — AST vs Regex comparison, divergence analysis

Workload page overview (workload page)

🤖 AI Auto-Fix (Experimental)

Generate structured prompts for AI agents (Claude CLI / Gemini CLI -> not recommended) to automatically migrate your code.

Recommended: Claude Code Opus 4 (CLI) with a small-to-medium repository (< 500 files impacted). Experimental — review all agent changes before merging.

Prerequisites

• An IDE (VSCode / WebStorm)
• Claude Code (recommended) OR Gemini CLI
• Note: migrating a rule costs a certain number of tokens!

Command

1. project > ./output/workload-planner.html
2. Open the page in your browser
3. On a migration rule, click the AI FIX button: it copies to clipboard
4. Open a terminal in the project to migrate
5. Paste the clipboard command such as:

   npx @silvestv/migration-planificator fix --rule=RULE_KEY

OR from another repo with

npx @silvestv/migration-planificator fix --rule=RULE_KEY --project-path=/path/to/project

6. Execute: prompt generation

Note: "RULE_KEY" values are visible at the bottom of rule "details" modals.

| Option | Description | Default | |--------|-------------|---------| | --rule=RULE_KEY | Migration rule to fix (required) | — | | --project-path=PATH | Path to Angular project | . | | --branch=BRANCH | Base branch | master | | -y | Skip precondition confirmation | false | | --skip-validation | Skip build & tests in prompt | false |

Output

4 files in output/ai/migration/{version}/{rule}-prompts/ :

| File | Purpose | |------|---------| | constitution.md | Absolute agent rules (safety, quality, imports) | | context.md | Rule description + all occurrences (file:line) | | ledger.json | Migration tracking (schematic, iterations, blame) | | file-prompt.md | Complete 7-phase instructions for the agent |

Usage

cd /path/to/project && claude       # or gemini
> Execute output/ai/migration/19/signal_inputs-prompts/file-prompt.md (example)

The agent will: check preconditions → create branch → propose plan → implement → validate (AST + build + tests) → commit & push.

Agent Pipeline

📋 Migration Rules

119 rules across 4 versions:

| Migration | Mandatory | Recommended | Optional | Total | |-----------|-----------|-------------|----------|-------| | 17→18 | 8 | 17 | 0 | 25 | | 18→19 | 15 | 13 | 9 | 37 | | 19→20 | 6 | 7 | 5 | 18 | | 20→21 | 21 | 6 | 12 | 39 |

Categories: environment • imports • api • routing • template • test • ssr • reactive • signals • config

Risk Levels: 🔴 Critical • 🟠 High • 🟡 Medium • 🟢 Low

🔒 Security

100% local processing. No telemetry, no external APIs, no data leaves your machine. See SECURITY.md

🤝 Support

• 🐛 Report a Bug
• ✨ Request a Feature
• ❓ Ask a Question
• 📧 [email protected]

📝 License

© 2025 Victor SILVESTRE — Apache License 2.0. Free for commercial use. See LICENSE.

Built with ts-morph, @angular/compiler, TailwindCSS, Chart.js

📧 Contact • 📦 NPM Package