RuboCop plugins/extensions API

[palkan]

Some thoughts on plugins/extensions API after writing a rubocop-md gem (btw, @bbatsov I'd like to transfer this gem to rubocop-hq if you don't mind).

• Ability to customize supported file extensions list Solved by Ability to specify files/directories to look at and ignore everything else #4247

• Ability to extend the default configuration.

When inheriting from default, the plugin's default configuration should be merged into it.

Right now we have to monkey-patch (see, for example, rubocop-rspec).

Related method is ConfigLoader#default_configuration:

def default_configuration
  @default_configuration ||= begin
    print 'Default ' if debug?
    load_file(DEFAULT_FILE)
  end
end

Suppose that we have a list of plugins. The the method could look like this:

def default_configuration
  @default_configuration ||= begin
    print 'Default ' if debug?
    plugins.inject(load_file(DEFAULT_FILE)) do |config, plugin|
      resolver.merge(config, plugin.default_config)
    end
  end
end

More specific features (but it would be great to have a way to do that without monkey-patching):

• Source pre-processing.

Ability to modify the source before parsing it (example).

It's a way to generate a Ruby-parseable contents from non-Ruby files.

• Post-processing after auto-correct.

Ideally, it would be great to make it possible to inject between any two steps in the process:

<start> -> read file -> parse code -> run cop (n times) -> perform auto-correct -> <finish>

These features are mostly useful to use RuboCop with non-Ruby files; there are some existing projects, such as https://github.com/ericqweinstein/ruumba, https://github.com/brigade/haml-lint.

We can introduce a plugin interface like this:

class MyRubocopPlugin < Rubocop::Plugin
  # register default config extension
  default_config File.join(__dir__, "default.yml")

  # conditionally enable plugins
  enable_if ->(filename) { markdown?(filename) }

  # register source preprocessing hook;
  # accepts callable object
  pre_process_source MyRubocopPluging::Preprocessor
  
  # register source post processing hook, which is called
  # when auto-correct generates a new code and before it's written to file,
  # so we can revert our pre-processing
  post_process_source MyRubocopPluging::Postprocessor

  # hook into auto-correct process; for example, we can build interactive auto-correct
  # by asking a user before adding a correction to the Corrector
  # (that's something I was thinking about for a long time, but it's not easy to implement right now)
  pre_autocorrect ->(correction) {
    # when `false` is returned then skip the correction
    prompt "Apply? y/n >\n#{correction}"
  }
end

[bbatsov]

Some thoughts on plugins/extensions API after writing a rubocop-md gem (btw, @bbatsov I'd like to transfer this gem to rubocop-hq if you don't mind).

I've just invited you to RuboCop HQ, so you can transfer the gem at your convenience.

When inheriting from default, the plugin's default configuration should be merged into it.

Yeah, I completely agree. This should be an easy change.

Ideally, it would be great to make it possible to inject between any two steps in the process:

Agree with you here as well.

I seem to recall you owe me a few PRs, so you might start by tackling this. ;-)

[palkan]

I seem to recall you owe me a few PRs, so you might start by tackling this. ;-)

Sure. I'll start right after Paris.rb)

[palkan]

@bbatsov

I've just invited you to RuboCop HQ, so you can transfer the gem at your convenience.

Done!

[splattael]

@bbatsov @palkan

Is the current implementation and the use of RuboCop's internal API as done in rubocop-md something you would recommend for other RuboCop plugins?

See https://github.com/rubocop/rubocop-md/blob/2fb1a9a6f847effad88840d0cb3afdb1d301413b/lib/rubocop/markdown/rubocop_ext.rb#L43-L84

Are there plans to enhance the documentation with how to create a plugin? I wasn't able to find anything related.

Just asking for the "best practices" 😀

Are there any other RuboCop plugins available where I can look at? 🤔

Edit: Oh I found some

• https://github.com/rubocop/rubocop-rake/blob/master/lib/rubocop/rake/inject.rb
• https://github.com/rubocop/rubocop-rails/blob/master/lib/rubocop/rails/inject.rb
• https://github.com/rubocop/rubocop-rspec/blob/master/lib/rubocop/rspec/inject.rb

🎉

[dvandersluis]

There is no official plugin architecture right now unfortunately. The solutions some of the extension libraries have used (such as the inject.rb file) are stable, but are susceptible to breaking if/when RuboCop itself changes.

A small amount of configuration has been moved to be more extensible by extensions, but there is much more that works now by hacks. https://docs.rubocop.org/rubocop/extensions.html is probably the best "documentation" right now but it's pretty sparse.

[splattael]

@dvandersluis Thanks for the fast and insightful response ❤️

I mixed up extensions with plugins - actually I thought these were two different concepts - they aren't 👍

https://github.com/rubocop/rubocop-extension-generator is a great starting point 🎉