werkcrappit/docs/adr/0005-gradle-integration.md

ADR 0005: Gradle Integration and Gate

• Status: accepted
• Date: 2026-10-01
• PR: #7

Context

The specification (6.4, 6.5) wants a thin Gradle integration on top of the existing info.solidsoft.pitest plugin and an opt-in gate that runs after PIT has finished, judging werkcrappit's own report.

Decision

Plugin de.javagil.werkcrappit. Applied next to info.solidsoft.pitest, it:

• adds de.javagil.werkcrappit:werkcrappit-pit of its own version to PIT's pitest configuration;
• adds the output format WERKCRAPPIT_MUTATION_CRAP to the pitest task, keeping the configured formats, or PIT's default HTML if none are configured;
• passes the werkcrappit { … } options into PIT's pluginConfiguration, keeping the entries of other plugins; the analysis context defaults to <project path>:pitest;
• registers mutationCrapCheck, which depends on pitest.

The PIT plugin sets the task's formats and plugin configuration to its extension's values, which are missing unless a build configures them, and adding to a missing Gradle collection property leaves it missing. So the plugin derives both from the PIT extension instead of adding to the task.

Not attached to check. PIT is expensive; a CI that wants the gate runs mutationCrapCheck explicitly.

Gate. mutationCrapCheck reads mutation-crap.json and calls Gate, which lives in werkcrappit-pit next to the report contract. It compares the exact fraction of every score; it never recomputes the formula. The rules are those of specification 6.4:

1. No maxMutationCrap: the gate is inactive and never fails because of a score.
2. A scored, not excluded method violates the limit exactly when its value is greater; equality passes.
3. A missing, unfinished or unreadable report, an unsupported schema version, an incomplete scope, an INCONCLUSIVE or COMPLEXITY_UNAVAILABLE method is an analysis error, reported as such and not as poor test quality.
4. NO_MUTATION_RESULTS and NO_ELIGIBLE_MUTANTS are noted, never judged.
5. No scored method at all fails as an empty evaluation, unless allowEmpty is set; it is reported only when no other analysis error explains it.
6. The gate depends on pitest; when PIT fails, Gradle never runs it, and a run that died inside PIT left a RUNNING report (ADR 0004).

Up to date. The gate declares no outputs and always runs; judging is cheap. The limit is not an input of pitest, so changing it does not repeat PIT.

Multi-project builds. Each project has its own pitest task, report directory, context and gate; nothing is merged across projects.

Consequences

• A build that configures the pitest task's outputFormats or pluginConfiguration directly, instead of the pitest extension, has those values replaced; the README says to use the extension.
• maxMutationCrap accepts any number; it is converted through its decimal text, so 10.92 stays 10.92.