@saulwade/swl-ses 2.3.0 → 2.4.1

package/habilidades/prevencion-sobreingenieria/recursos/soluciones-nativas.md

@@ -0,0 +1,166 @@
+# Soluciones nativas de plataforma
+
+Recurso de `prevencion-sobreingenieria` — peldaño 4 de la escalera de decisión.
+La primera pregunta del ingeniero perezoso-eficiente: *¿la plataforma ya hace
+esto?* Antes de instalar un paquete o escribir un componente, revisar aquí.
+La plataforma viaja gratis con la app, no se rompe en updates, y la escribió
+gente cuyo trabajo es exactamente ese problema.
+
+Adaptado de [ponytail](https://github.com/DietrichGebert/ponytail)
+`docs/platform-native.md` (MIT, DietrichGebert).
+
+---
+
+## Elementos HTML
+
+| Crees que necesitas | La plataforma ya tiene |
+|---|---|
+| Lib de date picker | `<input type="date">` |
+| Lib de time picker | `<input type="time">` |
+| Lib de color picker | `<input type="color">` |
+| Lib de range slider | `<input type="range">` |
+| Componente de progress bar | `<progress value="70" max="100">` |
+| Componente meter/gauge | `<meter value="0.7">` |
+| Lib de modal/diálogo | `<dialog>` + `dialog.showModal()` |
+| Componente acordeón/FAQ | `<details><summary>Título</summary>…</details>` |
+| Lib de tooltips | atributo `title` + CSS `::before`/`::after` |
+| Dropdown con búsqueda | `<input list="id"> <datalist id="id">` |
+| Textarea auto-crecible | `field-sizing: content` (CSS) |
+| Header sticky | `position: sticky; top: 0` (CSS) |
+
+## Capacidades CSS (donde se suele usar JS)
+
+| Crees que necesitas JS para | CSS ya tiene |
+|---|---|
+| Font size responsivo | `font-size: clamp(1rem, 2.5vw, 2rem)` |
+| Espaciado fluido | `padding: clamp(1rem, 5vw, 3rem)` |
+| Dark mode | `@media (prefers-color-scheme: dark)` |
+| Reduced motion | `@media (prefers-reduced-motion: reduce)` |
+| Layout responsivo sin breakpoints | `grid-template-columns: repeat(auto-fill, minmax(250px, 1fr))` |
+| Responsive a nivel componente | `@container` queries |
+| Design tokens / theming global | Custom properties (`--color-primario: #7c3aed`) |
+| Smooth scroll | `scroll-behavior: smooth` |
+| Carrusel con scroll-snap | `scroll-snap-type: x mandatory` + `scroll-snap-align: start` |
+| Aspect ratio | `aspect-ratio: 16 / 9` |
+| Truncar texto con elipsis | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` |
+| Clamp multilínea | `-webkit-line-clamp: 3` |
+| Aislamiento de estilos por capas | `@layer base, components, utilities` |
+| Selectores anidados | CSS nesting nativo (sin preprocesador) |
+| Selector de padre | `:has(input:checked)` |
+
+## JavaScript / APIs del navegador
+
+| Crees que necesitas | La plataforma ya tiene |
+|---|---|
+| `query-string` / `qs` | `new URLSearchParams(location.search)` |
+| `lodash.clonedeep` | `structuredClone(obj)` |
+| `lodash.groupby` | `Object.groupBy(arr, fn)` |
+| `numeral` / `accounting` | `new Intl.NumberFormat("es-MX", { style: "currency", currency: "MXN" })` |
+| `date-fns` format | `new Intl.DateTimeFormat("es-MX", { dateStyle: "long" }).format(fecha)` |
+| Tiempo relativo | `new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-3, "day")` |
+| Plurales i18n | `new Intl.PluralRules("es-MX").select(cantidad)` |
+| `clipboard.js` | `navigator.clipboard.writeText(texto)` |
+| `uuid` (v4) | `crypto.randomUUID()` |
+| Lib de infinite scroll | `new IntersectionObserver(cb).observe(sentinela)` |
+| Lib de resize listener | `new ResizeObserver(cb).observe(elemento)` |
+| Watcher de mutaciones DOM | `new MutationObserver(cb).observe(el, opciones)` |
+| Check de conectividad | `navigator.onLine` + eventos `online`/`offline` |
+| Lib de share sheet | `navigator.share({ title, text, url })` |
+| `store.js` / `localForage` (caso simple) | `localStorage.setItem(clave, JSON.stringify(valor))` |
+| Abortar fetch por timeout | `AbortSignal.timeout(5000)` pasado a `fetch` |
+| Event bus custom | `new EventTarget()` / `dispatchEvent(new CustomEvent("x", { detail }))` |
+
+**Debounce en 3 líneas** (sin dependencia):
+
+```js
+// simplificado: debounce de una sola instancia; lib si se necesitan N independientes
+let t;
+const debounce = (fn, ms) => (...args) => { clearTimeout(t); t = setTimeout(() => fn(...args), ms); };
+```
+
+## Swift / SwiftUI
+
+| Crees que necesitas | La plataforma ya tiene |
+|---|---|
+| Lib de date/time picker | `DatePicker` |
+| Lib de color picker | `ColorPicker` |
+| Search bar + filtrado | `.searchable(text:)` |
+| Lib de pull-to-refresh | `.refreshable { }` |
+| Swipe-to-delete / acciones de fila | `.swipeActions { }` |
+| Carga async de imágenes + caché | `AsyncImage` |
+| Lib de gráficas | Swift Charts (`import Charts`) |
+| Render de Markdown | `Text(...)` markdown / `AttributedString(markdown:)` |
+| Share sheet | `ShareLink` |
+| Spinner de carga | `ProgressView()` |
+| Photo picker | `PhotosPicker` |
+| JSON (SwiftyJSON) | `Codable` + `JSONDecoder`/`JSONEncoder` |
+| HTTP simple (Alamofire) | `URLSession` async/await |
+| Crypto (CryptoSwift) | `CryptoKit` |
+| Persistencia / ORM | `SwiftData`, o `@AppStorage` para key-values |
+| Logging | `Logger` (`os.log`) |
+
+## Stdlib de Node.js
+
+| Crees que necesitas | Node ya tiene |
+|---|---|
+| `mkdirp` / `make-dir` | `fs.mkdirSync(ruta, { recursive: true })` |
+| `rimraf` | `fs.rmSync(ruta, { recursive: true, force: true })` |
+| `uuid` (v4) | `crypto.randomUUID()` |
+| `object-assign` | `Object.assign()` / spread |
+| `array-uniq` | `[...new Set(arr)]` |
+| `array-flatten` / `flat` | `arr.flat(profundidad)` |
+| `path-exists` | `fs.existsSync(ruta)` |
+| `load-json-file` | `JSON.parse(fs.readFileSync(ruta, "utf8"))` |
+| `write-json-file` | `fs.writeFileSync(ruta, JSON.stringify(obj, null, 2))` |
+| `pkg-dir` | `path.resolve(__dirname, "..")` / `import.meta.dirname` |
+
+## Stdlib de Python
+
+| Crees que necesitas | Python ya tiene |
+|---|---|
+| `python-dateutil` (parsing básico) | `datetime.fromisoformat()` (3.7+) |
+| `pytz` | `zoneinfo.ZoneInfo("America/Mexico_City")` (3.9+) |
+| `attrs` (data classes simples) | `@dataclass` |
+| `pathlib2` | `pathlib.Path` (3.4+) |
+| `simplejson` (uso básico) | `json` (stdlib) |
+| `requests` (GET simple) | `urllib.request.urlopen(url)`; `requests` para algo real |
+| `click` (comando único) | `argparse` (stdlib) |
+| `mergedeep` | `dict \| otro_dict` (3.9+) |
+| `more-itertools` (básico) | `itertools`: `chain`, `islice`, `groupby`, `product` |
+| `toolz` (básico) | `functools`: `lru_cache`, `partial`, `reduce` |
+
+## Base de datos
+
+| Crees que necesitas código de app para | La BD ya tiene |
+|---|---|
+| Paginación | `LIMIT 20 OFFSET 40` |
+| Totales acumulados | `SUM(...) OVER (ORDER BY fecha)` (window function) |
+| Rank por grupo | `RANK() OVER (PARTITION BY categoria ORDER BY score DESC)` |
+| Deduplicación | `SELECT DISTINCT` / `ON CONFLICT DO NOTHING` |
+| Recorrido de árboles | CTE recursivo (`WITH RECURSIVE`) |
+| Full-text search (básico) | `tsvector` / `MATCH AGAINST` / `FTS5` |
+| Almacenar + consultar JSON | `jsonb` (Postgres) / `JSON_EXTRACT` (SQLite/MySQL) |
+| Generación de UUID | `gen_random_uuid()` (Postgres) / `UUID()` (MySQL) |
+| Timestamps de insert/update | `DEFAULT now()` + trigger / `ON UPDATE CURRENT_TIMESTAMP` |
+| Unicidad | constraint `UNIQUE`, no checks en la app |
+| Integridad referencial | `FOREIGN KEY`, no checks en la app |
+| Rangos de valores | `CHECK (precio > 0)`, no validación en la app |
+
+---
+
+## El patrón
+
+En todas las capas es el mismo ciclo:
+
+```
+El equipo de la plataforma pasa años resolviendo el problema.
+Alguien lo envuelve en un paquete.
+Instalas el wrapper.
+El wrapper queda sin mantenimiento.
+Terminas debugueando el wrapper.
+```
+
+Sáltate el wrapper. Cuando la solución nativa es genuinamente insuficiente
+(soporte de navegadores viejos, edge cases que no cubre, ergonomía que importa
+a escala), la librería se gana su lugar — instálala entonces, no antes
+(y verifica su vigencia con Context7, regla `usar-context7.md`).

package/habilidades/prevencion-sobreingenieria/recursos/variables-residuales-post-refactor.md

@@ -0,0 +1,85 @@
+# Variables residuales post-refactor son code smell
+
+Recurso de `prevencion-sobreingenieria`. Extraído del SKILL.md en v1.3.0 para
+respetar el límite de 300 líneas; el contenido es normativo sin cambios.
+
+## Regla
+
+Variables asignadas pero no usadas (F841 en ruff/flake8) **post-refactor** son
+casi siempre residuos de una versión anterior del código que el refactor no
+limpió. Se parecen a "variables temporales del desarrollador" pero delatan un
+refactor incompleto — la lógica que las usaba se movió o eliminó, pero las
+asignaciones quedaron.
+
+## Por qué son peligrosas
+
+- **Confunden al próximo lector**: asumirá que la variable se usa más abajo.
+- **Inflan el diff cognitivo** del refactor real.
+- **Ocultan bugs sutiles**: el valor asignado puede tener side effects (llamada
+  a función costosa o con efecto en estado) que ya no aporta nada al flujo.
+- **Invalidan la métrica de cobertura**: líneas "cubiertas" por tests que en
+  realidad no afectan el resultado.
+
+## Patrón operativo
+
+Después de **cualquier refactor** que modifique el flujo de una función (extraer
+método, inlinear función, cambiar el shape de un return), correr:
+
+```bash
+ruff check --select=F841 ruta/al/modulo.py
+# o para todo el proyecto
+ruff check --select=F841 .
+```
+
+Cada F841 detectado post-refactor es candidato 1 de 2:
+
+1. **Variable muerta** (caso común post-refactor): eliminarla.
+2. **Variable viva pero mal nombrada** (caso raro): si el valor se usa como
+   side effect intencional (ej: evaluar una propiedad para cachear), renombrar
+   con prefijo `_` y comentar el propósito.
+
+## Anti-patrón típico
+
+```python
+# Antes del refactor: había un if que usaba exito_key
+def procesar(data):
+    exito, exito_key = intentar(data)
+    if exito_key == "via_rapida":
+        return procesar_rapido(data)
+    return procesar_normal(data, exito_key)
+
+
+# Después de refactor que eliminó la rama "via_rapida"
+def procesar(data):
+    exito, exito_key = intentar(data)   # ← F841: exito_key asignado, no usado
+    return procesar_normal(data)         # ← también exito residual
+```
+
+## Patrón canónico
+
+```python
+# Post-refactor limpio
+def procesar(data):
+    _ = intentar(data)   # si el side effect de intentar() importa
+    return procesar_normal(data)
+
+# o mejor: si ni siquiera el side effect importa
+def procesar(data):
+    return procesar_normal(data)
+```
+
+## Reglas
+
+- **Gate pre-commit**: agregar `ruff check --select=F841` al pre-commit hook del proyecto. No bloquea en un repo grande donde F841 preexiste, pero sí bloquea en los archivos modificados por el commit actual.
+- **Revisión explícita post-refactor grande**: tras extraer 5+ métodos o mover 5+ bloques, correr `ruff --select=F401,F841` sobre los archivos tocados.
+- **NO silenciar con `# noqa: F841` sin justificación** — la excepción legítima (side effect intencional con nombre `_`) es tan rara que vale la pena documentarla; silenciar sin comentario es ocultar deuda.
+- **Incluir en checklist de PR**: "F841 limpio en archivos tocados" como item explícito.
+
+## Aplicabilidad
+
+Detectable en:
+
+- Python: `ruff --select=F841`, `flake8 --select=F841`.
+- TypeScript/JavaScript: `eslint --rule 'no-unused-vars: error'`.
+- Go: el compilador lo hace obligatorio (`declared but not used`).
+- Rust: warning `unused_variables`, promovido a error con `#![deny(unused_variables)]`.