Add error_recovery.yaml: a place to add scenarios we explicitly want to model in

pkg/front_end/error_recovery.yaml

Index: pkg/front_end/error_recovery.yaml
diff --git a/pkg/front_end/error_recovery.yaml b/pkg/front_end/error_recovery.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..c6636e7c3561b61a124add81bac6532a3402c059
--- /dev/null
+++ b/pkg/front_end/error_recovery.yaml
@@ -0,0 +1,134 @@
+# Copyright (c) 2017, 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.
+
+# Each entry in this file corresponds to an error recovery scenario. For each
+# scenario we specify:
+#
+#  1. An explanation of the problem (description).
+#  2. Important recovery notes (recovery): a list of text notes explaining of
+#     how the code is interpreted by the front-end and its clients.
+#  3. An optional set of questions if we don't have the answer at this
+#     moment (questions).
+#  4. An example code that illustrates the problem (example).
+#
+# At this time this is just a documentation file, the goal however is to turn it
+# also into a test suite so every example can be tested automatically.
+#
+# To do so we can start annotating the examples to indicate relevant error
+# locations with comments of the form `/*@error=name*/`, where `name` is a

[scheglov, 2017/08/10 00:13:14]

Do we mark a line, a region, or a single identifier where the error happens?

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Good question: let's do a token or region depending on what we know:
 - a token (in front of the token/identifier where the error would be reported)
 - a region starts the same, but then we add an /*@endError*/ comment where the
error region ends.

Added to the doc here.

+# message name from `messages.yaml` that corresponds to the error (if known). If
+# the compiler doesn't yet have a specific error message for the error, use
+# `/*@error=?*/`.
+
+NameConflictDuplicateField:
+  description: "A field was declared twice."
+  recovery:
+    - "both fields can be seen in the generated kernel output."
+    - "code completion works inside initializers of either field."

[scheglov, 2017/08/10 00:13:14]

"inside initializers" seems limiting.
Why not in the type too?

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Done.

+    - "any errors from the usage of the field should be lower priority than this error."
+  questions: >-
+    How do we interpret accesses to the field value? Do we pick one of the
+    implementations? Treat it's type as Object? try to find an LUB for the type?

[scheglov, 2017/08/10 00:13:14]

its
Try

Feel free to ignore this, if the goal is just to provide examples of errors.

Access should pick the first field, with its actual type. There is no much value
anyway - the program already has errors, but we need some simple algorithm that
users will easily understand. "The first one" is easy ;-)

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Sounds good. I adopted your suggestion.

+  example: >-
+    List bar = [1, 2];
+    StringBuffer foo = new StringBuffer();
+    class A {
+      /*@error=DuplicatedName*/ int field = bar.length;

[scheglov, 2017/08/10 00:13:14]

I think that the name of the field should be annotated with the error.

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Done.

+      /*@error=DuplicatedName*/ String field = '$foo';

[danrubel, 2017/08/10 16:32:33]

From an test automation standpoint, it would be really nice if the example
indicated the exact range of characters that should be highlighted by the error.
I believe that some downstream tools depend upon the error highlight range.

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Good suggestion. Done. Added /*@errorEnd*/ for this.

+    }
+
+NameConflictDuplicateMethod:
+  description: "A method was declared twice."
+  recovery:
+    - "both methods can be seen in the generated kernel output."
+    - "code completion works within both methods."
+  questions: >-
+    How do we interpret accesses to the methods? Do we pick one of the
+    implementations? Treat parameter and return types as Object? try to
+    find an LUB for the function type?

[scheglov, 2017/08/10 00:13:14]

Same here - outside of the class only the first is accessible.

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Done.

+
+  example: >-
+    List bar = [1, 2];
+    class A {
+      /*@error=DuplicatedName*/
+      int m() => bar.length;

[scheglov, 2017/08/10 00:13:14]

Same here - the problem is with the name, so the name should be annotated.

[Siggi Cherem (dart-lang), 2017/08/10 18:52:34]

Done.

+
+      /*@error=DuplicatedName*/
+      int m(StringBuffer foo) => '$foo';
+    }
+
+NameConflictInconsitentMemberKind:
+  description: "A method and a field have the same name."
+  recovery:
+    - "both can be seen in the generated output."
+  questions: >-
+    What do we do with accesses to this name? Pick one of the implementations?
+    Which one? Treat it as if it doesn't exist? Pick based on how it is used
+    (e.g. if it is used as a call, pick the method)?
+
+  example: >-
+    List bar = [1, 2];
+    class A {
+      /*@error=DuplicatedName*/
+      int m() => bar.length;
+
+      /*@error=DuplicatedName*/
+      int m(StringBuffer foo) => '$foo';
+    }
+
+ImportIsOutOfOrder:    
+  description: "An import was written below a definition."
+  recovery:
+    - "treat it as if the import was on top"
+    - "lower priority on errors that cascade from this"
+  example: >-
+    class A extends /*@error=SupertypeIsIllegal*/ B {}
+    /*@error=?*/
+    import 'b.dart'; // b.dart defines B
+
+CallAMissingConstructor:
+  description: "A named constructor has a typo in the name."
+  recovery:
+    - "keep the expression where it occurs."
+    - "treat the type of the expression as if a valid constructor was used."
+  example: >-
+    class C {
+      bar() => null;
+    }
+    main() {
+      var x = new C./*error=MethodNotFound*/foo();
+      x.bar(); // no errors here, `x` has inferred type `C`.
+    }
+
+TreatAbstractFunctionsAsEmpty:
+  description: "A function in a non-abstract class is missing a body."
+  recovery: "Treat it as if it was empty."
+  example: >-
+    class A {
+      /*@error=ExpectedBody*/
+      foo();
+    }
+
+IgnoreEmptyOptionalArgs:
+  description: "A function declares optional argument, but the list is empty."
+  recovery: "Treat it as if it wasn't there."
+  example: >-
+    m(a, b, []){}
+
+IgnoreEmptyOptionalArgs:
+  description: "A function declares both positional and named arguments."
+  questions: "Treat it as if only named arguments are there?"
+  example: >-
+    m(a, b, [c], {d}){}
+
+# TODO(sigmund): add details to the list below
+
+NameConflictDuplicateTopLevelField:
+  description: "A top-level field was declared twice."
+
+NameConflictDuplicateTopLevelMethod:
+  description: "A top-level method was declared twice."
+
+NameConflictDuplicateTopLevelDeclaration:
+  description: "Two top-level declarations use the same name."