feat: add @SimpleBuilderFor for generating builders of external types (#293)

[igel-devin-ai]

Summary

Implements #293: a new @SimpleBuilderFor annotation that generates builders for types that cannot carry @SimpleBuilder themselves — external/library classes or any type you don't want to annotate.

@SimpleBuilderFor(
    value = {ExternalUser.class, ExternalOrder.class},
    options = @SimpleBuilder.Options(builderSuffix = "Factory"))
public class ExternalBuilders {}

Placement: value accepts one or more Class<?>; options reuses SimpleBuilder.Options and falls back to compiler defaults. Generated builders are written to the holder class's package (the target-package selection stays a separate concern, #294). Naming follows the existing <SimpleName><builderSuffix> convention.

Processor wiring (BuilderProcessor): holders are collected via getElementsAnnotatedWith(SimpleBuilderFor.class), expanded into ElementToGenerate(element, config, builderPackage, reportingElement) where builderPackage is the holder's package and reportingElement routes diagnostics to the holder. Config resolves via a new BuilderConfigurationReader.resolveExternalConfiguration (defaults → compiler args → options attribute only — the foreign type's own annotations are ignored). Duplicate builder names (two holders, or direct @SimpleBuilder + @SimpleBuilderFor) are skipped with a warning, as are @Ignore4BuilderGeneration targets.

Scoping semantics: an explicit declaration always generates — builderGenerationPackages does not filter @SimpleBuilderFor targets; a conflicting scope emits a warning instead. BuilderScopeResolver now registers the actual builder TypeName per target (registerGeneratedBuilders(Map)); the builderUsagePackages filter keeps applying to all references, including generated-in-round builders — its position ahead of the generated-builder lookup is unchanged.

Accessibility: generation fails with a clear diagnostic (warning; error under -Asimplebuilder.strict=true) when the target type isn't visible from the builder package or has no accessible constructor — ProcessingContext.isMemberAccessibleFromBuilderPackage gates constructor, setter, and getter selection, so generated code only calls members it may legally call (also fixes latent private-constructor/member selection on the @SimpleBuilder path).

Jackson: JacksonModuleGenerator now groups modules by the generated builder's package instead of the target's.

Example: example/ExternalTypeBuilders + external/ExternalAddress produce example/ExternalAddressBuilder (committed under generated-example-builder/), exercised by ExternalAddressBuilderTest. The surefire/junit-engine harness fix for the example module is split out: #297

Tests: new SimpleBuilderForTest (12 cases: multi-value, options, records, inaccessible members, no-accessible-ctor, strict mode, collisions, scope override warning, consumer wiring). Updated BuilderScopeResolverTest for the Map-based registration and the verbose log assertions for the new log lines. mvn clean verify: BUILD SUCCESS (462 processor tests + 30 example tests).

[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!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud