Propagate deprecation metadata from DTO source elements into generated builders (#235)

[AndreasIgel]

Description

Resolves #235

Problem

Generated builders did not carry @Deprecated annotations or @deprecated Javadoc from the source DTO elements. Consumers of the generated builder APIs had no indication that a property or DTO class was deprecated, and the generated implementation code produced unchecked deprecation warnings when internally calling deprecated DTO members.

Solution

This PR propagates deprecation metadata through the full DTO-to-builder generation pipeline:

Deprecation propagation to generated builder methods:

• @Deprecated on constructor parameters, record components, setter methods, and field types is detected and propagated to all generated builder methods for that property (fluent setter, supplier, consumer, varargs, string-format, collection helpers, With interface).
• since and forRemoval attributes are preserved.
• @deprecated Javadoc text is extracted from the enclosing executable (setter/constructor) or record component and added to the generated method Javadoc.

Deprecation propagation from DTO class:

• @Deprecated on the DTO class propagates to the generated builder class itself, both constructors, and the create() factory method.

Class-level suppression:

• The generated builder class receives @SuppressWarnings({"deprecation", "removal"}) when any internal call touches a deprecated member:
  • Deprecated DTO class
  • Deprecated selected constructor
  • Deprecated getter called by the from-instance constructor
  • Deprecated builder methods (e.g. from deprecated setter/parameter/record component/field type) called by other generated helpers
  • Deprecated collection element types — the generated collection helper calls the element builder's create() internally

Design decisions:

• Getter deprecation is not a propagation source — the builder exposes no get-API; only the from-instance constructor calls the getter internally, covered by class-level suppression. The getter deprecation flag is stored in GetterInfoDto during field creation and checked separately.
• Setter deprecation is a propagation source — the builder's fluent methods replace the setter as the write API for the property. Setter deprecation is covered by the general anyMethodDeprecated check since it propagates @Deprecated to builder methods.
• Backing field deprecation is not checked — it is uncommon to deprecate a field without also deprecating the setter or constructor parameter, and checking the field adds complexity without practical value.
• @Deprecated is not copied to builder method parameters — the parameter is a new declaration; deprecation is about the property, not the parameter value. The annotation is applied to the builder method itself via DeprecationInfoDto.

Changes

Implementation:

• DeprecationInfoDto — new DTO carrying the @Deprecated annotation (with since/forRemoval) and @deprecated Javadoc text.
• GetterInfoDto — new record consolidating getter name and deprecation flag, set during field creation. Enforces non-null getter name via compact constructor.
• FieldDto — nullable deprecationInfo field; isDeprecated() derives from deprecatedAnnotation != null. getterInfo field replaces separate getterName/getterDeprecated fields; convenience methods getGetterName() and isGetterDeprecated() delegate to it.
• FieldAnnotationExtractor — extractDeprecatedAnnotation(Element, ProcessingContext) detects @Deprecated on any element without applying annotation filters. @Deprecated added to ANNOTATION_FILTERS so it is no longer copied to builder parameters. Split extractAnnotation into filtering and non-filtering variants.
• BuilderDefinitionCreator — detectAndApplyFieldDeprecation(...) detects deprecation from parameter -> record component -> setter -> field type (getter and backing field excluded). applyDeprecationToMethod(...) applies @Deprecated and Javadoc to generated methods. applyDeprecationSuppressions(...) adds class-level @SuppressWarnings based on internal deprecated calls, using DEPRECATED_TYPE = map2TypeName(Deprecated.class) for type-safe TypeName comparison.
• JavaLangAnalyser — added findFieldElement(...) (using ElementFilter.fieldsIn(...)), findRecordComponent(...), and extractDeprecatedJavaDoc(...) helpers.
• RoasterCodeGenerator — renders @Deprecated and @SuppressWarnings via applyAnnotations with simple-name handling for java.lang annotations.
• JavadocDto — added addDeprecated(String) for @deprecated tag support.

Tests:

• AnnotationCopyTest — 22 tests covering: deprecated constructor parameter, deprecated setter, deprecated record component, deprecated DTO class (full text-block comparison with minimal options), deprecated Javadoc propagation, since/forRemoval attribute preservation, deprecated getter (no method-level propagation, class-level suppression only, getter call in from-instance constructor), deprecated field type (method-level deprecation + class suppression), deprecated element builder (class-level suppression for collection helper calling deprecated element builder), and framework annotation filtering.

[codecov]

Codecov Report

❌ Patch coverage is 91.89189% with 15 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
.../builders/processor/analysis/JavaLangAnalyser.java	85.36%	1 Missing and 5 partials ⚠️
...s/processor/analysis/FieldAnnotationExtractor.java	66.66%	2 Missing and 3 partials ⚠️
...processor/processing/BuilderDefinitionCreator.java	96.63%	0 Missing and 4 partials ⚠️

📢 Thoughts on this report? Let us know!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud