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,24 @@ 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: {