RubyCritic: Ruby quality reports and source-control comparisons

It reads your version control, and the file warns you about the stash

Feature five in the overview is the one with a consequence.

RubyCritic uses your source control system to compare your currently uncommitted changes against your last commit. Only three are supported: Git, Mercurial and Perforce.

Underneath that is a warning, and it is the only warning in the file. If your code is not as you expect it to be after running RubyCritic, check your source control system stash.

That implies the tool sets your changes aside in order to measure them, which is the standard way to analyse a working tree without committing it, and it is why three version control systems are named rather than one. It is also why the warning exists: a stash you did not create is a surprise waiting to happen, and it is the sort of thing that gets discovered days later.

Commit first, or shelve deliberately. The cost of doing that is small and the alternative is a stash you have to remember about.

Screenshots illustrate the generated reports

The README illustrates the project overview, file index and smell index with screenshots. It also gives a small Ruby example and uses two further screenshots to contrast Reek output with the RubyCritic report. If an image is unavailable in a text-only view, consult the linked images in the repository rather than assuming the examples are missing. The `docs` directory explains the core metrics in more detail.

CI mode is a diff, and the threshold flag only works alongside a branch

The flag table is the most complete part of the file, and it describes a tool that can act as a gate rather than only as a report.

Two flags do that. The minimum score takes a float and defaults to zero, so nothing fails by default. The maximum decrease takes a float, defaults to zero, and is documented as working only with the branch flag, with the example value given as a half.

The CI mode is the third. It is described as faster, because it analyses the diff with respect to a base branch, and the base branch defaults to main. The branch flag sets that base explicitly.

So there are two different modes of operation and the distinction matters. A full run looks at every file you point it at. The CI mode looks only at what changed, which is why it is faster and why it will not surface a problem in code that has not been touched.

The report path defaults to a directory under tmp, coverage defaults to a directory in the project, and a flag suppresses opening the HTML report in a browser, which matters on a machine without one.

Three analysers with three different configuration stories

The analyser section is where the wrapping becomes concrete, because each of the three tools is configured differently.

Reek uses its own configuration loading mechanism. That means if you already have a Reek configuration file in your project root, RubyCritic respects it, with no extra flag. For a team that already runs Reek, the tool inherits the decisions already made about what counts as a smell.

Flay uses its default configuration, with nothing to say about it.

Flog gets flog's defaults plus three tweaks, and each is explained. One forces scores for all classes and methods, because without it flog only reports down to a threshold. One makes flog continue past a Ruby file it cannot parse instead of aborting. The third restricts reporting to code inside methods, which prevents flog reporting on methods named private or protected, and on framework methods like before_action and has_many.

That last tweak is the interesting one. It is a Rails accommodation in a tool that otherwise takes no view on your framework, and it means a codebase using callbacks will not accumulate noise from the callback methods themselves.

The project ships its own Reek and RuboCop configurations

The root of the repository is configured for four tools, and three of them are the kind of file a user of this project would also have.

There is a Reek configuration and a RuboCop configuration. A gem that wraps Reek and reports on code quality, and which respects your Reek configuration, is running its own Reek configuration over itself. The same is true of the RuboCop file, even though RuboCop is not one of the three analysers it wraps.

The others are more specific. A JRuby configuration file means the project is expected to run under that implementation. A Solargraph configuration points an editor's language server at the source. A YARD options file configures documentation generation. A markdown lint configuration covers the readme and the documents beside it.

There is also an Appraisals file and a gemfiles directory, which is the arrangement for testing against more than one set of dependency versions, and a Rakefile at the root. So the testing matrix is set up for multiple dependency sets even though the readme says nothing about which ones.

The build badge points at one system and the tree still holds another

There are three badges at the top, and they cover three different services.

One is a package registry version badge. One is a build status badge for a workflow file on a hosted continuous integration service, and the badge link points at a file named for the main branch. The third is a badge for a hosted code quality service, pointing at the project there.

Meanwhile the repository still contains a directory of scripts for a different hosted continuous integration service, the one whose configuration file was the convention before the first badge existed. Nothing in the tree suggests those scripts run.

So the visible state is a project mid-migration between two continuous integration systems, with the badge already moved and the old scripts still in place.

That same hosted code quality service appears a second time in the usage section, as the destination of a recipe. The file suggests wiring RubyCritic into a particular CI server so you can build your own poor-man's version of that service, which is a nice touch for anyone who wants the annotations without the subscription.

Configuration options and the Rake task

The README's YAML configuration example includes CI mode and its base branch, report and coverage paths, maximum decrease, output formats and `minimum_score: 95`. It also documents a Rake task with configurable task name, file patterns and options. Consult the current README and `rubycritic --help` for the complete example and defaults before wiring the tool into CI.

Editorial conclusion

RubyCritic is worth installing if you want a single report that combines duplication, complexity and smell counts, since running the three analysers separately and reconciling the numbers is the tedious part. Four things to know before you run it. It interacts with your version control system to compare uncommitted work against your last commit, and the file's own warning is to check your stash if your code is not what you expect, so commit or shelve before you start. The CI mode is not a different report but a faster one that only looks at the diff against a base branch, so it will not tell you about problems in code you have not touched. The minimum score and maximum decrease flags are a gate you configure, not something enabled by default. And the documentation is thin exactly where you would want it, since the worked example it advertises is absent.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. whitesmith/rubycritic on GitHub