English

¿Refactor grande? Escribe un codemod, no ediciones a mano

Cuando un refactor toca cientos de líneas, deja de editar a mano. Las ediciones manuales a esa escala son propensas a errores y agotadoras de revisar: vas a omitir casos, y tus revisores no pueden confiar en un diff de 500 líneas de "el mismo cambio, probablemente, en todas partes". Escribe la transformación en su lugar — un codemod, un script sed o una reescritura de AST — y el cambio se vuelve mecánico, uniforme y revisable.

Por qué las ediciones a mano fallan a escala

Un refactor como "renombra esta API", "cambia este import" o "modifica la firma de esta llamada" es una decisión aplicada N veces. Cuando N es 5, tu editor alcanza. Cuando N es 500:

• Omites casos. Grep encuentra los obvios; los concatenados como string, con alias o re-exportados se escapan.
• Introduces variación. Edita 500 sitios a mano y algunos quedarán sutilmente distintos: un argumento perdido aquí, una indentación incorrecta allá.
• La revisión se vuelve teatro. Ningún revisor lee de verdad 500 hunks casi idénticos. Los hojea, aprueba, y el único hunk equivocado llega a producción.

Una transformación con script invierte los tres puntos: la cobertura es lo que tu patrón matchea, cada cambio es idéntico por construcción, y el revisor lee la transformación de ~20 líneas, no la salida de 500.

Elige la herramienta más liviana que siga siendo correcta

Regla práctica: escala solo cuando la herramienta más simple pueda producir un falso match. Texto → patrón estructural → programa completo sobre el AST.

Cómo se ve

Una línea consciente de la sintaxis con ast-grep — reescribir declaraciones var a let en un repo TypeScript:

ast-grep --pattern 'var code = $PATTERN' \
         --rewrite 'let code = new $PATTERN' \
         --lang ts

Cuando necesitas lógica, una transformación de jscodeshift es una función JS pequeña; córrela primero en seco:

jscodeshift -t rename-api.js src/ --dry --print   # preview
jscodeshift -t rename-api.js src/                 # apply

En ambos casos, el artefacto que commiteas junto al diff es la transformación. Eso es lo que se revisa.

La recompensa en la revisión

Entrega el refactor como dos cosas: el script, y un commit que es puramente su salida. El revisor verifica la regla una vez, hace spot-checks de algunas aplicaciones y confía en el resto — porque una máquina aplicó una regla de manera uniforme. Es una garantía fundamentalmente más fuerte que 500 pulsaciones cuidadosas, y se puede re-ejecutar cuando la rama queda desactualizada: rebase, re-ejecuta el codemod, listo.

Trucos avanzados

• Separa lo mecánico de lo manual. Si 480 sitios son mecánicos y 20 requieren criterio, corre el codemod para los 480 en un commit y edita a mano los 20 en un segundo commit. Los revisores reciben un diff trivialmente verificable y otro pequeño y real.
• Dry-run como revisión. jscodeshift --dry --print y el modo interactivo de ast-grep te dejan inspeccionar los matches antes de tocar el disco — trata la lista de matches como el test de tu patrón.
• Deja que la IA escriba el codemod, no las ediciones. Pedirle a un agente de código que edite 500 líneas a mano multiplica sus oportunidades de alucinar una variante. Pedirle una transformación de 20 líneas te da un artefacto pequeño que sí puedes verificar — y luego tú lo ejecutas.
• Guarda el script en el repo. Bajo scripts/codemods/, las transformaciones se vuelven documentación de cómo evolucionó el código y plantillas para la próxima migración.

Recursos

• jscodeshift — toolkit de codemods para JavaScript/TypeScript
• ast-grep — búsqueda y reescritura estructural desde la CLI
• Tutorial de codemods de LibCST — transformaciones en Python que preservan el formato
• OpenRewrite — refactorización a gran escala basada en recetas
• Comby — búsqueda y reemplazo estructural liviano en más de 50 lenguajes

Read this article in English