@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/nextjs/seguridad.md

@@ -0,0 +1,216 @@
+# Regla: Seguridad — Next.js
+
+Next.js con App Router tiene características de seguridad integradas, pero
+requiere configuración explícita para ser seguro en producción. Esta regla
+cubre las decisiones que el desarrollador debe tomar conscientemente.
+
+---
+
+## Validar variables de entorno al arrancar
+
+Las variables de entorno no validadas causan errores crípticos en producción.
+Validarlas al arrancar con un schema zod:
+
+```ts
+// lib/env.ts
+import { z } from 'zod'
+
+const EnvSchema = z.object({
+  DATABASE_URL:        z.string().url(),
+  NEXTAUTH_SECRET:     z.string().min(32),
+  NEXTAUTH_URL:        z.string().url(),
+  STRIPE_SECRET_KEY:   z.string().startsWith('sk_'),
+  // Variables públicas (expuestas al cliente)
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+})
+
+export const env = EnvSchema.parse(process.env)
+```
+
+- Este módulo se importa en `next.config.js` para que falle al buildear, no en runtime.
+- Si la validación falla: el build se detiene con mensaje claro del campo faltante.
+
+---
+
+## Server Actions: validar inputs server-side con zod
+
+Las Server Actions son el nuevo endpoint de mutación. Reciben datos del cliente
+y DEBEN validarlos como si fueran un endpoint de API público:
+
+```ts
+// app/facturas/actions.ts
+'use server'
+
+import { z } from 'zod'
+import { auth } from '@/lib/auth'
+
+const CrearFacturaSchema = z.object({
+  clienteId: z.coerce.number().int().positive(),
+  items: z.array(z.object({
+    sku:    z.string().max(50),
+    qty:    z.coerce.number().int().min(1).max(9999),
+    precio: z.coerce.number().positive(),
+  })).min(1),
+})
+
+export async function crearFactura(formData: FormData) {
+  // Verificar autenticación
+  const sesion = await auth()
+  if (!sesion?.user) throw new Error('No autorizado')
+
+  // Validar inputs
+  const validado = CrearFacturaSchema.safeParse(Object.fromEntries(formData))
+  if (!validado.success) {
+    return { errores: validado.error.flatten().fieldErrors }
+  }
+
+  // Verificar que el cliente pertenece a la empresa del usuario (IDOR prevention)
+  const cliente = await obtenerClienteDeLaEmpresa(
+    validado.data.clienteId,
+    sesion.user.empresaId,
+  )
+  if (!cliente) return { errores: { clienteId: ['Cliente no encontrado'] } }
+
+  await facturaRepo.crear({ ...validado.data, empresaId: sesion.user.empresaId })
+}
+```
+
+---
+
+## CSRF: protección nativa en Server Actions
+
+- Las Server Actions incluyen protección CSRF automática de Next.js mediante
+  validación de origen. No requiere configuración adicional.
+- Los Route Handlers (`route.ts`) NO tienen CSRF automático. Agregar verificación
+  de origen si reciben mutaciones desde formularios con cookies de sesión:
+
+```ts
+// app/api/webhooks/stripe/route.ts
+export async function POST(request: Request) {
+  // Webhooks externos usan firma, no CSRF
+  const firma = request.headers.get('stripe-signature')
+  await verificarFirmaStripe(firma, await request.text())
+  // ...
+}
+```
+
+---
+
+## Content Security Policy en next.config.js
+
+```js
+// next.config.js
+const securityHeaders = [
+  { key: 'X-DNS-Prefetch-Control',   value: 'on' },
+  { key: 'X-Frame-Options',          value: 'SAMEORIGIN' },
+  { key: 'X-Content-Type-Options',   value: 'nosniff' },
+  { key: 'Referrer-Policy',          value: 'origin-when-cross-origin' },
+  {
+    key: 'Content-Security-Policy',
+    value: [
+      "default-src 'self'",
+      "script-src 'self' 'nonce-{NONCE}'",
+      "style-src 'self' 'unsafe-inline'",
+      "img-src 'self' data: https:",
+      "connect-src 'self' https://api.stripe.com",
+    ].join('; '),
+  },
+]
+
+module.exports = {
+  async headers() {
+    return [{ source: '/(.*)', headers: securityHeaders }]
+  },
+}
+```
+
+---
+
+## No exponer secretos al cliente
+
+- Solo las variables con prefijo `NEXT_PUBLIC_` se exponen al bundle del cliente.
+- NUNCA nombrar variables sensibles con `NEXT_PUBLIC_`:
+
+```bash
+# MAL — secreto expuesto al cliente
+NEXT_PUBLIC_DATABASE_URL=postgresql://...
+NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_...
+
+# BIEN — solo URLs públicas van con el prefijo
+NEXT_PUBLIC_APP_URL=https://app.empresa.com
+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
+
+# BIEN — secretos sin prefijo, solo disponibles en servidor
+STRIPE_SECRET_KEY=sk_live_...
+DATABASE_URL=postgresql://...
+```
+
+---
+
+## Rate limiting en Route Handlers
+
+```ts
+// lib/rate-limit.ts
+import { LRUCache } from 'lru-cache'
+
+const rateLimit = new LRUCache<string, number>({
+  max: 500,
+  ttl: 60 * 1000, // 1 minuto
+})
+
+export function checkRateLimit(ip: string, limit = 30): boolean {
+  const count = (rateLimit.get(ip) ?? 0) + 1
+  rateLimit.set(ip, count)
+  return count <= limit
+}
+
+// app/api/contacto/route.ts
+export async function POST(request: Request) {
+  const ip = request.headers.get('x-forwarded-for') ?? 'unknown'
+  if (!checkRateLimit(ip, 5)) {
+    return new Response('Too Many Requests', { status: 429 })
+  }
+  // ...
+}
+```
+
+---
+
+## Autenticación: NextAuth.js o Clerk
+
+- NUNCA implementar autenticación custom con JWT manual y manejo de sesiones propio.
+- **NextAuth.js (Auth.js v5)**: para proyectos con base de datos propia y necesidad
+  de control total.
+- **Clerk**: para proyectos que priorizan velocidad de implementación y no tienen
+  requisitos de datos en territorio específico.
+- Ambas opciones manejan correctamente: rotación de tokens, revocación de sesiones,
+  CSRF, cookies seguras y OAuth.
+
+---
+
+## dangerouslySetInnerHTML: sanitizar siempre
+
+```tsx
+// MAL — XSS directo si contenido viene del usuario
+<div dangerouslySetInnerHTML={{ __html: comentario.texto }} />
+
+// BIEN — sanitizado antes de renderizar
+import DOMPurify from 'isomorphic-dompurify'
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(comentario.texto) }} />
+```
+
+- Si `dangerouslySetInnerHTML` aparece en el codebase, es una señal de alerta
+  en code review que requiere verificación explícita de la fuente del contenido.
+
+---
+
+## Checklist de seguridad antes de merge
+
+- [ ] Variables de entorno validadas con zod en `lib/env.ts`
+- [ ] Server Actions con validación zod y verificación de autenticación
+- [ ] Server Actions con prevención de IDOR (datos filtrados por empresa/usuario)
+- [ ] CSP configurada en `next.config.js`
+- [ ] Sin variables sensibles con prefijo `NEXT_PUBLIC_`
+- [ ] Rate limiting en Route Handlers públicos
+- [ ] `dangerouslySetInnerHTML` con `DOMPurify.sanitize()` si existe
+- [ ] `npm audit` sin vulnerabilidades HIGH o CRITICAL

package/reglas/lenguajes/nextjs/testing.md

@@ -0,0 +1,193 @@
+# Regla: Testing — Next.js
+
+Probar Next.js con App Router requiere estrategia porque existen tres tipos de
+código distintos: Server Components (async, sin estado de React), Client Components
+(con hooks y eventos) y Server Actions (funciones del servidor invocadas desde el cliente).
+Esta regla define cómo cubrir cada uno.
+
+---
+
+## Stack de testing
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| **Vitest** | Test runner para unit tests y componentes. Reemplaza Jest en proyectos nuevos. |
+| **React Testing Library** | Renderizado y aserción de componentes. |
+| **Playwright** | Tests end-to-end con browser real. |
+| **MSW (Mock Service Worker)** | Mock de API en tests de integración. |
+
+- Configuración de Vitest con soporte de React:
+  ```ts
+  // vitest.config.ts
+  import { defineConfig } from 'vitest/config'
+  import react from '@vitejs/plugin-react'
+
+  export default defineConfig({
+    plugins: [react()],
+    test: {
+      environment: 'jsdom',
+      globals: true,
+      coverage: {
+        provider: 'v8',
+        thresholds: { lines: 80, functions: 80, branches: 80 },
+      },
+    },
+  })
+  ```
+
+---
+
+## Cobertura mínima: 80%
+
+```bash
+vitest run --coverage
+```
+
+- CI falla si algún umbral (líneas, funciones, ramas) cae por debajo del 80%.
+- La cobertura aplica sobre `components/`, `lib/`, `hooks/` y `actions/`.
+  No aplica sobre `app/**/page.tsx` ni `app/**/layout.tsx` (solo orquestan).
+
+---
+
+## Testing de Server Components
+
+Los Server Components son funciones `async` que retornan JSX. Se testean
+renderizando el resultado de la función directamente:
+
+```tsx
+// components/ResumenFactura.tsx
+export async function ResumenFactura({ facturaId }: { facturaId: number }) {
+  const factura = await obtenerFactura(facturaId)
+  return (
+    <article>
+      <h2>{factura.folio}</h2>
+      <p>Total: ${factura.total}</p>
+    </article>
+  )
+}
+
+// components/ResumenFactura.test.tsx
+import { render, screen } from '@testing-library/react'
+import { ResumenFactura } from './ResumenFactura'
+
+vi.mock('@/lib/facturas', () => ({
+  obtenerFactura: vi.fn().mockResolvedValue({
+    id: 1,
+    folio: 'FAC-00001',
+    total: 1160.0,
+  }),
+}))
+
+it('muestra el folio y total de la factura', async () => {
+  // Arrange + Act
+  const componente = await ResumenFactura({ facturaId: 1 })
+  render(componente)
+
+  // Assert
+  expect(screen.getByText('FAC-00001')).toBeInTheDocument()
+  expect(screen.getByText('Total: $1160')).toBeInTheDocument()
+})
+```
+
+---
+
+## Testing de Client Components con React Testing Library
+
+```tsx
+// components/FormularioLogin.test.tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { FormularioLogin } from './FormularioLogin'
+
+describe('FormularioLogin', () => {
+  it('muestra error cuando el email tiene formato inválido', async () => {
+    // Arrange
+    const usuario = userEvent.setup()
+    render(<FormularioLogin />)
+
+    // Act
+    await usuario.type(screen.getByLabelText('Correo electrónico'), 'no-es-email')
+    await usuario.click(screen.getByRole('button', { name: /iniciar sesión/i }))
+
+    // Assert
+    await waitFor(() => {
+      expect(screen.getByRole('alert')).toHaveTextContent('Correo inválido')
+    })
+  })
+})
+```
+
+---
+
+## MSW para mock de API en integración
+
+```ts
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+  http.get('/api/facturas', () => {
+    return HttpResponse.json({
+      data: [{ id: 1, folio: 'FAC-001', total: 580.0 }],
+      meta: { total: 1, page: 1, per_page: 20 },
+    })
+  }),
+]
+
+// tests/setup.ts
+import { setupServer } from 'msw/node'
+import { handlers } from './mocks/handlers'
+
+export const server = setupServer(...handlers)
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+---
+
+## Playwright para E2E
+
+```ts
+// e2e/facturas.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('usuario puede emitir una factura', async ({ page }) => {
+  // Arrange — iniciar sesión
+  await page.goto('/login')
+  await page.fill('[name="email"]', 'admin@empresa.com')
+  await page.fill('[name="password"]', 'password-de-test')
+  await page.click('button[type="submit"]')
+
+  // Act
+  await page.goto('/facturas/nueva')
+  await page.selectOption('[name="clienteId"]', '1')
+  await page.click('button:has-text("Emitir factura")')
+
+  // Assert
+  await expect(page.locator('[data-testid="folio-factura"]')).toBeVisible()
+  await expect(page.locator('[data-testid="estatus-factura"]')).toHaveText('Emitida')
+})
+```
+
+---
+
+## Snapshot testing: solo componentes estables
+
+- Los snapshots de componentes se desactualizan con cada cambio de UI y generan
+  ruido en los diffs. Usar solo para componentes de diseño muy estables.
+- Preferir aserciones explícitas con `getByRole`, `getByText`, `getByLabelText`.
+- Si se usa snapshot: revisar el diff antes de hacer `--updateSnapshot`. No aceptar
+  ciegamente.
+
+---
+
+## Checklist de testing antes de merge
+
+- [ ] `vitest run --coverage` pasa con umbral 80%
+- [ ] Server Components testeados con mock de sus dependencias de datos
+- [ ] Client Components testeados con React Testing Library y `userEvent`
+- [ ] MSW configurado para mocks de API en tests de integración
+- [ ] Al menos 1 test E2E con Playwright por flujo crítico nuevo
+- [ ] Sin `setTimeout` ni `sleep` en tests (usar `waitFor` de RTL)
+- [ ] Snapshot tests solo en componentes explícitamente marcados como estables

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

@@ -0,0 +1,228 @@
+# Regla: Estilo de Código — PHP
+
+Aplica a todo código PHP del proyecto. PHP moderno (8.1+) es un lenguaje con
+tipado estático opcional pero poderoso. Estas reglas maximizan la seguridad de
+tipos, la legibilidad y la mantenibilidad en proyectos Laravel y PHP puro.
+
+---
+
+## PSR-12 como estándar de formato
+
+- PSR-12 es el estándar de codificación obligatorio. Toda discrepancia de formato
+  se resuelve con el formateador automático, no con debate de equipo.
+- Usar **Laravel Pint** en proyectos Laravel, o **PHP-CS-Fixer** en proyectos PHP puro.
+- Ejecutar antes de cada commit:
+  ```bash
+  ./vendor/bin/pint --test    # verifica sin modificar
+  ./vendor/bin/pint           # aplica correcciones
+  ```
+- CI debe fallar si `pint --test` produce diferencias.
+- El archivo `pint.json` (o `.php-cs-fixer.php`) se versiona en el repositorio.
+
+---
+
+## strict_types en todos los archivos
+
+- Todo archivo PHP DEBE comenzar con la declaración de tipos estrictos:
+  ```php
+  <?php
+
+  declare(strict_types=1);
+  ```
+- Sin `declare(strict_types=1)`: PHP convierte tipos silenciosamente y produce bugs difíciles de rastrear.
+- No hay excepciones. Ni en scripts de migración, ni en helpers, ni en tests.
+
+---
+
+## Type hints obligatorios
+
+- Todo parámetro, retorno y propiedad de clase lleva tipo declarado.
+
+**MAL — sin tipos:**
+```php
+function calcularTotal($items, $descuento) {
+    return array_sum(array_column($items, 'precio')) * (1 - $descuento);
+}
+```
+
+**BIEN — con tipos:**
+```php
+function calcularTotal(array $items, float $descuento): float
+{
+    return array_sum(array_column($items, 'precio')) * (1 - $descuento);
+}
+```
+
+- Tipos de retorno `void` cuando la función no retorna valor.
+- `never` cuando la función siempre lanza excepción o termina el proceso.
+- `mixed` solo cuando es genuinamente imposible determinar el tipo.
+  Si aparece `mixed`: señal de deuda técnica, documentar con `// TODO:`.
+
+---
+
+## Readonly properties (PHP 8.2+)
+
+- Propiedades que no cambian después de la construcción se declaran `readonly`:
+
+```php
+// MAL — propiedad mutable que nunca debería mutar
+class Factura
+{
+    public string $folio;
+
+    public function __construct(string $folio)
+    {
+        $this->folio = $folio;
+    }
+}
+
+// BIEN — inmutabilidad declarada explícitamente
+class Factura
+{
+    public function __construct(
+        public readonly string $folio,
+        public readonly \DateTimeImmutable $fechaEmision,
+    ) {}
+}
+```
+
+---
+
+## Enums nativos (PHP 8.1+)
+
+- Reemplazar constantes de clase y strings mágicos con enums nativos:
+
+```php
+// MAL — constantes como pseudo-enum
+class EstatusFactura
+{
+    const BORRADOR = 'borrador';
+    const EMITIDA = 'emitida';
+    const CANCELADA = 'cancelada';
+}
+
+// BIEN — enum nativo con métodos
+enum EstatusFactura: string
+{
+    case Borrador = 'borrador';
+    case Emitida = 'emitida';
+    case Cancelada = 'cancelada';
+
+    public function esTerminal(): bool
+    {
+        return $this === self::Cancelada;
+    }
+}
+```
+
+---
+
+## Named arguments para funciones con muchos parámetros
+
+```php
+// MAL — posicional, ilegible
+$reporte = generarReporte(true, false, null, 'pdf', 100, 1);
+
+// BIEN — named arguments, autodocumentado
+$reporte = generarReporte(
+    incluirImpuestos: true,
+    incluirDescuentos: false,
+    filtroEmpresa: null,
+    formato: 'pdf',
+    limitePaginas: 100,
+    pagina: 1,
+);
+```
+
+---
+
+## Match expression sobre switch
+
+```php
+// MAL — switch verboso
+switch ($estatus) {
+    case 'activo':
+        $etiqueta = 'Activo';
+        break;
+    case 'inactivo':
+        $etiqueta = 'Inactivo';
+        break;
+    default:
+        throw new \InvalidArgumentException("Estatus desconocido: $estatus");
+}
+
+// BIEN — match con exhaustividad
+$etiqueta = match ($estatus) {
+    'activo' => 'Activo',
+    'inactivo' => 'Inactivo',
+    default => throw new \InvalidArgumentException("Estatus desconocido: $estatus"),
+};
+```
+
+---
+
+## Null safe operator en cadenas
+
+```php
+// MAL — verificaciones manuales de null en cadena
+$ciudad = null;
+if ($factura !== null && $factura->cliente !== null && $factura->cliente->direccion !== null) {
+    $ciudad = $factura->cliente->direccion->ciudad;
+}
+
+// BIEN — null safe operator
+$ciudad = $factura?->cliente?->direccion?->ciudad;
+```
+
+---
+
+## Arrow functions para closures simples
+
+```php
+// MAL — closure verboso para transformación simple
+$totales = array_map(function ($factura) {
+    return $factura->total;
+}, $facturas);
+
+// BIEN — arrow function concisa
+$totales = array_map(fn($factura) => $factura->total, $facturas);
+```
+
+---
+
+## Convenciones de nombres
+
+| Elemento | Convención | Ejemplo |
+|----------|-----------|---------|
+| Clases, interfaces, traits, enums | PascalCase | `FacturaService`, `Pagable` |
+| Métodos y funciones | camelCase | `calcularTotal()`, `obtenerCliente()` |
+| Variables y parámetros | camelCase | `$totalFactura`, `$clienteActivo` |
+| Constantes de clase | SCREAMING_SNAKE_CASE | `MAX_INTENTOS`, `TASA_IVA` |
+| Propiedades de modelo | camelCase en PHP, snake_case en BD | `$fechaEmision` ↔ `fecha_emision` |
+
+- Booleanos: prefijo `es`, `tiene`, `puede`, `esta`:
+  `$esActivo`, `$tieneSaldo`, `$puedeEditar`.
+- Colecciones: plural del elemento: `$facturas`, `$usuariosActivos`.
+
+---
+
+## Longitud máxima de método: 40 líneas
+
+- Un método que supera 40 líneas hace más de una cosa. Extraer métodos privados
+  con nombres descriptivos.
+- Complejidad ciclomática máxima: 5. Más de 5 ramas: refactorizar.
+- Parámetros de método: máximo 4. Si se necesitan más, usar un DTO o array tipado.
+
+---
+
+## Checklist de estilo antes de hacer commit
+
+- [ ] `declare(strict_types=1)` en todos los archivos PHP nuevos
+- [ ] `./vendor/bin/pint --test` pasa sin diferencias
+- [ ] Todo parámetro, retorno y propiedad tiene tipo declarado
+- [ ] Sin `mixed` sin comentario justificativo
+- [ ] Enums nativos en lugar de constantes de clase para dominios cerrados
+- [ ] `match` en lugar de `switch` donde aplica
+- [ ] Sin `null` checks manuales en cadena cuando `?->` funciona
+- [ ] Métodos <= 40 líneas
+- [ ] Sin abreviaciones en nombres de variables ni métodos