@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/java/hooks.md

@@ -0,0 +1,251 @@
+# Regla: Hooks de Desarrollo Java
+
+Los hooks de desarrollo son verificaciones automáticas que atrapan problemas
+antes de que lleguen al repositorio o al CI. Ejecutar manualmente es propenso
+a olvidos — automatizar garantiza consistencia.
+
+---
+
+## Checkstyle: verificación de estilo antes de commit
+
+Checkstyle verifica que el código sigue las convenciones definidas. Se integra
+como plugin de Maven/Gradle y como pre-commit hook.
+
+```xml
+<!-- pom.xml -->
+<plugin>
+  <groupId>org.apache.maven.plugins</groupId>
+  <artifactId>maven-checkstyle-plugin</artifactId>
+  <version>3.3.1</version>
+  <configuration>
+    <configLocation>google_checks.xml</configLocation>
+    <failsOnError>true</failsOnError>
+    <violationSeverity>warning</violationSeverity>
+  </configuration>
+  <executions>
+    <execution>
+      <id>validar-estilo</id>
+      <phase>validate</phase>
+      <goals><goal>check</goal></goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+Pre-commit hook local (`.git/hooks/pre-commit`):
+
+```bash
+#!/bin/sh
+# Verificar estilo Checkstyle antes de cada commit
+mvn checkstyle:check -q 2>&1
+if [ $? -ne 0 ]; then
+    echo "ERROR: Checkstyle falló. Corregir estilo antes de hacer commit."
+    echo "Ejecutar: mvn checkstyle:check para ver los errores."
+    exit 1
+fi
+```
+
+---
+
+## Spotless: formato automático obligatorio
+
+Spotless puede formatear en lugar de solo verificar. Integrar como hook de
+formato automático antes de verificar estilo.
+
+```xml
+<!-- pom.xml — Spotless formatea con google-java-format -->
+<plugin>
+  <groupId>com.diffplug.spotless</groupId>
+  <artifactId>spotless-maven-plugin</artifactId>
+  <version>2.43.0</version>
+  <configuration>
+    <java>
+      <googleJavaFormat>
+        <version>1.19.2</version>
+        <style>AOSP</style>
+      </googleJavaFormat>
+      <removeUnusedImports/>
+      <trimTrailingWhitespace/>
+    </java>
+  </configuration>
+  <executions>
+    <execution>
+      <phase>compile</phase>
+      <goals><goal>check</goal></goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+Aplicar formato manualmente antes de commit: `mvn spotless:apply`
+
+---
+
+## SpotBugs: análisis estático
+
+SpotBugs detecta bugs comunes (null pointer potential, resource leaks, bad practices)
+antes de que lleguen a producción.
+
+```xml
+<!-- pom.xml -->
+<plugin>
+  <groupId>com.github.spotbugs</groupId>
+  <artifactId>spotbugs-maven-plugin</artifactId>
+  <version>4.8.3.0</version>
+  <configuration>
+    <effort>Max</effort>
+    <threshold>Medium</threshold>
+    <failOnError>true</failOnError>
+    <plugins>
+      <!-- Detectar bugs de seguridad adicionales -->
+      <plugin>
+        <groupId>com.h3xstream.findsecbugs</groupId>
+        <artifactId>findsecbugs-plugin</artifactId>
+        <version>1.13.0</version>
+      </plugin>
+    </plugins>
+  </configuration>
+  <executions>
+    <execution>
+      <phase>verify</phase>
+      <goals><goal>check</goal></goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+---
+
+## JaCoCo: cobertura mínima en CI
+
+La cobertura se verifica en CI como gate bloqueante. Sin cobertura >= 80%,
+el build falla y no se puede mergear.
+
+```xml
+<!-- pom.xml -->
+<plugin>
+  <groupId>org.jacoco</groupId>
+  <artifactId>jacoco-maven-plugin</artifactId>
+  <version>0.8.11</version>
+  <executions>
+    <execution>
+      <id>prepare-agent</id>
+      <goals><goal>prepare-agent</goal></goals>
+    </execution>
+    <execution>
+      <id>report</id>
+      <phase>test</phase>
+      <goals><goal>report</goal></goals>
+    </execution>
+    <execution>
+      <id>check</id>
+      <phase>verify</phase>
+      <goals><goal>check</goal></goals>
+      <configuration>
+        <rules>
+          <rule>
+            <element>BUNDLE</element>
+            <limits>
+              <limit>
+                <counter>LINE</counter>
+                <value>COVEREDRATIO</value>
+                <minimum>0.80</minimum>
+              </limit>
+            </limits>
+          </rule>
+        </rules>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+```
+
+---
+
+## Detección de System.out.println en código no-test
+
+`System.out.println` en código de producción es un antipatrón. El logger
+configurado maneja niveles, formatos y destinos correctamente.
+
+Hook en CI (o pre-commit) que detecta y bloquea:
+
+```bash
+#!/bin/sh
+# Detectar System.out.println en código que no es test
+ARCHIVOS_CON_PRINT=$(grep -r "System\.out\.println" src/main/ --include="*.java" -l)
+
+if [ -n "$ARCHIVOS_CON_PRINT" ]; then
+    echo "ERROR: System.out.println detectado en código de producción."
+    echo "Usar SLF4J (log.info, log.debug, log.error) en su lugar."
+    echo "Archivos afectados:"
+    echo "$ARCHIVOS_CON_PRINT"
+    exit 1
+fi
+```
+
+En el `pom.xml` con Checkstyle, agregar la regla `RegexpSingleline`:
+
+```xml
+<module name="RegexpSingleline">
+  <property name="format" value="System\.out\.println"/>
+  <property name="message" value="Usar SLF4J en lugar de System.out.println"/>
+</module>
+```
+
+---
+
+## Verificación de @Deprecated sin javadoc de reemplazo
+
+Métodos deprecados sin indicar el reemplazo confunden al equipo.
+
+```java
+// MAL — sin indicación de reemplazo
+@Deprecated
+public Factura crearFacturaLegacy(String datos) { ... }
+
+// BIEN — documenta cuándo fue deprecado y qué usar en su lugar
+/**
+ * @deprecated Desde v2.3.0. Usar {@link FacturaService#crear(CrearFacturaRequest)} en su lugar.
+ */
+@Deprecated(since = "2.3.0", forRemoval = true)
+public Factura crearFacturaLegacy(String datos) { ... }
+```
+
+Script de verificación en CI:
+
+```bash
+#!/bin/sh
+# Detectar @Deprecated sin comentario de reemplazo
+DEPRECATED_SIN_DOC=$(grep -B2 "@Deprecated" src/main/**/*.java | grep -v "@deprecated" | grep "@Deprecated" || true)
+
+if [ -n "$DEPRECATED_SIN_DOC" ]; then
+    echo "ADVERTENCIA: @Deprecated sin javadoc de reemplazo encontrado."
+    echo "Agregar @deprecated en el javadoc indicando el reemplazo y la versión."
+fi
+```
+
+---
+
+## Pipeline CI completa de calidad
+
+Orden de ejecución en el pipeline de CI (cada fase bloquea las siguientes):
+
+```
+1. mvn spotless:check          → Formato de código
+2. mvn checkstyle:check        → Estilo y convenciones
+3. mvn test                    → Tests unitarios
+4. mvn spotbugs:check          → Análisis estático
+5. mvn verify                  → Tests de integración + cobertura JaCoCo
+6. mvn dependency-check:check  → Vulnerabilidades en dependencias
+```
+
+---
+
+## Checklist de hooks Java antes de hacer commit
+
+- [ ] `mvn spotless:check` pasa (o `mvn spotless:apply` aplicado)
+- [ ] `mvn checkstyle:check` pasa sin errores
+- [ ] Sin `System.out.println` en `src/main/`
+- [ ] Métodos @Deprecated tienen javadoc con reemplazo y versión
+- [ ] `mvn test` pasa localmente
+- [ ] `mvn spotbugs:check` pasa sin bugs de severidad media o alta

package/reglas/lenguajes/java/patrones.md

@@ -0,0 +1,226 @@
+# Regla: Patrones Java Idiomáticos
+
+Los patrones aquí listados no son opcionales: representan las soluciones probadas
+para problemas recurrentes en código Java de producción. Ignorarlos genera deuda
+técnica predecible y bugs conocidos.
+
+---
+
+## Inyección de dependencias vía constructor (nunca field injection)
+
+La inyección por campo (`@Autowired` en el campo) oculta dependencias, impide
+tests sin contenedor IoC y viola el principio de inmutabilidad.
+
+```java
+// MAL — field injection: dependencias ocultas, imposible testear sin Spring
+@Service
+public class FacturaService {
+    @Autowired
+    private FacturaRepository repositorio;  // no se ve en el constructor
+    @Autowired
+    private EventoPublicador publicador;
+}
+
+// BIEN — constructor injection: dependencias explícitas, testeable con mocks simples
+@Service
+public class FacturaService {
+    private final FacturaRepository repositorio;
+    private final EventoPublicador publicador;
+
+    public FacturaService(FacturaRepository repositorio, EventoPublicador publicador) {
+        this.repositorio = repositorio;
+        this.publicador = publicador;
+    }
+}
+```
+
+Con Lombok: `@RequiredArgsConstructor` en la clase + campos `final` genera el
+constructor automáticamente sin renunciar a la inyección por constructor.
+
+---
+
+## Repository pattern con interfaces
+
+Toda interacción con persistencia pasa por una interfaz de repositorio.
+La lógica de negocio depende de la interfaz, no de la implementación.
+
+```java
+// Interfaz — define el contrato, no el cómo
+public interface FacturaRepository {
+    Optional<Factura> buscarPorId(UUID id);
+    List<Factura> listarPorCliente(UUID clienteId, Pageable pageable);
+    Factura guardar(Factura factura);
+}
+
+// Implementación — detalle de persistencia (JPA, JDBC, etc.)
+@Repository
+public class FacturaRepositoryJpa implements FacturaRepository {
+    private final JpaFacturaRepository jpa;
+    // ...
+}
+```
+
+---
+
+## Builder pattern para objetos complejos
+
+Usar builder cuando un objeto tiene más de 4 parámetros opcionales de construcción.
+Lombok `@Builder` es la implementación preferida.
+
+```java
+// MAL — constructor telescópico: frágil, no documenta qué es cada argumento
+Factura f = new Factura(clienteId, fecha, items, descuento, null, "BORRADOR", true);
+
+// BIEN — builder: cada parámetro es explícito y opcional
+Factura factura = Factura.builder()
+    .clienteId(clienteId)
+    .fecha(LocalDate.now())
+    .items(items)
+    .descuento(BigDecimal.ZERO)
+    .estatus(EstatusFactura.BORRADOR)
+    .build();
+```
+
+---
+
+## Strategy con interfaces funcionales
+
+Para comportamiento intercambiable, preferir interfaces funcionales sobre
+jerarquías de clases cuando la estrategia es simple.
+
+```java
+// Interfaz funcional como estrategia
+@FunctionalInterface
+public interface CalculadorDescuento {
+    BigDecimal calcular(BigDecimal subtotal);
+}
+
+// Estrategias como lambdas o method references — sin clases adicionales
+CalculadorDescuento sinDescuento = subtotal -> BigDecimal.ZERO;
+CalculadorDescuento descuentoFijo = subtotal -> new BigDecimal("100.00");
+CalculadorDescuento descuentoPorcentual = subtotal -> subtotal.multiply(new BigDecimal("0.10"));
+```
+
+---
+
+## Stream API sobre loops imperativos
+
+Preferir Stream API para transformaciones, filtros y agregaciones de colecciones.
+Los loops imperativos son aceptables cuando el Stream resultaría más oscuro.
+
+```java
+// MAL — loop imperativo para transformación simple
+List<String> nombres = new ArrayList<>();
+for (Usuario u : usuarios) {
+    if (u.isActivo()) {
+        nombres.add(u.getNombre().toUpperCase());
+    }
+}
+
+// BIEN — Stream declara la intención, no los pasos
+List<String> nombres = usuarios.stream()
+    .filter(Usuario::isActivo)
+    .map(Usuario::getNombre)
+    .map(String::toUpperCase)
+    .toList();  // Java 16+: List inmutable directamente
+```
+
+---
+
+## CompletableFuture para operaciones asíncronas
+
+```java
+// Composición de operaciones asíncronas sin bloquear threads
+public CompletableFuture<FacturaEnviada> crearYEnviarFactura(FacturaRequest request) {
+    return CompletableFuture
+        .supplyAsync(() -> repositorio.guardar(request.toEntidad()), executor)
+        .thenApplyAsync(factura -> generarPdf(factura), executor)
+        .thenApplyAsync(pdf -> servicioEmail.enviar(pdf), executor)
+        .exceptionally(ex -> {
+            log.error("Error al crear factura", ex);
+            throw new FacturaException("No se pudo crear la factura", ex);
+        });
+}
+```
+
+---
+
+## Try-with-resources obligatorio
+
+Todo recurso que implementa `AutoCloseable` DEBE abrirse en try-with-resources.
+Nunca cerrar manualmente en `finally`.
+
+```java
+// MAL — cierre manual propenso a fugas de recursos
+InputStream stream = new FileInputStream(archivo);
+try {
+    procesar(stream);
+} finally {
+    stream.close();  // ¿qué pasa si procesar() lanza excepción?
+}
+
+// BIEN — cierre garantizado por la JVM
+try (var stream = new FileInputStream(archivo);
+     var reader = new BufferedReader(new InputStreamReader(stream))) {
+    procesar(reader);
+}
+```
+
+---
+
+## Jerarquía propia de excepciones
+
+- Excepciones de negocio heredan de `RuntimeException` (unchecked).
+- Checked exceptions solo para condiciones recuperables que el llamador DEBE manejar.
+- Nunca capturar `Exception` o `Throwable` sin razón documentada.
+
+```java
+// Jerarquía de dominio
+public class DominioException extends RuntimeException {
+    public DominioException(String mensaje) { super(mensaje); }
+    public DominioException(String mensaje, Throwable causa) { super(mensaje, causa); }
+}
+
+public class FacturaNoEncontradaException extends DominioException {
+    public FacturaNoEncontradaException(UUID id) {
+        super("Factura no encontrada: " + id);
+    }
+}
+
+public class SaldoInsuficienteException extends DominioException { ... }
+```
+
+---
+
+## Factory method para construcción compleja
+
+Cuando la construcción de un objeto requiere lógica, usar factory method estático
+en lugar de sobrecargar constructores.
+
+```java
+public class Factura {
+    // Factory methods con nombres descriptivos
+    public static Factura nueva(Cliente cliente, List<LineaFactura> lineas) {
+        var factura = new Factura();
+        factura.folio = generarFolio();
+        factura.cliente = cliente;
+        factura.lineas = List.copyOf(lineas);
+        factura.calcularTotales();
+        return factura;
+    }
+
+    public static Factura desde(FacturaDto dto) { ... }
+}
+```
+
+---
+
+## Checklist de patrones Java antes de abrir PR
+
+- [ ] Sin @Autowired en campos — inyección solo por constructor
+- [ ] Objetos con >4 parámetros usan Builder
+- [ ] Interacción con BD a través de interfaces Repository
+- [ ] Recursos AutoCloseable abiertos con try-with-resources
+- [ ] Excepciones de negocio extienden RuntimeException con jerarquía propia
+- [ ] Transformaciones de colecciones usan Stream API
+- [ ] Sin loops for que podrían ser un stream de 3 líneas

package/reglas/lenguajes/java/seguridad.md

@@ -0,0 +1,233 @@
+# Regla: Seguridad Java
+
+Esta regla es OBLIGATORIA. Ningún endpoint, servicio o componente se considera
+completo si viola alguno de los puntos aquí listados.
+Las vulnerabilidades de seguridad en Java tienen consecuencias predecibles
+y conocidas — no hay excusa para repetirlas.
+
+---
+
+## PreparedStatement SIEMPRE — nunca concatenar SQL
+
+La inyección SQL sigue siendo la vulnerabilidad #1 en aplicaciones Java.
+Es 100% evitable con parameterized queries.
+
+```java
+// MAL — SQL injection garantizada
+String query = "SELECT * FROM usuarios WHERE email = '" + email + "'";
+Statement stmt = conn.createStatement();
+ResultSet rs = stmt.executeQuery(query);
+
+// MAL — también vulnerable aunque parezca diferente
+String query = String.format("SELECT * FROM facturas WHERE id = %s", id);
+
+// BIEN — PreparedStatement con parámetros nombrados
+String query = "SELECT * FROM usuarios WHERE email = ? AND activo = ?";
+try (var stmt = conn.prepareStatement(query)) {
+    stmt.setString(1, email);
+    stmt.setBoolean(2, true);
+    ResultSet rs = stmt.executeQuery();
+}
+
+// BIEN — con JPA/Spring Data (ORM hace el trabajo)
+List<Usuario> usuarios = repositorio.findByEmailAndActivo(email, true);
+```
+
+Si se requiere SQL dinámico, usar `JdbcTemplate` con `?` o named parameters,
+nunca `String.format()` ni concatenación.
+
+---
+
+## Validación con @Valid y Bean Validation
+
+Toda entrada del usuario DEBE validarse en el servidor. La validación en frontend
+es UX, no seguridad.
+
+```java
+// DTO con restricciones de Bean Validation
+public record CrearFacturaRequest(
+    @NotNull(message = "El cliente es obligatorio")
+    UUID clienteId,
+
+    @NotEmpty(message = "La factura debe tener al menos una línea")
+    @Size(max = 100, message = "Máximo 100 líneas por factura")
+    List<@Valid LineaRequest> lineas,
+
+    @DecimalMin(value = "0.0", message = "El descuento no puede ser negativo")
+    @DecimalMax(value = "100.0", message = "El descuento no puede superar 100%")
+    BigDecimal descuentoPorcentaje
+) {}
+
+// Controller — @Valid activa la validación automáticamente
+@PostMapping("/facturas")
+public ResponseEntity<FacturaDto> crear(@RequestBody @Valid CrearFacturaRequest request) {
+    // Si llega aquí, request ya fue validado
+}
+```
+
+---
+
+## Spring Security: CORS, CSRF y sesiones
+
+```java
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    @Bean
+    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            // CORS desde variables de entorno, nunca hardcodeado
+            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
+            // CSRF: habilitar para apps con sesiones; deshabilitar solo en APIs stateless con JWT
+            .csrf(csrf -> csrf.disable())  // APIs REST con JWT — documentar por qué
+            // Sesiones stateless para APIs REST
+            .sessionManagement(session ->
+                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            // Headers de seguridad
+            .headers(headers -> headers
+                .frameOptions(frame -> frame.deny())
+                .xssProtection(xss -> xss.disable())  // CSP es mejor que X-XSS-Protection
+                .contentSecurityPolicy(csp ->
+                    csp.policyDirectives("default-src 'self'")))
+            .build();
+    }
+
+    @Bean
+    public CorsConfigurationSource corsConfigurationSource() {
+        var config = new CorsConfiguration();
+        // Leer desde environment, NUNCA hardcodear
+        config.setAllowedOrigins(List.of(env.getProperty("cors.allowed-origins").split(",")));
+        config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+        config.setAllowedHeaders(List.of("Authorization", "Content-Type"));
+        var source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/api/**", config);
+        return source;
+    }
+}
+```
+
+---
+
+## Secretos vía variables de entorno
+
+```java
+// MAL — secreto hardcodeado en el código fuente
+private static final String JWT_SECRET = "mi-secreto-super-secreto";
+private static final String DB_PASSWORD = "admin123";
+
+// MAL — secreto en application.properties que se versiona
+// application.properties:
+// spring.datasource.password=admin123
+
+// BIEN — variables de entorno inyectadas
+@Value("${JWT_SECRET}")
+private String jwtSecret;
+
+// BIEN — application.properties usa placeholders
+// application.properties:
+// spring.datasource.password=${DB_PASSWORD}
+// jwt.secret=${JWT_SECRET}
+```
+
+El archivo `.env` es solo para desarrollo local y SIEMPRE está en `.gitignore`.
+En producción, las variables se inyectan desde Vault, AWS Secrets Manager o el
+sistema de deployment.
+
+---
+
+## No deserializar objetos no confiables
+
+```java
+// MAL — deserialización insegura: vector de RCE (Remote Code Execution)
+ObjectInputStream ois = new ObjectInputStream(inputStreamDeUsuario);
+Object objeto = ois.readObject();  // NUNCA con datos no confiables
+
+// BIEN — usar JSON con Jackson o protobuf, no serialización Java nativa
+ObjectMapper mapper = new ObjectMapper();
+FacturaDto dto = mapper.readValue(jsonInput, FacturaDto.class);
+
+// BIEN — si se requiere deserialización Java, usar filtros de clase
+ObjectInputStream ois = new ObjectInputStream(input) {
+    @Override
+    protected Class<?> resolveClass(ObjectStreamClass desc) throws ClassNotFoundException {
+        if (!desc.getName().startsWith("com.miempresa.")) {
+            throw new InvalidClassException("Clase no permitida: " + desc.getName());
+        }
+        return super.resolveClass(desc);
+    }
+};
+```
+
+---
+
+## OWASP Dependency Check en CI
+
+```xml
+<!-- pom.xml — falla el build si hay CVE de severidad >= 8.0 -->
+<plugin>
+  <groupId>org.owasp</groupId>
+  <artifactId>dependency-check-maven</artifactId>
+  <version>9.0.10</version>
+  <configuration>
+    <failBuildOnCVSS>8</failBuildOnCVSS>
+    <suppressionFile>owasp-suppressions.xml</suppressionFile>
+  </configuration>
+  <executions>
+    <execution>
+      <goals><goal>check</goal></goals>
+    </execution>
+  </executions>
+</plugin>
+```
+
+---
+
+## Logging sin datos sensibles (SLF4J + Logback)
+
+```java
+// MAL — datos sensibles en logs
+log.info("Usuario autenticado: {} con contraseña: {}", email, password);
+log.debug("Token JWT generado: {}", jwtToken);
+log.error("Error de BD al procesar: {}", tarjetaCredito.getNumero());
+
+// BIEN — log solo información no sensible
+log.info("Autenticación exitosa para usuario: {}", email);
+log.debug("Token JWT generado para sesión: {}", sesionId);
+log.error("Error de BD al procesar pedido: {}", pedidoId);
+```
+
+Configurar en `logback.xml` un `PatternLayout` que sanitice campos sensibles
+si el logging de requests completos es necesario para debugging.
+
+---
+
+## Headers de seguridad en Spring Boot
+
+```yaml
+# application.yml — headers mínimos de seguridad
+server:
+  servlet:
+    session:
+      cookie:
+        http-only: true
+        secure: true
+        same-site: strict
+```
+
+Verificar con OWASP ZAP o similar que los headers `Strict-Transport-Security`,
+`X-Content-Type-Options`, `X-Frame-Options` y `Content-Security-Policy` están
+presentes en las respuestas de producción.
+
+---
+
+## Checklist de seguridad Java antes de abrir PR
+
+- [ ] Sin concatenación de strings en queries SQL — solo PreparedStatement o JPA
+- [ ] Inputs validados con @Valid y Bean Validation en todos los endpoints
+- [ ] Sin secretos hardcodeados — variables de entorno en todos los ambientes
+- [ ] Sin ObjectInputStream con datos de usuarios externos
+- [ ] CORS configurado desde variables de entorno, no hardcodeado
+- [ ] OWASP Dependency Check en CI sin CVEs críticos sin suprimir
+- [ ] Logs sin passwords, tokens ni datos personales
+- [ ] Headers de seguridad configurados en Spring Security