Now in beta on Sourcegraph: Searchable Ruby code with live usage examples for any project on GitHub

YARD + Ruby static analysis + type inference


We’re excited to announce beta support for Ruby (and Ruby on Rails) on Sourcegraph. This means you can now use Sourcegraph to:

Check out this 1-minute screencast to see how:

https://www.youtube.com/watch?v=YYL0ZoPeB5w

Ruby’s magic makes analysis and indexing tough

Much of what makes Ruby special is its magic: method_missing, duck typing, monkey-patching,instance_eval, and everything else that makes it an awesome language for DSLs. This magic, however, introduces both ambiguity and uncertainty, which makes it hard for people (such as yours truly) who write programs to statically analyze and infer types in Ruby code. In a later blog post we’ll go into more depth about the specific challenges and the techniques we use.

So, for now, Sourcegraph’s Ruby support is in beta.

How is it implemented?

We added reference handling (determining what definition each identifier refers to) and type inference (determine the type of each variable, like String or URI) to Loren Segal’s existing Ruby documentation tool YARD. Our fork is at sourcegraph/yard.

What works?

Here’s what Sourcegraph should handle well for most Ruby projects:

  • Ruby gems on GitHub with .gemspec files (standalone Ruby applications aren’t supported yet)
  • Documentation and definitions (we use an existing tool, YARD, for this)
  • Cross-references (i.e., clickable jump-to-definition links when you’re viewing source code) and automatic usage examples for most non-super-complex Ruby code (e.g., ActionMailer::Base#mail)
  • Type inference for most basic or local code (i.e., knowing that myvar is a String andcurrent_user is a User instance)

What doesn’t work? Basically, cross-references and type inference for complex DSLs. For example, Sourcegraph won’t be able to trace a call to something defined in instance_eval.

In practice, this means about about 50% of the identifiers in the average Ruby source file are clickable and display docs and usage examples (if present). There are some major omissions, such as Rails’ association class methods like has_and_belongs_to_many and its relatives, which have full documentation and linked definitions but no automatically discovered usage examples. We hope to increase the coverage to 80-90% with future Ruby analysis improvements.

Also, Ruby syntax highlighting needs some more work.

What’s next, and how you can help improve Ruby on Sourcegraph

In the next couple of weeks, we’ll work on improving our Ruby code analysis on the most-viewed Ruby projects on Sourcegraph, plus on any projects that you tweet @srcgraph about. We’ll also prioritize any Ruby projects whose READMEs link to their Sourcegraph page (https://sourcegraph.com/github.com/USER/REPO).

If you encounter a problem using Ruby on Sourcegraph that isn’t one of the known issues mentioned above, we’d love if you would report the issue.

We are also working on cleaning up the fork of YARD that we use to perform Ruby analysis. We’ll make another blog post when that’s ready, but if you’re interested in checking it out in the meantime, go for it (and contact me @sqs or post an issue if you have any questions).

Finally, we’re looking to hire a Ruby enthusiast to help us make Sourcegraph an awesome place to do all the things listed in the bullet points at the top of this post. This person would own all aspects of Ruby on Sourcegraph and would help us reach out to the Ruby community (specifically, projects and authors who use, or want to use, Sourcegraph) to make Sourcegraph better. Interested or know someone who is? Email us!

For updates and improvements, follow @srcgraph and me (@sqs), and sign up for Sourcegraph to get email updates.