Common Types

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

String

The URL of a page containing documentation associated with this error.

DiagnosticMessage

Additional messages associated with this diagnostic that provide context to help the user understand the diagnostic.

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.

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 PACKAGE_NAME

The name of a pub package is being suggested.

A message associated with a diagnostic.

For example, if the diagnostic is reporting that a variable has been referenced before it was declared, it might have a diagnostic message that indicates where the variable is declared.

String

The message to be displayed to the user.

Location

The location associated with or referenced by the message. Clients should provide the ability to navigate to the location.

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 EXTENSION FIELD FILE FUNCTION FUNCTION_INVOCATION FUNCTION_TYPE_ALIAS GETTER LABEL LIBRARY LOCAL_VARIABLE METHOD MIXIN 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.

ANNOTATIONS BLOCK CLASS_BODY DIRECTIVES DOCUMENTATION_COMMENT FILE_HEADER FUNCTION_BODY INVOCATION LITERAL

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

Deprecated - no longer sent.

 DYNAMIC_LOCAL_VARIABLE_DECLARATION DYNAMIC_LOCAL_VARIABLE_REFERENCE DYNAMIC_PARAMETER_DECLARATION DYNAMIC_PARAMETER_REFERENCE ENUM ENUM_CONSTANT FIELD

Deprecated - no longer sent.

 FIELD_STATIC

Deprecated - no longer sent.

 FUNCTION

Deprecated - no longer sent.

 FUNCTION_DECLARATION

Deprecated - no longer sent.

 FUNCTION_TYPE_ALIAS GETTER_DECLARATION

Deprecated - no longer sent.

 IDENTIFIER_DEFAULT IMPORT_PREFIX INSTANCE_FIELD_DECLARATION INSTANCE_FIELD_REFERENCE INSTANCE_GETTER_DECLARATION INSTANCE_GETTER_REFERENCE INSTANCE_METHOD_DECLARATION INSTANCE_METHOD_REFERENCE INSTANCE_SETTER_DECLARATION INSTANCE_SETTER_REFERENCE INVALID_STRING_ESCAPE KEYWORD LABEL LIBRARY_NAME LITERAL_BOOLEAN LITERAL_DOUBLE LITERAL_INTEGER LITERAL_LIST LITERAL_MAP LITERAL_STRING LOCAL_FUNCTION_DECLARATION LOCAL_FUNCTION_REFERENCE LOCAL_VARIABLE

Deprecated - no longer sent.

 LOCAL_VARIABLE_DECLARATION LOCAL_VARIABLE_REFERENCE METHOD

Deprecated - no longer sent.

 METHOD_DECLARATION

Deprecated - no longer sent.

 METHOD_DECLARATION_STATIC

Deprecated - no longer sent.

 METHOD_STATIC

Deprecated - no longer sent.

 PARAMETER

Deprecated - no longer sent.

 SETTER_DECLARATION

Deprecated - no longer sent.

 TOP_LEVEL_VARIABLE

Deprecated - no longer sent.

 PARAMETER_DECLARATION PARAMETER_REFERENCE STATIC_FIELD_DECLARATION STATIC_GETTER_DECLARATION STATIC_GETTER_REFERENCE STATIC_METHOD_DECLARATION STATIC_METHOD_REFERENCE STATIC_SETTER_DECLARATION STATIC_SETTER_REFERENCE TOP_LEVEL_FUNCTION_DECLARATION TOP_LEVEL_FUNCTION_REFERENCE TOP_LEVEL_GETTER_DECLARATION TOP_LEVEL_GETTER_REFERENCE TOP_LEVEL_SETTER_DECLARATION TOP_LEVEL_SETTER_REFERENCE TOP_LEVEL_VARIABLE_DECLARATION TYPE_NAME_DYNAMIC TYPE_PARAMETER UNRESOLVED_INSTANCE_MEMBER_REFERENCE VALID_STRING_ESCAPE

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 name of the target to which the user can navigate.

int

The length of the name of the target to which the user can navigate.

int

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

int

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

int

The offset of the target code to which the user can navigate.

int

The length of the target code to which the user can navigate.

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.

int

The offset of the first character of the element code, which is neither documentation, nor annotation.

int

The length of the element code.

Outline

The children of the node. The field will be omitted if the node has no children. Children are sorted by offset.

A description of a member that is being overridden.

ParameterKind

The kind of the parameter.

String

The name of the parameter.

String

The type of the parameter.

String

The default value for this parameter. This value will be omitted if the parameter does not have a default value.

An enumeration of the types of parameters.

OPTIONAL_NAMED

An optional named parameter.

OPTIONAL_POSITIONAL

An optional positional parameter.

REQUIRED_NAMED

A required named parameter.

REQUIRED_POSITIONAL

A required positional parameter.

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 EXTRACT_WIDGET INLINE_LOCAL_VARIABLE INLINE_METHOD MOVE_FILE RENAME

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.