path_coverage 0.0.1 → 0.0.2

data/lib/path_coverage/render.rb

@@ -0,0 +1,92 @@
+require 'json'
+require_relative 'gaps'
+require_relative 'html_report'
+require_relative 'manifest'
+require_relative 'merge'
+require_relative 'paths_report'
+require_relative 'post'
+require_relative 'site_paths'
+
+module PathCoverage
+  # The reporters, run from operands alone: needing nothing the
+  # run recorded beyond them, they can run in another process.
+  module Render
+    # Runs each reporter chosen in config. operands and
+    # site_paths are as Result gives them; files is { full path
+    # => {source:, sites:} } for each covered file.
+    def self.run(operands, files, config, paths = nil, site_paths: {})
+      site_paths = every_site(site_paths, files)
+      reporters = config.reporters
+      gaps(operands, files, site_paths) if reporters.include?(:gaps)
+      if reporters.include?(:html)
+        HtmlReport.write(operands, files, config, paths, site_paths:)
+      end
+      return unless reporters.include?(:post)
+
+      report = PathsReport.of(site_paths, files)
+      Post.deliver(operands, config.collector_url, report)
+    end
+
+    # site_paths with every site in files that it lacks, eg
+    # from a JSON report with no paths, given each possible
+    # path at a count of zero: unable to say which paths such
+    # a site took, the report claims none.
+    def self.every_site(site_paths, files)
+      none = files.values.each_with_object({}) do |parsed, all|
+        parsed[:sites].each do |site, condition|
+          all[site] = SitePaths.possible(condition).map do |path|
+            { path:, count: 0 }
+          end
+        end
+      end
+      none.merge(site_paths)
+    end
+
+    # Prints the gap lines: each path a site never took, each
+    # leaf named by its text in files.
+    def self.gaps(operands, files, site_paths)
+      texts = PathsReport.texts(files)
+      lines = Gaps.lines(operands, paths: site_paths, texts:)
+      lines.each { |line| puts line }
+    end
+
+    # Runs the reporters chosen in config from the JSON reports
+    # at paths, their counts merged, parsing each covered file
+    # afresh. paths is config.json_path alone by default.
+    def self.from_json(config, paths = [config.json_path])
+      operands = Merge.operands(paths.map { |path| read(path) })
+      site_paths = Merge.paths(paths.map { |path| paths_of(path) })
+      files = config.files.to_h do |path|
+        [path, Manifest.parse(path, config)]
+      end
+      run(operands, files, config, site_paths:)
+    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.
+    def self.read(path)
+      json = JSON.parse(File.read(path))
+      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/result.rb

@@ -0,0 +1,59 @@
+require_relative 'site_paths'
+
+module PathCoverage
+  # 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 } and site_paths is
+    # { site => { path => evaluations } }, both from the
+    # recorder.
+    def initialize(sites, counts, site_paths = {})
+      @sites = sites
+      @counts = counts
+      @site_paths = site_paths
+    end
+
+    # { site => [{ path:, count: }, ...] }: every possible path
+    # of each site, as SitePaths gives them, with the number of
+    # evaluations that took it, zero for one never taken.
+    def paths
+      @sites.to_h do |site, condition|
+        taken = @site_paths.fetch(site, {})
+        all = SitePaths.possible(condition).map do |path|
+          { path:, count: taken.fetch(path, 0) }
+        end
+        [site, all]
+      end
+    end
+
+    # { site => [counts of operand 0, counts of operand 1, ...] },
+    # with zero counts for an operand that never ran, and
+    # only: naming the one outcome a fixed leaf can have.
+    def operands
+      @sites.to_h do |site, condition|
+        leaves = condition.leaves.each_with_index.map do |range, i|
+          leaf(site, condition, range, i)
+        end
+        [site, leaves]
+      end
+    end
+
+    private
+
+    # The counts of one leaf, with only: when it is fixed.
+    def leaf(site, condition, range, index)
+      counts = counts_of(site, index)
+      only = condition.fixed[range]
+      only ? counts.merge(only:) : counts
+    end
+
+    # The recorded counts of one operand, or zeros.
+    def counts_of(site, index)
+      @counts.fetch([site, index], NEVER_RAN)
+    end
+  end
+end

data/lib/path_coverage/rewriter.rb

@@ -0,0 +1,120 @@
+module PathCoverage
+  # 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
+    PATH_NAME = '__path_coverage_path'.freeze
+
+    # Returns source with each operand in sites wrapped in a
+    # record call, each site as a whole in a leave call that
+    # enters it first, and each method in methods starting a
+    # path that its decisions are wrapped in decide calls to add
+    # to. Only text is inserted, never a newline, so backtrace
+    # line numbers still match the file on disk.
+    def self.rewrite(source, sites, methods = {})
+      inserts = sites.flat_map do |site, condition|
+        record_inserts(site, condition) +
+          trail_inserts(site, condition)
+      end
+      apply(source.dup, inserts + path_inserts(methods))
+    end
+
+    # The inserts that wrap each of site's leaves in a record
+    # call, innermost of all.
+    def self.record_inserts(site, condition)
+      condition.leaves.each_with_index.flat_map do |range, index|
+        command = condition.commands.include?(range)
+        wrap(record_call(site, index), range, command, 0)
+      end
+    end
+
+    WORD_OPERATORS = %w[and or].freeze
+
+    # The inserts that wrap site as a whole in a leave call,
+    # outside its leaves' record calls, whose first argument
+    # enters the site before any leaf runs, so each evaluation
+    # fills in a trail of its own. An and or or is held in
+    # parentheses, being, like a command call, no bare argument.
+    def self.trail_inserts(site, condition)
+      enter = "PathCoverage.enter(#{site.inspect}, " \
+              "#{condition.leaves.size})"
+      call = "PathCoverage.leave(#{enter}, "
+      wrapped = trailed(condition)
+      nested = wrapped.is_a?(Condition)
+      word = nested && WORD_OPERATORS.include?(wrapped.operator)
+      wrap(call, nested ? wrapped.extent : wrapped, word, 1)
+    end
+
+    # What a site's leave call wraps: an if's predicate, a leaf's
+    # byte range or a nested Condition, as its path is decided
+    # there and its arms are statements that may return or
+    # raise; any other site as a whole.
+    def self.trailed(condition)
+      return condition unless condition.operator == 'if'
+
+      condition.operands.first
+    end
+
+    # The opening of the record call around operand index of
+    # the site.
+    def self.record_call(site, index)
+      "PathCoverage.record(#{site.inspect}, #{index}, "
+    end
+
+    # The inserts that start each method's path at its entry,
+    # outermost of all there, and wrap each of its decisions'
+    # predicates in a decide call, outside any record or
+    # outcome call.
+    def self.path_inserts(methods)
+      methods.flat_map do |site, method|
+        decisions = method.decisions
+        start = path_start(site, decisions.size)
+        decides = decisions.each_with_index.flat_map do |decision, i|
+          call = "PathCoverage.decide(#{PATH_NAME}, #{i}, "
+          tail = decision.exits.nil? ? '' : ", #{decision.exits}"
+          wrap(call, decision.range, decision.command, 2, tail)
+        end
+        [[method.entry, start, 3]] + decides
+      end
+    end
+
+    # The statement that starts a call's path through the
+    # method at site, which has size decisions.
+    def self.path_start(site, size)
+      call = "PathCoverage.path(#{site.inspect}, #{size})"
+      "#{PATH_NAME} = #{call}; "
+    end
+
+    # The two inserts that wrap the code at range in call, of
+    # rank among inserts at the same offset, with tail as the
+    # call's further arguments. 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(call, range, command, rank, tail = '')
+      open, close = command ? ['(', ")#{tail})"] : ['', "#{tail})"]
+      [
+        [range.begin, call + open, rank],
+        [range.end, close, rank, :close]
+      ]
+    end
+
+    # Splices each [offset, text, rank] insert into source, last
+    # offset first so earlier offsets stay valid; a closing
+    # insert is marked :close. Text spliced in later at an
+    # offset lands before text already there, so at one offset
+    # opening inserts go in lowest rank first, leaving the
+    # highest outermost, then closing ones highest rank first,
+    # so the innermost call closes first and each tail stays
+    # with its own call.
+    def self.apply(source, inserts)
+      sorted = inserts.sort_by do |offset, _, rank, close|
+        close ? [-offset, 1, -rank] : [-offset, 0, rank]
+      end
+      sorted.each do |offset, text, _|
+        source.bytesplice(offset, 0, text)
+      end
+      source
+    end
+  end
+end

data/lib/path_coverage/site.rb

@@ -0,0 +1,11 @@
+module PathCoverage
+  # 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/path_coverage/site_paths.rb

@@ -0,0 +1,74 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The paths an evaluation of a site can take, worked out
+  # from its condition alone: the outcome of each leaf, in leaf
+  # order, nil for a leaf that evaluation never reaches.
+  module SitePaths
+    # Every possible path through site's condition, true
+    # before false.
+    def self.possible(site)
+      walk(site, site.fixed).map do |outcomes, _value|
+        site.leaves.map { |range| outcomes[range] }
+      end
+    end
+
+    # The outcome of an operand on which each operator goes on
+    # to its next operand; any other ends the chain there.
+    CONTINUES_ON = {
+      '&&' => true, 'and' => true, '||' => false, 'or' => false
+    }.freeze
+
+    # [[{ leaf range => outcome }, value], ...] for each way
+    # node can be evaluated, value being the outcome of node as
+    # a whole; fixed is the site's { leaf range => its one
+    # outcome }.
+    def self.walk(node, fixed)
+      return leaf(node, fixed) unless node.is_a?(Condition)
+      return ternary(node, fixed) if CHOICES.include?(node.operator)
+
+      chain(node, fixed)
+    end
+
+    # The ways a chain of one operator can be evaluated: each
+    # way of its first operand, going on to the next while each
+    # outcome is the one its operator goes on with.
+    def self.chain(node, fixed)
+      first, *rest = node.operands
+      goes_on = CONTINUES_ON.fetch(node.operator)
+      rest.reduce(walk(first, fixed)) do |ways, operand|
+        ways.flat_map do |outcomes, value|
+          next [[outcomes, value]] unless value == goes_on
+
+          walk(operand, fixed).map do |more, after|
+            [outcomes.merge(more), after]
+          end
+        end
+      end
+    end
+
+    # The ways a ternary or an if can be evaluated: each way of
+    # its predicate, then each way of the condition the arm it
+    # picks is, if that arm is one; an if with no else arm
+    # picks none. Its value is that of no choice, so is nil.
+    def self.ternary(node, fixed)
+      predicate, then_arm, else_arm = node.operands
+      walk(predicate, fixed).flat_map do |outcomes, value|
+        body = (value ? then_arm : else_arm)&.body
+        next [[outcomes, nil]] if body.nil?
+
+        walk(body, fixed).map do |more, _|
+          [outcomes.merge(more), nil]
+        end
+      end
+    end
+
+    # The ways a leaf can be evaluated: true, then false, or
+    # its one outcome alone when it is fixed.
+    def self.leaf(range, fixed)
+      only = fixed[range]
+      outcomes = only ? [only == :truthy] : [true, false]
+      outcomes.map { |outcome| [{ range => outcome }, outcome] }
+    end
+  end
+end

data/lib/path_coverage/site_tree.rb

@@ -0,0 +1,94 @@
+require_relative 'condition'
+
+module PathCoverage
+  # The tree shown under a site's line on its file's page: a
+  # grid whose columns are the site's paths, never taken first.
+  module SiteTree
+    # { operator:, counts:, cells:, operands: } for one site,
+    # from its paths, [{path:, count:}, ...]. counts are the
+    # columns' counts. Every node has cells, one per column: a
+    # leaf { text:, cells: } its outcome, nil where unreached;
+    # a condition { operator:, cells:, operands: } its value;
+    # an arm { arm:, text:, cells:, body: } whether the column
+    # took it, body being its condition's tree, nil for a plain
+    # arm. Texts are cut from source at the manifest's ranges.
+    def self.of(source, condition, paths)
+      columns = paths.sort_by.with_index do |taken, i|
+        [taken[:count].zero? ? 0 : 1, i]
+      end
+      outcomes = columns.map { |taken| taken[:path] }
+      tree = node(source, condition, outcomes, (0..).each)
+      tree.merge(counts: columns.map { |taken| taken[:count] })
+    end
+
+    # The tree of condition, each leaf taking the next index of
+    # leaves, so leaves pair with path entries left to right.
+    def self.node(source, condition, outcomes, leaves)
+      operands = condition.operands.map do |operand|
+        case operand
+        when Condition then node(source, operand, outcomes, leaves)
+        when Arm then operand
+        else leaf(source, operand, outcomes, leaves.next)
+        end
+      end
+      arms(source, condition, operands, outcomes, leaves)
+    end
+
+    # condition's node from its operands' nodes, its ternary
+    # arms built in order after its predicate, as each arm's
+    # cells follow from the predicate's.
+    def self.arms(source, condition, operands, outcomes, leaves)
+      predicate = operands.first
+      operands = operands.map do |operand|
+        next operand unless operand.is_a?(Arm)
+
+        arm(source, operand, predicate[:cells], outcomes, leaves)
+      end
+      cells = value(condition.operator, operands)
+      { operator: condition.operator, cells:, operands: }
+    end
+
+    # One arm of a ternary or an if: its text, nil for an arm
+    # with no statements, whether each column took it, from the
+    # predicate's cells, and the tree of its condition.
+    def self.arm(source, arm, decided, outcomes, leaves)
+      picked = arm.kind == :then
+      body = arm.body && node(source, arm.body, outcomes, leaves)
+      text = arm.extent && source.byteslice(arm.extent)
+      {
+        arm: arm.kind, text:,
+        cells: decided.map { |outcome| outcome == picked }, body:
+      }
+    end
+
+    # A condition's value in each column: a ternary's or an
+    # if's is its taken arm's body's, nil for a plain arm; a
+    # chain's is that of the last operand it reached.
+    def self.value(operator, operands)
+      if CHOICES.include?(operator)
+        _, *arms = operands
+        arms.map { |arm| arm[:body]&.fetch(:cells) }
+            .then { |bodies| ternary_value(arms, bodies) }
+      else
+        operands.map { |operand| operand[:cells] }
+                .transpose.map { |column| column.compact.last }
+      end
+    end
+
+    # Each column's value from the arm it took.
+    def self.ternary_value(arms, bodies)
+      arms.first[:cells].each_index.map do |column|
+        taken = arms.index { |arm| arm[:cells][column] }
+        taken && bodies[taken]&.fetch(column)
+      end
+    end
+
+    # One leaf's text and its outcome in each column.
+    def self.leaf(source, range, outcomes, index)
+      {
+        text: source.byteslice(range),
+        cells: outcomes.map { |path| path[index] }
+      }
+    end
+  end
+end

data/lib/path_coverage/source_lines.rb

@@ -0,0 +1,79 @@
+require_relative 'gaps'
+
+module PathCoverage
+  # The lines of one file's page, each with the status of the
+  # conditions on it.
+  module SourceLines
+    # [{number:, text:, status:, span:}] for each line of
+    # source. A line in a site's span shares one button with
+    # the span's other lines; status and span are nil on a line
+    # with no condition.
+    def self.of(source, sites, operands)
+      marks = marks(source, sites, operands)
+      source.lines.each_with_index.map do |text, index|
+        number = index + 1
+        mark = marks.fetch(number, {})
+        {
+          number:, text: text.chomp,
+          status: mark[:status], span: mark[:span]
+        }
+      end
+    end
+
+    # { line number => {status:, span:} } for each line a site
+    # covers, every line of a merged span sharing that span.
+    def self.marks(source, sites, operands)
+      blocks = merged(spans_of(source, sites, operands))
+      blocks.each_with_object({}) do |(span, status), marks|
+        span.each { |number| marks[number] = { status:, span: } }
+      end
+    end
+
+    # [span, status] for each site: from the line it starts on
+    # to the line its last operand ends on.
+    def self.spans_of(source, sites, operands)
+      sites.map do |site, condition|
+        last = condition.leaves.last
+        span = line_of(site)..end_line(source, last)
+        [span, status_of(operands.fetch(site))]
+      end
+    end
+
+    # The spans merged wherever they overlap, in line order. A
+    # merged span has :gaps if any of its sites has, so a
+    # covered site never hides another's gaps.
+    def self.merged(spans)
+      sorted = spans.sort_by { |span, _| span.begin }
+      sorted.each_with_object([]) do |(span, status), blocks|
+        last_span, last_status = blocks.last
+        if last_span && last_span.end >= span.begin
+          joined = last_span.begin..[last_span.end, span.end].max
+          blocks[-1] = [joined, worse(last_status, status)]
+        else
+          blocks << [span, status]
+        end
+      end
+    end
+
+    # :gaps if either status is :gaps, else :covered.
+    def self.worse(one, other)
+      [one, other].include?(:gaps) ? :gaps : :covered
+    end
+
+    # :covered when no operand has a gap, else :gaps.
+    def self.status_of(counts)
+      gaps = counts.flat_map { |operand| Gaps.operand_gap(operand) }
+      gaps.empty? ? :covered : :gaps
+    end
+
+    # The line a site starts on, from its path:line:column name.
+    def self.line_of(site)
+      site[/:(\d+):\d+\z/, 1].to_i
+    end
+
+    # The line of source on which byte range ends.
+    def self.end_line(source, range)
+      source.byteslice(0, range.end).count("\n") + 1
+    end
+  end
+end

data/lib/path_coverage/summary.rb

@@ -0,0 +1,33 @@
+module PathCoverage
+  # The per-file numbers the HTML index page shows.
+  module Summary
+    # One row per file that has sites in operands, as
+    # Result#operands gives them, in path order.
+    def self.files(operands)
+      by_path = operands.group_by { |site, _| path_of(site) }
+      by_path.sort.map { |path, sites| row(path, sites) }
+    end
+
+    # The summary row of one file's sites.
+    def self.row(path, sites)
+      operands = sites.flat_map { |_, counts| counts }
+      outcomes = operands.sum { |counts| counts[:only] ? 1 : 2 }
+      seen = operands.sum { |counts| seen_in(counts) }
+      {
+        path:, sites: sites.size, seen:, outcomes:,
+        percent: (100.0 * seen / outcomes).round,
+        missing: outcomes - seen
+      }
+    end
+
+    # How many of an operand's two outcomes were seen.
+    def self.seen_in(counts)
+      [counts[:truthy], counts[:falsy]].count(&:positive?)
+    end
+
+    # The file a site is in: its name minus :line:column.
+    def self.path_of(site)
+      site.sub(/:\d+:\d+\z/, '')
+    end
+  end
+end

data/lib/path_coverage/version.rb

@@ -0,0 +1,3 @@
+module PathCoverage
+  VERSION = '0.0.2'.freeze
+end

data/lib/path_coverage.rb

@@ -1,5 +1,2 @@
-# A placeholder holding the gem name path_coverage for the
-# successor of condition_coverage; it does nothing yet.
-module PathCoverage
-  VERSION = '0.0.1'.freeze
-end
+require_relative 'path_coverage/version'
+require_relative 'path_coverage/kernel'

metadata

@@ -1,29 +1,84 @@
 --- !ruby/object:Gem::Specification
 name: path_coverage
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Jon Jagger
-autorequire: 
-bindir: bin
+autorequire:
+bindir: exe
 cert_chain: []
 date: 2026-11-02 00:00:00.000000000 Z
-dependencies: []
-description: Reserves the name for the successor of condition_coverage, which records
-  the paths taken through each condition and method.
-email: 
-executables: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Records which paths each condition and each method took, and reports
+  the paths never taken in the terminal and as HTML.
+email:
+executables:
+- path_coverage_collector
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE.md
+- README.md
+- exe/path_coverage_collector
 - lib/path_coverage.rb
-homepage: https://github.com/cyber-dojo/condition_coverage
+- lib/path_coverage/auto.rb
+- lib/path_coverage/collector.rb
+- lib/path_coverage/condition.rb
+- lib/path_coverage/configuration.rb
+- lib/path_coverage/gaps.rb
+- lib/path_coverage/html/file.html
+- lib/path_coverage/html/index.html
+- lib/path_coverage/html/side.js
+- lib/path_coverage/html/sort.js
+- lib/path_coverage/html/style.css
+- lib/path_coverage/html/toggle.js
+- lib/path_coverage/html_file.rb
+- lib/path_coverage/html_index.rb
+- lib/path_coverage/html_nav.rb
+- lib/path_coverage/html_paths.rb
+- lib/path_coverage/html_report.rb
+- lib/path_coverage/html_template.rb
+- lib/path_coverage/html_tree.rb
+- lib/path_coverage/json_writer.rb
+- lib/path_coverage/kernel.rb
+- lib/path_coverage/manifest.rb
+- lib/path_coverage/manifest_choices.rb
+- lib/path_coverage/merge.rb
+- lib/path_coverage/path_gaps.rb
+- lib/path_coverage/path_manifest.rb
+- lib/path_coverage/paths_report.rb
+- lib/path_coverage/post.rb
+- lib/path_coverage/recorder.rb
+- lib/path_coverage/render.rb
+- lib/path_coverage/result.rb
+- lib/path_coverage/rewriter.rb
+- lib/path_coverage/site.rb
+- lib/path_coverage/site_paths.rb
+- lib/path_coverage/site_tree.rb
+- lib/path_coverage/source_lines.rb
+- lib/path_coverage/summary.rb
+- lib/path_coverage/version.rb
+homepage: https://github.com/cyber-dojo/path_coverage
 licenses:
 - BSD-2-Clause
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -38,8 +93,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
-summary: Path coverage for Ruby, alongside SimpleCov
+summary: Path coverage for Ruby, alongside SimpleCov branch coverage
 test_files: []