/kotlin-rules

name: kotlin-rules
description: "Kotlin coding rules: style, patterns, security, testing. Triggers: .kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx."
effort: medium
user-invocable: false
allowed-tools: Read

Kotlin Rules

These rules come from `app/rules/kotlin/` in ai-toolkit. They cover the project's standards for coding style, frameworks, patterns, security, and testing in Kotlin. Apply them when writing or reviewing Kotlin code.

Kotlin Coding Style

Naming

• PascalCase: classes, interfaces, objects, type aliases, enum entries.
• camelCase: functions, properties, local variables, parameters.
• UPPER_SNAKE: compile-time constants (`const val`), top-level `val` constants.
• Backing properties: prefix with `_` (`private val _items`, `val items: List<T>`).
• Package names: lowercase, no underscores (`com.company.project.feature`).

Null Safety

• Use nullable types only when nullability is semantically meaningful.
• Prefer `?.let { }`, `?:` (Elvis), and safe calls over `!!`.
• Never use `!!` except in tests or when null is truly impossible.
• Use `requireNotNull()` and `require()` for preconditions at public API boundaries.
• Use `checkNotNull()` and `check()` for state assertions.

Data Classes

• Use `data class` for DTOs, value objects, and state containers.
• Use `copy()` for immutable updates. Avoid mutable `var` in data classes.
• Use `sealed class` / `sealed interface` for restricted hierarchies.
• Use `value class` (inline class) for type-safe wrappers with zero overhead.
• Use `object` for singletons and namespace-like utility groupings.

Functions

• Use expression body (`= expr`) for single-expression functions.
• Use named arguments for functions with >2 parameters of the same type.
• Use default parameter values instead of overloaded functions.
• Use extension functions to add behavior without inheritance.
• Use `suspend` functions for async operations, not callbacks.

Collections

• Prefer `listOf`, `mapOf`, `setOf` (immutable) over `mutableListOf`.
• Use collection operators: `map`, `filter`, `groupBy`, `associate`.
• Use `sequence {}` for lazy evaluation on large collections.
• Prefer `firstOrNull()` over `first()` for safe access.
• Use destructuring: `val (name, age) = user`.

Scope Functions

• `let`: null-safe chaining and local scoping.
• `apply`: configure object after creation.
• `also`: side effects (logging, validation) in chains.
• `run`: compute a result using receiver's context.
• `with`: multiple operations on an object without chaining.
• Avoid nesting scope functions more than 1 level deep.

Formatting

• Use ktlint or detekt for automated formatting and linting.
• Use trailing commas in multi-line parameter/argument lists.
• Max line length: 120 characters (Kotlin convention).
• Use `when` expression over if-else chains for 3+ branches.

Kotlin Frameworks

Ktor (Server)

• Use routing DSL: `routing { get("/users") { call.respond(users) } }`.
• Use `install()` for plugins: ContentNegotiation, Authentication, CORS.
• Use `call.receive<T>()` for typed request body parsing with kotlinx.serialization.
• Use `StatusPages` plugin for centralized error handling.
• Use `Routing` with nested `route("/api/v1") { }` blocks for URL grouping.

Ktor (Client)

• Use `HttpClient` with engine configuration (CIO, OkHttp, Apache).
• Use `install(ContentNegotiation) { json() }` for JSON serialization.
• Use `client.get<T>()` with reified type for typed responses.
• Use `HttpTimeout` plugin for connection and request timeouts.
• Close `HttpClient` when done or use DI lifecycle management.

Spring Boot (Kotlin)

• Use constructor injection (Kotlin classes are `final` by default).
• Apply `kotlin-spring` plugin for open classes (required for proxying).
• Use `@ConfigurationProperties` with data classes for typed config.
• Use `WebFlux` with coroutines: `coRouter { }` and `suspend` handler functions.
• Use `spring-boot-starter-validation` with `@Valid` on Kotlin data classes.

Exposed (ORM)

• Use DSL API for type-safe queries: `Users.select { Users.name eq "Ada" }`.
• Use DAO API for Active Record-style: `User.find { Users.age greaterEq 18 }`.
• Wrap database operations in `transaction { }` blocks.
• Use `SchemaUtils.create(Users)` for schema management in development.

kotlinx.serialization

• Use `@Serializable` annotation on data classes for compile-time serialization.
• Use `@SerialName("field_name")` for JSON field name mapping.
• Use `Json { ignoreUnknownKeys = true }` for lenient deserialization.
• Use polymorphic serialization with `sealed class` and `@Polymorphic`.
• Prefer `kotlinx.serialization` over Jackson for pure Kotlin projects.

Koin (DI)

• Define modules: `module { single { UserService(get()) } }`.
• Use `by inject<T>()` for lazy injection in Android/Ktor.
• Use `factory { }` for new instance per injection, `single { }` for singleton.
• Use `checkModules()` in tests to verify DI graph completeness.

Compose (Multiplatform UI)

• Use `@Composable` functions for UI components. Keep them stateless.
• Use `remember { }` and `mutableStateOf()` for local state.
• Hoist state to callers: pass state down, events up.
• Use `LaunchedEffect` for side effects tied to composition lifecycle.
• Use `ViewModel` with `StateFlow` for screen-level state management.

Kotlin Patterns

Error Handling

• Use `Result<T>` for operations that can fail without exceptions.
• Use `runCatching { }` to wrap exception-throwing code into `Result`.
• Use `sealed class` hierarchies for domain errors: `sealed class AppError`.
• Prefer `fold()`, `getOrElse()`, `getOrNull()` over `getOrThrow()`.
• Use `require()` / `check()` for preconditions; they throw `IllegalArgumentException` / `IllegalStateException`.

Coroutines

• Use `suspend` functions for sequential async operations.
• Use `coroutineScope { }` for structured concurrency with parallel work.
• Use `async { }` + `await()` for concurrent independent operations.
• Use `s