Scope builder generation and builder usage by package (#114)

[AndreasIgel]

Summary

Previously the processor emitted a builder reference for every @SimpleBuilder-annotated field/collection-element type. That breaks when the referenced type is a precompiled library DTO whose builder was never generated: the generated code references a class that does not exist.

Two comma-separated package-list options now scope this, and the "may a builder be used here?" decision is centralized in one new class so generators/enhancers stay ignorant of the mechanism — they keep checking only TypeName.getBuilderType().isPresent().

• builderGenerationPackages — when non-empty, BuilderProcessor only generates builders for annotated DTOs in scope. Generation-scope packages are automatically included in the usage scope.
• builderUsagePackages — packages whose builders may be used as helpers. The candidate builder must be verified on the classpath before a reference is emitted; unresolvable ⇒ the field falls back to a plain setter.
• builderUsageSuffix — suffix used when looking up usage builders on the classpath (defaults to builderSuffix when empty). Allows referencing builders generated with a different suffix, e.g. LibraryDtoFactory instead of LibraryDtoBuilder.
• Both scopes empty/unset ⇒ behavior is exactly as before (reference any annotated type, no type search).

Builder contract instead of annotation check

Classpath lookup does not check for @SimpleBuilder (or any other annotation). Instead, the candidate class must satisfy the builder contract:

1. A constructor accepting the referenced type (used when the field already has a value)
2. A no-arg build() method returning the referenced type (used to obtain the built value)

This is annotation-agnostic, so builders generated with custom @SimpleBuilder.Template annotations or external tools are supported. It also avoids false positives like String → StringBuilder.

Decision logic

All in BuilderScopeResolver (analysis/), created once in the ProcessingContext constructor (getBuilderScopeResolver()); it reads the current target configuration on use, re-parses its package scopes only when that configuration changes, and caches the per-type result (Optional<TypeName> by FQN) so each referenced type is analysed once per configuration:

Optional<TypeName> resolveUsableBuilderType(TypeElement referenced) {
  if (referenced == null || hasIgnore4BuilderGeneration(referenced)) return empty(); // opt-out wins
  if (usageScope.isScoped() && !usageScope.includes(pkg))            return empty(); // scope gate
  if (generatedTypeNames.contains(fqn))                              return of(candidate); // trusted, no contract check
  return resolveByBuilderContract(candidate, fqn);                                    // classpath verify
}

The effective usage scope merges builderGenerationPackages and builderUsagePackages via PackageScopes.merge(...), so generation-scope packages never need to be repeated in the usage scope.

generatedTypeNames covers builders being generated in the current processing round — they are trusted without a classpath lookup because our own generators always satisfy the contract. BuilderProcessor resolves configuration and applies the generation filter for all elements first, registers the survivors via BuilderScopeResolver.registerGeneratedTypes(...), and only then generates. Types in neither scope stay unreferenced even when generated in the same round.

Opt-out precedence is structural: @Ignore4BuilderGeneration is checked first in the resolver, so an opted-out type can never be referenced, even when its package is in scope. The previous check in JavaLangMapper was folded into the resolver so there is a single decision point; the mapper now only does resolveUsableBuilderType(...).ifPresent(typeName::setBuilderType) (and the collection-element equivalent).

Package matching is case-insensitive and boundary-aware — Strings.CI.equals(pkg, p) || Strings.CI.startsWith(pkg, p + ".") (so a.bc does not match scope a.b, while COM.Example matches com.example) — implemented once in PackageScopes (model/core/) and shared by the resolver and BuilderProcessor. PackageScopes.merge combines two scopes into a union; BuilderConfiguration.overrideScopes (renamed from mergeScopes — it is an override, not a merge) resolves annotation-level values over compiler-argument-level ones.

Wiring is the usual three layers: SimpleBuilder.Options, CompilerArgumentsEnum / CompilerArgumentsReader (-Asimplebuilder.builderGenerationPackages, -Asimplebuilder.builderUsagePackages, -Asimplebuilder.builderUsageSuffix), BuilderConfigurationReader.parseOptionsFromMirror, and BuilderConfiguration (record field, DEFAULT, builder setter via trimToNull, merge, toString, getters).

Example module

A runnable demo lives in org.javahelpers.simple.builders.example.scoping, with the generated result committed under example/generated-example-builder/. ScopedOwnerDto configures both scopes inline and has three fields covering all three outcomes:

field	type's package	outcome in ScopedOwnerDtoBuilder
trusted	generation scope	trusted(Consumer<TrustedHelperDtoBuilder>) emitted
library	usage scope, builder absent	plain setter only — the bug this PR fixes
sponsor	neither scope	plain setter only, although SponsorDtoBuilder exists

LibraryHelperDto is annotated but configured outside the generation scope, so no builder is generated for it — that is how a precompiled library DTO without a builder is simulated inside one compilation.

Note: the example module's tests are compiled but never executed by Maven (the reactor inherits Surefire 2.12.4 and the module has no JUnit 5 engine), so ScopedOwnerDtoBuilderTest is compile-checked in CI and was run out-of-band via the JUnit Platform launcher (2/2 passing). This is pre-existing and affects the module's other test classes too.

Tests

BuilderScopeProcessingTest covers the compile-level behavior: both options unset (regression), exact and subpackage generation matching, out-of-scope DTOs getting no builder, usage scope with an existing vs. missing builder, a same-round helper with only the usage scope set, opt-out precedence, custom builderUsageSuffix, external builders without @SimpleBuilder, and both the compiler-arg and inline @SimpleBuilder(options = ...) forms. BuilderScopeResolverTest covers the plain-setter fallback, configuration changes on the same resolver instance, result caching, and registration/scope interaction. PackageScopesTest covers comma-splitting/trimming, blank ⇒ unscoped, exact-vs-subpackage matching, prefix-boundary rejection (com.examplefoo does not match com.example), case-insensitivity, and merge semantics. Processor suite: 547 tests green, full reactor mvn test green.

Docs

docs/CONFIGURATION.md gets "Builder Scoping" sections for builderGenerationPackages, builderUsagePackages, and builderUsageSuffix plus entries in the compiler-option and complete-example references; docs/CUSTOMIZING.md notes that custom generators/enhancers need no changes; README.md gets a "Builder Scoping Example" section linking the demo files in the same style as the other example sections.

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

already fixed

[igel-devin-ai]

Already fixed in an earlier commit.

[igel-devin-ai]

Confirmed — the deprecated StringUtils calls were replaced with Strings.CI equivalents in an earlier commit.

[AndreasIgel]

already done...

[igel-devin-ai]

Already fixed in an earlier commit.

[igel-devin-ai]

Confirmed — the string getters were removed in the latest commit. Only the set getters remain.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud