padded_cell 0.1.0 → 0.3.0

data/lib/padded_cell/chart/config.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # A PaddedCell.coverage block, in the test helper:
+    #
+    #   PaddedCell.coverage(:rails) do
+    #     track "{app,lib}/**/*.rb"
+    #     skip "app/legacy/"
+    #     group "Operations", "app/concepts"
+    #     minimum line: 90, branch: 80
+    #     minimum_by_file line: 50
+    #     minimum_by_group "Models", line: 95
+    #     maximum_drop line: 1
+    #     formats :markdown, :lcov, :json
+    #   end
+    #
+    # Filters and groups match paths (see Filter). What is
+    # measured is decided before the suite loads, on the command line:
+    # --coverage=lines,branches,methods.
+    class Config
+      FORMATS = %i[markdown lcov json].freeze
+      # Left out unless cleared: bundled gems, hidden files, test files.
+      DEFAULT_FILTERS = ['/vendor/bundle/', /\A\..*/, %r{\A(test|features|spec|autotest)/}].freeze
+      RAILS_GROUPS = {
+        'Channels' => 'app/channels', 'Controllers' => 'app/controllers', 'Helpers' => 'app/helpers',
+        'Jobs' => %w[app/jobs app/workers], 'Libraries' => 'lib/', 'Mailers' => 'app/mailers',
+        'Models' => 'app/models', 'Views' => 'app/views'
+      }.freeze
+
+      attr_reader :filters, :groups, :tracked, :output_formats, :directory, :token, :interval, :minimums,
+                  :file_minimums, :group_minimums, :maximum_drops
+
+      def initialize
+        @filters = DEFAULT_FILTERS.map { Filter.build(it) }
+        @groups = {}
+        @tracked = []
+        @minimums = {}
+        @file_minimums = {}
+        @group_minimums = {}
+        @maximum_drops = {}
+        @output_formats = %i[markdown lcov json]
+        @directory = 'coverage'
+        @token = 'nocov'
+        @interval = Probe::INTERVAL
+      end
+
+      # :rails skips config/ and db/, groups the
+      # app's directories, tracks {app,lib}/**/*.rb.
+      def profile(name)
+        raise ArgumentError, "unknown coverage profile #{name.inspect} (known: :rails)" unless name.to_s == 'rails'
+
+        skip(%r{\Aconfig/}, %r{\Adb/})
+        RAILS_GROUPS.each { |group_name, filter| group(group_name, filter) }
+        track('{app,lib}/**/*.rb')
+      end
+
+      # Files to report even when the suite never loads them, at 0%.
+      def track(*globs) = @tracked.concat(globs)
+
+      # Files to leave out of the report.
+      def skip(*filters, &block)
+        filters.each { @filters << Filter.build(it) }
+        @filters << Filter.build(&block) if block
+      end
+      alias filter skip
+
+      # Removes every filter, the defaults included.
+      def clear_filters = @filters.clear
+
+      # A file can be in several groups; files in none are Ungrouped.
+      # Defining a group again replaces it.
+      def group(name, filter = nil, &) = @groups[name.to_s] = Filter.build(filter, &)
+
+      # Thresholds compare percents floored to 2 decimals; a whole, passing
+      # run that misses one exits 3.
+      def minimum(line: nil, branch: nil, method: nil) = @minimums.merge!({ line:, branch:, method: }.compact)
+
+      # For every file.
+      def minimum_by_file(line: nil, branch: nil, method: nil)
+        @file_minimums.merge!({ line:, branch:, method: }.compact)
+      end
+
+      def minimum_by_group(name, line: nil, branch: nil, method: nil)
+        (@group_minimums[name.to_s] ||= {}).merge!({ line:, branch:, method: }.compact)
+      end
+
+      # How many points coverage may lose since the previous whole run.
+      def maximum_drop(line: nil, branch: nil, method: nil)
+        @maximum_drops.merge!({ line:, branch:, method: }.compact)
+      end
+
+      def formats(*names)
+        unknown = names.map(&:to_sym) - FORMATS
+        unless unknown.empty?
+          raise ArgumentError, "unknown coverage formats: #{unknown.join(', ')} (known: #{FORMATS.join(', ')})"
+        end
+
+        @output_formats = names.map(&:to_sym)
+      end
+
+      # Where reports go (default: coverage). --coverage-dir wins.
+      def dir(path) = @directory = path
+
+      # `# :nocov:` opens and closes blocks of lines coverage ignores.
+      def nocov_token(token) = @token = token
+
+      # How often, at least, a worker hands over what it measured (seconds,
+      # default 10, stretched to keep it under 1% of the worker's time; 0:
+      # after every test). A worker that dies loses what it measured since.
+      def flush_interval(seconds) = @interval = seconds
+
+      # What a report needs once files are filtered and grouped, as stored
+      # in its Document.
+      def settings
+        {
+          formats: @output_formats.map(&:to_s), nocov_token: @token, minimum: @minimums,
+          minimum_by_file: @file_minimums, minimum_by_group: @group_minimums, maximum_drop: @maximum_drops
+        }
+      end
+
+      # Criteria come from the command line, before the suite (and this
+      # block) loads.
+      def enable_coverage(*)
+        raise ArgumentError, 'coverage criteria come from --coverage=lines,branches,methods, not the test helper'
+      end
+    end
+  end
+end

data/lib/padded_cell/chart/delta.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # The coverage of one process, made to cross to another one and be summed
+    # there:
+    #
+    #   {path => {lines:, branches:, methods:}}
+    #
+    #   lines     Array, nil where there is no code (dense), or {index => hits}
+    #   branches  {[type, l1, c1, l2, c2] => {[type, l1, c1, l2, c2] => hits}}
+    #   methods   {[name, l1, c1, l2, c2] => [owner, hits]}
+    #
+    # A dense entry carries the structure of its file, zeros included. A
+    # sparse one holds only what ran, for files whose structure the receiver
+    # has from elsewhere (the runner loaded them before forking). Keys are
+    # source positions: Ruby's branch ids change with every compile, and
+    # method owners (anonymous classes) differ between processes.
+    module Delta
+      module_function
+
+      # result: Ruby's Coverage.result or peek_result. Files in known become
+      # sparse entries, or nothing when none of their code ran; files for
+      # which keep is false are left out.
+      def capture(result, known, keep)
+        delta = {}
+        result.each do |path, data|
+          next unless keep.call(path)
+
+          if known.include?(path)
+            entry = sparse(data)
+            delta[path] = entry if entry
+          else
+            delta[path] = dense(data)
+          end
+        end
+        delta
+      end
+
+      # Adds delta into total (both deltas). Sums hits; a dense entry brings
+      # its structure along. Order does not matter.
+      def merge!(total, delta)
+        delta.each do |path, entry|
+          into = total[path]
+          next total[path] = copy(entry) unless into
+
+          into[:lines] = merge_lines(into[:lines], entry[:lines])
+          merge_branches(into[:branches] ||= {}, entry[:branches]) if entry[:branches]
+          merge_methods(into[:methods] ||= {}, entry[:methods]) if entry[:methods]
+        end
+        total
+      end
+
+      # Coverage's arrays are frozen.
+      def dense(data)
+        {
+          lines: data[:lines].dup,
+          branches: data[:branches] && branches(data[:branches], all: true),
+          methods: data[:methods] && methods(data[:methods], all: true)
+        }.compact
+      end
+
+      # nil when nothing in the file ran. Branches only run on lines that ran;
+      # a method can run without a line (an empty body), so methods are
+      # looked at either way.
+      def sparse(data)
+        lines = data[:lines]
+        ran = (lines.compact.max || 0).positive?
+        methods = data[:methods] && methods(data[:methods], all: false)
+        return if !ran && (methods.nil? || methods.empty?)
+
+        entry = { lines: ran ? sparse_lines(lines) : {} }
+        entry[:branches] = branches(data[:branches], all: false) if ran && data[:branches]
+        entry[:methods] = methods if methods
+        entry
+      end
+
+      def sparse_lines(lines)
+        hits = {}
+        lines.each_with_index { |count, index| hits[index] = count if count&.positive? }
+        hits
+      end
+
+      def branches(raw, all:)
+        raw.each_with_object({}) do |(condition, arms), out|
+          kept = {}
+          arms.each { |arm, hits| kept[position(arm)] = hits if all || hits.positive? }
+          out[position(condition)] = kept if all || !kept.empty?
+        end
+      end
+
+      def methods(raw, all:)
+        raw.each_with_object({}) do |(key, hits), out|
+          next unless all || hits.positive?
+
+          owner, name, *span = key
+          entry = out[[name, *span]]
+          entry ? entry[1] += hits : out[[name, *span]] = [owner.name || owner.inspect, hits]
+        end
+      end
+
+      # [type, id, first line, first column, last line, last column], minus
+      # the id.
+      def position(key) = [key[0], key[2], key[3], key[4], key[5]]
+
+      def copy(entry)
+        {
+          lines: entry[:lines].dup,
+          branches: entry[:branches]&.transform_values(&:dup),
+          methods: entry[:methods]&.transform_values(&:dup)
+        }.compact
+      end
+
+      # Dense + dense sums by index (an eval'd file can grow); dense + sparse
+      # adds the sparse hits; sparse + sparse sums by index.
+      def merge_lines(into, lines)
+        return add_sparse(lines.dup, into) if into.is_a?(Hash) && lines.is_a?(Array)
+        return add_sparse(into, lines) if lines.is_a?(Hash)
+
+        lines.each_with_index do |hits, index|
+          next unless hits
+
+          into[index] = (into[index] || 0) + hits
+        end
+        into
+      end
+
+      def add_sparse(into, sparse)
+        sparse.each { |index, hits| into[index] = (into[index] || 0) + hits }
+        into
+      end
+
+      def merge_branches(into, branches)
+        branches.each do |condition, arms|
+          kept = into[condition] ||= {}
+          arms.each { |arm, hits| kept[arm] = (kept[arm] || 0) + hits }
+        end
+      end
+
+      def merge_methods(into, methods)
+        methods.each do |key, (owner, hits)|
+          entry = into[key]
+          entry ? entry[1] += hits : into[key] = [owner, hits]
+        end
+      end
+    end
+  end
+end

data/lib/padded_cell/chart/document.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'fileutils'
+require 'json'
+
+module PaddedCell
+  module Chart
+    # What a report is made from, as stored in coverage/.padded_cell.json:
+    # the files once filtered, tracked and grouped, and the report settings.
+    # --coverage-merge sums the documents of shards without loading the
+    # suite.
+    #
+    #   files   {name => {digest:, loaded:, lines:, branches:, methods:}} (see Raw)
+    #   groups  {group name => [file name, ...]}
+    #   shard   [index, count], 0-based
+    #   whole   the run selected no test by name or line
+    Document = Data.define(:root, :criteria, :lost, :shard, :whole, :settings, :files, :groups, :unmeasured) do
+      def self.build(raw, config:, shard:, whole:)
+        source_files = SourceFiles.new(raw[:files], config:, root: raw[:root])
+        files = source_files.rows.to_h do |path, name, lines, branches, methods, loaded|
+          [name, { digest: Digest::SHA256.file(path).hexdigest, loaded:, lines:, branches:, methods: }.compact]
+        end
+        groups = source_files.groups.to_h { |name, indices| [name, indices.map { source_files.rows[it][1] }] }
+        new(root: raw[:root], criteria: raw[:criteria].map(&:to_s), lost: raw[:lost], shard:, whole:,
+            settings: config.settings, files:, groups:, unmeasured: source_files.unmeasured)
+      end
+
+      def self.load(dir)
+        data = JSON.parse(File.read(File.join(dir, '.padded_cell.json')), symbolize_names: true)
+        raise ArgumentError, "#{dir}: not a padded_cell coverage document" unless data[:format] == Document::FORMAT
+
+        new(root: data[:root], criteria: data[:criteria], lost: data[:lost], shard: data[:shard],
+            whole: data[:whole], settings: data[:settings], unmeasured: [],
+            files: data[:files].transform_keys(&:to_s), groups: data[:groups].transform_keys(&:to_s))
+      end
+
+      # [[absolute path, name, lines, branches, methods, loaded], ...] in
+      # name order, for PaddedCellNative.chart_report.
+      def rows
+        files.sort.map do |name, file|
+          [File.join(root, name), name, file[:lines], file[:branches], file[:methods], file[:loaded]]
+        end
+      end
+
+      # [[group name, [row index, ...]], ...]
+      def group_rows
+        index = files.keys.sort.each_with_index.to_h
+        groups.map { |name, names| [name, names.map { index.fetch(it) }.sort] }
+      end
+
+      # Every shard of a whole run, and nothing lost: thresholds apply.
+      def complete? = whole && shard[0].zero? && shard[1] == 1 && lost.values.all?(&:zero?)
+
+      def write(dir)
+        FileUtils.mkdir_p(dir)
+        data = { format: Document::FORMAT, version: 1, **to_h.except(:unmeasured) }
+        File.write(File.join(dir, '.padded_cell.json'), JSON.generate(data))
+      end
+    end
+
+    Document::FORMAT = 'padded_cell-coverage'
+  end
+end

data/lib/padded_cell/chart/filter.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # What filter and group blocks receive: a file of the report.
+    class SourceFile
+      attr_reader :filename, :project_filename
+
+      def initialize(filename, project_filename)
+        @filename = filename
+        @project_filename = project_filename
+      end
+
+      # Its lines, as File.readlines gives them.
+      def src = @src ||= File.readlines(filename)
+      alias source src
+    end
+
+    # Filters and groups pick files by their path
+    # relative to the project root:
+    #
+    #   "lib/"         a directory, anywhere along the path
+    #   "app/models"   a path segment: app/models/user.rb, not app/models_old/
+    #   "contract.rb"  a file name ending
+    #   /regexp/       matched against the relative path
+    #   [a, b]         any of them
+    #   { |file| }     a block, given a SourceFile
+    module Filter
+      module_function
+
+      # A callable taking a SourceFile.
+      def build(argument = nil, &block)
+        case argument || block
+        when String then string(argument)
+        when Regexp then ->(file) { argument.match?(file.project_filename) }
+        when Array
+          filters = argument.map { build(it) }
+          ->(file) { filters.any? { it.call(file) } }
+        when Proc then argument || block
+        else raise ArgumentError, "a coverage filter is a String, Regexp, Array or block, not #{argument.inspect}"
+        end
+      end
+
+      def string(argument)
+        normalized = argument.delete_prefix('/')
+        escaped = Regexp.escape(normalized)
+        pattern = if normalized.end_with?('/') then %r{(?:\A|/)#{escaped}}
+                  elsif normalized.include?('.') && !normalized.include?('/') then %r{[^/]*#{escaped}(?=[/.]|\z)}
+                  else %r{(?:\A|/)#{escaped}(?=[/.]|\z)}
+                  end
+        ->(file) { pattern.match?(file.project_filename) }
+      end
+    end
+  end
+end

data/lib/padded_cell/chart/merge.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # --coverage-merge: one report from the documents of shards
+    # (--shard I/N), here, without loading the suite. Each shard stored its
+    # files filtered and grouped, with their settings.
+    module Merge
+      module_function
+
+      # dirs: the shards' coverage directories.
+      def call(dirs, root: File.realpath(Dir.pwd))
+        documents = dirs.map { Document.load(it) }
+        criteria = documents.map(&:criteria).uniq
+        raise ArgumentError, "the shards measured different criteria: #{criteria.join(' / ')}" if criteria.size > 1
+
+        Document.new(
+          root:, criteria: criteria.first, lost: lost(documents), shard: shard(documents),
+          whole: documents.all?(&:whole), settings: documents.first.settings, files: files(documents, root),
+          groups: groups(documents), unmeasured: []
+        )
+      end
+
+      def lost(documents)
+        documents.map(&:lost).reduce { |sum, lost| sum.merge(lost) { |_, left, right| left + right } }
+      end
+
+      # [0, 1] when the documents are every shard of a run, once each.
+      def shard(documents)
+        counts = documents.map { it.shard[1] }.uniq
+        indices = documents.map { it.shard[0] }.sort
+        counts.size == 1 && indices == (0...counts.first).to_a ? [0, 1] : documents.first.shard
+      end
+
+      def groups(documents)
+        documents.flat_map { it.groups.to_a }.group_by(&:first).transform_values { it.flat_map(&:last).uniq }
+      end
+
+      # A file loaded by any shard is summed over the shards that loaded it;
+      # otherwise it is the tracked, never loaded stub.
+      def files(documents, root)
+        documents.flat_map { it.files.to_a }.group_by(&:first).to_h do |name, entries|
+          files = entries.map(&:last)
+          same_source!(name, files, root)
+          loaded = files.select { it[:loaded] }
+          [name, loaded.empty? ? files.first : sum(loaded)]
+        end
+      end
+
+      def sum(files)
+        total = files.each_with_object({}) { |file, sum| Delta.merge!(sum, { file: Raw.entry(file) }) }
+        Raw.file(total[:file]).merge(digest: files.first[:digest], loaded: true)
+      end
+
+      def same_source!(name, files, root)
+        digests = files.map { it[:digest] }.uniq
+        return if digests == [Digest::SHA256.file(File.join(root, name)).hexdigest]
+
+        raise ArgumentError, "#{name} differs between the shards or from this checkout: merge reports of one commit"
+      end
+    end
+  end
+end

data/lib/padded_cell/chart/probe.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # The measuring side, in a worker and in its cells.
+    #
+    # A fork starts with its line and branch counters at zero, so each process
+    # measures only itself; method counters are inherited, and cleared on
+    # start when methods are measured.
+    #
+    # A cell sends its delta to its worker along with its result. The worker
+    # adds those to its own measure and appends the sum to its frame file
+    # every interval, and once more before its cleanup hooks (which may stop
+    # Coverage). A worker killed mid-run loses at most one interval.
+    #
+    # A flush copies the coverage of every file Ruby loaded, gems included: a
+    # few milliseconds in a small app, a few hundred in a big Rails one. The
+    # interval stretches to keep flushes under 1% of a worker's time.
+    class Probe
+      INTERVAL = 10.0
+      BUDGET = 100
+
+      def initialize(file:, known:, keep:, methods:, interval: INTERVAL)
+        @file = file
+        @known = known
+        @keep = keep
+        @methods = methods
+        @interval = interval
+        @wait = interval
+        @pending = {}
+        @lost = 0
+      end
+
+      # Right after a fork, before anything runs.
+      def start
+        ::Coverage.result(stop: false, clear: true) if @methods
+        @flushed = Minitest.clock_time
+      end
+
+      # The delta of a cell, at its end.
+      def capture = Delta.capture(::Coverage.peek_result, @known, @keep)
+
+      # A cell's delta, in its worker.
+      def absorb(delta) = Delta.merge!(@pending, delta)
+
+      # A cell that died before reporting.
+      def lost = @lost += 1
+
+      # Between tests.
+      def tick
+        flush if Minitest.clock_time - @flushed >= @wait
+      end
+
+      def flush
+        started = Minitest.clock_time
+        delta = Delta.merge!(Delta.capture(::Coverage.result(stop: false, clear: true), @known, @keep), @pending)
+        frame = Marshal.dump({ delta:, lost: @lost })
+        File.open(@file, 'ab') { it.write([frame.bytesize].pack('N') + frame) }
+        # Dense entries brought their structure to the runner: from now on,
+        # the cells forked here send these files sparse.
+        delta.each { |path, entry| @known << path if entry[:lines].is_a?(Array) }
+        @pending = {}
+        @lost = 0
+        @flushed = Minitest.clock_time
+        # 0: after every test, whatever it costs.
+        @wait = @interval.zero? ? 0 : [@interval, (@flushed - started) * BUDGET].max
+      end
+    end
+  end
+end

data/lib/padded_cell/chart/raw.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PaddedCell
+  module Chart
+    # The summed coverage as plain data (coverage/.padded_cell.json): what
+    # the reports are made from, and what shards merge.
+    #
+    #   files: {relative path => {lines:, branches:, methods:}}
+    #     lines     [hits or nil, ...] by line
+    #     branches  [[type, l1, c1, l2, c2, [[type, l1, c1, l2, c2, hits], ...]], ...]
+    #     methods   [[owner, name, l1, c1, l2, c2, hits], ...]
+    module Raw
+      module_function
+
+      def build(files, root:, criteria:, lost:)
+        {
+          format: 'padded_cell-coverage', version: 1, root:, criteria:, lost:,
+          files: files.sort.to_h { |path, entry| [path, file(entry)] }
+        }
+      end
+
+      # Every file reaches the runner dense at least once (the runner's own
+      # measure covers what it loaded, forks send the rest dense): lines is
+      # an Array by now. Branches keep Ruby's order, the order they were
+      # compiled in, which reports number them by; methods come in heap
+      # order, different in every process: sorted by position.
+      def file(entry)
+        {
+          lines: entry[:lines],
+          branches: entry[:branches]&.map do |condition, arms|
+            [*condition, arms.map { |arm, hits| [*arm, hits] }]
+          end,
+          methods: entry[:methods]&.sort_by { |(name, *span), _| [span, name] }
+                                 &.map { |(name, *span), (owner, hits)| [owner, name, *span, hits] }
+        }.compact
+      end
+
+      # file's inverse: a dense Delta entry.
+      def entry(file)
+        {
+          lines: file[:lines].dup,
+          branches: file[:branches]&.to_h { |row| [row[0, 5], row[5].to_h { |arm| [arm[0, 5], arm[5]] }] },
+          methods: file[:methods]&.to_h { |owner, name, *span, hits| [[name, *span], [owner, hits]] }
+        }.compact
+      end
+    end
+  end
+end