Cookstyle - Sane rubocop defaults for Chef Cookbooks
Cookstyle is a set of opinions about ruby code that are specific to cookbooks. Running both cookstyle and rubocop on the same codebase will result, by design, in changes being applied and then removed. Needless to say you should not use both tools on the same cookbook.
Cookstyle is included in the ChefDK, and can be used from the command
line by running cookstyle
.
The active ruleset is in the config/cookstyle.yml file. Changes to the rule set must be accompanied by arguments and code demonstrating why the change should be made, and in most cases we would expect the author of the change to help with updating the core community cookbooks.
How It Works
The project itself is a derivative of finstyle, but starts with all rules disabled. Cookstyle has a direct dependency on one specific version of RuboCop (at a time), and [patches it][patch] to load the [upstream configuration][upstream] and [custom set][config] of rule updates. When a new RuboCop release comes out, this library can rev its pinned version dependency and [re-vendor][rakefile] the upstream configuration to determine if any breaking style or lint rules were added/dropped/reversed/etc.
NOTE CAREFULLY ABOUT UPDATING COOKSTYLE
This is designed to allow bumping the rubocop engine while keeping backwards compatibility with the config and not requiring all the cookbooks to update.
The cookstyle_base.yml file is (essentially) the enabled.yml file from 0.37.2 (as of this writing) which is applied on top of 0.46.0 with all the rules disabled. It pins the default enabled set to 0.37.2 compatibility while running under the 0.46.0 engine.
There is no rake task for updating the cookstyle_base.yml
file. It was generated by hand -- the Description and other fields need to be dropped out of it.
It may be necessary to edit that file (again by hand) to resolve issues with later rubocop engines changing cop names (renaming, splitting up, etc).
Occasionally the cookstyle_base.yml
file should be updated, which will generate a lot of work to fix every cookbook that cookstyle runs against.
When updating to a new engine the rake vendor
task should still always be run in order to update the base set of cops and generate the default disabled.yml ruleset.
When editing the cookstyle_base.yml
becomes too much of a PITA, it may be time to bump the engine, run rake vendor
and then drop the new enabled.yml
into cookstyle_base.yml
, fix it up, and ship it and then deal with the fallout of all the new cops...
Installation
Cookstyle is included in the ChefDK. If you choose not to use ChefDK, you can still install Cookstyle manually using the instructions below.
Add this line to your application's Gemfile:
gem 'cookstyle'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cookstyle
Usage
Vanilla RuboCop
Run RuboCop as normal, simply add a -r cookstyle
option when running:
rubocop -r cookstyle -D --format offenses
cookstyle Command
Use this tool just as you would RuboCop, but invoke the cookstyle
binary instead which patches RuboCop to load rules from the cookstyle gem. For example:
cookstyle -D --format offenses
Rake
In a Rakefile, the setup is exactly the same, except you need to require the cookstyle library first:
require "cookstyle"
require "rubocop/rake_task"
RuboCop::RakeTask.new do |task|
task.options << "--display-cop-names"
end
guard-rubocop
You can use one of two methods. The simplest is to add the -r cookstyle
option to the :cli
option in your Guardfile:
guard :rubocop, cli: "-r cookstyle" do
watch(%r{.+\.rb$})
watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
end
Alternatively you could pass the path to Cookstyle's configuration by using the Cookstyle.config
method:
require "cookstyle"
guard :rubocop, cli: "--config #{Cookstyle.config}" do
watch(%r{.+\.rb$})
watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
end
.rubocop.yml
As with vanilla RuboCop, any custom settings can still be placed in a .rubocop.yml
file in the root of your project.