feat(help): refactor npm help/help-search

Lots of dead code removed thanks to streamlining of logic.
`npm help` `npm <command>` and `npm help-search` are all now separated
concerns, handling their own use cases. `help` calls `help-search` as a
last resort, but `npm <command>` no longer tries to wind its way through
to `help-search` just to get the basic npm usage displayed.

The `did you mean` output has been expanded. It now always suggests top
level commands, scripts, and bins, and suggests them in the way they
should be called.

PR-URL: #2859
Credit: @wraithgar
Close: #2859
Reviewed-by: @ruyadorno

Author: wraithgar

docs/content/commands/npm-dedupe.md

@@ -1,7 +1,7 @@
 ---
 title: npm-dedupe
 section: 1
-description: Reduce duplication
+description: Reduce duplication in the package tree
 ---
 
 ### Synopsis
@@ -10,7 +10,7 @@ description: Reduce duplication
 npm dedupe
 npm ddp
 
-aliases: find-dupes, ddp
+aliases: ddp
 ```
 
 ### Description
@@ -74,6 +74,7 @@ Using `npm find-dupes` will run the command in `--dry-run` mode.
 
 ### See Also
 
+* [npm find-dupes](/cli-commands/find-dupes)
 * [npm ls](/cli-commands/ls)
 * [npm update](/cli-commands/update)
 * [npm install](/cli-commands/install)

docs/content/commands/npm-find-dupes.md

@@ -0,0 +1,24 @@
+---
+title: npm-find-dupes
+section: 1
+description: Find duplication in the package tree
+---
+
+### Synopsis
+
+```bash
+npm find-dupes
+```
+
+### Description
+
+Runs `npm dedupe` in `--dry-run` mode, making npm only output the
+duplications, without actually changing the package tree.
+
+### See Also
+
+* [npm dedupe](/cli-commands/dedupe)
+* [npm ls](/cli-commands/ls)
+* [npm update](/cli-commands/update)
+* [npm install](/cli-commands/install)
+

docs/content/commands/npm-init.md

@@ -1,7 +1,7 @@
 ---
 title: npm-init
 section: 1
-description: create a package.json file
+description: Create a package.json file
 ---
 
 ### Synopsis

lib/access.js

@@ -20,6 +20,10 @@ const subcommands = [
 ]
 
 class Access extends BaseCommand {
+  static get description () {
+    return 'Set access level on published packages'
+  }
+
   static get name () {
     return 'access'
   }

lib/adduser.js

@@ -9,6 +9,10 @@ const authTypes = {
 }
 
 class AddUser extends BaseCommand {
+  static get description () {
+    return 'Add a registry user account'
+  }
+
   static get name () {
     return 'adduser'
   }

lib/audit.js

@@ -5,6 +5,11 @@ const auditError = require('./utils/audit-error.js')
 const BaseCommand = require('./base-command.js')
 
 class Audit extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Run a security audit'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'audit'

lib/base-command.js

@@ -6,6 +6,14 @@ class BaseCommand {
     this.npm = npm
   }
 
+  get name () {
+    return this.constructor.name
+  }
+
+  get description () {
+    return this.constructor.description
+  }
+
   get usage () {
     let usage = `npm ${this.constructor.name}\n\n`
     if (this.constructor.description)

lib/bin.js

@@ -2,6 +2,10 @@ const envPath = require('./utils/path.js')
 const BaseCommand = require('./base-command.js')
 
 class Bin extends BaseCommand {
+  static get description () {
+    return 'Display npm bin folder'
+  }
+
   static get name () {
     return 'bin'
   }

lib/bugs.js

@@ -5,6 +5,10 @@ const hostedFromMani = require('./utils/hosted-git-info-from-manifest.js')
 const BaseCommand = require('./base-command.js')
 
 class Bugs extends BaseCommand {
+  static get description () {
+    return 'Report bugs for a package in a web browser'
+  }
+
   static get name () {
     return 'bugs'
   }

lib/cache.js

@@ -7,6 +7,10 @@ const rimraf = promisify(require('rimraf'))
 const BaseCommand = require('./base-command.js')
 
 class Cache extends BaseCommand {
+  static get description () {
+    return 'Manipulates packages cache'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'cache'

lib/ci.js

@@ -20,6 +20,11 @@ const removeNodeModules = async where => {
 const BaseCommand = require('./base-command.js')
 
 class CI extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Install a project with a clean slate'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'ci'

lib/cli.js

@@ -40,11 +40,14 @@ module.exports = (process) => {
   npm.load(async er => {
     if (er)
       return errorHandler(er)
+
+    // npm --version=cli
     if (npm.config.get('version', 'cli')) {
-      console.log(npm.version)
+      npm.output(npm.version)
       return errorHandler.exit(0)
     }
 
+    // npm --versions=cli
     if (npm.config.get('versions', 'cli')) {
       npm.argv = ['version']
       npm.config.set('usage', false, 'cli')
@@ -57,9 +60,20 @@ module.exports = (process) => {
     if (impl)
       impl(npm.argv, errorHandler)
     else {
-      npm.config.set('usage', false)
-      npm.argv.unshift(cmd)
-      npm.commands.help(npm.argv, errorHandler)
+      try {
+        // I don't know why this is needed but we get a cb() not called if we
+        // omit it
+        npm.log.level = 'silent'
+        if (cmd) {
+          const didYouMean = require('./utils/did-you-mean.js')
+          const suggestions = await didYouMean(npm, cmd)
+          npm.output(suggestions)
+        } else
+          npm.output(npm.usage)
+        process.exitCode = 1
+      } catch (err) {
+        errorHandler(err)
+      }
     }
   })
 }

lib/completion.js

@@ -46,13 +46,13 @@ const BaseCommand = require('./base-command.js')
 
 class Completion extends BaseCommand {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get name () {
-    return 'completion'
+  static get description () {
+    return 'Tab Completion for npm'
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get description () {
-    return 'npm command completion script. save to ~/.bashrc or ~/.zshrc'
+  static get name () {
+    return 'completion'
   }
 
   // completion for the completion command

lib/config.js

@@ -30,6 +30,10 @@ const publicVar = k => !/^(\/\/[^:]+:)?_/.test(k)
 
 const BaseCommand = require('./base-command.js')
 class Config extends BaseCommand {
+  static get description () {
+    return 'Manage the npm configuration files'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'config'

lib/dedupe.js

@@ -5,6 +5,11 @@ const reifyFinish = require('./utils/reify-finish.js')
 const BaseCommand = require('./base-command.js')
 
 class Dedupe extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Reduce duplication in the package tree'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'dedupe'

lib/deprecate.js

@@ -7,6 +7,10 @@ const libaccess = require('libnpmaccess')
 const BaseCommand = require('./base-command.js')
 
 class Deprecate extends BaseCommand {
+  static get description () {
+    return 'Deprecate a version of a package'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'deprecate'

lib/diff.js

@@ -12,6 +12,10 @@ const readLocalPkg = require('./utils/read-local-package.js')
 const BaseCommand = require('./base-command.js')
 
 class Diff extends BaseCommand {
+  static get description () {
+    return 'The registry diff command'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'diff'

lib/dist-tag.js

@@ -8,6 +8,10 @@ const readLocalPkgName = require('./utils/read-local-package.js')
 const BaseCommand = require('./base-command.js')
 
 class DistTag extends BaseCommand {
+  static get description () {
+    return 'Modify package distribution tags'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'dist-tag'

lib/docs.js

@@ -1,17 +1,23 @@
 const log = require('npmlog')
 const pacote = require('pacote')
 const openUrl = require('./utils/open-url.js')
-const usageUtil = require('./utils/usage.js')
 const hostedFromMani = require('./utils/hosted-git-info-from-manifest.js')
 
-class Docs {
-  constructor (npm) {
-    this.npm = npm
+const BaseCommand = require('./base-command.js')
+class Docs extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Open documentation for a package in a web browser'
+  }
+
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get name () {
+    return 'docs'
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  get usage () {
-    return usageUtil('docs', 'npm docs [<pkgname> [<pkgname> ...]]')
+  static get usage () {
+    return ['[<pkgname> [<pkgname> ...]]']
   }
 
   exec (args, cb) {

lib/doctor.js

@@ -32,6 +32,11 @@ const maskLabel = mask => {
 
 const BaseCommand = require('./base-command.js')
 class Doctor extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Check your npm environment'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'doctor'

lib/edit.js

@@ -9,6 +9,10 @@ const completion = require('./utils/completion/installed-shallow.js')
 const BaseCommand = require('./base-command.js')
 
 class Edit extends BaseCommand {
+  static get description () {
+    return 'Edit an installed package'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'edit'

lib/exec.js

@@ -40,13 +40,13 @@ const BaseCommand = require('./base-command.js')
 
 class Exec extends BaseCommand {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get name () {
-    return 'exec'
+  static get description () {
+    return 'Run a command from a local or remote npm package'
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get description () {
-    return 'Run a command from a local or remote npm package.'
+  static get name () {
+    return 'exec'
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */

lib/explain.js

@@ -8,6 +8,10 @@ const validName = require('validate-npm-package-name')
 const BaseCommand = require('./base-command.js')
 
 class Explain extends BaseCommand {
+  static get description () {
+    return 'Explain installed packages'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'explain'

lib/explore.js

@@ -8,6 +8,10 @@ const completion = require('./utils/completion/installed-shallow.js')
 const BaseCommand = require('./base-command.js')
 
 class Explore extends BaseCommand {
+  static get description () {
+    return 'Browse an installed package'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'explore'

lib/find-dupes.js

@@ -2,6 +2,11 @@
 const BaseCommand = require('./base-command.js')
 
 class FindDupes extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Find duplication in the package tree'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'find-dupes'

lib/fund.js

@@ -22,6 +22,11 @@ const getPrintableName = ({ name, version }) => {
 const BaseCommand = require('./base-command.js')
 
 class Fund extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Retrieve funding information'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'fund'

lib/get.js

@@ -1,6 +1,11 @@
 const BaseCommand = require('./base-command.js')
 
 class Get extends BaseCommand {
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get description () {
+    return 'Get a value from the npm configuration'
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'get'