sourcegraph / sourcegraph-extension-api

Sourcegraph extension API: use and build extensions that enhance reading and reviewing code in your existing tools. "The extension API you wish your code host had."

⚠⚠⚠ Sourcegraph extension API has moved!

• Documentation: https://docs.sourcegraph.com/extensions
• Source code: https://github.com/sourcegraph/sourcegraph/tree/master/packages/sourcegraph-extension-api

sourcegraph-extension-api's Issues

Broken link in README.md

Codecov extension's main extension.ts file in the readme links to sourcegraph.sgdev.com - i assume it should link directly to the github repo instead where the public has access ;-)

Buggy hover extensions should not be able to break other hover providers

The sourcegraph-string-references extension breaks code intelligence in certain places. This should not be possible.

If one hover provider fails, other hover providers should continue to work.

I don't know which component is responsible for this so I am filing on this repo. Feel free to move.

cc @chrismwendt @sqs @felixfbecker @ijsnow

API rate limit exceeded during semantic-release

https://travis-ci.org/sourcegraph/sourcegraph-extension-api/builds/436293041?utm_source=github_status&utm_medium=notification

[6:53:34 PM] [semantic-release] › ✖  An error occurred while running semantic-release: { HttpError: {"message":"API rate limit exceeded for user ID 15893131.","documentation_url":"https://developer.github.com/v3/#rate-limiting"}

@felixfbecker Do you know if there is any action to be taken here?

createWebWorkerMessageTransports could be implicit

Since createWebWorkerMessageTransports(self) must be called for every extension, then it could be moved into the activateExtension() function.

Extension-provided links can leak referrer in the browser extension on e.g. GitHub

The same is not true when clicking links the same links on Sourcegraph because we specify rel="noreferrer noopener"

Dynamic iconURLs

Being able to set the iconURL dynamically would let CXP extensions gray out their icon when toggled (e.g. Codecov), show little badges, or show a red X to draw the user's attention to a bad setting (e.g. API token).

Alternative to dynamic imports in a Sourcegraph extentsion?

Question description

Has anyone used dynamic import statements inside of any existing Sourcegraph extension?

Is your question related to a problem? If so, please describe or link to another issue.

Trying to use import() statements in an extension with parcel I ran across the issue

TypeError: Module scripts are not supported on WorkerGlobalScope yet (see https://crbug.com/680046)

Is there an alternative recommended way I could bundle the extension to be able use importScripts instead?

Additional context

My specific use case is trying to import individual rule definitions from tslint like
import(`tslint/lib/rules/${ruleName}Rule`)

Including every rule as a static import looks to work when bundling but I'm hitting an issue in sourcegraph itself where it seems like it won't run the extension code and I don't get an error as well as bloating the extension file size.

Code intelligence hovers pop up on my hover link decorations, yuck

My extension provides a decoration with some after: { contentText: "...", linkURL: "..." } and on GitHub.com the code intelligence hovers pop up when I move my mouse over it, which makes clicking the link really yucky:

allow an extension to specify that it should only be run when in a repo

Create a sourcegraph extension generator (npm init @sourcegraph/extension)

This can be a fork of https://github.com/sourcegraph/create

Support updating config of other than highest-precedence subject

Use cases:

• sourcegraph/code-intel-extensions#5

line decoration link handling is inconsistent

• In Sourcegraph, a line decoration link opens a new tab.
• On GitHub.com, a line decoration link replaces the current tab / navigates away from the current tab.

Ideally this behavior would be controllable, or at least consistent.

files.exclude in settings.json

From @felixfbecker:

I modified the extension API, builded, and wondered where the output was because I couldn’t see any dist folder. After rerunning the build multiple times, inspecting the build script etc I did an ls in the terminal and finally found that VS Code was configured to hide the folders.

@felixfbecker: Would you prefer if it output to lib/?

Also, did you intentionally configure VS Code to hide dist? I had (previously) configured my VS Code in user settings to have

"files.exclude": {..., "**/dist": true}

to exclude dist, so I would have run into the same confusion as you. But I worry if we make it use lib/, then people who have manually hidden lib/ would be confused, so that might not be the right solution. You would have a better sense.

Extension authoring feedback

From @felixfbecker:

Some feedback on working with the extension stuff for the first time. All these points are minor and I could probably all resolve them if I just dig deeper, but all the points together already costed me a lot of time. I hope we can resolve most of these (i.e. better documentation and team education) since more people will run into this. For context, this was to investigate a P1 regression reported by a user: sourcegraph/sourcegraph#138

• ~~~The platform flag is on in production, but not in local dev, which in this case meant the issue didn’t appear locally. I had to remember to turn on the feature flag locally (I first had just cleared local storage).~~~ fixed
• I didn’t know where LSP stuff now comes from (i.e. where is the code?) which made it hard to debug, since providers are now dynamic. I have no idea at what layer in extensions-api I could add the validation.
• ~~~I also couldn’t easily trace it because the extension API didn’t publish sourcemaps properly~~~ fixed sourcegraph/sourcegraph#13129
• #44
• I tried syncing changes in lib/ to the web app but that didn’t work initially, because the extension API builds multiple module targets, and the files we use are actually in module/ (relates to the point above, because I didn’t see the folder)
• I wasn’t aware that sourcegraph (npm package) is also depended on by @sourcegraph/extensions-client-common, and hovers will actually go through that package. This caused me to sync changes to the wrong package at first
• ~~~After this, I could still not trace the call because apparently the extension also doesn’t contain proper sourcemaps. I couldn’t fix that because I don’t know where it is, which was the point of tracing it…~~~ fixed sourcegraph/sourcegraph#13129
• I searched for repos in the sourcegraph org and found sourcegraph-langserver-http and guessed that could be it (even though I first thought it was an HTTP langserver)
• ~~~I did a PR: sourcegraph/sourcegraph-langserver-http#4~~~ merged
• I don’t know how I would deploy that change, or where to look to find out -- awaiting reply in sourcegraph/sourcegraph-langserver-http#4 (comment)

Document how to create extensions

The extension authoring experience is undocumented. We intend to write very good tutorials and publish our API docs soon.

High-level:

Writing a Sourcegraph extension is very similar to writing an editor extension for VS Code. See the Codecov extension's main extension.ts file for an example.

Subscribe to this issue to get notified when extension authoring docs exist.

Don't swallow error message when createMessageTransports fails

When createMessageTransports is rejected, the error message is throw away. It would be nice to keep it around so the client can display that error to the user (e.g. if a JS bundle 404s).

I think this would involve changing the () => ... to e => ... at https://sourcegraph.sgdev.org/github.com/sourcegraph/cxp-js@9baa81d/-/blob/src/client/client.ts#L168 and changing the ClientState type from an enum to something like ClientState | Error.

Extension request: Git blame

The extension API lets you add after-line decorations. As a developer, I would like to be able to toggle on/off seeing blame annotations for all lines in the file. Currently Sourcegraph shows you this on the selected line but not all lines, and GitHub (and other code hosts) requires you to go to a different page for this info.

This would be implemented by:

1. Show a Blame toggle button and storing the toggle state in settings
2. When blame is on, fetch the blame data for all lines in the current file (e.g., from the Sourcegraph GraphQL API using sourcegraph.commands.executeCommand('queryGraphQL', graphqlquerystring, mapofvars)
3. Display an after-line decoration for each line with the blame author, date, commit message summary, abbreviated SHA, etc. (whatever is useful and looks good; there is a lot of prior art here)

All common features (like hovers) should have dedicated methods

When an author has to write connection.send{Request,Notification} and pass in the method, it feels more like a protocol and less like an API.

Aliases like onHover() or publishDecorations() will enable authors to more easily explore the API via autocomplete in their editor and make extension code more readable.

Google Cloud API - anyone publishing extensions that employ it?

I'm trying to publish an extension that employs the Google Cloud API.

I attempt to publish code that calls the Translate constructor -

import { Translate } from 'google-cloud/translate';
// Instantiate a client
const translate = new Translate({projectId: 'my-project-id' });

src ext publish fails:

npm WARN deprecated [email protected]: The google-cloud package has been deprecated. We strongly recommend installing individual API packages, such as @google-cloud/storage. For a list of Google Cloud Platform API specific packages please visit https://cloud.google.com/nodejs/docs/reference/libraries

> [email protected] preinstall /Users/dan/IdeaProjects/sourcegraph-lionize/node_modules/google-cloud
> node scripts/preinstall.js

The google-cloud package has been deprecated. We stronglyrecommend installing individual API packages, such as @google-cloud/storage. For a list of Google Cloud Platform API specific packages please visit https://cloud.google.com/nodejs/docs/reference/libraries
npm WARN sourcegraph-lionize@ No repository field.
npm WARN sourcegraph-lionize@ No license field.

npm ERR! code ELIFECYCLE
npm ERR! errno 255
npm ERR! [email protected] preinstall: node scripts/preinstall.js
npm ERR! Exit status 255
npm ERR!
npm ERR! Failed at the [email protected] preinstall script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

I'm able to execute the attached javascript file using the node command line tool and don't get any such warnings or errors.

The license in this case comes from the file specified by the environmental variable GOOGLE_APPLICATION_CREDENTIALS (JSON file that contains a private key). One would want to prevent the plaintext dissemination of these private keys to all client browsers; does a strategy exist for client-side execution when private keys are needed?
translate.js.txt

Deprecate npm package cxp

RegExp constructor fails to function as expected?

Writing a Sourcegraph extension in typescript, "new RegExp ('')" constructor fails to produce something usable like the "/ /;" regexp builder.

Is it there additional configuration required to be able to call "new RegeExp ('')" in your extension

Client settings confusion / issues

There is ongoing confusion around how client settings work. This is a point I have brought up, as well as others.

Related and/or previous issues:

• https://github.com/sourcegraph/enterprise/issues/13501
• sourcegraph/sourcegraph#256

Goal: How do we make client settings work well for users? The first step here should be discussion about what the current problems are, the second should be how to fix them.

Multiple components

Sometimes there are multiple components on a page (diff views, snippets, editor splits) that need to be registered in the CXP controller.

Syntax checking of .ts files - any tips?

Syntax errors in .ts files - how does a developer best catch them?

I've had syntax errors pass through src ext publish without any warning. When the browser loads the extension with a syntax error on the client side, the .js appears then disappears very quickly in the developer console. This arrangement means the developer has to find syntax errors by carefully reading all the code.

Is there a good way to check the syntax of your TypeScript code? Guessing tsc should help, at the moment I'm seeing if I can put together a tsconfig.json that works for my extension. Is there a good template?

New feature: Enable local testing of a Sourcegraph extension before publishing

It would be nice to be able to test an extension on a local Sourcegraph installation before publishing it to the world. Can we have a way to install an extension in a local installation, including Docker-based installations?

Registering capabilities and listening to requests could be simplified

The two calls sendRequest(RegistrationRequest.type, ...) followed by onRequest(...) are redundant because it's useless to register (e.g. a hover provider) but not add a listener.

https://github.com/sourcegraph/cx-hello-world-hover/blob/a109acf36ecb92a86a1dca53f269ce5f640f883f/src/extension.ts

    await cxp.rawConnection.sendRequest(RegistrationRequest.type, {
        registrations: [
            {
                id: HoverRequest.type.method,
                method: HoverRequest.type.method,
                registerOptions: { documentSelector: ['*'] },
            },
        ],
    })

    // Start responding to hover tooltip requests.
    cxp.rawConnection.onRequest(HoverRequest.type.method, () => ({
        contents: '👋 Hello from an extension!',
    }))

These two calls could be merged into one addListener(...) call (just like DOM events) which automatically registers and deregisters the capability.

const listener = cxp.addListener('hover', pos => ...)

cxp.removeListener(listener) could also be supported.

DecorationAttachmentRenderingOptions.hoverMessage does not work in browser extension

The code discussions extension provides a hoverMessage in all attachments it creates, but they only show up on Sourcegraph and not e.g. on GItHub with the browser extension.

https://github.com/sourcegraph/sourcegraph-extension-api/blob/master/src/sourcegraph.d.ts#L453-L454