path_coverage 0.0.1 → 0.0.2

data/lib/path_coverage/manifest.rb

@@ -0,0 +1,177 @@
+require 'prism'
+require_relative 'condition'
+require_relative 'manifest_choices'
+require_relative 'site'
+
+module PathCoverage
+  # Finds every condition site in source without running it: each
+  # outermost &&, ||, and or or, each ternary and each if, with the
+  # conditions nested in it.
+  module Manifest
+    # { site => Condition } for each site in source.
+    def self.sites(source, path)
+      collector = ConditionSites.new(path)
+      Prism.parse(source).value.accept(collector)
+      collector.sites
+    end
+
+    # The source and sites of the covered file at full_path.
+    def self.parse(full_path, config)
+      source = File.read(full_path)
+      { source:, sites: sites(source, config.relative(full_path)) }
+    end
+
+    # True for a call to a named method with arguments and no
+    # parentheses, eg `id.include? 'N'`, but not `id.size == 6`;
+    # such a call is no bare argument, so a rewrite wrapping it
+    # in another call must parenthesise it.
+    def self.command?(node)
+      node.type == :call_node && node.arguments &&
+        node.opening_loc.nil? && node.name.match?(/\A[a-z_]/i)
+    end
+
+    # Literals and lambdas, whose value is truthy by their form;
+    # a constant is not among them, as it can hold nil or false.
+    TRUTHY_TYPES = %i[
+      string_node integer_node symbol_node array_node hash_node
+      true_node lambda_node
+    ].freeze
+    FALSY_TYPES = %i[nil_node false_node].freeze
+
+    # Ruby raises TypeError on assigning nil or false to these.
+    TRUTHY_GLOBALS = %i[$stdout $stderr].freeze
+
+    # The one outcome a leaf can have, eg :truthy for `Clock.new`
+    # or a literal, :falsy for `nil`; nil for a leaf that can
+    # have either.
+    def self.fixed_outcome(node)
+      return :falsy if FALSY_TYPES.include?(node.type)
+
+      :truthy if truthy_only?(node)
+    end
+
+    # True for a leaf that can never be falsy.
+    def self.truthy_only?(node)
+      TRUTHY_TYPES.include?(node.type) || new_call?(node) ||
+        truthy_global?(node)
+    end
+
+    # True for a call to new, eg `Clock.new`.
+    def self.new_call?(node)
+      node.type == :call_node && node.name == :new
+    end
+
+    # True for $stdout or $stderr, which can never be falsy.
+    def self.truthy_global?(node)
+      node.type == :global_variable_read_node &&
+        TRUTHY_GLOBALS.include?(node.name)
+    end
+
+    # Collects each site and its Condition.
+    class ConditionSites < Prism::Visitor
+      include ManifestChoices
+
+      # Starts with no sites found.
+      def initialize(path)
+        @path = path
+        @sites = {}
+        @notes = nil
+        super()
+      end
+
+      # The sites found so far.
+      attr_reader :sites
+
+      OPERATOR_TYPES = %i[and_node or_node].freeze
+
+      # Notes an && or and site.
+      def visit_and_node(node)
+        add_site(node)
+      end
+
+      # Notes an || or or site.
+      def visit_or_node(node)
+        add_site(node)
+      end
+
+      # Notes a ternary or an if site, its arms included; a
+      # modifier if is no site itself.
+      def visit_if_node(node)
+        return super if modifier?(node)
+
+        add_site(node)
+      end
+
+      # Notes node as a site. It claims its place first, so a
+      # site found inside one of its leaves follows it, keeping
+      # the sites in source order.
+      def add_site(node)
+        site = Site.of(@path, node)
+        @sites[site] = nil
+        outer = @notes
+        @notes = { commands: [], fixed: {} }
+        condition = condition_of(node)
+        @sites[site] = condition.with(**@notes)
+        @notes = outer
+      end
+
+      # node as a Condition, operands and all, named by its
+      # operator as written; a ternary is named ?: and an if is
+      # named if, their operands being a predicate and arms.
+      def condition_of(node)
+        return choice_of(node) if node.type == :if_node
+
+        Condition.new(
+          operator: node.operator, operands: operands_of(node),
+          extent: extent_of(node)
+        )
+      end
+
+      # node's operands: a chain of the same operator flattened
+      # into one list, the other operator nested as a Condition,
+      # anything else a leaf's byte range.
+      def operands_of(node)
+        [node.left, node.right].flat_map do |written|
+          operand = grouped(written)
+          next operands_of(operand) if operand.type == node.type
+          next [condition_of(operand)] if operator?(operand)
+
+          [leaf(operand)]
+        end
+      end
+
+      # The byte range of node as written.
+      def extent_of(node)
+        loc = node.location
+        loc.start_offset...loc.end_offset
+      end
+
+      # True for an &&, ||, and or or node.
+      def operator?(node)
+        OPERATOR_TYPES.include?(node.type)
+      end
+
+      # The byte range of a leaf operand, once any site inside
+      # it is noted too, and the range noted among its site's
+      # commands and fixed leaves where it is one.
+      def leaf(operand)
+        operand.accept(self)
+        loc = operand.location
+        range = loc.start_offset...loc.end_offset
+        @notes[:commands] << range if Manifest.command?(operand)
+        outcome = Manifest.fixed_outcome(operand)
+        @notes[:fixed][range] = outcome if outcome
+        range
+      end
+
+      # The one statement inside a parenthesised operand, or the
+      # operand itself.
+      def grouped(operand)
+        return operand unless operand.type == :parentheses_node
+
+        statements = operand.body&.body || []
+        statements.size == 1 ? statements.first : operand
+      end
+    end
+  end
+end

data/lib/path_coverage/manifest_choices.rb

@@ -0,0 +1,113 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The part of the manifest's visitor that builds the sites
+  # whose predicate picks an arm: a ternary, named ?:, and an
+  # if, named if. It relies on its includer's condition_of,
+  # extent_of, grouped, leaf and operator?.
+  module ManifestChoices
+    # True for a modifier if, eg `return if done?`, whose
+    # statement comes before its if keyword.
+    def modifier?(node)
+      return false if ternary?(node) || node.statements.nil?
+
+      node.statements.location.start_offset <
+        node.if_keyword_loc.start_offset
+    end
+
+    # A ternary or an if as a Condition.
+    def choice_of(node)
+      ternary?(node) ? ternary_condition(node) : if_condition(node)
+    end
+
+    # A ternary as a Condition, its extent the whole of it.
+    def ternary_condition(node)
+      Condition.new(
+        operator: '?:', operands: ternary_of(node),
+        extent: extent_of(node)
+      )
+    end
+
+    # An if as a Condition, its extent its if keyword to the end
+    # of its predicate, as its arms are statements, not part of
+    # the expression.
+    def if_condition(node)
+      start = node.if_keyword_loc.start_offset
+      Condition.new(
+        operator: 'if', operands: if_of(node),
+        extent: start...node.predicate.location.end_offset
+      )
+    end
+
+    # An if's predicate, then its then arm and, when it has
+    # one, its else arm.
+    def if_of(node)
+      [
+        predicate_of(node),
+        statement_arm(:then, node.statements),
+        *else_arm(node.subsequent)
+      ]
+    end
+
+    # An if's arm, statements its code, which never folds into
+    # the if's site; any site inside it is a site of its own.
+    # An arm with no statements has no extent.
+    def statement_arm(kind, statements)
+      statements&.accept(self)
+      extent = statements && extent_of(statements)
+      Arm.new(kind:, extent:, body: nil)
+    end
+
+    # An if's else arm, from subsequent: an else's statements,
+    # or an elsif, which is a site of its own; none for none.
+    def else_arm(subsequent)
+      return [] if subsequent.nil?
+      if subsequent.type == :else_node
+        return [statement_arm(:else, subsequent.statements)]
+      end
+
+      subsequent.accept(self)
+      extent = extent_of(subsequent)
+      [Arm.new(kind: :else, extent:, body: nil)]
+    end
+
+    # A ternary's predicate, then its then and else arms.
+    def ternary_of(node)
+      [
+        predicate_of(node),
+        arm_of(:then, node.statements),
+        arm_of(:else, node.subsequent.statements)
+      ]
+    end
+
+    # One arm of a ternary, statements its code: a condition
+    # folds in as its body, being part of the one expression;
+    # any site inside a plain arm is a site of its own.
+    def arm_of(kind, statements)
+      written = grouped(statements.body.first)
+      body = condition_of(written) if foldable?(written)
+      statements.accept(self) if body.nil?
+      Arm.new(kind:, extent: extent_of(statements), body:)
+    end
+
+    # True for a condition that folds into a ternary's site:
+    # an &&, ||, and, or, or a ternary.
+    def foldable?(node)
+      operator?(node) || ternary?(node)
+    end
+
+    # True for a ternary, an if with no if keyword.
+    def ternary?(node)
+      node.type == :if_node && node.if_keyword_loc.nil?
+    end
+
+    # A ternary's or an if's predicate as its operand: an && or
+    # || nested as a Condition, anything else a leaf.
+    def predicate_of(node)
+      predicate = node.predicate
+      return condition_of(predicate) if operator?(predicate)
+
+      leaf(predicate)
+    end
+  end
+end

data/lib/path_coverage/merge.rb

@@ -0,0 +1,35 @@
+module PathCoverage
+  # Combines the operands of several runs of the same source.
+  module Merge
+    # One operands hash, as Result#operands gives them, whose
+    # counts are the sums of every run's.
+    def self.operands(runs)
+      runs.reduce do |total, run|
+        total.merge(run) do |_site, mine, theirs|
+          mine.zip(theirs).map { |a, b| sum(a, b) }
+        end
+      end
+    end
+
+    # One site paths hash, as Result#paths gives them, each
+    # path's count the sum of every run's; runs of the same
+    # source list the same paths in the same order.
+    def self.paths(runs)
+      runs.reduce do |total, run|
+        total.merge(run) do |_site, mine, theirs|
+          mine.zip(theirs).map do |a, b|
+            { path: a[:path], count: a[:count] + b[:count] }
+          end
+        end
+      end
+    end
+
+    # One operand's counts from two runs, added; a fixed leaf's
+    # only comes from the source, so either run's will do.
+    def self.sum(mine, theirs)
+      mine.merge(theirs) do |key, a, b|
+        key == :only ? a : a + b
+      end
+    end
+  end
+end

data/lib/path_coverage/path_gaps.rb

@@ -0,0 +1,41 @@
+module PathCoverage
+  # The terminal worklist for paths: one line per path a method
+  # never took, and nothing for a method that took them all.
+  module PathGaps
+    OUTCOMES = [true, false].freeze
+
+    # The gap lines of methods, as PathManifest.methods gives
+    # them, for the paths the recorder counted, eg
+    # "k.rb:1:0 fee path never taken: line 3 true, line 6 true".
+    def self.lines(methods, paths)
+      methods.flat_map do |site, method|
+        taken = paths.fetch(site, {})
+        every = possible(method.decisions)
+        every.reject { |path| taken.key?(path) }.map do |path|
+          gap = "#{site} #{method.name} path never taken"
+          "#{gap}: #{steps(method, path)}"
+        end
+      end
+    end
+
+    # Every path through decisions, true before false at each:
+    # one taking a decision's leaving outcome ends there.
+    def self.possible(decisions)
+      return [[]] if decisions.empty?
+
+      first, *rest = decisions
+      OUTCOMES.flat_map do |outcome|
+        next [[outcome]] if outcome == first.exits
+
+        possible(rest).map { |tail| [outcome] + tail }
+      end
+    end
+
+    # path's outcomes, each named by its decision's line.
+    def self.steps(method, path)
+      path.each_with_index.map do |outcome, index|
+        "line #{method.decisions[index].line} #{outcome}"
+      end.join(', ')
+    end
+  end
+end

data/lib/path_coverage/path_manifest.rb

@@ -0,0 +1,110 @@
+require 'prism'
+require_relative 'manifest'
+require_relative 'site'
+
+module PathCoverage
+  # One if a method's path passes: its line, the byte range of
+  # its predicate, and whether that predicate is a command call.
+  # exits is the outcome whose arm always leaves the method,
+  # ending the path there, or nil when neither arm does.
+  Decision = Data.define(:line, :range, :command, :exits) do
+    # A decision with no arm that leaves by default.
+    def initialize(line:, range:, command:, exits: nil)
+      super
+    end
+  end
+
+  # A method whose calls each take one path through its
+  # decisions, in source order. entry is the byte offset of its
+  # first decision's statement, where each call's path starts.
+  PathMethod = Data.define(:name, :entry, :decisions)
+
+  # Finds, without running it, the decisions of each method in
+  # source whose paths are to be counted.
+  module PathManifest
+    # { def site => PathMethod } for each def in source.
+    def self.methods(source, path)
+      collector = PathMethods.new(path)
+      Prism.parse(source).value.accept(collector)
+      collector.methods
+    end
+
+    # Collects each def and the ifs at the top level of its body.
+    class PathMethods < Prism::Visitor
+      # Starts with no methods found.
+      def initialize(path)
+        @path = path
+        @methods = {}
+        super()
+      end
+
+      # The methods found so far.
+      attr_reader :methods
+
+      # Notes node's top-level ifs as its decisions, when it has
+      # at least two (with fewer its paths are its branches),
+      # then any def inside it, each a method of its own.
+      def visit_def_node(node)
+        ifs = statements_of(node.body).select do |statement|
+          statement.type == :if_node
+        end
+        note(node, ifs) if ifs.size >= 2
+        super
+      end
+
+      # Notes node as a method whose decisions are ifs.
+      def note(node, ifs)
+        @methods[Site.of(@path, node)] = PathMethod.new(
+          name: node.name,
+          entry: ifs.first.location.start_offset,
+          decisions: ifs.map { |statement| decision(statement) }
+        )
+      end
+
+      # The top-level statements of a def's body: those before
+      # any rescue, and none for an empty or endless def.
+      def statements_of(body)
+        body = body.statements if body&.type == :begin_node
+        body&.type == :statements_node ? body.body : []
+      end
+
+      # The Decision of an if statement.
+      def decision(statement)
+        predicate = statement.predicate
+        loc = predicate.location
+        Decision.new(
+          line: loc.start_line,
+          range: loc.start_offset...loc.end_offset,
+          command: Manifest.command?(predicate) || false,
+          exits: exits(statement)
+        )
+      end
+
+      LEAVING_CALLS = %i[fail raise].freeze
+
+      # The outcome of an if statement whose arm always leaves
+      # the method: true for its then arm, false for its else
+      # arm, nil for neither.
+      def exits(statement)
+        return true if leaves?(statement.statements)
+
+        otherwise = statement.subsequent
+        false if otherwise&.type == :else_node &&
+                 leaves?(otherwise.statements)
+      end
+
+      # True when the last of statements is a return, or a
+      # fail or raise of the method's own; false for an empty
+      # arm, which has no statements.
+      def leaves?(statements)
+        return false if statements.nil?
+
+        last = statements.body.last
+        return true if last.type == :return_node
+
+        last.type == :call_node && last.receiver.nil? &&
+          LEAVING_CALLS.include?(last.name)
+      end
+    end
+  end
+end

data/lib/path_coverage/paths_report.rb

@@ -0,0 +1,55 @@
+module PathCoverage
+  # What the reports say about each site's paths beyond their
+  # counts, worked out from each covered file's source: where
+  # each leaf is, and what it says.
+  module PathsReport
+    # { site => { leaves:, taken: } }: taken is each path and
+    # its count, as Result#paths gives them, and leaves each
+    # leaf's ["line:column", "line:column"] span, so a tool can
+    # recover each leaf exactly. files is { full path =>
+    # {source:, sites:} }.
+    def self.of(site_paths, files)
+      spans = leaf_spans(files)
+      site_paths.to_h do |site, taken|
+        [site, { leaves: spans.fetch(site), taken: }]
+      end
+    end
+
+    # { site => [each leaf's source text] } for every site in
+    # files.
+    def self.texts(files)
+      each_site(files) do |source, condition|
+        condition.leaves.map { |range| source.byteslice(range) }
+      end
+    end
+
+    # { site => [each leaf's span] } for every site in files.
+    def self.leaf_spans(files)
+      each_site(files) do |source, condition|
+        condition.leaves.map do |range|
+          [at(source, range.begin), at(source, range.end)]
+        end
+      end
+    end
+
+    # { site => what the block makes of its file's source and
+    # its condition } for every site in files.
+    def self.each_site(files)
+      files.values.each_with_object({}) do |parsed, all|
+        parsed[:sites].each do |site, condition|
+          all[site] = yield(parsed[:source], condition)
+        end
+      end
+    end
+
+    # "line:column" of a byte offset in source, the line from
+    # 1 and the column, in characters, from 0, as site names
+    # count them.
+    def self.at(source, offset)
+      before = source.byteslice(0, offset)
+      line = before.count("\n") + 1
+      start = before.rindex("\n")
+      "#{line}:#{before.length - (start ? start + 1 : 0)}"
+    end
+  end
+end

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,99 @@
+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
+  end
+end