Merge pull request #31468 from backstage/mui-to-bui

MUI to BUI migration tracker
2025-10-23 16:53:56 +02:00
parent 21ec131c20 acbaf00433
commit 50c9b6f4ad
5 changed files with 1457 additions and 1 deletions
@@ -0,0 +1,70 @@
+name: MUI to BUI Migration Tracker
+
+on:
+  schedule:
+    # Run daily at midnight UTC
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+    # Allow manual triggering
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  update-migration-progress:
+    runs-on: ubuntu-latest
+    name: Update Migration Progress Issue
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@ec9f2d5744a09debf3a187a3f4f675c53b671911 # v2.13.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+
+      - name: yarn install
+        uses: backstage/actions/yarn-install@b3c1841fd69e1658ac631afafd0fb140a2309024 # v0.6.17
+        with:
+          cache-prefix: ${{ runner.os }}-v20.x
+
+      - name: Run migration analysis
+        id: analysis
+        run: |
+          # Run the migration script and save markdown output
+          yarn mui-to-bui --markdown > migration-report.md
+
+          # Read the report into an environment variable (escape for GitHub Actions)
+          echo "REPORT<<EOF" >> $GITHUB_ENV
+          cat migration-report.md >> $GITHUB_ENV
+          echo "EOF" >> $GITHUB_ENV
+
+      - name: Update GitHub Issue
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const issueNumber = 31467;
+            const reportBody = process.env.REPORT;
+
+            try {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                body: reportBody
+              });
+              
+              console.log(`✅ Successfully updated issue #${issueNumber}`);
+            } catch (error) {
+              console.error(`❌ Error updating issue: ${error.message}`);
+              throw error;
+            }
@@ -45,6 +45,7 @@
    "lint:docs": "node ./scripts/check-docs-quality",
    "lint:peer-deps": "backstage-repo-tools peer-deps",
    "lint:type-deps": "backstage-repo-tools type-deps",
+    "mui-to-bui": "node scripts/mui-to-bui/backstage-migration-analytics.js",
    "new": "backstage-cli new",
    "prepare": "husky",
    "prettier:check": "prettier --check .",
@@ -106,6 +107,7 @@
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "@yarnpkg/plugin-npm@npm:^3.1.0": "patch:@yarnpkg/plugin-npm@npm%3A3.1.0#~/.yarn/patches/@yarnpkg-plugin-npm-npm-3.1.0-6533d0f5a1.patch",
+    "GendocuPublicApis": "npm:gendocu-public-apis@^1.0.0",
    "ast-types@0.14.2": "patch:ast-types@npm%3A0.14.2#./.yarn/patches/ast-types-npm-0.14.2-43c4ac4b0d.patch",
    "ast-types@^0.14.1": "patch:ast-types@npm%3A0.14.2#./.yarn/patches/ast-types-npm-0.14.2-43c4ac4b0d.patch",
    "ast-types@npm:0.14.2": "patch:ast-types@npm%3A0.16.1#./.yarn/patches/ast-types-npm-0.16.1-43c4ac4b0d.patch",
@@ -115,7 +117,6 @@
    "csstype@npm:^3.1.2": "3.0.9",
    "csstype@npm:^3.1.3": "3.0.9",
    "jest-haste-map@^29.7.0": "patch:jest-haste-map@npm%3A29.7.0#./.yarn/patches/jest-haste-map-npm-29.7.0-e3be419eff.patch",
-    "GendocuPublicApis": "npm:gendocu-public-apis@^1.0.0",
    "recast@npm:0.23.9>ast-types": "patch:ast-types@npm%3A0.16.1#./.yarn/patches/ast-types-npm-0.16.1-43c4ac4b0d.patch"
  },
  "dependencies": {
@@ -166,6 +167,7 @@
    "sloc": "^0.3.1",
    "sort-package-json": "^2.8.0",
    "storybook": "^9.1.7",
+    "ts-morph": "^24.0.0",
    "typedoc": "^0.28.0",
    "typescript": "~5.7.0",
    "vite": "^7.1.5"
@@ -0,0 +1,233 @@
+# 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](https://ts-morph.com/) 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
+
+```bash
+# 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](https://ts-morph.com/) 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](https://github.com/backstage/backstage/issues/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](https://ts-morph.com/) 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
+
+```bash
+# 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
+
+```bash
+# 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
+```
@@ -44985,6 +44985,7 @@ __metadata:
    sloc: "npm:^0.3.1"
    sort-package-json: "npm:^2.8.0"
    storybook: "npm:^9.1.7"
+    ts-morph: "npm:^24.0.0"
    typedoc: "npm:^0.28.0"
    typescript: "npm:~5.7.0"
    vite: "npm:^7.1.5"