Track generated example builders outside target/ and harden the generation gate

[AndreasIgel]

Upstream counterpart of fork PR AndreasIgel#14. Head branch: AndreasIgel/simple-builders-fork:feature/167-tracked-generated-sources → base java-helpers/simple-builders:main.

Summary

Makes the committed example builders durable and makes the CI gate able to detect a missing builder (generator regression), not just stale output.

Fixes #167

Problem

Generated builders were committed under example/target/generated-sources/ (kept in git via an example/.gitignore exception), and the CI step diffed target/generated-sources/. target/ is wiped by mvn clean and git-ignored by convention, so the committed copies are fragile, and a builder that silently stops being generated leaves no diff → the gate passes.

Changes

• example/pom.xml — point maven-compiler-plugin's generatedSourcesDirectory at a tracked dir outside target/:

  <generatedSourcesDirectory>${project.basedir}/generated-example-builder</generatedSourcesDirectory>

  mvn clean no longer wipes them; they're regenerated (deterministically) on every build.
• Move the 7 committed builders example/target/generated-sources/annotations/... → example/generated-example-builder/..., update the README links to the new path, and remove the doc-only example/.gitignore (it held no ignore rules).
• .github/workflows/maven.yml — replace the target/-diff step with a clean-slate regenerate + git status gate:

  rm -rf example/generated-example-builder
  mvn -B -q -DskipTests -pl example clean compile
  # any modification, deletion (missing builder), or new untracked builder fails:
  [ -z "$(git status --porcelain -- example/generated-example-builder)" ]

• Self-checking signal: the example tests already consume the generated builders (BookDtoBuilder.create(), PersonDtoBuilder.create(), ProductRecordBuilder, the Jackson module), so a missing/broken builder also fails compilation independently of the diff.

Validation (local)

• mvn clean verify → BUILD SUCCESS, 283 tests pass.
• Clean-slate regenerate produces zero drift against the committed sources.
• actionlint passes.

Red build/dependency-review checks on the fork are the missing SONAR_TOKEN/CODECOV_TOKEN and disabled Dependency graph — unrelated to this change.

---

Review follow-ups (addressed): renamed the tracked dir to generated-example-builder (clearer than generated-sources/annotations); removed the comment-only example/.gitignore; rebased onto current main so the already-merged SonarCloud cache-key change (#188) no longer shows in this diff; updated the five README links to the new path.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[AndreasIgel]

If I am remembering correct the generated builders are linked in some markdown files. So these links need to be updated too!?

[AndreasIgel]

Good catch on the markdown links — the README linked the generated builders at example/target/generated-sources/annotations/..., which this PR moves out of target/. Updated all five README links to the new tracked path example/generated-example-builder/... so they resolve in-repo. (The target/generated-sources/annotations mentions in docs/CUSTOMIZING.md / docs/DEBUG_LOGGING.md are generic instructions about where the annotation processor emits output in a consumer's own project, so those are intentionally left unchanged.)