theus-cli 0.2.36 → 0.2.37

package/vendor/theus-arsenal/skills/patrones-kotlin/SKILL.md

@@ -0,0 +1,717 @@
+---
+name: patrones-kotlin
+description: Patrones idiomáticos de Kotlin para aplicaciones robustas y mantenibles — null safety, inmutabilidad, sealed classes, corrutinas y Flow, funciones de extensión, builders DSL y Gradle Kotlin DSL.
+---
+
+# Patrones de desarrollo en Kotlin
+
+Patrones idiomáticos de Kotlin y buenas prácticas para construir aplicaciones robustas, eficientes y mantenibles.
+
+## Cuándo usarla
+
+- Al escribir código Kotlin nuevo
+- Al revisar código Kotlin
+- Al refactorizar código Kotlin existente
+- Al diseñar módulos o librerías en Kotlin
+- Al configurar builds con Gradle Kotlin DSL
+
+## Cómo funciona
+
+Esta skill impone convenciones idiomáticas de Kotlin en siete áreas clave: null safety mediante el sistema de tipos y los operadores de llamada segura, inmutabilidad con `val` y `copy()` en data classes, sealed classes e interfaces para jerarquías de tipos exhaustivas, concurrencia estructurada con corrutinas y `Flow`, funciones de extensión para añadir comportamiento sin herencia, builders DSL con seguridad de tipos usando `@DslMarker` y lambdas con receptor, y Gradle Kotlin DSL para la configuración del build.
+
+## Ejemplos
+
+**Null safety con el operador Elvis:**
+```kotlin
+fun getUserEmail(userId: String): String {
+    val user = userRepository.findById(userId)
+    return user?.email ?: "desconocido@example.com"
+}
+```
+
+**Sealed class para resultados exhaustivos:**
+```kotlin
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Failure(val error: AppError) : Result<Nothing>()
+    data object Loading : Result<Nothing>()
+}
+```
+
+**Concurrencia estructurada con async/await:**
+```kotlin
+suspend fun fetchUserWithPosts(userId: String): UserProfile =
+    coroutineScope {
+        val user = async { userService.getUser(userId) }
+        val posts = async { postService.getUserPosts(userId) }
+        UserProfile(user = user.await(), posts = posts.await())
+    }
+```
+
+## Principios fundamentales
+
+### 1. Null safety
+
+El sistema de tipos de Kotlin distingue tipos anulables y no anulables. Aprovéchalo al máximo.
+
+```kotlin
+// Bien: tipos no anulables por defecto
+fun getUser(id: String): User {
+    return userRepository.findById(id)
+        ?: throw UserNotFoundException("Usuario $id no encontrado")
+}
+
+// Bien: llamadas seguras y operador Elvis
+fun getUserEmail(userId: String): String {
+    val user = userRepository.findById(userId)
+    return user?.email ?: "desconocido@example.com"
+}
+
+// Mal: desempaquetado forzado de tipos anulables
+fun getUserEmail(userId: String): String {
+    val user = userRepository.findById(userId)
+    return user!!.email // Lanza NPE si es null
+}
+```
+
+### 2. Inmutabilidad por defecto
+
+Prefiere `val` sobre `var` y colecciones inmutables sobre mutables.
+
+```kotlin
+// Bien: datos inmutables
+data class User(
+    val id: String,
+    val name: String,
+    val email: String,
+)
+
+// Bien: transformar con copy()
+fun updateEmail(user: User, newEmail: String): User =
+    user.copy(email = newEmail)
+
+// Bien: colecciones inmutables
+val users: List<User> = listOf(user1, user2)
+val filtered = users.filter { it.email.isNotBlank() }
+
+// Mal: estado mutable
+var currentUser: User? = null // Evita el estado global mutable
+val mutableUsers = mutableListOf<User>() // Evítalo salvo que sea realmente necesario
+```
+
+### 3. Cuerpos de expresión y funciones de una sola expresión
+
+Usa cuerpos de expresión para funciones concisas y legibles.
+
+```kotlin
+// Bien: cuerpo de expresión
+fun isAdult(age: Int): Boolean = age >= 18
+
+fun formatFullName(first: String, last: String): String =
+    "$first $last".trim()
+
+fun User.displayName(): String =
+    name.ifBlank { email.substringBefore('@') }
+
+// Bien: when como expresión
+fun statusMessage(code: Int): String = when (code) {
+    200 -> "OK"
+    404 -> "No encontrado"
+    500 -> "Error interno del servidor"
+    else -> "Estado desconocido: $code"
+}
+
+// Mal: cuerpo de bloque innecesario
+fun isAdult(age: Int): Boolean {
+    return age >= 18
+}
+```
+
+### 4. Data classes para objetos de valor
+
+Usa data classes para tipos cuyo propósito principal es contener datos.
+
+```kotlin
+// Bien: data class con copy, equals, hashCode, toString
+data class CreateUserRequest(
+    val name: String,
+    val email: String,
+    val role: Role = Role.USER,
+)
+
+// Bien: value class para seguridad de tipos (cero coste en tiempo de ejecución)
+@JvmInline
+value class UserId(val value: String) {
+    init {
+        require(value.isNotBlank()) { "UserId no puede estar en blanco" }
+    }
+}
+
+@JvmInline
+value class Email(val value: String) {
+    init {
+        require('@' in value) { "Email inválido: $value" }
+    }
+}
+
+fun getUser(id: UserId): User = userRepository.findById(id)
+```
+
+## Sealed classes e interfaces
+
+### Modelar jerarquías restringidas
+
+```kotlin
+// Bien: sealed class para when exhaustivo
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Failure(val error: AppError) : Result<Nothing>()
+    data object Loading : Result<Nothing>()
+}
+
+fun <T> Result<T>.getOrNull(): T? = when (this) {
+    is Result.Success -> data
+    is Result.Failure -> null
+    is Result.Loading -> null
+}
+
+fun <T> Result<T>.getOrThrow(): T = when (this) {
+    is Result.Success -> data
+    is Result.Failure -> throw error.toException()
+    is Result.Loading -> throw IllegalStateException("Aún cargando")
+}
+```
+
+### Sealed interfaces para respuestas de API
+
+```kotlin
+sealed interface ApiError {
+    val message: String
+
+    data class NotFound(override val message: String) : ApiError
+    data class Unauthorized(override val message: String) : ApiError
+    data class Validation(
+        override val message: String,
+        val field: String,
+    ) : ApiError
+    data class Internal(
+        override val message: String,
+        val cause: Throwable? = null,
+    ) : ApiError
+}
+
+fun ApiError.toStatusCode(): Int = when (this) {
+    is ApiError.NotFound -> 404
+    is ApiError.Unauthorized -> 401
+    is ApiError.Validation -> 422
+    is ApiError.Internal -> 500
+}
+```
+
+## Funciones de ámbito (scope functions)
+
+### Cuándo usar cada una
+
+```kotlin
+// let: transformar un valor anulable o un resultado con ámbito
+val length: Int? = name?.let { it.trim().length }
+
+// apply: configurar un objeto (devuelve el objeto)
+val user = User().apply {
+    name = "Alice"
+    email = "alice@example.com"
+}
+
+// also: efectos secundarios (devuelve el objeto)
+val user = createUser(request).also { logger.info("Usuario creado: ${it.id}") }
+
+// run: ejecutar un bloque con receptor (devuelve el resultado)
+val result = connection.run {
+    prepareStatement(sql)
+    executeQuery()
+}
+
+// with: forma no-extensión de run
+val csv = with(StringBuilder()) {
+    appendLine("name,email")
+    users.forEach { appendLine("${it.name},${it.email}") }
+    toString()
+}
+```
+
+### Antipatrones
+
+```kotlin
+// Mal: anidar funciones de ámbito
+user?.let { u ->
+    u.address?.let { addr ->
+        addr.city?.let { city ->
+            println(city) // Difícil de leer
+        }
+    }
+}
+
+// Bien: encadenar llamadas seguras
+val city = user?.address?.city
+city?.let { println(it) }
+```
+
+## Funciones de extensión
+
+### Añadir funcionalidad sin herencia
+
+```kotlin
+// Bien: extensiones específicas del dominio
+fun String.toSlug(): String =
+    lowercase()
+        .replace(Regex("[^a-z0-9\\s-]"), "")
+        .replace(Regex("\\s+"), "-")
+        .trim('-')
+
+fun Instant.toLocalDate(zone: ZoneId = ZoneId.systemDefault()): LocalDate =
+    atZone(zone).toLocalDate()
+
+// Bien: extensiones de colecciones
+fun <T> List<T>.second(): T = this[1]
+
+fun <T> List<T>.secondOrNull(): T? = getOrNull(1)
+
+// Bien: extensiones con ámbito acotado (sin contaminar el espacio de nombres global)
+class UserService {
+    private fun User.isActive(): Boolean =
+        status == Status.ACTIVE && lastLogin.isAfter(Instant.now().minus(30, ChronoUnit.DAYS))
+
+    fun getActiveUsers(): List<User> = userRepository.findAll().filter { it.isActive() }
+}
+```
+
+## Corrutinas
+
+### Concurrencia estructurada
+
+```kotlin
+// Bien: concurrencia estructurada con coroutineScope
+suspend fun fetchUserWithPosts(userId: String): UserProfile =
+    coroutineScope {
+        val userDeferred = async { userService.getUser(userId) }
+        val postsDeferred = async { postService.getUserPosts(userId) }
+
+        UserProfile(
+            user = userDeferred.await(),
+            posts = postsDeferred.await(),
+        )
+    }
+
+// Bien: supervisorScope cuando los hijos pueden fallar de forma independiente
+suspend fun fetchDashboard(userId: String): Dashboard =
+    supervisorScope {
+        val user = async { userService.getUser(userId) }
+        val notifications = async { notificationService.getRecent(userId) }
+        val recommendations = async { recommendationService.getFor(userId) }
+
+        Dashboard(
+            user = user.await(),
+            notifications = try {
+                notifications.await()
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                emptyList()
+            },
+            recommendations = try {
+                recommendations.await()
+            } catch (e: CancellationException) {
+                throw e
+            } catch (e: Exception) {
+                emptyList()
+            },
+        )
+    }
+```
+
+### Flow para streams reactivos
+
+```kotlin
+// Bien: flow frío con manejo de errores adecuado
+fun observeUsers(): Flow<List<User>> = flow {
+    while (currentCoroutineContext().isActive) {
+        val users = userRepository.findAll()
+        emit(users)
+        delay(5.seconds)
+    }
+}.catch { e ->
+    logger.error("Error observando usuarios", e)
+    emit(emptyList())
+}
+
+// Bien: operadores de Flow
+fun searchUsers(query: Flow<String>): Flow<List<User>> =
+    query
+        .debounce(300.milliseconds)
+        .distinctUntilChanged()
+        .filter { it.length >= 2 }
+        .mapLatest { q -> userRepository.search(q) }
+        .catch { emit(emptyList()) }
+```
+
+### Cancelación y limpieza
+
+```kotlin
+// Bien: respetar la cancelación
+suspend fun processItems(items: List<Item>) {
+    items.forEach { item ->
+        ensureActive() // Comprueba la cancelación antes de trabajo costoso
+        processItem(item)
+    }
+}
+
+// Bien: limpieza con try/finally
+suspend fun acquireAndProcess() {
+    val resource = acquireResource()
+    try {
+        resource.process()
+    } finally {
+        withContext(NonCancellable) {
+            resource.release() // Libera siempre, incluso ante cancelación
+        }
+    }
+}
+```
+
+## Delegación
+
+### Delegación de propiedades
+
+```kotlin
+// Inicialización perezosa
+val expensiveData: List<User> by lazy {
+    userRepository.findAll()
+}
+
+// Propiedad observable
+var name: String by Delegates.observable("inicial") { _, old, new ->
+    logger.info("Nombre cambiado de '$old' a '$new'")
+}
+
+// Propiedades respaldadas por un mapa
+class Config(private val map: Map<String, Any?>) {
+    val host: String by map
+    val port: Int by map
+    val debug: Boolean by map
+}
+
+val config = Config(mapOf("host" to "localhost", "port" to 8080, "debug" to true))
+```
+
+### Delegación de interfaces
+
+```kotlin
+// Bien: delegar la implementación de una interfaz
+class LoggingUserRepository(
+    private val delegate: UserRepository,
+    private val logger: Logger,
+) : UserRepository by delegate {
+    // Sobrescribe solo lo que necesita logging
+    override suspend fun findById(id: String): User? {
+        logger.info("Buscando usuario por id: $id")
+        return delegate.findById(id).also {
+            logger.info("Usuario encontrado: ${it?.name ?: "null"}")
+        }
+    }
+}
+```
+
+## Builders DSL
+
+### Builders con seguridad de tipos
+
+```kotlin
+// Bien: DSL con @DslMarker
+@DslMarker
+annotation class HtmlDsl
+
+@HtmlDsl
+class HTML {
+    private val children = mutableListOf<Element>()
+
+    fun head(init: Head.() -> Unit) {
+        children += Head().apply(init)
+    }
+
+    fun body(init: Body.() -> Unit) {
+        children += Body().apply(init)
+    }
+
+    override fun toString(): String = children.joinToString("\n")
+}
+
+fun html(init: HTML.() -> Unit): HTML = HTML().apply(init)
+
+// Uso
+val page = html {
+    head { title("Mi página") }
+    body {
+        h1("Bienvenido")
+        p("¡Hola, mundo!")
+    }
+}
+```
+
+### DSL de configuración
+
+```kotlin
+data class ServerConfig(
+    val host: String = "0.0.0.0",
+    val port: Int = 8080,
+    val ssl: SslConfig? = null,
+    val database: DatabaseConfig? = null,
+)
+
+data class SslConfig(val certPath: String, val keyPath: String)
+data class DatabaseConfig(val url: String, val maxPoolSize: Int = 10)
+
+class ServerConfigBuilder {
+    var host: String = "0.0.0.0"
+    var port: Int = 8080
+    private var ssl: SslConfig? = null
+    private var database: DatabaseConfig? = null
+
+    fun ssl(certPath: String, keyPath: String) {
+        ssl = SslConfig(certPath, keyPath)
+    }
+
+    fun database(url: String, maxPoolSize: Int = 10) {
+        database = DatabaseConfig(url, maxPoolSize)
+    }
+
+    fun build(): ServerConfig = ServerConfig(host, port, ssl, database)
+}
+
+fun serverConfig(init: ServerConfigBuilder.() -> Unit): ServerConfig =
+    ServerConfigBuilder().apply(init).build()
+
+// Uso
+val config = serverConfig {
+    host = "0.0.0.0"
+    port = 443
+    ssl("/certs/cert.pem", "/certs/key.pem")
+    database("jdbc:postgresql://localhost:5432/mydb", maxPoolSize = 20)
+}
+```
+
+## Sequences para evaluación perezosa
+
+```kotlin
+// Bien: usa sequences en colecciones grandes con varias operaciones encadenadas
+val result = users.asSequence()
+    .filter { it.isActive }
+    .map { it.email }
+    .filter { it.endsWith("@empresa.com") }
+    .take(10)
+    .toList()
+
+// Bien: generar secuencias infinitas
+val fibonacci: Sequence<Long> = sequence {
+    var a = 0L
+    var b = 1L
+    while (true) {
+        yield(a)
+        val next = a + b
+        a = b
+        b = next
+    }
+}
+
+val first20 = fibonacci.take(20).toList()
+```
+
+## Gradle Kotlin DSL
+
+### Configuración de build.gradle.kts
+
+```kotlin
+// Consulta las últimas versiones: https://kotlinlang.org/docs/releases.html
+plugins {
+    kotlin("jvm") version "2.3.10"
+    kotlin("plugin.serialization") version "2.3.10"
+    id("io.ktor.plugin") version "3.4.0"
+    id("org.jetbrains.kotlinx.kover") version "0.9.7"
+    id("io.gitlab.arturbosch.detekt") version "1.23.8"
+}
+
+group = "com.example"
+version = "1.0.0"
+
+kotlin {
+    jvmToolchain(21)
+}
+
+dependencies {
+    // Ktor
+    implementation("io.ktor:ktor-server-core:3.4.0")
+    implementation("io.ktor:ktor-server-netty:3.4.0")
+    implementation("io.ktor:ktor-server-content-negotiation:3.4.0")
+    implementation("io.ktor:ktor-serialization-kotlinx-json:3.4.0")
+
+    // Exposed
+    implementation("org.jetbrains.exposed:exposed-core:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-dao:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0")
+    implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")
+
+    // Koin
+    implementation("io.insert-koin:koin-ktor:4.2.0")
+
+    // Corrutinas
+    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")
+
+    // Testing
+    testImplementation("io.kotest:kotest-runner-junit5:6.1.4")
+    testImplementation("io.kotest:kotest-assertions-core:6.1.4")
+    testImplementation("io.kotest:kotest-property:6.1.4")
+    testImplementation("io.mockk:mockk:1.14.9")
+    testImplementation("io.ktor:ktor-server-test-host:3.4.0")
+    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
+}
+
+tasks.withType<Test> {
+    useJUnitPlatform()
+}
+
+detekt {
+    config.setFrom(files("config/detekt/detekt.yml"))
+    buildUponDefaultConfig = true
+}
+```
+
+## Patrones de manejo de errores
+
+### Tipo Result para operaciones de dominio
+
+```kotlin
+// Bien: usa el Result de Kotlin o una sealed class propia
+suspend fun createUser(request: CreateUserRequest): Result<User> = runCatching {
+    require(request.name.isNotBlank()) { "El nombre no puede estar en blanco" }
+    require('@' in request.email) { "Formato de email inválido" }
+
+    val user = User(
+        id = UserId(UUID.randomUUID().toString()),
+        name = request.name,
+        email = Email(request.email),
+    )
+    userRepository.save(user)
+    user
+}
+
+// Bien: encadenar resultados
+val displayName = createUser(request)
+    .map { it.name }
+    .getOrElse { "Desconocido" }
+```
+
+### require, check, error
+
+```kotlin
+// Bien: precondiciones con mensajes claros
+fun withdraw(account: Account, amount: Money): Account {
+    require(amount.value > 0) { "El importe debe ser positivo: $amount" }
+    check(account.balance >= amount) { "Saldo insuficiente: ${account.balance} < $amount" }
+
+    return account.copy(balance = account.balance - amount)
+}
+```
+
+## Operaciones sobre colecciones
+
+### Procesamiento idiomático de colecciones
+
+```kotlin
+// Bien: operaciones encadenadas
+val activeAdminEmails: List<String> = users
+    .filter { it.role == Role.ADMIN && it.isActive }
+    .sortedBy { it.name }
+    .map { it.email }
+
+// Bien: agrupación y agregación
+val usersByRole: Map<Role, List<User>> = users.groupBy { it.role }
+
+val oldestByRole: Map<Role, User?> = users.groupBy { it.role }
+    .mapValues { (_, users) -> users.minByOrNull { it.createdAt } }
+
+// Bien: associate para crear mapas
+val usersById: Map<UserId, User> = users.associateBy { it.id }
+
+// Bien: partition para dividir
+val (active, inactive) = users.partition { it.isActive }
+```
+
+## Referencia rápida: idiomas de Kotlin
+
+| Idioma | Descripción |
+|-------|-------------|
+| `val` sobre `var` | Prefiere variables inmutables |
+| `data class` | Para objetos de valor con equals/hashCode/copy |
+| `sealed class/interface` | Para jerarquías de tipos restringidas |
+| `value class` | Para envoltorios con seguridad de tipos y coste cero |
+| `when` como expresión | Coincidencia de patrones exhaustiva |
+| Llamada segura `?.` | Acceso a miembros seguro ante null |
+| Elvis `?:` | Valor por defecto para anulables |
+| `let`/`apply`/`also`/`run`/`with` | Funciones de ámbito para código limpio |
+| Funciones de extensión | Añadir comportamiento sin herencia |
+| `copy()` | Actualizaciones inmutables en data classes |
+| `require`/`check` | Aserciones de precondiciones |
+| Corrutinas `async`/`await` | Ejecución concurrente estructurada |
+| `Flow` | Streams reactivos fríos |
+| `sequence` | Evaluación perezosa |
+| Delegación `by` | Reutilizar implementación sin herencia |
+
+## Antipatrones a evitar
+
+```kotlin
+// Mal: desempaquetado forzado de tipos anulables
+val name = user!!.name
+
+// Mal: fuga de platform types desde Java
+fun getLength(s: String) = s.length // Seguro
+fun getLength(s: String?) = s?.length ?: 0 // Maneja nulls provenientes de Java
+
+// Mal: data classes mutables
+data class MutableUser(var name: String, var email: String)
+
+// Mal: usar excepciones para control de flujo
+try {
+    val user = findUser(id)
+} catch (e: NotFoundException) {
+    // No uses excepciones para casos esperados
+}
+
+// Bien: usa retorno anulable o Result
+val user: User? = findUserOrNull(id)
+
+// Mal: ignorar el ámbito de las corrutinas
+GlobalScope.launch { /* Evita GlobalScope */ }
+
+// Bien: usa concurrencia estructurada
+coroutineScope {
+    launch { /* Correctamente acotado */ }
+}
+
+// Mal: funciones de ámbito profundamente anidadas
+user?.let { u ->
+    u.address?.let { a ->
+        a.city?.let { c -> process(c) }
+    }
+}
+
+// Bien: cadena directa segura ante null
+user?.address?.city?.let { process(it) }
+```
+
+**Recuerda**: el código Kotlin debe ser conciso pero legible. Aprovecha el sistema de tipos para la seguridad, prefiere la inmutabilidad y usa corrutinas para la concurrencia. Ante la duda, deja que el compilador te ayude.
+
+## Skills relacionadas
+
+- `testing-kotlin` — patrones de testing con Kotest, MockK y Kover
+- `corrutinas-flows-kotlin` — corrutinas y Flow en profundidad
+- `patrones-kotlin-ktor` — patrones de servidor con Ktor
+- `patrones-kotlin-exposed` — acceso a datos con Exposed