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
• 📧 victor.silvestre.dev@gmail.com

---

📝 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