feat(workspaces): add --include-workspace-root and explicit --no-workspacesfritzy/workspace-root

Adds a new config item that includes the workspace root. This also changes
--workspaces to a trinary, so that setting it to false will explicitly exclude
workspaces altogether.

PR-URL: https://github.com/npm/cli/pull/3890
Credit: @fritzy
Close: #3890
Reviewed-by: @wraithgar

3 files changed, 78 insertions, 34 deletions

diff --git a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
index e0878c357..aaf59e6a2 100644
--- a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
@@ -63,6 +63,7 @@ Array [
   "ignore-scripts",
   "include",
   "include-staged",
+  "include-workspace-root",
   "init-author-email",
   "init-author-name",
   "init-author-url",
@@ -832,6 +833,19 @@ Allow installing "staged" published packages, as defined by [npm RFC PR
 This is experimental, and not implemented by the npm public registry.
 `
 
+exports[`test/lib/utils/config/definitions.js TAP > config description for include-workspace-root 1`] = `
+#### \`include-workspace-root\`
+
+* Default: false
+* Type: Boolean
+
+Include the workspace root when workspaces are enabled for a command.
+
+When false, specifying individual workspaces via the \`workspace\` config, or
+all workspaces via the \`workspaces\` flag, will cause npm to operate only on
+the specified workspaces, and not on the root project.
+`
+
 exports[`test/lib/utils/config/definitions.js TAP > config description for init-author-email 1`] = `
 #### \`init-author-email\`
 
@@ -1864,8 +1878,8 @@ 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)
+* Path to a parent workspace directory (will result in selecting all
+  workspaces within that folder)
 
 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
@@ -1877,12 +1891,20 @@ This value is not exported to the environment for child processes.
 exports[`test/lib/utils/config/definitions.js TAP > config description for workspaces 1`] = `
 #### \`workspaces\`
 
-* Default: false
-* Type: Boolean
+* Default: null
+* Type: null or Boolean
 
-Enable running a command in the context of **all** the configured
+Set to true to run the command in the context of **all** configured
 workspaces.
 
+Explicitly setting this to false will cause commands like \`install\` to
+ignore workspaces altogether. When not set explicitly:
+
+- Commands that operate on the \`node_modules\` tree (install, update, etc.)
+will link workspaces into the \`node_modules\` folder. - Commands that do
+other things (test, exec, publish, etc.) will operate on the root project,
+_unless_ one or more workspaces are specified in the \`workspace\` config.
+
 This value is not exported to the environment for child processes.
 `
 
diff --git a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs
index d092ba02b..dc55893d0 100644
--- a/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs
@@ -680,6 +680,20 @@ This is experimental, and not implemented by the npm public registry.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### \`include-workspace-root\`
+
+* Default: false
+* Type: Boolean
+
+Include the workspace root when workspaces are enabled for a command.
+
+When false, specifying individual workspaces via the \`workspace\` config, or
+all workspaces via the \`workspaces\` flag, will cause npm to operate only on
+the specified workspaces, and not on the root project.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### \`init-author-email\`
 
 * Default: ""
@@ -1643,8 +1657,8 @@ 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)
+* Path to a parent workspace directory (will result in selecting all
+  workspaces within that folder)
 
 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
@@ -1657,12 +1671,20 @@ This value is not exported to the environment for child processes.
 
 #### \`workspaces\`
 
-* Default: false
-* Type: Boolean
+* Default: null
+* Type: null or Boolean
 
-Enable running a command in the context of **all** the configured
+Set to true to run the command in the context of **all** configured
 workspaces.
 
+Explicitly setting this to false will cause commands like \`install\` to
+ignore workspaces altogether. When not set explicitly:
+
+- Commands that operate on the \`node_modules\` tree (install, update, etc.)
+will link workspaces into the \`node_modules\` folder. - Commands that do
+other things (test, exec, publish, etc.) will operate on the root project,
+_unless_ one or more workspaces are specified in the \`workspace\` config.
+
 This value is not exported to the environment for child processes.
 
 <!-- automatically generated, do not edit manually -->
diff --git a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs
index 0fd36c7c1..0e48cfa61 100644
--- a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs
@@ -211,7 +211,7 @@ All commands:
                     [--json] [--package-lock-only]
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help audit" for more info
 
@@ -314,7 +314,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
                     [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: ddp
                     
@@ -345,7 +345,7 @@ All commands:
                     [--diff-no-prefix] [--diff-src-prefix <path>] [--diff-dst-prefix <path>]
                     [--diff-text] [-g|--global] [--tag <tag>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help diff" for more info
 
@@ -360,7 +360,7 @@ All commands:
                     
                     Options:
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: dist-tags
                     
@@ -376,7 +376,7 @@ All commands:
                     Options:
                     [--no-browser|--browser <browser>] [--registry <registry>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: home
                     
@@ -420,7 +420,7 @@ All commands:
                     [--package <pkg>[@<version>] [--package <pkg>[@<version>] ...]]
                     [-c|--call <call>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: x
                     
@@ -464,7 +464,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
                     [--no-audit] [--no-bin-links] [--no-fund]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help find-dupes" for more info
 
@@ -532,7 +532,7 @@ All commands:
                     Options:
                     [-y|--yes] [-f|--force]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     aliases: create, innit
                     
@@ -561,7 +561,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
                     [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     aliases: i, in, ins, inst, insta, instal, isnt, isnta, isntal, add
                     
@@ -604,7 +604,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
                     [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: it
                     
@@ -625,7 +625,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--ignore-scripts]
                     [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: ln
                     
@@ -643,7 +643,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--link]
                     [--package-lock-only] [--unicode]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: la
                     
@@ -687,7 +687,7 @@ All commands:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--link]
                     [--package-lock-only] [--unicode]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: list
                     
@@ -748,7 +748,7 @@ All commands:
                     Options:
                     [--dry-run] [--json] [--pack-destination <pack-destination>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help pack" for more info
 
@@ -817,7 +817,7 @@ All commands:
                     Options:
                     [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]] [--dry-run]
                     [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help prune" for more info
 
@@ -831,7 +831,7 @@ All commands:
                     Options:
                     [--tag <tag>] [--access <restricted|public>] [--dry-run] [--otp <otp>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help publish" for more info
 
@@ -845,7 +845,7 @@ All commands:
                     Options:
                     [-g|--global] [--no-bin-links] [--ignore-scripts]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: rb
                     
@@ -861,7 +861,7 @@ All commands:
                     Options:
                     [--no-browser|--browser <browser>]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help repo" for more info
 
@@ -898,7 +898,7 @@ All commands:
                     
                     Options:
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces] [--if-present] [--ignore-scripts]
+                    [-ws|--workspaces] [--include-workspace-root] [--if-present] [--ignore-scripts]
                     [--script-shell <script-shell>]
                     
                     aliases: run, rum, urn
@@ -939,7 +939,7 @@ All commands:
                     
                     Options:
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     Run "npm help set-script" for more info
 
@@ -1055,7 +1055,7 @@ All commands:
                     Options:
                     [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     aliases: un, unlink, remove, rm, r
                     
@@ -1099,7 +1099,7 @@ All commands:
                     [--no-package-lock] [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
                     [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     aliases: up, upgrade, udpate
                     
@@ -1116,7 +1116,7 @@ All commands:
                     [--allow-same-version] [--no-commit-hooks] [--no-git-tag-version] [--json]
                     [--preid prerelease-id] [--sign-git-tag]
                     [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     alias: verison
                     
@@ -1131,7 +1131,7 @@ All commands:
                     
                     Options:
                     [--json] [-w|--workspace <workspace-name> [-w|--workspace <workspace-name> ...]]
-                    [-ws|--workspaces]
+                    [-ws|--workspaces] [--include-workspace-root]
                     
                     aliases: v, info, show