diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md index bc9263d7aeda7..85fe261a923c4 100644 --- a/docs/content/commands/npm-outdated.md +++ b/docs/content/commands/npm-outdated.md @@ -9,7 +9,6 @@ description: Check for outdated packages ```bash npm outdated [[<@scope>/] ...] ``` - ### 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](/commmands/explain) * [npm dist-tag](/commands/npm-dist-tag) * [npm registry](/using-npm/registry) * [npm folders](/configuring-npm/folders) diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md index 44b79a801f15e..a97a7ac6c072c 100644 --- a/docs/content/using-npm/config.md +++ b/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: diff --git a/lib/explain.js b/lib/explain.js index de04c69857240..03cbc1d62d59c 100644 --- a/lib/explain.js +++ b/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 [''] + return [ + '', + '[<@scope>/]', + '[<@scope>/]@', + '[<@scope>/]@', + '[<@scope>/]@', + ] } /* istanbul ignore next - see test/lib/load-all-commands.js */ diff --git a/lib/outdated.js b/lib/outdated.js index 1be92b9349fe7..3b442b00e39d4 100644 --- a/lib/outdated.js +++ b/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 current version, see:\n npm explain ') } } @@ -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.version === latest.version) || + (this.npm.config.get('in-range') === false && wanted.version !== latest.version) + + 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 & diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js index ce7702aaa4f79..c9b5ab90dab09 100644 --- a/lib/utils/config/definitions.js +++ b/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, diff --git a/tap-snapshots/smoke-tests/index.js.test.cjs b/tap-snapshots/smoke-tests/index.js.test.cjs index 89c0cb20b5e36..fddb9cb524278 100644 --- a/tap-snapshots/smoke-tests/index.js.test.cjs +++ b/tap-snapshots/smoke-tests/index.js.test.cjs @@ -480,6 +480,9 @@ exports[`smoke-tests/index.js TAP npm outdated > should have expected outdated o Package Current Wanted Latest Location Depended by abbrev 1.0.4 1.1.1 1.1.1 node_modules/abbrev project +For more info on why dependencies have been installed at their current version, see: + npm explain + ` exports[`smoke-tests/index.js TAP npm prefix > should have expected prefix output 1`] = ` diff --git a/tap-snapshots/test/lib/load-all-commands.js.test.cjs b/tap-snapshots/test/lib/load-all-commands.js.test.cjs index 097123d46a3cc..d225581073485 100644 --- a/tap-snapshots/test/lib/load-all-commands.js.test.cjs +++ b/tap-snapshots/test/lib/load-all-commands.js.test.cjs @@ -304,7 +304,11 @@ npm explain Explain installed packages Usage: -npm explain +npm explain +npm explain [<@scope>/] +npm explain [<@scope>/]@ +npm explain [<@scope>/]@ +npm explain [<@scope>/]@ Options: [--json] [-w|--workspace [-w|--workspace ...]] @@ -624,7 +628,7 @@ Usage: npm outdated [[<@scope>/] ...] Options: -[-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] +[-a|--all] [--in-range] [--json] [-l|--long] [-p|--parseable] [-g|--global] [-w|--workspace [-w|--workspace ...]] Run "npm help outdated" for more info diff --git a/tap-snapshots/test/lib/outdated.js.test.cjs b/tap-snapshots/test/lib/outdated.js.test.cjs index 9f589d0134c03..f6bbb1e707b86 100644 --- a/tap-snapshots/test/lib/outdated.js.test.cjs +++ b/tap-snapshots/test/lib/outdated.js.test.cjs @@ -12,6 +12,20 @@ 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 current version, see: + npm explain +` + +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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP should display outdated deps outdated --json --long > must match snapshot 1`] = ` @@ -89,6 +103,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 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 current version, see: + npm explain +` + +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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=dev --omit=peer > must match snapshot 1`] = ` @@ -97,6 +123,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=dev > must match snapshot 1`] = ` @@ -106,6 +135,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP should display outdated deps outdated --omit=prod > must match snapshot 1`] = ` @@ -114,6 +146,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP should display outdated deps outdated --parseable --long > must match snapshot 1`] = ` @@ -139,18 +174,27 @@ 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 current version, see: + npm explain ` 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 current version, see: + npm explain ` 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP workspaces > should display all dependencies 1`] = ` @@ -160,6 +204,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP workspaces > should display json results filtered by ws 1`] = ` @@ -179,6 +226,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP workspaces > should display nested deps when filtering by ws and using --all 1`] = ` @@ -186,6 +236,9 @@ exports[`test/lib/outdated.js TAP workspaces > should display nested deps when f 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP workspaces > should display no results if ws has no deps to display 1`] = ` @@ -201,6 +254,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP workspaces > should display ws outdated deps human output 1`] = ` @@ -209,6 +265,9 @@ 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 current version, see: + npm explain ` exports[`test/lib/outdated.js TAP workspaces > should display ws outdated deps json output 1`] = ` @@ -249,4 +308,7 @@ 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 current version, see: + npm explain ` diff --git a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs index 32443c57af35b..8f2a0ffa74a3a 100644 --- a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs +++ b/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", diff --git a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs index da8cd1794f2ac..9ff1640710d79 100644 --- a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs +++ b/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: diff --git a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs index 54f6c3d2feb2a..769067352b541 100644 --- a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs +++ b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs @@ -429,7 +429,11 @@ All commands: Explain installed packages Usage: - npm explain + npm explain + npm explain [<@scope>/] + npm explain [<@scope>/]@ + npm explain [<@scope>/]@ + npm explain [<@scope>/]@ Options: [--json] [-w|--workspace [-w|--workspace ...]] @@ -715,7 +719,7 @@ All commands: npm outdated [[<@scope>/] ...] Options: - [-a|--all] [--json] [-l|--long] [-p|--parseable] [-g|--global] + [-a|--all] [--in-range] [--json] [-l|--long] [-p|--parseable] [-g|--global] [-w|--workspace [-w|--workspace ...]] Run "npm help outdated" for more info diff --git a/test/lib/outdated.js b/test/lib/outdated.js index 462ec0fc62b6c..7e13536f369f3 100644 --- a/test/lib/outdated.js +++ b/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: {