Clean up error API in broccoli-plugin

[joliss]

Should we clean up the error-reporting API for Broccoli plugins in the same go as the upcoming .rebuild change? (Edit: Now the new new broccoli-plugin-based API.)

At the moment we have an informally-specified set of error properties: .message, .file, .treeDir, .line, .column, .stack

As a reminder for anyone popping in, we're using these properties to separate out info on structured error pages like this one:

In the future, we might even automatically show a few lines of file context, similar to how Rails does it.

So my problem is, it's unclear to me what an exhaustive set of error properties would look like. The current set is pretty very ad-hoc. Any opinions and insights would be much appreciated!

/Cc @iamstef, @rwjblue, and anyone else interested in plugin error reporting.

[joliss]

Some changes we might want to make, off the top of my head:

• I remember seeing compilers with column ranges (like .columnStart, .columnStop). Perhaps we should support that.
• The .message property that Broccoli uses coincides with the JavaScript Error.prototype.message standard property. This is usually OK, but perhaps it's better to separate the two? Maybe not, let's not duplicate stuff.
• Move everything into a err.broccoliInfo sub-object or so, to avoid polluting the main error namespace?
• Plugins that have multiple input trees (= load paths) may(?) need to communicate which tree an offending file came from. At the moment we have .treeDir (the base directory of the input tree) and .file (the relative path of the offending input file), where path.join(err.treeDir, err.file) is supposed to be the full file path. It's not clear to me whether this is even necessary. It seems a bit cumbersome.

Some of these changes might be breaking - so if we decide to do them, we should bundle them with the new .rebuild API.

[stefanpenner]

that looks good, I think as we are often working on files and we can sometimes have tools provide us with amazing context to where the error happened in the file. We may want to specialize this extra context as another property.

[joliss]

Good point. So perhaps what we see above would be a .context property, and if we don't have it (as would be usually the case) Broccoli can auto-generate it from file/line/column.

[joliss]

I tried to jot down a coherent proposal: https://gist.github.com/joliss/d93b6ca378521e808edd

[joliss]

More notes from discussing with @stefanpenner:

Some build errors are unexpected (bug in plugin, wrong options) and need a stack trace, but some errors tell the user that they did something wrong (compile error, missing file) and don't need a stack trace. We'd like some word to refer to errors that don't need stack traces. Some ideas: humanized, handled, graceful, stackless, build, actionable (like 4xx vs 5xx http), user error.

If we have an error API that supports different kinds of errors, we might want to make different aspects combinable/orthogonal, rather than having disjoint subclasses. E.g. an error might have a location (file/line/col) and/or a link to a deprecation page.

[stefanpenner]

and don't need a stack trace

I suspect in some "verbose" mode, those stacks should be provided (just in case something seriously went wrong). But by default, the are "expected" parts of the workflow, stacktraces are extra noise to parse.