lumin 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0e71927fa0a39ebcef64e2921aea21c7898ddbec64088640b69e0e8d6e88025
+  data.tar.gz: e7a8b7a424ed0fbc43a3de35dbc2bf8ebac9c5b3158e337fa88723d61cf03649
+SHA512:
+  metadata.gz: 59100309f1000e3577f0961dbec8e92deca533848b25956011ff54db828a754958de7bd43a762062475825a019d201a5a4d71a9d95bd7395be16bc8ef9c4425d
+  data.tar.gz: b134624d1dcf071c6f2296c2bc91a68e65c841f3e6861c904efab09e3b4656c8b5a2391b8859e6f0150918ca5cc148d9e40201204d531c167eca89ba519a6e64

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes are documented here following Keep a Changelog, and the
+project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-16
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,208 @@
+# 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`:
+
+```ruby
+gem "lumin", require: false
+```
+
+Then install the bundle:
+
+```sh
+bundle install
+```
+
+For use outside a bundle, install the gem directly:
+
+```sh
+gem install lumin
+```
+
+## Usage
+
+Run Lumin without paths to check the files selected by the configuration:
+
+```sh
+bundle exec lumin
+```
+
+Pass one or more files or directories to limit the check:
+
+```sh
+bundle exec lumin app/ lib/ spec/example_spec.rb
+```
+
+Apply safe corrections with `--fix`:
+
+```sh
+bundle exec lumin --fix
+```
+
+Preview corrections as a unified diff without changing files:
+
+```sh
+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:
+
+```sh
+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:
+
+```yaml
+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`:
+
+```sh
+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`:
+
+```yaml
+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](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:
+
+```sh
+bundle install
+bundle exec rake
+```
+
+Verify the packaged gem with:
+
+```sh
+bundle exec ruby script/package_smoke.rb
+```
+
+Benchmark instructions and recorded results are available in
+[benchmark/README.md](benchmark/README.md).
+
+## Contributing
+
+Bug reports and pull requests are welcome. Please include tests for behavior
+changes and update [CHANGELOG.md](CHANGELOG.md) when the change is
+user-visible.
+
+## License
+
+Lumin is available as open source under the terms of the
+[MIT License](LICENSE.txt).

data/RULES.md

@@ -0,0 +1,46 @@
+# Writing Lumin rules
+
+Rules inherit from `Lumin::Rule`. A rule may subscribe to Prism node types,
+run once for each source, or use both hooks. The dispatcher combines all node
+subscriptions into one AST walk.
+
+```ruby
+module Lumin
+  module Rules
+    module Lint
+      class NoEval < Lumin::Rule
+        MSG = "avoid eval"
+
+        on :call_node do |node|
+          add_offense(node.message_loc, message: MSG) if node.name == :eval
+        end
+      end
+    end
+  end
+end
+```
+
+Configuration defaults declare all supported rule-specific keys:
+
+```ruby
+default_config max: 120
+safe false
+```
+
+Pass a correction block to make an offense correctable. The block is evaluated
+only during `--fix` and receives an `Astel::Rewriter`:
+
+```ruby
+add_offense(node.location, message: MSG) do |rewriter|
+  rewriter.replace(node.location, "replacement")
+end
+```
+
+Rules are registered when their class inherits from `Lumin::Rule`. A plugin gem
+should require `lumin`, define its rules under its own module, then call
+`Lumin.register_plugin(MyPlugin::Rules)`. Plugin rule classes must still have
+stable, named constants so configuration names and cache keys remain stable.
+
+Rule tests can include the helper style used by Lumin itself:
+`expect_offense(code, rule: "Lint/NoEval")` and
+`expect_correction(code, corrected, rule: "Lint/NoEval")`.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/benchmark/README.md

@@ -0,0 +1,33 @@
+# Benchmarks
+
+Run the persistent benchmark against a substantial Ruby checkout. For example,
+after cloning Rails outside this repository:
+
+```sh
+bundle exec ruby benchmark/lumin_bench.rb ../rails
+```
+
+The script measures 1, 4, and 8 workers, followed by cold- and warm-cache
+runs. Set `RUBOCOP=1` to compare the same files against the two equivalent
+RuboCop rules. Set `VERIFY=1` to enforce the v0.1 performance gates: at least
+5x serial throughput with eight available cores, a warm-cache duration below
+one tenth of the cold run, and at least 10x RuboCop throughput.
+
+## Recorded result
+
+Measured 2026-07-13 on an Apple M4 Pro with 12 available physical CPUs,
+Ruby 4.0.0, Prism 1.9.0, and Rails commit
+`d7150bfc0109b33165cec73f24b1cdf17b252566` (3,433 Ruby files):
+
+| Mode | Time |
+|---|---:|
+| 1 worker | 1.026s |
+| 4 workers | 0.336s |
+| 8 workers | 0.204s |
+| 12 workers | 0.195s |
+| Cold cache | 1.708s |
+| Warm cache, new Runner | 0.056s |
+| RuboCop, same files and equivalent rules | 16.659s |
+
+The measured 8-worker speedup was 5.03x, the persistent warm cache was 30.5x
+faster than the cold run, and the all-core run was 85.26x faster than RuboCop.

data/benchmark/lumin_bench.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "benchmark"
+require "bundler"
+require "etc"
+require "open3"
+require "tmpdir"
+require "lumin"
+
+root = File.expand_path(ARGV.fetch(0) { abort("usage: #{$PROGRAM_NAME} PROJECT_ROOT") })
+paths = Dir.glob(File.join(root, "**", "*.rb"))
+abort("no Ruby files found under #{root}") if paths.empty?
+
+samples = Integer(ENV.fetch("SAMPLES", "3"), 10)
+config = Lumin::Config.from_hash({})
+measure = lambda do |workers|
+  Array.new(samples) do
+    Benchmark.realtime do
+      Lumin::Runner.new(config: config, parallel: workers, cache: false).run(paths)
+    end
+  end.sort.fetch(samples / 2)
+end
+
+puts "files: #{paths.length}"
+available_cpus = Etc.nprocessors
+puts "available CPUs: #{available_cpus}"
+worker_counts = [1, 4, 8, available_cpus].uniq
+timings = worker_counts.to_h do |workers|
+  elapsed = measure.call(workers)
+  puts format("workers=%d median: %.3fs", workers, elapsed)
+  [workers, elapsed]
+end
+
+Dir.mktmpdir("lumin-cache") do |cache_dir|
+  cold_runner = Lumin::Runner.new(config: config, parallel: false, cache_dir: cache_dir)
+  cold = Benchmark.realtime { cold_runner.run(paths) }
+  warm_runner = Lumin::Runner.new(config: config, parallel: false, cache_dir: cache_dir)
+  warm = Benchmark.realtime { warm_runner.run(paths) }
+  puts format("cache cold: %.3fs", cold)
+  puts format("cache warm (new runner): %.3fs", warm)
+  abort("warm cache is not at least 10x faster") if ENV["VERIFY"] == "1" && warm * 10 >= cold
+end
+
+speedup = timings.fetch(1) / timings.fetch(8)
+puts format("8-worker speedup: %.2fx", speedup)
+if ENV["VERIFY"] == "1" && Etc.nprocessors >= 8 && speedup < 5.0
+  abort(format("8-worker speedup is below 5x: %.2fx", speedup))
+end
+
+if ENV["RUBOCOP"] == "1"
+  rubocop_config = File.expand_path("rubocop.yml", __dir__)
+  command = ["rubocop", "--config", rubocop_config, "--cache", "false", "--format", "quiet", *paths]
+  status = nil
+  rubocop = Benchmark.realtime do
+    Bundler.with_unbundled_env do
+      _stdout, stderr, status = Open3.capture3(*command)
+      abort("RuboCop benchmark failed: #{stderr.lines.first}") unless [0, 1].include?(status.exitstatus)
+    end
+  end
+  fastest_lumin = timings.fetch(available_cpus)
+  ratio = rubocop / fastest_lumin
+  puts format("RuboCop: %.3fs", rubocop)
+  puts format("Lumin vs RuboCop: %.2fx", ratio)
+  abort(format("Lumin is less than 10x faster than RuboCop: %.2fx", ratio)) if ENV["VERIFY"] == "1" && ratio < 10
+end

data/benchmark/rubocop.yml

@@ -0,0 +1,11 @@
+AllCops:
+  DisabledByDefault: true
+  NewCops: disable
+  TargetRubyVersion: 3.3
+
+Layout/LineLength:
+  Enabled: true
+  Max: 120
+
+Style/FrozenStringLiteralComment:
+  Enabled: true

data/exe/lumin

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "lumin/cli"
+
+exit Lumin::CLI.start

data/lib/lumin/autocorrector.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tempfile"
+require "astel"
+require_relative "error"
+require_relative "source_snapshot"
+
+module Lumin
+  class Autocorrector
+    class CorrectionError < Error; end
+
+    Result = Data.define(:offenses, :corrected, :diff, :warnings, :content_digest, :fingerprint)
+
+    def initialize(worker, max_iterations: 5)
+      @worker = worker
+      @max_iterations = max_iterations
+    end
+
+    def call(path, unsafe: false, dry_run: false)
+      snapshot = SourceSnapshot.read(path)
+      original = snapshot.source
+      current = original
+      warnings = []
+      iterations = 0
+      source = parse(current, path)
+
+      @max_iterations.times do
+        iterations += 1
+        break unless source.valid?
+
+        offenses = @worker.lint_source(source)
+        corrections = offenses.select { |offense| offense.correctable? && (offense.safe || unsafe) }
+        break if corrections.empty?
+
+        rewriter = Astel::Rewriter.new(source)
+        corrections.each do |offense|
+          begin
+            offense.correction.call(rewriter)
+          rescue Astel::Rewriter::ConflictError
+            warnings << "#{path}: skipped conflicting correction for #{offense.rule_name}"
+          end
+        end
+        break if rewriter.edits.empty?
+
+        rewritten = rewriter.rewrite
+        break if rewritten == current
+
+        parsed = parse(rewritten, path)
+        raise CorrectionError, "autocorrection produced invalid Ruby for #{path}" unless parsed.valid?
+
+        current = rewritten
+        source = parsed
+      end
+
+      final_offenses = @worker.lint_source(source)
+      remaining = final_offenses.any? { |offense| offense.correctable? && (offense.safe || unsafe) }
+      if iterations == @max_iterations && remaining
+        warnings << "#{path}: autocorrection did not converge after #{@max_iterations} iterations"
+      end
+      corrected = current != original
+      fingerprint = if corrected && !dry_run
+                      write_atomically(path, current, expected_fingerprint: snapshot.fingerprint)
+                    elsif corrected
+                      nil
+                    else
+                      snapshot.fingerprint
+                    end
+      Result.new(
+        offenses: final_offenses,
+        corrected: corrected,
+        diff: corrected && dry_run ? unified_diff(path, original, current) : nil,
+        warnings: warnings.uniq.freeze,
+        content_digest: Digest::SHA256.hexdigest(current),
+        fingerprint: fingerprint
+      )
+    end
+
+    private
+
+    def parse(source, path)
+      Astel::SourceFile.from_string(source, path: path, version: @worker.config.target_ruby)
+    end
+
+    def write_atomically(path, content, expected_fingerprint:)
+      stat = File.stat(path)
+      Tempfile.create([".lumin", ".rb"], File.dirname(File.expand_path(path))) do |file|
+        file.binmode
+        file.write(content)
+        file.flush
+        file.fsync
+        File.chmod(stat.mode, file.path)
+        file.close
+        unless SourceSnapshot.fingerprint(path) == expected_fingerprint
+          raise CorrectionError, "#{path} changed during autocorrection; refusing to overwrite it"
+        end
+        File.rename(file.path, path)
+      end
+      written_fingerprint(path, content)
+    end
+
+    def written_fingerprint(path, content)
+      snapshot = SourceSnapshot.read(path)
+      snapshot.fingerprint if snapshot.source == content
+    rescue SourceSnapshot::ChangedError, SystemCallError
+      nil
+    end
+
+    def unified_diff(path, before, after)
+      before_lines = before.lines
+      after_lines = after.lines
+      output = +"--- #{path}\n+++ #{path}\n"
+      output << "@@ -1,#{before_lines.length} +1,#{after_lines.length} @@\n"
+      before_lines.each do |line|
+        output << "-#{line}"
+        output << "\n" unless line.end_with?("\n")
+      end
+      after_lines.each do |line|
+        output << "+#{line}"
+        output << "\n" unless line.end_with?("\n")
+      end
+      output
+    end
+  end
+end