Add workspaces support to reify/rebuild commands

This adds `--workspace` support to:

- audit (including audit fix)
- ci
- dedupe
- find-dupes
- install
- install-ci-test
- install-test
- prune
- rebuild
- uninstall
- update

Author: isaacs

docs/content/commands/npm-audit.md

@@ -271,6 +271,38 @@ it will be included.
 If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment
 variable will be set to `'production'` for all lifecycle scripts.
 
+#### `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)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also

docs/content/commands/npm-install.md

@@ -571,6 +571,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `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)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### Algorithm

docs/content/commands/npm-prune.md

@@ -77,6 +77,38 @@ Whether or not to output JSON data, rather than the normal output.
 
 Not supported by all npm commands.
 
+#### `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)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also

docs/content/commands/npm-uninstall.md

@@ -68,6 +68,38 @@ Save installed packages to a package.json file as dependencies.
 When used with the `npm rm` command, removes the dependency from
 package.json.
 
+#### `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)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also

docs/content/commands/npm-update.md

@@ -258,6 +258,38 @@ commands that modify your local installation, eg, `install`, `update`,
 Note: This is NOT honored by other network related commands, eg `dist-tags`,
 `owner`, etc.
 
+#### `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)
+
+When set for the `npm init` command, this may be set to the folder of a
+workspace which does not yet exist, to create the folder and set it up as a
+brand new workspace within the project.
+
+This value is not exported to the environment for child processes.
+
+#### `workspaces`
+
+* Default: false
+* Type: Boolean
+
+Enable running a command in the context of **all** the configured
+workspaces.
+
+This value is not exported to the environment for child processes.
+
 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
 
 ### See Also

lib/audit.js

@@ -2,9 +2,9 @@ const Arborist = require('@npmcli/arborist')
 const auditReport = require('npm-audit-report')
 const reifyFinish = require('./utils/reify-finish.js')
 const auditError = require('./utils/audit-error.js')
-const BaseCommand = require('./base-command.js')
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
 
-class Audit extends BaseCommand {
+class Audit extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Run a security audit'
@@ -24,6 +24,7 @@ class Audit extends BaseCommand {
       'json',
       'package-lock-only',
       'omit',
+      ...super.params,
     ]
   }
 
@@ -57,7 +58,9 @@ class Audit extends BaseCommand {
       audit: true,
       path: this.npm.prefix,
       reporter,
+      workspaces: this.workspaces,
     }
+
     const arb = new Arborist(opts)
     const fix = args[0] === 'fix'
     await arb.audit({ fix })

lib/base-command.js

@@ -6,6 +6,7 @@ class BaseCommand {
   constructor (npm) {
     this.wrapWidth = 80
     this.npm = npm
+    this.workspaces = null
   }
 
   get name () {

lib/ci.js

@@ -17,9 +17,9 @@ const removeNodeModules = async where => {
   await Promise.all(entries.map(f => rimraf(`${path}/${f}`, rimrafOpts)))
   process.emit('timeEnd', 'npm-ci:rm')
 }
-const BaseCommand = require('./base-command.js')
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
 
-class CI extends BaseCommand {
+class CI extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Install a project with a clean slate'
@@ -55,6 +55,7 @@ class CI extends BaseCommand {
       path: where,
       log: this.npm.log,
       save: false, // npm ci should never modify the lockfile or package.json
+      workspaces: this.workspaces,
     }
 
     const arb = new Arborist(opts)

lib/dedupe.js

@@ -2,9 +2,9 @@
 const Arborist = require('@npmcli/arborist')
 const reifyFinish = require('./utils/reify-finish.js')
 
-const BaseCommand = require('./base-command.js')
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
 
-class Dedupe extends BaseCommand {
+class Dedupe extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Reduce duplication in the package tree'
@@ -49,6 +49,7 @@ class Dedupe extends BaseCommand {
       log: this.npm.log,
       path: where,
       dryRun,
+      workspaces: this.workspaces,
     }
     const arb = new Arborist(opts)
     await arb.dedupe(opts)

lib/install.js

@@ -9,8 +9,8 @@ const { resolve, join } = require('path')
 const Arborist = require('@npmcli/arborist')
 const runScript = require('@npmcli/run-script')
 
-const BaseCommand = require('./base-command.js')
-class Install extends BaseCommand {
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
+class Install extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Install a package'
@@ -37,6 +37,7 @@ class Install extends BaseCommand {
       'bin-links',
       'fund',
       'dry-run',
+      ...super.params,
     ]
   }
 
@@ -143,6 +144,7 @@ class Install extends BaseCommand {
       auditLevel: null,
       path: where,
       add: args,
+      workspaces: this.workspaces,
     }
     const arb = new Arborist(opts)
     await arb.reify(opts)

lib/prune.js

@@ -2,8 +2,8 @@
 const Arborist = require('@npmcli/arborist')
 const reifyFinish = require('./utils/reify-finish.js')
 
-const BaseCommand = require('./base-command.js')
-class Prune extends BaseCommand {
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
+class Prune extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Remove extraneous packages'
@@ -16,7 +16,7 @@ class Prune extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['omit', 'dry-run', 'json']
+    return ['omit', 'dry-run', 'json', ...super.params]
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
@@ -34,6 +34,7 @@ class Prune extends BaseCommand {
       ...this.npm.flatOptions,
       path: where,
       log: this.npm.log,
+      workspaces: this.workspaces,
     }
     const arb = new Arborist(opts)
     await arb.prune(opts)

lib/rebuild.js

@@ -4,8 +4,10 @@ const npa = require('npm-package-arg')
 const semver = require('semver')
 const completion = require('./utils/completion/installed-deep.js')
 
-const BaseCommand = require('./base-command.js')
-class Rebuild extends BaseCommand {
+// TODO: make Arborist.rebuild() understand the workspaces option
+// and then extend ArboristWorkspaceCmd instead
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
+class Rebuild extends ArboristWorkspaceCmd {
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get description () {
     return 'Rebuild a package'
@@ -22,6 +24,7 @@ class Rebuild extends BaseCommand {
       'global',
       'bin-links',
       'ignore-scripts',
+      ...super.params,
     ]
   }
 
@@ -45,6 +48,8 @@ class Rebuild extends BaseCommand {
     const arb = new Arborist({
       ...this.npm.flatOptions,
       path: where,
+      // TODO when extending ReifyCmd
+      // workspaces: this.workspaces,
     })
 
     if (args.length) {

lib/uninstall.js

@@ -5,8 +5,8 @@ const rpj = require('read-package-json-fast')
 const reifyFinish = require('./utils/reify-finish.js')
 const completion = require('./utils/completion/installed-shallow.js')
 
-const BaseCommand = require('./base-command.js')
-class Uninstall extends BaseCommand {
+const ArboristWorkspaceCmd = require('./workspaces/arborist-cmd.js')
+class Uninstall extends ArboristWorkspaceCmd {
   static get description () {
     return 'Remove a package'
   }
@@ -18,7 +18,7 @@ class Uninstall extends BaseCommand {
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
   static get params () {
-    return ['save']
+    return ['save', ...super.params]
   }
 
   /* istanbul ignore next - see test/lib/load-all-commands.js */
@@ -66,7 +66,7 @@ class Uninstall extends BaseCommand {
       path,
       log: this.npm.log,
       rm: args,
-
+      workspaces: this.workspaces,
     }
     const arb = new Arborist(opts)
     await arb.reify(opts)