condition_coverage 0.0.1 → 0.0.3

data/lib/condition_coverage/html_file.rb

@@ -0,0 +1,159 @@
+require 'cgi/escape'
+require_relative 'html_template'
+
+module ConditionCoverage
+  # One covered file's HTML page: its source, with the numbers
+  # of the lines holding a condition as the one button that
+  # opens the condition's tree.
+  module HtmlFile
+    # The whole page for the file at path (relative to root),
+    # written at files/<path>.html, so it links back to the
+    # index one folder up for each folder in that.
+    def self.page(path, lines, trees)
+      HtmlTemplate.fill(
+        HtmlTemplate.asset('file.html'),
+        'path' => CGI.escapeHTML(path),
+        'index' => "#{'../' * (path.count('/') + 1)}index.html",
+        'style' => HtmlTemplate.asset('style.css'),
+        'script' => HtmlTemplate.asset('toggle.js'),
+        'listing' => listing(lines, trees)
+      )
+    end
+
+    # The source listing of lines, as SourceLines.of gives them:
+    # each run of lines sharing a span is one block, followed
+    # by its hidden tree. trees is { span's first line =>
+    # [SiteTree.of, ...] }.
+    def self.listing(lines, trees = {})
+      blocks = lines.chunk_while do |line, following|
+        line[:span] && line[:span] == following[:span]
+      end
+      body = blocks.map { |block| block(block, trees) }.join("\n")
+      %(<div class="code">\n#{body}\n</div>)
+    end
+
+    # A plain line, or the lines of one span behind one button
+    # with the span's tree straight after them.
+    def self.block(lines, trees)
+      first = lines[0]
+      return plain_line(first) if first[:span].nil?
+
+      number = first[:number]
+      site_trees = trees.fetch(number, [])
+      span_block(lines, site_trees.size) + tree(number, site_trees)
+    end
+
+    # The lines of one span: one button over all their numbers,
+    # and how many sites it opens when that is two or more,
+    # beside their code.
+    def self.span_block(lines, sites)
+      numbers = lines.map { |line| number(line[:number]) }.join
+      codes = lines.map { |line| code(line) }.join
+      srcs = %(<div class="srcs">#{codes}</div>)
+      content = site_count(sites) + numbers
+      %(<div class="block">#{button(lines[0], content)}#{srcs}</div>)
+    end
+
+    # The count of a button's sites, shown only for two or more.
+    def self.site_count(sites)
+      return '' if sites < 2
+
+      %(<span class="site-count" data-site-count="">#{sites}</span>)
+    end
+
+    HEADINGS = %w[condition true false gap].freeze
+
+    # The hidden tree of a span: a heading row, then each site's
+    # rows in a group of their own.
+    def self.tree(number, site_trees)
+      groups = site_trees.map do |site|
+        rows = site_rows(site).join
+        %(<div class="site" data-site="">#{rows}</div>)
+      end
+      id = "tree-#{number}"
+      body = [heading_row, *groups].join
+      %(<div class="tree" id="#{id}" hidden="hidden">#{body}</div>)
+    end
+
+    # The row naming each column of a tree.
+    def self.heading_row
+      cells = HEADINGS.map { |name| %(<span>#{name}</span>) }.join
+      %(<div class="row headings" data-heading="">#{cells}</div>)
+    end
+
+    # A site's operator row, then the rows of its operands.
+    def self.site_rows(site)
+      row = %(<div class="row">#{operator(site)}</div>)
+      [row, *operand_rows(site, '')]
+    end
+
+    # The rows of a condition's operands, each branching from
+    # its operator after indent; a nested condition's operands
+    # 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 ? '└─ ' : '├─ ')
+        next [operand_row(operand, branch)] unless operand[:operator]
+
+        nested = operand_rows(operand, indent + (tip ? '   ' : '│  '))
+        [subtree_row(operand, branch), *nested]
+      end
+    end
+
+    # A nested condition's row: its branch and its operator.
+    def self.subtree_row(condition, branch)
+      cells = branch_cell(branch) + operator(condition)
+      %(<div class="row" data-subtree="">#{cells}</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, true and false
+    # counts, and gap.
+    def self.operand_row(operand, branch)
+      cells = %i[text truthy falsy gap].map do |name|
+        value = CGI.escapeHTML(operand[name].to_s)
+        %(<span class="#{name}" data-#{name}="">#{value}</span>)
+      end
+      lead = branch_cell(branch)
+      %(<div class="row" data-operand="">#{lead}#{cells.join}</div>)
+    end
+
+    # The cell drawing a row's branch from its operator.
+    def self.branch_cell(branch)
+      %(<span class="branch" data-branch="">#{branch}</span>)
+    end
+
+    # A line with no condition: its number, then its code.
+    def self.plain_line(line)
+      %(<div class="line">#{number(line[:number])}#{code(line)}</div>)
+    end
+
+    # The closed button over a span's numbers, opening the tree
+    # named after its first line.
+    def self.button(first, numbers)
+      [
+        %(<button type="button" class="lnum"),
+        %( data-status="#{first[:status]}" aria-expanded="false"),
+        %( aria-controls="tree-#{first[:number]}">#{numbers}</button>)
+      ].join
+    end
+
+    # One line's number.
+    def self.number(number)
+      %(<span class="lineno" data-line="#{number}">#{number}</span>)
+    end
+
+    # One line's code, escaped.
+    def self.code(line)
+      text = CGI.escapeHTML(line[:text])
+      %(<span class="src" data-src="">#{text}</span>)
+    end
+  end
+end

data/lib/condition_coverage/html_index.rb

@@ -0,0 +1,43 @@
+require 'cgi/escape'
+require_relative 'html_template'
+
+module ConditionCoverage
+  # The HTML index page: one sortable row per covered file,
+  # each linking to that file's own page.
+  module HtmlIndex
+    # The whole index page: the files table, sortable by any
+    # column, with one row per Summary.files row.
+    def self.page(rows)
+      HtmlTemplate.fill(
+        HtmlTemplate.asset('index.html'),
+        'style' => HtmlTemplate.asset('style.css'),
+        'script' => HtmlTemplate.asset('sort.js'),
+        'rows' => rows.map { |row| row(row) }.join("\n")
+      )
+    end
+
+    # 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),
+        cell(row[:sites], row[:sites]),
+        cell(row[:percent], seen),
+        cell(row[:missing], row[:missing])
+      ]
+    end
+
+    # One table cell, sorted by sort_value, showing content.
+    def self.cell(sort_value, content)
+      %(<td data-sort="#{sort_value}">#{content}</td>)
+    end
+  end
+end

data/lib/condition_coverage/html_report.rb

@@ -0,0 +1,46 @@
+require 'fileutils'
+require_relative 'html_file'
+require_relative 'html_index'
+require_relative 'site_tree'
+require_relative 'source_lines'
+require_relative 'summary'
+
+module ConditionCoverage
+  # 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. files is { full path => {source:, sites:} }
+    # for each covered file, as the kernel parsed it.
+    def self.write(result, files, config)
+      dir = config.output_dir
+      index = HtmlIndex.page(Summary.files(result))
+      File.write("#{dir}/index.html", index)
+      files.each do |full_path, parsed|
+        path = config.relative(full_path)
+        write_page("#{dir}/files/#{path}.html", path, parsed, result)
+      end
+    end
+
+    # Writes one file's page to out.
+    def self.write_page(out, path, parsed, result)
+      source = parsed[:source]
+      lines = SourceLines.of(source, parsed[:sites], result.operands)
+      trees = trees(source, parsed[:sites], lines, result.operands)
+      FileUtils.mkdir_p(File.dirname(out))
+      File.write(out, HtmlFile.page(path, lines, trees))
+    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, operands)
+      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, operands.fetch(site))
+        trees[first] << tree
+      end
+      trees
+    end
+  end
+end

data/lib/condition_coverage/html_template.rb

@@ -0,0 +1,20 @@
+module ConditionCoverage
+  # 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/condition_coverage/json_writer.rb

@@ -0,0 +1,13 @@
+require 'json'
+
+module ConditionCoverage
+  # The base reporter: the result as raw JSON, which every
+  # other reporter can read back.
+  module JsonWriter
+    # Writes result to path as {"sites": {site: [counts, ...]}}.
+    def self.write(result, path)
+      json = JSON.pretty_generate('sites' => result.operands)
+      File.write(path, json)
+    end
+  end
+end

data/lib/condition_coverage/kernel.rb

@@ -0,0 +1,111 @@
+require 'fileutils'
+require_relative 'configuration'
+require_relative 'gaps'
+require_relative 'html_report'
+require_relative 'json_writer'
+require_relative 'manifest'
+require_relative 'recorder'
+require_relative 'result'
+require_relative 'rewriter'
+
+# Condition 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 ConditionCoverage
+  @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
+
+  # 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
+
+  # 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|
+      ConditionCoverage.instrumented(path, ConditionCoverage.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] = parse(path, config)
+    rewritten = Rewriter.rewrite(parsed[:source], parsed[:sites])
+    RubyVM::InstructionSequence.compile(rewritten, path, path)
+  end
+
+  # The source and sites of the covered file at path.
+  def self.parse(path, config)
+    source = File.read(path)
+    { source:, sites: Manifest.sites(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.
+  def self.report(config)
+    files = parsed_files(config)
+    result = Result.new(merged_sites(files), @recorder.counts)
+    FileUtils.mkdir_p(config.output_dir)
+    JsonWriter.write(result, config.json_path)
+    run_reporters(result, files, config)
+  end
+
+  # Runs each reporter chosen in the start block.
+  def self.run_reporters(result, files, config)
+    reporters = config.reporters
+    if reporters.include?(:gaps)
+      Gaps.lines(result).each { |line| puts line }
+    end
+    return unless reporters.include?(:html)
+
+    HtmlReport.write(result, files, config)
+  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) { 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

data/lib/condition_coverage/manifest.rb

@@ -0,0 +1,107 @@
+require 'prism'
+require_relative 'condition'
+require_relative 'site'
+
+module ConditionCoverage
+  # Finds every condition site in source without running it: each
+  # outermost &&, ||, and or or, 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
+
+    # Collects each site and its Condition.
+    class ConditionSites < Prism::Visitor
+      # Starts with no sites found.
+      def initialize(path)
+        @path = path
+        @sites = {}
+        @commands = []
+        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 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.
+      def add_site(node)
+        site = Site.of(@path, node)
+        @sites[site] = nil
+        outer = @commands
+        @commands = []
+        condition = condition_of(node)
+        @sites[site] = condition.with(commands: @commands)
+        @commands = outer
+      end
+
+      # node as a Condition, operands and all, named by its
+      # operator as written.
+      def condition_of(node)
+        operator = node.operator
+        Condition.new(operator:, operands: operands_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
+
+      # 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 among its site's commands
+      # if it is a command call.
+      def leaf(operand)
+        operand.accept(self)
+        loc = operand.location
+        range = loc.start_offset...loc.end_offset
+        @commands << range if command?(operand)
+        range
+      end
+
+      # True for a call to a named method with arguments and no
+      # parentheses, eg `id.include? 'N'`, but not `id.size == 6`.
+      def command?(node)
+        node.type == :call_node && node.arguments &&
+          node.opening_loc.nil? && node.name.match?(/\A[a-z_]/i)
+      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/condition_coverage/recorder.rb

@@ -0,0 +1,24 @@
+module ConditionCoverage
+  # Records the outcome of each instrumented operand.
+  class Recorder
+    # Starts with no outcomes counted.
+    def initialize
+      @counts = Hash.new do |counts, key|
+        counts[key] = { truthy: 0, falsy: 0 }
+      end
+    end
+
+    # The truthy and falsy counts of every operand recorded so
+    # far, keyed by [site, index]; an operand that never ran
+    # has no entry.
+    attr_reader :counts
+
+    # Counts value's outcome and returns it unchanged, so the
+    # condition around it behaves exactly as uninstrumented.
+    def record(site, index, value)
+      outcome = value ? :truthy : :falsy
+      @counts[[site, index]][outcome] += 1
+      value
+    end
+  end
+end

data/lib/condition_coverage/result.rb

@@ -0,0 +1,31 @@
+module ConditionCoverage
+  # What a run found: every site the manifest knows of, with
+  # the counts its operands were recorded with. Every
+  # reporter builds on this.
+  class Result
+    NEVER_RAN = { truthy: 0, falsy: 0 }.freeze
+
+    # sites is { site => Condition }, from the manifest;
+    # counts is { [site, index] => counts }, from the recorder.
+    def initialize(sites, counts)
+      @sites = sites
+      @counts = counts
+    end
+
+    # { site => [counts of operand 0, counts of operand 1, ...] },
+    # with zero counts for an operand that never ran.
+    def operands
+      @sites.to_h do |site, condition|
+        size = condition.leaves.size
+        [site, Array.new(size) { |i| counts_of(site, i) }]
+      end
+    end
+
+    private
+
+    # The recorded counts of one operand, or zeros.
+    def counts_of(site, index)
+      @counts.fetch([site, index], NEVER_RAN)
+    end
+  end
+end

data/lib/condition_coverage/rewriter.rb

@@ -0,0 +1,39 @@
+module ConditionCoverage
+  # Instruments source text so that each leaf operand records its
+  # outcome when the code runs. It inserts text at the byte
+  # ranges the manifest found, and never parses.
+  module Rewriter
+    # Returns source with each operand in sites wrapped in a
+    # record call. Only text is inserted, never a newline, so
+    # backtrace line numbers still match the file on disk.
+    def self.rewrite(source, sites)
+      inserts = sites.flat_map do |site, condition|
+        condition.leaves.each_with_index.flat_map do |range, index|
+          command = condition.commands.include?(range)
+          wrap(site, index, range, command)
+        end
+      end
+      apply(source.dup, inserts)
+    end
+
+    # The two inserts that wrap one operand in a record call. A
+    # command call is parenthesised, as it is no bare argument;
+    # nothing else is, since parentheses make a statement, which
+    # gives its line a line-coverage count of its own.
+    def self.wrap(site, index, range, command)
+      open, close = command ? ['(', '))'] : ['', ')']
+      call = "ConditionCoverage.record(#{site.inspect}, #{index}, "
+      [[range.begin, call + open], [range.end, close]]
+    end
+
+    # Splices each [offset, text] insert into source,
+    # last offset first so earlier offsets stay valid.
+    def self.apply(source, inserts)
+      sorted = inserts.sort_by { |offset, _| -offset }
+      sorted.each do |offset, text|
+        source.bytesplice(offset, 0, text)
+      end
+      source
+    end
+  end
+end

data/lib/condition_coverage/site.rb

@@ -0,0 +1,11 @@
+module ConditionCoverage
+  # Names a condition by where it starts in its file, so the
+  # rewriter and the manifest agree on which site is which.
+  module Site
+    # "path:line:column" of node, eg "k.rb:2:2".
+    def self.of(path, node)
+      loc = node.location
+      "#{path}:#{loc.start_line}:#{loc.start_column}"
+    end
+  end
+end

data/lib/condition_coverage/site_tree.rb

@@ -0,0 +1,39 @@
+require_relative 'condition'
+require_relative 'gaps'
+
+module ConditionCoverage
+  # The tree shown under a site's line on its file's page.
+  module SiteTree
+    # { operator:, operands: [{text:, truthy:, falsy:, gap:}] }
+    # for one site, a nested condition being an operand of the
+    # same { operator:, operands: } shape. Each leaf has its
+    # text cut from source at its manifest byte range, its
+    # counts, and its gap label in the same words as the
+    # terminal gaps list (nil for none).
+    def self.of(source, condition, counts)
+      node(source, condition, counts.each)
+    end
+
+    # The tree of condition, each leaf taking the next of
+    # counts, so leaves pair with counts left to right.
+    def self.node(source, condition, counts)
+      operands = condition.operands.map do |operand|
+        if operand.is_a?(Condition)
+          node(source, operand, counts)
+        else
+          leaf(source, operand, counts.next)
+        end
+      end
+      { operator: condition.operator, operands: }
+    end
+
+    # One leaf's text, counts and gap.
+    def self.leaf(source, range, counts)
+      {
+        text: source.byteslice(range),
+        truthy: counts[:truthy], falsy: counts[:falsy],
+        gap: Gaps.operand_gap(counts).first
+      }
+    end
+  end
+end