feat(config): Add --lockfile-version config option

Depends on @npmcli/arborist@4.0.0

Re: npm/rfcs#434

PR-URL: #3880
Credit: @isaacs
Close: #3880
Reviewed-by: @wraithgar

docs/content/using-npm/config.md

@@ -969,6 +969,31 @@ When passed to `npm config` this refers to which config file to use.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### `lockfile-version`
+
+* Default: Version 2 if no lockfile or current lockfile version less than or
+  equal to 2, otherwise maintain current lockfile version
+* Type: null, 1, 2, or 3
+
+Set the lockfile format version to be used in package-lock.json and
+npm-shrinkwrap-json files. Possible options are:
+
+1: The lockfile version used by npm versions 5 and 6. Lacks some data that
+is used during the install, resulting in slower and possibly less
+deterministic installs. Prevents lockfile churn when interoperating with
+older npm versions.
+
+2: The default lockfile version used by npm version 7. Includes both the
+version 1 lockfile data and version 3 lockfile data, for maximum determinism
+and interoperability, at the expense of more bytes on disk.
+
+3: Only the new lockfile information introduced in npm version 7. Smaller on
+disk than lockfile version 2, but not interoperable with older npm versions.
+Ideal if all users are on npm version 7 and higher.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### `loglevel`
 
 * Default: "notice"

lib/utils/config/definitions.js

@@ -1142,6 +1142,33 @@ define('location', {
   },
 })
 
+define('lockfile-version', {
+  default: null,
+  type: [null, 1, 2, 3],
+  defaultDescription: `
+    Version 2 if no lockfile or current lockfile version less than or equal to
+    2, otherwise maintain current lockfile version
+  `,
+  description: `
+    Set the lockfile format version to be used in package-lock.json and
+    npm-shrinkwrap-json files.  Possible options are:
+
+    1: The lockfile version used by npm versions 5 and 6.  Lacks some data that
+    is used during the install, resulting in slower and possibly less
+    deterministic installs.  Prevents lockfile churn when interoperating with
+    older npm versions.
+
+    2: The default lockfile version used by npm version 7.  Includes both the
+    version 1 lockfile data and version 3 lockfile data, for maximum
+    determinism and interoperability, at the expense of more bytes on disk.
+
+    3: Only the new lockfile information introduced in npm version 7.  Smaller
+    on disk than lockfile version 2, but not interoperable with older npm
+    versions.  Ideal if all users are on npm version 7 and higher.
+  `,
+  flatten,
+})
+
 define('loglevel', {
   default: 'notice',
   type: [

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

@@ -86,6 +86,7 @@ exports[`test/lib/config.js TAP config list --json > output matches snapshot 1`]
   "link": false,
   "local-address": null,
   "location": "user",
+  "lockfile-version": null,
   "loglevel": "notice",
   "logs-max": 10,
   "long": false,
@@ -236,6 +237,7 @@ legacy-peer-deps = false
 link = false 
 local-address = null 
 location = "user" 
+lockfile-version = null 
 loglevel = "notice" 
 logs-max = 10 
 ; long = false ; overridden by cli

tap-snapshots/test/lib/utils/config/definitions.js.test.cjs

@@ -82,6 +82,7 @@ Array [
   "link",
   "local-address",
   "location",
+  "lockfile-version",
   "loglevel",
   "logs-max",
   "long",
@@ -1041,6 +1042,30 @@ exports[`test/lib/utils/config/definitions.js TAP > config description for locat
 When passed to \`npm config\` this refers to which config file to use.
 `
 
+exports[`test/lib/utils/config/definitions.js TAP > config description for lockfile-version 1`] = `
+#### \`lockfile-version\`
+
+* Default: Version 2 if no lockfile or current lockfile version less than or
+  equal to 2, otherwise maintain current lockfile version
+* Type: null, 1, 2, or 3
+
+Set the lockfile format version to be used in package-lock.json and
+npm-shrinkwrap-json files. Possible options are:
+
+1: The lockfile version used by npm versions 5 and 6. Lacks some data that
+is used during the install, resulting in slower and possibly less
+deterministic installs. Prevents lockfile churn when interoperating with
+older npm versions.
+
+2: The default lockfile version used by npm version 7. Includes both the
+version 1 lockfile data and version 3 lockfile data, for maximum determinism
+and interoperability, at the expense of more bytes on disk.
+
+3: Only the new lockfile information introduced in npm version 7. Smaller on
+disk than lockfile version 2, but not interoperable with older npm versions.
+Ideal if all users are on npm version 7 and higher.
+`
+
 exports[`test/lib/utils/config/definitions.js TAP > config description for loglevel 1`] = `
 #### \`loglevel\`
 

tap-snapshots/test/lib/utils/config/describe-all.js.test.cjs

@@ -843,6 +843,31 @@ When passed to \`npm config\` this refers to which config file to use.
 <!-- automatically generated, do not edit manually -->
 <!-- see lib/utils/config/definitions.js -->
 
+#### \`lockfile-version\`
+
+* Default: Version 2 if no lockfile or current lockfile version less than or
+  equal to 2, otherwise maintain current lockfile version
+* Type: null, 1, 2, or 3
+
+Set the lockfile format version to be used in package-lock.json and
+npm-shrinkwrap-json files. Possible options are:
+
+1: The lockfile version used by npm versions 5 and 6. Lacks some data that
+is used during the install, resulting in slower and possibly less
+deterministic installs. Prevents lockfile churn when interoperating with
+older npm versions.
+
+2: The default lockfile version used by npm version 7. Includes both the
+version 1 lockfile data and version 3 lockfile data, for maximum determinism
+and interoperability, at the expense of more bytes on disk.
+
+3: Only the new lockfile information introduced in npm version 7. Smaller on
+disk than lockfile version 2, but not interoperable with older npm versions.
+Ideal if all users are on npm version 7 and higher.
+
+<!-- automatically generated, do not edit manually -->
+<!-- see lib/utils/config/definitions.js -->
+
 #### \`loglevel\`
 
 * Default: "notice"