Check for @alwaysThrows when evaluating for dead code.

The meta package version 1.1.0 includes a new `alwaysThrows`, which developers
can use to annotate methods that always throw. This helps to avoid erroneous
DEAD_CODE warnings from analyzer.

Bug: #31384
Change-Id: I70e2469b4f3a0d2c87064851160b268ea2259807
Reviewed-on: https://dart-review.googlesource.com/26563
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>

Author: srawlins

pkg/analyzer/lib/dart/element/element.dart

@@ -608,6 +608,12 @@ abstract class Element implements AnalysisTarget, ResolutionTarget {
    */
   int get id;
 
+  /**
+   * Return `true` if this element has an annotation of the form
+   * '@alwaysThrows'.
+   */
+  bool get isAlwaysThrows;
+
   /**
    * Return `true` if this element has an annotation of the form '@deprecated'
    * or '@Deprecated('..')'.
@@ -808,6 +814,12 @@ abstract class ElementAnnotation
    */
   Element get element;
 
+  /**
+   * Return `true` if this annotation marks the associated function as always
+   * throwing.
+   */
+  bool get isAlwaysThrows;
+
   /**
    * Return `true` if this annotation marks the associated element as being
    * deprecated.

pkg/analyzer/lib/src/dart/element/element.dart

@@ -2789,6 +2789,12 @@ class DynamicElementImpl extends ElementImpl implements TypeDefiningElement {
  * A concrete implementation of an [ElementAnnotation].
  */
 class ElementAnnotationImpl implements ElementAnnotation {
+  /**
+   * The name of the top-level variable used to mark that a function always
+   * throws, for dead code purposes.
+   */
+  static String _ALWAYS_THROWS_VARIABLE_NAME = "alwaysThrows";
+
   /**
    * The name of the top-level variable used to mark a method parameter as
    * covariant.
@@ -2904,6 +2910,12 @@ class ElementAnnotationImpl implements ElementAnnotation {
   @override
   AnalysisContext get context => compilationUnit.library.context;
 
+  @override
+  bool get isAlwaysThrows =>
+      element is PropertyAccessorElement &&
+      element.name == _ALWAYS_THROWS_VARIABLE_NAME &&
+      element.library?.name == _META_LIB_NAME;
+
   /**
    * Return `true` if this annotation marks the associated parameter as being
    * covariant, meaning it is allowed to have a narrower type in an override.
@@ -3156,6 +3168,10 @@ abstract class ElementImpl implements Element {
    */
   String get identifier => name;
 
+  @override
+  bool get isAlwaysThrows =>
+      metadata.any((ElementAnnotation annotation) => annotation.isAlwaysThrows);
+
   @override
   bool get isDeprecated {
     for (ElementAnnotation annotation in metadata) {
@@ -7415,6 +7431,9 @@ class MultiplyDefinedElementImpl implements MultiplyDefinedElement {
   @override
   Element get enclosingElement => null;
 
+  @override
+  bool get isAlwaysThrows => false;
+
   @override
   bool get isDeprecated => false;
 

pkg/analyzer/lib/src/dart/element/handle.dart

@@ -347,6 +347,9 @@ abstract class ElementHandle implements Element {
   @override
   int get hashCode => _location.hashCode;
 
+  @override
+  bool get isAlwaysThrows => actualElement.isAlwaysThrows;
+
   @override
   bool get isDeprecated => actualElement.isDeprecated;
 

pkg/analyzer/lib/src/dart/element/member.dart

@@ -393,6 +393,9 @@ abstract class Member implements Element {
   @override
   int get id => _baseElement.id;
 
+  @override
+  bool get isAlwaysThrows => _baseElement.isAlwaysThrows;
+
   @override
   bool get isDeprecated => _baseElement.isDeprecated;
 

pkg/analyzer/lib/src/generated/resolver.dart

@@ -633,7 +633,6 @@ class BestPracticesVerifier extends RecursiveAstVisitor<Object> {
    *
    * @param element some element to check for deprecated use of
    * @param node the node use for the location of the error
-   * @return `true` if and only if a hint code is generated on the passed node
    * See [HintCode.DEPRECATED_MEMBER_USE].
    */
   void _checkForDeprecatedMemberUse(Element element, AstNode node) {
@@ -3269,6 +3268,10 @@ class ExitDetector extends GeneralizingAstVisitor<bool> {
         return false;
       }
     }
+    Element element = node.methodName.staticElement;
+    if (element != null && element.isAlwaysThrows) {
+      return true;
+    }
     return _nodeExits(node.argumentList);
   }
 

pkg/analyzer/test/generated/hint_code_test.dart

@@ -31,6 +31,7 @@ class HintCodeTest extends ResolverTestCase {
         r'''
 library meta;
 
+const _AlwaysThrows alwaysThrows = const _AlwaysThrows();
 const _Factory factory = const _Factory();
 const Immutable immutable = const Immutable();
 const _Literal literal = const _Literal();
@@ -46,6 +47,9 @@ class Immutable {
   final String reason;
   const Immutable([this.reason]);
 }
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
 class _Factory {
   const _Factory();
 }
@@ -719,6 +723,68 @@ f() {
     verify([source]);
   }
 
+  test_deadCode_statementAfterAlwaysThrowsFunction() async {
+    Source source = addSource(r'''
+import 'package:meta/meta.dart';
+
+@alwaysThrows
+void a() {
+  throw 'msg';
+}
+
+f() {
+  var one = 1;
+  a();
+  var two = 2;
+}''');
+    await computeAnalysisResult(source);
+    assertErrors(source, [HintCode.DEAD_CODE]);
+    verify([source]);
+  }
+
+  test_deadCode_statementAfterAlwaysThrowsMethod() async {
+    Source source = addSource(r'''
+import 'package:meta/meta.dart';
+
+class C {
+  @alwaysThrows
+  void a() {
+    throw 'msg';
+  }
+}
+
+f() {
+  var one = 1;
+  new C().a();
+  var two = 2;
+}''');
+    await computeAnalysisResult(source);
+    assertErrors(source, [HintCode.DEAD_CODE]);
+    verify([source]);
+  }
+
+  @failingTest
+  test_deadCode_statementAfterAlwaysThrowsGetter() async {
+    Source source = addSource(r'''
+import 'package:meta/meta.dart';
+
+class C {
+  @alwaysThrows
+  int get a {
+    throw 'msg';
+  }
+}
+
+f() {
+  var one = 1;
+  new C().a;
+  var two = 2;
+}''');
+    await computeAnalysisResult(source);
+    assertErrors(source, [HintCode.DEAD_CODE]);
+    verify([source]);
+  }
+
   test_deprecatedAnnotationUse_assignment() async {
     Source source = addSource(r'''
 class A {

pkg/analyzer/test/generated/non_hint_code_test.dart

@@ -20,6 +20,24 @@ main() {
 
 @reflectiveTest
 class NonHintCodeTest extends ResolverTestCase {
+  @override
+  void reset() {
+    super.resetWith(packages: [
+      [
+        'meta',
+        r'''
+library meta;
+
+const _AlwaysThrows alwaysThrows = const _AlwaysThrows();
+
+class _AlwaysThrows {
+  const _AlwaysThrows();
+}
+'''
+      ]
+    ]);
+  }
+
   test_async_future_object_without_return() async {
     Source source = addSource('''
 import 'dart:async';
@@ -474,6 +492,23 @@ abstract class A {
     verify([source]);
   }
 
+  test_missingReturn_alwaysThrows() async {
+    Source source = addSource(r'''
+import 'package:meta/meta.dart';
+
+@alwaysThrows
+void a() {
+  throw 'msg';
+}
+
+int f() {
+  a();
+}''');
+    await computeAnalysisResult(source);
+    assertNoErrors(source);
+    verify([source]);
+  }
+
   test_nullAwareInCondition_for_noCondition() async {
     Source source = addSource(r'''
 m(x) {