Faire de petites modifications testées dans un grand monorepo TypeScript

## Comprendre la structure et les outils du dépôt avant de modifier Considérez le guide canonique des agents du dépôt comme l'unique source d'instructions. Conservez les autres points d'entrée des agents sous forme de références succinctes et mettez à jour le guide canonique lorsque l'architecture, les outils, les versions, les processus de travail ou les règles destinées aux contributeurs changent. Identifiez : - la véritable racine du dépôt, la zone principale du code source, la zone des scripts de construction, la documentation, les applications de test et les espaces de travail générés ; - la branche de base requise, la version de l'environnement d'exécution, le gestionnaire de paquets, l'orchestrateur de tâches, l'outil d'analyse statique, le formateur de code et les systèmes d'exploitation utilisés pour l'intégration continue ; - les exportations publiques par opposition aux exportations explicitement internes ; - les vérificateurs de types propres à chaque paquet et toute répartition des versions du compilateur entre les vérifications du dépôt, les outils de l'éditeur et les consommateurs en aval de l'API. Maintenez la configuration partagée valide pour chaque parcours de compilation pris en charge. N'adoptez pas une option ou une syntaxe au seul motif que le vérificateur le plus récent l'accepte. Pour les outils d'interface modulaires, distinguez les moteurs de rendu à l'exécution, les moteurs de regroupement et les intégrations aux frameworks qui associent les deux à la configuration du framework. Préservez une architecture de démarrage rapide, par exemple grâce à une indexation statique avant le chargement à l'exécution ; un seul module utilisateur non valide ne doit pas entraîner l'indisponibilité de toute l'interface de navigation ou d'administration. ## Lancer seulement les compilations et vérifications utiles à la modification Exécutez les commandes depuis le répertoire de travail documenté et utilisez les noms de projets de l'espace de travail, et non les noms de paquets publiés, lorsque vous ciblez le graphe de tâches. Commencez par des tâches hors production, compatibles avec le cache et tenant compte des dépendances : 1. compilez le projet ou l'ensemble de paquets concerné ; 2. exécutez des vérifications de types ciblées ; 3. formatez les fichiers modifiés et soumettez-les à l'analyse statique ; 4. exécutez les tests pertinents les plus proches ; 5. validez le comportement dans l'interface de développement interne. Ne passez à la configuration de production, aux environnements isolés générés ou aux processus équivalents à l'intégration continue que si la modification dépend de l'intégration d'un modèle, du raccordement des tâches de production ou d'un comportement entre paquets. Respectez les dépendances entre tâches, sauf si vous reprenez délibérément à partir d'une phase ultérieure déjà vérifiée. Ne démarrez pas par défaut de serveurs de développement destinés à fonctionner longtemps. Les commandes qui exigent un modèle, une cible ou un environnement doivent les recevoir explicitement. Lorsqu'un environnement isolé généré échoue, utilisez l'interface interne documentée comme solution de repli pour le diagnostic avant de modifier l'architecture de construction. ## Choisir le type de test selon le code et empêcher les tests de s'influencer Adaptez la forme du test au comportement : - testez les composants rendus au moyen de scénarios placés à proximité du code et de fonctions d'interaction, y compris pour l'accessibilité et le comportement des utilisateurs ; - utilisez des tests unitaires pour les utilitaires purs, les hooks et les modules sans rendu ; - utilisez des outils visuels pour l'apparence ; - utilisez des suites de tests de bout en bout, de vérification rapide ou d'exécution pour les contrats d'intégration. Testez le comportement exporté et les effets secondaires observables, et non les détails privés de l'implémentation. Ne dupliquez pas les garanties déjà imposées par les types, les règles d'analyse statique, les interactions des scénarios ou les tests de navigateur de plus haut niveau. Pour le code lié au système de fichiers, préférez un système de fichiers en mémoire à de véritables répertoires temporaires ou au remplacement intégral de modules. Réinitialisez l'état virtuel avant chaque test, ne redirigez que les méthodes nécessaires du système de fichiers et vérifiez l'état du disque virtuel lorsque cela est utile. N'affectez jamais directement les valeurs globales ambiantes dans les tests. Utilisez les substituts globaux suivis par le framework de test et restaurez-les après chaque test, y compris pour les clés qui n'existaient pas auparavant. Une affectation directe crée entre les fichiers des fuites qui dépendent de l'ordre d'exécution. Normalisez les chemins attendus avec les utilitaires de chemins de l'environnement d'exécution afin que les vérifications du système de fichiers réussissent aussi bien sous Unix que sous Windows. ## Vérifier d'abord les hypothèses et ne pas ajouter d'abstractions inutiles Vérifiez les hypothèses relatives à l'environnement au moyen d'une petite sonde jetable avant de fonder l'architecture sur celles-ci. Ne transformez pas une croyance non vérifiée concernant les outils de regroupement, les métadonnées, les chargeurs ou la sortie générée en commentaire ou en abstraction permanente. Formalisez d'abord les hypothèses durables au moyen des types et des règles d'analyse statique existantes. Si l'application statique est peu pratique, ajoutez une vérification peu coûteuse à l'exécution, à la limite concernée, afin que les violations échouent près de leur origine. Préférez la suppression et la simplicité directe à une souplesse spéculative. N'ajoutez pas d'abstractions, de solutions de repli ou de points d'extension pour des consommateurs qui n'existent pas. Les commentaires constituent une documentation de maintenance, pas une transcription d'enquête. Expliquez la raison durable en une ou deux phrases ; omettez les identifiants de tickets, l'historique des sondes, les récits de comparaison d'octets et les références fragiles à des numéros de ligne. Couvrez largement les cas limites pour les parcours sensibles à la sécurité et les migrations de systèmes anciens. Limitez le code de compatibilité à une fenêtre de versions explicite afin qu'il puisse être retiré à la fin de la prise en charge. ## Ne pas toucher aux fichiers générés sans raison et utiliser les outils de formatage et de journalisation du dépôt Exécutez le formateur du dépôt après les modifications, puis soumettez les fichiers modifiés à l'analyse statique et lancez les tests pertinents. Utilisez les outils configurés ; ne remplacez pas les outils d'analyse abandonnés et ne formatez pas manuellement du code dont le formatage relève du formateur. Exécutez les nouveaux scripts TypeScript par le parcours natif actuel du dépôt et utilisez des extensions TypeScript explicites dans les importations lorsque la configuration l'exige. Ne migrez les anciens chargeurs que dans le périmètre modifié. Utilisez l'abstraction de journalisation du projet dans le code normal du serveur et du client. Réservez les appels directs à la console aux scripts isolés pour lesquels l'importation du journaliseur serait déraisonnable. Ne validez jamais de modifications accidentelles apportées aux fichiers générés. Un artefact généré ne peut changer que s'il s'agit de la conséquence déterministe d'une modification intentionnelle du code source dans le même travail. Sinon, laissez-le intact et signalez les dérives récurrentes du générateur. Tenez compte d'Unix et de Windows dans les chemins, les sous-processus et les tests. Considérez la couverture des plateformes par l'intégration continue comme une exigence de compatibilité et non comme un nettoyage facultatif. ## Terminer une modification en vérifiant son comportement, pas seulement la compilation Pour une modification ordinaire : 1. installez les dépendances uniquement si nécessaire ; 2. compilez le graphe de dépendances pertinent ; 3. effectuez la plus petite modification cohérente ; 4. recompilez les paquets concernés ; 5. exécutez des vérifications de types ciblées, le formatage, l'analyse statique et les tests adaptés au contrat ; 6. validez dans l'interface interne ; 7. ajoutez des vérifications en environnement isolé ou équivalentes à la production uniquement lorsqu'elles sont directement pertinentes. Pour l'intégration d'un moteur de rendu, d'un framework, d'un outil de construction ou d'une extension, modifiez le paquet responsable, compilez-le d'abord hors mode production, puis testez-le au moyen d'une application générée correspondante et du processus d'exécution ou de bout en bout pertinent. Si une construction échoue, actualisez les dépendances et réessayez la compilation ciblée avant d'augmenter la mémoire ou de modifier l'architecture. Examinez les sorties générées et les caches lorsque le comportement de l'environnement isolé diffère de celui de l'interface interne. Ne déclarez pas la modification prête sur la seule base de la compilation. Les preuves requises correspondent au plus petit ensemble couvrant la limite du paquet modifié, les parcours de compilation pris en charge, le comportement observable, les hypothèses multiplateformes et le processus d'intégration directement concerné.