exhale 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cadf9f2ab741c8b3067a4b0a0fc455e850c932b9d64d1958dc4b3aa95b48e3e8
-  data.tar.gz: af11c04726fbf8871630d55c15334789dccab422aa7993a650266715ffd9e3f8
+  metadata.gz: 1bb02e1c178e586604ee60a1137eccc618adb554f4698bcfdba2eb847b419606
+  data.tar.gz: fc4f22bebe777b3466f79f477d1ab286c77eada7d897cf14c479b5f6732b46fa
 SHA512:
-  metadata.gz: 122094bca81d07462b84ee61d363672e6e5d3526c1e5ff634682cce17fc328355bd6db9b7949d671b492334949cb9c14d287f5bd128866842d4b7952063f9667
-  data.tar.gz: da79c22a530eabefc86315cdf14d2a519b283efb30e244fc8dcec187613f38a7b1f694ba62e8eeb737103c9bf74e3f42b9e1fdf06a14fcc7b665ff35d530b7bf
+  metadata.gz: bb150d270734ec90b0e16006f60b9284f7900e380d982a85de862e7d7bdfcea74cb9c8b49b3471bd634aa6ed31e86053ba71d1524162b7a70a18b23c132d1bdd
+  data.tar.gz: 3ac44ea2d46351e35d7a013a3d06dae27c9b2cbc51925a4c8d6e581f91266856313e612ff70dae16a3c4746296d654e2b374c7d05088d8569a4a95812e210d53

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- `exhale complexity` is the second check. It scores every Ruby method and Rails DSL body with Cognitive Complexity at the head and at the merge base, and fails a pull request that raises a unit past the floor (8 by default) or adds one over it. Renamed and moved methods keep their history by identity, then by shape. `complexity.md` in a primitive sets its floor and keeps units up to a ceiling's max. `exhale complexity explain UNIT` prints every point. JSON lists every unit; EDN writes crapper's entries.
+- The Contract loads per check: dry reads `duplication.md`, complexity reads `complexity.md`, and a block that belongs to the other check is an error.
+- The mutation gate moves to Mutineer 1.5. `timeout: 120` in `.mutineer.yml` replaces the `test/support/mutineer_timeout.rb` patch, and 8 ignore entries for continuation lines are gone, because Mutineer now selects tests for the later lines of a multi-line call or hash. The 13 on the right side of a multi-line `&&` stay, because Mutineer still selects no tests for an operand that may never run.
+- `bin/mutate --matrix` reports blind and redundant tests with Mutineer 1.5's kill matrix. It is a separate run, not part of the gate.
+
 ## 0.1.0
 
 First release. `exhale dry` sweeps the whole codebase for duplicated Ruby and HTML ERB and fails while any copy isn't kept by the Contract.

data/README.md

@@ -1,12 +1,12 @@
 # exhale
 
-<p align="center"><img src="assets/huff-exhale.png" alt="Huff, the Impatient Programming imp, blowing three identical cards into one while his robot watches from the leash" width="320"></p>
+<p align="center"><img src="assets/huff-exhale.svg" alt="Huff, the Impatient Programming imp, lips pursed, blowing two duplicate cards away while he keeps one in his hand and his robot sits at his feet" width="320"></p>
 
-exhale is the contraction gate for Rails. It fails a pull request while the codebase it leaves behind holds duplicated code the Contract doesn't keep, and it tells the agent doing the cleanup which original each copy should fold into.
+Exhale aims to be the premier contraction toolkit for Ruby, the checks for the breathe-out phase of Impatient Programming. Its first check is `exhale dry`. It fails a pull request while the codebase it leaves behind holds duplicated code the Contract doesn't keep, and it tells the agent doing the cleanup which original each copy should fold into.
 
 Agents duplicate by default. They read the codebase, find a shape that works, and copy it. When pull requests merge without a person reading every diff, the copy reaches main unless a machine stops it, and every session after that copies it again. exhale is that machine for the exhale half of the breath: expand to learn, then contract what you learned into what already exists, in the same PR.
 
-The first check is `exhale dry`. It combines Uncle Bob's [dryer](https://github.com/unclebob/dryer) and Ryan Davis's [flay](https://github.com/seattlerb/flay), rebuilt on [Prism](https://github.com/ruby/prism) and [Herb](https://herb-tools.dev) so it reads modern Ruby and ERB the way Rails writes them.
+`exhale dry` combines Robert Martin's [dryer](https://github.com/unclebob/dryer) and Ryan Davis's [flay](https://github.com/seattlerb/flay), rebuilt on [Prism](https://github.com/ruby/prism) and [Herb](https://herb-tools.dev) so it reads modern Ruby and ERB the way Rails writes them. The second check, `exhale complexity`, fails a pull request that leaves a method harder to follow than it found it. A leaked-guards check is planned.
 
 ## Install
 
@@ -20,10 +20,10 @@ end
 ```bash
 bundle install
 bundle binstubs exhale
-bin/exhale
+bin/exhale dry
 ```
 
-Exit code 0 means the codebase is clean. 1 means the gate failed: there's unkept duplication, or a Contract clause is stale or names code that doesn't exist. 2 means exhale couldn't run, usually because a file doesn't parse.
+`exhale dry` exits 0 when the codebase is clean. It exits 1 when the gate fails: there's unkept duplication, or a Contract clause is stale or names code that doesn't exist. It exits 2 when it couldn't run, usually because a file doesn't parse.
 
 ## What it compares
 
@@ -51,7 +51,7 @@ Every subtree of a normalized unit is a fingerprint. Each fingerprint is weighte
 
 ## The gate
 
-Every run sweeps the whole codebase. Main passes the same gate, so anything a pull request trips over is its own doing. exhale compares against the merge base only to label findings:
+Every run sweeps the whole codebase. Main passes the same gate, so anything a pull request trips over is its own doing. `exhale dry` compares against the merge base only to label findings:
 
 | Label | Meaning |
 | --- | --- |
@@ -61,7 +61,7 @@ Every run sweeps the whole codebase. Main passes the same gate, so anything a pu
 
 The report also lists what the PR contracted: pairs that matched at the base and don't anymore.
 
-An existing app won't sweep clean on its first run. `--introduced-only` gates on introduced and shifted findings and lists the rest as warnings. Once main is clean, drop the flag.
+An existing app won't sweep clean on its first run. `exhale dry --introduced-only` gates on introduced and shifted findings and lists the rest as warnings. Once main is clean, drop the flag.
 
 ## The Contract
 
@@ -72,6 +72,7 @@ contract/
   provider_adapter/
     README.md        the primitive's prose, plus a covers block
     duplication.md   duplication it keeps, why, and its settings
+    complexity.md    complexity it keeps, why, and its floor
 ```
 
 A `parallel` block declares units that stay parallel on purpose. Its reason is the section it sits in:
@@ -118,10 +119,53 @@ exhale:
         bundler-cache: true
     - name: exhale
       shell: bash
-      run: bin/exhale --base origin/${{ github.base_ref || 'main' }} | tee -a "$GITHUB_STEP_SUMMARY"
+      run: bin/exhale dry --base origin/${{ github.base_ref || 'main' }} | tee -a "$GITHUB_STEP_SUMMARY"
 ```
 
-`fetch-depth: 0` gives exhale the history it needs to find the merge base and run `git blame`. `--format json` prints the same findings as data, and `--format edn` prints them in the shape dryer writes to `.metrics/dry.edn`.
+`fetch-depth: 0` gives `exhale dry` the history it needs to find the merge base and run `git blame`. `exhale dry --format json` prints the same findings as data, and `--format edn` prints them in the shape dryer writes to `.metrics/dry.edn`.
+
+## exhale complexity
+
+`exhale complexity` scores every Ruby method and Rails DSL body twice, at the head and at the merge base, and fails the pull request when a score rose past the floor. Absolute scores mostly track size and swing from team to team, so the gate judges the change. Code that was already complex passes until someone makes it worse.
+
+The score is G. Ann Campbell's Cognitive Complexity (SonarSource, 2017). A method that reads straight down scores low however long it is. Each `if`, `unless`, ternary, loop, `case`, `rescue` and iterating block costs a point plus how deeply it's nested, so a branch inside a loop inside a block costs 3. An `elsif` or `else` costs 1, and so does each run of `&&` or `||` and a recursive call. Calls like `send`, `define_method` and `instance_eval` cost 1 each and are reported apart as metaprogramming. `contract/cognitive/README.md` writes down every rule, down to which blocks count as iterating.
+
+| Label | Meaning | Gate |
+| --- | --- | --- |
+| Raised | The score rose and ends over the floor | fails |
+| Introduced | A new unit scores over the floor | fails |
+| Kept | The score rose past the floor and stays within a ceiling | passes |
+| Contracted | The score fell | passes |
+| Gone | The base unit has no match at the head | passes |
+
+A method keeps its history when it moves to another file, and when it's renamed: an unmatched new unit is compared with an unmatched old one whose normalized shape scores 0.80 or more against it. Splitting a method passes as long as the method doesn't rise and every new piece ends at or under the floor.
+
+The floor is 8. A primitive can set its own in `complexity.md`, and a `ceiling` block lets a unit go over the floor, up to its max, for the reason in the section it sits in:
+
+````markdown
+```settings
+floor: 10
+```
+
+## The rate table stays one method
+
+Splitting it scatters the regions across files.
+
+```ceiling
+max: 14
+Billing::Rates#lookup
+```
+````
+
+A ceiling that names no method or DSL body fails the gate, and so does one whose units all score at or under the floor again. A ceiling only loosens: a max under the floor changes nothing. `exhale complexity explain Billing::Rates#lookup` prints a unit's score with every point, its line and the construct that earned it. `--floor N` changes the report for a local run and leaves the exit code on the Contract's floors. `--format json` lists every unit with its score, metaprogramming points and label, and `--format edn` writes the entries crapper writes so uml-viewer can read them.
+
+With no git repository or no merge base there's nothing to compare, so the run exits 0 and lists the units over the floor as warnings. In CI, run it beside `exhale dry`:
+
+```yaml
+    - name: exhale complexity
+      shell: bash
+      run: bin/exhale complexity --base origin/${{ github.base_ref || 'main' }} | tee -a "$GITHUB_STEP_SUMMARY"
+```
 
 ## Determinism
 
@@ -133,9 +177,9 @@ The same commit gets the same verdict on any machine on any day. The verdict rea
 
 ## How exhale holds itself to this
 
-exhale has its own Contract in `contract/`: 64 numbered obligations across 11 primitives (source, unit, shape, fingerprint, matcher, sweep, gate, clause, report, revision and cli). Every obligation has at least one test that names it with a `# Contract: <primitive>/<id>` comment, and `rake contract` publishes contract coverage and fails while any obligation lacks an executable test. CI also runs exhale on itself, reading that Contract.
+exhale has its own Contract in `contract/`: 82 numbered obligations across 13 primitives (source, unit, shape, fingerprint, matcher, sweep, gate, clause, report, revision, cli, cognitive and ratchet). Every obligation has at least one test that names it with a `# Contract: <primitive>/<id>` comment, and `rake contract` publishes contract coverage and fails while any obligation lacks an executable test. CI also runs `exhale dry` and `exhale complexity` on itself, reading that Contract.
 
-The mutation gate runs every mutant [Mutineer](https://github.com/davidteren/mutineer) can make of `lib/` against the whole suite. Each one is either killed by a test or listed in `.mutineer.yml` with the reason no test can catch it: an equivalent mutant, an infinite loop, or a line Ruby's coverage can't see. `bin/mutate` runs it under Ruby 3.4.
+The mutation gate runs every mutant [Mutineer](https://github.com/davidteren/mutineer) can make of `lib/` against the whole suite. Each one is either killed by a test or listed in `.mutineer.yml` with the reason no test can catch it: an equivalent mutant, an infinite loop, or a line Ruby's coverage can't see. `bin/mutate` runs it under Ruby 3.4. `bin/mutate --matrix` also names the tests that kill no mutant and the tests whose every kill another test also makes; it runs every covering test per mutant, so it is a separate, slower run and not part of the gate.
 
 ## Known limits in 0.1
 

data/exhale.gemspec

@@ -8,10 +8,10 @@ Gem::Specification.new do |spec|
   spec.authors = ["Obie Fernandez"]
   spec.email = ["obiefernandez@gmail.com"]
 
-  spec.summary = "The contraction gate for Rails: no PR merges while the codebase holds duplication the Contract doesn't keep"
+  spec.summary = "The contraction toolkit for Rails. Its first check, exhale dry, fails a PR while the codebase holds duplication the Contract doesn't keep"
   spec.description = <<~DESC.strip.gsub(/\n/, " ")
-    exhale gates the exhale of every pull request in a Rails app. Its first check, exhale dry,
-    sweeps the whole codebase for duplicated Ruby and ERB, scores near-copies by rarity-weighted
+    exhale is the contraction toolkit for the exhale of every pull request in a Rails app. Its
+    first check, exhale dry, sweeps the whole codebase for duplicated Ruby and ERB, scores near-copies by rarity-weighted
     structural similarity, and fails the build while any copy is undeclared. Deliberate
     duplication is declared in the Contract, next to the reason for it. Built on Prism and Herb.
   DESC

data/lib/exhale/cli.rb

@@ -4,15 +4,23 @@ require "optparse"
 require_relative "version"
 require_relative "errors"
 require_relative "report"
+require_relative "units"
 require_relative "dry/check"
+require_relative "complexity/check"
 
 module Exhale
   # exhale [dry] [PATH...] [options]
   # exhale dry explain A B
+  # exhale complexity [PATH...] [options]
+  # exhale complexity explain UNIT
   #
   # Exit codes: 0 pass, 1 the gate failed, 2 exhale couldn't run.
   class CLI
-    CHECKS = %w[dry].freeze
+    CHECKS = %w[dry complexity].freeze
+    BANNERS = {
+      "dry" => "usage: exhale [dry] [PATH...] [options]\n       exhale dry explain IDENTITY IDENTITY",
+      "complexity" => "usage: exhale complexity [PATH...] [options]\n       exhale complexity explain IDENTITY"
+    }.freeze
 
     def initialize(argv, out: $stdout, err: $stderr)
       @argv = argv.dup
@@ -23,7 +31,7 @@ module Exhale
     end
 
     def run
-      @argv.shift if CHECKS.include?(@argv.first)
+      @check = CHECKS.include?(@argv.first) ? @argv.shift : "dry"
       return explain(@argv.drop(1)) if @argv.first == "explain"
 
       paths = parser.parse(@argv)
@@ -32,10 +40,7 @@ module Exhale
       paths = narrowing(paths)
       return 2 unless paths
 
-      result = Dry::Check.new(root: @options[:root], base: @options[:base], include_tests: @options[:include_tests],
-                              contract_dir: @options[:contract_dir], overrides: @options[:overrides],
-                              introduced_only: @options[:introduced_only], paths: paths,
-                              cache_dir: @options[:cache_dir]).run
+      result = @check == "dry" ? dry(paths) : complexity(paths)
       @out.print Report.render(result, @options[:format])
       result.exit_code
     rescue OptionParser::ParseError, ArgumentError => e
@@ -49,37 +54,65 @@ module Exhale
 
     private
 
+    def dry(paths)
+      Dry::Check.new(root: @options[:root], base: @options[:base], include_tests: @options[:include_tests],
+                     contract_dir: @options[:contract_dir], overrides: @options[:overrides],
+                     introduced_only: @options[:introduced_only], paths: paths, cache_dir: @options[:cache_dir]).run
+    end
+
+    def complexity(paths)
+      Complexity::Check.new(root: @options[:root], base: @options[:base], floor: @options[:floor],
+                            include_tests: @options[:include_tests], contract_dir: @options[:contract_dir],
+                            paths: paths).run
+    end
+
     def parser
       @parser ||= OptionParser.new do |o|
-        o.banner = "usage: exhale [dry] [PATH...] [options]\n       exhale dry explain IDENTITY IDENTITY"
-        o.on("--base REF", "Label findings against the merge base of REF and HEAD (default: the default branch)") do |v|
+        o.banner = BANNERS.fetch(@check)
+        o.on("--base REF", "Compare with the merge base of REF and HEAD (default: the default branch)") do |v|
           @options[:base] = v
         end
-        o.on("--threshold N", Float, "Minimum score, 0 to 1 (overrides the Contract; the run won't gate)") do |v|
-          @options[:overrides][:threshold] = Rational(v.to_s)
-        end
-        o.on("--min-lines N", Integer, "Minimum source lines (overrides the Contract; the run won't gate)") do |v|
-          @options[:overrides][:min_lines] = v
-        end
-        o.on("--min-nodes N", Integer, "Minimum normalized nodes (overrides the Contract; the run won't gate)") do |v|
-          @options[:overrides][:min_nodes] = v
-        end
-        o.on("--format F", "text, json or edn (default text)") { |v| @options[:format] = v }
-        o.on("--include-tests", "Compare spec/ and test/ too") { @options[:include_tests] = true }
-        o.on("--introduced-only", "On-ramp: gate only on introduced and shifted findings") do
-          @options[:introduced_only] = true
-        end
-        o.on("--contract DIR", "The Contract's root (default contract/)") { |v| @options[:contract_dir] = v }
-        o.on("--cache DIR", "Cache directory (default tmp/exhale/)") { |v| @options[:cache_dir] = v }
-        o.on("--root DIR", "Repository root (default: the current directory)") { |v| @options[:root] = v }
-        o.on("-v", "--version", "Print the version") do
-          @out.puts "exhale #{VERSION}"
-          exit 0
-        end
-        o.on("-h", "--help", "Print this help") do
-          @out.puts o
-          exit 0
-        end
+        @check == "dry" ? dry_options(o) : complexity_options(o)
+        common_options(o)
+      end
+    end
+
+    def complexity_options(o)
+      o.on("--floor N", Integer, "Scores at or under N never fail (overrides the Contract for this report)") do |v|
+        raise OptionParser::InvalidArgument, "--floor #{v}" if v.negative?
+
+        @options[:floor] = v
+      end
+    end
+
+    def dry_options(o)
+      o.on("--threshold N", Float, "Minimum score, 0 to 1 (overrides the Contract; the run won't gate)") do |v|
+        @options[:overrides][:threshold] = Rational(v.to_s)
+      end
+      o.on("--min-lines N", Integer, "Minimum source lines (overrides the Contract; the run won't gate)") do |v|
+        @options[:overrides][:min_lines] = v
+      end
+      o.on("--min-nodes N", Integer, "Minimum normalized nodes (overrides the Contract; the run won't gate)") do |v|
+        @options[:overrides][:min_nodes] = v
+      end
+      o.on("--introduced-only", "On-ramp: gate only on introduced and shifted findings") do
+        @options[:introduced_only] = true
+      end
+      o.on("--cache DIR", "Cache directory (default tmp/exhale/)") { |v| @options[:cache_dir] = v }
+    end
+
+    def common_options(o)
+      o.on("--format F", "text, json or edn (default text)") { |v| @options[:format] = v }
+      o.on("--include-tests", "Include spec/ and test/") { @options[:include_tests] = true }
+      o.on("--contract DIR", "The Contract's root (default contract/)") { |v| @options[:contract_dir] = v }
+      o.on("--root DIR", "Repository root (default: the current directory)") { |v| @options[:root] = v }
+      o.on("-v", "--version", "Print the version") do
+        @out.puts "exhale #{VERSION}"
+        exit 0
+      end
+      o.on("-h", "--help", "Print this help") do
+        @out.puts o
+        exit 0
       end
     end
 
@@ -105,28 +138,48 @@ module Exhale
       false
     end
 
-    # Prints two units' normalized trees and their score, for tuning. It
-    # checks --format, --root and --base the way a run does, so a flag that
-    # would fail CI fails here too.
+    # explain checks --format, --root and --base the way a run does, so a
+    # flag that would fail CI fails here too.
     def explain(args)
       args = parser.parse(args)
-      unless args.size == 2
-        @err.puts "usage: exhale dry explain IDENTITY IDENTITY"
+      arity = @check == "dry" ? 2 : 1
+      unless args.size == arity
+        @err.puts "usage: #{BANNERS.fetch(@check).lines.last.strip}"
         return 2
       end
       return 2 unless valid_format?
 
+      @check == "dry" ? dry_explain(args) : complexity_explain(args.first)
+    end
+
+    # Prints one unit's score and every point that earned it.
+    def complexity_explain(identity)
+      Complexity::Check.new(root: @options[:root], base: @options[:base]).validate!
+      root = File.expand_path(@options[:root])
+      git = Git.new(root)
+      units, _errors = Units.read(root, files: (git.files if git.repo?), include_tests: @options[:include_tests])
+      unit = units.find { |u| u.language == :ruby && u.identity == identity }
+      return missing(identity) unless unit
+
+      @out.print Report.explain(Complexity::Scored.of(unit))
+      0
+    end
+
+    def missing(identity)
+      @err.puts "exhale: no unit named #{identity}"
+      2
+    end
+
+    # Prints two units' normalized trees and their score, for tuning.
+    def dry_explain(args)
       Dry::Check.new(root: @options[:root], base: @options[:base], cache_dir: @options[:cache_dir]).validate!
       root = File.expand_path(@options[:root])
       git = Git.new(root)
       sweep = Dry::Sweep.new(root, files: (git.files if git.repo?), include_tests: @options[:include_tests],
                                    contract_dir: @options[:contract_dir]).run
       a, b = args.map { |identity| sweep.index.entries.find { |e| e.unit.identity == identity } }
-      missing = args.zip([a, b]).find { |_, entry| entry.nil? }
-      if missing
-        @err.puts "exhale: no unit named #{missing[0]}"
-        return 2
-      end
+      absent = args.zip([a, b]).find { |_, entry| entry.nil? }
+      return missing(absent[0]) if absent
 
       [a, b].each do |entry|
         @out.puts "#{entry.unit.identity}  #{entry.unit.path}:#{entry.unit.start_line}-#{entry.unit.end_line}"

data/lib/exhale/complexity/check.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+require_relative "../errors"
+require_relative "../git"
+require_relative "../source_files"
+require_relative "../units"
+require_relative "../contract"
+require_relative "../dry/check"
+require_relative "cognitive"
+require_relative "ratchet"
+
+module Exhale
+  module Complexity
+    DEFAULT_FLOOR = 8
+
+    # rows are narrowed to the run's paths. floor is the floor the report
+    # was judged with: the default, or --floor's. floors are the primitives
+    # that set their own, by name. contract_failing are the rows that fail
+    # under the Contract's floors and pass under --floor's.
+    Result = Struct.new(:rows, :clause_errors, :parse_errors, :base_sha, :notes, :exit_code, :floor, :floors,
+                        :contract_failing, keyword_init: true)
+
+    # The complexity check: scores every Ruby unit at the head and at the
+    # merge base, and hands both to the Ratchet.
+    class Check
+      def initialize(root:, base: nil, floor: nil, include_tests: false, contract_dir: "contract", paths: [])
+        @root = File.expand_path(root)
+        @base_ref = base
+        @floor = floor
+        @include_tests = include_tests
+        @contract_dir = contract_dir
+        @paths = paths
+        @git = Git.new(@root)
+        @notes = []
+      end
+
+      def run
+        base_sha = validate!
+        units, parse_errors = Units.read(@root, files: (@git.files if @git.repo?), include_tests: @include_tests)
+        contract = Contract.load(@root, dir: @contract_dir, check: :complexity)
+        @resolver = Contract::Resolver.new(contract, units)
+        head = units.select { |unit| unit.language == :ruby }.map { |unit| Scored.of(unit) }
+        base = base_scores(base_sha) if base_sha
+        no_base_note(base_sha)
+        ceilings = ceiling_lookup(contract)
+        errors = contract.errors + @resolver.errors + ceiling_errors(contract, head)
+
+        judge = lambda do |floor_for|
+          narrow(Ratchet.new(head: head, base: base, floor_for: floor_for, ceiling_for: ceilings).rows)
+        end
+        verdict = judge.call(method(:contract_floor))
+        rows = @floor ? judge.call(->(_unit) { @floor }) : verdict
+        Result.new(rows: rows, clause_errors: errors, parse_errors: parse_errors, base_sha: base_sha, notes: notes,
+                   exit_code: exit_code(parse_errors, verdict, errors), floor: @floor || DEFAULT_FLOOR,
+                   floors: floors(contract), contract_failing: contract_failing(verdict, rows))
+      end
+
+      # The SHA of the merge base, or nil when there's none to compare with.
+      # A --base git can't find is an error, the same as for dry.
+      def validate!
+        Dry::Check.new(root: @root, base: @base_ref).validate!
+      end
+
+      private
+
+      def contract_floor(unit)
+        @resolver.settings_for(unit, { floor: DEFAULT_FLOOR })[:floor]
+      end
+
+      def base_scores(sha)
+        Dir.mktmpdir("exhale-complexity") do |dir|
+          files = @git.files_at(sha).select { |path| SourceFiles.language(path) == :ruby }
+          @git.export_files(sha, files, dir)
+          units, errors = Units.read(dir, files: files, include_tests: @include_tests)
+          errors.each { |e| @notes << "#{e.path} doesn't parse at the base, so its units count as new" }
+          units.map { |unit| Scored.of(unit) }
+        end
+      end
+
+      def no_base_note(base_sha)
+        return if base_sha
+
+        advice = "; pass --base REF to compare" if @git.repo? && !@git.default_branch_ref
+        @notes.unshift("#{no_base_reason}, so nothing is compared; units over the floor are warnings#{advice}")
+      end
+
+      def no_base_reason
+        return "not a git repository" unless @git.repo?
+        return "no merge base found" if @git.default_branch_ref
+
+        *first, last = Git::DEFAULT_CANDIDATES
+        "no default branch found (origin/HEAD, #{first.join(', ')} or #{last})"
+      end
+
+      # Both lists hold the same units in the same order.
+      def contract_failing(verdict, rows)
+        verdict.zip(rows).filter_map { |contract, shown| contract if contract.failing? && !shown.failing? }
+      end
+
+      # Under --floor every primitive takes it, so none has its own.
+      def floors(contract)
+        return {} if @floor
+
+        contract.settings.filter_map { |name, settings| [name, settings[:floor]] if settings.key?(:floor) }.to_h
+      end
+
+      def notes
+        notes = @notes.dup
+        if @floor
+          notes << "--floor #{@floor} overrides the Contract for this report only; " \
+                   "the exit code keeps the Contract's floors"
+        end
+        notes << "narrowed to #{@paths.join(', ')}: only units there are reported and gated" unless @paths.empty?
+        notes
+      end
+
+      # unit => the clause of its most specific ceiling reference. A tie
+      # takes the lower max, then the clause written first.
+      def ceiling_lookup(contract)
+        best = {}.compare_by_identity
+        ceiling_ranks(contract).sort_by(&:first).each { |_, unit, clause| best[unit] = clause }
+        ->(unit) { best[unit] }
+      end
+
+      def ceiling_ranks(contract)
+        ceilings(contract).each_with_index.flat_map do |clause, index|
+          clause.references.flat_map do |ref|
+            @resolver.units_for(ref).map { |unit| [[ref.specificity, -clause.max, -index], unit, clause] }
+          end
+        end
+      end
+
+      def ceilings(contract)
+        contract.clauses.select { |clause| clause.kind == :ceiling }
+      end
+
+      def ceiling_errors(contract, head)
+        scores = head.each_with_object({}.compare_by_identity) { |scored, map| map[scored.unit] = scored.score }
+        ceilings(contract).filter_map do |clause|
+          problem = ceiling_problem(clause, scores)
+          ContractError.new(clause.path, clause.line, problem) if problem
+        end
+      end
+
+      # A ceiling has to name a scored unit, and is stale once nothing it
+      # names sits over the floor. A reference that names nothing at all is
+      # already the resolver's error.
+      def ceiling_problem(clause, scores)
+        named = clause.references.flat_map { |ref| @resolver.units_for(ref) }
+        return if named.empty?
+
+        scored = named.select { |unit| scores.key?(unit) }
+        return "ceiling names no scored unit; only methods and DSL bodies are scored" if scored.empty?
+        return if scored.any? { |unit| scores[unit] > contract_floor(unit) }
+
+        "stale ceiling: nothing it names scores over the floor; delete it"
+      end
+
+      def narrow(rows)
+        return rows if @paths.empty?
+
+        rows.select { |row| @paths.any? { |p| p == "." || row.unit.path == p || row.unit.path.start_with?("#{p}/") } }
+      end
+
+      def exit_code(parse_errors, verdict, errors)
+        return 2 unless parse_errors.empty?
+
+        verdict.any?(&:failing?) || !errors.empty? ? 1 : 0
+      end
+    end
+  end
+end