---
name: legacy-code-rescue
description: >
  Técnicas para trabajar con código heredado sin tests, siguiendo la metodología
  de Michael Feathers ("Working Effectively with Legacy Code"). Cubre
  identificación de seams, characterization tests para capturar comportamiento
  real (no el deseado), patrones para introducir cambios sin romper
  (sprout method, sprout class, wrap method, wrap class), técnicas para romper
  dependencias problemáticas, y orden de prioridad cuando se hereda código
  sin cobertura. Cargar cuando se herede código sin tests, cuando un módulo
  crítico tenga cobertura <30%, o cuando se planee refactoring de un sistema
  heredado.
version: "1.0.0"
evolved: false
herramientasPermitidas: [Read]
exclusiones:
  - "No cargar para refactoring de código moderno con buena cobertura — si los tests existen y cubren el área a refactorear, basta con `tdd-workflow`. Este skill es específico para código sin red de seguridad."
  - "No cargar para migración entre versiones de framework — usar `deprecacion-migracion`. Este skill cubre rescate de código heredado en general, no actualizaciones de stack."
  - "No cargar para deprecación planificada de features — usar `deprecacion-migracion`. Este skill cubre el problema inverso: código que NO se quiere deprecar pero hay que cambiar con seguridad."
  - "No cargar para optimización de rendimiento de código moderno — los patrones aquí (especialmente characterization tests) priorizan seguridad sobre velocidad. Si la prioridad es perf, usar `performance-baseline` y profilers."
evolvable: true
---

# Legacy Code Rescue

Adaptado de "Working Effectively with Legacy Code" (Michael Feathers, 2004).
Definición operativa de Feathers: **legacy code es código sin tests**, sin
importar su edad o calidad aparente.

## Cuándo cargar

- Se hereda un módulo crítico con cobertura <30% y hay que cambiarlo.
- Se diagnostica un bug en código que nadie ha tocado en meses/años.
- Se planea un refactor de un sistema sin red de seguridad de tests.
- Se necesita agregar una feature en código que actualmente no se puede
  testear de forma aislada.
- Se reciben quejas tipo "tengo miedo de tocar X porque puede romper Y".

## Cuándo NO cargar

- El código tiene cobertura ≥80% y los tests pasan — usar `tdd-workflow`.
- Se está migrando entre versiones de framework — usar `deprecacion-migracion`.
- Se está deprecando una feature intencionalmente — usar `deprecacion-migracion`.
- El objetivo es optimizar rendimiento — los patrones aquí priorizan seguridad
  sobre velocidad; usar `performance-baseline` y profilers.

## Directiva primaria

**Antes de cambiar código heredado, capturar lo que hace**, no lo que se
supone que debe hacer. El comportamiento actual (incluidos sus bugs) es
la fuente de verdad — algún caller probablemente depende de cada peculiaridad.

Orden estricto:
1. **Caracterizar** el comportamiento actual con tests.
2. **Romper dependencias** lo mínimo necesario para que los tests sean posibles.
3. **Cambiar** el código.
4. **Refactorizar** ya con red de seguridad.

NO empezar refactorizando "porque el código está feo". Sin tests, cada cambio
es una apuesta.

---

## Identificar seams (costuras)

Un **seam** es un punto donde el comportamiento del programa puede cambiarse
sin editar el código original. Los seams son la palanca para introducir
tests sin romper nada.

### Tipos de seams

| Tipo | Cuándo aplica | Cómo se activa |
|------|---------------|----------------|
| **Object seam** | OOP con polimorfismo | Inyectar una subclase/mock que herede |
| **Preprocessing seam** | C/C++ con `#define` | Macros o preprocesador |
| **Link seam** | Lenguajes compilados con linker | Sustituir librería en build |
| **Method seam** (Python/JS) | Lenguajes dinámicos | Monkeypatching, importlib |

En Python/TypeScript modernos, el object seam es el predominante:
inyectar dependencias en lugar de instanciarlas dentro del constructor.

### Identificar seams en código existente

Buscar:
- `new SomeClass()` dentro de constructores → object seam latente al refactorizar.
- Llamadas estáticas a clases globales → buscar wrappers o usar dependency injection.
- Imports de módulos con efectos secundarios → candidato a method seam.
- Funciones puras escondidas dentro de métodos largos → extraer es seam barato.

---

## Characterization tests — capturar el comportamiento real

Un **characterization test** documenta lo que el código HACE, no lo que
debería hacer. Son la red de seguridad mínima antes de cualquier cambio.

### Receta

1. Tomar el código y ejecutarlo con un input concreto.
2. Capturar el output exacto (incluido errores, side effects, state final).
3. Escribir un test que assert ese output específico.
4. Repetir con varios inputs representativos: caso típico, edge cases
   conocidos, inputs malformados, valores extremos.
5. Cuando el test pasa, **es la verdad** — incluso si revela un bug.

```python
# Ejemplo: función legacy sin tests
def calcular_descuento(precio, tipo_cliente):
    # ... 80 líneas de if/else, redondeos extraños, edge cases ocultos
    return total

# Characterization test — captura el comportamiento ACTUAL
def test_caracterizacion_descuento():
    # Input típico
    assert calcular_descuento(100, "VIP") == 85.0
    # Edge case observado: tipo_cliente vacío
    assert calcular_descuento(100, "") == 100.0
    # Bug aparente, pero callers pueden depender de él
    assert calcular_descuento(0, "VIP") == 0.0
    # Negativos: el código devuelve negativos sin validar — documentarlo
    assert calcular_descuento(-50, "VIP") == -42.5
```

### Reglas para characterization tests

- **No "arreglar" bugs** mientras se caracteriza — eso viene después.
- Si el comportamiento parece incorrecto, escribir un test que lo
  documente Y abrir un ticket separado para discutir el cambio.
- Apuntar a cubrir los flujos que se van a tocar — no toda la base de
  código.
- Tests rápidos > tests perfectos. Un test feo que corre es mejor que
  uno elegante que no se escribió.

---

## Patrones para cambio seguro

Cuando hay que agregar comportamiento sin tocar código existente.

### Sprout Method

Si necesitas lógica nueva dentro de un método legacy difícil de testear,
**escribe la lógica nueva como método aparte** (con tests propios) y
llámalo desde el método legacy.

```python
# Antes — quieres agregar validación al método legacy
def procesar_orden(orden):
    # 200 líneas legacy intocables
    ...

# Después — la nueva validación vive aparte y SÍ es testeable
def procesar_orden(orden):
    # 200 líneas legacy intocables
    if not _validar_disponibilidad_inventario(orden):  # nuevo
        return ResultadoOrden.fallo("sin stock")
    ...

def _validar_disponibilidad_inventario(orden):
    """Nuevo método con tests propios (no toca el legacy)."""
    return all(item.cantidad <= item.producto.stock for item in orden.items)
```

### Sprout Class

Cuando la lógica nueva es suficientemente grande, va en una **clase nueva**
en lugar de un método. Misma idea: lógica nueva con tests, llamada desde
el legacy.

### Wrap Method

Si necesitas ejecutar algo ANTES o DESPUÉS de un método legacy, renombra
el original a algo interno (`_procesar_orden_original`) y crea uno nuevo
con la firma original que llame al wrap + el original.

```python
def procesar_orden(orden):  # firma pública intacta
    _registrar_intento(orden)         # nueva pre-acción, testeable
    resultado = _procesar_orden_original(orden)
    _registrar_resultado(resultado)   # nueva post-acción, testeable
    return resultado

def _procesar_orden_original(orden):
    # 200 líneas legacy intocables, ahora son privadas
    ...
```

### Wrap Class

Para wrap de un sistema más grande: una clase nueva con la misma interfaz
delega al legacy y agrega comportamiento alrededor (decorator pattern).

---

## Romper dependencias

Algunos legacy methods son intratables por dependencias:
- Conexiones a BD/red en el constructor.
- Singletons globales que se acceden en cualquier parte.
- Llamadas a `time.now()`, `random()`, filesystem.

Técnicas (en orden de invasividad creciente):

1. **Subclass and Override Method**: hereda de la clase legacy, sobreescribe
   el método problemático con un mock para los tests.
2. **Extract Interface / Extract Class**: extrae una interfaz pequeña con
   solo los métodos que el código usa, e inyecta una implementación de prueba.
3. **Parameterize Method/Constructor**: inyecta como parámetro lo que antes
   se obtenía globalmente (clock, random, IO).
4. **Replace Function with Function Pointer / Strategy**: cambiar funciones
   estáticas por callables inyectables.

Aplicar la técnica MENOS invasiva que resuelva el problema. Cuanto más
invasiva, más riesgo de romper algo durante el rescate.

---

## Anti-patrones

- **Refactorizar antes de tener characterization tests**: cualquier cambio
  estructural sin red de seguridad es una apuesta.
- **"Mejorar" el comportamiento mientras se caracteriza**: si parece un
  bug, documéntalo en un ticket y déjalo intacto en el characterization
  test. Cambios funcionales van en commits separados con su propia revisión.
- **Apuntar a 100% de cobertura del módulo entero**: el objetivo es
  cubrir lo que se va a tocar. Cobertura completa puede tomar meses;
  cubrir el slice de cambio toma horas.
- **Borrar código "muerto" sin verificar**: en legacy, algo que parece
  muerto puede ser invocado por reflection o cron. Buscar referencias
  con `grep -r` antes de borrar.
- **Sustituir "todo" con un mock**: si el test pasa solo porque mockeaste
  todas las dependencias, ya no testea nada. Mockear solo lo necesario
  para aislar el código bajo prueba.

---

## Gotchas / Errores comunes no obvios

- **Characterization test "perfecto" que se rompe en CI por orden no determinista**: el código legacy depende del orden de iteración de un dict (Python <3.7) o del timezone del servidor. Causa: comportamiento dependiente de entorno. Solución: capturar la dependencia (forzar timezone UTC en el test, ordenar collections antes de assert) y documentar la dependencia ambiental como bug a discutir.
- **Sprout Method que sí toca el legacy "solo un poquito"**: el desarrollador agrega un `if condicion_nueva` dentro del legacy en lugar de extraer. Causa: parece más simple. Solución: si tocas el legacy, ya no es sprout; o caracterizas primero, o aplicas wrap method que NO modifica el cuerpo original.
- **Inyectar dependencia con un default que llama al global**: `def __init__(self, db=None): self.db = db or get_global_db()`. Causa: querer mantener compatibilidad con callers viejos. Solución: el default escondido invalida la inyección — los tests acaban tocando el global. Aceptar que romper la firma es parte del rescate; agregar wrappers de compatibilidad fuera de la clase si es necesario.
- **Cobertura como métrica engañosa**: 80% de cobertura de líneas pero los asserts solo verifican que "no lanza excepción". Causa: tests escritos para subir el número, no para capturar comportamiento. Solución: cada characterization test debe tener al menos un assert sobre el output o side effect concreto, no solo `assert resultado is not None`.
- **Mock de la BD que devuelve datos perfectos donde el legacy maneja datos sucios**: el código legacy tiene defensas contra datos inconsistentes que el mock no reproduce. Causa: el mock idealiza la realidad. Solución: el mock debe reproducir la sucidad observada en producción (NULLs inesperados, encodings raros, duplicados) — caracterizar la entrada real es parte del rescate.

## Orden de prioridad cuando se hereda código

1. **Estabilizar**: identificar el módulo más crítico, escribir
   characterization tests sobre los flujos que se van a tocar pronto.
2. **Aislar**: romper dependencias problemáticas con seams para que el
   módulo crítico pueda testearse en isolation.
3. **Cubrir**: agregar tests sobre código nuevo (Sprout/Wrap) y sobre
   regresiones detectadas.
4. **Cambiar**: hacer el cambio funcional pedido, ya con red de seguridad.
5. **Refactorizar**: mejorar la estructura ya que está cubierta. NO antes.

NO refactorices código que no piensas tocar. La cobertura no es un fin
en sí mismo — es palanca para cambios futuros.

## Checklist antes de tocar código heredado

- [ ] ¿Existen characterization tests sobre la zona de cambio?
- [ ] Si no: ¿se escribieron antes de cualquier modificación?
- [ ] ¿Las dependencias bloqueantes (DB, red, time, random) están aisladas?
- [ ] ¿El cambio funcional va en un commit separado del refactor estructural?
- [ ] ¿Se documentaron en tickets los bugs detectados durante la caracterización?
- [ ] ¿La cobertura nueva es del slice tocado, no del módulo completo?
- [ ] ¿El sprout/wrap se queda fuera del cuerpo legacy original?
