path_coverage 0.0.1 → 0.1.0

data/lib/path_coverage/condition.rb

@@ -0,0 +1,96 @@
+module PathCoverage
+  # The operators whose predicate picks an arm.
+  CHOICES = %w[?: if unless].freeze
+
+  # The choices whose arms are statements, so whose path is
+  # decided by their predicate alone.
+  STATEMENT_CHOICES = %w[if unless].freeze
+
+  # The predicate outcome on which each choice takes its then
+  # arm: an unless's is false.
+  THEN_ON = Hash.new(true).merge('unless' => false).freeze
+
+  # The methods that call their block an item at a time until
+  # it decides, its last answer deciding the result.
+  STOP_EARLY = %w[
+    any? all? none? find detect find_index take_while
+  ].freeze
+
+  # How many items a block method's block was called with, as
+  # its receiver's leaf outcome: none, one, or two or more.
+  ITEMS = ['0 items', '1 item', '2+ items'].freeze
+
+  # Every path a stop-early block method's call can take: how
+  # many items its block was called with, and its last answer,
+  # nil when it was never called.
+  STOP_EARLY_PATHS = [
+    [ITEMS[0], nil],
+    [ITEMS[1], true], [ITEMS[1], false],
+    [ITEMS[2], true], [ITEMS[2], false]
+  ].freeze
+
+  # The methods that call their block with every item.
+  EVERY_ITEM = %w[
+    select filter reject partition count filter_map
+  ].freeze
+
+  # A block's answers over every item it was called with.
+  ANSWERS = ['all true', 'all false', 'both'].freeze
+
+  # Every path an every-item block method's call can take: how
+  # many items its block was called with, and its answers,
+  # which can be both only with two or more items.
+  EVERY_ITEM_PATHS = [
+    [ITEMS[0], nil],
+    [ITEMS[1], ANSWERS[0]], [ITEMS[1], ANSWERS[1]],
+    [ITEMS[2], ANSWERS[0]], [ITEMS[2], ANSWERS[1]],
+    [ITEMS[2], ANSWERS[2]]
+  ].freeze
+
+  # Every block method whose call is a site, by its paths.
+  BLOCK_PATHS = [
+    *STOP_EARLY.map { |name| [name, STOP_EARLY_PATHS] },
+    *EVERY_ITEM.map { |name| [name, EVERY_ITEM_PATHS] }
+  ].to_h.freeze
+
+  # One arm of a ternary, an if or an unless: kind is :then or
+  # :else, extent its byte range, nil for an arm with no
+  # statements, and body the Condition it is, when it is one,
+  # else nil for a plain value or statements, which decide
+  # nothing.
+  Arm = Data.define(:kind, :extent, :body)
+
+  # One site's condition as the manifest found it: its operator
+  # and its operands, each the byte range of a leaf or a nested
+  # Condition. A site's commands are the byte ranges of its
+  # leaves that are command calls, eg `ok? id`; its fixed are
+  # { byte range => :truthy } for leaves that can have that one
+  # outcome only, eg `Clock.new`. Its extent is the byte range
+  # of the whole condition as written, eg a ternary's from its
+  # predicate to its else arm, which its leaves alone cannot
+  # give.
+  Condition = Data.define(
+    :operator, :operands, :commands, :fixed, :extent
+  ) do
+    # A condition with no command-call or fixed leaves, and no
+    # extent, by default.
+    def initialize(
+      operator:, operands:, commands: [], fixed: {}, extent: nil
+    )
+      super
+    end
+
+    # The byte range of every leaf operand, left to right, a
+    # ternary's arms' after its predicate's; a leaf's index here
+    # is the index it is recorded under.
+    def leaves
+      operands.flat_map do |operand|
+        case operand
+        when Condition then operand.leaves
+        when Arm then operand.body&.leaves || []
+        else [operand]
+        end
+      end
+    end
+  end
+end

data/lib/path_coverage/configuration.rb

@@ -0,0 +1,130 @@
+module PathCoverage
+  # Raised for a start block that cannot be applied.
+  class ConfigurationError < StandardError; end
+
+  # The settings given in a PathCoverage.start block.
+  class Configuration
+    GLOB_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+    SETTINGS = %w[
+      collector cover coverage_dir measure report root
+    ].freeze
+    REPORTERS = %w[gaps html post].freeze
+    MEASURES = %w[decisions methods].freeze
+
+    # Evaluates the settings block against a new configuration.
+    def initialize(&)
+      @globs = []
+      @reporters = [:gaps]
+      @measures = [:decisions]
+      instance_eval(&)
+    end
+
+    # The reporters chosen with report, :gaps when none were.
+    attr_reader :reporters
+
+    # What is measured, chosen with measure.
+    # :decisions, the paths within each decision, when nothing
+    # was chosen.
+    attr_reader :measures
+
+    # Chooses what is measured.
+    # Eg measure :decisions, :methods also measures the paths
+    # across each method's decisions.
+    # Refuses a name there is no measure for.
+    def measure(*names)
+      check('measure', names, MEASURES)
+      @measures = names.map(&:to_sym)
+    end
+
+    # The dir the reports are written to.
+    def output_dir
+      @coverage_dir
+    end
+
+    # The url the :post reporter sends the JSON report to.
+    attr_reader :collector_url
+
+    # Sets the url the :post reporter sends the JSON report to.
+    def collector(url)
+      @collector_url = url
+    end
+
+    # Sets the dir that cover globs and site names are
+    # relative to.
+    def root(dir)
+      @root = dir
+    end
+
+    # Adds a glob, relative to root, of files to instrument.
+    def cover(glob)
+      @globs << glob
+    end
+
+    # Chooses the reporters run at exit, eg report :gaps;
+    # refuses a name there is no reporter for.
+    def report(*names)
+      check('reporter', names, REPORTERS)
+      @reporters = names.map(&:to_sym)
+    end
+
+    # Refuses the first of names that is not in known, naming
+    # it as a kind and listing the known ones.
+    def check(kind, names, known)
+      names.each do |name|
+        next if known.include?(name.to_s)
+
+        raise ConfigurationError, [
+          "unknown #{kind} #{name} in PathCoverage.start",
+          "the #{kind}s are: #{known.join(', ')}"
+        ].join("\n")
+      end
+    end
+
+    # Sets the dir the path_coverage.json report is
+    # written to.
+    def coverage_dir(dir)
+      @coverage_dir = dir
+    end
+
+    # Every file the cover globs match under root, as full
+    # paths, whether or not the run loads it.
+    def files
+      Dir.glob(@globs, base: @root).sort.map { |f| "#{@root}/#{f}" }
+    end
+
+    # Where the JSON report goes.
+    def json_path
+      "#{output_dir}/path_coverage.json"
+    end
+
+    # True when path is under root and matches a cover glob.
+    def covers?(path)
+      path.start_with?("#{@root}/") && matches?(relative(path))
+    end
+
+    # True when the root-relative path matches a cover glob.
+    def matches?(relative_path)
+      @globs.any? do |glob|
+        File.fnmatch?(glob, relative_path, GLOB_FLAGS)
+      end
+    end
+
+    # path relative to root, eg "source/kata.rb".
+    def relative(path)
+      path.delete_prefix("#{@root}/")
+    end
+
+    # Refuses a setting that does not exist, naming it.
+    def method_missing(name, *)
+      raise ConfigurationError, [
+        "unknown setting #{name} in PathCoverage.start",
+        "the settings are: #{SETTINGS.join(', ')}"
+      ].join("\n")
+    end
+
+    # Answers only for the settings there are.
+    def respond_to_missing?(_name, _include_private = false)
+      false
+    end
+  end
+end

data/lib/path_coverage/gaps.rb

@@ -0,0 +1,60 @@
+module PathCoverage
+  # The terminal worklist: one line per path a site never
+  # took, and nothing for a site that took them all. Every
+  # count stays in the operands and paths for reporters that
+  # show them all.
+  module Gaps
+    # The gap lines of operands and paths, as Result gives
+    # them, in manifest order; texts is { site => each leaf's
+    # source text }.
+    def self.lines(operands, paths: {}, texts: {})
+      operands.flat_map do |site, counts|
+        if counts.all? { |each| never_ran?(each) }
+          next ["#{site} never reached"]
+        end
+
+        path_gaps(site, paths.fetch(site, []), texts[site])
+      end
+    end
+
+    # One line per path site never took, as Result#paths gives
+    # them, naming the outcome of each leaf the path reaches,
+    # texts being each leaf's source text.
+    def self.path_gaps(site, paths, texts)
+      paths.select { |each| each[:count].zero? }.map do |each|
+        steps = each[:path].zip(texts).filter_map do |outcome, text|
+          "#{code(text)} #{outcome}" unless outcome.nil?
+        end
+        "#{site} path never taken: #{steps.join(', ')}"
+      end
+    end
+
+    # text as a markdown code span on one line: each run of
+    # whitespace one space, fenced by a run of backticks one
+    # longer than any inside it, with a space inside the fence
+    # when text starts or ends with one.
+    def self.code(text)
+      text = text.gsub(/\s+/, ' ')
+      longest = text.scan(/`+/).map(&:size).max || 0
+      fence = '`' * (longest + 1)
+      pad = text.start_with?('`') || text.end_with?('`') ? ' ' : ''
+      "#{fence}#{pad}#{text}#{pad}#{fence}"
+    end
+
+    # The one outcome this operand is missing, if any; a fixed
+    # leaf, which can have one outcome only, needs only to run.
+    def self.operand_gap(counts)
+      return ['never evaluated'] if never_ran?(counts)
+      return [] if counts[:only]
+      return ['never true'] if counts[:truthy].zero?
+      return ['never false'] if counts[:falsy].zero?
+
+      []
+    end
+
+    # True when the operand was never recorded either way.
+    def self.never_ran?(counts)
+      counts[:truthy].zero? && counts[:falsy].zero?
+    end
+  end
+end

data/lib/path_coverage/html/file.html

@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>{{path}} · Path coverage</title>
+<style>
+/*<![CDATA[*/
+{{style}}
+/*]]>*/
+</style>
+</head>
+<body>
+<main class="page">
+<header class="head" data-head="">
+<p class="back"><a data-index="" href="{{index}}">Path coverage</a></p>
+<h1 class="path">{{path}}</h1>
+{{jumps}}
+</header>
+<div class="box">
+{{listing}}
+</div>
+<div class="pathgrids" hidden="hidden">
+{{grids}}
+</div>
+</main>
+<script>
+//<![CDATA[
+{{script}}
+//]]>
+</script>
+</body>
+</html>

data/lib/path_coverage/html/index.html

@@ -0,0 +1,41 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>Path coverage</title>
+<style>
+/*<![CDATA[*/
+{{style}}
+/*]]>*/
+</style>
+</head>
+<body>
+<main class="page">
+<h1>Path coverage</h1>
+<div class="box">
+<table id="files">
+<thead>
+<tr>
+<th aria-sort="none"><button type="button" data-column="0" data-type="text">File</button></th>
+<th class="num" aria-sort="none"><button type="button" data-column="1" data-type="number">Sites</button></th>
+<th class="num" aria-sort="none"><button type="button" data-column="2" data-type="number">Within each decision</button></th>
+{{across}}
+</tr>
+</thead>
+<tbody>
+{{rows}}
+</tbody>
+<tfoot>
+{{total}}
+</tfoot>
+</table>
+</div>
+</main>
+<script>
+//<![CDATA[
+{{script}}
+//]]>
+</script>
+</body>
+</html>