Compatibility dan Migration

// compatibility_dan_migration.kt
// Mendemonstrasikan konsep kompatibilitas dan migrasi Kotlin:
// - binary compatibility (kotlin metadata)
// - language version dan api version
// - deprecation cycle (warning -> error -> removal)
// - migration tools (kotlin -Xfix)

// 1. Deprecation cycle — penggunaan @Deprecated
class PenyimpananLama {
    @Deprecated(
        message = "Gunakan ambilVersiBaru() — yang mengembalikan nullable",
        replaceWith = ReplaceWith("ambilVersiBaru()"),
        level = DeprecationLevel.WARNING
    )
    fun ambilVersiLama(): String = "data lama"

    fun ambilVersiBaru(): String? = null
}

// 2. Deprecation level ERROR — penggunaan langsung gagal compile
class ApiLama {
    @Deprecated(
        message = "API dihapus, migrasi ke ApiBaru",
        level = DeprecationLevel.ERROR
    )
    fun halu(): String = "halu"
}

class ApiBaru {
    fun halo(): String = "halo"
}

// 3. Binary compatibility — interface dan implementasi versi berbeda
interface Kontrak {
    val versi: Int
    fun proses(data: String): String
}

class ImplementasiLama : Kontrak {
    override val versi = 1
    override fun proses(data: String) = "v1:$data"
}

class ImplementasiBaru : Kontrak {
    override val versi = 2
    override fun proses(data: String) = "v2:$data (encoded)"
}

// 4. Language version dan API version
//    Di build.gradle.kts:
//      kotlin {
//        compilerOptions {
//          languageVersion.set(KotlinVersion.VERSION_2_0)
//          apiVersion.set(KotlinVersion.VERSION_2_0)
//        }
//      }
//    Untuk mengaktifkan fitur eksperimen:
//      freeCompilerArgs.add("-XXLanguage:+WhenGuards")

// 5. Migration helper — gunakan .replaceWith untuk auto-migrate
class Layanan {
    @Deprecated("Gunakan simpan(nama, data)", ReplaceWith("simpan(\"default\", data)"))
    fun simpan(data: String) = simpan("default", data)

    fun simpan(nama: String, data: String): String = "$nama=$data"
}

fun main() {
    println("=== Compatibility dan Migration ===")
    println()

    println("--- 1. Deprecation level WARNING ---")
    val lama = PenyimpananLama()
    println("Hasil: ${lama.ambilVersiBaru() ?: "(kosong)"}")
    println("Metode lama masih bisa dipanggil (dengan warning saat compile)")

    println()
    println("--- 2. Deprecation level ERROR ---")
    val baru = ApiBaru()
    println("ApiBaru.halo() = ${baru.halo()}")
    println("ApiLama.halu() gagal compile (DeprecationLevel.ERROR)")

    println()
    println("--- 3. Binary compatibility lewat interface ---")
    val daftar: List<Kontrak> = listOf(ImplementasiLama(), ImplementasiBaru())
    daftar.forEach {
        println("  versi ${it.versi}: ${it.proses("data-input")}")
    }

    println()
    println("--- 4. ReplaceWith untuk auto-migrate ---")
    val ls = Layanan()
    println("simpan(data=\"halo\")        = ${ls.simpan("halo")}")
    println("simpan(\"cache\", \"halo\")  = ${ls.simpan("cache", "halo")}")

    println()
    println("--- 5. Strategi migrasi ---")
    val strategi = listOf(
        "1. Update compiler ke versi target",
        "2. Set languageVersion dan apiVersion sesuai versi lama",
        "3. Jalankan build — perhatikan deprecation warning",
        "4. Migrasi bertahap menggunakan -Xfix=n",
        "5. Update languageVersion dan apiVersion ke versi baru",
        "6. Hapus kode kompatibilitas setelah semua dependensi dimigrasi"
    )
    strategi.forEach { println("  $it") }

    println()
    println("--- 6. Aturan kompatibilitas ---")
    val aturan = listOf(
        "Binary: bytecode tetap kompatibel (kotlin metadata menjamin)",
        "Source: kode lama harus tetap compile di compiler baru",
        "Behavior: hasil runtime tidak berubah (kecuali bug fix)",
        "Deprecation: 2 versi mayor sebelum removal (warning -> error -> hapus)"
    )
    aturan.forEach { println("  - $it") }
}

=== Compatibility dan Migration ===

--- 1. Deprecation level WARNING ---
Hasil: (kosong)
Metode lama masih bisa dipanggil (dengan warning saat compile)

--- 2. Deprecation level ERROR ---
ApiBaru.halo() = halo
ApiLama.halu() gagal compile (DeprecationLevel.ERROR)

--- 3. Binary compatibility lewat interface ---
  versi 1: v1:data-input
  versi 2: v2:data-input (encoded)

--- 4. ReplaceWith untuk auto-migrate ---
simpan(data="halo")        = default=halo
simpan("cache", "halo")  = cache=halo

--- 5. Strategi migrasi ---
  1. Update compiler ke versi target
  2. Set languageVersion dan apiVersion sesuai versi lama
  3. Jalankan build — perhatikan deprecation warning
  4. Migrasi bertahap menggunakan -Xfix=n
  5. Update languageVersion dan apiVersion ke versi baru
  6. Hapus kode kompatibilitas setelah semua dependensi dimigrasi

--- 6. Aturan kompatibilitas ---
  - Binary: bytecode tetap kompatibel (kotlin metadata menjamin)
  - Source: kode lama harus tetap compile di compiler baru
  - Behavior: hasil runtime tidak berubah (kecuali bug fix)
  - Deprecation: 2 versi mayor sebelum removal (warning -> error -> hapus)

kotlin {
    compilerOptions {
        languageVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.VERSION_2_0)
        apiVersion.set(org.jetbrains.kotlin.gradle.dsl.KotlinVersion.VERSION_2_0)
    }
}

plugins {
    id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.16.3"
}

apiValidation {
    ignoredPackages.add("kotlinx.coroutines.internal")
    nonPublicMarkers.add("kotlin.PublishedApi")
}