Morph Neutrino API and CLI into middleware injectors for external CLI tools (#852)

__Edited to reflect current state of PR.__

Fixes #708.
Fixes #736.
Fixes #870.
Fixes #842.
Closes #773.
Closes #839.
Closes #849.

Outstanding issues to file:

- [x] Update docs to reflect these API changes (#896)
- [x] ~~Determine need for config-loading bins instead of forcing config file boilerplate (still unsure if we should do this because of IDE integration)~~
- [x] Modify stats to produce friendlier build output (#897)

This patch is a work-in-progress, and is quite the overhaul of Neutrino into something different. Right now there is no change to the documentation, which I will change if we decide to move forward with this.

This patch morphs Neutrino into a "preset engine" for transforming managed webpack configuration into a format that can be consumed by other CLI tools. No longer would we wrap external CLI tools like webpack, eslint, jest, karma, mocha, stylelint, etc. Instead, Neutrino could augment these tools by exposing methods for returning usable configuration.

This approach gives the user control of their CLI tool back, and they can programmatically invoke Neutrino to load their configuration, and override however they like:

```bash
webpack --mode production
```

```js
// webpack.config.js
const neutrino = require('neutrino');

// Load with no config overrides:
module.exports = neutrino().webpack();

// Load with config overrides:
module.exports = neutrino().webpack(config => {
  // return whatever config you want
});

// Load with no config overrides using low-level API:
module.exports = neutrino().output('webpack');

// Load with config overrides using low-level API:
module.exports = neutrino().output('webpack', config => {
  // return whatever config you want
});
```

The same works for ESLint and friends too (except for mocha, since it has no config file we can be required from):

```bash
eslint src
```

```js
// .eslintrc.js
const neutrino = require('neutrino');

// Load with no config overrides:
module.exports = neutrino().eslintrc();

// Load with config overrides:
module.exports = neutrino().eslintrc(config => {
  // return whatever config you want, like manipulating rules, etc.
});
```

---

- This approach is predicated on having middleware defined in `.neutrinorc.js`, which shouldn't change at all.
- ~~This does do away with a bunch of CLI functionality like `--inspect` or `--use`, but those become less useful if we are just an interface to external CLI tools. We can discuss potentially bringing those back.~~ This is now back in the form of the CLI with `neutrino --inspect`.
- ~~All environment variables are gone. We rely only on webpack's `mode` value.~~ We internally only use webpack's `mode` value, but still set `process.env.NODE_ENV` if not set based on the mode, or defaulted to `production`.
- ~~There is no longer a create-project tool, since we cannot force users to choose between competing tools like webpack-cli or webpack-command, and webpack-dev-server or webpack-serve.~~ The create-project tool is back, and we opt for `webpack-cli` and `webpack-dev-server` as opinions for now.

I'm sure there are other major things I am neglecting to mention. Let's discuss! I see so many benefits to this, including reduced maintenance burden and the ability to allow people to use Neutrino without dumping their existing tools.

cc: @mozilla-neutrino/core-contributors

Author: eliperelman

.eslintrc.js

@@ -1,5 +1,3 @@
-const { Neutrino } = require('./packages/neutrino');
+const neutrino = require('./packages/neutrino');
 
-module.exports = Neutrino({ root: __dirname })
-  .use('.neutrinorc.js')
-  .call('eslintrc');
+module.exports = neutrino(require('./.neutrinorc')).eslintrc();

package.json

@@ -19,7 +19,7 @@
     "docs:bootstrap": "pip install -r docs/requirements.txt",
     "docs:serve": "mkdocs serve",
     "link:all": "lerna exec yarn link",
-    "lint": "node packages/neutrino/bin/neutrino lint",
+    "lint": "eslint packages .neutrinorc.js",
     "precommit": "lint-staged",
     "release": "lerna publish --force-publish=*",
     "release:preview": "lerna publish --force-publish=* --skip-git --skip-npm",
@@ -31,7 +31,7 @@
     "validate:eslintrc:airbnb-base": "eslint --no-eslintrc --print-config . -c ./packages/airbnb-base/eslintrc.js > /dev/null",
     "validate:eslintrc:standardjs": "eslint --no-eslintrc --print-config . -c ./packages/standardjs/eslintrc.js > /dev/null",
     "validate:eslintrc": "yarn validate:eslintrc:eslint && yarn validate:eslintrc:airbnb-base && yarn validate:eslintrc:airbnb && yarn validate:eslintrc:standardjs && yarn validate:eslintrc:root",
-    "version": "test -v SKIP_CHANGELOG || yarn changelog --package && git add CHANGELOG.md"
+    "version": "[[ -z \"$SKIP_CHANGELOG\" ]] || yarn changelog --package && git add CHANGELOG.md"
   },
   "devDependencies": {
     "auto-changelog": "^1.4.6",
@@ -40,12 +40,19 @@
     "eslint-config-prettier": "^2.9.0",
     "eslint-plugin-prettier": "^2.6.0",
     "husky": "^0.14.3",
+    "jest": "^22.4.3",
+    "karma": "^2.0.2",
+    "karma-cli": "^1.0.1",
     "lerna": "^2.11.0",
     "lint-staged": "^7.0.5",
+    "mocha": "^5.2.0",
     "nyc": "^11.7.1",
     "prettier": "^1.12.1",
+    "stylelint": "^8.4.0",
     "verdaccio": "3.0.0-beta.10",
-    "verdaccio-memory": "^1.0.1"
+    "verdaccio-memory": "^1.0.1",
+    "webpack": "^4.8.3",
+    "webpack-dev-server": "^3.1.4"
   },
   "lint-staged": {
     "*.js": [

packages/airbnb-base/eslintrc.js

@@ -1,5 +1,3 @@
-const { Neutrino } = require('../neutrino');
+const neutrino = require('../neutrino');
 
-module.exports = Neutrino({ cwd: __dirname })
-  .use(require('.')) // eslint-disable-line global-require
-  .call('eslintrc');
+module.exports = neutrino(require('.')).eslintrc();

packages/airbnb-base/package.json

@@ -24,11 +24,12 @@
   },
   "dependencies": {
     "@neutrinojs/eslint": "^8.2.0",
-    "eslint": "^4.19.1",
     "eslint-config-airbnb-base": "^12.1.0",
     "eslint-plugin-import": "^2.11.0"
   },
   "peerDependencies": {
-    "neutrino": "^8.0.0"
+    "eslint": "^4.0.0",
+    "neutrino": "^8.0.0",
+    "webpack": "^4.0.0"
   }
 }

packages/airbnb-base/test/airbnb_test.js

@@ -1,5 +1,6 @@
 import test from 'ava';
-import { Neutrino } from 'neutrino';
+import Neutrino from '../../neutrino/Neutrino';
+import neutrino from '../../neutrino';
 
 const mw = () => require('..');
 const options = { eslint: { rules: { semi: false } } };
@@ -9,37 +10,49 @@ test('loads preset', t => {
 });
 
 test('uses preset', t => {
-  t.notThrows(() => Neutrino().use(mw()));
+  t.notThrows(() => new Neutrino().use(mw()));
 });
 
 test('uses with options', t => {
-  t.notThrows(() => Neutrino().use(mw(), options));
+  t.notThrows(() => new Neutrino().use(mw(), options));
 });
 
 test('instantiates', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw());
 
   t.notThrows(() => api.config.toConfig());
 });
 
 test('instantiates with options', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw(), options);
 
   t.notThrows(() => api.config.toConfig());
 });
 
-test('exposes lint command', t => {
-  const api = Neutrino();
+test('exposes eslintrc output handler', t => {
+  const api = new Neutrino();
 
   api.use(mw());
 
-  t.is(typeof api.commands.lint, 'function');
+  const handler = api.outputHandlers.get('eslintrc');
+
+  t.is(typeof handler, 'function');
+});
+
+test('exposes eslintrc config from output', t => {
+  const config = neutrino(mw()).output('eslintrc');
+
+  t.is(typeof config, 'object');
+});
+
+test('exposes eslintrc method', t => {
+  t.is(typeof neutrino(mw()).eslintrc, 'function');
 });
 
-test('exposes eslintrc config', t => {
-  t.is(typeof Neutrino().use(mw()).call('eslintrc'), 'object');
+test('exposes eslintrc config from method', t => {
+  t.is(typeof neutrino(mw()).eslintrc(), 'object');
 });

packages/airbnb/eslintrc.js

@@ -1,5 +1,3 @@
-const { Neutrino } = require('../neutrino');
+const neutrino = require('../neutrino');
 
-module.exports = Neutrino({ cwd: __dirname })
-  .use(require('.')) // eslint-disable-line global-require
-  .call('eslintrc');
+module.exports = neutrino(require('.')).eslintrc();

packages/airbnb/package.json

@@ -24,13 +24,14 @@
   },
   "dependencies": {
     "@neutrinojs/eslint": "^8.2.0",
-    "eslint": "^4.19.1",
     "eslint-config-airbnb": "^16.1.0",
     "eslint-plugin-import": "^2.11.0",
     "eslint-plugin-jsx-a11y": "^6.0.3",
     "eslint-plugin-react": "^7.7.0"
   },
   "peerDependencies": {
-    "neutrino": "^8.0.0"
+    "eslint": "^4.0.0",
+    "neutrino": "^8.0.0",
+    "webpack": "^4.0.0"
   }
 }

packages/airbnb/test/airbnb_test.js

@@ -1,5 +1,6 @@
 import test from 'ava';
-import { Neutrino } from 'neutrino';
+import Neutrino from '../../neutrino/Neutrino';
+import neutrino from '../../neutrino';
 
 const mw = () => require('..');
 const options = { eslint: { rules: { semi: false } } };
@@ -9,37 +10,49 @@ test('loads preset', t => {
 });
 
 test('uses preset', t => {
-  t.notThrows(() => Neutrino().use(mw()));
+  t.notThrows(() => new Neutrino().use(mw()));
 });
 
 test('uses with options', t => {
-  t.notThrows(() => Neutrino().use(mw(), options));
+  t.notThrows(() => new Neutrino().use(mw(), options));
 });
 
 test('instantiates', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw());
 
   t.notThrows(() => api.config.toConfig());
 });
 
 test('instantiates with options', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw(), options);
 
   t.notThrows(() => api.config.toConfig());
 });
 
-test('exposes lint command', t => {
-  const api = Neutrino();
+test('exposes eslintrc output handler', t => {
+  const api = new Neutrino();
 
   api.use(mw());
 
-  t.is(typeof api.commands.lint, 'function');
+  const handler = api.outputHandlers.get('eslintrc');
+
+  t.is(typeof handler, 'function');
+});
+
+test('exposes eslintrc config from output', t => {
+  const config = neutrino(mw()).output('eslintrc');
+
+  t.is(typeof config, 'object');
+});
+
+test('exposes eslintrc method', t => {
+  t.is(typeof neutrino(mw()).eslintrc, 'function');
 });
 
-test('exposes eslintrc config', t => {
-  t.is(typeof Neutrino().use(mw()).call('eslintrc'), 'object');
+test('exposes eslintrc config from method', t => {
+  t.is(typeof neutrino(mw()).eslintrc(), 'object');
 });

packages/banner/package.json

@@ -21,10 +21,8 @@
     "npm": ">=5.4.0",
     "yarn": ">=1.2.1"
   },
-  "dependencies": {
-    "webpack": "^4.7.0"
-  },
   "peerDependencies": {
-    "neutrino": "^8.0.0"
+    "neutrino": "^8.0.0",
+    "webpack": "^4.0.0"
   }
 }

packages/banner/test/middleware_test.js

@@ -1,5 +1,5 @@
 import test from 'ava';
-import { Neutrino } from 'neutrino';
+import Neutrino from '../../neutrino/Neutrino';
 
 const mw = () => require('..');
 const options = { raw: false, entryOnly: false };
@@ -9,23 +9,23 @@ test('loads middleware', t => {
 });
 
 test('uses middleware', t => {
-  t.notThrows(() => Neutrino().use(mw()));
+  t.notThrows(() => new Neutrino().use(mw()));
 });
 
 test('uses with options', t => {
-  t.notThrows(() => Neutrino().use(mw(), options));
+  t.notThrows(() => new Neutrino().use(mw(), options));
 });
 
 test('instantiates', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw());
 
   t.notThrows(() => api.config.toConfig());
 });
 
 test('instantiates with options', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw(), options);
 

packages/clean/package.json

@@ -25,6 +25,7 @@
     "clean-webpack-plugin": "^0.1.19"
   },
   "peerDependencies": {
-    "neutrino": "^8.0.0"
+    "neutrino": "^8.0.0",
+    "webpack": "^4.0.0"
   }
 }

packages/clean/test/middleware_test.js

@@ -1,5 +1,5 @@
 import test from 'ava';
-import { Neutrino } from 'neutrino';
+import Neutrino from '../../neutrino/Neutrino';
 
 const mw = () => require('..');
 const options = { paths: ['sample'], root: __dirname };
@@ -9,23 +9,23 @@ test('loads middleware', t => {
 });
 
 test('uses middleware', t => {
-  t.notThrows(() => Neutrino().use(mw()));
+  t.notThrows(() => new Neutrino().use(mw()));
 });
 
 test('uses with options', t => {
-  t.notThrows(() => Neutrino().use(mw(), options));
+  t.notThrows(() => new Neutrino().use(mw(), options));
 });
 
 test('instantiates', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw());
 
   t.notThrows(() => api.config.toConfig());
 });
 
 test('instantiates with options', t => {
-  const api = Neutrino();
+  const api = new Neutrino();
 
   api.use(mw(), options);
 

packages/compile-loader/index.js

@@ -1,16 +1,25 @@
 const babelMerge = require('babel-merge');
 
-module.exports = (neutrino, options = {}) => neutrino.config.module
-  .rule(options.ruleId || 'compile')
+module.exports = (neutrino, options = {}) => {
+  neutrino.config.module
+    .rule(options.ruleId || 'compile')
     .test(options.test || neutrino.regexFromExtensions())
     .when(options.include, rule => rule.include.merge(options.include))
     .when(options.exclude, rule => rule.exclude.merge(options.exclude))
     .use(options.useId || 'babel')
-      .loader(require.resolve('babel-loader'))
-      .options({
-        cacheDirectory: true,
-        babelrc: false,
-        ...(options.babel || {})
-      });
+    .loader(require.resolve('babel-loader'))
+    .options({
+      cacheDirectory: true,
+      babelrc: false,
+      ...(options.babel || {})
+    });
+
+  neutrino.register('babel', (neutrino, override) => override(
+    neutrino.config.module
+      .rule('compile')
+      .use('babel')
+      .get('options')
+  ));
+};
 
 module.exports.merge = babelMerge;

packages/compile-loader/package.json

@@ -25,10 +25,10 @@
   "dependencies": {
     "@babel/core": "^7.0.0-beta.46",
     "babel-loader": "^8.0.0-beta.2",
-    "babel-merge": "^1.1.1",
-    "webpack": "^4.7.0"
+    "babel-merge": "^1.1.1"
   },
   "peerDependencies": {
-    "neutrino": "^8.0.0"
+    "neutrino": "^8.0.0",
+    "webpack": "^4.0.0"
   }
 }