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:
- emacs-sourcegraph-mode, an editor plugin for Emacs
- Sourcegraph.com, an open-source code search engine
Screenshots are below.
This toolchain is not a standalone program; it provides additional functionality to editor plugins and other applications that use srclib.
First,
install the src
program (see srclib installation instructions).
Then run:
git clone https://github.com/sourcegraph/srclib-javascript.git
cd srclib-javascript
src toolchain add sourcegraph.com/sourcegraph/srclib-javascript
To verify that installation succeeded, run:
src toolchain list
You should see this srclib-javascript toolchain in the list.
Now that this toolchain is installed, any program that relies on srclib (such as editor plugins) will support JavaScript.
(TODO(sqs): add a tutorial link)
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.
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.)
Testing this toolchain requires that you have installed src
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:
# build the Docker container to run the tests in isolation
src toolchain build sourcegraph.com/sourcegraph/srclib-javascript
# run the tests
src test
By default, that command runs tests in an isolated Docker container. To run the
tests on your local machine, run src test -m program
. See the srclib
documentation for more information about the differences between these two
execution methods.
Patches are welcomed via GitHub pull request! See CONTRIBUTING.md for more information.
srclib-javascript's type inference is based on Tern.