feat: display overrides in ls, explain and query

docs/content/using-npm/dependency-selectors.md

@@ -54,7 +54,7 @@ The [`npm query`](/commands/npm-query) commmand exposes a new dependency selecto
 - [`:private`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#private) when a dependency is private
 - `:link` when a dependency is linked (for instance, workspaces or packages manually [`linked`](https://docs.npmjs.com/cli/v8/commands/npm-link)
 - `:deduped` when a dependency has been deduped (note that this does *not* always mean the dependency has been hoisted to the root of node_modules)
-- `:override` when a dependency is an override (not implemented yet)
+- `:overridden` when a dependency has been overridden
 - `:extraneous` when a dependency exists but is not defined as a dependency of any node
 - `:invalid` when a dependency version is out of its ancestors specified range
 - `:missing` when a dependency is not found on disk

lib/commands/explain.js

@@ -59,7 +59,7 @@ class Explain extends ArboristWorkspaceCmd {
 
     const expls = []
     for (const node of nodes) {
-      const { extraneous, dev, optional, devOptional, peer, inBundle } = node
+      const { extraneous, dev, optional, devOptional, peer, inBundle, overridden } = node
       const expl = node.explain()
       if (extraneous) {
         expl.extraneous = true
@@ -69,6 +69,7 @@ class Explain extends ArboristWorkspaceCmd {
         expl.devOptional = devOptional
         expl.peer = peer
         expl.bundled = inBundle
+        expl.overridden = overridden
       }
       expls.push(expl)
     }

lib/commands/ls.js

@@ -329,6 +329,11 @@ const getHumanOutputItem = (node, { args, color, global, long }) => {
         ? ' ' + (color ? chalk.green.bgBlack('extraneous') : 'extraneous')
         : ''
     ) +
+    (
+      node.overridden
+        ? ' ' + (color ? chalk.gray('overridden') : 'overridden')
+        : ''
+    ) +
     (isGitNode(node) ? ` (${node.resolved})` : '') +
     (node.isLink ? ` -> ${relativePrefix}${targetLocation}` : '') +
     (long ? `${EOL}${node.package.description || ''}` : '')
@@ -347,6 +352,13 @@ const getJsonOutputItem = (node, { global, long }) => {
     item.resolved = node.resolved
   }
 
+  // if the node is the project root, do not add the overridden flag. the project root can't be
+  // overridden anyway, and if we add the flag it causes undesirable behavior when `npm ls --json`
+  // is ran in an empty directory since we end up printing an object with only an overridden prop
+  if (!node.isProjectRoot) {
+    item.overridden = node.overridden
+  }
+
   item[_name] = node.name
 
   // special formatting for top-level package name
@@ -555,6 +567,7 @@ const parseableOutput = ({ global, long, seenNodes }) => {
         out += node.path !== node.realpath ? `:${node.realpath}` : ''
         out += isExtraneous(node, { global }) ? ':EXTRANEOUS' : ''
         out += node[_invalid] ? ':INVALID' : ''
+        out += node.overridden ? ':OVERRIDDEN' : ''
       }
       out += EOL
     }

lib/commands/query.js

@@ -20,6 +20,7 @@ class QuerySelectorItem {
     this.dev = node.target.dev
     this.inBundle = node.target.inBundle
     this.deduped = this.from.length > 1
+    this.overridden = node.overridden
     for (const edge of node.target.edgesIn) {
       this.from.push(edge.from.location)
     }

lib/utils/explain-dep.js

@@ -8,6 +8,7 @@ const nocolor = {
   magenta: s => s,
   blue: s => s,
   green: s => s,
+  gray: s => s,
 }
 
 const { relative } = require('path')
@@ -18,13 +19,14 @@ const explainNode = (node, depth, color) =>
   explainLinksIn(node, depth, color)
 
 const colorType = (type, color) => {
-  const { red, yellow, cyan, magenta, blue, green } = color ? chalk : nocolor
+  const { red, yellow, cyan, magenta, blue, green, gray } = color ? chalk : nocolor
   const style = type === 'extraneous' ? red
     : type === 'dev' ? yellow
     : type === 'optional' ? cyan
     : type === 'peer' ? magenta
     : type === 'bundled' ? blue
     : type === 'workspace' ? green
+    : type === 'overridden' ? gray
     : /* istanbul ignore next */ s => s
   return style(type)
 }
@@ -40,6 +42,7 @@ const printNode = (node, color) => {
     peer,
     bundled,
     isWorkspace,
+    overridden,
   } = node
   const { bold, dim, green } = color ? chalk : nocolor
   const extra = []
@@ -63,6 +66,10 @@ const printNode = (node, color) => {
     extra.push(' ' + bold(colorType('bundled', color)))
   }
 
+  if (overridden) {
+    extra.push(' ' + bold(colorType('overridden', color)))
+  }
+
   const pkgid = isWorkspace
     ? green(`${name}@${version}`)
     : `${bold(name)}@${bold(version)}`
@@ -112,11 +119,15 @@ const explainDependents = ({ name, dependents }, depth, color) => {
   return str.split('\n').join('\n  ')
 }
 
-const explainEdge = ({ name, type, bundled, from, spec }, depth, color) => {
+const explainEdge = ({ name, type, bundled, from, spec, rawSpec, overridden }, depth, color) => {
   const { bold } = color ? chalk : nocolor
-  const dep = type === 'workspace'
+  let dep = type === 'workspace'
     ? bold(relative(from.location, spec.slice('file:'.length)))
     : `${bold(name)}@"${bold(spec)}"`
+  if (overridden) {
+    dep = `${colorType('overridden', color)} ${dep} (was "${rawSpec}")`
+  }
+
   const fromMsg = ` from ${explainFrom(from, depth, color)}`
 
   return (type === 'prod' ? '' : `${colorType(type, color)} `) +

tap-snapshots/test/lib/commands/ls.js.test.cjs

@@ -255,6 +255,12 @@ exports[`test/lib/commands/ls.js TAP ls --parseable no args > should output pars
 {CWD}/tap-testdir-ls-ls---parseable-no-args/node_modules/dog
 `
 
+exports[`test/lib/commands/ls.js TAP ls --parseable overridden dep > should contain overridden outout 1`] = `
+{CWD}/tap-testdir-ls-ls---parseable-overridden-dep:test-overridden@1.0.0
+{CWD}/tap-testdir-ls-ls---parseable-overridden-dep/node_modules/foo:foo@1.0.0
+{CWD}/tap-testdir-ls-ls---parseable-overridden-dep/node_modules/bar:bar@1.0.0:OVERRIDDEN
+`
+
 exports[`test/lib/commands/ls.js TAP ls --parseable resolved points to git ref > should output tree containing git refs 1`] = `
 {CWD}/tap-testdir-ls-ls---parseable-resolved-points-to-git-ref
 {CWD}/tap-testdir-ls-ls---parseable-resolved-points-to-git-ref/node_modules/abbrev
@@ -567,6 +573,20 @@ test-npm-ls@1.0.0 {CWD}/tap-testdir-ls-ls-no-args
 
 `
 
+exports[`test/lib/commands/ls.js TAP ls overridden dep > should contain overridden outout 1`] = `
+test-overridden@1.0.0 {CWD}/tap-testdir-ls-ls-overridden-dep
+\`-- foo@1.0.0
+  \`-- bar@1.0.0 overridden
+
+`
+
+exports[`test/lib/commands/ls.js TAP ls overridden dep w/ color > should contain overridden outout 1`] = `
+test-overridden@1.0.0 {CWD}/tap-testdir-ls-ls-overridden-dep-w-color
+\`-- foo@1.0.0
+  \`-- bar@1.0.0 overridden
+
+`
+
 exports[`test/lib/commands/ls.js TAP ls print deduped symlinks > should output tree containing linked deps 1`] = `
 print-deduped-symlinks@1.0.0 {CWD}/tap-testdir-ls-ls-print-deduped-symlinks
 +-- a@1.0.0

tap-snapshots/test/lib/commands/query.js.test.cjs

@@ -22,7 +22,8 @@ exports[`test/lib/commands/query.js TAP global > should return global package 1`
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   }
 ]
 `
@@ -51,7 +52,8 @@ exports[`test/lib/commands/query.js TAP include-workspace-root > should return w
     ],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   },
   {
     "name": "c",
@@ -66,7 +68,8 @@ exports[`test/lib/commands/query.js TAP include-workspace-root > should return w
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   }
 ]
 `
@@ -86,7 +89,8 @@ exports[`test/lib/commands/query.js TAP linked node > should return linked node
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   }
 ]
 `
@@ -111,7 +115,8 @@ exports[`test/lib/commands/query.js TAP recursive tree > should return everythin
     ],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   },
   {
     "pkgid": "a@",
@@ -125,7 +130,8 @@ exports[`test/lib/commands/query.js TAP recursive tree > should return everythin
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   },
   {
     "pkgid": "b@",
@@ -139,7 +145,8 @@ exports[`test/lib/commands/query.js TAP recursive tree > should return everythin
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   }
 ]
 `
@@ -167,7 +174,8 @@ exports[`test/lib/commands/query.js TAP simple query > should return root object
     ],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   },
   {
     "pkgid": "a@",
@@ -181,7 +189,8 @@ exports[`test/lib/commands/query.js TAP simple query > should return root object
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   },
   {
     "pkgid": "b@",
@@ -195,7 +204,8 @@ exports[`test/lib/commands/query.js TAP simple query > should return root object
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   }
 ]
 `
@@ -215,7 +225,8 @@ exports[`test/lib/commands/query.js TAP workspace query > should return workspac
     "to": [],
     "dev": false,
     "inBundle": false,
-    "deduped": false
+    "deduped": false,
+    "overridden": false
   }
 ]
 `

tap-snapshots/test/lib/utils/explain-dep.js.test.cjs

@@ -156,6 +156,28 @@ optdep@1.0.0 optional
 node_modules/optdep
 `
 
+exports[`test/lib/utils/explain-dep.js TAP overridden > explain color deep 1`] = `
+overridden-root@1.0.0 overridden
+node_modules/overridden-root
+  overridden overridden-dep@"1.0.0" (was "^2.0.0") from the root project
+`
+
+exports[`test/lib/utils/explain-dep.js TAP overridden > explain nocolor shallow 1`] = `
+overridden-root@1.0.0 overridden
+node_modules/overridden-root
+  overridden overridden-dep@"1.0.0" (was "^2.0.0") from the root project
+`
+
+exports[`test/lib/utils/explain-dep.js TAP overridden > print color 1`] = `
+overridden-root@1.0.0 overridden
+node_modules/overridden-root
+`
+
+exports[`test/lib/utils/explain-dep.js TAP overridden > print nocolor 1`] = `
+overridden-root@1.0.0 overridden
+node_modules/overridden-root
+`
+
 exports[`test/lib/utils/explain-dep.js TAP peer > explain color deep 1`] = `
 peer@1.0.0 peer
 node_modules/peer