path_coverage 0.0.2 → 0.1.0

data/lib/path_coverage/html_index.rb

@@ -3,41 +3,72 @@ require_relative 'html_template'
 
 module PathCoverage
   # The HTML index page: one sortable row per covered file,
-  # each linking to that file's own page.
+  # each linking to that file's own page, then a Total row.
   module HtmlIndex
     # The whole index page: the files table, sortable by any
-    # column, with one row per Summary.files row.
-    def self.page(rows)
+    # column, with one row per Summary.files row, and total, as
+    # Summary.total gives it, as its footer.
+    def self.page(rows, total)
       HtmlTemplate.fill(
         HtmlTemplate.asset('index.html'),
         'style' => HtmlTemplate.asset('style.css'),
         'script' => HtmlTemplate.asset('sort.js'),
-        'rows' => rows.map { |row| row(row) }.join("\n")
+        'rows' => rows.map { |row| row(row) }.join("\n"),
+        'total' => total_row(total),
+        'across' => total[:methods] ? ACROSS : ''
       )
     end
 
+    # The heading of the across column, there only when methods
+    # are measured.
+    ACROSS = '<th class="num" aria-sort="none"><button ' \
+             'type="button" data-column="3" data-type="number">' \
+             "Across a method's decisions</button></th>".freeze
+
     # The table row of one Summary.files row; each cell has a
     # data-sort value for the page's column sorting.
     def self.row(row)
-      "<tr>#{cells(row).join}</tr>"
-    end
-
-    # The four cells: file, sites, outcomes seen, missing.
-    def self.cells(row)
       path = CGI.escapeHTML(row[:path])
       link = %(<a href="files/#{path}.html">#{path}</a>)
-      seen = "#{row[:seen]} / #{row[:outcomes]} · #{row[:percent]}%"
-      [
-        cell(path, link),
+      "<tr>#{cell(path, link)}#{counts(row).join}</tr>"
+    end
+
+    # The footer row: the sums over every file.
+    def self.total_row(total)
+      "<tr>#{cell('Total', 'Total')}#{counts(total).join}</tr>"
+    end
+
+    # The cells after the file's: its sites, then its total
+    # within each decision, then, when methods are measured, its
+    # total across a method's decisions.
+    def self.counts(row)
+      cells = [
         cell(row[:sites], row[:sites]),
-        cell(row[:percent], seen),
-        cell(row[:missing], row[:missing])
+        paths_cell(row[:decisions])
       ]
+      row[:methods] ? cells + [paths_cell(row[:methods])] : cells
+    end
+
+    # A cell showing [taken, possible] paths, eg 3 / 6 (50%),
+    # sorted by its percent. With no paths to take, as in a file
+    # with no method of two or more decisions, it shows -,
+    # titled with why, with an empty sort value, which sort.js
+    # keeps last whichever way the column is sorted.
+    def self.paths_cell(pair)
+      taken, possible = pair
+      if possible.zero?
+        return cell('', '-', 'no method with two or more decisions')
+      end
+
+      percent = (100.0 * taken / possible).round
+      cell(percent, "#{taken} / #{possible} (#{percent}%)")
     end
 
-    # One table cell, sorted by sort_value, showing content.
-    def self.cell(sort_value, content)
-      %(<td data-sort="#{sort_value}">#{content}</td>)
+    # One table cell, sorted by sort_value, showing content,
+    # with title as its hover text when there is one.
+    def self.cell(sort_value, content, title = nil)
+      hover = title ? %( title="#{title}") : ''
+      %(<td data-sort="#{sort_value}"#{hover}>#{content}</td>)
     end
   end
 end

data/lib/path_coverage/html_report.rb

@@ -18,7 +18,7 @@ module PathCoverage
     # file, as the kernel parsed it.
     def self.write(operands, files, config, paths = nil, site_paths:)
       dir = config.output_dir
-      index = HtmlIndex.page(Summary.files(operands))
+      index = index(files, config, paths, site_paths)
       File.write("#{dir}/index.html", index)
       files.each do |full_path, parsed|
         path = config.relative(full_path)
@@ -30,6 +30,20 @@ module PathCoverage
       end
     end
 
+    # The index page: a row per file of its totals within each
+    # decision, and, when paths are given, as they are when
+    # methods are measured, across each method's decisions too;
+    # then their Total row.
+    def self.index(files, config, paths, site_paths)
+      methods = files.map do |full_path, parsed|
+        path = config.relative(full_path)
+        PathManifest.methods(parsed[:source], path)
+      end
+      all = methods.reduce({}, :merge)
+      rows = Summary.files(site_paths, all, paths)
+      HtmlIndex.page(rows, Summary.total(rows))
+    end
+
     # simplecov:disable
     # SPIKE: the hidden path grids of one file's methods.
     def self.path_grids(path, parsed, paths)
@@ -80,10 +94,11 @@ module PathCoverage
       tree.merge(at: at(source, condition.extent), operands:)
     end
 
-    # An arm's node with its at:, and its body's tree located.
+    # An arm's node with its at:, nil for an arm with no
+    # statements, and its body's tree located.
     def self.located_arm(source, arm, node)
       body = arm.body && located(source, arm.body, node[:body])
-      node.merge(at: at(source, arm.extent), body:)
+      node.merge(at: arm.extent && at(source, arm.extent), body:)
     end
 
     # [line, column, line, column] of the byte range in source.

data/lib/path_coverage/html_tree.rb

@@ -1,10 +1,19 @@
 require 'cgi/escape'
+require_relative 'condition'
 
 module PathCoverage
   # The tree of a span's sites on a file's page, from SiteTree.of
   # for each site: a grid whose columns are a site's paths.
   module HtmlTree
-    OUTCOMES = { true => 'T', false => 'F', nil => '' }.freeze
+    OUTCOMES = {
+      true => 'T', false => 'F', nil => '',
+      ITEMS[0] => '0', ITEMS[1] => '1', ITEMS[2] => '*',
+      ANSWERS[0] => 'T', ANSWERS[1] => 'F', ANSWERS[2] => 'TF'
+    }.freeze
+    # The choices whose arms are named by their kind, eg then,
+    # else or when, as their text is statements.
+    NAMED_ARMS = [*STATEMENT_CHOICES, 'case'].freeze
+
     # A bullet marks a path taking an arm.
     TAKEN = { true => [0x2022].pack('U'), false => '' }.freeze
 
@@ -92,7 +101,7 @@ module PathCoverage
 
     # The name of an arm of a condition whose operator is choice.
     def self.arm_label(arm, choice)
-      return arm[:arm].to_s if choice == 'if'
+      return arm[:arm].to_s if NAMED_ARMS.include?(choice)
 
       mark = arm[:arm] == :then ? '?' : ':'
       body = arm[:body]

data/lib/path_coverage/json_writer.rb

@@ -4,17 +4,21 @@ module PathCoverage
   # The base reporter: the result as raw JSON, which every
   # other reporter can read back.
   module JsonWriter
-    # Writes operands, as Result gives them, and paths, as
-    # PathsReport gives them, to path as {"sites": {site:
-    # [counts, ...]}, "paths": {site: {leaves:, taken:}}}.
-    def self.write(operands, path, paths = {})
-      File.write(path, json(operands, paths))
+    # Writes operands, as Result gives them, paths, as
+    # PathsReport gives them, and totals, as Kernel.totals gives
+    # them, to path as {"sites": {site: [counts, ...]}, "paths":
+    # {site: {leaves:, taken:}}, "totals": {"decisions": [taken,
+    # possible]}}.
+    def self.write(operands, path, paths = {}, totals: {})
+      File.write(path, json(operands, paths, totals:))
     end
 
-    # operands, and any paths, as the JSON report's text.
-    def self.json(operands, paths = {})
+    # operands, and any paths and totals, as the JSON report's
+    # text.
+    def self.json(operands, paths = {}, totals: {})
       report = { 'sites' => operands }
       report['paths'] = paths unless paths.empty?
+      report['totals'] = totals unless totals.empty?
       JSON.pretty_generate(report)
     end
   end

data/lib/path_coverage/kernel.rb

@@ -1,4 +1,5 @@
 require 'fileutils'
+require_relative 'calls'
 require_relative 'configuration'
 require_relative 'json_writer'
 require_relative 'manifest'
@@ -9,6 +10,7 @@ require_relative 'recorder'
 require_relative 'render'
 require_relative 'result'
 require_relative 'rewriter'
+require_relative 'totals'
 
 # Path coverage for Ruby. This file is the kernel: it loads
 # before any covered file and is never itself instrumented, since
@@ -32,37 +34,6 @@ module PathCoverage
     @config
   end
 
-  # The call rewritten code makes around each operand; returns
-  # value unchanged.
-  def self.record(site, index, value)
-    @recorder.record(site, index, value)
-  end
-
-  # The call rewritten code makes before a site's first leaf,
-  # site having size leaves; returns the evaluation's trail.
-  def self.enter(site, size)
-    @recorder.enter(site, size)
-  end
-
-  # The call rewritten code makes around a site as a whole,
-  # with the trail enter gave it; returns value unchanged.
-  def self.leave(trail, value)
-    @recorder.leave(trail, value)
-  end
-
-  # The call rewritten code makes as a call reaches its
-  # method's first decision; returns the call's new path.
-  def self.path(site, size)
-    @recorder.path(site, size)
-  end
-
-  # The call rewritten code makes around each decision's
-  # predicate, with exits for one whose arm leaves the method;
-  # returns value unchanged.
-  def self.decide(path, index, value, exits = nil)
-    @recorder.decide(path, index, value, exits)
-  end
-
   # Instruments every file later required that the settings
   # block covers, and reports when the process exits. on_exit
   # is Kernel#at_exit except in tests, which must not print
@@ -118,9 +89,9 @@ module PathCoverage
   end
 
   # The methods of the covered file at path whose paths are
-  # counted, none unless config measures paths.
+  # counted, none unless config measures methods.
   def self.path_methods(path, source, config)
-    return {} unless config.measures.include?(:paths)
+    return {} unless config.measures.include?(:methods)
 
     PathManifest.methods(source, config.relative(path))
   end
@@ -132,7 +103,8 @@ module PathCoverage
   def self.report(config)
     files = parsed_files(config)
     result = collect(files, config)
-    paths = config.measures.include?(:paths) ? @recorder.paths : nil
+    methods = config.measures.include?(:methods)
+    paths = methods ? @recorder.paths : nil
     Render.run(
       result.operands, files, config, paths, site_paths: result.paths
     )
@@ -159,10 +131,24 @@ module PathCoverage
     result = Result.new(sites, @recorder.counts, @recorder.site_paths)
     FileUtils.mkdir_p(config.output_dir)
     report = PathsReport.of(result.paths, files)
-    JsonWriter.write(result.operands, config.json_path, report)
+    totals = totals(result, files, config)
+    path = config.json_path
+    JsonWriter.write(result.operands, path, report, totals:)
     result
   end
 
+  # The JSON report's totals, each [taken, possible] paths:
+  # within each decision, and, when config measures methods,
+  # across each method's decisions too.
+  def self.totals(result, files, config)
+    totals = { 'decisions' => Totals.decisions(result.paths) }
+    return totals unless config.measures.include?(:methods)
+
+    methods = path_methods_of(files, config)
+    taken = Totals.methods(methods, @recorder.paths)
+    totals.merge('methods' => taken)
+  end
+
   # { full path => {source:, sites:} } for every covered file:
   # as parsed when it loaded, or parsed now for a file the run
   # never loaded.

data/lib/path_coverage/manifest.rb

@@ -1,12 +1,14 @@
 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 and each if, with the
-  # conditions nested in it.
+  # 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)
@@ -69,6 +71,8 @@ module PathCoverage
 
     # Collects each site and its Condition.
     class ConditionSites < Prism::Visitor
+      include ManifestBlocks
+      include ManifestCase
       include ManifestChoices
 
       # Starts with no sites found.
@@ -94,19 +98,40 @@ module PathCoverage
         add_site(node)
       end
 
-      # Notes a ternary or an if site, its arms included; a
-      # modifier if is no site itself.
+      # Notes a ternary or an if site, a modifier if included,
+      # its arms included.
       def visit_if_node(node)
-        return super if modifier?(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. It claims its place first, so a
-      # site found inside one of its leaves follows it, keeping
-      # the sites in source order.
+      # 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.of(@path, node)
+        site = Site.at(@path, site_loc(node))
         @sites[site] = nil
         outer = @notes
         @notes = { commands: [], fixed: {} }
@@ -116,10 +141,13 @@ module PathCoverage
       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.
+      # 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 node.type == :if_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),

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

@@ -2,20 +2,37 @@ 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?.
+  # 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
-    # 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?
+    # 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
 
-      node.statements.location.start_offset <
-        node.if_keyword_loc.start_offset
+    # 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 or an if as a Condition.
+    # A ternary, an if or an unless as a Condition.
     def choice_of(node)
       ternary?(node) ? ternary_condition(node) : if_condition(node)
     end
@@ -28,24 +45,26 @@ module PathCoverage
       )
     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.
+    # 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 = node.if_keyword_loc.start_offset
+      start = keyword_loc(node).start_offset
       Condition.new(
-        operator: 'if', operands: if_of(node),
+        operator: unless?(node) ? 'unless' : '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.
+    # 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(node.subsequent)
+        *else_arm(rest)
       ]
     end
 

data/lib/path_coverage/recorder.rb

@@ -1,3 +1,5 @@
+require_relative 'condition'
+
 module PathCoverage
   # Records the outcome of each instrumented operand.
   class Recorder
@@ -95,5 +97,86 @@ module PathCoverage
       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