feat: add knownVulnerable semver range option

README.md

@@ -90,6 +90,30 @@ All options are optional.
 * `npmVersion` - String, default `null`.  The npm version to use when
   checking manifest for `engines` requirement satisfaction.  (If `null`,
   then this particular check is skipped.)
+* `avoid` - String, default `null`.  A SemVer range of
+  versions that should be avoided.  An avoided version MAY be selected if
+  there is no other option, so when using this for version selection ensure
+  that you check the result against the range to see if there was no
+  alternative available.
+* `avoidStrict` Boolean, default `false`.  If set to true, then
+  `pickManifest` will never return a version in the `avoid` range.  If the
+  only available version in the `wanted` range is a version that should be
+  avoided, then it will return a version _outside_ the `wanted` range,
+  preferring to do so without making a SemVer-major jump, if possible.  If
+  there are no versions outside the `avoid` range, then throw an
+  `ETARGET` error.  It does this by calling pickManifest first with the
+  `wanted` range, then with a `^` affixed to the version returned by the
+  `wanted` range, and then with a `*` version range, and throwing if
+  nothing could be found to satisfy the avoidance request.
+
+Return value is the manifest as it exists in the packument, possibly
+decorated with the following boolean flags:
+
+* `_shouldAvoid` The version is in the `avoid` range.  Watch out!
+* `_outsideDependencyRange` The version is outside the `wanted` range,
+  because `avoidStrict: true` was set.
+* `_isSemVerMajor` The `_outsideDependencyRange` result is a SemVer-major
+  step up from the version returned by the `wanted` range.
 
 ### Algorithm
 
@@ -114,17 +138,19 @@ All options are optional.
    `before` setting, then select that manifest.
 6. If nothing is yet selected, sort by the following heuristics in order,
    and select the top item:
-    1. Prioritize versions that are not in `policyRestrictions` over those
+    1. Prioritize versions that are not in the `avoid` range over those
        that are.
-    2. Prioritize published versions over staged versions.
-    3. Prioritize versions that are not deprecated, and which have a
+    2. Prioritize versions that are not in `policyRestrictions` over those
+       that are.
+    3. Prioritize published versions over staged versions.
+    4. Prioritize versions that are not deprecated, and which have a
        satisfied engines requirement, over those that are either deprecated
        or have an engines mismatch.
-    4. Prioritize versions that have a satisfied engines requirement over
+    5. Prioritize versions that have a satisfied engines requirement over
        those that do not.
-    5. Prioritize versions that are not are not deprecated (but have a
+    6. Prioritize versions that are not are not deprecated (but have a
        mismatched engines requirement) over those that are deprecated.
-    6. Prioritize higher SemVer precedence over lower SemVer precedence.
+    7. Prioritize higher SemVer precedence over lower SemVer precedence.
 7. If no manifest was selected, raise an `ETARGET` error.
 8. If the selected item is in the `policyRestrictions.versions` list, raise
    an `E403` error.

index.js

@@ -16,17 +16,68 @@ const engineOk = (manifest, npmVersion, nodeVersion) => {
 const isBefore = (verTimes, ver, time) =>
   !verTimes || !verTimes[ver] || Date.parse(verTimes[ver]) <= time
 
+const avoidSemverOpt = { includePrerelease: true, loose: true }
+const shouldAvoid = (ver, avoid) =>
+  avoid && semver.satisfies(ver, avoid, avoidSemverOpt)
+
+const decorateAvoid = (result, avoid) =>
+  result && shouldAvoid(result.version, avoid)
+    ? { ...result, _shouldAvoid: true }
+    : result
+
 const pickManifest = (packument, wanted, opts) => {
   const {
     defaultTag = 'latest',
     before = null,
     nodeVersion = process.version,
     npmVersion = null,
-    includeStaged = false
+    includeStaged = false,
+    avoid = null,
+    avoidStrict = false
   } = opts
 
   const { name, time: verTimes } = packument
   const versions = packument.versions || {}
+
+  if (avoidStrict) {
+    const looseOpts = {
+      ...opts,
+      avoidStrict: false
+    }
+
+    const result = pickManifest(packument, wanted, looseOpts)
+    if (!result || !result._shouldAvoid) {
+      return result
+    }
+
+    const caret = pickManifest(packument, `^${result.version}`, looseOpts)
+    if (!caret || !caret._shouldAvoid) {
+      return {
+        ...caret,
+        _outsideDependencyRange: true,
+        _isSemVerMajor: false
+      }
+    }
+
+    const star = pickManifest(packument, '*', looseOpts)
+    if (!star || !star._shouldAvoid) {
+      return {
+        ...star,
+        _outsideDependencyRange: true,
+        _isSemVerMajor: true
+      }
+    }
+
+    throw Object.assign(new Error(`No avoidable versions for ${name}`), {
+      code: 'ETARGET',
+      name,
+      wanted,
+      avoid,
+      before,
+      versions: Object.keys(versions)
+    })
+  }
+
   const staged = (includeStaged && packument.stagedVersions &&
     packument.stagedVersions.versions) || {}
   const restricted = (packument.policyRestrictions &&
@@ -49,7 +100,7 @@ const pickManifest = (packument, wanted, opts) => {
     // we use that.  Otherwise, we get the highest precedence version
     // prior to the dist-tag.
     if (isBefore(verTimes, ver, time)) {
-      return versions[ver] || staged[ver] || restricted[ver]
+      return decorateAvoid(versions[ver] || staged[ver] || restricted[ver], avoid)
     } else {
       return pickManifest(packument, `<=${ver}`, opts)
     }
@@ -59,15 +110,19 @@ const pickManifest = (packument, wanted, opts) => {
   if (wanted && type === 'version') {
     const ver = semver.clean(wanted, { loose: true })
     const mani = versions[ver] || staged[ver] || restricted[ver]
-    return isBefore(verTimes, ver, time) ? mani : null
+    return isBefore(verTimes, ver, time) ? decorateAvoid(mani, avoid) : null
   }
 
   // ok, sort based on our heuristics, and pick the best fit
   const range = type === 'range' ? wanted : '*'
 
   // if the range is *, then we prefer the 'latest' if available
+  // but skip this if it should be avoided, in that case we have
+  // to try a little harder.
   const defaultVer = distTags[defaultTag]
-  if (defaultVer && (range === '*' || semver.satisfies(defaultVer, range, { loose: true }))) {
+  if (defaultVer &&
+      (range === '*' || semver.satisfies(defaultVer, range, { loose: true })) &&
+      !shouldAvoid(defaultVer, avoid)) {
     const mani = versions[defaultVer]
     if (mani && isBefore(verTimes, defaultVer, time)) {
       return mani
@@ -81,20 +136,24 @@ const pickManifest = (packument, wanted, opts) => {
     .filter(([ver, mani]) => isBefore(verTimes, ver, time))
 
   if (!allEntries.length) {
-    throw Object.assign(new Error(`No valid versions available for ${name}`), {
+    throw Object.assign(new Error(`No versions available for ${name}`), {
       code: 'ENOVERSIONS',
       name,
       type,
       wanted,
+      before,
       versions: Object.keys(versions)
     })
   }
 
+  const sortSemverOpt = { loose: true }
   const entries = allEntries.filter(([ver, mani]) =>
     semver.satisfies(ver, range, { loose: true }))
     .sort((a, b) => {
       const [vera, mania] = a
       const [verb, manib] = b
+      const notavoida = !shouldAvoid(vera, avoid)
+      const notavoidb = !shouldAvoid(verb, avoid)
       const notrestra = !restricted[a]
       const notrestrb = !restricted[b]
       const notstagea = !staged[a]
@@ -104,21 +163,23 @@ const pickManifest = (packument, wanted, opts) => {
       const enginea = engineOk(mania, npmVersion, nodeVersion)
       const engineb = engineOk(manib, npmVersion, nodeVersion)
       // sort by:
+      // - not an avoided version
       // - not restricted
       // - not staged
       // - not deprecated and engine ok
       // - engine ok
       // - not deprecated
       // - semver
-      return (notrestrb - notrestra) ||
+      return (notavoidb - notavoida) ||
+        (notrestrb - notrestra) ||
         (notstageb - notstagea) ||
         ((notdeprb && engineb) - (notdepra && enginea)) ||
         (engineb - enginea) ||
         (notdeprb - notdepra) ||
-        semver.rcompare(vera, verb, { loose: true })
+        semver.rcompare(vera, verb, sortSemverOpt)
     })
 
-  return entries[0] && entries[0][1]
+  return decorateAvoid(entries[0] && entries[0][1], avoid)
 }
 
 module.exports = (packument, wanted, opts = {}) => {