RuboCop — Ruby Static Code Analyzer and Formatter

Introduction

RuboCop enforces the community Ruby style guide through static analysis and automatic formatting. It catches style violations, naming issues, and code complexity problems, then auto-corrects many of them. It is the standard linter in the Ruby ecosystem.

What RuboCop Does

• Checks Ruby source files against hundreds of configurable cops (rules)
• Auto-corrects safe violations with -a and all correctable violations with -A
• Supports department-based organization: Layout, Lint, Metrics, Naming, Style, and Security
• Integrates with editors, CI pipelines, and pre-commit hooks
• Generates TODO files for incremental adoption on legacy codebases

Architecture Overview

RuboCop uses the parser gem to produce an AST from Ruby source files. Each cop is a class that registers on specific AST node types via a visitor pattern. The runner coordinates file discovery, cop execution, and formatter output. Auto-correction works by rewriting source ranges on the AST, with conflict resolution for overlapping corrections.

Self-Hosting & Configuration

• Install as a gem (gem install rubocop) or add to your Gemfile as a development dependency
• Create a .rubocop.yml file to enable, disable, or configure individual cops
• Generate a .rubocop_todo.yml with rubocop --auto-gen-config to baseline existing violations
• Add department-specific extensions like rubocop-rails, rubocop-rspec, or rubocop-performance
• Use inherit_from in .rubocop.yml to share configurations across projects

Key Features

• Over 450 built-in cops covering style, lint, metrics, naming, and security
• Safe and unsafe auto-correction modes for fixing violations automatically
• Extension gems for Rails, RSpec, Minitest, Performance, and more
• Caching for fast incremental analysis on unchanged files
• Multiple output formatters including JSON, HTML, and GitHub Actions annotations

Comparison with Similar Tools

• Standard — a zero-configuration RuboCop wrapper with opinionated defaults; RuboCop offers full customization
• Reek — detects code smells like feature envy and long methods; RuboCop covers broader style and lint rules
• Flay — finds duplicated code; RuboCop focuses on style and correctness rather than duplication
• Brakeman — scans for Rails security vulnerabilities; RuboCop covers general code quality with a smaller security department

FAQ

Q: How do I adopt RuboCop on a large legacy codebase? A: Run rubocop --auto-gen-config to create a TODO file that disables all current violations, then enable cops incrementally.

Q: What is the difference between -a and -A? A: The -a flag applies only safe corrections that preserve behavior. The -A flag also applies unsafe corrections that may change semantics.

Q: Can I write custom cops? A: Yes. Create a class inheriting from RuboCop::Cop::Base, define on_send or other node callbacks, and register it via a plugin or require in .rubocop.yml.

Q: Does RuboCop support Ruby 3.x syntax? A: Yes. RuboCop tracks the latest Ruby syntax through the parser gem and adds cops for new language features.

Sources

• https://github.com/rubocop/rubocop
• https://docs.rubocop.org/