Builds reproductibles pour bases de code héritées : arrêter la dérive

Pourquoi les projets hérités cassent entre les machines

Les bases de code héritées échouent souvent de la façon la plus agaçante : de manière non consistante. Un développeur peut lancer l’app sans problème, un autre obtient une erreur cryptique. CI passe le matin et échoue l’après-midi. Un petit changement apparemment inoffensif est déployé, et la production se comporte différemment.

Cette dérive du « ça marche sur ma machine » signifie que le code n’est pas la seule chose qui détermine si votre build réussit. Des différences cachées entre les laptops, les runners CI et les serveurs de production modifient ce qui est installé, comment ça s’exécute, et ce qui est finalement déployé.

Le pire, c’est l’aléatoire. On finit par ne plus faire confiance aux tests parce qu’ils sont instables. On perd du temps à chasser des bugs qu’on ne peut pas reproduire. Et on commence à appliquer des rustines risquées (comme épingler une dépendance à la main) juste pour débloquer la situation, ce qui peut créer de nouvelles surprises plus tard.

La plupart des causes sont simples et réparables :

• Versions différentes de Node.js (même de petites différences peuvent casser des modules natifs ou des outils)
• Lockfiles manquants ou ignorés, si bien que les installations tirent des arbres de dépendances légèrement différents
• Outils globaux (npm, yarn, pnpm, TypeScript, ESLint) différents selon les machines
• Scripts postinstall qui se comportent différemment selon l’OS ou le shell
• Cache CI qui masque des problèmes qu’une installation propre révélerait

L’objectif est simple : les mêmes entrées doivent produire les mêmes sorties partout. Même version de Node, même gestionnaire de paquets, même graphe de dépendances, mêmes étapes de build, mêmes artefacts.

Une fois la dérive éliminée, les échecs cessent d’être aléatoires. Quand quelque chose casse, ça casse pour tout le monde, au même endroit, avec la même erreur. C’est à ce moment-là qu’un projet hérité redevient maintenable.

Ce que signifie une build reproductible dans les projets Node

Une build reproductible signifie que vous pouvez prendre le même code, lancer les mêmes commandes, et obtenir le même résultat à chaque fois. Dans les projets Node, ce « résultat » n’est pas seulement « ça tourne sur mon laptop ». Il doit se comporter de la même manière pour tous les membres de l’équipe, en CI et en production.

Si une machine utilise Node 18 et une autre Node 20, ou si une installation récupère des paquets plus récents qu’une autre, vous n’avez pas vraiment le même projet.

Dans un repo Node sain, ces éléments doivent être cohérents :

• Installation : un clone propre s’installe sans correctifs manuels
• Sortie de build : les mêmes sources produisent des artefacts fonctionnellement identiques
• Tests : le même run de tests passe ou échoue pour les mêmes raisons
• Scripts : npm run build (ou équivalent) se comporte de la même façon partout
• Erreurs : quand quelque chose casse, ça casse de la même manière, pas aléatoirement

Certaines choses ne seront pas identiques par conception. Les timestamps dans les bundles, les chemins spécifiques à la machine, les variables d’environnement, ou les appels vers des services externes peuvent ajouter du bruit. La solution n’est pas d’ignorer leur existence, mais de rendre déterministes les dépendances, les versions d’outils et les étapes de build, puis de séparer la configuration d’exécution au moment du runtime.

Vous pouvez généralement repérer l’absence de reproductibilité quand une installation propre échoue, ou quand CI échoue mais que les laptops passent. Un autre signal fort est quand la suppression de node_modules change le comportement, ou quand deux coéquipiers obtiennent des versions différentes d’une même dépendance après install.

Si vous ne pouvez pas cloner le repo sur une machine neuve et obtenir une build réussie avec un petit ensemble de commandes documentées, la dérive a déjà commencé.

Choisir une seule source de vérité pour les versions et les scripts

Les projets hérités cassent parce que les règles vivent dans la tête des gens. Un dev utilise Node 18, CI utilise Node 20, la production est encore sur 16, et personne ne le remarque jusqu’à ce qu’une dépendance change de comportement. Choisissez un endroit dans le repo où la vérité est écrite et appliquée.

Commencez par décider où déclarer les versions. Placez-les dans des fichiers qui voyagent avec le code, pas dans une ligne de README qui devient vite obsolète. Les choix courants sont un fichier de version Node géré par le repo, un paramètre de version du gestionnaire de paquets, et (si vous utilisez des conteneurs) une étiquette d’image de base qui ne flotte pas.

Ensuite, mettez-vous d’accord sur les points d’entrée du build. Tout le monde doit exécuter les mêmes commandes pour l’installation, le build et les tests. S’il y a plusieurs façons de builder (scripts personnalisés, flags ad hoc, dossiers différents), la dérive reviendra.

Une règle utile : si CI ne peut pas l’exécuter à partir d’un checkout propre en utilisant les scripts du projet, ce n’est pas une partie officielle du build.

Avant de changer quoi que ce soit, capturez une base à partir d’un état propre et notez-la : la commande utilisée, la version de Node, le gestionnaire de paquets, et si les tests passent. Cela vous donne une référence quand quelque chose casse après le durcissement des règles.

Verrouiller les versions de Node et du gestionnaire de paquets

La plupart des bugs « ça marche sur ma machine » commencent avant que votre code d’application n’exécute quoi que ce soit. Si une personne est sur Node 18, CI sur Node 20 et la production sur Node 16, vous testez trois applications différentes.

Verrouillez Node dans un endroit que les développeurs verront et suivront. Un simple .nvmrc ou .node-version dans le repo rend la version attendue visible dès l’ouverture du projet. Sauvegardez-la aussi dans package.json pour que les outils puissent avertir (ou échouer) si la version est incorrecte.

Puis verrouillez la version du gestionnaire de paquets. Se fier à ce qui est installé globalement (npm/yarn/pnpm) invite des changements silencieux dans la résolution des dépendances. Fixez-le au niveau du projet pour que tout le monde installe de la même façon, dans tous les environnements.

{
  "engines": {
    "node": ">=20 <21"
  },
  "packageManager": "[email protected]"
}

Ajoutez une vérification rapide de version qui s’exécute avant les installations ou les tests. Elle doit échouer avec un message clair, pas une erreur mystérieuse 10 minutes plus tard. Restez strict :

• Vérifier que node -v correspond à la version majeure épinglée
• Vérifier que la version du gestionnaire de paquets correspond à packageManager
• Faire échouer CI immédiatement si l’un ou l’autre ne correspond pas

Imposer les lockfiles et des installations déterministes

Les lockfiles font la différence entre « nous avons tous installé des dépendances » et « nous avons tous installé les mêmes dépendances ». Cette homogénéité évite les cassures aléatoires quand une dépendance transitive publie un correctif.

D’abord, choisissez un seul gestionnaire de paquets et engagez-vous à l’utiliser. Les outils mélangés créent de la dérive silencieuse : une personne utilise npm, une autre Yarn, CI utilise pnpm, et vous vous retrouvez avec des arbres de dépendances différents même sans modification de package.json.

Nettoyez le repo pour qu’il n’y ait qu’un seul lockfile correspondant à l’outil choisi (package-lock.json, yarn.lock ou pnpm-lock.yaml). Si vous en voyez plusieurs, considérez cela comme un bug, pas comme une préférence.

Utiliser des commandes d’installation qui refusent les surprises

Les installations déterministes échouent rapidement quand le lockfile et package.json sont en désaccord. C’est ce que vous voulez.

# npm
npm ci

# Yarn (Berry)
yarn install --immutable

# pnpm
pnpm install --frozen-lockfile

Si l’installation échoue, corrigez le lockfile proprement au lieu d’assouplir les règles. Le but est d’arrêter les changements cachés.

Rendre le lockfile non optionnel

Traitez les modifications de lockfile comme des modifications de code : révisez-les et bloquez les merges qui les oublient.

• CI échoue si package.json a changé mais pas le lockfile
• CI échoue si le repo contient plusieurs lockfiles
• Les réviseurs rejettent « j’ai lancé l’install et ça a mis à jour plein de choses » sans raison claire
• Les montées de dépendances sont groupées et expliquées, pas mélangées aux PRs de fonctionnalités

Faire en sorte que CI se comporte comme une machine propre

Beaucoup de dérive survit parce que les laptops portent un état caché. CI doit être l’opposé : une machine propre, à chaque exécution, utilisant exactement les mêmes étapes d’installation et de build que celles que l’équipe utilise localement.

Traitez chaque exécution CI comme un nouveau checkout. Ne vous fiez pas à des node_modules restants, des fichiers générés ou des outils globaux. Si la build ne passe que quand quelque chose existe déjà, ce n’est pas une vraie build.

Conservez un script comme source de vérité. Si les développeurs exécutent npm run build, CI doit lancer ce script exact, pas une chaîne de commandes personnalisée.

Une approche CI pratique :

• Checkouter dans un workspace propre à chaque exécution
• Installer depuis le lockfile uniquement (pas d’install « best effort »)
• Exécuter les mêmes scripts que local : lint, test, build
• Échouer quand quelque chose d’important est hors service (conflits de peer dependencies, variables d’environnement manquantes, erreurs de typage)
• Sauvegarder les artefacts seulement après la réussite du build

Le cache peut aider, mais il peut aussi masquer des problèmes. Mettez en cache uniquement ce qui est sans risque de réutilisation, et invalidez-le quand les dépendances changent.

• Cachez le cache de téléchargement du gestionnaire de paquets (pas node_modules)
• Clef du cache basée sur le hash du lockfile
• Bustez le cache quand la version de Node.js ou du gestionnaire change

Aligner la production avec ce que CI a réellement buildé

Beaucoup de bugs « ça marche sur ma machine » apparaissent après le déploiement parce que la production n’exécute pas la même chose que ce que CI a testé. Traitez CI comme l’endroit où la réalité est décidée, et faites en sorte que la production corresponde.

D’abord, choisissez où les builds ont lieu et tenez-vous-en :

• Builder en CI et déployer l’artefact fini (ou l’image de conteneur), ou
• Builder en production, mais alors la production doit utiliser exactement la même version de Node, le même gestionnaire et les mêmes commandes d’installation que CI

Mélanger ces deux approches est la façon la plus sûre d’obtenir des changements surprises de dépendances.

Si vous utilisez Docker, épinglez l’étiquette d’image de base au lieu d’un tag flottant. Un petit changement d’image de base peut changer Node, OpenSSL ou des libs système et créer un « même code, comportement différent » au déploiement. Mettez à jour l’image de base volontairement, puis laissez CI la tester.

Séparez les variables d’environnement du résultat du build. Les secrets et valeurs spécifiques aux environnements doivent être injectés au runtime, pas intégrés dans un bundle compilé ou committés dans des fichiers de config. C’est à la fois un problème de sécurité et de reproductibilité.

Enfin, vérifiez que l’exécution déployée correspond bien à ce que vous avez épinglé. Si CI utilise Node 20, la production ne doit pas tourner silencieusement sur Node 18.

Étapes pas à pas : enlever la dérive sans bloquer l’équipe

La dérive commence souvent petit : une personne met à jour Node, une autre supprime le lockfile, CI utilise une commande d’install différente, et la production récupère un arbre de dépendances légèrement différent. Réparez en phases pour ne pas bloquer le travail quotidien.

Commencez par une base, puis durcissez les règles progressivement :

• Capturez la réalité actuelle : version de Node, gestionnaire de paquets, commande d’installation, et présence/utilisation du lockfile
• Choisissez et épinglez les versions attendues : ajoutez un fichier de version Node et fixez la version du gestionnaire pour que tout le monde utilise les mêmes outils
• R rendez les installations déterministes partout : mettez à jour CI pour utiliser des installs propres et builder depuis un workspace propre à chaque run
• Prouvez que ça marche depuis zéro : faites un test de « fresh clone » sur une nouvelle machine ou un dossier propre, puis buildez en mode proche de la production
• Appliquez les règles après validation : ajoutez des checks fail-fast (mismatch Node, changements manquants de lockfile) et protégez le lockfile contre les éditions non intentionnelles

Un motif fréquent avec les prototypes hérités générés par IA est que l’épinglage de Node et l’obligation d’installations gelées transforment une erreur aléatoire en une erreur cohérente et lisible (dépendance manquante, engine incompatible, ou script qui ne fonctionnait que sur une machine). Une fois cohérent, c’est corrigeable.

Erreurs courantes qui recréent le « ça marche sur ma machine »

La plupart des équipes partent d’intentions saines, puis de petits raccourcis ramènent la dérive. L’objectif est simple : le même code doit se builder de la même façon sur un laptop, en CI et en production.

Un piège courant est d’utiliser une installation « best effort » en CI. npm install peut mettre à jour le lockfile, tirer des arbres de dépendances légèrement différents, ou se comporter différemment selon la version de npm. C’est comme ça qu’une build verte locale devient rouge en CI le lendemain.

Une autre erreur est de traiter node_modules comme partie intégrante du projet. Le committer, le cacher trop agressivement, ou supposer qu’il est déjà présent masque de vrais problèmes de dépendances. Alors une machine propre (ou un runner CI propre) devient le premier endroit où les problèmes apparaissent.

Aussi : choisissez un seul gestionnaire de paquets. Quand un repo mélange npm, Yarn et pnpm, les gens vont « réparer » un problème en changeant de commande. Ça marche une fois, puis cela modifie silencieusement le graphe de dépendances.

Les recréateurs de dérive qui reviennent souvent :

• CI utilise une installation non déterministe (par exemple, met à jour le lockfile durant le build)
• Le repo dépend d’un node_modules existant au lieu d’une installation propre
• Plusieurs gestionnaires et plusieurs lockfiles coexistent dans le même repo
• Les builds dépendent d’outils CLI globaux (présents sur la machine de quelqu’un, absents en CI)
• Images Docker ou runtime non épinglées (par exemple latest)

Checklist rapide avant de faire confiance à la build

Avant de passer une journée à « réparer CI », prouvez que le projet peut builder depuis zéro sur une machine propre. S’il échoue là, il échouera en production tôt ou tard.

Les 5 vérifications qui attrapent la majorité des dérives

Commencez par un test de fresh clone. Sur un nouveau laptop ou dans un dossier temp propre (pas d’ancien node_modules), lancez l’installation, le build et les tests exactement comme écrit dans le dépôt. Si des étapes supplémentaires non documentées sont nécessaires, vous n’avez pas encore une build fiable.

Confirmez les versions. La version de Node.js et celle du gestionnaire doivent correspondre à ce que le repo attend, pas à ce qui est installé globalement.

Vérifiez le lockfile. Il doit y avoir exactement un lockfile, il doit être commité, et il ne doit changer que lorsque vous mettez à jour les dépendances volontairement.

Assurez-vous que CI installe de manière déterministe. CI doit utiliser la commande d’installation propre à votre outil (par exemple npm ci plutôt que npm install) pour qu’il ne puisse pas réécrire le lockfile ou tirer des dépendances transitoires plus récentes en silence.

Vérifiez que la production correspond à ce que CI a buildé. La version de Node en production doit correspondre à la version épinglée, et votre déploiement doit expédier le même artefact que CI a créé (plutôt que de rebuild en production avec un environnement différent).

Exemple : stabiliser un prototype hérité généré par IA

Un fondateur hérite d’une app Node générée par un outil IA. Elle tourne sur le laptop du dev original, mais CI échoue avec des erreurs vagues comme « Cannot find module », « Unsupported engine », ou des tests qui passent localement et échouent en CI.

Après une vérification rapide, le schéma est familier :

• Le dev local est sur Node 20, CI sur Node 18, et la production sur Node 16
• Il n’y a pas de lockfile (ou il est ignoré), donc chaque install récupère des versions légèrement différentes
• CI restaure des dépendances mises en cache et ne se comporte jamais comme une machine propre

La solution n’est pas sophistiquée. Il s’agit de rendre la build déterministe, puis de forcer tous les environnements à la respecter.

Épinglez Node.js (et le gestionnaire), ajoutez ou restaurez le lockfile, passez CI en mode d’install strict, et effectuez au moins une installation froide localement (supprimez node_modules, installez à neuf) pour prouver que votre laptop ne masque pas les problèmes.

Le résultat visé est ennuyeux : le même commit produit le même arbre de dépendances et le même résultat de build partout.

Étapes suivantes si votre build héritée reste instable

Si vous voyez encore des bugs « ça marche sur ma machine » après les basiques, ne changez pas cinq choses à la fois. Standardisez dans un ordre strict : versions d’abord, lockfiles ensuite, puis règles CI. Chaque étape doit éliminer des variables.

Notez ce que vous traiterez comme vérité pour ce repo : la version de Node.js, le gestionnaire de paquets et sa version, et la commande d’installation unique que tout le monde doit utiliser. Gardez ce jeu de règles petit et visible.

Si le code lui-même est en désordre (surtout les prototypes générés par IA), les builds reproductibles sont la première tâche de réparation, pas un luxe. Tant que les builds ne sont pas prévisibles, chaque autre correction est plus difficile à vérifier.

Si vous avez besoin d’aide rapide, FixMyMess (fixmymess.ai) se concentre sur la prise en charge d’apps générées par IA et la mise en production. Un audit gratuit du code peut repérer d’où vient la dérive (versions, lockfiles, scripts cachés), puis l’équipe peut corriger la build et les problèmes sous-jacents en une passe.