06. Baseline et retrait de dette

Comprendre le mécanisme

Une baseline enregistre des erreurs existantes pour permettre une adoption progressive à un niveau donné. Elle ne corrige pas les défauts et ne doit pas devenir une règle d’ignorance universelle. Son périmètre doit être versionné et relu comme de la dette : catégories, chemins, quantités et plan de retrait. Les erreurs nouvelles doivent rester visibles.

Raisonner et vérifier

Évitez de régénérer automatiquement la baseline à chaque exécution de CI, car une régression pourrait être absorbée. Une suppression doit être justifiée par un faux positif ou une dette connue, avec un périmètre étroit. Après correction, retirez l’entrée devenue inutile et gardez les mécanismes qui signalent les exceptions non pertinentes. La revue doit distinguer amélioration réelle et simple déplacement des diagnostics.

Inventaire de diagnostics

Une baseline décrit des diagnostics existants. Elle ne réécrit pas les comportements du code. Une baseline enregistre des écarts déjà connus sans corriger leur cause. Associez les entrées sensibles à un travail de résolution et conservez la possibilité de retrouver pourquoi elles ont été admises temporairement.

Nouveaux défauts visibles

Les nouvelles erreurs doivent rester visibles. Elle doit distinguer dette connue et nouvel écart. La CI doit comparer le code à la dette révisée, pas recréer cette dette avant chaque analyse. Introduisez un défaut de laboratoire pour confirmer qu’un diagnostic nouveau fait effectivement échouer le pipeline.

Régénération encadrée

La régénération doit être revue. Cette pratique peut normaliser chaque nouveau défaut. Une mise à jour d’outil peut modifier les diagnostics et nécessiter une régénération. Examinez le diff et ses raisons ; une hausse silencieuse du nombre d’erreurs masquées demande une explication.

Suppression ciblée

Une suppression doit être étroite et justifiée. Une suppression globale masque la couverture. Préférez un identifiant de diagnostic, un chemin et une justification précis à une expression globale. Une règle très large peut masquer demain une nouvelle erreur dans une zone jusque-là correcte.

Exception devenue inutile

La correction doit retirer l’exception devenue inutile. La dette doit diminuer avec les corrections. Quand le code est corrigé, retirez l’entrée associée. Vérifiez le signal d’erreur ignorée non retrouvée si configuré ; il aide à éviter que des suppressions obsolètes restent actives sans propriétaire.

Revue du diff

Le diff de baseline doit être relu. Des motifs élargis peuvent cacher davantage d’erreurs. Lisez les messages, chemins et nombres d’occurrences modifiés. Une petite variation textuelle peut cacher un élargissement important du périmètre ; le nombre total seul ne décrit pas le risque ajouté.

Exclusions

Les chemins exclus doivent être compris. La propriété du code n’a pas changé. Exclure tout un dossier supprime aussi les futurs diagnostics de ce dossier. Documentez pourquoi le code est hors périmètre et quelle autre vérification couvre ses points d’entrée réels.

Adoption progressive

Une baseline peut faciliter une montée progressive. Elle peut servir à planifier la réduction de dette. Vous pouvez viser un niveau plus strict en acceptant une dette initiale limitée. Empêchez les ajouts et retirez les entrées à mesure des corrections afin que cette stratégie produise une progression mesurable.

Faux positif démontré

Le faux positif doit être démontré. Le diagnostic peut révéler un défaut réel. Un diagnostic gênant n’est pas automatiquement faux. Réduisez le cas, vérifiez le contrat de la dépendance et fournissez une fixture prouvant pourquoi le code est sûr avant d’ajouter une suppression.

Après correction

Les tests restent nécessaires après suppression d’un diagnostic. La suppression ne prouve aucune correction runtime. Une modification de type peut changer un chemin d’erreur ou une conversion. Gardez les tests de comportement concernés ; la disparition du diagnostic ne démontre pas que les sorties métier restent conformes.

Atelier guidé : lire, expliquer et vérifier le code

vendor/bin/phpstan analyse --generate-baseline
vendor/bin/phpstan analyse

La séquence proposée génère une baseline à partir du code courant avant de l’analyser. Elle risque donc d’admettre le défaut même qu’elle devait détecter. Réorganisez la CI pour utiliser la baseline révisée du dépôt et gardez la génération comme opération de maintenance dont le diff est relu.

La baseline n’édite pas le code pour le corriger. Rien ne prouve une réduction du périmètre ignoré. L’analyse statique n’exécute pas toute la suite. Une régénération aveugle peut normaliser de nouveaux écarts.

Travail pratique : Générez une baseline de laboratoire puis introduisez une nouvelle erreur et corrigez une ancienne.

Critères de correction : La nouvelle erreur fait échouer la CI ; l’ancienne exception est supprimée après correction. Comparez le diff de baseline et refusez les motifs globaux ajoutés sans justification.