migrate-to-shoehorn

Visión general de la skill migrate-to-shoehorn

La skill migrate-to-shoehorn te ayuda a refactorizar código de tests en TypeScript para dejar atrás las aserciones frágiles con as y pasar a @total-typescript/shoehorn. Encaja especialmente bien si ya tienes tests llenos de as Type o as unknown as Type, sobre todo cuando las formas de objeto son grandes y el setup acaba siendo ruidoso y engañoso.

Para qué sirve migrate-to-shoehorn

Usa migrate-to-shoehorn cuando tu objetivo real no sea “aprender una librería”, sino limpiar fixtures de test inseguros sin reescribir toda la suite. La skill está centrada en una tarea de refactorización muy concreta:

• sustituir as Type por fromPartial()
• sustituir as unknown as Type por fromAny()
• reducir boilerplate falso en tests con objetos de entrada grandes

Quién debería instalar esta skill

Esta migrate-to-shoehorn skill encaja muy bien si:

• mantienes tests de TypeScript con mucho casting
• quieres fixtures parciales más seguras
• necesitas ayuda para decidir qué patrón de aserción corresponde a cada helper de shoehorn
• quieres que un agente ejecute o guíe una refactorización dirigida en lugar de darte consejos genéricos de TypeScript

Qué importa más antes de adoptarla

El principal punto de decisión es el alcance: esta skill está pensada explícitamente para tests, no para código de producción. Eso importa porque shoehorn resulta útil cuando quieres usar datos incompletos o incluso inválidos para construir casos de prueba, pero aun así quieres un tipado más claro e intencional que el que ofrecen las aserciones en bruto.

Por qué usar migrate-to-shoehorn en lugar de un prompt genérico de refactorización

Un prompt genérico puede eliminar as de forma mecánica y pasar por alto la intención. migrate-to-shoehorn resulta más útil porque está ajustada a los patrones de migración reales con los que suelen encontrarse los equipos:

• entradas parciales de test para tipos de objeto grandes
• datos erróneos de forma intencional en tests negativos
• eliminación de propiedades falsas que no importan para el test

Ese enfoque más acotado suele implicar menos suposiciones y menos reemplazos inseguros.

Cómo usar la skill migrate-to-shoehorn

Contexto de instalación de la skill migrate-to-shoehorn

Para usar la librería subyacente en tu proyecto, instala:

npm i @total-typescript/shoehorn

Si vas a instalar la skill en un entorno compatible con skills, sigue el flujo habitual de instalación de tu plataforma y después invoca migrate-to-shoehorn cuando estés trabajando en refactors de tests.

Lee primero este archivo

Empieza por SKILL.md dentro de la carpeta migrate-to-shoehorn. En este repositorio, esa es la fuente principal de verdad y contiene los patrones de migración que impulsan la skill.

Orden de lectura recomendado:

1. migrate-to-shoehorn/SKILL.md
2. los archivos de test que quieres cambiar
3. los usos locales de as Type y as unknown as Type

Qué entrada necesita la skill

La skill funciona mejor si le proporcionas:

• el fragmento actual del test
• la función o el componente objetivo que se está invocando
• el nombre del tipo relevante, si lo conoces
• si los datos del test deben ser válidos o intencionalmente inválidos
• si quieres un arreglo puntual o un patrón de migración repetible

Sin ese contexto, un agente todavía puede sugerir fromPartial() o fromAny(), pero puede elegir el helper equivocado.

Patrones de migración clave que conviene pedir

Los patrones prácticos de migrate-to-shoehorn usage son sencillos:

• as Type → normalmente fromPartial()
• as unknown as Type → normalmente fromAny()
• objeto falso enorme donde solo importan unos pocos campos → fromPartial()

Ese es el valor central de la skill: convierte peticiones vagas como “limpia estos casts en los tests” en un enfoque de refactorización consistente.

Cómo redactar un buen prompt para migrate-to-shoehorn

Un prompt débil:

Replace as with shoehorn.

Un prompt más sólido:

Use the migrate-to-shoehorn skill to refactor this test file. Replace plain as Request casts with fromPartial() where the object is just a partial fixture. Replace as unknown as Request with fromAny() only where the test intentionally passes invalid data. Keep the test behavior unchanged and add imports if needed.

Esa versión le da al agente intención, límites y una regla de decisión.

Ejemplo: migración de un fixture parcial

Antes:

getUser({ body: { id: "123" } } as Request);

Después:

import { fromPartial } from "@total-typescript/shoehorn";

getUser(fromPartial({ body: { id: "123" } }));

Úsalo cuando el fixture esté incompleto a nivel estructural, pero siga siendo conceptualmente válido para el test.

Ejemplo: migración de datos intencionalmente incorrectos

Antes:

getUser({ body: { id: 123 } } as unknown as Request);

Después:

import { fromAny } from "@total-typescript/shoehorn";

getUser(fromAny({ body: { id: 123 } }));

Úsalo cuando el test pase datos inválidos de forma deliberada para ejercitar validaciones o rutas de fallo.

Mejor flujo de trabajo para refactors grandes con migrate-to-shoehorn

Para una migrate-to-shoehorn guide a nivel de repositorio, no reescribas todo en bloque y a ciegas. Un flujo más seguro sería:

1. busca en los archivos de test as y as unknown as
2. clasifica los casts entre parcial-válido e intencionalmente-inválido
3. migra primero una carpeta de tests
4. ejecuta tests y typecheck
5. estandariza el estilo de imports y la elección de helpers
6. después escala al resto de la suite

Así evitas mezclar casts legítimos de tests negativos con limpiezas normales de fixtures.

Consejos prácticos para mejorar la calidad del resultado

Pídele al agente que conserve estos detalles:

• los nombres y aserciones existentes de los tests
• la intención semántica de los tests con entradas inválidas
• la forma mínima del fixture en lugar de objetos falsos completamente expandidos
• la deduplicación de imports si se usan varios helpers

También conviene indicar claramente si quieres que la skill prefiera el fixture más pequeño posible. Eso suele producir el refactor con shoehorn más limpio.

Cuándo migrate-to-shoehorn no es la herramienta adecuada

No uses migrate-to-shoehorn for Refactoring si tu problema real es la seguridad de tipos en producción, el modelado de dominio o la corrección del contrato de una API. Esta skill no está pensada para “arreglar” tipos en todas partes. Es una ayuda específica para refactorizar tests.

Preguntas frecuentes sobre la skill migrate-to-shoehorn

¿migrate-to-shoehorn es solo para tests?

Sí. Ese es el límite más importante. La skill está diseñada en torno a la ergonomía y la intención de los tests, no a patrones de tipado para producción.

¿Necesito shoehorn si mis tests ya pasan?

No necesariamente. Instala migrate-to-shoehorn si tus tests actuales son difíciles de leer, están llenos de objetos falsos ruidosos o dependen de casts inseguros que ocultan la intención. Si tu setup de tests ya es claro, puede que la migración no compense.

¿Cuál es la diferencia entre fromPartial y fromAny?

fromPartial() encaja con datos de fixture incompletos pero razonables en lo demás.
fromAny() encaja con datos intencionalmente inválidos, cuando el test debe saltarse un tipado más estricto para simular una entrada errónea en tiempo de ejecución.

Esa distinción es una de las razones principales para usar la skill en lugar de un prompt amplio del tipo “elimina aserciones”.

¿migrate-to-shoehorn es apta para principiantes?

Sí, si ya entiendes lo básico de los tests en TypeScript. El alcance de la skill es pequeño y las reglas de migración son fáciles de seguir. El principal riesgo para principiantes es abusar de shoehorn fuera de los tests.

¿Puedo usar esta skill para migrar un repositorio entero?

Sí, pero solo si revisas por categorías. El principal modo de fallo en migraciones grandes es tratar todos los casts como si fueran equivalentes. Algunos son fixtures parciales; otros son payloads rotos de forma intencional; y algunos pueden pertenecer a código de producción y no deberían migrarse con este patrón.

¿Es mejor que usar prompting normal?

Por lo general, sí, cuando la tarea es específicamente “migrar aserciones de tests a shoehorn”. Los prompts normales pueden conocer la librería, pero migrate-to-shoehorn usage funciona mejor cuando buscas una correspondencia consistente entre el estilo de cast anterior y el helper correcto.

Cómo mejorar la skill migrate-to-shoehorn

Dale al agente la intención del test, no solo el código

La manera más rápida de mejorar los resultados de migrate-to-shoehorn es indicar si cada test está comprobando:

• comportamiento happy path con setup parcial
• fallo de validación con entrada intencionalmente incorrecta
• casos límite que solo necesitan unos pocos campos

Ese único dato suele decidir entre fromPartial() y fromAny().

Marca desde el principio qué archivos son solo de test

Si un archivo mezcla helpers y código de producción, dilo explícitamente. La skill es mucho más segura cuando le indicas al agente:

Only apply migrate-to-shoehorn changes inside test files and test fixtures.

Así evitas que el patrón se extienda accidentalmente a rutas que no son de test.

Pide un inventario de casts antes de cambiar nada

En suites desordenadas, empieza con:

Using the migrate-to-shoehorn skill, classify each cast in this file as fromPartial, fromAny, or leave unchanged, then explain why.

Ese paso de revisar antes de reescribir ayuda a detectar casos límite antes del cambio real.

Aporta tipos cercanos cuando la inferencia no sea clara

Si el fragmento por sí solo no muestra el tipo esperado, incluye la firma de la función o la definición de tipo relevante. Un contexto de tipos más sólido conduce a mejores decisiones de imports y a menos reescrituras forzadas.

Vigila estos modos de fallo habituales

Los problemas más comunes durante migrate-to-shoehorn install y su adopción son:

• usar shoehorn en código de producción
• convertir datos intencionalmente inválidos a fromPartial()
• expandir objetos de fixture en vez de simplificarlos
• cambiar el significado del test mientras se “limpian” los tipos

No son problemas de la librería; son problemas de prompting y de revisión.

Itera sobre la primera salida

Después de la primera pasada, pide un segundo refinamiento, por ejemplo:

• minimizar cada fixture para dejar solo los campos necesarios para el test
• consolidar imports
• explicar cualquier cast restante que deba mantenerse
• separar datos parciales válidos de datos de test inválidos

Así conviertes una migración básica en un patrón de testing más limpio y sostenible a largo plazo.