Ferramentas para desenvolvedores · Formatador e validador JSON
Corrija um package.json quebrado antes do CI: lendo a posição do erro
· Por que é importante
JSON fluxo de trabalho do desenvolvedor validação
Um package.json, composer.json ou launch.json editado manualmente falha muito depois de você salvá-lo, geralmente em CI. Este post mostra como validar antes de confirmar e ler a posição do erro rapidamente.
Doze minutos de pipeline para aprender sobre uma vírgula
Doze minutos de pipeline para aprender sobre uma vírgula – um conflito de mesclagem resolvido manualmente, um editor verde e uma construção vermelha. A verificação do repositório pode parecer normal porque o Git registra bytes, e não se um manifesto é analisado. O CI então instala dependências, alcança o arquivo danificado e para antes que os testes forneçam qualquer sinal útil.
A ferramenta verifica apenas a sintaxe estrita JSON e aceita documentos com até 8,000,000 JavaScript caracteres. package.json e composer.json são exemplos estritos adequados. Arquivos como tsconfig.json podem usar um analisador tolerante a comentários, portanto, rejeitar seus comentários como JSON não prova que a ferramenta proprietária os rejeitará. Valide em relação à gramática que o programa de consumo realmente declara.
Quais arquivos de configuração JSON quebram com mais frequência
Quais arquivos de configuração JSON quebram com mais frequência - package.json, composer.json, launch.json e arquivos de bloqueio, e por que tsconfig.json, que permite comentários, precisa de cuidados separados. Manifestos editados por humanos tendem a falhar em torno de blocos de dependência, scripts e configurações de ferramentas aninhadas. Os arquivos de bloqueio gerados falham de maneira diferente: a resolução manual de conflitos pode danificar delimitadores ou duplicar seções estruturais.
Não presuma que todos os arquivos com uma extensão semelhante a JSON usam JSON estrito. As configurações do VS Code e do TypeScript geralmente permitem comentários ou vírgulas finais por meio de analisadores especializados, enquanto os manifestos de pacotes geralmente não permitem. Valide um arquivo de bloqueio gerado com seu gerenciador de pacotes quando possível, porque a sintaxe válida por si só não pode restaurar hashes, regras de ordenação ou consistência interna esperada por esse gerador.
Por que as ferramentas falham tarde – gerenciadores de pacotes e compiladores analisam sob demanda, então um erro de sintaxe surge no momento da instalação ou construção, em vez de ao salvar
Por que as ferramentas falham tarde — gerenciadores de pacotes e compiladores analisam sob demanda, portanto, um erro de sintaxe surge no momento da instalação ou compilação, em vez de ao salvar. Um editor de texto pode colorir colchetes sem executar o analisador oficial, e um manifesto alterado pode não ser lido durante uma tarefa local restrita. O CI inicia em um ambiente limpo e exercita caminhos de configuração que as estações de trabalho em cache ignoram.
O atraso resultante inclui tempo de fila, checkout, configuração de dependências e trabalhos preliminares não relacionados. Pior ainda, a eventual mensagem pode nomear apenas um arquivo de pacote inválido enquanto oculta a linha original atrás da saída do comando. Uma análise local imediatamente após a edição recolhe esse ciclo de feedback. Ele também separa uma falha gramatical de erros posteriores de resolução de dependência ou de esquema que exigem investigação diferente.
Lendo a posição de erro sob pressão
Lendo a posição do erro sob pressão – linha e coluna, o token anterior e os três padrões de conflito de mesclagem que produzem JSON inválido. O personagem marcado é onde a continuação se tornou impossível, nem sempre onde o erro começou. Uma cotação de fechamento pode expor uma cotação anterior sem escape; uma chave pode revelar uma vírgula ausente imediatamente antes da próxima propriedade.
Após as mesclagens, procure marcadores de conflito deixados como texto simples, blocos de membros duplicados unidos sem vírgula e delimitadores excluídos ao escolher um lado. Inspecione o token antes do local relatado e conte os limites do contêiner ao redor. Faça um reparo, execute novamente a validação e preserve a diferença original, porque um analisador geralmente relata apenas o primeiro obstáculo e um segundo conflito independente pode permanecer mais abaixo.
Exemplo resolvido: um package.json após uma mesclagem incorreta
Exemplo resolvido: um package.json após uma mesclagem incorreta - um bloco de dependências duplicadas, uma vírgula faltando, o relatório do validador e a correção. Imagine `"scripts":{"test":"vitest"}` seguido imediatamente por `"dependencies":{"vite":"7.3.6"}`. O segundo nome da propriedade é onde o analisador descobre que o objeto não possui um separador, embora a vírgula corretiva pertença depois do objeto de scripts.
Insira essa vírgula e valide novamente antes de formatar. Se a mesclagem também produziu duas chaves `dependencies`, a análise estrita ainda poderá ser bem-sucedida porque nomes duplicados são sintaticamente permitidos, mas a análise JavaScript mantém apenas o valor posterior. Compare as duas ramificações e combine os membros pretendidos em vez de excluir um bloco mecanicamente. O reparo de sintaxe e a resolução de mesclagem semântica são tarefas consecutivas e distintas.
Tornando a validação um hábito
Tornando a validação um hábito - cole antes de confirmar ou valide qualquer JSON que você editou fora de um IDE, sem precisar de uma conta ou plugin. O melhor gatilho é comportamental: sempre que os marcadores de conflito foram resolvidos, um bloco grande foi movido ou a pontuação foi digitada manualmente, execute a verificação da ferramenta proprietária ou um analisador estrito antes de preparar o arquivo.
Os repositórios podem automatizar a mesma regra com uma verificação pré-confirmação e um trabalho de CI com escopo definido para manifestos, mas a automação deve complementar o feedback imediato em vez de se tornar o primeiro analisador. Mantenha a formatação separada do reparo para que a diferença mostre o caractere significativo. Para arquivos gerados, regenere a partir do manifesto de origem em vez de normalizar a saída editada manualmente e deixe o gerador provar suas próprias invariantes.
O que isso não cobre
O que isso não cobre - erros semânticos, como um intervalo de versão errado ou um campo desconhecido, dos quais JSON válido não pode protegê-lo. Um manifesto de pacote pode ser analisado ao nomear um script inexistente, colocar uma dependência na seção errada ou usar uma expressão de versão que seja resolvida inesperadamente. Chaves duplicadas também podem passar em verificações gramaticais enquanto substituem silenciosamente valores anteriores.
Use validação do gerenciador de pacotes, esquemas, testes de instalação e revisão dessas camadas. Essa verificação também não prova que um arquivo de bloqueio corresponda ao seu manifesto ou que uma configuração de inicialização nomeie um depurador instalado. Se o formato real for JSONC ou outro dialeto, use seu analisador em vez de remover a sintaxe suportada apenas para satisfazer JSON estrito. A gramática é o portão mais antigo, não o contrato de configuração completo.
Conclusão: uma verificação de sintaxe custa segundos, um pipeline com falha custa minutos
Conclusão: uma verificação de sintaxe custa segundos, um pipeline com falha custa minutos — e o relatório preciso do validador encurta a correção. Execute-o nos bytes editados finais, comece na linha e coluna relatadas e, em seguida, inspecione o token anterior em busca de um separador ou delimitador ausente. Revalite após cada correção porque erros posteriores podem ser ocultados inicialmente.
Depois que a sintaxe estrita for aprovada, retorne ao consumidor: execute o gerenciador de pacotes, o compilador ou a validação específica do editor que entende os campos e valores permitidos. Mantenha as diferenças de reparo restritas, especialmente após mesclagens, para que os revisores possam distinguir a pontuação das decisões de dependência. Essa sequência detecta localmente a falha mais barata e reserva tempo de pipeline caro para comportamentos que somente o ambiente completo pode avaliar.