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

.github/workflows/maven.yml

@@ -69,26 +69,27 @@ jobs:
     - name: Build with Maven
       run: mvn -B install -Pmetrics --file pom.xml
 
-    - name: Check for uncommitted generated source changes
+    - name: Verify committed generated example builders
       if: github.event_name == 'pull_request'
       run: |
-        echo "Checking for uncommitted generated source changes..."
-
-        # Check if there are any changes in generated-sources directories
-        if git diff --name-only HEAD | grep -E "target/generated-sources/"; then
-          echo "❌ ERROR: Found uncommitted generated source changes!"
-          echo ""
-          echo "The following generated files have changed:"
-          git diff --name-only HEAD | grep -E "target/generated-sources/" | sed 's/^/  /'
-          echo ""
-          echo "Please commit these changes to the repository:"
-          echo "  git add target/generated-sources/"
-          echo "  git commit -m \"Update generated sources\""
-          echo ""
+        # Regenerate the example builders from a clean slate into their tracked
+        # directory. Deleting first means a *missing* builder (generator
+        # regression) shows up as a git deletion, stale output as a
+        # modification, and a brand-new builder as an untracked file — so any
+        # drift fails the check. (Dependencies were installed by the build step
+        # above, so -pl example is sufficient here.)
+        rm -rf example/generated-example-builder
+        mvn -B -q -DskipTests -pl example clean compile
+
+        CHANGES="$(git status --porcelain -- example/generated-example-builder)"
+        if [ -n "$CHANGES" ]; then
+          echo "::error::Committed generated example builders are out of date or missing."
+          echo "Run 'mvn -pl example clean compile' and commit example/generated-example-builder/."
+          echo "$CHANGES"
+          git --no-pager diff -- example/generated-example-builder
           exit 1
-        else
-          echo "✅ No uncommitted generated source changes found"
         fi
+        echo "Committed generated example builders are up to date."
 
     - name: Package Sonar analysis inputs (fork PRs)
       if: always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository

README.md

@@ -316,24 +316,24 @@ A comprehensive example showcasing all fundamental Java property types with a mi
 
 - **Source DTO**: [`BookDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/BookDto.java) - Demonstrates all primitive types, collections, Optional, BigDecimal, date/time types, and nested objects
 - **Custom Annotation**: [`@ElementaryBuilder`](example/src/main/java/org/javahelpers/simple/builders/example/ElementaryBuilder.java) - A template annotation that disables all advanced features (suppliers, consumers, collection builders, With interface, @Generated annotation)
-- **Generated Builder**: [`BookDtoBuilder.java`](example/target/generated-sources/annotations/org/javahelpers/simple/builders/example/BookDtoBuilder.java) - Clean, minimal builder with only setter methods
+- **Generated Builder**: [`BookDtoBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/BookDtoBuilder.java) - Clean, minimal builder with only setter methods
 - **Tests**: [`BookDtoBuilderTest.java`](example/src/test/java/org/javahelpers/simple/builders/example/BookDtoBuilderTest.java) - Usage examples
 
 ### Full-Featured Examples
 
 Examples with all builder features enabled:
 
-- **Person DTO**: [`PersonDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/PersonDto.java) and [`PersonDtoBuilder.java`](example/target/generated-sources/annotations/org/javahelpers/simple/builders/example/PersonDtoBuilder.java) - Demonstrates nested objects, collections, suppliers, conditional logic, and various setter patterns
+- **Person DTO**: [`PersonDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/PersonDto.java) and [`PersonDtoBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/PersonDtoBuilder.java) - Demonstrates nested objects, collections, suppliers, conditional logic, and various setter patterns
   - **Usage Examples**: [`PersonDtoBuilderTest.java`](example/src/test/java/org/javahelpers/simple/builders/example/PersonDtoBuilderTest.java) - Shows supplier methods, collection builders, nested builder consumers, and conditional logic
-- **Product Record**: [`ProductRecord.java`](example/src/main/java/org/javahelpers/simple/builders/example/ProductRecord.java) and [`ProductRecordBuilder.java`](example/target/generated-sources/annotations/org/javahelpers/simple/builders/example/ProductRecordBuilder.java) - Java Record support with full builder features and With interface pattern
+- **Product Record**: [`ProductRecord.java`](example/src/main/java/org/javahelpers/simple/builders/example/ProductRecord.java) and [`ProductRecordBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/ProductRecordBuilder.java) - Java Record support with full builder features and With interface pattern
   - **Usage Examples**: [`ProductRecordTest.java`](example/src/test/java/org/javahelpers/simple/builders/example/ProductRecordTest.java) - Comprehensive tests demonstrating With interface for immutable Records, fluent modifications, and custom with methods
 
 ### Advanced Features
 
 Examples demonstrating special annotations and nested object relationships:
 
-- **Sponsor DTO**: [`SponsorDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/SponsorDto.java) and [`SponsorDtoBuilder.java`](example/target/generated-sources/annotations/org/javahelpers/simple/builders/example/SponsorDtoBuilder.java) - Simple DTO used as nested object in other examples
-- **Mannschaft DTO**: [`MannschaftDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/MannschaftDto.java) and [`MannschaftDtoBuilder.java`](example/target/generated-sources/annotations/org/javahelpers/simple/builders/example/MannschaftDtoBuilder.java) - Demonstrates `@IgnoreInBuilder` annotation to exclude specific setter methods from the generated builder, plus Set collections with nested objects
+- **Sponsor DTO**: [`SponsorDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/SponsorDto.java) and [`SponsorDtoBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/SponsorDtoBuilder.java) - Simple DTO used as nested object in other examples
+- **Mannschaft DTO**: [`MannschaftDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/MannschaftDto.java) and [`MannschaftDtoBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/MannschaftDtoBuilder.java) - Demonstrates `@IgnoreInBuilder` annotation to exclude specific setter methods from the generated builder, plus Set collections with nested objects
 
 These examples serve as both documentation and integration tests for the annotation processor.
 

example/pom.xml

@@ -80,7 +80,10 @@
           <source>${java.version}</source>
           <target>${java.version}</target>
           <release>${java.version}</release>
-          <generatedSourcesDirectory>${project.build.directory}/generated-sources/annotations</generatedSourcesDirectory>
+          <!-- Emit generated builders into a tracked directory (outside target/)
+               so they survive `mvn clean`, can be browsed/reviewed, and drift is
+               detectable via `git diff` in CI. -->
+          <generatedSourcesDirectory>${project.basedir}/generated-example-builder</generatedSourcesDirectory>
         </configuration>
         <executions>
           <execution>