Improve compile-time error handling.

pkg/front_end/lib/src/fasta/errors.dart

 // Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 library fasta.errors;
 
 import 'dart:async' show
     Future;
 
 import 'dart:convert' show
@@ skipping 16 matching lines @@
 
 /// Tracks if there has been a crash reported through [reportCrash]. Should be
 /// reset between each compilation by calling [resetCrashReporting].
 bool hasCrashed = false;
 
 /// Tracks the first source URI that has been read and is used as a fall-back
 /// for [reportCrash]. Should be reset between each compilation by calling
 /// [resetCrashReporting].
 Uri firstSourceUri;
 
+/// Used to report an internal error.
+///
+/// Internal errors should be avoided as best as possible, but are preferred
+/// over assertion failures. Favor error messages that starts with "Internal
+/// error: " and a short description that may help a developer debug the issue.
+/// This method should be called instead of using `throw`, as this allows us to
+/// ensure that there are no throws anywhere in the codebase.
 dynamic internalError(Object error) {
   throw error;
 }
 
+/// Used to report an error in input.
+///
+/// Avoid using this for reporting compile-time errors, instead use
+/// `LibraryBuilder.addCompileTimeError` for those.
+///
+/// An input error is any error that isn't an internal error. We use the term
+/// "input error" in favor of "user error". This way, if an input error isn't
+/// handled correctly, the user will never see a stack trace that says "user
+/// error".
 dynamic inputError(Uri uri, int charOffset, Object error) {

[Siggi Cherem (dart-lang), 2017/02/10 23:12:32]

As error-recovery matures is the idea that if we have an input that produces an
input error, we'll work to make it into a recoverable compile-time error and get
rid of the input error?

If so, maybe call this unexpectedInputError to highlight that this should be
used only as a marker that something unexpected happened?

[ahe, 2017/02/13 14:41:02]

There are times when this is the correct method to use, for example, when
reporting an error on a command line option.

I do like the name "unexpectedInput" as this completely removes the word "error"
from the stack trace.

I'll rename this in a future CL.

   throw new InputError(uri, charOffset, error);
 }
 
 class InputError {
   final Uri uri;
 
   final int charOffset;
 
   final Object error;
 
@@ skipping 95 matching lines @@
   return new Future.error(error, trace);
 }
 
 String safeToString(Object object) {
   try {
     return "$object";
   } catch (e) {
     return "Error when converting ${object.runtimeType} to string.";
   }
 }