Парсер и компаратор SemVer

Что такое парсер семантических версий?#

Семантическое версионирование (SemVer) — соглашение major.minor.patch, которым большинство библиотек сигнализирует о типе изменения в релизе: баг-фикс поднимает patch, обратно совместимые добавления поднимают minor, ломающие изменения поднимают major. Добавьте предрелизный тег (1.0.0-beta.1) или метаданные сборки (+exp.sha.1) — и получится полная грамматика, определённая на semver.org 2.0.0.

Проблема в том, что «сравнить две версии» и «удовлетворяет ли эта версия моему диапазону зависимостей» легко выполнить ошибочно на глаз. 1.0.0 выше или ниже 1.0.0-beta? (Выше — релиз всегда превосходит свой предрелиз.) Удовлетворяет ли 1.2.3 условию ^1.2.0? (Да.) А ~1.2.0? (Тоже да, но по более жёсткой причине.) Эта страница разбирает версии так, как их определяет спецификация, показывает компоненты, сравнивает две версии по старшинству и отвечает на запросы диапазонов тем же синтаксисом ^ / ~ / >= / || / дефис, что использует package.json, — всё локально, по настоящим правилам, а не наугад.

Как пользоваться#

1. Воспользуйтесь кнопками быстрой подстановки вверху, чтобы вставить типовые примеры, или вводите напрямую.
2. Введите Версия A и Версия B в два поля. Ведущая v или = принимается и вырезается; 1.2.3-beta.1+build.42 разбирается на части.
3. Введите выражение Диапазон, если нужна проверка удовлетворения. По умолчанию ^1.2.0 || >=2.0.0 <3.0.0 — два OR-множества, как пишут реальные диапазоны зависимостей. Поддерживаемый синтаксис: ^ (карет), ~ (тильда), >= <= > < =, wildcards x / X / *, частичные версии (1.2), дефисные диапазоны - и || для OR-множеств.
4. Читайте две карточки разбора. Каждая показывает каноническую clean форму и развёрнутые поля major, minor, patch, prerelease и build. Недопустимая версия краснеет с сообщением.
5. Читайте карточку сравнения. Она выводит A < B, A = B или A > B по старшинству, плюс diff — старший из изменившихся компонентов (major, minor, patch, prerelease или build).
6. Читайте карточку проверки диапазона. Она сообщает для введённого диапазона, удовлетворяет ли ему A и удовлетворяет ли B.

Ключевые возможности#

• Старшинство по спецификации. Сравнение проходит по major.minor.patch, а затем по идентификаторам предрелиза с правилом: версия без предрелиза всегда превосходит версию с предрелизом. Числовые идентификаторы сравниваются численно (beta.2 < beta.11); буквенно-цифровые — лексически; числовый всегда ниже буквенно-цифрового. Метаданные сборки разбираются и показываются, но никогда не влияют на старшинство.
• Каретка и тильда корректно десугариваются. ^1.2.3 превращается в >=1.2.3 <2.0.0; ^0.2.3 — в >=0.2.3 <0.3.0; ^0.0.3 — в >=0.0.3 <0.0.4 (правило «крайнего левого ненулевого» у каретки). Тильда фиксирует тот же minor: ~1.2.3 это >=1.2.3 <1.3.0.
• Диапазоны с ||, дефисами и wildcards. ^1.0.0 || >=2.0.0 <3.0.0 (OR двух множеств), 1.2.0 - 1.5.0 (включающий дефисный диапазон), 1.x / 1.2.* (диапазоны с wildcards) — всё парсится и проверяется.
• Шлюз включения предрелизов. Предрелизная версия может удовлетворять диапазону, только если в том же множестве есть компаратор с предрелизным тегом на той же тройке major.minor.patch. Так, 1.5.0-rc.1 не удовлетворяет ^1.2.0, но удовлетворяет ^1.5.0-rc.0 — точно так, как реальные пакетные менеджеры не пускают случайные предрелизы в release-сборки.
• Diff, который рассказывает историю. Поле diff сообщает старший изменившийся компонент, поэтому прыжок с 1.2.3 на 2.0.0 покажет major, а переход 1.0.0 → 1.0.0 с изменённой сборкой покажет build, даже если старшинство не изменилось.
• Снисходительный ввод. Ведущая v, ведущая = и окружающие пробелы допускаются, поэтому версии, скопированные из git-тега или changelog, разбираются без ручной чистки.

Разбор примера#

С умолчаниями — A 1.2.3, B 2.0.0, диапазон ^1.2.0 || >=2.0.0 <3.0.0 — страница сообщит:

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 удовлетворяет   B удовлетворяет

Обе версии удовлетворяют диапазону, но по разным причинам: A попадает в первое OR-множество (^1.2.0 → >=1.2.0 <2.0.0), B — во второе (>=2.0.0 <3.0.0). Поменяйте B на 3.0.0, и её значок переключится на не удовлетворяет — верхняя граница <3.0.0 её исключает.

Чтобы увидеть правило предрелиза в деле, поставьте A 1.5.0-rc.1, B 1.5.0 и оставьте диапазон ^1.5.0-rc.0. Теперь A удовлетворяет (та же 1.5.0, диапазон несёт подходящий предрелизный тег), тогда как обычный ^1.5.0 не пропустил бы 1.5.0-rc.1 — шлюз существует именно для того, чтобы удерживать release-кандидаты вне разрешения release-зависимостей, пока вы явно не подключите их.

FAQ#

1.0.0 выше, чем 1.0.0-beta?#

Да. Версия без предрелизного тега всегда имеет большее старшинство, чем версия с предрелизным тегом, даже при той же major.minor.patch. Поэтому 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. Вот почему «выход в gold» у релиза — реальное повышение старшинства, а не просто смена ярлыка.

В чём разница между ^ и ~?#

Каретка разрешает обновления, не меняющие крайний левый ненулевой компонент: ^1.2.3 допускает любой 1.x.x от 1.2.3 до (не включая) 2.0.0. Тильда строже — при полной версии она фиксирует minor: ~1.2.3 допускает только 1.2.x. При указании только major (~1) тильда и каретка обе разрешают весь major-диапазон. Большинство библиотек фиксирует через ^; патчи к собственным опубликованным пакетам часто используют ~.

Почему моя предрелизная версия не удовлетворяет ^1.0.0?#

По дизайну. Предрелиз вроде 1.5.0-rc.1 удовлетворяет диапазону, лишь когда в том же AND-множестве есть компаратор с предрелизным тегом на той же 1.5.0. ^1.0.0 десугаривается в >=1.0.0 <2.0.0-0 без предрелиза на 1.5.0, поэтому шлюз удержит вашу release-сборку от подтягивания чьего-то случайного release-кандидата. Чтобы подключить, напишите ^1.5.0-rc.0 явно.

Влияет ли метаданные сборки на сравнение?#

Нет. 1.0.0+exp.sha.5 и 1.0.0+exp.sha.6 имеют равное старшинство — метаданные сборки нужны только для идентификации. Парсер всё равно их показывает (а diff сообщает изменение build, когда различаются только метаданные), но никогда не определяет через них порядок.