Herramientas de desarrollo · JSON formateador y validador
Reparar un package.json roto antes de que lo haga CI: leer la posición del error
· Por qué es importante
json flujo de trabajo del desarrollador validación
Un package.json, composer.json o launch.json editado a mano falla mucho después de guardarlo, generalmente en CI. Esta publicación muestra cómo validar antes de confirmar y leer rápidamente la posición del error.
Doce minutos de canalización para aprender sobre una coma
Doce minutos de proceso para aprender sobre una coma: un conflicto de fusión resuelto a mano, un editor verde y una compilación roja. La verificación del repositorio puede parecer normal porque Git registra bytes, no si un manifiesto los analiza. Luego, CI instala dependencias, llega al archivo dañado y se detiene antes de que las pruebas proporcionen alguna señal útil.
La herramienta comprueba únicamente la sintaxis estricta JSON y acepta documentos de hasta 8,000,000 caracteres JavaScript. package.json y composer.json son ejemplos estrictos adecuados. Archivos como tsconfig.json pueden usar un analizador tolerante a comentarios, por lo que rechazar sus comentarios como JSON no prueba que la herramienta propietaria los rechace. Valide con la gramática que realmente declara el programa consumidor.
Qué archivos de configuración JSON se rompen con más frecuencia
Qué archivos de configuración JSON se rompen con más frecuencia: package.json, composer.json, launch.json y archivos de bloqueo, y por qué tsconfig.json, que permite comentarios, necesita atención separada. Los manifiestos editados por humanos tienden a fallar en torno a bloques de dependencia, scripts y configuraciones de herramientas anidadas. Los archivos de bloqueo generados fallan de manera diferente: la resolución manual de conflictos puede dañar los delimitadores o duplicar secciones estructurales.
No asuma que todos los archivos con una extensión similar a JSON utilizan JSON estricto. La configuración de VS Code y la configuración de TypeScript comúnmente permiten comentarios o comas finales a través de analizadores especializados, mientras que los manifiestos de paquetes generalmente no lo hacen. Valide un archivo de bloqueo generado con su administrador de paquetes cuando sea posible, porque la sintaxis válida por sí sola no puede restaurar los hashes, las reglas de ordenamiento o la coherencia interna esperada por ese generador.
Por qué las herramientas fallan tarde: los administradores de paquetes y los compiladores analizan según demanda, por lo que aparece un error de sintaxis en el momento de la instalación o la compilación en lugar de al guardar
Por qué las herramientas fallan tarde: los administradores de paquetes y los compiladores analizan según demanda, por lo que aparece un error de sintaxis en el momento de la instalación o la compilación en lugar de al guardar. Un editor de texto puede colorear las llaves sin ejecutar el analizador autorizado y es posible que un manifiesto modificado no se lea durante una tarea local limitada. La CI comienza desde un entorno limpio y practica rutas de configuración que las estaciones de trabajo almacenadas en caché omiten.
El retraso resultante incluye tiempo de cola, pago, configuración de dependencia y trabajos preliminares no relacionados. Peor aún, el mensaje final puede nombrar solo un archivo de paquete no válido y ocultar la línea original detrás de la salida del comando. Un análisis local inmediatamente después de la edición colapsa ese ciclo de retroalimentación. También separa una falla gramatical de errores posteriores de resolución de dependencia o de esquema que requieren una investigación diferente.
Lectura de la posición de error bajo presión
Lectura de la posición de error bajo presión: línea y columna, el token anterior y los tres patrones de conflicto de fusión que producen JSON no válido. El carácter marcado es donde la continuación se hizo imposible, no siempre donde comenzó el error. Una cotización de cierre puede exponer una cotización anterior sin escape; una llave puede revelar que falta una coma inmediatamente antes de la siguiente propiedad.
Después de las fusiones, busque marcadores de conflicto que se dejen como texto sin formato, bloques de miembros duplicados unidos sin coma y delimitadores eliminados al elegir un lado. Inspeccione el token antes de la ubicación informada y cuente los límites del contenedor circundante. Haga una reparación, vuelva a ejecutar la validación y conserve la diferencia original, porque un analizador generalmente informa solo el primer obstáculo y un segundo conflicto independiente puede permanecer más abajo.
Ejemplo resuelto: un package.json después de una mala combinación
Ejemplo resuelto: un package.json después de una combinación incorrecta: un bloque de dependencias duplicado, una coma faltante, el informe del validador y la solución. Imagine `"scripts":{"test":"vitest"}` seguido inmediatamente de `"dependencies":{"vite":"7.3.6"}`. El segundo nombre de propiedad es donde el analizador descubre que el objeto carece de separador, aunque la coma correctiva va después del objeto de scripts.
Inserte esa coma y valide nuevamente antes de formatear. Si la combinación también produjo dos claves `dependencies`, el análisis estricto aún puede tener éxito porque sintácticamente se permiten nombres duplicados, pero el análisis de JavaScript mantiene solo el valor posterior. Compare ambas ramas y combine los miembros previstos en lugar de eliminar un bloque mecánicamente. La reparación de sintaxis y la resolución de fusión semántica son tareas distintas y consecutivas.
Hacer de la validación un hábito
Hacer de la validación un hábito: pegue antes de confirmar o valide cualquier JSON que haya editado fuera de un IDE, sin necesidad de una cuenta o un complemento. El mejor desencadenante es el conductual: cada vez que se resolvieron marcadores de conflicto, se movió un bloque grande o se escribió puntuación manualmente, ejecute la verificación de la herramienta propietaria o un analizador estricto antes de preparar el archivo.
Los repositorios pueden automatizar la misma regla con una verificación previa a la confirmación y un trabajo de CI con alcance de manifiestos, pero la automatización debe complementar la retroalimentación inmediata en lugar de convertirse en el primer analizador. Mantenga el formato separado de la reparación para que la diferencia muestre el carácter significativo. Para los archivos generados, regenere desde el manifiesto fuente en lugar de normalizar la salida editada manualmente, luego deje que el generador pruebe sus propias invariantes.
Lo que esto no cubre
Lo que esto no cubre: errores semánticos como un rango de versión incorrecto o un campo desconocido, de los cuales un JSON válido no puede protegerlo. Un manifiesto de paquete puede analizarse mientras nombra un script inexistente, coloca una dependencia en la sección incorrecta o usa una expresión de versión que se resuelve inesperadamente. Las claves duplicadas también pueden pasar revisiones gramaticales y al mismo tiempo reemplazar silenciosamente valores anteriores.
Utilice la validación del administrador de paquetes, los esquemas, las pruebas de instalación y la revisión de esas capas. Esta verificación tampoco prueba que un archivo de bloqueo coincida con su manifiesto o que una configuración de inicio nombre un depurador instalado. Si el formato real es JSONC u otro dialecto, utilice su analizador en lugar de eliminar la sintaxis admitida simplemente para satisfacer el estricto JSON. La gramática es la puerta de entrada más temprana, no el contrato de configuración completo.
Conclusión: una verificación de sintaxis cuesta segundos, una canalización fallida cuesta minutos
Conclusión: una verificación de sintaxis cuesta segundos, una canalización fallida cuesta minutos y el informe preciso del validador acorta la solución. Ejecútelo en los bytes editados finales, comience en la línea y columna informadas, luego inspeccione el token anterior en busca de un separador o delimitador faltante. Vuelva a validar después de cada corrección porque los errores posteriores pueden ocultarse inicialmente.
Una vez que pase la sintaxis estricta, regrese al consumidor: ejecute el administrador de paquetes, el compilador o la validación específica del editor que comprenda los campos y valores permitidos. Mantenga estrechas las diferencias de reparación, especialmente después de fusiones, para que los revisores puedan distinguir la puntuación de las decisiones de dependencia. Esta secuencia detecta la falla más barata localmente y reserva un costoso tiempo de canalización para comportamientos que solo el entorno completo puede evaluar.