@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/php/testing.md

@@ -0,0 +1,205 @@
+# Regla: Testing — PHP / Laravel
+
+Los tests en PHP con Laravel cubren dos dimensiones: lógica de negocio aislada
+(unit tests) y comportamiento HTTP end-to-end (feature tests). Esta regla define
+cuándo usar cada tipo, cómo estructurarlos y qué herramientas son válidas.
+
+---
+
+## Frameworks de testing
+
+- **PHPUnit**: framework base, ya incluido en Laravel. Usar para proyectos existentes.
+- **Pest**: alternativa moderna con sintaxis más concisa. Usar para proyectos nuevos
+  o cuando el equipo lo adopte conscientemente.
+- No mezclar PHPUnit y Pest en el mismo proyecto sin consenso del equipo.
+- **Mockery**: para mocks y stubs. Integrado con ambos frameworks.
+
+---
+
+## Cobertura mínima: 80%
+
+- Ejecutar con reporte de cobertura:
+  ```bash
+  php artisan test --coverage --min=80
+  ```
+- CI falla si la cobertura cae por debajo del 80%.
+- La cobertura se mide sobre código de negocio: `app/Services/`, `app/Repositories/`,
+  `app/Models/`. No sobre controllers ni providers.
+- Cobertura del 100% con tests triviales no es el objetivo. 80% con tests
+  que prueban comportamiento real vale más.
+
+---
+
+## Feature tests para endpoints HTTP
+
+Los feature tests verifican el comportamiento completo del endpoint, incluyendo
+middleware, validación, respuesta y efectos en la BD:
+
+```php
+class EmitirFacturaTest extends TestCase
+{
+    use RefreshDatabase;
+
+    public function test_usuario_autorizado_puede_emitir_factura(): void
+    {
+        // Arrange
+        $empresa = Empresa::factory()->create();
+        $usuario = User::factory()->para($empresa)->conRol('admin')->create();
+        $cliente = Cliente::factory()->para($empresa)->create();
+
+        // Act
+        $respuesta = $this->actingAs($usuario)
+            ->postJson('/api/v1/facturas', [
+                'cliente_id' => $cliente->id,
+                'items' => [
+                    ['sku' => 'PROD-01', 'qty' => 2, 'precio' => 100.00],
+                ],
+            ]);
+
+        // Assert
+        $respuesta->assertCreated()
+            ->assertJsonPath('data.estatus', 'emitida')
+            ->assertJsonPath('data.cliente.id', $cliente->id);
+
+        $this->assertDatabaseHas('facturas', [
+            'empresa_id' => $empresa->id,
+            'estatus'    => 'emitida',
+        ]);
+    }
+
+    public function test_usuario_sin_rol_admin_recibe_403(): void
+    {
+        $usuario = User::factory()->conRol('visor').create();
+
+        $this->actingAs($usuario)
+            ->postJson('/api/v1/facturas', [])
+            ->assertForbidden();
+    }
+}
+```
+
+---
+
+## Unit tests para lógica de negocio
+
+Los unit tests prueban services y clases de dominio en aislamiento, mockeando
+todas las dependencias externas:
+
+```php
+class CalculadoraImpuestoTest extends TestCase
+{
+    public function test_calcula_iva_sobre_precio_base(): void
+    {
+        // Arrange
+        $calculadora = new CalculadoraImpuesto(tasaIva: 0.16);
+
+        // Act
+        $resultado = $calculadora->calcularIva(precio: 100.0);
+
+        // Assert
+        $this->assertEqualsWithDelta(16.0, $resultado, delta: 0.001);
+    }
+
+    public function test_lanza_excepcion_con_precio_negativo(): void
+    {
+        $calculadora = new CalculadoraImpuesto(tasaIva: 0.16);
+
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('El precio no puede ser negativo');
+
+        $calculadora->calcularIva(precio: -1.0);
+    }
+}
+```
+
+---
+
+## Factories para datos de prueba
+
+- NUNCA crear registros de BD con `new Model()` ni arrays hardcodeados en tests.
+- Usar Laravel Model Factories. Definir estados para variaciones comunes:
+
+```php
+class FacturaFactory extends Factory
+{
+    public function definition(): array
+    {
+        return [
+            'folio'         => 'FAC-' . $this->faker->unique()->numerify('#####'),
+            'estatus'       => EstatusFactura::Borrador,
+            'total'         => $this->faker->randomFloat(2, 100, 10000),
+            'fecha_emision' => $this->faker->dateTimeBetween('-1 year', 'now'),
+        ];
+    }
+
+    public function emitida(): static
+    {
+        return $this->state(['estatus' => EstatusFactura::Emitida]);
+    }
+
+    public function cancelada(): static
+    {
+        return $this->state(['estatus' => EstatusFactura::Cancelada]);
+    }
+}
+```
+
+---
+
+## Database testing: RefreshDatabase vs DatabaseTransactions
+
+| Trait | Cuándo usar | Costo |
+|-------|------------|-------|
+| `RefreshDatabase` | Tests que modifican el schema o necesitan estado limpio garantizado | Alto — hace migrate:fresh por clase |
+| `DatabaseTransactions` | Tests CRUD simples sin cambios de schema | Bajo — rollback al final de cada test |
+
+- Preferir `DatabaseTransactions` para tests de feature rápidos.
+- Usar `RefreshDatabase` solo cuando el test necesita un estado absolutamente limpio.
+
+---
+
+## Mocks con Mockery
+
+```php
+public function test_emitir_factura_envia_email_al_cliente(): void
+{
+    // Arrange
+    $mailer = Mockery::mock(MailerInterface::class);
+    $mailer->shouldReceive('enviarFactura')
+        ->once()
+        ->with(Mockery::type(Factura::class));
+
+    $service = new FacturaService(
+        facturas: $this->app->make(FacturaRepositoryInterface::class),
+        mailer: $mailer,
+    );
+
+    $factura = Factura::factory()->create();
+
+    // Act
+    $service->emitir($factura->id);
+
+    // Assert — verificado por Mockery::shouldReceive()->once()
+}
+```
+
+---
+
+## Patrón Arrange-Act-Assert (AAA)
+
+- Cada test tiene exactamente tres bloques separados con comentario.
+- Una sola afirmación conceptual por test. Múltiples `assert*` sobre el mismo
+  resultado están bien; verificar comportamientos distintos en el mismo test no.
+- Nombre del test: `test_[escenario]_[resultado_esperado]`.
+
+---
+
+## Checklist de testing antes de merge
+
+- [ ] `php artisan test --coverage --min=80` pasa
+- [ ] Feature test para cada endpoint nuevo
+- [ ] Unit test para cada método público de Service nuevo
+- [ ] Factories usadas para todos los registros de BD en tests
+- [ ] Sin `sleep()` ni dependencias de tiempo real (usar `Carbon::setTestNow()`)
+- [ ] Patron AAA con comentarios en cada test
+- [ ] Test de regresión para cada bug corregido

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

@@ -0,0 +1,207 @@
+# Regla: Estilo de Código — Rust
+
+Aplica a todo código Rust del proyecto. El compilador de Rust ya impone muchas
+restricciones; estas reglas cubren las decisiones de estilo y legibilidad que
+el compilador no puede forzar. El objetivo es código que sea seguro, claro y
+que cualquier miembro del equipo pueda mantener con confianza.
+
+---
+
+## Formateo con rustfmt (obligatorio)
+
+- `rustfmt` es el formateador oficial y su uso es obligatorio. No se aceptan
+  PRs con código sin formatear.
+- El archivo `rustfmt.toml` en la raíz del proyecto define la configuración.
+  Si no existe, usar los valores por defecto de rustfmt.
+- Ejecutar antes de cada commit: `cargo fmt --check` para verificar sin modificar.
+- NUNCA editar manualmente el indentado o el espaciado — dejar que rustfmt decida.
+- CI debe fallar si `cargo fmt --check` produce diferencias.
+
+---
+
+## Clippy como linter (obligatorio)
+
+- Clippy detecta errores idiomáticos que rustfmt no cubre.
+- Ejecutar con: `cargo clippy -- -D warnings`
+  El flag `-D warnings` convierte todo warning en error — CI falla si hay alguno.
+- Cuando un lint de Clippy es incorrecto para el caso específico, suprimir
+  con `#[allow(clippy::nombre_del_lint)]` en el sitio exacto, con comentario
+  explicando por qué:
+  ```rust
+  #[allow(clippy::too_many_arguments)] // Esta función es el punto de entrada del CLI y requiere todos estos parámetros
+  pub fn ejecutar(...) { ... }
+  ```
+- NUNCA `#![allow(clippy::all)]` a nivel de crate — suprime lints válidos.
+
+---
+
+## Convenciones de nombres
+
+| Elemento | Convención | Ejemplo |
+|----------|-----------|---------|
+| Funciones y métodos | `snake_case` | `calcular_total()` |
+| Variables y parámetros | `snake_case` | `precio_unitario` |
+| Constantes y statics | `SCREAMING_SNAKE_CASE` | `MAX_REINTENTOS` |
+| Tipos, traits, enums | `PascalCase` | `FacturaError`, `Pagable` |
+| Variantes de enum | `PascalCase` | `EstadoPedido::Enviado` |
+| Módulos y archivos | `snake_case` | `factura_service.rs` |
+| Lifetimes | `'a`, `'b` o nombres cortos descriptivos | `'entrada`, `'cache` |
+
+- NUNCA abreviar nombres de tipos. `UsrMngr` — mal. `UserManager` — bien.
+- Prefijo `is_` / `has_` para métodos que retornan `bool`:
+  `is_active()`, `has_items()`, `can_retry()`.
+
+---
+
+## Ownership y borrowing: reglas de cuándo usar qué
+
+| Situación | Usar | Razón |
+|-----------|------|-------|
+| Leer datos sin modificar | `&T` | Préstamo inmutable, sin costo de copia |
+| Modificar datos en el lugar | `&mut T` | Préstamo mutable |
+| Tomar posesión para almacenar | `T` (move) | El caller ya no necesita el valor |
+| Compartir entre hilos | `Arc<T>` | Reference counting atómico |
+| Mutación compartida entre hilos | `Arc<Mutex<T>>` | Exclusión mutua |
+
+**Parámetros de función**:
+- Preferir `&str` sobre `&String` — acepta tanto `&str` como `&String`.
+- Preferir `&[T]` sobre `&Vec<T>` — acepta cualquier slice.
+- Preferir `&Path` sobre `&PathBuf`.
+- Usar `impl Trait` para aceptar cualquier implementador del trait:
+
+```rust
+// MAL — restringe a String específicamente
+fn saludar(nombre: &String) -> String { ... }
+
+// BIEN — acepta &str, &String, Cow<str>, etc.
+fn saludar(nombre: &str) -> String { ... }
+```
+
+**Retornos**:
+- Retornar `String` (owned) cuando el caller necesita poseer el valor.
+- Retornar `&str` solo cuando el lifetime está atado al receiver (`&self`).
+
+---
+
+## Organización de módulos
+
+- Organizar módulos por **dominio**, no por tipo de artefacto.
+
+```
+// MAL — organizado por tipo
+src/
+  models/
+  services/
+  handlers/
+
+// BIEN — organizado por dominio
+src/
+  facturacion/
+    mod.rs
+    factura.rs
+    calculo.rs
+  usuario/
+    mod.rs
+    autenticacion.rs
+```
+
+- Cada módulo tiene su `mod.rs` que re-exporta solo lo público necesario.
+- Módulos de utilidades genéricas van en `src/comun/` o `src/infra/`.
+
+---
+
+## Visibilidad por defecto: privada
+
+- Todo es privado por defecto en Rust. `pub` solo cuando el símbolo es
+  parte de la interfaz pública intencional del módulo.
+- Escala de visibilidad (usar la más restrictiva posible):
+  1. Privado (sin modificador) — solo dentro del módulo
+  2. `pub(super)` — visible en el módulo padre
+  3. `pub(crate)` — visible en todo el crate
+  4. `pub` — visible fuera del crate (API pública)
+- Los campos de struct son privados por defecto. Exponer solo con métodos
+  o con `pub` cuando sea realmente necesario.
+
+---
+
+## No unwrap() en código de producción
+
+- `unwrap()` y `expect()` panicanean en runtime. Prohibidos en `src/` fuera de tests.
+- Usar el operador `?` para propagar errores.
+- Usar combinators de `Option` para manejar la ausencia de valor:
+
+```rust
+// MAL — panics si el valor es None
+let config = env::var("DATABASE_URL").unwrap();
+
+// BIEN — propaga el error con contexto
+let config = env::var("DATABASE_URL")
+    .map_err(|_| ConfigError::MissingEnvVar("DATABASE_URL"))?;
+```
+
+- `expect()` solo está permitido en código de inicio de la aplicación
+  (main, configuración inicial) donde un panic es aceptable, y con mensaje descriptivo:
+  `config.load().expect("No se pudo cargar configuración inicial")`.
+- En tests: `unwrap()` y `expect()` son aceptables.
+
+---
+
+## Iteradores sobre loops indexados
+
+```rust
+// MAL — loop indexado, verboso y propenso a off-by-one
+for i in 0..facturas.len() {
+    procesar(&facturas[i]);
+}
+
+// BIEN — iterador idiomático
+for factura in &facturas {
+    procesar(factura);
+}
+
+// BIEN — con transformación
+let totales: Vec<f64> = facturas.iter().map(|f| f.total()).collect();
+```
+
+- Prefer `iter()` sobre índices directos en la mayoría de los casos.
+- `iter_mut()` para modificación in-place. `into_iter()` para consumir.
+- Cadenas de iteradores (`map`, `filter`, `flat_map`, `fold`) sobre loops
+  cuando la operación es una transformación de datos.
+
+---
+
+## Lifetimes explícitos: solo cuando el compilador no infiere
+
+- No agregar lifetimes donde el compilador puede inferirlos (elision rules).
+- Lifetimes explícitos en structs que contienen referencias:
+
+```rust
+// NECESARIO — el struct contiene una referencia
+struct Analizador<'a> {
+    datos: &'a [u8],
+}
+
+// INNECESARIO — el compilador infiere correctamente
+fn primera_linea(texto: &str) -> &str { ... }
+```
+
+---
+
+## Longitud máxima de función: 50 líneas
+
+- Las funciones no deben exceder 50 líneas de código efectivo.
+- Funciones largas se dividen en funciones privadas con nombres descriptivos.
+- Los métodos de `impl` siguen la misma regla.
+
+---
+
+## Checklist de estilo antes de hacer commit
+
+- [ ] `cargo fmt --check` pasa sin diferencias
+- [ ] `cargo clippy -- -D warnings` pasa sin warnings
+- [ ] Sin `unwrap()` ni `expect()` en `src/` fuera de tests y main
+- [ ] Parámetros de función usan `&str` / `&[T]` en lugar de `&String` / `&Vec<T>`
+- [ ] Sin loops indexados donde un iterador funciona igual
+- [ ] Visibilidad mínima necesaria en todos los símbolos
+- [ ] Módulos organizados por dominio, no por tipo de artefacto
+- [ ] Funciones <= 50 líneas

package/reglas/lenguajes/rust/hooks.md

@@ -0,0 +1,240 @@
+# Regla: Hooks de Calidad — Rust
+
+Checks automáticos que se ejecutan en distintos puntos del ciclo de desarrollo
+para detectar problemas antes de que lleguen a revisión de código o a producción.
+Ningún check es opcional — todos bloquean el flujo si detectan un problema.
+
+---
+
+## cargo fmt --check antes de commit
+
+**Pre-commit hook** — bloquea el commit si el código no está formateado:
+
+```bash
+#!/usr/bin/env bash
+# .git/hooks/pre-commit o configurado via pre-commit framework
+
+set -e
+
+echo "Verificando formato con rustfmt..."
+cargo fmt --check
+
+if [ $? -ne 0 ]; then
+    echo "ERROR: El código no está formateado."
+    echo "Ejecutar: cargo fmt"
+    exit 1
+fi
+```
+
+Con el framework `pre-commit` (recomendado para equipos):
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt
+        language: system
+        entry: cargo fmt --check
+        pass_filenames: false
+```
+
+- Si el check falla: ejecutar `cargo fmt` (sin `--check`) y hacer el commit de nuevo.
+- NUNCA commitear con `--no-verify` para saltarse el formato.
+
+---
+
+## cargo clippy -- -D warnings antes de commit
+
+**Pre-commit hook** — bloquea el commit si hay warnings de Clippy:
+
+```bash
+echo "Ejecutando Clippy..."
+cargo clippy --all-targets --all-features -- -D warnings
+
+if [ $? -ne 0 ]; then
+    echo "ERROR: Clippy encontró warnings."
+    echo "Corregir los warnings antes de hacer commit."
+    exit 1
+fi
+```
+
+- `--all-targets` incluye tests, benchmarks y ejemplos — no solo el código de producción.
+- `--all-features` activa todos los feature flags para detectar problemas en cualquier configuración.
+- Si un lint específico de Clippy es un falso positivo para el caso en cuestión,
+  suprimir con `#[allow(clippy::lint_name)]` en el sitio exacto, con comentario.
+  NUNCA suprimir a nivel de crate.
+
+---
+
+## cargo test antes de merge
+
+**CI — bloquea el merge si algún test falla**:
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Ejecutar tests
+        run: cargo test --all-targets --all-features
+
+      - name: Cobertura de código
+        run: |
+          cargo install cargo-llvm-cov --locked
+          cargo llvm-cov --all-features --fail-under-lines 80
+```
+
+- `cargo test` se ejecuta en CI en cada PR — no solo antes de merge.
+- Los tests deben pasar en el runner de CI, no solo en la máquina local.
+- La cobertura se verifica como parte del mismo job de tests.
+
+---
+
+## cargo-audit en CI semanal
+
+**Job separado — ejecuta semanalmente y en PRs que modifican Cargo.lock**:
+
+```yaml
+# .github/workflows/audit.yml
+name: Security Audit
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'  # Lunes a las 6am UTC
+  push:
+    paths:
+      - 'Cargo.lock'
+      - 'Cargo.toml'
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: rustsec/audit-check@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+- El job de auditoría falla si encuentra vulnerabilidades HIGH o CRITICAL.
+- Las alertas de `cargo audit` se notifican al canal de seguridad del equipo.
+- Vulnerabilidades MEDIUM generan warning — deben resolverse en <2 semanas.
+
+---
+
+## Detección de println! en código no-test
+
+**Custom Clippy lint via CI** — detecta prints de debug que no deben llegar a producción:
+
+```bash
+# En el job de CI, después de los tests
+echo "Verificando que no hay println! en código de producción..."
+
+# Buscar println! en src/ pero no en mod tests ni en main.rs
+if grep -rn "println!" src/ --include="*.rs" | grep -v "#\[cfg(test)\]" | grep -v "fn main"; then
+    echo "ERROR: println! encontrado en código de producción."
+    echo "Usar tracing::info! o tracing::debug! en su lugar."
+    exit 1
+fi
+```
+
+Alternativamente, via Clippy con configuración en `clippy.toml`:
+
+```toml
+# clippy.toml
+# Prohibir macros de debugging en código de producción
+disallowed-macros = [
+    { path = "std::println", reason = "Usar tracing::info! en código de producción" },
+    { path = "std::eprintln", reason = "Usar tracing::error! en código de producción" },
+    { path = "std::dbg", reason = "Macro de debugging — eliminar antes de merge" },
+]
+```
+
+- `println!` y `eprintln!` están permitidos solo en:
+  - `src/main.rs` para output esperado de CLIs
+  - `#[cfg(test)] mod tests`
+  - Ejemplos en `examples/`
+- En el resto del código: usar `tracing::info!`, `tracing::debug!`, `tracing::error!`.
+
+---
+
+## Detección de unwrap() y expect() en src/
+
+**Parte del hook de pre-commit** — detecta panics potenciales en código de producción:
+
+```bash
+echo "Verificando ausencia de unwrap()/expect() en código de producción..."
+
+# Buscar en src/ excluyendo módulos de test
+if grep -rn "\.unwrap()\|\.expect(" src/ --include="*.rs" \
+   | grep -v "#\[cfg(test)\]" \
+   | grep -v "// ALLOW-UNWRAP:"; then
+    echo "ERROR: unwrap()/expect() encontrado en código de producción."
+    echo "Usar el operador ? o manejo explícito de errores."
+    echo "Si el unwrap() está justificado, agregar comentario: // ALLOW-UNWRAP: razón"
+    exit 1
+fi
+```
+
+- `unwrap()` y `expect()` están permitidos en:
+  - `#[cfg(test)] mod tests`
+  - `src/main.rs` para inicialización de la aplicación (con `expect()` descriptivo)
+  - Código marcado con `// ALLOW-UNWRAP: <razón explícita>`
+- Cuando se necesita `expect()` fuera de tests: el mensaje debe explicar por qué
+  el `None`/`Err` es imposible en ese punto.
+
+---
+
+## Configuración completa recomendada
+
+```yaml
+# .pre-commit-config.yaml — instalar con: pre-commit install
+repos:
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: Formato (rustfmt)
+        language: system
+        entry: cargo fmt --check
+        pass_filenames: false
+
+      - id: cargo-clippy
+        name: Linter (clippy)
+        language: system
+        entry: cargo clippy --all-targets -- -D warnings
+        pass_filenames: false
+
+      - id: no-println
+        name: Sin println! en producción
+        language: pygrep
+        entry: '\bprintln!\('
+        files: '^src/(?!main\.rs).*\.rs$'
+        exclude: '#\[cfg\(test\)\]'
+
+      - id: no-unwrap
+        name: Sin unwrap() en producción
+        language: pygrep
+        entry: '\.unwrap\(\)'
+        files: '^src/.*\.rs$'
+        exclude: '(#\[cfg\(test\)\]|ALLOW-UNWRAP)'
+```
+
+---
+
+## Checklist de hooks antes de integrar al proyecto
+
+- [ ] `pre-commit install` ejecutado en el repositorio del proyecto
+- [ ] `cargo fmt --check` en el hook de pre-commit
+- [ ] `cargo clippy -- -D warnings` en el hook de pre-commit
+- [ ] `cargo test` en el pipeline de CI (cada PR)
+- [ ] `cargo audit` en job semanal de CI
+- [ ] Detección de `println!` en `src/` fuera de tests y main
+- [ ] Detección de `unwrap()` en `src/` fuera de tests
+- [ ] Cobertura mínima del 80% verificada en CI