Outils de développement · JSON formateur et validateur
Corrigez un package.json cassé avant CI : lecture de la position de l'erreur
· Pourquoi c'est important
json flux de travail du développeur validation
Un package.json, composer.json ou launch.json édité manuellement échoue longtemps après son enregistrement, généralement dans CI. Cet article montre comment valider avant de vous engager et lire rapidement la position de l'erreur.
Douze minutes de pipeline pour en savoir plus sur une virgule
Douze minutes de pipeline pour en savoir plus sur une virgule : un conflit de fusion résolu à la main, un éditeur vert et une version rouge. L'extraction du référentiel peut sembler normale car Git enregistre les octets, et non si un manifeste est analysé. CI installe ensuite les dépendances, atteint le fichier endommagé et s'arrête avant que les tests ne fournissent un signal utile.
L'outil vérifie uniquement la syntaxe stricte JSON et accepte les documents jusqu'à 8,000,000 caractères JavaScript. package.json et composer.json sont des exemples stricts appropriés. Les fichiers tels que tsconfig.json peuvent utiliser un analyseur tolérant les commentaires, donc rejeter leurs commentaires en tant que JSON ne prouve pas que l'outil propriétaire les rejettera. Validez par rapport à la grammaire déclarée par le programme consommateur.
Quels fichiers de configuration JSON tombent en panne le plus souvent
Quels fichiers de configuration JSON se cassent le plus souvent : package.json, composer.json, launch.json et fichiers de verrouillage, et pourquoi tsconfig.json, qui autorise les commentaires, nécessite une attention particulière. Les manifestes édités par l'homme ont tendance à échouer autour des blocs de dépendance, des scripts et des paramètres d'outils imbriqués. Les fichiers de verrouillage générés échouent différemment : la résolution manuelle des conflits peut endommager les délimiteurs ou dupliquer des sections structurelles.
Ne supposez pas que tous les fichiers avec une extension de type JSON utilisent le strict JSON. Les paramètres VS Code et la configuration TypeScript autorisent généralement les commentaires ou les virgules de fin via des analyseurs spécialisés, contrairement aux manifestes de packages. Validez un fichier de verrouillage généré avec son gestionnaire de packages lorsque cela est possible, car une syntaxe valide ne peut à elle seule restaurer les hachages, les règles de classement ou la cohérence interne attendue par ce générateur.
Pourquoi les outils échouent tardivement : les gestionnaires de packages et les compilateurs analysent à la demande, de sorte qu'une erreur de syntaxe apparaît au moment de l'installation ou de la construction plutôt qu'à la sauvegarde.
Pourquoi les outils échouent tardivement : les gestionnaires de packages et les compilateurs analysent à la demande, de sorte qu'une erreur de syntaxe apparaît au moment de l'installation ou de la construction plutôt que lors de la sauvegarde. Un éditeur de texte peut colorer les accolades sans exécuter l'analyseur faisant autorité, et un manifeste modifié peut ne pas être lu lors d'une tâche locale restreinte. CI part d'un environnement propre et exerce des chemins de configuration que les postes de travail en cache ignorent.
Le retard qui en résulte inclut le temps d'attente, le paiement, la configuration des dépendances et les tâches préliminaires non liées. Pire encore, le message éventuel peut nommer uniquement un fichier de package invalide tout en masquant la ligne d'origine derrière la sortie de la commande. Une analyse locale immédiatement après l'édition réduit cette boucle de rétroaction. Il sépare également un échec grammatical des erreurs ultérieures de résolution de dépendances ou de schéma qui nécessitent une enquête différente.
Lecture de la position d'erreur sous pression
Lecture de la position de l'erreur sous pression : ligne et colonne, le jeton précédent et les trois modèles de conflit de fusion qui produisent un JSON invalide. Le caractère marqué est l’endroit où la suite est devenue impossible, pas toujours là où l’erreur a commencé. Une citation de clôture peut exposer une citation antérieure non échappée ; une accolade peut révéler une virgule manquante juste avant la propriété suivante.
Après les fusions, recherchez les marqueurs de conflit laissés sous forme de texte brut, les blocs de membres dupliqués joints sans virgule et les délimiteurs supprimés lors du choix d'un côté. Inspectez le jeton avant l’emplacement signalé et comptez les limites du conteneur environnant. Effectuez une réparation, réexécutez la validation et conservez la différence d'origine, car un analyseur ne signale généralement que le premier obstacle et un deuxième conflit indépendant peut rester plus bas.
Exemple fonctionnel : un package.json après une mauvaise fusion
Exemple fonctionnel : un package.json après une mauvaise fusion – un bloc de dépendances dupliqué, une virgule manquante, le rapport du validateur et le correctif. Imaginez `"scripts":{"test":"vitest"}` suivi immédiatement par `"dependencies":{"vite":"7.3.6"}`. Le deuxième nom de propriété est l'endroit où l'analyseur découvre que l'objet n'a pas de séparateur, bien que la virgule corrective appartienne après l'objet scripts.
Insérez cette virgule et validez à nouveau avant le formatage. Si la fusion a également produit deux clés `dependencies`, l'analyse stricte peut toujours réussir car les noms en double sont syntaxiquement autorisés, mais l'analyse JavaScript ne conserve que la valeur la plus récente. Comparez les deux branches et combinez les membres prévus plutôt que de supprimer un bloc mécaniquement. La réparation syntaxique et la résolution de fusion sémantique sont des tâches consécutives et distinctes.
Faire de la validation une habitude
Faire de la validation une habitude : collez-le avant de le valider ou validez tout JSON que vous avez modifié en dehors d'un IDE, sans avoir besoin d'un compte ou d'un plugin. Le meilleur déclencheur est comportemental : chaque fois que des marqueurs de conflit ont été résolus, qu'un gros bloc a été déplacé ou que la ponctuation a été saisie manuellement, exécutez la vérification de l'outil propriétaire ou un analyseur strict avant de transférer le fichier.
Les référentiels peuvent automatiser la même règle avec une vérification préalable à la validation et une tâche CI limitée aux manifestes, mais l'automatisation doit compléter les commentaires immédiats plutôt que de devenir le premier analyseur. Gardez le formatage séparé de la réparation afin que le diff affiche le caractère significatif. Pour les fichiers générés, régénérez à partir du manifeste source au lieu de normaliser la sortie éditée manuellement, puis laissez le générateur prouver ses propres invariants.
Ce que cela ne couvre pas
Ce que cela ne couvre pas : les erreurs sémantiques telles qu'une plage de versions incorrecte ou un champ inconnu, contre lesquels JSON valide ne peut pas vous protéger. Un manifeste de package peut analyser tout en nommant un script inexistant, en plaçant une dépendance dans la mauvaise section ou en utilisant une expression de version qui se résout de manière inattendue. Les clés en double peuvent également réussir les vérifications grammaticales tout en remplaçant silencieusement les valeurs antérieures.
Utilisez la validation du gestionnaire de packages, les schémas, les tests d'installation et la révision de ces couches. Cette vérification ne prouve pas non plus qu'un fichier de verrouillage correspond à son manifeste ou qu'une configuration de lancement nomme un débogueur installé. Si le format réel est JSONC ou un autre dialecte, utilisez son analyseur plutôt que de supprimer la syntaxe prise en charge simplement pour satisfaire au strict JSON. La grammaire est la première porte, pas le contrat de configuration complet.
À retenir : une vérification de la syntaxe coûte quelques secondes, un pipeline défaillant coûte des minutes
À retenir : une vérification de la syntaxe coûte quelques secondes, un pipeline défaillant coûte des minutes — et le rapport précis du validateur raccourcit le correctif. Exécutez-le sur les derniers octets modifiés, commencez par la ligne et la colonne signalées, puis inspectez le jeton précédent pour détecter un séparateur ou un délimiteur manquant. Revalidez après chaque correction car les erreurs ultérieures peuvent être masquées dans un premier temps.
Une fois la syntaxe stricte passée, revenez au consommateur : exécutez la validation spécifique au gestionnaire de packages, au compilateur ou à l'éditeur qui comprend les champs et les valeurs autorisés. Gardez les différences de réparation étroites, en particulier après les fusions, afin que les réviseurs puissent distinguer la ponctuation des décisions de dépendance. Cette séquence détecte localement la défaillance la moins coûteuse et réserve du temps de pipeline coûteux pour un comportement que seul l'environnement complet peut évaluer.