Migration: record the "origin" of each edge in the NullabilityEdge object.

This paves the way for being able to explain to the user exactly why
the migration tool made any given nullability decision.

Change-Id: I553e4881fdb37b238a066fcfba7c21ae919d7d6e
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/106381
Reviewed-by: Brian Wilkerson <[email protected]>

Author: stereotype441

pkg/nnbd_migration/lib/src/edge_origin.dart

@@ -0,0 +1,101 @@
+// Copyright (c) 2019, 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.
+
+import 'package:analyzer/src/generated/source.dart';
+
+/// Edge origin resulting from the use of a type that is always nullable.
+///
+/// For example, in the following code snippet:
+///   void f(dynamic x) {}
+///
+/// this class is used for the edge connecting `always` to the type of f's `x`
+/// parameter, due to the fact that the `dynamic` type is always considered
+/// nullable.
+class AlwaysNullableTypeOrigin extends EdgeOriginWithLocation {
+  AlwaysNullableTypeOrigin(Source source, int offset) : super(source, offset);
+}
+
+/// Common interface for classes providing information about how an edge came
+/// to be; that is, what was found in the source code that led the migration
+/// tool to create the edge.
+abstract class EdgeOrigin {}
+
+/// Common base class for edge origins that are associated with a single
+/// location in the source code.
+abstract class EdgeOriginWithLocation extends EdgeOrigin {
+  /// The source file containing the code construct that led to the edge.
+  final Source source;
+
+  /// The offset within the source file of the code construct that led to the
+  /// edge.
+  final int offset;
+
+  EdgeOriginWithLocation(this.source, this.offset);
+}
+
+/// Edge origin resulting from a class that is instantiated to bounds.
+///
+/// For example, in the following code snippet:
+///   class C<T extends Object> {}
+///   C x;
+///
+/// this class is used for the edge connecting the type of x's type parameter
+/// with the type bound in the declaration of C.
+class InstantiateToBoundsOrigin extends EdgeOriginWithLocation {
+  InstantiateToBoundsOrigin(Source source, int offset) : super(source, offset);
+}
+
+/// Edge origin resulting from a call site that does not supply a named
+/// parameter.
+///
+/// For example, in the following code snippet:
+///   void f({int i}) {}
+///   main() {
+///     f();
+///   }
+///
+/// this class is used for the edge connecting `always` to the type of f's `i`
+/// parameter, due to the fact that the call to `f` implicitly passes a null
+/// value for `i`.
+class NamedParameterNotSuppliedOrigin extends EdgeOriginWithLocation {
+  NamedParameterNotSuppliedOrigin(Source source, int offset)
+      : super(source, offset);
+}
+
+/// Edge origin resulting from the presence of a non-null assertion.
+///
+/// For example, in the following code snippet:
+///   void f(int i) {
+///     assert(i != null);
+///   }
+///
+/// this class is used for the edge connecting the type of f's `i` parameter to
+/// `never`, due to the assert statement proclaiming that `i` is not `null`.
+class NonNullAssertionOrigin extends EdgeOriginWithLocation {
+  NonNullAssertionOrigin(Source source, int offset) : super(source, offset);
+}
+
+/// Edge origin resulting from the presence of an explicit nullability hint
+/// comment.
+///
+/// For example, in the following code snippet:
+///   void f(int/*?*/ i) {}
+///
+/// this class is used for the edge connecting `always` to the type of f's `i`
+/// parameter, due to the presence of the `/*?*/` comment.
+class NullabilityCommentOrigin extends EdgeOriginWithLocation {
+  NullabilityCommentOrigin(Source source, int offset) : super(source, offset);
+}
+
+/// Edge origin resulting from the presence of an optional formal parameter.
+///
+/// For example, in the following code snippet:
+///   void f({int i}) {}
+///
+/// this class is used for the edge connecting `always` to the type of f's `i`
+/// parameter, due to the fact that `i` is optional and has no initializer.
+class OptionalFormalParameterOrigin extends EdgeOriginWithLocation {
+  OptionalFormalParameterOrigin(Source source, int offset)
+      : super(source, offset);
+}

pkg/nnbd_migration/lib/src/expression_checks.dart

@@ -3,6 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analyzer_plugin/protocol/protocol_common.dart';
+import 'package:nnbd_migration/src/edge_origin.dart';
 import 'package:nnbd_migration/src/nullability_node.dart';
 import 'package:nnbd_migration/src/potential_modification.dart';
 
@@ -13,7 +14,7 @@ import 'package:nnbd_migration/src/potential_modification.dart';
 /// TODO(paulberry): the only check we support now is [nullCheck], which checks
 /// that the expression is not null.  We need to add other checks, e.g. to check
 /// that a List<int?> is actually a List<int>.
-class ExpressionChecks extends PotentialModification {
+class ExpressionChecks extends PotentialModification implements EdgeOrigin {
   /// Source offset where a trailing `!` might need to be inserted.
   final int offset;
 

pkg/nnbd_migration/lib/src/graph_builder.dart

@@ -19,6 +19,8 @@ import 'package:nnbd_migration/src/node_builder.dart';
 import 'package:nnbd_migration/src/nullability_node.dart';
 import 'package:nnbd_migration/src/variables.dart';
 
+import 'edge_origin.dart';
+
 /// Visitor that builds nullability graph edges by examining code to be
 /// migrated.
 ///
@@ -154,8 +156,9 @@ class GraphBuilder extends GeneralizingAstVisitor<DecoratedType> {
     if (identical(_conditionInfo?.condition, node.condition)) {
       if (!_inConditionalControlFlow &&
           _conditionInfo.trueDemonstratesNonNullIntent != null) {
-        _conditionInfo.trueDemonstratesNonNullIntent
-            ?.recordNonNullIntent(_guards, _graph);
+        _graph.connect(_conditionInfo.trueDemonstratesNonNullIntent,
+            _graph.never, NonNullAssertionOrigin(_source, node.offset),
+            hard: true);
       }
     }
     node.message?.accept(this);
@@ -271,9 +274,11 @@ class GraphBuilder extends GeneralizingAstVisitor<DecoratedType> {
         // Nothing to do; the implicit default value of `null` will never be
         // reached.
       } else {
-        NullabilityNode.recordAssignment(_graph.always,
-            getOrComputeElementType(node.declaredElement).node, _guards, _graph,
-            hard: false);
+        _graph.connect(
+            _graph.always,
+            getOrComputeElementType(node.declaredElement).node,
+            OptionalFormalParameterOrigin(_source, node.offset),
+            guards: _guards);
       }
     } else {
       _handleAssignment(
@@ -607,11 +612,13 @@ $stackTrace''');
           throw new StateError('No type annotation for type name '
               '${typeName.toSource()}, offset=${typeName.offset}');
         }
+        var origin = InstantiateToBoundsOrigin(_source, typeName.offset);
         for (int i = 0; i < instantiatedType.typeArguments.length; i++) {
           _unionDecoratedTypes(
               instantiatedType.typeArguments[i],
               _variables.decoratedElementType(element.typeParameters[i],
-                  create: true));
+                  create: true),
+              origin);
         }
       } else {
         for (int i = 0; i < typeArguments.length; i++) {
@@ -648,9 +655,8 @@ $stackTrace''');
   void _checkAssignment(DecoratedType destinationType, DecoratedType sourceType,
       ExpressionChecks expressionChecks,
       {@required bool hard}) {
-    NullabilityNode.recordAssignment(
-        sourceType.node, destinationType.node, _guards, _graph,
-        hard: hard);
+    _graph.connect(sourceType.node, destinationType.node, expressionChecks,
+        guards: _guards, hard: hard);
     // TODO(paulberry): generalize this.
     if ((_isSimple(sourceType) || destinationType.type.isObject) &&
         _isSimple(destinationType)) {
@@ -732,7 +738,8 @@ $stackTrace''');
     // Any parameters not supplied must be optional.
     for (var entry in calleeType.namedParameters.entries) {
       if (suppliedNamedParameters.contains(entry.key)) continue;
-      entry.value.node.recordNamedParameterNotSupplied(_guards, _graph);
+      entry.value.node.recordNamedParameterNotSupplied(_guards, _graph,
+          NamedParameterNotSuppliedOrigin(_source, argumentList.offset));
     }
   }
 
@@ -812,8 +819,9 @@ $stackTrace''');
     return false;
   }
 
-  void _unionDecoratedTypes(DecoratedType x, DecoratedType y) {
-    _graph.union(x.node, y.node);
+  void _unionDecoratedTypes(
+      DecoratedType x, DecoratedType y, EdgeOrigin origin) {
+    _graph.union(x.node, y.node, origin);
     if (x.typeArguments.isNotEmpty ||
         y.typeArguments.isNotEmpty ||
         x.returnType != null ||

pkg/nnbd_migration/lib/src/node_builder.dart

@@ -16,6 +16,8 @@ import 'package:nnbd_migration/src/decorated_type.dart';
 import 'package:nnbd_migration/src/expression_checks.dart';
 import 'package:nnbd_migration/src/nullability_node.dart';
 
+import 'edge_origin.dart';
+
 /// Visitor that builds nullability nodes based on visiting code to be migrated.
 ///
 /// The return type of each `visit...` method is a [DecoratedType] indicating
@@ -58,7 +60,7 @@ class NodeBuilder extends GeneralizingAstVisitor<DecoratedType> {
         ? new DecoratedType(
             DynamicTypeImpl.instance,
             NullabilityNode.forInferredDynamicType(
-                _graph, enclosingNode.offset))
+                _graph, _source, enclosingNode.offset))
         : type.accept(this);
   }
 
@@ -167,7 +169,8 @@ $stackTrace''');
     var type = node.type;
     if (type.isVoid || type.isDynamic) {
       var nullabilityNode = NullabilityNode.forTypeAnnotation(node.end);
-      _graph.connect(_graph.always, nullabilityNode);
+      _graph.connect(_graph.always, nullabilityNode,
+          AlwaysNullableTypeOrigin(_source, node.offset));
       var decoratedType =
           DecoratedTypeAnnotation(type, nullabilityNode, node.offset);
       _variables.recordDecoratedTypeAnnotation(_source, node, decoratedType,
@@ -218,12 +221,16 @@ $stackTrace''');
         positionalParameters: positionalParameters,
         namedParameters: namedParameters);
     _variables.recordDecoratedTypeAnnotation(_source, node, decoratedType);
-    switch (_classifyComment(node.endToken.next.precedingComments)) {
+    var commentToken = node.endToken.next.precedingComments;
+    switch (_classifyComment(commentToken)) {
       case _NullabilityComment.bang:
-        _graph.connect(decoratedType.node, _graph.never, hard: true);
+        _graph.connect(decoratedType.node, _graph.never,
+            NullabilityCommentOrigin(_source, commentToken.offset),
+            hard: true);
         break;
       case _NullabilityComment.question:
-        _graph.connect(_graph.always, decoratedType.node);
+        _graph.connect(_graph.always, decoratedType.node,
+            NullabilityCommentOrigin(_source, commentToken.offset));
         break;
       case _NullabilityComment.none:
         break;
@@ -238,8 +245,10 @@ $stackTrace''');
   DecoratedType visitTypeParameter(TypeParameter node) {
     var element = node.declaredElement;
     var decoratedBound = node.bound?.accept(this) ??
-        DecoratedType(element.bound ?? _typeProvider.objectType,
-            NullabilityNode.forInferredDynamicType(_graph, node.offset));
+        DecoratedType(
+            element.bound ?? _typeProvider.objectType,
+            NullabilityNode.forInferredDynamicType(
+                _graph, _source, node.offset));
     _variables.recordDecoratedElementType(element, decoratedBound);
     return null;
   }