swarf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c617f49a96d65792c3b8d3e2465effae7ad84b0c9b414770a4726cc0c8187165
+  data.tar.gz: 689601738e13957770d0a0c1a018e37507d5d563cc46688506f6162cc67d1367
+SHA512:
+  metadata.gz: 1fdfdb2342066a65fa736103f9af0caa4472a35f444f80045ae1b88a17a1290904b1d86e610b9660cf75f2887bac4f4fbc4512c4a4ac28a09365a6fe3743545e
+  data.tar.gz: b2ae944731ba4966ce88b5abe117b61c8fe7563659274ab03e1834c3751501c7c8a8f53b2447959b7bb86c00061ee1338de8a1097698427d31ed840456b79da7

data/.standard.yml

@@ -0,0 +1 @@
+ruby_version: 3.0

data/.swarfignore

@@ -0,0 +1,4 @@
+# The probe starts Coverage itself, so it is loaded before measurement begins and can
+# never appear in the store. Both spellings are here because patterns match relative to
+# the directory scanned: `swarf` sees lib/swarf/probe.rb, `swarf lib/` sees swarf/probe.rb.
+**/swarf/probe.rb

data/CONTEXT.md

@@ -0,0 +1,15 @@
+# Domain language
+
+Terms used in swarf's code, tests and commit messages. The README splits swarf into two halves that never talk to each other: the **probe**, which records coverage from inside your test process, and the **runner**, which scores. The terms below name the parts of the runner.
+
+## Scan
+
+One pass over a set of paths, joining parsed complexity to recorded coverage to produce scores.
+
+A scan owns no I/O policy — it is given its paths, its ignore patterns, its store and its root — and no formatting beyond naming each method's `file:line`. Scan is the part of the runner that produces scores; `CLI` and `Report` are the rest of it.
+
+## Measurement
+
+What test runs recorded about one file: line hits, branch outcomes, method call counts, and the SHA-256 of the bytes those numbers were measured against.
+
+A measurement knows whether it still describes the file on disk. It answers that question the first time it is asked and remembers the answer — asked before the source is read, it would report bytes the scan never saw, which is the confidently-wrong staleness DESIGN §4 exists to prevent.

data/README.md

@@ -0,0 +1,312 @@
+# swarf
+
+Scores every Ruby method by how complex it is against how well your tests actually exercise it.
+
+```
+$ swarf lib/
+
+Method          CC    Cov%   CRAP      Evidence  Location
+---------------------------------------------------------------------
+Cart#checkout    6    0.0%  42.00  never called  lib/cart.rb:31
+Cart#discount    4   50.0%   6.00        3/6 br  lib/cart.rb:24
+Cart#shipping    3   66.7%   3.33        2/3 br  lib/cart.rb:15
+Cart#subtotal    1  100.0%   1.00        1/1 ln  lib/cart.rb:11
+```
+
+## The metric
+
+```
+CRAP(m) = CC² · (1 − coverage)³ + CC
+```
+
+Complexity is squared; the _uncovered_ fraction is cubed. Two identities explain the shape:
+
+| coverage | CRAP       | meaning                                             |
+| -------- | ---------- | --------------------------------------------------- |
+| 100%     | `CC`       | fully tested code is only as risky as it is complex |
+| 0%       | `CC² + CC` | untested complexity grows quadratically             |
+
+The curve is nearly flat near full coverage and violently steep near zero, which is the
+point: simple code and small gaps stay quiet, complex code nobody has run scores loudly.
+
+From Alberto Savoia and Bob Evans (2007), where it stood for _Change Risk Analysis and
+Prediction_; Robert C. Martin's ports expand it as _Change Risk Anti-Pattern_. Same formula.
+
+## Install
+
+```ruby
+# Gemfile
+gem "swarf", group: :development
+```
+
+```
+$ bundle install
+```
+
+## Getting started
+
+### 1. Score complexity — no setup at all
+
+Complexity is parsed straight from your source, so this works immediately:
+
+```
+$ bundle exec swarf lib/
+
+Method          CC  Cov%   CRAP  Evidence  Location
+---------------------------------------------------------
+Cart#checkout    6     —  42.00   no data  lib/cart.rb:31
+Cart#discount    4     —  20.00   no data  lib/cart.rb:24
+Cart#shipping    3     —  12.00   no data  lib/cart.rb:15
+Cart#subtotal    1     —   2.00   no data  lib/cart.rb:11
+
+No coverage recorded for every file — run your suite with swarf/probe loaded.
+```
+
+`no data` means no test run has been recorded yet, so every method reports `CC² + CC`.
+That is not a placeholder — it is the correct score for code nothing has run. Adding
+coverage can only ever pull a number _down_, toward `CC`.
+
+### 2. Record coverage — one line
+
+Load the probe **before anything else** in your test runs.
+
+**RSpec** — add to `.rspec`, above every other line:
+
+```
+--require swarf/probe
+```
+
+**Minitest** — the very first line of `test/test_helper.rb`, above `minitest/autorun`:
+
+```ruby
+require "swarf/probe"
+```
+
+**Minitest via Rake** — in the `Rakefile`. `test_prelude` runs before the tests load:
+
+```ruby
+Minitest::TestTask.create do |t|
+  t.test_prelude = 'require "swarf/probe"'
+end
+```
+
+**Rails** — in `test/test_helper.rb`, above `config/environment`, or the whole app loads
+before the probe does and none of it is measured:
+
+```ruby
+ENV["RAILS_ENV"] ||= "test"
+
+require "bundler/setup"
+require "swarf/probe"
+
+require_relative "../config/environment"
+```
+
+`bundler/setup` is only what `config/boot` would do anyway; the probe needs it to find the
+gem this early. Rails parallelises tests by forking, which swarf handles — every worker
+merges into the store under a lock.
+
+**Anything else** — set it on the command line, no files to edit:
+
+```
+$ RUBYOPT="-rswarf/probe" bundle exec rake test
+```
+
+Order matters and is not negotiable: `Coverage` measures only files loaded _after_ it
+starts. Put the probe under your application and the application is invisible to it.
+
+Then ignore the store:
+
+```
+# .gitignore
+.swarf/
+```
+
+### 3. Run your tests, then score again
+
+```
+$ bundle exec rspec
+$ bundle exec swarf lib/
+
+Method          CC    Cov%   CRAP      Evidence  Location
+---------------------------------------------------------------------
+Cart#checkout    6    0.0%  42.00  never called  lib/cart.rb:31
+Cart#discount    4   50.0%   6.00        3/6 br  lib/cart.rb:24
+Cart#shipping    3   66.7%   3.33        2/3 br  lib/cart.rb:15
+Cart#subtotal    1  100.0%   1.00        1/1 ln  lib/cart.rb:11
+```
+
+Every run merges into `.swarf/coverage.json`, so partial runs are fine — running one spec
+file does not erase what another proved. Your runs, CI's runs and a colleague's all add up.
+
+## Reading the report
+
+| column     | means                                                             |
+| ---------- | ----------------------------------------------------------------- |
+| `CC`       | cyclomatic complexity — how many decisions the method makes       |
+| `Cov%`     | how much of it your tests exercised, or `—` when nothing is known |
+| `CRAP`     | the score; worst first                                            |
+| `Evidence` | where the coverage number came from, so you know what to do next  |
+
+The evidence column is the actionable half:
+
+| evidence       | what it means                               | what to do                           |
+| -------------- | ------------------------------------------- | ------------------------------------ |
+| `never called` | no test has ever executed this method       | **write** a test                     |
+| `3/6 br`       | 3 of 6 branch outcomes were taken           | **extend** a test to the other cases |
+| `1/1 ln`       | no branches, so lines are the whole truth   | nothing, if it is 100%               |
+| `no data`      | no test run has been recorded for this file | run your suite with the probe loaded |
+| `stale`        | the file changed since it was measured      | re-run your suite                    |
+
+Both `no data` and `stale` fall back to the `CRAP = CC² + CC` floor rather than guessing.
+
+Those two also print under the table, counted by file, because the fix is per file rather
+than per method:
+
+```
+… 45 more (--limit 0 for all)
+No coverage recorded for 3 of 11 files — run your suite with swarf/probe loaded.
+2 of 11 files changed after measurement — re-run your suite.
+```
+
+A fully measured project prints neither line.
+
+## Command line
+
+```
+$ swarf                       # the whole project
+$ swarf lib/ app/             # directories, recursively
+$ swarf lib/app/cart.rb       # a single file
+$ swarf --limit 50            # show 50 rows instead of 20
+$ swarf --limit 0             # show everything
+$ swarf --ignore "app/legacy/**"   # skip a path (repeatable)
+$ swarf --all                 # score everything, ignoring nothing
+$ swarf --version
+$ swarf --help
+```
+
+Only the worst 20 rows print by default, with a count of what was held back. A 245-file
+project reports 344 methods, and the tail of that list is all `CRAP 1.00` — noise that
+buries the handful of rows worth acting on.
+
+## What gets skipped
+
+```
+**/test/**  **/spec/**  **/features/**     where coverage comes from, not where risk is
+db/**                                      migrations and schema
+**/vendor/**  **/tmp/**  **/log/**  **/node_modules/**
+```
+
+Migrations matter more than they look. They are generated, run once and never tested, so
+on a well-tested codebase they are the only untested code left and they take over the top
+of the report — on a 20-file Rails app they ranked 3rd, 4th and 5th.
+
+Add your own in `.swarfignore` at the project root, one glob per line:
+
+```
+# generated
+lib/api/generated_client.rb
+app/legacy/**
+```
+
+Patterns match against each file's path relative to the directory being scanned, and both
+`*` and `**` cross directories. Naming a path on the command line always wins, so
+`swarf db/migrate` scores migrations even though `db/**` is a default.
+
+Directories are searched for `**/*.rb`, skipping `test/`, `spec/`, `vendor/`, `tmp/` and
+`node_modules/`. Naming one of those directly still scores it.
+
+`SWARF_DIR` moves the coverage store, which both the probe and the runner must agree on:
+
+```
+$ SWARF_DIR=/tmp/swarf bundle exec rspec
+$ SWARF_DIR=/tmp/swarf bundle exec swarf lib/
+```
+
+## How it works
+
+Two halves that never talk to each other, joined by a file on disk.
+
+```mermaid
+flowchart LR
+    accTitle: How swarf computes a CRAP score
+    accDescr: Any test run loads the probe, which records line, branch and method coverage into a JSON store. Separately, the swarf CLI parses your sources with Prism for complexity, joins the two, and prints a report worst first.
+    subgraph probe["PROBE — inside your test process"]
+        Specs["your specs"] -->|records| DB[("`.swarf/coverage.json`")]
+    end
+    subgraph runner["RUNNER — when you type swarf"]
+        Src["lib/**/*.rb"] -->|"Prism: complexity"| Score["CRAP per method"]
+    end
+    DB -->|"lines, branches, call counts"| Score
+    Score --> Report["report, worst first"]
+```
+
+The probe is about thirty lines: `Coverage.start` plus an `at_exit` that dumps the result.
+The runner never loads your application — it parses text.
+
+## Things worth knowing
+
+**Coverage needs a run; complexity does not.** Nothing static can tell you whether a line
+executed. Any run counts, not just specs — a rake task, booting the app, a script.
+
+**The probe must load first.** `Coverage` only measures files loaded after it starts. Put
+it ahead of your application, or the application is invisible to it.
+
+**swarf and SimpleCov cannot both run.** Ruby permits one `Coverage.start` per process. If
+SimpleCov gets there first, swarf warns and records nothing rather than killing your suite.
+
+**Branch coverage is preferred, with a line fallback.** Ruby puts a decision on a line that
+runs whichever way the decision goes, so `return 0 if x.negative?` reads 100% by line even
+when the guard never fires — maximally wrong exactly where risk collects. Methods with no
+branches fall back to lines, where "did it run" is the whole truth.
+
+**`never called` is a fact, not an inference.** It comes from a VM-level call count. It
+tells you to _write_ a test; `3/6 br` tells you to _extend_ one. A bare `0.0%` tells you
+neither.
+
+**Edited files report `no coverage`, not stale numbers.** Coverage is indexed by line
+number, so inserting a method at the top of a file shifts every line below it while the
+counters stay put. swarf stores a SHA-256 per measured file and drops entries whose bytes
+changed, because stale coverage is worse than none — it is confidently wrong.
+
+**swarf's CC will not match RuboCop's.** It counts `if`, `unless`, `while`, `until`, `for`,
+each `when`, each `in`, each `rescue`, `&&`, `||` and `&.` — **not blocks**. Six chained
+`add_option` blocks are not six decisions. The trade-off is that CC largely ignores
+iteration, since Ruby iterates with blocks.
+
+**There is no threshold and nothing fails.** swarf sorts worst-first and prints. Because
+`CRAP = CC` at full coverage, a fixed threshold is a complexity cap in disguise — a method
+at CC 9 can never score under 9 however well you test it, and the only remaining move is to
+split it. Ranking is enough; capping complexity is RuboCop's job.
+
+## Known limitations
+
+- Methods defined inside a `Struct.new do ... end` block take the enclosing module's name
+  (`Swarf#crap` rather than `Swarf::Score#crap`), because the block is not a class node.
+- `define_method` and other dynamically defined methods are not seen at all — swarf reads
+  `def`.
+- Nested `def`s get their own complexity, but the outer method's coverage still counts the
+  inner method's lines and branches.
+- Methods inside `class << self` are named correctly; methods defined by `instance_eval` or
+  a reopened singleton via a variable are not.
+
+## Development
+
+```
+$ bin/setup
+$ bundle exec rake test
+```
+
+To watch swarf score itself:
+
+```
+$ RUBYOPT="-Ilib -rswarf/probe" bundle exec rake test
+$ ruby -Ilib exe/swarf lib/
+```
+
+### Releasing
+
+1. Update the version in `lib/swarf/version.rb`
+2. Run `bundle install` to update the lockfile
+3. Commit: `git commit -am "Release vX.Y.Z"`
+4. Run `bundle exec rake release` (builds the gem, creates the git tag, pushes to RubyGems)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+
+Minitest::TestTask.create do |task|
+  # Record swarf's coverage with swarf. The prelude runs before the tests load,
+  # which is the only place `Coverage.start` can still see them.
+  task.test_prelude = 'require "swarf/probe"'
+end
+
+task default: %i[test standard]

data/exe/swarf

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+# frozen_string_literal: true
+
+require "swarf"
+
+exit Swarf::CLI.run(ARGV)

data/lib/swarf/cli.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Swarf
+  class CLI
+    def self.run(argv, out: $stdout, err: $stderr)
+      new(argv).run(out)
+    rescue Error => e
+      err.puts("swarf: #{e.message}")
+      1
+    end
+
+    def initialize(argv)
+      @limit = Report::DEFAULT_LIMIT
+      @extra_ignore = []
+      @all = false
+      @paths = parse(argv)
+    end
+
+    def run(out)
+      scores = Scan.new(paths: @paths, ignore: ignore).scores
+      out.print Report.new(scores, limit: @limit).to_s
+      0
+    end
+
+    private
+
+    def ignore
+      return [] if @all
+
+      Sources::DEFAULT_IGNORE + Sources.ignore_file + @extra_ignore
+    end
+
+    def parse(argv)
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: swarf [options] [paths]"
+        opts.on("-n", "--limit N", Integer, "Rows to show (0 for all, default #{Report::DEFAULT_LIMIT})") do |n|
+          @limit = n
+        end
+        opts.on("-i", "--ignore GLOB", "Skip paths matching GLOB (repeatable)") do |glob|
+          @extra_ignore << glob
+        end
+        opts.on("-a", "--all", "Score everything, including #{Sources::IGNORE_FILE} and the defaults") do
+          @all = true
+        end
+        opts.on("-v", "--version", "Print the version and exit") do
+          puts VERSION
+          exit 0
+        end
+        opts.on("-h", "--help", "Print this message and exit") do
+          puts opts
+          exit 0
+        end
+      end
+      parser.parse(argv)
+    end
+  end
+end

data/lib/swarf/complexity.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Swarf
+  module Complexity
+    Method = Struct.new(:path, :name, :cc, :start_line, :body) do
+      def range = start_line..(body&.last || start_line)
+    end
+
+    def self.analyze(source, path:)
+      result = Prism.parse(source)
+      visitor = Visitor.new(path)
+      result.value.accept(visitor)
+      visitor.methods
+    end
+
+    class Visitor < Prism::Visitor
+      attr_reader :methods
+
+      def initialize(path)
+        @path = path
+        @methods = []
+        @stack = []
+        @scope = []
+        @singleton = 0
+        super()
+      end
+
+      def visit_class_node(node)
+        in_scope(node.constant_path.slice) { super }
+      end
+
+      def visit_module_node(node)
+        in_scope(node.constant_path.slice) { super }
+      end
+
+      def visit_singleton_class_node(node)
+        @singleton += 1
+        super
+        @singleton -= 1
+      end
+
+      def visit_def_node(node)
+        method = Method.new(path: @path, name: qualify(node), cc: 1,
+          start_line: node.location.start_line, body: body_range(node))
+        @methods << method
+        @stack.push(method)
+        super
+        @stack.pop
+      end
+
+      DECISIONS = %i[
+        if unless while until for when in rescue rescue_modifier and or
+      ].freeze
+
+      DECISIONS.each do |construct|
+        define_method(:"visit_#{construct}_node") do |node|
+          decision
+          super(node)
+        end
+      end
+
+      def visit_call_node(node)
+        decision if node.safe_navigation?
+        super
+      end
+
+      private
+
+      def decision
+        @stack.last&.cc += 1
+      end
+
+      def in_scope(name)
+        @scope.push(name)
+        yield
+        @scope.pop
+      end
+
+      def qualify(node)
+        return node.name.to_s if @scope.empty?
+
+        separator = (node.receiver || @singleton.positive?) ? "." : "#"
+        "#{@scope.join("::")}#{separator}#{node.name}"
+      end
+
+      def body_range(node)
+        return nil unless node.body
+
+        first = node.body.location.start_line
+        last = node.body.location.end_line
+        return first..last if node.equal_loc
+
+        clamped = [first, node.location.start_line + 1].max..[last, node.location.end_line - 1].min
+        (clamped.begin > clamped.end) ? first..last : clamped
+      end
+    end
+  end
+end

data/lib/swarf/coverage_map.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Swarf
+  class CoverageMap
+    Result = Struct.new(:coverage, :evidence)
+
+    NO_DATA = Result.new(coverage: nil, evidence: "no data")
+    STALE = Result.new(coverage: nil, evidence: "stale")
+    NEVER_CALLED = Result.new(coverage: 0.0, evidence: "never called")
+    NO_BODY = Result.new(coverage: 1.0, evidence: "no body")
+
+    def initialize(data)
+      @data = data
+    end
+
+    def for(method)
+      measurement = @data[method.path]
+      return NO_DATA if measurement.nil?
+      return STALE unless measurement.current?
+      return NEVER_CALLED if measurement.calls(method.start_line)&.zero?
+
+      branch_coverage(measurement, method) || line_coverage(measurement, method) || NO_BODY
+    end
+
+    private
+
+    def branch_coverage(measurement, method)
+      outcomes = measurement.branches(method.range)
+      return nil if outcomes.empty?
+
+      ratio(outcomes.count(&:positive?), outcomes.size, "br")
+    end
+
+    def line_coverage(measurement, method)
+      return nil unless method.body
+
+      hits = measurement.lines(method.body)
+      return nil if hits.empty?
+
+      ratio(hits.count(&:positive?), hits.size, "ln")
+    end
+
+    def ratio(covered, total, unit)
+      Result.new(coverage: covered.fdiv(total), evidence: "#{covered}/#{total} #{unit}")
+    end
+  end
+end

data/lib/swarf/measurement.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Swarf
+  class Measurement
+    def initialize(path, entry)
+      @path = path
+      @entry = entry
+      @current = nil
+    end
+
+    def current?
+      @current = File.file?(@path) && Digest::SHA256.file(@path).hexdigest == @entry["sha"] if @current.nil?
+      @current
+    end
+
+    def calls(line)
+      @entry["methods"][line.to_s]
+    end
+
+    def branches(range)
+      range.flat_map { |line| outcomes_by_line.fetch(line, []) }
+    end
+
+    def lines(range)
+      range.filter_map { |line| @entry["lines"][line - 1] }
+    end
+
+    private
+
+    def outcomes_by_line
+      @outcomes_by_line ||= @entry["branches"].each_with_object({}) do |(branch, taken), by_line|
+        (by_line[branch.split(":")[2].to_i] ||= []).concat(taken.values)
+      end
+    end
+  end
+end

data/lib/swarf/probe.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "coverage"
+
+module Swarf
+  module Probe
+    def self.start
+      ::Coverage.start(lines: true, branches: true, methods: true)
+      at_exit { record(::Coverage.result) }
+    rescue RuntimeError => e
+      warn "swarf: coverage is already being measured (#{e.message}); not recording. " \
+           "Remove SimpleCov, or drop the swarf/probe require."
+    end
+
+    def self.record(result)
+      require_relative "store"
+      Store.new.record(result)
+    end
+  end
+end
+
+Swarf::Probe.start

data/lib/swarf/report.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Swarf
+  class Report
+    HEADINGS = ["Method", "CC", "Cov%", "CRAP", "Evidence", "Location"].freeze
+
+    DEFAULT_LIMIT = 20
+
+    def initialize(scores, limit: DEFAULT_LIMIT)
+      @scores = scores.sort_by { |score| -score.crap }
+      @shown = limit.zero? ? @scores : @scores.first(limit)
+    end
+
+    def to_s
+      return "No methods found.\n" if @scores.empty?
+
+      rows = @shown.map { |score| cells(score) }
+      widths = column_widths(rows)
+      lines = [heading(widths), divider(widths), *rows.map { |row| line(row, widths) }]
+      "#{(lines + footer).join("\n")}\n"
+    end
+
+    private
+
+    def held_back = @scores.size - @shown.size
+
+    # Notes the reader can act on, each named for the move it asks for. Kept out of the
+    # rows because the action is per file, not per method: a project nothing has run is
+    # one sentence, not one row per method.
+    def footer
+      notes = []
+      notes << "… #{held_back} more (--limit 0 for all)" if held_back.positive?
+      notes << unmeasured_note if unmeasured.positive?
+      notes << stale_note if stale.positive?
+      notes.empty? ? notes : [""] + notes
+    end
+
+    def unmeasured_note
+      "No coverage recorded for #{scope(unmeasured)} — run your suite with swarf/probe loaded."
+    end
+
+    def stale_note = "#{scope(stale).capitalize} changed after measurement — re-run your suite."
+
+    def scope(count) = (count == files.size) ? "every file" : "#{count} of #{files.size} files"
+
+    def unmeasured = @unmeasured ||= files_reporting(CoverageMap::NO_DATA.evidence)
+
+    def stale = @stale ||= files_reporting(CoverageMap::STALE.evidence)
+
+    def files_reporting(evidence)
+      files.count { |methods| methods.all? { |score| score.evidence == evidence } }
+    end
+
+    def files
+      @files ||= @scores.group_by { |score| score.location.to_s.rpartition(":").first }.values
+    end
+
+    def cells(score)
+      [score.name, score.cc.to_s, percentage(score.coverage), format("%.2f", score.crap),
+        score.evidence.to_s, score.location.to_s]
+    end
+
+    def percentage(coverage) = coverage.nil? ? "—" : format("%.1f%%", coverage * 100)
+
+    def column_widths(rows)
+      ([HEADINGS] + rows).transpose.map { |column| column.map(&:length).max }
+    end
+
+    def heading(widths) = line(HEADINGS, widths)
+
+    def divider(widths) = "-" * (widths.sum + 2 * (widths.size - 1))
+
+    def line(cells, widths)
+      cells.each_with_index.map do |cell, index|
+        (index.zero? || index == cells.size - 1) ? cell.ljust(widths[index]) : cell.rjust(widths[index])
+      end.join("  ").rstrip
+    end
+  end
+end

data/lib/swarf/scan.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Swarf
+  class Scan
+    def initialize(paths:, ignore: [], store: Store.new, root: Dir.pwd)
+      @root = File.expand_path(root)
+      @paths = resolve(paths)
+      @ignore = ignore
+      @store = store
+    end
+
+    def scores
+      coverage = CoverageMap.new(@store.read)
+      Sources.collect(@paths, ignore: @ignore).flat_map do |path|
+        Complexity.analyze(File.read(path), path: path).map do |method|
+          found = coverage.for(method)
+          Score.new(name: method.name, cc: method.cc, coverage: found.coverage,
+            evidence: found.evidence, location: locate(method))
+        end
+      end
+    end
+
+    private
+
+    def resolve(paths)
+      return [@root] if paths.empty?
+
+      paths.map { |path| File.expand_path(path, @root) }
+    end
+
+    def locate(method)
+      "#{method.path.delete_prefix("#{@root}/")}:#{method.start_line}"
+    end
+  end
+end

data/lib/swarf/score.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Swarf
+  Score = Struct.new(:name, :cc, :coverage, :evidence, :location) do
+    def crap = Swarf.crap(cc, coverage || 0.0)
+  end
+end

data/lib/swarf/sources.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Swarf
+  module Sources
+    IGNORE_FILE = ".swarfignore"
+
+    DEFAULT_IGNORE = [
+      "**/test/**", "**/spec/**", "**/features/**",
+      "db/**",
+      "**/vendor/**", "**/tmp/**", "**/log/**", "**/node_modules/**"
+    ].freeze
+
+    def self.collect(paths, ignore:)
+      patterns = ignore.flat_map { |pattern| variants(pattern) }
+      paths.flat_map { |path| expand(path, patterns) }.uniq.sort
+    end
+
+    def self.ignore_file(root = Dir.pwd)
+      File.readlines(File.join(root, IGNORE_FILE), chomp: true)
+        .map(&:strip).reject { |line| line.empty? || line.start_with?("#") }
+    rescue Errno::ENOENT
+      []
+    end
+
+    def self.expand(path, patterns)
+      return [path] if File.file?(path)
+      raise Error, "no such file or directory: #{path}" unless File.directory?(path)
+
+      Dir.glob(File.join(path, "**", "*.rb"))
+        .reject { |file| ignored?(file.delete_prefix("#{path}/"), patterns) }
+    end
+
+    def self.ignored?(relative, patterns)
+      patterns.any? do |pattern|
+        File.fnmatch?(pattern, relative, File::FNM_PATHNAME) || File.fnmatch?(pattern, relative)
+      end
+    end
+
+    def self.variants(pattern)
+      pattern.start_with?("**/") ? [pattern, pattern.delete_prefix("**/")] : [pattern]
+    end
+  end
+end

data/lib/swarf/store.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require "fileutils"
+
+module Swarf
+  class Store
+    FILENAME = "coverage.json"
+
+    def self.default_dir = ENV.fetch("SWARF_DIR", File.join(Dir.pwd, ".swarf"))
+
+    def initialize(dir = self.class.default_dir, root: Dir.pwd)
+      @dir = dir
+      @root = File.expand_path(root)
+    end
+
+    def read
+      parse(File.read(path)).to_h { |file, entry| [file, Measurement.new(file, entry)] }
+    rescue Errno::ENOENT
+      {}
+    end
+
+    def record(result)
+      fresh = normalize(result)
+      return if fresh.empty?
+
+      FileUtils.mkdir_p(@dir)
+      File.open(path, File::RDWR | File::CREAT, 0o644) do |file|
+        file.flock(File::LOCK_EX)
+        merged = merge(parse(file.read), fresh)
+        file.rewind
+        file.write(JSON.pretty_generate(merged))
+        file.truncate(file.pos)
+      end
+    end
+
+    private
+
+    def path = File.join(@dir, FILENAME)
+
+    def parse(json)
+      JSON.parse(json)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def merge(merged, fresh)
+      fresh.each do |file, entry|
+        previous = merged[file]
+        merged[file] = (previous && previous["sha"] == entry["sha"]) ? combine(previous, entry) : entry
+      end
+      merged
+    end
+
+    def normalize(result)
+      result.filter_map do |file, coverage|
+        file = File.expand_path(file, @root)
+        next unless project_file?(file)
+
+        [file, {
+          "sha" => Digest::SHA256.file(file).hexdigest,
+          "lines" => coverage[:lines] || [],
+          "branches" => stringify_branches(coverage[:branches] || {}),
+          "methods" => stringify_methods(coverage[:methods] || {})
+        }]
+      end.to_h
+    end
+
+    def project_file?(file)
+      file.start_with?("#{@root}/") && File.file?(file)
+    end
+
+    def stringify_branches(branches)
+      branches.to_h do |branch, outcomes|
+        [branch.join(":"), outcomes.transform_keys { |outcome| outcome.join(":") }]
+      end
+    end
+
+    def stringify_methods(methods)
+      methods.each_with_object(Hash.new(0)) do |((_owner, _name, line, *), count), totals|
+        totals[line.to_s] += count
+      end
+    end
+
+    def combine(previous, fresh)
+      fresh.merge(
+        "lines" => sum_lines(previous["lines"], fresh["lines"]),
+        "branches" => sum_branches(previous["branches"], fresh["branches"]),
+        "methods" => previous["methods"].merge(fresh["methods"]) { |_, a, b| a + b }
+      )
+    end
+
+    def sum_lines(previous, fresh)
+      fresh.each_with_index.map do |hits, index|
+        hits.nil? ? nil : hits + (previous[index] || 0)
+      end
+    end
+
+    def sum_branches(previous, fresh)
+      fresh.merge(previous) do |_branch, a, b|
+        a.merge(b) { |_outcome, x, y| x + y }
+      end
+    end
+  end
+end

data/lib/swarf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Swarf
+  VERSION = "0.1.0"
+end

data/lib/swarf.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "swarf/version"
+require_relative "swarf/complexity"
+require_relative "swarf/measurement"
+require_relative "swarf/store"
+require_relative "swarf/coverage_map"
+require_relative "swarf/score"
+require_relative "swarf/report"
+require_relative "swarf/sources"
+require_relative "swarf/scan"
+require_relative "swarf/cli"
+
+module Swarf
+  class Error < StandardError; end
+
+  # CRAP(m) = CC(m)^2 * (1 - coverage(m))^3 + CC(m)
+  #
+  # Complexity is squared; the *uncovered* fraction is cubed. The score is
+  # nearly flat near full coverage and violently steep near zero, so simple
+  # code and small gaps stay quiet while complex code nothing has run scores
+  # loudly.
+  def self.crap(complexity, coverage)
+    (complexity**2) * ((1.0 - coverage)**3) + complexity
+  end
+end

data/swarf.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "lib/swarf/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "swarf"
+  spec.version = Swarf::VERSION
+  spec.authors = ["Ariel Rzezak"]
+  spec.email = ["arzezak@gmail.com"]
+
+  spec.summary = "Scores Ruby methods by the CRAP metric: complexity against coverage."
+  spec.description = "Ranks every Ruby method by complexity against test coverage, worst first."
+  spec.homepage = "https://github.com/arzezak/swarf"
+  spec.required_ruby_version = ">= 3.4.0"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      f.start_with?(*%w[bin/ Gemfile .gitignore test/])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |file| File.basename(file) }
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: swarf
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ariel Rzezak
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Ranks every Ruby method by complexity against test coverage, worst first.
+email:
+- arzezak@gmail.com
+executables:
+- swarf
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- ".swarfignore"
+- CONTEXT.md
+- README.md
+- Rakefile
+- exe/swarf
+- lib/swarf.rb
+- lib/swarf/cli.rb
+- lib/swarf/complexity.rb
+- lib/swarf/coverage_map.rb
+- lib/swarf/measurement.rb
+- lib/swarf/probe.rb
+- lib/swarf/report.rb
+- lib/swarf/scan.rb
+- lib/swarf/score.rb
+- lib/swarf/sources.rb
+- lib/swarf/store.rb
+- lib/swarf/version.rb
+- swarf.gemspec
+homepage: https://github.com/arzezak/swarf
+licenses: []
+metadata:
+  homepage_uri: https://github.com/arzezak/swarf
+  source_code_uri: https://github.com/arzezak/swarf
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Scores Ruby methods by the CRAP metric: complexity against coverage.'
+test_files: []