feat: add JSON reporter. fixes #16

[shellscape]

This PR contains a:

• bugfix
• new feature
• code refactor
• test update
• typo fix
• metadata update

Motivation / Use-Case

Issue #16 called for a reporter that did nothing but write the JSON result of a build to stdout.

Breaking Changes

None

Additional Info

webpack-cli ships with a mind bottling number of CLI flags one can use to control the output. Those seem pretty limited for the JSON option, though it looks like webpack-cli also sets stats.modules = true for JSON output. As a practice and principle, webpack-command does not support those flags, nor does it default stats.modules if the JsonReporter is used; those settings should be controlled by users in a config.

/cc @billyjanitsch @valscion for review

[tmair]

There is a typo here:
rogress instead of progress

[valscion]

Looks nice! I'll test this with webpack-bundle-analyzer.

Note that if the output of stats.toJson is huge, JSON.stringify could cause the process to run out of memory. We faced this over at webpack-bundle-analyzer: webpack-contrib/webpack-bundle-analyzer#119

The fix was to use bfj to write the JSON in a streaming fashion: https://github.com/webpack-contrib/webpack-bundle-analyzer/pull/129/files

I'm not sure if this will be a problem with webpack-command, though. And whether it's worth it to add another dependency here.

[shellscape]

@valscion that's a great bit of info, thanks. I wonder if there are key indicators in the stats object that would determine if we needed to use bfj.

[valscion]

I wonder if there are key indicators in the stats object that would determine if we needed to use bfj.

Hmm I think we could check if any of the array values are exceedingly large, and then use something like bfj?

For example, given this JSON for webpack 3:

{
  "errors": [],
  "warnings": [],
  "version": "3.11.0",
  "hash": "79b004e761ec803e461a",
  "children": [
    {
      "errors": [],
      "warnings": [],
      "hash": "79b004e761ec803e461a",
      "time": 12038,
      "publicPath": "",
      "assetsByChunkName": { },
      "filteredAssets": 0,
      "entrypoints": { },
      "chunks": [
        { }
      ],
      "modules": [
        { }
      ],
      "filteredModules": 0
    }
  ]
}

...the huge values in here can be the chunks and modules. We could add some logic to say the combined sizes of some of these are larger than some constant, then we'd use streaming JSON output.

I'm not sure if it's worth the hassle, though. I've seen the stats JSON having various kinds of structures in the past, and so peeking inside it has seemed to be a bit brittle.

[shellscape]

I've seen the stats JSON having various kinds of structures in the past, and so peeking inside it has seemed to be a bit brittle.

Seems to be a trend in webpack. The same thing is true of errors and warnings - you never know what you're going to get in there.

OK so I suppose we'll chalk this up as a might-happen-case and if it does pop up, we know what to do to solve it. bfj isn't that big but it's big enough that a third-party, separate module containing a reporter for that scenario would probably be the best route given that it'll be a specialized use-case.

[valscion]

Yeah, it's probably best this way. webpack-cli would also have had the same issue, I think, as that also used JSON.stringify if I remember correctly.

if it does pop up, we know what to do to solve it

Yeah, this seems to be a good approach here :)

[valscion]

Seems like webpack-cli outputs the results of --json prettified, i.e. are indeed indented the way I wrote in #39 (comment)

This instead outputs the entire result to one line. It makes it a bit difficult to open the resulting JSON file to manually check any of the contents. I'm not sure if it's something that's concerning here, but we did indeed have a PR over at webpack-bundle-analyzer to specifically change this to be pretty formatted: webpack-contrib/webpack-bundle-analyzer#180 — I'd suppose you would get pressure to change the output to be less condensed if kept as-is.

---

I tested this out on my webpack 4 migration code, and indeed with --reporter json, the resulting JSON can be used for

webpack-bundle-analyzer path/to/stats.json

so for our use cases, this feature works.

---

How do you feel about this CLI flag differing from webpack-cli? Do you think we could get similar main-level API for this as in webpack-cli so that webpack ecosystem could continue saying that --json flag works, or should we teach our users to use --reporter json instead if they're using webpack-command?

This is a concern to us at webpack-bundle-analyzer, as we've indeed documented how to use the --json flag in the README.md here: https://github.com/webpack-contrib/webpack-bundle-analyzer#usage-as-a-cli-utility

It would feel a bit strange to mention that there's two ways of getting JSON out of webpack command here. It's not a deal breaker, though — merely something that could be a bit confusing to users.

[valscion]

Should this perhaps be JsonReporter instead of JesonReporter?

[shellscape]

jeez, yeah it should. I shouldn't PR so early in the morning 😆

[valscion]

I kinda liked JesonReporter 😄

[shellscape]

Seems like webpack-cli outputs the results of --json prettified

Yeah, you're correct: https://github.com/webpack/webpack-cli/blob/master/bin/cli.js#L485
What I'd like to do then is provide a --pretty flag for those that need it. So it'd look like: --reporter json --pretty

It would feel a bit strange to mention that there's two ways of getting JSON out of webpack command here. It's not a deal breaker, though — merely something that could be a bit confusing to users.

All good points above that quote. So w-command operates on a different paradigm than w-cli. w-cli is an absolute mess of CLI options, and while --json is inherently simpler than --reporter json, we want to push users towards a standard paradigm they're going to see in other tools (mocha, jest, eslint, etc). And while it might take a while, I fully intend on w-command gaining the majority of the user-base. There's a slight learning curve there, but I believe it's worth while.

[valscion]

👍 Seems reasonable to push the ecosystem towards a different paradigm than what webpack-cli had.

What I'd like to do then is provide a --pretty flag for those that need it. So it'd look like: --reporter json --pretty

Could we do the opposite? Something like --reporter json --optimized or alike — as most likely the prettification will be quite fast and will likely be what users expected to see.

I don't feel too strongly on this, though — you do what you think is best ☺️

[shellscape]

I've got no issue doing pretty output first. If there's a call for non-pretty we can add that option in there at that point.

[valscion]

Nice, this seems good to me!

---

On another note, I got this error when I accidentally ran on master branch where the json reporter wasn't defined:

TypeError: ReporterClass is not a constructor
    at module.exports (/Users/vesa/code/test/node_modules/webpack-command/lib/compiler.js:90:20)
    at load.then (/Users/vesa/code/test/node_modules/webpack-command/lib/index.js:45:47)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:188:7)
    at Function.Module.runMain (module.js:686:11)
    at startup (bootstrap_node.js:187:16)
    at bootstrap_node.js:608:3
error Command failed with exit code 1.

Should I open a new issue to discuss adding a better error message here?

[shellscape]

No need, I'll get a fix up for that here in a moment. Thanks for pointing that out!

[valscion]

Thanks! Great work 👍