path_coverage 0.0.1 → 0.1.0

data/lib/path_coverage/post.rb

@@ -0,0 +1,26 @@
+require 'net/http'
+require_relative 'json_writer'
+
+module PathCoverage
+  # The :post reporter: sends the JSON report to a collector,
+  # for runs whose own files are thrown away, eg a failing
+  # docker build step.
+  module Post
+    # POSTs operands and paths, as the JSON report, to url,
+    # never through an http_proxy, which could not reach a
+    # collector local to the run. A collector that cannot be
+    # reached, or does not answer within a second, is passed
+    # over in silence: the run's own output and exit status
+    # must stay as they are.
+    def self.deliver(operands, url, paths = {})
+      uri = URI(url)
+      http = Net::HTTP.new(uri.host, uri.port, nil)
+      http.open_timeout = http.read_timeout = 1
+      headers = { 'Content-Type' => 'application/json' }
+      body = JsonWriter.json(operands, paths)
+      http.post(uri.path, body, headers)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/path_coverage/recorder.rb

@@ -0,0 +1,182 @@
+require_relative 'condition'
+
+module PathCoverage
+  # Records the outcome of each instrumented operand.
+  class Recorder
+    # One call's way through its method: the outcome of each
+    # decision made so far, of the number of decisions its
+    # method has.
+    Path = Struct.new(:site, :decisions, :outcomes)
+
+    # One evaluation's way through its site: the outcome of
+    # each leaf, nil for one not yet, or never, reached.
+    Trail = Struct.new(:site, :outcomes)
+
+    # Starts with no outcomes, paths or site paths counted.
+    def initialize
+      @counts = Hash.new do |counts, key|
+        counts[key] = { truthy: 0, falsy: 0 }
+      end
+      @paths = Hash.new do |paths, site|
+        paths[site] = Hash.new(0)
+      end
+      @site_paths = Hash.new do |site_paths, site|
+        site_paths[site] = Hash.new(0)
+      end
+      @trails_key = :"path_coverage_trails_#{object_id}"
+    end
+
+    # The stack of site's evaluations under way in the current
+    # thread (fiber), innermost last, so another thread's never
+    # mix with its.
+    def trails(site)
+      stacks = Thread.current[@trails_key] ||=
+        Hash.new { |all, key| all[key] = [] }
+      stacks[site]
+    end
+
+    # { site => { [outcome, ...] => evaluations } } for every
+    # evaluation of a site entered and left so far.
+    attr_reader :site_paths
+
+    # Starts an evaluation of site, which has size leaves, as
+    # the trail its leaves' records fill in.
+    def enter(site, size)
+      trail = Trail.new(site, Array.new(size))
+      trails(site).push(trail)
+      trail
+    end
+
+    # Ends trail's evaluation, counting its path, and returns
+    # value, the site's, unchanged. An evaluation of the same
+    # site still entered above trail, as one that raised
+    # leaves, took trail's later outcomes, so trail's path is
+    # not counted; the stack is cleared down to trail either
+    # way.
+    def leave(trail, value)
+      stack = trails(trail.site)
+      clean = stack.last.equal?(trail)
+      nil until stack.empty? || stack.pop.equal?(trail)
+      @site_paths[trail.site][trail.outcomes] += 1 if clean
+      value
+    end
+
+    # { method site => { [outcome, ...] => calls } } for every
+    # path taken all the way through so far.
+    attr_reader :paths
+
+    # A new call's path through the method at site, which has
+    # size decisions.
+    def path(site, size)
+      Path.new(site, size, [])
+    end
+
+    # Notes value's outcome as path's index-th decision, counts
+    # path once that is its last, or once it is exits, the
+    # outcome whose arm leaves the method, and returns value
+    # unchanged.
+    def decide(path, index, value, exits = nil)
+      outcome = value ? true : false
+      path.outcomes[index] = outcome
+      last = index == path.decisions - 1 || outcome == exits
+      @paths[path.site][path.outcomes] += 1 if last
+      value
+    end
+
+    # The truthy and falsy counts of every operand recorded so
+    # far, keyed by [site, index]; an operand that never ran
+    # has no entry.
+    attr_reader :counts
+
+    # Counts value's outcome and returns it unchanged, so the
+    # condition around it behaves exactly as uninstrumented.
+    def record(site, index, value)
+      outcome = value ? :truthy : :falsy
+      @counts[[site, index]][outcome] += 1
+      trail = trails(site).last
+      trail.outcomes[index] = outcome == :truthy if trail
+      value
+    end
+
+    # A stand-in for a case's index-th pattern of total: the
+    # case matches its subject against the stand-in, which
+    # matches it against the pattern, once, as the case would
+    # have.
+    WhenMatch = Struct.new(
+      :recorder, :site, :index, :total, :pattern
+    ) do
+      # Whether pattern matches subject, exactly as pattern says,
+      # noted on the site's path.
+      def ===(subject)
+        recorder.matched(site, index, total, pattern === subject)
+      end
+    end
+
+    # The stand-in for pattern, the index-th of size in the case
+    # at site.
+    def when_match(site, index, size, pattern)
+      WhenMatch.new(self, site, index, size, pattern)
+    end
+
+    # Notes whether the index-th of size patterns matched, the
+    # first entering the case's site, and a match or the last
+    # leaving it, as no more patterns are then tried; returns
+    # matched unchanged.
+    def matched(site, index, size, matched)
+      enter(site, size) if index.zero?
+      record(site, index, matched)
+      last = matched || index == size - 1
+      leave(trails(site).last, matched) if last
+      matched
+    end
+
+    # Starts an evaluation of a stop-early block method's call
+    # at site, its block not yet called with any item.
+    def enter_items(site)
+      trail = enter(site, 2)
+      trail.outcomes[0] = ITEMS[0]
+      trail
+    end
+
+    # Notes value, the block's answer, as its last, and one more
+    # item it was called with; returns value unchanged. A block
+    # called where its call was not entered, eg in another
+    # fiber, is counted but noted on no path.
+    def item(site, value)
+      trail = trails(site).last
+      one_more(trail) if trail
+      record(site, 1, value)
+    end
+
+    # Notes value, the block's answer for one more item, among
+    # all its answers so far: all true, all false, or both;
+    # returns value unchanged. A block called where its call
+    # was not entered is counted but noted on no path.
+    def answer(site, value)
+      trail = trails(site).last
+      if trail
+        one_more(trail)
+        now = value ? ANSWERS[0] : ANSWERS[1]
+        same = [nil, now].include?(trail.outcomes[1])
+        trail.outcomes[1] = same ? now : ANSWERS[2]
+      end
+      @counts[[site, 1]][value ? :truthy : :falsy] += 1
+      value
+    end
+
+    # Notes on trail one more item its block was called with.
+    def one_more(trail)
+      called = ITEMS.index(trail.outcomes[0]) + 1
+      trail.outcomes[0] = ITEMS[[called, 2].min]
+    end
+
+    # Ends a block method's call, counting its receiver truthy
+    # when its block was called, falsy when not, and its path;
+    # returns value, the call's, unchanged.
+    def leave_items(trail, value)
+      called = trail.outcomes[0] != ITEMS[0]
+      @counts[[trail.site, 0]][called ? :truthy : :falsy] += 1
+      leave(trail, value)
+    end
+  end
+end

data/lib/path_coverage/render.rb

@@ -0,0 +1,92 @@
+require 'json'
+require_relative 'gaps'
+require_relative 'html_report'
+require_relative 'manifest'
+require_relative 'merge'
+require_relative 'paths_report'
+require_relative 'post'
+require_relative 'site_paths'
+
+module PathCoverage
+  # The reporters, run from operands alone: needing nothing the
+  # run recorded beyond them, they can run in another process.
+  module Render
+    # Runs each reporter chosen in config. operands and
+    # site_paths are as Result gives them; files is { full path
+    # => {source:, sites:} } for each covered file.
+    def self.run(operands, files, config, paths = nil, site_paths: {})
+      site_paths = every_site(site_paths, files)
+      reporters = config.reporters
+      gaps(operands, files, site_paths) if reporters.include?(:gaps)
+      if reporters.include?(:html)
+        HtmlReport.write(operands, files, config, paths, site_paths:)
+      end
+      return unless reporters.include?(:post)
+
+      report = PathsReport.of(site_paths, files)
+      Post.deliver(operands, config.collector_url, report)
+    end
+
+    # site_paths with every site in files that it lacks, eg
+    # from a JSON report with no paths, given each possible
+    # path at a count of zero: unable to say which paths such
+    # a site took, the report claims none.
+    def self.every_site(site_paths, files)
+      none = files.values.each_with_object({}) do |parsed, all|
+        parsed[:sites].each do |site, condition|
+          all[site] = SitePaths.possible(condition).map do |path|
+            { path:, count: 0 }
+          end
+        end
+      end
+      none.merge(site_paths)
+    end
+
+    # Prints the gap lines: each path a site never took, each
+    # leaf named by its text in files.
+    def self.gaps(operands, files, site_paths)
+      texts = PathsReport.texts(files)
+      lines = Gaps.lines(operands, paths: site_paths, texts:)
+      lines.each { |line| puts line }
+    end
+
+    # Runs the reporters chosen in config from the JSON reports
+    # at paths, their counts merged, parsing each covered file
+    # afresh. paths is config.json_path alone by default.
+    def self.from_json(config, paths = [config.json_path])
+      operands = Merge.operands(paths.map { |path| read(path) })
+      site_paths = Merge.paths(paths.map { |path| paths_of(path) })
+      files = config.files.to_h do |path|
+        [path, Manifest.parse(path, config)]
+      end
+      run(operands, files, config, site_paths:)
+    end
+
+    # The site paths of the JSON report at path, as
+    # Result#paths gives them; none for a report that has none.
+    def self.paths_of(path)
+      json = JSON.parse(File.read(path))
+      json.fetch('paths', {}).transform_values do |site|
+        site['taken'].map do |each|
+          { path: each['path'], count: each['count'] }
+        end
+      end
+    end
+
+    # The operands of the JSON report at path.
+    def self.read(path)
+      json = JSON.parse(File.read(path))
+      json['sites'].transform_values do |leaves|
+        leaves.map { |leaf| counts(leaf) }
+      end
+    end
+
+    # One operand's counts as JSON holds them, with the keys,
+    # and any only: value, as the symbols Result#operands uses.
+    def self.counts(leaf)
+      counts = { truthy: leaf['truthy'], falsy: leaf['falsy'] }
+      only = leaf['only']
+      only ? counts.merge(only: only.to_sym) : counts
+    end
+  end
+end

data/lib/path_coverage/result.rb

@@ -0,0 +1,59 @@
+require_relative 'site_paths'
+
+module PathCoverage
+  # What a run found: every site the manifest knows of, with
+  # the counts its operands were recorded with. Every
+  # reporter builds on this.
+  class Result
+    NEVER_RAN = { truthy: 0, falsy: 0 }.freeze
+
+    # sites is { site => Condition }, from the manifest;
+    # counts is { [site, index] => counts } and site_paths is
+    # { site => { path => evaluations } }, both from the
+    # recorder.
+    def initialize(sites, counts, site_paths = {})
+      @sites = sites
+      @counts = counts
+      @site_paths = site_paths
+    end
+
+    # { site => [{ path:, count: }, ...] }: every possible path
+    # of each site, as SitePaths gives them, with the number of
+    # evaluations that took it, zero for one never taken.
+    def paths
+      @sites.to_h do |site, condition|
+        taken = @site_paths.fetch(site, {})
+        all = SitePaths.possible(condition).map do |path|
+          { path:, count: taken.fetch(path, 0) }
+        end
+        [site, all]
+      end
+    end
+
+    # { site => [counts of operand 0, counts of operand 1, ...] },
+    # with zero counts for an operand that never ran, and
+    # only: naming the one outcome a fixed leaf can have.
+    def operands
+      @sites.to_h do |site, condition|
+        leaves = condition.leaves.each_with_index.map do |range, i|
+          leaf(site, condition, range, i)
+        end
+        [site, leaves]
+      end
+    end
+
+    private
+
+    # The counts of one leaf, with only: when it is fixed.
+    def leaf(site, condition, range, index)
+      counts = counts_of(site, index)
+      only = condition.fixed[range]
+      only ? counts.merge(only:) : counts
+    end
+
+    # The recorded counts of one operand, or zeros.
+    def counts_of(site, index)
+      @counts.fetch([site, index], NEVER_RAN)
+    end
+  end
+end

data/lib/path_coverage/rewriter.rb

@@ -0,0 +1,166 @@
+require_relative 'condition'
+
+module PathCoverage
+  # Instruments source text so that each leaf operand records its
+  # outcome when the code runs. It inserts text at the byte
+  # ranges the manifest found, and never parses.
+  module Rewriter
+    PATH_NAME = '__path_coverage_path'.freeze
+
+    # Returns source with each operand in sites wrapped in a
+    # record call, each site as a whole in a leave call that
+    # enters it first, and each method in methods starting a
+    # path that its decisions are wrapped in decide calls to add
+    # to. Only text is inserted, never a newline, so backtrace
+    # line numbers still match the file on disk.
+    def self.rewrite(source, sites, methods = {})
+      inserts = sites.flat_map do |site, condition|
+        site_inserts(site, condition)
+      end
+      apply(source.dup, inserts + path_inserts(methods))
+    end
+
+    # The inserts for one site, by its kind: a case's patterns'
+    # stand-ins, a block method's call and block, or any other
+    # site's leaves' records and its leave.
+    def self.site_inserts(site, condition)
+      kind = condition.operator
+      return case_inserts(site, condition) if kind == 'case'
+
+      blocks = BLOCK_PATHS.key?(kind)
+      return block_inserts(site, condition) if blocks
+
+      record_inserts(site, condition) + trail_inserts(site, condition)
+    end
+
+    # The inserts that wrap a block method's call whole in a
+    # leave_items call that enters it first, inside any leave of
+    # a site it is the predicate of, and its block's expression,
+    # outside any site's leave there, in an item call, noting its
+    # last answer, or for a method that calls it with every item
+    # an answer call, noting every answer.
+    def self.block_inserts(site, condition)
+      _receiver, body = condition.leaves
+      enter = "PathCoverage.enter_items(#{site.inspect})"
+      call = "PathCoverage.leave_items(#{enter}, "
+      every = EVERY_ITEM.include?(condition.operator)
+      noter = every ? 'answer' : 'item'
+      item = "PathCoverage.#{noter}(#{site.inspect}, "
+      command = condition.commands.include?(body)
+      wrap(call, condition.extent, false, 0.5) +
+        wrap(item, body, command, 1.5)
+    end
+
+    # The inserts that wrap each pattern of a case site in a
+    # when_match call, its stand-in, which enters and leaves the
+    # site itself, as the case tries its patterns one by one.
+    def self.case_inserts(site, condition)
+      size = condition.leaves.size
+      condition.leaves.each_with_index.flat_map do |range, index|
+        call = "PathCoverage.when_match(#{site.inspect}, " \
+               "#{index}, #{size}, "
+        wrap(call, range, false, 0)
+      end
+    end
+
+    # The inserts that wrap each of site's leaves in a record
+    # call, innermost of all.
+    def self.record_inserts(site, condition)
+      condition.leaves.each_with_index.flat_map do |range, index|
+        command = condition.commands.include?(range)
+        wrap(record_call(site, index), range, command, 0)
+      end
+    end
+
+    WORD_OPERATORS = %w[and or].freeze
+
+    # The inserts that wrap site as a whole in a leave call,
+    # outside its leaves' record calls, whose first argument
+    # enters the site before any leaf runs, so each evaluation
+    # fills in a trail of its own. An and or or is held in
+    # parentheses, being, like a command call, no bare argument.
+    def self.trail_inserts(site, condition)
+      enter = "PathCoverage.enter(#{site.inspect}, " \
+              "#{condition.leaves.size})"
+      call = "PathCoverage.leave(#{enter}, "
+      wrapped = trailed(condition)
+      nested = wrapped.is_a?(Condition)
+      word = nested && WORD_OPERATORS.include?(wrapped.operator)
+      wrap(call, nested ? wrapped.extent : wrapped, word, 1)
+    end
+
+    # What a site's leave call wraps: an if's or an unless's
+    # predicate, a leaf's byte range or a nested Condition, as
+    # its path is decided there and its arms are statements that
+    # may return or raise; any other site as a whole.
+    def self.trailed(condition)
+      unless STATEMENT_CHOICES.include?(condition.operator)
+        return condition
+      end
+
+      condition.operands.first
+    end
+
+    # The opening of the record call around operand index of
+    # the site.
+    def self.record_call(site, index)
+      "PathCoverage.record(#{site.inspect}, #{index}, "
+    end
+
+    # The inserts that start each method's path at its entry,
+    # outermost of all there, and wrap each of its decisions'
+    # predicates in a decide call, outside any record or
+    # outcome call.
+    def self.path_inserts(methods)
+      methods.flat_map do |site, method|
+        decisions = method.decisions
+        start = path_start(site, decisions.size)
+        decides = decisions.each_with_index.flat_map do |decision, i|
+          call = "PathCoverage.decide(#{PATH_NAME}, #{i}, "
+          tail = decision.exits.nil? ? '' : ", #{decision.exits}"
+          wrap(call, decision.range, decision.command, 2, tail)
+        end
+        [[method.entry, start, 3]] + decides
+      end
+    end
+
+    # The statement that starts a call's path through the
+    # method at site, which has size decisions.
+    def self.path_start(site, size)
+      call = "PathCoverage.path(#{site.inspect}, #{size})"
+      "#{PATH_NAME} = #{call}; "
+    end
+
+    # The two inserts that wrap the code at range in call, of
+    # rank among inserts at the same offset, with tail as the
+    # call's further arguments. A command call is parenthesised,
+    # as it is no bare argument; nothing else is, since
+    # parentheses make a statement, which gives its line a
+    # line-coverage count of its own.
+    def self.wrap(call, range, command, rank, tail = '')
+      open, close = command ? ['(', ")#{tail})"] : ['', "#{tail})"]
+      [
+        [range.begin, call + open, rank],
+        [range.end, close, rank, :close]
+      ]
+    end
+
+    # Splices each [offset, text, rank] insert into source, last
+    # offset first so earlier offsets stay valid; a closing
+    # insert is marked :close. Text spliced in later at an
+    # offset lands before text already there, so at one offset
+    # opening inserts go in lowest rank first, leaving the
+    # highest outermost, then closing ones highest rank first,
+    # so the innermost call closes first and each tail stays
+    # with its own call.
+    def self.apply(source, inserts)
+      sorted = inserts.sort_by do |offset, _, rank, close|
+        close ? [-offset, 1, -rank] : [-offset, 0, rank]
+      end
+      sorted.each do |offset, text, _|
+        source.bytesplice(offset, 0, text)
+      end
+      source
+    end
+  end
+end

data/lib/path_coverage/site.rb

@@ -0,0 +1,16 @@
+module PathCoverage
+  # Names a condition by where it starts in its file, so the
+  # rewriter and the manifest agree on which site is which.
+  module Site
+    # "path:line:column" of node, eg "k.rb:2:2".
+    def self.of(path, node)
+      at(path, node.location)
+    end
+
+    # "path:line:column" of where loc starts, eg an if's keyword,
+    # which a modifier if's statement comes before.
+    def self.at(path, loc)
+      "#{path}:#{loc.start_line}:#{loc.start_column}"
+    end
+  end
+end

data/lib/path_coverage/site_paths.rb

@@ -0,0 +1,86 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The paths an evaluation of a site can take, worked out
+  # from its condition alone: the outcome of each leaf, in leaf
+  # order, nil for a leaf that evaluation never reaches.
+  module SitePaths
+    # Every possible path through site's condition, true
+    # before false; a stop-early block method's are fixed by its
+    # shape alone.
+    def self.possible(site)
+      shape = BLOCK_PATHS[site.operator]
+      return shape if shape
+
+      walk(site, site.fixed).map do |outcomes, _value|
+        site.leaves.map { |range| outcomes[range] }
+      end
+    end
+
+    # The outcome of an operand on which each operator goes on
+    # to its next operand; any other ends the chain there. A
+    # when's patterns, and a case's whens, stop at a match.
+    CONTINUES_ON = {
+      '&&' => true, 'and' => true, '||' => false, 'or' => false,
+      'when' => false, 'case' => false
+    }.freeze
+
+    # [[{ leaf range => outcome }, value], ...] for each way
+    # node can be evaluated, value being the outcome of node as
+    # a whole; fixed is the site's { leaf range => its one
+    # outcome }. A case is the chain of its whens' conditions.
+    def self.walk(node, fixed)
+      return leaf(node, fixed) unless node.is_a?(Condition)
+      return ternary(node, fixed) if CHOICES.include?(node.operator)
+
+      if node.operator == 'case'
+        whens = node.operands.filter_map(&:body)
+        return chain(node.with(operands: whens), fixed)
+      end
+
+      chain(node, fixed)
+    end
+
+    # The ways a chain of one operator can be evaluated: each
+    # way of its first operand, going on to the next while each
+    # outcome is the one its operator goes on with.
+    def self.chain(node, fixed)
+      first, *rest = node.operands
+      goes_on = CONTINUES_ON.fetch(node.operator)
+      rest.reduce(walk(first, fixed)) do |ways, operand|
+        ways.flat_map do |outcomes, value|
+          next [[outcomes, value]] unless value == goes_on
+
+          walk(operand, fixed).map do |more, after|
+            [outcomes.merge(more), after]
+          end
+        end
+      end
+    end
+
+    # The ways a ternary, an if or an unless can be evaluated:
+    # each way of its predicate, then each way of the condition
+    # the arm it picks is, if that arm is one; one with no else
+    # arm picks none. Its value is that of no choice, so is nil.
+    def self.ternary(node, fixed)
+      predicate, then_arm, else_arm = node.operands
+      then_on = THEN_ON[node.operator]
+      walk(predicate, fixed).flat_map do |outcomes, value|
+        body = (value == then_on ? then_arm : else_arm)&.body
+        next [[outcomes, nil]] if body.nil?
+
+        walk(body, fixed).map do |more, _|
+          [outcomes.merge(more), nil]
+        end
+      end
+    end
+
+    # The ways a leaf can be evaluated: true, then false, or
+    # its one outcome alone when it is fixed.
+    def self.leaf(range, fixed)
+      only = fixed[range]
+      outcomes = only ? [only == :truthy] : [true, false]
+      outcomes.map { |outcome| [{ range => outcome }, outcome] }
+    end
+  end
+end