Skip to content

lsif.md

Latest commit

 

History

History
224 lines (145 loc) · 10.1 KB

lsif.md

File metadata and controls

224 lines (145 loc) · 10.1 KB

LSIF Typed protocol reference

Descriptor

Name Type Description
name string
disambiguator string
suffix Suffix

Suffix

Number Name Description
0 UnspecifiedSuffix
1 Package
2 Type
3 Term
4 Method
5 TypeParameter
6 Parameter
7 Meta Can be used for any purpose.
8 Local

Diagnostic

Represents a diagnostic, such as a compiler error or warning, which should be reported for a document.

Name Type Description
severity Severity Should this diagnostic be reported as an error, warning, info, or hint?
code string Code of this diagnostic, which might appear in the user interface.
message string Message of this diagnostic.
source string Human-readable string describing the source of this diagnostic, e.g. 'typescript' or 'super lint'.
repeated tags DiagnosticTag

Document

Document defines the metadata about a source file on disk.

Name Type Description
relative_path string (Required) Path to the text document relative to the directory supplied in the associated Metadata.project_root. Not URI-encoded. This value should not begin with a directory separator.
repeated occurrences Occurrence Occurrences that appear in this file.
repeated symbols SymbolInformation Symbols that are defined within this document.

Index

Index represents a complete LSIF index for a workspace this is rooted at a single directory. An Index message payload can have a large memory footprint and it's therefore recommended to emit and consume an Index payload one field value at a time. To permit streaming consumption of an Index payload, the metadata field must appear at the start of the stream and must only appear once in the stream. Other field values may appear in any order.

Name Type Description
metadata Metadata Metadata about this index.
repeated documents Document Documents that belong to this index.
repeated external_symbols SymbolInformation (optional) Symbols that are referenced from this index but are defined in an external package (a separate Index message). Leave this field empty if you assume the external package will get indexed separately. If the external package won't get indexed for some reason then you can use this field to provide hover documentation for those external symbols.

Metadata

Name Type Description
version ProtocolVersion Which version of this protocol was used to generate this index?
tool_info ToolInfo Information about the tool that produced this index.
project_root string URI-encoded absolute path to the root directory of this index. All documents in this index must appear in a subdirectory of this root directory.
text_document_encoding TextEncoding Text encoding of the source files on disk that are referenced from Document.relative_path.

Occurrence

Occurrence associates a source position with a symbol and/or highlighting information.

Name Type Description
repeated range int32 Source position of this occurrence. Must be exactly three or four elements:
symbol string (optional) The symbol that appears at this position. See SymbolInformation.symbol for how to format symbols as strings.
symbol_roles int32 (optional) Bitmask for what SymbolRole apply to this occurrence. See SymbolRole for how to read and write this field.
repeated override_documentation string (optional) Markdown-formatted documentation for this specific range. If empty, the Symbol.documentation field is used instead. One example where this field might be useful is when the symbol represents a generic function (with abstract type parameters such as List<T>) and at this occurrence we know the exact values (such as List<String>).
syntax_kind SyntaxKind (optional) What syntax highlighting class should be used for this range?
repeated diagnostics Diagnostic Diagnostics that have been reported for this specific range.

Additional notes on range:

Source position of this occurrence. Must be exactly three or four elements:

  • Four elements: [startLine, startCharacter, endLine, endCharacter]
  • Three elements: [startLine, startCharacter, endCharacter]. The end line is inferred to have the same value as the start line.

Line numbers and characters are always 0-based. Make sure to increment the line/character values before displaying them in an editor-like UI because editors conventionally use 1-based numbers.

Historical note: the original draft of this schema had a Range message type with start and end fields of type Position, mirroring LSP. Benchmarks revealed that this encoding was inefficient and that we could reduce the total payload size of an index by 50% by using repeated int32 instead. The repeated int32 encoding is admittedly more embarrassing to work with in some programming languages but we hope the performance improvements make up for it.

Package

Name Type Description
manager string
name string
version string

Relationship

Name Type Description
symbol string
is_reference bool When resolving "Find references", this field documents what other symbols should be included together with this symbol. For example, consider the following TypeScript code that defines two symbols Animal#sound() and Dog#sound(): ts interface Animal { ^^^^^^ definition Animal# sound(): string ^^^^^ definition Animal#sound() } class Dog implements Animal { ^^^ definition Dog#, implementation_symbols = Animal# public sound(): string { return "woof" } ^^^^^ definition Dog#sound(), references_symbols = Animal#sound(), implementation_symbols = Animal#sound() } const animal: Animal = new Dog() ^^^^^^ reference Animal# console.log(animal.sound()) ^^^^^ reference Animal#sound() Doing "Find references" on the symbol Animal#sound() should return references to the Dog#sound() method as well. Vice-versa, doing "Find references" on the Dog#sound() method should include references to the Animal#sound() method as well.
is_implementation bool Similar to references_symbols but for "Go to implementation". It's common for the implementation_symbols and references_symbols fields have the same values but that's not always the case. In the TypeScript example above, observe that implementation_symbols has the value "Animal#" for the "Dog#" symbol while references_symbols is empty. When requesting "Find references" on the "Animal#" symbol we don't want to include references to "Dog#" even if "Go to implementation" on the "Animal#" symbol should navigate to the "Dog#" symbol.
is_type_definition bool Similar to references_symbols but for "Go to type definition".

Symbol

Symbol is similar to a URI, it identifies a class, method, or a local variable. SymbolInformation contains rich metadata about symbols such as the docstring.

Symbol has a standardized string representation, which can be used interchangeably with Symbol. The syntax for Symbol is the following:

  <symbol>               ::= <scheme> ' ' <package> ' ' { <descriptor> } | 'local ' <local-id>
  <package>              ::= <manager> ' ' <package-name> ' ' <version>
  <scheme>               ::= any UTF-8, escape spaces with double space.
  <manager>              ::= same as above, use the placeholder '.' to indicate an empty value
  <package-name>         ::= same as above
  <version>              ::= same as above
  <descriptor>           ::= <package> | <type> | <term> | <method> | <type-parameter> | <parameter> | <meta>
  <package>              ::= <name> '/'
  <type>                 ::= <name> '#'
  <term>                 ::= <name> '.'
  <meta>                 ::= <name> ':'
  <method>               ::= <name> '(' <method-disambiguator> ').'
  <type-parameter>       ::= '[' <name> ']'
  <parameter>            ::= '(' <name> ')'
  <name>                 ::= <identifier>
  <method-disambiguator> ::= <simple-identifier>
  <identifier>           ::= <simple-identifier> | <escaped-identifier>
  <simple-identifier>    ::= { <identifier-character> }
  <identifier-character> ::= '_' | '+' | '-' | '$' | ASCII letter or digit
  <escaped-identifier>   ::= '`' { <escaped-character> } '`'
  <escaped-characters>   ::= any UTF-8 character, escape backticks with double backtick.
Name Type Description
scheme string
package Package
repeated descriptors Descriptor

SymbolInformation

SymbolInformation defines metadata about a symbol, such as the symbol's docstring or what package it's defined it.

Name Type Description
symbol string Identifier of this symbol, which can be referenced from Occurence.symbol. The string must be formatted according to the grammar in Symbol.
repeated documentation string (optional, but strongly recommended) The markdown-formatted documentation for this symbol. This field is repeated to allow different kinds of documentation. For example, it's nice to include both the signature of a method (parameters and return type) along with the accompanying docstring.
repeated relationships Relationship (optional) Relationships to other symbols (e.g., implements, type definition).

ToolInfo

Name Type Description
name string Name of the indexer that produced this index.
version string Version of the indexer that produced this index.
repeated arguments string Command-line arguments that were used to invoke this indexer.