/** * ## The Sourcegraph extension API * * Sourcegraph extensions enhance your code host, code reviews, and Sourcegraph itself by adding features such as: * - Code navigation (go-to-definition, find references, hovers, etc.) * - Test coverage overlays * - Links to live traces, log output, and performance data for a line of code * - Git blame * - Usage examples for functions */ declare module 'sourcegraph' { export interface Unsubscribable { unsubscribe(): void } /** * @deprecated Use the global [native `URL` API](https://developer.mozilla.org/en-US/docs/Web/API/URL) */ export const URI: typeof URL /** * @deprecated Use the global [native `URL` API](https://developer.mozilla.org/en-US/docs/Web/API/URL) */ export type URI = URL export class Position { /** Zero-based line number. */ readonly line: number /** Zero-based character on the line. */ readonly character: number /** * Constructs a Position from a line and character. * * @param line A zero-based line value. * @param character A zero-based character value. */ constructor(line: number, character: number) /** * Check if this position is before `other`. * * @param other A position. * @returns `true` if position is on a smaller line * or on the same line on a smaller character. */ isBefore(other: Position): boolean /** * Check if this position is before or equal to `other`. * * @param other A position. * @returns `true` if position is on a smaller line * or on the same line on a smaller or equal character. */ isBeforeOrEqual(other: Position): boolean /** * Check if this position is after `other`. * * @param other A position. * @returns `true` if position is on a greater line * or on the same line on a greater character. */ isAfter(other: Position): boolean /** * Check if this position is after or equal to `other`. * * @param other A position. * @returns `true` if position is on a greater line * or on the same line on a greater or equal character. */ isAfterOrEqual(other: Position): boolean /** * Check if this position is equal to `other`. * * @param other A position. * @returns `true` if the line and character of the given position are equal to * the line and character of this position. */ isEqual(other: Position): boolean /** * Compare this to `other`. * * @param other A position. * @returns A number smaller than zero if this position is before the given position, * a number greater than zero if this position is after the given position, or zero when * this and the given position are equal. */ compareTo(other: Position): number /** * Create a new position relative to this position. * * @param lineDelta Delta value for the line value, default is `0`. * @param characterDelta Delta value for the character value, default is `0`. * @returns A position which line and character is the sum of the current line and * character and the corresponding deltas. */ translate(lineDelta?: number, characterDelta?: number): Position /** * Derived a new position relative to this position. * * @param change An object that describes a delta to this position. * @returns A position that reflects the given delta. Will return `this` position if the change * is not changing anything. */ translate(change: { lineDelta?: number; characterDelta?: number }): Position /** * Create a new position derived from this position. * * @param line Value that should be used as line value, default is the [existing value](#Position.line) * @param character Value that should be used as character value, default is the [existing value](#Position.character) * @returns A position where line and character are replaced by the given values. */ with(line?: number, character?: number): Position /** * Derived a new position from this position. * * @param change An object that describes a change to this position. * @returns A position that reflects the given change. Will return `this` position if the change * is not changing anything. */ with(change: { line?: number; character?: number }): Position } /** * A range represents an ordered pair of two positions. * It is guaranteed that [start](#Range.start).isBeforeOrEqual([end](#Range.end)) * * Range objects are __immutable__. Use the [with](#Range.with), * [intersection](#Range.intersection), or [union](#Range.union) methods * to derive new ranges from an existing range. */ export class Range { /** * The start position. It is before or equal to [end](#Range.end). */ readonly start: Position /** * The end position. It is after or equal to [start](#Range.start). */ readonly end: Position /** * Create a new range from two positions. If `start` is not * before or equal to `end`, the values will be swapped. * * @param start A position. * @param end A position. */ constructor(start: Position, end: Position) /** * Create a new range from number coordinates. It is a shorter equivalent of * using `new Range(new Position(startLine, startCharacter), new Position(endLine, endCharacter))` * * @param startLine A zero-based line value. * @param startCharacter A zero-based character value. * @param endLine A zero-based line value. * @param endCharacter A zero-based character value. */ constructor(startLine: number, startCharacter: number, endLine: number, endCharacter: number) /** * `true` if `start` and `end` are equal. */ isEmpty: boolean /** * `true` if `start.line` and `end.line` are equal. */ isSingleLine: boolean /** * Check if a position or a range is contained in this range. * * @param positionOrRange A position or a range. * @returns `true` if the position or range is inside or equal * to this range. */ contains(positionOrRange: Position | Range): boolean /** * Check if `other` equals this range. * * @param other A range. * @returns `true` when start and end are [equal](#Position.isEqual) to * start and end of this range. */ isEqual(other: Range): boolean /** * Intersect `range` with this range and returns a new range or `undefined` * if the ranges have no overlap. * * @param range A range. * @returns A range of the greater start and smaller end positions. Will * return undefined when there is no overlap. */ intersection(range: Range): Range | undefined /** * Compute the union of `other` with this range. * * @param other A range. * @returns A range of smaller start position and the greater end position. */ union(other: Range): Range /** * Derived a new range from this range. * * @param start A position that should be used as start. The default value is the [current start](#Range.start). * @param end A position that should be used as end. The default value is the [current end](#Range.end). * @returns A range derived from this range with the given start and end position. * If start and end are not different `this` range will be returned. */ with(start?: Position, end?: Position): Range /** * Derived a new range from this range. * * @param change An object that describes a change to this range. * @returns A range that reflects the given change. Will return `this` range if the change * is not changing anything. */ with(change: { start?: Position; end?: Position }): Range } /** * Represents a text selection in an editor. */ export class Selection extends Range { /** * The position at which the selection starts. * This position might be before or after [active](#Selection.active). */ anchor: Position /** * The position of the cursor. * This position might be before or after [anchor](#Selection.anchor). */ active: Position /** * Create a selection from two positions. * * @param anchor A position. * @param active A position. */ constructor(anchor: Position, active: Position) /** * Create a selection from four coordinates. * * @param anchorLine A zero-based line value. * @param anchorCharacter A zero-based character value. * @param activeLine A zero-based line value. * @param activeCharacter A zero-based character value. */ constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number) /** * A selection is reversed if [active](#Selection.active).isBefore([anchor](#Selection.anchor)). */ isReversed: boolean } /** * Represents a location inside a resource, such as a line * inside a text file. */ export class Location { /** * The resource identifier of this location. */ readonly uri: URL /** * The document range of this location. */ readonly range?: Range /** * Creates a new location object. * * @param uri The resource identifier. * @param rangeOrPosition The range or position. Positions will be converted to an empty range. */ constructor(uri: URL, rangeOrPosition?: Range | Position) } /** * A text document, such as a file in a repository. */ export interface TextDocument { /** * The URI of the text document. */ readonly uri: string /** * The language of the text document. */ readonly languageId: string /** * The text contents of the text document. * * When using the [Sourcegraph browser * extension](https://sourcegraph.com/docs/integration/browser_extension), the value is * `undefined` because determining the text contents (in general) is not possible without * additional access to the code host API. In the future, this limitation may be removed. */ readonly text: string | undefined /** * Convert the position to a zero-based offset. * * The position will be adjusted using {@link TextDocument#validatePosition}. * * @param position A position. * @returns A valid zero-based offset. * @throws if {@link TextDocument#text} is undefined. */ offsetAt(position: Position): number /** * Convert a zero-based offset to a position. * * @param offset A zero-based offset. * @returns A valid {@link Position}. * @throws if {@link TextDocument#text} is undefined. */ positionAt(offset: number): Position /** * Ensure a position is contained in the range of this document. If not, adjust it so that * it is. * * @param position A position. * @returns The given position or a new, adjusted position. * @throws if {@link TextDocument#text} is undefined. */ validatePosition(position: Position): Position /** * Ensure a range is completely contained in this document. * * @param range A range. * @returns The given range or a new, adjusted range. * @throws if {@link TextDocument#text} is undefined. */ validateRange(range: Range): Range /** * Get the range of the word at the given position. * * The position will be adjusted using {@link TextDocument#validatePosition}. * * @param position A position. * @returns A range spanning a word, or `undefined`. */ getWordRangeAtPosition(position: Position): Range | undefined /** * Get the substring of text content from the provided range. * * @param range A range * @returns The text inside the provided range, or the whole text if no range is provided */ getText(range?: Range): string | undefined } /** * A document filter denotes a document by different properties like the * [language](#TextDocument.languageId), the scheme of its resource, or a glob-pattern that is * applied to the [path](#TextDocument.fileName). * A document filter matches if all the provided properties (those of `language`, `scheme` and `pattern` that are not `undefined`) match. * If all properties are `undefined`, the document filter matches all documents. * * Examples: * ```ts * // A language filter that applies to typescript files on disk * { language: 'typescript', scheme: 'file' } * * // A language filter that applies to all package.json paths * { language: 'json', pattern: '**package.json' } * ``` */ export interface DocumentFilter { /** A language id, such as `typescript` or `*`. */ language?: string /** A URI scheme, such as `file` or `untitled`. */ scheme?: string /** A glob pattern, such as `*.{ts,js}`. */ pattern?: string /** A base URI (e.g. root URI of a workspace folder) that the document must be within. */ baseUri?: URL | string } /** * A document selector is the combination of one or many document filters. * A document matches the selector if any of the given filters matches. * If the filter is a string and not a {@link DocumentFilter}, it will be treated as a language id. * * @example let sel: DocumentSelector = [{ language: 'typescript' }, { language: 'json', pattern: '**∕tsconfig.json' }]; */ export type DocumentSelector = (string | DocumentFilter)[] /** * A window in the client application that is running the extension. */ export interface Window { /** * The user interface view components that are visible in the window. */ visibleViewComponents: ViewComponent[] /** * The currently active view component in the window. */ activeViewComponent: ViewComponent | undefined /** * An event that is fired when the active view component changes. */ activeViewComponentChanges: Subscribable } /** * A user interface component in an application window. * * Each {@link ViewComponent} has a distinct {@link ViewComponent#type} value that indicates what kind of * component it is ({@link CodeEditor}, etc.). */ export type ViewComponent = CodeEditor | DirectoryViewer export interface Directory { /** * The URI of the directory. * * @todo The format of this URI will be changed in the future. It must not be relied on. */ readonly uri: URL } /** * A viewer for directories. * * This API is experimental and subject to change. */ export interface DirectoryViewer { readonly type: 'DirectoryViewer' /** * The directory shown in the directory viewer. * This currently only exposes the URI of the directory. */ readonly directory: Directory } /** * A text editor for code files (as opposed to a rich text editor for documents or other kinds of file format * editors). */ export interface CodeEditor { /** The type tag for this kind of {@link ViewComponent}. */ readonly type: 'CodeEditor' /** The internal ID of this code editor. */ /** * The text document that is open in this editor. The document remains the same for the entire lifetime of * this editor. */ readonly document: TextDocument /** * The primary selection in this text editor. This is equivalent to `CodeEditor.selections[0] || null`. * * @todo Make this non-readonly. */ readonly selection: Selection | null /** * The selections in this text editor. A text editor has zero or more selections. The primary selection * ({@link CodeEditor#selection}), if any selections exist, is always at index 0. * * @todo Make this non-readonly. */ readonly selections: Selection[] /** * An event that is fired when the selections in this text editor change. * The primary selection ({@link CodeEditor#selection}), if any selections exist, * is always at index 0 of the emitted array. */ readonly selectionsChanges: Subscribable } /** * A panel view created by {@link sourcegraph.app.createPanelView}. */ export interface PanelView extends Unsubscribable { /** * The title of the panel view. */ title: string /** * The content to show in the panel view. Markdown is supported. */ content: string /** * The priority of this panel view. A higher value means that the item is shown near the beginning (usually * the left side). */ priority: number /** * Display the results of the location provider (with the given ID) in * this panel below the {@link PanelView#contents}. If * maxLocationResults is set, then only maxLocationResults will be shown * in the panel. * * Experimental. Subject to change or removal without notice. * * @internal */ component: { locationProvider: string; maxLocationResults?: number } | null /** * A selector that defines the documents this panel is applicable to. */ selector: DocumentSelector | null } export type ChartContent = LineChartContent | BarChartContent | PieChartContent export interface ChartAxis { /** The key in the data object. */ dataKey: K /** The scale of the axis. */ scale?: 'time' | 'linear' /** The type of the data key. */ type: 'number' | 'category' } export interface LineChartContent { chart: 'line' /** An array of data objects, with one element for each step on the X axis. */ data: D[] /** The series (lines) of the chart. */ series: LineChartSeries[] xAxis: ChartAxis } export interface LineChartSeries { /** The key in each data object for the values this line should be calculated from. */ dataKey: keyof D /** The name of the line shown in the legend and tooltip. */ name?: string /** * The link URLs for each data point. * A link URL should take the user to more details about the specific data point. */ linkURLs?: Record | string[] /** The CSS color of the line. */ stroke?: string } export interface BarChartContent { chart: 'bar' /** An array of data objects, with one element for each step on the X axis. */ data: D[] /** The series of the chart. */ series: { /** The key in each data object for the values this bar should be calculated from. */ dataKey: keyof D /** * An optional stack id of each bar. * When two bars have the same same `stackId`, the two bars are stacked in order. */ stackId?: string /** The name of the series, shown in the legend. */ name?: string /** * The link URLs for each bar. * A link URL should take the user to more details about the specific data point. */ linkURLs?: string[] /** The CSS fill color of the line. */ fill?: string }[] xAxis: ChartAxis } export interface PieChartContent { chart: 'pie' pies: { /** The key of each sector's va lue. */ dataKey: keyof D /** The key of each sector's name. */ nameKey: keyof D /** The key of each sector's fill color. */ fillKey?: keyof D /** An array of data objects, with one element for each pie sector. */ data: D[] /** T he key of each sector's link URL. */ linkURLKey?: keyof D }[] } /** * A view is a page or partial page. */ export interface View { /** The title of the view. */ title: string /** An optional subtitle displayed under the title. */ subtitle?: string /** * The content sections of the view. The sections are rendered in order. * * Support for non-MarkupContent elements is experimental and subject to change or removal * without notice. */ content: ( | MarkupContent | ChartContent | { component: string; props: { [name: string]: string | number | boolean | null | undefined } } )[] } /** * A view provider registered with {@link sourcegraph.app.registerViewProvider}. */ export type ViewProvider = | InsightsPageViewProvider | HomepageViewProvider | GlobalPageViewProvider | DirectoryViewProvider /** * Experimental view provider shown on the dashboard on the insights page. * This API is experimental and is subject to change or removal without notice. */ export interface InsightsPageViewProvider { readonly where: 'insightsPage' /** * Provide content for the view. */ provideView(context: {}): ProviderResult } /** * Experimental view provider shown on the homepage (below the search box in the Sourcegraph web app). * This API is experimental and is subject to change or removal without notice. */ export interface HomepageViewProvider { readonly where: 'homepage' /** * Provide content for the view. */ provideView(context: {}): ProviderResult } /** * Experimental global view provider. Global view providers are shown on a dedicated page in the app. * This API is experimental and is subject to change or removal without notice. */ export interface GlobalPageViewProvider { readonly where: 'global/page' /** * Provide content for the view. * * @param params Parameters from the page (such as URL query parameters). The schema of these parameters is * experimental and subject to change without notice. * @returns The view content. */ provideView(context: { [param: string]: string }): ProviderResult } /** * Context passed to directory view providers. * * The schema of these parameters is experimental and subject to change without notice. */ export interface DirectoryViewContext { /** The directory viewer displaying the view. */ viewer: DirectoryViewer /** The workspace of the directory. */ workspace: WorkspaceRoot } /** * Experimental view provider for directory pages. * This API is experimental and is subject to change or removal without notice. */ export interface DirectoryViewProvider { readonly where: 'directory' /** * Provide content for a view. * * @param context The context of the directory. The schema of these parameters is experimental and subject to * change without notice. * @returns The view content. */ provideView(context: DirectoryViewContext): ProviderResult } /** * The client application that is running the extension. */ export namespace app { /** * The currently active window, or `undefined`. The active window is the window that has focus, or when * none has focus, the window that was most recently focused. */ export const activeWindow: Window | undefined /** * An event that is fired when the currently active window changes. */ export const activeWindowChanges: Subscribable /** * All application windows that are accessible by the extension. * * @readonly */ export const windows: Window[] /** * Log a message to the console if logs for the extension are enabled in user settings. * * Messages are automatically prefixed by the extension's ID. * * Note that messages may be transferred via the structured clone algorithm. Ensure that your messages are * [cloneable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm#things_that_dont_work_with_structured_clone) */ export function log(message?: any, ...optionalParams: any[]): void } /** * A workspace root is a directory that has been added to a workspace. A workspace can have zero or more roots. * Often, each root is the root directory of a repository. */ export interface WorkspaceRoot { /** * The URI of the root. * * @todo The format of this URI will be changed in the future. It must not be relied on. * * @example git://github.com/sourcegraph/sourcegraph?sha#mydir1/mydir2 */ readonly uri: URL } /** * The logical workspace that the extension is running in, which may consist of multiple folders, projects, and * repositories. */ export namespace workspace { /** * All text documents currently known to the system. * * @readonly */ export const textDocuments: TextDocument[] /** * An event that is fired when a new text document is opened. * * @deprecated Renamed to {@link workspace.openedTextDocuments}. */ export const onDidOpenTextDocument: Subscribable /** * An event that is fired when a new text document is opened. */ export const openedTextDocuments: Subscribable /** * The root directories of the workspace, if any. * * @example The repository that is currently being viewed is a root. * @todo Currently only a single root is supported. * @readonly */ export const roots: readonly WorkspaceRoot[] /** * An event that is fired when a workspace root is added or removed from the workspace. * * @deprecated Renamed to {@link workspace.rootsChanges}. */ export const onDidChangeRoots: Subscribable /** * An event that is fired when a workspace root is added or removed from the workspace. */ export const rootChanges: Subscribable /** * The current version context of the workspace, if any. * * A version context is a set of repositories and revisions on a Sourcegraph instance. * When set, extensions use it to scope search queries, code navigation actions, etc. * * See more information at http://sourcegraph.com/docs/user/search * * @deprecated */ export const versionContext: string | undefined /** * An event that is fired when a workspace's version context changes. * * @deprecated */ export const versionContextChanges: Subscribable /** * The current search context of the workspace, if any. * * A search context is a set of repositories and revisions on a Sourcegraph instance. * When set, extensions use it to scope search queries, code navigation actions, etc. * * See more information at https://sourcegraph.com/docs/code-search/features#search-contexts */ export const searchContext: string | undefined /** * An event that is fired when a workspace's search context changes. */ export const searchContextChanges: Subscribable } /** * The full configuration value, containing all settings for the current subject. * * @template C The configuration schema. */ export interface Configuration { /** * Returns a value at a specific key in the configuration. * * @template C The configuration schema. * @template K Valid key on the configuration object. * @param key The name of the configuration property to get. * @returns The configuration value, or `undefined`. */ get(key: K): Readonly | undefined /** * Updates the configuration value for the given key. The updated configuration value is persisted by the * client. * * @template C The configuration schema. * @template K Valid key on the configuration object. * @param key The name of the configuration property to update. * @param value The new value, or undefined to remove it. * @returns A promise that resolves when the client acknowledges the update. */ update(key: K, value: C[K] | undefined): Promise /** * The configuration value as a plain object. */ readonly value: Readonly } interface ConfigurationService extends Subscribable { /** * Returns the full configuration object. * * @template C The configuration schema. * @returns The full configuration object. */ get(): Configuration } /** * The configuration settings. * * It may be merged from the following sources of settings, in order: * * Default settings * Global settings * Organization settings (for all organizations the user is a member of) * User settings * Repository settings * Directory settings * * @todo Add a way to get/update configuration for a specific scope or subject. * @todo Support applying defaults to the configuration values. */ export const configuration: ConfigurationService /** * A provider result represents the values that a provider, such as the {@link HoverProvider}, may return. The * result may be a single value, a Promise that resolves to a single value, a Subscribable that emits zero * or more values, or an AsyncIterable that yields zero or more values. */ export type ProviderResult = | T | undefined | null | Promise | Subscribable | AsyncIterable /** The kinds of markup that can be used. */ export enum MarkupKind { PlainText = 'plaintext', Markdown = 'markdown', } /** * Human-readable text that supports various kinds of formatting. */ export interface MarkupContent { /** The marked up text. */ value: string /** * The kind of markup used. * * @default MarkupKind.Markdown */ kind?: MarkupKind } /** A badge holds the extra fields that can be attached to a providable type T via Badged. */ export interface Badge { /** * Aggregable badges are concatenated and de-duplicated within a particular result set. These * values can briefly be used to describe some common property of the underlying result set. * * We currently use this to display whether a file in the file match locations pane contains * only precise or only search-based code navigation results. */ aggregableBadges?: AggregableBadge[] } /** * Aggregable badges are concatenated and de-duplicated within a particular result set. These * values can briefly be used to describe some common property of the underlying result set. */ export interface AggregableBadge { /** The display text of the badge. */ text: string /** If set, the badge becomes a link with this destination URL. */ linkURL?: string /** Tooltip text to display when hovering over the badge. */ hoverMessage?: string } /** * A wrapper around a providable type (hover text and locations) with additional context to enable * displaying badges next to the wrapped result value in the UI. */ export type Badged = T & Badge /** * A hover represents additional information for a symbol or word. Hovers are rendered in a tooltip-like * widget. */ export interface Hover { /** * The contents of this hover. */ contents: MarkupContent /** * The range to which this hover applies. When missing, the editor will use the range at the current * position or the current position itself. */ range?: Range } export interface HoverProvider { provideHover(document: TextDocument, position: Position): ProviderResult> } /** * The definition of a symbol represented as one or many [locations](#Location). For most programming languages * there is only one location at which a symbol is defined. If no definition can be found `null` is returned. */ export type Definition = Badged | Badged[] | null /** * A definition provider implements the "go-to-definition" feature. */ export interface DefinitionProvider { /** * Provide the definition of the symbol at the given position and document. * * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @returns A definition location, or an array of definitions, or `null` if there is no definition. */ provideDefinition(document: TextDocument, position: Position): ProviderResult } /** * Additional information and parameters for a references request. */ export interface ReferenceContext { /** Include the declaration of the current symbol. */ includeDeclaration: boolean } /** * The reference provider interface defines the contract between extensions and * the [find references](https://code.visualstudio.com/docs/editor/editingevolved#_peek)-feature. */ export interface ReferenceProvider { /** * Provides a set of workspace-wide references for the given position in a document. * * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @param context Additional information and parameters for the request. * @returns An array of reference locations. */ provideReferences( document: TextDocument, position: Position, context: ReferenceContext ): ProviderResult[]> } /** * A location provider implements features such as "find implementations" and "find type definition". It is the * general form of {@link DefinitionProvider} and {@link ReferenceProvider}. */ export interface LocationProvider { /** * Provide related locations for the symbol at the given position and document. * * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * @returns Related locations, or `null` if there are none. */ provideLocations(document: TextDocument, position: Position): ProviderResult } /** * A document highlight is a range inside a text document which deserves special attention. * Usually a document highlight is visualized by changing the background color of its range. */ export interface DocumentHighlight { /** * The range this highlight applies to. */ range: Range /** * The highlight kind, default is text. */ kind?: DocumentHighlightKind } /** * A document highlight kind. */ export enum DocumentHighlightKind { Text = 'text', Read = 'read', Write = 'write', } /** * A document highlight provider provides ranges to highlight in the current document like all * occurrences of a variable or all exit-points of a function. * * Providers are queried for document highlights on symbol hovers in any document matching * the document selector specified at registration time. */ export interface DocumentHighlightProvider { /** * Provide document highlights for the given position and document. * * @param document The document in which the command was invoked. * @param position The position at which the command was invoked. * * @returns An array of document highlights, or a thenable that resolves to document highlights. * The lack of a result can be signaled by returning `undefined`, `null`, or an empty array. */ provideDocumentHighlights(document: TextDocument, position: Position): ProviderResult } export namespace languages { /** * Registers a hover provider, which returns a formatted hover message (intended for display in a tooltip) * when the user hovers on code. * * Multiple providers can be registered for a language. In that case, providers are queried in parallel and * the results are merged. A failing provider (rejected promise or exception) will not cause the whole * operation to fail. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A hover provider. * @returns An unsubscribable to unregister this provider. */ export function registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Unsubscribable /** * Registers a definition provider. * * Multiple providers can be registered for a language. In that case, providers are queried in parallel and * the results are merged. A failing provider (rejected promise or exception) will not cause the whole * operation to fail. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A definition provider. * @returns An unsubscribable to unregister this provider. */ export function registerDefinitionProvider( selector: DocumentSelector, provider: DefinitionProvider ): Unsubscribable /** * Registers a reference provider. * * Multiple providers can be registered for a language. In that case, providers are queried in parallel and * the results are merged. A failing provider (rejected promise or exception) will not cause the whole * operation to fail. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A reference provider. * @returns An unsubscribable to unregister this provider. */ export function registerReferenceProvider( selector: DocumentSelector, provider: ReferenceProvider ): Unsubscribable /** * Registers a generic provider of a list of locations. It is the general form of * {@link registerDefinitionProvider} and {@link registerReferenceProvider}. It is intended for "find * implementations", "find type definition", and other similar features. * * The provider can be executed with the `executeLocationProvider` builtin command, passing the {@link id} * as the first argument. For more information, see * https://sourcegraph.com/docs/extensions/authoring/builtin_commands#executeLocationProvider. * * @param id An identifier for this location provider that distinguishes it from other location providers. * @param selector A selector that defines the documents this provider is applicable to. * @param provider A location provider. * @returns An unsubscribable to unregister this provider. */ export function registerLocationProvider( id: string, selector: DocumentSelector, provider: LocationProvider ): Unsubscribable /** * Registers a completion item provider. * * Multiple providers can be registered with overlapping document selectors. In that case, * providers are queried in parallel and the results are merged. A failing provider will not * cause the whole operation to fail. * * @param selector A selector that defines the documents this provider applies to. * @param provider A completion item provider. * @returns An unsubscribable to unregister this provider. * * @deprecated */ export function registerCompletionItemProvider( selector: DocumentSelector, provider: CompletionItemProvider ): Unsubscribable /** * Registers a document highlight provider. * * Multiple providers can be registered with overlapping document selectors. In that case, * providers are queried in parallel and the results are merged. A failing provider will not * cause the whole operation to fail. * * @param selector A selector that defines the documents this provider applies to. * @param provider A document hover provider. * @returns An unsubscribable to unregister this provider. */ export function registerDocumentHighlightProvider( selector: DocumentSelector, provider: DocumentHighlightProvider ): Unsubscribable } /** * Commands are functions that are implemented and registered by extensions. Extensions can invoke any command * (including commands registered by other extensions). The extension can also define contributions (in * package.json), such as actions and menu items, that invoke a command. */ export namespace commands { /** * Registers a command that can be invoked by an action or menu item, or directly (with * {@link commands.executeCommand}). * * @param command A unique identifier for the command. * @param callback A command function. If it returns a {@link Promise}, execution waits until it is resolved. * @returns Unsubscribable to unregister this command. * @throws Registering a command with an existing command identifier throws an error. */ export function registerCommand(command: string, callback: (...args: any[]) => any): Unsubscribable /** * Executes the command with the given command identifier. * * @template T The result type of the command. * @param command Identifier of the command to execute. * @param rest Parameters passed to the command function. * @returns A {@link Promise} that resolves to the result of the given command. * @throws If no command exists with the given command identifier, an error is thrown. */ export function executeCommand(command: string, ...args: any[]): Promise } export namespace graphQL { /** * Executes a [Sourcegraph GraphQL API](https://sourcegraph.com/docs/api/graphql) query or mutation on the associated Sourcegraph instance and returns a promise for the result. * * @template TResult The GraphQL result type * @template TVariables The type of the variables object * @param request The GraphQL request (query or mutation) * @param variables An object whose properties are GraphQL query name-value variable pairs * @returns A Promise for the result of the GraphQL request */ export function execute( request: string, variables: TVariables ): Promise> export type GraphQLResult = SuccessGraphQLResult | ErrorGraphQLResult export interface SuccessGraphQLResult { data: T errors: undefined } export interface ErrorGraphQLResult { // It might be possible that even with errored response we have // a partially resolved data // See https://github.com/sourcegraph/sourcegraph/pull/36033 data: T | null errors: readonly import('graphql').GraphQLError[] } } export interface ContextValues { [key: string]: string | number | boolean | null } /** * Internal API for Sourcegraph extensions. Most of these will be removed for the beta release of Sourcegraph * extensions. They are necessary now due to limitations in the extension API and its implementation that will * be addressed in the beta release. * * @internal * @hidden */ export namespace internal { /** * Returns a promise that resolves when all pending messages have been sent to the client. * It helps enforce serialization of messages. * * @internal */ export function sync(): Promise /** * Updates context values for use in context expressions and contribution labels. * * @param updates The updates to apply to the context. If a context property's value is null, it is deleted from the context. */ export function updateContext(updates: ContextValues): void /** * The URL to the Sourcegraph site that the user's session is associated with. This refers to * Sourcegraph.com (`https://sourcegraph.com`) by default, or a self-hosted instance of Sourcegraph. * * @todo Consider removing this when https://github.com/sourcegraph/sourcegraph/issues/566 is fixed. * * @example `https://sourcegraph.com` */ export const sourcegraphURL: URL /** * The client application that is running this extension, either 'sourcegraph' for Sourcegraph or 'other' * for all other applications (such as GitHub, GitLab, etc.). * * @todo Consider removing this when https://github.com/sourcegraph/sourcegraph/issues/566 is fixed. */ export const clientApplication: 'sourcegraph' | 'other' } /** Support types for {@link Subscribable}. */ interface NextObserver { closed?: boolean next: (value: T) => void error?: (err: any) => void complete?: () => void } interface ErrorObserver { closed?: boolean next?: (value: T) => void error: (err: any) => void complete?: () => void } interface CompletionObserver { closed?: boolean next?: (value: T) => void error?: (err: any) => void complete: () => void } type PartialObserver = NextObserver | ErrorObserver | CompletionObserver /** * A stream of values that may be subscribed to. */ export interface Subscribable { /** * Subscribes to the stream of values. * * @returns An unsubscribable that, when its {@link Unsubscribable#unsubscribe} method is called, causes * the subscription to stop reacting to the stream. */ subscribe(observer?: PartialObserver): Unsubscribable /** @deprecated Use an observer instead of a complete callback */ subscribe(next: null | undefined, error: null | undefined, complete: () => void): Unsubscribable /** @deprecated Use an observer instead of an error callback */ subscribe(next: null | undefined, error: (error: any) => void, complete?: (() => void) | null): Unsubscribable /** @deprecated Use an observer instead of a complete callback */ // eslint-disable-next-line @typescript-eslint/unified-signatures subscribe(next: (value: T) => void, error: null | undefined, complete: () => void): Unsubscribable subscribe( next?: ((value: T) => void) | null, error?: ((error: any) => void) | null, complete?: (() => void) | null ): Unsubscribable } /** * The extension context is passed to the extension's activate function and contains utilities for the * extension lifecycle. * * @since Sourcegraph 3.0. Use `export function activate(ctx?: ExtensionContext) { ... }` for prior * versions (to ensure your code handles the pre-3.0-preview case when `ctx` is undefined). */ export interface ExtensionContext { /** * An object that maintains subscriptions to resources that should be freed when the extension is * deactivated. * * When an extension is deactivated, first its exported `deactivate` function is called (if one exists). * The `deactivate` function may be async, in which case deactivation blocks on it finishing. Next, * regardless of whether the `deactivate` function finished successfully or rejected with an error, all * unsubscribables passed to {@link ExtensionContext#subscriptions#add} are unsubscribed from. * * (An extension is deactivated when the user disables it, or after an arbitrary time period if its * activationEvents no longer evaluate to true.) */ subscriptions: { /** * Mark a resource's teardown function to be called when the extension is deactivated. * * @param unsubscribable An {@link Unsubscribable} that frees (unsubscribes from) a resource, or a * plain function that does the same. Async functions are not supported. (If deactivation requires * async operations, make the `deactivate` function async; that is supported.) */ add: (unsubscribable: Unsubscribable | (() => void)) => void } } }