sourcegraph/browser

Sourcegraph browser extension

\

Overview

The Sourcegraph browser extension adds tooltips to code on GitHub, Phabricator, and Bitbucket. The tooltips include features like:

• symbol type information & documentation
• go to definition & find references (currently for Go, Java, TypeScript, JavaScript, Python)
• find references

🚀 Install: Sourcegraph for Chrome

🚀 Install: Sourcegraph for Firefox

It works as follows:

• when visiting e.g. https://github.com/..., the extension injects a content script (inject.bundle.js)
• there is a background script running to access certain chrome APIs, like storage (background.bundle.js)
• a "code view" contains rendered (syntax highlighted) code (in an HTML table); the extension adds event listeners to the code view which control the tooltip
• when the user mouses over a code table cell, the extension modifies the DOM node:
  • text nodes are wrapped in (so hover/click events have appropriate specificity)
  • element nodes may be recursively split into multiple element nodes (e.g. a &Router{namedRoutes: contains multiple code tokens, and event targets need more granular ranges)
  • We assume syntax highlighting takes care of the base case of wrapping a discrete language symbol
  • tooltip data is fetched from the Sourcegraph API
• when an event occurs, we modify a central state store about what kind of tooltip to display
• code subscribes to the central store updates, and creates/adds/removes/hides an absolutely positioned element (the tooltip)

Project layout

• src/extension/
  • Entrypoint for browser extension builds. (Includes bundled assets, background scripts, options)
• src/browser
  • A wrapper around the browser APIs.
• src/libs/
  • Isolated pieces of the browser extension. This contains code that is specific to code hosts and separate "mini applications" included in the browser extension such as the src omnibar cli.
• src/libs/phabricator/
  • Entrypoint for Phabricator extension. This is used by the browser extension and sourcegraph/phabricator-extension.
• src/shared/
  • Code shared by the extension and the libraries. Ideally, nothing in here should reach into any other directory.
• src/config/
  • Polyfills and configuration/plumbing code that is bundled via webpack. The configuration code adds properties to window that make it easier to tell what environment the script is running in. This is useful because the code can be run in the content script, background, options page, or in the actual page when injected by Phabricator and each environment will have different ways to do different things.
• src/e2e/
  • E2e test suite.
• scripts/
  • Development scripts.
• webpack
  • Build configs.
• build
  • Generated directory containing the output from webpack and the generated bundles for each browser.

Requirements

• node
• yarn
• make

Development

For each browser run:

yarn run dev

To only build for a single browser (which makes builds faster in local development), set the env var TARGETS=chrome or TARGETS=firefox.

Now, follow the steps below for the browser you intend to work with.

Chrome

• Browse to chrome://extensions.
• If you already have the Sourcegraph extension installed, disable it by unchecking the "Enabled" box.
• Click on Load unpacked extensions, and select the build/chrome folder.
• Browse to any public repository on GitHub to confirm it is working.
• After making changes it is necessary to refresh the extension. This is done by going to chrome://extensions and clicking "Reload".

Updating the bundle

Click reload for Sourcegraph at chrome://extensions

Firefox (hot reloading)

In a separate terminal session run:

yarn global add web-ext
yarn run dev:firefox

A Firefox window will be spun up with the extension already installed.

Updating the bundle

Save a file and wait for webpack to finish rebuilding.

Caveats

The window that is spun up is completely separate from any existing sessions you have on Firefox. You'll have to sign into everything at the beginning of each development session(each time you run yarn run dev:firefox). You should ensure you're signed into any Sourcegraph instance you point the extension at as well as GitHub.

Firefox (manual)

• Go to about:debugging
• Select "Enable add-on debugging"
• Click "Load Temporary Add-on" and select "firefox-bundle.xpi"
• More information

Updating the bundle

Click reload for Sourcegraph at about:debugging

Testing

• Unit tests: yarn test
• E2E tests: yarn test-e2e

e2e tests

The test suite in e2e/github.test.ts runs on the release branch bext/release in both Chrome and Firefox against a Sourcegraph Docker instance.

The test suite in e2e/phabricator.test.ts tests the Phabricator native integration. It assumes an existing Sourcegraph and Phabricator instance that has the Phabricator extension installed. There are automated scripts to set up the Phabricator instance, see https://docs.sourcegraph.com/dev/phabricator_gitolite. It currently does not run in CI and is intended to be run manually for release testing.

e2e/bitbucket.test.ts tests the browser extension on a Bitbucket Server instance.

e2e/gitlab.test.ts tests the browser extension on gitlab.com (or a private Gitlab instance).

Deploy

Deployment the Chrome web store happen automatically in CI when the bext/release branch is updated. Releases are also uploaded to the GitHub releases page and tagged in git.

To release the latest commit on master, ensure your master is up-to-date and run

git push origin master:bext/release