undercover 0.8.4 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f86959c16f0b74f14a45569ca4d746650e764eef3b94cc8f10ff341b2900f099
-  data.tar.gz: ef70c14d604fa88d59cca1cec6155382eed5360795a6c9c38c3b3d72366e2080
+  metadata.gz: 45405b87566ffc4a838da25a9154b47f48b0578c469497eda044ea665005cfed
+  data.tar.gz: f90beafad3d6d90215c2326c7c702e725a25bfefbaf5b82ed2ea749133042b67
 SHA512:
-  metadata.gz: 703e9ea6340101fd7d49368eb07bfd70986f31f7306219f5b3f791383eecf63483db59360716005e528ecdf6aae91e7ce4bb1d3a7d3c5b62dceccb5dde1e85b0
-  data.tar.gz: 704e695944e5135f41408bc9fa9f8b27c3213574a884d04a5f8723c7f985d0f309d32c49977d74ced2d21da4b580129419d2971a26fe91c495b4e0246ce4c1ff
+  metadata.gz: 588486852ac15ef12aad5442b86567ed9e32ec36cb91ba4c45b164972f62cb1e1e1a253d5f9f2ee831bdc26074ba8446e8dfd99f6b0ae80405eac521f648a8f8
+  data.tar.gz: 5b63e08d782e36bae4513828a5f5b40bcf2c777775248285224faa19f482032ee962a02ae4e4859cf8c6d81e4a0816106d29e5a5b21bdb115646797ccb7b0f64

data/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: grodowski
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

data/.github/workflows/ruby.yml

@@ -5,9 +5,9 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: ['4.0', '3.4']
+        ruby: ['4.0', '3.4', '3.2']
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0 # fetch all since test fixtures depend on history
       - name: Set up Ruby ${{ matrix.ruby }}
@@ -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/.rubocop.yml

@@ -1,6 +1,6 @@
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.0
+  TargetRubyVersion: 3.2
   Exclude:
     - spec/fixtures/**/*
   SuggestExtensions: false

data/CHANGELOG.md

@@ -6,6 +6,31 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-26
+### Added
+- ERB view template coverage, opt in with `--include-files '*.rb,*.rake,*.ru,Rakefile,*.erb'`. Requires Ruby 3.2+ and `SimpleCov.enable_coverage :eval` ([#250](https://github.com/grodowski/undercover/pull/250))
+- Add `--commits-only` to check only committed changes after `--compare ref`, ignoring the index and working tree, for sparse or partial clones ([#273](https://github.com/grodowski/undercover/pull/273))
+- Add coverage report filtering to reduce resource usage ([#263](https://github.com/grodowski/undercover/pull/263))
+- Print a one-line hint about UndercoverCI after the text report (in Claude Code sessions, about the undercover Claude Code skill instead); hide it with `--no-hint` or `UNDERCOVER_NO_HINT=1` ([#278](https://github.com/grodowski/undercover/pull/278))
+
+### Changed
+- Parse Ruby with Prism instead of imagen and parser: Ruby 3.4/4.0 syntax is analysed instead of skipped, `_1` blocks are checked, destructured block params are named as written, and `--ruby-syntax`/`-r` is ignored with a warning ([#279](https://github.com/grodowski/undercover/pull/279))
+- **Breaking:** require SimpleCov `>= 1.0` and Ruby `>= 3.2`, restoring `ignored_files` under SimpleCov 1.x. Pin `undercover ~> 0.8.0` for SimpleCov 0.x / Ruby 3.0–3.1 ([#270](https://github.com/grodowski/undercover/pull/270))
+- Updated RuboCop `1.84.2` to `1.92.1`
+
+### Fixed
+- Fix ERB view coverage: parse templates with output block helpers (`<%= form_with ... do %>`), warn about an unparseable template once and list it in `Report#erb_parse_failures`, recommend ERB globs that keep the defaults, and keep `--format json` output parseable ([#277](https://github.com/grodowski/undercover/pull/277))
+- Find the coverage root of a monorepo app in sparse checkouts, by checking paths against HEAD when they are not on disk ([#275](https://github.com/grodowski/undercover/pull/275))
+- Analyse large files in linear time. Matching changed lines to code blocks was quadratic in file size, so a PR touching big files could take minutes; a 6,000-line file now takes 0.2s instead of 27s ([#274](https://github.com/grodowski/undercover/pull/274))
+- Respect SimpleCov's own filters and ignore changes outside the covered directory when the coverage report covers a subdirectory of the repository, such as an app in a monorepo. **Breaking:** `--include-files` and `--exclude-files` globs are now matched relative to the covered directory, so drop that directory from them — `apps/dash/**/*.rb` becomes `**/*.rb`; undercover warns rather than reporting success when globs skip every candidate file. Reports now also record the undercover version, and `--path` is deprecated and ignored because the project root comes from `--git-dir` ([#245](https://github.com/grodowski/undercover/pull/245))
+
+# [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 +241,9 @@ 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.9.0...HEAD
+[0.9.0]: https://github.com/grodowski/undercover/compare/v0.8.5...v0.9.0
+[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/Gemfile

@@ -9,9 +9,11 @@ gem 'bundler'
 gem 'pry'
 gem 'rake', '~> 13.0'
 gem 'rspec', '~> 3.0'
-gem 'rubocop', '~> 1.84.0'
+gem 'rubocop'
 gem 'ruby-lsp-rspec', require: false
 gem 'simplecov'
 gem 'simplecov-html'
 gem 'simplecov_json_formatter'
 gem 'timecop'
+
+gem 'erubi', '>= 1.13'

data/README.md

@@ -37,6 +37,9 @@ Or install it yourself as:
 
 ## Setting up coverage reporting
 
+> [!NOTE]
+> `undercover` requires SimpleCov >= 1.0 (and Ruby >= 3.2). For older SimpleCov (0.x) or Ruby setups, pin `undercover` to `~> 0.8.0`.
+
 To make your specs or tests compatible with `undercover`, please add `undercover` to your gemfile to use the undercover formatter the test helper.
 
 ```ruby
@@ -54,8 +57,8 @@ require 'undercover/simplecov_formatter'
 SimpleCov.formatter = SimpleCov::Formatter::Undercover
 
 SimpleCov.start do
-  add_filter(/^\/spec\//) # For RSpec
-  add_filter(/^\/test\//) # For Minitest
+  skip(/^\/spec\//) # For RSpec (`add_filter` on SimpleCov < 1.0)
+  skip(/^\/test\//) # For Minitest
   enable_coverage(:branch) # Report branch coverage to trigger branch-level undercover warnings
 end
 # ...
@@ -63,6 +66,50 @@ end
 
 Then run your test suite once through to generate the initial coverage file before you can run the `undercover` command.
 
+Ruby's branch coverage counts a hidden `else` for every `case` (and `if`) without one, so a `case` that handles all its values still gets flagged for a missing branch. To ignore these implicit branches:
+
+```ruby
+SimpleCov.start do
+  coverage :branch, ignore: :implicit_else # SimpleCov 1.3+
+  # SimpleCov 1.0-1.2: enable_coverage(:branch) and SimpleCov.ignore_branches :implicit_else
+end
+```
+
+## ERB view template coverage
+
+Undercover supports coverage analysis for ERB view templates. This requires:
+
+1. **Ruby 3.2+**
+2. **SimpleCov's eval coverage**, via `enable_coverage(:eval)`
+
+```ruby
+# spec_helper.rb
+SimpleCov.start do
+  enable_coverage(:branch)
+  enable_coverage(:eval)  # Required for view coverage
+end
+```
+
+3. **Opt-in via `--include-files`** since view coverage is not enabled by default. The option replaces the default list (`*.rb,*.rake,*.ru,Rakefile`), so repeat the defaults alongside `*.erb`:
+
+```sh
+undercover --include-files '*.rb,*.rake,*.ru,Rakefile,*.erb'
+```
+
+Or in your `.undercover` config file:
+
+```sh
+-f *.rb,*.rake,*.ru,Rakefile,*.erb
+```
+
+`--exclude-files` likewise replaces its defaults (`test/*,spec/*,db/*,config/*,*_test.rb,*_spec.rb,vendor/*`). To also skip generator templates, which are never rendered by your tests, keep the defaults in the list:
+
+```sh
+-x test/*,spec/*,db/*,config/*,*_test.rb,*_spec.rb,vendor/*,*/templates/*
+```
+
+**Why opt-in?** View coverage requires `enable_coverage(:eval)`, which is not enabled by default in SimpleCov. Without it, view files would be flagged as having 0% coverage (false positives).
+
 ## Upgrading from pre-0.7.0
 
 If you're upgrading from an older version of undercover that used LCOV, you can migrate to the new SimpleCov formatter:
@@ -86,6 +133,40 @@ SimpleCov.formatter = SimpleCov::Formatter::Undercover
 
 Note: LCOV support will be deprecated in a future release, but remains fully functional for existing projects.
 
+## Monorepos
+
+Undercover works when the coverage report covers a subdirectory of the repository rather than
+the whole thing, which is the usual shape of a monorepo:
+
+```
+monorepo/
+  .git
+  apps/
+    dash/          <- SimpleCov runs here
+      coverage/coverage.json
+    admin/
+```
+
+Run it from the directory SimpleCov covered and point `--git-dir` at the repository:
+
+```sh
+cd apps/dash
+undercover --git-dir ../../.git --compare origin/main
+```
+
+Undercover works out that coverage was recorded under `apps/dash` by matching the paths in the
+report against the files in the repository, so there is nothing to configure. In particular:
+
+- SimpleCov's own filters are honoured. `SimpleCov.start('rails')` skips `db/`, `config/` and
+  `vendor/`, and those files will not be reported even though git sees them as `apps/dash/db/...`
+- changes in sibling directories, such as `apps/admin`, are left alone. They are outside the
+  coverage report and there is nothing to judge them by
+- warnings are reported relative to the repository root (`apps/dash/lib/foo.rb`), so they line
+  up with what CI annotations expect
+
+File globs passed to `--include-files` and `--exclude-files` are matched relative to the covered
+directory, so write `lib/**/*.rb` rather than `apps/dash/lib/**/*.rb`.
+
 ## Usage
 
 Invoked with no arguments, Undercover will flag all untested methods and classes from the current diff:
@@ -106,6 +187,8 @@ Check out `docs/` for CI configuration examples:
 - [CircleCI - advanced](docs/circleci_advanced.yml)
 - [Semaphore](docs/semaphore.yml)
 
+`undercover` prints a one-line hint about UndercoverCI to stderr after the text report (in Claude Code sessions, about the undercover Claude Code skill instead). Hide it with `--no-hint` (also in `.undercover`) or `UNDERCOVER_NO_HINT=1`.
+
 Merging coverage results ([sample gist](https://gist.github.com/grodowski/9744ff91034dce8df20c2a8210409fb0)) is required for parallel tests before processing with `undercover`.
 
 ## Code review integrations
@@ -127,17 +210,74 @@ Options can be passed when running the command from the command line:
 Usage: undercover [options]
     -s, --simplecov path             SimpleCov JSON report file
     -l, --lcov path                  LCOV report file path (to be deprecated)
-    -p, --path path                  Project directory
     -g, --git-dir dir                Override `.git` with a custom directory
     -c, --compare ref                Generate coverage warnings for all changes after `ref`
-    -r, --ruby-syntax ver            Ruby syntax version, one of: current, ruby18, ruby19, ruby20, ruby21, ruby22, ruby23, ruby24, ruby25, ruby26, ruby30, ruby31, ruby32, ruby33
+        --commits-only               Only check committed changes after `--compare ref`, ignoring the index and working tree
     -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.
+    -x, --exclude-files globs        Skip files matching specified glob patterns (comma separated). Defaults to 'test/*,spec/*,db/*,config/*,*_test.rb,*_spec.rb,vendor/*'
+        --format FORMAT              Output format: text, json (default: text)
+        --no-hint                    Hide the one-line hint printed after the text report (or set UNDERCOVER_NO_HINT=1)
     -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.
@@ -156,17 +296,17 @@ Options assume that the program is run from the top level of the project directo
 
 Projects with low or nonexistent test coverage are likely to generate large numbers of warnings. While the default workflow would be to address them before the PR approval, your strategy might be different.
 
-In order to acknowledge an untested change and remove the UndercoverCI warning with the intention to improve later (or never), you can wrap the code block with the `:nocov:` syntax, e.g.
+In order to acknowledge an untested change and remove the UndercoverCI warning with the intention to improve later (or never), you can wrap the code block with SimpleCov's skip markers, e.g.
 
 ```rb
-# :nocov:
+# simplecov:disable
 def skip_this_method
     never_reached
 end
-# :nocov:
+# simplecov:enable
 ```
 
-Read more about the `:nocov:` syntax in [SimpleCov's readme](https://github.com/simplecov-ruby/simplecov#ignoringskipping-code).
+The legacy `# :nocov:` token still works (deprecated in SimpleCov 1.0). Read more in [SimpleCov's readme](https://github.com/simplecov-ruby/simplecov#ignoringskipping-code).
 
 ## Why?
 

data/bin/undercover

@@ -2,15 +2,7 @@
 # frozen_string_literal: true
 
 $LOAD_PATH.unshift("#{__dir__}/../lib")
-$VERBOSE = nil
 
 require 'undercover'
-require 'benchmark'
 
-result = 0
-time = Benchmark.realtime do
-  result = Undercover::CLI.run(ARGV)
-end
-
-puts "Undercover finished in #{time.round(4)}s"
-exit result
+exit Undercover::CLI.run(ARGV, timed: true)

data/lib/undercover/ast_branch_annotator.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Undercover
+  # Labels the lines where Ruby's branch coverage starts a branch (if, unless, ternary,
+  # case/when) with the source of their condition
+  class AstBranchAnnotator < Prism::Visitor
+    def self.call(prism_node)
+      return {} unless prism_node.is_a?(Prism::Node)
+
+      new.tap { prism_node.accept(_1) }.info
+    end
+
+    attr_reader :info
+
+    def initialize
+      super
+      @info = {}
+    end
+
+    def visit_if_node(node)
+      if node.if_keyword_loc
+        label(node.if_keyword_loc, "#{node.if_keyword_loc.slice} #{node.predicate.slice}")
+        label_else(node.subsequent)
+      else
+        label(node.then_keyword_loc, "? #{node.predicate.slice}")
+        label(node.subsequent.else_keyword_loc, ':')
+      end
+      super
+    end
+
+    def visit_unless_node(node)
+      label(node.keyword_loc, "unless #{node.predicate.slice}")
+      label_else(node.else_clause)
+      super
+    end
+
+    def visit_when_node(node)
+      label(node.keyword_loc, "when #{node.conditions.first.slice}")
+      super
+    end
+
+    # A guard (`in x if y`) is not a branch of its own
+    def visit_in_node(node)
+      guard = node.pattern
+      return super unless guard.is_a?(Prism::IfNode) || guard.is_a?(Prism::UnlessNode)
+
+      [guard.statements, guard.predicate, node.statements].compact.each { _1.accept(self) }
+    end
+
+    private
+
+    def label(location, text)
+      info[location.start_line] ||= text
+    end
+
+    def label_else(branch)
+      label(branch.else_keyword_loc, 'else') if branch.is_a?(Prism::ElseNode)
+    end
+  end
+end

data/lib/undercover/changeset.rb

@@ -8,12 +8,31 @@ module Undercover
   class Changeset
     T_ZERO = Time.strptime('0', '%s').freeze
 
-    def initialize(dir, compare_base = nil, filter_set = nil)
+    def initialize(dir, compare_base = nil, filter_set = nil, commits_only: false)
+      raise ArgumentError, 'commits_only requires a compare_base' if commits_only && !compare_base
+
       @dir = dir
       @repo = Rugged::Repository.new(dir)
       @repo.workdir = Pathname.new(dir).dirname.to_s # TODO: can replace?
       @compare_base = compare_base
       @filter_set = filter_set
+      @commits_only = commits_only
+    end
+
+    # @return String absolute path to the repository working directory
+    def repo_workdir
+      repo.workdir
+    end
+
+    # Answers from HEAD's tree rather than the disk, so it holds for files a sparse
+    # checkout left out of the working tree.
+    # @param path [String] relative to the repository root
+    # @return Boolean whether HEAD has a file or directory at path
+    def head_path?(path)
+      head.tree.path(path)
+      true
+    rescue Rugged::TreeError
+      false
     end
 
     def last_modified
@@ -56,10 +75,15 @@ module Undercover
     private
 
     # Diffs `head` or `head` + `compare_base` (if exists),
-    # as it makes sense to run Undercover with the most recent file versions
+    # as it makes sense to run Undercover with the most recent file versions.
+    # With `commits_only`, diffs `compare_base` against `head` and ignores the index and
+    # working tree, so files missing from a sparse checkout are not reported as deleted.
     def full_diff
-      base = compare_base_obj || head
-      @full_diff ||= base.diff(repo.index).merge!(repo.diff_workdir(head))
+      @full_diff ||= if commits_only
+                       compare_base_obj.diff(head)
+                     else
+                       (compare_base_obj || head).diff(repo.index).merge!(repo.diff_workdir(head))
+                     end
     end
 
     def compare_base_obj
@@ -74,6 +98,6 @@ module Undercover
       repo.head.target
     end
 
-    attr_reader :repo, :compare_base, :filter_set
+    attr_reader :repo, :compare_base, :filter_set, :commits_only
   end
 end

data/lib/undercover/cli.rb

@@ -2,43 +2,53 @@
 
 require 'undercover'
 require 'rainbow'
+require 'benchmark'
 
 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
+  module CLI # rubocop:disable Metrics/ModuleLength
+    HINTS = {
+      undercover_ci: 'UndercoverCI shows these results on your pull requests: https://undercover-ci.com ' \
+                     '(hide with --no-hint)',
+      claude_code: 'undercover has a Claude Code skill: https://github.com/grodowski/undercover-claude ' \
+                   '(hide with --no-hint)'
     }.freeze
-    def self.run(args)
+
+    def self.run(args, timed: false)
       opts = Undercover::Options.new.parse(args)
-      syntax_version(opts.syntax_version)
+      # Text after the JSON document would break parsing it
+      return run_report(opts) if !timed || opts.formatter == 'json'
 
-      run_report(opts)
+      result = nil
+      time = Benchmark.realtime { result = run_report(opts) }
+      puts "Undercover finished in #{time.round(4)}s"
+      result
     end
 
     def self.run_report(opts) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
       coverage_path = opts.simplecov_resultset || opts.lcov
       return handle_missing_coverage_path(opts) if coverage_path.nil?
       return handle_missing_file(coverage_path) unless File.exist?(coverage_path)
+      return handle_commits_only_without_compare if opts.commits_only && !opts.compare
+
+      changeset_obj = changeset(opts)
+      only_files = changeset_obj.file_paths.then { |f| f.empty? ? nil : f }
 
       simplecov_adapter = if opts.simplecov_resultset
-                            SimplecovResultAdapter.parse(File.open(opts.simplecov_resultset), opts)
+                            SimplecovResultAdapter.parse(File.open(opts.simplecov_resultset), opts,
+                                                         only_files: only_files)
                           else
                             # TODO: lcov will be deprecated end of 2025 and we'll be able to refactor harder
-                            LcovParser.parse(File.open(opts.lcov), opts)
+                            LcovParser.parse(File.open(opts.lcov), opts, only_files: only_files)
                           end
 
-      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)
+    def self.handle_missing_coverage_path(_opts = nil)
       puts Rainbow('❌ ERROR: No coverage report found. Checked default paths:').red
       puts Rainbow('  - ./coverage/coverage.json (SimpleCov)').red
-      puts Rainbow("  - ./coverage/lcov/#{Pathname.new(File.expand_path(opts.path)).split.last}.lcov (LCOV)").red
+      puts Rainbow("  - ./coverage/lcov/#{Pathname.new(Dir.pwd).split.last}.lcov (LCOV)").red
       puts Rainbow('Set a custom path with --lcov or --simplecov option').red
       1
     end
@@ -48,27 +58,95 @@ 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
+    def self.handle_commits_only_without_compare
+      puts Rainbow('❌ ERROR: --commits-only requires --compare ref').red
+      1
+    end
+
+    def self.handle_report_validation(report, coverage_path, opts)
+      validation_error = report.validate(coverage_path)
+      flagged = validation_error ? [] : report.flagged_results
+      unless validation_error
+        warn_if_erb_has_no_coverage(report)
+        warn_if_everything_was_globbed_out(report, opts)
       end
+      formatter = build_formatter(flagged, validation_error, opts)
+
+      puts formatter
+      print_hint(opts)
+      formatter.exit_code
+    end
+
+    # Flushes stdout first: when it's piped (CI logs) it is buffered, and the hint on
+    # stderr would otherwise land before the report
+    def self.print_hint(opts)
+      hint = hint_for(opts) or return
+
+      $stdout.flush
+      warn(Rainbow(hint).faint)
+    end
+
+    def self.hint_for(opts, env = ENV)
+      return if opts.formatter == 'json' || opts.no_hint || !env['UNDERCOVER_NO_HINT'].to_s.empty?
 
-      flagged = report.flagged_results
-      puts Undercover::Formatter.new(flagged)
-      flagged.any? ? 1 : 0
+      env['CLAUDECODE'].to_s.empty? ? HINTS[:undercover_ci] : HINTS[:claude_code]
     end
 
-    def self.syntax_version(version)
-      return unless version
+    # Reporting nothing because every candidate was filtered out looks identical to a
+    # clean run, so say which it was. Goes to stderr to leave --format json parseable.
+    def self.warn_if_everything_was_globbed_out(report, opts)
+      return unless report.results.empty?
 
-      Imagen.parser_version = version
+      skipped = report.globbed_out_files
+      return if skipped.empty?
+      return warn_erb_is_opt_in(skipped) if erb_not_opted_in?(skipped, opts)
+      return warn_globbed_out_besides_erb(skipped) if report.erb_files_without_coverage.any?
+
+      warn(Rainbow("⚠️  WARNING: nothing was checked - all #{skipped.size} candidate file(s) were " \
+                   'skipped by --include-files/--exclude-files. Globs are matched relative to the ' \
+                   'directory SimpleCov covered, so they should not repeat its path.').yellow)
+    end
+
+    # Templates skipped for lack of coverage were candidates too, so not everything was globbed out
+    def self.warn_globbed_out_besides_erb(skipped)
+      warn(Rainbow("⚠️  WARNING: besides those ERB templates, #{skipped.size} candidate file(s) were skipped " \
+                   'by --include-files/--exclude-files.').yellow)
+    end
+
+    # The default globs skip ERB templates, so blaming the glob root would mislead
+    def self.erb_not_opted_in?(skipped, opts)
+      skipped.any? { _1.end_with?(FileLoader::ERB_EXTENSION) } &&
+        opts.glob_allow_filters.none? { _1.include?(FileLoader::ERB_EXTENSION) }
+    end
+
+    def self.warn_erb_is_opt_in(skipped)
+      templates = skipped.count { _1.end_with?(FileLoader::ERB_EXTENSION) }
+      warn(Rainbow("⚠️  WARNING: nothing was checked - #{templates} changed ERB template(s) were skipped " \
+                   'because view coverage is opt-in. Check them with ' \
+                   "--include-files '*.rb,*.rake,*.ru,Rakefile,*.erb' and enable_coverage(:eval) in SimpleCov.start.")
+             .yellow)
+    end
+
+    def self.warn_if_erb_has_no_coverage(report)
+      templates = report.erb_files_without_coverage
+      return if templates.empty?
+
+      warn(Rainbow("⚠️  WARNING: skipped #{templates.size} ERB template(s) - the coverage report has no " \
+                   'ERB coverage. Add enable_coverage(:eval) to SimpleCov.start to check them.').yellow)
+    end
+
+    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
 
+    # --git-dir is resolved against the working directory, and the repository it points
+    # at determines the project root. Everything else is derived from there.
     def self.changeset(opts)
-      git_dir = File.join(opts.path, opts.git_dir)
-      Undercover::Changeset.new(git_dir, opts.compare)
+      Undercover::Changeset.new(opts.git_dir, opts.compare, commits_only: opts.commits_only)
     end
   end
 end