semver 5.2.0 → 5.5.0

package/README.md

@@ -1,53 +1,71 @@
 semver(1) -- The semantic versioner for npm
 ===========================================
 
+## Install
+
+```bash
+npm install --save semver
+````
+
 ## Usage
 
-    $ npm install semver
+As a node module:
 
-    semver.valid('1.2.3') // '1.2.3'
-    semver.valid('a.b.c') // null
-    semver.clean('  =v1.2.3   ') // '1.2.3'
-    semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
-    semver.gt('1.2.3', '9.8.7') // false
-    semver.lt('1.2.3', '9.8.7') // true
+```js
+const semver = require('semver')
+
+semver.valid('1.2.3') // '1.2.3'
+semver.valid('a.b.c') // null
+semver.clean('  =v1.2.3   ') // '1.2.3'
+semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
+semver.gt('1.2.3', '9.8.7') // false
+semver.lt('1.2.3', '9.8.7') // true
+semver.valid(semver.coerce('v2')) // '2.0.0'
+semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'
+```
 
 As a command-line utility:
 
-    $ semver -h
+```
+$ semver -h
+
+SemVer 5.3.0
 
-    SemVer 5.1.0
+A JavaScript implementation of the http://semver.org/ specification
+Copyright Isaac Z. Schlueter
 
-    A JavaScript implementation of the http://semver.org/ specification
-    Copyright Isaac Z. Schlueter
+Usage: semver [options] <version> [<version> [...]]
+Prints valid versions sorted by SemVer precedence
 
-    Usage: semver [options] <version> [<version> [...]]
-    Prints valid versions sorted by SemVer precedence
+Options:
+-r --range <range>
+        Print versions that match the specified range.
 
-    Options:
-    -r --range <range>
-            Print versions that match the specified range.
+-i --increment [<level>]
+        Increment a version by the specified level.  Level can
+        be one of: major, minor, patch, premajor, preminor,
+        prepatch, or prerelease.  Default level is 'patch'.
+        Only one version may be specified.
 
-    -i --increment [<level>]
-            Increment a version by the specified level.  Level can
-            be one of: major, minor, patch, premajor, preminor,
-            prepatch, or prerelease.  Default level is 'patch'.
-            Only one version may be specified.
+--preid <identifier>
+        Identifier to be used to prefix premajor, preminor,
+        prepatch or prerelease version increments.
 
-    --preid <identifier>
-            Identifier to be used to prefix premajor, preminor,
-            prepatch or prerelease version increments.
+-l --loose
+        Interpret versions and ranges loosely
 
-    -l --loose
-            Interpret versions and ranges loosely
+-c --coerce
+        Coerce a string into SemVer if possible
+        (does not imply --loose)
 
-    Program exits successfully if any valid version satisfies
-    all supplied ranges, and prints all satisfying versions.
+Program exits successfully if any valid version satisfies
+all supplied ranges, and prints all satisfying versions.
 
-    If no satisfying versions are found, then exits failure.
+If no satisfying versions are found, then exits failure.
 
-    Versions are printed in ascending order, so supplying
-    multiple versions to the utility will just sort them.
+Versions are printed in ascending order, so supplying
+multiple versions to the utility will just sort them.
+```
 
 ## Versions
 
@@ -124,20 +142,20 @@ The method `.inc` takes an additional `identifier` string argument that
 will append the value of the string as a prerelease identifier:
 
 ```javascript
-> semver.inc('1.2.3', 'prerelease', 'beta')
-'1.2.4-beta.0'
+semver.inc('1.2.3', 'prerelease', 'beta')
+// '1.2.4-beta.0'
 ```
 
 command-line example:
 
-```shell
+```bash
 $ semver 1.2.3 -i prerelease --preid beta
 1.2.4-beta.0
 ```
 
 Which then can be used to increment further:
 
-```shell
+```bash
 $ semver 1.2.4-beta.0 -i prerelease
 1.2.4-beta.1
 ```
@@ -294,6 +312,8 @@ strings that they parse.
 * `major(v)`: Return the major version number.
 * `minor(v)`: Return the minor version number.
 * `patch(v)`: Return the patch version number.
+* `intersects(r1, r2, loose)`: Return true if the two supplied ranges
+  or comparators intersect.
 
 ### Comparison
 
@@ -317,6 +337,9 @@ strings that they parse.
   (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`),
   or null if the versions are the same.
 
+### Comparators
+
+* `intersects(comparator)`: Return true if the comparators intersect
 
 ### Ranges
 
@@ -325,6 +348,8 @@ strings that they parse.
   range.
 * `maxSatisfying(versions, range)`: Return the highest version in the list
   that satisfies the range, or `null` if none of them do.
+* `minSatisfying(versions, range)`: Return the lowest version in the list
+  that satisfies the range, or `null` if none of them do.
 * `gtr(version, range)`: Return `true` if version is greater than all the
   versions possible in the range.
 * `ltr(version, range)`: Return `true` if version is less than all the
@@ -333,6 +358,7 @@ strings that they parse.
   the bounds of the range in either the high or low direction.  The
   `hilo` argument must be either the string `'>'` or `'<'`.  (This is
   the function called by `gtr` and `ltr`.)
+* `intersects(range)`: Return true if any of the ranges comparators intersect
 
 Note that, since ranges may be non-contiguous, a version might not be
 greater than a range, less than a range, *or* satisfy a range!  For
@@ -344,3 +370,19 @@ satisfy the range.
 
 If you want to know if a version satisfies or does not satisfy a
 range, use the `satisfies(version, range)` function.
+
+### Coercion
+
+* `coerce(version)`: Coerces a string to semver if possible
+
+This aims to provide a very forgiving translation of a non-semver
+string to semver. It looks for the first digit in a string, and
+consumes all remaining characters which satisfy at least a partial semver
+(e.g., `1`, `1.2`, `1.2.3`) up to the max permitted length (256 characters).
+Longer versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`).
+All surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes `3.4.0`).
+Only text which lacks digits will fail coercion (`version one` is not valid).
+The maximum  length for any semver component considered for coercion is 16 characters;
+longer components will be ignored (`10000000000000000.4.7.4` becomes `4.7.4`).
+The maximum value for any semver component is `Integer.MAX_SAFE_INTEGER || (2**53 - 1)`;
+higher value components are invalid (`9999999999999999.4.7.4` is likely invalid).

package/bin/semver

@@ -12,6 +12,7 @@ var argv = process.argv.slice(2)
   , inc = null
   , version = require("../package.json").version
   , loose = false
+  , coerce = false
   , identifier = undefined
   , semver = require("../semver")
   , reverse = false
@@ -54,6 +55,9 @@ function main () {
       case "-r": case "--range":
         range.push(argv.shift())
         break
+      case "-c": case "--coerce":
+        coerce = true
+        break
       case "-h": case "--help": case "-?":
         return help()
       default:
@@ -62,8 +66,10 @@ function main () {
     }
   }
 
-  versions = versions.filter(function (v) {
-    return semver.valid(v, loose)
+  versions = versions.map(function (v) {
+    return coerce ? (semver.coerce(v) || {version: v}).version : v
+  }).filter(function (v) {
+    return semver.valid(v)
   })
   if (!versions.length) return fail()
   if (inc && (versions.length !== 1 || range.length))
@@ -122,6 +128,10 @@ function help () {
               ,"-l --loose"
               ,"        Interpret versions and ranges loosely"
               ,""
+              ,"-c --coerce"
+              ,"        Coerce a string into SemVer if possible"
+              ,"        (does not imply --loose)"
+              ,""
               ,"Program exits successfully if any valid version satisfies"
               ,"all supplied ranges, and prints all satisfying versions."
               ,""

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "semver",
-  "version": "5.2.0",
+  "version": "5.5.0",
   "description": "The semantic version parser used by npm.",
   "main": "semver.js",
   "scripts": {
-    "test": "tap test/*.js"
+    "test": "tap test/*.js --cov -J"
   },
   "devDependencies": {
-    "tap": "^2.0.0"
+    "tap": "^10.7.0"
   },
   "license": "ISC",
   "repository": "https://github.com/npm/node-semver",

package/range.bnf

@@ -3,10 +3,10 @@ logical-or ::= ( ' ' ) * '||' ( ' ' ) *
 range      ::= hyphen | simple ( ' ' simple ) * | ''
 hyphen     ::= partial ' - ' partial
 simple     ::= primitive | partial | tilde | caret
-primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' | ) partial
+primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
 partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
 xr         ::= 'x' | 'X' | '*' | nr
-nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
+nr         ::= '0' | [1-9] ( [0-9] ) *
 tilde      ::= '~' partial
 caret      ::= '^' partial
 qualifier  ::= ( '-' pre )? ( '+' build )?

package/semver.js

@@ -21,6 +21,9 @@ exports.SEMVER_SPEC_VERSION = '2.0.0';
 var MAX_LENGTH = 256;
 var MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER || 9007199254740991;
 
+// Max safe segment length for coercion.
+var MAX_SAFE_COMPONENT_LENGTH = 16;
+
 // The actual regexps go on exports.re
 var re = exports.re = [];
 var src = exports.src = [];
@@ -156,6 +159,15 @@ src[XRANGE] = '^' + src[GTLT] + '\\s*' + src[XRANGEPLAIN] + '$';
 var XRANGELOOSE = R++;
 src[XRANGELOOSE] = '^' + src[GTLT] + '\\s*' + src[XRANGEPLAINLOOSE] + '$';
 
+// Coercion.
+// Extract anything that could conceivably be a part of a valid semver
+var COERCE = R++;
+src[COERCE] = '(?:^|[^\\d])' +
+              '(\\d{1,' + MAX_SAFE_COMPONENT_LENGTH + '})' +
+              '(?:\\.(\\d{1,' + MAX_SAFE_COMPONENT_LENGTH + '}))?' +
+              '(?:\\.(\\d{1,' + MAX_SAFE_COMPONENT_LENGTH + '}))?' +
+              '(?:$|[^\\d])';
+
 // Tilde ranges.
 // Meaning is "reasonably at or greater than"
 var LONETILDE = R++;
@@ -314,9 +326,9 @@ function SemVer(version, loose) {
   else
     this.prerelease = m[4].split('.').map(function(id) {
       if (/^[0-9]+$/.test(id)) {
-        var num = +id
+        var num = +id;
         if (num >= 0 && num < MAX_SAFE_INTEGER)
-          return num
+          return num;
       }
       return id;
     });
@@ -563,7 +575,7 @@ function patch(a, loose) {
 
 exports.compare = compare;
 function compare(a, b, loose) {
-  return new SemVer(a, loose).compare(b);
+  return new SemVer(a, loose).compare(new SemVer(b, loose));
 }
 
 exports.compareLoose = compareLoose;
@@ -704,11 +716,59 @@ Comparator.prototype.test = function(version) {
   return cmp(version, this.operator, this.semver, this.loose);
 };
 
+Comparator.prototype.intersects = function(comp, loose) {
+  if (!(comp instanceof Comparator)) {
+    throw new TypeError('a Comparator is required');
+  }
+
+  var rangeTmp;
+
+  if (this.operator === '') {
+    rangeTmp = new Range(comp.value, loose);
+    return satisfies(this.value, rangeTmp, loose);
+  } else if (comp.operator === '') {
+    rangeTmp = new Range(this.value, loose);
+    return satisfies(comp.semver, rangeTmp, loose);
+  }
+
+  var sameDirectionIncreasing =
+    (this.operator === '>=' || this.operator === '>') &&
+    (comp.operator === '>=' || comp.operator === '>');
+  var sameDirectionDecreasing =
+    (this.operator === '<=' || this.operator === '<') &&
+    (comp.operator === '<=' || comp.operator === '<');
+  var sameSemVer = this.semver.version === comp.semver.version;
+  var differentDirectionsInclusive =
+    (this.operator === '>=' || this.operator === '<=') &&
+    (comp.operator === '>=' || comp.operator === '<=');
+  var oppositeDirectionsLessThan =
+    cmp(this.semver, '<', comp.semver, loose) &&
+    ((this.operator === '>=' || this.operator === '>') &&
+    (comp.operator === '<=' || comp.operator === '<'));
+  var oppositeDirectionsGreaterThan =
+    cmp(this.semver, '>', comp.semver, loose) &&
+    ((this.operator === '<=' || this.operator === '<') &&
+    (comp.operator === '>=' || comp.operator === '>'));
+
+  return sameDirectionIncreasing || sameDirectionDecreasing ||
+    (sameSemVer && differentDirectionsInclusive) ||
+    oppositeDirectionsLessThan || oppositeDirectionsGreaterThan;
+};
+
 
 exports.Range = Range;
 function Range(range, loose) {
-  if ((range instanceof Range) && range.loose === loose)
-    return range;
+  if (range instanceof Range) {
+    if (range.loose === loose) {
+      return range;
+    } else {
+      return new Range(range.raw, loose);
+    }
+  }
+
+  if (range instanceof Comparator) {
+    return new Range(range.value, loose);
+  }
 
   if (!(this instanceof Range))
     return new Range(range, loose);
@@ -783,6 +843,22 @@ Range.prototype.parseRange = function(range) {
   return set;
 };
 
+Range.prototype.intersects = function(range, loose) {
+  if (!(range instanceof Range)) {
+    throw new TypeError('a Range is required');
+  }
+
+  return this.set.some(function(thisComparators) {
+    return thisComparators.every(function(thisComparator) {
+      return range.set.some(function(rangeComparators) {
+        return rangeComparators.every(function(rangeComparator) {
+          return thisComparator.intersects(rangeComparator, loose);
+        });
+      });
+    });
+  });
+};
+
 // Mostly just for testing and legacy API reasons
 exports.toComparators = toComparators;
 function toComparators(range, loose) {
@@ -966,11 +1042,11 @@ function replaceXRange(comp, loose) {
       } else if (gtlt === '<=') {
         // <=0.7.x is actually <0.8.0, since any 0.7.x should
         // pass.  Similarly, <=7.x is actually <8.0.0, etc.
-        gtlt = '<'
+        gtlt = '<';
         if (xm)
-          M = +M + 1
+          M = +M + 1;
         else
-          m = +m + 1
+          m = +m + 1;
       }
 
       ret = gtlt + M + '.' + m + '.' + p;
@@ -1087,11 +1163,42 @@ function satisfies(version, range, loose) {
 
 exports.maxSatisfying = maxSatisfying;
 function maxSatisfying(versions, range, loose) {
-  return versions.filter(function(version) {
-    return satisfies(version, range, loose);
-  }).sort(function(a, b) {
-    return rcompare(a, b, loose);
-  })[0] || null;
+  var max = null;
+  var maxSV = null;
+  try {
+    var rangeObj = new Range(range, loose);
+  } catch (er) {
+    return null;
+  }
+  versions.forEach(function (v) {
+    if (rangeObj.test(v)) { // satisfies(v, range, loose)
+      if (!max || maxSV.compare(v) === -1) { // compare(max, v, true)
+        max = v;
+        maxSV = new SemVer(max, loose);
+      }
+    }
+  })
+  return max;
+}
+
+exports.minSatisfying = minSatisfying;
+function minSatisfying(versions, range, loose) {
+  var min = null;
+  var minSV = null;
+  try {
+    var rangeObj = new Range(range, loose);
+  } catch (er) {
+    return null;
+  }
+  versions.forEach(function (v) {
+    if (rangeObj.test(v)) { // satisfies(v, range, loose)
+      if (!min || minSV.compare(v) === 1) { // compare(min, v, true)
+        min = v;
+        minSV = new SemVer(min, loose);
+      }
+    }
+  })
+  return min;
 }
 
 exports.validRange = validRange;
@@ -1192,3 +1299,26 @@ function prerelease(version, loose) {
   var parsed = parse(version, loose);
   return (parsed && parsed.prerelease.length) ? parsed.prerelease : null;
 }
+
+exports.intersects = intersects;
+function intersects(r1, r2, loose) {
+  r1 = new Range(r1, loose)
+  r2 = new Range(r2, loose)
+  return r1.intersects(r2)
+}
+
+exports.coerce = coerce;
+function coerce(version) {
+  if (version instanceof SemVer)
+    return version;
+
+  if (typeof version !== 'string')
+    return null;
+
+  var match = version.match(re[COERCE]);
+
+  if (match == null)
+    return null;
+
+  return parse((match[1] || '0') + '.' + (match[2] || '0') + '.' + (match[3] || '0')); 
+}