Écrire des règles d’analyse statique avec des corrections automatiques qui ne changent pas l’exécution du code

## Viser les cas courants et laisser de côté les cas rares Gardez chaque règle conceptuellement simple. Ciblez les motifs récurrents à forte valeur et laissez sans prise en charge les rares cas limites lorsque leur couverture rendrait la règle obscure ou les corrections risquées. Définissez un contrat de règle stable avec une fonction de création et des métadonnées. Dans un adaptateur fondé sur les événements, enregistrez les écouteurs d’entrée et de sortie au moyen des points d’extension fournis au lieu de renvoyer une table de visiteurs conventionnelle. Les écouteurs doivent renvoyer ou produire avec yield des objets de problème ; laissez l’adaptateur effectuer le signalement. Chaque problème doit désigner le nœud et le message concernés, puis ajouter des données, une correction ou des suggestions uniquement si nécessaire. Si l’API du correcteur propose un mécanisme d’abandon, utilisez-le dès qu’une modification sûre ne peut pas être démontrée. Placez les valeurs par défaut des options dans les métadonnées afin que le framework puisse les fusionner de manière cohérente, sans dupliquer la logique de fusion dans la règle. ## Choisir le préréglage qui reçoit la règle et faire commencer les noms d’options par check Traitez l’affectation aux préréglages comme une décision produit : - Placez les règles non controversées dans le préréglage le plus sûr et dans tous les préréglages plus larges. - Placez les valeurs par défaut utiles mais prescriptives uniquement dans le préréglage recommandé et les collections plus larges. - Écartez des préréglages par défaut les comportements spécialisés ou qui nécessitent une activation explicite. Ne confondez pas « sans parti pris » et « trop prescriptif ». En cas d’incertitude, indiquez le niveau proposé et demandez à la personne responsable de la maintenance de décider. Donnez aux options booléennes publiques des noms positifs de la forme `check*`, afin que `true` active toujours le comportement. Les listes de motifs ignorés peuvent conserver des noms conventionnels comme `ignore`. Déclarez explicitement chaque langue prise en charge. Si la logique dépend uniquement des noms de fichiers, du texte brut, des commentaires ou des directives, prenez en charge plusieurs langues lorsque c’est raisonnable et utilisez des fonctions auxiliaires de racine et de commentaires qui abstraient les types de nœuds propres à chaque langue. ## Nommer les helpers selon ce qu’ils renvoient et réutiliser les utilitaires existants Nommez les fonctions auxiliaires privées d’après leur contrat observable. `is*`, `has*`, `should*`, `can*` et `needs*` doivent renvoyer des booléens, de préférence un `false` explicite plutôt qu’une valeur undefined accidentelle. Utilisez `get*Problem` pour un problème facultatif et `get*Problems` pour plusieurs problèmes. Réservez `report*` aux fonctions auxiliaires qui effectuent directement un signalement. Ne combinez pas le signalement ou l’utilisation de yield avec le résultat d’un prédicat. Construisez le problème séparément, puis prenez la décision booléenne au point d’appel. Avant d’ajouter une fonction auxiliaire, inspectez les modules d’AST, d’utilitaires généraux, de correction et de règles partagées du dépôt, puis consultez les utilitaires fiables de l’écosystème. Réutilisez les exports regroupés et les fonctions auxiliaires établies pour l’évaluation statique, la recherche de variables, la détection des effets de bord, les tests de tokens, la résolution des références, les parenthèses, les points-virgules et la construction des corrections. Rendez une fonction auxiliaire commune uniquement lorsqu’elle est clairement réutilisable ; conservez localement la petite logique propre à une règle. ## N’utiliser l’analyse du flux de contrôle que pour savoir si le code sort toujours Utilisez l’analyse du flux de contrôle du framework lorsqu’une règle doit déterminer si une branche ou une fonction se termine toujours par des structures telles que return, throw, break, continue, une sélection exhaustive ou une boucle infinie. Le parcours manuel de l’AST est généralement moins précis autour de la gestion des exceptions, des étiquettes, de l’imbrication et des segments inaccessibles. Pour l’analyse des branches, enregistrez le suivi de sortie de branche du dépôt et interrogez-le après la sortie de la condition englobante. Pour l’analyse des fonctions, maintenez un ensemble de segments par chemin de code afin que les fonctions imbriquées ne contaminent pas leurs fonctions parentes. Capturez l’accessibilité à la sortie du nœud AST concerné ; n’attendez pas la fin du chemin de code si le framework a déjà effacé les segments courants. Utilisez des vérifications syntaxiques plus simples lorsque la question consiste uniquement à savoir si la dernière instruction possède un type donné, où apparaissent les return ou si un correcteur local se termine par return ou throw. N’introduisez pas de mécanisme de flux de contrôle sans besoin réel d’analyser l’accessibilité. ## Régénérer les index et en-têtes de documentation générés au lieu de les modifier à la main Repérez les fichiers et les régions générés avant toute modification. Ne modifiez jamais manuellement les index, tableaux ou en-têtes de documentation générés. Exécutez le générateur responsable après l’ajout, le retrait ou le renommage de règles source. Lors de la résolution de conflits, conservez les entrées qui font autorité et régénérez les résultats déterministes au lieu de les reconstruire manuellement. Conservez la documentation rédigée par des personnes sous toute limite d’en-tête généré. Utilisez la syntaxe de configuration privilégiée par le dépôt dans les exemples ; ne passez pas à des exemples de type JSON entre guillemets, sauf si l’exemple est explicitement en JSON. Lorsque des motifs de règles partagés existent aussi dans un dépôt ou un paquet associé, déterminez si la même modification doit y être portée. Traitez ce choix comme une décision explicite de compatibilité, et non comme une modification automatique entre projets. ## Lancer seulement les tests de la règle pendant le développement, puis toute la suite à la fin Écrivez des tests ciblés avant la mise en œuvre ou en parallèle. Privilégiez les tests par instantané lorsque l’environnement de test peut capturer ensemble les diagnostics, les corrections et les suggestions, et réservez les modes d’analyse spécialisés aux cas qui en ont besoin. Pendant le développement, exécutez uniquement le test de la règle ciblée. Mettez les instantanés à jour intentionnellement et retirez les marqueurs temporaires de test ciblé avant de terminer. N’intégrez pas les tests d’intégration lents à la boucle de modification habituelle. Testez la nouvelle règle sur le projet lui-même après sa mise en œuvre et après chaque correction de logique, car les corrections révèlent souvent des infractions ailleurs. À la fin, exécutez l’analyseur réel du dépôt, les tests ciblés et le test sur le projet lui-même, puis la suite de tests complète une seule fois. Ne remplacez pas l’analyseur prévu par un autre outil de lint uniquement parce que celui-ci ne signale aucun problème. ## Tester les corrections avec des commentaires et une syntaxe délicate Testez le comportement, les absences de correspondance, les corrections et les suggestions sans dupliquer la couverture. Incluez les cas pertinents de ces familles : - syntaxe typée, assertions de type, génériques et chaînage optionnel ; - JSX, commentaires, parenthèses supplémentaires et expressions imbriquées ou chaînées ; - propriétés calculées, modèles, syntaxe d’expansion et déstructuration ; - valeurs de retour utilisées ou non utilisées ; - analyse syntaxique seule ou informations de type complètes lorsque la règle dépend des types. Testez les cas qu’une règle ignore volontairement afin que la limite soit documentée. Vérifiez les corrections en présence de commentaires et de risques liés à l’insertion automatique des points-virgules. Si un cas nécessite un autre analyseur, configurez-le dans le plus petit périmètre de test qui exprime l’exigence. ## Ne proposer une correction automatique que si elle ne change pas l’exécution, et garder les commentaires Proposez une correction automatique uniquement lorsqu’elle ne peut pas modifier le comportement à l’exécution. Lorsque le comportement risque de changer, privilégiez une suggestion. La conservation des commentaires est obligatoire : si un remplacement ou un retrait contient des commentaires, abandonnez la correction ou utilisez une modification sensible à la plage qui les maintient en place. Avant de produire une correction, vérifiez si un remplacement nécessite des parenthèses, si un crochet ou une parenthèse initiale exige un point-virgule et si des tokens adjacents nécessitent un espacement. Utilisez des corrections génératrices pour les opérations comportant plusieurs modifications. Préservez le comportement du chaînage optionnel et évitez les modifications dangereuses lorsqu’une valeur est consommée autrement que comme expression autonome. Ne rendez pas les corrections démesurément complexes uniquement pour préserver des éléments intégrés masqués, les effets de bord d’accesseurs ou de proxys, ou les trous de tableaux clairsemés, sauf si le dépôt possède déjà une protection locale simple. Signalez le problème sans correction lorsque la sûreté ne peut pas être établie. ## Nommer la règle, la créer depuis l’ossature et la mener des tests au commit Choisissez des noms qui décrivent la structure et l’intention : utilisez des préfixes comme `no-`, `prefer-`, `require-` ou `consistent-` lorsqu’ils clarifient le comportement. Nommez la cible, et non le remplacement proposé, et évitez les noms vagues. Utilisez le mécanisme d’ossature du dépôt pour créer la mise en œuvre, le test, la documentation et les entrées d’index générées. Suivez ensuite cette séquence : 1. Ajoutez des tests qui échouent ou qui sont représentatifs. 2. Mettez en œuvre la logique de règle minimale qui les satisfait. 3. Documentez le comportement et les exclusions volontaires. 4. Exécutez les tests ciblés et la commande de lint faisant autorité. 5. Testez sur le projet lui-même, puis exécutez la suite complète à la fin. 6. Confirmez que les fichiers générés sont à jour et qu’aucun fichier temporaire ne subsiste. Respectez la convention du projet pour les messages de commit, y compris la ponctuation obligatoire autour des noms de règles et d’options. La livraison n’est terminée que lorsque le code source, les tests, la documentation, les zones générées et les résultats de validation concordent.