|
| 1 | +# UI5 Modernization Plugin |
| 2 | + |
| 3 | +A comprehensive plugin providing a complete toolkit for modernizing SAPUI5/OpenUI5 applications by removing deprecated APIs and producing modernized UI5 code. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Modernized UI5 code removes all deprecated APIs and global namespace access. This plugin provides: |
| 8 | + |
| 9 | +- **Autonomous migration workflow** with end-to-end orchestration |
| 10 | +- **Specialized fix skills** for every linter rule category |
| 11 | +- **Validation** at every step via UI5 linter integration |
| 12 | + |
| 13 | +## Skills Included |
| 14 | + |
| 15 | +This plugin bundles 14 specialized skills for producing modernized UI5 code: |
| 16 | + |
| 17 | +### Migration Workflow |
| 18 | + |
| 19 | +- **`/modernize-ui5`** - Autonomous end-to-end workflow: runs linter, applies autofix, uses specialized skills for remaining errors, documents unfixable issues, and generates a summary report |
| 20 | + |
| 21 | +### Global Namespace Fixes |
| 22 | + |
| 23 | +- **`/fix-js-globals`** - Fix JavaScript `no-globals` errors: global namespace assignments, delete expressions, `sap.ui.core.Core` direct access, jQuery/$ global calls |
| 24 | +- **`/fix-xml-globals`** - Fix XML view/fragment globals: global variable access, ambiguous event handlers, formatters, type references in bindings, factory functions, legacy `template:require` syntax |
| 25 | +- **`/fix-pseudo-modules`** - Fix pseudo module and implicit global issues: deprecated enum/DataType pseudo module access, direct `library.EnumName` access, OData expression addons in bindings |
| 26 | + |
| 27 | +### Deprecated API Fixes |
| 28 | + |
| 29 | +- **`/fix-deprecated-controls`** - Fix deprecated controls, classes, interfaces, and types with modern replacements (e.g., `sap.m.MessagePage` to `IllustratedMessage`) |
| 30 | +- **`/fix-partially-deprecated-apis`** - Fix partially deprecated API usage: `Parameters.get`, `JSONModel.loadData`, `Mobile.init`, `ODataModel.v2.createEntry`, `View.create`, `Fragment.load`, `Router` constructor, string formatters in JS bindings |
| 31 | +- **`/fix-table-row-mode`** - Migrate deprecated Table row properties (`visibleRowCountMode`, `visibleRowCount`, `rowHeight`, `fixedRowCount`, `fixedBottomRowCount`, `minAutoRowCount`) to structured `rowMode` aggregation |
| 32 | + |
| 33 | +### Component and Bootstrap Fixes |
| 34 | + |
| 35 | +- **`/fix-component-async`** - Fix Component.js async configuration: `IAsyncContentCreation` interface, manifest declaration, redundant async flags |
| 36 | +- **`/fix-bootstrap-params`** - Fix HTML bootstrap parameter issues: missing/deprecated parameters (`async`, `compat-version`, `animation`, `binding-syntax`), deprecated theme values, deprecated libraries |
| 37 | +- **`/fix-manifest-json`** - Fix manifest.json issues: outdated manifest version, legacy UI5 version, deprecated libraries/components, deprecated view/model types, removed properties |
| 38 | + |
| 39 | +### Control and Rendering Fixes |
| 40 | + |
| 41 | +- **`/fix-control-renderer`** - Fix Control renderer issues: missing renderer declaration, string-based renderer, implicit auto-discovery (breaking change in modernized UI5 code), `apiVersion:2` configuration |
| 42 | +- **`/fix-csp-compliance`** - Fix Content Security Policy compliance: unsafe inline scripts, inline JavaScript in HTML, inline event handlers |
| 43 | +- **`/fix-xml-native-html`** - Fix native HTML and SVG usage in XML views/fragments: replace `html:div`, `html:span`, `html:a` with UI5 controls, SVG with UI5 icons |
| 44 | + |
| 45 | +### Test Infrastructure |
| 46 | + |
| 47 | +- **`/fix-test-starter`** - Migrate from legacy QUnit test setup to modern Test Starter concept for `*.qunit.html` and `*.qunit.js` files |
| 48 | + |
| 49 | +## Quick Start |
| 50 | + |
| 51 | +### 1. Start with the Migration Workflow |
| 52 | + |
| 53 | +The main entry point is the autonomous workflow skill which orchestrates the entire migration: |
| 54 | + |
| 55 | +``` |
| 56 | +/modernize-ui5 |
| 57 | +``` |
| 58 | + |
| 59 | +This will autonomously: |
| 60 | +- Run UI5 linter to assess the current state |
| 61 | +- Apply autofix for issues the linter can resolve |
| 62 | +- Use specialized skills for remaining errors |
| 63 | +- Document unfixable issues |
| 64 | +- Generate a summary report |
| 65 | + |
| 66 | +### 2. Use Specialized Skills for Specific Issues |
| 67 | + |
| 68 | +When you encounter specific error patterns, use the targeted skills: |
| 69 | + |
| 70 | +``` |
| 71 | +# Global namespace issues |
| 72 | +/fix-js-globals # For no-globals errors in JS files |
| 73 | +/fix-xml-globals # For no-globals errors in XML views/fragments |
| 74 | +/fix-pseudo-modules # For pseudo module and implicit global issues |
| 75 | +
|
| 76 | +# Deprecated API migrations |
| 77 | +/fix-deprecated-controls # For deprecated controls, classes, interfaces |
| 78 | +/fix-partially-deprecated-apis # For partially deprecated API calls |
| 79 | +/fix-table-row-mode # For deprecated Table row properties |
| 80 | +
|
| 81 | +# Component and bootstrap |
| 82 | +/fix-component-async # For Component.js async issues |
| 83 | +/fix-bootstrap-params # For HTML bootstrap parameters |
| 84 | +/fix-manifest-json # For manifest.json issues |
| 85 | +
|
| 86 | +# Control and rendering |
| 87 | +/fix-control-renderer # For control renderer issues |
| 88 | +/fix-csp-compliance # For CSP compliance issues |
| 89 | +/fix-xml-native-html # For native HTML/SVG in XML views |
| 90 | +
|
| 91 | +# Test infrastructure |
| 92 | +/fix-test-starter # For Test Starter migration |
| 93 | +``` |
| 94 | + |
| 95 | +## Understanding Modernized UI5 Code Requirements |
| 96 | + |
| 97 | +### Critical Success Criteria |
| 98 | + |
| 99 | +For your app to produce modernized UI5 code, you MUST fix **ALL linter errors (severity 2)** reported by the UI5 linter: |
| 100 | + |
| 101 | +**Common error categories:** |
| 102 | +1. **`no-deprecated-api`** - All deprecated APIs that must be replaced (most common) |
| 103 | +2. **`no-globals`** - All global namespace access must use proper imports (most common) |
| 104 | +3. **Other rule violations** - Any additional errors specific to your codebase |
| 105 | + |
| 106 | +**Check your progress:** |
| 107 | +```bash |
| 108 | +# Count ALL critical errors (must be 0) |
| 109 | +npx @ui5/linter --format json 2>&1 | jq '[.[] | select(.messages) | .messages[] | select(.severity == 2)] | length' |
| 110 | + |
| 111 | +# Count by specific categories (for tracking progress) |
| 112 | +npx @ui5/linter --format json 2>&1 | jq '[.[] | select(.messages) | .messages[] | select(.severity == 2)] | group_by(.ruleId) | map({rule: .[0].ruleId, count: length})' |
| 113 | +``` |
| 114 | + |
| 115 | +### Error vs Warning Priority |
| 116 | + |
| 117 | +- **Errors (severity 2)** 🔴 - MUST fix ALL for modernized UI5 code |
| 118 | +- **Warnings (severity 1)** ⚠️ - Can address later (non-blocking) |
| 119 | + |
| 120 | +The migration workflow focuses on `no-globals` and `no-deprecated-api` as these are the most common error categories, but you must address ALL errors to achieve fully modernized UI5 code. |
| 121 | + |
| 122 | +## Migration Phases Overview |
| 123 | + |
| 124 | +The `/modernize-ui5` workflow handles the following phases autonomously: |
| 125 | + |
| 126 | +``` |
| 127 | +Phase 1: Assessment |
| 128 | +├── Run linter baseline |
| 129 | +├── Count all critical errors (severity 2) |
| 130 | +└── Create migration branch |
| 131 | +
|
| 132 | +Phase 2: Autofix |
| 133 | +├── Run linter with --fix flag |
| 134 | +└── Review and validate autofix changes |
| 135 | +
|
| 136 | +Phase 3: Fix Remaining Errors |
| 137 | +├── Apply specialized skills per linter rule |
| 138 | +├── Track progress continuously |
| 139 | +└── Document unfixable issues |
| 140 | +
|
| 141 | +Phase 4: Validation and Completion |
| 142 | +├── Run final linter check (0 errors required) |
| 143 | +├── Build verification |
| 144 | +└── Generate migration summary report |
| 145 | +``` |
| 146 | + |
| 147 | +## Key Features |
| 148 | + |
| 149 | +### Autonomous Execution |
| 150 | + |
| 151 | +The `/modernize-ui5` workflow is designed for **autonomous execution**: |
| 152 | + |
| 153 | +1. Runs the full migration end-to-end without constant confirmation |
| 154 | +2. Applies autofix first, then uses specialized skills for remaining errors |
| 155 | +3. Tracks progress via continuous linter error counts |
| 156 | +4. Documents unfixable issues separately |
| 157 | +5. Generates a comprehensive summary report |
| 158 | + |
| 159 | +### Validation Tools |
| 160 | + |
| 161 | +Built-in validation at every step: |
| 162 | + |
| 163 | +- **Linter integration** - Continuous error count tracking |
| 164 | +- **Build verification** - Confirms no breaking changes |
| 165 | +- **Detailed guidance** - UI5 Linter `--details` flag for immediate fix guidance |
| 166 | +- **UI5 MCP Server** - API documentation and replacements |
| 167 | + |
| 168 | +## Prerequisites |
| 169 | + |
| 170 | +Before using this plugin, ensure you have: |
| 171 | + |
| 172 | +1. **UI5 application** on version 1.71+ (preferably 1.120+) |
| 173 | +2. **UI5 linter installed**: `npm install --save-dev @ui5/linter` |
| 174 | +3. **Git repository** with clean working directory |
| 175 | +4. **Test suite** working (QUnit/OUnit/OPA) |
| 176 | +5. **Build system** working (UI5 CLI or Maven) |
| 177 | + |
| 178 | +## Expected Results |
| 179 | + |
| 180 | +### Before Migration |
| 181 | + |
| 182 | +- no-deprecated-api errors: 200-500+ ❌ |
| 183 | +- no-globals errors: 100-300+ ❌ |
| 184 | +- Build: ✅ Success |
| 185 | +- Tests: ✅ Passing |
| 186 | + |
| 187 | +### After Migration (Modernized UI5 Code) |
| 188 | + |
| 189 | +- **ALL LINTER ERRORS: 0** ✅ (REQUIRED - any severity 2 error means code is not fully modernized) |
| 190 | + - no-deprecated-api errors: 0 ✅ |
| 191 | + - no-globals errors: 0 ✅ |
| 192 | + - Other rule errors: 0 ✅ |
| 193 | +- Linter warnings: <100 ⚠️ (acceptable) |
| 194 | +- Build: ✅ Success |
| 195 | +- Tests: ✅ Passing |
| 196 | + |
| 197 | +## Estimated Timeline |
| 198 | + |
| 199 | +For a large enterprise application (300+ JS files): |
| 200 | + |
| 201 | +- **Phase 0 (Assessment)**: 1 day |
| 202 | +- **Phase 1-5 (Critical Errors)**: 16-27 days |
| 203 | +- **Phase 6-7 (Supporting)**: 2 days |
| 204 | +- **Phase 8-10 (Validation)**: 5-7 days |
| 205 | +- **Total**: 24-40 days |
| 206 | + |
| 207 | +Smaller applications will take proportionally less time. |
| 208 | + |
| 209 | +## Troubleshooting |
| 210 | + |
| 211 | +### Getting Detailed Error Information |
| 212 | + |
| 213 | +```bash |
| 214 | +# Get fix guidance for all errors |
| 215 | +npx @ui5/linter --details |
| 216 | + |
| 217 | +# Get fix guidance for specific file |
| 218 | +npx @ui5/linter --details path/to/file.js |
| 219 | +``` |
| 220 | + |
| 221 | +## Support and Resources |
| 222 | + |
| 223 | +### Official UI5 Documentation |
| 224 | + |
| 225 | +- [Migration Guide](https://ui5.sap.com/#/topic/9638e4fce4de4fa8ae8f3b6e01d43b68) |
| 226 | +- [Deprecated APIs](https://ui5.sap.com/#/topic/a6e6b1f06b1a413d8afe36afc6a8cadf) |
| 227 | + |
| 228 | +### Using with UI5 MCP Server |
| 229 | + |
| 230 | +This plugin works great with the UI5 MCP Server for API documentation: |
| 231 | + |
| 232 | +- Query deprecated APIs |
| 233 | +- Find modern replacements |
| 234 | +- Get code examples |
| 235 | +- View parameter details |
| 236 | + |
| 237 | +## Installation |
| 238 | + |
| 239 | +First, add the marketplace (one-time setup): |
| 240 | + |
| 241 | +```bash |
| 242 | +/plugin marketplace add https://github.com/UI5/plugins-claude.git |
| 243 | +``` |
| 244 | + |
| 245 | +Then install this plugin: |
| 246 | + |
| 247 | +```bash |
| 248 | +/plugin install ui5-modernization |
| 249 | +``` |
| 250 | + |
| 251 | +For more details, see the [marketplace README](../../README.md). |
| 252 | + |
| 253 | +## License |
| 254 | + |
| 255 | +Apache-2.0 |
| 256 | + |
| 257 | +## Version |
| 258 | + |
| 259 | +0.1.0 |
0 commit comments