Renombraste un archivo y el CI se rompió: rutas rotas

En pocas palabras: Cuando renombrás un archivo, las rutas en package.json, Dockerfile COPY y workflows de GitHub Actions quedan como strings sin chequear. PathMend, extensión gratuita de VS Code con licencia MIT, las subraya con reglas PM001 a PM011 antes del push y ofrece actualizarlas.

Al mover un archivo, los imports se actualizan pero las rutas en package.json, Dockerfile, workflows de GitHub Actions y CODEOWNERS quedan igual, y las rutas rotas en CI aparecen recién en el build. PathMend, extensión gratuita de VS Code, las marca antes del push.

PathMend es una extensión gratuita y open source (licencia MIT) de VS Code, publicada por jaytankdev, que revisa las rutas escritas en archivos de configuración: package.json, tsconfig, Dockerfiles, Compose, GitHub Actions, .gitlab-ci.yml, CODEOWNERS y launch.json. Subraya el string exacto cuando el archivo no existe, con reglas de la PM001 a la PM011. Sirve para detectar el problema antes que docker build, npm publish o el pipeline.

¿Por qué VS Code no actualiza las rutas del Dockerfile cuando renombro un archivo?

Porque las herramientas de refactor trabajan sobre el código: siguen imports y referencias. Según el artículo del autor de PathMend, publicado el 16 de octubre de 2026, las rutas en archivos de configuración son strings planos y nada los chequea hasta que un build, un release o la asignación de revisión de GitHub los usa.

El escenario de la fuente es este: movés scripts/start.sh a tools/start.sh, VS Code te arregla los imports, los tests pasan en verde, hacés push con la conciencia tranquila y cuando el pipeline llega al build de la imagen el Dockerfile sigue diciendo COPY scripts/start.sh y todo se corta.

Una aclaración: esto no es un anuncio de Vercel. La empresa aparece solo porque la fuente cita un issue de Next.js (#33338) como ejemplo real del error de COPY. Más contexto en desplegar un proyecto React con Vite.

Lo que sí me parece un buen diagnóstico del autor: el problema no es que falte una herramienta de refactor “más inteligente”, sino que nadie es dueño de esos strings.

¿En qué archivos quedan rutas rotas después de mover un archivo?

Quedan en package.json, Dockerfile, workflows de GitHub Actions, tsconfig.json y CODEOWNERS, según la lista de la fuente. Cada uno falla en un momento distinto, y por eso las rutas rotas en CI se descubren tarde y en lugares alejados del renombrado.

Archivo	Campos con rutas	Cómo se rompe
package.json	main, bin, exports, files	Un paquete publicado que apunta a nada (reanimated#3026)
Dockerfile	COPY / ADD	“COPY failed: file not found in build context” (next.js #33338)
Workflow de GitHub Actions	run: / working-directory	“No such file or directory” en un step
tsconfig.json	extends / references	Un type check que falla lejos del renombrado
CODEOWNERS	Patrones de carpetas y archivos	No falla nada: la carpeta movida no matchea archivos y nadie recibe el pedido de revisión

Mi lectura (es opinión, no dato de la fuente): CODEOWNERS es el peor de los cinco justamente porque no grita. Un build rojo se arregla enseguida. Una carpeta sin revisores puede pasar sin que nadie lo note.

El caso de package.json también tiene su lado incómodo. El README de PathMend cita el issue “Package json main points to non existing file” de react-native-reanimated, que llegó a un release.

¿Qué significa “COPY failed: file not found in build context” y cómo se arregla?

Significa que Docker no encontró el archivo de origen de un COPY dentro del build context. En el caso de la fuente, la causa es que el archivo se movió y el Dockerfile conserva la ruta vieja. El arreglo es corregir el origen (tools/start.sh en vez de scripts/start.sh) y reconstruir con el mismo contexto que usa el CI. Sobre eso hablamos en publicar tu web gratis en Vercel.

Hay una segunda causa posible: que la ruta no coincida con el contexto. La fuente menciona el issue docker/build-push-action#97, “What’s the Context for COPY?”, como ejemplo de ese desfase. Un COPY escrito como ../../src con un contexto en services/api sale del contexto, y PathMend lo marca con la regla PM011.

¿Cómo encontrar rutas rotas en CI a mano con git grep, docker build y npm pack?

Buscás el path viejo con git grep en todo el repo, después corrés docker build con el mismo contexto que el CI y npm pack –dry-run. Son los comandos que propone la fuente; adaptá el contexto y los patrones a tu repo.

git grep -n "scripts/start.sh"
git grep -n "scripts/" -- '*.json' '*.yml' '*.yaml' 'Dockerfile*' CODEOWNERS

El límite lo dice el propio autor: funciona, pero solo para el string que te acordaste de buscar.

Para un archivo suelto alcanza. Si movés una carpeta entera con varios archivos adentro, el método depende de tu memoria, y ahí es donde se escapa algo. Tema relacionado: un deploy verde que igual esconde errores.

¿Qué es PathMend y qué chequea en VS Code?

PathMend es una extensión de VS Code que chequea que las rutas escritas en archivos de configuración existan dentro del workspace. Todo lo que sigue sale del README y del artículo del autor; no la probamos nosotros.

• Diagnóstico sobre el string exacto: subraya la ruta rota en package.json, tsconfig, Dockerfile, Compose, GitHub Actions, .gitlab-ci.yml, CODEOWNERS y launch.json (reglas PM001 a PM011).
• Quick Fix “Did you mean …?”: busca el archivo con el mismo nombre en otra carpeta (el caso típico de “lo moví”) o una ortografía parecida.
• Aviso al renombrar: si renombrás o movés algo en VS Code, pregunta algo como “3 config references still point to src/utils – update all?”, con las opciones Update all, Preview e Ignore.
• Panel Broken References: tiene ícono propio en la barra de actividad con un badge y lista cada ruta rota con arreglo de un clic.
• Contexto de Docker: resuelve los COPY contra el build context de un Compose que use ese Dockerfile y marca los escapes del contexto.

Se instala con code --install-extension jaytankdev.pathmend. El código está en el repositorio de GitHub bajo licencia MIT.

¿Qué límites tiene PathMend y qué falsos positivos evita?

Evita falsos positivos saltando $VAR, ${ }, COPY –from, URLs y carpetas de salida como dist/ o el outDir de tu tsconfig. Sus límites declarados: no lee contextos de build pasados por línea de comandos, no aplica .dockerignore y un git mv en la terminal no dispara el aviso de renombrado.

No usa red, telemetría ni procesos hijos, y funciona en workspaces no confiables porque solo comprueba si las rutas existen. Un detalle de los límites que conviene tener presente: sin un Compose que apunte al Dockerfile, acepta un COPY si el origen existe relativo a la carpeta del Dockerfile o a cualquier carpeta padre hasta la raíz del workspace. Eso puede dar un falso “todo bien” si tu CI usa otro contexto.

Consecuencia práctica: no reemplaza a docker build ni a npm pack –dry-run en el CI. Es una alerta temprana. Cubrimos ese tema en detalle en otras plataformas de deploy además de Vercel.

¿Cómo verificar que no queden rutas rotas antes de mergear?

Esta secuencia es una propuesta editorial armada con los comandos de la fuente; no la medimos ni la probamos en un repo real.

1. Buscá el path viejo: git grep del nombre anterior en archivos de configuración; el resultado esperado es cero coincidencias.
2. Reconstruí la imagen: docker build con el mismo contexto que usa el CI, no con el que tengas a mano.
3. Mirá el paquete: corré npm pack –dry-run y comprobá que los archivos de main, bin, exports y files aparezcan en la lista.
4. Revisá CODEOWNERS a ojo: es el único que no falla solo.
5. Si usás PathMend: dejá el panel Broken References en cero.

Qué está confirmado y qué no

• Confirmado por las fuentes: la lista de reglas PM001 a PM011, la licencia MIT, la ausencia de red y telemetría, y las limitaciones declaradas por el autor.
• No confirmado: qué tan bien detecta casos en repos grandes, cuántos falsos positivos da en la práctica y cuánta gente la usa. Las fuentes no traen mediciones, y las afirmaciones son del propio autor.
• Tampoco consta: la versión actual de la extensión ni su fecha de lanzamiento.

Errores comunes

• Buscar solo el archivo y no la carpeta. Si movés un directorio, el git grep de “scripts/start.sh” no encuentra “scripts/” en un working-directory. Buscá también el prefijo, como en el segundo comando de arriba.
• Probar docker build con otro contexto. Si lo corrés desde otra carpeta que el CI, podés ver verde en tu máquina y rojo en el pipeline.
• Mover con git mv y esperar el aviso. PathMend no ve los renombrados hechos en la terminal; las referencias aparecen como rotas, sin el “update all”.
• Dar por buena una carpeta de CODEOWNERS. Sin error no hay alarma, y el patrón viejo simplemente deja de matchear.

Preguntas Frecuentes

¿VS Code actualiza las rutas del Dockerfile o de GitHub Actions al renombrar un archivo?

Según la fuente, las herramientas de refactor actualizan las rutas del código, pero no los strings de Dockerfile o workflows. PathMend agrega ese paso: al renombrar en VS Code ofrece actualizar las referencias en archivos de configuración.

¿Cómo busco todas las referencias a un archivo que moví en Dockerfile y workflows?

Corré git grep -n con el path viejo y otro con la carpeta, limitado a ‘*.json’ ‘*.yml’ ‘*.yaml’ ‘Dockerfile*’ y CODEOWNERS. Solo encuentra lo que escribas en el patrón, así que probá con el nombre del archivo y con su carpeta.

¿Cómo verifico que package.json no apunte a archivos que no existen antes de publicar?

Corré npm pack –dry-run y comprobá que los archivos de main, bin, exports y files estén en la lista. PathMend también chequea esos campos (regla PM001), incluidos los fallbacks .js e index.js de Node.

¿PathMend lee mi código o manda datos a algún servidor?

Según el README, no usa red, telemetría ni procesos hijos. Solo lee archivos de configuración y comprueba que las rutas existan, sin abrir el contenido de los archivos referenciados.

¿PathMend reemplaza a docker build en el CI?

No. No lee contextos de build pasados por línea de comandos ni aplica .dockerignore, así que puede aceptar un COPY que el build real rechace. Dejá docker build y npm pack –dry-run como verificación final.

Conclusión

Las rutas rotas en CI vienen de un hueco concreto: el refactor cubre el código y los strings de configuración quedan sin dueño. Lo que podés hacer hoy es meter el git grep del path viejo, el docker build con el contexto del CI y el npm pack –dry-run en tu checklist de renombrados, y revisar CODEOWNERS a mano.

PathMend es una opción razonable si renombrás seguido, siempre que tomes sus resultados como alerta temprana y no como garantía. Falta ver mediciones independientes.

Fuentes

• GitHub (jay-tank/pathmend) – README de PathMend con reglas PM001 a PM011, ajustes y limitaciones
• dev.to – “You renamed a file and CI broke”, artículo del autor de PathMend (16/10/2026)