From 8898710220a3d84b0a9ea2a6d9cf880e50b94c9e Mon Sep 17 00:00:00 2001
From: Nathan Fritz <fritzy@github.com>
Date: Tue, 10 May 2022 10:00:36 -0700
Subject: [PATCH] feat: deprecated set-script, birthday, --global, and --local

---
 docs/content/commands/npm-bin.md              |  2 +
 docs/content/commands/npm-config.md           | 11 +++++
 docs/content/commands/npm-diff.md             |  2 +
 docs/content/commands/npm-install-test.md     |  2 +
 docs/content/commands/npm-install.md          |  2 +
 docs/content/commands/npm-link.md             |  2 +
 docs/content/commands/npm-ls.md               |  2 +
 docs/content/commands/npm-outdated.md         |  2 +
 docs/content/commands/npm-prefix.md           |  2 +
 docs/content/commands/npm-rebuild.md          |  2 +
 docs/content/commands/npm-root.md             |  2 +
 docs/content/commands/npm-set-script.md       |  2 +
 docs/content/commands/npm-update.md           |  2 +
 docs/content/using-npm/config.md              | 45 ++++++++++++-------
 lib/commands/birthday.js                      |  4 +-
 lib/commands/set-script.js                    |  4 +-
 lib/utils/config/definitions.js               | 15 +++++++
 .../test/lib/load-all-commands.js.test.cjs    |  4 +-
 .../lib/utils/config/definitions.js.test.cjs  | 11 +++++
 .../lib/utils/config/describe-all.js.test.cjs | 45 ++++++++++++-------
 .../test/lib/utils/npm-usage.js.test.cjs      |  2 +-
 test/lib/commands/set-script.js               |  2 +-
 22 files changed, 127 insertions(+), 40 deletions(-)

diff --git a/docs/content/commands/npm-bin.md b/docs/content/commands/npm-bin.md
index 94b72cfd5c81c..b344ea2fc9415 100644
--- a/docs/content/commands/npm-bin.md
+++ b/docs/content/commands/npm-bin.md
@@ -34,6 +34,8 @@ Print the folder where npm will install executables.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-config.md b/docs/content/commands/npm-config.md
index a66a198ce42d1..809e42a1be1cd 100644
--- a/docs/content/commands/npm-config.md
+++ b/docs/content/commands/npm-config.md
@@ -124,6 +124,8 @@ Not supported by all npm commands.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
@@ -156,6 +158,15 @@ The command to run for `npm edit` and `npm config edit`.
 
 When passed to `npm config` this refers to which config file to use.
 
+When set to "global" mode, packages are installed into the `prefix` folder
+instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
+* bin files are linked to `{prefix}/bin`
+* man pages are linked to `{prefix}/share/man`
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
diff --git a/docs/content/commands/npm-diff.md b/docs/content/commands/npm-diff.md
index 7dcc8af7c3b4c..7183e4a2b752e 100644
--- a/docs/content/commands/npm-diff.md
+++ b/docs/content/commands/npm-diff.md
@@ -248,6 +248,8 @@ Treat all files as text in `npm diff`.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-install-test.md b/docs/content/commands/npm-install-test.md
index 3dd860ea5c6f6..18e374869d5a6 100644
--- a/docs/content/commands/npm-install-test.md
+++ b/docs/content/commands/npm-install-test.md
@@ -70,6 +70,8 @@ rather than using npm's default semver range operator.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-install.md b/docs/content/commands/npm-install.md
index 445772f0353a1..f99fcc0161dea 100644
--- a/docs/content/commands/npm-install.md
+++ b/docs/content/commands/npm-install.md
@@ -460,6 +460,8 @@ rather than using npm's default semver range operator.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-link.md b/docs/content/commands/npm-link.md
index 975c807c38b34..34c67aa3def81 100644
--- a/docs/content/commands/npm-link.md
+++ b/docs/content/commands/npm-link.md
@@ -153,6 +153,8 @@ rather than using npm's default semver range operator.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-ls.md b/docs/content/commands/npm-ls.md
index ded8c0c0d26ef..5ad4593bfa2f6 100644
--- a/docs/content/commands/npm-ls.md
+++ b/docs/content/commands/npm-ls.md
@@ -137,6 +137,8 @@ Output parseable results from commands that write to standard output. For
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-outdated.md b/docs/content/commands/npm-outdated.md
index 6fa026550e747..1bf2de039c315 100644
--- a/docs/content/commands/npm-outdated.md
+++ b/docs/content/commands/npm-outdated.md
@@ -150,6 +150,8 @@ Output parseable results from commands that write to standard output. For
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-prefix.md b/docs/content/commands/npm-prefix.md
index 39328bcc88a14..6f08e43fa8c0c 100644
--- a/docs/content/commands/npm-prefix.md
+++ b/docs/content/commands/npm-prefix.md
@@ -51,6 +51,8 @@ npm prefix -g
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-rebuild.md b/docs/content/commands/npm-rebuild.md
index 52c368c8c513b..fa5b0cfa97d7c 100644
--- a/docs/content/commands/npm-rebuild.md
+++ b/docs/content/commands/npm-rebuild.md
@@ -42,6 +42,8 @@ will be rebuilt.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-root.md b/docs/content/commands/npm-root.md
index 40b58e4b33d0b..80545235fc969 100644
--- a/docs/content/commands/npm-root.md
+++ b/docs/content/commands/npm-root.md
@@ -41,6 +41,8 @@ echo "Global packages installed in: ${global_node_modules}"
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/commands/npm-set-script.md b/docs/content/commands/npm-set-script.md
index 0fc267f760c81..8695b43f14423 100644
--- a/docs/content/commands/npm-set-script.md
+++ b/docs/content/commands/npm-set-script.md
@@ -7,6 +7,8 @@ description: Set tasks in the scripts section of package.json
 ### Synopsis
 An npm command that lets you create a task in the `scripts` section of the `package.json`.
 
+Deprecated.
+
 <!-- AUTOGENERATED USAGE DESCRIPTIONS START -->
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/commands/set-script.js -->
diff --git a/docs/content/commands/npm-update.md b/docs/content/commands/npm-update.md
index 421d04ca3dc58..55aad182fcafe 100644
--- a/docs/content/commands/npm-update.md
+++ b/docs/content/commands/npm-update.md
@@ -188,6 +188,8 @@ Will also prevent writing to `package-lock.json` if set to `false`.
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the `prefix`
 folder instead of the current working directory. See
diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index a33e791bb836b..12b508582af1c 100644
--- a/docs/content/using-npm/config.md
+++ b/docs/content/using-npm/config.md
@@ -687,23 +687,6 @@ results in no commit being made at all.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
-#### `global`
-
-* Default: false
-* Type: Boolean
-
-Operates in "global" mode, so that packages are installed into the `prefix`
-folder instead of the current working directory. See
-[folders](/configuring-npm/folders) for more on the differences in behavior.
-
-* packages are installed into the `{prefix}/lib/node_modules` folder, instead
-  of the current working directory.
-* bin files are linked to `{prefix}/bin`
-* man pages are linked to `{prefix}/share/man`
-
-<!-- automatically generated, do not edit manually -->
-<!-- see lib/utils/config/definitions.js -->
-
 #### `global-style`
 
 * Default: false
@@ -1001,6 +984,15 @@ npm registry. Must be IPv4 in versions of Node prior to 0.12.
 
 When passed to `npm config` this refers to which config file to use.
 
+When set to "global" mode, packages are installed into the `prefix` folder
+instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
+* bin files are linked to `{prefix}/bin`
+* man pages are linked to `{prefix}/share/man`
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
@@ -1941,6 +1933,25 @@ Alias for `--include=dev`.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### `global`
+
+* Default: false
+* Type: Boolean
+* DEPRECATED: `--global`, `--local` are deprecated. Use `--location=global`
+  instead.
+
+Operates in "global" mode, so that packages are installed into the `prefix`
+folder instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the `{prefix}/lib/node_modules` folder, instead
+  of the current working directory.
+* bin files are linked to `{prefix}/bin`
+* man pages are linked to `{prefix}/share/man`
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### `init.author.email`
 
 * Default: ""
diff --git a/lib/commands/birthday.js b/lib/commands/birthday.js
index c7b5b31c54a62..cdd6db6286905 100644
--- a/lib/commands/birthday.js
+++ b/lib/commands/birthday.js
@@ -1,13 +1,15 @@
 const BaseCommand = require('../base-command.js')
+const log = require('../utils/log-shim')
 
 class Birthday extends BaseCommand {
   static name = 'birthday'
-  static description = 'Birthday'
+  static description = 'Birthday, deprecated'
   static ignoreImplicitWorkspace = true
   static isShellout = true
 
   async exec () {
     this.npm.config.set('yes', true)
+    log.warn('birthday', 'birthday is deprecated and will be removed in a future release')
     return this.npm.exec('exec', ['@npmcli/npm-birthday'])
   }
 }
diff --git a/lib/commands/set-script.js b/lib/commands/set-script.js
index a6b7c3a50cdaf..a085f72a31428 100644
--- a/lib/commands/set-script.js
+++ b/lib/commands/set-script.js
@@ -5,7 +5,7 @@ const log = require('../utils/log-shim')
 
 const BaseCommand = require('../base-command.js')
 class SetScript extends BaseCommand {
-  static description = 'Set tasks in the scripts section of package.json'
+  static description = 'Set tasks in the scripts section of package.json, deprecated'
   static params = ['workspace', 'workspaces', 'include-workspace-root']
   static name = 'set-script'
   static usage = ['[<script>] [<command>]']
@@ -34,6 +34,8 @@ class SetScript extends BaseCommand {
 
   async exec (args) {
     this.validate(args)
+    log.warn('set-script',
+      'set-script is deprecated, use `npm pkg set scripts.scriptname="cmd" instead.')
     const warn = await this.doSetScript(this.npm.localPrefix, args[0], args[1])
     if (warn) {
       log.warn('set-script', `Script "${args[0]}" was overwritten`)
diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js
index c4be3a6584cc1..92fbbd1e6dc20 100644
--- a/lib/utils/config/definitions.js
+++ b/lib/utils/config/definitions.js
@@ -811,6 +811,9 @@ define('global', {
   default: false,
   type: Boolean,
   short: 'g',
+  deprecated: `
+    \`--global\`, \`--local\` are deprecated. Use \`--location=global\` instead.
+  `,
   description: `
     Operates in "global" mode, so that packages are installed into the
     \`prefix\` folder instead of the current working directory.  See
@@ -1179,12 +1182,24 @@ define('location', {
   `,
   description: `
     When passed to \`npm config\` this refers to which config file to use.
+
+    When set to "global" mode, packages are installed into the \`prefix\` folder
+    instead of the current working directory. See
+    [folders](/configuring-npm/folders) for more on the differences in behavior.
+
+    * packages are installed into the \`{prefix}/lib/node_modules\` folder,
+      instead of the current working directory.
+    * bin files are linked to \`{prefix}/bin\`
+    * man pages are linked to \`{prefix}/share/man\`
   `,
   flatten: (key, obj, flatOptions) => {
     flatten(key, obj, flatOptions)
     if (flatOptions.global) {
       flatOptions.location = 'global'
     }
+    if (obj.location === 'global') {
+      flatOptions.global = true
+    }
   },
 })
 
diff --git a/tap-snapshots/test/lib/load-all-commands.js.test.cjs b/tap-snapshots/test/lib/load-all-commands.js.test.cjs
index 20915cdd87131..2029289d128a8 100644
--- a/tap-snapshots/test/lib/load-all-commands.js.test.cjs
+++ b/tap-snapshots/test/lib/load-all-commands.js.test.cjs
@@ -69,7 +69,7 @@ Run "npm help bin" for more info
 `
 
 exports[`test/lib/load-all-commands.js TAP load each command birthday > must match snapshot 1`] = `
-Birthday
+Birthday, deprecated
 
 Usage:
 npm birthday
@@ -802,7 +802,7 @@ Run "npm help set" for more info
 `
 
 exports[`test/lib/load-all-commands.js TAP load each command set-script > must match snapshot 1`] = `
-Set tasks in the scripts section of package.json
+Set tasks in the scripts section of package.json, deprecated
 
 Usage:
 npm set-script [<script>] [<command>]
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 c31a6b7dc7e67..b12dccdb76c31 100644
--- a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
@@ -731,6 +731,8 @@ exports[`test/lib/utils/config/definitions.js TAP > config description for globa
 
 * Default: false
 * Type: Boolean
+* DEPRECATED: \`--global\`, \`--local\` are deprecated. Use \`--location=global\`
+  instead.
 
 Operates in "global" mode, so that packages are installed into the \`prefix\`
 folder instead of the current working directory. See
@@ -1077,6 +1079,15 @@ exports[`test/lib/utils/config/definitions.js TAP > config description for locat
 * Type: "global", "user", or "project"
 
 When passed to \`npm config\` this refers to which config file to use.
+
+When set to "global" mode, packages are installed into the \`prefix\` folder
+instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the \`{prefix}/lib/node_modules\` folder, instead
+  of the current working directory.
+* bin files are linked to \`{prefix}/bin\`
+* man pages are linked to \`{prefix}/share/man\`
 `
 
 exports[`test/lib/utils/config/definitions.js TAP > config description for lockfile-version 1`] = `
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 0ec2ca17a4ef1..cacbe96a74f35 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
@@ -560,23 +560,6 @@ results in no commit being made at all.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
-#### \`global\`
-
-* Default: false
-* Type: Boolean
-
-Operates in "global" mode, so that packages are installed into the \`prefix\`
-folder instead of the current working directory. See
-[folders](/configuring-npm/folders) for more on the differences in behavior.
-
-* packages are installed into the \`{prefix}/lib/node_modules\` folder, instead
-  of the current working directory.
-* bin files are linked to \`{prefix}/bin\`
-* man pages are linked to \`{prefix}/share/man\`
-
-<!-- automatically generated, do not edit manually -->
-<!-- see lib/utils/config/definitions.js -->
-
 #### \`global-style\`
 
 * Default: false
@@ -874,6 +857,15 @@ npm registry. Must be IPv4 in versions of Node prior to 0.12.
 
 When passed to \`npm config\` this refers to which config file to use.
 
+When set to "global" mode, packages are installed into the \`prefix\` folder
+instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the \`{prefix}/lib/node_modules\` folder, instead
+  of the current working directory.
+* bin files are linked to \`{prefix}/bin\`
+* man pages are linked to \`{prefix}/share/man\`
+
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
@@ -1814,6 +1806,25 @@ Alias for \`--include=dev\`.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### \`global\`
+
+* Default: false
+* Type: Boolean
+* DEPRECATED: \`--global\`, \`--local\` are deprecated. Use \`--location=global\`
+  instead.
+
+Operates in "global" mode, so that packages are installed into the \`prefix\`
+folder instead of the current working directory. See
+[folders](/configuring-npm/folders) for more on the differences in behavior.
+
+* packages are installed into the \`{prefix}/lib/node_modules\` folder, instead
+  of the current working directory.
+* bin files are linked to \`{prefix}/bin\`
+* man pages are linked to \`{prefix}/share/man\`
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### \`init.author.email\`
 
 * Default: ""
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 3487378a2119d..22fad5c778ca0 100644
--- a/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs
+++ b/tap-snapshots/test/lib/utils/npm-usage.js.test.cjs
@@ -840,7 +840,7 @@ All commands:
                     
                     Run "npm help set" for more info
 
-    set-script      Set tasks in the scripts section of package.json
+    set-script      Set tasks in the scripts section of package.json, deprecated
                     
                     Usage:
                     npm set-script [<script>] [<command>]
diff --git a/test/lib/commands/set-script.js b/test/lib/commands/set-script.js
index 2c4fe57d68542..cf0df53af14bb 100644
--- a/test/lib/commands/set-script.js
+++ b/test/lib/commands/set-script.js
@@ -130,7 +130,7 @@ t.test('warns when overwriting', async t => {
   })
 
   await setScript.exec(['arg1', 'arg2'])
-  t.hasStrict(WARN_OUTPUT[0], ['set-script', 'Script "arg1" was overwritten'], 'warning was logged')
+  t.hasStrict(WARN_OUTPUT[1], ['set-script', 'Script "arg1" was overwritten'], 'warning was logged')
 })
 
 t.test('workspaces', async t => {