pkg/analysis_server/doc/implementation/quick_assist.md - sdk - Git at Google

 # Writing a quick assist

 This document describes what a quick assist is and outlines the basic steps for
 writing a quick assist.

 ## Overview

 A quick assist is an automated [code edit](code_edits.md) that is both
 [local in scope](code_edits.md#scope) and doesn't require any user input. If a
 code edit requires user input, might depend on knowledge from outside the local
 library, or could make changes outside the local library, then it should be
 implemented using a refactoring.

 Unlike quick fixes, quick assists are displayed even when there are no
 diagnostics being reported against the code. They are not intended to fix
 problems that are being reported, but are used to perform common and
 straightforward code transformations.

 In this document we'll use a simple example of writing an assist to convert a
 decimal representation of an integer into a hexadecimal representation. While
 this wouldn't be a good assist to offer, it's simple enough that the details of
 the implementation won't mask the general process used to implement an assist.

 ## Design considerations

 Because quick assists are computed on demand, they need to be computed quickly.
 (Some clients request quick assists every time the user repositions the cursor.)
 That places a performance requirement on quick assists, one that requires that
 the code to compute a quick assist can't perform any potentially lengthy
 computations such as searching all of the user's code or accessing the network.
 That, in turn, generally means that assists can only support localized changes.
 They can add or remove text in the local library, but generally can't do more
 than that.

 Unlike quick fixes, there is no signal to indicate which assists might apply at
 a given location in the code. That means that we have to test every assist to
 see whether it's appropriate, which puts a practical limit on the number of
 assists that we can implement. (Even if each assist only takes 100 milliseconds
 to determine whether it applies, if we have 100 assists it will take 10 seconds
 to return the list of assists to the user, which is too slow.) That means that
 we need to be discerning about which assists are implemented and work to make
 assists return quickly if they are not appropriate.

 ## Describing the assist

 Each assist has an instance of the class `AssistKind` associated with it. The
 existing assists for Dart are defined in the class `DartAssistKind`. An
 assist kind has an identifier, a priority, and a message.

 The identifier is used by some LSP-based clients to provide user-defined
 shortcuts. It's a hierarchical dot-separated identifier and should follow the
 pattern seen in the existing assist kinds.

 The priority is used to order the list of assists when presented to the user.
 The larger the value the closer to the top of the list it will appear. If you're
 implementing an assist for Dart files, you should use one of the constants
 defined in `DartAssistKindPriority` (typically
 `DartAssistKindPriority.DEFAULT`), or add a new constant if there's a need for
 it.

 The message is what will be displayed to the user by the client. This should be
 a sentence fragment (no terminating period) that would be appropriate as a label
 in a menu or on a button. It should describe the change that will be made to the
 user's code.

 Create a static field whose value is an `AssistKind` describing the assist
 you're implementing. For our example you might define a new constant in
 `DartAssistKind` like this:

 ```dart
 static const CONVERT_TO_HEX = AssistKind(
   'dart.assist.convert.toHex',
   DartAssistKindPriority.DEFAULT,
   "Convert to hexadecimal",
 );
 ```

 ## Implementing the assist, part 1

 To implement the assist you'll create a subclass of `CorrectionProducer`. Most
 of the existing correction producers are in the directory
 `analysis_server/lib/src/services/correction/dart`, so we'll start by creating
 a file named `convert_to_hex.dart` in that directory that contains the following
 (with the year updated appropriately):

 ```dart
 // Copyright (c) 2022, 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:analysis_server/src/services/correction/assist.dart';
 import 'package:analysis_server/src/services/correction/dart/abstract_producer.dart';
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer_plugin/utilities/assist/assist.dart';
 import 'package:analyzer_plugin/utilities/change_builder/change_builder_core.dart';
 import 'package:analyzer_plugin/utilities/range_factory.dart';

 class ConvertToHex extends CorrectionProducer {
   @override
   AssistKind get assistKind => DartAssistKind.CONVERT_TO_HEX;

   @override
   Future<void> compute(ChangeBuilder builder) async {
   }
 }
 ```

 The `compute` method is where the assist will be built. We'll come back to it in
 "Implementing the assist, part 2".

 The `assistKind` getter is how you associate the assist kind we created earlier
 with the assist produced by the `compute` method.

 There's another getter you might need to override. The message associated with
 the assist kind is actually a template that can be filled in at runtime. The
 placeholders in the message are denoted by integers inside curly braces (such as
 `{0}`). The integers are indexes into a list of replacement values (hence, zero
 based), and the getter `assistArguments` returns the list of replacement values.
 The message we used above doesn't have any placeholders, but if we'd written the
 message as `"Convert to '{0}'"`, then we could return the replacement values by
 implementing:

 ```dart
 String _hexRepresentation = '';

 @override
 List<Object> get assistArguments => [_hexRepresentation];
 ```

 and assigning the replacement string to the field inside the `compute` method.

 If you don't implement this getter, then the inherited getter will return an
 empty list. The number of elements in the list must match the largest index used
 in the message. If it doesn't, an exception will be thrown at runtime.

 ## Testing the assist

 Before we look at implementing the `compute` method, we should probably write
 some tests. Even if you don't normally use a test-driven approach to coding, we
 recommend it in this case because writing the tests can help you think of corner
 cases that the implementation will need to handle. The corresponding tests are
 in the directory `analysis_server/test/src/services/correction/assist`, so we'll
 create a file named `convert_to_hex_test.dart` that contains the following:

 ```dart
 // Copyright (c) 2022, 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:analysis_server/src/services/correction/assist.dart';
 import 'package:analyzer_plugin/utilities/assist/assist.dart';
 import 'package:test_reflective_loader/test_reflective_loader.dart';

 import 'assist_processor.dart';

 void main() {
   defineReflectiveSuite(() {
     defineReflectiveTests(ConvertToHexTest);
   });
 }

 @reflectiveTest
 class ConvertToHexTest extends AssistProcessorTest {
   @override
   AssistKind get kind => DartAssistKind.CONVERT_TO_HEX;
 }
 ```

 This getter tells the test framework to expect an assist of the returned kind.

 The test can then be written in a method that looks something like this:

 ```dart
 Future<void> test_positive() async {
   await resolveTestCode('''
 var c = ^42;
 ''');
   await assertHasAssist('''
 var c = 0x2a;
 ''');
 }
 ```

 The test framework will look for the marker `^`, remember it's offset,
 create a file containing the first piece of code with the marker removed, run
 the assist over the code, use our correction producer to build an edit, apply
 the edit to the file, and textually compare the results with the second piece of
 code.

 ## Registering the assist

 Before we can run the test, we need to register the correction producer so that
 it can be run.

 The list of assists is computed by the `AssistProcessor`, which has two static
 lists named `generators` and `multiGenerators` that contain the correction
 producers used to compute the assists.

 Actually, the lists contain functions used to create the producers. We do that
 so that producers can't accidentally carry state over from one use to the next.
 These functions are usually a tear-off of the correction producer's constructor.

 The last step is to add your correction producer to the list named `generators`.
 We'll talk about the other list in "Multi-assist producers".

 At this point you should be able to run the test and see it failing.

 ## Implementing the assist, part 2

 We're now at a point where we can finish the implementation of the assist by
 implementing the `compute` method.

 The correction producer has access to most of the information you should need in
 order to write the assist. The change builder passed to `compute` is how you
 construct the edit that will be sent back to the client.

 The first step in the implementation of any assist is to find the location in
 the AST where the cursor is positioned and verify that all the conditions on
 which the assist is predicated are valid. For example, for our assist we'll need
 to ensure that the cursor is on an integer literal, that the literal consists of
 decimal digits, and that the value is a valid integer.

 Finding the AST node is easy because it's done for you by the assist processor
 before `compute` is invoked. All you have to do is use the getter `node` to find
 the node at the cursor.

 ```dart
 @override
 Future<void> compute(ChangeBuilder builder) async {
   final node = this.node;
 }
 ```

 Then we need to verify that this node is an integer literal:

 ```dart
 @override
 Future<void> compute(ChangeBuilder builder) async {
   final node = this.node;
   if (node is! IntegerLiteral) {
     return;
   }
 }
 ```

 If it isn't, then we'll return. Because we haven't used the builder to create a
 assist, returning now means that no assist from this producer will be sent to
 the client.

 We'll also check that the integer has the right form and is valid:

 ```dart
 @override
 Future<void> compute(ChangeBuilder builder) async {
   final node = this.node;
   if (node is! IntegerLiteral) {
     return;
   }
   var value = node.value;
   if (value == null) {
     return;
   }
   if (node.literal.lexeme.contains(RegExp('[^0-9]'))) {
     return;
   }
 }
 ```

 After all those checks we now know that we have a decimal integer that we can
 convert. Note that we check for a `null` value before checking for non-decimal
 digits because it's a faster check and we want the assist to fail as quickly as
 possible.

 We're now ready to create the edit. To do that we're going to use the
 `ChangeBuilder` passed to the `compute` method. In the example below we'll
 introduce a couple of the methods on `ChangeBuilder`, but for more information
 you can read [Creating `SourceChange`s](https://github.com/dart-lang/sdk/blob/main/pkg/analyzer_plugin/doc/tutorial/creating_edits.md).

 ```dart
 @override
 Future<void> compute(ChangeBuilder builder) async {
   final node = this.node;
   if (node is! IntegerLiteral) {
     return;
   }
   var value = node.value;
   if (value == null) {
     return;
   }
   if (node.literal.lexeme.contains(RegExp('[^0-9]'))) {
     return;
   }
   await builder.addDartFileEdit(file, (builder) {
     var hexDigits = value.toRadixString(16);
     builder.addSimpleReplacement(range.node(node), '0x$hexDigits');
   });
 }
 ```

 We're using `addDartFileEdit` to create an edit in a `.dart` file. In this case
 the edit is simple: we're just replacing one representation of the integer
 literal with a representation of the same value in a different base. The getter
 `range` returns a `RangeFactory`, a utility class with lots of methods to make
 it easier to create `SourceRange`s.

 We're missing several test cases. Minimally we should test that the assist works
 correctly with negative values (it doesn't), and that it will not produce an
 edit if the integer literal isn't valid. We'll leave adding such tests as an
 exercise for the reader.

 In this example we're just making a simple replacement, so we're avoiding any
 need to worry about formatting. As a general principle we don't attempt to
 format the code after it's been modified, but we do make an effort to leave the
 code in a reasonably readable state. There's a getter (`eol`) that you can use
 to get the end-of-line marker that should be used in the file, and there's
 another getter (`utils`) that will return an object with several utility methods
 that help with things like getting the right indentation for nested code.

 ## Multi-assist producers

 We skipped over the list named `multiGenerators` earlier, promising that we'd
 return to it later. You'll probably never have a need for it, but in case you do
 this section will hopefully tell you what you need to know.

 There's a subclass of `CorrectionProducer` named `MultiCorrectionProducer` and
 this list is how you register one of them. That class exists for rare cases
 where you need to use a single correction producer to produce multiple assists.
 This is generally only needed when you can't know in advance the maximum number
 of assists that might need to be produced. For example, there's a set of assists
 to wrap a Flutter `Widget` in another widget, but the set of widgets that can
 wrap a given widget depends on the widget being wrapped.

 If you are able to enumerate the possible assists ahead of time, then you're
 probably better off to create one subclass of `CorrectionProducer` for each of
 the assists.
	# Writing a quick assist

	This document describes what a quick assist is and outlines the basic steps for
	writing a quick assist.

	## Overview

	A quick assist is an automated [code edit](code_edits.md) that is both
	[local in scope](code_edits.md#scope) and doesn't require any user input. If a
	code edit requires user input, might depend on knowledge from outside the local
	library, or could make changes outside the local library, then it should be
	implemented using a refactoring.

	Unlike quick fixes, quick assists are displayed even when there are no
	diagnostics being reported against the code. They are not intended to fix
	problems that are being reported, but are used to perform common and
	straightforward code transformations.

	In this document we'll use a simple example of writing an assist to convert a
	decimal representation of an integer into a hexadecimal representation. While
	this wouldn't be a good assist to offer, it's simple enough that the details of
	the implementation won't mask the general process used to implement an assist.

	## Design considerations

	Because quick assists are computed on demand, they need to be computed quickly.
	(Some clients request quick assists every time the user repositions the cursor.)
	That places a performance requirement on quick assists, one that requires that
	the code to compute a quick assist can't perform any potentially lengthy
	computations such as searching all of the user's code or accessing the network.
	That, in turn, generally means that assists can only support localized changes.
	They can add or remove text in the local library, but generally can't do more
	than that.

	Unlike quick fixes, there is no signal to indicate which assists might apply at
	a given location in the code. That means that we have to test every assist to
	see whether it's appropriate, which puts a practical limit on the number of
	assists that we can implement. (Even if each assist only takes 100 milliseconds
	to determine whether it applies, if we have 100 assists it will take 10 seconds
	to return the list of assists to the user, which is too slow.) That means that
	we need to be discerning about which assists are implemented and work to make
	assists return quickly if they are not appropriate.

	## Describing the assist

	Each assist has an instance of the class `AssistKind` associated with it. The
	existing assists for Dart are defined in the class `DartAssistKind`. An
	assist kind has an identifier, a priority, and a message.

	The identifier is used by some LSP-based clients to provide user-defined
	shortcuts. It's a hierarchical dot-separated identifier and should follow the
	pattern seen in the existing assist kinds.

	The priority is used to order the list of assists when presented to the user.
	The larger the value the closer to the top of the list it will appear. If you're
	implementing an assist for Dart files, you should use one of the constants
	defined in `DartAssistKindPriority` (typically
	`DartAssistKindPriority.DEFAULT`), or add a new constant if there's a need for
	it.

	The message is what will be displayed to the user by the client. This should be
	a sentence fragment (no terminating period) that would be appropriate as a label
	in a menu or on a button. It should describe the change that will be made to the
	user's code.

	Create a static field whose value is an `AssistKind` describing the assist
	you're implementing. For our example you might define a new constant in
	`DartAssistKind` like this:

	```dart
	static const CONVERT_TO_HEX = AssistKind(
	'dart.assist.convert.toHex',
	DartAssistKindPriority.DEFAULT,
	"Convert to hexadecimal",
	);
	```

	## Implementing the assist, part 1

	To implement the assist you'll create a subclass of `CorrectionProducer`. Most
	of the existing correction producers are in the directory
	`analysis_server/lib/src/services/correction/dart`, so we'll start by creating
	a file named `convert_to_hex.dart` in that directory that contains the following
	(with the year updated appropriately):

	```dart
	// Copyright (c) 2022, 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:analysis_server/src/services/correction/assist.dart';
	import 'package:analysis_server/src/services/correction/dart/abstract_producer.dart';
	import 'package:analyzer/dart/ast/ast.dart';
	import 'package:analyzer_plugin/utilities/assist/assist.dart';
	import 'package:analyzer_plugin/utilities/change_builder/change_builder_core.dart';
	import 'package:analyzer_plugin/utilities/range_factory.dart';

	class ConvertToHex extends CorrectionProducer {
	@override
	AssistKind get assistKind => DartAssistKind.CONVERT_TO_HEX;

	@override
	Future<void> compute(ChangeBuilder builder) async {
	}
	}
	```

	The `compute` method is where the assist will be built. We'll come back to it in
	"Implementing the assist, part 2".

	The `assistKind` getter is how you associate the assist kind we created earlier
	with the assist produced by the `compute` method.

	There's another getter you might need to override. The message associated with
	the assist kind is actually a template that can be filled in at runtime. The
	placeholders in the message are denoted by integers inside curly braces (such as
	`{0}`). The integers are indexes into a list of replacement values (hence, zero
	based), and the getter `assistArguments` returns the list of replacement values.
	The message we used above doesn't have any placeholders, but if we'd written the
	message as `"Convert to '{0}'"`, then we could return the replacement values by
	implementing:

	```dart
	String _hexRepresentation = '';

	@override
	List<Object> get assistArguments => [_hexRepresentation];
	```

	and assigning the replacement string to the field inside the `compute` method.

	If you don't implement this getter, then the inherited getter will return an
	empty list. The number of elements in the list must match the largest index used
	in the message. If it doesn't, an exception will be thrown at runtime.

	## Testing the assist

	Before we look at implementing the `compute` method, we should probably write
	some tests. Even if you don't normally use a test-driven approach to coding, we
	recommend it in this case because writing the tests can help you think of corner
	cases that the implementation will need to handle. The corresponding tests are
	in the directory `analysis_server/test/src/services/correction/assist`, so we'll
	create a file named `convert_to_hex_test.dart` that contains the following:

	```dart
	// Copyright (c) 2022, 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:analysis_server/src/services/correction/assist.dart';
	import 'package:analyzer_plugin/utilities/assist/assist.dart';
	import 'package:test_reflective_loader/test_reflective_loader.dart';

	import 'assist_processor.dart';

	void main() {
	defineReflectiveSuite(() {
	defineReflectiveTests(ConvertToHexTest);
	});
	}

	@reflectiveTest
	class ConvertToHexTest extends AssistProcessorTest {
	@override
	AssistKind get kind => DartAssistKind.CONVERT_TO_HEX;
	}
	```

	This getter tells the test framework to expect an assist of the returned kind.

	The test can then be written in a method that looks something like this:

	```dart
	Future<void> test_positive() async {
	await resolveTestCode('''
	var c = ^42;
	''');
	await assertHasAssist('''
	var c = 0x2a;
	''');
	}
	```

	The test framework will look for the marker `^`, remember it's offset,
	create a file containing the first piece of code with the marker removed, run
	the assist over the code, use our correction producer to build an edit, apply
	the edit to the file, and textually compare the results with the second piece of
	code.

	## Registering the assist

	Before we can run the test, we need to register the correction producer so that
	it can be run.

	The list of assists is computed by the `AssistProcessor`, which has two static
	lists named `generators` and `multiGenerators` that contain the correction
	producers used to compute the assists.

	Actually, the lists contain functions used to create the producers. We do that
	so that producers can't accidentally carry state over from one use to the next.
	These functions are usually a tear-off of the correction producer's constructor.

	The last step is to add your correction producer to the list named `generators`.
	We'll talk about the other list in "Multi-assist producers".

	At this point you should be able to run the test and see it failing.

	## Implementing the assist, part 2

	We're now at a point where we can finish the implementation of the assist by
	implementing the `compute` method.

	The correction producer has access to most of the information you should need in
	order to write the assist. The change builder passed to `compute` is how you
	construct the edit that will be sent back to the client.

	The first step in the implementation of any assist is to find the location in
	the AST where the cursor is positioned and verify that all the conditions on
	which the assist is predicated are valid. For example, for our assist we'll need
	to ensure that the cursor is on an integer literal, that the literal consists of
	decimal digits, and that the value is a valid integer.

	Finding the AST node is easy because it's done for you by the assist processor
	before `compute` is invoked. All you have to do is use the getter `node` to find
	the node at the cursor.

	```dart
	@override
	Future<void> compute(ChangeBuilder builder) async {
	final node = this.node;
	}
	```

	Then we need to verify that this node is an integer literal:

	```dart
	@override
	Future<void> compute(ChangeBuilder builder) async {
	final node = this.node;
	if (node is! IntegerLiteral) {
	return;
	}
	}
	```

	If it isn't, then we'll return. Because we haven't used the builder to create a
	assist, returning now means that no assist from this producer will be sent to
	the client.

	We'll also check that the integer has the right form and is valid:

	```dart
	@override
	Future<void> compute(ChangeBuilder builder) async {
	final node = this.node;
	if (node is! IntegerLiteral) {
	return;
	}
	var value = node.value;
	if (value == null) {
	return;
	}
	if (node.literal.lexeme.contains(RegExp('[^0-9]'))) {
	return;
	}
	}
	```

	After all those checks we now know that we have a decimal integer that we can
	convert. Note that we check for a `null` value before checking for non-decimal
	digits because it's a faster check and we want the assist to fail as quickly as
	possible.

	We're now ready to create the edit. To do that we're going to use the
	`ChangeBuilder` passed to the `compute` method. In the example below we'll
	introduce a couple of the methods on `ChangeBuilder`, but for more information
	you can read [Creating `SourceChange`s](https://github.com/dart-lang/sdk/blob/main/pkg/analyzer_plugin/doc/tutorial/creating_edits.md).

	```dart
	@override
	Future<void> compute(ChangeBuilder builder) async {
	final node = this.node;
	if (node is! IntegerLiteral) {
	return;
	}
	var value = node.value;
	if (value == null) {
	return;
	}
	if (node.literal.lexeme.contains(RegExp('[^0-9]'))) {
	return;
	}
	await builder.addDartFileEdit(file, (builder) {
	var hexDigits = value.toRadixString(16);
	builder.addSimpleReplacement(range.node(node), '0x$hexDigits');
	});
	}
	```

	We're using `addDartFileEdit` to create an edit in a `.dart` file. In this case
	the edit is simple: we're just replacing one representation of the integer
	literal with a representation of the same value in a different base. The getter
	`range` returns a `RangeFactory`, a utility class with lots of methods to make
	it easier to create `SourceRange`s.

	We're missing several test cases. Minimally we should test that the assist works
	correctly with negative values (it doesn't), and that it will not produce an
	edit if the integer literal isn't valid. We'll leave adding such tests as an
	exercise for the reader.

	In this example we're just making a simple replacement, so we're avoiding any
	need to worry about formatting. As a general principle we don't attempt to
	format the code after it's been modified, but we do make an effort to leave the
	code in a reasonably readable state. There's a getter (`eol`) that you can use
	to get the end-of-line marker that should be used in the file, and there's
	another getter (`utils`) that will return an object with several utility methods
	that help with things like getting the right indentation for nested code.

	## Multi-assist producers

	We skipped over the list named `multiGenerators` earlier, promising that we'd
	return to it later. You'll probably never have a need for it, but in case you do
	this section will hopefully tell you what you need to know.

	There's a subclass of `CorrectionProducer` named `MultiCorrectionProducer` and
	this list is how you register one of them. That class exists for rare cases
	where you need to use a single correction producer to produce multiple assists.
	This is generally only needed when you can't know in advance the maximum number
	of assists that might need to be produced. For example, there's a set of assists
	to wrap a Flutter `Widget` in another widget, but the set of widgets that can
	wrap a given widget depends on the widget being wrapped.

	If you are able to enumerate the possible assists ahead of time, then you're
	probably better off to create one subclass of `CorrectionProducer` for each of
	the assists.