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

2 files changed, 54 insertions, 10 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 -->