Analizador y comparador SemVer

¿Qué es un analizador de versiones semánticas?#

Semantic Versioning (SemVer) es la convención mayor.menor.parche que la mayoría de las librerías usan para señalar qué tipo de cambio contiene una release: una corrección de bug sube parche, las adiciones compatibles hacia atrás suben menor, y los cambios rompedores suben mayor. Añade una etiqueta de preliminar (1.0.0-beta.1) o metadatos de compilación (+exp.sha.1) y obtienes la gramática completa definida en semver.org 2.0.0.

El problema es que «comparar dos versiones» y «¿esta versión satisface mi rango de dependencia?» son cosas fáciles de errar a ojo. ¿Es 1.0.0 mayor o menor que 1.0.0-beta? (Mayor: una release siempre supera a su preliminar.) ¿Satisface 1.2.3 el rango ^1.2.0? (Sí.) ¿Y ~1.2.0? (También, pero por una razón más ajustada.) Esta página analiza las versiones como las define la especificación, te muestra los componentes, compara dos versiones por precedencia y responde a consultas de rango con la misma sintaxis ^ / ~ / >= / || / guion que usa un package.json, todo localmente y contra las reglas reales, no contra una suposición.

Cómo se usa#

1. Usa los botones de autorrelleno de la parte superior para soltar ejemplos comunes, o teclea directamente.
2. Introduce la Versión A y la Versión B en las dos entradas. Se acepta y se elimina una v o un = iniciales; 1.2.3-beta.1+build.42 se analiza hasta sus partes.
3. Introduce una expresión de Rango si quieres una comprobación de satisfacción. El valor por defecto es ^1.2.0 || >=2.0.0 <3.0.0, dos conjuntos unidos por OR, como se escriben los rangos reales de dependencia. Sintaxis admitida: ^ (acento circunflejo), ~ (tilde), >= <= > < =, comodines x / X / *, versiones parciales (1.2), rangos con guion - y || para unir conjuntos con OR.
4. Lee las dos tarjetas de análisis. Cada una muestra la forma canónica clean y los campos desglosados major, minor, patch, prerelease y build. Una versión inválida pone roja su tarjeta con un mensaje.
5. Lee la tarjeta de comparación. Expone A < B, A = B o A > B por precedencia, además del diff: el componente superior que cambió (mayor, menor, parche, preliminar o compilación).
6. Lee la tarjeta de verificación de rango. Te dice, para el rango que has tecleado, si A lo satisface y si B lo satisface.

Características clave#

• Precedencia según la especificación. La comparación recorre major.minor.patch y luego los identificadores de preliminar, con la regla de que una versión sin preliminar siempre supera a una con él. Los identificadores numéricos se comparan numéricamente (beta.2 < beta.11); los alfanuméricos, léxicamente; y los numéricos siempre se sitúan por debajo de los alfanuméricos. Los metadatos de compilación se analizan y muestran, pero nunca afectan a la precedencia.
• Circunflejo y tilde, desazucarados correctamente. ^1.2.3 se convierte en >=1.2.3 <2.0.0; ^0.2.3, en >=0.2.3 <0.3.0; ^0.0.3, en >=0.0.3 <0.0.4 (la regla del «componente no nulo más a la izquierda» del circunflejo). La tilde fija el menor: ~1.2.3 es >=1.2.3 <1.3.0.
• Rangos con ||, guiones y comodines. ^1.0.0 || >=2.0.0 <3.0.0 (OR de dos conjuntos), 1.2.0 - 1.5.0 (rango inclusivo con guion), 1.x / 1.2.* (rangos con comodín) se analizan y comprueban.
• La puerta de inclusión de preliminares. Una versión preliminar solo puede satisfacer un rango cuando algún comparador del mismo conjunto lleva una etiqueta preliminar en el mismo major.minor.patch. Así, 1.5.0-rc.1 no satisface ^1.2.0, pero sí satisface ^1.5.0-rc.0, igual que los gestores de paquetes reales mantienen aleatorios preliminares fuera de tus builds de release.
• Un diff que cuenta una historia. El campo diff informa del componente superior que cambió, así que un salto de 1.2.3 a 2.0.0 muestra mayor, y de 1.0.0 a 1.0.0 con un build cambiado muestra compilación aunque la precedencia no cambie.
• Entrada indulgente. Se toleran una v inicial, un = inicial y los espacios en blanco alrededor, así las versiones copiadas de una etiqueta git o de un changelog se analizan sin limpieza manual.

Ejemplo práctico#

Con los valores por defecto (A 1.2.3, B 2.0.0, rango ^1.2.0 || >=2.0.0 <3.0.0), la página informa:

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

Ambas versiones satisfacen el rango, pero por razones distintas: A cae dentro del primer conjunto OR (^1.2.0 → >=1.2.0 <2.0.0), B cae dentro del segundo (>=2.0.0 <3.0.0). Cambia B a 3.0.0 y su insignia pasa a no satisface: el límite superior <3.0.0 la excluye.

Para ver la regla de preliminar en acción, pon A en 1.5.0-rc.1 y B en 1.5.0, y mantén el rango como ^1.5.0-rc.0. Ahora A satisface (mismo 1.5.0, el rango lleva una etiqueta preliminar coincidente), mientras que un ^1.5.0 simple no dejaría pasar a 1.5.0-rc.1: la puerta existe justamente para mantener candidates fuera de la resolución de dependencias de release hasta que tú decidas incluirlas.

Preguntas frecuentes#

¿Es 1.0.0 mayor que 1.0.0-beta?#

Sí. Una versión sin etiqueta preliminar tiene siempre mayor precedencia que una con etiqueta preliminar, incluso en el mismo major.minor.patch. Así, 1.0.0 > 1.0.0-rc.1 > 1.0.0-beta.11 > 1.0.0-alpha. Por eso una release que «llega a oro» es un incremento real de precedencia, no solo un cambio de etiqueta.

¿Cuál es la diferencia entre ^ y ~?#

El circunflejo permite actualizaciones que no modifican el componente no nulo más a la izquierda: ^1.2.3 admite cualquier 1.x.x desde 1.2.3 hasta (sin incluir) 2.0.0. La tilde es más estricta: cuando se le da una versión completa, fija el menor; ~1.2.3 admite solo 1.2.x. Con solo el mayor (~1), tilde y circunflejo permiten ambos todo el rango del mayor. La mayoría de las librerías fijan con ^; los parches a tus propios paquetes publicados usan a menudo ~.

¿Por qué mi versión preliminar no satisface ^1.0.0?#

Por diseño. Una preliminar como 1.5.0-rc.1 solo satisface un rango cuando algún comparador del mismo conjunto AND lleva una preliminar en el mismo 1.5.0. ^1.0.0 se desazucara a >=1.0.0 <2.0.0-0 sin preliminar en 1.5.0, así que la puerta impide que tu build de release se traiga un candidate aleatorio de alguien. Si quieres incluirlo, escribe ^1.5.0-rc.0 explícitamente.

¿Los metadatos de compilación afectan a la comparación?#

No. 1.0.0+exp.sha.5 y 1.0.0+exp.sha.6 tienen la misma precedencia: los metadatos de compilación sirven solo para identificación. El analizador los muestra (y el diff informa de un cambio build cuando solo difieren los metadatos), pero nunca deciden un orden.