Reproduire le comportement d’un autre framework web avec une couche de compatibilité

## Utiliser les tests et le code du framework de référence comme spécification Traitez la compatibilité comme une question de preuve. Les tests et l’implémentation du framework cible définissent le comportement attendu de manière plus fiable que l’intuition. Pour chaque fonctionnalité ou correction de bogue : 1. Effectuez une recherche large dans les suites de tests unitaires et de bout en bout du projet de référence, notamment sur les noms associés, les erreurs, les entrées non valides et les cas limites. 2. Lisez l’implémentation correspondante pour comprendre l’ordre, les valeurs par défaut et le comportement en cas d’échec. 3. Recherchez les issues ou les discussions de conception antérieures lorsque le code n’indique pas si un comportement est intentionnel. 4. Portez les cas pertinents avant d’implémenter le changement et reliez chaque portage à son test de référence. 5. Documentez les preuves dans la description du changement. Utilisez un clone local superficiel pour rechercher rapidement dans le code source et les tests. N’utilisez la recherche de code à distance que si le clone est indisponible ou si la question exige de consulter les discussions actuelles. Si la couche de compatibilité doit intentionnellement différer pour des raisons de sécurité, de déploiement ou de plateforme, consignez explicitement cette décision. Ne laissez jamais une divergence accidentelle se faire passer pour une fonctionnalité. ## Écrire d’abord un test qui échoue et corriger ensemble tous les points d’entrée Écrivez d’abord un test ciblé qui échoue, puis implémentez le plus petit changement satisfaisant au contrat vérifié. - Exécutez le fichier de test du sous-système modifié, ainsi que les tests qui lui sont directement couplés. - Ajoutez des entrées de fixture pour le comportement d’intégration ; réservez les exemples aux démonstrations destinées aux utilisateurs. - Utilisez des filtres par nom de test pendant les itérations. - Laissez la CI exécuter la suite complète, sauf si le changement touche le routage partagé, l’infrastructure de build, les modules virtuels ou des auxiliaires de test communs. - Lorsque l’infrastructure partagée change, n’étendez la validation locale qu’aux surfaces transversales concernées. Associez la validation à la responsabilité : les shims nécessitent des tests de shims, le routage des tests d’ordre des routes, la mise en cache des tests de cache, et les changements de build ou de déploiement des tests de build. Le traitement des requêtes se trouve souvent dans des points d’entrée distincts pour le développement, la production, le rendu côté serveur et l’edge. Vérifiez chaque implémentation responsable du même comportement et corrigez les écarts de parité dans le même changement, au lieu de laisser en place des doublons connus. ## Transmettre les données de requête entre environnements et garder le code généré léger Des environnements de build ou de rendu distincts peuvent posséder des graphes de modules et des états de modules indépendants. Ne supposez jamais que définir l’état d’une requête dans un environnement modifie un autre environnement. - Transmettez explicitement le `pathname`, les paramètres, les en-têtes, les cookies et tout autre contexte de requête à travers les limites entre environnements. - Initialisez le contexte immédiatement avant le rendu, puis nettoyez-le après. - Séparez l’état propre à la requête et les petites façades publiques des implémentations lourdes. - Vérifiez à la fois la consommation en streaming et le moment du nettoyage. Les modules d’entrée générés ne doivent contenir que les importations propres aux routes, les manifestes et un raccordement léger. Déplacez l’orchestration des requêtes, la politique de cache, la répartition par méthode, les redirections, la gestion des erreurs, la fusion des en-têtes et tout autre comportement testable dans des modules typés ordinaires. Testez directement les auxiliaires extraits avec des tests unitaires. Les tests du code généré doivent vérifier la délégation et le raccordement, plutôt que de comparer de longues chaînes d’implémentation. Maintenez une frontière de responsabilité claire entre le plugin du bundler sous-jacent et la couche de compatibilité. Le plugin peut prendre en charge les transformations, la sérialisation, les builds multi-environnements, le traitement CSS et l’amorçage de l’hydratation, tandis que la couche de compatibilité prend en charge le routage, le cycle de vie des requêtes, la composition des layouts, la navigation, la mise en cache et les shims d’API. ## Normaliser les chemins de fichiers et construire avec le pipeline multi-environnement complet Les chemins de système de fichiers utilisés comme identifiants de modules ou importations générées doivent suivre une même politique de séparateur canonique sur tous les systèmes d’exploitation. - Dans le code source, utilisez une abstraction de chemin qui préserve la sémantique native tout en renvoyant des identifiants canoniques. - Ne normalisez que les valeurs provenant de l’extérieur, comme les répertoires de travail des processus, les modules résolus, les chemins réels, les résultats de glob et les identifiants signalés par le bundler. - Ne normalisez pas plusieurs fois les valeurs déjà produites par la couche de chemins canoniques. - Séparez l’assainissement des barres obliques inverses dans les URL du traitement des chemins de système de fichiers. - Documentez et contrôlez par lint toute véritable exception de chemin natif. Les tests doivent construire leurs entrées avec les API de chemins natives afin que Windows fournisse de véritables barres obliques inverses. Ne canonicalisez que les sorties attendues. Des tests multiplateformes entièrement construits avec des barres obliques ne peuvent pas détecter une régression de normalisation sous Windows. Les builds de production doivent utiliser le pipeline complet du builder multi-environnements du plugin du framework. Un appel de build générique pour un seul environnement peut omettre silencieusement des phases requises pour le serveur, le moteur de rendu et le client. Lorsque la chaîne d’outils change de version majeure, privilégiez les familles actuelles d’options de transformateur, d’optimiseur de dépendances et de bundler. Traitez les anciens noms d’options comme des cibles de migration. Les modules virtuels nécessitent aussi une gestion explicite des identifiants préfixés par la racine, des préfixes nuls déjà résolus et des importations absolues lorsqu’aucun emplacement physique de module n’existe. ## Garder les requêtes courantes légères et définir le comportement du cache Écartez les environnements d’exécution propres à une fonctionnalité du chemin courant des requêtes. - Conditionnez les comportements facultatifs à l’aide de métadonnées peu coûteuses de requête ou de route avant de les importer dynamiquement. - Utilisez des importations de types uniquement lorsque du code d’exécution n’est pas nécessaire. - Filtrez les hooks du bundler avant l’exécution des gestionnaires JavaScript, en excluant les dépendances, les environnements d’exécution générés, les prébundles et les cibles syntaxiques impossibles. - Séparez les modules légers d’état et d’enregistrement des implémentations de cache, de navigation ou de rendu. - Réutilisez les clés de cache calculées et les dérivations de requêtes. - Remontez les expressions et tableaux immuables. - Déplacez si possible l’analyse déterministe et la sélection des ressources au moment du build. N’ajoutez pas de mise en cache tant que la responsabilité, l’invalidation et la parité entre environnements d’exécution ne sont pas explicites. Un graphe de modules plus petit n’est pas un avantage s’il provoque du code périmé, des conditions d’exécution différentes ou des bundles de plateforme défectueux. Gardez les gestionnaires de stockage simples et placez au-dessus d’eux la politique de régénération incrémentielle. Définissez séparément le comportement `stale-while-revalidate`, la régénération `single-flight`, les métadonnées de revalidation et l’invalidation par tag. Les entrées arrivées à expiration peuvent être renvoyées périmées pendant la régénération ; les entrées explicitement invalidées doivent être supprimées. Rendez la sélection du backend déclarative, conservez une valeur par défaut sûre et enregistrez les adaptateurs facultatifs avant leur première utilisation. ## Traiter les requêtes dans le même ordre que le framework de référence Modélisez le cycle de vie des requêtes du framework cible comme un contrat ordonné : 1. Les en-têtes de configuration statique sont évalués par rapport à la requête d’origine. 2. Les redirections statiques sont évaluées par rapport à la requête d’origine. 3. Le middleware s’exécute et peut réécrire, rediriger ou modifier les en-têtes. 4. Les réécritures antérieures au système de fichiers sont évaluées par rapport à l’état après middleware. 5. Les routes statiques et du système de fichiers sont résolues. 6. Les réécritures postérieures au système de fichiers s’exécutent. 7. Les routes dynamiques sont résolues. 8. Les réécritures de repli s’exécutent. Ne déplacez pas une étape simplement parce que la réponse finale paraît équivalente. La correspondance conditionnelle peut changer lorsque le middleware modifie la requête. Consignez les écarts de parité connus au lieu de les masquer. Préservez les distinctions intentionnelles, par exemple entre les ressources statiques qui contournent le middleware et les fichiers publics qui le traversent. Pour les API en évolution, ne prenez en charge les anciens et nouveaux modes d’accès que lorsque le contrat de compatibilité exige les deux. Une promesse enrichie de champs résolus, par exemple, peut permettre à la fois l’accès aux paramètres avec attente et l’accès direct. Les bibliothèques tierces qui utilisent des importations d’API publiques peuvent fonctionner grâce à des alias ou à la normalisation des extensions. Celles qui dépendent de plugins de build ou d’API internes exigent une intégration explicite ; les installer et les importer ne suffit pas. ## Ne pas contourner le lockfile et fusionner seulement par une pull request validée Ne contournez jamais un lockfile figé lors d’une installation sans surveillance. Si la résolution des dépendances exige réellement de modifier le lockfile, arrêtez-vous et demandez à l’utilisateur d’effectuer ou d’autoriser cette opération. Les versions exactes et les hachages d’intégrité constituent une frontière de sécurité de la chaîne d’approvisionnement. Ne poussez jamais directement vers la branche par défaut protégée, ne contournez pas sa protection et ne forcez pas une fusion administrative. Suivez cette séquence : 1. Créez une branche de fonctionnalité ciblée. 2. Apportez le plus petit changement cohérent et exécutez les vérifications ciblées. 3. Effectuez le commit selon la convention de message exigée par le dépôt. 4. Poussez la branche et ouvrez une pull request. 5. Attendez que toutes les vérifications obligatoires de format, de types, unitaires et de bout en bout réussissent. 6. Corrigez les échecs au lieu de les contourner. 7. Fusionnez par la méthode approuvée et supprimez la branche. Laissez l’automatisation de publication dériver les métadonnées du changelog à partir des conventional commits. N’utilisez les mécanismes de remplacement documentés que pour une reclassification rétroactive délibérée ; ne modifiez pas manuellement les artefacts de publication générés. Pour les refactorisations importantes, utilisez de petits changements empilés qui extraient chacun une frontière cohérente, ajoutent des tests ciblés pour les auxiliaires et mettent à jour les assertions de délégation. La CI pour les contributions non fiables doit s’exécuter sans secrets et avec des autorisations en lecture seule. Les workflows de prévisualisation contenant des secrets doivent ignorer les forks, sauf si un mainteneur autorisé les déclenche explicitement au moyen d’une commande contrôlée par l’identité. Chaque exemple déployé doit être enregistré dans la matrice de build et disposer d’un smoke test qui vérifie la route, le statut et le contenu attendus. La publication ou le déploiement n’est terminé qu’après la réussite des vérifications requises et des preuves postérieures au déploiement.