exhale 0.1.0 → 0.2.0

data/lib/exhale/report.rb

@@ -3,23 +3,31 @@
 require "json"
 require_relative "version"
 require_relative "dry/normalizer"
+require_relative "complexity/check"
 
 module Exhale
   # Renders a duplication check's result as text for the agent doing the
   # exhale, JSON for tools, or EDN in the shape dryer writes to
-  # .metrics/dry.edn.
+  # .metrics/dry.edn. A complexity check's result renders the same three
+  # ways, its EDN in the shape crapper writes.
   module Report
     FORMATS = %w[text json edn].freeze
+    COMPLEXITY_LABELS = %i[raised introduced kept warning contracted gone].freeze
+    TOP_LINES = 5
     LABELS = { introduced: "INTRODUCED", shifted: "SHIFTED", already_there: "ALREADY THERE", found: "FOUND" }.freeze
 
     module_function
 
     def render(result, format)
+      raise ArgumentError, "unknown format #{format.inspect}" unless FORMATS.include?(format)
+
+      text, json, edn = if result.is_a?(Complexity::Result) then [ComplexityText, ComplexityJson, ComplexityEdn]
+                        else [Text, Json, Edn]
+                        end
       case format
-      when "text" then Text.new(result).render
-      when "json" then JSON.pretty_generate(Json.new(result).to_h)
-      when "edn" then Edn.new(result).render
-      else raise ArgumentError, "unknown format #{format.inspect}"
+      when "text" then text.new(result).render
+      when "json" then JSON.pretty_generate(json.new(result).to_h)
+      else edn.new(result).render
       end
     end
 
@@ -39,6 +47,30 @@ module Exhale
       value.to_f.round(2)
     end
 
+    # One unit's score with every point, for `exhale complexity explain`.
+    def explain(scored)
+      unit = scored.unit
+      out = ["#{unit.identity}  #{unit.path}:#{unit.start_line}-#{unit.end_line}",
+             "score #{scored.score}, #{scored.meta} metaprogramming"]
+      width = scored.points.map { |p| p.construct.size }.max.to_i
+      scored.points.each do |p|
+        out << "  line #{p.line.to_s.ljust(5)} +#{p.increment}  #{p.construct.ljust(width)}  nesting #{p.nesting}"
+      end
+      "#{out.join("\n")}\n"
+    end
+
+    def complexity_counts(result)
+      counts = Hash.new(0)
+      result.rows.each { |row| counts[row.label] += 1 }
+      counts
+    end
+
+    # [[line, points earned there, constructs]], worst first.
+    def worst_lines(points)
+      points.group_by(&:line).map { |line, at| [line, at.sum(&:increment), at.map(&:construct).uniq] }
+            .sort_by { |line, total, _| [-total, line] }.first(TOP_LINES)
+    end
+
     class Text
       def initialize(result)
         @result = result
@@ -199,5 +231,138 @@ module Exhale
         "{:file #{l.path.inspect}, :start-line #{l.start_line}, :end-line #{l.end_line}}"
       end
     end
+
+    # Shares the duplication report's error lines and places.
+    class ComplexityText < Text
+      HEADINGS = { raised: "RAISED", introduced: "INTRODUCED", warning: "OVER THE FLOOR" }.freeze
+      CONTRACT_FAILING = "FAILS UNDER THE CONTRACT'S FLOORS"
+
+      def render
+        @out << header
+        @result.notes.each { |note| @out << "note: #{note}" }
+        @result.rows.select { |row| HEADINGS.key?(row.label) }.sort_by { |row| order(row) }.each { |row| unit(row) }
+        # Under --floor these units pass in the report but fail the run.
+        @result.contract_failing.each { |row| unit(row, CONTRACT_FAILING) }
+        kept
+        errors
+        @out << ""
+        @out << "#{Report.complexity_counts(@result)[:contracted]} contracted"
+        "#{@out.join("\n")}\n"
+      end
+
+      private
+
+      def header
+        counts = Report.complexity_counts(@result)
+        parts = ["#{@result.rows.count(&:head)} units"]
+        COMPLEXITY_LABELS.each { |label| parts << "#{counts[label]} #{label}" if counts[label].positive? }
+        parts << plural(@result.clause_errors.size, "contract error") unless @result.clause_errors.empty?
+        parts << plural(@result.parse_errors.size, "parse error") unless @result.parse_errors.empty?
+        parts << (@result.exit_code.zero? ? "clean" : "failing")
+        base = @result.base_sha ? "   base #{@result.base_sha[0, 7]}" : ""
+        floors = @result.floors.map { |name, floor| ", #{name} #{floor}" }.join
+        "exhale complexity: #{parts.join(', ')}#{base}   floor #{@result.floor}#{floors}"
+      end
+
+      def order(row)
+        [HEADINGS.keys.index(row.label), -row.head.score, row.unit.path, row.unit.start_line]
+      end
+
+      def unit(row, heading = HEADINGS.fetch(row.label))
+        head = row.head
+        @out << ""
+        @out << "#{heading}  #{head.unit.identity}  #{scores(row)}"
+        @out << "  #{place(head.unit)}"
+        @out << "  was #{row.base.unit.identity} at #{place(row.base.unit)}" if row.match == :shape
+        Report.worst_lines(head.points).each do |line, total, constructs|
+          @out << "  line #{line.to_s.ljust(5)} +#{total.to_s.ljust(3)} #{constructs.join(', ')}"
+        end
+        @out << "  hint      #{hint(row)}"
+      end
+
+      def scores(row)
+        limit = row.ceiling ? "ceiling #{row.ceiling.max}" : "floor #{row.floor}"
+        from = row.base ? "#{row.base.score} -> " : ""
+        "#{from}#{row.head.score} (#{limit})"
+      end
+
+      def hint(row)
+        limit = row.ceiling ? [row.ceiling.max, row.floor].max : row.floor
+        case row.label
+        when :raised
+          "bring it back to #{[row.base.score, limit].max} or less: pull the worst lines into named methods"
+        when :introduced then "split it until every piece scores #{limit} or less"
+        else "it was already over the floor; nothing is compared without a base"
+        end
+      end
+
+      def kept
+        @result.rows.select { |row| row.label == :kept }.each do |row|
+          clause = row.ceiling
+          @out << ""
+          @out << "KEPT  #{row.head.unit.identity}  #{scores(row)}  #{clause.path}:#{clause.line} \"#{clause.heading}\""
+        end
+      end
+    end
+
+    class ComplexityJson
+      def initialize(result)
+        @result = result
+      end
+
+      def to_h
+        {
+          "exhale" => VERSION,
+          "check" => "complexity",
+          "base" => @result.base_sha,
+          "floor" => @result.floor,
+          "floors" => @result.floors,
+          "exit_code" => @result.exit_code,
+          "counts" => Report.complexity_counts(@result).transform_keys(&:to_s),
+          "notes" => @result.notes,
+          "units" => @result.rows.map { |row| row(row) },
+          "contract_failing" => @result.contract_failing.map { |row| row.unit.identity },
+          "contract_errors" => @result.clause_errors.map { |e| error(e) },
+          "parse_errors" => @result.parse_errors.map { |e| error(e) }
+        }
+      end
+
+      private
+
+      def row(row)
+        side(row.head || row.base).merge(
+          "label" => row.label.to_s, "score" => row.head&.score, "base_score" => row.base&.score,
+          "base" => row.head && row.base ? side(row.base).slice("identity", "path", "start_line", "end_line") : nil,
+          "match" => row.match&.to_s, "similarity" => row.similarity&.to_f&.round(2), "floor" => row.floor,
+          "ceiling" => row.ceiling && row.ceiling.to_h.slice(:path, :line, :max).transform_keys(&:to_s)
+        )
+      end
+
+      def side(scored)
+        unit = scored.unit
+        { "identity" => unit.identity, "kind" => unit.kind.to_s, "path" => unit.path,
+          "start_line" => unit.start_line, "end_line" => unit.end_line, "metaprogramming" => scored.meta,
+          "points" => scored.points.map { |p| p.to_h.transform_keys(&:to_s) } }
+      end
+
+      def error(e)
+        { "path" => e.path, "line" => e.line, "message" => e.message }
+      end
+    end
+
+    # The entries crapper writes, so uml-viewer can read them.
+    class ComplexityEdn
+      def initialize(result)
+        @result = result
+      end
+
+      def render
+        rows = @result.rows.select(&:head).map do |row|
+          unit = row.head.unit
+          "{:name #{unit.name.inspect}, :namespace #{unit.namespace.inspect}, :complexity #{row.head.score}}"
+        end
+        "{:entries\n [#{rows.join("\n  ")}]}\n"
+      end
+    end
   end
 end

data/lib/exhale/units.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "source_files"
+require_relative "units/ruby"
+require_relative "units/erb"
+
+module Exhale
+  # The units of a tree, read from the files SourceFiles lists.
+  module Units
+    module_function
+
+    # [units, parse errors]. A file that can't be read, or isn't UTF-8, is a
+    # parse error like any other: no gate passes code it didn't read.
+    def read(root, files: nil, include_tests: false)
+      errors = []
+      units = SourceFiles.list(root, files: files, include_tests: include_tests).flat_map do |path, language|
+        source = source(root, path)
+        language == :ruby ? Ruby.extract(source, path) : Erb.extract(source, path)
+      rescue ParseError => e
+        errors << e
+        []
+      end
+      [units, errors]
+    end
+
+    def source(root, path)
+      source = File.read(File.join(root, path), encoding: "UTF-8")
+      return source if source.valid_encoding?
+
+      line = source.each_line.find_index { |text| !text.valid_encoding? }.to_i + 1
+      raise ParseError.new(path, line, "isn't valid UTF-8")
+    rescue SystemCallError, IOError => e
+      raise ParseError.new(path, 1, "can't be read: #{e.message}")
+    end
+  end
+end

data/lib/exhale/version.rb

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

data/lib/exhale.rb

@@ -8,6 +8,7 @@ require_relative "exhale/git"
 require_relative "exhale/source_files"
 require_relative "exhale/units/ruby"
 require_relative "exhale/units/erb"
+require_relative "exhale/units"
 require_relative "exhale/contract"
 require_relative "exhale/dry/normalizer/ruby"
 require_relative "exhale/dry/normalizer/erb"
@@ -17,6 +18,9 @@ require_relative "exhale/dry/index"
 require_relative "exhale/dry/matcher"
 require_relative "exhale/dry/gate"
 require_relative "exhale/dry/check"
+require_relative "exhale/complexity/cognitive"
+require_relative "exhale/complexity/ratchet"
+require_relative "exhale/complexity/check"
 require_relative "exhale/report"
 require_relative "exhale/cli"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: exhale
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Obie Fernandez
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -80,11 +80,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: 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 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.
+description: 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.
 email:
 - obiefernandez@gmail.com
 executables:
@@ -101,6 +101,9 @@ files:
 - exhale.gemspec
 - lib/exhale.rb
 - lib/exhale/cli.rb
+- lib/exhale/complexity/check.rb
+- lib/exhale/complexity/cognitive.rb
+- lib/exhale/complexity/ratchet.rb
 - lib/exhale/contract.rb
 - lib/exhale/contract/markdown.rb
 - lib/exhale/contract/reference.rb
@@ -119,6 +122,7 @@ files:
 - lib/exhale/shape.rb
 - lib/exhale/source_files.rb
 - lib/exhale/unit.rb
+- lib/exhale/units.rb
 - lib/exhale/units/erb.rb
 - lib/exhale/units/ruby.rb
 - lib/exhale/version.rb
@@ -147,6 +151,6 @@ requirements: []
 rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
-summary: 'The contraction gate for Rails: no PR merges while the codebase holds duplication
-  the Contract doesn''t keep'
+summary: The contraction toolkit for Rails. Its first check, exhale dry, fails a PR
+  while the codebase holds duplication the Contract doesn't keep
 test_files: []