lint_roller - A plugin specification for linters

lint_roller is an itty-bitty plugin API for code analysis tools like linters and formatters. It provides plugins for those tools to load extensions and specify custom rulesets.

As of April 2025, both Standard Ruby and RuboCop rely on this gem for publishing plugins. And because lint_roller only specifies the basic lifecycle hooks a plugin system might need (as opposed to configuration formats or protocols), there's nothing preventing other tools like rufo or brakeman from adopting it. With broader support, a single gem could theoretically bundle separate configurations for many different analysis tools at a single version release (imagine a seattle-style gem, an official set of Sorbet recommendations, or an easy-to-distribute set of organization-wide styles).

How to make a plugin

If you want to make a plugin, the first thing you should do is extend LintRoller::Plugin with a custom class. Let's take this example plugin for banana-related static analysis:

moduleBananaRollerclassPlugin < LintRoller::Plugin# `config' is a Hash of options passed to the plugin by the userdefinitialize(config={})@alternative=config["alternative"] ||= "chocolate"enddefaboutLintRoller::About.new(name: "banana_roller",version: "1.0",# or, in a gem, probably BananaRoller::VERSIONhomepage: "https://github.com/example/banana_roller",description: "Configuration of banana-related code")end# `context' is an instance of LintRoller::Context provided by the runnerdefsupported?(context)context.engine == :rubocopend# `context' is an instance of LintRoller::Context provided by the runnerdefrules(context)LintRoller::Rules.new(type: :path,config_format: :rubocop,value: Pathname.new(__dir__).join("../../config/default.yml"))endendend

And that's pretty much it. Just a declarative way to identify your plugin, detect whether it supports the given LintRoller::Context (e.g. the current runner and engine and their respective _versions), for which the plugin will ultimately its configuration as a LintRoller::Rules object.

Packaging a plugin in a gem

In order for a formatter to use your plugin, it needs to know what path to require as well as the name of the plugin class to instantiate and invoke.

To make this work seamlessly for your users without additional configuration of their own, all you need to do is specify a metadata attribute called default_lint_roller_plugin in your gemspec.

Taking standard-custom as an example, its gemspec contains:

Gem::Specification.newdo |spec|
# …spec.metadata["default_lint_roller_plugin"]="Standard::Custom::Plugin"# …end

Because gem specs are loaded by RubyGems and Bundler very early, remember to specify the plugin as a string representation of the constant, as load order usually matters, and most tools will need to be loaded before any custom extensions. Hence, "Standard::Custom::Plugin" instead of Standard::Custom::Plugin.

Using your plugin

Once you've made your plugin, here's how it's configured from a Standard Ruby .standard.yml file.

If your plugin is packaged as a gem

Packaging your plugin in a gem is the golden path, both because distributing code via RubyGems.org is very neat, but also because it makes the least work for your users.

If your gem name is banana_roller and you've set spec.metadata["default_lint_roller_plugin"] to "BananaRoller::Plugin", then your users could just add this to their .standard.yml file:

plugins:
- banana_roller

And that's it! During initialization, standardrb will require "banana_roller" and know to call BananaRoller::Plugin.new(config) to instantiate it.

If your plugin ISN'T in a gem

If you're developing a plugin for internal use or in conjunction with a single project, you may want it to live in the same repo as opposed to packaging it in a gem.

To do this, then—in lieu of a gem name—provide the path you want to be required as its name, and (since there is no spec.metadata to learn of your plugin's class name), specify it as an option on the plugin:

plugins:
- lib/banana_roller/plugin:
plugin_class_name: BananaRoller::Plugin

(Be careful with the indentation here! Any configuration under a plugin must be indented in order for it to be parsed as a hash under the "lib/banana_roller/plugin" key.)

Additionally, if you want the plugin's name to make more sense, you can give it whatever name you like in the configuration and specify the require_path explicitly:

plugins:
- banana_roller:
require_path: lib/banana_roller/pluginplugin_class_name: BananaRoller::Plugin

Passing user configuration to the plugin

When a LintRoller::Plugin is instantiated, users can pass a configuration hash that tells your plugin how to behave.

To illustrate how this works in Standard Ruby, anything passed as a hash beneath a plugin will be passed to the class's initialize method:

plugins:
- apple_roller
- banana_roller:
require_path: lib/banana_roller/pluginplugin_class_name: BananaRoller::Pluginalternative: "apples"
- orange_roller:
rind: false

In the above case, apple_roller's plugin class will be instantiated with new({}), banana_roller will get all 3 of those parameters passed BananaRoller::Plugin.new({require_path…}), and orange_roller's class will be called with new({rind: false}).

Code of Conduct

This project follows Test Double's code of conduct for all community interactions, including (but not limited to) one-on-one communications, public posts/comments, code reviews, pull requests, and GitHub issues. If violations occur, Test Double will take any action they deem appropriate for the infraction, up to and including blocking a user from the organization's repositories.