@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/go/testing.md

@@ -0,0 +1,272 @@
+# Regla: Testing Go
+
+Go tiene soporte de testing integrado en la toolchain. Esta regla establece
+cómo usarlo correctamente. El runner nativo es suficiente para la mayoría
+de casos — no se necesitan frameworks externos pesados.
+
+---
+
+## go test como runner nativo
+
+```bash
+# Correr todos los tests del proyecto
+go test ./...
+
+# Con verbose para ver nombres de tests
+go test -v ./...
+
+# Tests de un paquete específico
+go test ./internal/factura/...
+
+# Detectar data races (OBLIGATORIO en CI)
+go test -race ./...
+
+# Con cobertura
+go test -cover -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out -o coverage.html
+```
+
+---
+
+## testify/assert para assertions legibles
+
+La librería `testify/assert` provee mensajes de error descriptivos cuando
+los tests fallan. Las funciones nativas de `testing.T` son verbosas y sus
+mensajes de error poco informativos.
+
+```go
+import (
+    "testing"
+    "github.com/stretchr/testify/assert"
+    "github.com/stretchr/testify/require"
+)
+
+// assert: el test continúa aunque falle
+// require: el test se detiene si falla (para precondiciones)
+
+func TestCrearFactura(t *testing.T) {
+    // MAL — testing nativo: mensaje de error pobre
+    if factura.Total != 290.00 {
+        t.Errorf("expected 290.00, got %v", factura.Total)
+    }
+
+    // BIEN — testify: mensaje claro con valores esperado y actual
+    assert.Equal(t, 290.00, factura.Total)
+    assert.NotNil(t, factura.ID)
+    assert.Equal(t, "BORRADOR", factura.Estatus)
+
+    // require para precondiciones: si falla, no tiene sentido continuar
+    require.NoError(t, err, "crear factura no debe retornar error")
+    require.NotNil(t, factura, "factura no debe ser nil")
+    assert.Equal(t, clienteID, factura.ClienteID)  // solo si llegamos aquí
+}
+```
+
+---
+
+## Table-driven tests obligatorios para múltiples casos
+
+Este es el patrón idiomático de Go para tests con múltiples entradas/salidas.
+Elimina la duplicación y hace los casos explícitos.
+
+```go
+func TestCalcularIva(t *testing.T) {
+    // Tabla de casos de prueba
+    casos := []struct {
+        nombre    string
+        subtotal  float64
+        tasa      float64
+        ivaEsper  float64
+        debeError bool
+    }{
+        {
+            nombre:   "IVA estándar 16% sobre 100",
+            subtotal: 100.00, tasa: 0.16, ivaEsper: 16.00,
+        },
+        {
+            nombre:   "IVA reducido 8% sobre 100",
+            subtotal: 100.00, tasa: 0.08, ivaEsper: 8.00,
+        },
+        {
+            nombre:   "IVA tasa cero",
+            subtotal: 100.00, tasa: 0.00, ivaEsper: 0.00,
+        },
+        {
+            nombre:     "Subtotal negativo retorna error",
+            subtotal:   -10.00, tasa: 0.16, debeError: true,
+        },
+    }
+
+    for _, c := range casos {
+        t.Run(c.nombre, func(t *testing.T) {
+            // Arrange
+            calc := NuevoCalculadorIva()
+
+            // Act
+            resultado, err := calc.Calcular(c.subtotal, c.tasa)
+
+            // Assert
+            if c.debeError {
+                require.Error(t, err)
+                return
+            }
+            require.NoError(t, err)
+            assert.InDelta(t, c.ivaEsper, resultado, 0.001)
+        })
+    }
+}
+```
+
+---
+
+## go test -race para detectar data races
+
+Las data races son bugs no deterministas y difíciles de reproducir en producción.
+Correr con `-race` en CI es obligatorio.
+
+```bash
+# En CI — falla si detecta data race
+go test -race ./...
+```
+
+```go
+// Ejemplo de data race que -race detecta
+func TestContadorConcurrente(t *testing.T) {
+    contador := &Contador{}
+    var wg sync.WaitGroup
+
+    for i := 0; i < 1000; i++ {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            contador.Incrementar()  // -race detecta si Incrementar no es thread-safe
+        }()
+    }
+
+    wg.Wait()
+    assert.Equal(t, 1000, contador.Valor())
+}
+```
+
+---
+
+## Mocks con interfaces — sin frameworks pesados
+
+Go no necesita frameworks de mocking pesados. Las interfaces permiten mocks simples.
+Para mocks generados automáticamente: `mockery` o `moq`.
+
+```go
+// Interface del repositorio
+type FacturaRepository interface {
+    Guardar(ctx context.Context, f *Factura) error
+    BuscarPorID(ctx context.Context, id uuid.UUID) (*Factura, error)
+}
+
+// Mock manual para tests simples
+type MockFacturaRepository struct {
+    GuardarFn     func(ctx context.Context, f *Factura) error
+    BuscarPorIDFn func(ctx context.Context, id uuid.UUID) (*Factura, error)
+}
+
+func (m *MockFacturaRepository) Guardar(ctx context.Context, f *Factura) error {
+    return m.GuardarFn(ctx, f)
+}
+
+func (m *MockFacturaRepository) BuscarPorID(ctx context.Context, id uuid.UUID) (*Factura, error) {
+    return m.BuscarPorIDFn(ctx, id)
+}
+
+// Uso en test
+func TestCrearFactura_GuardaYRetorna(t *testing.T) {
+    facturaGuardada := &Factura{ID: uuid.New()}
+    repo := &MockFacturaRepository{
+        GuardarFn: func(ctx context.Context, f *Factura) error {
+            return nil
+        },
+    }
+    servicio := NuevoFacturaService(repo, zap.NewNop())
+
+    resultado, err := servicio.Crear(context.Background(), CrearRequest{})
+
+    require.NoError(t, err)
+    assert.NotNil(t, resultado)
+    assert.Equal(t, facturaGuardada.ID, resultado.ID)
+}
+```
+
+---
+
+## httptest para testing de handlers HTTP
+
+```go
+func TestHandlerCrearFactura_Exitoso(t *testing.T) {
+    // Arrange
+    servicio := &MockFacturaService{...}
+    handler := NuevoFacturaHandler(servicio)
+    body := `{"clienteId": "...","lineas": [...]}`
+
+    req := httptest.NewRequest(http.MethodPost, "/v1/facturas",
+        strings.NewReader(body))
+    req.Header.Set("Content-Type", "application/json")
+    rec := httptest.NewRecorder()
+
+    // Act
+    handler.ServeHTTP(rec, req)
+
+    // Assert
+    assert.Equal(t, http.StatusCreated, rec.Code)
+    var respuesta map[string]any
+    require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &respuesta))
+    assert.NotNil(t, respuesta["id"])
+}
+```
+
+---
+
+## TestMain para setup/teardown global
+
+```go
+func TestMain(m *testing.M) {
+    // Setup — ejecutado antes de todos los tests del paquete
+    contenedor := iniciarContenedorPostgres()
+    configurarDB(contenedor.ConnectionString())
+
+    codigo := m.Run()  // ejecutar tests
+
+    // Teardown — ejecutado después de todos los tests
+    contenedor.Terminar()
+    os.Exit(codigo)
+}
+```
+
+---
+
+## Cobertura: go test -cover -coverprofile
+
+```bash
+# Generar reporte de cobertura
+go test -cover -coverprofile=coverage.out ./...
+
+# Ver cobertura por función
+go tool cover -func=coverage.out
+
+# Ver umbral — falla si cobertura < 80%
+COBERTURA=$(go tool cover -func=coverage.out | grep total | awk '{print $3}' | tr -d '%')
+if (( $(echo "$COBERTURA < 80" | bc -l) )); then
+    echo "Cobertura $COBERTURA% está por debajo del mínimo de 80%"
+    exit 1
+fi
+```
+
+---
+
+## Checklist de testing Go antes de abrir PR
+
+- [ ] `go test ./...` pasa sin errores
+- [ ] `go test -race ./...` pasa sin data races
+- [ ] Table-driven tests para funciones con múltiples casos
+- [ ] Mocks implementados como interfaces, no con frameworks invasivos
+- [ ] Cobertura del paquete >= 80%
+- [ ] Handlers HTTP testeados con httptest
+- [ ] Sin time.Sleep() en tests — usar canales o contextos con timeout
+- [ ] Tests son deterministas (mismo resultado en cada ejecución)

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

@@ -0,0 +1,217 @@
+# Regla: Estilo de Código Java (Java 17+)
+
+Esta regla es OBLIGATORIA para todo código Java nuevo o modificado.
+Java moderno (17+) ofrece construcciones que eliminan verbosidad sin sacrificar
+claridad. Usarlas no es opcional: reducen bugs y aumentan legibilidad.
+
+---
+
+## Formateador obligatorio
+
+- Usar **google-java-format** o **Spotless** con perfil AOSP (4 espacios).
+  Alternativa aceptable: Checkstyle con configuración de Google Style Guide.
+- El formateador corre en CI como verificación bloqueante. Un PR que no formatea
+  no pasa la pipeline sin importar el resto.
+- Configurar el IDE para formatear al guardar. No formatear manualmente.
+
+```xml
+<!-- pom.xml — Spotless obligatorio -->
+<plugin>
+  <groupId>com.diffplug.spotless</groupId>
+  <artifactId>spotless-maven-plugin</artifactId>
+  <version>2.43.0</version>
+  <configuration>
+    <java>
+      <googleJavaFormat>
+        <version>1.19.2</version>
+        <style>AOSP</style>
+      </googleJavaFormat>
+    </java>
+  </configuration>
+</plugin>
+```
+
+---
+
+## Records para DTOs inmutables (Java 16+)
+
+Los records eliminan el boilerplate de DTOs. Todo DTO inmutable DEBE ser record.
+
+```java
+// MAL — clase tradicional con boilerplate innecesario
+public class UsuarioDto {
+    private final String nombre;
+    private final String email;
+    public UsuarioDto(String nombre, String email) { ... }
+    public String getNombre() { return nombre; }
+    // ... equals, hashCode, toString
+}
+
+// BIEN — record: inmutable, compacto, con equals/hashCode/toString automáticos
+public record UsuarioDto(String nombre, String email) {}
+```
+
+---
+
+## Sealed classes para jerarquías cerradas (Java 17+)
+
+Cuando una jerarquía tiene un número fijo conocido de subtipos, usar `sealed`.
+Permite al compilador verificar exhaustividad en switch expressions.
+
+```java
+// BIEN
+public sealed interface ResultadoPago
+    permits PagoAprobado, PagoRechazado, PagoPendiente {}
+
+public record PagoAprobado(String transaccionId) implements ResultadoPago {}
+public record PagoRechazado(String motivo) implements ResultadoPago {}
+public record PagoPendiente(Instant expiracion) implements ResultadoPago {}
+
+// Switch exhaustivo — el compilador verifica que todos los casos están cubiertos
+String mensaje = switch (resultado) {
+    case PagoAprobado a -> "Aprobado: " + a.transaccionId();
+    case PagoRechazado r -> "Rechazado: " + r.motivo();
+    case PagoPendiente p -> "Pendiente hasta " + p.expiracion();
+};
+```
+
+---
+
+## Pattern matching para instanceof (Java 16+)
+
+```java
+// MAL — cast manual redundante
+if (objeto instanceof Factura) {
+    Factura factura = (Factura) objeto;
+    procesar(factura);
+}
+
+// BIEN — pattern matching elimina el cast
+if (objeto instanceof Factura factura) {
+    procesar(factura);
+}
+```
+
+---
+
+## Text blocks para strings multilínea (Java 15+)
+
+```java
+// MAL — concatenación ilegible
+String sql = "SELECT f.id, f.total\n" +
+             "FROM facturas f\n" +
+             "WHERE f.estatus = 'ACTIVA'\n" +
+             "ORDER BY f.fecha_emision DESC";
+
+// BIEN — text block preserva indentación y legibilidad
+String sql = """
+    SELECT f.id, f.total
+    FROM facturas f
+    WHERE f.estatus = 'ACTIVA'
+    ORDER BY f.fecha_emision DESC
+    """;
+```
+
+---
+
+## Optional: uso correcto
+
+- `Optional` es para valores de RETORNO que pueden estar ausentes. Solo ahí.
+- NUNCA como parámetro de método — usar sobrecarga o valor por defecto.
+- NUNCA como campo de clase — usar null con documentación o valor centinela.
+
+```java
+// MAL — Optional como parámetro
+public void enviarCorreo(String destinatario, Optional<String> asunto) { ... }
+
+// MAL — Optional como campo
+public class Pedido {
+    private Optional<String> notas;  // serialización rota, null es suficiente
+}
+
+// BIEN — Optional solo en retorno
+public Optional<Usuario> buscarPorEmail(String email) {
+    return repositorio.findByEmail(email);
+}
+
+// BIEN — consumir con métodos funcionales, no con isPresent()/get()
+buscarPorEmail(email)
+    .map(Usuario::getNombre)
+    .orElse("Anónimo");
+```
+
+---
+
+## var para variables locales con tipo obvio
+
+```java
+// MAL — tipo redundante cuando el constructor lo hace obvio
+HashMap<String, List<Factura>> facturasPorCliente = new HashMap<String, List<Factura>>();
+
+// BIEN — var elimina redundancia sin perder claridad
+var facturasPorCliente = new HashMap<String, List<Factura>>();
+
+// MAL — var donde el tipo no es obvio (reduce legibilidad)
+var resultado = procesarPedido(id);  // ¿Qué tipo retorna procesarPedido?
+
+// BIEN — tipo explícito cuando no es obvio del lado derecho
+ResultadoProcesamiento resultado = procesarPedido(id);
+```
+
+---
+
+## Campos final y nombres
+
+- Declarar `final` todo campo que no cambia después de la construcción.
+- Declarar `final` todo parámetro de método cuando el método es largo.
+- Clases: `PascalCase`. Métodos y variables: `camelCase`.
+- Constantes: `SCREAMING_CASE` con `static final`.
+- Sin abreviaciones salvo las universalmente conocidas (`id`, `dto`, `url`).
+
+```java
+// MAL
+private String n;                     // nombre críptico
+private int contadorTemporalLogs;     // hungarian notation innecesaria
+static final int maxReintentos = 3;   // constante en camelCase
+
+// BIEN
+private final String nombre;
+private int contadorLogs;
+static final int MAX_REINTENTOS = 3;
+```
+
+---
+
+## Límites de tamaño
+
+- Máximo **40 líneas** por método (sin contar líneas en blanco y comentarios).
+- Máximo **300 líneas** por clase. Si crece más: extraer clases colaboradoras.
+- Máximo **5 parámetros** por método. Si se necesitan más: crear un objeto de parámetros.
+
+---
+
+## Organización de imports
+
+Orden estricto, separados por línea en blanco:
+1. `java.*`
+2. `javax.*`
+3. `jakarta.*`
+4. `org.*`
+5. `com.*` (librerías externas)
+6. Paquetes del proyecto propio
+
+Sin imports con wildcard (`import java.util.*`). Un tipo por línea.
+
+---
+
+## Checklist de estilo Java antes de abrir PR
+
+- [ ] google-java-format / Spotless aplicado — el CI no fallará por formato
+- [ ] DTOs inmutables convertidos a records
+- [ ] Jerarquías cerradas usan sealed interfaces
+- [ ] instanceof con pattern matching (sin cast manual)
+- [ ] Optional solo en valores de retorno
+- [ ] Constantes en SCREAMING_CASE con static final
+- [ ] Sin imports wildcard
+- [ ] Métodos <= 40 líneas, clases <= 300 líneas
+- [ ] Campos inmutables marcados como final