Summary

Fixes #4106 by carrying the JSpecify input and output contracts of reused mapping methods through generated assignments.

MapStruct previously based null guards primarily on source/target nullability and null-value-check strategy. It did not retain whether a selected helper method required a non-null argument or guaranteed a non-null result, which could generate unsafe calls or reject safe constructor mappings.

Implementation

• Add internal assignment contracts for the innermost reused-method input and outermost reused-method result.
• Resolve explicit and scoped JSpecify nullability from selected mapping methods, including methods from uses types.
• Propagate contracts through method chains and conversion wrappers.
• Generate a source guard when a nullable value is passed to a non-null helper parameter.
• Invoke nullable-input helpers directly when their result is not explicitly @Nullable, preserving legacy behavior for unannotated return types.
• Validate constructor parameters against the effective assignment result.
• Preserve legacy behavior for built-ins, forged methods, assignments without method contracts, and -Amapstruct.disableJSpecify=true.
• Add a verbose diagnostic for guards introduced by reused-method input contracts.
• Document null propagation and clarify that JSpecify annotations do not participate in overload selection.

This also covers the related scenarios described in #4077, #4081, and #4086 without adding public API.

Verification

• Exact JSpecify: False positive error for nullable source with nullable-param non-null-return method #4086 reproducer: compiled and executed successfully; generated code invokes mapValue(source.getValue()) directly.
• Explicit-@Nullable return negative case: still produces the expected non-null-constructor diagnostic.
• Full JSpecify*Test suite: 111 tests passed.
• Focused reused-method, disabled-option, and verbose-diagnostic tests: 13 passed.
• Constructor contract regression tests: 2 passed.
• Full processor Surefire results: 3,561 tests, 0 failures, 0 errors.
• Processor Checkstyle: passed with 0 violations.
• Targeted MavenIntegrationTest#fullFeatureTest: passed.

The full reactor clean install -DskipDistribution=true exceeded the local 15-minute command limit after the processor suite completed; the affected integration path and Checkstyle were rerun successfully afterward.