backstage/scripts/mui-to-bui/README.md

Backstage MUI to BUI Migration Analytics

This script provides accurate TypeScript AST-based analysis of MUI to @backstage/ui migration progress in the Backstage repository.

Key Benefits:

• 🔍 AST-Powered - Uses ts-morph for accurate TypeScript parsing
• 🎯 Component Discovery - Finds all components from import statements
• 📝 Complex Patterns - Handles aliases, destructuring, renamed imports
• 🚀 Easy Access - Run from anywhere using yarn scripts
• 📊 GitHub Integration - Automatically updates GitHub issues with migration progress
• ⚡ Reliable - Accurate component usage tracking

🚀 Quick Start

# From anywhere in the repository
yarn mui-to-bui              # Generate console report
yarn mui-to-bui --json       # Export detailed JSON data
yarn mui-to-bui --csv        # Export component usage CSV
yarn mui-to-bui --markdown   # Generate GitHub-optimized markdown
yarn mui-to-bui --components # Show detailed list of all components

✨ Features

TypeScript AST Analysis

• 🔍 Accurate - Uses ts-morph for proper TypeScript AST parsing
• 🎯 Component Discovery - Finds all components from import statements
• 📝 Complex Patterns - Handles aliases, destructuring, renamed imports
• ⚡ Reliable - Accurate component usage tracking
• 🚀 Comprehensive - Analyzes thousands of files efficiently

Comprehensive Analysis

• Tracks MUI v4 (@material-ui/*), MUI v5 (@mui/*), and Backstage UI (@backstage/ui)
• Provides migration status and prioritized recommendations
• Generates detailed reports with component usage statistics

Smart Recommendations

• Prioritizes MUI v4 migrations (highest priority)
• Identifies files with mixed imports (quick wins)
• Highlights most-used components for migration planning
• Provides actionable insights for migration priorities

GitHub Integration

• Automatically updates a GitHub issue with migration progress
• Runs daily via GitHub Actions workflow
• Can be triggered manually for on-demand updates
• Formatted markdown with collapsible sections and progress bars

📊 Sample Output

🔍 Backstage MUI to BUI Migration Report
=======================================

Analyzing migration from MUI to @backstage/ui in the Backstage repository

📊 SUMMARY
--------------------
Total files analyzed: 2,847
Files with MUI imports: 987
Files with Backstage UI imports: 345
Total import statements: 2,134
Components found: 156

🚀 MIGRATION PROGRESS
--------------------
✅ Fully migrated: 345 files (25.9%)
🔄 Mixed imports: 234 files (17.5%)
❌ Not started: 756 files (56.6%)

📚 LIBRARY USAGE
--------------------
@material-ui/core: 1,234 imports in 456 files
@mui/material: 567 imports in 234 files
@backstage/ui: 345 imports in 234 files

💡 RECOMMENDATIONS
--------------------
🔴 756 files still use MUI v4 (@material-ui). These should be prioritized for migration.

🟡 234 files have mixed imports. Focus on completing these migrations first for quick wins.

🔵 Migration progress: 25.9% of files fully migrated to Backstage UI

🎯 What This Tells You

Migration Priorities

1. MUI v4 First: Files using @material-ui/* should be migrated first
2. Complete Mixed Files: Files with both MUI and Backstage UI imports are easy wins
3. Component Focus: Prioritize the most-used components for maximum impact
4. Track Progress: Monitor migration progress over time with automated reports

Actionable Insights

• High Priority: Identify files still using deprecated MUI v4
• Quick Wins: Files with mixed imports are partially migrated - finish them first
• Component Usage: See which components are most used to prioritize migration efforts
• Progress Tracking: Automated GitHub issue updates keep everyone informed

🔧 GitHub Workflow Integration

The migration progress is automatically tracked via GitHub Actions:

Workflow Features

• Daily Updates: Runs every day at midnight UTC
• Manual Trigger: Can be triggered manually via GitHub Actions UI
• Issue Updates: Automatically updates Issue #31467
• Formatted Reports: GitHub-optimized markdown with tables and collapsible sections

Workflow File

The workflow is defined in .github/workflows/mui-migration-tracker.yml and:

1. Checks out the repository
2. Sets up Node.js and installs dependencies
3. Runs the migration analysis script
4. Updates the GitHub issue with the latest report

📁 File Structure

scripts/mui-to-bui/
├── backstage-migration-analytics.js    # AST-powered migration analytics
└── README.md                          # This documentation

.github/workflows/
└── mui-migration-tracker.yml         # GitHub Actions workflow for automated updates

🛠 Technical Details

Analysis Scope

• File Types: .tsx, .ts, .jsx, .js
• Ignored Directories: node_modules, dist, build, .git, coverage, .yarn
• Import Tracking: All MUI and Backstage UI package imports
• Component Usage: All components discovered via AST parsing

TypeScript AST Parsing

• Uses ts-morph for accurate parsing
• Handles complex import patterns (aliases, destructuring, etc.)
• Tracks component usage throughout the codebase
• Identifies unused imports for potential cleanup

🚨 Important Notes

Performance

• Analysis takes ~30-60 seconds for the full repository
• Processes files in batches to avoid memory issues
• Efficiently analyzes thousands of files

Dependencies

• Requires ts-morph package (already in dependencies)
• Uses Node.js built-in modules for file system operations
• GitHub Actions workflow uses GITHUB_TOKEN for issue updates

🔍 Understanding the Data

Migration Status Categories

• ✅ Fully Migrated: Only uses Backstage UI components
• 🔄 Mixed: Uses both MUI and Backstage UI (partial migration)
• ❌ Not Started: Only uses MUI components
• ℹ️ Not Applicable: No relevant UI imports found

Library Categories

• MUI v4: @material-ui/core, @material-ui/lab, @material-ui/icons
• MUI v5: @mui/material, @mui/lab, @mui/icons-material
• Backstage UI: @backstage/ui, @spotify-portal/canon

This comprehensive analysis helps you make informed decisions about migration priorities and strategies, with automated tracking to monitor progress over time.

💾 Saving Output to Files

# Save outputs to files for sharing or further analysis
yarn mui-to-bui --markdown > migration-report.md
yarn mui-to-bui --csv > migration-components.csv
yarn mui-to-bui --json > migration-data.json
yarn mui-to-bui --components > all-components.txt

# Save with timestamps
yarn mui-to-bui --csv > "migration-$(date +%Y%m%d).csv"
yarn mui-to-bui --markdown > "migration-report-$(date +%Y%m%d).md"

🧩 Detailed Component Analysis

View All Components

# See detailed breakdown of all 420+ components
yarn mui-to-bui --components

This shows:

• 📊 Complete component list sorted by usage frequency
• 📁 Top files using each component
• ⚠️ Imported but unused components (potential cleanup opportunities)
• 📈 Usage statistics for prioritizing migration efforts

Sample Component Output

1. Typography
   Usage: 1,633 times across 705 files
   Top files:
     • plugins/catalog/src/components/CatalogTable/CatalogTable.tsx (15 uses)
     • plugins/search/src/components/SearchResult/SearchResult.tsx (14 uses)
     • plugins/techdocs/src/components/TechDocsPage.tsx (13 uses)
     ... and 702 more files

2. Box
   Usage: 1,572 times across 697 files
   Top files:
     • plugins/app-visualizer/src/components/AppVisualizerPage/DetailedVisualizer.tsx (15 uses)
     • plugins/scaffolder/src/components/TemplateCard/TemplateCard.tsx (14 uses)
     ... and 695 more files