DAS plugins: Document writing quick fixes

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

Author: srawlins

pkg/analysis_server_plugin/doc/writing_a_plugin.md

@@ -46,7 +46,7 @@ Here we have a class, `SimplePlugin`, which extends the `Plugin` class from the
 `analysis_server_plugin` package. This class has one method that we override:
 `register`. In the `register` method, we can register analysis rules and quick
 fixes (CorrectionProducers). See details in the [writing rules][] doc, and the
-writing quick fixes doc (TODO).
+[writing fixes][] doc.
 
 Additionally, we provide a top-level variable in this file called `plugin`,
 which is an instance of our `SimplePlugin` class. When a running instance of
@@ -64,4 +64,5 @@ plugin isolate has crashed, the "plugins" screen will display the crash.
 can help in debugging plugin code.
 
 [writing rules]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md
+[writing fixes]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_fixes.md
 [analyzer diagnostics pages]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server/doc/tutorial/instrumentation.md#open-the-analyzer-diagnostics-pages

pkg/analysis_server_plugin/doc/writing_fixes.md

@@ -0,0 +1,139 @@
+# Writing fixes
+
+This package gives analyzer plugin authors the ability to write "quick fixes"
+targeted at specific diagnostics, that can fix source code from a developer's
+IDE. This document describes briefly how to write such a fix, and how to
+register it in an analyzer plugin.
+
+## The analysis rule
+
+A quick fix must be associated with a diagnostic in order to be presented to a
+devloper in their IDE. (There is a separate feature calls "assists" which do
+not need to be associated with diagnostics; analyzer plugins can't currently
+offer assists.)
+
+For this guide, we will be using the "MyRule" rule from the [writing rules][]
+guide.
+
+
+## The ResolvedCorrectionProducer class
+
+A quick fix is specified by subclassing the ResolvedCorrectionProducer class.
+Here is our example:
+
+```dart
+import 'package:analysis_server_plugin/edit/dart/correction_producer.dart';
+import 'package:analysis_server_plugin/edit/dart/dart_fix_kind_priority.dart';
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer_plugin/utilities/change_builder/change_builder_core.dart';
+import 'package:analyzer_plugin/utilities/fixes/fixes.dart';
+import 'package:analyzer_plugin/utilities/range_factory.dart';
+
+class RemoveAwait extends ResolvedCorrectionProducer {
+  static const _removeAwaitKind = FixKind(
+      'dart.fix.moveBelowEnclosingTestCall',
+      DartFixKindPriority.standard,
+      "Move below the enclosing 'test' call");
+
+  RemoveAwait({required super.context});
+
+  @override
+  CorrectionApplicability get applicability =>
+      CorrectionApplicability.singleLocation;
+
+  @override
+  FixKind get fixKind => _removeAwaitKind;
+
+  @override
+  Future<void> compute(ChangeBuilder builder) async {
+    var awaitExpression = node;
+    if (awaitExpression is AwaitExpression) {
+      var awaitToken = awaitExpression.awaitKeyword;
+      await builder.addDartFileEdit(file, (builder) {
+        builder.addDeletion(range.startStart(awaitToken, awaitToken.next!));
+      });
+    }
+  }
+}
+```
+
+Let's look at each declaration individually:
+
+* `class RemoveAwait` - A quick fix is a class that extends
+  `ResolvedCorrectionProducer`. The name of the base class indicates that an
+  instance of this class can produce "corrections" (a set of edits) for a
+  resolved library.
+* `static const _removeAwaitKind = FixKind(...)` - Each quick fix must have an
+  associated `FixKind` which has a unique `id`
+  (`'dart.fix.moveBelowEnclosingTestCall'`), a priority
+  (`DartFixKindPriority.standard` is a fine default), and a message which is
+  displayed in the IDE (`"Move below the enclosing 'test' call"`).
+* `RemoveAwait({required super.context});` - A standard constructor that
+  accepts a `CorrectionProducerContext` and passes it up to the
+  super-constructor.
+* `CorrectionApplicability get applicability =>` - the applicability field
+  describes how widely a fix can be applied safely and sensibly. Currently,
+  fixes registered in plugins cannot be applied in bulk, so only
+  `CorrectionApplicability.singleLocation` and
+  `CorrectionApplicability.acrossSingleFile` should be used.
+* `FixKind get fixKind => _removeAwaitKind;` - each instance of this class can
+  refer to the static field for it's `fixKind`.
+* `Future<void> compute(ChangeBuilder builder)` - This method is called when an
+  associated diagnostic (lint or warning) has been reported, and we want a
+  possible correction from this correction producer. This is the code that
+  looks at the error node (the `node` field) and surrounding code and
+  determines what correction to offer, if any.
+
+  * `await builder.addDartFileEdit(...)` - Once we have determined that we want
+    to offer a fix, we call this method, and specify code deletions,
+    insertions, and/or replacements inside the callback function. If there are
+    cases where this correction producer will not offer any quick fixes (such
+    as the source code having certain properties), then those cases should be
+    checked so that we don't call this method in such cases.
+  * `builder.addDeletion(...)` - For this fix (removing an `await` keyword), we
+    can use `addDeletion` to specify a range of source code text to delete. The
+    `DartFileEditBuilder` class has many utilities for adding various edits.
+
+  Writing a quick fix can be non-trivial, even for changes which are
+  conceptually simple. It may be helpful to see examples that are similar to a
+  desired fix. See the [fixes that are offered by Dart Analysis
+  Server][existing-fixes] for hundreds of examples.
+
+Instances of the correction producer class are short-lived, and they can
+contain state related to the specific reported diagnostic and
+code-under-analysis. Indeed, the `CorrectionProducerContext`, which is passed
+into the constructor, and available as a field in the super-class, contains
+information specific to the code-under-analysis and the diagnostic.
+
+## Registering a quick fix
+
+In order for a quick fix to be used in an analyzer plugin, it must be
+registered. Register the quick fix's constructor inside a plugin's
+`register` method:
+
+```dart
+import 'package:analysis_server_plugin/plugin.dart';
+import 'package:analysis_server_plugin/registry.dart';
+
+final plugin = SimplePlugin();
+
+class SimplePlugin extends Plugin {
+  @override
+  void register(PluginRegistry registry) {
+    registry.registerWarningRule(MyRule());
+    registry.registerFixForRule(MyRule.code, RemoveAwait.new);
+  }
+}
+```
+
+Here, the warning (`MyRule.code`) is associated with the fix (the constructor
+for the`RemoveAwait` class), in `registry.registerFixForRule`. Instances of
+correction producers contain state related to the specific reported diagnostic
+and the code-under-analysis, which is why the constructor is given here,
+instead of a long-lived instance.
+
+See [writing a plugin][] for information about the `Plugin` class.
+
+[writing rules]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md
+[existing-fixes]: https://github.com/dart-lang/sdk/tree/main/pkg/analysis_server/lib/src/services/correction/dart
+[writing a plugin]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md

pkg/analysis_server_plugin/doc/writing_rules.md

@@ -1,4 +1,4 @@
-# Writing Rules
+# Writing rules
 
 This package gives analyzer plugin authors the ability to write static rules
 for source code. This document describes briefly how to write such a rule, and
@@ -17,8 +17,12 @@ various syntax tree nodes that the visitor class needs to visit. Let's see an
 example:
 
 ```dart
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/src/dart/error/lint_codes.dart';
+import 'package:analyzer/src/lint/linter.dart';
+
 class MyRule extends AnalysisRule {
-  static const LintCode _code = LintCode(
+  static const LintCode code = LintCode(
     'my_rule',
     'No await expressions',
     correctionMessage: "Try removing 'await'.",
@@ -31,7 +35,7 @@ class MyRule extends AnalysisRule {
         );
 
   @override
-  LintCode get lintCode => _code;
+  LintCode get lintCode => code;
 
   @override
   void registerNodeProcessors(
@@ -86,6 +90,10 @@ implementation. Let's look at a quick example:
 [SimpleAstVisitor docs]: https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/lib/dart/ast/visitor.dart#L1841
 
 ```dart
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:analyzer/src/lint/linter.dart';
+
 class _Visitor extends SimpleAstVisitor<void> {
   final LintRule rule;
 
@@ -138,6 +146,9 @@ registered. Register an instance of an analysis rule inside a plugin's
 `register` method:
 
 ```dart
+import 'package:analysis_server_plugin/plugin.dart';
+import 'package:analysis_server_plugin/registry.dart';
+
 class SimplePlugin extends Plugin {
   @override
   void register(PluginRegistry registry) {
@@ -151,6 +162,6 @@ enabled by default. To register an analysis rule as a "lint rule," such that it
 must be specifically enabled from analysis options, use `registerLintRule`
 instead.
 
-See [writing a plugin][] for for information about the `Plugin` class.
+See [writing a plugin][] for information about the `Plugin` class.
 
-[writing a plugin]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md
+[writing a plugin]: https://github.com/dart-lang/sdk/blob/main/pkg/analysis_server_plugin/doc/writing_rules.md