feat: add --install-strategy=hoisted|nested|shallow, deprecate --global-style, --legacy-bundling (#5709)

BREAKING CHANGE: deprecate boolean install flags in favor of `--install-strategy`
* deprecate --global-style, --global now sets --install-strategy=shallow
* deprecate --legacy-bundling, now sets --install-strategy=nested

Author: fritzy

lib/commands/dedupe.js

@@ -8,8 +8,9 @@ class Dedupe extends ArboristWorkspaceCmd {
   static description = 'Reduce duplication in the package tree'
   static name = 'dedupe'
   static params = [
-    'global-style',
+    'install-strategy',
     'legacy-bundling',
+    'global-style',
     'strict-peer-deps',
     'package-lock',
     'omit',

lib/commands/find-dupes.js

@@ -5,8 +5,9 @@ class FindDupes extends ArboristWorkspaceCmd {
   static description = 'Find duplication in the package tree'
   static name = 'find-dupes'
   static params = [
-    'global-style',
+    'install-strategy',
     'legacy-bundling',
+    'global-style',
     'strict-peer-deps',
     'package-lock',
     'omit',

lib/commands/install.js

@@ -20,8 +20,9 @@ class Install extends ArboristWorkspaceCmd {
     'save',
     'save-exact',
     'global',
-    'global-style',
+    'install-strategy',
     'legacy-bundling',
+    'global-style',
     'omit',
     'strict-peer-deps',
     'package-lock',

lib/commands/link.js

@@ -22,8 +22,9 @@ class Link extends ArboristWorkspaceCmd {
     'save',
     'save-exact',
     'global',
-    'global-style',
+    'install-strategy',
     'legacy-bundling',
+    'global-style',
     'strict-peer-deps',
     'package-lock',
     'omit',

lib/commands/update.js

@@ -14,8 +14,9 @@ class Update extends ArboristWorkspaceCmd {
   static params = [
     'save',
     'global',
-    'global-style',
+    'install-strategy',
     'legacy-bundling',
+    'global-style',
     'omit',
     'strict-peer-deps',
     'package-lock',

lib/utils/config/definitions.js

@@ -823,20 +823,6 @@ define('global', {
   },
 })
 
-define('global-style', {
-  default: false,
-  type: Boolean,
-  description: `
-    Causes npm to install the package into your local \`node_modules\` folder
-    with the same layout it uses with the global \`node_modules\` folder.
-    Only your direct dependencies will show in \`node_modules\` and
-    everything they depend on will be flattened in their \`node_modules\`
-    folders.  This obviously will eliminate some deduping. If used with
-    \`legacy-bundling\`, \`legacy-bundling\` will be preferred.
-  `,
-  flatten,
-})
-
 // the globalconfig has its default defined outside of this module
 define('globalconfig', {
   type: path,
@@ -851,6 +837,25 @@ define('globalconfig', {
   flatten,
 })
 
+define('global-style', {
+  default: false,
+  type: Boolean,
+  description: `
+    Only install direct dependencies in the top level \`node_modules\`,
+    but hoist on deeper dependendencies.
+    Sets \`--install-strategy=shallow\`.
+  `,
+  deprecated: `
+    This option has been deprecated in favor of \`--install-strategy=shallow\`
+  `,
+  flatten (key, obj, flatOptions) {
+    if (obj[key]) {
+      obj['install-strategy'] = 'shallow'
+      flatOptions.installStrategy = 'shallow'
+    }
+  },
+})
+
 define('heading', {
   default: 'npm',
   type: String,
@@ -1076,6 +1081,21 @@ define('install-links', {
   flatten,
 })
 
+define('install-strategy', {
+  default: 'hoisted',
+  type: ['hoisted', 'nested', 'shallow'],
+  description: `
+    Sets the strategy for installing packages in node_modules.
+    hoisted (default): Install non-duplicated in top-level, and duplicated as
+      necessary within directory structure.
+    nested: (formerly --legacy-bundling) install in place, no hoisting.
+    shallow (formerly --global-style) only install direct deps at top-level.
+    linked: (coming soon) install in node_modules/.store, link in place,
+      unhoisted.
+  `,
+  flatten,
+})
+
 define('json', {
   default: false,
   type: Boolean,
@@ -1111,12 +1131,21 @@ define('legacy-bundling', {
   default: false,
   type: Boolean,
   description: `
-    Causes npm to install the package such that versions of npm prior to 1.4,
-    such as the one included with node 0.8, can install the package.  This
-    eliminates all automatic deduping. If used with \`global-style\` this
-    option will be preferred.
+    Instead of hoisting package installs in \`node_modules\`, install packages
+    in the same manner that they are depended on. This may cause very deep
+    directory structures and duplicate package installs as there is no
+    de-duplicating.
+    Sets \`--install-strategy=nested\`.
   `,
-  flatten,
+  deprecated: `
+    This option has been deprecated in favor of \`--install-strategy=nested\`
+  `,
+  flatten (key, obj, flatOptions) {
+    if (obj[key]) {
+      obj['install-strategy'] = 'nested'
+      flatOptions.installStrategy = 'nested'
+    }
+  },
 })
 
 define('legacy-peer-deps', {
@@ -1523,8 +1552,8 @@ define('prefix', {
   short: 'C',
   default: '',
   defaultDescription: `
-    In global mode, the folder where the node executable is installed. In
-    local mode, the nearest parent folder containing either a package.json
+    In global mode, the folder where the node executable is installed.
+    Otherwise, the nearest parent folder containing either a package.json
     file or a node_modules folder.
   `,
   description: `

smoke-tests/tap-snapshots/test/index.js.test.cjs

@@ -56,7 +56,8 @@ npm ERR! npm ci
 npm ERR! 
 npm ERR! Options:
 npm ERR! [-S|--save|--no-save|--save-prod|--save-dev|--save-optional|--save-peer|--save-bundle]
-npm ERR! [-E|--save-exact] [-g|--global] [--global-style] [--legacy-bundling]
+npm ERR! [-E|--save-exact] [-g|--global] [--install-strategy <hoisted|nested|shallow>]
+npm ERR! [--legacy-bundling] [--global-style]
 npm ERR! [--omit <dev|optional|peer> [--omit <dev|optional|peer> ...]]
 npm ERR! [--strict-peer-deps] [--no-package-lock] [--foreground-scripts]
 npm ERR! [--ignore-scripts] [--no-audit] [--no-bin-links] [--no-fund] [--dry-run]

tap-snapshots/test/lib/commands/config.js.test.cjs

@@ -60,8 +60,8 @@ exports[`test/lib/commands/config.js TAP config list --json > output matches sna
   "git": "git",
   "git-tag-version": true,
   "global": false,
-  "global-style": false,
   "globalconfig": "{GLOBALPREFIX}/npmrc",
+  "global-style": false,
   "heading": "npm",
   "https-proxy": null,
   "if-present": false,
@@ -82,6 +82,7 @@ exports[`test/lib/commands/config.js TAP config list --json > output matches sna
   "init.module": "{HOME}/.npm-init.js",
   "init.version": "1.0.0",
   "install-links": true,
+  "install-strategy": "hoisted",
   "key": null,
   "legacy-bundling": false,
   "legacy-peer-deps": false,
@@ -234,6 +235,7 @@ init.license = "ISC"
 init.module = "{HOME}/.npm-init.js" 
 init.version = "1.0.0" 
 install-links = true 
+install-strategy = "hoisted" 
 json = false 
 key = null 
 legacy-bundling = false