undercover 0.8.4 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f86959c16f0b74f14a45569ca4d746650e764eef3b94cc8f10ff341b2900f099
-  data.tar.gz: ef70c14d604fa88d59cca1cec6155382eed5360795a6c9c38c3b3d72366e2080
+  metadata.gz: 8d93f862aad4a70d2370f9da2021a4b32c284084f4a56bc2a04da6f409d2b777
+  data.tar.gz: 1cc3a1f5e26aa234019c3ae76df456534a7047dfbb1421175db56ab869d4150f
 SHA512:
-  metadata.gz: 703e9ea6340101fd7d49368eb07bfd70986f31f7306219f5b3f791383eecf63483db59360716005e528ecdf6aae91e7ce4bb1d3a7d3c5b62dceccb5dde1e85b0
-  data.tar.gz: 704e695944e5135f41408bc9fa9f8b27c3213574a884d04a5f8723c7f985d0f309d32c49977d74ced2d21da4b580129419d2971a26fe91c495b4e0246ce4c1ff
+  metadata.gz: ae42ba519cd6bd3435fee10c67c20907690036a4bccdd425c2cde2b4276a2bbd33ffd9d8d091b73c6d760fdf7e4bca52e400d71c85f21440f2d2c4ad2fb53d86
+  data.tar.gz: 28c65742716800a1a042b513ebe4bf14f254d46d22ef8959406d49f682132525fff4e19a21a7e7418562485cda79f9cb167bfb11877763b0b17e9645a09e116b

data/.github/workflows/ruby.yml

@@ -23,7 +23,7 @@ jobs:
         run: |
           git fetch --update-head-ok origin master:master
           undercover --simplecov coverage/undercover_coverage.json --compare master
-      - uses: actions/upload-artifact@v6
+      - uses: actions/upload-artifact@v7
         with:
           name: undercover-${{ matrix.ruby }}-coverage
           path: coverage/undercover_coverage.json
@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     steps:
-      - uses: actions/download-artifact@v7
+      - uses: actions/download-artifact@v8
         with:
           name: undercover-4.0-coverage
       - name: Upload coverage

data/CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+# [0.8.5] - 2026-04-21
+### Added
+- `--format json` CLI option for machine-readable output ([#251](https://github.com/grodowski/undercover/pull/251))
+
+### Fixed
+- Add `benchmark` as a dependency, required for Ruby 4
+
 # [0.8.4] - 2026-02-06
 ### Fixed
 - Print branch coverage even on n/a lines (https://github.com/grodowski/undercover/pull/249) by [@kuahyeow](https://github.com/kuahyeow)
@@ -216,7 +223,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 - First release of `undercover` 🎉
 
-[Unreleased]: https://github.com/grodowski/undercover/compare/v0.8.4...HEAD
+[Unreleased]: https://github.com/grodowski/undercover/compare/v0.8.5...HEAD
+[0.8.5]: https://github.com/grodowski/undercover/compare/v0.8.4...v0.8.5
 [0.8.4]: https://github.com/grodowski/undercover/compare/v0.8.3...v0.8.4
 [0.8.3]: https://github.com/grodowski/undercover/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/grodowski/undercover/compare/v0.8.1...v0.8.2

data/README.md

@@ -134,10 +134,67 @@ Usage: undercover [options]
     -w, --max-warnings limit         Maximum number of warnings to generate before stopping analysis. Useful as a performance improvement for large diffs.
     -f, --include-files globs        Include files matching specified glob patterns (comma separated). Defaults to '*.rb,*.rake,*.ru,Rakefile'
     -x, --exclude-files globs        Skip files matching specified glob patterns (comma separated). Empty by default.
+        --format FORMAT              Output format: text, json (default: text)
     -h, --help                       Prints this help
         --version                    Show version
 ```
 
+### JSON Output
+
+Use `--format json` to get machine-readable output, useful for CI integrations and tooling:
+
+```sh
+undercover --compare origin/main --format json
+```
+
+Output structure:
+
+```json
+{
+  "warnings": [
+    {
+      "node": "Foo#bar",
+      "type": "instance method",
+      "file": "lib/foo.rb",
+      "first_line": 10,
+      "last_line": 20,
+      "coverage": 0.5,
+      "uncovered_lines": [11],
+      "uncovered_branches": [
+        {
+          "line": 13,
+          "block": 0,
+          "branch": 0,
+          "description": "if user.admin?"
+        },
+        {
+          "line": 16,
+          "block": 0,
+          "branch": 1,
+          "description": "else"
+        },
+        {
+          "line": 19,
+          "block": 0,
+          "branch": 2,
+          "description": "? role == :admin → else"
+        }
+      ]
+    }
+  ],
+  "summary": {
+    "total_warnings": 1,
+    "files_affected": 1
+  }
+}
+```
+
+Each warning includes:
+- `uncovered_lines` — line numbers with zero execution count
+- `uncovered_branches` — branch entries that were never taken, each with `line`, `block`, and `branch` identifiers. The optional `description` field names the branch from the source (e.g. `"if user.admin?"`, `"else"`, `"when :active"`). For same-line branches such as ternaries, the arm type is appended after ` → ` (e.g. `"? role == :admin → else"`).
+
+Branch-level entries require `enable_coverage(:branch)` in your SimpleCov configuration (see [Setting up coverage reporting](#setting-up-coverage-reporting)).
+
 ### Configuration File
 
 A configuration file named `.undercover` can be created at the top level of a project's directory containing the same set of options for the CLI.

data/lib/undercover/ast_branch_annotator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Undercover
+  class AstBranchAnnotator
+    def self.call(ast_node)
+      new.annotate(ast_node)
+    end
+
+    # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+    def annotate(ast_node, info = {})
+      return info unless ast_node.is_a?(::Parser::AST::Node)
+
+      case ast_node.type
+      when :if
+        annotate_if_node(ast_node, info)
+      when :case
+        ast_node.children.drop(1).each do |child|
+          next unless child.is_a?(::Parser::AST::Node) && child.type == :when
+
+          cond_src = expression_source(child.children.first)
+          info[child.location.keyword.line] ||= "when #{cond_src}"
+        end
+      end
+
+      ast_node.children.each { |c| annotate(c, info) }
+      info
+    end
+    # rubocop:enable Metrics/MethodLength,Metrics/AbcSize
+
+    private
+
+    def annotate_if_node(ast_node, info) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
+      loc = ast_node.location
+      cond_src = expression_source(ast_node.children.first)
+      case loc
+      when Parser::Source::Map::Condition
+        kw = loc.keyword
+        info[kw.line] ||= "#{kw.source} #{cond_src}"
+        info[loc.else.line] ||= 'else' if loc.else&.source == 'else'
+      when Parser::Source::Map::Ternary
+        info[loc.question.line] ||= "? #{cond_src}"
+        info[loc.colon.line] ||= ':'
+      end
+    end
+
+    def expression_source(node)
+      node.location.expression.source
+    end
+  end
+end

data/lib/undercover/cli.rb

@@ -5,12 +5,6 @@ require 'rainbow'
 
 module Undercover
   module CLI
-    WARNINGS_TO_S = {
-      stale_coverage: Rainbow('🚨 WARNING: Coverage data is older than your ' \
-                              'latest changes and results might be incomplete. ' \
-                              'Re-run tests to update').yellow,
-      no_changes: Rainbow('✅ No reportable changes').green
-    }.freeze
     def self.run(args)
       opts = Undercover::Options.new.parse(args)
       syntax_version(opts.syntax_version)
@@ -32,7 +26,7 @@ module Undercover
 
       changeset_obj = changeset(opts)
       report = Undercover::Report.new(changeset_obj, opts, simplecov_adapter).build
-      handle_report_validation(report, coverage_path)
+      handle_report_validation(report, coverage_path, opts)
     end
 
     def self.handle_missing_coverage_path(opts)
@@ -48,16 +42,21 @@ module Undercover
       1
     end
 
-    def self.handle_report_validation(report, coverage_path)
-      error = report.validate(coverage_path)
-      if error
-        puts(WARNINGS_TO_S[error])
-        return 0 if error == :no_changes
-      end
+    def self.handle_report_validation(report, coverage_path, opts)
+      validation_error = report.validate(coverage_path)
+      flagged = validation_error ? [] : report.flagged_results
+      formatter = build_formatter(flagged, validation_error, opts)
+
+      puts formatter
+      formatter.exit_code
+    end
 
-      flagged = report.flagged_results
-      puts Undercover::Formatter.new(flagged)
-      flagged.any? ? 1 : 0
+    def self.build_formatter(flagged, validation_error, opts)
+      if opts.formatter == 'json'
+        Undercover::JsonFormatter.new(flagged, validation_error)
+      else
+        Undercover::Formatter.new(flagged, validation_error)
+      end
     end
 
     def self.syntax_version(version)

data/lib/undercover/formatter.rb

@@ -2,16 +2,33 @@
 
 module Undercover
   class Formatter
-    def initialize(results)
+    WARNINGS_TO_S = {
+      stale_coverage: Rainbow('🚨 WARNING: Coverage data is older than your ' \
+                              'latest changes and results might be incomplete. ' \
+                              'Re-run tests to update').yellow,
+      no_changes: Rainbow('✅ No reportable changes').green
+    }.freeze
+
+    def initialize(results, validation_error = nil)
       @results = results
+      @validation_error = validation_error
     end
 
     def to_s
+      return WARNINGS_TO_S[@validation_error] if @validation_error
+
       return success unless @results.any?
 
       ([warnings_header] + formatted_warnings).join("\n")
     end
 
+    def exit_code
+      return 0 if @validation_error
+      return 0 unless @results.any?
+
+      1
+    end
+
     private
 
     def formatted_warnings

data/lib/undercover/json_formatter.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'undercover/ast_branch_annotator'
+
+module Undercover
+  class JsonFormatter
+    def initialize(results, validation_error = nil)
+      @results = results
+      @validation_error = validation_error
+    end
+
+    def to_s
+      JSON.pretty_generate(to_h)
+    end
+
+    def to_h
+      output = {
+        warnings: warnings,
+        summary: summary
+      }
+      output[:validation] = @validation_error.to_s if @validation_error && @validation_error != :no_changes
+      output
+    end
+
+    def exit_code
+      return 0 if @validation_error
+      return 0 unless @results.any?
+
+      1
+    end
+
+    private
+
+    def warnings # rubocop:disable Metrics/MethodLength
+      @results.map do |result|
+        {
+          node: result.node.name,
+          type: result.node.human_name,
+          file: result.file_path,
+          first_line: result.first_line,
+          last_line: result.last_line,
+          coverage: result.coverage_f,
+          uncovered_lines: uncovered_lines(result),
+          uncovered_branches: uncovered_branches(result)
+        }
+      end
+    end
+
+    def uncovered_lines(result)
+      result.coverage
+            .select { |cov| cov.size == 2 }
+            .reject { |ln, _| result.skipped?(result.file_path, ln) }
+            .select { |_, count| count.zero? }
+            .map { |ln, _| ln }
+    end
+
+    def uncovered_branches(result)
+      annotated_branches(result)
+        .reject { |b| result.skipped?(result.file_path, b[:line]) || b[:count] == 'ignored' }
+        .select { |b| b[:count].zero? }
+        .map { |b| b.except(:count) }
+    end
+
+    def annotated_branches(result) # rubocop:disable Metrics/AbcSize
+      ast_info = AstBranchAnnotator.call(result.node.ast_node)
+      counts_per_line = result.branches.each_with_object(Hash.new(0)) { |b, h| h[b[:line]] += 1 }
+      result.branches.map do |entry|
+        arm = result.branch_label(result.file_path, entry[:branch]) if counts_per_line[entry[:line]] > 1
+        label = [ast_info[entry[:line]], arm].compact.join(' → ')
+        next entry if label.empty?
+
+        entry.merge(description: label)
+      end
+    end
+
+    def summary
+      {
+        total_warnings: @results.size,
+        files_affected: @results.map(&:file_path).uniq.size
+      }
+    end
+  end
+end

data/lib/undercover/lcov_parser.rb

@@ -58,6 +58,10 @@ module Undercover
       false
     end
 
+    def branch_label(_filepath, _branch_no)
+      nil
+    end
+
     def ignored_files
       # supported by SimplecovResultAdapter only
       []

data/lib/undercover/options.rb

@@ -34,6 +34,8 @@ module Undercover
     DEFAULT_FILE_INCLUDE_GLOBS = %w[*.rb *.rake *.ru Rakefile].freeze
     DEFAULT_FILE_EXCLUDE_GLOBS = %w[test/* spec/* db/* config/* *_test.rb *_spec.rb].freeze
 
+    FORMATS = %w[text json].freeze
+
     attr_accessor :lcov,
                   :simplecov_resultset,
                   :path,
@@ -44,7 +46,8 @@ module Undercover
                   :file_scope,
                   :glob_allow_filters,
                   :glob_reject_filters,
-                  :max_warnings_limit
+                  :max_warnings_limit,
+                  :formatter
 
     def initialize
       @run_mode = DIFF_TRIGGER_LINE
@@ -55,6 +58,7 @@ module Undercover
       self.glob_allow_filters = DEFAULT_FILE_INCLUDE_GLOBS
       self.glob_reject_filters = DEFAULT_FILE_EXCLUDE_GLOBS
       self.max_warnings_limit = nil
+      self.formatter = 'text'
     end
 
     # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
@@ -84,6 +88,7 @@ module Undercover
         ruby_syntax_option(opts)
         max_warnings_limit_option(opts)
         file_filters(opts)
+        format_option(opts)
       end.parse(args)
 
       guess_resultset_path unless simplecov_resultset
@@ -197,5 +202,12 @@ module Undercover
         self.glob_reject_filters = split_comma_separated_with_braces(comma_separated_globs)
       end
     end
+
+    def format_option(parser)
+      desc = "Output format: #{FORMATS.join(', ')} (default: text)"
+      parser.on('--format FORMAT', FORMATS, desc) do |format|
+        self.formatter = format
+      end
+    end
   end
 end

data/lib/undercover/result.rb

@@ -9,7 +9,7 @@ module Undercover
     attr_reader :node, :coverage, :coverage_adapter, :file_path
 
     def_delegators :node, :first_line, :last_line, :name
-    def_delegators :coverage_adapter, :skipped?
+    def_delegators :coverage_adapter, :skipped?, :branch_label
 
     def initialize(node, coverage_adapter, file_path) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
       @node = node
@@ -123,6 +123,15 @@ module Undercover
     end
     # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
+    # Returns raw branch coverage entries for this result as structured hashes.
+    # Callers that need human-readable descriptions should use AstBranchAnnotator
+    # separately (e.g. JsonFormatter).
+    def branches
+      coverage.select { |cov| cov.size == 4 }.map do |ln, block_no, branch_no, count|
+        {line: ln, block: block_no, branch: branch_no, count: count}
+      end
+    end
+
     def file_path_with_lines
       "#{file_path}:#{first_line}:#{last_line}"
     end

data/lib/undercover/simplecov_result_adapter.rb

@@ -52,6 +52,13 @@ module Undercover
       source_file['lines'][line_no - 1] == 'ignored'
     end
 
+    def branch_label(filepath, branch_no)
+      source_file = find_file(filepath)
+      return nil unless source_file
+
+      source_file['branches']&.dig(branch_no - 1, 'type')
+    end
+
     # unused for now
     def total_coverage; end
     def total_branch_coverage; end

data/lib/undercover/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Undercover
-  VERSION = '0.8.4'
+  VERSION = '0.8.5'
 end

data/lib/undercover.rb

@@ -13,6 +13,7 @@ require 'undercover/result'
 require 'undercover/cli'
 require 'undercover/changeset'
 require 'undercover/formatter'
+require 'undercover/json_formatter'
 require 'undercover/options'
 require 'undercover/filter_set'
 require 'undercover/simplecov_result_adapter'

data/undercover.gemspec

@@ -4,7 +4,7 @@ lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'undercover/version'
 
-Gem::Specification.new do |spec|
+Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.name          = 'undercover'
   spec.version       = Undercover::VERSION
   spec.authors       = ['Jan Grodowski']
@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.0.0'
 
   spec.add_dependency 'base64'
+  spec.add_dependency 'benchmark'
   spec.add_dependency 'bigdecimal'
   spec.add_dependency 'imagen', '>= 0.2.0'
   spec.add_dependency 'rainbow', '>= 2.1', '< 4.0'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: undercover
 version: !ruby/object:Gem::Version
-  version: 0.8.4
+  version: 0.8.5
 platform: ruby
 authors:
 - Jan Grodowski
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bigdecimal
   requirement: !ruby/object:Gem::Requirement
@@ -147,10 +161,12 @@ files:
 - docs/screenshot_warnings.png
 - docs/semaphore.yml
 - lib/undercover.rb
+- lib/undercover/ast_branch_annotator.rb
 - lib/undercover/changeset.rb
 - lib/undercover/cli.rb
 - lib/undercover/filter_set.rb
 - lib/undercover/formatter.rb
+- lib/undercover/json_formatter.rb
 - lib/undercover/lcov_parser.rb
 - lib/undercover/options.rb
 - lib/undercover/result.rb