From faf716de7ad4b69486e42de591588d8b750bbdb9 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sat, 16 May 2026 10:29:50 -0500
Subject: fix(coverage): include gptel-tools in instrumentation glob

Undercover now instruments gptel-tools/*.el alongside modules/*.el,
so the new git_status / git_log / git_diff / web_fetch tools (and
their successors) report coverage instead of reading as zero.

The matching pre-coverage clean step deletes gptel-tools/*.elc so
stale byte-compiled artifacts don't shadow the .el sources.  If
Emacs loads the .elc first, undercover's source instrumentation
never runs.

docs/design/coverage.org gains an Elisp-coverage-producer subsection
documenting the glob, the :merge-report dependence (SimpleCov merges
cross-process reports, LCOV does not), and the missing-artifact
failure mode.
---
 Makefile                   |  4 ++--
 docs/design/coverage.org   | 31 +++++++++++++++++++++++++++++++
 tests/run-coverage-file.el |  1 +
 3 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 02ee56bb..4e19149d 100644
--- a/Makefile
+++ b/Makefile
@@ -234,8 +234,8 @@ COVERAGE_EXCLUDE = \
 COVERAGE_TESTS = $(filter-out $(COVERAGE_EXCLUDE),$(UNIT_TESTS))
 
 coverage: coverage-clean $(COVERAGE_DIR)
-	@echo "[i] Deleting modules/*.elc so undercover can instrument sources..."
-	@rm -f $(MODULE_DIR)/*.elc
+	@echo "[i] Deleting compiled coverage targets so undercover can instrument sources..."
+	@rm -f $(MODULE_DIR)/*.elc gptel-tools/*.elc
 	@echo "[i] Running coverage across $(words $(COVERAGE_TESTS)) test files..."
 	@echo "    (this is slower than 'make test' — each file runs in its own Emacs)"
 	@echo "    excluded from coverage: $(notdir $(COVERAGE_EXCLUDE))"
diff --git a/docs/design/coverage.org b/docs/design/coverage.org
index b5083f66..acd8b4c4 100644
--- a/docs/design/coverage.org
+++ b/docs/design/coverage.org
@@ -66,6 +66,37 @@ Three files:
 
 =init.el= requires the core and the active backends.
 
+*** Elisp coverage producer
+
+For the Elisp backend, =make coverage= is the only supported producer of the
+coverage artifact.  It removes stale compiled files for instrumented sources,
+then runs each unit test file in its own batch Emacs process.  Before loading
+the test file, the Makefile loads =tests/run-coverage-file.el=, which
+initializes packages and configures Undercover:
+
+#+begin_src emacs-lisp
+(undercover "modules/*.el"
+            "gptel-tools/*.el"
+            (:report-format 'simplecov)
+            (:report-file ".coverage/simplecov.json")
+            (:merge-report t)
+            (:send-report nil))
+#+end_src
+
+Undercover is therefore the instrumentation layer: it instruments
+=modules/*.el= and =gptel-tools/*.el=, records Edebug stop-point hits while
+tests execute, and writes the line hit arrays.  SimpleCov is the local
+interchange format consumed by the rest of this design.  The split-per-test-file
+Makefile strategy depends on =:merge-report t=; Undercover can merge SimpleCov
+reports across separate Emacs processes, while its LCOV writer cannot merge
+reports.  This is the concrete reason the artifact is
+=.coverage/simplecov.json= rather than =coverage.lcov=.
+
+The Makefile excludes tests that are incompatible with instrumented source
+loading, such as byte-compilation checks.  If =.coverage/simplecov.json= is not
+created, the coverage run is considered failed; downstream report commands
+should not infer partial coverage from a missing artifact.
+
 *** Backend protocol
 
 Each backend is a plist registered into =cj/coverage-backends=:
diff --git a/tests/run-coverage-file.el b/tests/run-coverage-file.el
index 50a0ed2e..6ac65300 100644
--- a/tests/run-coverage-file.el
+++ b/tests/run-coverage-file.el
@@ -32,6 +32,7 @@
 (setq undercover-force-coverage t)
 
 (undercover "modules/*.el"
+            "gptel-tools/*.el"
 			(:report-format 'simplecov)
 			(:report-file ".coverage/simplecov.json")
 			(:merge-report t)
-- 
cgit v1.2.3