Calculateur SemVer

Que sont les plages SemVer ?

Alors que le versionnage semantique definit comment numeroter les versions, la syntaxe des plages SemVer definit comment exprimer quelles versions sont acceptables en tant que dependances. La syntaxe des plages est le langage que les gestionnaires de paquets comme npm, Yarn, Cargo et Composer utilisent pour determiner quelles versions d’une dependance sont compatibles avec votre projet.

Quand vous ecrivez "lodash": "^4.17.21" dans votre package.json, vous declarez une plage : “toute version de lodash superieure ou egale a 4.17.21 et inferieure a 5.0.0.” Le gestionnaire de paquets utilise cette plage pour selectionner la meilleure version correspondante depuis le registre, en equilibrant l’obtention des derniers correctifs et l’evitement des changements incompatibles.

Comprendre la syntaxe des plages est essentiel pour tout developpeur qui gere des dependances. Des plages mal configurees sont une source frequente de bugs “ca marche sur ma machine”, de builds casses et de problemes inattendus en production.

Caret (^) vs Tilde (~)

Les deux operateurs de plage les plus couramment utilises sont le caret (^) et le tilde (~). Ils sont utilises par defaut dans la plupart des gestionnaires de paquets, et leur comportement differe de maniere critique.

Caret (^) — Compatible avec la version

Le caret autorise les modifications qui ne changent pas le chiffre non nul le plus a gauche :

Plage	Equivalent	Autorise
^1.2.3	>=1.2.3 <2.0.0	Mises a jour mineures et correctifs
^0.2.3	>=0.2.3 <0.3.0	Correctifs uniquement
^0.0.3	>=0.0.3 <0.0.4	Rien (correspondance exacte)

Le caret est l’operateur par defaut dans npm. Lorsque vous executez npm install lodash, la version enregistree dans package.json utilise le prefixe caret (par ex. ^4.17.21). Pour les versions 1.0.0 et superieures, c’est generalement sur car SemVer garantit la retrocompatibilite au sein de la meme version MAJEURE.

Cependant, pour les versions 0.x, le caret devient beaucoup plus restrictif. ^0.2.3 n’autorise que les mises a jour de correctifs car la version MINEURE est le chiffre non nul le plus a gauche. Cela protege contre l’instabilite que SemVer autorise pendant le developpement initial.

Tilde (~) — Approximativement equivalent

Le tilde n’autorise que les modifications au niveau des correctifs si une version MINEURE est specifiee :

Plage	Equivalent	Autorise
~1.2.3	>=1.2.3 <1.3.0	Correctifs uniquement
~1.2	>=1.2.0 <1.3.0	Correctifs uniquement
~1	>=1.0.0 <2.0.0	Mises a jour mineures et correctifs

Le tilde est plus restrictif que le caret pour les versions >= 1.0.0. Alors que ^1.2.3 accepterait 1.9.0, ~1.2.3 ne l’accepterait pas — il plafonne a la prochaine version MINEURE.

Operateurs de comparaison

Au-dela du caret et du tilde, la syntaxe des plages SemVer prend en charge des operateurs de comparaison explicites qui offrent un controle precis :

Operateur	Signification	Exemple	Se resout en
>=	Superieur ou egal	>=1.2.3	1.2.3 et au-dessus (pas de limite superieure)
>	Superieur a	>1.2.3	Au-dessus de 1.2.3, sans l’inclure
<=	Inferieur ou egal	<=2.0.0	2.0.0 et en dessous
<	Inferieur a	<2.0.0	En dessous de 2.0.0, sans l’inclure
=	Correspondance exacte	=1.2.3	Uniquement 1.2.3

Vous pouvez combiner les operateurs pour definir des plages precises :

>=1.2.3 <2.0.0     # Identique a ^1.2.3
>=1.0.0 <1.3.0     # 1.0.0 jusqu'a 1.2.x

Plages avec tiret

Un tiret entre deux versions definit une plage inclusive :

1.2.3 - 2.3.4     # >=1.2.3 <=2.3.4
1.2 - 2.3.4       # >=1.2.0 <=2.3.4
1.2.3 - 2.3       # >=1.2.3 <2.4.0

Lorsqu’une version partielle est utilisee du cote droit, les composants manquants sont traites comme des caracteres generiques jusqu’a la prochaine limite significative. 1.2.3 - 2.3 signifie “jusqu’a mais sans inclure 2.4.0.”

Plages X et caracteres generiques

Chacun des trois composants de version peut etre remplace par x, X ou * pour indiquer “n’importe quelle valeur” :

Plage	Equivalent	Description
*	>=0.0.0	N’importe quelle version
1.x	>=1.0.0 <2.0.0	N’importe quelle version 1.x.x
1.2.x	>=1.2.0 <1.3.0	N’importe quelle version 1.2.x
"" (vide)	>=0.0.0	Identique a *

Les plages X sont utiles pour exprimer clairement l’intention : 1.x signifie “je depend de l’API v1” sans specifier quelle version mineure ou de correctif.

Combiner des plages avec OU (||)

L’operateur double barre (||) combine plusieurs plages. Une version satisfait la plage combinee si elle correspond a n’importe laquelle des sous-plages :

^1.2.3 || ^2.0.0          # 1.x (>=1.2.3) OU 2.x
>=1.0.0 <1.5.0 || >=2.0.0 # 1.0-1.4.x OU 2.0+

C’est utile lorsqu’une bibliotheque prend en charge plusieurs versions majeures d’une dependance pair. Par exemple, une bibliotheque de composants React pourrait declarer "react": "^17.0.0 || ^18.0.0" pour prendre en charge React 17 et React 18.

Tableau de reference des plages SemVer

Syntaxe	Equivalent	Defaut npm ?	Cas d’utilisation
^1.2.3	>=1.2.3 <2.0.0	Oui (defaut)	Accepter les mises a jour mineures + correctifs
~1.2.3	>=1.2.3 <1.3.0	Non	Accepter les correctifs uniquement
1.2.3	=1.2.3	Non	Version exacte (epinglee)
>=1.0.0 <2.0.0	Identique	Non	Plage explicite
1.2.x	>=1.2.0 <1.3.0	Non	Correctif generique
*	>=0.0.0	Non	N’importe quelle version
^1.2.3 || ^2.0.0	Union	Non	Plusieurs versions majeures

Cas d’utilisation courants

• Dependances npm / Yarn : Le champ dependencies du package.json utilise les plages SemVer pour declarer les versions de dependances acceptables. Le caret (^) est l’operateur par defaut.
• Dependances pair : Les bibliotheques declarent des dependances pair avec des plages pour prendre en charge plusieurs versions majeures de frameworks (par ex. "react": "^17.0.0 || ^18.0.0").
• Contraintes CI/CD : Les pipelines de build utilisent des plages pour specifier les versions d’outils, assurant des builds coherents tout en recevant les mises a jour de correctifs.
• Fichiers de verrouillage : package-lock.json et yarn.lock figent les versions exactes resolues, tandis que les plages dans package.json definissent l’espace de versions acceptable.
• Protocoles de workspaces monorepo : Les outils monorepo (Turborepo, Lerna, pnpm) utilisent les plages SemVer pour gerer les dependances inter-paquets au sein du workspace.
• Images de conteneurs : Les directives FROM des Dockerfiles utilisent des tags de version suivant les conventions SemVer (par ex. node:18.17 pour le dernier correctif 18.17.x).