Flow analysis: clarifying comments for "why not promoted" logic.

These comments address code review comments from
https://dart-review.googlesource.com/c/sdk/+/181741.

Bug: #44898
Change-Id: I93d35600048318c20e6c41b290b6736d0086a574
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/184980
Reviewed-by: Johnni Winther <[email protected]>
Commit-Queue: Paul Berry <[email protected]>

Author: stereotype441

pkg/_fe_analyzer_shared/lib/src/flow_analysis/flow_analysis.dart

@@ -4989,6 +4989,31 @@ class _PropertyGetReference<Variable extends Object, Type extends Object>
 
   @override
   Type getDeclaredType(TypeOperations<Variable, Type> typeOperations) {
+    // Since we don't actually support property promotion, we just compute what
+    // promotions would have occurred if we *did* support it (for the purpose of
+    // issuing more useful error messages), we have some leeway in how we define
+    // the "declared type" of a property.  It's tempting to define it as the
+    // return type of the referenced getter, but this is problematic for two
+    // reasons: (1) we don't have the necessary hooks to ask the client what
+    // this type is, and (2) the referenced getter can become more specific due
+    // to the presence of other promotions, breaking the invariant that promoted
+    // types are expected to be subtypes of the declared type, e.g.:
+    //
+    //   abstract class C { num? get x; }
+    //   abstract class D extends C { int? get x; }
+    //   f(C c) {
+    //     if (c.x != null) { // "promotes" c.x to `num`
+    //       if (c is D) { // promotes c to D, so c.x now refers to an `int?`
+    //         // Invariant broken: `num` is not a subtype of `int?`
+    //       }
+    //     }
+    //   }
+    //
+    // Rather than break the invariant (which could lead to unexpected behaviors
+    // of flow analysis, including possibly crashes), it seems wiser to simply
+    // define the "declared type" for properties to be the top type; in practice
+    // this still produces useful results, and it doesn't violate soundness
+    // because we don't actually promote property references.
     return typeOperations.topType;
   }
 

pkg/front_end/lib/src/fasta/type_inference/type_inferrer.dart

@@ -328,6 +328,13 @@ class TypeInferrerImpl implements TypeInferrer {
           dataForTesting.flowAnalysisResult.nonPromotionReasons[expression] =
               nonPromotionReasonText;
         }
+        // Note: this will always pick the first viable reason (only).  I
+        // (paulberry) believe this is the one that will be the most relevant,
+        // but I need to do more testing to validate that.  I can't do that
+        // additional testing yet because at the moment we only handle failed
+        // promotions to non-nullable.
+        // TODO(paulberry): do more testing and then expand on the comment
+        // above.
         context = [message];
         break;
       }

pkg/front_end/test/spell_checking_list_code.txt

@@ -101,6 +101,7 @@ bb
 became
 beforehand
 behave
+believe
 bellow
 belonging
 beloning
@@ -631,6 +632,7 @@ layout
 lc
 ld
 leafp
+leeway
 len
 lets
 letting
@@ -1175,6 +1177,7 @@ tells
 temp
 temporaries
 temps
+tempting
 term
 termcap
 terminator
@@ -1323,6 +1326,7 @@ vector
 vegorov
 verbosity
 versa
+viable
 vice
 video
 violated
@@ -1355,6 +1359,7 @@ widgets
 wiki
 wikipedia
 wind
+wiser
 with1
 wn
 worthwhile