path_coverage 0.1.0 → 0.2.0

data/lib/path_coverage/html_index_head.rb

@@ -0,0 +1,49 @@
+module PathCoverage
+  # The two heading rows of the HTML index's files tables: File
+  # and Sites, then each total's name over its taken, / of and %
+  # columns, every column sortable.
+  module HtmlIndexHead
+    # The class and label of each of a total's three columns.
+    PARTS = [%w[taken taken], ['of', '/ of'], %w[percent %]].freeze
+
+    # The two heading rows; methods' total only when methods are
+    # measured.
+    def self.of(methods)
+      names = ['Within each decision']
+      names << 'Within each method' if methods
+      rows = [top_row(names), part_row(names)]
+      rows.map { |row| "<tr>\n#{row}\n</tr>" }.join("\n")
+    end
+
+    # The first heading row: File and Sites, each over both rows,
+    # then each total's name over its three columns.
+    def self.top_row(names)
+      fixed = [
+        heading(' rowspan="2"', 0, 'text', 'File'),
+        heading(' class="num" rowspan="2"', 1, 'number', 'Sites')
+      ]
+      groups = names.map do |name|
+        %(<th class="group" colspan="3">#{name}</th>)
+      end
+      (fixed + groups).join("\n")
+    end
+
+    # The second heading row: each total's taken, / of and %.
+    def self.part_row(names)
+      names.each_index.flat_map do |group|
+        PARTS.each_with_index.map do |(css, label), i|
+          column = 2 + (3 * group) + i
+          heading(%( class="#{css}"), column, 'number', label)
+        end
+      end.join("\n")
+    end
+
+    # A sortable heading, attrs its th's, sorting the column-th
+    # column as type, its button showing label.
+    def self.heading(attrs, column, type, label)
+      data = %(data-column="#{column}" data-type="#{type}")
+      button = %(<button type="button" #{data}>#{label}</button>)
+      %(<th#{attrs} aria-sort="none">#{button}</th>)
+    end
+  end
+end

data/lib/path_coverage/html_report.rb

@@ -15,9 +15,11 @@ module PathCoverage
     # Writes every page. operands and site_paths are as Result
     # gives them, site_paths holding every site in files; files
     # is { full path => {source:, sites:} } for each covered
-    # file, as the kernel parsed it.
+    # file, as the kernel parsed it. The files dir is emptied
+    # first, so it holds no page for a file no longer covered.
     def self.write(operands, files, config, paths = nil, site_paths:)
       dir = config.output_dir
+      FileUtils.rm_rf("#{dir}/files")
       index = index(files, config, paths, site_paths)
       File.write("#{dir}/index.html", index)
       files.each do |full_path, parsed|
@@ -32,8 +34,10 @@ module PathCoverage
 
     # 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.
+    # methods are measured, within each method too;
+    # then their Total row. With groups configured, each group,
+    # and the files in none, get a tab of their own too. Any
+    # operators config ignored are named after them.
     def self.index(files, config, paths, site_paths)
       methods = files.map do |full_path, parsed|
         path = config.relative(full_path)
@@ -41,7 +45,10 @@ module PathCoverage
       end
       all = methods.reduce({}, :merge)
       rows = Summary.files(site_paths, all, paths)
-      HtmlIndex.page(rows, Summary.total(rows))
+      groups = config.groups
+      tabs = groups.empty? ? [] : Summary.groups(rows, groups)
+      ignored = config.ignored
+      HtmlIndex.page(rows, Summary.total(rows), tabs, ignored:)
     end
 
     # simplecov:disable
@@ -81,24 +88,34 @@ module PathCoverage
     # on it and on each of its operands: a leaf's from its byte
     # range, a condition's and an arm's from its extent, the
     # whole of it as written. Columns count characters, not
-    # bytes.
+    # bytes. A node past the condition's operands, eg owner at
+    # the end of user&.account&.owner, is kept as it is.
     def self.located(source, condition, tree)
       pairs = condition.operands.zip(tree[:operands])
       operands = pairs.map do |operand, node|
-        case operand
-        when Condition then located(source, operand, node)
-        when Arm then located_arm(source, operand, node)
-        else node.merge(at: at(source, operand))
-        end
+        located_operand(source, operand, node)
+      end
+      rest = tree[:operands].drop(pairs.size)
+      tree.merge(at: at(source, condition.extent),
+                 operands: operands + rest)
+    end
+
+    # SPIKE: the node of operand with its at:, as located gives
+    # a condition's, an arm's or a leaf's.
+    def self.located_operand(source, operand, node)
+      case operand
+      when Condition then located(source, operand, node)
+      when Arm then located_arm(source, operand, node)
+      else node.merge(at: at(source, operand))
       end
-      tree.merge(at: at(source, condition.extent), operands:)
     end
 
     # 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: arm.extent && at(source, arm.extent), body:)
+      body = arm.body ? located(source, arm.body, node[:body]) : nil
+      at = arm.extent ? at(source, arm.extent) : nil
+      node.merge(at:, body:)
     end
 
     # [line, column, line, column] of the byte range in source.

data/lib/path_coverage/html_tabs.rb

@@ -0,0 +1,26 @@
+require 'cgi/escape'
+
+module PathCoverage
+  # The index page's tab bar, one tab per table: All files,
+  # then each group.
+  module HtmlTabs
+    # The tab bar of names, the first tab selected, each tab
+    # controlling the table of the same index.
+    def self.bar(names)
+      tabs = names.each_with_index.map { |name, i| tab(name, i) }
+      nav = %(<nav class="tabs" role="tablist" aria-label="Groups">)
+      "#{nav}#{tabs.join}</nav>"
+    end
+
+    # The index-th tab, named name.
+    def self.tab(name, index)
+      selected = index.zero?
+      [
+        %(<button type="button" role="tab"),
+        %( aria-selected="#{selected}"),
+        %( aria-controls="files-#{index}">),
+        CGI.escapeHTML(name), '</button>'
+      ].join
+    end
+  end
+end

data/lib/path_coverage/html_tree.rb

@@ -1,5 +1,6 @@
 require 'cgi/escape'
 require_relative 'condition'
+require_relative 'kinds'
 
 module PathCoverage
   # The tree of a span's sites on a file's page, from SiteTree.of
@@ -8,14 +9,13 @@ module PathCoverage
     OUTCOMES = {
       true => 'T', false => 'F', nil => '',
       ITEMS[0] => '0', ITEMS[1] => '1', ITEMS[2] => '*',
-      ANSWERS[0] => 'T', ANSWERS[1] => 'F', ANSWERS[2] => 'TF'
+      ANSWERS[0] => 'T', ANSWERS[1] => 'F', ANSWERS[2] => 'TF',
+      PRESENCE[0] => [0x25CF].pack('U'),
+      PRESENCE[1] => [0x2205].pack('U')
     }.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
+    # A tick marks a path taking an arm.
+    TAKEN = { true => [0x2713].pack('U'), false => '' }.freeze
 
     # The tree of a span, open when its sites have gaps, else
     # hidden: each site's rows in a group of their own.
@@ -45,10 +45,13 @@ module PathCoverage
       end.join
     end
 
-    # One cell per path, naming each with names.
+    # One cell per path, naming each with names; a &. receiver's,
+    # shown as a glyph, titled not nil or nil for its hover text.
     def self.cells(values, names = OUTCOMES)
       values.map do |value|
-        %(<span class="cell" data-cell="">#{names[value]}</span>)
+        title = PRESENCE.include?(value) ? %( title="#{value}") : ''
+        attrs = %(class="cell" data-cell=""#{title})
+        %(<span #{attrs}>#{names[value]}</span>)
       end.join
     end
 
@@ -61,10 +64,16 @@ module PathCoverage
     # The rows of a condition's operands, each branching from
     # its operator after indent; a nested condition's operands,
     # and those of an arm's condition, follow its own row,
-    # indented under its branch.
+    # indented under its branch. A leaf with sites inside it
+    # branches as those sites, then the leaf, in the order they
+    # run.
     def self.operand_rows(condition, indent)
-      last = condition[:operands].size - 1
-      condition[:operands].each_with_index.flat_map do |operand, i|
+      own = Kinds.of(condition[:operator]).rows(condition, indent)
+      return own if own
+
+      operands = unfolded(condition[:operands])
+      last = operands.size - 1
+      operands.each_with_index.flat_map do |operand, i|
         tip = i == last
         branch = indent + (tip ? '└─ ' : '├─ ')
         under = indent + (tip ? '   ' : '│  ')
@@ -91,7 +100,7 @@ module PathCoverage
     # plain arm marks the paths taking it.
     def self.arm_rows(arm, branch, under, choice)
       body = arm[:body]
-      values = cells((body || arm)[:cells], body ? OUTCOMES : TAKEN)
+      values = body ? cells(body[:cells]) : cells(arm[:cells], TAKEN)
       text = CGI.escapeHTML(arm_label(arm, choice))
       lead = branch_cell(branch) +
              %(<span class="arm" data-label="">#{text}</span>)
@@ -99,13 +108,20 @@ module PathCoverage
       body ? [row, *operand_rows(body, under)] : [row]
     end
 
-    # The name of an arm of a condition whose operator is choice.
+    # The name of an arm of a condition whose operator is choice,
+    # as its kind names it, eg then for an if's.
     def self.arm_label(arm, choice)
-      return arm[:arm].to_s if NAMED_ARMS.include?(choice)
+      Kinds.of(choice).arm_label(arm, choice)
+    end
 
-      mark = arm[:arm] == :then ? '?' : ':'
-      body = arm[:body]
-      "#{mark} #{body ? body[:operator] : arm[:text]}"
+    # operands with each node standing for the nodes its kind
+    # unfolds it into, eg a leaf with sites inside it for those
+    # sites, then the leaf; a leaf or an arm for itself.
+    def self.unfolded(operands)
+      operands.flat_map do |operand|
+        operator = operand[:operator]
+        operator ? Kinds.of(operator).unfold(operand) : [operand]
+      end
     end
 
     # A nested condition's row: its branch, its operator, and
@@ -122,20 +138,25 @@ module PathCoverage
       %(<div class="row"#{attrs}>#{lead}#{values}</div>)
     end
 
-    # The cell naming a condition's operator.
+    # The cell naming a condition's operator, or its label when
+    # it has one, eg select { for a site inside a leaf.
     def self.operator(condition)
-      name = CGI.escapeHTML(condition[:operator])
+      name = CGI.escapeHTML(condition[:label] || condition[:operator])
       %(<span class="operator" data-operator="">#{name}</span>)
     end
 
     # One operand's row: its branch, text, and its outcome on
     # each path.
+    # An operand that is only called, eg owner at the end of
+    # user&.account&.owner, has a tick on each path that called
+    # it instead.
     def self.operand_row(operand, branch)
       text = CGI.escapeHTML(operand[:text].to_s)
       lead = branch_cell(branch) +
              %(<span class="text" data-text="">#{text}</span>)
       attrs = %( data-operand=""#{at(operand)})
-      row(attrs, lead, cells(operand[:cells]))
+      names = operand[:called] ? TAKEN : OUTCOMES
+      row(attrs, lead, cells(operand[:cells], names))
     end
 
     # The cell drawing a row's branch from its operator.

data/lib/path_coverage/json_reader.rb

@@ -0,0 +1,94 @@
+require 'json'
+require_relative 'kinds'
+require_relative 'merge'
+
+module PathCoverage
+  # Reads back the JSON reports JsonWriter writes, merging the
+  # counts of several runs, and refusing any report whose
+  # sites' paths are listed differently from a render's.
+  module JsonReader
+    # The keys of a JSON report's fingerprint.
+    FINGERPRINT = %w[ignored treats].freeze
+
+    # The operands of the JSON reports at paths, merged; raises
+    # unless each measured the kinds a render does, with
+    # fingerprint, as Configuration#fingerprint gives it.
+    def self.operands(paths, fingerprint)
+      Merge.operands(paths.map { |path| read(path, fingerprint) })
+    end
+
+    # The method paths of the JSON reports at paths, merged.
+    def self.method_paths(paths)
+      merged(paths, 'method_paths')
+    end
+
+    # The paths taken of the JSON reports at paths, as
+    # Render.run takes them: site_paths:, each site's possible
+    # paths, and outside:, those a treatment rules out, each
+    # merged.
+    def self.taken(paths)
+      site_paths = Merge.paths(paths.map { |path| paths_of(path) })
+      { site_paths:, outside: merged(paths, 'outside') }
+    end
+
+    # Raises unless json, the JSON report at path, measured the
+    # kinds a render does, with fingerprint; one that measured
+    # others, or names none, lists its sites' paths differently,
+    # so its counts cannot be trusted to the paths a render
+    # lists.
+    def self.same_kinds(path, json, fingerprint)
+      kinds = json['kinds'] == Kinds.names
+      return if kinds && json.slice(*FINGERPRINT) == fingerprint
+
+      raise ArgumentError, "#{path} measured other kinds"
+    end
+
+    # The key lists of the JSON reports at paths, as listed_of
+    # gives them, each path's count the sum of every report's.
+    def self.merged(paths, key)
+      Merge.method_paths(paths.map { |path| listed_of(path, key) })
+    end
+
+    # The JSON report at path's list under key, eg its method
+    # paths as the recorder counts them, { site => { path =>
+    # count } }; none for a report that has none, eg from a run
+    # that did not measure methods, so the render claims no
+    # path taken.
+    def self.listed_of(path, key)
+      json = JSON.parse(File.read(path))
+      json.fetch(key, {}).transform_values do |taken|
+        taken.to_h { |each| [each['path'], each['count']] }
+      end
+    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, which raises
+    # unless it measured the kinds a render does, with
+    # fingerprint.
+    def self.read(path, fingerprint)
+      json = JSON.parse(File.read(path))
+      same_kinds(path, json, fingerprint)
+      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/json_writer.rb

@@ -1,25 +1,57 @@
 require 'json'
+require_relative 'kinds'
 
 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, 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,
+    # PathsReport gives them, totals, as Kernel.totals gives
+    # them, and method_paths, as the recorder counts them, to
+    # path as {"sites": {site: [counts, ...]}, "paths":
+    # {site: {leaves:, taken:}}, "method_paths": {site:
+    # [{path:, count:}, ...]}, "totals": {"decisions": [taken,
     # possible]}}.
-    def self.write(operands, path, paths = {}, totals: {})
-      File.write(path, json(operands, paths, totals:))
+    # parts are json's.
+    def self.write(operands, path, paths = {}, **parts)
+      File.write(path, json(operands, paths, **parts))
     end
 
-    # operands, and any paths and totals, as the JSON report's
-    # text.
-    def self.json(operands, paths = {}, totals: {})
-      report = { 'sites' => operands }
+    # The keys of parts listed as { site => [{path:, count:}] }:
+    # each method's paths taken, and each path taken that a
+    # treatment rules out, as Result#outside gives them.
+    LISTED = %i[method_paths outside].freeze
+
+    # operands, and any paths, and parts' method_paths:,
+    # outside: and totals:, as the JSON report's text, with
+    # parts' fingerprint:, as Configuration#fingerprint gives
+    # it, and the names of the kinds measured.
+    def self.json(operands, paths = {}, **parts)
+      fingerprint = parts.fetch(:fingerprint, {})
+      report = { 'sites' => operands, **fingerprint }
       report['paths'] = paths unless paths.empty?
+      report.merge!(lists(parts))
+      totals = parts.fetch(:totals, {})
       report['totals'] = totals unless totals.empty?
+      report['kinds'] = Kinds.names
       JSON.pretty_generate(report)
     end
+
+    # { key => its list } of each of parts' LISTED keys that
+    # has one, as listed gives them.
+    def self.lists(parts)
+      LISTED.filter_map do |key|
+        taken = parts.fetch(key, {})
+        [key.to_s, listed(taken)] unless taken.empty?
+      end.to_h
+    end
+
+    # taken, { site => { path => count } }, as JSON lists it,
+    # eg { 'k.rb:2:2' => [{ path: [true, false], count: 1 }] }.
+    def self.listed(taken)
+      taken.transform_values do |counts|
+        counts.map { |path, count| { path:, count: } }
+      end
+    end
   end
 end

data/lib/path_coverage/kernel.rb

@@ -1,6 +1,7 @@
 require 'fileutils'
 require_relative 'calls'
 require_relative 'configuration'
+require_relative 'console_summary'
 require_relative 'json_writer'
 require_relative 'manifest'
 require_relative 'path_gaps'
@@ -10,7 +11,6 @@ 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
@@ -48,18 +48,26 @@ module PathCoverage
   # Starts from settings in env alone, for a run whose code
   # cannot be changed, eg one started by RUBYOPT=-r: covers
   # the comma-separated PATH_COVERAGE_COVER globs under
-  # PATH_COVERAGE_ROOT, writing the JSON report into
-  # PATH_COVERAGE_DIR and POSTing it to
+  # PATH_COVERAGE_ROOT, skipping any matching the
+  # comma-separated PATH_COVERAGE_SKIP globs, writing the JSON
+  # report into PATH_COVERAGE_DIR and POSTing it to
   # PATH_COVERAGE_COLLECTOR. Without a collector it
   # starts nothing, so RUBYOPT can be set for every run.
   def self.start_from_env(env, on_exit: method(:at_exit))
     return unless env.key?('PATH_COVERAGE_COLLECTOR')
 
-    start(on_exit:) do
+    start(on_exit:, &env_settings(env))
+  end
+
+  # The start block of the settings in env, as start_from_env
+  # reads them.
+  def self.env_settings(env)
+    covers = env.fetch('PATH_COVERAGE_COVER').split(',')
+    skips = env.fetch('PATH_COVERAGE_SKIP', '').split(',')
+    proc do
       root env.fetch('PATH_COVERAGE_ROOT')
-      env.fetch('PATH_COVERAGE_COVER').split(',').each do |glob|
-        cover glob
-      end
+      covers.each { |glob| cover glob }
+      skips.each { |glob| skip glob }
       coverage_dir env.fetch('PATH_COVERAGE_DIR')
       collector env.fetch('PATH_COVERAGE_COLLECTOR')
       report :post
@@ -105,9 +113,7 @@ module PathCoverage
     result = collect(files, config)
     methods = config.measures.include?(:methods)
     paths = methods ? @recorder.paths : nil
-    Render.run(
-      result.operands, files, config, paths, site_paths: result.paths
-    )
+    Render.run(result.operands, files, config, paths, **result.taken)
     return unless config.reporters.include?(:gaps)
 
     methods = path_methods_of(files, config)
@@ -130,23 +136,39 @@ module PathCoverage
     sites = merged_sites(files)
     result = Result.new(sites, @recorder.counts, @recorder.site_paths)
     FileUtils.mkdir_p(config.output_dir)
+    write_json(result, files, config)
+    result
+  end
+
+  # Writes result as the JSON report at config's json_path: its
+  # operands, site paths, paths a treatment rules out, and
+  # totals, and the method paths the recorder counted, so a
+  # render from the JSON alone has them, and config's
+  # fingerprint.
+  def self.write_json(result, files, config)
     report = PathsReport.of(result.paths, files)
     totals = totals(result, files, config)
-    path = config.json_path
-    JsonWriter.write(result.operands, path, report, totals:)
-    result
+    JsonWriter.write(result.operands, config.json_path, report,
+                     totals:, method_paths: @recorder.paths,
+                     outside: result.outside,
+                     fingerprint: config.fingerprint)
   end
 
   # The JSON report's totals, each [taken, possible] paths:
   # within each decision, and, when config measures methods,
-  # across each method's decisions too.
+  # within each method too; with groups configured, each group's
+  # own too, under groups.
   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)
+    measured = config.measures.include?(:methods)
+    methods = measured ? path_methods_of(files, config) : {}
+    paths = measured ? @recorder.paths : nil
+    totals = ConsoleSummary.totals(result.paths, methods, paths)
+    groups = config.groups
+    return totals if groups.empty?
+
+    summary = ConsoleSummary
+    own = summary.group_totals(result.paths, methods, paths, groups)
+    totals.merge('groups' => own)
   end
 
   # { full path => {source:, sites:} } for every covered file:

data/lib/path_coverage/kinds/base.rb

@@ -0,0 +1,71 @@
+module PathCoverage
+  module Kinds
+    # The hooks every kind has, each as most kinds need it; a
+    # kind extends Base and defines its own in place of any.
+    module Base
+      # The ways a site of this kind as a whole can be evaluated:
+      # as it can be nested in another.
+      def root_ways(node, fixed)
+        ways(node, fixed)
+      end
+
+      # Whether its leaves, nested in a site, need calls of their
+      # own in place of record calls; false for most.
+      def own_calls?
+        false
+      end
+
+      # The inserts for a site of this kind: its leaves' records,
+      # and its leave around them.
+      def site_inserts(site, condition)
+        Rewriter.record_inserts(site, condition) +
+          Rewriter.trail_inserts(site, condition)
+      end
+
+      # What a site of this kind's leave call wraps: the whole of
+      # it, for most.
+      def trailed(condition)
+        condition
+      end
+
+      # Its node in a site's tree, each leaf taking the next index
+      # of leaves: its operands' nodes, then its arms', if any.
+      def node(source, condition, outcomes, leaves)
+        built = [outcomes, leaves]
+        operands = SiteTree.operands_of(source, condition, *built)
+        SiteTree.arms(source, condition, operands, *built)
+      end
+
+      # The nodes its node stands for among its siblings' in a
+      # site's tree on a file's page: itself, for most.
+      def unfold(node)
+        [node]
+      end
+
+      # The inserts, besides its leaves' calls, for one nested in
+      # a site at its at-th leaf: none for most.
+      def inserts(_site, _inner, _at, _commands)
+        []
+      end
+
+      # nodes, the tree nodes of condition's operands, with any
+      # texts that repeat others cut: none for most.
+      def texted(_source, _condition, nodes)
+        nodes
+      end
+
+      # The text a site of this kind opens and closes with, as
+      # [opening, closing], eg ['{', '}'] for a block's braces.
+      # Most kinds have none, so ['', ''].
+      def brackets(_source, _site)
+        ['', '']
+      end
+
+      # Its operands' rows in a site's tree on a file's page, nil
+      # for most, whose operands branch from its operator.
+      def rows(_condition, _indent)
+        nil
+      end
+    end
+  end
+end