Add cover-diff target for changed-line coverage reports (#3820)

Integrate optional diff-cover behind a cover_diff ninja/make target and
document the pull-request iteration workflow. Add ci/coverage_files_from_diff.sh
to build NRN_COVERAGE_FILES from a branch diff.
Document NRN_COVERAGE_DIFF_BRANCH

Can invoke diff-cover from PROJECT_SOURCE_DIR with an absolute path to coverage-combined.info.

Add cover-begin, cover-html, cover-diff ninja/make target aliases

Hyphenated names are thin DEPENDS aliases for the existing underscore
targets so both forms work at the build tool level.

---------

Co-authored-by: Grok <grok@x.ai>

Author: nrnhines

CMakeLists.txt

@@ -216,7 +216,7 @@ set(NRN_RX3D_OPT_LEVEL
     "${NRN_RX3D_OPT_LEVEL_DEFAULT}"
     CACHE STRING "Optimization level for Cython generated files (non-zero may compile slowly)")
 
-option(NRN_ENABLE_COVERAGE "EnableCode Coverage (make cover_begin, make cover_html)" OFF)
+option(NRN_ENABLE_COVERAGE "EnableCode Coverage (cover-begin, cover-html, cover-diff)" OFF)
 set(NRN_COVERAGE_FILES
     ""
     CACHE STRING "semicolon (;) separated list of files to collect code coverage")

ci/coverage_files_from_diff.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Emit a semicolon-separated source file list for -DNRN_COVERAGE_FILES=...
+# Usage: coverage_files_from_diff.sh [base-ref]
+# Default base-ref is master (three-dot diff: base...HEAD).
+# Exits 1 with a stderr message when no compiled sources (.cpp/.c) changed.
+set -euo pipefail
+
+base="${1:-master}"
+mapfile -t files < <(git diff --name-only "${base}...HEAD" | grep -E '\.(cpp|c)$' || true)
+if ((${#files[@]} == 0)); then
+  echo "No compiled sources (.cpp/.c) changed vs ${base}; omit -DNRN_COVERAGE_FILES" >&2
+  exit 1
+fi
+(IFS=';'; echo "${files[*]}")

cmake/Coverage.cmake

@@ -12,7 +12,8 @@
 #   NRN_COVERAGE_FILES speeds the workflow tremendously, when iteratively
 #   working on a single or a few files.
 #
-#   Two targets are created: cover_begin and cover_html.
+#   Targets: cover_begin (alias cover-begin), cover_html (cover-html),
+#   and cover_diff (cover-diff, requires diff-cover).
 #
 #   cover_begin erases all the *.gcda coverage files and
 #   creates a baseline report (coverage-base.info)
@@ -124,6 +125,19 @@ if(NRN_ENABLE_COVERAGE)
   set(cover_combine_command "${LCOV}" "--add-tracefile" "coverage-base.info" "--add-tracefile"
                             "coverage-run.info" "--output-file" "coverage-combined.info")
   set(cover_html_command genhtml "coverage-combined.info" "--output-directory" html)
+
+  set(NRN_COVERAGE_DIFF_BRANCH
+      "master"
+      CACHE STRING "Git branch for cover_diff (diff-cover --compare-branch)")
+
+  find_program(DIFF_COVER diff-cover)
+  if(DIFF_COVER)
+    # diff-cover matches git diff paths to lcov SF: paths via GitPathTool, which is relative to cwd.
+    # Run from PROJECT_SOURCE_DIR (not the build dir) so repo-root paths like src/foo.cpp align with
+    # the lcov report.
+    set(cover_diff_report "${PROJECT_BINARY_DIR}/html-diff/index.html")
+  endif()
+
   add_custom_target(
     cover_clean
     COMMAND ${cover_clean_command}
@@ -137,6 +151,7 @@ if(NRN_ENABLE_COVERAGE)
     COMMAND ${cover_clean_command}
     COMMAND ${cover_baseline_command}
     WORKING_DIRECTORY "${PROJECT_BINARY_DIR}")
+  add_custom_target(cover-begin DEPENDS cover_begin)
   add_custom_target(
     cover_collect
     COMMAND ${cover_collect_command}
@@ -152,4 +167,22 @@ if(NRN_ENABLE_COVERAGE)
     COMMAND ${cover_html_command}
     COMMAND echo "View in browser at file://${PROJECT_BINARY_DIR}/html/index.html"
     WORKING_DIRECTORY "${PROJECT_BINARY_DIR}")
+  add_custom_target(cover-html DEPENDS cover_html)
+
+  if(DIFF_COVER)
+    add_custom_target(
+      cover_diff
+      COMMAND ${cover_collect_command}
+      COMMAND ${cover_combine_command}
+      COMMAND ${CMAKE_COMMAND} -E make_directory "${PROJECT_BINARY_DIR}/html-diff"
+      COMMAND
+        ${CMAKE_COMMAND} -E chdir "${PROJECT_SOURCE_DIR}" "${DIFF_COVER}"
+        "${PROJECT_BINARY_DIR}/coverage-combined.info" "--compare-branch"
+        "${NRN_COVERAGE_DIFF_BRANCH}" "--show-uncovered" "--format" "html:${cover_diff_report}"
+      COMMAND echo "View changed-line coverage at file://${cover_diff_report}"
+      WORKING_DIRECTORY "${PROJECT_BINARY_DIR}")
+    add_custom_target(cover-diff DEPENDS cover_diff)
+  else()
+    message(STATUS "diff-cover not found; cover_diff target unavailable (pip install diff-cover)")
+  endif()
 endif()

docs/cmake_doc/options.rst

@@ -572,16 +572,20 @@ NRN_ENABLE_COVERAGE:BOOL=OFF
 
   Requires ``lcov`` (e.g. ``sudo apt install lcov``).
 
-  Provides two make targets to simplify the repeated "run tests, examine coverage"
+  Provides make targets to simplify the repeated "run tests, examine coverage"
   workflow.
-    -- ``make cover_begin`` erases all previous coverage data
+    -- ``make cover-begin`` (``cover_begin``) erases all previous coverage data
     (``*.gcda`` files), and creates a baseline report. (Note all files and
     folders are created in the ``CMAKE_BINARY_DIR`` where you ran cmake.)
 
-    -- ``make cover_html`` creates a coverage report for the sum of all the
-    software runs since the last ``cover_begin`` and prints a file url
+    -- ``make cover-html`` (``cover_html``) creates a coverage report for the sum of all the
+    software runs since the last ``cover-begin`` and prints a file url
     that you can paste into your browser to review the coverage.
 
+    -- ``make cover-diff`` (``cover_diff``; requires ``pip install diff-cover``) reports
+    coverage on changed lines vs. ``NRN_COVERAGE_DIFF_BRANCH`` (default
+    ``master``). See `Developer Builds: Code Coverage <../install/code_coverage.html>`_.
+
   When using an iterative workflow to examine test coverage of a single
   or a few files, the above targets run much faster when this option is
   combined with `NRN_COVERAGE_FILES:STRING=`_
@@ -596,14 +600,19 @@ NRN_COVERAGE_FILES:STRING=
 
   ``-DNRN_COVERAGE_FILES="src/nrniv/partrans.cpp;src/nmodl/parsact.cpp;src/nrnpython/nrnpy_hoc.cpp"``
 
-  For a list of all the cpp files changed in a pull request, consider
-  copy/pasting the ``;`` separated list obtained with
+  For a list of compiled sources changed on a branch, use
 
   .. code-block:: shell
 
-     a=`git diff --name-only master | grep '\.cpp'`
-     echo $a | sed 's/ /;/g'
+     ci/coverage_files_from_diff.sh master
+
+  The script lists ``.cpp`` and ``.c`` files only. It exits with an error
+  when none changed (omit this option in that case).
 
+NRN_COVERAGE_DIFF_BRANCH:STRING=master
+--------------------------------------
+  Git branch passed to ``diff-cover --compare-branch`` for the
+  ``cover_diff`` target. Defaults to ``master``.
 
 NRN_SANITIZERS:STRING=
 ----------------------

docs/install/code_coverage.md

@@ -4,6 +4,7 @@
 ## Dependencies (Linux)
 ```
 sudo apt install lcov
+pip install diff-cover
 ```
 
 ## Instructions
@@ -88,9 +89,43 @@ cmake .. -DCMAKE_INSTALL_PREFIX=install \
 
 make -j 6 install
 
-make cover_begin
+make cover-begin
 
 make test
 
-make cover_html
+make cover-html
 ```
+
+## Changed-line coverage (pull requests)
+
+Whole-file ``cover_html`` reports do not distinguish lines you changed from
+legacy uncovered code. For pull-request iteration, use ``cover_diff`` after
+running tests. It wraps `diff-cover <https://github.com/Bachmann1234/diff_cover>`_
+and reports coverage on the diff against a base branch (Codecov "patch coverage"
+uses the same idea).
+
+```
+ninja cover-begin
+ctest -j8 -R 'some_test_pattern'
+ninja cover-diff
+```
+
+``cover_diff`` collects coverage, then prints uncovered **changed** lines on the
+console and writes ``html-diff/index.html``.
+
+The comparison branch defaults to ``master``. Override at configure time:
+
+```
+cmake .. -DNRN_COVERAGE_DIFF_BRANCH=master ...
+```
+
+Optional: limit instrumentation to compiled sources changed on your branch:
+
+```
+files=$(../ci/coverage_files_from_diff.sh master)
+cmake .. -DNRN_ENABLE_COVERAGE=ON -DNRN_COVERAGE_FILES="${files}" ...
+```
+
+The script lists only ``.cpp`` and ``.c`` files (headers are not compiled).
+It exits with an error when no such files changed; in that case omit
+``-DNRN_COVERAGE_FILES`` and use full or ``cover_diff`` reporting only.