Common Types

1.0.0

This document contains a specification of the types that are common between the analysis server wire protocol and the analysis server plugin wire protocol. While those protocols are versioned, the common types are not versioned separately.

When those protocols have identical definitions of a type, the type definition should be removed from the two individual specifications and added to this document. Two definitions of a type are identical if the HTML that defines the types is identical and if all of the types referenced by those two types are identical.

When it becomes necessary to change the definition of a common type in one protocol such that the type will no longer be common, that type and any types that reference that type must be removed from this document and added to both of the documents that include this document.

A directive to begin overlaying the contents of a file. The supplied content will be used for analysis in place of the file contents in the filesystem.

If this directive is used on a file that already has a file content overlay, the old overlay is discarded and replaced with the new one.

String String

The new content of the file.

An indication of an error, warning, or hint that was produced by the analysis.

AnalysisErrorSeverity

The severity of the error.

AnalysisErrorType

The type of the error.

Location

The location associated with the error.

String

The message to be displayed for this error. The message should indicate what is wrong with the code and why it is wrong.

String

The correction message to be displayed for this error. The correction message should indicate how the user can fix the error. The field is omitted if there is no correction message associated with the error code.

String

The name, as a string, of the error code associated with this error.

bool

A hint to indicate to interested clients that this error has an associated fix (or fixes). The absence of this field implies there are not known to be fixes. Note that since the operation to calculate whether fixes apply needs to be performant it is possible that complicated tests will be skipped and a false negative returned. For this reason, this attribute should be treated as a "hint". Despite the possibility of false negatives, no false positives should be returned. If a client sees this flag set they can proceed with the confidence that there are in fact associated fixes.

An enumeration of the possible severities of analysis errors.

INFO WARNING ERROR

An enumeration of the possible types of analysis errors.

CHECKED_MODE_COMPILE_TIME_ERROR COMPILE_TIME_ERROR HINT LINT STATIC_TYPE_WARNING STATIC_WARNING SYNTACTIC_ERROR TODO

A directive to modify an existing file content overlay. One or more ranges of text are deleted from the old file content overlay and replaced with new text.

The edits are applied in the order in which they occur in the list. This means that the offset of each edit must be correct under the assumption that all previous edits have been applied.

It is an error to use this overlay on a file that does not yet have a file content overlay or that has had its overlay removed via RemoveContentOverlay.

If any of the edits cannot be applied due to its offset or length being out of range, an INVALID_OVERLAY_CHANGE error will be reported.

String SourceEdit

The edits to be applied to the file.

A suggestion for how to complete partially entered text. Many of the fields are optional, depending on the kind of element being suggested.

CompletionSuggestionKind

The kind of element being suggested.

int

The relevance of this completion suggestion where a higher number indicates a higher relevance.

String

The identifier to be inserted if the suggestion is selected. If the suggestion is for a method or function, the client might want to additionally insert a template for the parameters. The information required in order to do so is contained in other fields.

String

Text to be displayed in, for example, a completion pop-up. This field is only defined if the displayed text should be different than the completion. Otherwise it is omitted.

int

The offset, relative to the beginning of the completion, of where the selection should be placed after insertion.

int

The number of characters that should be selected after insertion.

bool

True if the suggested element is deprecated.

bool

True if the element is not known to be valid for the target. This happens if the type of the target is dynamic.

String

An abbreviated version of the Dartdoc associated with the element being suggested. This field is omitted if there is no Dartdoc associated with the element.

String

The Dartdoc associated with the element being suggested. This field is omitted if there is no Dartdoc associated with the element.

String

The class that declares the element being suggested. This field is omitted if the suggested element is not a member of a class.

String

A default String for use in generating argument list source contents on the client side.

int

Pairs of offsets and lengths describing 'defaultArgumentListString' text ranges suitable for use by clients to set up linked edits of default argument source contents. For example, given an argument list string 'x, y', the corresponding text range [0, 1, 3, 1], indicates two text ranges of length 1, starting at offsets 0 and 3. Clients can use these ranges to treat the 'x' and 'y' values specially for linked edits.

Element

Information about the element reference being suggested.

String

The return type of the getter, function or method or the type of the field being suggested. This field is omitted if the suggested element is not a getter, function or method.

String

The names of the parameters of the function or method being suggested. This field is omitted if the suggested element is not a setter, function or method.

String

The types of the parameters of the function or method being suggested. This field is omitted if the parameterNames field is omitted.

int

The number of required parameters for the function or method being suggested. This field is omitted if the parameterNames field is omitted.

bool

True if the function or method being suggested has at least one named parameter. This field is omitted if the parameterNames field is omitted.

String

The name of the optional parameter being suggested. This field is omitted if the suggestion is not the addition of an optional argument within an argument list.

String

The type of the options parameter being suggested. This field is omitted if the parameterName field is omitted.

String

The import to be added if the suggestion is out of scope and needs an import to be added to be in scope.

An enumeration of the kinds of elements that can be included in a completion suggestion.

ARGUMENT_LIST

A list of arguments for the method or function that is being invoked. For this suggestion kind, the completion field is a textual representation of the invocation and the parameterNames, parameterTypes, and requiredParameterCount attributes are defined.

IMPORT IDENTIFIER

The element identifier should be inserted at the completion location. For example "someMethod" in import 'myLib.dart' show someMethod;. For suggestions of this kind, the element attribute is defined and the completion field is the element's identifier.

INVOCATION

The element is being invoked at the completion location. For example, 'someMethod' in x.someMethod();. For suggestions of this kind, the element attribute is defined and the completion field is the element's identifier.

KEYWORD

A keyword is being suggested. For suggestions of this kind, the completion is the keyword.

NAMED_ARGUMENT

A named argument for the current call site is being suggested. For suggestions of this kind, the completion is the named argument identifier including a trailing ':' and a space.

OPTIONAL_ARGUMENT OVERRIDE

An overriding implementation of a class member is being suggested.

PARAMETER

Information about an element (something that can be declared in code).

ElementKind

The kind of the element.

String

The name of the element. This is typically used as the label in the outline.

Location

The location of the name in the declaration of the element.

int

A bit-map containing the following flags:

  • 0x01 - set if the element is explicitly or implicitly abstract
  • 0x02 - set if the element was declared to be ‘const’
  • 0x04 - set if the element was declared to be ‘final’
  • 0x08 - set if the element is a static member of a class or is a top-level function or field
  • 0x10 - set if the element is private
  • 0x20 - set if the element is deprecated
String

The parameter list for the element. If the element is not a method or function this field will not be defined. If the element doesn't have parameters (e.g. getter), this field will not be defined. If the element has zero parameters, this field will have a value of "()".

String

The return type of the element. If the element is not a method or function this field will not be defined. If the element does not have a declared return type, this field will contain an empty string.

String

The type parameter list for the element. If the element doesn't have type parameters, this field will not be defined.

An enumeration of the kinds of elements.

CLASS CLASS_TYPE_ALIAS COMPILATION_UNIT CONSTRUCTOR CONSTRUCTOR_INVOCATION ENUM ENUM_CONSTANT FIELD FILE FUNCTION FUNCTION_INVOCATION FUNCTION_TYPE_ALIAS GETTER LABEL LIBRARY LOCAL_VARIABLE METHOD PARAMETER PREFIX SETTER TOP_LEVEL_VARIABLE TYPE_PARAMETER UNIT_TEST_GROUP UNIT_TEST_TEST UNKNOWN String

The absolute, normalized path of a file.

If the format of a file path in a request is not valid, e.g. the path is not absolute or is not normalized, then an error of type INVALID_FILE_PATH_FORMAT will be generated.

An enumeration of the kinds of folding regions.

COMMENT CLASS_MEMBER DIRECTIVES DOCUMENTATION_COMMENT TOP_LEVEL_DECLARATION

A description of a region that can be folded.

FoldingKind

The kind of the region.

int

The offset of the region to be folded.

int

The length of the region to be folded.

A description of a region that could have special highlighting associated with it.

HighlightRegionType

The type of highlight associated with the region.

int

The offset of the region to be highlighted.

int

The length of the region to be highlighted.

An enumeration of the kinds of highlighting that can be applied to files.

ANNOTATION BUILT_IN CLASS COMMENT_BLOCK COMMENT_DOCUMENTATION COMMENT_END_OF_LINE CONSTRUCTOR DIRECTIVE DYNAMIC_TYPE

Only for version 1 of highlight.

 DYNAMIC_LOCAL_VARIABLE_DECLARATION

Only for version 2 of highlight.

 DYNAMIC_LOCAL_VARIABLE_REFERENCE

Only for version 2 of highlight.

 DYNAMIC_PARAMETER_DECLARATION

Only for version 2 of highlight.

 DYNAMIC_PARAMETER_REFERENCE

Only for version 2 of highlight.

 ENUM ENUM_CONSTANT FIELD

Only for version 1 of highlight.

 FIELD_STATIC

Only for version 1 of highlight.

 FUNCTION

Only for version 1 of highlight.

 FUNCTION_DECLARATION

Only for version 1 of highlight.

 FUNCTION_TYPE_ALIAS GETTER_DECLARATION

Only for version 1 of highlight.

 IDENTIFIER_DEFAULT IMPORT_PREFIX INSTANCE_FIELD_DECLARATION

Only for version 2 of highlight.

 INSTANCE_FIELD_REFERENCE

Only for version 2 of highlight.

 INSTANCE_GETTER_DECLARATION

Only for version 2 of highlight.

 INSTANCE_GETTER_REFERENCE

Only for version 2 of highlight.

 INSTANCE_METHOD_DECLARATION

Only for version 2 of highlight.

 INSTANCE_METHOD_REFERENCE

Only for version 2 of highlight.

 INSTANCE_SETTER_DECLARATION

Only for version 2 of highlight.

 INSTANCE_SETTER_REFERENCE

Only for version 2 of highlight.

 INVALID_STRING_ESCAPE

Only for version 2 of highlight.

 KEYWORD LABEL LIBRARY_NAME

Only for version 2 of highlight.

 LITERAL_BOOLEAN LITERAL_DOUBLE LITERAL_INTEGER LITERAL_LIST LITERAL_MAP LITERAL_STRING LOCAL_FUNCTION_DECLARATION

Only for version 2 of highlight.

 LOCAL_FUNCTION_REFERENCE

Only for version 2 of highlight.

 LOCAL_VARIABLE

Only for version 1 of highlight.

 LOCAL_VARIABLE_DECLARATION LOCAL_VARIABLE_REFERENCE

Only for version 2 of highlight.

 METHOD

Only for version 1 of highlight.

 METHOD_DECLARATION

Only for version 1 of highlight.

 METHOD_DECLARATION_STATIC

Only for version 1 of highlight.

 METHOD_STATIC

Only for version 1 of highlight.

 PARAMETER

Only for version 1 of highlight.

 SETTER_DECLARATION

Only for version 1 of highlight.

 TOP_LEVEL_VARIABLE

Only for version 1 of highlight.

 PARAMETER_DECLARATION

Only for version 2 of highlight.

 PARAMETER_REFERENCE

Only for version 2 of highlight.

 STATIC_FIELD_DECLARATION

Only for version 2 of highlight.

 STATIC_GETTER_DECLARATION

Only for version 2 of highlight.

 STATIC_GETTER_REFERENCE

Only for version 2 of highlight.

 STATIC_METHOD_DECLARATION

Only for version 2 of highlight.

 STATIC_METHOD_REFERENCE

Only for version 2 of highlight.

 STATIC_SETTER_DECLARATION

Only for version 2 of highlight.

 STATIC_SETTER_REFERENCE

Only for version 2 of highlight.

 TOP_LEVEL_FUNCTION_DECLARATION

Only for version 2 of highlight.

 TOP_LEVEL_FUNCTION_REFERENCE

Only for version 2 of highlight.

 TOP_LEVEL_GETTER_DECLARATION

Only for version 2 of highlight.

 TOP_LEVEL_GETTER_REFERENCE

Only for version 2 of highlight.

 TOP_LEVEL_SETTER_DECLARATION

Only for version 2 of highlight.

 TOP_LEVEL_SETTER_REFERENCE

Only for version 2 of highlight.

 TOP_LEVEL_VARIABLE_DECLARATION

Only for version 2 of highlight.

 TYPE_NAME_DYNAMIC TYPE_PARAMETER UNRESOLVED_INSTANCE_MEMBER_REFERENCE

Only for version 2 of highlight.

 VALID_STRING_ESCAPE

Only for version 2 of highlight.

This object matches the format and documentation of the Entry object documented in the Kythe Storage Model.

KytheVName

The ticket of the source node.

String

An edge label. The schema defines which labels are meaningful.

KytheVName

The ticket of the target node.

String

A fact label. The schema defines which fact labels are meaningful.

int

The String value of the fact.

This object matches the format and documentation of the Vector-Name object documented in the Kythe Storage Model.

String

An opaque signature generated by the analyzer.

String

The corpus of source code this KytheVName belongs to. Loosely, a corpus is a collection of related files, such as the contents of a given source repository.

String

A corpus-specific root label, typically a directory path or project identifier, denoting a distinct subset of the corpus. This may also be used to designate virtual collections like generated files.

String

A path-structured label describing the “location” of the named object relative to the corpus and the root.

String

The language this name belongs to.

A collection of positions that should be linked (edited simultaneously) for the purposes of updating code after a source change. For example, if a set of edits introduced a new variable name, the group would contain all of the positions of the variable name so that if the client wanted to let the user edit the variable name after the operation, all occurrences of the name could be edited simultaneously.

Position

The positions of the regions that should be edited simultaneously.

int

The length of the regions that should be edited simultaneously.

LinkedEditSuggestion

Pre-computed suggestions for what every region might want to be changed to.

A suggestion of a value that could be used to replace all of the linked edit regions in a LinkedEditGroup.

String

The value that could be used to replace all of the linked edit regions.

LinkedEditSuggestionKind

The kind of value being proposed.

An enumeration of the kind of values that can be suggested for a linked edit.

METHOD PARAMETER TYPE VARIABLE

A location (character range) within a file.

FilePath

The file containing the range.

int

The offset of the range.

int

The length of the range.

int

The one-based index of the line containing the first character of the range.

int

The one-based index of the column containing the first character of the range.

A description of a region from which the user can navigate to the declaration of an element.

int

The offset of the region from which the user can navigate.

int

The length of the region from which the user can navigate.

int

The indexes of the targets (in the enclosing navigation response) to which the given region is bound. By opening the target, clients can implement one form of navigation. This list cannot be empty.

A description of a target to which the user can navigate.

ElementKind

The kind of the element.

int

The index of the file (in the enclosing navigation response) to navigate to.

int

The offset of the region to which the user can navigate.

int

The length of the region to which the user can navigate.

int

The one-based index of the line containing the first character of the region.

int

The one-based index of the column containing the first character of the region.

A description of the references to a single element within a single file.

Element

The element that was referenced.

int

The offsets of the name of the referenced element within the file.

int

The length of the name of the referenced element.

An node in the outline structure of a file.

Element

A description of the element represented by this node.

int

The offset of the first character of the element. This is different than the offset in the Element, which is the offset of the name of the element. It can be used, for example, to map locations in the file back to an outline.

int

The length of the element.

Outline

The children of the node. The field will be omitted if the node has no children.

A position within a file.

FilePath

The file containing the position.

int

The offset of the position.

An enumeration of the kinds of refactorings that can be created.

CONVERT_GETTER_TO_METHOD CONVERT_METHOD_TO_GETTER EXTRACT_LOCAL_VARIABLE EXTRACT_METHOD INLINE_LOCAL_VARIABLE INLINE_METHOD MOVE_FILE RENAME SORT_MEMBERS

A description of a parameter in a method refactoring.

String

The unique identifier of the parameter. Clients may omit this field for the parameters they want to add.

RefactoringMethodParameterKind

The kind of the parameter.

String

The type that should be given to the parameter, or the return type of the parameter's function type.

String

The name that should be given to the parameter.

String

The parameter list of the parameter's function type. If the parameter is not of a function type, this field will not be defined. If the function type has zero parameters, this field will have a value of '()'.

An enumeration of the kinds of parameters.

REQUIRED POSITIONAL NAMED

A description of a problem related to a refactoring.

RefactoringProblemSeverity

The severity of the problem being represented.

String

A human-readable description of the problem being represented.

Location

The location of the problem being represented. This field is omitted unless there is a specific location associated with the problem (such as a location where an element being renamed will be shadowed).

An enumeration of the severities of problems that can be returned by the refactoring requests.

INFO

A minor code problem. No example, because it is not used yet.

WARNING

A minor code problem. For example names of local variables should be camel case and start with a lower case letter. Staring the name of a variable with an upper case is OK from the language point of view, but it is nice to warn the user.

ERROR

The refactoring technically can be performed, but there is a logical problem. For example the name of a local variable being extracted conflicts with another name in the scope, or duplicate parameter names in the method being extracted, or a conflict between a parameter name and a local variable, etc. In some cases the location of the problem is also provided, so the IDE can show user the location and the problem, and let the user decide whether they want to perform the refactoring. For example the name conflict might be expected, and the user wants to fix it afterwards.

FATAL

A fatal error, which prevents performing the refactoring. For example the name of a local variable being extracted is not a valid identifier, or selection is not a valid expression.

A directive to remove an existing file content overlay. After processing this directive, the file contents will once again be read from the file system.

If this directive is used on a file that doesn't currently have a content overlay, it has no effect.

String

A description of a set of edits that implement a single conceptual change.

String

A human-readable description of the change to be applied.

SourceFileEdit

A list of the edits used to effect the change, grouped by file.

LinkedEditGroup

A list of the linked editing groups used to customize the changes that were made.

Position

The position that should be selected after the edits have been applied.

String

The optional identifier of the change kind. The identifier remains stable even if the message changes, or is parameterized.

A description of a single change to a single file.

int

The offset of the region to be modified.

int

The length of the region to be modified.

String

The code that is to replace the specified region in the original code.

String

An identifier that uniquely identifies this source edit from other edits in the same response. This field is omitted unless a containing structure needs to be able to identify the edit for some reason.

For example, some refactoring operations can produce edits that might not be appropriate (referred to as potential edits). Such edits will have an id so that they can be referenced. Edits in the same response that do not need to be referenced will not have an id.

A description of a set of changes to a single file.

FilePath

The file containing the code to be modified.

long

The modification stamp of the file at the moment when the change was created, in milliseconds since the "Unix epoch". Will be -1 if the file did not exist and should be created. The client may use this field to make sure that the file was not changed since then, so it is safe to apply the change.

SourceEdit

A list of the edits used to effect the change.