Analyzer warnings: add support for @Deprecation.instantiate

Work towards #60504

* The annotation causes certain usage to generate a warning (+ tests).
* Possible fixes for this new warning are offered (+ tests).
* Placing the annotation on an invalid element generates a different
  warning (+ tests).

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

Author: srawlins

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

@@ -3464,6 +3464,11 @@ WarningCode.DEPRECATED_IMPLEMENT:
   status: hasFix
 WarningCode.DEPRECATED_IMPLEMENTS_FUNCTION:
   status: hasFix
+WarningCode.DEPRECATED_INSTANTIATE:
+  status: noFix
+  notes: |-
+    The only fix would be to delete the whole instance creation expression, or
+    follow the directions in the deprecation message.
 WarningCode.DEPRECATED_MIXIN_FUNCTION:
   status: needsFix
   notes: |-
@@ -3555,6 +3560,9 @@ WarningCode.INVALID_DEPRECATED_EXTEND_ANNOTATION:
 WarningCode.INVALID_DEPRECATED_IMPLEMENT_ANNOTATION:
   status: needsFix
   notes: The fix is to remove the annotation.
+WarningCode.INVALID_DEPRECATED_INSTANTIATE_ANNOTATION:
+  status: needsFix
+  notes: The fix is to remove the annotation.
 WarningCode.INVALID_DEPRECATED_SUBCLASS_ANNOTATION:
   status: needsFix
   notes: The fix is to remove the annotation.

pkg/analyzer/lib/src/diagnostic/diagnostic_code_values.g.dart

@@ -984,6 +984,7 @@ const List<DiagnosticCode> diagnosticCodeValues = [
   WarningCode.deprecatedExtendsFunction,
   WarningCode.deprecatedImplement,
   WarningCode.deprecatedImplementsFunction,
+  WarningCode.deprecatedInstantiate,
   WarningCode.deprecatedMixinFunction,
   WarningCode.deprecatedNewInCommentReference,
   WarningCode.deprecatedSubclass,
@@ -1019,6 +1020,7 @@ const List<DiagnosticCode> diagnosticCodeValues = [
   WarningCode.invalidAwaitNotRequiredAnnotation,
   WarningCode.invalidDeprecatedExtendAnnotation,
   WarningCode.invalidDeprecatedImplementAnnotation,
+  WarningCode.invalidDeprecatedInstantiateAnnotation,
   WarningCode.invalidDeprecatedSubclassAnnotation,
   WarningCode.invalidExportOfInternalElement,
   WarningCode.invalidExportOfInternalElementIndirectly,

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

@@ -141,6 +141,13 @@ class AnnotationVerifier {
       _checkDeprecatedSubclass(node, node.parent);
       return;
     }
+
+    var isInstantiate =
+        value.getField('_isInstantiate')?.toBoolValue() ?? false;
+    if (isInstantiate) {
+      _checkDeprecatedInstantiate(node, node.parent);
+      return;
+    }
   }
 
   void _checkDeprecatedExtend(Annotation node, AstNode parent) {
@@ -154,10 +161,8 @@ class AnnotationVerifier {
     }
 
     if (declaredElement is ClassElement) {
-      var hasGenerativeConstructor = declaredElement.constructors.any(
-        (c) => c.isPublic && c.isGenerative,
-      );
-      if (declaredElement.isExtendableOutside && hasGenerativeConstructor) {
+      if (declaredElement.isExtendableOutside &&
+          declaredElement.hasGenerativeConstructor) {
         return;
       }
     }
@@ -194,6 +199,29 @@ class AnnotationVerifier {
     );
   }
 
+  void _checkDeprecatedInstantiate(Annotation node, AstNode parent) {
+    Element? declaredElement;
+    if (parent
+        case ClassDeclaration(:var declaredFragment) ||
+            ClassTypeAlias(:var declaredFragment)) {
+      declaredElement = declaredFragment!.element;
+    } else if (parent is GenericTypeAlias) {
+      declaredElement = parent.type.type?.element;
+    }
+
+    if (declaredElement is ClassElement) {
+      if (!declaredElement.isAbstract &&
+          declaredElement.hasGenerativeConstructor) {
+        return;
+      }
+    }
+
+    _diagnosticReporter.atNode(
+      node.name,
+      WarningCode.invalidDeprecatedInstantiateAnnotation,
+    );
+  }
+
   void _checkDeprecatedSubclass(Annotation node, AstNode parent) {
     Element? declaredElement;
     if (parent
@@ -735,3 +763,8 @@ class AnnotationVerifier {
     };
   }
 }
+
+extension on ClassElement {
+  bool get hasGenerativeConstructor =>
+      constructors.any((c) => c.isPublic && c.isGenerative);
+}

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

@@ -300,6 +300,7 @@ class BestPracticesVerifier extends RecursiveAstVisitor<void> {
   @override
   void visitConstructorName(ConstructorName node) {
     _deprecatedMemberUseVerifier.constructorName(node);
+    _deprecatedFunctionalityVerifier.constructorName(node);
     super.visitConstructorName(node);
   }
 

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

@@ -6489,6 +6489,14 @@ class WarningCode extends DiagnosticCode {
     uniqueName: 'DEPRECATED_IMPLEMENTS_FUNCTION',
   );
 
+  /// Parameters:
+  /// Object p0: the name of the member
+  static const WarningCode deprecatedInstantiate = WarningCode(
+    'DEPRECATED_INSTANTIATE',
+    "Instantiating '{0}' is deprecated.",
+    correctionMessage: "Try instantiating a non-abstract class.",
+  );
+
   /// No parameters.
   static const WarningCode deprecatedMixinFunction = WarningCode(
     'DEPRECATED_SUBTYPE_OF_FUNCTION',
@@ -6825,6 +6833,13 @@ class WarningCode extends DiagnosticCode {
     correctionMessage: "Try removing the '@Deprecated.implement' annotation.",
   );
 
+  /// No parameters.
+  static const WarningCode invalidDeprecatedInstantiateAnnotation = WarningCode(
+    'INVALID_DEPRECATED_INSTANTIATE_ANNOTATION',
+    "The annotation '@Deprecated.instantiate' can only be applied to classes.",
+    correctionMessage: "Try removing the '@Deprecated.instantiate' annotation.",
+  );
+
   /// No parameters.
   static const WarningCode invalidDeprecatedSubclassAnnotation = WarningCode(
     'INVALID_DEPRECATED_SUBCLASS_ANNOTATION',

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

@@ -28,6 +28,18 @@ class DeprecatedFunctionalityVerifier {
     _checkForDeprecatedImplement(node.implementsClause?.interfaces);
   }
 
+  void constructorName(ConstructorName node) {
+    var classElement = node.type.element;
+    if (classElement == null) return;
+    if (classElement.hasDeprecatedWithField('_isInstantiate')) {
+      _diagnosticReporter.atNode(
+        node,
+        WarningCode.deprecatedInstantiate,
+        arguments: [classElement.name!],
+      );
+    }
+  }
+
   void enumDeclaration(EnumDeclaration node) {
     _checkForDeprecatedImplement(node.implementsClause?.interfaces);
   }

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

@@ -318,26 +318,37 @@ class Deprecated extends Object {
   final bool _isImplement;
   final bool _isExtend;
   final bool _isSubclass;
+  final bool _isInstantiate;
   const Deprecated(this.message)
       : _isUse = true,
         _isImplement = false,
         _isExtend = false,
-        _isSubclass = false;
+        _isSubclass = false,
+        _isInstantiate = false;
   const Deprecated.implement([this.message = "next release"])
       : _isUse = false,
         _isImplement = true,
         _isExtend = false,
-        _isSubclass = false;
+        _isSubclass = false,
+        _isInstantiate = false;
   const Deprecated.extend([this.message = "next release"])
       : _isUse = false,
         _isImplement = false,
         _isExtend = true,
-        _isSubclass = false;
+        _isSubclass = false,
+        _isInstantiate = false;
   const Deprecated.subclass([this.message = "next release"])
       : _isUse = false,
         _isImplement = false,
         _isExtend = false,
-        _isSubclass = true;
+        _isSubclass = true,
+        _isInstantiate = false;
+  const Deprecated.instantiate([this.message = "next release"])
+      : _isUse = false,
+        _isImplement = false,
+        _isExtend = false,
+        _isSubclass = false,
+        _isInstantiate = true;
 }
 
 class pragma {

pkg/analyzer/messages.yaml

@@ -23909,7 +23909,7 @@ WarningCode:
     documentation: |-
       #### Description
 
-      The analyzer produces this diagnostic when a class which is annotated with
+      The analyzer produces this diagnostic when a class annotated with
       `@Deprecated.extend` is used in the `extends` clause of a class
       declaration.
 
@@ -23984,12 +23984,12 @@ WarningCode:
     documentation: |-
       #### Description
 
-      The analyzer produces this diagnostic when a class which is annotated with
+      The analyzer produces this diagnostic when a class annotated with
       `@Deprecated.implement` is used in the `implements` clause of a class or
       enum declaration. This annotation indicates that the ability for classes
       to implement the annotated class is deprecated, and will soon be removed,
-      perhaps
-      by marking the annotated class with `interface`, `final`, or `sealed`.
+      perhaps by marking the annotated class with `interface`, `final`, or
+      `sealed`.
 
       #### Example
 
@@ -24024,6 +24024,43 @@ WarningCode:
     problemMessage: "Implementing 'Function' has no effect."
     correctionMessage: "Try removing 'Function' from the 'implements' clause."
     hasPublishedDocs: true
+  DEPRECATED_INSTANTIATE:
+    parameters:
+      Object p0: the name of the member
+    problemMessage: "Instantiating '#p0' is deprecated."
+    correctionMessage: Try instantiating a non-abstract class.
+    hasPublishedDocs: false
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when a class annotated with
+      `@Deprecated.instantiate` is instantiated. This annotation indicates that
+      the ability to instantiate the class is deprecated, and will soon be removed,
+      perhaps by marking the annotated class with `abstract`, or `sealed`.
+
+      #### Example
+
+      If the library `p` defines a class annotated with
+      `@Deprecated.instantiate`:
+
+      ```dart
+      %uri="package:p/p.dart"
+      @Deprecated.instantiate()
+      class C {}
+      ```
+
+      Then, the following code, when in a library other than `p`, produces this
+      diagnostic:
+
+      ```dart
+      import 'package:p/p.dart';
+
+      var c = [!C!]();
+      ```
+
+      #### Common fixes
+
+      Follow any directions found in the `Deprecation.instantiate` annotation.
   DEPRECATED_MIXIN_FUNCTION:
     parameters: none
     sharedName: DEPRECATED_SUBTYPE_OF_FUNCTION
@@ -24093,7 +24130,7 @@ WarningCode:
     documentation: |-
       #### Description
 
-      The analyzer produces this diagnostic when a class which is annotated with
+      The analyzer produces this diagnostic when a class annotated with
       `@Deprecated.subclass` is used in the `extends` clause of a class
       declaration, or the `implements` clause of a class or enum declaration.
 
@@ -24804,6 +24841,36 @@ WarningCode:
 
       Remove the annotation:
 
+      ```dart
+      sealed class C {}
+      ```
+  INVALID_DEPRECATED_INSTANTIATE_ANNOTATION:
+    parameters: none
+    problemMessage: "The annotation '@Deprecated.instantiate' can only be applied to classes."
+    correctionMessage: Try removing the '@Deprecated.instantiate' annotation.
+    hasPublishedDocs: false
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when anything other than an
+      instantiable class is annotated with Deprecated.instantiate. An
+      instantiable class is one not declared with the `abstract` or `sealed`
+      keywords, and with at least one public, generative constructor.
+
+      #### Example
+
+      The following code produces this diagnostic because the annotation is on a
+      sealed class:
+
+      ```dart
+      @[!Deprecated.instantiate!]()
+      sealed class C {}
+      ```
+
+      #### Common fixes
+
+      Remove the annotation:
+
       ```dart
       sealed class C {}
       ```

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

@@ -59,7 +59,7 @@ class Bar implements Foo2 {}
   test_annotatedClassTypeAlias() async {
     newFile('$testPackageLibPath/foo.dart', r'''
 @Deprecated.implement()
-class Foo  = Object with M;
+class Foo = Object with M;
 mixin M {}
 ''');