RFC: Error and Reporting Alignment

Proposal for Codifying Errors Across the Ecosystem for Consistent Reporting

While working on webpack-stylish one thing has become glaringly obvious: the format of errors in and out of webpack proper, across the ecosystem and between loaders and plugins, is extremely inconsistent. This ultimately provides a poor user experience when debugging errors. And would open greater opportunities to mitigate new-user intimidation by the output. (ref: https://twitter.com/marvinhagemeist/status/965134200012713984)

Examples

A warning sample from webpack:

‘./entry.js\n6:12-19 Critical dependency: require function is used in a way in which dependencies cannot be statically extracted\n @ ./entry.js’

An error sample from webpack:

 ’./entry.js\nModule not found: Error: Can\’t resolve \‘test\’ in \‘/code/webpack-stylish/test/fixture\‘\n @ ./entry.js 6:14-29’

Errors from the performance features: https://github.com/webpack/webpack/blob/master/lib/performance/AssetsOverSizeLimitWarning.js

An ecosystem example: https://github.com/JaKXz/stylelint-webpack-plugin/blob/master/lib/run-compilation.js#L38. Whereby this plugin is passing along stylelint-formatted errors in a group, as a single error, to the compilation.

All are of a different format, containing different formats of information without. The performance (and others) errors are vastly different as their messages contain lists of files replete with newlines. As you can see from the error and warning examples, the line:column positions are in different places.

Identifiable Problems

1. Messages are overly verbose
2. Lack of consistent toString()
3. Line number and column representation is not consistent
4. Metadata accessible only in the error message (eg. list of assets)

Proposed Solution

My proposal is multi-faceted:

1. Create a standard WebpackError class containing the following signature:

abstract class WebpackError {
  get id             // hash identifying the error
  get/set message
  get/set name       // name to identify the file, error category, group, etc. eg. "performance" or "configuration"
  get/set lineNumber
  get/set column
  get/set columnEnd  // some webpack errors contain a column range
  get metaData       // object provided to set error-specific data. eg. an asset list

  function toString([formatterFn])  // formatterFn can/should be set in the constructor, if needed
}

The base class would be abstract only in that the class should not be directly instantiated. The class should be extended/inherited by a subclass. This will provide for more accurate identification of Error sources, should the provided information in the class be insufficient.

1. toString() will by default output in the following format:

{lineNumber}:{column} {name}: {message}

There may be an opportunity to automate rendering of metaData as well.

1. Enforce by proxying as a warning in v3, and as an error in v4+, that all objects pushed to compilation.errors and compilation.warnings be an instance of WebpackError

2. Error if WebpackErrorinstance is created without minimum set of options: column, lineNumber, message, name.

3. Warn if a WebpackError has a message set longer than a reasonable preset value. (Reference ESLint for example, which imposes reasonable error message lengths)

4. Update both v3 and v4 to use these patterns.

5. Update loaders in webpack-contrib to use these patterns.

6. Write blog post outlining the changes needed by 3rd party loader/plugin authors.

7. Update webpack.js.org to include a page on error reporting.

Conclusion

I believe these changes will be a great improvement to webpack on the whole. As mentioned, it will greatly improve the user experience, aid in debugging, and reduce new user and adoption friction.

[shellscape]

Yes, they should be serializable. I don’t foresee any issue with the proposal being so, but it’s possible that classes with extend that error class may implement code that is not. However, I’m not sure how we’d enforce that as yet.

[shellscape]

This effort is being abandoned due to managerial disagreement. Copying from PR #6823:

As mentioned off-Github: This PR is being blocked based on commented-out code within the PR, despite the fact that no guidelines exist within CONTRIBUTING.md which explicitly forbid that practice, and despite the fact that the comments are pertinent to quick-to-follow phases related to and reliant upon the code within the //TODO: blocks, and that the commented-out code is expressive and speaks to intent and guidance for changes to follow.

I understand that disagreements with a maintainer’s choices are inevitable, but I disagree with applying arbitrary rules to Pull Requests on a whim. For these reasons I’m closing this PR and abandoning my effort to improve webpack’s Error use. This is a net loss for the user experience.