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

Depends on @npmcli/arborist@4.0.0

Re: https://github.com/npm/rfcs/pull/434

PR-URL: https://github.com/npm/cli/pull/3880
Credit: @isaacs
Close: #3880
Reviewed-by: @wraithgar

5 files changed, 104 insertions, 0 deletions

diff --git a/docs/content/using-npm/config.md b/docs/content/using-npm/config.md
index 10e8ca9b9..fb155ebcf 100644
--- a/docs/content/using-npm/config.md
+++ b/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"
diff --git a/lib/utils/config/definitions.js b/lib/utils/config/definitions.js
index 009f60a7b..3bb8a4210 100644
--- a/lib/utils/config/definitions.js
+++ b/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: [
diff --git a/tap-snapshots/test/lib/config.js.test.cjs b/tap-snapshots/test/lib/config.js.test.cjs
index b21b75cd2..0c57014de 100644
--- a/tap-snapshots/test/lib/config.js.test.cjs
+++ b/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
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 9d5fe79af..e0878c357 100644
--- a/tap-snapshots/test/lib/utils/config/definitions.js.test.cjs
+++ b/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\`
 
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 4e3efb916..d092ba02b 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
@@ -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"