linter: add unnecessary_unawaited lint rule

Work towards #46218

Change-Id: I0c6953463d053205cc1110f554578e6b85eac0db
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/426240
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>

Author: srawlins

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

@@ -2480,6 +2480,10 @@ LintCode.unnecessary_this:
   status: hasFix
 LintCode.unnecessary_to_list_in_spreads:
   status: hasFix
+LintCode.unnecessary_unawaited:
+  status: needsFix
+  notes: |-
+    A fix can be made to remove the 'unawaited' call.
 LintCode.unnecessary_underscores:
   status: hasFix  
 LintCode.unreachable_from_main:

pkg/linter/example/all.yaml

@@ -207,6 +207,7 @@ linter:
     - unnecessary_string_interpolations
     - unnecessary_this
     - unnecessary_to_list_in_spreads
+    - unnecessary_unawaited
     - unnecessary_underscores
     - unreachable_from_main
     - unrelated_type_equality_checks

pkg/linter/lib/src/extensions.dart

@@ -329,9 +329,14 @@ extension ElementExtension on Element? {
   };
 
   /// Whether this is an [Annotatable] which is annotated with `@awaitNotRequired`.
-  bool get hasAwaitNotRequired =>
-      this is Annotatable &&
-      (this! as Annotatable).metadata2.hasAwaitNotRequired;
+  bool get hasAwaitNotRequired {
+    var self = this;
+    if (self == null || self is! Annotatable) {
+      return false;
+    }
+    return (self as Annotatable).metadata2.hasAwaitNotRequired ||
+        (self is PropertyAccessorElement && self.variable3.hasAwaitNotRequired);
+  }
 
   bool get isDartCorePrint {
     var self = this;

pkg/linter/lib/src/lint_codes.g.dart

@@ -1827,6 +1827,14 @@ class LinterLintCode extends LintCode {
     hasPublishedDocs: true,
   );
 
+  static const LintCode unnecessary_unawaited = LinterLintCode(
+    LintNames.unnecessary_unawaited,
+    "Unnecessary use of 'unawaited'.",
+    correctionMessage:
+        "Try removing the use of 'unawaited', as the unawaited element is "
+        "annotated with '@awaitNotRequired'.",
+  );
+
   static const LintCode unnecessary_underscores = LinterLintCode(
     LintNames.unnecessary_underscores,
     "Unnecessary use of multiple underscores.",

pkg/linter/lib/src/lint_names.g.dart

@@ -545,6 +545,8 @@ abstract final class LintNames {
   static const String unnecessary_to_list_in_spreads =
       'unnecessary_to_list_in_spreads';
 
+  static const String unnecessary_unawaited = 'unnecessary_unawaited';
+
   static const String unnecessary_underscores = 'unnecessary_underscores';
 
   static const String unreachable_from_main = 'unreachable_from_main';

pkg/linter/lib/src/rules.dart

@@ -226,6 +226,7 @@ import 'rules/unnecessary_string_escapes.dart';
 import 'rules/unnecessary_string_interpolations.dart';
 import 'rules/unnecessary_this.dart';
 import 'rules/unnecessary_to_list_in_spreads.dart';
+import 'rules/unnecessary_unawaited.dart';
 import 'rules/unnecessary_underscores.dart';
 import 'rules/unreachable_from_main.dart';
 import 'rules/unrelated_type_equality_checks.dart';
@@ -478,6 +479,7 @@ void registerLintRules() {
     ..registerLintRule(UnnecessaryStringInterpolations())
     ..registerLintRule(UnnecessaryThis())
     ..registerLintRule(UnnecessaryToListInSpreads())
+    ..registerLintRule(UnnecessaryUnawaited())
     ..registerLintRule(UnnecessaryUnderscores())
     ..registerLintRule(UnreachableFromMain())
     ..registerLintRule(UnrelatedTypeEqualityChecks())

pkg/linter/lib/src/rules/unnecessary_unawaited.dart

@@ -0,0 +1,66 @@
+// 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/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/dart/element/element.dart';
+
+import '../analyzer.dart';
+import '../extensions.dart';
+
+const _desc = r"Unnecessary use of 'unawaited'.";
+
+class UnnecessaryUnawaited extends LintRule {
+  UnnecessaryUnawaited()
+    : super(name: LintNames.unnecessary_unawaited, description: _desc);
+
+  @override
+  LintCode get lintCode => LinterLintCode.unnecessary_unawaited;
+
+  @override
+  void registerNodeProcessors(
+    NodeLintRegistry registry,
+    LinterContext context,
+  ) {
+    var visitor = _Visitor(this);
+    registry.addMethodInvocation(this, visitor);
+  }
+}
+
+class _Visitor extends SimpleAstVisitor<void> {
+  final LintRule rule;
+
+  _Visitor(this.rule);
+
+  @override
+  void visitMethodInvocation(MethodInvocation node) {
+    if (!node.isUnawaitedFunction) return;
+    if (node.target != null) return;
+
+    // If there are 0 or more than 1 arguments, then a different error is
+    // reported.
+    if (node.argumentList.arguments.length != 1) return;
+
+    var argument = node.argumentList.arguments.first;
+    var element = switch (argument.unParenthesized) {
+      BinaryExpression(:var element) => element,
+      MethodInvocation(:var methodName) => methodName.element,
+      PrefixExpression(:var element) => element,
+      PrefixedIdentifier(:var identifier) => identifier.element,
+      PropertyAccess(:var propertyName) => propertyName.element,
+      SimpleIdentifier(:var element) => element,
+      _ => null,
+    };
+    if (element is! Annotatable) return;
+    if (element.hasAwaitNotRequired) {
+      rule.reportAtNode(node.methodName);
+    }
+  }
+}
+
+extension on MethodInvocation {
+  bool get isUnawaitedFunction =>
+      methodName.name == 'unawaited' &&
+      methodName.element?.library2?.name3 == 'dart.async';
+}

pkg/linter/messages.yaml

@@ -13586,6 +13586,38 @@ LintCode:
         ...['foo', 'bar', 'baz'].map((String s) => Text(s)),
       ]
       ```
+  unnecessary_unawaited:
+    problemMessage: "Unnecessary use of 'unawaited'."
+    correctionMessage: "Try removing the use of 'unawaited', as the unawaited element is annotated with '@awaitNotRequired'."
+    state:
+      stable: "3.9"
+    categories: [brevity, unintentional, unusedCode]
+    hasPublishedDocs: false
+    deprecatedDetails: |-
+      A call to a function, method, or operator, or a reference to a field,
+      getter, or top-level variable which is annotated with `@awaitNotRequired`
+      does not necessarily need to be awaited, nor does it need to be wrapped in
+      a call to `unawaited()`.
+
+      **BAD:**
+      ```dart
+      @awaitNotRequired
+      Future<LogMessage> log(String message) { ... }
+
+      void f() {
+        unawaited(log('Message.'));
+      }
+      ```
+
+      **GOOD:**
+      ```dart
+      @awaitNotRequired
+      Future<LogMessage> log(String message) { ... }
+
+      void f() {
+        log('Message.');
+      }
+      ```
   unnecessary_underscores:
     problemMessage: "Unnecessary use of multiple underscores."
     correctionMessage: "Try using '_'."

pkg/linter/test/rules/all.dart

@@ -288,6 +288,7 @@ import 'unnecessary_string_interpolations_test.dart'
 import 'unnecessary_this_test.dart' as unnecessary_this;
 import 'unnecessary_to_list_in_spreads_test.dart'
     as unnecessary_to_list_in_spreads;
+import 'unnecessary_unawaited_test.dart' as unnecessary_unawaited;
 import 'unnecessary_underscores_test.dart' as unnecessary_underscores;
 import 'unreachable_from_main_test.dart' as unreachable_from_main;
 import 'unrelated_type_equality_checks_test.dart'
@@ -536,6 +537,7 @@ void main() {
   unnecessary_string_interpolations.main();
   unnecessary_this.main();
   unnecessary_to_list_in_spreads.main();
+  unnecessary_unawaited.main();
   unnecessary_underscores.main();
   unreachable_from_main.main();
   unrelated_type_equality_checks.main();

pkg/linter/test/rules/unnecessary_unawaited_test.dart

@@ -0,0 +1,159 @@
+// 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:test_reflective_loader/test_reflective_loader.dart';
+
+import '../rule_test_support.dart';
+
+void main() {
+  defineReflectiveSuite(() {
+    defineReflectiveTests(UnnecessaryUnawaitedTest);
+  });
+}
+
+@reflectiveTest
+class UnnecessaryUnawaitedTest extends LintRuleTest {
+  @override
+  bool get addMetaPackageDep => true;
+
+  @override
+  String get lintRule => LintNames.unnecessary_unawaited;
+
+  test_binaryOperator_annotated() async {
+    await assertDiagnostics(
+      r'''
+import 'dart:async';
+import 'package:meta/meta.dart';
+void f(C c) {
+  unawaited(c + c);
+}
+class C {
+  @awaitNotRequired
+  Future<void> operator +(C c) => Future.value();
+}
+''',
+      [lint(70, 9)],
+    );
+  }
+
+  test_binaryOperator_notAnnotated() async {
+    await assertNoDiagnostics(r'''
+import 'dart:async';
+void f(C c) {
+  unawaited(c + c);
+}
+class C {
+  Future<void> operator +(C c) => Future.value();
+}
+''');
+  }
+
+  test_function_annotated() async {
+    await assertDiagnostics(
+      r'''
+import 'dart:async';
+import 'package:meta/meta.dart';
+void f() {
+  unawaited(f2());
+}
+@awaitNotRequired
+Future<void> f2() => Future.value();
+''',
+      [lint(67, 9)],
+    );
+  }
+
+  test_function_notAnnotated() async {
+    await assertNoDiagnostics(r'''
+import 'dart:async';
+void f() {
+  unawaited(f2());
+}
+Future<void> f2() => Future.value();
+''');
+  }
+
+  test_method_annotated() async {
+    await assertDiagnostics(
+      r'''
+import 'dart:async';
+import 'package:meta/meta.dart';
+void f(C c) {
+  unawaited(c.m());
+}
+class C {
+  @awaitNotRequired
+  Future<void> m() => Future.value();
+}
+''',
+      [lint(70, 9)],
+    );
+  }
+
+  test_method_notAnnotated() async {
+    await assertNoDiagnostics(r'''
+import 'dart:async';
+void f(C c) {
+  unawaited(c.m());
+}
+class C {
+  Future<void> m() => Future.value();
+}
+''');
+  }
+
+  test_topLevelVariable_annotated() async {
+    await assertDiagnostics(
+      r'''
+import 'dart:async';
+import 'package:meta/meta.dart';
+void f() {
+  unawaited(f2);
+}
+@awaitNotRequired
+Future<void> f2 = Future.value();
+''',
+      [lint(67, 9)],
+    );
+  }
+
+  test_topLevelVariable_notAnnotated() async {
+    await assertNoDiagnostics(r'''
+import 'dart:async';
+void f() {
+  unawaited(f2);
+}
+Future<void> f2 = Future.value();
+''');
+  }
+
+  test_unaryOperator_annotated() async {
+    await assertDiagnostics(
+      r'''
+import 'dart:async';
+import 'package:meta/meta.dart';
+void f(C c) {
+  unawaited(-c);
+}
+class C {
+  @awaitNotRequired
+  Future<void> operator -() => Future.value();
+}
+''',
+      [lint(70, 9)],
+    );
+  }
+
+  test_unaryOperator_notAnnotated() async {
+    await assertNoDiagnostics(r'''
+import 'dart:async';
+void f(C c) {
+  unawaited(-c);
+}
+class C {
+  Future<void> operator -() => Future.value();
+}
+''');
+  }
+}