Lumin

Lumin is a fast, Prism-native linter for Ruby. It parses and walks each file once, regardless of the number of enabled rules, and is designed for fast feedback on both local checkouts and CI.

Features

A single Prism parse and AST walk per file
Process-based parallelism with a thread fallback on platforms without fork
Content-addressed caching that accounts for source, configuration, version, and enabled rules
Safe autocorrection, optional unsafe corrections, and dry-run diffs
Text, JSON, and GitHub Actions output formats
Strict configuration validation and shareable configuration through files or gems
A plugin API for adding project-specific rules

Requirements

Lumin requires Ruby 3.3 or newer.

Installation

Add Lumin to your Gemfile:

gem "lumin", require: false

Then install the bundle:

bundle install

For use outside a bundle, install the gem directly:

gem install lumin

Usage

Run Lumin without paths to check the files selected by the configuration:

bundle exec lumin

Pass one or more files or directories to limit the check:

bundle exec lumin app/ lib/ spec/example_spec.rb

Apply safe corrections with --fix:

bundle exec lumin --fix

Preview corrections as a unified diff without changing files:

bundle exec lumin --fix --dry-run

Use --fix-unsafe to include corrections declared unsafe by a rule.

Output formats

The default output is human-readable text. JSON and GitHub Actions annotations are also available:

bundle exec lumin --format json
bundle exec lumin --format github

Exit status

Status	Meaning
`0`	No offenses remain
`1`	One or more offenses were found
`2`	Configuration or execution failed

Configuration

Lumin works without a configuration file. To customize it, create .lumin.yml in the project root:

target_ruby: "3.3"

include:
  - "app/**/*.rb"
  - "lib/**/*.rb"
  - "spec/**/*.rb"

exclude:
  - "vendor/**/*"
  - "tmp/**/*"

rules:
  Style/FrozenStringLiteral:
    enabled: true
    autocorrect: true
  Style/LineLength:
    max: 120
  Lint/NoMethodMissing:
    enabled: false

target_ruby controls the Ruby version passed to Prism when parsing source. The default is Ruby 3.3. Unknown top-level keys, rule names, and rule settings are rejected before linting begins.

Any rule can be disabled with enabled: false. For a correctable rule, autocorrect: false reports offenses without applying its corrections.

Use a different configuration file with --config:

bundle exec lumin --config config/lumin.yml

Inheriting configuration

inherit_from accepts a local path or the name of a gem that provides either .lumin.yml or config/lumin.yml:

inherit_from:
  - config/lumin_base.yml
  - lumin-config-example

rules:
  Style/LineLength:
    max: 100

Inherited mappings are deeply merged, and the current file takes precedence.

Built-in rules

All built-in rules are enabled by default.

Rule	Description	Configuration	Autocorrect
`Style/FrozenStringLiteral`	Requires a `frozen_string_literal` magic comment	—	Safe
`Style/LineLength`	Reports lines longer than the configured limit	`max` (default: `120`)	No
`Lint/NoMethodMissing`	Reports definitions of `method_missing`	—	No

See RULES.md for the rule and plugin API.

Command-line options

Option	Description
`-c`, `--config PATH`	Use a specific configuration file
`-f`, `--format NAME`	Select `text`, `json`, or `github` output
`--parallel[=N]`	Enable parallel execution with an optional worker count
`--no-parallel`	Force serial execution
`--[no-]cache`	Enable or disable the result cache
`--cache-dir PATH`	Use a specific cache directory
`--clear-cache`	Remove cached results and exit
`--fix`	Apply safe corrections
`--fix-unsafe`	Apply both safe and unsafe corrections
`--dry-run`	Print corrections as a diff; requires `--fix`
`-v`, `--version`	Print the Lumin version
`-h`, `--help`	Print command-line help

By default, Lumin estimates the workload from the total input size. Small runs stay serial to avoid process startup overhead, while larger runs add workers gradually up to the available CPU count. Use --parallel=N to choose an exact maximum or --no-parallel to force serial execution. The result cache is stored under $XDG_CACHE_HOME/lumin or ~/.cache/lumin.

Development

Install dependencies and run the test suite:

bundle install
bundle exec rake

Verify the packaged gem with:

bundle exec ruby script/package_smoke.rb

Benchmark instructions and recorded results are available in benchmark/README.md.

Contributing

Bug reports and pull requests are welcome. Please include tests for behavior changes and update CHANGELOG.md when the change is user-visible.

License

Lumin is available as open source under the terms of the MIT License.