@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/csharp/hooks.md

@@ -0,0 +1,281 @@
+# Regla: Hooks de Calidad — C# / .NET
+
+Checks automáticos que se ejecutan en puntos clave del ciclo de desarrollo para
+detectar problemas antes de que lleguen al equipo o a producción. Todos los checks
+son obligatorios y bloquean el flujo si detectan un problema.
+
+---
+
+## dotnet format --verify-no-changes 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
+
+set -e
+
+echo "Verificando formato con dotnet format..."
+dotnet format --verify-no-changes
+
+if [ $? -ne 0 ]; then
+    echo "ERROR: El código no está formateado."
+    echo "Ejecutar: dotnet format"
+    exit 1
+fi
+```
+
+Con el framework `pre-commit`:
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: dotnet-format
+        name: dotnet format
+        language: system
+        entry: dotnet format --verify-no-changes
+        pass_filenames: false
+        types: [c#]
+```
+
+- Si el check falla: ejecutar `dotnet format` sin flags y hacer el commit de nuevo.
+- El archivo `.editorconfig` es la fuente de verdad para las reglas de formato.
+- NUNCA commitear con `--no-verify` para saltarse el formato.
+
+---
+
+## dotnet build antes de commit
+
+**Pre-commit hook** — bloquea el commit si hay errores de compilación:
+
+```bash
+echo "Compilando el proyecto..."
+dotnet build --no-restore -warnaserror
+
+if [ $? -ne 0 ]; then
+    echo "ERROR: La compilación falló."
+    echo "Corregir los errores antes de hacer commit."
+    exit 1
+fi
+```
+
+- `--no-restore` en el hook — el restore es costoso y debe hacerse manualmente.
+- `-warnaserror` convierte warnings en errores — la misma configuración que CI.
+- El flag `-warnaserror` debe estar también en el `.csproj` para consistencia:
+  ```xml
+  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+  ```
+
+---
+
+## Roslyn analyzers habilitados como errores
+
+Los analyzers de Roslyn detectan bugs y problemas de seguridad durante la compilación.
+Configurar en el `.csproj`:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <!-- Nullable reference types como errores -->
+    <Nullable>enable</Nullable>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+
+    <!-- Nivel de análisis máximo -->
+    <AnalysisLevel>latest</AnalysisLevel>
+    <AnalysisMode>All</AnalysisMode>
+
+    <!-- Security analyzers -->
+    <EnableNETAnalyzers>true</EnableNETAnalyzers>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- Analyzers adicionales de seguridad -->
+    <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" />
+    <PackageReference Include="SecurityCodeScan.VS2019" PrivateAssets="all" />
+    <PackageReference Include="Meziantou.Analyzer" PrivateAssets="all" />
+  </ItemGroup>
+</Project>
+```
+
+- `SecurityCodeScan` detecta SQL injection, XSS y otras vulnerabilidades OWASP en tiempo de compilación.
+- `Meziantou.Analyzer` detecta patrones problemáticos de async/await, performance y API misuse.
+- Si un analyzer genera un falso positivo: suprimir con `#pragma warning disable CSXXXX`
+  en el sitio exacto, con comentario explicando por qué.
+  NUNCA suprimir a nivel de proyecto sin revisión del equipo.
+
+---
+
+## Detección de Console.WriteLine en código no-test
+
+**En CI como parte del build** — detecta logs de debug que no deben llegar a producción:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Verificar ausencia de Console.WriteLine en producción
+  run: |
+    # Buscar en src/ pero no en archivos de test
+    if grep -rn "Console\.Write" src/ --include="*.cs" | \
+       grep -v "\.Tests\." | grep -v "// ALLOW-CONSOLE"; then
+      echo "ERROR: Console.Write encontrado en código de producción."
+      echo "Usar ILogger<T> en su lugar."
+      exit 1
+    fi
+```
+
+O mediante un analyzer de Roslyn configurado en `.editorconfig`:
+
+```ini
+# .editorconfig
+[*.cs]
+# Prohibir Console.Write* en código de producción
+dotnet_diagnostic.CA2241.severity = error
+
+# Configurar analyzer para detectar Console.WriteLine
+dotnet_diagnostic.MA0003.severity = error  # Meziantou: evitar Console.Write
+```
+
+- `Console.WriteLine` y `Console.Write` permitidos solo en:
+  - Proyectos de tipo CLI/consola donde es el output intencionado
+  - Archivos `*.Tests.cs` o dentro de proyectos `*.Tests`
+  - Código marcado con `// ALLOW-CONSOLE: razón específica`
+- En el resto del código: usar `ILogger<T>` inyectado via DI.
+
+---
+
+## dotnet test con cobertura en CI
+
+```yaml
+# .github/workflows/ci.yml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.x'
+
+      - name: Restaurar dependencias
+        run: dotnet restore
+
+      - name: Compilar
+        run: dotnet build --no-restore -warnaserror
+
+      - name: Ejecutar tests con cobertura
+        run: |
+          dotnet test --no-build \
+            --collect:"XPlat Code Coverage" \
+            --results-directory ./coverage
+
+      - name: Verificar umbral de cobertura
+        run: |
+          dotnet tool install -g dotnet-reportgenerator-globaltool
+          reportgenerator \
+            -reports:"./coverage/**/*.xml" \
+            -targetdir:./coverage-report \
+            -reporttypes:Cobertura
+          # Falla si cobertura total < 80%
+          python scripts/check-coverage.py ./coverage-report/Cobertura.xml 80
+
+      - name: Publicar reporte de cobertura
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: ./coverage-report
+```
+
+- `dotnet test` en CI con `--collect:"XPlat Code Coverage"` genera reportes Cobertura XML.
+- Publicar el reporte como artefacto del job para revisión post-ejecución.
+- Cobertura mínima: 80% para proyectos de lógica de negocio.
+
+---
+
+## Security analyzers integrados
+
+```yaml
+# Job de seguridad en CI — separado del job de tests
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verificar vulnerabilidades en paquetes
+        run: dotnet list package --vulnerable --include-transitive
+
+      - name: Ejecutar CodeQL
+        uses: github/codeql-action/analyze@v3
+        with:
+          languages: csharp
+
+      - name: Ejecutar OWASP Dependency Check
+        uses: dependency-check/Dependency-Check_Action@main
+        with:
+          format: HTML
+          args: >
+            --scan . --out reports
+            --failOnCVSS 7
+```
+
+- `dotnet list package --vulnerable` detecta NuGet packages con CVEs conocidos.
+- CodeQL analiza el código en busca de vulnerabilidades de seguridad.
+- OWASP Dependency Check como capa adicional para detección de CVEs.
+- El job de seguridad corre en cada PR y semanalmente como job independiente.
+
+---
+
+## Configuracion completa del pipeline CI
+
+```yaml
+# .github/workflows/ci.yml — pipeline completo
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with: { dotnet-version: '8.x' }
+      - run: dotnet format --verify-no-changes
+
+  build-and-test:
+    runs-on: ubuntu-latest
+    needs: format
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with: { dotnet-version: '8.x' }
+      - run: dotnet restore
+      - run: dotnet build --no-restore -warnaserror
+      - run: dotnet test --no-build --collect:"XPlat Code Coverage"
+
+  security:
+    runs-on: ubuntu-latest
+    needs: build-and-test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-dotnet@v4
+        with: { dotnet-version: '8.x' }
+      - run: dotnet list package --vulnerable --include-transitive
+```
+
+---
+
+## Checklist de hooks antes de integrar al proyecto
+
+- [ ] Hook de pre-commit instalado con `dotnet format --verify-no-changes`
+- [ ] Hook de pre-commit con `dotnet build -warnaserror`
+- [ ] `<TreatWarningsAsErrors>true</TreatWarningsAsErrors>` en todos los `.csproj`
+- [ ] `<Nullable>enable</Nullable>` en todos los `.csproj`
+- [ ] Roslyn analyzers configurados (`SecurityCodeScan`, `Meziantou.Analyzer`)
+- [ ] Pipeline de CI con job de formato, compilación, tests y seguridad
+- [ ] `dotnet test` con cobertura en CI y verificación del umbral del 80%
+- [ ] `dotnet list package --vulnerable` en CI (cada PR y semanalmente)
+- [ ] Detección de `Console.WriteLine` en código de producción

package/reglas/lenguajes/csharp/patrones.md

@@ -0,0 +1,226 @@
+# Regla: Patrones de Diseño — C# / .NET
+
+Patrones establecidos en el ecosistema .NET moderno para código mantenible,
+testeable y con separación clara de responsabilidades. Estos patrones están
+soportados por las herramientas del stack — no reinventar lo que ya existe.
+
+---
+
+## CQRS con MediatR
+
+Separar operaciones de lectura (queries) de escritura (commands):
+
+```csharp
+// Command — modifica estado, no retorna datos de negocio
+public record CrearFacturaCommand(string ClienteEmail, decimal Total)
+    : IRequest<Guid>;
+
+public class CrearFacturaHandler : IRequestHandler<CrearFacturaCommand, Guid>
+{
+    public async Task<Guid> Handle(CrearFacturaCommand cmd, CancellationToken ct)
+    {
+        var factura = new Factura(cmd.ClienteEmail, cmd.Total);
+        await _repo.AgregarAsync(factura, ct);
+        return factura.Id;
+    }
+}
+
+// Query — solo lectura, no modifica estado
+public record ObtenerFacturasQuery(string ClienteEmail)
+    : IRequest<IReadOnlyList<FacturaDto>>;
+
+// En el endpoint
+app.MapPost("/facturas", async (CrearFacturaCommand cmd, IMediator mediator) =>
+    Results.Created($"/facturas/{await mediator.Send(cmd)}", null));
+```
+
+- Cada Command y Query es un record inmutable con los parámetros necesarios.
+- Los Handlers tienen una sola responsabilidad.
+- MediatR permite agregar behaviors (pipeline) para logging, validación y cache
+  sin modificar los handlers.
+
+---
+
+## Repository pattern con EF Core
+
+```csharp
+// Interfaz — define el contrato, independiente de EF
+public interface IFacturaRepository
+{
+    Task<Factura?> ObtenerPorIdAsync(Guid id, CancellationToken ct = default);
+    Task<IReadOnlyList<Factura>> ListarPorClienteAsync(string email, CancellationToken ct = default);
+    Task AgregarAsync(Factura factura, CancellationToken ct = default);
+}
+
+// Implementación con EF Core
+public class FacturaRepository : IFacturaRepository
+{
+    private readonly AppDbContext _db;
+
+    public async Task<Factura?> ObtenerPorIdAsync(Guid id, CancellationToken ct)
+        => await _db.Facturas.FindAsync(new object[] { id }, ct);
+
+    public async Task AgregarAsync(Factura factura, CancellationToken ct)
+    {
+        await _db.Facturas.AddAsync(factura, ct);
+        // No llama SaveChangesAsync — eso es responsabilidad del servicio/handler
+    }
+}
+```
+
+- Los repositorios NUNCA llaman `SaveChangesAsync` — eso es del Handler o Service.
+- Inyectar la interfaz (`IFacturaRepository`), no la implementación concreta.
+- `Unit of Work` via `AppDbContext.SaveChangesAsync()` en el Handler, después de
+  todas las operaciones de la transacción.
+
+---
+
+## Options pattern para configuración
+
+```csharp
+// Clase de configuración fuertemente tipada
+public class SmtpOptions
+{
+    public const string SectionName = "Smtp";
+
+    public string Host { get; init; } = string.Empty;
+    public int Puerto { get; init; } = 587;
+    public bool UsarTls { get; init; } = true;
+}
+
+// Registro en Program.cs
+builder.Services.Configure<SmtpOptions>(
+    builder.Configuration.GetSection(SmtpOptions.SectionName));
+
+// Uso en servicios — IOptions<T> para configuración estática
+public class EmailService(IOptions<SmtpOptions> opts)
+{
+    private readonly SmtpOptions _config = opts.Value;
+}
+
+// IOptionsSnapshot<T> para configuración recargable por request
+// IOptionsMonitor<T> para configuración recargable en singletons
+```
+
+- NUNCA inyectar `IConfiguration` directamente en servicios — usar Options pattern.
+- Validar la configuración al inicio con `ValidateDataAnnotations()` o `Validate()`.
+- `init` (no `set`) para propiedades de configuración — son inmutables después de cargar.
+
+---
+
+## Dependency injection nativo de .NET
+
+```csharp
+// Program.cs — registro de servicios
+builder.Services.AddScoped<IFacturaRepository, FacturaRepository>();
+builder.Services.AddScoped<IEmailService, SmtpEmailService>();
+builder.Services.AddSingleton<ICacheService, RedisCacheService>();
+
+// Lifetimes:
+// Scoped    — una instancia por request HTTP (la más común para servicios)
+// Transient — nueva instancia cada vez (para servicios sin estado)
+// Singleton — una instancia por toda la vida de la app (caches, configs)
+```
+
+- Usar el DI nativo de .NET — no agregar Autofac, Ninject u otros contenedores
+  sin una razón técnica específica documentada.
+- NUNCA usar `ServiceLocator` o `IServiceProvider` directamente en servicios
+  de negocio — es un anti-patrón que oculta dependencias.
+- Registrar la interfaz, no la implementación: `AddScoped<IServicio, Implementacion>()`.
+
+---
+
+## Result pattern para errores sin excepciones
+
+```csharp
+// MAL — excepciones para flujo de control normal
+public async Task<Factura> ObtenerAsync(Guid id)
+{
+    var factura = await _repo.ObtenerPorIdAsync(id);
+    if (factura is null)
+        throw new FacturaNotFoundException(id); // excepción como flujo normal
+    return factura;
+}
+
+// BIEN — Result pattern expresa el error en el tipo de retorno
+public async Task<Result<Factura>> ObtenerAsync(Guid id, CancellationToken ct)
+{
+    var factura = await _repo.ObtenerPorIdAsync(id, ct);
+    return factura is not null
+        ? Result.Ok(factura)
+        : Result.Fail<Factura>($"Factura {id} no encontrada");
+}
+
+// En el handler/endpoint — manejo explícito
+var resultado = await servicio.ObtenerAsync(id, ct);
+if (resultado.IsFailed)
+    return Results.NotFound(resultado.Errors);
+```
+
+- Usar `FluentResults` o `ErrorOr` para el Result pattern.
+- Las excepciones son para condiciones verdaderamente excepcionales (corrupción de datos,
+  fallas de infraestructura) — no para flujos de negocio esperados.
+- Los endpoints mapean `Result<T>` a respuestas HTTP apropiadas.
+
+---
+
+## Channel<T> para productor/consumidor
+
+```csharp
+// Para procesar eventos de forma asíncrona sin bloquear el request
+public class ColaProcesamiento<T>
+{
+    private readonly Channel<T> _canal = Channel.CreateBounded<T>(
+        new BoundedChannelOptions(1000) { FullMode = BoundedChannelFullMode.Wait });
+
+    public async ValueTask EnqueueAsync(T item, CancellationToken ct)
+        => await _canal.Writer.WriteAsync(item, ct);
+
+    public async Task ProcesarAsync(
+        Func<T, CancellationToken, Task> procesador,
+        CancellationToken ct)
+    {
+        await foreach (var item in _canal.Reader.ReadAllAsync(ct))
+            await procesador(item, ct);
+    }
+}
+```
+
+- `Channel<T>` para comunicación asíncrona entre productores y consumidores.
+- `BoundedChannel` con límite de capacidad — evita consumo ilimitado de memoria.
+- Usar `BackgroundService` de .NET para el consumidor.
+
+---
+
+## Minimal APIs vs Controllers: criterio de decisión
+
+| Situación | Usar | Razón |
+|-----------|------|-------|
+| APIs simples, pocos endpoints | Minimal APIs | Menos boilerplate, más rápido |
+| APIs grandes con muchos filtros y convenciones | Controllers | Mejor organización con attributes |
+| Versionado de API complejo | Controllers | ApiExplorer integrado más maduro |
+| Alta performance, bajo overhead | Minimal APIs | Menor overhead por request |
+| Equipo familiarizado con MVC | Controllers | Menor curva de aprendizaje |
+
+```csharp
+// Minimal API — para servicios simples o microservicios
+app.MapGet("/facturas/{id:guid}", async (Guid id, IMediator mediator, CancellationToken ct)
+    => await mediator.Send(new ObtenerFacturaQuery(id), ct) is { } factura
+        ? Results.Ok(factura)
+        : Results.NotFound())
+    .WithName("ObtenerFactura")
+    .RequireAuthorization();
+```
+
+---
+
+## Checklist de patrones antes de hacer merge
+
+- [ ] Commands y Queries son records inmutables que implementan `IRequest<T>`
+- [ ] Handlers tienen exactamente una responsabilidad
+- [ ] Repositorios no llaman `SaveChangesAsync` — eso es del handler
+- [ ] Configuración accedida via `IOptions<T>`, no `IConfiguration` directamente
+- [ ] Sin uso de `ServiceLocator` en servicios de negocio
+- [ ] Errores de flujo normal manejados con Result pattern, no excepciones
+- [ ] `CancellationToken` propagado en todas las operaciones async
+- [ ] DI nativo de .NET — sin contenedores externos sin justificación