Receta: Auditoría del Stack

Una auditoría de stack responde tres preguntas: ¿Está saludable nuestro grafo de dependencias? ¿Estamos acumulando deuda técnica? ¿Qué debemos actualizar a continuación y en qué orden?

Esta receta usa las herramientas del Stream H de SpecForge para ejecutar una auditoría completa de salud del stack y construir un plan de actualización accionable.

---

Paso 1 — Ejecutar la Auditoría Completa del Stack

Prompt:

Audit the stack for project proj_abc123

Qué esperar:

Stack Health Score: 71/100

Dependency Status:
  up_to_date:    34 packages  ✅
  outdated:      12 packages  ⚠️
  vulnerable:     3 packages  🚨
  unmaintained:   1 package   ❌

Critical (fix immediately):
  - lodash 4.17.20 → CVE-2021-23337 (Prototype pollution)
  - axios 0.21.1 → CVE-2023-45857 (CSRF vulnerability)
  - follow-redirects 1.14.7 → CVE-2023-26159

High Priority (next sprint):
  - typescript 4.9.5 → 5.7.2 (13 minor versions behind)
  - vitest 0.34.0 → 3.1.0 (major version behind)
  - express 4.18.0 → 5.0.1 (major version available)

Medium Priority (this quarter):
  - 8 packages 1–3 minor versions behind

---

Paso 2 — Detectar APIs Deprecadas

Prompt:

Detect deprecated APIs in project proj_abc123

Esto escanea los archivos fuente (sin red requerida) en busca de uso de APIs deprecadas:

Deprecated API Usage Found:

src/middleware/session.ts:14
  express-session secret as string — deprecated, use array of secrets
  Effort to fix: 0.5h

src/utils/crypto.ts:8
  crypto.createCipher — deprecated since Node 10, use createCipheriv
  Security risk: HIGH
  Effort to fix: 2h

src/config/database.ts:22
  mongoose.connect callback — deprecated in Mongoose 7, use promise
  Effort to fix: 1h

Total tech debt: ~3.5h

---

Paso 3 — Planear Actualizaciones Prioritarias

Para cada item crítico o de alta prioridad, genera un plan de actualización:

Prompt:

Plan the upgrade from axios 0.21.1 to the latest stable for project proj_abc123

Qué esperar:

## Plan de Actualización de Axios: 0.21.1 → 1.7.9

### Breaking Changes
- AbortController reemplaza a CancelToken (deprecado en v0.22)
- Content-Type por defecto para POST cambió a application/json (sin cambio requerido)
- Tipos de respuesta cambiaron en definiciones TypeScript

### Pasos de Migración
1. Actualizar package.json: axios ^1.7.9
2. Reemplazar todo uso de CancelToken:
   - Buscar: axios.CancelToken.source()
   - Reemplazar: AbortController / AbortSignal
3. Actualizar tipos TypeScript (genérico AxiosResponse cambió)
4. Ejecutar suite de tests — los interceptores de axios son retrocompatibles

### Archivos afectados (5):
- src/api/client.ts (uso de CancelToken en líneas 34, 67)
- src/api/interceptors.ts (token cancel en línea 89)
- src/utils/request.ts (manejo de timeout)
- tests/api/client.test.ts (actualizaciones de mocks necesarias)
- tests/api/interceptors.test.ts (actualizaciones de mocks necesarias)

### Esfuerzo estimado: 3h
### Rollback: pin a 0.27.2 (último estable 0.x)

---

Paso 4 — Crear Specs para Actualizaciones Mayores

Para actualizaciones de versión major que afectan múltiples archivos, crea una spec apropiada:

Prompt:

Create a spec for upgrading Express from 4.18 to 5.0 in project proj_abc123

Esto te da:

• Criterios de aceptación para la actualización (todos los endpoints siguen funcionando, sin breaking behavior)
• Un plan de migración
• Requisitos de cobertura de tests (comparación antes + después)

---

Paso 5 — Verificación de Gobernanza de Datos

Si el proyecto maneja datos de usuario:

Prompt:

Run a data governance check for project proj_abc123

Qué esperar:

PII Detection:
  spec SPEC-003 (user registration): email, name, phone — needs retention policy
  spec SPEC-007 (analytics): IP address stored — GDPR legitimate interest required

GDPR Compliance:
  ✅ Data minimization — specs collect minimal PII
  ⚠️  Retention policy missing for user.email (SPEC-003)
  ⚠️  Right to erasure not specified in any spec
  ❌  No privacy notice spec exists

Recommendations:
  1. Create spec for GDPR compliance (right to erasure, data export)
  2. Add retention policy to SPEC-003
  3. Generate privacy notice template

---

Paso 6 — Priorizar el Backlog de Remediación

Prompt:

Create specs for the top 3 security vulnerabilities found in the stack audit for project proj_abc123

SpecForge crea specs para cada corrección de CVE, correctamente acotadas con criterios de aceptación.

---

Paso 7 — Hacer Seguimiento del Progreso

Programa auditorías regulares y rastrea el StackHealthScore a lo largo del tiempo:

Prompt:

Audit the stack for project proj_abc123

Objetivo: StackHealthScore ≥ 85, cero paquetes vulnerable o unmaintained.

---

Cadencia de Auditoría Recomendada

Disparador	Acción
Mensual	audit_stack — escaneo completo de dependencias
Trimestral	detect_deprecations — escaneo de código fuente
Pre-release	audit_stack + security_check en specs de pago/auth
Post-incidente	capture_learning + actualizar specs afectadas
Major Node.js LTS	detect_deprecations + plan_upgrade para paquetes afectados

---

Hallazgos Comunes y Correcciones

Hallazgo	Herramienta	Tiempo típico de corrección
CVE en dependencia directa	plan_upgrade	1–4h
CVE en dependencia transitiva	plan_upgrade + override manual	2–8h
API deprecada en código fuente	detect_deprecations	0.5–3h por archivo
Paquete sin mantenimiento	Reemplazar con fork mantenido	4–16h
Major version desactualizada	plan_upgrade	2–12h