@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/java/testing.md

@@ -0,0 +1,238 @@
+# Regla: Testing Java
+
+Los tests no son opcionales. Un método sin test es un método que no se puede
+modificar con confianza. Esta regla aplica a todo código Java nuevo o modificado.
+
+---
+
+## JUnit 5 como framework principal
+
+JUnit 5 (Jupiter) es el único framework de testing aceptado. JUnit 4 está prohibido
+en código nuevo. No mezclar anotaciones de ambas versiones en el mismo proyecto.
+
+```java
+// MAL — JUnit 4 en código nuevo
+import org.junit.Test;
+import org.junit.Before;
+
+// BIEN — JUnit 5
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+```
+
+---
+
+## @DisplayName descriptivos en español
+
+Los nombres de los métodos de test son para máquinas. `@DisplayName` es para humanos.
+Todo test DEBE tener `@DisplayName` con el escenario completo en español.
+
+```java
+// MAL — nombre técnico sin contexto
+@Test
+void test1() { ... }
+
+@Test
+void calcularIvaTest() { ... }
+
+// BIEN — describe el escenario y el resultado esperado
+@Test
+@DisplayName("Calcula IVA de 16% para productos gravados con tasa estándar")
+void calcularIva_productoGravadoTasaEstandar_retornaIva16Porciento() {
+    // ...
+}
+
+@Test
+@DisplayName("Lanza excepción cuando el subtotal es negativo")
+void calcularIva_subtotalNegativo_lanzaIllegalArgumentException() {
+    // ...
+}
+```
+
+---
+
+## Patrón Arrange-Act-Assert (AAA)
+
+Todos los tests siguen AAA. Los tres bloques separados con comentario o línea en blanco.
+
+```java
+@Test
+@DisplayName("Crea factura con total correcto para múltiples líneas con IVA")
+void crearFactura_variasLineas_calculaTotalConIva() {
+    // Arrange
+    var cliente = ClienteFactory.clienteActivo();
+    var lineas = List.of(
+        LineaFactura.de(Producto.con(precio("100.00")), cantidad(2)),
+        LineaFactura.de(Producto.con(precio("50.00")), cantidad(1))
+    );
+    var servicio = new FacturaService(repositorioMock, calculadorIva);
+
+    // Act
+    var factura = servicio.crear(cliente, lineas);
+
+    // Assert
+    assertThat(factura.getSubtotal()).isEqualByComparingTo("250.00");
+    assertThat(factura.getIva()).isEqualByComparingTo("40.00");
+    assertThat(factura.getTotal()).isEqualByComparingTo("290.00");
+}
+```
+
+---
+
+## Mockito para mocks — no PowerMock
+
+PowerMock no se usa. Si el código requiere PowerMock (mockear static, final,
+constructores), el código tiene un problema de diseño que debe corregirse primero.
+
+```java
+// Configuración estándar
+@ExtendWith(MockitoExtension.class)
+class FacturaServiceTest {
+    @Mock
+    private FacturaRepository repositorio;
+
+    @Mock
+    private EventoPublicador publicador;
+
+    @InjectMocks
+    private FacturaService servicio;
+
+    @Test
+    @DisplayName("Publica evento cuando la factura se crea exitosamente")
+    void crear_facturaValida_publicaEventoCreado() {
+        // Arrange
+        var factura = FacturaFactory.borradora();
+        when(repositorio.guardar(any())).thenReturn(factura);
+
+        // Act
+        servicio.crear(factura.getCliente(), factura.getLineas());
+
+        // Assert
+        verify(publicador).publicar(argThat(evento ->
+            evento instanceof FacturaCreada fc && fc.facturaId().equals(factura.getId())
+        ));
+    }
+}
+```
+
+---
+
+## AssertJ para assertions fluidas
+
+AssertJ provee mensajes de error descriptivos y una API fluida.
+Usar siempre sobre `assertEquals`, `assertTrue` y similares de JUnit.
+
+```java
+// MAL — assertions básicas con mensajes de error pobres
+assertEquals("ACTIVA", factura.getEstatus());
+assertTrue(factura.getLineas().size() > 0);
+assertNotNull(factura.getId());
+
+// BIEN — AssertJ: legible y con mensajes de error útiles al fallar
+assertThat(factura.getEstatus()).isEqualTo(EstatusFactura.ACTIVA);
+assertThat(factura.getLineas()).isNotEmpty().hasSize(3);
+assertThat(factura.getId()).isNotNull();
+assertThat(factura.getTotal()).isGreaterThan(BigDecimal.ZERO);
+
+// Para excepciones
+assertThatThrownBy(() -> servicio.crear(clienteInactivo, lineas))
+    .isInstanceOf(ClienteInactivoException.class)
+    .hasMessageContaining("inactivo");
+```
+
+---
+
+## TestContainers para tests de integración con BD
+
+Las pruebas de integración usan TestContainers. No hay bases de datos H2 en
+tests — H2 tiene comportamiento diferente a PostgreSQL/MySQL en producción.
+
+```java
+@SpringBootTest
+@Testcontainers
+class FacturaRepositoryIntegrationTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16")
+        .withDatabaseName("test_db")
+        .withUsername("test")
+        .withPassword("test");
+
+    @DynamicPropertySource
+    static void configurarPropiedades(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Test
+    @DisplayName("Persiste y recupera factura con todas sus líneas")
+    void guardar_facturaConLineas_persisteCorrectamente() { ... }
+}
+```
+
+---
+
+## Tests parametrizados con @ParameterizedTest
+
+Para múltiples casos del mismo escenario, usar `@ParameterizedTest` en lugar
+de duplicar métodos de test.
+
+```java
+@ParameterizedTest(name = "Tasa {0}% sobre ${1} resulta en ${2} de IVA")
+@CsvSource({
+    "0.16, 100.00, 16.00",
+    "0.08, 100.00, 8.00",
+    "0.00, 100.00, 0.00",
+    "0.16, 0.00,   0.00"
+})
+@DisplayName("Calcula IVA correctamente para diferentes tasas y subtotales")
+void calcularIva_variasConfiguraciones_resultadoCorrecto(
+        double tasa, String subtotal, String ivaEsperado) {
+    var resultado = calculador.calcular(new BigDecimal(subtotal), tasa);
+    assertThat(resultado).isEqualByComparingTo(ivaEsperado);
+}
+```
+
+---
+
+## Cobertura mínima 80% con JaCoCo
+
+JaCoCo en CI con umbral de fallo. Sin excepciones para módulos de lógica de negocio.
+
+```xml
+<!-- pom.xml -->
+<plugin>
+  <groupId>org.jacoco</groupId>
+  <artifactId>jacoco-maven-plugin</artifactId>
+  <configuration>
+    <rules>
+      <rule>
+        <element>BUNDLE</element>
+        <limits>
+          <limit>
+            <counter>LINE</counter>
+            <value>COVEREDRATIO</value>
+            <minimum>0.80</minimum>
+          </limit>
+        </limits>
+      </rule>
+    </rules>
+  </configuration>
+</plugin>
+```
+
+---
+
+## Checklist de testing Java antes de abrir PR
+
+- [ ] Todo método público nuevo tiene al menos un test
+- [ ] Tests usan @DisplayName descriptivo en español
+- [ ] Patrón AAA aplicado con separación visual clara
+- [ ] Mocks con Mockito — sin PowerMock
+- [ ] Assertions con AssertJ — sin assertEquals de JUnit
+- [ ] Tests de integración con TestContainers (no H2)
+- [ ] Casos parametrizados usan @ParameterizedTest
+- [ ] Cobertura del módulo >= 80% en reporte JaCoCo
+- [ ] Sin Thread.sleep() en tests

package/reglas/lenguajes/kotlin/estilo-codigo.md

@@ -0,0 +1,208 @@
+# Regla: Estilo de Código Kotlin
+
+Esta regla es OBLIGATORIA para todo código Kotlin nuevo o modificado.
+Kotlin ofrece construcciones que eliminan verbosidad y reducen bugs por diseño.
+Usarlas no es opcional: `val` sobre `var`, null safety real, y coroutines sobre callbacks.
+
+---
+
+## Linters obligatorios: ktlint y Detekt
+
+- **ktlint** verifica formato y convenciones del lenguaje. Corre en CI como verificación bloqueante.
+- **Detekt** analiza complejidad, code smells y anti-patrones. Falla con severidad `error`.
+- Configurar el IDE para aplicar ktlint al guardar. No formatear manualmente.
+
+```kotlin
+// build.gradle.kts
+plugins {
+    id("org.jlleitschuh.gradle.ktlint") version "12.1.0"
+    id("io.gitlab.arturbosch.detekt") version "1.23.6"
+}
+
+detekt {
+    config.setFrom("$rootDir/config/detekt.yml")
+    buildUponDefaultConfig = true
+}
+```
+
+---
+
+## val sobre var: inmutabilidad por defecto
+
+Declarar `val` siempre que el valor no cambie después de la asignación.
+`var` solo cuando la mutabilidad es estrictamente necesaria y documentada.
+
+```kotlin
+// MAL — var donde el valor nunca se reasigna
+var nombre = "Juan"
+var total = calcularTotal(items)
+
+// BIEN — val comunica que no cambia
+val nombre = "Juan"
+val total = calcularTotal(items)
+```
+
+---
+
+## data class para DTOs, sealed class para estados
+
+```kotlin
+// BIEN — data class para transportar datos (equals, hashCode, copy gratis)
+data class UsuarioDto(
+    val id: UUID,
+    val nombre: String,
+    val email: String,
+)
+
+// BIEN — sealed class para estados cerrados con when exhaustivo
+sealed class EstadoPedido {
+    data class Procesando(val progreso: Int) : EstadoPedido()
+    data class Completado(val transaccionId: String) : EstadoPedido()
+    data class Error(val mensaje: String) : EstadoPedido()
+}
+
+// MAL — String o constantes enteras para estados
+const val ESTADO_PROCESANDO = 1
+const val ESTADO_COMPLETADO = 2
+```
+
+---
+
+## Null safety: nunca !! en producción
+
+El operador `!!` es una bomba de tiempo. Lanza `NullPointerException` en runtime.
+Usar `?.`, `?:`, `let`, o `requireNotNull` con mensaje descriptivo.
+
+```kotlin
+// MAL — !! puede lanzar NPE en producción
+val nombre = usuario!!.perfil!!.nombre
+
+// BIEN — manejo explícito del nulo
+val nombre = usuario?.perfil?.nombre ?: "Anónimo"
+
+// BIEN — fallo temprano con mensaje claro cuando el nulo es inesperado
+val usuario = repositorio.buscarPorId(id)
+    ?: throw IllegalStateException("Usuario $id no encontrado")
+```
+
+Detekt con la regla `ForbiddenCode` o `NullableToStringCall` debe detectar `!!` en `src/`.
+
+---
+
+## when exhaustivo para sealed classes
+
+El compilador verifica que todos los casos están cubiertos cuando `when` es expresión.
+
+```kotlin
+// MAL — when como sentencia pierde exhaustividad del compilador
+when (estado) {
+    is EstadoPedido.Procesando -> mostrarProgreso(estado.progreso)
+    is EstadoPedido.Completado -> mostrarExito()
+    // Error olvidado — el compilador no avisa
+}
+
+// BIEN — when como expresion fuerza exhaustividad
+val mensaje: String = when (estado) {
+    is EstadoPedido.Procesando -> "Procesando ${estado.progreso}%"
+    is EstadoPedido.Completado -> "Completado: ${estado.transaccionId}"
+    is EstadoPedido.Error -> "Error: ${estado.mensaje}"
+}
+```
+
+---
+
+## Extension functions para enriquecer tipos sin herencia
+
+```kotlin
+// MAL — función utilitaria con receptor como parámetro
+fun formatearFecha(fecha: LocalDate): String = ...
+
+// BIEN — extension function: legible como llamada a método
+fun LocalDate.formatearParaFactura(): String =
+    DateTimeFormatter.ofPattern("dd/MM/yyyy").format(this)
+
+// Uso natural
+val texto = fechaEmision.formatearParaFactura()
+```
+
+---
+
+## Scope functions con criterio
+
+| Función | Uso correcto |
+|---------|-------------|
+| `let` | Transformar un valor nullable o encadenar operaciones |
+| `run` | Ejecutar bloque en contexto del objeto, retornar resultado |
+| `with` | Operar sobre objeto sin repetir su nombre (no nullable) |
+| `apply` | Configurar objeto y retornarlo (builders) |
+| `also` | Efecto secundario (logging, validación) sin alterar el flujo |
+
+```kotlin
+// BIEN — apply para configurar
+val intent = Intent(context, MainActivity::class.java).apply {
+    putExtra("userId", usuario.id)
+    flags = Intent.FLAG_ACTIVITY_CLEAR_TOP
+}
+
+// MAL — anidamiento de scope functions (ilegible)
+usuario?.let { u ->
+    u.perfil?.run {
+        with(this) { /* confusión total sobre 'this' */ }
+    }
+}
+```
+
+Máximo dos scope functions anidadas. Si se necesitan más, extraer funciones con nombre.
+
+---
+
+## Coroutines: suspend funciones, no callbacks
+
+```kotlin
+// MAL — callback hell
+fun obtenerUsuario(id: String, callback: (Usuario?, Error?) -> Unit) {
+    api.buscar(id) { resultado, error ->
+        if (error != null) callback(null, error)
+        else callback(resultado, null)
+    }
+}
+
+// BIEN — suspend function: lineal, testeable, componible
+suspend fun obtenerUsuario(id: String): Usuario =
+    api.buscar(id)
+```
+
+---
+
+## Nombres y límites de tamaño
+
+- Clases e interfaces: `PascalCase`
+- Funciones, variables y propiedades: `camelCase`
+- Constantes (`val` en companion object o top-level): `SCREAMING_CASE`
+- Máximo **40 líneas** por función (sin contar líneas en blanco y comentarios)
+- Máximo **4 parámetros** por función. Si se necesitan más: data class de parámetros
+- Single expression functions cuando el cuerpo es una sola expresión legible
+
+```kotlin
+// BIEN — single expression function
+fun esAdmin(usuario: Usuario): Boolean = usuario.rol == Rol.ADMIN
+
+// MAL — cuerpo innecesariamente expandido
+fun esAdmin(usuario: Usuario): Boolean {
+    return usuario.rol == Rol.ADMIN
+}
+```
+
+---
+
+## Checklist de estilo Kotlin antes de abrir PR
+
+- [ ] ktlint aplicado sin errores
+- [ ] Detekt pasa con configuración del proyecto
+- [ ] Sin `!!` en código de `src/` (solo en tests con justificación)
+- [ ] `val` usado por defecto; `var` solo donde hay mutacion real
+- [ ] `data class` para DTOs, `sealed class` para estados cerrados
+- [ ] `when` sobre sealed classes es expresion (no sentencia)
+- [ ] Funciones <= 40 líneas
+- [ ] Sin callbacks: usar `suspend` functions y coroutines
+- [ ] Sin scope functions anidadas más de dos niveles

package/reglas/lenguajes/kotlin/hooks.md

@@ -0,0 +1,245 @@
+# Regla: Hooks de Calidad para Kotlin
+
+Esta regla define las verificaciones automáticas obligatorias que corren en cada
+commit y merge para código Kotlin. Los hooks detectan errores en segundos —
+mucho antes de que lleguen a code review o a producción.
+
+---
+
+## ktlint --format antes de commit (pre-commit hook)
+
+ktlint verifica y corrige formato automáticamente. El hook debe correr en modo
+`--format` para aplicar correcciones, y fallar si quedan errores no autocorregibles.
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit o via lefthook/husky
+
+echo "Ejecutando ktlint..."
+./gradlew ktlintFormat
+
+# Verificar si ktlint introdujo cambios (reformateo)
+if ! git diff --quiet; then
+    echo "ktlint reformateó archivos. Revisa los cambios y vuelve a hacer commit."
+    exit 1
+fi
+
+./gradlew ktlintCheck
+if [ $? -ne 0 ]; then
+    echo "ktlint encontró errores de formato no corregibles automáticamente."
+    exit 1
+fi
+```
+
+Configuración recomendada vía **Lefthook** (más rápido que husky para JVM):
+
+```yaml
+# lefthook.yml
+pre-commit:
+  parallel: false
+  commands:
+    ktlint:
+      glob: "*.{kt,kts}"
+      run: ./gradlew ktlintFormat && ./gradlew ktlintCheck
+```
+
+---
+
+## Detekt con configuración del proyecto
+
+Detekt analiza complejidad ciclomática, código duplicado, funciones largas y
+anti-patrones. La configuración base del proyecto define la severidad de cada regla.
+
+```yaml
+# config/detekt.yml — reglas críticas en error
+complexity:
+  LongMethod:
+    active: true
+    threshold: 40
+  ComplexMethod:
+    active: true
+    threshold: 10
+
+style:
+  ForbiddenComment:
+    active: true
+    values: ['TODO:', 'FIXME:', 'HACK:']
+
+potential-bugs:
+  UnsafeCallOnNullableType:
+    active: true  # detecta !!
+```
+
+```bash
+# En el hook pre-merge (no pre-commit — Detekt es más lento)
+./gradlew detekt
+if [ $? -ne 0 ]; then
+    echo "Detekt encontró problemas. Revisa el reporte en build/reports/detekt/"
+    exit 1
+fi
+```
+
+---
+
+## Gradle build antes de merge (CI obligatorio)
+
+El build completo con tests corre en CI antes de aprobar el merge.
+Localmente, correr al menos una vez antes de abrir el PR.
+
+```bash
+# Pre-push hook — más lento pero evita PRs rotos
+./gradlew build
+if [ $? -ne 0 ]; then
+    echo "Build fallido. No se puede hacer push."
+    exit 1
+fi
+```
+
+En CI (GitHub Actions):
+```yaml
+- name: Build y test
+  run: ./gradlew build koverXmlReport
+
+- name: Verificar cobertura
+  run: ./gradlew koverVerify
+```
+
+---
+
+## Detección de println en código no-test
+
+`println()` en producción contamina los logs del sistema y puede exponer datos sensibles.
+Solo se permite en archivos bajo `src/test/`.
+
+```bash
+# Script de detección — corre en pre-commit
+KOTLIN_SRC=$(git diff --cached --name-only | grep -E "^src/main.*\.kt$")
+
+if [ -n "$KOTLIN_SRC" ]; then
+    MATCHES=$(echo "$KOTLIN_SRC" | xargs grep -l "println(" 2>/dev/null)
+    if [ -n "$MATCHES" ]; then
+        echo "ERROR: println() encontrado en código de producción:"
+        echo "$MATCHES"
+        echo "Usar Timber.d() o el logger del proyecto."
+        exit 1
+    fi
+fi
+```
+
+Alternativa vía regla Detekt personalizada o `ForbiddenMethodCall`:
+```yaml
+style:
+  ForbiddenMethodCall:
+    active: true
+    methods:
+      - reason: "Usar Timber o logger del proyecto"
+        value: "kotlin.io.println"
+```
+
+---
+
+## Detección de !! (force unwrap) en src/
+
+El operador `!!` en producción es una bomba de tiempo. Detectarlo en pre-commit
+evita que llegue al repositorio principal.
+
+```bash
+# Detección de !! en archivos Kotlin de producción
+KOTLIN_MAIN=$(git diff --cached --name-only | grep -E "^src/main.*\.kt$")
+
+if [ -n "$KOTLIN_MAIN" ]; then
+    # Excluir !! dentro de comentarios y strings
+    MATCHES=$(echo "$KOTLIN_MAIN" | xargs grep -En "[^!'\"]\!\![^=]" 2>/dev/null | grep -v "//.*!!")
+    if [ -n "$MATCHES" ]; then
+        echo "ERROR: Operador !! encontrado en src/main:"
+        echo "$MATCHES"
+        echo "Usar ?., ?: o requireNotNull() con mensaje descriptivo."
+        exit 1
+    fi
+fi
+
+```
+
+---
+
+## Android Lint con severidad error
+
+Android Lint detecta problemas específicos de Android: uso de APIs deprecadas,
+faltantes de permisos, problemas de rendimiento en Compose, etc.
+
+```kotlin
+// build.gradle.kts
+android {
+    lint {
+        abortOnError = true
+        warningsAsErrors = false  // solo errors bloquean el build
+        checkDependencies = true
+        htmlReport = true
+        xmlReport = true
+    }
+}
+```
+
+Reglas de lint que DEBEN estar en severidad `error` en el proyecto:
+- `HardcodedText` — textos sin localizar
+- `UnusedResources` — recursos no referenciados
+- `MissingPermission` — llamadas a APIs que requieren permisos no declarados
+- `NewApi` — uso de API no disponible en el minSdk del proyecto
+
+```bash
+# En pre-merge (CI)
+./gradlew lint
+if [ $? -ne 0 ]; then
+    echo "Android Lint encontró errores. Ver app/build/reports/lint-results.html"
+    exit 1
+fi
+```
+
+---
+
+## Configuración de Lefthook (recomendado)
+
+Lefthook es más rápido que husky y nativo en JVM. Configuración completa:
+
+```yaml
+# lefthook.yml en la raíz del proyecto
+pre-commit:
+  parallel: true
+  commands:
+    ktlint:
+      glob: "src/main/**/*.{kt,kts}"
+      run: ./gradlew ktlintFormat ktlintCheck
+    detectar-println:
+      glob: "src/main/**/*.kt"
+      run: |
+        if grep -rn "println(" {staged_files} 2>/dev/null; then
+          echo "ERROR: println() en producción. Usar el logger del proyecto."
+          exit 1
+        fi
+    detectar-force-unwrap:
+      glob: "src/main/**/*.kt"
+      run: |
+        if grep -En "[^!'\"]\!\![^=]" {staged_files} 2>/dev/null | grep -v "//"; then
+          echo "ERROR: Operador !! en producción."
+          exit 1
+        fi
+
+pre-push:
+  commands:
+    detekt:
+      run: ./gradlew detekt
+    lint:
+      run: ./gradlew lint
+```
+
+---
+
+## Checklist de hooks Kotlin
+
+- [ ] ktlint configurado y corriendo en pre-commit
+- [ ] Detekt configurado con `config/detekt.yml` del proyecto
+- [ ] Gradle build corre en CI antes de aprobar merge
+- [ ] Detección de `println()` activa para `src/main/`
+- [ ] Detección de `!!` activa para `src/main/`
+- [ ] Android Lint con `abortOnError = true`
+- [ ] Lefthook o husky instalado y versionado en el repositorio