Analyseur et comparateur SemVer

Qu’est-ce qu’un analyseur de version sémantique ?#

La version sémantique (SemVer) est la convention majeure.mineure.correctif que la plupart des bibliothèques utilisent pour signaler le type de changement que contient une release : un correctif de bogue incrémente correctif, des ajouts compatibles ascendantes incrémentent mineure, et des changements cassants incrémentent majeure. Ajoutez une étiquette de pré-version (1.0.0-beta.1) ou des métadonnées de build (+exp.sha.1) et vous obtenez la grammaire complète définie par semver.org 2.0.0.

Le problème, c’est que « comparer deux versions » et « cette version satisfait-elle ma plage de dépendance » sont faciles à se tromper à l’œil. 1.0.0 est-il supérieur ou inférieur à 1.0.0-beta ? (Supérieur — une release surpasse toujours sa pré-version.) 1.2.3 satisfait-il ^1.2.0 ? (Oui.) Satisfait-il ~1.2.0 ? (Aussi oui, mais pour une raison plus serrée.) Cette page analyse les versions comme la spec les définit, vous montre les composants, compare deux versions par précédence, et répond aux requêtes de plage avec la même syntaxe ^ / ~ / >= / || / tiret qu’un package.json utilise — le tout localement, selon les vraies règles plutôt qu’une supposition.

Comment l’utiliser#

1. Utilisez les boutons de remplissage rapide en haut pour déposer des exemples courants, ou saisissez directement.
2. Saisissez Version A et Version B dans les deux champs. Un v ou un = de tête est accepté et retiré ; 1.2.3-beta.1+build.42 est analysé jusqu’à ses parties.
3. Saisissez une expression Plage si vous voulez un contrôle de satisfaction. Le défaut est ^1.2.0 || >=2.0.0 <3.0.0 — deux jeux OU, comme s’écrivent les vraies plages de dépendance. Syntaxe gérée : ^ (circonflexe), ~ (tilde), >= <= > < =, jokers x / X / *, versions partielles (1.2), plages par tiret -, et || pour OU des jeux.
4. Lisez les deux cartes d’analyse. Chacune affiche la forme canonique clean et les champs éclatés major, minor, patch, prerelease et build. Une version invalide fait passer sa carte au rouge avec un message.
5. Lisez la carte de comparaison. Elle expose A < B, A = B ou A > B par précédence, plus le diff — le composant le plus haut qui a changé (major, minor, patch, prerelease ou build).
6. Lisez la carte de vérification de plage. Elle vous dit, pour la plage saisie, si A la satisfait et si B la satisfait.

Fonctionnalités clés#

• Précédence selon la spec. La comparaison parcourt major.minor.patch puis les identifiants de pré-version, avec la règle qu’une version sans pré-version surpasse toujours une version avec. Les identifiants numériques se comparent numériquement (beta.2 < beta.11) ; les alphanumériques se comparent lexicalement ; et un numérique est toujours inférieur à un alphanumérique. Les métadonnées de build sont analysées et affichées mais n’affectent jamais la précédence.
• Circonflexe et tilde, désucrés correctement. ^1.2.3 devient >=1.2.3 <2.0.0 ; ^0.2.3 devient >=0.2.3 <0.3.0 ; ^0.0.3 devient >=0.0.3 <0.0.4 — la règle du « non-zéro le plus à gauche » du circonflexe. Le tilde épingle sur la même mineure : ~1.2.3 est >=1.2.3 <1.3.0.
• Plages avec ||, tirets et jokers. ^1.0.0 || >=2.0.0 <3.0.0 (OU de deux jeux), 1.2.0 - 1.5.0 (plage inclusive par tiret), 1.x / 1.2.* (plages joker) s’analysent et se testent toutes.
• La porte d’inclusion des pré-versions. Une pré-version ne peut satisfaire une plage que si un comparateur du même jeu porte une étiquette de pré-version sur le même major.minor.patch. Donc 1.5.0-rc.1 ne satisfait pas ^1.2.0, mais elle satisfait ^1.5.0-rc.0 — ce qui correspond à la façon dont les vrais gestionnaires de paquets tiennent les pré-versions aléatoires hors de vos builds de release.
• Un diff qui raconte une histoire. Le champ diff rapporte le composant le plus haut qui a changé, donc un saut de 1.2.3 à 2.0.0 affiche major, et 1.0.0 à 1.0.0 avec un build changé affiche build même si la précédence est inchangée.
• Entrée tolérante. Un v de tête, un = de tête et les blancs autour sont tolérés, donc les versions copiées d’un tag git ou d’un changelog s’analysent sans nettoyage manuel.

Exemple commenté#

Avec les défauts — A 1.2.3, B 2.0.0, plage ^1.2.0 || >=2.0.0 <3.0.0 — la page rapporte :

A clean    1.2.3        (major 1, minor 2, patch 3)
B clean    2.0.0        (major 2, minor 0, patch 0)
compare    1.2.3  <  2.0.0
diff       major
range      A satisfies   B satisfies

Les deux versions satisfont la plage, mais pour des raisons différentes : A tombe dans le premier jeu OU (^1.2.0 → >=1.2.0 <2.0.0), B dans le second (>=2.0.0 <3.0.0). Changez B en 3.0.0 et son badge bascule à not satisfies — la borne supérieure <3.0.0 l’exclut.

Pour voir la règle de pré-version à l’œuvre, réglez A sur 1.5.0-rc.1 et B sur 1.5.0, et gardez la plage sur ^1.5.0-rc.0. Désormais A satisfait (même 1.5.0, la plage porte une étiquette de pré-version correspondante), tandis qu’un simple ^1.5.0 ne laisserait pas passer 1.5.0-rc.1 — la porte existe précisément pour tenir les release candidates hors de la résolution de dépendance de release jusqu’à ce que vous y optiez.

FAQ#

1.0.0 est-il supérieur à 1.0.0-beta ?#

Oui. Une version sans étiquette de pré-version a toujours une précédence supérieure à une version avec étiquette de pré-version, même à major.minor.patch identique. Donc 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. C’est pourquoi une release qui « passe gold » est un vrai cran de précédence, pas juste un changement d’étiquette.

Quelle est la différence entre ^ et ~ ?#

Le circonflexe autorise les mises à jour qui ne modifient pas le composant non-zéro le plus à gauche : ^1.2.3 permet tout 1.x.x depuis 1.2.3 jusqu’à (mais sans l’inclure) 2.0.0. Le tilde est plus strict — il épingle la mineure quand on lui donne une version complète : ~1.2.3 ne permet que 1.2.x. Avec seulement une majeure (~1), tilde et circonflexe autorisent tous deux toute la plage majeure. La plupart des bibliothèques épinglent avec ^ ; les correctifs de vos propres paquets publiés utilisent souvent ~.

Pourquoi ma pré-version ne satisfait-elle pas ^1.0.0 ?#

Par conception. Une pré-version comme 1.5.0-rc.1 ne satisfait une plage que si un comparateur du même jeu ET porte une étiquette de pré-version sur le même 1.5.0. ^1.0.0 se désucré en >=1.0.0 <2.0.0-0 sans pré-version sur 1.5.0, donc la porte empêche votre build de release de tirer la release candidate aléatoire de quelqu’un d’autre. Pour opter, écrivez explicitement ^1.5.0-rc.0.

Les métadonnées de build affectent-elles la comparaison ?#

Non. 1.0.0+exp.sha.5 et 1.0.0+exp.sha.6 ont une précédence égale — les métadonnées de build ne servent qu’à l’identification. L’analyseur les affiche quand même (et le diff rapporte un changement build quand seules les métadonnées diffèrent), mais elles ne décident jamais d’un ordre.