@saulwade/swl-ses 1.3.7 → 1.4.0

package/habilidades/react-experto/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: react-experto
 description: React + Next.js mejores prácticas modernas. Cubre Server Components vs Client Components, data fetching patterns (RSC, React Query, SWR, Server Actions), state management (useState, Zustand, Jotai), performance (memo, lazy, Suspense, streaming) y Next.js App Router patterns.
-version: "1.1.1"
+version: "1.2.0"
 evolved: true
-evolved-from: "1.1.0"
-evolved-at: "2026-05-11"
+evolved-from: "1.1.1"
+evolved-at: "2026-05-12"
 evolved-by: "aprender"
-evolved-note: "L-105 SIGM: setState dentro de useEffect bloqueado por react-hooks/set-state-in-effect (eslint-plugin-react-hooks v7+) - 3 patrones de reemplazo (lazy init, useMemo, useSyncExternalStore) confirmados x3 en F1.2/F1.3/F3"
+evolved-note: "Backport L-138 SIGM: Sidebar/menu con RBAC debe ocultar secciones cuyos items quedan todos filtrados; previo L-105 setState in useEffect"
 herramientasPermitidas: [Read]
 exclusiones:
   - "No cargar para optimización de rendimiento React (memo, useMemo, useCallback, virtualización, code splitting) — para rendimiento cargar `react-optimizacion`."
@@ -158,6 +158,47 @@ useEffect(() => {
 const filtrados = useMemo(() => usuarios.filter(u => u.activo), [usuarios]);
 ```
 
+### Sidebar/menu con RBAC: ocultar secciones cuyos items quedan todos filtrados
+
+**Problema** (L-138 SIGM 2026-05-12): un sidebar con secciones colapsables filtra items por permiso del usuario. Si un usuario sin el permiso requerido ve la sección con su header y chevron pero al expandirla aparece un `<ul>` vacío, el bug confunde — el usuario reporta "el menú no despliega nada", sin saber si es bug del sistema o falta data. Caso SIGM: sección "Ventanilla" tenía 1 item con permiso `CAJA:cobrar`; cuando ningún usuario tenía ese string literal (era `RECAUDACION:CAJA:cobrar`), todos los usuarios veían la sección vacía.
+
+```tsx
+// MAL — header se renderiza aunque el <ul> quede vacío
+{NAV_SECTIONS.map((section) => (
+  <Section key={section.title}>
+    <SectionHeader title={section.title} />
+    <ul>
+      {section.items
+        .filter((item) => !item.permiso || tienePermiso(item.permiso))
+        .map((item) => <NavItem key={item.href} {...item} />)}
+    </ul>
+  </Section>
+))}
+```
+
+```tsx
+// BIEN — filtrar items ANTES de decidir si renderizar la sección
+{NAV_SECTIONS.map((section) => {
+  const itemsVisibles = section.items.filter(
+    (item) => !item.permiso || tienePermiso(item.permiso),
+  )
+  if (itemsVisibles.length === 0) return null  // ← omitir sección entera
+
+  return (
+    <Section key={section.title}>
+      <SectionHeader title={section.title} />
+      <ul>
+        {itemsVisibles.map((item) => <NavItem key={item.href} {...item} />)}
+      </ul>
+    </Section>
+  )
+})}
+```
+
+**Aplica también a**: tabs, breadcrumbs, dropdowns de filtros, paneles de configuración con secciones por permiso. Patrón: cualquier UI que agrupa items en secciones donde los items pueden filtrarse por RBAC.
+
+**Test obligatorio**: cuando el mock de `useAuth` NO incluye los permisos de una sección, esa sección NO debe renderizarse en el DOM (`expect(queryByText('NombreSección')).not.toBeInTheDocument()`).
+
 ```tsx
 // MAL: fetch en Client Component cuando podria ser RSC
 useEffect(() => {

package/habilidades/release-semver/.evolved.json

@@ -1,9 +1,9 @@
-{
-  "SKILL.md": {
-    "evolved": true,
-    "evolvedFrom": "1.0.1",
-    "evolvedAt": "2026-05-02",
-    "evolvedBy": "aprender",
-    "evolvedNote": "Sección nueva: publish a múltiples registries (republish-only + auth GitHub Packages)"
-  }
+{
+  "SKILL.md": {
+    "evolved": true,
+    "evolvedFrom": "1.0.1",
+    "evolvedAt": "2026-05-02",
+    "evolvedBy": "aprender",
+    "evolvedNote": "Sección nueva: publish a múltiples registries (republish-only + auth GitHub Packages)"
+  }
 }

package/habilidades/swl-claudemd/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: swl-claudemd
 description: Conocimiento operacional para auditar y mantener archivos CLAUDE.md — contrato canónico de secciones (best practices Anthropic, ADR-0016), umbrales de bloat (líneas totales, bullets gigantes, placeholders, @references rotas), reglas de extracción a archivos referenciados con @, y plantillas de inicialización (init-user para ~/.claude/CLAUDE.md, init-project para CLAUDE.md raíz detectando stack). Provee las reglas; el comando /swl:claudemd ejecuta el flujo. Cargar desde ese comando o cuando el hook claudemd-bloat-detector sugiera intervención.
-version: "1.0.1"
+version: "1.0.2"
 herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
 exclusiones:
   - "No cargar para editar reglas globales en ~/.claude/rules/ — usar Edit directo."
@@ -205,6 +205,20 @@ Genera `./CLAUDE.md` raíz del proyecto detectando stack actual.
   pueden NO tener todas las secciones canónicas (porque heredan del root).
   Por ahora el auditor aplica el contrato uniforme; si el ADR-0007 se
   acepta, el auditor debe distinguir root vs subdirectorio.
+- **Codificar el patrón legacy/malo como ejemplo "correcto" en una regla
+  de CLAUDE.md codifica el bug**: una regla cuya prosa enseña el patrón
+  correcto pero cuyo *ejemplo* muestra el patrón malo se auto-perpetúa.
+  Cada release nuevo copia el ejemplo y replica el problema. Caso real:
+  CLAUDE.md v1.3.5 línea 59 decía *"todo mensaje del installer/docs usa
+  `npx swl-ses@latest <comando>`"* — pero `npx swl-ses@latest` sin scope
+  resuelve al paquete legacy DEPRECATED tras el rebrand 2026-04-30. La
+  regla acumuló 152 ocurrencias del patrón malo en 8 releases consecutivos
+  hasta v1.3.6. Solución: las reglas DEBEN mostrar el patrón correcto en
+  el ejemplo. Si la regla tiene que citar un patrón malo (para
+  prohibirlo), envolverlo en bloque "NUNCA" explícito separado del
+  ejemplo de uso correcto. Pregunta de auditoría: *si un autor de release
+  futuro copia el ejemplo de esta regla literalmente, ¿produce código
+  correcto?* Si no, la regla está mal escrita.
 
 ## Señales de alerta
 

package/habilidades/tdd-workflow/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: tdd-workflow
 description: Flujo completo de Test-Driven Development. Ciclo RED (el test falla) → GREEN (implementación mínima) → REFACTOR (limpieza). Incluye cobertura mínima obligatoria, tests de frontera, factories, fixtures y estrategias para diferentes tipos de código (APIs, services, componentes Angular).
-version: "1.0.1"
+version: "1.0.2"
 evolved: true
-evolved-from: "1.0.0"
-evolved-at: "2026-05-11"
+evolved-from: "1.0.1"
+evolved-at: "2026-05-14"
 evolved-by: "aprender"
-evolved-note: "L-109 SIGM: nombrar tests por causa raíz (no por feature) — test_repository_no_usa_columna_inexistente_p_monto detectó bug en F1.4 sin necesidad de reproducción manual"
+evolved-note: "Patrón reloj inyectable (parámetro `ahora` con default Date.now()) para tests deterministas sin freezegun/jest.useFakeTimers — validado en 3 módulos sesión webhook Opción C"
 herramientasPermitidas: [Read, Bash]
 evolvable: true  # default para skill estandar
 exclusiones:
@@ -297,4 +297,36 @@ pytest --cov=src/services --cov-fail-under=90
 
 **`db_session.rollback()` en el fixture de pytest-asyncio no deshace los datos insertados por `db.flush()` dentro de la función testeada cuando la sesión usa `autocommit=True` implícito por configuración del engine**: algunos proyectos configuran `AsyncEngine` con `isolation_level="AUTOCOMMIT"` para compatibilidad con operaciones DDL; en ese contexto, cada `flush()` hace commit inmediatamente y el `rollback()` del fixture no puede deshacer esos cambios. Causa: `AUTOCOMMIT` en PostgreSQL significa que no hay transacción activa que se pueda revertir. Fix: verificar que el engine de tests NO use `isolation_level="AUTOCOMMIT"` (la configuración debe ser solo para el engine de migraciones Alembic, no para el de la app). Para tests que necesitan AUTOCOMMIT por alguna razón, usar una BD de test separada que se trunca con `TRUNCATE ... RESTART IDENTITY CASCADE` en el teardown del fixture.
 
+**Reloj inyectable como parámetro `ahora` habilita tests deterministas sin `freezegun`, `jest.useFakeTimers()` ni `sinon.useFakeTimers()`** [PATRÓN VALIDADO en SWL Opción C webhook]: cuando una API depende del tiempo (rate-limit con bucket que se rellena, dedup con ventana de retención, cache con TTL, schedulers), recibir el timestamp por parámetro en lugar de llamar `Date.now()` internamente permite que los tests pasen 1000 segundos en 0 ms reales. Diseño: `metodo(arg1, arg2, ahora = Date.now())` — producción no cambia (llamadas siguen siendo `obj.consumir(1)`), tests pasan `ahora` explícito (`obj.consumir(1, T0 + 5000)`). Validado en 3 módulos esta sesión: `rate-limit-ip.js` (40+ tests bucket refill, capacidad, cleanup), `webhook-dedup.js` (ventana de retención, rotación idempotente), helpers internos de `webhook-server.js`. Ningún test usa `sleep`, ningún test es flaky, ningún test mockea `Date`. Aplicable a JS/TS y a Python (`def consumir(self, tokens, ahora=None)` con `ahora = ahora or datetime.now(UTC)` al inicio).
+
+```js
+// MAL — test no-determinista, requiere sleep o mock global
+class Bucket {
+  consumir(n) {
+    const ahora = Date.now();  // ← imposible de controlar desde el test
+    this._rellenar(ahora);
+    if (this.tokens >= n) { this.tokens -= n; return true; }
+    return false;
+  }
+}
+
+// BIEN — reloj inyectable, test determinista
+class Bucket {
+  consumir(n, ahora = Date.now()) {  // ← default en producción, inyectable en test
+    this._rellenar(ahora);
+    if (this.tokens >= n) { this.tokens -= n; return true; }
+    return false;
+  }
+}
+
+// En el test:
+const T0 = 1700000000000;
+const b = new Bucket(10, 1, T0);
+for (let i = 0; i < 10; i++) b.consumir(1, T0);   // saturar
+assert.equal(b.consumir(1, T0), false);            // sin refill aún
+assert.equal(b.consumir(5, T0 + 5000), true);      // 5 seg después: 5 tokens
+```
+
+Aplica también a tests de clock skew (tiempo retrocede por NTP): pasar `T0 - 1000` y validar que la lógica no rompe. Origen: rate-limit-ip.js + webhook-dedup.js sesión 2026-05-13.
+
 **Tests nombrados por feature (`test_emitir_factura_exitosa`) pierden poder regresivo; nombrados por causa raíz (`test_repository_no_usa_columna_inexistente_p_monto`) detectan regresiones específicas sin reproducción manual** [CONFIRMADO en SIGM Opción C F1.4]: cuando se descubre un bug por una causa raíz concreta (typo en nombre de columna SQL, omisión de `selectinload`, mock que devuelve dict en vez de objeto, schema obsoleto), el test de regresión que se escribe debe llevar el nombre de la causa, no del feature afectado. Caso real: durante F1.4 de SIGM, el repository de pagos referenciaba `p.monto` cuando la columna se llamaba `p.monto_pagado`; el test escrito como `test_repository_no_usa_columna_inexistente_p_monto` falló inmediatamente en la siguiente sesión cuando otro agente reintrodujo el typo, sin necesidad de reproducir el escenario de negocio (emitir cobro real, verificar respuesta). Causa: los nombres orientados a feature (`test_pago_exitoso`) son ambiguos sobre QUÉ falla — si el test falla, el desarrollador debe diagnosticar; los nombres orientados a causa raíz (`test_X_no_usa_Y`, `test_query_incluye_selectinload_Z`, `test_service_devuelve_dict_no_objeto`) son auto-diagnósticos. Fix: para cada bug que cueste >30 min diagnosticar, escribir UN test adicional cuyo nombre describa la condición técnica violada, no el escenario de negocio. Convención: `test_<componente>_<condicion_tecnica>` o `test_<componente>_no_<anti_patron>`. Estos tests son tu segunda línea de defensa contra regresiones de la misma causa raíz, complementarios a los tests de comportamiento.