feat: add devEngines field

This field is only looked at when in the top-level project, and takes precedence over `engines` when present

An alternative implementation instead of a new top-level field would be `publishConfig.engines`, which when present would override `engines` for NON top-level projects.

Author: ljharb

docs/lib/content/commands/npm-query.md

@@ -125,6 +125,7 @@ npm query ":type(git)" | jq 'map(.name)' | xargs -I {} npm why {}
     "peerDependencies": {},
     "peerDependenciesMeta": {},
     "engines": {},
+    "devEngines": {},
     "os": [],
     "cpu": [],
     "workspaces": {},
@@ -158,7 +159,7 @@ $ npm query ':root>:outdated(in-range).prod' --no-expect-results
 
 ### Package lock only mode
 
-If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded.  This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines).
+If package-lock-only is enabled, only the information in the package lock (or shrinkwrap) is loaded.  This means that information from the package.json files of your dependencies will not be included in the result set (e.g. description, homepage, engines, devEngines).
 
 ### Configuration
 

docs/lib/content/configuring-npm/package-json.md

@@ -1051,6 +1051,12 @@ Unless the user has set the
 advisory only and will only produce warnings when your package is installed as a
 dependency.
 
+### devEngines
+
+This field works exactly like the `engines` field, but it is only respected at the project root.
+
+When present, the `engines` field is ignored.
+
 ### os
 
 You can specify which operating systems your

docs/lib/content/using-npm/developers.md

@@ -61,8 +61,9 @@ goes in that file.  At the very least, you need:
 * name: This should be a string that identifies your project.  Please do
   not use the name to specify that it runs on node, or is in JavaScript.
   You can use the "engines" field to explicitly state the versions of node
-  (or whatever else) that your program requires, and it's pretty well
-  assumed that it's JavaScript.
+  (or whatever else) that your program requires (and "devEngines" when the
+  requirements for developers differ from the requirements for users), and
+  it's pretty well assumed that it's JavaScript.
 
   It does not necessarily need to match your github repository name.
 
@@ -71,8 +72,12 @@ goes in that file.  At the very least, you need:
 * version: A semver-compatible version.
 
 * engines: Specify the versions of node (or whatever else) that your
-  program runs on.  The node API changes a lot, and there may be bugs or
-  new functionality that you depend on.  Be explicit.
+  program runs on. The node API changes a lot, and there may be bugs or
+  new functionality that you depend on. Be explicit.
+
+* devEngines: Specify the versions of node (or whatever else) that your
+  program needs for development. The node API changes a lot, and there may
+  be bugs or new functionality that you depend on. Be explicit.
 
 * author: Take some credit.
 

node_modules/npm-install-checks/lib/index.js

@@ -1,9 +1,9 @@
 const semver = require('semver')
 
-const checkEngine = (target, npmVer, nodeVer, force = false) => {
+const checkEngine = ({ devEngines, engines, _id: pkgid }, npmVer, nodeVer, force = false, isProjectRoot = false) => {
   const nodev = force ? null : nodeVer
-  const eng = target.engines
   const opt = { includePrerelease: true }
+  const eng = isProjectRoot ? devEngines || engines : engines
   if (!eng) {
     return
   }
@@ -12,7 +12,7 @@ const checkEngine = (target, npmVer, nodeVer, force = false) => {
   const npmFail = npmVer && eng.npm && !semver.satisfies(npmVer, eng.npm, opt)
   if (nodeFail || npmFail) {
     throw Object.assign(new Error('Unsupported engine'), {
-      pkgid: target._id,
+      pkgid,
       current: { node: nodeVer, npm: npmVer },
       required: eng,
       code: 'EBADENGINE',

test/lib/commands/publish.js

@@ -753,6 +753,7 @@ t.test('manifest', async t => {
     'tap',
     'readme',
     'engines',
+    'devEngines',
     'workspaces',
   ]
 

workspaces/arborist/lib/arborist/build-ideal-tree.js

@@ -232,7 +232,7 @@ module.exports = cls => class IdealTreeBuilder extends cls {
     for (const node of this.idealTree.inventory.values()) {
       if (!node.optional) {
         try {
-          checkEngine(node.package, npmVersion, nodeVersion, this[_force])
+          checkEngine(node.package, npmVersion, nodeVersion, this[_force], node.isProjectRoot)
         } catch (err) {
           if (engineStrict) {
             throw err

workspaces/arborist/lib/shrinkwrap.js

@@ -92,6 +92,7 @@ const pkgMetaKeys = [
   'acceptDependencies',
   'funding',
   'engines',
+  'devEngines',
   'os',
   'cpu',
   '_integrity',

workspaces/arborist/test/arborist/build-ideal-tree.js

@@ -126,6 +126,18 @@ t.test('fail on mismatched engine when engineStrict is set', async t => {
   }), { code: 'EBADENGINE' })
 })
 
+t.test('fail on mismatched devEngine when engineStrict is set', async t => {
+  const path = resolve(fixtures, 'dev-engine-specification')
+
+  t.rejects(buildIdeal(path, {
+    ...OPT,
+    nodeVersion: '12.18.4',
+    engineStrict: true,
+  }).then(() => {
+    throw new Error('failed to fail')
+  }), { code: 'EBADENGINE' })
+})
+
 t.test('fail on malformed package.json', t => {
   const path = resolve(fixtures, 'malformed-json')
 
@@ -157,6 +169,18 @@ t.test('warn on mismatched engine when engineStrict is false', t => {
   ]))
 })
 
+t.test('warn on mismatched devEngine when engineStrict is false', t => {
+  const path = resolve(fixtures, 'dev-engine-specification')
+  const check = warningTracker()
+  return buildIdeal(path, {
+    ...OPT,
+    nodeVersion: '12.18.4',
+    engineStrict: false,
+  }).then(() => t.match(check(), [
+    ['warn', 'EBADENGINE'],
+  ]))
+})
+
 t.test('fail on mismatched platform', async t => {
   const path = resolve(fixtures, 'platform-specification')
   t.rejects(buildIdeal(path, {

workspaces/arborist/test/fixtures/dev-engine-specification/package-lock.json

@@ -0,0 +1,16 @@
+{
+  "name": "dev-engine-platform-test",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+  },
+  "devEngines": {
+    "node": "< 0.1"
+  }
+}