About Cookstyle

Cookstyle is a code linting tool that helps you write better Chef Infra cookbooks by detecting and automatically correcting style, syntax, and logic mistakes in your code.

Cookstyle is powered by the RuboCop linting engine. RuboCop ships with over 300 rules, or cops, designed to detect common Ruby coding mistakes and enforce a common coding style. We’ve customized Cookstyle with a subset of those cops tailored for cookbook development. We also ship Chef-specific cops that catch common cookbook coding mistakes, clean up portions of code that are no longer necessary, and detect deprecations that prevent cookbooks from running on the latest releases of Chef Infra Client.

Cookstyle increases code quality by:

• Enforcing style conventions and best practices.
• Helping every member of a team author similarly structured code.
• Maintaining uniformity in the source code.
• Setting expectations for fellow (and future) project contributors.
• Detecting deprecated code that creates errors after upgrading to a newer Chef Infra Client release.
• Detecting common Chef Infra mistakes that cause code to fail or behave incorrectly.

Cookstyle vs RuboCop

Cookstyle is more stable than RuboCop and is customized for Chef cookbook code. This means that linting cookbooks with Cookstyle will be more consistent and less likely to produce CI test failures.

Tailored cops

Cookbook development differs from traditional Ruby software development, so we maintain a tailored set of built-in cops from RuboCop. Cops that aren’t useful for cookbook development are disabled, and occasionally we change the configuration of a rule to enforce a different behavior. We’ve also extended the base RuboCop package with a set of our own Chef Infra-specific cops. These cops are only found in Cookstyle and will help you write more reliable and future-proof cookbooks.

New cops

New cops are continuously added to RuboCop. New cops can make an existing codebase fail CI tests and force authors to constantly update their code.

With Cookstyle, we update the RuboCop engine for bug and performance fixes, but we only change the set of cops that will fail tests once a year during Chef Infra’s major release in April. All new cops are introduced at RuboCop’s refactor alert level, meaning they will alert to the screen as you run Cookstyle, but they won’t fail a build. This stability means you are free to upgrade releases of Cookstyle without being forced to update your infrastructure code.

Run Cookstyle

Run Cookstyle from the command line, typically against a single cookbook and the Ruby files within it:

cookstyle /path/to/cookbook

You can also run Cookstyle from the root of an individual cookbook directory:

cookstyle .

Cookstyle returns a list, through standard output, that shows the results of the evaluation:

Inspecting 8 files
CWCWCCCC

Offences:

cookbooks/apache/attributes/default.rb:1:1: C: Missing utf-8 encoding comment.
default["apache"]["indexfile"] = "index1.html"
^
cookbooks/apache/attributes/default.rb:1:9: C: Prefer single-quoted strings when you don't
need string interpolation or special symbols.
default["apache"]["indexfile"] = "index1.html"
        ^^^^^^^^
cookbooks/apache/attributes/default.rb:1:19: C: Prefer single-quoted strings when you
don't need string interpolation or special symbols.
default["apache"]["indexfile"] = "index1.html"
                  ^^^^^^^^^^^

Output

Cookstyle output:

• States the number of files found and examined. For example: Inspecting 8 files
• Lists the results of those files as a series of symbols. For example: CWCWCCCC
• For each symbol, states the file name, line number, character number, type of issue or error, describes the issue or error, and specifies the location in the source code at which the issue or error is located

A Cookstyle evaluation has the following syntax:

FILENAME:LINE_NUMBER:CHARACTER_NUMBER: TYPE_OF_ERROR: MESSAGE
SOURCE CODE
^^^^^^^^^^^

For example:

cookbooks/apache/attributes/default.rb:1:9: C: Prefer single-quoted strings when you don't
need string interpolation or special symbols.
default["apache"]["indexfile"] = "index1.html"
        ^^^^^^^^

Symbols

The following symbols appear in the standard output to indicate the result of an evaluation:

.

The file doesn’t have any issues.

C

The file has an issue with convention.

E

The file contains an error.

F

The file contains a fatal error.

W

The file contains a warning.

R

The file contains code that should be refactored.

Autocorrecting Cookstyle warnings

Many Cookstyle cops can autocorrect violations. To autocorrect code, run the following command from the cookbook directory:

cookstyle -a .

After running this command, verify that the autocorrection logic results in appropriate cookbook code.

.rubocop.yml

Use a .rubocop.yml file in a cookbook to override the default settings in Cookstyle for enabled and disabled rules. Only enabled rules—either in the enabled.yml file in Cookstyle itself or rules that are specifically enabled in a cookbook’s .rubocop.yml file—will be used during the evaluation. Any rule that becomes unhelpful should be disabled in the .rubocop.yml file.

Each cookbook has its own .rubocop.yml file, which means that each cookbook may have its own set of enabled, disabled, and custom rules. That said, it’s more common for all cookbooks to have the same set of enabled, disabled, and custom rules. When RuboCop is run against a cookbook, the full set of enabled and disabled rules (as defined in the enabled.yml and disabled.yml files in Cookstyle itself) are loaded first, and are then compared against the settings in the cookbook’s .rubocop.yml file.

Custom rules should be specified in the .rubocop.yml file. The state of rules—enabled or disabled—in a .rubocop.yml file take precedence over the state of rules defined in the enabled.yml and disabled.yml files.

Syntax

A .rubocop.yml file has the following syntax:

NAME_OF_RULE:
  Description: 'a description of a rule'
  Enabled: (true or false)
  KEY: VALUE

where

• NAME_OF_RULE is the name of a rule
• Description is the string that prints as part of the standard output that describes the rule if it’s triggered during the evaluation
• Enabled enables a rule (true) or disables a rule (false); for non-custom rules, this value will override the settings in the enabled.yml and disabled.yml files in Cookstyle
• KEY: VALUE adds additional details for a rule, if necessary. For example, Max: 200 sets the line length to 200 characters for the LineLength rule

.rubocop_todo.yml

Use a .rubocop_todo.yml file to capture the current state of all evaluations. This allows evaluations to be reviewed one at a time. Disable any unhelpful evaluations, then address the remaining ones.

To generate the .rubocop_todo.yml file, run the following command:

cookstyle --auto-gen-config

Disable Cookstyle cops in code

Use Cookstyle-specific comments in your cookbook code to enable or disable cops. You can also use standard RuboCop comments to enable and disable cops.

Disable a cop using a RuboCop comment:

node.normal[:foo] # rubocop: disable ChefCorrectness/Bar

Disable a cop using a Cookstyle comment:

node.normal[:foo] # cookstyle: disable ChefCorrectness/Bar

Disable a cop in a section of a file using a Cookstyle comment:

# cookstyle: disable ChefCorrectness/Bar
node.normal[:foo]
# cookstyle: enable ChefCorrectness/Bar