# 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`.