srclib-javascript

srclib-javascript is a srclib toolchain that performs JavaScript (Node.js) code analysis: type inference, documentation generation, jump-to-definition, dependency resolution, etc.

It enables this functionality in any client application whose code analysis is powered by srclib, including Sourcegraph.

Screenshots are below.

Installation

This toolchain is not a standalone program; it provides additional functionality to applications that use srclib.

First, install the srclib program (see srclib installation instructions).

Then run:

srclib toolchain install javascript

To verify that installation succeeded, run:

srclib toolchain list

You should see this srclib-javascript toolchain in the list.

Now that this toolchain is installed, any program that relies on srclib will support JavaScript.

(TODO(sqs): add a tutorial link)

Screenshot

Here's what srclib-javascript's analysis looks like in these applications.

The first screenshot shows the Underscore JavaScript library on Sourcegraph.com. Here, srclib-javascript enables clickable links for every identifier (that take you to their definitions), automatic cross-repository usage examples, type inference, and documentation generation.

The second screenshot shows the emacs-sourcegraph-mode plugin for Emacs with this toolchain installed. Here, srclib-javascript enables jump-to-definition, type inference, documentation generation, and automatic cross-repository usage examples from Sourcegraph.com. All code analysis is performed locally by srclib using this toolchain.

Known issues

srclib-javascript is alpha-quality software. It powers code analysis on Sourcegraph.com but has not been widely tested or adapted for other use cases. It also has several limitations.

• Currently only detects and analyzes CommonJS packages (anything with a package.json), including Node.js packages. In particular, this means it generally does not handle front-end/client-side JavaScript.
• Does not handle global ECMAScript 5 (Array.prototype. methods, etc.) or browser objects (window, document, etc.) well.
• Gets easily confused by complex CommonJS module re-exporting. (E.g., when an index.js file requires submodules and re-exports them, it doesn't do a good job of tracing external invocations of the module to their actual function literal definition.)

Tests

Testing this toolchain requires that you have installed srclib from srclib and that you have this toolchain set up. See srclib documentation for more information.

To test this toolchain's output against the expected output, run:

srclib test

Contributing

Patches are welcomed via GitHub pull request! See CONTRIBUTING.md for more information.

srclib-javascript's type inference is based on Tern.