fix(usage): tie usage to config

This starts us down the path of tying the params our commands accept to
their config items.  For now it is optional, and not every current
config item would cleanly render if we added them today.

The ones that are added here DO render nicely, and we can iterate from
here.  We can also at a later date do the same kind of appraoch with our
positional args.

PR-URL: #2908
Credit: @wraithgar
Close: #2908
Reviewed-by: @nlf, @isaacs

Author: wraithgar

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