Improve Build/Template Error Messages

[jfelchner]

One of my major OSS initiatives in 2018 is going to be to improve error messages throughout Ember in order to make our lives as developers easier. One of the lowest hanging fruit in regards to improving errors involves the error page that is shown when a build error happens.

The purpose of this issue is to document all of the work that is required to get the error page to the state we think as a community that should be the end result. I'll edit this description as requirements change.

• [ ] Add basic styling to the error page
  • https://github.com/ember-cli/broccoli-middleware/pull/25 (MVP)
  • https://github.com/ember-cli/broccoli-middleware/pull/4 (Epic)
• [ ] Update broccoli's error object to return the error information with the data outlined below
  • https://github.com/ember-cli/broccoli-builder/pull/10
• [ ] Update glimmer to return a parseable error object with the data outlined below
  • https://github.com/tildeio/glimmer/issues/348
  • https://github.com/glimmerjs/glimmer-vm/pull/540
• [ ] Update Ember.js to return a parseable error object with the data outlined below
  • https://github.com/emberjs/ember.js/issues/14625
• [ ] Update Handlebars to return a parseable error object with the data outlined below
  • Unclear on how to do this just yet. Handlebars allows a custom error parser to be added in, however it's currently in some auto-generated json code so I'm unclear as to where to modify to make this happen.
• [ ] Update HTMLBars to Allow Add-On Authors to Generate Consistent Error Messages
  • https://github.com/ember-cli/ember-cli-htmlbars/pull/115
• [ ] Incorporate the new error objects into the error page
• [ ] Documentation for All the Things
  • https://github.com/ember-cli/ember-cli/pull/7090

There will likely be other error improvements that will fall out of this work at which time I'll create a new issue for those improvements.

Error Structure

Note: This list is what we expect to need from the error object for all of its various use cases.

• Error Location Object
  • File Name
  • File Extension
  • Line Number
  • Column Number
• Code Frame - The snippet of code where the error occurred
• Error Class - (eg "ParseError", "TemplateError", "BuildError", etc)
• Main Error Message - The simple message not including any other information included elsewhere (eg "file already exists, mkdir 'C:\inetpub\wwwroot\ember-test\tmp")
• Call Stack - As an array of objects containing:
  • Call Pointer (Function name, keyword, etc)
  • Location Object (see "Error Location Object" above)
• Documentation URL - An (optional) URL which can be attached to the error in order to provide much more information than can be provided in the error itself.

EmberCLI

• Environment
  • EmberCLI Version
  • Ember Version
  • Ember Data Version
  • Node Version
  • NPM/Yarn Version
  • TODO: Path Variables?

Broccoli Only

• Node List
  • Node ID
  • Node Name
  • Parent Node ID
• Instantiation Stack - As an array of objects containing:
  • Call Pointer (Function name, keyword, etc)
  • Location Object (see "Error Location Object" above)

Examples

• Bundler
• [Yarn]() TODO

[stefanpenner]

https://github.com/broccolijs/broccoli#errors is some related docs, but more detailed work is happening here: https://github.com/broccolijs/broccoli/blob/06438d912ffedd1cf236337569ceae49e9c9e29d/lib/builder.js#L279-L373

and more specifically: https://github.com/broccolijs/broccoli/blob/06438d912ffedd1cf236337569ceae49e9c9e29d/lib/builder.js#L356-L372

[stefanpenner]

cc @joliss

[joliss]

Big :+1: on getting a richer Broccoli error object, and using it to produce better error pages.

We can evolve the Broccoli error API without breakage by adding feature flags to Broccoli's node API and converting old error objects into new error objects and vice versa. (@rwjblue has done this before as well.)

[joliss]

The current structure of Broccoli errors is defined in builder.js:378. The file/treeDir/line/column structure is very rudimentary indeed, and we could clearly extend it as suggested by @jfelchner.

[locks]

Closing as stale. Big changes are coming to CLI's pipeline which the current discussion won't suit. Thank you for all the effforts!