🔄 MMD Migrator

Automated migration tool for Material 3 to Mudita Mindful Design (MMD) components

Seamlessly migrate your Jetpack Compose Material 3 components to MMD with intelligent, context-aware transformations.

---

✨ Features

Simple Migration (Recommended)

• 🚀 Fast Regex-Based Migration - Process entire projects in seconds
• 🎯 Context-Aware Replacements - Smart detection of component relationships
• 🔍 UTF-8 Validation - Ensures file encoding compatibility
• 📊 Detailed Reports - Clear statistics and change summaries
• 🧪 Dry-Run Mode - Preview changes before applying
• ⚙️ Custom Mappings - Override default component mappings
• 🔧 Gradle Integration - Simple task-based workflow

OpenRewrite Migration (Experimental)

• 🔬 AST-Based Transformations - Precise syntax tree analysis
• ⚠️ Experimental Status - Use with caution, known limitations exist

---

🚀 Quick Start

1. Add the Plugin

In your build.gradle.kts:

plugins {
    id("com.mudita.mmd-migrator") version "{version}"
}

2. Run Migration

Using Simple Migration (Recommended):

# Preview changes (dry-run)
./gradlew migrateMmdSimpleDryRun

# Apply migration
./gradlew migrateMmdSimple

Using OpenRewrite (Experimental):

# Preview changes (dry-run)
./gradlew migrateToMmdDryRun

# Apply migration
./gradlew migrateToMmd

💡 Tip: Start with Simple Migration for best results. See Migration Methods for detailed comparison.

3. Review & Compile

# Check compilation
./gradlew compileKotlin

# Run your tests
./gradlew test

---

📖 What Gets Migrated

Components

Transforms Material 3 components to their MMD equivalents:

// Before
import androidx.compose.material3.Button
import androidx.compose.material3.Text

Button(onClick = { }) {
    Text("Click me")
}

// After
import com.mudita.mmd.components.buttons.ButtonMMD
import com.mudita.mmd.components.text.TextMMD

ButtonMMD(onClick = { }) {
    TextMMD("Click me")
}

Defaults & Properties (Context-Aware)

Intelligently migrates Defaults objects based on context:

// Before
TextField(
    value = text,
    onValueChange = { text = it },
    colors = TextFieldDefaults.colors()
)

// After
TextFieldMMD(
    value = text,
    onValueChange = { text = it },
    colors = TextFieldDefaultsMMD.colors()
)

Smart Detection:

• ✅ TextFieldDefaults inside TextField → migrated to TextFieldDefaultsMMD
• ❌ TextFieldDefaults inside OutlinedTextField → not migrated (OutlinedTextField isn't in MMD)

Supported Components

View full list (60+ components)

Basic Components

• Badge, BadgedBox
• Button, OutlinedButton, TextButton, IconButton
• Card, ElevatedCard, OutlinedCard
• Checkbox, TriStateCheckbox
• Switch
• RadioButton
• Text

Input Components

• TextField
• Slider

Chips

• AssistChip, FilterChip, InputChip, SuggestionChip

Navigation

• NavigationBar, NavigationBarItem
• TopAppBar

Tabs

• Tab, TabRow, LeadingIconTab
• PrimaryTabRow, PrimaryScrollableTabRow
• SecondaryTabRow, SecondaryScrollableTabRow

Progress & Loading

• CircularProgressIndicator, LinearProgressIndicator
• ProgressIndicatorDefaults

Pickers

• DatePicker, TimePicker
• rememberDatePickerState, rememberTimePickerState

Menus & Dropdowns

• DropdownMenu, DropdownMenuItem

Dialogs & Sheets

• ModalBottomSheet, rememberModalBottomSheetState

Layout & Dividers

• HorizontalDivider, VerticalDivider

Feedback

• Snackbar, SnackbarHost, SnackbarHostState

Search

• SearchBar, SearchBarDefaults

Tooltips

• PlainTooltip (→ TooltipMMD)
• TooltipBox

Buttons (Extended)

• FloatingActionButton, SmallFloatingActionButton

Lazy Lists

• LazyColumn, LazyRow

Theme

• MaterialTheme → ThemeMMD

---

📊 Migration Output

Console Report (Dry-Run)

=== MMD Simple Migration ===
Project: /path/to/your/project
Mode: DRY RUN
Mappings loaded: 156
UTF-8 encoding validation: enabled

HomeScreen.kt:
  ✓ Button -> ButtonMMD
  ✓ ButtonDefaults -> ButtonDefaultsMMD (inside ButtonMMD)
  ✓ Text -> TextMMD
  ✓ Card -> CardMMD

ProfileScreen.kt:
  ✓ TextField -> TextFieldMMD
  ✓ TextFieldDefaults -> TextFieldDefaultsMMD (inside TextFieldMMD)
  ✓ Switch -> SwitchMMD

============================================================
=== Migration Summary ===
============================================================

📊 Files:
   Total analyzed:        42
   Successfully migrated: 38
   Skipped (no changes):  4

🔄 Changes:
   Total transformations: 156
   Unique components:     12

📦 Migrated components:
   • Button
   • Card
   • Switch
   • Text
   • TextField
   ...

============================================================
ℹ️  This was a DRY RUN - No files were modified
============================================================

To apply these changes, run:
  ./gradlew migrateMmdSimple

---

🔀 Migration Methods

MMD Migrator provides two migration approaches with different trade-offs:

Method 1: Simple Migration (Recommended) 🚀

Fast, reliable regex-based migration for production use.

Features

• ✅ Fast: Process entire projects in seconds
• ✅ Context-Aware: Smart detection of component relationships
• ✅ UTF-8 Safe: Built-in encoding validation
• ✅ Detailed Reports: Clear statistics and change summaries
• ✅ Production Ready: Stable and well-tested

Usage

# Preview changes without modifying files
./gradlew migrateMmdSimpleDryRun

# Apply migration
./gradlew migrateMmdSimple

# With custom mappings
./gradlew migrateMmdSimple -PmappingPath=/path/to/custom-mapping.json

When to Use

• ✅ Production projects
• ✅ Large codebases
• ✅ When you need reliable, predictable results
• ✅ Standard Material 3 to MMD migrations

---

Method 2: OpenRewrite Migration (Experimental) ⚠️

AST-based migration with precise syntax analysis - currently has limitations.

Features

• 🔬 AST-Based: Operates on Abstract Syntax Tree for precise transformations
• 🎯 Syntax-Aware: Understands Kotlin code structure
• ⚠️ Experimental: Not recommended for production use

Known Issues

• ❌ Unstable: May fail on some Kotlin constructs
• ❌ Slow: Significantly longer execution time for large projects
• ❌ Compatibility: Issues with some Gradle versions
• ❌ Limited Context-Aware: Less sophisticated than Simple Migration
• ❌ Configuration: May require additional setup

Usage

# Preview changes (dry-run)
./gradlew migrateToMmdDryRun

# Apply migration
./gradlew migrateToMmd

When to Use

• 🔬 Experimental/research purposes
• 🧪 Testing AST-based transformations
• 📚 Learning about OpenRewrite capabilities
• ⚠️ NOT recommended for production projects

---

Comparison

Feature	Simple Migration	OpenRewrite Migration
Speed	⚡ Fast (seconds)	🐢 Slow (minutes)
Stability	✅ Production-ready	⚠️ Experimental
Context-Aware	✅ Advanced	⚠️ Limited
UTF-8 Support	✅ Full validation	⚠️ Basic
Reports	✅ Detailed	⚠️ Basic
Dry-Run	✅ Yes	✅ Yes
Custom Mappings	✅ Yes	❌ No
Recommended	✅ Yes	❌ No

Recommendation: Use Simple Migration (migrateMmdSimple) for all production work. OpenRewrite is available for experimental purposes only.

---

🎯 Advanced Usage

Custom Mapping File

Override default component mappings:

./gradlew migrateMmdSimple -PmappingPath=/path/to/custom-mapping.json

Mapping Format:

{
  "components": [
    {
      "componentName": {
        "m3": "Button",
        "mmd": "ButtonMMD"
      },
      "additionalFields": {
        "m3": ["ButtonDefaults"],
        "mmd": ["ButtonDefaultsMMD"]
      },
      "sourcePackage": "androidx.compose.material3",
      "targetPackage": "com.mudita.mmd.components.buttons",
      "paramsToDrop": ["elevation", "interactionSource"]
    }
  ]
}

Disable UTF-8 Validation

If you need to skip encoding validation:

// In your build.gradle.kts
tasks.named<com.mudita.migration.gradle.SimpleMigrationTask>("migrateMmdSimple") {
    // Note: This is not directly configurable via task API yet
    // UTF-8 validation is enabled by default for safety
}

---

🏗️ Project Structure

mmd-migrator/
├── mmd-migrator-core/              # Core migration logic
│   ├── src/main/kotlin/
│   │   ├── simple/                 # Regex-based migrator (recommended)
│   │   │   ├── SimpleMigrator.kt
│   │   │   ├── core/               # CodeTransformer, MappingLoader
│   │   │   ├── validation/         # FileEncodingValidator
│   │   │   └── logger/             # Logging adapters
│   │   └── openrewrite/            # AST-based migrator (experimental)
│   │       ├── recipe/             # OpenRewrite recipes
│   │       │   ├── ButtonMigrationRecipe.kt
│   │       │   └── ...             # Other component recipes
│   │       └── MigrationExecutor.kt
│   └── src/main/resources/
│       ├── mapping.json            # Component mappings for simple migrator
│       └── META-INF/rewrite/       # OpenRewrite recipe descriptors
│
├── mmd-migrator-plugin/            # Gradle plugin wrapper
│   └── src/main/kotlin/
│       └── gradle/
│           ├── MmdMigratorPlugin.kt
│           ├── SimpleMigrationTask.kt      # Simple migration task
│           └── OpenRewriteMigrationTask.kt # OpenRewrite migration task
│
└── README.md

---

🧠 How It Works: Context-Aware Detection

The migrator uses intelligent context detection to avoid breaking code:

Example 1: Mixed Component Usage

// File contains both TextField (migrated) and OutlinedTextField (not migrated)

@Composable
fun MyForm() {
    TextField(
        value = text1,
        colors = TextFieldDefaults.colors()  // ✅ Migrated to TextFieldDefaultsMMD
    )
    
    OutlinedTextField(
        value = text2,
        colors = TextFieldDefaults.colors()  // ❌ Not migrated (OutlinedTextField not in MMD)
    )
}

Example 2: Button Variants

// File uses Button (migrated) and TextButton (not migrated)

@Composable
fun MyButtons() {
    Button(
        colors = ButtonDefaults.buttonColors()  // ✅ Migrated
    ) { }
    
    TextButton(
        colors = ButtonDefaults.textButtonColors()  // ❌ Not migrated
    ) { }
}

Multi-Pass Processing

Migration happens in phases:

1. Phase 1: Context-aware components (import-based)
2. Phase 1.5: Defaults inside already-migrated MMD components
3. Phase 2: Regular components
4. Phase 3: Smart property-based replacements
5. Phase 4: Revert unmigrated Defaults methods
6. Phase 5: Revert Defaults inside unmigrated siblings

---

🔧 For Plugin Developers

Building Locally

# Build and publish to Maven Local
./gradlew publishToMavenLocal

# Use in another project
# In settings.gradle.kts of target project:
pluginManagement {
    repositories {
        mavenLocal()
        gradlePluginPortal()
    }
}

Running Tests

# All tests
./gradlew test

# Simple migration tests only
./gradlew :mmd-migrator-core:test --tests "*simple*"

# Integration tests
./gradlew :mmd-migrator-core:test --tests "*Integration*"

# With verbose output
./gradlew test --info

Project Setup for Development

1. Clone the repository
2. Build the plugin: ./gradlew publishToMavenLocal
3. Create a test project with the plugin applied
4. Iterate:
   • Make changes in mmd-migrator-core or mmd-migrator-plugin
   • Run ./gradlew publishToMavenLocal
   • Test in your test project

---

📋 Requirements

• Kotlin: 2.1.0 or newer
• Gradle: 7.x or newer
• JDK: 11 or newer
• Project Type: Android or Kotlin with Jetpack Compose

---

⚠️ Known Limitations

1. Multi-line Raw Strings

The regex-based approach may not perfectly handle multi-line triple-quoted strings:

val text = """
    This is a
    multi-line string
    with Text("content")  // Might be incorrectly replaced
"""

Workaround: Review changes carefully in files with extensive multi-line strings.

2. Dynamic Component Names

Components resolved at runtime won't be detected:

val componentName = if (condition) "Button" else "Card"
// Cannot be migrated automatically

3. Reflection-Based Usage

Components accessed via reflection are not migrated:

val componentClass = Class.forName("androidx.compose.material3.Button")

---

🐛 Troubleshooting

Migration Doesn't Find Files

Issue: No files found or some files skipped.

Solution: The migrator only processes files that:

• Have .kt extension
• Contain @Composable annotation
• Import from androidx.compose.material3 or androidx.compose.foundation.lazy

Check if your files meet these criteria.

---

Encoding Errors

Issue: File encoding validation failed

Solution:

1. Ensure your files are UTF-8 encoded
2. Check for BOM (Byte Order Mark) - the migrator preserves it
3. Look for mixed line endings (CRLF vs LF)

---

Unexpected Changes

Issue: Some components were migrated incorrectly.

Solution:

1. Run dry-run first: ./gradlew migrateMmdSimpleDryRun
2. Review the changes carefully
3. Use version control to diff changes
4. Report issues with specific examples

---

Plugin Not Found

Issue: Plugin with id 'com.mudita.mmd-migrator' not found

Solution:

1. Ensure you've published to Maven Local: ./gradlew publishToMavenLocal
2. Check your settings.gradle.kts includes mavenLocal()
3. Verify the version number matches

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass: ./gradlew test
5. Submit a pull request

---

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

---

🙏 Acknowledgments

• Built with OpenRewrite for experimental AST-based transformations
• Powered by Kotlin and Gradle
• Inspired by the need for seamless design system migrations
• Primary migration engine uses custom regex-based approach for reliability and performance

---

📞 Support

• Issues: GitHub Issues
• Documentation: This README

---

Made with ❤️ by Mudita