82 lines
4.8 KiB
Markdown
82 lines
4.8 KiB
Markdown
# werkcrappit — Agent Instructions
|
|
|
|
This file holds the shared, tool-agnostic instructions for all AI coding agents.
|
|
Claude Code imports it from `CLAUDE.md` via `@AGENTS.md`.
|
|
|
|
## Specification
|
|
|
|
The specification is [docs/pitest-mutation-crap-coding-agent-auftrag.md](docs/pitest-mutation-crap-coding-agent-auftrag.md) (in German).
|
|
IMPORTANT: Read it before designing or changing anything.
|
|
Do not change its metric formula, its status policy `strict-v1` or its binding constraints without a documented decision.
|
|
The default status policy is `timeouts-killed-v1`, a documented deviation (ADR 0006); `strict-v1` is unchanged and selectable.
|
|
|
|
## Build and Test Commands
|
|
|
|
```bash
|
|
./gradlew build # compile + unit tests + functional tests
|
|
./gradlew :werkcrappit-pit:test --tests "de.javagil.werkcrappit.pit.SomeTest" # a single test class
|
|
./gradlew :werkcrappit-pit:functionalTest # real PIT runs on fixture projects via Gradle TestKit
|
|
./gradlew :werkcrappit-gradle-plugin:functionalTest # the gate in real builds, incl. multi-project
|
|
```
|
|
|
|
## Module Structure
|
|
|
|
- `werkcrappit-pit` (`de.javagil.werkcrappit.pit`) — the PIT plugin JAR: metric core, JaCoCo adapter, PIT result listener, reports.
|
|
- `werkcrappit-gradle-plugin` (`de.javagil.werkcrappit.gradle`) — the Gradle plugin `de.javagil.werkcrappit`: wiring into `info.solidsoft.pitest` and the gate task over the finished report; the gate logic itself is `de.javagil.werkcrappit.pit.gate` in `werkcrappit-pit`.
|
|
|
|
Tests mirror this structure under `src/test/java`.
|
|
Functional tests live in the source set `functionalTest` of each module; their fixture projects consume the plugins as published into the root's `build/functional-test-repo`, never the classes of the build.
|
|
|
|
## Hard Invariants
|
|
|
|
- Mutation results come from the PIT listener interface, never from importing `mutations.xml`.
|
|
- Complexity comes from JaCoCo Core analysing the original, unmutated class files — no JaCoCo agent, no `.exec` file, no extra test run.
|
|
- The metric core knows neither PIT nor JaCoCo nor Gradle types; `CoreIndependenceTest` checks it.
|
|
- A Mutation-CRAP value is compared as an exact fraction (`MutationCrap.exceeds`), never as a rounded or floating-point number.
|
|
- The Gradle plugin holds no second implementation of the formula; it evaluates the report contract.
|
|
- The plugin only observes: it never filters mutants, changes their status or alters PIT's configuration.
|
|
|
|
## Code and Tests
|
|
|
|
- Production code in Java 21; build scripts in Gradle Kotlin DSL.
|
|
- Use `var` or `final var` where it keeps the code readable.
|
|
- Tests with JUnit Jupiter and AssertJ; Mockito only where a test double beats a small real fixture.
|
|
|
|
## File-Formatting
|
|
|
|
Write documentation in English in Markdown files.
|
|
The one exception are the Gherkin features under `docs/features/`: German, as the specification has them (`# language: de`, IDs `@MC-…`).
|
|
In Markdown, use a single line per sentence.
|
|
Keep sentences short.
|
|
|
|
## Documentation
|
|
|
|
- `docs/adr/` — architecture decisions, starting with `0001-pit-integration.md`.
|
|
- `docs/compatibility.md` — the version combinations a functional test actually ran.
|
|
- `docs/guides/` — integration guides for real projects, starting with the pilot hsadmin-ng.
|
|
- `docs/features/` — the acceptance scenarios of the specification as Gherkin (German); `docs/acceptance-test-map.md` maps each `@MC-…` ID to the JUnit tests that verify it.
|
|
- `docs/rfcs/` — proposals larger than one PR and not yet a decision.
|
|
- `docs/prs/` — one document per pull request.
|
|
- `docs/werkcrappit.werkbaum` — the plan; each PR updates the status of its nodes.
|
|
|
|
## Working Mode
|
|
|
|
The specification's section 8.3 has eight steps; each is one pull request with green CI on werkator.javagil.de and its own PR-doc.
|
|
The pilot project is hsadmin-ng (Java); Kotlin stays the specification's optional goal.
|
|
Releases go to the Gitea Maven package registry on git.javagil.de.
|
|
|
|
## Workflow
|
|
|
|
Follow [docs/agentic-workflow.md](docs/agentic-workflow.md), the workflow of all werk repositories:
|
|
roles, steps of a PR, review rounds, PR documents, versions and the writing style.
|
|
In addition, for werkcrappit:
|
|
|
|
- A version is published once and never replaced: the Gitea registry refuses a second upload.
|
|
- The build derives the version from the PR documents, from the base version 0.26.14 on;
|
|
for it, each Gradle run needs the full history and `origin/main`.
|
|
- The release notes stand in the section "Release Notes" of the PR document;
|
|
a change that users do not notice starts with "Internal:".
|
|
`./gradlew changelog` writes them into `build/changelog/CHANGELOG.md`, followed by `CHANGELOG.md`, which ends with 0.26.14.
|
|
- The acceptance scenarios of the specification stay in `docs/features/` (German, IDs `@MC-…`);
|
|
`docs/acceptance-test-map.md` maps each ID to the tests that verify it.
|