Prepare for decoupling analyzer ASTs from element model.

pkg/analyzer/lib/dart/ast/resolution_map.dart

Index: pkg/analyzer/lib/dart/ast/resolution_map.dart
diff --git a/pkg/analyzer/lib/dart/ast/resolution_map.dart b/pkg/analyzer/lib/dart/ast/resolution_map.dart
new file mode 100644
index 0000000000000000000000000000000000000000..ef2c2bd84e18d4fe4e7f612bbed5b08af001d7e5
--- /dev/null
+++ b/pkg/analyzer/lib/dart/ast/resolution_map.dart
@@ -0,0 +1,318 @@
+// 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.
+
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/dart/element/type.dart';
+
+/**
+ * A collection of methods which may be used to map from nodes in a resolved AST
+ * to elements and types in the element model.
+ *
+ * Clients should not extend, implement or mix-in this class.
+ */
+class ResolutionMap {

[Brian Wilkerson, 2016/12/07 18:26:20]

I was expecting to see an abstract class without an implementation. Was that an
oversight, or is there a reason for leaving this a concrete class?

[Paul Berry, 2016/12/07 18:55:01]

Whoops, this was an oversight.  I was intending to make this abstract and remove
the implementations, and I forgot.

Fixed now.

+  /**
+   * Return the best element available for the function being invoked at [node].
+   * If resolution was able to find a better element based on type propagation,
+   * that element will be returned. Otherwise, the element found using the
+   * result of static analysis will be returned. If resolution has not been
+   * performed, then `null` will be returned.
+   */
+  ExecutableElement bestElementForFunctionExpressionInvocation(
+          FunctionExpressionInvocation node) =>
+      node.bestElement;
+
+  /**
+   * Return the best element available for the identifier [node]. If resolution
+   * was able to find a better element based on type propagation, that element
+   * will be returned. Otherwise, the element found using the result of static
+   * analysis will be returned. If resolution has not been performed, then
+   * `null` will be returned.
+   */
+  Element bestElementForIdentifier(Identifier node) => node.bestElement;
+
+  /**
+   * Return the best element available for the expression [node]. If resolution
+   * was able to find a better element based on type propagation, that element
+   * will be returned. Otherwise, the element found using the result of static
+   * analysis will be returned. If resolution has not been performed, then
+   * `null` will be returned.
+   */
+  MethodElement bestElementForMethodReference(MethodReferenceExpression node) =>
+      node.bestElement;
+
+  /**
+   * Return the best parameter element information available for the expression
+   * [node]. If type propagation was able to find a better parameter element
+   * than static analysis, that type will be returned. Otherwise, the result of
+   * static analysis will be returned.
+   */
+  ParameterElement bestParameterElementForExpression(Expression node) =>
+      node.bestParameterElement;
+
+  /**
+   * Return the best type information available for the expression [node]. If
+   * type propagation was able to find a better type than static analysis, that
+   * type will be returned. Otherwise, the result of static analysis will be
+   * returned. If no type analysis has been performed, then the type 'dynamic'
+   * will be returned.
+   */
+  DartType bestTypeForExpression(Expression node) => node.bestType;
+
+  /**
+   * Return the element annotation representing the annotation [node] in the
+   * element model.
+   */
+  ElementAnnotation elementAnnotationForAnnotation(Annotation node) =>
+      node.elementAnnotation;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  ClassElement elementDeclaredByClassDeclaration(ClassDeclaration node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  ConstructorElement elementDeclaredByConstructorDeclaration(
+          ConstructorDeclaration node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  Element elementDeclaredByDeclaration(Declaration node) => node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  LocalVariableElement elementDeclaredByDeclaredIdentifier(
+          DeclaredIdentifier node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the directive [node], or `null` if the
+   * AST structure has not been resolved or if this directive could not be
+   * resolved.
+   */
+  Element elementDeclaredByDirective(Directive node) => node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  ClassElement elementDeclaredByEnumDeclaration(EnumDeclaration node) =>
+      node.element;
+
+  /**
+   * Return the element representing the parameter [node], or `null` if this
+   * parameter has not been resolved.
+   */
+  ParameterElement elementDeclaredByFormalParameter(FormalParameter node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  ExecutableElement elementDeclaredByFunctionDeclaration(
+          FunctionDeclaration node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the function expression [node], or
+   * `null` if the AST structure has not been resolved.
+   */
+  ExecutableElement elementDeclaredByFunctionExpression(
+          FunctionExpression node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  ExecutableElement elementDeclaredByMethodDeclaration(
+          MethodDeclaration node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the declaration [node], or `null` if
+   * either this node corresponds to a list of declarations or if the AST
+   * structure has not been resolved.
+   */
+  VariableElement elementDeclaredByVariableDeclaration(
+          VariableDeclaration node) =>
+      node.element;
+
+  /**
+   * Return the element associated with the annotation [node], or `null` if the
+   * AST structure has not been resolved or if this annotation could not be
+   * resolved.
+   */
+  Element elementForAnnotation(Annotation node) => node.element;
+
+  /**
+   * Return the element associated with the compilation unit [node], or `null`
+   * if the AST structure has not been resolved.
+   */
+  CompilationUnitElement elementForCompilationUnit(CompilationUnit node) =>

[Brian Wilkerson, 2016/12/07 18:26:20]

I suppose it's a little strange to say that the compilation unit "declares"
anything, and yet it doesn't exactly reference anything either, so I think I'd
lean toward the "DeclaredBy" nomenclature.

[Paul Berry, 2016/12/07 18:55:01]

Done.

+      node.element;
+
+  /**
+   * Return the element representing the parameter being named by the
+   * expression [node], or `null` if the AST structure has not been resolved or
+   * if there is no parameter with the same name as this expression.
+   */
+  ParameterElement elementForNamedExpression(NamedExpression node) =>
+      node.element;
+
+  /**
+   * Return a list containing the elements representing the parameters in the
+   * list [node]. The list will contain `null`s if the parameters in this list
+   * have not been resolved.
+   */
+  List<ParameterElement> parameterElementsForFormalParameterList(
+          FormalParameterList node) =>
+      node.parameterElements;
+
+  /**
+   * Return the element associated with the function being invoked at [node]
+   * based on propagated type information, or `null` if the AST structure has
+   * not been resolved or the function could not be resolved.
+   */
+  ExecutableElement propagatedElementForFunctionExpressionInvocation(
+          FunctionExpressionInvocation node) =>
+      node.propagatedElement;
+
+  /**
+   * Return the element associated with the identifier [node] based on
+   * propagated type information, or `null` if the AST structure has not been
+   * resolved or if this identifier could not be resolved. One example of the
+   * latter case is an identifier that is not defined within the scope in which
+   * it appears.
+   */
+  Element propagatedElementForIdentifier(Identifier node) =>
+      node.propagatedElement;
+
+  /**
+   * Return the element associated with the expression [node] based on
+   * propagated types, or `null` if the AST structure has not been resolved, or
+   * there is no meaningful propagated element to return (e.g. because this is a
+   * non-compound assignment expression, or because the method referred to could
+   * not be resolved).
+   */
+  MethodElement propagatedElementForMethodReference(
+          MethodReferenceExpression node) =>
+      node.propagatedElement;
+
+  /**
+   * If the expression [node] is an argument to an invocation, and the AST
+   * structure has been resolved, and the function being invoked is known based
+   * on propagated type information, and [node] corresponds to one of the
+   * parameters of the function being invoked, then return the parameter element
+   * representing the parameter to which the value of [node] will be
+   * bound. Otherwise, return `null`.
+   */
+  ParameterElement propagatedParameterElementForExpression(Expression node) =>
+      node.propagatedParameterElement;
+
+  /**
+   * Return the propagated type of the expression [node], or `null` if type
+   * propagation has not been performed on the AST structure.
+   */
+  DartType propagatedTypeForExpression(Expression node) => node.propagatedType;
+
+  /**
+   * Return the element associated with the constructor referenced by [node]
+   * based on static type information, or `null` if the AST structure has not
+   * been resolved or if the constructor could not be resolved.
+   */
+  ConstructorElement staticElementForConstructorReference(
+          ConstructorReferenceNode node) =>
+      node.staticElement;
+
+  /**
+   * Return the element associated with the function being invoked at [node]
+   * based on static type information, or `null` if the AST structure has not
+   * been resolved or the function could not be resolved.
+   */
+  ExecutableElement staticElementForFunctionExpressionInvocation(
+          FunctionExpressionInvocation node) =>
+      node.staticElement;
+
+  /**
+   * Return the element associated with the identifier [node] based on static
+   * type information, or `null` if the AST structure has not been resolved or
+   * if this identifier could not be resolved. One example of the latter case is
+   * an identifier that is not defined within the scope in which it appears
+   */
+  Element staticElementForIdentifier(Identifier node) => node.staticElement;
+
+  /**
+   * Return the element associated with the expression [node] based on the
+   * static types, or `null` if the AST structure has not been resolved, or
+   * there is no meaningful static element to return (e.g. because this is a
+   * non-compound assignment expression, or because the method referred to could
+   * not be resolved).
+   */
+  MethodElement staticElementForMethodReference(
+          MethodReferenceExpression node) =>
+      node.staticElement;
+
+  /**
+   * Return the function type of the invocation [node] based on the static type
+   * information, or `null` if the AST structure has not been resolved, or if
+   * the invoke could not be resolved.
+   *
+   * This will usually be a [FunctionType], but it can also be an
+   * [InterfaceType] with a `call` method, `dynamic`, `Function`, or a `@proxy`
+   * interface type that implements `Function`.
+   */
+  DartType staticInvokeTypeForInvocationExpression(InvocationExpression node) =>
+      node.staticInvokeType;
+
+  /**
+   * If the expression [node] is an argument to an invocation, and the AST
+   * structure has been resolved, and the function being invoked is known based
+   * on static type information, and [node] corresponds to one of the parameters
+   * of the function being invoked, then return the parameter element
+   * representing the parameter to which the value of [node] will be
+   * bound. Otherwise, return `null`.
+   */
+  ParameterElement staticParameterElementForExpression(Expression node) =>
+      node.staticParameterElement;
+
+  /**
+   * Return the static type of the expression [node], or `null` if the AST
+   * structure has not been resolved.
+   */
+  DartType staticTypeForExpression(Expression node) => node.staticType;
+
+  /**
+   * Return the type being named by [node], or `null` if the AST structure has
+   * not been resolved.
+   */
+  DartType typeForTypeName(TypeName node) => node.type;
+
+  /**
+   * Return the element associated with the uri of the directive [node], or
+   * `null` if the AST structure has not been resolved or if the URI could not
+   * be resolved. Examples of the latter case include a directive that contains
+   * an invalid URL or a URL that does not exist.
+   */
+  Element uriElementForDirective(UriBasedDirective node) => node.uriElement;
+}