rubocop-gradual

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

rubocop-gradual

★ 38 Open GitHub ↗

Gradually improve your code with RuboCop

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# RuboCop Gradual

[![Gem Version](https://badge.fury.io/rb/rubocop-gradual.svg)](https://rubygems.org/gems/rubocop-gradual)
[![Build](https://github.com/skryukov/rubocop-gradual/workflows/Build/badge.svg)](https://github.com/skryukov/rubocop-gradual/actions)

RuboCop Gradual is a tool that helps track down and fix RuboCop offenses in your code gradually. It's a more flexible alternative to RuboCop's `--auto-gen-config` option.

RuboCop Gradual:

- generates the lock file with all RuboCop offenses and uses hashes to track each offense **line by line**
- **automatically** updates the lock file on every successful run, but returns errors on new offenses
- does not prevent your editor from **showing ignored offenses**

Gain full control of gradual improvements: just add `rubocop-gradual` and use it as proxy for `rubocop`.

<img src="https://cdn.evilmartians.com/badges/logo-no-label.svg" alt="Evil Martians logo" width="22" height="16" /> RuboCop Gradual is built by <a href="https://evilmartians.com/">Evil Martians</a>, an American design and engineering consultancy for developer tools, AI, and cybersecurity startups.

## Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add rubocop-gradual

Run RuboCop Gradual to create a lock file (defaults to `.rubocop_gradual.lock`):

$ rubocop-gradual

Commit the lock file to the project repository to keep track of all non-fixed offenses.

Run `rubocop-gradual` before commiting changes to update the lock file. RuboCop Gradual will keep updating the lock file to keep track of all non-fixed offenses, but it will throw an error if there are any new offenses.

## Usage

Proposed workflow:

- Remove `rubocop_todo.yml` if it exists.
- Run `rubocop-gradual` to generate a lock file and commit it to the project repository.
- Add `rubocop-gradual --check` to your CI pipeline instead of `rubocop`/`standard`. It will throw an error if the lock file is out of date.
- Run `rubocop-gradual` to update the lock file, or `rubocop-gradual -a` to run autocorrection for all new and changed files and then update the lock file.
- Optionally, add `rubocop-gradual` as a pre-commit hook to your repository (using [lefthook], for example).
- RuboCop Gradual will throw an error on any new offense, but if you really want to force update the lock file, run `rubocop-gradual --force-update`.

## Available options

```
    -U, --force-update               Force update Gradual lock file.
        --check                      Check Gradual lock file is up-to-date.
    -a, --autocorrect                Autocorrect offenses (only when it's safe).
    -A, --autocorrect-all            Autocorrect offenses (safe and unsafe).
        --gradual-file FILE          Specify Gradual lock file.
        --standard                   Lint with the Standard ruleset.
        --list, --list-target-files  List target files.
    -v, --version                    Display version.
    -h, --help                       Prints this help.
```

## Rake tasks

To use built-in Rake tasks add the following to your Rakefile:

```ruby
# Rakefile
require "rubocop/gradual/rake_task"

RuboCop::Gradual::RakeTask.new
```

This will add rake tasks:

```
bundle exec rake -T
rake rubocop_gradual                  # Run RuboCop Gradual
rake rubocop_gradual:autocorrect      # Run RuboCop Gradual with autocorrect (only when it's safe)
rake rubocop_gradual:autocorrect_all  # Run RuboCop Gradual with autocorrect (safe and unsafe)
rake rubocop_gradual:check            # Run RuboCop Gradual to check the lock file
rake rubocop_gradual:force_update     # Run RuboCop Gradual to force update the lock file
```

It's possible to customize the Rake task name and options:

```ruby
# Rakefile

require "rubocop/gradual/rake_task"

RuboCop::Gradual::RakeTask.new(:custom_task_name) do |task|
  task.options = %w[--gradual-file custom_gradual_file.lock]
  task.verbose = false
end
```

## Partial linting (experimental)

RuboCop Gradual supports partial linting. It's useful when you want to run RuboCop Gradual on a subset of files, for example, on changed files in a pull request:

```shell
rubocop-gradual path/to/file # run `rubocop-gradual` on a subset of files
rubocop-gradual --staged # run `rubocop-gradual` on staged files
rubocop-gradual --unstaged # run `rubocop-gradual` on unstaged files
rubocop-gradual --commit origin/main # run `rubocop-gradual` on changed files since the commit

# it's possible to combine options with autocorrect:
rubocop-gradual --staged --autocorrect # run `rubocop-gradual` with autocorrect on staged files
```

## Standard support (experimental)

RuboCop Gradual can lint with the [Standard] ruleset instead of a RuboCop configuration. Add the [standard gem] to your Gemfile and pass the `--standard` option:

```shell
rubocop-gradual --standard # run `rubocop-gradual` with the Standard ruleset
rubocop-gradual --standard -a # run `rubocop-gradual` with the Standard ruleset and autocorrect
```

RuboCop Gradual picks up `.standard.yml` and `.standard_todo.yml` configuration files, so existing Standard setups work as is.

## Require mode (experimental)

RuboCop Gradual can be used in "Require mode", which is a way to replace `rubocop` with `rubocop-gradual`:

```yaml
# .rubocop.yml

require:
  - rubocop/gradual/patch
```

Now base `rubocop` command will run `rubocop-gradual`:

```shell
rubocop # run `rubocop-gradual`
rubocop -a # run `rubocop-gradual` with autocorrect (only when it's safe)
rubocop -A # run `rubocop-gradual` with autocorrect (safe and unsafe)
rubocop gradual check # run `rubocop-gradual` to check the lock file
rubocop gradual force_update # run `rubocop-gradual` to force update the lock file
```

To set a custom path to Gradual lock file, add `--gradual-file FILE` to a special `.rubocop-gradual` file:

```
# .rubocop-gradual
--rubocop-gradual-file path/to/my_lock_file.lock
```

To temporarily disable RuboCop Gradual, prepend command with `NO_GRADUAL=1`:

```shell
NO_GRADUAL=1 rubocop # run `rubocop`
```

## Alternatives

- [RuboCop TODO file]. Comes out of the box with RuboCop. Provides a way to ignore offenses on the file level, which is problematic since it is possible to introduce new offenses without any signal from linter.
- [Pronto]. Checks for offenses only on changed files. Does not provide a way to temporarily ignore offenses.
- [Betterer]. Universal test runner that helps make incremental improvements witten in JavaScript. RuboCop Gradual is highly inspired by Betterer.

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`.

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/skryukov/rubocop-gradual

## License

The gem is available as open source under the terms of the [MIT License].

[lefthook]: https://github.com/evilmartians/lefthook
[Standard]: https://github.com/standardrb/standard
[standard gem]: https://rubygems.org/gems/standard
[RuboCop TODO file]: https://docs.rubocop.org/rubocop/configuration.html#automatically-generated-configuration
[Pronto]: https://github.com/prontolabs/pronto-rubocop
[Betterer]: https://github.com/phenomnomnominal/betterer
[MIT License]: https://opensource.org/licenses/MIT

rubocop-gradual

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README