feat(explain): add workspaces support

- Add highlight style for workspaces items in human output
- Add ability to filter results by workspace using `-w` config
- Added tests and docs

Fixes: https://github.com/npm/statusboard/issues/300

PR-URL: https://github.com/npm/cli/pull/3265
Credit: @ruyadorno
Close: #3265
Reviewed-by: @isaacs

2 files changed, 162 insertions, 5 deletions

diff --git a/test/lib/explain.js b/test/lib/explain.js
index 7e4ec8bd3..f690aeb2c 100644
--- a/test/lib/explain.js
+++ b/test/lib/explain.js
@@ -175,3 +175,129 @@ t.test('explain some nodes', t => {
   })
   t.end()
 })
+
+t.test('workspaces', async t => {
+  npm.localPrefix = npm.prefix = t.testdir({
+    'package.json': JSON.stringify({
+      name: 'workspaces-project',
+      version: '1.0.0',
+      workspaces: ['packages/*'],
+      dependencies: {
+        abbrev: '^1.0.0',
+      },
+    }),
+    node_modules: {
+      a: t.fixture('symlink', '../packages/a'),
+      b: t.fixture('symlink', '../packages/b'),
+      c: t.fixture('symlink', '../packages/c'),
+      once: {
+        'package.json': JSON.stringify({
+          name: 'once',
+          version: '1.0.0',
+          dependencies: {
+            wrappy: '2.0.0',
+          },
+        }),
+      },
+      abbrev: {
+        'package.json': JSON.stringify({
+          name: 'abbrev',
+          version: '1.0.0',
+        }),
+      },
+      wrappy: {
+        'package.json': JSON.stringify({
+          name: 'wrappy',
+          version: '2.0.0',
+        }),
+      },
+    },
+    packages: {
+      a: {
+        'package.json': JSON.stringify({
+          name: 'a',
+          version: '1.0.0',
+          dependencies: {
+            once: '1.0.0',
+          },
+        }),
+      },
+      b: {
+        'package.json': JSON.stringify({
+          name: 'b',
+          version: '1.0.0',
+          dependencies: {
+            abbrev: '^1.0.0',
+          },
+        }),
+      },
+      c: {
+        'package.json': JSON.stringify({
+          name: 'c',
+          version: '1.0.0',
+        }),
+      },
+    },
+  })
+
+  await new Promise((res, rej) => {
+    explain.exec(['wrappy'], err => {
+      if (err)
+        rej(err)
+
+      t.strictSame(
+        OUTPUT,
+        [['wrappy@2.0.0 depth=Infinity color=true']],
+        'should explain workspaces deps'
+      )
+      OUTPUT.length = 0
+      res()
+    })
+  })
+
+  await new Promise((res, rej) => {
+    explain.execWorkspaces(['wrappy'], ['a'], err => {
+      if (err)
+        rej(err)
+
+      t.strictSame(
+        OUTPUT,
+        [
+          ['wrappy@2.0.0 depth=Infinity color=true'],
+        ],
+        'should explain deps when filtering to a single ws'
+      )
+      OUTPUT.length = 0
+      res()
+    })
+  })
+
+  await new Promise((res, rej) => {
+    explain.execWorkspaces(['abbrev'], [], err => {
+      if (err)
+        rej(err)
+
+      t.strictSame(
+        OUTPUT,
+        [
+          ['abbrev@1.0.0 depth=Infinity color=true'],
+        ],
+        'should explain deps of workspaces only'
+      )
+      OUTPUT.length = 0
+      res()
+    })
+  })
+
+  await new Promise((res, rej) => {
+    explain.execWorkspaces(['abbrev'], ['a'], err => {
+      t.equal(
+        err,
+        'No dependencies found matching abbrev',
+        'should throw usage if dep not found within filtered ws'
+      )
+
+      res()
+    })
+  })
+})
diff --git a/test/lib/utils/explain-dep.js b/test/lib/utils/explain-dep.js
index cab4d7b59..000f5b816 100644
--- a/test/lib/utils/explain-dep.js
+++ b/test/lib/utils/explain-dep.js
@@ -1,8 +1,16 @@
+const { resolve } = require('path')
 const t = require('tap')
-const npm = {}
-const { explainNode, printNode } = t.mock('../../../lib/utils/explain-dep.js', {
-  '../../../lib/npm.js': npm,
-})
+const { explainNode, printNode } = require('../../../lib/utils/explain-dep.js')
+const testdir = t.testdirName
+
+const redactCwd = (path) => {
+  const normalizePath = p => p
+    .replace(/\\+/g, '/')
+    .replace(/\r\n/g, '\n')
+  return normalizePath(path)
+    .replace(new RegExp(normalizePath(process.cwd()), 'g'), '{CWD}')
+}
+t.cleanSnapshot = (str) => redactCwd(str)
 
 const cases = {
   prodDep: {
@@ -204,9 +212,32 @@ cases.manyDeps = {
   ],
 }
 
+cases.workspaces = {
+  name: 'a',
+  version: '1.0.0',
+  location: 'a',
+  isWorkspace: true,
+  dependents: [],
+  linksIn: [
+    {
+      name: 'a',
+      version: '1.0.0',
+      location: 'node_modules/a',
+      isWorkspace: true,
+      dependents: [
+        {
+          type: 'workspace',
+          name: 'a',
+          spec: `file:${resolve(testdir, 'ws-project', 'a')}`,
+          from: { location: resolve(testdir, 'ws-project') },
+        },
+      ],
+    },
+  ],
+}
+
 for (const [name, expl] of Object.entries(cases)) {
   t.test(name, t => {
-    npm.color = true
     t.matchSnapshot(printNode(expl, true), 'print color')
     t.matchSnapshot(printNode(expl, false), 'print nocolor')
     t.matchSnapshot(explainNode(expl, Infinity, true), 'explain color deep')