scully 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60f372659dc1904e0b9c5cc49099d0076b44c6b824a71a56db36d1b803a0cc74
-  data.tar.gz: a42de17b73055ce13d28c6f757ba6aff96219d200f9a84396206c427af6fca44
+  metadata.gz: c42579c421ad026eb06b80cc2e42d679a39d3a5bec2789ef73e26857888b2e69
+  data.tar.gz: 8cf9890e7b6f5b3c54cf3a77f22124624f7523f86b0f73bc678ef2b3bf382ddc
 SHA512:
-  metadata.gz: 281a93104a33ac19bc5d1d64a7dc285b8dd41fb799e56efd95ec72e6be31e5499d47b31c74d5a9709bbb11c61bb574a6743e3256a442d8fd1010b933419e7088
-  data.tar.gz: 6a7fc73c2d86148264f5751356fc6f6211fefe05255a35af3447745593051332c1b4641f18648dc61d8ad8344e2187156066b982a1dcfb830dadb1a8fa46651d
+  metadata.gz: 8dd3ac44b0c9e686943493444f2ad1273a4b5d3cee9da46029cdd6456fc0c8cf4f44cf577d0e0234d7e5014d6a0ea9c237fdb5d3076ae0c91b9aad341cb5013e
+  data.tar.gz: 461bbbab137a7fcca5837c9ed250e6fe28d36cf706beeb91d2be87e684500d9ee66ff63f6afa98fd4910b788fd90c8b805efb00caf4c9f51345cf51b61ec2936

data/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-10-14
+
+First usable release: a static checker that reports RSpec and Minitest tests that cannot be
+trusted as evidence of behaviour. It reads tests with Prism and never runs them.
+
+### Added
+
+- `scully check [PATH ...]` (or bare `scully`) finds `*_spec.rb` and `*_test.rb` files, works
+  out whether each is RSpec or Minitest, and prints a report grouped into errors, warnings and
+  skipped files, with source snippets, a summary line and one `scully why` command per finding.
+- Rule `no_assertion` (warning): an active test whose body makes no assertion. Counts RSpec
+  expectations, Minitest assertions and expectations, mocha and `Minitest::Mock` message
+  expectations, Minitest-style `assert`/`refute` calls in RSpec examples (including Capybara's
+  `page.assert_selector`), `assert_*`/`expect_*` helpers, and helpers defined in the same file
+  that assert.
+- Rule `tautology` (error): an equality assertion that compares a stubbed method with the value
+  the test stubbed it to return, so it can never fail. The stub is shown next to the assertion.
+- Syntax errors are reported as `parse` errors. Findings from a file that could not be read
+  completely are marked inconclusive, and such a file makes the run exit 1, so a broken suite
+  never looks clean.
+- `scully why PATH[:LINE]` explains a finding: why it matters, what scully saw, how to fix it,
+  how certain it is, and the matching RuboCop cop, if any. Without a line it lists the file's
+  findings.
+- `--color` and `--hyperlinks` options (`auto`, `always`, `never`), honouring `NO_COLOR` and
+  `FORCE_HYPERLINK`. Colour and links never change the text.
+- Exit status 0 for a clean run, 1 for findings or incomplete files, 2 when scully cannot run.
+- Output is deterministic: the same files give byte-identical output whatever the argument
+  order, locale or checkout location.
+
 ## [0.0.1] - 2026-10-12
 
 - Initial release
+
+[Unreleased]: https://github.com/theomelo/scully/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/theomelo/scully/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/theomelo/scully/releases/tag/v0.0.1

data/README.md

@@ -1,15 +1,20 @@
 # Scully
 
-"The truth is out there"  (Use tests to prove it!)
+"The truth is out there"  (Use tests to prove it!)
 
-TBA
+Scully reads a Ruby test suite and reports tests that cannot be trusted as evidence of
+behaviour: tests that check nothing, and tests that can never fail. It works on RSpec and
+Minitest files, by static analysis only: it parses your tests with Prism and never runs them.
+The same input always gives the same output, byte for byte.
 
 ## Installation
 
+Scully needs Ruby 4.0.6 or newer.
+
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add scully
+bundle add scully --group=development,test
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
@@ -20,22 +25,280 @@ gem install scully
 
 ## Usage
 
-TBA
+```text
+scully check [options] [PATH ...]
+scully [options] [PATH ...]          # same as check
+scully why [options] PATH[:LINE]
+scully --version
+scully --help
+```
+
+### `scully check`
+
+```bash
+scully check                 # the current directory
+scully check spec test       # only these directories
+scully check spec/models/order_spec.rb
+```
+
+- With no PATH, scully checks `.`. A bare `scully` is the same as `scully check`, and
+  `scully spec` is the same as `scully check spec`. To check a directory named `check` or
+  `why`, name the command first: `scully check why`.
+- Directories are searched recursively for `*_spec.rb` and `*_test.rb` files, skipping
+  `vendor`, `node_modules`, `tmp`, `.git` and any other directory whose name starts with `.`.
+  The skip list applies only below the directory you pass, so `scully check tmp` still
+  searches `tmp`. A file passed explicitly is checked whatever its name.
+- Each file is classified as RSpec or Minitest by its content (`RSpec.describe`,
+  `require "spec_helper"`, a class inheriting from `Minitest::Test` or
+  `ActiveSupport::TestCase`, `require "test_helper"`, ...), then by whether it sits under
+  `spec/` or `test/`. Files that match neither are listed as skipped.
+- Paths in the report are relative to the current directory. Argument order does not change
+  the output, and a file reached through several paths is checked once.
+
+### The report
+
+Given these two files:
+
+```ruby
+# spec/tautology_spec.rb
+RSpec.describe Pricing do
+  let(:tax) { double(rate: 0.2) }
+
+  before { allow(gateway).to receive(:fee).and_return(3) }
+
+  it "reads the tax rate" do
+    expect(tax.rate).to eq(0.2)
+  end
+
+  it "reads the fee" do
+    expect(gateway.fee).to eq(3)
+  end
+end
+```
+
+```ruby
+# spec/no_assertion_spec.rb
+RSpec.describe Order do
+  it "sums line items" do
+    Order.new.total
+  end
+end
+```
+
+`scully check spec` prints:
+
+```text
+errors (2)
+
+error[tautology]: assertion checks a value the test stubbed
+ --> spec/tautology_spec.rb:7:5
+  |
+2 |   let(:tax) { double(rate: 0.2) }
+  |               ----------------- stubbed in setup to return `0.2`
+...
+7 |     expect(tax.rate).to eq(0.2)
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^ compares the stub with its own return value
+
+error[tautology]: assertion checks a value the test stubbed
+  --> spec/tautology_spec.rb:11:5
+   |
+ 4 |   before { allow(gateway).to receive(:fee).and_return(3) }
+   |            --------------------------------------------- stubbed in setup to return `3`
+...
+11 |     expect(gateway.fee).to eq(3)
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ compares the stub with its own return value
+
+warnings (1)
+
+warning[no_assertion]: test makes no assertion
+ --> spec/no_assertion_spec.rb:2:3
+  |
+2 |   it "sums line items" do
+  |   ^^^^^^^^^^^^^^^^^^^^ this test runs code but never checks a result
+
+summary: 2 files (0 incomplete, 0 skipped), 3 tests, 2 errors, 1 warnings
+evidence: static analysis only; coverage and mutation testing not run
+
+Use `scully why <location>` for more info about each finding:
+
+scully why spec/tautology_spec.rb:7      # tautology
+scully why spec/tautology_spec.rb:11     # tautology
+scully why spec/no_assertion_spec.rb:2   # no_assertion
+```
+
+and exits 1.
+
+- Findings are grouped as `errors`, then `warnings`, then `skipped` files, and sorted by path,
+  line, column and rule. Empty groups are left out.
+- Each finding shows the rule, the message, the `path:line:column` location, and the source
+  lines involved. `^` marks the main location; `-` marks related code, such as the stub a
+  tautology compares against.
+- A file with syntax errors is analyzed only in part. Its findings are marked
+  `(incomplete file: inconclusive)`, and the summary counts it as incomplete and lists the tests
+  that could not be analyzed (`5 tests (1 not analyzed)`).
+- The summary line always has the same shape, so it is easy to read from scripts. The
+  `evidence:` line is a reminder that scully reads code; it does not measure coverage or run
+  mutation testing.
+- The report ends with one `scully why` command per finding.
+
+### `scully why`
+
+`scully why PATH:LINE` re-checks one file and explains the finding(s) on that line: why it
+matters, what scully saw, how to fix it, how sure it is, and which RuboCop cop covers similar
+ground.
+
+```text
+$ scully why spec/tautology_spec.rb:7
+error[tautology]: assertion checks a value the test stubbed
+ --> spec/tautology_spec.rb:7:5
+  |
+2 |   let(:tax) { double(rate: 0.2) }
+  |               ----------------- stubbed in setup to return `0.2`
+...
+7 |     expect(tax.rate).to eq(0.2)
+  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^ compares the stub with its own return value
+
+because:
+  The assertion checks a value the test itself stubbed, so it can never fail and says
+  nothing about the code under test.
+
+what happened:
+  `tax.rate` is stubbed to return `0.2` (line 2), and the expectation on line 7 compares
+  `tax.rate` with `0.2`. No code under test runs between the stub and the assertion.
+
+help:
+  Assert on the result of the code that uses the stubbed object, not on the stub itself. If
+  the test only documents the stub, delete it.
+
+evidence: static analysis (complete file)
+see also: no matching cop in rubocop-rspec or rubocop-minitest
+```
+
+`scully why PATH` without a line lists every finding in the file, with the `scully why`
+command for each. When there is no finding on the given line, scully says so on stderr, lists
+the findings the file does have, and exits 1.
+
+## Rules
+
+### `no_assertion` (warning)
+
+A test that makes no assertion passes whatever the code does, so it gives coverage without
+evidence. Scully reports active tests (not pending or skipped) whose body contains no
+assertion. It counts:
+
+- RSpec expectations: `expect(...).to`, `expect { ... }.to`, `is_expected`, `should`, and
+  message expectations such as `expect(mailer).to receive(:deliver)`.
+- Minitest assertions and expectations: `assert*`, `refute*`, `flunk`, `must_*`, `wont_*`,
+  mocha `expects`, and `Minitest::Mock#expect` / `#verify`.
+- Minitest-style `assert*` and `refute*` calls in RSpec examples, with or without a receiver
+  (rspec-rails mixes them in, and Capybara adds `page.assert_selector` and friends).
+- Helpers whose name starts with `assert_` or `expect_`, and helpers defined in the same file
+  whose body asserts, directly or through other helpers in that file.
+
+Assertions only in `after` or `teardown` do not count. A helper defined in another file cannot
+be followed yet, so a test that asserts only through one is reported; `scully why` lists the
+calls it could not follow.
+
+Companion cops:
+
+- `RSpec/NoExpectationExample` in
+  [rubocop-rspec](https://docs.rubocop.org/rubocop-rspec/latest/cops_rspec.html#rspecnoexpectationexample)
+- `Minitest/NoAssertions` in
+  [rubocop-minitest](https://docs.rubocop.org/rubocop-minitest/latest/cops_minitest.html#minitestnoassertions),
+  disabled by default
+
+### `tautology` (error)
+
+An assertion that checks a value the test itself stubbed can never fail and says nothing about
+the code under test. Scully reports an equality assertion whose subject is a stubbed method
+called on the stubbed receiver, when the expected value matches the stubbed return value:
+
+```ruby
+let(:tax) { double(rate: 0.2) }
+
+it "reads the tax rate" do
+  expect(tax.rate).to eq(0.2)   # checks the double, not the code
+end
+```
+
+Recognised stubs: `allow(...).to receive(...).and_return(...)`, `receive_messages`, doubles
+created with attributes (`double(rate: 0.2)`, `instance_double`, ...), Minitest's
+`obj.stub(:m, value) do ... end` (inside its block only) and mocha's
+`obj.stubs(:m).returns(value)`, in the test body or in `let`, `before` or `setup`. Message
+expectations (`expect(...).to receive(...).and_return(...)`, `Minitest::Mock#expect`) can fail
+on their own and are not treated as stubs.
+
+Companion cops: none; no cop in rubocop-rspec or rubocop-minitest matches this rule.
+
+### `parse` (error)
+
+Scully can only check code it can read. Each line with a syntax error is reported once, with
+the first parser message and a count of the others. `ruby -c PATH` shows Ruby's own message.
+
+## Options
+
+| Option | Values | Default | Effect |
+|---|---|---|---|
+| `--color=WHEN` | `auto`, `always`, `never` | `auto` | Colour the severity words and markers. `auto` colours only when stdout is a terminal and `NO_COLOR` is unset or empty. |
+| `--hyperlinks=WHEN` | `auto`, `always`, `never` | `auto` | In `scully why`, make cop names clickable links instead of printing their URLs on a separate line. |
+| `--version` | | | Print `scully <version>` and exit. |
+| `--help` | | | Print usage and exit. |
+
+Colour and links never change the text: removing the escape sequences gives exactly the
+output you get through a pipe.
+
+### Environment variables
+
+| Variable | Effect |
+|---|---|
+| `NO_COLOR` | A non-empty value turns colour off in `auto` mode ([no-color.org](https://no-color.org)). |
+| `FORCE_HYPERLINK` | `0` turns links off, any other non-empty value turns them on, in `auto` mode. |
+| `CI`, `TEAMCITY_VERSION` | Turn links off in `auto` mode. |
+| `TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `VTE_VERSION`, `WT_SESSION`, `TERM` | Used in `auto` mode to detect terminals that render links (for example iTerm2 3.1+, WezTerm, VS Code 1.72+, Ghostty, Windows Terminal, kitty, Alacritty, VTE 0.50.1+). |
+
+Without `FORCE_HYPERLINK`, links are on only when stdout is a terminal. No other environment
+variable or locale setting affects the output.
+
+## Exit status
+
+| Status | `scully check` | `scully why` |
+|---|---|---|
+| 0 | Every file was read completely and there are no findings. | The finding(s) or the file index were printed. |
+| 1 | Any finding, or any file that could not be read completely. | No finding at that location. |
+| 2 | Scully could not run: a path does not exist, or an option or argument is wrong. | The path does not exist, or the arguments are wrong. |
+
+A run is clean only when it exits 0: a file with syntax errors or invalid UTF-8 makes the run
+exit 1 even without findings. Errors that exit 2 print `scully: <message>` to stderr.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake` to run the tests and RuboCop. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+Fixtures live in `test/fixtures/` and the expected reports in `test/golden/`. After an
+intended output change, regenerate the goldens with
+`SCULLY_UPDATE_GOLDEN=1 bundle exec rake test` and review the diff.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new
+version, update the version number in `version.rb`, and then run `bundle exec rake release`,
+which will create a git tag for the version, push git commits and the created tag, and push the
+`.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/theomelo/scully. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/theomelo/scully/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/theomelo/scully. This
+project is intended to be a safe, welcoming space for collaboration, and contributors are
+expected to adhere to the
+[code of conduct](https://github.com/theomelo/scully/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the Scully project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/theomelo/scully/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Scully project's codebases, issue trackers, chat rooms and mailing
+lists is expected to follow the
+[code of conduct](https://github.com/theomelo/scully/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -3,7 +3,11 @@
 require 'bundler/gem_tasks'
 require 'minitest/test_task'
 
-Minitest::TestTask.create
+# Only test_*.rb files are the gem's own tests; *_test.rb files under test/fixtures are sample
+# input for scully and must never run.
+Minitest::TestTask.create do |task|
+  task.test_globs = ['test/**/test_*.rb']
+end
 
 require 'rubocop/rake_task'
 

data/exe/scully

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'scully'
+
+exit Scully::CLI.start(ARGV)

data/lib/scully/analyzer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Scully
+  # Runs discovery, parsing, framework detection, normalization and rules, and collects the
+  # results into a RunReport.
+  class Analyzer
+    # Framework normalizers turn a SourceFile into TestCases.
+    NORMALIZERS = { rspec: Frameworks::RSpec, minitest: Frameworks::Minitest }.freeze
+
+    # SourceFiles read during the last run, by path.
+    attr_reader :sources
+
+    # Built-in rule run on every file report.
+    PARSE = Rules::Parse.new
+
+    def initialize(rules:, normalizers: NORMALIZERS)
+      @rules = rules
+      @normalizers = normalizers
+      @sources = {}
+    end
+
+    def run(paths, cwd: Dir.pwd)
+      files = Discovery.call(paths, cwd:).map { analyze_file(it, cwd) }
+      findings = files.flat_map { check(it) }.sort_by(&:sort_key)
+      counts = count(files, findings)
+      exit_status = findings.empty? && counts[:incomplete].zero? ? 0 : 1
+      RunReport.new(files:, findings:, counts:, exit_status:)
+    end
+
+    private
+
+    def analyze_file(path, cwd)
+      source = @sources[path] = SourceFile.read(path, base: cwd)
+      framework = Frameworks::Detector.detect(path, source.result&.value)
+      # A broken file is incomplete even without a framework: its errors may hide the tests.
+      return skipped(path) if framework.nil? && !source.incomplete?
+
+      FileReport.new(path:, framework:, status: source.incomplete? ? :incomplete : :complete, skip_reason: nil,
+                     parse_errors: source.parse_errors, test_cases: test_cases(source, framework))
+    end
+
+    def test_cases(source, framework)
+      return [] unless source.result && framework
+
+      mark_not_analyzed(@normalizers.fetch(framework).call(source), source.parse_errors)
+    end
+
+    def skipped(path)
+      FileReport.new(path:, framework: nil, status: :skipped, skip_reason: Frameworks::Detector::SKIP_REASON,
+                     parse_errors: [], test_cases: [])
+    end
+
+    # A test whose extent contains a parse error is partly invented by the parser, so no rule
+    # runs on it.
+    def mark_not_analyzed(test_cases, parse_errors)
+      test_cases.map do |test_case|
+        next test_case unless parse_errors.any? { contains?(test_case.extent, it.span) }
+
+        test_case.with(status: :not_analyzed, assertions: [], doubles: [], helper_calls: [])
+      end
+    end
+
+    # Span ends are exclusive: an error that starts right where a test ends is outside it.
+    def contains?(outer, inner)
+      start = [inner.start_line, inner.start_column]
+      (start <=> [outer.start_line, outer.start_column]) >= 0 &&
+        (start <=> [outer.end_line, outer.end_column]).negative?
+    end
+
+    # Parse findings are certain; what the rules found in an incomplete file may not be.
+    def check(file)
+      findings = file.test_cases.select { it.status == :active }.flat_map do |test_case|
+        @rules.flat_map { it.check(test_case) }
+      end
+      findings = findings.map { it.with(evidence: :inconclusive) } if file.status == :incomplete
+      PARSE.findings(file) + findings
+    end
+
+    def count(files, findings)
+      tests = files.flat_map(&:test_cases)
+      { files: files.size,
+        incomplete: files.count { it.status == :incomplete },
+        skipped: files.count { it.status == :skipped },
+        tests: tests.size,
+        not_analyzed: tests.count { it.status == :not_analyzed },
+        errors: findings.count { it.severity == :error },
+        warnings: findings.count { it.severity == :warning } }
+    end
+  end
+end

data/lib/scully/cli.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module Scully
+  # Command line entry point: `scully check [PATH ...]` (the default) and `scully why`.
+  class CLI
+    COMMANDS = %w[check why].freeze
+    MODES = %w[auto always never].freeze
+    USAGE_HINT = "Run 'scully --help' for usage."
+
+    # Rules run by default.
+    RULES = [Rules::NoAssertion, Rules::Tautology].freeze
+
+    # Runs the command and returns the process exit status.
+    # +env+ is read only to decide colour and hyperlinks.
+    def self.start(argv, out: $stdout, err: $stderr, cwd: Dir.pwd, env: ENV)
+      new(out:, err:, cwd:, env:).start(argv.map { argument(it) })
+    end
+
+    # Arguments arrive in the locale's encoding: US-ASCII under LANG=C even when they hold UTF-8
+    # bytes, which makes any regexp match raise. They are read as UTF-8 when valid, else as bytes.
+    def self.argument(text)
+      utf8 = text.b.force_encoding(Encoding::UTF_8)
+      utf8.valid_encoding? ? utf8 : text.b
+    end
+    private_class_method :argument
+
+    def initialize(out:, err:, cwd:, env:)
+      @out = out
+      @env = env
+      @err = err
+      @cwd = cwd
+      @rules = RULES.map(&:new)
+      @options = { color: 'auto', hyperlinks: 'auto' }
+    end
+
+    # The first non-option argument selects `check` or `why`; anything else runs `check`.
+    def start(argv)
+      catch(:done) do
+        arguments = parser.parse!(argv)
+        command = COMMANDS.include?(arguments.first) ? arguments.shift : 'check'
+        return command == 'why' ? why(arguments) : check(arguments)
+      end
+      0
+    rescue OptionParser::ParseError, UsageError => e
+      fail_with(e.message, hint: true)
+    rescue Error => e
+      fail_with(e.message)
+    end
+
+    # A bad argument: reported with the usage hint.
+    class UsageError < Error; end
+
+    private
+
+    def check(paths)
+      analyzer = Analyzer.new(rules: @rules)
+      run = analyzer.run(paths, cwd: @cwd)
+      messages = rules_by_id.transform_values { it.class.message }
+      @out.print Render::Report.render(run, messages:, sources: analyzer.sources, terminal:)
+      run.exit_status
+    end
+
+    # Re-analyzes one file; prints the findings on LINE, or the file's index without a line.
+    # A skipped file prints its skip line either way.
+    def why(arguments)
+      path, line = why_target(arguments)
+      view = why_view(path)
+      text = view.skipped || (line ? view.location(line) : view.index)
+      text ? @out.print(text) : @err.print(view.missing(line))
+      text ? 0 : 1
+    end
+
+    def why_view(path)
+      analyzer = Analyzer.new(rules: @rules)
+      run = analyzer.run([path], cwd: @cwd)
+      file = run.files.first
+      Render::Why.new(file, findings: run.findings, rules: rules_by_id, source: analyzer.sources.fetch(file.path),
+                            terminal:)
+    end
+
+    # PATH[:LINE] from the only argument, matched as bytes so a name that is not valid UTF-8
+    # still parses.
+    def why_target(arguments)
+      raise UsageError, 'why needs one file' if arguments.empty?
+
+      match = arguments.first.b.match(/\A(.+):(\d+)\z/m)
+      path, line = match ? [match[1], match[2].to_i] : [arguments.first.b, nil]
+      offending = File.directory?(File.expand_path(path, @cwd.b)) ? arguments.first : arguments[1]
+      raise UsageError, "why needs one file: #{offending}" if offending
+
+      [path, line]
+    end
+
+    def rules_by_id = [Analyzer::PARSE, *@rules].to_h { [it.class.id, it] }
+
+    def terminal
+      Render::Terminal.new(env: @env, tty: @out.tty?, color: @options[:color], hyperlinks: @options[:hyperlinks])
+    end
+
+    def parser
+      OptionParser.new do |opts|
+        opts.banner = "Usage: scully check [options] [PATH ...]\n       scully why [options] PATH[:LINE]"
+        opts.separator ''
+        opts.on('--color=WHEN', MODES, 'Colour output: auto, always, never (default auto)') { @options[:color] = it }
+        opts.on('--hyperlinks=WHEN', MODES, 'Link cop names in `scully why`: auto, always, never (default auto)') do
+          @options[:hyperlinks] = it
+        end
+        opts.on('--version', 'Print the version and exit') { finish("scully #{VERSION}") }
+        opts.on('--help', 'Print this help and exit') { finish(opts.help) }
+      end
+    end
+
+    def finish(text)
+      @out.puts text
+      throw :done
+    end
+
+    def fail_with(message, hint: false)
+      @err.puts "scully: #{message}"
+      @err.puts USAGE_HINT if hint
+      2
+    end
+  end
+end

data/lib/scully/discovery.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'find'
+
+module Scully
+  # Expands PATH arguments into the sorted list of test files to analyze.
+  #
+  # A file PATH is taken as given. A directory PATH is searched recursively for `*_spec.rb` and
+  # `*_test.rb`, skipping vendored, generated and hidden directories below it.
+  module Discovery
+    TEST_FILE = /_(spec|test)\.rb\z/
+    SKIPPED_DIRECTORIES = %w[vendor node_modules tmp .git].freeze
+
+    module_function
+
+    # Returns UTF-8 paths relative to +cwd+, deduplicated and sorted by bytes.
+    # Raises Scully::Error naming the first PATH that does not exist.
+    #
+    # PATHs and +cwd+ come in the locale's encoding (BINARY or US-ASCII under LANG=C), so they
+    # are handled as bytes, which never raise on names that are not valid UTF-8, and tagged
+    # UTF-8 on the way out so they join with source text.
+    def call(paths, cwd: Dir.pwd)
+      paths = ['.'] if paths.empty?
+      root = Pathname.new(File.expand_path(cwd.b))
+      paths.flat_map { expand(it.b, root) }.uniq.sort
+    end
+
+    def expand(path, root)
+      absolute = root.join(path).cleanpath
+      raise Error, "no such file: #{path}" unless absolute.exist?
+      return [relative(absolute, root)] unless absolute.directory?
+
+      search(absolute.to_s).map { relative(Pathname.new(it), root) }
+    end
+
+    # The directory given on the command line is always searched, even if its name would be skipped.
+    def search(directory)
+      found = []
+      Find.find(directory) do |path|
+        if File.directory?(path)
+          Find.prune if path != directory && skip?(File.basename(path))
+        elsif TEST_FILE.match?(File.basename(path)) && File.file?(path)
+          found << path
+        end
+      end
+      found
+    end
+
+    def skip?(name) = SKIPPED_DIRECTORIES.include?(name) || name.start_with?('.')
+
+    def relative(path, root) = path.relative_path_from(root).to_s.force_encoding(Encoding::UTF_8)
+  end
+end