This document contains a specification of the API used by the analysis server to communicate with analysis server plugins. Changes to the API will be accompanied by an update to the protocol version number according to the principles of semantic versioning (semver.org).
TBD
The plugin domain contains API’s related to the execution of a plugin.
TODO: Provide notifications by which plugins can report instrumentation and/or DartSilo data.
TODO: Add a notification to the server protocol to inform the client of problems related to the execution of plugins.
Used to request that the plugin perform a version check to confirm that it works with the version of the analysis server that is executing it.
The path to the directory containing the on-disk byte store that is to be used by any analysis drivers that are created.
The path to the directory containing the SDK that is to be used by any analysis drivers that are created.
The version number of the plugin spec supported by the analysis server that is executing the plugin.
A flag indicating whether the plugin supports the same version of the plugin spec as the analysis server. If the value is false, then the plugin is expected to shutdown after returning the response.
The name of the plugin. This value is only used when the server needs to identify the plugin, either to the user or for debugging purposes.
The version of the plugin. This value is only used when the server needs to identify the plugin, either to the user or for debugging purposes.
Information that the user can use to use to contact the maintainers of the plugin when there is a problem.
The glob patterns of the files for which the plugin will provide information. This value is ignored if the isCompatible field is false. Otherwise, it will be used to identify the files for which the plugin should be notified of changes.
Used to request that the plugin exit. The server will not send any other requests after this request. The plugin should not send any responses or notifications after sending the response to this request.
Used to report that an unexpected error has occurred while executing the plugin. This notification is not used for problems with specific requests (which should be returned as part of the response) but is used for exceptions that occur while performing other tasks, such as analysis or preparing notifications.
A flag indicating whether the error is a fatal error, meaning that the plugin will shutdown automatically after sending this notification. If true, the server will not expect any other responses or notifications from the plugin.
The error message indicating what kind of error was encountered.
The stack trace associated with the generation of the error, used for debugging the plugin.
The analysis domain contains API’s related to the analysis of files.
Return the navigation information associated with the given region of the given file. If the navigation information for the given file has not yet been computed, or the most recently computed navigation information for the given file is out of date, then the response for this request will be delayed until it has been computed. If the content of the file changes after this request was received but before a response could be sent, then an error of type CONTENT_MODIFIED will be generated.
If a navigation region overlaps (but extends either before or after) the given region of the file it will be included in the result. This means that it is theoretically possible to get the same navigation region in response to multiple requests. Clients can avoid this by always choosing a region that starts at the beginning of a line and ends at the end of a (possibly different) line in the file.
The file in which navigation information is being requested.
The offset of the region for which navigation information is being requested.
The length of the region for which navigation information is being requested.
A list of the paths of files that are referenced by the navigation targets.
A list of the navigation targets that are referenced by the navigation regions.
A list of the navigation regions within the requested region of the file.
Used to inform the plugin of changes to files in the file system. Only events associated with files that match the interestingFiles glob patterns will be forwarded to the plugin.
The watch events that the plugin should handle.
Set the list of context roots that should be analyzed.
A list of the context roots that should be analyzed.
Used to set the priority files to the files in the given list. A priority file is a file that should be given priority when scheduling which analysis work to do first. The list typically contains those files that are visible to the user and those for which analysis results will have the biggest impact on the user experience. The order of the files within the list is significant: the first file will be given higher priority than the second, the second higher priority than the third, and so on.
The files that are to be a priority for analysis.
Used to subscribe for services that are specific to individual files. All previous subscriptions should be replaced by the current set of subscriptions. If a given service is not included as a key in the map then no files should be subscribed to the service, exactly as if the service had been included in the map with an explicit empty list of files.
A table mapping services to a list of the files being subscribed to the service.
Used to update the content of one or more files. Files that were previously updated but not included in this update remain unchanged. This effectively represents an overlay of the filesystem. The files whose content is overridden are therefore seen by the plugin as being files with the given content, even if the files do not exist on the filesystem or if the file path represents the path to a directory on the filesystem.
A table mapping the files whose content has changed to a description of the content change.
Used to report the errors associated with a given file. The set of errors included in the notification is always a complete list that supersedes any previously reported errors.
The file containing the errors.
The errors contained in the file.
Used to report the folding regions associated with a given file. Folding regions can be nested, but cannot be overlapping. Nesting occurs when a foldable element, such as a method, is nested inside another foldable element such as a class.
Folding regions that overlap a folding region computed by the server, or by one of the other plugins that are currently running, might be dropped by the server in order to present a consistent view to the client.
This notification should only be sent if the server has subscribed to it by including the value "FOLDING" in the list of services passed in an analysis.setSubscriptions request.
The file containing the folding regions.
The folding regions contained in the file.
Used to report the highlight regions associated with a given file. Each highlight region represents a particular syntactic or semantic meaning associated with some range. Note that the highlight regions that are returned can overlap other highlight regions if there is more than one meaning associated with a particular region.
This notification should only be sent if the server has subscribed to it by including the value "HIGHLIGHTS" in the list of services passed in an analysis.setSubscriptions request.
The file containing the highlight regions.
The highlight regions contained in the file.
Used to report the navigation regions associated with a given file. Each navigation region represents a list of targets associated with some range. The lists will usually contain a single target, but can contain more in the case of a part that is included in multiple libraries or in Dart code that is compiled against multiple versions of a package. Note that the navigation regions that are returned should not overlap other navigation regions.
Navigation regions that overlap a navigation region computed by the server, or by one of the other plugins that are currently running, might be dropped or modified by the server in order to present a consistent view to the client.
This notification should only be sent if the server has subscribed to it by including the value "NAVIGATION" in the list of services passed in an analysis.setSubscriptions request.
The file containing the navigation regions.
The navigation regions contained in the file.
The navigation targets referenced in the file. They are referenced by NavigationRegions by their index in this array.
The files containing navigation targets referenced in the file. They are referenced by NavigationTargets by their index in this array.
Used to report the occurrences of references to elements within a single file. None of the occurrence regions should overlap.
Occurrence regions that overlap an occurrence region computed by the server, or by one of the other plugins that are currently running, might be dropped or modified by the server in order to present a consistent view to the client.
This notification should only be sent if the server has subscribed to it by including the value "OCCURRENCES" in the list of services passed in an analysis.setSubscriptions request.
The file in which the references occur.
The occurrences of references to elements within the file.
Used to report the outline fragments associated with a single file.
The outline fragments will be merged with any outline produced by the server and with any fragments produced by other plugins. If the server cannot create a coherent outline, some fragments might be dropped.
This notification should only be sent if the server has subscribed to it by including the value "OUTLINE" in the list of services passed in an analysis.setSubscriptions request.
The file with which the outline is associated.
The outline fragments associated with the file.
The code completion domain contains API's related to getting code completion suggestions.
Used to request that completion suggestions for the given offset in the given file be returned.
The file containing the point at which suggestions are to be made.
The offset within the file at which suggestions are to be made.
The offset of the start of the text to be replaced. This will be different than the offset used to request the completion suggestions if there was a portion of an identifier before the original offset. In particular, the replacementOffset will be the offset of the beginning of said identifier.
The length of the text to be replaced if the remainder of the identifier containing the cursor is to be replaced when the suggestion is applied (that is, the number of characters in the existing identifier).
The completion suggestions being reported. The notification contains all possible completions at the requested cursor position, even those that do not match the characters the user has already typed. This allows the client to respond to further keystrokes from the user without having to make additional requests.
The edit domain contains API's related to edits that can be applied to the code.
Used to request the set of assists that are available at the given location. An assist is distinguished from a refactoring primarily by the fact that it affects a single file and does not require user input in order to be performed.
The file containing the code for which assists are being requested.
The offset of the code for which assists are being requested.
The length of the code for which assists are being requested.
The assists that are available at the given location.
Used to request a list of the kinds of refactorings that are valid for the given selection in the given file.
The file containing the code on which the refactoring would be based.
The offset of the code on which the refactoring would be based.
The length of the code on which the refactoring would be based.
The kinds of refactorings that are valid for the given selection.
The list of refactoring kinds is currently limited to those defined by the server API, preventing plugins from adding their own refactorings. However, plugins can support pre-defined refactorings, such as a rename refactoring, at locations not supported by server.
Used to request the set of fixes that are available for the errors at a given offset in a given file.
The file containing the errors for which fixes are being requested.
The offset used to select the errors for which fixes will be returned.
The fixes that are available for the errors at the given offset.
Used to request the changes required to perform a refactoring.
The kind of refactoring to be performed.
The file containing the code involved in the refactoring.
The offset of the region involved in the refactoring.
The length of the region involved in the refactoring.
True if the client is only requesting that the values of the options be validated and no change be generated.
Data used to provide values provided by the user. The structure of the data is dependent on the kind of refactoring being performed. The data that is expected is documented in the section titled Refactorings, labeled as "Options". This field can be omitted if the refactoring does not require any options or if the values of those options are not known.
The initial status of the refactoring, that is, problems related to the context in which the refactoring is requested. The list should be empty if there are no known problems.
The options validation status, that is, problems in the given options, such as light-weight validation of a new name, flags compatibility, etc. The list should be empty if there are no known problems.
The final status of the refactoring, that is, problems identified in the result of a full, potentially expensive validation and / or change creation. The list should be empty if there are no known problems.
Data used to provide feedback to the user. The structure of the data is dependent on the kind of refactoring being created. The data that is returned is documented in the section titled Refactorings, labeled as "Feedback".
The changes that are to be applied to affect the refactoring. This field can be omitted if there are problems that prevent a set of changes from being computed, such as having no options specified for a refactoring that requires them, or if only validation was requested.
The ids of source edits that are not known to be valid. An edit is not known to be valid if there was insufficient type information for the plugin to be able to determine whether or not the code needs to be modified, such as when a member is being renamed and there is a reference to a member from an unknown type. This field can be omitted if the change field is omitted or if there are no potential edits for the refactoring.
The kythe domain contains APIs related to generating Dart content in the Kythe format.
Return the list of KytheEntry objects for some file, given the current state of the file system populated by "analysis.updateContent".
The file containing the code for which the Kythe Entry objects are being requested.
The list of KytheEntry objects for the queried file.
The set of files paths that were required, but not in the file system, to give a complete and accurate Kythe graph for the file. This could be due to a referenced file that does not exist or generated files not being generated or passed before the call to "getKytheEntries".
This section contains descriptions of the data types referenced in the API’s of the various domains.
A list of fixes associated with a specific error
An enumeration of the services provided by the analysis domain that are related to a specific list of files.
FOLDING
HIGHLIGHTS
NAVIGATION
OCCURRENCES
OUTLINE
A description of an analysis context.
A source change that has a priority associated with it.
An abstract superclass of all refactoring feedbacks.
An abstract superclass of all refactoring options.
An indication of a problem with the execution of the server, typically in response to a request.
An enumeration of the types of errors that can occur in the execution of the plugin.
INVALID_OVERLAY_CHANGE
An "analysis.updateContent" request contained a ChangeContentOverlay object that can't be applied. This can happen for two reasons:
INVALID_PARAMETER
One of the method parameters was invalid.
PLUGIN_ERROR
An internal error occurred in the plugin while attempting to respond to a request. Also see the plugin.error notification for errors that occur outside of handling a request.
UNKNOWN_REQUEST
A request was received that the plugin does not recognize, or cannot handle in its current configuration.
A watch event sent by the server when the file system has been modified.
An indication of the type of change associated with a watch event.
ADD
An indication that the file or directory was added.
MODIFY
An indication that the file was modified.
REMOVE
An indication that the file or directory was removed.
This section contains additional information for each kind of refactoring. In addition to a brief description of the refactoring, there is a specification of the feedback that is provided when a refactoring is requested using the edit.getRefactoring request (designed to improve the UX) and the options that may be provided to edit.getRefactoring.
Convert a getter into a method by removing the keyword get and adding an empty parameter list.
It is an error if the range contains anything other than all or part of the name of a single getter.
Convert a method into a getter by adding the keyword get and removing the parameter list.
It is an error if the range contains anything other than all or part of the name of a single method or if the method has a non-empty parameter list.
Create a local variable initialized by the expression that covers the specified selection.
It is an error if the selection range is not covered by a complete expression.
The offsets of the expressions that cover the specified selection, from the down most to the up most.
The lengths of the expressions that cover the specified selection, from the down most to the up most.
The proposed names for the local variable.
The offsets of the expressions that would be replaced by a reference to the variable.
The lengths of the expressions that would be replaced by a reference to the variable. The lengths correspond to the offsets. In other words, for a given expression, if the offset of that expression is offsets[i], then the length of that expression is lengths[i].
The name that the local variable should be given.
True if all occurrences of the expression within the scope in which the variable will be defined should be replaced by a reference to the local variable. The expression used to initiate the refactoring will always be replaced.
Create a method whose body is the specified expression or list of statements, possibly augmented with a return statement.
It is an error if the range contains anything other than a complete expression (no partial expressions are allowed) or a complete sequence of statements.
The offset to the beginning of the expression or statements that will be extracted.
The length of the expression or statements that will be extracted.
The proposed return type for the method. If the returned element does not have a declared return type, this field will contain an empty string.
The proposed names for the method.
True if a getter could be created rather than a method.
The proposed parameters for the method.
The offsets of the expressions or statements that would be replaced by an invocation of the method.
The lengths of the expressions or statements that would be replaced by an invocation of the method. The lengths correspond to the offsets. In other words, for a given expression (or block of statements), if the offset of that expression is offsets[i], then the length of that expression is lengths[i].
The return type that should be defined for the method.
True if a getter should be created rather than a method. It is an error if this field is true and the list of parameters is non-empty.
The name that the method should be given.
The parameters that should be defined for the method.
It is an error if a REQUIRED or NAMED parameter follows a POSITIONAL parameter. It is an error if a REQUIRED or POSITIONAL parameter follows a NAMED parameter.
True if all occurrences of the expression or statements should be replaced by an invocation of the method. The expression or statements used to initiate the refactoring will always be replaced.
Inline the initializer expression of a local variable in place of any references to that variable.
It is an error if the range contains anything other than all or part of the name of a single local variable.
The name of the variable being inlined.
The number of times the variable occurs.
Inline a method in place of one or all references to that method.
It is an error if the range contains anything other than all or part of the name of a single method.
The name of the class enclosing the method being inlined. If not a class member is being inlined, this field will be absent.
The name of the method (or function) being inlined.
True if the declaration of the method is selected and all references should be inlined.
True if the method being inlined should be removed. It is an error if this field is true and inlineAll is false.
True if all invocations of the method should be inlined, or false if only the invocation site used to create this refactoring should be inlined.
Move the given file and update all of the references to that file and from it. The move operation is supported in general case - for renaming a file in the same folder, moving it to a different folder or both.
The refactoring must be activated before an actual file moving operation is performed.
The "offset" and "length" fields from the request are ignored, but the file specified in the request specifies the file to be moved.
The new file path to which the given file is being moved.
Rename a given element and all of the references to that element.
It is an error if the range contains anything other than all or part of the name of a single function (including methods, getters and setters), variable (including fields, parameters and local variables), class or function type.
The offset to the beginning of the name selected to be renamed.
The length of the name selected to be renamed.
The human-readable description of the kind of element being renamed (such as “class” or “function type alias”).
The old name of the element before the refactoring.
The name that the element should have after the refactoring.