build: add a coverage target and CI job

.github/workflows/ci.yml

@@ -16,6 +16,32 @@ jobs:
       - name: Test
         run: make test
 
+  # Reports only, no threshold. We don't know the baseline yet, and a gate set
+  # from a guess just gets ignored. Add --fail-under-line once the number settles.
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install gcovr
+        run: sudo apt-get update && sudo apt-get install -y gcovr
+      - name: Build instrumented and run suite
+        run: make coverage
+      - name: Summary
+        if: always()
+        run: |
+          {
+            echo '## Coverage'
+            echo '```'
+            cat coverage.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload HTML report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: coverage-html/
+
   windows:
     runs-on: windows-latest
     defaults:

.gitignore

@@ -149,6 +149,13 @@ CLAUDE.md
 /a_compute.bin
 /a_compute.ttinsn
 
+# gcov instrumentation and the reports make coverage builds from it
+*.gcda
+*.gcno
+*.gcov
+/coverage.txt
+/coverage-html/
+
 # Header dependency files from -MMD
 *.d
 tdf_flag_out.txt

CHANGELOG.md

@@ -161,6 +161,16 @@ Booth — Changelog
 - guard the divergent-return lowering against regressing to `s_endpgm`
   (Zane Hambly, 2026-07-26)
 
+- #154: `make coverage` builds an instrumented tree and reports line coverage
+  via gcovr, with a CI job that posts the summary and uploads the HTML
+  (Zane Hambly, 2026-08-02)
+
+- #154: cover the SSA register allocator, which had never been run by a test.
+  Six fixtures and any `--max-vgprs` below 8 leave virtual registers
+  unallocated under `--ssa-ra`; those are pinned in `tests/tra_ssa.c` until
+  the allocator is fixed
+  (Zane Hambly, 2026-08-02)
+
 ### Documentation
 
 - drop the LLVM requirement from the usage documentation

Makefile

@@ -12,14 +12,19 @@ else
   GCC_ONLY =
 endif
 
+# Empty for a normal build. `make coverage` re-invokes make with this set, and
+# it lands at the end of CFLAGS/TCFLAGS so its -O0 beats the -O2 above.
+COVFLAGS =
+
 CFLAGS  = -std=c99 -MMD -MP -Wall -Wextra -pedantic -O2 \
           -Wshadow -Wstrict-prototypes -Wmissing-prototypes \
           -Wformat=2 -Wundef -Wcast-align -Wnull-dereference \
           -Wconversion -Wold-style-definition \
           -Wdouble-promotion -Wswitch-enum -Wwrite-strings \
           -D_FORTIFY_SOURCE=2 -fstack-protector-strong -fPIE $(CF_PROT) \
           $(GCC_ONLY) \
-          -Isrc -Isrc/fe -Isrc/ir -Isrc/tdf -Isrc/backend -Isrc/amdgpu -Isrc/tensix -Isrc/nvidia -Isrc/metal -Isrc/intel -Isrc/triton -Isrc/cpu -Isrc/runtime
+          -Isrc -Isrc/fe -Isrc/ir -Isrc/tdf -Isrc/backend -Isrc/amdgpu -Isrc/tensix -Isrc/nvidia -Isrc/metal -Isrc/intel -Isrc/triton -Isrc/cpu -Isrc/runtime \
+          $(COVFLAGS)
 LDFLAGS = -pie
 LIBS    = -lm
 # Linux/ELF only: -Wl,-z,relro,-z,now -Wl,-z,noexecstack
@@ -83,7 +88,7 @@ $(OBJDIR)/%.o: %.c
 # ---- Test Suite ----
 TCFLAGS = -std=c99 -MMD -MP -D_POSIX_C_SOURCE=200809L -Wall -Wextra -O0 -g \
           -Isrc -Isrc/fe -Isrc/ir -Isrc/tdf -Isrc/backend -Isrc/amdgpu -Isrc/tensix -Isrc/nvidia -Isrc/metal -Isrc/intel -Isrc/triton -Isrc/cpu -Isrc/runtime \
-          -Iruntime
+          -Iruntime $(COVFLAGS)
 TSRC    = tests/tmain.c tests/tsmoke.c tests/tcomp.c tests/tenc.c \
           tests/ttabs.c tests/ttypes.c tests/terrs.c tests/tphase.c \
           tests/tdce.c \
@@ -96,6 +101,7 @@ TSRC    = tests/tmain.c tests/tsmoke.c tests/tcomp.c tests/tenc.c \
           tests/twarpsize.c \
           tests/tabend.c \
           tests/tregalloc.c \
+          tests/tra_ssa.c \
           tests/tguard.c \
           tests/ttriton.c \
           tests/ttdf.c \
@@ -190,12 +196,45 @@ uninstall:
 	rm -f $(BINDIR)/$(TARGET)$(EXE)
 	rm -rf $(SHAREDIR) $(CMAKEDIR)
 
+# ---- Coverage ----
+# Instrumented objects live in their own tree. Sharing one with the normal build
+# means a later `make test` relinks against gcov objects and dies on missing
+# __gcov symbols, which reads like a broken toolchain rather than a stale tree.
+COVDIR  := build/cov-$(UNAME_S)
+
+# kath is instrumented too, not just trunner: trv_elf, ttdf and ttriton shell out
+# to ./kath, so a lot of the backend is only reached through the real binary.
+# -U_FORTIFY_SOURCE because glibc #warnings at -O0 when it's set, and -Werror
+# turns that into a build failure.
+# -w because -O0 drops the value-range info that lets -Wformat-truncation prove
+# its bounds at -O2, so the strict set fires on code that is fine. The normal
+# build is the warnings gate; this one only counts lines.
+COV_CF   = --coverage -O0 -U_FORTIFY_SOURCE -w
+
+# Both binaries land in the repo root whichever tree built them, so clear them
+# first to force an instrumented link, and again at the end so the next plain
+# `make` doesn't quietly keep running the instrumented one.
+coverage:
+	rm -f $(TARGET) $(TARGET).exe trunner trunner.exe
+	find $(COVDIR) -name '*.gcda' -delete 2>/dev/null || true
+	$(MAKE) OBJDIR=$(COVDIR) COVFLAGS="$(COV_CF)" $(TARGET) trunner
+	-./trunner --all
+	@command -v gcovr >/dev/null 2>&1 || { echo "gcovr not found. pip install gcovr"; exit 1; }
+	@mkdir -p coverage-html
+	gcovr --root . --object-directory $(COVDIR) \
+	      --filter 'src/' --filter 'runtime/' \
+	      --exclude-unreachable-branches \
+	      --print-summary --txt coverage.txt --html-details coverage-html/index.html
+	rm -f $(TARGET) $(TARGET).exe trunner trunner.exe
+	@echo "report: coverage.txt and coverage-html/index.html"
+
 clean:
-	rm -rf $(OBJDIR)
+	rm -rf $(OBJDIR) $(COVDIR)
 	rm -f $(TARGET) $(TARGET).exe trunner trunner.exe
+	rm -rf coverage.txt coverage-html
 
 # Header deps from -MMD. Without these a header edit leaves stale objects
 # linked in and the build silently disagrees with the source.
 -include $(OBJECTS:.o=.d) $(TOBJS:.o=.d) $(HOSTRT:.o=.d)
 
-.PHONY: all clean test install uninstall
+.PHONY: all clean test install uninstall coverage

tests/tmain.c

@@ -52,7 +52,7 @@ int th_exist(const char *path)
 
 static const char *cat_order[] = {
     "smoke", "compile", "encode", "tables",
-    "types", "errors", "phase", "sched", "abend", "regalloc", NULL
+    "types", "errors", "phase", "sched", "abend", "regalloc", "ra_ssa", NULL
 };
 
 static int cat_idx(const char *cat)