@mmerterden/multi-agent-pipeline 20.1.0 → 20.2.0

package/pipeline/skills/shared/external/gradle-kotlin-dsl/references/patterns.md

@@ -0,0 +1,715 @@
+# Gradle Kotlin DSL Patterns
+
+Full code examples backing the guidance in `SKILL.md`. Headings mirror the
+SKILL.md sections.
+
+## Contents
+
+- [Version Catalog](#version-catalog)
+- [Convention Plugins](#convention-plugins)
+- [App Module Configuration](#app-module-configuration)
+- [Library Module Configuration](#library-module-configuration)
+- [Compose Configuration](#compose-configuration)
+- [Build Variants and Flavors](#build-variants-and-flavors)
+- [Signing Config](#signing-config)
+- [R8 and ProGuard](#r8-and-proguard)
+- [Build Performance](#build-performance)
+- [Typed BuildConfig Injection](#typed-buildconfig-injection)
+- [Typed Module Paths and Flavors](#typed-module-paths-and-flavors)
+- [Convention Plugin Composition](#convention-plugin-composition)
+- [Fast-Feedback Tasks](#fast-feedback-tasks)
+
+## Version Catalog
+
+Define all versions, libraries, and plugins in `gradle/libs.versions.toml`:
+
+```toml
+[versions]
+agp = "8.7.3"
+kotlin = "2.1.0"
+ksp = "2.1.0-1.0.29"
+compose-bom = "2024.12.01"
+hilt = "2.53.1"
+room = "2.6.1"
+retrofit = "2.11.0"
+okhttp = "4.12.0"
+coroutines = "1.9.0"
+lifecycle = "2.8.7"
+navigation = "2.8.5"
+serialization = "1.7.3"
+coil = "2.7.0"
+turbine = "1.2.0"
+roborazzi = "1.32.2"
+
+[libraries]
+# Compose
+compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
+compose-ui = { group = "androidx.compose.ui", name = "ui" }
+compose-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
+compose-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
+compose-material3 = { group = "androidx.compose.material3", name = "material3" }
+compose-runtime = { group = "androidx.compose.runtime", name = "runtime" }
+
+# Lifecycle
+lifecycle-runtime-compose = { group = "androidx.lifecycle", name = "lifecycle-runtime-compose", version.ref = "lifecycle" }
+lifecycle-viewmodel-compose = { group = "androidx.lifecycle", name = "lifecycle-viewmodel-compose", version.ref = "lifecycle" }
+
+# Navigation
+navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }
+
+# Hilt
+hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
+hilt-compiler = { group = "com.google.dagger", name = "hilt-android-compiler", version.ref = "hilt" }
+hilt-navigation-compose = { group = "androidx.hilt", name = "hilt-navigation-compose", version = "1.2.0" }
+
+# Room
+room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
+room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
+room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
+room-testing = { group = "androidx.room", name = "room-testing", version.ref = "room" }
+
+# Network
+retrofit = { group = "com.squareup.retrofit2", name = "retrofit", version.ref = "retrofit" }
+okhttp = { group = "com.squareup.okhttp3", name = "okhttp", version.ref = "okhttp" }
+okhttp-logging = { group = "com.squareup.okhttp3", name = "logging-interceptor", version.ref = "okhttp" }
+serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "serialization" }
+retrofit-serialization = { group = "com.squareup.retrofit2", name = "converter-kotlinx-serialization", version = "2.11.0" }
+
+# Coroutines
+coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
+coroutines-android = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-android", version.ref = "coroutines" }
+coroutines-test = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-test", version.ref = "coroutines" }
+
+# Image loading
+coil-compose = { group = "io.coil-kt", name = "coil-compose", version.ref = "coil" }
+
+# Testing
+junit = { group = "junit", name = "junit", version = "4.13.2" }
+turbine = { group = "app.cash.turbine", name = "turbine", version.ref = "turbine" }
+truth = { group = "com.google.truth", name = "truth", version = "1.4.4" }
+compose-ui-test = { group = "androidx.compose.ui", name = "ui-test-junit4" }
+compose-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
+roborazzi = { group = "io.github.takahirom.roborazzi", name = "roborazzi", version.ref = "roborazzi" }
+roborazzi-compose = { group = "io.github.takahirom.roborazzi", name = "roborazzi-compose", version.ref = "roborazzi" }
+
+[bundles]
+compose = ["compose-ui", "compose-ui-tooling-preview", "compose-material3", "compose-runtime"]
+compose-debug = ["compose-ui-tooling", "compose-ui-test-manifest"]
+lifecycle = ["lifecycle-runtime-compose", "lifecycle-viewmodel-compose"]
+room = ["room-runtime", "room-ktx"]
+network = ["retrofit", "okhttp", "okhttp-logging", "serialization-json", "retrofit-serialization"]
+
+[plugins]
+android-application = { id = "com.android.application", version.ref = "agp" }
+android-library = { id = "com.android.library", version.ref = "agp" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+room = { id = "androidx.room", version.ref = "room" }
+```
+
+## Convention Plugins
+
+Create a `build-logic` module to share common configurations:
+
+### settings.gradle.kts (root)
+
+```kotlin
+pluginManagement {
+    includeBuild("build-logic")
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+```
+
+### build-logic/settings.gradle.kts
+
+```kotlin
+dependencyResolutionManagement {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}
+
+include(":convention")
+```
+
+### build-logic/convention/build.gradle.kts
+
+```kotlin
+plugins {
+    `kotlin-dsl`
+}
+
+dependencies {
+    compileOnly(libs.android.gradlePlugin)
+    compileOnly(libs.kotlin.gradlePlugin)
+    compileOnly(libs.compose.gradlePlugin)
+}
+```
+
+### Android Library Convention Plugin
+
+```kotlin
+// build-logic/convention/src/main/kotlin/AndroidLibraryConventionPlugin.kt
+import com.android.build.gradle.LibraryExtension
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.configure
+
+class AndroidLibraryConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) {
+        with(target) {
+            with(pluginManager) {
+                apply("com.android.library")
+                apply("org.jetbrains.kotlin.android")
+            }
+
+            extensions.configure<LibraryExtension> {
+                compileSdk = 35
+                defaultConfig {
+                    minSdk = 26
+                    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+                }
+                compileOptions {
+                    sourceCompatibility = JavaVersion.VERSION_17
+                    targetCompatibility = JavaVersion.VERSION_17
+                }
+            }
+        }
+    }
+}
+```
+
+### Register in build-logic/convention/build.gradle.kts
+
+```kotlin
+gradlePlugin {
+    plugins {
+        register("androidLibrary") {
+            id = "app.android.library"
+            implementationClass = "AndroidLibraryConventionPlugin"
+        }
+        register("androidCompose") {
+            id = "app.android.compose"
+            implementationClass = "AndroidComposeConventionPlugin"
+        }
+        register("androidHilt") {
+            id = "app.android.hilt"
+            implementationClass = "AndroidHiltConventionPlugin"
+        }
+    }
+}
+```
+
+### Usage in Feature Module
+
+```kotlin
+// feature/home/build.gradle.kts
+plugins {
+    id("app.android.library")
+    id("app.android.compose")
+    id("app.android.hilt")
+}
+
+dependencies {
+    implementation(project(":core:model"))
+    implementation(project(":core:data"))
+    implementation(project(":core:ui"))
+}
+```
+
+## App Module Configuration
+
+```kotlin
+// app/build.gradle.kts
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.compose.compiler)
+    alias(libs.plugins.hilt)
+    alias(libs.plugins.ksp)
+}
+
+android {
+    namespace = "com.example.app"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "com.example.app"
+        minSdk = 26
+        targetSdk = 35
+        versionCode = 1
+        versionName = "1.0.0"
+        testInstrumentationRunner = "com.example.app.HiltTestRunner"
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
+        debug {
+            isMinifyEnabled = false
+            applicationIdSuffix = ".debug"
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+}
+
+dependencies {
+    implementation(platform(libs.compose.bom))
+    implementation(libs.bundles.compose)
+    implementation(libs.bundles.lifecycle)
+    implementation(libs.navigation.compose)
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+    implementation(libs.hilt.navigation.compose)
+
+    debugImplementation(libs.bundles.compose.debug)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.truth)
+    testImplementation(libs.coroutines.test)
+    testImplementation(libs.turbine)
+
+    androidTestImplementation(platform(libs.compose.bom))
+    androidTestImplementation(libs.compose.ui.test)
+}
+```
+
+## Library Module Configuration
+
+```kotlin
+// core/data/build.gradle.kts
+plugins {
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.hilt)
+    alias(libs.plugins.ksp)
+}
+
+android {
+    namespace = "com.example.core.data"
+    compileSdk = 35
+
+    defaultConfig {
+        minSdk = 26
+    }
+}
+
+dependencies {
+    implementation(project(":core:model"))
+    implementation(project(":core:network"))
+    implementation(project(":core:database"))
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)
+    implementation(libs.coroutines.core)
+
+    testImplementation(libs.junit)
+    testImplementation(libs.truth)
+    testImplementation(libs.coroutines.test)
+}
+```
+
+## Compose Configuration
+
+```kotlin
+// Convention plugin or inline
+android {
+    buildFeatures {
+        compose = true
+    }
+}
+
+// With Kotlin 2.0+, use the Compose Compiler plugin:
+plugins {
+    alias(libs.plugins.compose.compiler)
+}
+
+// Optional: Compose compiler metrics for performance debugging
+// In gradle.properties or via command line:
+// composeCompiler.reportsDestination=build/compose-reports
+// composeCompiler.metricsDestination=build/compose-metrics
+```
+
+## Build Variants and Flavors
+
+```kotlin
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+        debug {
+            isMinifyEnabled = false
+            applicationIdSuffix = ".debug"
+            isDebuggable = true
+        }
+        create("staging") {
+            initWith(getByName("release"))
+            applicationIdSuffix = ".staging"
+            isMinifyEnabled = true
+            matchingFallbacks += "release"
+        }
+    }
+
+    flavorDimensions += "environment"
+    productFlavors {
+        create("dev") {
+            dimension = "environment"
+            applicationIdSuffix = ".dev"
+            buildConfigField("String", "BASE_URL", "\"https://dev-api.example.com/\"")
+        }
+        create("prod") {
+            dimension = "environment"
+            buildConfigField("String", "BASE_URL", "\"https://api.example.com/\"")
+        }
+    }
+}
+```
+
+## Signing Config
+
+```kotlin
+android {
+    signingConfigs {
+        create("release") {
+            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "release.keystore")
+            storePassword = System.getenv("KEYSTORE_PASSWORD") ?: ""
+            keyAlias = System.getenv("KEY_ALIAS") ?: ""
+            keyPassword = System.getenv("KEY_PASSWORD") ?: ""
+        }
+    }
+
+    buildTypes {
+        release {
+            signingConfig = signingConfigs.getByName("release")
+        }
+    }
+}
+```
+
+Never commit keystore passwords. Use environment variables or `local.properties` (gitignored).
+
+## R8 and ProGuard
+
+### proguard-rules.pro
+
+```proguard
+# Kotlin serialization
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+
+-keepclassmembers class kotlinx.serialization.json.** {
+    *** Companion;
+}
+-keepclasseswithmembers class kotlinx.serialization.json.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+-keep,includedescriptorclasses class com.example.app.data.dto.**$$serializer { *; }
+-keepclassmembers class com.example.app.data.dto.** {
+    *** Companion;
+}
+-keepclasseswithmembers class com.example.app.data.dto.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+# Retrofit
+-keepattributes Signature
+-keepattributes Exceptions
+-keepclassmembers,allowshrinking,allowobfuscation interface * {
+    @retrofit2.http.* <methods>;
+}
+-dontwarn javax.annotation.**
+-dontwarn kotlin.Unit
+-dontwarn retrofit2.KotlinExtensions
+-dontwarn retrofit2.KotlinExtensions$*
+
+# OkHttp
+-dontwarn okhttp3.internal.platform.**
+-dontwarn org.conscrypt.**
+-dontwarn org.bouncycastle.**
+-dontwarn org.openjsse.**
+
+# Hilt
+-keep class dagger.hilt.** { *; }
+```
+
+## Build Performance
+
+### gradle.properties
+
+```properties
+# Parallel execution
+org.gradle.parallel=true
+
+# Configuration cache
+org.gradle.configuration-cache=true
+
+# Build cache
+org.gradle.caching=true
+
+# JVM memory
+org.gradle.jvmargs=-Xmx4g -XX:+UseG1GC -XX:MaxMetaspaceSize=1g
+
+# Kotlin daemon
+kotlin.daemon.jvmargs=-Xmx2g
+
+# Non-transitive R classes (reduces rebuild scope)
+android.nonTransitiveRClass=true
+
+# Disable unused features
+android.defaults.buildfeatures.buildconfig=false
+android.defaults.buildfeatures.aidl=false
+android.defaults.buildfeatures.renderscript=false
+```
+
+### Dependency Locking
+
+```kotlin
+dependencyLocking {
+    lockAllConfigurations()
+}
+
+// Generate lock files: ./gradlew dependencies --write-locks
+```
+
+## Typed BuildConfig Injection
+
+Replace scattered `buildConfigField("String", "BASE_URL", "\"...\"")` calls with a
+typed key enum, per-module contributor objects, and a central resolver that
+filters by module scope and de-dupes.
+
+```kotlin
+// build-logic/convention/src/main/kotlin/buildconfig/BuildConfigKey.kt
+enum class BuildConfigKey(val javaType: String) {
+    BASE_URL("String"),
+    ANALYTICS_ENABLED("boolean"),
+    API_TIMEOUT_SECONDS("int"),
+}
+
+enum class ModuleScope { APP, FEATURE, ALL }
+
+data class BuildConfigEntry(
+    val key: BuildConfigKey,
+    val value: String,
+    val scope: ModuleScope = ModuleScope.ALL,
+)
+
+interface BuildConfigContributor {
+    fun entries(flavor: Flavor): List<BuildConfigEntry>
+}
+
+object BuildConfigResolver {
+    fun resolve(
+        contributors: List<BuildConfigContributor>,
+        scope: ModuleScope,
+        flavor: Flavor,
+    ): List<BuildConfigEntry> =
+        contributors
+            .flatMap { it.entries(flavor) }
+            .filter { it.scope == scope || it.scope == ModuleScope.ALL }
+            .distinctBy { it.key }
+}
+```
+
+A contributor lives next to the module it belongs to:
+
+```kotlin
+object NetworkBuildConfig : BuildConfigContributor {
+    override fun entries(flavor: Flavor) = listOf(
+        BuildConfigEntry(
+            key = BuildConfigKey.BASE_URL,
+            value = "\"${flavor.baseUrl}\"",
+        ),
+        BuildConfigEntry(
+            key = BuildConfigKey.API_TIMEOUT_SECONDS,
+            value = "30",
+            scope = ModuleScope.ALL,
+        ),
+    )
+}
+```
+
+The convention plugin materializes the resolved entries once per flavor, so the
+`javaType` is always correct and no module hand-writes a `buildConfigField`:
+
+```kotlin
+internal fun VariantDimension.applyBuildConfig(
+    resolver: BuildConfigResolver,
+    contributors: List<BuildConfigContributor>,
+    scope: ModuleScope,
+    flavor: Flavor,
+) {
+    resolver.resolve(contributors, scope, flavor).forEach { entry ->
+        buildConfigField(entry.key.javaType, entry.key.name, entry.value)
+    }
+}
+```
+
+## Typed Module Paths and Flavors
+
+Model module paths and flavors as sealed/enum types so builds reference
+`Module.Core.Domain.toProject()` instead of the stringly-typed
+`project(":core:domain")`.
+
+```kotlin
+// build-logic/convention/src/main/kotlin/Module.kt
+sealed interface Module {
+    val path: String
+
+    sealed interface Core : Module {
+        data object Domain : Core { override val path = ":core:domain" }
+        data object Data : Core { override val path = ":core:data" }
+        data object Ui : Core { override val path = ":core:ui" }
+    }
+
+    sealed interface Feature : Module {
+        data object Home : Feature { override val path = ":feature:home" }
+        data object Profile : Feature { override val path = ":feature:profile" }
+    }
+}
+
+fun DependencyHandler.toProject(module: Module): ProjectDependency =
+    project(mapOf("path" to module.path)) as ProjectDependency
+
+context(DependencyHandler)
+fun Module.toProject(): ProjectDependency = toProject(this)
+
+enum class Flavor(val flavorName: String, val dimension: String, val baseUrl: String) {
+    DEV("dev", "environment", "https://dev-api.example.com/"),
+    PROD("prod", "environment", "https://api.example.com/"),
+}
+```
+
+```kotlin
+// feature/home/build.gradle.kts
+dependencies {
+    implementation(Module.Core.Domain.toProject())
+    implementation(Module.Core.Ui.toProject())
+}
+```
+
+## Convention Plugin Composition
+
+Higher-level plugins apply lower ones. A single `feature-impl` plugin applies
+library + hilt + compose + test and wires the standard dependency set, so a
+feature module's `plugins {}` block is one line.
+
+```kotlin
+// build-logic/convention/src/main/kotlin/FeatureImplConventionPlugin.kt
+class FeatureImplConventionPlugin : Plugin<Project> {
+    override fun apply(target: Project) = with(target) {
+        with(pluginManager) {
+            apply("app.android.library")
+            apply("app.android.hilt")
+            apply("app.android.compose")
+            apply("app.android.test")
+        }
+        dependencies {
+            add("implementation", Module.Core.Ui.toProject(this))
+            add("implementation", Module.Core.Domain.toProject(this))
+        }
+    }
+}
+```
+
+Shared toolchain and compiler flags live in one extension both the library and
+app plugins call:
+
+```kotlin
+// build-logic/convention/src/main/kotlin/KotlinAndroid.kt
+internal fun Project.configureKotlinAndroid(
+    extension: CommonExtension<*, *, *, *, *, *>,
+) {
+    extension.apply {
+        compileSdk = 35
+        defaultConfig { minSdk = 26 }
+        compileOptions {
+            sourceCompatibility = JavaVersion.VERSION_17
+            targetCompatibility = JavaVersion.VERSION_17
+        }
+    }
+    extensions.configure<KotlinAndroidProjectExtension> {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_17)
+            freeCompilerArgs.addAll("-Xexplicit-api=strict")
+        }
+    }
+}
+```
+
+Alias the convention plugins in the version catalog so modules apply
+`libs.plugins.*` instead of a raw id string:
+
+```toml
+[plugins]
+app-android-feature = { id = "app.android.feature", version = "unspecified" }
+app-android-library = { id = "app.android.library", version = "unspecified" }
+app-android-compose = { id = "app.android.compose", version = "unspecified" }
+```
+
+```kotlin
+// feature/home/build.gradle.kts
+plugins {
+    alias(libs.plugins.app.android.feature)
+}
+```
+
+## Fast-Feedback Tasks
+
+Install git hooks through a Gradle task wired as a `preBuild` dependency, so a
+fresh clone gets the hooks on its first build. Resolve the git directory
+correctly when `.git` is a worktree pointer file rather than a directory.
+
+```kotlin
+// build-logic/convention or root build.gradle.kts
+fun resolveGitDir(root: File): File {
+    val dotGit = root.resolve(".git")
+    if (dotGit.isDirectory) return dotGit
+    val pointer = dotGit.readText().substringAfter("gitdir:").trim()
+    return File(pointer).let { if (it.isAbsolute) it else root.resolve(pointer).canonicalFile }
+}
+
+val installGitHooks by tasks.registering(Copy::class) {
+    from(rootDir.resolve("scripts/git-hooks"))
+    into(resolveGitDir(rootDir).resolve("hooks"))
+    filePermissions { unix("rwxr-xr-x") }
+}
+
+subprojects {
+    tasks.matching { it.name == "preBuild" }.configureEach {
+        dependsOn(rootProject.tasks.named("installGitHooks"))
+    }
+}
+```
+
+The build cache (`org.gradle.caching=true`) belongs in the same perf-flag set as
+parallel execution and the configuration cache; see
+[Build Performance](#build-performance).