Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,110 @@
# Stryker Mutation-Testing
**Status:** `backlog: test-coverage.md (Phase 10) fertig + Bedarf nach höherer Test-Quality (z.B. nach unentdecktem Critical-Bug in Production der trotz hoher Coverage durchgekommen ist)`
**Task-ID:** #77
**Phase:** 11 (Backlog)
**Estimated Effort:** ~1 Woche Setup + Tuning + Initial-Fix-Sprint wenn aktiviert
**Owner:** unassigned
## Problem
Coverage-Zahlen aus Phase 10 (`test-coverage.md`) sagen nur, dass Code „ausgeführt" wurde, nicht dass das Verhalten „verifiziert" wurde. Tests, die zwar Coverage erzeugen aber keine echten Assertions machen (z.B. `expect(result).toBeDefined()` statt `expect(result).toEqual({...})`), bleiben unentdeckt. Sobald Coverage > ~80% etabliert ist und trotzdem Bugs in Production rutschen, lohnt sich Mutation-Testing als nächster Quality-Hebel.
Mutation-Testing ist sehr build-intensiv (Faktor 50-500x normale Test-Laufzeit, weil pro Mutation die volle Test-Suite gegen mutierten Code läuft). Vorab-Aktivierung ohne stabile Coverage-Baseline wäre verfrüht, weil zuerst Coverage hochgezogen werden muss, bevor Mutation-Score sinnvoll wird.
## Depends on
- `../10-compliance-polish/test-coverage.md` — Coverage muss erst belastbar sein, sonst ist Mutation-Score nicht aussagekräftig
- bestehende Vitest-Setup im Codebase
## Blocks
- nichts (Backlog-Item, blockt keine aktive Roadmap)
## Approach
**Stryker (`@stryker-mutator/core` + `@stryker-mutator/vitest-runner`) als Nightly-Job, nicht als PR-Check.** Begründung:
- *Stryker als PR-Check*: würde PR-Builds um Faktor 50+ verlangsamen. Verworfen.
- *Stryker als Nightly-Job (gewählt)*: läuft auf separatem CI-Runner über Nacht, Report wird morgens als GitHub-Action-Artifact + Slack/Email-Notification ausgeliefert. Slow-Feedback, aber für Mutation-Testing akzeptabel.
- *Andere Mutation-Tools (Pitest für Java, mutmut für Python)*: nicht relevant — TS-Codebase, Stryker ist Standard.
**Was Stryker macht:** mutiert Code in kleinen Weisen — Operator-Swap (`+` → `-`, `===` → `!==`), Boolean-Flip (`true` → `false`), Return-Value-Replacement (`return x` → `return null`), Conditional-Boundary-Shifts (`<` → `<=`) — und prüft, ob die Test-Suite den mutierten Code „killt" (Test failt). Wenn ein Mutant „überlebt" (alle Tests bleiben grün trotz Mutation), ist das ein Hinweis auf schwache Tests.
**Score-Target:** Mutation-Score (`killed / total`) **>70% auf Critical-Paths** (Auth, Billing, Tenant-Isolation, Audit-Logging, AI-Cost-Tracking). Niedrigere Schwelle für Non-Critical-Paths (UI-Komponenten, Marketing-Pages) — dort ist Mutation-Testing weniger wertvoll und kostet zu viel CI-Zeit.
**Tuning:** anfänglich nur ausgewählte Pakete/Module mutieren, nicht den ganzen Monorepo (sonst läuft Nightly-Job über 24h). Inkrementell ausweiten wenn CI-Kapazität es zulässt.
**Initial-Fix-Sprint:** nach erstem Stryker-Run werden vermutlich viele „überlebende" Mutanten gefunden. Sprint priorisiert Critical-Path-Survivors, fügt fehlende Assertions hinzu, fixt schwache Tests. Pro Modul ein Commit.
## Implementation Steps
1. **Stryker-Install + Minimal-Config** — `@stryker-mutator/core` + `@stryker-mutator/vitest-runner` als Dev-Deps, `stryker.config.mjs` mit Scope auf zunächst nur 1-2 Critical-Module (z.B. `app/utils/auth/` + `app/modules/billing/`). Commit: `11-backlog/stryker: install + minimal config for auth + billing`
2. **Erster Lokal-Run + Baseline-Report** — `npx stryker run` lokal, Output sichten, Baseline-Mutation-Score dokumentieren in `docs/quality/mutation-testing.md`. Commit: `11-backlog/stryker: baseline report`
3. **Nightly-CI-Workflow** — GitHub-Actions-Workflow `mutation-testing-nightly.yml`, läuft 03:00 UTC, läuft Stryker für definierten Scope, lädt HTML-Report als Artifact hoch, postet Score in Slack/Discord (oder Issue-Comment). Commit: `11-backlog/stryker: nightly ci workflow`
4. **Initial-Fix-Sprint (Auth-Module)** — überlebende Mutanten im Auth-Modul analysieren, fehlende Assertions hinzufügen oder neue Test-Cases. Pro logischem Fix-Block ein Commit `11-backlog/stryker: kill <n> mutants in <module>`
5. **Initial-Fix-Sprint (Billing-Module)** — gleiches für Billing
6. **Scope-Erweiterung Critical-Path-Module** — Tenant-Isolation-Module, Audit-Logging-Module, AI-Cost-Tracking-Module hinzunehmen. Commit: `11-backlog/stryker: expand scope to tenant + audit + ai-cost`
7. **Score-Gate für Critical-Paths** — Stryker-Config: `thresholds.high=80, thresholds.low=70, thresholds.break=70` für Critical-Path-Module, Nightly failt unter 70%. Commit: `11-backlog/stryker: enforce 70% threshold on critical paths`
8. **Doku** — `docs/quality/mutation-testing.md`: was Mutation-Testing ist, wie man den Nightly-Report liest, wie man überlebende Mutanten fixt, welche Module im Scope sind. Commit: `11-backlog/stryker: documentation`
## Test Requirements
- **Lokaler Stryker-Run** funktioniert auf einem Critical-Path-Modul ohne Crash
- **Nightly-CI-Workflow** läuft erfolgreich durch (mind. 1x bestätigt auf Staging-Branch)
- **HTML-Report** wird als Artifact gespeichert und ist downloadbar
- **Score-Threshold** wird durchgesetzt: ein bewusst eingeführter „leerer Assertion"-Test in Critical-Path muss den Nightly failen lassen
- **Coverage-Target:** Mutation-Score >70% auf jedem Critical-Path-Modul (Auth, Billing, Tenant, Audit, AI-Cost) nach Initial-Fix-Sprint
- **Test-Files:** keine neuen Test-Files dediziert für Stryker; existing Tests werden verbessert
**NICHT als completed markieren bevor mind. 2 Critical-Path-Module die 70%-Schwelle erreichen.**
## Acceptance Criteria
- [ ] Stryker installiert + konfiguriert mit Scope auf mind. 5 Critical-Path-Module
- [ ] Lokaler Run funktioniert
- [ ] Nightly-CI-Workflow läuft stabil, postet Report in Notification-Channel
- [ ] HTML-Report als Artifact verfügbar
- [ ] Initial-Fix-Sprint: alle Critical-Path-Module erreichen Mutation-Score ≥70%
- [ ] Score-Threshold im CI durchgesetzt (Nightly failt bei Threshold-Bruch)
- [ ] `docs/quality/mutation-testing.md` mit Erklärung + Report-Reading-Guide + Scope-Liste
- [ ] Tests grün
- [ ] Progress-Log + PROGRESS.md aktualisiert
## Rollback Strategy
- Stryker ist purely additive Quality-Tooling — Entfernen brichtnichts in der App-Funktionalität
- Nightly-CI-Workflow kann via GitHub-Actions-UI deaktiviert werden, Default-Build-Pipeline läuft unverändert
- Wenn Mutation-Score-Gate falsche Positives produziert: Scope verkleinern statt Tool entfernen
- Stryker-Config in einer Datei (`stryker.config.mjs`) — einfacher Revert
## Security Notes
- Stryker mutiert Source-Code in temporären Ordnern — sicherstellen, dass `.gitignore` `.stryker-tmp/` enthält (gleich beim Setup)
- Nightly-CI-Runner braucht read-only Code-Access, keine Secrets — Stryker macht keine Network-Calls
- HTML-Report enthält Source-Code-Snippets — als private GitHub-Action-Artifact halten, nicht öffentlich
## Subagent Recommendations
- **Planning:** `Plan`-Subagent mit Critical-Path-Modul-Liste als Input
- **Research:** `Explore`-Subagent für Stryker-Best-Practices in Monorepos (insb. wie man Scope sinnvoll begrenzt)
- **Implementation:** ein `general-purpose`-Subagent pro Step
- **Tests (Fix-Sprint):** ein `general-purpose`-Subagent pro Critical-Path-Modul für das Kill-Mutants-Refactoring
- **Verification:** `gsd-verifier` für Threshold-Enforcement-Test (bewusst leerer Test → Nightly muss fail)
- **Code-Review:** `gsd-code-reviewer` nach jedem Fix-Sprint-Modul
## Staging-Deployment-Steps
1. Branch `agent/11-backlog-stryker` pushen
2. Lokaler Stryker-Run auf Auth-Modul, Report sichten
3. Nightly-Workflow auf Branch testen (manueller Trigger via `workflow_dispatch`)
4. HTML-Report-Artifact downloaden, manuell inspizieren
5. Bewusst leeren Test einbauen, Nightly muss failen — danach revertieren
## Deviations from Plan
_(Wird vom ausführenden Agent gefüllt.)_
## Progress Log
_(Wird vom ausführenden Agent gefüllt.)_