analyzer: implement invalid_await_not_required_annotation warning

Work towards #46218

Change-Id: I41391cc317dec625f0b34afbf5f5a3402d8b08b4
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/424261
Reviewed-by: Konstantin Shcheglov <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/analysis_server/lib/src/services/correction/error_fix_status.yaml

@@ -3542,6 +3542,8 @@ WarningCode.INFERENCE_FAILURE_ON_UNTYPED_PARAMETER:
   status: noFix
 WarningCode.INVALID_ANNOTATION_TARGET:
   status: hasFix
+WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION:
+  status: needsFix
 WarningCode.INVALID_EXPORT_OF_INTERNAL_ELEMENT:
   status: needsFix
   notes: |-

pkg/analyzer/lib/src/error/annotation_verifier.dart

@@ -44,8 +44,7 @@ class AnnotationVerifier {
     }
     var parent = node.parent;
     if (element.isAwaitNotRequired) {
-      // TODO(srawlins): Check that functions return Future and fields and
-      // getters have a static type of Future.
+      _checkAwaitNotRequired(node);
     } else if (element.isFactory) {
       _checkFactory(node);
     } else if (element.isInternal) {
@@ -72,6 +71,48 @@ class AnnotationVerifier {
     _checkKinds(node, parent, element);
   }
 
+  void _checkAwaitNotRequired(Annotation node) {
+    void checkType(DartType? type, {AstNode? errorNode}) {
+      if (type == null || type.isDartAsyncFuture || type.isDartAsyncFutureOr) {
+        return;
+      }
+
+      var element = type.element3;
+      if (element is InterfaceElement2 &&
+          element.allSupertypes.any((t) => t.isDartAsyncFuture)) {
+        return;
+      }
+
+      _errorReporter.atNode(
+        errorNode ?? node.name,
+        WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION,
+      );
+    }
+
+    var parent = node.parent;
+    if (parent
+        case MethodDeclaration(:var declaredFragment) ||
+            FunctionDeclaration(:var declaredFragment)) {
+      var type = declaredFragment?.element.type;
+      if (type is FunctionType) {
+        checkType(type.returnType);
+      }
+    } else if (parent case FieldDeclaration(:var fields)) {
+      for (var field in fields.variables) {
+        checkType(field.declaredFieldElement.type, errorNode: field);
+      }
+    } else if (parent case TopLevelVariableDeclaration(:var variables)) {
+      for (var variable in variables.variables) {
+        checkType(
+          variable.declaredTopLevelVariableElement.type,
+          errorNode: variable,
+        );
+      }
+    } else {
+      // Warning reported by `_checkKinds`.
+    }
+  }
+
   /// Reports a warning at [node] if its parent is not a valid target for a
   /// `@factory` annotation.
   void _checkFactory(Annotation node) {

pkg/analyzer/lib/src/error/codes.g.dart

@@ -6640,6 +6640,13 @@ class WarningCode extends ErrorCode {
     hasPublishedDocs: true,
   );
 
+  ///  No parameters.
+  static const WarningCode INVALID_AWAIT_NOT_REQUIRED_ANNOTATION = WarningCode(
+    'INVALID_AWAIT_NOT_REQUIRED_ANNOTATION',
+    "The annotation 'awaitNotRequired' can only be applied to a "
+        "Future-returning function, or a Future-typed field.",
+  );
+
   ///  Parameters:
   ///  0: the name of the element
   static const WarningCode INVALID_EXPORT_OF_INTERNAL_ELEMENT = WarningCode(

pkg/analyzer/lib/src/error/error_code_values.g.dart

@@ -1017,6 +1017,7 @@ const List<ErrorCode> errorCodeValues = [
   WarningCode.INFERENCE_FAILURE_ON_UNINITIALIZED_VARIABLE,
   WarningCode.INFERENCE_FAILURE_ON_UNTYPED_PARAMETER,
   WarningCode.INVALID_ANNOTATION_TARGET,
+  WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION,
   WarningCode.INVALID_EXPORT_OF_INTERNAL_ELEMENT,
   WarningCode.INVALID_EXPORT_OF_INTERNAL_ELEMENT_INDIRECTLY,
   WarningCode.INVALID_FACTORY_METHOD_DECL,

pkg/analyzer/messages.yaml

@@ -24156,6 +24156,36 @@ WarningCode:
       #### Common fixes
 
       Remove the annotation from the declaration.
+  INVALID_AWAIT_NOT_REQUIRED_ANNOTATION:
+    problemMessage: "The annotation 'awaitNotRequired' can only be applied to a Future-returning function, or a Future-typed field."
+    hasPublishedDocs: false
+    comment: No parameters.
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when anything other than a
+      `Future`-returning function or a `Future`-typed field or top-level
+      variable is annotated with [`awaitNotRequired`][meta-awaitNotRequired].
+
+      #### Example
+
+      The following code produces this diagnostic because the annotation is on a
+      `void`-returning function:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @[!awaitNotRequired!]
+      void f() {}
+      ```
+
+      #### Common fixes
+
+      Remove the annotation:
+
+      ```dart
+      void f() {}
+      ```
   INVALID_EXPORT_OF_INTERNAL_ELEMENT:
     problemMessage: "The member '{0}' can't be exported as a part of a package's public API."
     correctionMessage: "Try using a hide clause to hide '{0}'."

pkg/analyzer/test/src/diagnostics/invalid_await_not_required_annotation_test.dart

@@ -0,0 +1,187 @@
+// Copyright (c) 2025, 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/error/codes.g.dart';
+import 'package:test_reflective_loader/test_reflective_loader.dart';
+
+import '../dart/resolution/context_collection_resolution.dart';
+
+void main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(InvalidAwaitNotRequiredAnnotationTest);
+  });
+}
+
+@reflectiveTest
+class InvalidAwaitNotRequiredAnnotationTest extends PubPackageResolutionTest {
+  @override
+  void setUp() {
+    super.setUp();
+    writeTestPackageConfigWithMeta();
+  }
+
+  test_invalid_field_inferredReturnType() async {
+    await assertErrorsInCode(
+      '''
+import 'package:meta/meta.dart';
+class C {
+  @awaitNotRequired
+  var x = 0;
+}
+''',
+      [error(WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION, 69, 5)],
+    );
+  }
+
+  test_invalid_field_intReturnType() async {
+    await assertErrorsInCode(
+      '''
+import 'package:meta/meta.dart';
+class C {
+  @awaitNotRequired
+  int x = 0;
+}
+''',
+      [error(WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION, 69, 5)],
+    );
+  }
+
+  test_invalid_function_voidReturnType() async {
+    await assertErrorsInCode(
+      '''
+import 'package:meta/meta.dart';
+@awaitNotRequired
+void f() {}
+''',
+      [error(WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION, 34, 16)],
+    );
+  }
+
+  test_invalid_method_voidReturnType() async {
+    await assertErrorsInCode(
+      '''
+import 'package:meta/meta.dart';
+class C {
+  @awaitNotRequired
+  void f() {}
+}
+''',
+      [error(WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION, 46, 16)],
+    );
+  }
+
+  test_invalid_method_voidReturnType_inheritedReturnType() async {
+    await assertErrorsInCode(
+      '''
+import 'package:meta/meta.dart';
+class C {
+  void f() {}
+}
+class D extends C {
+  @awaitNotRequired
+  @override
+  f() {}
+}
+''',
+      [error(WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION, 82, 16)],
+    );
+  }
+
+  test_invalid_topLevelVariable_intReturnType() async {
+    await assertErrorsInCode(
+      '''
+import 'package:meta/meta.dart';
+@awaitNotRequired
+int x = 0;
+''',
+      [error(WarningCode.INVALID_AWAIT_NOT_REQUIRED_ANNOTATION, 55, 5)],
+    );
+  }
+
+  test_valid_field_futureReturnType() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+class C {
+  @awaitNotRequired
+  Future<int> x = Future.value(7);
+}
+''');
+  }
+
+  test_valid_field_futureReturnType_inferred() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+class C {
+  @awaitNotRequired
+  var x = Future.value(7);
+}
+''');
+  }
+
+  test_valid_function_futureOrReturnType() async {
+    await assertNoErrorsInCode('''
+import 'dart:async';
+import 'package:meta/meta.dart';
+@awaitNotRequired
+FutureOr<int> f() => 7;
+''');
+  }
+
+  test_valid_function_futureReturnType() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+@awaitNotRequired
+Future<int> f() => Future.value(7);
+''');
+  }
+
+  test_valid_function_futureReturnType_nullable() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+@awaitNotRequired
+Future<int>? f() => null;
+''');
+  }
+
+  test_valid_function_futureSubtypeReturnType() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+@awaitNotRequired
+external Future2<int> f();
+abstract class Future2<T> implements Future<T> {}
+''');
+  }
+
+  test_valid_method_futureReturnType() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+class C {
+  @awaitNotRequired
+  Future<int> f() => Future.value(7);
+}
+''');
+  }
+
+  test_valid_method_futureReturnType_inheritedReturnType() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+class C {
+  Future<int> f() => Future.value(0);
+}
+class D extends C {
+  @awaitNotRequired
+  @override
+  f() => Future.value(7);
+}
+''');
+  }
+
+  test_valid_topLevelVariable_futureReturnType() async {
+    await assertNoErrorsInCode('''
+import 'package:meta/meta.dart';
+@awaitNotRequired
+Future<int> x = Future.value(7);
+''');
+  }
+}

pkg/analyzer/test/src/diagnostics/test_all.dart

@@ -432,6 +432,8 @@ import 'invalid_annotation_from_deferred_library_test.dart'
 import 'invalid_annotation_target_test.dart' as invalid_annotation_target;
 import 'invalid_annotation_test.dart' as invalid_annotation;
 import 'invalid_assignment_test.dart' as invalid_assignment;
+import 'invalid_await_not_required_annotation_test.dart'
+    as await_not_required_annotation;
 import 'invalid_constant_test.dart' as invalid_constant;
 import 'invalid_constructor_name_test.dart' as invalid_constructor_name;
 import 'invalid_do_not_submit_test.dart' as invalid_do_not_submit;
@@ -1213,6 +1215,7 @@ main() {
     invalid_annotation_from_deferred_library.main();
     invalid_annotation_target.main();
     invalid_assignment.main();
+    await_not_required_annotation.main();
     invalid_constant.main();
     invalid_constructor_name.main();
     invalid_do_not_submit.main();