generate-compat-matrix.main.kts

#!/usr/bin/env kotlin
@file:DependsOn("com.github.ajalt.clikt:clikt-jvm:5.0.3")
@file:DependsOn("com.squareup.moshi:moshi:1.15.2")
@file:DependsOn("com.squareup.moshi:moshi-kotlin:1.15.2")
@file:DependsOn("com.squareup.okhttp3:okhttp:4.12.0")
@file:DependsOn("com.google.guava:guava:33.4.0-jre")
@file:DependsOn("io.github.z4kn4fein:semver-jvm:3.0.0")
@file:DependsOn("org.jsoup:jsoup:1.17.2")

import com.github.ajalt.clikt.core.CliktCommand
import com.github.ajalt.clikt.core.ProgramResult
import com.github.ajalt.clikt.core.main
import com.squareup.moshi.Moshi
import com.squareup.moshi.adapter
import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
import io.github.z4kn4fein.semver.Version
import io.github.z4kn4fein.semver.toVersion
import java.net.URL
import javax.xml.parsers.DocumentBuilderFactory
import org.jsoup.Jsoup
import org.w3c.dom.Element

/** Represents a matrix consumed by GitHub actions */
class Matrix(val include: List<Map<String, String>>)

data class VersionRange(val min: Version, val max: Version) {
  fun inRange(version: Version): Boolean {
    return version >= min && version <= max
  }
}

/** Generates a matrix of different build tools we use. */
class GenerateMatrix : CliktCommand() {

  // TODO: introduce params if needed
  //  private val gradleProperties: File by option("--gradle-properties").file().required()
  //  private val versionsToml: File by option("--versions-toml").file().required()

  @OptIn(ExperimentalStdlibApi::class)
  override fun run() {
    val moshi = Moshi.Builder().add(KotlinJsonAdapterFactory()).build()

    /**
     * we test against AGP:
     * - Latest stable
     * - Pre-release alpha
     * - Pre-release beta/rc
     * - Latest version from previous major release
     */
    @Suppress("SwallowedException", "TooGenericExceptionCaught")
    val agpVersions =
      try {
        fetchAgpVersions()
      } catch (e: Exception) {
        print(e.printStackTrace())
        echo("Error parsing AGP versions")
        throw ProgramResult(1)
      }

    val agpToGradle =
      try {
        val (compatVersions, latestVersion) = fetchAgpCompatibilityTable(agpVersions)
        buildMap<Version, Version> {
          for (agpVersion in agpVersions) {
            val gradleVersion =
              compatVersions[agpVersion]
                ?: fetchGradleVersionFromReleaseNotes(agpVersion)
                ?: latestVersion
            put(agpVersion, gradleVersion)
          }
        }
      } catch (e: Exception) {
        print(e.printStackTrace())
        echo("Error parsing AGP compatibility table")
        throw ProgramResult(1)
      }

    // Fetch Kotlin minimum supported Gradle version
    val kotlinToGradleMap =
      try {
        fetchKotlinGradleCompatibility()
      } catch (e: Exception) {
        print(e.printStackTrace())
        echo("Error parsing Kotlin Gradle compatibility")
        throw ProgramResult(1)
      }

    val agpToKotlin =
      try {
        fetchAgpKotlinCompatibility()
      } catch (e: Exception) {
        print(e.printStackTrace())
        echo("Error parsing AGP Kotlin compatibility")
        throw ProgramResult(1)
      }

    val baseIncludes = buildList {
      for (entry in agpToGradle.entries) {
        add(
          buildMap {
            val agpVersion = entry.key
            put("agp", agpVersion.toString())
            val gradle = entry.value

            // Pick the latest Kotlin whose required AGP <= this AGP. Strip the pre-release
            // identifier so 9.3.0-alpha01 isn't treated as < 9.3.0 by semver rules, which would
            // skip a row that should match.
            val agpStable = Version(agpVersion.major, agpVersion.minor, agpVersion.patch)
            val kotlinVersion =
              agpToKotlin
                .filter { (minAgp, _) -> agpStable >= minAgp }
                .maxByOrNull { it.second }
                ?.second

            // Floor: if the chosen Kotlin requires a newer Gradle than AGP does, bump Gradle up
            val kotlinMinGradle =
              kotlinVersion?.let { kv ->
                kotlinToGradleMap.entries.find { (kotlin, _) -> kotlin.inRange(kv) }?.value?.min
              }
            val finalGradle =
              if (kotlinMinGradle != null && gradle < kotlinMinGradle) {
                echo(
                  "Warning: Gradle ${gradle} for AGP ${entry.key} is below Kotlin minimum ${kotlinMinGradle}"
                )
                kotlinMinGradle
              } else {
                gradle
              }

            // Gradle does not use .patch if it's 0 ¯\_(ツ)_/¯, but only in Gradle < 9 :D
            val (finalMajor, finalMinor, finalPatch) = finalGradle
            put(
              "gradle",
              if (finalMajor < 9 && finalPatch == 0) "${finalMajor}.${finalMinor}"
              else finalGradle.toString(),
            )
            // TODO: if needed we can test against different Java versions
            put("java", "17")
            if (kotlinVersion != null) {
              put("kotlin", kotlinVersion.toString())
            }
          }
        )
      }
    }

    val allIncludes = baseIncludes + extraIncludes(baseIncludes)

    val json = moshi.adapter<Matrix>().toJson(Matrix(allIncludes))

    // Example output:
    // {"include":[{"agp":"8.11.0-alpha08","gradle":"8.11.1","java":"17","groovy":"1.7.1"},{"agp":"8.10.0-rc04","gradle":"8.11.1","java":"17","groovy":"1.7.1"},{"agp":"8.9.2","gradle":"8.11.1","java":"17","groovy":"1.7.1"},{"agp":"7.4.2","gradle":"7.5","java":"17","groovy":"1.2"}]}
    echo(json)
  }

  /** Add extra configuration */
  @Suppress("UNUSED_PARAMETER")
  private fun extraIncludes(baseIncludes: List<Map<String, String>>): List<Map<String, String>> {
    return emptyList()
    //    return baseIncludes.map { matrix ->
    //      matrix.toMutableMap().apply {
    //        put("kotlin", "x.y.z")
    //      }
    //    }
  }

  /**
   * Fetches Kotlin minimum supported Gradle version mapping from the official Kotlin documentation
   *
   * @return Map where key is Kotlin version range and value is Gradle version range
   */
  private fun fetchKotlinGradleCompatibility(): Map<VersionRange, VersionRange> {
    return try {
      // Parse the official Kotlin documentation page for compatibility info
      val html = URL("https://kotlinlang.org/docs/gradle-configure-project.html").readText()
      val doc = Jsoup.parse(html)

      // Look for the compatibility table
      val tables = doc.select("table")
      val compatibilityTable =
        tables.find { table ->
          val headers = table.select("th").map { it.text() }
          headers.any { it.contains("KGP version", ignoreCase = true) } &&
            headers.any { it.contains("Gradle", ignoreCase = true) }
        }

      val kotlinToGradleMap = mutableMapOf<VersionRange, VersionRange>()

      if (compatibilityTable != null) {
        val rows = compatibilityTable.select("tr")
        // Skip header row and process all data rows
        rows.drop(1).forEach { row ->
          val cells = row.select("td").map { it.text().trim() }
          if (cells.size >= 2) {
            val kotlinVersionRange = cells[0]
            val gradleVersionRange = cells[1]

            try {
              val kotlinRange = parseVersionRange(kotlinVersionRange)
              val gradleRange = parseVersionRange(gradleVersionRange)

              kotlinToGradleMap[kotlinRange] = gradleRange
            } catch (e: Exception) {
              echo(
                "Warning: Could not parse Kotlin/Gradle versions: $kotlinVersionRange, $gradleVersionRange - ${e.message}"
              )
            }
          }
        }
      }

      kotlinToGradleMap
    } catch (e: Exception) {
      echo("Warning: Could not fetch Kotlin compatibility from docs: ${e.message}")
      emptyMap()
    }
  }

  /**
   * Parses a version range string and returns a VersionRange object Examples:
   * - "2.2.0" -> VersionRange(Version("2.2.0"), Version("2.2.0"))
   * - "2.1.20-2.1.21" -> VersionRange(Version("2.1.20"), Version("2.1.21"))
   * - "7.6.3–8.14" -> VersionRange(Version("7.6.3"), Version("8.14"))
   */
  private fun parseVersionRange(versionRangeString: String): VersionRange {
    // Check if it's a range or single version
    val rangeSeparators = listOf("–", "-", "—") // different dash types
    val separator = rangeSeparators.find { versionRangeString.contains(it) }

    if (separator != null) {
      // It's a range
      val parts = versionRangeString.split(separator, limit = 2)
      if (parts.size == 2) {
        val startVersion = sanitizeVersion(parts[0].trim())
        val endVersion = sanitizeVersion(parts[1].trim())

        val start = startVersion.toVersion(strict = false)
        val end = endVersion.toVersion(strict = false)

        return VersionRange(start, end)
      } else {
        throw IllegalArgumentException("Invalid range format: $versionRangeString")
      }
    } else {
      // Single version
      val cleanVersion = sanitizeVersion(versionRangeString)
      val version = cleanVersion.toVersion(strict = false)
      return VersionRange(version, version)
    }
  }

  /**
   * Sanitizes version strings by removing or converting special characters that are not compatible
   * with semantic versioning
   */
  private fun sanitizeVersion(versionString: String): String {
    return versionString
      .replace("*", "") // Remove asterisks (e.g., "8.10*" -> "8.10")
      .replace("+", "") // Remove plus signs (e.g., "8.10+" -> "8.10")
      .replace("\\", "") // Remove backslashes
      .trim()
  }

  private fun fetchAgpVersions(): List<Version> {
    val semvers = mutableListOf<Version>()
    val documentBuilder = DocumentBuilderFactory.newInstance().newDocumentBuilder()
    val document =
      documentBuilder.parse(
        "https://dl.google.com/dl/android/maven2/com/android/tools/build/group-index.xml"
      )
    document.documentElement.normalize()

    val root = document.documentElement
    val gradleElements = root.getElementsByTagName("gradle")
    for (i in 0 until gradleElements.length) {
      val element = gradleElements.item(i) as Element
      val versions = element.getAttribute("versions")
      versions.split(",").forEach { version ->
        val semver = Version.parse(version, strict = false)
        semvers += semver
      }
    }

    // AGP usually has two pre-releases at the same time
    val latestPreRelease = semvers.last { it.isPreRelease }
    var secondToLatestPreRelease =
      semvers.lastOrNull { it.isPreRelease && it.minor == (latestPreRelease.minor - 1) }
    if (secondToLatestPreRelease == null) {
      // this means the previous pre-release is actually in the previous major
      secondToLatestPreRelease =
        semvers.last { it.isPreRelease && it.major == (latestPreRelease.major - 1) }
    }
    val latest = semvers.last { it.isStable }
    val previousMajorLatest = semvers.last { it.isStable && it.major == (latest.major - 1) }
    return listOf(latestPreRelease, secondToLatestPreRelease, latest, previousMajorLatest)
  }

  /**
   * Fetches the AGP -> Gradle compatibility table from Android Studio's CompatibleGradleVersion.kt,
   * which is kept more up-to-date than the public developer.android.com page. The file is served
   * base64-encoded by gitiles when using `?format=TEXT`.
   */
  private fun fetchAgpCompatibilityTable(
    agpVersions: List<Version>
  ): Pair<Map<Version, Version>, Version> {
    val source =
      fetchGooglesourceText(
        "https://android.googlesource.com/platform/tools/adt/idea/+/refs/heads/mirror-goog-studio-main/build-common/src/com/android/tools/idea/gradle/util/CompatibleGradleVersion.kt?format=TEXT"
      )

    // Enum entries: VERSION_X_Y_Z(GradleVersion.version("X.Y.Z")).
    // VERSION_FOR_DEV references a constant instead of a literal and is handled separately below.
    val enumRegex = Regex("""(VERSION_[A-Z0-9_]+)\s*\(\s*GradleVersion\.version\("([^"]+)"\)""")
    val enumToGradle = mutableMapOf<String, Version>()
    enumRegex.findAll(source).forEach { match ->
      val (enumName, versionStr) = match.destructured
      val v =
        parseVersionOrNull(versionStr)
          ?: run {
            echo("Warning: could not parse Gradle version '$versionStr' for $enumName")
            return@forEach
          }
      enumToGradle[enumName] = v
    }
    // VERSION_FOR_DEV points at SdkConstants.GRADLE_LATEST_VERSION, which is declared in a
    // different file — fetch it so AGP pre-releases get the correct bleeding-edge Gradle version.
    enumToGradle["VERSION_FOR_DEV"] = fetchGradleLatestVersion()
    val latestGradle =
      enumToGradle.values.maxOrNull()
        ?: error("No parseable Gradle versions found in CompatibleGradleVersion.kt")

    // Map entries: AgpVersion.parse("X.Y.Z") to VERSION_A_B_C
    val mapRegex = Regex("""AgpVersion\.parse\("([^"]+)"\)\s*to\s*(VERSION_[A-Z0-9_]+)""")
    val agpToGradle = LinkedHashMap<Version, Version>()
    mapRegex.findAll(source).forEach { match ->
      val (agpStr, enumName) = match.destructured
      val agp =
        parseVersionOrNull(agpStr)
          ?: run {
            echo("Warning: could not parse AGP version '$agpStr'")
            return@forEach
          }
      val gradle = enumToGradle[enumName] ?: return@forEach
      agpToGradle[agp] = gradle
    }

    if (agpToGradle.isEmpty()) {
      error("No AGP->Gradle entries parsed from CompatibleGradleVersion.kt")
    }

    val gradleVersions = mutableMapOf<Version, Version>()
    for (agpVersion in agpVersions) {
      // the table keys use representative .0 patches, so match by major/minor
      val entry =
        agpToGradle.entries.find {
          it.key.major == agpVersion.major && it.key.minor == agpVersion.minor
        }
      if (entry != null) {
        gradleVersions[agpVersion] = entry.value
      }
    }

    return gradleVersions to latestGradle
  }

  /**
   * Fetches the AGP -> Kotlin compatibility table from developer.android.com/build/kotlin-support,
   * and resolves each Kotlin minor to its latest stable patch on Maven Central. Rows whose Kotlin
   * minor has no stable release yet (e.g. Kotlin 2.4 while only 2.4.0-Beta* is published) are
   * dropped so the matrix never references an unreleased version.
   */
  private fun fetchAgpKotlinCompatibility(): List<Pair<Version, Version>> {
    val html = URL("https://developer.android.com/build/kotlin-support").readText()
    val doc = Jsoup.parse(html)
    val table =
      doc.select("table").find { t ->
        val headers = t.select("th").map { it.text() }
        headers.any { it.contains("Kotlin version", ignoreCase = true) } &&
          headers.any { it.contains("Required AGP", ignoreCase = true) }
      } ?: error("Could not find AGP/Kotlin compatibility table")

    val latestStablePatches = fetchLatestStableKotlinPatches()

    // Cells may carry footnote markers like "8.13.19[1]"; extract the leading x.y[.z] token.
    val versionRegex = Regex("""\d+\.\d+(\.\d+)?""")
    val result = mutableListOf<Pair<Version, Version>>()
    for (row in table.select("tr").drop(1)) {
      val cells = row.select("td").map { it.text() }
      if (cells.size < 2) continue
      val kotlin = versionRegex.find(cells[0])?.value?.let(::parseVersionOrNull) ?: continue
      val agp = versionRegex.find(cells[1])?.value?.let(::parseVersionOrNull) ?: continue
      val stableKotlin = latestStablePatches[kotlin.major to kotlin.minor]
      if (stableKotlin == null) {
        echo("Warning: Kotlin ${kotlin.major}.${kotlin.minor} has no stable release yet, skipping")
        continue
      }
      result += agp to stableKotlin
    }
    if (result.isEmpty()) error("No rows parsed from AGP/Kotlin compatibility table")
    return result
  }

  /**
   * Reads kotlin-stdlib's maven-metadata.xml and returns, per Kotlin major.minor, the highest
   * published stable patch version.
   */
  private fun fetchLatestStableKotlinPatches(): Map<Pair<Int, Int>, Version> {
    val documentBuilder = DocumentBuilderFactory.newInstance().newDocumentBuilder()
    val document =
      documentBuilder.parse(
        "https://repo1.maven.org/maven2/org/jetbrains/kotlin/kotlin-stdlib/maven-metadata.xml"
      )
    document.documentElement.normalize()
    val versionNodes = document.documentElement.getElementsByTagName("version")
    val stable = mutableListOf<Version>()
    for (i in 0 until versionNodes.length) {
      val v = parseVersionOrNull(versionNodes.item(i).textContent) ?: continue
      if (v.isStable) stable += v
    }
    return stable.groupBy { it.major to it.minor }.mapValues { (_, vs) -> vs.max() }
  }

  /**
   * Fetches the value of `SdkConstants.GRADLE_LATEST_VERSION` from Android Studio's source, used to
   * resolve `CompatibleGradleVersion.VERSION_FOR_DEV` for bleeding-edge AGP versions.
   */
  private fun fetchGradleLatestVersion(): Version {
    val source =
      fetchGooglesourceText(
        "https://android.googlesource.com/platform/tools/base/+/refs/heads/mirror-goog-studio-main/common/src/main/java/com/android/SdkConstants.java?format=TEXT"
      )
    val match =
      Regex("""GRADLE_LATEST_VERSION\s*=\s*"([^"]+)"""").find(source)
        ?: error("GRADLE_LATEST_VERSION not found in SdkConstants.java")
    return Version.parse(match.groupValues[1], strict = false)
  }

  /** Decodes gitiles' `?format=TEXT` response (base64-encoded) to raw source text. */
  private fun fetchGooglesourceText(url: String): String =
    URL(url).readText().let { String(java.util.Base64.getDecoder().decode(it)) }

  private fun parseVersionOrNull(s: String): Version? =
    try {
      Version.parse(s, strict = false)
    } catch (_: Throwable) {
      null
    }

  /**
   * Fetches the minimum required Gradle version from the AGP release notes page. This is used as a
   * fallback when the AGP version is not yet listed in the compatibility table.
   *
   * @param agpVersion the AGP version to look up
   * @return the minimum required Gradle version, or null if the release notes page doesn't exist
   */
  private fun fetchGradleVersionFromReleaseNotes(agpVersion: Version): Version? {
    // Release notes URLs are per-minor version and always use patch 0
    // e.g. agp-9-2-0-release-notes covers all 9.2.x versions
    val url =
      "https://developer.android.com/build/releases/agp-${agpVersion.major}-${agpVersion.minor}-0-release-notes"
    val html =
      try {
        URL(url).readText()
      } catch (e: Throwable) {
        echo("Warning: Could not fetch release notes from $url")
        return null
      }
    val doc = Jsoup.parse(html)
    val tables = doc.select("table")
    for (table in tables) {
      val headers = table.select("tr").firstOrNull()?.select("th")?.map { it.text() } ?: continue
      // The compatibility table has "Minimum version" and "Default version" columns
      if (headers.none { it.contains("version", ignoreCase = true) }) continue
      for (row in table.select("tr")) {
        val cells = row.select("td").map { it.text() }
        if (cells.size >= 2 && cells[0].trim().equals("Gradle", ignoreCase = true)) {
          return parseVersionOrNull(cells[1])
            ?: run {
              echo("Warning: Could not parse Gradle version '${cells[1]}' from release notes")
              null
            }
        }
      }
    }
    return null
  }
}

GenerateMatrix().main(args)