fix(usage): tie usage to config

docs/content/using-npm/config.md

@@ -96,6 +96,8 @@ The following shorthands are parsed on the command-line:
 * `-H`: `--usage`
 * `--help`: `--usage`
 * `-v`: `--version`
+* `-w`: `--workspace`
+* `--ws`: `--workspaces`
 * `-y`: `--yes`
 
 <!-- AUTOGENERATED CONFIG SHORTHANDS END -->
@@ -1311,6 +1313,34 @@ The program to use to view help content.
 
 Set to `"browser"` to view html help content in the default web browser.
 
+#### `which`
+
+* Default: null
+* Type: null or Number
+
+If there are multiple funding sources, which 1-indexed source URL to open.
+
+#### `workspace`
+
+* Default:
+* Type: String (can be set multiple times)
+
+Enable running a command in the context of the configured workspaces of the
+current project while filtering by running only the workspaces defined by
+this configuration option.
+
+Valid values for the `workspace` config are either: - Workspace names - Path
+to a workspace directory - Path to a parent workspace directory (will result
+to selecting all of the nested workspaces)
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
 #### `yes`
 
 * Default: false

lib/adduser.js

@@ -17,8 +17,12 @@ class AddUser extends BaseCommand {
     return 'adduser'
   }
 
-  static get usage () {
-    return ['[--registry=url] [--scope=@orgname] [--always-auth]']
+  static get params () {
+    return [
+      'registry',
+      'scope',
+      'always-auth',
+    ]
   }
 
   exec (args, cb) {

lib/audit.js

@@ -16,13 +16,21 @@ class Audit extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get usage () {
+  static get params () {
     return [
-      '[--json] [--production]',
-      'fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)]',
+      'dry-run',
+      'force',
+      'json',
+      'package-lock-only',
+      'production',
     ]
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get usage () {
+    return ['[fix]']
+  }
+
   async completion (opts) {
     const argv = opts.conf.argv.remain
 

lib/base-command.js

@@ -1,5 +1,6 @@
 // Base class for npm.commands[cmd]
 const usageUtil = require('./utils/usage.js')
+const ConfigDefinitions = require('./utils/config/definitions.js')
 
 class BaseCommand {
   constructor (npm) {
@@ -25,6 +26,9 @@ class BaseCommand {
     else
       usage = `${usage}${this.constructor.usage.map(u => `npm ${this.constructor.name} ${u}`).join('\n')}`
 
+    if (this.constructor.params)
+      usage = `${usage}\n\nOptions:\n[${this.constructor.params.map(p => ConfigDefinitions[p].usage).join('] [')}]`
+
     // Mostly this just appends aliases, this could be more clear
     usage = usageUtil(this.constructor.name, usage)
     usage = `${usage}\n\nRun "npm help ${this.constructor.name}" for more info`

lib/bin.js

@@ -10,8 +10,8 @@ class Bin extends BaseCommand {
     return 'bin'
   }
 
-  static get usage () {
-    return ['[-g]']
+  static get params () {
+    return ['global']
   }
 
   exec (args, cb) {

lib/fund.js

@@ -32,9 +32,19 @@ class Fund extends BaseCommand {
     return 'fund'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'json',
+      'browser',
+      'unicode',
+      'which',
+    ]
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['[--json] [--browser] [--unicode] [[<@scope>/]<pkg> [--which=<fundingSourceNumber>]']
+    return ['[[<@scope>/]<pkg>]']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */

lib/install.js

@@ -21,6 +21,14 @@ class Install extends BaseCommand {
     return 'install'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'save',
+      'save-exact',
+    ]
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
     return [
@@ -33,7 +41,7 @@ class Install extends BaseCommand {
       '<tarball file>',
       '<tarball url>',
       '<git:// url>',
-      '<github username>/<github project> [--save-prod|--save-dev|--save-optional|--save-peer] [--save-exact] [--no-save]',
+      '<github username>/<github project>',
     ]
   }
 

lib/logout.js

@@ -15,8 +15,11 @@ class Logout extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get usage () {
-    return ['[--registry=<url>] [--scope=<@scope>]']
+  static get params () {
+    return [
+      'registry',
+      'scope',
+    ]
   }
 
   exec (args, cb) {

lib/pack.js

@@ -21,9 +21,14 @@ class Pack extends BaseCommand {
     return 'pack'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['dry-run']
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['[[<@scope>/]<pkg>...] [--dry-run]']
+    return ['[[<@scope>/]<pkg>...]']
   }
 
   exec (args, cb) {

lib/ping.js

@@ -8,6 +8,11 @@ class Ping extends BaseCommand {
     return 'Ping npm registry'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['registry']
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get name () {
     return 'ping'

lib/prune.js

@@ -14,9 +14,14 @@ class Prune extends BaseCommand {
     return 'prune'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['production']
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['[[<@scope>/]<pkg>...] [--production]']
+    return ['[[<@scope>/]<pkg>...]']
   }
 
   exec (args, cb) {

lib/publish.js

@@ -28,10 +28,15 @@ class Publish extends BaseCommand {
     return 'publish'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['tag', 'access', 'dry-run']
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
     return [
-      '[<folder>] [--tag <tag>] [--access <public|restricted>] [--dry-run]',
+      '[<folder>]',
     ]
   }
 

lib/root.js

@@ -11,8 +11,8 @@ class Root extends BaseCommand {
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
-  static get usage () {
-    return ['[-g]']
+  static get params () {
+    return ['global']
   }
 
   exec (args, cb) {

lib/search.js

@@ -36,9 +36,19 @@ class Search extends BaseCommand {
     return 'search'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return [
+      'long',
+      'json',
+      'parseable',
+      'description',
+    ]
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['[-l|--long] [--json] [--parseable] [--no-description] [search terms ...]']
+    return ['[search terms ...]']
   }
 
   exec (args, cb) {

lib/uninstall.js

@@ -16,9 +16,14 @@ class Uninstall extends BaseCommand {
     return 'uninstall'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['save']
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['[<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]']
+    return ['[<@scope>/]<pkg>...']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */

lib/update.js

@@ -18,9 +18,14 @@ class Update extends BaseCommand {
     return 'update'
   }
 
+  /* istanbul ignore next - see test/lib/load-all-commands.js */
+  static get params () {
+    return ['global']
+  }
+
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get usage () {
-    return ['[-g] [<pkg>...]']
+    return ['[<pkg>...]']
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */

lib/utils/config/definition.js

@@ -15,14 +15,16 @@ const required = [
 
 const allowed = [
   'default',
-  'type',
+  'defaultDescription',
+  'deprecated',
   'description',
   'flatten',
+  'hint',
+  'key',
   'short',
+  'type',
   'typeDescription',
-  'defaultDescription',
-  'deprecated',
-  'key',
+  'usage',
 ]
 
 const {
@@ -43,6 +45,10 @@ class Definition {
       this.defaultDescription = describeValue(this.default)
     if (!this.typeDescription)
       this.typeDescription = describeType(this.type)
+    if (!this.hint)
+      this.hint = `<${this.key}>`
+    if (!this.usage)
+      this.usage = describeUsage(this)
   }
 
   validate () {
@@ -73,6 +79,28 @@ ${description}
   }
 }
 
+// Usage for a single param, abstracted because we have arrays of types in
+// config definition
+const paramUsage = (type, def) => {
+  let key = `--${def.key}`
+  if (def.short && typeof def.short === 'string')
+    key = `-${def.short}|${key}`
+  if (type === Boolean)
+    return `${key}`
+  else
+    return `${key} ${def.hint}`
+}
+
+const describeUsage = (def) => {
+  if (Array.isArray(def.type)) {
+    if (!def.type.some(d => d !== null && typeof d !== 'string'))
+      return `--${def.key} <${def.type.filter(d => d).join('|')}>`
+    else
+      return def.type.filter(d => d).map((t) => paramUsage(t, def)).join('|')
+  }
+  return paramUsage(def.type, def)
+}
+
 const describeType = type => {
   if (Array.isArray(type)) {
     const descriptions = type