@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/rust/patrones.md

@@ -0,0 +1,250 @@
+# Regla: Patrones de Diseño — Rust
+
+Patrones idiomáticos de Rust para código de producción. El objetivo es aprovechar
+el sistema de tipos y el ownership model para escribir código correcto por
+construcción, no solo por convención.
+
+---
+
+## Error handling: thiserror y anyhow
+
+**thiserror** para librerías (errores tipados que el llamador puede inspeccionar):
+
+```rust
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum FacturaError {
+    #[error("Factura no encontrada: {id}")]
+    NoEncontrada { id: u64 },
+
+    #[error("Total inválido: {total} (debe ser > 0)")]
+    TotalInvalido { total: f64 },
+
+    #[error("Error de base de datos")]
+    BaseDatos(#[from] sqlx::Error),
+}
+```
+
+**anyhow** para aplicaciones (propagación de errores con contexto):
+
+```rust
+use anyhow::{Context, Result};
+
+async fn cargar_config() -> Result<Config> {
+    let ruta = env::var("CONFIG_PATH")
+        .context("Variable CONFIG_PATH no definida")?;
+
+    let contenido = fs::read_to_string(&ruta)
+        .with_context(|| format!("No se pudo leer el archivo: {ruta}"))?;
+
+    toml::from_str(&contenido)
+        .context("Formato de configuración inválido")
+}
+```
+
+- NUNCA mezclar: `thiserror` en librerías, `anyhow` en binarios/aplicaciones.
+- NUNCA retornar `Box<dyn Error>` — usar `anyhow::Error` o un tipo específico.
+
+---
+
+## Builder pattern para structs complejos
+
+Cuando un struct tiene más de 4 campos o campos opcionales, usar builder:
+
+```rust
+// MAL — constructor con muchos parámetros, difícil de leer
+let factura = Factura::new(123, "cliente@email.com", 1500.0, None, true, "MXN");
+
+// BIEN — builder con nombres explícitos
+let factura = Factura::builder()
+    .id(123)
+    .cliente("cliente@email.com")
+    .total(1500.0)
+    .moneda("MXN")
+    .build()?;
+```
+
+- El método `build()` retorna `Result<T, Error>` para validar invariantes.
+- Usar el crate `derive_builder` para casos simples.
+- Para builders complejos con validación, implementar manualmente.
+
+---
+
+## Newtype pattern para type safety
+
+Envolver tipos primitivos para que el compilador detecte usos incorrectos:
+
+```rust
+// MAL — dos u64 intercambiables, el compilador no detecta el error
+fn transferir(origen: u64, destino: u64, monto: f64) { ... }
+transferir(cuenta_destino, cuenta_origen, 100.0); // invertidos, sin error
+
+// BIEN — tipos distintos que el compilador distingue
+struct CuentaId(u64);
+struct Monto(f64);
+
+fn transferir(origen: CuentaId, destino: CuentaId, monto: Monto) { ... }
+// transferir(cuenta_destino, cuenta_origen, monto); // ERROR DE COMPILACIÓN
+```
+
+- Implementar `Display`, `Debug`, `From<u64>` y `Into<u64>` según necesidad.
+- Implementar `Deref` solo cuando el newtype ES el tipo interno (no solo lo contiene).
+
+---
+
+## Trait objects vs generics
+
+| Situación | Usar | Razón |
+|-----------|------|-------|
+| Tipo conocido en compilación, performance crítica | `impl Trait` / genéricos | Monomorphization, sin overhead |
+| Colección heterogénea de implementadores | `Box<dyn Trait>` | Dispatch dinámico necesario |
+| Trait object en función | `&dyn Trait` | Sin heap allocation |
+| Tamaño del binario importa | Genéricos con cuidado | Monomorphization puede inflarlo |
+
+```rust
+// Genéricos — dispatch estático, cero overhead
+fn procesar<T: Pagable>(item: &T) -> Resultado { ... }
+
+// Trait object — dispatch dinámico, cuando el tipo varía en runtime
+fn registrar_handler(handler: Box<dyn EventHandler>) { ... }
+```
+
+---
+
+## From/Into para conversiones idiomáticas
+
+Implementar `From<T>` automáticamente proporciona `Into<T>`:
+
+```rust
+impl From<FacturaDb> for Factura {
+    fn from(db: FacturaDb) -> Self {
+        Factura {
+            id: FacturaId(db.id),
+            total: Monto(db.total),
+            estatus: db.estatus.parse().unwrap_or_default(),
+        }
+    }
+}
+
+// El llamador puede usar From o Into indistintamente
+let factura = Factura::from(fila_db);
+let factura: Factura = fila_db.into();
+```
+
+- NUNCA implementar `Into<T>` directamente — implementar `From<T>` y dejar que
+  el compilador derive `Into<T>` automáticamente.
+- Implementar `TryFrom<T>` cuando la conversión puede fallar.
+
+---
+
+## Option combinators
+
+```rust
+// MAL — if-let verboso para transformaciones simples
+let nombre_upper = if let Some(n) = usuario.nombre {
+    Some(n.to_uppercase())
+} else {
+    None
+};
+
+// BIEN — combinators
+let nombre_upper = usuario.nombre.map(|n| n.to_uppercase());
+
+// MAL — unwrap con default innecesariamente verboso
+let total = factura.total.unwrap_or(0.0);
+
+// BIEN — unwrap_or_default cuando el default del tipo es correcto
+let total = factura.total.unwrap_or_default(); // 0.0 para f64
+
+// Cadena de operaciones con Option
+let descuento = usuario
+    .membresia
+    .filter(|m| m.esta_activa())
+    .map(|m| m.porcentaje_descuento())
+    .unwrap_or(0.0);
+```
+
+- `map` para transformar el valor interno.
+- `and_then` para operaciones que pueden retornar `None`.
+- `or_else` para proveer un alternativo si el valor es `None`.
+- `unwrap_or_default` cuando el default del tipo es el valor correcto.
+- `ok_or_else` para convertir `Option<T>` en `Result<T, E>`.
+
+---
+
+## Async con Tokio
+
+```rust
+use tokio::{join, select, spawn};
+
+// Ejecutar tareas independientes en paralelo
+async fn cargar_datos(id: u64) -> Result<DatoCompleto> {
+    let (usuario, facturas) = join!(
+        repo.obtener_usuario(id),
+        repo.listar_facturas(id)
+    )?;
+    Ok(DatoCompleto { usuario, facturas })
+}
+
+// Spawn para background tasks
+spawn(async move {
+    if let Err(e) = enviar_notificacion(evento).await {
+        tracing::error!("Error enviando notificación: {e}");
+    }
+});
+
+// Select para timeout o cancelación
+select! {
+    resultado = operacion_lenta() => manejar(resultado),
+    _ = tokio::time::sleep(Duration::from_secs(30)) => {
+        return Err(Error::Timeout);
+    }
+}
+```
+
+- NUNCA usar `std::thread::sleep` en código async — usar `tokio::time::sleep`.
+- NUNCA bloquear el thread de Tokio con operaciones sincrónicas largas.
+  Usar `tokio::task::spawn_blocking` para código CPU-intensivo o IO síncrono.
+- `#[tokio::main]` solo en `main()`. El resto son funciones `async fn` normales.
+
+---
+
+## RAII: Drop trait para cleanup
+
+```rust
+struct ConexionBd {
+    inner: pg::Connection,
+}
+
+impl Drop for ConexionBd {
+    fn drop(&mut self) {
+        // Se ejecuta automáticamente al salir del scope
+        if let Err(e) = self.inner.cerrar() {
+            tracing::warn!("Error cerrando conexión: {e}");
+        }
+    }
+}
+
+// El cleanup es automático — no hay finally ni try/catch necesario
+{
+    let conn = ConexionBd::conectar(&url)?;
+    conn.ejecutar(query)?;
+} // conn.drop() se llama aquí automáticamente
+```
+
+- Usar RAII para recursos que necesiten cleanup garantizado.
+- Los guardas de Mutex (`MutexGuard`) son RAII — liberan el lock al salir del scope.
+
+---
+
+## Checklist de patrones antes de hacer merge
+
+- [ ] Errores de librería usan `thiserror`, errores de aplicación usan `anyhow`
+- [ ] Sin `Box<dyn Error>` como tipo de retorno
+- [ ] Structs complejos (>4 campos opcionales) usan builder pattern
+- [ ] IDs y valores de dominio usan newtype pattern
+- [ ] Sin `unwrap()` en `src/` fuera de tests (ver regla de estilo)
+- [ ] Option manejado con combinators, no con if-let cuando es una transformación
+- [ ] Tareas async independientes usand `join!` para ejecución paralela
+- [ ] Sin bloqueo del runtime async con operaciones síncronas largas

package/reglas/lenguajes/rust/seguridad.md

@@ -0,0 +1,221 @@
+# Regla: Seguridad — Rust
+
+Rust elimina por diseño clases enteras de vulnerabilidades (buffer overflows,
+use-after-free, data races). Sin embargo, existen vectores de ataque específicos
+de Rust que requieren disciplina explícita. Esta regla cubre lo que el compilador
+no puede garantizar por sí solo.
+
+---
+
+## cargo-audit para CVEs en dependencias
+
+```bash
+# Instalar
+cargo install cargo-audit
+
+# Ejecutar auditoría
+cargo audit
+
+# Con política estricta — falla si hay cualquier vulnerabilidad
+cargo audit --deny warnings
+```
+
+- `cargo audit` debe ejecutarse en CI **semanalmente** como job independiente.
+- También ejecutar en el pipeline de PR si `Cargo.lock` cambia.
+- Si un CVE no tiene fix disponible:
+  1. Documentar en `Cargo.toml` como una excepción justificada con ticket.
+  2. Evaluar si el vector de ataque aplica al uso real de la dependencia.
+  3. Definir fecha límite para migrar o reemplazar la dependencia.
+- NUNCA ignorar un CVE HIGH o CRITICAL sin aprobación explícita del equipo.
+
+---
+
+## cargo-deny para licencias y vulnerabilidades
+
+```bash
+cargo install cargo-deny
+cargo deny check
+```
+
+`deny.toml` en la raíz del proyecto:
+
+```toml
+[advisories]
+vulnerability = "deny"
+unmaintained = "warn"
+unsound = "deny"
+
+[licenses]
+# Solo licencias compatibles con el proyecto
+allow = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC"]
+deny = ["GPL-2.0", "AGPL-3.0"]
+
+[bans]
+# Prohibir crates con historial de problemas de seguridad
+deny = [
+    { name = "openssl", reason = "Usar rustls o native-tls verificados" },
+]
+```
+
+- `cargo-deny` en CI detecta tanto vulnerabilidades como conflictos de licencia.
+- Revisar y actualizar `deny.toml` cuando se agregan dependencias nuevas.
+
+---
+
+## unsafe: prohibido sin justificación en ADR
+
+- `unsafe` desactiva las garantías del compilador. Todo bloque `unsafe` es
+  responsabilidad explícita del desarrollador — el compilador ya no verifica.
+- **Regla**: todo uso de `unsafe` en el código del proyecto (no en dependencias)
+  requiere:
+  1. Un comentario inmediatamente antes del bloque explicando POR QUÉ es seguro.
+  2. Un ADR documentando la decisión si el `unsafe` es en código de librería.
+  3. Revisión de seguridad explícita en el PR.
+
+```rust
+// MAL — unsafe sin justificación
+unsafe {
+    *ptr = valor;
+}
+
+// BIEN — unsafe con safety comment obligatorio
+// SAFETY: ptr apunta a memoria válida y alineada porque
+// fue obtenido de Box::into_raw() en la misma función y
+// no ha sido liberado ni aliasado desde entonces.
+unsafe {
+    *ptr = valor;
+}
+```
+
+- `#![forbid(unsafe_code)]` en crates que no necesitan `unsafe` — el compilador
+  rechaza cualquier bloque `unsafe` y protege contra PRs accidentales.
+- Si se necesita `unsafe` en un módulo específico, aislar en un módulo dedicado
+  con interfaz safe hacia afuera.
+
+---
+
+## Miri para detectar undefined behavior
+
+```bash
+# Instalar (requiere toolchain nightly)
+rustup +nightly component add miri
+
+# Ejecutar tests bajo Miri
+cargo +nightly miri test
+```
+
+- Miri ejecuta el código en un intérprete que detecta UB, accesos inválidos
+  a memoria y data races que ocurren en runtime.
+- Ejecutar Miri en todo código que contiene `unsafe`.
+- Miri puede ser lento — ejecutarlo como job separado en CI, no en cada PR.
+- Si Miri reporta un error: es un bug real que debe corregirse, no ignorarse.
+
+---
+
+## No transmute sin revisión de seguridad
+
+- `std::mem::transmute` reinterpreta los bits de un valor como otro tipo.
+  Es el operador más peligroso de Rust — puede violar todas las garantías del sistema de tipos.
+- **Regla**: `transmute` está prohibido sin revisión explícita de seguridad
+  documentada en el PR y en el código.
+- Alternativas que no requieren `transmute`:
+  - Conversión de números: `as` cast o `From`/`Into`
+  - Conversión de punteros: `pointer::cast()`
+  - Conversión de referencias: `pointer::cast()` con `unsafe` justificado
+  - Cambio de lifetime: rediseñar la API para que el compilador la acepte
+
+---
+
+## Secretos: no en const/static
+
+```rust
+// MAL — la API key queda en el binario compilado y en el historial de git
+const API_KEY: &str = "sk-prod-abc123xyz789";
+
+// MAL — static mutable tampoco es seguro
+static mut TOKEN: String = String::new();
+
+// BIEN — leer de variable de entorno en runtime
+fn cargar_config() -> Result<Config> {
+    Ok(Config {
+        api_key: env::var("API_KEY")
+            .context("Variable API_KEY no definida")?,
+    })
+}
+```
+
+- Las constantes en Rust se embeben en el binario. Un secreto en `const` puede
+  extraerse del ejecutable con herramientas básicas de análisis binario.
+- Usar variables de entorno para secretos, inyectadas por el sistema de deployment.
+- En desarrollo local: archivo `.env` (en `.gitignore`) con `dotenvy` crate.
+
+---
+
+## Validar inputs en boundaries del sistema
+
+```rust
+use garde::Validate;
+
+#[derive(Validate)]
+pub struct NuevaFactura {
+    #[garde(length(min = 1, max = 255))]
+    pub descripcion: String,
+
+    #[garde(range(min = 0.01, max = 1_000_000.0))]
+    pub total: f64,
+
+    #[garde(email)]
+    pub cliente_email: String,
+}
+
+pub async fn crear_factura(
+    State(repo): State<Arc<FacturaRepo>>,
+    Json(input): Json<NuevaFactura>,
+) -> Result<Json<Factura>, AppError> {
+    input.validate(&())?; // Retorna error si algún campo es inválido
+    let factura = repo.crear(input).await?;
+    Ok(Json(factura))
+}
+```
+
+- Validar toda entrada externa (HTTP, archivos, CLI) en el boundary de entrada.
+- No asumir que los datos de la base de datos son válidos si pueden haber sido
+  escritos por otros sistemas.
+- Usar el crate `garde` o `validator` para validación declarativa.
+
+---
+
+## Pin para futures auto-referenciales
+
+```rust
+use std::pin::Pin;
+use futures::Future;
+
+// Cuando un future contiene referencias a sí mismo, Pin garantiza
+// que no se moverá en memoria mientras está pendiente.
+type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
+
+// En traits async con objetos (trait objects de futures)
+trait Procesador: Send {
+    fn procesar<'a>(&'a self, item: &'a Item) -> BoxFuture<'a, Result<()>>;
+}
+```
+
+- Usar `Pin<Box<dyn Future>>` para almacenar futures en structs o como parámetros.
+- No implementar `Unpin` manualmente en futures a menos que se pueda demostrar
+  que son seguros de mover.
+- El compilador detectará la mayoría de los errores relacionados con Pin —
+  si hay que combatir al compilador para que acepte el código, revisar el diseño.
+
+---
+
+## Checklist de seguridad antes de hacer merge
+
+- [ ] `cargo audit` pasa sin vulnerabilidades HIGH o CRITICAL
+- [ ] `cargo deny check` pasa (licencias y vulnerabilidades)
+- [ ] Todo bloque `unsafe` tiene safety comment explicando por qué es seguro
+- [ ] Sin `transmute` sin revisión de seguridad documentada
+- [ ] Sin secretos en `const`, `static` o en código fuente
+- [ ] Inputs externos validados con esquemas (garde/validator)
+- [ ] `#![forbid(unsafe_code)]` en crates que no lo necesitan
+- [ ] Miri ejecutado en todo código nuevo con `unsafe`

package/reglas/lenguajes/rust/testing.md

@@ -0,0 +1,194 @@
+# Regla: Pruebas — Rust
+
+Las pruebas en Rust son ciudadanos de primera clase: viven junto al código que
+prueban y el compilador las verifica. El sistema de tipos ya elimina clases
+enteras de bugs — los tests cubren la lógica de negocio y los contratos públicos.
+
+---
+
+## cargo test como runner principal
+
+- `cargo test` ejecuta todos los tests: unitarios, de integración y doctests.
+- `cargo test nombre` para ejecutar un test específico.
+- `cargo test -- --nocapture` para ver salida en tests que pasan.
+- CI siempre ejecuta `cargo test --all-targets --all-features` antes del merge.
+- Los benchmarks no corren con `cargo test` — usar `cargo bench`.
+
+---
+
+## rstest para tests parametrizados y fixtures
+
+```rust
+use rstest::{fixture, rstest};
+
+#[fixture]
+fn factura_valida() -> Factura {
+    Factura::builder().id(FacturaId(1)).total(Monto(1500.0)).build().unwrap()
+}
+
+// Test parametrizado — evita duplicar el mismo test con distintos valores
+#[rstest]
+#[case(0.16, 240.0)]
+#[case(0.08, 120.0)]
+#[case(0.0,  0.0)]
+fn test_calcular_iva_por_tasa(factura_valida: Factura, #[case] tasa: f64, #[case] esperado: f64) {
+    assert_eq!(factura_valida.calcular_iva(tasa).0, esperado);
+}
+```
+
+- Usar `#[fixture]` para objetos complejos reutilizados entre tests.
+- Usar `#[rstest]` con `#[case]` en lugar de duplicar tests con distintos inputs.
+
+---
+
+## proptest para property-based testing
+
+```rust
+use proptest::prelude::*;
+
+proptest! {
+    #[test]
+    fn iva_nunca_supera_el_total(total in 0.01f64..1_000_000.0) {
+        let factura = FacturaFactory::con_total(total);
+        prop_assert!(factura.calcular_iva(0.16).0 <= total);
+    }
+}
+```
+
+- Usar proptest para invariantes que deben cumplirse para cualquier input válido.
+- Especialmente útil para: serialización/deserialización, algoritmos matemáticos y parsers.
+- Complementa los tests unitarios — no los reemplaza.
+
+---
+
+## mockall para mocks de traits
+
+```rust
+use mockall::mock;
+
+mock! {
+    RepoMock {}
+    impl FacturaRepo for RepoMock {
+        async fn obtener(&self, id: FacturaId) -> Result<Factura, FacturaError>;
+    }
+}
+
+#[tokio::test]
+async fn test_servicio_propaga_error_de_repo() {
+    // Arrange
+    let mut repo = MockRepoMock::new();
+    repo.expect_obtener()
+        .returning(|_| Err(FacturaError::NoEncontrada { id: 99 }));
+
+    // Act
+    let resultado = FacturaServicio::new(Arc::new(repo))
+        .obtener(FacturaId(99)).await;
+
+    // Assert
+    assert!(matches!(resultado, Err(FacturaError::NoEncontrada { .. })));
+}
+```
+
+- Mockear solo dependencias externas (BD, APIs, filesystem) — nunca código propio del dominio.
+- Verificar el número de llamadas con `.times(N)` para side effects esperados.
+
+---
+
+## cargo-llvm-cov para cobertura
+
+```bash
+cargo install cargo-llvm-cov
+cargo llvm-cov --fail-under-lines 80
+```
+
+- Cobertura mínima: **80%** de líneas en módulos de lógica de negocio.
+- CI debe fallar si la cobertura cae por debajo del umbral.
+- Excluir código de arranque y configuración con `#[cfg(not(tarpaulin_include))]`.
+
+---
+
+## Tests unitarios en el mismo archivo (#[cfg(test)] mod tests)
+
+```rust
+// src/facturacion/calculo.rs
+pub fn calcular_iva(base: f64, tasa: f64) -> f64 { base * tasa }
+
+#[cfg(test)]
+mod tests {
+    use super::*; // accede también a funciones privadas
+
+    #[test]
+    fn iva_con_tasa_estandar() {
+        // Arrange
+        let (base, tasa) = (1000.0, 0.16);
+        // Act
+        let resultado = calcular_iva(base, tasa);
+        // Assert
+        assert_eq!(resultado, 160.0);
+    }
+}
+```
+
+- `use super::*` permite probar funciones privadas del módulo.
+- `#[cfg(test)]` garantiza que el código de test no se incluye en el binario.
+
+---
+
+## Tests de integración en tests/
+
+Los tests de integración viven en `tests/` en la raíz del crate y solo acceden
+a la API pública:
+
+```
+mi-crate/
+├── src/
+└── tests/
+    └── facturacion_integration.rs
+```
+
+- Usar una BD aislada por test (transacción que se revierte, o BD en memoria).
+- Los tests de integración son más lentos — ejecutar en job CI separado si es necesario.
+
+---
+
+## Benchmarks con criterion
+
+```rust
+// benches/calculo_bench.rs
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn benchmark_calcular_totales(c: &mut Criterion) {
+    let facturas: Vec<Factura> = (0..1000).map(FacturaFactory::nueva).collect();
+    c.bench_function("calcular_totales_1000", |b| {
+        b.iter(|| calcular_totales(black_box(&facturas)))
+    });
+}
+
+criterion_group!(benchmarks, benchmark_calcular_totales);
+criterion_main!(benchmarks);
+```
+
+- Los benchmarks van en `benches/` — no en `src/` ni `tests/`.
+- `black_box` previene que el compilador optimice el código de benchmark.
+- No corren en CI normal — solo al investigar regresiones de performance.
+
+---
+
+## Patrón Arrange-Act-Assert
+
+- Los tres bloques siempre separados con comentario o línea en blanco.
+- Nombre del test: `test_[unidad]_[condicion]_[resultado_esperado]`.
+- Un solo concepto por test. Si el Arrange es extenso, extraer a fixture de rstest.
+
+---
+
+## Checklist de pruebas antes de hacer merge
+
+- [ ] `cargo test --all-targets` pasa completamente
+- [ ] Tests nuevos para toda lógica de negocio nueva
+- [ ] Test de regresión escrito antes del fix para todo bug
+- [ ] `cargo llvm-cov --fail-under-lines 80` pasa
+- [ ] Tests unitarios en `#[cfg(test)] mod tests` del mismo archivo
+- [ ] Tests de integración en `tests/`
+- [ ] Sin `time::sleep` en tests — usar mocks del reloj
+- [ ] Tests parametrizados con `rstest` en lugar de tests duplicados