From 57c4a7bcfd68da7daaaf33d06b038877a88d8453 Mon Sep 17 00:00:00 2001
From: omartelo <meopedevts@proton.me>
Date: Thu, 16 Jul 2026 13:15:45 -0300
Subject: [PATCH] chore: mutation testing via gremlins

`task mutation` runs go-gremlins/gremlins over the module; scope a package with
`task mutation -- ./internal/store/`. .gremlins.yaml pins workers to 1, which is
load-bearing: the default one-worker-per-CPU runs mutant test binaries in
parallel and the SQLite-backed store tests then contend and time out en masse
(every mutant TIMED OUT, efficacy 0%). Single-worker efficacy on internal/store
is ~97% with zero timeouts. timeout-coefficient gives slow packages (terminal
spawns real PTYs) headroom before a genuine hang is declared timed out.
---
 .gremlins.yaml | 11 +++++++++++
 Taskfile.yml   | 10 ++++++++++
 2 files changed, 21 insertions(+)
 create mode 100644 .gremlins.yaml

diff --git a/.gremlins.yaml b/.gremlins.yaml
new file mode 100644
index 000000000..63ab701cb
--- /dev/null
+++ b/.gremlins.yaml
@@ -0,0 +1,11 @@
+# Mutation-testing config for `task mutation` (go-gremlins/gremlins).
+#
+# workers: 1 is load-bearing. Gremlins defaults to one worker per CPU and runs
+# mutant test binaries in parallel; the SQLite-backed store tests then contend
+# and start timing out — every mutant reported TIMED OUT, efficacy 0%. That is
+# machine contention, not a weak suite (single-worker efficacy on internal/store
+# is ~97%). timeout-coefficient buys slow packages (terminal spawns real PTYs)
+# headroom before a genuine hang is declared timed out.
+unleash:
+  workers: 1
+  timeout-coefficient: 20
diff --git a/Taskfile.yml b/Taskfile.yml
index 093040485..451381b9f 100644
--- a/Taskfile.yml
+++ b/Taskfile.yml
@@ -64,6 +64,16 @@ tasks:
       - cmd: go test ./...
       - cmd: cd frontend && pnpm test
 
+  mutation:
+    summary: 'Mutation tests via gremlins (config: .gremlins.yaml). Scope with -- ./pkg/'
+    preconditions:
+      - sh: command -v gremlins
+        msg: "gremlins is required: go install github.com/go-gremlins/gremlins/cmd/gremlins@latest"
+    cmds:
+      # No path → whole module (slow: single-worker, terminal spawns real PTYs).
+      # Scope a run with: task mutation -- ./internal/store/
+      - cmd: gremlins unleash {{.CLI_ARGS}}
+
   package:
     summary: Builds the Linux packages (deb, rpm, archlinux) into bin/
     deps: [build]