glean/glass/if/glass.thrift (265 lines of code) (raw):
/*
* Copyright (c) Meta Platforms, Inc. and affiliates.
* All rights reserved.
*
* This source code is licensed under the BSD-style license found in the
* LICENSE file in the root directory of this source tree.
*/
include "glean/github/if/fb303.thrift"
include "glean/if/index.thrift"
namespace hs Glean
namespace hack GleanGlass
namespace py3 glean
namespace cpp2 glean
// request types
// Repositories are referred to by their SCS repo names
typedef string RepoName (hs.newtype)
// The UTF-8 path of a file relative to the source control root
typedef string Path (hs.newtype)
// Unique revision identifier (repo-wide unique id)
typedef string Revision (hs.newtype)
// A line range in the file to restrict the query. start should be <= end, and
// range is inclusive of end.
struct LineRange {
// 1-based line index
1: i64 lineBegin (hs.strict);
// end line index, range is inclusive
2: i64 lineEnd (hs.strict);
}
// Resolved symbol range in a file, using line/column locators.
// lines and columns are 1-indexed.
struct Range {
1: i64 lineBegin (hs.strict);
2: i64 columnBegin (hs.strict);
3: i64 lineEnd (hs.strict);
4: i64 columnEnd (hs.strict);
}
// Accurate byte ranges of symbols (can be resolved to Ranges)
struct ByteSpan {
1: i64 start (hs.strict);
2: i64 length (hs.strict);
}
// An universal, unresolved symbol location.
struct Location {
// The repository it is defined in
1: RepoName repository;
// the filepath in that repository
2: Path filepath;
// unresolved bytespan location in file
3: ByteSpan span (hs.strict);
}
// An universal, resolved symbol location.
struct LocationRange {
// The repository it is defined in
1: RepoName repository;
// the filepath in that repository
2: Path filepath;
// resolved line/column ranges in file
3: Range range (hs.strict);
}
// Generic request options, supported by most calls
struct RequestOptions {
// repo-global revision identifier, otherwise latest index
1: optional Revision revision;
// maximum results to return.
2: optional i32 limit;
}
// List symbols in a file. Symbols are spans of one or more tokens Glean has
// information on (e.g. references, declarations, ..)
struct DocumentSymbolsRequest {
// SCS repo name (n.b not old style arcanist)
1: RepoName repository;
// UTF-8 path to file in repo relative to source control repo root
2: Path filepath;
// Limit results to this line range in file
3: optional list<LineRange> range;
// include references?
4: bool include_refs = true;
}
// response types
// Human-readable opaque, stable, globally unique symbol identifier
typedef string SymbolId (hs.newtype)
// Type of attributes associated with a symbol.
union Attribute {
1: bool aBool;
2: i64 aInteger;
3: double aDouble;
4: string aString;
5: list<string> aList;
}
// Symbol attributes, keyed by attribute name
typedef map<string, Attribute> Attributes (hs.newtype)
// For clients that can't process maps, use an assoc list for attributes
struct KeyedAttribute {
1: string key;
2: Attribute attribute;
}
// For clients that can't process maps, use an assoc list for attributes
typedef list<KeyedAttribute> AttributeList (hs.newtype)
// Reference symbols. These are use sites that point to their definition
struct ReferenceRangeSymbolX {
// a symbol id to its definition
1: SymbolId sym;
// local line:col spans in this file
2: Range range (hs.strict);
// this points to the (unresolved) definition site
3: LocationRange target;
// attributes of this reference
4: AttributeList attributes;
// this points to an optional name range of the `target` rather than
// the full definition. the range is assumed to be in the same
// `repository` and `filepath` as the `target` field.
5: optional Range targetName;
}
// a definition symbol
struct DefinitionSymbolX {
// a stable name for the definition
1: SymbolId sym;
// the resolved local line:col spans in this file
2: Range range (hs.strict);
// attributes of this definition
3: AttributeList attributes;
// the resolved local line:col spans of the symbol name in this file
4: optional Range nameRange (hs.strict);
}
// sometimes we prefer to combine all symbols in a file, for use later
struct SymbolX {
// A stable name for the definition of this symbol
1: SymbolId sym;
// the resolved local line:col spans in this file
2: Range range (hs.strict);
// if this is a reference, it will point to its definition
3: optional LocationRange target;
// additional metadata associated with the symbol
4: Attributes attributes;
// the resolved local line:col spans of the symbol name in this file
5: optional Range nameRange (hs.strict);
// if this is a reference, it will point to the name of its definition
6: optional Range targetName;
}
// Path-based symbol identifer. This is less stable than an SymbolId, and is
// stable only for a given revision. However, it is precise and efficient, in
// that it will uniquely map to an entity in the underlying database, without
// requiring search.
//
// (dons: how is this different to LocationRange?)
//
struct SymbolPath {
// The repository it is defined in
1: RepoName repository;
// the filepath in that repository
2: Path filepath;
// the resolved local line:col spans in this file
3: Range range (hs.strict);
}
// A list of known symbols in the file, their locations, and their keys
// with all locations resolved to line/column ranges, and attributes
struct DocumentSymbolListXResult {
// references that appear in this file
1: list<ReferenceRangeSymbolX> references;
// definitions in this file
2: list<DefinitionSymbolX> definitions;
// actual revision used for results
3: Revision revision;
}
// For cursor navigation in a file, it is useful to have a line indexed
// map of symbols (to quickly find token under cursor)
struct DocumentSymbolIndex {
// all symbols present in this file, 1-indexed by line.
1: map<i64, list<SymbolX>> symbols;
// actual revision used for results
2: Revision revision;
// count of unique symbols in the map
3: i64 size (hs.strict);
}
// Generic server exception
exception ServerException {
1: string message;
}
// Type of abstract identifiers
typedef string Name (hs.newtype)
// A pair of names, usually a scope or qualified name and local identifier
struct QualifiedName {
1: Name localName;
2: Name container;
}
// Annotations/Attributes/Decorators/Directives attach metadata to definitions in source code
struct Annotation {
1: string source; // the annotation as it appears in the source code
2: optional SymbolId symbol; // the symbol of the annotation
3: string name;
}
enum Visibility {
Public = 20,
Protected = 30,
Private = 40,
}
// A symbol description extends the symbol id with additional attributes
struct SymbolDescription {
1: SymbolId sym;
2: SymbolPath location;
3: QualifiedName name;
4: optional SymbolKind kind;
5: optional list<Annotation> annotations;
6: list<LocationRange> comments;
7: optional Visibility visibility;
8: string repo_hash;
}
struct SearchContext {
1: optional RepoName repo_name;
2: optional Language language;
4: set<SymbolKind> kinds;
}
// tags for symbol kinds, so clients can distinguish them
enum SymbolKind {
Package = 1,
Type = 2,
Value = 3,
File = 4,
Module = 5,
Namespace = 6,
Class_ = 7,
Method = 8,
Property = 9,
Field = 10,
Constructor = 11,
Enum = 12,
Interface = 13,
Function = 14,
Variable = 15,
Constant = 16,
String = 17,
Number = 18,
Boolean = 19,
Array = 20,
Object = 21,
Key = 22,
Null = 23,
Enumerator = 24,
Struct = 25,
Event = 26,
Operator = 27,
TypeParameter = 28,
Union = 29,
Macro = 30,
} (
hack.attributes = "\GraphQLEnum('GlassSymbolKind'), \RelayFlowEnum, \SelfDescriptive, \Oncalls('code_indexing')",
)
enum Language {
Cpp = 1,
JavaScript = 2,
Hack = 3,
Haskell = 4,
Java = 5,
ObjectiveC = 6,
Python = 7,
PreProcessor = 8,
Thrift = 9,
Rust = 10,
Buck = 11,
Erlang = 12,
} (
hack.attributes = "\GraphQLEnum('GlassLanguage'), \RelayFlowEnum, \SelfDescriptive, \Oncalls('code_indexing')",
)
// Kinds of definitions. E.g. for jump-to-declaration or jump-to-definition
enum DefinitionKind {
Definition = 1,
Declaration = 2,
} (
hack.attributes = "\GraphQLEnum('GlassDefinitionKind'), \SelfDescriptive, \Oncalls('code_indexing')",
)
struct SearchByNameRequest {
1: SearchContext context;
2: string name;
3: bool detailedResults; // fill out symbol_details in the response
4: bool ignoreCase = false;
}
struct SearchByNameResult {
1: list<SymbolId> symbols;
2: list<SymbolDescription> symbolDetails;
}
struct SearchBySymbolIdResult {
1: list<SymbolId> symbols;
}
enum RelationType {
Extends = 1, // OOP inheritance
Contains = 2, // Syntactically nested (usually)
}
enum RelationDirection {
Parent = 1,
Child = 2,
}
struct SearchRelatedRequest {
1: RelationType relatedBy;
2: RelationDirection relation;
3: bool recursive; // Not just directly related entities
4: optional set<SymbolKind> filter; //return only these symbols of these kinds
}
// Consider capping the number of symbols in a single angle query before increasing this number
const i32 RELATED_SYMBOLS_MAX_LIMIT = 100;
struct RelatedSymbols {
1: SymbolId parent;
2: SymbolId child;
}
struct SearchRelatedResult {
1: list<RelatedSymbols> edges;
}
// Glass symbol service
service GlassService extends fb303.FacebookService {
// Return a list of symbols in the given file, with attributes
DocumentSymbolListXResult documentSymbolListX(
1: DocumentSymbolsRequest request,
2: RequestOptions options,
) throws (1: ServerException e);
// Return a line-index map of resolved symbols, useful for cursor lookup
DocumentSymbolIndex documentSymbolIndex(
1: DocumentSymbolsRequest request,
2: RequestOptions options,
) throws (1: ServerException e);
// Resolve a location span to a concrete line:col range in a file
Range jumpTo(1: Location reference, 2: RequestOptions options) throws (
1: ServerException e,
);
// Find any uses of a definition, generically
list<Location> findReferences(
1: SymbolId symbol,
2: RequestOptions options,
) throws (1: ServerException e);
// Find any uses of a definition, resolving all locations to line/col ranges
list<LocationRange> findReferenceRanges(
1: SymbolId symbol,
2: RequestOptions options,
) throws (1: ServerException e);
// Resolve a symbol id to its definition location
Location resolveSymbol(1: SymbolId symbol, 2: RequestOptions options) throws (
1: ServerException e,
);
// Return basic details about a symbol, a bit more than resolveSymbol
SymbolDescription describeSymbol(
1: SymbolId symbol,
2: RequestOptions options,
) throws (1: ServerException e);
// Find symbol ids based on exact local name
// (e.g. Glean)
SearchByNameResult searchByName(
1: SearchByNameRequest request,
3: RequestOptions options,
) throws (1: ServerException e);
// Find symbol ids based on local name prefix
// (e.g. Glea)
SearchByNameResult searchByNamePrefix(
1: SearchByNameRequest request,
2: RequestOptions options,
) throws (1: ServerException e);
// Find symbol ids based on the prefix of a full symbol id
// (e.g. www/php/Gl)
SearchBySymbolIdResult searchBySymbolId(
1: SymbolId symbol_prefix,
2: RequestOptions options,
) throws (1: ServerException e);
SearchRelatedResult searchRelated(
1: SymbolId symbol,
2: RequestOptions options,
3: SearchRelatedRequest request,
) throws (1: ServerException e);
// Trigger the creation of an incremental database based on file changes
// relative to an indexed revision
index.IndexResponse index(1: index.IndexRequest request) throws (
1: ServerException e,
);
}