path_coverage 0.0.1 → 0.1.0

data/lib/path_coverage/manifest.rb

@@ -0,0 +1,205 @@
+require 'prism'
+require_relative 'condition'
+require_relative 'manifest_blocks'
+require_relative 'manifest_case'
+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, if, unless and case
+  # with a subject, 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 ManifestBlocks
+      include ManifestCase
+      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, a modifier if included,
+      # its arms included.
+      def visit_if_node(node)
+        add_site(node)
+      end
+
+      # Notes an unless site, a modifier unless included, its
+      # arms included.
+      def visit_unless_node(node)
+        add_site(node)
+      end
+
+      # Notes a case site, when its paths can be seen; any other
+      # case is no site, though a condition inside it may be.
+      def visit_case_node(node)
+        return super unless case_site?(node)
+
+        add_site(node)
+      end
+
+      # Notes a block method's call as a site, when its block's
+      # every call can be seen; any other call is no site, though
+      # a condition inside it may be.
+      def visit_call_node(node)
+        return super unless block_site?(node)
+
+        add_site(node)
+      end
+
+      # Notes node as a site, named where it starts: an if or an
+      # unless at its keyword. It claims its place first, so a
+      # site found inside one of its leaves or arms follows it.
+      def add_site(node)
+        site = Site.at(@path, site_loc(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 ?:, an if if and
+      # an unless unless, their operands a predicate and arms; a
+      # case case, its operands its arms.
+      def condition_of(node)
+        return choice_of(node) if CHOICE_TYPES.include?(node.type)
+        return case_condition(node) if node.type == :case_node
+        return block_condition(node) if node.type == :call_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_blocks.rb

@@ -0,0 +1,57 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The part of the manifest's visitor that builds the site of a
+  # call to a block method, one that calls its block an item at
+  # a time, until it decides, eg any?, or for every item, eg
+  # select: its leaves are its receiver, whose items the block
+  # is called with, and its block's one expression, whose
+  # answers decide. It relies on its includer's extent_of and
+  # @notes.
+  module ManifestBlocks
+    # True for a call whose block's every call can be seen: to a
+    # block method, on a receiver, with no arguments, which can
+    # make it ignore its block, not by &., which skips it for
+    # nil, and with a block of one expression.
+    def block_site?(node)
+      BLOCK_PATHS.key?(node.name.to_s) && !node.receiver.nil? &&
+        node.arguments.nil? && !node.safe_navigation? &&
+        !block_expression(node.block).nil?
+    end
+
+    # The one expression of block, nil for no block, a block
+    # passed as an argument, or one of other than one expression.
+    def block_expression(block)
+      return nil unless block&.type == :block_node
+
+      statements = block.body
+      return nil unless statements&.type == :statements_node
+
+      statements.body.size == 1 ? statements.body.first : nil
+    end
+
+    # A block method's call as a Condition, named by its method,
+    # its extent the whole call. Its block's expression is noted
+    # among the commands when it is no bare argument.
+    def block_condition(node)
+      node.receiver.accept(self)
+      body = block_expression(node.block)
+      body.accept(self)
+      @notes[:commands] << extent_of(body) if bare_less?(body)
+      Condition.new(
+        operator: node.name.to_s,
+        operands: [extent_of(node.receiver), extent_of(body)],
+        extent: extent_of(node)
+      )
+    end
+
+    # True for an expression that is no bare argument: a command
+    # call, or an and or an or.
+    def bare_less?(node)
+      return true if Manifest.command?(node)
+
+      %i[and_node or_node].include?(node.type) &&
+        %w[and or].include?(node.operator)
+    end
+  end
+end

data/lib/path_coverage/manifest_case.rb

@@ -0,0 +1,54 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The part of the manifest's visitor that builds a case site,
+  # named case: its arms are its whens, each holding a when
+  # condition of its patterns, and its else. It relies on its
+  # includer's extent_of and statement_arm.
+  module ManifestCase
+    # True for a case whose paths can be seen: one with a
+    # subject, as each pattern is then matched against it, and
+    # no splat among its patterns, whose items cannot each be
+    # stood in for.
+    def case_site?(node)
+      return false if node.predicate.nil?
+
+      node.conditions.none? do |clause|
+        clause.conditions.any? { |each| each.type == :splat_node }
+      end
+    end
+
+    # A case as a Condition, its extent its case keyword to the
+    # end of its subject, as its arms are statements.
+    def case_condition(node)
+      node.predicate.accept(self)
+      whens = node.conditions.map { |clause| when_arm(clause) }
+      start = node.case_keyword_loc.start_offset
+      Condition.new(
+        operator: 'case',
+        operands: [*whens, *case_else(node.else_clause)],
+        extent: start...node.predicate.location.end_offset
+      )
+    end
+
+    # One when as an arm, its body a when condition whose leaves
+    # are its patterns' byte ranges. A pattern is matched, not
+    # tested for truth, so none is ever fixed.
+    def when_arm(clause)
+      patterns = clause.conditions.map do |pattern|
+        pattern.accept(self)
+        extent_of(pattern)
+      end
+      body = Condition.new(
+        operator: 'when', operands: patterns,
+        extent: patterns.first.begin...patterns.last.end
+      )
+      statement_arm(:when, clause.statements).with(body:)
+    end
+
+    # A case's else arm, none when it has no else.
+    def case_else(clause)
+      clause ? [statement_arm(:else, clause.statements)] : []
+    end
+  end
+end

data/lib/path_coverage/manifest_choices.rb

@@ -0,0 +1,132 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The part of the manifest's visitor that builds the sites
+  # whose predicate picks an arm: a ternary, named ?:, an if,
+  # named if, and an unless, named unless. It relies on its
+  # includer's condition_of, extent_of, grouped, leaf and
+  # operator?.
+  module ManifestChoices
+    # The node types whose predicate picks an arm, a ternary
+    # being an if_node with no if keyword.
+    CHOICE_TYPES = %i[if_node unless_node].freeze
+
+    # Where node's site starts: an if's or an unless's keyword,
+    # which a modifier's statement comes before; anything
+    # else's own start.
+    def site_loc(node)
+      return node.message_loc if node.type == :call_node
+      return node.location unless CHOICE_TYPES.include?(node.type)
+      return node.location if ternary?(node)
+
+      keyword_loc(node)
+    end
+
+    # The location of an if's or an unless's keyword.
+    def keyword_loc(node)
+      unless?(node) ? node.keyword_loc : node.if_keyword_loc
+    end
+
+    # True for an unless.
+    def unless?(node)
+      node.type == :unless_node
+    end
+
+    # A ternary, an if or an unless 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 or an unless as a Condition, named by its keyword,
+    # its extent its keyword to the end of its predicate, as its
+    # arms are statements, not part of the expression.
+    def if_condition(node)
+      start = keyword_loc(node).start_offset
+      Condition.new(
+        operator: unless?(node) ? 'unless' : 'if',
+        operands: if_of(node),
+        extent: start...node.predicate.location.end_offset
+      )
+    end
+
+    # An if's or an unless's predicate, then its then arm and,
+    # when it has one, its else arm.
+    def if_of(node)
+      rest = unless?(node) ? node.else_clause : node.subsequent
+      [
+        predicate_of(node),
+        statement_arm(:then, node.statements),
+        *else_arm(rest)
+      ]
+    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