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: https://github.com/npm/cli/pull/2859
Credit: @wraithgar
Close: #2859
Reviewed-by: @ruyadorno

3 files changed, 154 insertions, 58 deletions

diff --git a/tap-snapshots/test-lib-dist-tag.js-TAP.test.js b/tap-snapshots/test-lib-dist-tag.js-TAP.test.js
index 89a87ae64..06936795b 100644
--- a/tap-snapshots/test-lib-dist-tag.js-TAP.test.js
+++ b/tap-snapshots/test-lib-dist-tag.js-TAP.test.js
@@ -8,6 +8,8 @@
 exports[`test/lib/dist-tag.js TAP add missing args > should exit usage error message 1`] = `
 npm dist-tag
 
+Modify package distribution tags
+
 Usage:
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
@@ -21,6 +23,8 @@ Run "npm help dist-tag" for more info
 exports[`test/lib/dist-tag.js TAP add missing pkg name > should exit usage error message 1`] = `
 npm dist-tag
 
+Modify package distribution tags
+
 Usage:
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
@@ -43,6 +47,8 @@ dist-tag add 1.0.0 to @scoped/another@7.7.7
 exports[`test/lib/dist-tag.js TAP borked cmd usage > should show usage error 1`] = `
 npm dist-tag
 
+Modify package distribution tags
+
 Usage:
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
@@ -62,6 +68,8 @@ latest: 1.0.0
 exports[`test/lib/dist-tag.js TAP ls on missing name in current package > should throw usage error message 1`] = `
 npm dist-tag
 
+Modify package distribution tags
+
 Usage:
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
@@ -111,6 +119,8 @@ exports[`test/lib/dist-tag.js TAP remove existing tag > should return success ms
 exports[`test/lib/dist-tag.js TAP remove missing pkg name > should exit usage error message 1`] = `
 npm dist-tag
 
+Modify package distribution tags
+
 Usage:
 npm dist-tag add <pkg>@<version> [<tag>]
 npm dist-tag rm <pkg> <tag>
diff --git a/tap-snapshots/test-lib-publish.js-TAP.test.js b/tap-snapshots/test-lib-publish.js-TAP.test.js
index 97ce7a773..e777797d7 100644
--- a/tap-snapshots/test-lib-publish.js-TAP.test.js
+++ b/tap-snapshots/test-lib-publish.js-TAP.test.js
@@ -8,6 +8,8 @@
 exports[`test/lib/publish.js TAP shows usage with wrong set of arguments > should print usage 1`] = `
 npm publish
 
+Publish a package
+
 Usage:
 npm publish [<folder>] [--tag <tag>] [--access <public|restricted>] [--dry-run]
 
diff --git a/tap-snapshots/test-lib-utils-npm-usage.js-TAP.test.js b/tap-snapshots/test-lib-utils-npm-usage.js-TAP.test.js
index caabec66b..11f7ff024 100644
--- a/tap-snapshots/test-lib-utils-npm-usage.js-TAP.test.js
+++ b/tap-snapshots/test-lib-utils-npm-usage.js-TAP.test.js
@@ -6,8 +6,9 @@
  */
 'use strict'
 exports[`test/lib/utils/npm-usage.js TAP usage basic usage > must match snapshot 1`] = `
+npm <command>
 
-Usage: npm <command>
+Usage:
 
 npm install        install all the dependencies in your project
 npm install <foo>  add the <foo> dependency to your project
@@ -38,55 +39,12 @@ More configuration info: npm help config
 Configuration fields: npm help 7 config
 
 npm@{VERSION} {BASEDIR}
-
-`
-
-exports[`test/lib/utils/npm-usage.js TAP usage did you mean? > must match snapshot 1`] = `
-
-Usage: npm <command>
-
-npm install        install all the dependencies in your project
-npm install <foo>  add the <foo> dependency to your project
-npm test           run this project's tests
-npm run <foo>      run the script named <foo>
-npm <command> -h   quick help on <command>
-npm -l             display usage info for all commands
-npm help <term>    search for help on <term>
-npm help npm       more involved overview
-
-All commands:
-
-    access, adduser, audit, bin, bugs, cache, ci, completion,
-    config, dedupe, deprecate, diff, dist-tag, docs, doctor,
-    edit, exec, explain, explore, find-dupes, fund, get, help,
-    hook, init, install, install-ci-test, install-test, link,
-    ll, login, logout, ls, org, outdated, owner, pack, ping,
-    prefix, profile, prune, publish, rebuild, repo, restart,
-    root, run-script, search, set, set-script, shrinkwrap, star,
-    stars, start, stop, team, test, token, uninstall, unpublish,
-    unstar, update, version, view, whoami
-
-Specify configs in the ini-formatted file:
-    /some/config/file/.npmrc
-or on the command line via: npm <command> --key=value
-
-More configuration info: npm help config
-Configuration fields: npm help 7 config
-
-npm@{VERSION} {BASEDIR}
-
-`
-
-exports[`test/lib/utils/npm-usage.js TAP usage did you mean? > must match snapshot 2`] = `
-
-Did you mean one of these?
-    install
-    uninstall
 `
 
 exports[`test/lib/utils/npm-usage.js TAP usage set process.stdout.columns columns=0 > must match snapshot 1`] = `
+npm <command>
 
-Usage: npm <command>
+Usage:
 
 npm install        install all the dependencies in your project
 npm install <foo>  add the <foo> dependency to your project
@@ -117,12 +75,12 @@ More configuration info: npm help config
 Configuration fields: npm help 7 config
 
 npm@{VERSION} {BASEDIR}
-
 `
 
 exports[`test/lib/utils/npm-usage.js TAP usage set process.stdout.columns columns=90 > must match snapshot 1`] = `
+npm <command>
 
-Usage: npm <command>
+Usage:
 
 npm install        install all the dependencies in your project
 npm install <foo>  add the <foo> dependency to your project
@@ -153,12 +111,12 @@ More configuration info: npm help config
 Configuration fields: npm help 7 config
 
 npm@{VERSION} {BASEDIR}
-
 `
 
 exports[`test/lib/utils/npm-usage.js TAP usage with browser > must match snapshot 1`] = `
+npm <command>
 
-Usage: npm <command>
+Usage:
 
 npm install        install all the dependencies in your project
 npm install <foo>  add the <foo> dependency to your project
@@ -189,12 +147,12 @@ More configuration info: npm help config
 Configuration fields: npm help 7 config
 
 npm@{VERSION} {BASEDIR}
-
 `
 
 exports[`test/lib/utils/npm-usage.js TAP usage with long > must match snapshot 1`] = `
+npm <command>
 
-Usage: npm <command>
+Usage:
 
 npm install        install all the dependencies in your project
 npm install <foo>  add the <foo> dependency to your project
@@ -209,6 +167,8 @@ All commands:
 
     access          npm access
                     
+                    Set access level on published packages
+                    
                     Usage:
                     npm access public [<package>]
                     npm access restricted [<package>]
@@ -224,6 +184,8 @@ All commands:
 
     adduser         npm adduser
                     
+                    Add a registry user account
+                    
                     Usage:
                     npm adduser [--registry=url] [--scope=@orgname] [--always-auth]
                     
@@ -233,6 +195,8 @@ All commands:
 
     audit           npm audit
                     
+                    Run a security audit
+                    
                     Usage:
                     npm audit [--json] [--production]
                     npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)]
@@ -241,6 +205,8 @@ All commands:
 
     bin             npm bin
                     
+                    Display npm bin folder
+                    
                     Usage:
                     npm bin [-g]
                     
@@ -248,6 +214,8 @@ All commands:
 
     bugs            npm bugs
                     
+                    Report bugs for a package in a web browser
+                    
                     Usage:
                     npm bugs [<pkgname>]
                     
@@ -257,6 +225,8 @@ All commands:
 
     cache           npm cache
                     
+                    Manipulates packages cache
+                    
                     Usage:
                     npm cache add <tarball file>
                     npm cache add <folder>
@@ -270,6 +240,8 @@ All commands:
 
     ci              npm ci
                     
+                    Install a project with a clean slate
+                    
                     Usage:
                     npm ci
                     
@@ -279,7 +251,7 @@ All commands:
 
     completion      npm completion
                     
-                    npm command completion script. save to ~/.bashrc or ~/.zshrc
+                    Tab Completion for npm
                     
                     Usage:
                     npm completion
@@ -288,6 +260,8 @@ All commands:
 
     config          npm config
                     
+                    Manage the npm configuration files
+                    
                     Usage:
                     npm config set <key>=<value> [<key>=<value> ...]
                     npm config get [<key> [<key> ...]]
@@ -301,6 +275,8 @@ All commands:
 
     dedupe          npm dedupe
                     
+                    Reduce duplication in the package tree
+                    
                     Usage:
                     npm dedupe
                     
@@ -310,6 +286,8 @@ All commands:
 
     deprecate       npm deprecate
                     
+                    Deprecate a version of a package
+                    
                     Usage:
                     npm deprecate <pkg>[@<version>] <message>
                     
@@ -317,6 +295,8 @@ All commands:
 
     diff            npm diff
                     
+                    The registry diff command
+                    
                     Usage:
                     npm diff [...<paths>]
                     npm diff --diff=<pkg-name> [...<paths>]
@@ -328,6 +308,8 @@ All commands:
 
     dist-tag        npm dist-tag
                     
+                    Modify package distribution tags
+                    
                     Usage:
                     npm dist-tag add <pkg>@<version> [<tag>]
                     npm dist-tag rm <pkg> <tag>
@@ -337,12 +319,21 @@ All commands:
                     
                     Run "npm help dist-tag" for more info
 
-    docs            npm docs [<pkgname> [<pkgname> ...]]
+    docs            npm docs
+                    
+                    Open documentation for a package in a web browser
+                    
+                    Usage:
+                    npm docs [<pkgname> [<pkgname> ...]]
                     
                     alias: home
+                    
+                    Run "npm help docs" for more info
 
     doctor          npm doctor
                     
+                    Check your npm environment
+                    
                     Usage:
                     npm doctor
                     
@@ -350,6 +341,8 @@ All commands:
 
     edit            npm edit
                     
+                    Edit an installed package
+                    
                     Usage:
                     npm edit <pkg>[/<subpkg>...]
                     
@@ -357,7 +350,7 @@ All commands:
 
     exec            npm exec
                     
-                    Run a command from a local or remote npm package.
+                    Run a command from a local or remote npm package
                     
                     Usage:
                     npm exec -- <pkg>[@<version>] [args...]
@@ -371,6 +364,8 @@ All commands:
 
     explain         npm explain
                     
+                    Explain installed packages
+                    
                     Usage:
                     npm explain <folder | specifier>
                     
@@ -380,6 +375,8 @@ All commands:
 
     explore         npm explore
                     
+                    Browse an installed package
+                    
                     Usage:
                     npm explore <pkg> [ -- <command>]
                     
@@ -387,6 +384,8 @@ All commands:
 
     find-dupes      npm find-dupes
                     
+                    Find duplication in the package tree
+                    
                     Usage:
                     npm find-dupes
                     
@@ -394,6 +393,8 @@ All commands:
 
     fund            npm fund
                     
+                    Retrieve funding information
+                    
                     Usage:
                     npm fund [--json] [--browser] [--unicode] [[<@scope>/]<pkg> [--which=<fundingSourceNumber>]
                     
@@ -401,6 +402,8 @@ All commands:
 
     get             npm get
                     
+                    Get a value from the npm configuration
+                    
                     Usage:
                     npm get [<key> ...] (See \`npm config\`)
                     
@@ -408,6 +411,8 @@ All commands:
 
     help            npm help
                     
+                    Get help on npm
+                    
                     Usage:
                     npm help <term> [<terms..>]
                     
@@ -417,6 +422,8 @@ All commands:
 
     hook            npm hook
                     
+                    Manage registry hooks
+                    
                     Usage:
                     npm hook add <pkg> <url> <secret> [--type=<type>]
                     npm hook ls [pkg]
@@ -427,6 +434,8 @@ All commands:
 
     init            npm init
                     
+                    Create a package.json file
+                    
                     Usage:
                     npm init [--force|-f|--yes|-y|--scope]
                     npm init <@scope> (same as \`npx <@scope>/create\`)
@@ -438,6 +447,8 @@ All commands:
 
     install         npm install
                     
+                    Install a package
+                    
                     Usage:
                     npm install [<@scope>/]<pkg>
                     npm install [<@scope>/]<pkg>@<tag>
@@ -456,6 +467,8 @@ All commands:
 
     install-ci-test npm install-ci-test
                     
+                    Install a project with a clean slate and run tests
+                    
                     Usage:
                     npm install-ci-test
                     
@@ -465,6 +478,8 @@ All commands:
 
     install-test    npm install-test
                     
+                    Install package(s) and run tests
+                    
                     Usage:
                     npm install-test [<@scope>/]<pkg>
                     npm install-test [<@scope>/]<pkg>@<tag>
@@ -483,6 +498,8 @@ All commands:
 
     link            npm link
                     
+                    Symlink a package folder
+                    
                     Usage:
                     npm link (in package dir)
                     npm link [<@scope>/]<pkg>[@<version>]
@@ -493,6 +510,8 @@ All commands:
 
     ll              npm ll
                     
+                    List installed packages
+                    
                     Usage:
                     npm ll [[<@scope>/]<pkg> ...]
                     
@@ -502,6 +521,8 @@ All commands:
 
     login           npm adduser
                     
+                    Add a registry user account
+                    
                     Usage:
                     npm adduser [--registry=url] [--scope=@orgname] [--always-auth]
                     
@@ -511,6 +532,8 @@ All commands:
 
     logout          npm logout
                     
+                    Log out of the registry
+                    
                     Usage:
                     npm logout [--registry=<url>] [--scope=<@scope>]
                     
@@ -518,6 +541,8 @@ All commands:
 
     ls              npm ls
                     
+                    List installed packages
+                    
                     Usage:
                     npm ls npm ls [[<@scope>/]<pkg> ...]
                     
@@ -527,6 +552,8 @@ All commands:
 
     org             npm org
                     
+                    Manage orgs
+                    
                     Usage:
                     npm org set orgname username [developer | admin | owner]
                     npm org rm orgname username
@@ -538,6 +565,8 @@ All commands:
 
     outdated        npm outdated
                     
+                    Check for outdated packages
+                    
                     Usage:
                     npm outdated [[<@scope>/]<pkg> ...]
                     
@@ -545,6 +574,8 @@ All commands:
 
     owner           npm owner
                     
+                    Manage package owners
+                    
                     Usage:
                     npm owner add <user> [<@scope>/]<pkg>
                     npm owner rm <user> [<@scope>/]<pkg>
@@ -556,6 +587,8 @@ All commands:
 
     pack            npm pack
                     
+                    Create a tarball from a package
+                    
                     Usage:
                     npm pack [[<@scope>/]<pkg>...] [--dry-run]
                     
@@ -563,7 +596,7 @@ All commands:
 
     ping            npm ping
                     
-                    ping registry
+                    Ping npm registry
                     
                     Usage:
                     npm ping
@@ -572,6 +605,8 @@ All commands:
 
     prefix          npm prefix
                     
+                    Display prefix
+                    
                     Usage:
                     npm prefix [-g]
                     
@@ -579,6 +614,8 @@ All commands:
 
     profile         npm profile
                     
+                    Change settings on your registry profile
+                    
                     Usage:
                     npm profile enable-2fa [auth-only|auth-and-writes]
                     npm profile disable-2fa
@@ -589,6 +626,8 @@ All commands:
 
     prune           npm prune
                     
+                    Remove extraneous packages
+                    
                     Usage:
                     npm prune [[<@scope>/]<pkg>...] [--production]
                     
@@ -596,6 +635,8 @@ All commands:
 
     publish         npm publish
                     
+                    Publish a package
+                    
                     Usage:
                     npm publish [<folder>] [--tag <tag>] [--access <public|restricted>] [--dry-run]
                     
@@ -603,6 +644,8 @@ All commands:
 
     rebuild         npm rebuild
                     
+                    Rebuild a package
+                    
                     Usage:
                     npm rebuild [[<@scope>/]<name>[@<version>] ...]
                     
@@ -612,6 +655,8 @@ All commands:
 
     repo            npm repo
                     
+                    Open package repository page in the browser
+                    
                     Usage:
                     npm repo [<pkgname> [<pkgname> ...]]
                     
@@ -619,6 +664,8 @@ All commands:
 
     restart         npm restart
                     
+                    Restart a package
+                    
                     Usage:
                     npm restart [-- <args>]
                     
@@ -626,6 +673,8 @@ All commands:
 
     root            npm root
                     
+                    Display npm root
+                    
                     Usage:
                     npm root [-g]
                     
@@ -633,6 +682,8 @@ All commands:
 
     run-script      npm run-script
                     
+                    Run arbitrary package scripts
+                    
                     Usage:
                     npm run-script <command> [-- <args>]
                     
@@ -642,6 +693,8 @@ All commands:
 
     search          npm search
                     
+                    Search for pacakges
+                    
                     Usage:
                     npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]
                     
@@ -651,6 +704,8 @@ All commands:
 
     set             npm set
                     
+                    Set a value in the npm configuration
+                    
                     Usage:
                     npm set <key>=<value> [<key>=<value> ...] (See \`npm config\`)
                     
@@ -658,6 +713,8 @@ All commands:
 
     set-script      npm set-script
                     
+                    Set tasks in the scripts section of package.json
+                    
                     Usage:
                     npm set-script [<script>] [<command>]
                     
@@ -665,6 +722,8 @@ All commands:
 
     shrinkwrap      npm shrinkwrap
                     
+                    Lock down dependency versions for publication
+                    
                     Usage:
                     npm shrinkwrap
                     
@@ -672,6 +731,8 @@ All commands:
 
     star            npm star
                     
+                    Mark your favorite packages
+                    
                     Usage:
                     npm star [<pkg>...]
                     
@@ -679,6 +740,8 @@ All commands:
 
     stars           npm stars
                     
+                    View packages marked as favorites
+                    
                     Usage:
                     npm stars [<user>]
                     
@@ -686,6 +749,8 @@ All commands:
 
     start           npm start
                     
+                    Start a package
+                    
                     Usage:
                     npm start [-- <args>]
                     
@@ -693,6 +758,8 @@ All commands:
 
     stop            npm stop
                     
+                    Stop a package
+                    
                     Usage:
                     npm stop [-- <args>]
                     
@@ -700,6 +767,8 @@ All commands:
 
     team            npm team
                     
+                    Manage organization teams and team memberships
+                    
                     Usage:
                     npm team create <scope:team> [--otp <otpcode>]
                     npm team destroy <scope:team> [--otp <otpcode>]
@@ -711,6 +780,8 @@ All commands:
 
     test            npm test
                     
+                    Test a package
+                    
                     Usage:
                     npm test [-- <args>]
                     
@@ -720,6 +791,8 @@ All commands:
 
     token           npm token
                     
+                    Manage your authentication tokens
+                    
                     Usage:
                     npm token list
                     npm token revoke <id|token>
@@ -729,6 +802,8 @@ All commands:
 
     uninstall       npm uninstall
                     
+                    Remove a package
+                    
                     Usage:
                     npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]
                     
@@ -738,6 +813,8 @@ All commands:
 
     unpublish       npm unpublish
                     
+                    Remove a package from the registry
+                    
                     Usage:
                     npm unpublish [<@scope>/]<pkg>[@<version>]
                     
@@ -745,6 +822,8 @@ All commands:
 
     unstar          npm unstar
                     
+                    Remove an item from your favorite packages
+                    
                     Usage:
                     npm unstar [<pkg>...]
                     
@@ -752,6 +831,8 @@ All commands:
 
     update          npm update
                     
+                    Update packages
+                    
                     Usage:
                     npm update [-g] [<pkg>...]
                     
@@ -761,6 +842,8 @@ All commands:
 
     version         npm version
                     
+                    Bump a package version
+                    
                     Usage:
                     npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
                     
@@ -770,6 +853,8 @@ All commands:
 
     view            npm view
                     
+                    View registry info
+                    
                     Usage:
                     npm view [<@scope>/]<pkg>[@<version>] [<field>[.subfield]...]
                     
@@ -779,7 +864,7 @@ All commands:
 
     whoami          npm whoami
                     
-                    prints username according to given registry
+                    Display npm username
                     
                     Usage:
                     npm whoami [--registry <registry>]
@@ -794,5 +879,4 @@ More configuration info: npm help config
 Configuration fields: npm help 7 config
 
 npm@{VERSION} {BASEDIR}
-
 `