Kotlin

What this skill does

<!-- KOTLIN:START -->
# Kotlin Project Rules

## Agent Automation Commands

**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).

```bash
# Complete quality check sequence (Gradle):
./gradlew ktlintCheck     # Format check
./gradlew detekt          # Linting
./gradlew test            # All tests (100% pass)
./gradlew build           # Build verification
./gradlew koverVerify     # Coverage (95%+ required)

# Security audit:
./gradlew dependencyCheckAnalyze  # Vulnerability scan
./gradlew dependencyUpdates       # Check outdated deps
```

## Kotlin Configuration

**CRITICAL**: Use Kotlin 2.0+ with strict null safety.

- **Version**: Kotlin 2.0+
- **JVM Target**: 17+
- **Language Features**: All enabled
- **Compiler**: K2 compiler
- **Null Safety**: Strict

### build.gradle.kts Requirements

```kotlin
plugins {
    kotlin("jvm") version "2.0.0"
    id("org.jetbrains.dokka") version "1.9.20"
    id("io.gitlab.arturbosch.detekt") version "1.23.5"
    id("org.jlleitschuh.gradle.ktlint") version "12.1.0"
    `maven-publish`
    signing
}

group = "io.github.your-username"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    implementation(kotlin("stdlib"))
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")
    
    testImplementation(kotlin("test"))
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")
    testImplementation("io.mockk:mockk:1.13.9")
}

kotlin {
    jvmToolchain(17)
    
    compilerOptions {
        freeCompilerArgs.add("-Xjsr305=strict")
        freeCompilerArgs.add("-Xcontext-receivers")
        allWarningsAsErrors.set(true)
    }
}

tasks.test {
    useJUnitPlatform()
}

tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
    kotlinOptions {
        jvmTarget = "17"
        freeCompilerArgs = listOf(
            "-Xjsr305=strict",
            "-Xcontext-receivers"
        )
        allWarningsAsErrors = true
    }
}

detekt {
    config.setFrom(files("$rootDir/detekt.yml"))
    buildUponDefaultConfig = true
    allRules = false
}

ktlint {
    version.set("1.1.0")
    android.set(false)
    ignoreFailures.set(false)
}
```

## Code Quality Standards

### Mandatory Quality Checks

**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.

**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!

```bash
# Pre-Commit Checklist (MUST match .github/workflows/*.yml)

# 1. Format check (matches workflow - use Check, not Format!)
./gradlew ktlintCheck

# 2. Lint (matches workflow)
./gradlew detekt

# 3. Build (MUST pass with no warnings - matches workflow)
./gradlew build -x test

# 4. Run all tests (MUST pass 100% - matches workflow)
./gradlew test

# 5. Check coverage (MUST meet threshold)
./gradlew koverVerify

# If ANY fails: ❌ DO NOT COMMIT - Fix first!
```

**If ANY of these fail, you MUST fix the issues before committing.**

**Why This Matters:**
- CI/CD failures happen when local commands differ from workflows
- Example: Using `ktlintFormat` locally but `ktlintCheck` in CI = failure
- Example: Using `koverHtmlReport` locally but `koverVerify` in CI = coverage failures

### Code Style

Use ktlint with `.editorconfig`:

```ini
root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 4
indent_style = space
insert_final_newline = true
max_line_length = 120
tab_width = 4

[*.{kt,kts}]
ij_kotlin_allow_trailing_comma = true
ij_kotlin_allow_trailing_comma_on_call_site = true

# Imports
ij_kotlin_imports_layout = *,java.**,javax.**,kotlin.**,^

# Wrapping
ij_kotlin_line_break_after_multiline_when_entry = true
ij_kotlin_wrap_expression_body_functions = 1
ij_kotlin_wrap_first_method_in_call_chain = false

# Spacing
ij_kotlin_space_after_type_colon = true
ij_kotlin_space_before_type_colon = false
```

### Static Analysis

Use Detekt. Configuration in `detekt.yml`:

```yaml
build:
  maxIssues: 0
  weights:
    complexity: 2
    LongParameterList: 1
    style: 1
    comments: 1

complexity:
  active: true
  ComplexMethod:
    threshold: 15
  LongMethod:
    threshold: 60
  LongParameterList:
    functionThreshold: 6
  TooManyFunctions:
    thresholdInFiles: 15

naming:
  active: true
  FunctionNaming:
    active: true
  ClassNaming:
    active: true
  VariableNaming:
    active: true

style:
  active: true
  MagicNumber:
    active: true
  ReturnCount:
    max: 3

coroutines:
  active: true
  GlobalCoroutineUsage:
    active: true
  SuspendFunWithFlowReturnType:
    active: true
```

### Testing

- **Framework**: JUnit 5 (Jupiter)
- **Mocking**: MockK
- **Coroutines**: kotlinx-coroutines-test
- **Coverage**: Kover
- **Coverage Threshold**: 95%+

Example test:

```kotlin
import io.mockk.*
import kotlinx.coroutines.test.runTest
import org.junit.jupiter.api.Test
import org.junit.jupiter.api.assertThrows
import kotlin.test.assertEquals

class DataProcessorTest {
    
    @Test
    fun `process valid input returns uppercase`() {
        val processor = DataProcessor()
        val result = processor.process("hello")
        
        assertEquals("HELLO", result)
    }
    
    @Test
    fun `process empty input throws exception`() {
        val processor = DataProcessor()
        
        assertThrows<IllegalArgumentException> {
            processor.process("")
        }
    }
    
    @Test
    fun `processAsync works correctly`() = runTest {
        val processor = DataProcessor()
        val result = processor.processAsync("test")
        
        assertEquals("TEST", result)
    }
    
    @Test
    fun `test with mocking`() {
        val repository = mockk<UserRepository>()
        every { repository.findById(1) } returns User(1, "John")
        
        val service = UserService(repository)
        val user = service.getUser(1)
        
        assertEquals("John", user?.name)
        verify { repository.findById(1) }
    }
}
```

### Null Safety

- Use non-null types by default
- Use `?` for nullable types
- Use safe calls `?.` and Elvis operator `?:`
- Avoid `!!` operator (use only when absolutely necessary)

Example:

```kotlin
data class User(
    val id: Int,
    val name: String,
    val email: String?,
    val phone: String? = null
)

class UserService(private val repository: UserRepository) {
    
    fun findUser(id: Int): User? {
        return repository.findById(id)
    }
    
    fun getUserName(id: Int): String {
        val user = findUser(id) ?: throw UserNotFoundException(id)
        return user.name
    }
    
    fun getUserEmail(id: Int): String {
        val user = findUser(id) ?: return "[email protected]"
        return user.email ?: "[email protected]"
    }
    
    fun processUsers(ids: List<Int>): List<String> {
        return ids.mapNotNull { id ->
            findUser(id)?.name
        }
    }
}
```

### Coroutines

- Use structured concurrency
- Prefer `suspend` functions over callbacks
- Use `Flow` for reactive streams
- Handle cancellation properly

Example:

```kotlin
import kotlinx.coroutines.*
import kotlinx.coroutines.flow.*

class DataService(private val api: ApiClient) {
    
    suspend fun fetchData(id: Int): Result<Data> = withContext(Dispatchers.IO) {
        try {
            val data = api.getData(id)
            Result.success(data)
        } catch (e: Exception) {
            Result.failure(e)
        }
    }
    
    fun observeData(id: Int): Flow<Data> = flow {
        while (currentCoroutineContext().isActive) {
            val data = api.getData(id)
            emit(data)
            delay(1000)
        }
    }.flowOn(Dispatchers.IO)
    
    suspend fun fetchMultiple(ids: List<Int>): List<Data> = coroutineScope {
        ids.map { id ->
            async { fetchData(id).getOrNull() }
        }.awaitAll().filterNotNull()
    }
}
```

### Data Classes & Sealed Classes

- Use `data class` for value objects
- Use `sealed class`/`sealed interface` for restricted hierarchies
- Use `val