Overview

What is Reviewer and how does it help?

Reviewer reduces the friction of using multiple automated code review tools so you can run them more frequently and consistently.

Reviewer is not a tool for automating or scripting project work. The basic idea behind reviewer is for it to serve as wrapper around your code-review-based tools so you can reliably and efficiently benefit from a wider variety of tools.

Why use Reviewer?

If it's not immediately clear how Reviewer can help, you're in the right place. Depending on your familiarity or experience with code review tools, it's worth addressing the value of those tools before we talk about Reviewer.

If you're already familiar with and sold on automated code review tools, then you can skip down to the next section. If not, let's talk in broad strokes about the benefits of using them.

Why use automated code review tools?

When writing software, the sooner you catch (and fix) problems, the cheaper it is. In fact, this holds so true, that one could compellingly argue that increasing the quality of your code is effectively free. (To a point of course.)

And there's a plethora of modern automated tools that can facilitate catching problems before you make a commit or even open a pull request. So instead of trudging through your code for every bug, you let the machines proactively keep an eye on your code so they can alert you to issues before they move along your development process.

For many types of problems, not only are the machines faster at finding problems, but they're more accurate as well. In some cases, the automated tools can not only find issues but also automatically correct some classes of issues without any effort on your part. You save time and money, and your code quality improves.

But while these tools are individually amazing, using more than a few in a project quickly becomes cumbersome and overbearing. That's where Reviewer comes in.

Why add Reviewer to the mix?

Yet another tool? That would normally be my response. Using yet another tool to manage the compleexity of a collection of tools feels like exactly the wrong answer in most cases. So Reviewer works hard to keep things simple and stay out of your way.

Reviewer strives to make it easier and more natural to use multiple code review tools in ways that fit in perfectly with modern software development. But enough hype, let's dive into tangible examples of how it helps reduce friction and fix issues earlier and more efficiently.

What if, instead of...

$ yarn audit --level moderate
$ bundle exec bundle-audit check --no-update
$ bundle exec rubocop --parallel
$ bundle exec erblint --lint-all --enable-all-linters
$ yarn stylelint .
$ yarn eslint .

...you could just type...

$ rvw

And then when it runs all of the tools, instead of flooding the screen with output from each tool, it suppresses successful results and shows concise and readable output unless the tool fails. And it also tells you how long each tool takes to execute in case you only want to run the slow tools in specific contexts. (In the shell, the output is colorized for increased scannability as well.)

Bundler Audit · Review Gem Dependencies for Security Issues
Success (2.064s)

Minitest · Unit Tests
Success (1.339s)

Rubocop · Review Ruby Syntax & Formatting for Consistency
Success (2.841s)

But when the tool finds a problem, what if it knew not to run any subsequent tools and showed you just that failure? So instead of scrolling back through screenfuls of successful output, it only shows you what you need to fix so you can focus on one thing at a time.

Inch · Review Ruby Documentation
$ bundle exec inch > /dev/null
Failure · Exit Status 10

Re-running Inch verbosely:
$ bundle exec inch

# Undocumented:
┃  U  ↑  Reviewer#review
┃  U  ↑  Reviewer#format

Then sometimes you may just want one tool, and you want it to run with the correct settings without remembering all the right flags.

$ bundle exec rubocop --parallel

...becomes...

$ rvw rubocop

For other contexts you want to run several tools, but skip others to save time. Reviewer makes it easy to run subsets of those tools so you're not wasting time running tools that don't need to be run as frequenty.

$ rvw security # Zero-in on security issues
$ rvw syntax   # Only run syntax tools when you're cleaning up
$ rvw ruby     # Only run ruby tools if that's all you're working on
$ rvw ci       # Keep CI fast by only running critical tools
$ rvw pr       # Run the tools that ensure you're ready to open a pull request
$ rvw fast     # Fast tools can be run with reckless abandon
$ rvw slow     # Easily run painfully slow tools less frequently

And sometimes it's handy to only review specific files or sets of files without having to remember each tool's unique syntax for specificying files. Do they use a --files flag or some other flag or no flag at all? Should the files be comma-separated or space-separated? Just pass a list of files to Reviewer, and let it apply the right syntax for each of the tools.

$ bundle exec rake test TEST=test/models/user.rb
$ bundle exec rubocop app
$ bundle exec reek app/models/user.rb
$ bundle exec brakeman --path app/models

$ rvw app/models/user.rb

Or for those times you only want to review a file based on its state:

$ rvw staged    # Only review staged files
$ rvw untracked # Review all of your untracked files

Or you may even want to mix and match capabilities:

$ rvw staged ruby
$ rvw rubocop staged

And since some of these tools can auto-correct in some cases, what if you didn't have to remember which tools could do that or remember whether the flag is --write, --fix, --auto-correct, or something else?

$ fmt

...and what if the fmt command worked just like the rvw command...

$ fmt staged
$ fmt ruby

...and since running a handful of tools can frequently mean updates or tools that aren't installed, so what if it could also proactively direct you to installation instructions if a specified tool isn't installed...

Tool · This is a tool without the command installed
Failure · Tool executable for 'missing_tool'

Reviewer ran this command:
bundle exec missing_tool > /dev/null

Try installing the tool:
bundle exec gem install missing_tool

Read the installation guidance:
https://example.com/docs/install

And all it takes is a little YAML to set up your desired tools. And chances are good most of the tools you want to use already have common YAML configurations already done for you.

And one more thing. Wouldn't it be nice if you could set up personal defaults that you could use across projects without having to install these tools into every codebase you touch? But, if you happen to be working on a codebase that already had them installed, it would use the codebase settings instead of your personal settings? Yeah, it's gonna do that too.

And that's just the beginning.

Sound nice? Stay in the loop: https://twitter.com/garrettdimon