@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/go/hooks.md

@@ -0,0 +1,249 @@
+# Regla: Hooks de Desarrollo Go
+
+Go tiene excelentes herramientas de análisis estático integradas o de la comunidad.
+Automatizarlas como hooks garantiza que el código que llega al repositorio ya
+superó las verificaciones básicas, reduciendo el ruido en code review.
+
+---
+
+## go vet obligatorio antes de commit
+
+`go vet` examina el código fuente e identifica construcciones sospechosas que
+el compilador no reporta como errores pero que probablemente son bugs.
+
+```bash
+# Verificación básica — debe pasar siempre
+go vet ./...
+```
+
+Casos que `go vet` detecta:
+- `Printf`-like calls con formato incorrecto (`fmt.Sprintf("%d", "string")`)
+- Variables de loop capturadas incorrectamente en goroutines
+- Llamadas a `sync.Mutex` después de copiar el struct
+- `unreachable code` después de return/break/continue
+
+Pre-commit hook:
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+echo "Ejecutando go vet..."
+if ! go vet ./...; then
+    echo "ERROR: go vet encontró problemas. Corregir antes de hacer commit."
+    exit 1
+fi
+echo "go vet: OK"
+```
+
+---
+
+## staticcheck como linter principal
+
+`staticcheck` es el analizador estático más completo para Go. Detecta bugs,
+código ineficiente, código simplificable y APIs deprecadas.
+
+```bash
+# Instalar
+go install honnef.co/go/tools/cmd/staticcheck@latest
+
+# Ejecutar
+staticcheck ./...
+```
+
+Verificaciones clave de staticcheck:
+- SA: Análisis estático (bugs reales como nil dereference, locks mal usados)
+- S: Código simplificable
+- ST: Violaciones de estilo
+- QF: Sugerencias de quickfix (código mejorable)
+- Deprecations: uso de APIs deprecadas de la stdlib
+
+Configuración en `staticcheck.conf` en la raíz del proyecto:
+
+```ini
+# staticcheck.conf
+checks = ["all", "-ST1000", "-ST1003"]
+# ST1000: comentario de paquete (puede ser ruidoso en paquetes internos)
+# ST1003: naming de identificadores (demasiado estricto para nombres en español)
+```
+
+---
+
+## golangci-lint con configuración del proyecto
+
+`golangci-lint` agrega una capa de verificación coordinando múltiples linters.
+La configuración en `.golangci.yml` garantiza que todos en el equipo usan los mismos checks.
+
+```yaml
+# .golangci.yml — configuración del proyecto
+run:
+  timeout: 5m
+  go: "1.21"
+
+linters:
+  enable:
+    - errcheck       # errores no verificados
+    - gosimple       # simplificaciones de código
+    - govet          # vet checks
+    - ineffassign    # asignaciones sin uso
+    - staticcheck    # análisis estático completo
+    - unused         # código sin usar
+    - goimports      # imports no organizados
+    - misspell       # typos en comentarios
+    - godot          # punto final en comentarios
+    - gosec          # seguridad
+    - bodyclose      # response body no cerrado
+    - noctx          # HTTP requests sin context
+
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+  govet:
+    enable:
+      - shadow        # detección de variable shadowing
+
+issues:
+  exclude-rules:
+    # En archivos de test, errcheck es menos estricto
+    - path: "_test\\.go"
+      linters:
+        - errcheck
+```
+
+```bash
+# Ejecutar
+golangci-lint run ./...
+
+# En CI con reporte
+golangci-lint run --out-format github-actions ./...
+```
+
+---
+
+## Detección de fmt.Println en código no-test
+
+`fmt.Println` y `fmt.Printf` en código de producción son logs no estructurados
+que no se pueden filtrar, enrutar ni analizar. Usar `zap`, `slog` o el logger
+del proyecto.
+
+Hook de detección:
+
+```bash
+#!/bin/sh
+# Detectar fmt.Println/Printf en src que no son test
+ARCHIVOS=$(grep -r "fmt\.Print" --include="*.go" \
+    --exclude="*_test.go" \
+    --exclude-dir=vendor \
+    -l . 2>/dev/null)
+
+if [ -n "$ARCHIVOS" ]; then
+    echo "ERROR: fmt.Print* detectado en código de producción."
+    echo "Usar el logger del proyecto (zap/slog) en su lugar."
+    echo "Archivos afectados:"
+    echo "$ARCHIVOS"
+    exit 1
+fi
+```
+
+Con golangci-lint, agregar el linter `forbidigo`:
+
+```yaml
+# En .golangci.yml
+linters:
+  enable:
+    - forbidigo
+
+linters-settings:
+  forbidigo:
+    forbid:
+      - pattern: "^fmt\\.Print"
+        msg: "Usar el logger del proyecto en lugar de fmt.Print*"
+```
+
+---
+
+## go mod tidy antes de commit
+
+`go mod tidy` asegura que `go.mod` y `go.sum` están sincronizados con las
+importaciones reales del proyecto. Sin esto, el CI puede fallar con módulos
+que no están en el go.sum.
+
+```bash
+#!/bin/sh
+# Verificar que go.mod y go.sum están actualizados
+go mod tidy
+
+# Si go mod tidy modificó archivos, el commit no debe proceder
+if ! git diff --quiet go.mod go.sum; then
+    echo "ERROR: go.mod o go.sum están desactualizados."
+    echo "Ejecutar 'go mod tidy' y agregar los cambios al commit."
+    exit 1
+fi
+```
+
+---
+
+## errcheck: verificación de errores no manejados
+
+`errcheck` como parte de golangci-lint detecta errores ignorados sin el
+`_ =` explícito, y también con él si `check-type-assertions: true`.
+
+```go
+// MAL — estos casos son detectados por errcheck
+repositorio.Guardar(ctx, factura)      // error retornado e ignorado
+archivo, _ := os.Open(ruta)            // error ignorado con blank identifier
+
+// BIEN — error manejado explícitamente
+if err := repositorio.Guardar(ctx, factura); err != nil {
+    return fmt.Errorf("guardar factura: %w", err)
+}
+
+archivo, err := os.Open(ruta)
+if err != nil {
+    return fmt.Errorf("abrir archivo %s: %w", ruta, err)
+}
+```
+
+---
+
+## Pipeline CI completa de calidad Go
+
+Orden de ejecución (cada fase bloquea las siguientes):
+
+```bash
+# 1. Formato
+gofmt -l . && test -z "$(gofmt -l .)"
+
+# 2. Imports
+goimports -l . && test -z "$(goimports -l .)"
+
+# 3. Módulos actualizados
+go mod tidy && git diff --exit-code go.mod go.sum
+
+# 4. Compilación
+go build ./...
+
+# 5. Tests con race detection
+go test -race ./...
+
+# 6. Análisis estático
+golangci-lint run ./...
+
+# 7. Seguridad
+gosec -severity medium ./...
+
+# 8. Cobertura
+go test -coverprofile=coverage.out ./...
+go tool cover -func=coverage.out | grep total
+```
+
+---
+
+## Checklist de hooks Go antes de hacer commit
+
+- [ ] `go vet ./...` pasa sin errores
+- [ ] `gofmt -l .` retorna vacío
+- [ ] `go mod tidy` no modifica go.mod ni go.sum
+- [ ] Sin `fmt.Println`/`fmt.Printf` en código fuera de tests
+- [ ] `golangci-lint run ./...` pasa
+- [ ] `gosec ./...` sin severidad media o alta
+- [ ] `go test -race ./...` pasa sin data races

package/reglas/lenguajes/go/patrones.md

@@ -0,0 +1,249 @@
+# Regla: Patrones Go Idiomáticos
+
+Los patrones aquí listados son soluciones probadas para problemas recurrentes
+en Go de producción. El lenguaje tiene sus propios modismos — aplicar patrones
+de otros lenguajes sin adaptarlos genera código que "funciona pero no es Go".
+
+---
+
+## Functional options para configuración
+
+El patrón de opciones funcionales permite API de construcción extensible sin
+romper compatibilidad al agregar nuevas opciones.
+
+```go
+// MAL — constructor con muchos parámetros booleanos/opcionales
+func NuevoCliente(host string, port int, timeout time.Duration, tls bool, maxConn int) *Cliente { ... }
+
+// BIEN — functional options: cada opción es explícita y opcional
+type ClienteOption func(*cliente)
+
+func ConTimeout(d time.Duration) ClienteOption {
+    return func(c *cliente) { c.timeout = d }
+}
+
+func ConTLS(certPath string) ClienteOption {
+    return func(c *cliente) {
+        c.tls = true
+        c.certPath = certPath
+    }
+}
+
+func NuevoCliente(host string, opts ...ClienteOption) *Cliente {
+    c := &cliente{
+        host:    host,
+        timeout: 30 * time.Second,  // valores por defecto razonables
+        maxConn: 10,
+    }
+    for _, opt := range opts {
+        opt(c)
+    }
+    return c
+}
+
+// Consumo — solo las opciones necesarias
+cliente := NuevoCliente("api.ejemplo.com",
+    ConTimeout(5*time.Second),
+    ConTLS("/certs/client.pem"),
+)
+```
+
+---
+
+## Interface satisfaction implícita
+
+Go no usa `implements`. Un tipo satisface una interfaz automáticamente si tiene
+los métodos requeridos. Verificar en compile time con asignación a blank identifier.
+
+```go
+// Verificación en compile time — falla si *FacturaService no implementa la interfaz
+var _ FacturaRepository = (*FacturaRepositoryPostgres)(nil)
+
+// Inyección de dependencias: el servicio depende de la interfaz, no del concreto
+type FacturaService struct {
+    repo   FacturaRepository  // interface
+    logger *zap.Logger
+}
+
+func NuevoFacturaService(repo FacturaRepository, logger *zap.Logger) *FacturaService {
+    return &FacturaService{repo: repo, logger: logger}
+}
+```
+
+---
+
+## Context propagation: context.Context como primer parámetro
+
+`context.Context` es el primer parámetro de toda función que hace I/O, llama
+a servicios externos o puede cancelarse/timeout.
+
+```go
+// MAL — sin context: no hay forma de cancelar ni hacer timeout
+func (s *FacturaService) Crear(req CrearRequest) (*Factura, error) { ... }
+
+// MAL — context en el struct (compartido entre llamadas)
+type FacturaService struct {
+    ctx context.Context  // NUNCA almacenar context en struct
+}
+
+// BIEN — context como primer parámetro
+func (s *FacturaService) Crear(ctx context.Context, req CrearRequest) (*Factura, error) {
+    // Propagar el context a llamadas downstream
+    if err := s.validar(ctx, req); err != nil {
+        return nil, err
+    }
+    factura, err := s.repo.Guardar(ctx, req.toFactura())
+    if err != nil {
+        return nil, fmt.Errorf("guardar factura: %w", err)
+    }
+    return factura, nil
+}
+```
+
+---
+
+## Error wrapping con fmt.Errorf y %w
+
+Envolver errores agrega contexto sin perder el tipo original para `errors.Is`/`errors.As`.
+
+```go
+// MAL — error devuelto sin contexto
+if err != nil {
+    return err  // el llamador no sabe en qué operación falló
+}
+
+// MAL — error formateado como string (pierde el tipo)
+if err != nil {
+    return fmt.Errorf("error al guardar: " + err.Error())
+}
+
+// BIEN — wrapping con %w preserva el tipo para unwrapping
+if err != nil {
+    return fmt.Errorf("guardar factura %s: %w", factura.ID, err)
+}
+
+// Errores sentinel para tipos conocidos
+var (
+    ErrFacturaNoEncontrada  = errors.New("factura no encontrada")
+    ErrClienteInactivo      = errors.New("cliente inactivo")
+    ErrSaldoInsuficiente    = errors.New("saldo insuficiente")
+)
+
+// Verificación con errors.Is (funciona aunque el error esté envuelto)
+if errors.Is(err, ErrFacturaNoEncontrada) {
+    return c.JSON(http.StatusNotFound, errorResponse(err))
+}
+```
+
+---
+
+## Goroutines con errgroup
+
+Usar `golang.org/x/sync/errgroup` para goroutines coordinadas. Propaga errores
+y cancelación correctamente.
+
+```go
+// MAL — goroutines sin manejo de errores ni cancelación
+var wg sync.WaitGroup
+for _, id := range ids {
+    wg.Add(1)
+    go func(id uuid.UUID) {
+        defer wg.Done()
+        procesarFactura(id)  // ¿cómo se maneja el error?
+    }(id)
+}
+wg.Wait()
+
+// BIEN — errgroup maneja errores y cancela el resto si uno falla
+g, ctx := errgroup.WithContext(ctx)
+for _, id := range ids {
+    id := id  // capturar para la goroutine (Go < 1.22)
+    g.Go(func() error {
+        return procesarFactura(ctx, id)
+    })
+}
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("procesar facturas: %w", err)
+}
+```
+
+---
+
+## Table-driven tests como patrón por defecto
+
+Ver la regla de testing para el ejemplo completo. Los table-driven tests son
+el patrón idiomatic en Go para múltiples casos de prueba del mismo comportamiento.
+
+---
+
+## Middleware pattern para HTTP
+
+```go
+// Tipo de middleware
+type Middleware func(http.Handler) http.Handler
+
+// Implementación de middleware de autenticación
+func RequiereAutenticacion(validador TokenValidador) Middleware {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            token := r.Header.Get("Authorization")
+            claims, err := validador.Validar(token)
+            if err != nil {
+                http.Error(w, "No autorizado", http.StatusUnauthorized)
+                return
+            }
+            // Propagar claims via context
+            ctx := context.WithValue(r.Context(), claimsKey, claims)
+            next.ServeHTTP(w, r.WithContext(ctx))
+        })
+    }
+}
+
+// Composición de middlewares
+handler := RequiereAutenticacion(validador)(
+    RequiereRol("ADMIN")(
+        manejadorFacturas,
+    ),
+)
+```
+
+---
+
+## Preferir comunicación sobre mutex
+
+```go
+// MAL — mutex para estado compartido (propenso a deadlocks)
+type Contador struct {
+    mu    sync.Mutex
+    valor int
+}
+
+func (c *Contador) Incrementar() {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.valor++
+}
+
+// BIEN — channel para comunicación entre goroutines (cuando aplica)
+func NuevoContador() *Contador {
+    c := &Contador{ch: make(chan int, 1)}
+    c.ch <- 0  // valor inicial
+    go c.ejecutar()
+    return c
+}
+
+// Nota: mutex es apropiado para estado simple; channels para orquestación
+// La regla es: "do not communicate by sharing memory; share memory by communicating"
+```
+
+---
+
+## Checklist de patrones Go antes de abrir PR
+
+- [ ] Funciones con múltiples parámetros opcionales usan functional options
+- [ ] context.Context es el primer parámetro en toda función con I/O
+- [ ] Errores envueltos con fmt.Errorf y %w (no descartados ni concatenados)
+- [ ] Goroutines coordinadas usan errgroup, no WaitGroup manual
+- [ ] Interfaces verificadas en compile time con `var _ Interface = (*Tipo)(nil)`
+- [ ] Sin context.Context almacenado en structs
+- [ ] Errores sentinel definidos para tipos de error conocidos

package/reglas/lenguajes/go/seguridad.md

@@ -0,0 +1,225 @@
+# Regla: Seguridad Go
+
+Esta regla es OBLIGATORIA para todo código Go de producción. Go tiene defaults
+seguros en muchas áreas, pero no en todas. Las vulnerabilidades documentadas
+aquí son evitables con los patrones correctos desde el inicio.
+
+---
+
+## gosec como scanner de seguridad en CI
+
+`gosec` analiza el AST de Go buscando patrones de código inseguro. Es el primer
+mecanismo de defensa automática.
+
+```bash
+# Instalar
+go install github.com/securego/gosec/v2/cmd/gosec@latest
+
+# Ejecutar sobre todo el proyecto
+gosec ./...
+
+# En CI — falla si hay issues de severidad alta o media
+gosec -severity medium -confidence medium -fmt json -out gosec-report.json ./...
+```
+
+Reglas críticas que gosec verifica:
+- G101: Credenciales hardcodeadas
+- G201/G202: SQL injection
+- G304: Path traversal en lectura de archivos
+- G401/G501: Uso de algoritmos criptográficos débiles (MD5, SHA1)
+- G501: Import de `math/rand` para uso criptográfico
+
+---
+
+## No usar unsafe sin justificación en ADR
+
+El paquete `unsafe` rompe las garantías de tipo y memoria de Go. Es legítimo
+en casos muy específicos (interop con C, serialización de alto rendimiento),
+pero nunca sin documentación explícita.
+
+```go
+// MAL — unsafe sin justificación
+import "unsafe"
+func convertirBytes(b []byte) string {
+    return *(*string)(unsafe.Pointer(&b))
+}
+
+// BIEN — conversión segura (copia, pero es lo correcto)
+func convertirBytes(b []byte) string {
+    return string(b)
+}
+
+// Excepción documentada — si se requiere unsafe por rendimiento crítico:
+// 1. Crear ADR documentando la justificación
+// 2. Aislar en archivo con nombre: unsafe_*.go
+// 3. Comentario inline explicando por qué es seguro en este caso específico
+```
+
+---
+
+## crypto/rand para secretos — nunca math/rand
+
+`math/rand` es un PRNG determinista. Predecible. Jamás para tokens, IDs de sesión,
+claves criptográficas ni cualquier valor que deba ser impredecible.
+
+```go
+// MAL — math/rand: predecible, no apto para seguridad
+import "math/rand"
+token := fmt.Sprintf("%d", rand.Int63())  // VULNERABLE
+
+// BIEN — crypto/rand: criptográficamente seguro
+import (
+    "crypto/rand"
+    "encoding/base64"
+)
+
+func GenerarToken(n int) (string, error) {
+    bytes := make([]byte, n)
+    if _, err := rand.Read(bytes); err != nil {
+        return "", fmt.Errorf("generar token: %w", err)
+    }
+    return base64.URLEncoding.EncodeToString(bytes), nil
+}
+```
+
+---
+
+## html/template para HTML — no text/template
+
+`text/template` NO escapa HTML automáticamente. Usar `html/template` siempre
+que se genere HTML para evitar XSS.
+
+```go
+// MAL — text/template: sin escape automático de HTML
+import "text/template"
+tmpl := template.Must(template.New("").Parse("<h1>{{.Nombre}}</h1>"))
+
+// BIEN — html/template: escapa automáticamente contenido potencialmente peligroso
+import "html/template"
+tmpl := template.Must(html_template.New("").Parse("<h1>{{.Nombre}}</h1>"))
+// Si .Nombre = "<script>alert('xss')</script>", se renderiza como texto seguro
+```
+
+---
+
+## SQL con placeholders — nunca fmt.Sprintf
+
+La inyección SQL es tan simple de evitar como usar placeholders. No hay excusa.
+
+```go
+// MAL — SQL injection garantizada
+query := fmt.Sprintf("SELECT * FROM facturas WHERE cliente_id = '%s'", clienteID)
+rows, err := db.QueryContext(ctx, query)
+
+// MAL — strings.Builder no ayuda
+var sb strings.Builder
+sb.WriteString("SELECT * FROM facturas WHERE cliente_id = '")
+sb.WriteString(clienteID)
+
+// BIEN — placeholders: la BD separa código de datos
+rows, err := db.QueryContext(ctx,
+    "SELECT id, total, estatus FROM facturas WHERE cliente_id = $1 AND estatus = $2",
+    clienteID, estatus,
+)
+
+// BIEN — con sqlx o GORM (internamente usan placeholders)
+var facturas []Factura
+err := db.SelectContext(ctx, &facturas,
+    "SELECT * FROM facturas WHERE cliente_id = $1", clienteID)
+```
+
+---
+
+## TLS 1.2+ en clientes HTTP
+
+El cliente HTTP por defecto de Go es seguro en versiones recientes, pero
+es mejor ser explícito con la configuración mínima de TLS.
+
+```go
+// MAL — skip de verificación de certificado (nunca en producción)
+cliente := &http.Client{
+    Transport: &http.Transport{
+        TLSClientConfig: &tls.Config{InsecureSkipVerify: true},  // PROHIBIDO
+    },
+}
+
+// BIEN — TLS mínimo explícito
+cliente := &http.Client{
+    Timeout: 30 * time.Second,
+    Transport: &http.Transport{
+        TLSClientConfig: &tls.Config{
+            MinVersion: tls.VersionTLS12,
+        },
+        DialContext: (&net.Dialer{
+            Timeout:   10 * time.Second,
+            KeepAlive: 30 * time.Second,
+        }).DialContext,
+    },
+}
+```
+
+---
+
+## No almacenar secretos en structs serializables
+
+Los structs con tags `json:` o `yaml:` pueden serializarse accidentalmente
+en logs, respuestas de API o archivos de configuración.
+
+```go
+// MAL — el campo Password aparece en JSON si se serializa Config
+type Config struct {
+    Host     string `json:"host"`
+    Password string `json:"password"`  // PELIGROSO: aparece en logs/respuestas
+    APIKey   string `json:"api_key"`
+}
+
+// BIEN — secretos sin tag json, o con "-" para excluirlos siempre
+type Config struct {
+    Host     string `json:"host"`
+    Password string `json:"-"`   // nunca serializado
+    APIKey   string `json:"-"`
+}
+
+// BIEN — tipo opaco que no serializa su contenido
+type SecretString string
+func (s SecretString) MarshalJSON() ([]byte, error) {
+    return []byte(`"[REDACTED]"`), nil
+}
+```
+
+---
+
+## Rate limiting con golang.org/x/time/rate
+
+```go
+import "golang.org/x/time/rate"
+
+// Limiter: 10 requests por segundo, burst de 20
+limiter := rate.NewLimiter(rate.Limit(10), 20)
+
+// Middleware de rate limiting
+func RateLimitMiddleware(limiter *rate.Limiter) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            if !limiter.Allow() {
+                http.Error(w, "Demasiadas solicitudes", http.StatusTooManyRequests)
+                return
+            }
+            next.ServeHTTP(w, r)
+        })
+    }
+}
+```
+
+---
+
+## Checklist de seguridad Go antes de abrir PR
+
+- [ ] `gosec ./...` pasa sin issues de severidad media o alta
+- [ ] Sin importación de `math/rand` para valores de seguridad — usar `crypto/rand`
+- [ ] Sin `InsecureSkipVerify: true` en ningún cliente TLS
+- [ ] SQL usa placeholders (`$1`, `?`) — sin fmt.Sprintf en queries
+- [ ] HTML renderizado con `html/template`, no `text/template`
+- [ ] Sin `unsafe` sin ADR documentado y comentario de justificación
+- [ ] Secretos en structs marcados con `json:"-"` o tipo opaco
+- [ ] Rate limiting configurado en endpoints públicos