analyzer: rework AnalysisErrorListener deprecation

Work towards #60635

In this change, we rework the AnalysisErrorListener deprecation to
better support users who have their own class that implements
AnalysisErrorListener. This change introduces a sealed supertype,
DiagnosticOrErrorListener, with the old implementation,
AnalysisErrorListener, and the new implementation, DiagnosticListener,
as its sole direct subclasses. Users who have implemented
AnalysisErrorListener should be able to instead implement
DiagnosticListener, and their class is an acceptable instance of
DiagnosticOrErrorListener, wherever that is needed.

In a breaking change we can drop AnalysisErrorListener and deprecate
DiagnosticOrErrorListener, and in the next breaking change, we can drop
DiagnosticOrErrorListener.

For reference, see the first API difference when deprecating AnalysisErrorListener and introducing DiagnosticListener: 903d77c#diff-dec15868961d7eadcd009f49d129bebcdb747aaa8dbfde5f5a08884e0cf11e32

Change-Id: I3ccf11d54b41fbca98d020d89978d250c16b4c04
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/436480
Reviewed-by: Paul Berry <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/analysis_server/lib/src/lsp/source_edits.dart

@@ -678,7 +678,7 @@ class _MinimalEditComputer {
       var scanner = Scanner(
         _SourceMock.instance,
         CharSequenceReader(s),
-        DiagnosticListener.NULL_LISTENER,
+        DiagnosticListener.nullListener,
       )..configureFeatures(
         featureSetForOverriding: featureSet,
         featureSet: featureSet,

pkg/analysis_server/lib/src/services/correction/fix/data_driven/transform_set_manager.dart

@@ -115,7 +115,7 @@ class TransformSetManager {
     try {
       var content = file.readAsStringSync();
       var parser = TransformSetParser(
-        DiagnosticReporter(DiagnosticListener.NULL_LISTENER, FileSource(file)),
+        DiagnosticReporter(DiagnosticListener.nullListener, FileSource(file)),
         packageName,
       );
       return parser.parse(content);

pkg/analysis_server/lib/src/services/correction/statement_analyzer.dart

@@ -26,7 +26,7 @@ List<Token> _getTokens(String text, FeatureSet featureSet) {
     var scanner = Scanner(
       _SourceMock.instance,
       CharSequenceReader(text),
-      DiagnosticListener.NULL_LISTENER,
+      DiagnosticListener.nullListener,
     )..configureFeatures(
       featureSetForOverriding: featureSet,
       featureSet: featureSet,

pkg/analysis_server/test/stress/replay/replay.dart

@@ -226,7 +226,7 @@ class Driver {
     var scanner = Scanner(
       _TestSource(),
       CharSequenceReader(text),
-      error.DiagnosticListener.NULL_LISTENER,
+      error.DiagnosticListener.nullListener,
     )..configureFeatures(
       featureSetForOverriding: featureSet,
       featureSet: featureSet,

pkg/analysis_server/test/utils/test_support.dart

@@ -137,7 +137,7 @@ class GatheringDiagnosticListener implements DiagnosticListener {
   /// Adds the given [diagnostics] to this listener.
   void addAll(List<Diagnostic> diagnostics) {
     for (var diagnostic in diagnostics) {
-      onError(diagnostic);
+      onDiagnostic(diagnostic);
     }
   }
 
@@ -388,7 +388,7 @@ class GatheringDiagnosticListener implements DiagnosticListener {
   }
 
   @override
-  void onError(Diagnostic diagnostic) {
+  void onDiagnostic(Diagnostic diagnostic) {
     _diagnostics.add(diagnostic);
   }
 

pkg/analysis_server_plugin/lib/edit/correction_utils.dart

@@ -443,7 +443,7 @@ class TokenUtils {
       var scanner = Scanner(
         _SourceMock(),
         CharSequenceReader(s),
-        DiagnosticListener.NULL_LISTENER,
+        DiagnosticListener.nullListener,
       )..configureFeatures(
           featureSetForOverriding: featureSet,
           featureSet: featureSet,

pkg/analyzer/CHANGELOG.md

@@ -17,8 +17,12 @@
 * Deprecate `ErrorSeverity`; use `DiagnosticSeverity` instead.
 * Deprecate `DiagnosticCode.errorSeverity`; use
   `DiagnosticCode.diagnosticSeverity` instead.
-* Deprecate `ErrorListener` and `RecordingErrorListener`; use
-  `DiagnosticListener` and `RecordingDiagnosticListener` instead.
+* Deprecate `AnalysisErrorListener`, `BooleanErrorListener`, and
+  `RecordingErrorListener`; use `DiagnosticListener`,
+  `BooleanDiagnosticListener`, and `RecordingDiagnosticListener` respectively,
+  instead. Instead of calling or overriding `AnalysisErrorListener.onError`,
+  call or override `DiagnosticListener.onDiagnostic`. Instead of using
+  `AnalysisErrorListener.NULL_LISTENER`, use `DiagnosticListener.nullListener`.
 * Deprecate `RecordingErrorListener.errors`; use
   `RecordingDiagnosticListener.diagnostics` instead.
 * Deprecate `RecordingErrorListener.getErrorsForSource`; no longer supported.

pkg/analyzer/api.txt

@@ -4770,16 +4770,22 @@ package:analyzer/error/error.dart:
   ErrorSeverity (type alias for DiagnosticSeverity, deprecated)
   ErrorType (type alias for DiagnosticType, deprecated)
 package:analyzer/error/listener.dart:
-  BooleanDiagnosticListener (class extends Object implements DiagnosticListener):
+  AnalysisErrorListener (class extends Object implements DiagnosticOrErrorListener, deprecated):
+    NULL_LISTENER (static getter: AnalysisErrorListener)
+    new (constructor: AnalysisErrorListener Function())
+    onError (method: void Function(Diagnostic))
+  BooleanDiagnosticListener (class extends Object implements AnalysisErrorListener, DiagnosticListener):
     new (constructor: BooleanDiagnosticListener Function())
     errorReported (getter: bool)
+    onDiagnostic (method: void Function(Diagnostic))
     onError (method: void Function(Diagnostic))
-  DiagnosticListener (class extends Object):
-    NULL_LISTENER (static getter: DiagnosticListener)
+  DiagnosticListener (class extends Object implements DiagnosticOrErrorListener):
+    nullListener (static getter: DiagnosticListener)
     new (constructor: DiagnosticListener Function())
-    onError (method: void Function(Diagnostic))
+    onDiagnostic (method: void Function(Diagnostic))
+  DiagnosticOrErrorListener (class extends Object, sealed (immediate subtypes: AnalysisErrorListener, DiagnosticListener))
   DiagnosticReporter (class extends Object):
-    new (constructor: DiagnosticReporter Function(DiagnosticListener, Source))
+    new (constructor: DiagnosticReporter Function(DiagnosticOrErrorListener, Source))
     lockLevel (getter: int)
     lockLevel= (setter: int)
     source (getter: Source)
@@ -4791,13 +4797,15 @@ package:analyzer/error/listener.dart:
     atSourceSpan (method: void Function(SourceSpan, DiagnosticCode, {List<Object>? arguments, List<DiagnosticMessage>? contextMessages, Object? data}))
     atToken (method: void Function(Token, DiagnosticCode, {List<Object>? arguments, List<DiagnosticMessage>? contextMessages, Object? data}))
     reportError (method: void Function(Diagnostic))
-  RecordingDiagnosticListener (class extends Object implements DiagnosticListener):
+  RecordingDiagnosticListener (class extends Object implements AnalysisErrorListener, DiagnosticListener):
     new (constructor: RecordingDiagnosticListener Function())
     diagnostics (getter: List<Diagnostic>)
     errors (getter: List<Diagnostic>, deprecated)
     getErrorsForSource (method: List<Diagnostic> Function(Source), deprecated)
+    onDiagnostic (method: void Function(Diagnostic))
     onError (method: void Function(Diagnostic))
-  AnalysisErrorListener (type alias for DiagnosticListener, deprecated)
+  DiagnosticOrErrorListenerExtension (extension on DiagnosticOrErrorListener):
+    onDiagnostic (method: void Function(Diagnostic))
   BooleanErrorListener (type alias for BooleanDiagnosticListener, deprecated)
   ErrorReporter (type alias for DiagnosticReporter, deprecated)
   RecorderingErrorListener (type alias for RecordingDiagnosticListener, deprecated)

pkg/analyzer/lib/error/listener.dart

@@ -16,9 +16,6 @@ import 'package:analyzer/src/utilities/extensions/collection.dart';
 import 'package:meta/meta.dart';
 import 'package:source_span/source_span.dart';
 
-@Deprecated("Use 'DiagnosticListener' instead")
-typedef AnalysisErrorListener = DiagnosticListener;
-
 @Deprecated("Use 'BooleanDiagnosticListener' instead")
 typedef BooleanErrorListener = BooleanDiagnosticListener;
 
@@ -28,38 +25,55 @@ typedef ErrorReporter = DiagnosticReporter;
 @Deprecated("Use 'RecordingDiagnosticListener' instead")
 typedef RecorderingErrorListener = RecordingDiagnosticListener;
 
-/// An [DiagnosticListener] that keeps track of whether any diagnostic has been
+/// An object that listens for [Diagnostic]s being produced by the analysis
+/// engine.
+@Deprecated("Use 'DiagnosticListener' instead")
+abstract class AnalysisErrorListener implements DiagnosticOrErrorListener {
+  /// A diagnostic listener that ignores diagnostics that are reported to it.
+  @Deprecated("Use 'DiagnosticListener.nullListener' instead")
+  static const AnalysisErrorListener NULL_LISTENER = _NullErrorListener();
+
+  /// This method is invoked when a [diagnostic] has been found by the analysis
+  /// engine.
+  void onError(Diagnostic diagnostic);
+}
+
+/// A [DiagnosticListener] that keeps track of whether any diagnostic has been
 /// reported to it.
-class BooleanDiagnosticListener implements DiagnosticListener {
+class BooleanDiagnosticListener
+    implements
+        // ignore: deprecated_member_use_from_same_package
+        AnalysisErrorListener,
+        DiagnosticListener {
   /// A flag indicating whether a diagnostic has been reported to this listener.
   bool _diagnosticReported = false;
 
   /// Whether a diagnostic has been reported to this listener.
   bool get errorReported => _diagnosticReported;
 
   @override
-  void onError(Diagnostic diagnostic) {
+  void onDiagnostic(Diagnostic diagnostic) {
     _diagnosticReported = true;
   }
+
+  @override
+  void onError(Diagnostic diagnostic) => onDiagnostic(diagnostic);
 }
 
-/// An object that listens for [Diagnostic]s being produced by the analysis
-/// engine.
-abstract class DiagnosticListener {
+abstract class DiagnosticListener implements DiagnosticOrErrorListener {
   /// A diagnostic listener that ignores diagnostics that are reported to it.
-  static const DiagnosticListener NULL_LISTENER = _NullDiagnosticListener();
+  static const DiagnosticListener nullListener = _NullDiagnosticListener();
 
-  /// This method is invoked when a [diagnostic] has been found by the analysis
-  /// engine.
-  // TODO(srawlins): Rename to 'onDiagnostic'.
-  void onError(Diagnostic diagnostic);
+  void onDiagnostic(Diagnostic diagnostic);
 }
 
+sealed class DiagnosticOrErrorListener {}
+
 /// An object used to create diagnostics and report them to a diagnostic
 /// listener.
 class DiagnosticReporter {
   /// The diagnostic listener to which diagnostics are reported.
-  final DiagnosticListener _diagnosticListener;
+  final DiagnosticOrErrorListener _diagnosticListener;
 
   /// The source to be used when reporting diagnostics.
   final Source _source;
@@ -211,7 +225,7 @@ class DiagnosticReporter {
 
     contextMessages ??= [];
     contextMessages.addAll(convertTypeNames(arguments));
-    _diagnosticListener.onError(
+    _diagnosticListener.onDiagnostic(
       Diagnostic.tmp(
         source: _source,
         offset: offset,
@@ -266,14 +280,18 @@ class DiagnosticReporter {
 
   /// Report the given [diagnostic].
   void reportError(Diagnostic diagnostic) {
-    _diagnosticListener.onError(diagnostic);
+    _diagnosticListener.onDiagnostic(diagnostic);
   }
 }
 
 /// A diagnostic listener that records the diagnostics that are reported to it
 /// in a way that is appropriate for caching those diagnostic within an
 /// analysis context.
-class RecordingDiagnosticListener implements DiagnosticListener {
+class RecordingDiagnosticListener
+    implements
+        // ignore: deprecated_member_use_from_same_package
+        AnalysisErrorListener,
+        DiagnosticListener {
   Set<Diagnostic>? _diagnostics;
 
   /// The diagnostics collected by the listener.
@@ -297,17 +315,42 @@ class RecordingDiagnosticListener implements DiagnosticListener {
   }
 
   @override
-  void onError(Diagnostic diagnostic) {
+  void onDiagnostic(Diagnostic diagnostic) {
     (_diagnostics ??= {}).add(diagnostic);
   }
+
+  @override
+  void onError(Diagnostic diagnostic) => onDiagnostic(diagnostic);
 }
 
-/// An [DiagnosticListener] that ignores everything.
+/// A [DiagnosticListener] that ignores everything.
 class _NullDiagnosticListener implements DiagnosticListener {
   const _NullDiagnosticListener();
 
+  @override
+  void onDiagnostic(Diagnostic diagnostic) {
+    // Ignore diagnostics.
+  }
+}
+
+// ignore: deprecated_member_use_from_same_package
+/// An [AnalysisErrorListener] that ignores everything.
+class _NullErrorListener
+    implements
+        // ignore: deprecated_member_use_from_same_package
+        AnalysisErrorListener {
+  const _NullErrorListener();
+
   @override
   void onError(Diagnostic diagnostic) {
     // Ignore diagnostics.
   }
 }
+
+extension DiagnosticOrErrorListenerExtension on DiagnosticOrErrorListener {
+  void onDiagnostic(Diagnostic diagnostic) => switch (this) {
+    DiagnosticListener self => self.onDiagnostic(diagnostic),
+    // ignore: deprecated_member_use_from_same_package
+    AnalysisErrorListener self => self.onError(diagnostic),
+  };
+}

pkg/analyzer/lib/src/dart/analysis/file_state.dart

@@ -591,7 +591,8 @@ class FileState {
 
   /// Return a new parsed unresolved [CompilationUnit].
   CompilationUnitImpl parse({
-    DiagnosticListener diagnosticListener = DiagnosticListener.NULL_LISTENER,
+    DiagnosticOrErrorListener diagnosticListener =
+        DiagnosticListener.nullListener,
     required OperationPerformanceImpl performance,
   }) {
     try {
@@ -608,7 +609,7 @@ class FileState {
   /// Parses given [code] with the same features as this file.
   CompilationUnitImpl parseCode({
     required String code,
-    required DiagnosticListener diagnosticListener,
+    required DiagnosticOrErrorListener diagnosticListener,
     required OperationPerformanceImpl performance,
   }) {
     return performance.run('parseCode', (performance) {