feat(config): add in-range

This adds a flag for `npm outdated` to use to limit output either to
packages that have updates in-range of the current package's
requirements, or those that have no updates in-range of the current
package's requirements.

It also adds to the normal (i.e. non JSON or parseable) output directing
folks to use `npm explain` for more info.  This is because the output of
`npm outdated` is misleading, sometimes saying an available version is
present when there is another package in the tree responsible for
keeping the version where it is.

docs/content/commands/npm-outdated.md

@@ -9,7 +9,6 @@ description: Check for outdated packages
 ```bash
 npm outdated [[<@scope>/]<pkg> ...]
 ```
-
 ### Description
 
 This command will check the registry to see if any (or, specific) installed
@@ -97,6 +96,16 @@ When running `npm outdated` and `npm ls`, setting `--all` will show all
 outdated or installed packages, rather than only those directly depended
 upon by the current project.
 
+#### `in-range`
+
+* Default: null
+* Type: null or Boolean
+
+When running `npm outdated` setting `--in-range` will limit output to only
+those packages with existing versions in range of the current project's
+dependencies. `--no-in-range` will limit output to only those packages with
+updates that are out of range of the current project's dependencies.
+
 #### `json`
 
 * Default: false
@@ -162,6 +171,7 @@ This value is not exported to the environment for child processes.
 ### See Also
 
 * [npm update](/commands/npm-update)
+* [npm explain](/using-npm/explain)
 * [npm dist-tag](/commands/npm-dist-tag)
 * [npm registry](/using-npm/registry)
 * [npm folders](/configuring-npm/folders)

docs/content/using-npm/config.md

@@ -618,6 +618,16 @@ Note that commands explicitly intended to run a particular script, such as
 will still run their intended script if `ignore-scripts` is set, but they
 will *not* run any pre- or post-scripts.
 
+#### `in-range`
+
+* Default: null
+* Type: null or Boolean
+
+When running `npm outdated` setting `--in-range` will limit output to only
+those packages with existing versions in range of the current project's
+dependencies. `--no-in-range` will limit output to only those packages with
+updates that are out of range of the current project's dependencies.
+
 #### `include`
 
 * Default:

lib/explain.js

@@ -19,7 +19,13 @@ class Explain extends ArboristWorkspaceCmd {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['<folder | specifier>']
+    return [
+      '<folder>',
+      '[<@scope>/]<pkg>',
+      '[<@scope>/]<pkg>@<tag>',
+      '[<@scope>/]<pkg>@<version>',
+      '[<@scope>/]<pkg>@<version range>',
+    ]
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */

lib/outdated.js

@@ -32,6 +32,7 @@ class Outdated extends ArboristWorkspaceCmd {
   static get params () {
     return [
       'all',
+      'in-range',
       'json',
       'long',
       'parseable',
@@ -116,6 +117,7 @@ class Outdated extends ArboristWorkspaceCmd {
         stringLength: s => ansiTrim(s).length,
       }
       this.npm.output(table(outTable, tableOpts))
+      this.npm.output('\nFor more info on why dependencies have been installed at their given versions, see `npm explain <pkg>`.')
     }
   }
 
@@ -231,17 +233,23 @@ class Outdated extends ArboristWorkspaceCmd {
           this.maybeWorkspaceName(edge.from)
           : 'global'
 
-        this.list.push({
-          name: edge.name,
-          path,
-          type,
-          current,
-          location,
-          wanted: wanted.version,
-          latest: latest.version,
-          dependent,
-          homepage: packument.homepage,
-        })
+        const include =
+          this.npm.config.get('in-range') === null ||
+          (this.npm.config.get('in-range') === true && wanted === latest) ||
+          (this.npm.config.get('in-range') === false && wanted !== latest)
+
+        if (include)
+          this.list.push({
+            name: edge.name,
+            path,
+            type,
+            current,
+            location,
+            wanted: wanted.version,
+            latest: latest.version,
+            dependent,
+            homepage: packument.homepage,
+          })
       }
     } catch (err) {
       // silently catch and ignore ETARGET, E403 &

lib/utils/config/definitions.js

@@ -1022,6 +1022,19 @@ define('init.version', {
   `,
 })
 
+define('in-range', {
+  default: null,
+  type: [null, Boolean],
+  description: `
+    When running \`npm outdated\` setting \`--in-range\` will limit output to
+    only those packages with existing versions in range of the current
+    project's dependencies.  \`--no-in-range\` will limit output to only those
+    packages with updates that are out of range of the current project's
+    dependencies.
+  `,
+  flatten,
+})
+
 define('json', {
   default: false,
   type: Boolean,

tap-snapshots/test/lib/load-all-commands.js.test.cjs

@@ -304,7 +304,11 @@ npm explain
 Explain installed packages
 
 Usage:
-npm explain <folder | specifier>
+npm explain <folder>
+npm explain [<@scope>/]<pkg>
+npm explain [<@scope>/]<pkg>@<tag>
+npm explain [<@scope>/]<pkg>@<version>
+npm explain [<@scope>/]<pkg>@<version range>
 
 Options:
 [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
@@ -624,7 +628,7 @@ Usage:
 npm outdated [[<@scope>/]<pkg> ...]
 
 Options:
-[-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global]
+[-a|--all] [--in-range] [--json] [-l|--long] [-p|--parseable] [-g|--global]
 [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
 
 Run "npm help outdated" for more info

tap-snapshots/test/lib/outdated.js.test.cjs

@@ -12,6 +12,18 @@ cat        1.0.0   1.0.1   1.0.1  node_modules/cat   tap-testdir-outdated-should
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  tap-testdir-outdated-should-display-outdated-deps
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog   tap-testdir-outdated-should-display-outdated-deps
 theta    MISSING   1.0.1   1.0.1  -                  tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
+`
+
+exports[`test/lib/outdated.js TAP should display outdated deps outdated --in-range > must match snapshot 1`] = `
+
+Package  Current  Wanted  Latest  Location           Depended by
+cat        1.0.0   1.0.1   1.0.1  node_modules/cat   tap-testdir-outdated-should-display-outdated-deps
+chai       1.0.0   1.0.1   1.0.1  node_modules/chai  tap-testdir-outdated-should-display-outdated-deps
+theta    MISSING   1.0.1   1.0.1  -                  tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated --json --long > must match snapshot 1`] = `
@@ -89,6 +101,16 @@ cat        1.0.0   1.0.1   1.0.1  node_modules/cat   tap-testdir-outdated-should
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  tap-testdir-outdated-should-display-outdated-deps  peerDependencies
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog   tap-testdir-outdated-should-display-outdated-deps  dependencies
 theta    MISSING   1.0.1   1.0.1  -                  tap-testdir-outdated-should-display-outdated-deps  dependencies
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
+`
+
+exports[`test/lib/outdated.js TAP should display outdated deps outdated --no-in-range > must match snapshot 1`] = `
+
+Package  Current  Wanted  Latest  Location          Depended by
+dog        1.0.1   1.0.1   2.0.0  node_modules/dog  tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=dev --omit=peer > must match snapshot 1`] = `
@@ -97,6 +119,8 @@ exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=d
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat  tap-testdir-outdated-should-display-outdated-deps
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog  tap-testdir-outdated-should-display-outdated-deps
 theta    MISSING   1.0.1   1.0.1  -                 tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=dev > must match snapshot 1`] = `
@@ -106,6 +130,8 @@ exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=d
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  tap-testdir-outdated-should-display-outdated-deps
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog   tap-testdir-outdated-should-display-outdated-deps
 theta    MISSING   1.0.1   1.0.1  -                  tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=prod > must match snapshot 1`] = `
@@ -114,6 +140,8 @@ exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=p
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat   tap-testdir-outdated-should-display-outdated-deps
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  tap-testdir-outdated-should-display-outdated-deps
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog   tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated --parseable --long > must match snapshot 1`] = `
@@ -139,18 +167,24 @@ exports[`test/lib/outdated.js TAP should display outdated deps outdated > must m
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  tap-testdir-outdated-should-display-outdated-deps
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog   tap-testdir-outdated-should-display-outdated-deps
 theta    MISSING   1.0.1   1.0.1  -                  tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated global > must match snapshot 1`] = `
 
 Package  Current  Wanted  Latest  Location          Depended by
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat  global
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP should display outdated deps outdated specific dep > must match snapshot 1`] = `
 
 Package  Current  Wanted  Latest  Location          Depended by
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat  tap-testdir-outdated-should-display-outdated-deps
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP workspaces > should display all dependencies 1`] = `
@@ -160,6 +194,8 @@ cat        1.0.0   1.0.1   1.0.1  node_modules/cat   a@1.0.0
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  foo
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog   tap-testdir-outdated-workspaces
 theta    MISSING   1.0.1   1.0.1  -                  c@1.0.0
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP workspaces > should display json results filtered by ws 1`] = `
@@ -179,13 +215,17 @@ exports[`test/lib/outdated.js TAP workspaces > should display missing deps when
 
 Package  Current  Wanted  Latest  Location  Depended by
 theta    MISSING   1.0.1   1.0.1  -         c@1.0.0
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP workspaces > should display nested deps when filtering by ws and using --all 1`] = `
 
 Package  Current  Wanted  Latest  Location           Depended by
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat   a@1.0.0
 chai       1.0.0   1.0.1   1.0.1  node_modules/chai  foo
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP workspaces > should display no results if ws has no deps to display 1`] = `
@@ -201,6 +241,8 @@ exports[`test/lib/outdated.js TAP workspaces > should display results filtered b
 
 Package  Current  Wanted  Latest  Location          Depended by
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat  a@1.0.0
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP workspaces > should display ws outdated deps human output 1`] = `
@@ -209,6 +251,8 @@ Package  Current  Wanted  Latest  Location          Depended by
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat  a@1.0.0
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog  tap-testdir-outdated-workspaces
 theta    MISSING   1.0.1   1.0.1  -                 c@1.0.0
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `
 
 exports[`test/lib/outdated.js TAP workspaces > should display ws outdated deps json output 1`] = `
@@ -249,4 +293,6 @@ exports[`test/lib/outdated.js TAP workspaces > should highlight ws in dependend
 cat        1.0.0   1.0.1   1.0.1  node_modules/cat  a@1.0.0
 dog        1.0.1   1.0.1   2.0.0  node_modules/dog  tap-testdir-outdated-workspaces
 theta    MISSING   1.0.1   1.0.1  -                 c@1.0.0
+
+For more info on why dependencies have been installed at their given versions, see \`npm explain <pkg>\`.
 `

tap-snapshots/test/lib/utils/config/definitions.js.test.cjs

@@ -75,6 +75,7 @@ Array [
   "init.license",
   "init.module",
   "init.version",
+  "in-range",
   "json",
   "key",
   "legacy-bundling",

tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs

@@ -497,6 +497,16 @@ Note that commands explicitly intended to run a particular script, such as
 will still run their intended script if \`ignore-scripts\` is set, but they
 will *not* run any pre- or post-scripts.
 
+#### \`in-range\`
+
+* Default: null
+* Type: null or Boolean
+
+When running \`npm outdated\` setting \`--in-range\` will limit output to only
+those packages with existing versions in range of the current project's
+dependencies. \`--no-in-range\` will limit output to only those packages with
+updates that are out of range of the current project's dependencies.
+
 #### \`include\`
 
 * Default:

tap-snapshots/test/lib/utils/npm-usage.js.test.cjs

@@ -429,7 +429,11 @@ All commands:
                     Explain installed packages
                     
                     Usage:
-                    npm explain <folder | specifier>
+                    npm explain <folder>
+                    npm explain [<@scope>/]<pkg>
+                    npm explain [<@scope>/]<pkg>@<tag>
+                    npm explain [<@scope>/]<pkg>@<version>
+                    npm explain [<@scope>/]<pkg>@<version range>
                     
                     Options:
                     [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
@@ -715,7 +719,7 @@ All commands:
                     npm outdated [[<@scope>/]<pkg> ...]
                     
                     Options:
-                    [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global]
+                    [-a|--all] [--in-range] [--json] [-l|--long] [-p|--parseable] [-g|--global]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
                     
                     Run "npm help outdated" for more info

test/lib/outdated.js

@@ -304,6 +304,28 @@ t.test('should display outdated deps', t => {
     })
   })
 
+  t.test('outdated --in-range', t => {
+    outdated(testDir, {
+      config: {
+        ['in-range']: true,
+      },
+    }).exec([], () => {
+      t.matchSnapshot(logs)
+      t.end()
+    })
+  })
+
+  t.test('outdated --no-in-range', t => {
+    outdated(testDir, {
+      config: {
+        ['in-range']: false,
+      },
+    }).exec([], () => {
+      t.matchSnapshot(logs)
+      t.end()
+    })
+  })
+
   t.test('outdated specific dep', t => {
     outdated(testDir, {
       config: {