From 7b177e43f3bfb558bcd8723cdb2166a3df19647a Mon Sep 17 00:00:00 2001
From: isaacs <i@izs.me>
Date: Thu, 1 Apr 2021 10:06:33 -0700
Subject: [PATCH] Add a 'envExport' flag for config definitions

It defaults to true, but setting it to any falsey value will tell
`@npmcli/config` not to export it into the environment, and will also
put a remark in the documentation that it is not exported.

PR-URL: https://github.com/npm/cli/pull/3014
Credit: @isaacs
Close: #3014
Reviewed-by: @nlf
---
 docs/content/using-npm/config.md              |  4 ++++
 lib/utils/config/definition.js                |  8 +++++++-
 lib/utils/config/definitions.js               |  2 ++
 ...b-utils-config-describe-all.js-TAP.test.js |  4 ++++
 test/lib/utils/config/definition.js           | 20 +++++++++++++++++++
 5 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index cfce5396f40a7..b0f365f293dfc 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -1333,6 +1333,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)
 
+This value is not exported to the environment for child processes.
+
 #### `workspaces`
 
 * Default: false
@@ -1341,6 +1343,8 @@ to selecting all of the nested workspaces)
 Enable running a command in the context of **all** the configured
 workspaces.
 
+This value is not exported to the environment for child processes.
+
 #### `yes`
 
 * Default: null
diff --git a/lib/utils/config/definition.js b/lib/utils/config/definition.js
index 1d487f531243d..e7c605fb7e308 100644
--- a/lib/utils/config/definition.js
+++ b/lib/utils/config/definition.js
@@ -25,6 +25,7 @@ const allowed = [
   'type',
   'typeDescription',
   'usage',
+  'envExport',
 ]
 
 const {
@@ -39,6 +40,8 @@ const {
 class Definition {
   constructor (key, def) {
     this.key = key
+    // if it's set falsey, don't export it, otherwise we do by default
+    this.envExport = true
     Object.assign(this, def)
     this.validate()
     if (!this.defaultDescription)
@@ -68,6 +71,9 @@ class Definition {
   // a textual description of this config, suitable for help output
   describe () {
     const description = unindent(this.description)
+    const noEnvExport = this.envExport ? '' : `
+This value is not exported to the environment for child processes.
+`
     const deprecated = !this.deprecated ? ''
       : `* DEPRECATED: ${unindent(this.deprecated)}\n`
     return wrapAll(`#### \`${this.key}\`
@@ -76,7 +82,7 @@ class Definition {
 * Type: ${unindent(this.typeDescription)}
 ${deprecated}
 ${description}
-`)
+${noEnvExport}`)
   }
 }
 
diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js
index 14d8eaa699435..d87c43ddade50 100644
--- a/lib/utils/config/definitions.js
+++ b/lib/utils/config/definitions.js
@@ -2044,6 +2044,7 @@ define('workspace', {
   type: [String, Array],
   hint: '<workspace-name>',
   short: 'w',
+  envExport: false,
   description: `
     Enable running a command in the context of the configured workspaces of the
     current project while filtering by running only the workspaces defined by
@@ -2061,6 +2062,7 @@ define('workspaces', {
   default: false,
   type: Boolean,
   short: 'ws',
+  envExport: false,
   description: `
     Enable running a command in the context of **all** the configured
     workspaces.
diff --git a/tap-snapshots/test-lib-utils-config-describe-all.js-TAP.test.js b/tap-snapshots/test-lib-utils-config-describe-all.js-TAP.test.js
index d424508c308c4..6c26590626115 100644
--- a/tap-snapshots/test-lib-utils-config-describe-all.js-TAP.test.js
+++ b/tap-snapshots/test-lib-utils-config-describe-all.js-TAP.test.js
@@ -1212,6 +1212,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)
 
+This value is not exported to the environment for child processes.
+
 #### \`workspaces\`
 
 * Default: false
@@ -1220,6 +1222,8 @@ to selecting all of the nested workspaces)
 Enable running a command in the context of **all** the configured
 workspaces.
 
+This value is not exported to the environment for child processes.
+
 #### \`yes\`
 
 * Default: null
diff --git a/test/lib/utils/config/definition.js b/test/lib/utils/config/definition.js
index 88a527db6949d..45f4c977a77a0 100644
--- a/test/lib/utils/config/definition.js
+++ b/test/lib/utils/config/definition.js
@@ -25,6 +25,7 @@ t.test('basic definition', async t => {
     usage: '--key <key>',
     typeDescription: 'Number or String',
     description: 'just a test thingie',
+    envExport: true,
   })
   t.matchSnapshot(def.describe(), 'human-readable description')
 
@@ -119,6 +120,25 @@ t.test('basic definition', async t => {
     description: 'asdf',
   })
   t.equal(optionalBool.usage, '--key')
+
+  const noExported = new Definition('methane', {
+    envExport: false,
+    type: String,
+    typeDescription: 'Greenhouse Gas',
+    default: 'CH4',
+    description: `
+      This is bad for the environment, for our children, do not put it there.
+    `,
+  })
+  t.equal(noExported.envExport, false, 'envExport flag is false')
+  t.equal(noExported.describe(), `#### \`methane\`
+
+* Default: "CH4"
+* Type: Greenhouse Gas
+
+This is bad for the environment, for our children, do not put it there.
+
+This value is not exported to the environment for child processes.`)
 })
 
 t.test('missing fields', async t => {