path_coverage 0.0.1 → 0.0.2

data/lib/path_coverage/html_paths.rb

@@ -0,0 +1,138 @@
+require 'cgi/escape'
+require 'prism'
+require_relative 'path_gaps'
+
+module PathCoverage
+  # SPIKE: the path grids of one covered file's page, hidden in
+  # the page until side.js moves them into the rail. Each grid
+  # has a row per decision, to sit level with that decision's
+  # line, and a column per possible path, never-taken first.
+  module HtmlPaths
+    # The hidden grids of every method in methods.
+    def self.grids(source, methods, paths)
+      ends = end_lines(source)
+      arms = arm_lines(source)
+      methods.map do |site, method|
+        grid(site, method, paths.fetch(site, {}), ends, arms)
+      end.join("\n")
+    end
+
+    # { an if's first line => its parts' lines } for every if:
+    # head, its if and predicate; then, its then arm; else, its
+    # else (or elsif) keyword through its arm; end, its end line.
+    # Each is [first, last], nil when absent; a modifier if or
+    # ternary is all head.
+    def self.arm_lines(source)
+      arms = {}
+      walk = lambda do |node|
+        arms[node.location.start_line] = if_parts(node) if node.type == :if_node
+        node.compact_child_nodes.each { |child| walk.call(child) }
+      end
+      walk.call(Prism.parse(source).value)
+      arms
+    end
+
+    # The lines of an if's parts, as arm_lines gives them.
+    def self.if_parts(node)
+      start = node.location.start_line
+      return { head: [start, start] } if node.end_keyword_loc.nil?
+
+      last = node.end_keyword_loc.start_line
+      then_arm = span(node.statements)
+      else_part = else_lines(node.subsequent, last)
+      body = [then_arm&.first, else_part&.first, last].compact.min
+      {
+        head: [start, [start, body - 1].max], then: then_arm,
+        else: else_part, end: [last, last]
+      }
+    end
+
+    # The lines from an else or elsif keyword to the end of its
+    # arm, the line before the if's end for an elsif.
+    def self.else_lines(otherwise, last)
+      return nil if otherwise.nil?
+      return [otherwise.location.start_line, last - 1] if otherwise.type == :if_node
+
+      first = otherwise.else_keyword_loc.start_line
+      [first, otherwise.statements ? otherwise.statements.location.end_line : first]
+    end
+
+    # The first and last lines of statements, nil for none.
+    def self.span(statements)
+      return nil if statements.nil?
+
+      loc = statements.location
+      [loc.start_line, loc.end_line]
+    end
+
+    # { def's first line => its last line } for every def.
+    def self.end_lines(source)
+      ends = {}
+      walk = lambda do |node|
+        if node.type == :def_node
+          loc = node.location
+          ends[loc.start_line] = loc.end_line
+        end
+        node.compact_child_nodes.each { |child| walk.call(child) }
+      end
+      walk.call(Prism.parse(source).value)
+      ends
+    end
+
+    # One method's grid: its calls row, level with its def, then
+    # a row per decision, level with that decision's line.
+    def self.grid(site, method, taken, ends, arms)
+      first = site.split(':')[-2].to_i
+      every = PathGaps.possible(method.decisions)
+      ordered = every.each_with_index.sort_by do |path, i|
+        [taken.key?(path) ? 1 : 0, i]
+      end.map(&:first)
+      missing = every.count { |path| !taken.key?(path) }
+      status = missing.zero? ? 'covered' : 'gaps'
+      rows = [calls_row(first, ordered, taken, method, every.size - missing)]
+      method.decisions.each_with_index do |decision, i|
+        rows << decision_row(decision, i, ordered, taken, arms)
+      end
+      attrs = [
+        %(id="paths-#{first}" data-first="#{first}"),
+        %(data-col="#{site.split(':').last}"),
+        %(data-last="#{ends.fetch(first, first)}" data-status="#{status}")
+      ].join(' ')
+      %(<div class="pathgrid" #{attrs} hidden="hidden">#{rows.join}</div>)
+    end
+
+    # The row level with the def: how many calls took each path,
+    # never-taken ones marked.
+    def self.calls_row(first, ordered, taken, method, seen)
+      cells = ordered.map do |path|
+        calls = taken.fetch(path, 0)
+        css = calls.zero? ? 'pcell never' : 'pcell taken'
+        %(<span class="#{css}">#{calls.zero? ? '0' : calls}</span>)
+      end
+      name = CGI.escapeHTML(method.name.to_s)
+      label = %(<span class="plabel">#{seen}/#{ordered.size}</span>)
+      title = %( title="#{name}: #{seen} of #{ordered.size} paths taken")
+      %(<div class="prow calls" data-line="#{first}"#{title}>#{label}#{cells.join}</div>)
+    end
+
+    # The row level with a decision: T or F for each path that
+    # makes it, those of never-taken paths marked, blank for a
+    # path that ended before it.
+    def self.decision_row(decision, index, ordered, taken, arms)
+      cells = ordered.map do |path|
+        outcome = path[index]
+        next '<span class="pcell ended"></span>' if outcome.nil?
+
+        never = taken.key?(path) ? '' : ' never'
+        %(<span class="pcell #{outcome}#{never}">#{outcome ? 'T' : 'F'}</span>)
+      end
+      label = %(<span class="plabel">#{decision.line}</span>)
+      arm = arms.fetch(decision.line, {})
+      parts = %i[head then else end].map do |part|
+        %(data-#{part}="#{arm[part]&.join(',')}")
+      end
+      data = [%(data-line="#{decision.line}"), *parts].join(' ')
+      %(<div class="prow" #{data}>#{label}#{cells.join}</div>)
+    end
+  end
+end

data/lib/path_coverage/html_report.rb

@@ -0,0 +1,103 @@
+require 'fileutils'
+require_relative 'html_file'
+require_relative 'html_index'
+require_relative 'html_paths'
+require_relative 'path_manifest'
+require_relative 'site_tree'
+require_relative 'source_lines'
+require_relative 'summary'
+
+module PathCoverage
+  # The :html reporter: index.html, and files/<path>.html for
+  # each covered file, written to the configuration's
+  # output_dir.
+  module HtmlReport
+    # 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.
+    def self.write(operands, files, config, paths = nil, site_paths:)
+      dir = config.output_dir
+      index = HtmlIndex.page(Summary.files(operands))
+      File.write("#{dir}/index.html", index)
+      files.each do |full_path, parsed|
+        path = config.relative(full_path)
+        out = "#{dir}/files/#{path}.html"
+        # simplecov:disable
+        grids = paths ? path_grids(path, parsed, paths) : ''
+        # simplecov:enable
+        write_page(out, path, parsed, [operands, site_paths], grids)
+      end
+    end
+
+    # simplecov:disable
+    # SPIKE: the hidden path grids of one file's methods.
+    def self.path_grids(path, parsed, paths)
+      source = parsed[:source]
+      methods = PathManifest.methods(source, path)
+      HtmlPaths.grids(source, methods, paths)
+    end
+    # simplecov:enable
+
+    # Writes one file's page to out, from its sites' operand
+    # counts and paths.
+    def self.write_page(out, path, parsed,
+                        (operands, site_paths), grids)
+      source, sites = parsed.values_at(:source, :sites)
+      lines = SourceLines.of(source, sites, operands)
+      trees = trees(source, sites, lines, site_paths)
+      FileUtils.mkdir_p(File.dirname(out))
+      File.write(out, HtmlFile.page(path, lines, trees, grids))
+    end
+
+    # { first line of a span => [SiteTree.of, ...] } for the
+    # sites of one file, each under the span its line is in.
+    def self.trees(source, sites, lines, site_paths)
+      trees = Hash.new { |all, first| all[first] = [] }
+      sites.each do |site, condition|
+        first = lines[SourceLines.line_of(site) - 1][:span].begin
+        tree = SiteTree.of(source, condition, site_paths.fetch(site))
+        trees[first] << located(source, condition, tree)
+      end
+      trees
+    end
+
+    # simplecov:disable
+    # SPIKE: tree with an at: of [line, column, line, column]
+    # 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.
+    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
+      end
+      tree.merge(at: at(source, condition.extent), operands:)
+    end
+
+    # An arm's node with its at:, 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:)
+    end
+
+    # [line, column, line, column] of the byte range in source.
+    def self.at(source, range)
+      [*position(source, range.begin), *position(source, range.end)]
+    end
+
+    # [line, column] of a byte offset in source.
+    def self.position(source, offset)
+      before = source.byteslice(0, offset)
+      newline = before.rindex("\n")
+      column = before.length - (newline ? newline + 1 : 0)
+      [before.count("\n") + 1, column]
+    end
+    # simplecov:enable
+  end
+end

data/lib/path_coverage/html_template.rb

@@ -0,0 +1,20 @@
+module PathCoverage
+  # The HTML report's page templates, styles and scripts, kept
+  # as files beside this one, and the filling of their slots.
+  module HtmlTemplate
+    DIR = File.join(__dir__, 'html')
+
+    # The text of one of the report's template, style or script
+    # files.
+    def self.asset(name)
+      File.read(File.join(DIR, name))
+    end
+
+    # template with each {{name}} replaced by values[name].
+    def self.fill(template, values)
+      template.gsub(/\{\{(\w+)\}\}/) do
+        values.fetch(Regexp.last_match(1))
+      end
+    end
+  end
+end

data/lib/path_coverage/html_tree.rb

@@ -0,0 +1,137 @@
+require 'cgi/escape'
+
+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
+    # A bullet marks a path taking an arm.
+    TAKEN = { true => [0x2022].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.
+    def self.of(number, site_trees, open)
+      groups = site_trees.map do |site|
+        rows = site_rows(site).join
+        %(<div class="site" data-site="">#{rows}</div>)
+      end
+      hidden = open ? '' : ' hidden="hidden"'
+      body = groups.join
+      %(<div class="tree" id="tree-#{number}"#{hidden}>#{body}</div>)
+    end
+
+    # A site's row, naming its operator and each path's count,
+    # then the rows of its operands.
+    def self.site_rows(site)
+      counts = count_cells(site[:counts])
+      [row(at(site), operator(site), counts), *operand_rows(site, '')]
+    end
+
+    # One cell per path's count, a path never taken marked as a
+    # gap.
+    def self.count_cells(counts)
+      counts.map do |count|
+        css = count.zero? ? 'count never' : 'count'
+        %(<span class="#{css}" data-count="">#{count}</span>)
+      end.join
+    end
+
+    # One cell per path, naming each with names.
+    def self.cells(values, names = OUTCOMES)
+      values.map do |value|
+        %(<span class="cell" data-cell="">#{names[value]}</span>)
+      end.join
+    end
+
+    # SPIKE: the data-at attribute of a node located in its
+    # source, '' for one that is not.
+    def self.at(node)
+      node[:at] ? %( data-at="#{node[:at].join(',')}") : ''
+    end
+
+    # 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.
+    def self.operand_rows(condition, indent)
+      last = condition[:operands].size - 1
+      condition[:operands].each_with_index.flat_map do |operand, i|
+        tip = i == last
+        branch = indent + (tip ? '└─ ' : '├─ ')
+        under = indent + (tip ? '   ' : '│  ')
+        node_rows(operand, branch, under, condition[:operator])
+      end
+    end
+
+    # The rows of one operand of a condition whose operator is
+    # choice, branching after branch, any operands of its own
+    # indented to under.
+    def self.node_rows(operand, branch, under, choice)
+      if operand.key?(:arm)
+        return arm_rows(operand, branch, under, choice)
+      end
+      return [operand_row(operand, branch)] unless operand[:operator]
+
+      [subtree_row(operand, branch), *operand_rows(operand, under)]
+    end
+
+    # An arm's row: a ternary's, ? for then and : for else, an
+    # arm holding a condition showing the condition's operator
+    # and value, its operands below, a plain arm its text; an
+    # if's named then or else, as its text is statements. A
+    # 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)
+      text = CGI.escapeHTML(arm_label(arm, choice))
+      lead = branch_cell(branch) +
+             %(<span class="arm" data-label="">#{text}</span>)
+      row = row(%( data-arm=""#{at(arm)}), lead, values)
+      body ? [row, *operand_rows(body, under)] : [row]
+    end
+
+    # 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'
+
+      mark = arm[:arm] == :then ? '?' : ':'
+      body = arm[:body]
+      "#{mark} #{body ? body[:operator] : arm[:text]}"
+    end
+
+    # A nested condition's row: its branch, its operator, and
+    # its value on each path.
+    def self.subtree_row(condition, branch)
+      lead = branch_cell(branch) + operator(condition)
+      attrs = %( data-subtree=""#{at(condition)})
+      row(attrs, lead, cells(condition[:cells]))
+    end
+
+    # A row of the grid, with attrs, lead's cells naming it,
+    # then values, its cells for each path.
+    def self.row(attrs, lead, values)
+      %(<div class="row"#{attrs}>#{lead}#{values}</div>)
+    end
+
+    # The cell naming a condition's operator.
+    def self.operator(condition)
+      name = CGI.escapeHTML(condition[:operator])
+      %(<span class="operator" data-operator="">#{name}</span>)
+    end
+
+    # One operand's row: its branch, text, and its outcome on
+    # each path.
+    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]))
+    end
+
+    # The cell drawing a row's branch from its operator.
+    def self.branch_cell(branch)
+      %(<span class="branch" data-branch="">#{branch}</span>)
+    end
+  end
+end

data/lib/path_coverage/json_writer.rb

@@ -0,0 +1,21 @@
+require 'json'
+
+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))
+    end
+
+    # operands, and any paths, as the JSON report's text.
+    def self.json(operands, paths = {})
+      report = { 'sites' => operands }
+      report['paths'] = paths unless paths.empty?
+      JSON.pretty_generate(report)
+    end
+  end
+end

data/lib/path_coverage/kernel.rb

@@ -0,0 +1,179 @@
+require 'fileutils'
+require_relative 'configuration'
+require_relative 'json_writer'
+require_relative 'manifest'
+require_relative 'path_gaps'
+require_relative 'path_manifest'
+require_relative 'paths_report'
+require_relative 'recorder'
+require_relative 'render'
+require_relative 'result'
+require_relative 'rewriter'
+
+# Path coverage for Ruby. This file is the kernel: it loads
+# before any covered file and is never itself instrumented, since
+# an instrumented recorder would record itself.
+module PathCoverage
+  @recorder = Recorder.new
+  @config = nil
+  # { full path => {source:, sites:} } of each covered file
+  # parsed as it loaded, so the exit report need not read it
+  # again.
+  @parsed = {}
+
+  # The one recorder that every instrumented operand reports to.
+  def self.recorder
+    @recorder
+  end
+
+  # The configuration of the latest start, which the load
+  # hook consults; nil before the first start.
+  def self.config
+    @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
+  # a report as their own process exits.
+  def self.start(on_exit: method(:at_exit), &)
+    config = Configuration.new(&)
+    install_hook if @config.nil?
+    @config = config
+    on_exit.call { report(config) }
+  end
+
+  # 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_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
+      root env.fetch('PATH_COVERAGE_ROOT')
+      env.fetch('PATH_COVERAGE_COVER').split(',').each do |glob|
+        cover glob
+      end
+      coverage_dir env.fetch('PATH_COVERAGE_DIR')
+      collector env.fetch('PATH_COVERAGE_COLLECTOR')
+      report :post
+    end
+  end
+
+  # Routes every later load through instrumented, under
+  # whichever configuration is current. Installed once: a
+  # second definition would warn that it was redefined.
+  def self.install_hook
+    iseq = RubyVM::InstructionSequence
+    iseq.singleton_class.define_method(:load_iseq) do |path|
+      PathCoverage.instrumented(path, PathCoverage.config)
+    end
+  end
+
+  # The compiled, rewritten code of path, or nil for a path
+  # config does not cover, which Ruby then loads as normal.
+  def self.instrumented(path, config)
+    return unless config.covers?(path)
+
+    parsed = @parsed[path] = Manifest.parse(path, config)
+    methods = path_methods(path, parsed[:source], config)
+    sites = parsed[:sites]
+    rewritten = Rewriter.rewrite(parsed[:source], sites, methods)
+    RubyVM::InstructionSequence.compile(rewritten, path, path)
+  end
+
+  # The methods of the covered file at path whose paths are
+  # counted, none unless config measures paths.
+  def self.path_methods(path, source, config)
+    return {} unless config.measures.include?(:paths)
+
+    PathManifest.methods(source, config.relative(path))
+  end
+
+  # Writes the JSON report, then runs the chosen reporters, for
+  # every covered file whether or not the run loaded it, into
+  # coverage_dir, created first if need be. The paths never
+  # taken follow the condition gaps.
+  def self.report(config)
+    files = parsed_files(config)
+    result = collect(files, config)
+    paths = config.measures.include?(:paths) ? @recorder.paths : nil
+    Render.run(
+      result.operands, files, config, paths, site_paths: result.paths
+    )
+    return unless config.reporters.include?(:gaps)
+
+    methods = path_methods_of(files, config)
+    PathGaps.lines(methods, @recorder.paths).each { |line| puts line }
+  end
+
+  # The methods whose paths are counted of every covered file,
+  # in one manifest.
+  def self.path_methods_of(files, config)
+    all = files.map do |path, parsed|
+      path_methods(path, parsed[:source], config)
+    end
+    all.reduce({}, :merge)
+  end
+
+  # The Result of every covered file, with the counts and site
+  # paths this run recorded, once its operands and paths are
+  # written as the JSON report.
+  def self.collect(files, config)
+    sites = merged_sites(files)
+    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)
+    result
+  end
+
+  # { full path => {source:, sites:} } for every covered file:
+  # as parsed when it loaded, or parsed now for a file the run
+  # never loaded.
+  def self.parsed_files(config)
+    config.files.to_h do |path|
+      [path, @parsed.fetch(path) { Manifest.parse(path, config) }]
+    end
+  end
+
+  # The sites of every covered file, in one manifest.
+  def self.merged_sites(files)
+    files.values.map { |parsed| parsed[:sites] }.reduce({}, :merge)
+  end
+end