Analysis Server Plugin API Specification

Version 1.0.0-alpha.0

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).

Overview

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.

FilePath

The path to the directory containing the on-disk byte store that is to be used by any analysis drivers that are created.

FilePath

The path to the directory containing the SDK that is to be used by any analysis drivers that are created.

String

The version number of the plugin spec supported by the analysis server that is executing the plugin.

bool

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.

String

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.

String

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.

String

Information that the user can use to use to contact the maintainers of the plugin when there is a problem.

String

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.

bool

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.

String

The error message indicating what kind of error was encountered.

String

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.

FilePath

The file in which navigation information is being requested.

int

The offset of the region for which navigation information is being requested.

int

The length of the region for which navigation information is being requested.

FilePath

A list of the paths of files that are referenced by the navigation targets.

NavigationTarget

A list of the navigation targets that are referenced by the navigation regions.

NavigationRegion

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.

WatchEvent

The watch events that the plugin should handle.

Set the list of context roots that should be analyzed.

ContextRoot

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.

FilePath

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.

AnalysisService FilePath

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.

FilePath AddContentOverlay ChangeContentOverlay RemoveContentOverlay

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.

FilePath

The file containing the errors.

AnalysisError

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.

FilePath

The file containing the folding regions.

FoldingRegion

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.

FilePath

The file containing the highlight regions.

HighlightRegion

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.

FilePath

The file containing the navigation regions.

NavigationRegion

The navigation regions contained in the file.

NavigationTarget

The navigation targets referenced in the file. They are referenced by NavigationRegions by their index in this array.

FilePath

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.

FilePath

The file in which the references occur.

Occurrences

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.

FilePath

The file with which the outline is associated.

Outline

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.

FilePath

The file containing the point at which suggestions are to be made.

int

The offset within the file at which suggestions are to be made.

int

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.

int

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).

CompletionSuggestion

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.

FilePath

The file containing the code for which assists are being requested.

int

The offset of the code for which assists are being requested.

int

The length of the code for which assists are being requested.

PrioritizedSourceChange

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.

FilePath

The file containing the code on which the refactoring would be based.

int

The offset of the code on which the refactoring would be based.

int

The length of the code on which the refactoring would be based.

RefactoringKind

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.

FilePath

The file containing the errors for which fixes are being requested.

int

The offset used to select the errors for which fixes will be returned.

AnalysisErrorFixes

The fixes that are available for the errors at the given offset.

Used to request the changes required to perform a refactoring.

RefactoringKind

The kind of refactoring to be performed.

FilePath

The file containing the code involved in the refactoring.

int

The offset of the region involved in the refactoring.

int

The length of the region involved in the refactoring.

bool

True if the client is only requesting that the values of the options be validated and no change be generated.

RefactoringOptions

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.

RefactoringProblem

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.

RefactoringProblem

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.

RefactoringProblem

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.

RefactoringFeedback

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".

SourceChange

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.

String

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".

FilePath

The file containing the code for which the Kythe Entry objects are being requested.

KytheEntry

The list of KytheEntry objects for the queried file.

FilePath

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".

Types

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

AnalysisError

The error with which the fixes are associated.

PrioritizedSourceChange

The fixes associated with the 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.

FilePath

The absolute path of the root directory containing the files to be analyzed.

FilePath

A list of the absolute paths of files and directories within the root directory that should not be analyzed.

FilePath

The absolute path of the analysis options file that should be used to control the analysis of the files in the context.

A source change that has a priority associated with it.

int

The priority of the change. The value is expected to be non-negative, and zero (0) is the lowest priority.

SourceChange

The change with which the relevance is associated.

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.

RequestErrorCode

A code that uniquely identifies the error that occurred.

String

A short description of the error.

String

The stack trace associated with processing the request, used for debugging the plugin.

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:

  • there was no preceding AddContentOverlay and hence no content to which the edits could be applied, or
  • one or more of the specified edits have an offset or length that is out of range.
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.

WatchEventType

The type of change represented by this event.

FilePath

The absolute path of the file or directory that changed.

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.

Refactorings

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.

int

The offsets of the expressions that cover the specified selection, from the down most to the up most.

int

The lengths of the expressions that cover the specified selection, from the down most to the up most.

String

The proposed names for the local variable.

int

The offsets of the expressions that would be replaced by a reference to the variable.

int

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].

String

The name that the local variable should be given.

bool

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.

int

The offset to the beginning of the expression or statements that will be extracted.

int

The length of the expression or statements that will be extracted.

String

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.

String

The proposed names for the method.

bool

True if a getter could be created rather than a method.

RefactoringMethodParameter

The proposed parameters for the method.

int

The offsets of the expressions or statements that would be replaced by an invocation of the method.

int

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].

String

The return type that should be defined for the method.

bool

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.

String

The name that the method should be given.

RefactoringMethodParameter

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.

  • To change the order and/or update proposed parameters, add parameters with the same identifiers as proposed.
  • To add new parameters, omit their identifier.
  • To remove some parameters, omit them in this list.
bool

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.

String

The name of the variable being inlined.

int

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.

String

The name of the class enclosing the method being inlined. If not a class member is being inlined, this field will be absent.

String

The name of the method (or function) being inlined.

bool

True if the declaration of the method is selected and all references should be inlined.

bool

True if the method being inlined should be removed. It is an error if this field is true and inlineAll is false.

bool

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.

FilePath

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.

int

The offset to the beginning of the name selected to be renamed.

int

The length of the name selected to be renamed.

String

The human-readable description of the kind of element being renamed (such as “class” or “function type alias”).

String

The old name of the element before the refactoring.

String

The name that the element should have after the refactoring.

Index