swl-ses 3.3.2

package/habilidades/react-optimizacion/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: react-optimizacion
+description: Optimización de rendimiento en React. memo, useMemo, useCallback, code splitting, lazy loading, concurrent features, Suspense y patrones de estado eficiente.
+---
+
+# Optimización de Rendimiento en React
+
+## Principio de optimización prematura
+
+**No optimices antes de medir.** La mayoría de los problemas de rendimiento en React
+provienen de re-renders innecesarios o de carga inicial pesada. Primero identifica
+el cuello de botella con React DevTools Profiler, luego aplica la solución correcta.
+
+---
+
+## Re-renders: cuándo ocurren y cómo controlarlos
+
+Un componente se re-renderiza cuando:
+1. Su propio estado cambia (`useState`, `useReducer`).
+2. Su componente padre se re-renderiza (incluso si las props no cambiaron).
+3. Un contexto del que consume cambia.
+
+### React.memo — evitar re-renders por props iguales
+
+```tsx
+import React, { memo } from 'react';
+
+// Memorizar componente que recibe props estables
+const FacturaCard = memo(function FacturaCard({
+  factura,
+  onCancelar,
+}: {
+  factura: Factura;
+  onCancelar: (id: string) => void;
+}) {
+  return (
+    <div className="border rounded-lg p-4">
+      <h3 className="font-semibold">{factura.folio}</h3>
+      <p>{factura.cliente}</p>
+      <button onClick={() => onCancelar(factura.id)}>Cancelar</button>
+    </div>
+  );
+});
+
+// Comparación personalizada cuando la comparación shallow no es suficiente
+const FacturaTable = memo(
+  function FacturaTable({ facturas }: { facturas: Factura[] }) {
+    return <table>...</table>;
+  },
+  (prev, next) => {
+    // true = NO re-renderizar
+    return prev.facturas.length === next.facturas.length &&
+      prev.facturas.every((f, i) => f.id === next.facturas[i].id);
+  }
+);
+```
+
+### useMemo — memorizar cálculos costosos
+
+```tsx
+import { useMemo } from 'react';
+
+function ResumenFacturas({ facturas }: { facturas: Factura[] }) {
+  // Solo recalcular cuando facturas cambia
+  const estadisticas = useMemo(() => ({
+    total: facturas.reduce((sum, f) => sum + f.monto, 0),
+    emitidas: facturas.filter(f => f.estatus === 'emitida').length,
+    canceladas: facturas.filter(f => f.estatus === 'cancelada').length,
+    promedio: facturas.length > 0
+      ? facturas.reduce((sum, f) => sum + f.monto, 0) / facturas.length
+      : 0,
+  }), [facturas]);
+
+  // MAL: calcular en el render sin useMemo (se recalcula en CADA re-render del padre)
+  // const total = facturas.reduce((sum, f) => sum + f.monto, 0);
+
+  return (
+    <div>
+      <p>Total: ${estadisticas.total}</p>
+      <p>Emitidas: {estadisticas.emitidas}</p>
+    </div>
+  );
+}
+```
+
+### useCallback — estabilizar referencias de funciones
+
+```tsx
+import { useCallback } from 'react';
+
+function ListaFacturas() {
+  const [facturas, setFacturas] = useState<Factura[]>([]);
+
+  // Sin useCallback, esta función tiene nueva referencia en cada render
+  // lo que causa que FacturaCard (con memo) se re-renderice de todas formas
+  const handleCancelar = useCallback((id: string) => {
+    setFacturas(prev => prev.map(f =>
+      f.id === id ? { ...f, estatus: 'cancelada' } : f
+    ));
+  }, []); // Sin dependencias porque usa el setter funcional de useState
+
+  const handleActualizar = useCallback((id: string, datos: Partial<Factura>) => {
+    setFacturas(prev => prev.map(f =>
+      f.id === id ? { ...f, ...datos } : f
+    ));
+  }, []);
+
+  return (
+    <div>
+      {facturas.map(factura => (
+        <FacturaCard
+          key={factura.id}
+          factura={factura}
+          onCancelar={handleCancelar}  // Referencia estable → memo funciona
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## Code Splitting y Lazy Loading
+
+### React.lazy + Suspense
+
+```tsx
+import React, { lazy, Suspense } from 'react';
+import { Routes, Route } from 'react-router-dom';
+
+// Lazy imports — cada módulo se convierte en un chunk separado
+const FacturasPage = lazy(() => import('./pages/FacturasPage'));
+const ReportesPage = lazy(() => import('./pages/ReportesPage'));
+const ConfiguracionPage = lazy(() => import('./pages/ConfiguracionPage'));
+
+function App() {
+  return (
+    <Suspense fallback={<PageLoader />}>
+      <Routes>
+        <Route path="/facturas" element={<FacturasPage />} />
+        <Route path="/reportes" element={<ReportesPage />} />
+        <Route path="/configuracion" element={<ConfiguracionPage />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+### Lazy loading de componentes pesados
+
+```tsx
+import { lazy, Suspense, useState } from 'react';
+
+// Cargar gráfica solo cuando el usuario la solicita
+const GraficaVentas = lazy(() => import('./GraficaVentas'));
+
+function Dashboard() {
+  const [mostrarGrafica, setMostrarGrafica] = useState(false);
+
+  return (
+    <div>
+      <button onClick={() => setMostrarGrafica(true)}>
+        Ver gráfica de ventas
+      </button>
+      {mostrarGrafica && (
+        <Suspense fallback={<div className="h-64 animate-pulse bg-gray-100" />}>
+          <GraficaVentas />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
+## Concurrent Features
+
+### useTransition — marcar actualizaciones como no urgentes
+
+```tsx
+import { useTransition, useState } from 'react';
+
+function BuscadorFacturas() {
+  const [query, setQuery] = useState('');
+  const [resultados, setResultados] = useState<Factura[]>([]);
+  const [isPending, startTransition] = useTransition();
+
+  const handleBusqueda = (valor: string) => {
+    // Actualización urgente: el input responde inmediatamente
+    setQuery(valor);
+
+    // Actualización no urgente: los resultados pueden esperar
+    startTransition(() => {
+      const filtrados = buscarFacturas(valor);
+      setResultados(filtrados);
+    });
+  };
+
+  return (
+    <div>
+      <input
+        value={query}
+        onChange={e => handleBusqueda(e.target.value)}
+        placeholder="Buscar facturas..."
+      />
+      {isPending && <span className="text-gray-400">Buscando...</span>}
+      <ListaResultados resultados={resultados} />
+    </div>
+  );
+}
+```
+
+### useDeferredValue — versión diferida de un valor
+
+```tsx
+import { useDeferredValue, memo } from 'react';
+
+function ListaFiltrada({ items }: { items: string[] }) {
+  const [filtro, setFiltro] = useState('');
+  // Versión diferida del filtro — permite que el input sea fluido
+  const filtroDeferred = useDeferredValue(filtro);
+
+  // isStale detecta si estamos mostrando resultado desactualizado
+  const isStale = filtro !== filtroDeferred;
+
+  const itemsFiltrados = useMemo(
+    () => items.filter(item => item.includes(filtroDeferred)),
+    [items, filtroDeferred]
+  );
+
+  return (
+    <div>
+      <input value={filtro} onChange={e => setFiltro(e.target.value)} />
+      <ul style={{ opacity: isStale ? 0.6 : 1 }}>
+        {itemsFiltrados.map(item => <li key={item}>{item}</li>)}
+      </ul>
+    </div>
+  );
+}
+```
+
+---
+
+## Virtualización para listas largas
+
+```tsx
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useRef } from 'react';
+
+function ListaVirtualizada({ facturas }: { facturas: Factura[] }) {
+  const contenedorRef = useRef<HTMLDivElement>(null);
+
+  const virtualizer = useVirtualizer({
+    count: facturas.length,
+    getScrollElement: () => contenedorRef.current,
+    estimateSize: () => 80,  // altura estimada en px por fila
+    overscan: 5,             // filas extra fuera del viewport
+  });
+
+  return (
+    <div ref={contenedorRef} style={{ height: '600px', overflow: 'auto' }}>
+      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
+        {virtualizer.getVirtualItems().map(virtualItem => (
+          <div
+            key={virtualItem.key}
+            style={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              width: '100%',
+              transform: `translateY(${virtualItem.start}px)`,
+            }}
+          >
+            <FacturaCard factura={facturas[virtualItem.index]} />
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Optimización de Context
+
+El contexto causa re-render en TODOS los consumidores cuando cambia.
+Dividir en contextos más pequeños o usar selectores:
+
+```tsx
+// MAL: un solo contexto con todo el estado
+const AppContext = createContext<AppState>({...});
+
+// BIEN: separar por dominio y frecuencia de cambio
+const AuthContext = createContext<AuthState>({...});      // Cambia raramente
+const UIContext = createContext<UIState>({...});          // Cambia frecuentemente
+const FacturasContext = createContext<FacturasState>({...}); // Cambia al interactuar
+
+// BIEN: con useMemo para estabilizar el valor del contexto
+function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [usuario, setUsuario] = useState<Usuario | null>(null);
+
+  const value = useMemo(() => ({
+    usuario,
+    login: async (creds: Credentials) => { ... },
+    logout: () => setUsuario(null),
+  }), [usuario]);  // Solo se crea objeto nuevo cuando usuario cambia
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+```
+
+---
+
+## Cuándo NO usar memo/useMemo/useCallback
+
+Estas optimizaciones tienen un costo: complejidad de código y overhead de comparación.
+No aplicar cuando:
+
+- El componente es simple y rápido de renderizar.
+- Las props cambian en casi todos los re-renders de todas formas.
+- El cálculo en `useMemo` es trivial (suma de 3 números).
+- No hay evidencia medida de problema de rendimiento.
+
+**Regla práctica**: medir primero con React DevTools Profiler. Si un componente
+aparece en llamas largas o con muchos re-renders no esperados, entonces optimizar.

package/habilidades/release-semver/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: release-semver
+description: Versionado semántico (SemVer). Cuándo bumpar major/minor/patch, changelogs convencionales, estrategia de tags y proceso de release completo.
+---
+
+# Versionado Semántico (SemVer)
+
+## Principio fundamental
+
+Un número de versión tiene la forma `MAJOR.MINOR.PATCH` (ej. `2.4.1`). Cada segmento comunica
+intención de compatibilidad a los consumidores del paquete o servicio.
+
+---
+
+## Cuándo bumpar cada segmento
+
+### PATCH — arreglos compatibles hacia atrás
+
+Incrementa PATCH cuando:
+- Se corrige un bug sin cambiar la interfaz pública.
+- Se corrige documentación o typos en código que afectan comportamiento.
+- Se mejoran mensajes de error sin cambiar el tipo de excepción.
+- Se actualizan dependencias de parche (`requests 2.31.0 → 2.31.1`).
+
+```
+1.4.2 → 1.4.3   # fix: corrige cálculo incorrecto en factura
+```
+
+### MINOR — funcionalidad nueva compatible hacia atrás
+
+Incrementa MINOR cuando:
+- Se agrega un endpoint, método o parámetro opcional nuevo.
+- Se agrega una funcionalidad que los consumidores pueden ignorar.
+- Se depreca algo (pero aún funciona).
+- Se actualiza una dependencia minor que agrega capacidades.
+
+```
+1.4.3 → 1.5.0   # feat: agrega exportación a PDF
+```
+
+Al subir MINOR, el PATCH siempre regresa a 0.
+
+### MAJOR — cambios incompatibles hacia atrás (breaking changes)
+
+Incrementa MAJOR cuando:
+- Se elimina un endpoint, método o campo.
+- Se cambia el tipo o contrato de un parámetro existente.
+- Se cambia el comportamiento esperado de forma que rompe integraciones existentes.
+- Se cambia la autenticación/autorización de forma incompatible.
+
+```
+1.5.0 → 2.0.0   # feat!: migra autenticación de JWT a OAuth2
+```
+
+Al subir MAJOR, MINOR y PATCH regresan a 0.
+
+### Versión 0.x.y — desarrollo inicial
+
+Mientras la versión MAJOR sea `0`, la API se considera inestable. Cualquier MINOR puede
+contener breaking changes. Cuando el software está listo para producción, se lanza `1.0.0`.
+
+---
+
+## Commits Convencionales
+
+Los commits convencionales generan el changelog automáticamente y determinan el bump.
+
+### Formato
+
+```
+<tipo>[scope opcional][! para breaking]: <descripción corta>
+
+[cuerpo opcional]
+
+[footer opcional: BREAKING CHANGE: descripción]
+```
+
+### Tipos y su impacto en versión
+
+| Tipo       | Impacto versión | Descripción                                      |
+|------------|----------------|--------------------------------------------------|
+| `fix`      | PATCH           | Corrección de bug                                |
+| `feat`     | MINOR           | Nueva funcionalidad                              |
+| `feat!`    | MAJOR           | Nueva funcionalidad con breaking change          |
+| `fix!`     | MAJOR           | Fix con breaking change                          |
+| `refactor` | ninguno         | Refactorización sin cambio de comportamiento     |
+| `chore`    | ninguno         | Tareas de mantenimiento (CI, deps, config)       |
+| `docs`     | ninguno         | Documentación únicamente                         |
+| `test`     | ninguno         | Agregar o corregir tests                         |
+| `perf`     | PATCH           | Mejora de rendimiento sin cambio de interfaz     |
+| `ci`       | ninguno         | Cambios en pipelines de CI/CD                    |
+| `style`    | ninguno         | Formato, espacios, punto y coma (sin lógica)     |
+
+### Ejemplos de commits bien escritos
+
+```bash
+git commit -m "fix(auth): corrige expiración incorrecta de tokens de refresco"
+git commit -m "feat(reportes): agrega exportación a Excel con formato condicional"
+git commit -m "feat(api)!: cambia paginación de offset a cursor
+
+BREAKING CHANGE: el parámetro 'page' fue reemplazado por 'cursor'.
+Los clientes deben actualizar sus integraciones."
+```
+
+---
+
+## Proceso de release
+
+### Paso 1 — Preparar la rama de release
+
+```bash
+# En main, crear rama release
+git checkout -b release/2.1.0
+
+# Actualizar versión en archivos del proyecto
+# Python: pyproject.toml, __version__
+# Node: package.json
+# Java: pom.xml o build.gradle
+```
+
+### Paso 2 — Generar CHANGELOG
+
+Usar `conventional-changelog` o `git-cliff` para generar el changelog automáticamente:
+
+```bash
+# Con git-cliff (recomendado)
+git cliff --tag v2.1.0 --output CHANGELOG.md
+
+# Con conventional-changelog
+npx conventional-changelog -p conventionalcommits -i CHANGELOG.md -s
+```
+
+Estructura esperada del CHANGELOG:
+
+```markdown
+## [2.1.0] - 2026-03-25
+
+### Nuevas funcionalidades
+- feat(reportes): agrega exportación a Excel (#234)
+- feat(usuarios): agrega campo de foto de perfil (#241)
+
+### Correcciones
+- fix(auth): corrige expiración incorrecta de tokens (#238)
+- fix(factura): redondeo incorrecto en descuentos (#240)
+```
+
+### Paso 3 — Commit de versión y tag
+
+```bash
+# Commit del bump de versión
+git add pyproject.toml CHANGELOG.md
+git commit -m "chore(release): v2.1.0"
+
+# Crear tag anotado (no ligero)
+git tag -a v2.1.0 -m "Release v2.1.0"
+
+# Subir rama y tag
+git push origin release/2.1.0
+git push origin v2.1.0
+```
+
+### Paso 4 — Merge a main y develop
+
+```bash
+git checkout main
+git merge --no-ff release/2.1.0
+git push origin main
+
+git checkout develop
+git merge --no-ff release/2.1.0
+git push origin develop
+
+git branch -d release/2.1.0
+```
+
+---
+
+## Estrategia de tags
+
+### Tags anotados vs. ligeros
+
+Siempre usar **tags anotados** (`git tag -a`) para releases. Los tags ligeros son solo para
+marcado temporal interno. Los tags anotados incluyen autor, fecha y mensaje — esto es esencial
+para `git describe` y herramientas de release.
+
+### Convención de nombres
+
+```
+v{MAJOR}.{MINOR}.{PATCH}           # release estable:    v2.1.0
+v{MAJOR}.{MINOR}.{PATCH}-rc.{N}    # release candidate:  v2.1.0-rc.1
+v{MAJOR}.{MINOR}.{PATCH}-beta.{N}  # beta pública:       v2.1.0-beta.2
+v{MAJOR}.{MINOR}.{PATCH}-alpha.{N} # alpha interna:      v2.1.0-alpha.1
+```
+
+### Listar y filtrar tags
+
+```bash
+git tag --sort=-v:refname         # Lista tags en orden semver descendente
+git tag -l "v2.*"                 # Solo tags de la serie 2.x
+git describe --tags --abbrev=0    # Último tag del commit actual
+```
+
+---
+
+## Herramientas recomendadas
+
+| Herramienta            | Uso                                          |
+|------------------------|----------------------------------------------|
+| `git-cliff`            | Generación de CHANGELOG desde commits        |
+| `commitizen`           | Wizard interactivo para commits convencionales |
+| `semantic-release`     | Release automatizado desde CI                |
+| `bump2version`         | Bump de versión en archivos Python           |
+| `conventional-commits` | Spec oficial de commits convencionales       |
+
+---
+
+## Anti-patrones a evitar
+
+- **Nunca reutilizar un tag**: Si el release `v2.1.0` se publicó, no se puede mover ese tag.
+  Si hay un error, publicar `v2.1.1`.
+- **Nunca usar tags ligeros en releases**: No aportan metadata y dificultan trazabilidad.
+- **Nunca saltarse MAJOR por miedo**: Si hay breaking change, es MAJOR. Ocultarlo como MINOR
+  rompe la confianza de los consumidores.
+- **No mezclar tipos de commit en uno solo**: Un commit = un cambio lógico = un tipo.
+- **No escribir changelogs manuales sin estructura**: Usar el formato estándar para que las
+  herramientas puedan procesarlos.