add @useResult

See: https://github.com/dart-lang/linter/issues/1888

Change-Id: Idd529c86236a4c2692104dc36cb0a7f0d5dd35aa
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/200301
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Phil Quitslund <[email protected]>

Author: pq

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

@@ -601,6 +601,10 @@ abstract class Element implements AnalysisTarget {
   /// Return `true` if this element has an annotation of the form `@sealed`.
   bool get hasSealed;
 
+  /// Return `true` if this element has an annotation of the form `@useResult`
+  /// or `@UseResult('..')`.
+  bool get hasUseResult;
+
   /// Return `true` if this element has an annotation of the form
   /// `@visibleForTemplate`.
   bool get hasVisibleForTemplate;
@@ -807,6 +811,10 @@ abstract class ElementAnnotation implements ConstantEvaluationTarget {
   /// intended to be used as an annotation.
   bool get isTarget;
 
+  /// Return `true` if this annotation marks the associated returned element as
+  /// requiring use.
+  bool get isUseResult;
+
   /// Return `true` if this annotation marks the associated member as being
   /// visible for template files.
   bool get isVisibleForTemplate;

pkg/analyzer/lib/error/error.dart

@@ -607,6 +607,8 @@ const List<ErrorCode> errorCodeValues = [
   HintCode.UNUSED_IMPORT,
   HintCode.UNUSED_LABEL,
   HintCode.UNUSED_LOCAL_VARIABLE,
+  HintCode.UNUSED_RESULT,
+  HintCode.UNUSED_RESULT_WITH_MESSAGE,
   HintCode.UNUSED_SHOWN_NAME,
   LanguageCode.IMPLICIT_DYNAMIC_FIELD,
   LanguageCode.IMPLICIT_DYNAMIC_FUNCTION,

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

@@ -2006,6 +2006,13 @@ class ElementAnnotationImpl implements ElementAnnotation {
   /// specific set of target element kinds.
   static const String _TARGET_CLASS_NAME = 'Target';
 
+  /// The name of the class used to mark a returned element as requiring use.
+  static const String _USE_RESULT_CLASS_NAME = "UseResult";
+
+  /// The name of the top-level variable used to mark a returned element as
+  /// requiring use.
+  static const String _USE_RESULT_VARIABLE_NAME = "useResult";
+
   /// The name of the top-level variable used to mark a method as being
   /// visible for templates.
   static const String _VISIBLE_FOR_TEMPLATE_VARIABLE_NAME =
@@ -2118,6 +2125,12 @@ class ElementAnnotationImpl implements ElementAnnotation {
   bool get isTarget => _isConstructor(
       libraryName: _META_META_LIB_NAME, className: _TARGET_CLASS_NAME);
 
+  @override
+  bool get isUseResult =>
+      _isConstructor(
+          libraryName: _META_LIB_NAME, className: _USE_RESULT_CLASS_NAME) ||
+      _isPackageMetaGetter(_USE_RESULT_VARIABLE_NAME);
+
   @override
   bool get isVisibleForTemplate => _isTopGetter(
       libraryName: _NG_META_LIB_NAME,
@@ -2497,6 +2510,18 @@ abstract class ElementImpl implements Element {
     return false;
   }
 
+  @override
+  bool get hasUseResult {
+    final metadata = this.metadata;
+    for (var i = 0; i < metadata.length; i++) {
+      var annotation = metadata[i];
+      if (annotation.isUseResult) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   @override
   bool get hasVisibleForTemplate {
     final metadata = this.metadata;
@@ -4870,6 +4895,9 @@ class MultiplyDefinedElementImpl implements MultiplyDefinedElement {
   @override
   bool get hasSealed => false;
 
+  @override
+  bool get hasUseResult => false;
+
   @override
   bool get hasVisibleForTemplate => false;
 

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

@@ -518,6 +518,9 @@ abstract class Member implements Element {
   @override
   bool get hasSealed => _declaration.hasSealed;
 
+  @override
+  bool get hasUseResult => _declaration.hasUseResult;
+
   @override
   bool get hasVisibleForTemplate => _declaration.hasVisibleForTemplate;
 

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

@@ -95,6 +95,37 @@ class HintCode extends AnalyzerErrorCode {
       "The receiver uses '?.', so its value can be null.",
       correction: "Replace the '.' with a '?.' in the invocation.");
 
+  /**
+   * Generate a hint for method, property or function annotated with
+   * `@useResult` whose invocation is unchecked.
+   *
+   * Parameters:
+   * 0: the name of the annotated method, property or function
+   */
+  static const HintCode UNUSED_RESULT = HintCode(
+      'UNUSED_RESULT', "'{0}' should be used.",
+      correction:
+          "Try using the result by invoking a member, passing it to a function, or returning it from this function.",
+      hasPublishedDocs: false);
+
+  /**
+   * Generate a hint for method, property or function annotated with
+   * `@useResult` whose invocation is unchecked.
+   *
+   * Parameters:
+   * 0: the name of the annotated method, property or function
+   * 1: message details
+   */
+  static const HintCode UNUSED_RESULT_WITH_MESSAGE = HintCode(
+    'UNUSED_RESULT',
+    "'{0}' should be used. {1}.",
+    // todo(pq): consider passing in correction details: https://github.com/dart-lang/sdk/issues/46066
+    correction:
+        "Try using the result by invoking a member, passing it to a function, or returning it from this function.",
+    hasPublishedDocs: false,
+    uniqueName: 'HintCode.UNUSED_RESULT_WITH_MESSAGE',
+  );
+
   /**
    * Dead code is code that is never reached, this can happen for instance if a
    * statement follows a return statement.

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

@@ -98,7 +98,7 @@ class BestPracticesVerifier extends RecursiveAstVisitor<void> {
     required DeclaredVariables declaredVariables,
     required AnalysisOptions analysisOptions,
     required WorkspacePackage? workspacePackage,
-  })   : _nullType = typeProvider.nullType,
+  })  : _nullType = typeProvider.nullType,
         _typeSystem = typeSystem,
         _isNonNullableByDefault = typeSystem.isNonNullableByDefault,
         _strictInference =
@@ -2007,6 +2007,8 @@ extension on TargetKind {
         return 'parameters';
       case TargetKind.setter:
         return 'setters';
+      case TargetKind.topLevelVariable:
+        return 'top-level variables';
       case TargetKind.type:
         return 'types (classes, enums, mixins, or typedefs)';
       case TargetKind.typedefType:

pkg/analyzer/lib/src/test_utilities/mock_packages.dart

@@ -36,11 +36,19 @@ const _OptionalTypeArgs optionalTypeArgs = const _OptionalTypeArgs();
 const _Protected protected = const _Protected();
 const Required required = const Required();
 const _Sealed sealed = const _Sealed();
+const UseResult useResult = UseResult();
 const _VisibleForTesting visibleForTesting = const _VisibleForTesting();
 
 class _AlwaysThrows {
   const _AlwaysThrows();
 }
+@Target({
+  TargetKind.field,
+  TargetKind.function,
+  TargetKind.getter,
+  TargetKind.method,
+  TargetKind.topLevelVariable,
+})
 class _DoNotStore {
   const _DoNotStore();
 }
@@ -76,6 +84,10 @@ class Required {
 class _Sealed {
   const _Sealed();
 }
+class UseResult {
+  final String reason;
+  const UseResult([this.reason = '']);
+}
 class _VisibleForTesting {
   const _VisibleForTesting();
 }
@@ -99,6 +111,7 @@ enum TargetKind {
   mixinType,
   parameter,
   setter,
+  topLevelVariable,
   type,
   typedefType,
 }

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

@@ -13,6 +13,7 @@ main() {
   });
 }
 
+/// todo(pq): add tests for topLevelVariables: https://dart-review.googlesource.com/c/sdk/+/200301
 @reflectiveTest
 class InvalidAnnotationTargetTest extends PubPackageResolutionTest {
   void test_classType_class() async {

pkg/meta/lib/meta.dart

@@ -253,6 +253,20 @@ const Required required = Required();
 ///   `C` and `D` are declared in different packages.
 const _Sealed sealed = _Sealed();
 
+/// Used to annotate a method, field, or getter within a class, mixin, or
+/// extension, or a or top-level getter, variable or function to indicate that
+/// the value obtained by invoking it should be use. A value is considered used
+/// if it is assigned to a variable, passed to a function, or used as the target
+/// of an invocation, or invoked (if the result is itself a function).
+///
+/// Tools, such as the analyzer, can provide feedback if
+///
+/// * the annotation is associated with anything other than a method, field or
+///   getter, top-level variable, getter or function or
+/// * the value obtained by a method, field, getter or top-level getter,
+///   variable or function annotated with `@useResult` is not used.
+const UseResult useResult = UseResult();
+
 /// Used to annotate a field that is allowed to be overridden in Strong Mode.
 ///
 /// Deprecated: Most of strong mode is now the default in 2.0, but the notion of
@@ -314,6 +328,23 @@ class Required {
   const Required([this.reason = '']);
 }
 
+/// See [useResult] for more details.
+@Target({
+  TargetKind.field,
+  TargetKind.function,
+  TargetKind.getter,
+  TargetKind.method,
+  TargetKind.topLevelVariable,
+})
+class UseResult {
+  /// A human-readable explanation of the reason why the value returned by
+  /// accessing this member should be checked.
+  final String reason;
+
+  /// Initialize a newly created instance to have the given [reason].
+  const UseResult([this.reason = '']);
+}
+
 class _AlwaysThrows {
   const _AlwaysThrows();
 }

pkg/meta/lib/meta_meta.dart

@@ -73,6 +73,10 @@ enum TargetKind {
   /// at the top-level of a library.
   setter,
 
+  /// Indicates that an annotation is valid on any top-level variable
+  /// declaration.
+  topLevelVariable,
+
   /// Indicates that an annotation is valid on any declaration that introduces a
   /// type. This includes classes, enums, mixins and typedefs, but does not
   /// include extensions because extensions don't introduce a type.