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

README.md

@@ -31,6 +31,7 @@ A zero-reflection Java annotation processor that generates fluent, type-safe bui
   - [Elementary Builder Example](#elementary-builder-example)
   - [Full-Featured Examples](#full-featured-examples)
   - [Advanced Features](#advanced-features)
+  - [Builder Scoping Example](#builder-scoping-example)
 - [Performance Measurement](#performance-measurement)
 - [Contributing](#contributing)
 - [License](#license)
@@ -465,6 +466,16 @@ Examples demonstrating special annotations and nested object relationships:
 - **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
 - **Default Values**: [`ProductWithDefaults.java`](example/src/main/java/org/javahelpers/simple/builders/example/ProductWithDefaults.java) (record) and [`OrderWithDefaults.java`](example/src/main/java/org/javahelpers/simple/builders/example/OrderWithDefaults.java) (class) - Demonstrate `@Default` annotation for unset builder fields
 
+### Builder Scoping Example
+
+A runnable example demonstrating package-scoped builder generation and usage:
+
+- **Source DTO**: [`ScopedOwnerDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/scoping/ScopedOwnerDto.java) - Configures both package scopes inline and demonstrates the generation-scope, usage-scope, and out-of-scope field cases
+- **Trusted helper**: [`TrustedHelperDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/scoping/TrustedHelperDto.java) - In-generation-scope helper whose builder is referenced as a builder consumer
+- **Library helper**: [`library/LibraryHelperDto.java`](example/src/main/java/org/javahelpers/simple/builders/example/library/LibraryHelperDto.java) - Annotated but outside the generation scope, so no builder exists and the owner falls back to a plain setter
+- **Generated Builder**: [`ScopedOwnerDtoBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/scoping/ScopedOwnerDtoBuilder.java) - Shows the consumer overload for `trusted` and plain setters for `library` and `sponsor`
+- **Tests**: [`ScopedOwnerDtoBuilderTest.java`](example/src/test/java/org/javahelpers/simple/builders/example/scoping/ScopedOwnerDtoBuilderTest.java) - Asserts the generated API shape
+
 These examples serve as both documentation and integration tests for the annotation processor.
 
 ## Performance Measurement

core/src/main/java/org/javahelpers/simple/builders/core/annotations/Ignore4BuilderGeneration.java

@@ -40,6 +40,11 @@
  * generation for the exact type it is placed on and does not cascade to further subclasses, which
  * may therefore still get a builder from an inherited {@code @SimpleBuilder} or template
  * annotation.
+ *
+ * <p>This is the per-type opt-out. To restrict generation to whole packages instead (including
+ * types whose {@code @SimpleBuilder} is inherited or applied via a template), use {@code
+ * builderGenerationPackages} in {@link SimpleBuilder.Options} or the {@code
+ * simplebuilder.builderGenerationPackages} compiler option.
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.CLASS)

core/src/main/java/org/javahelpers/simple/builders/core/annotations/SimpleBuilder.java

@@ -60,6 +60,8 @@
  *   <li><b>Collection Helpers:</b> generateVarArgsHelpers, usingArrayListBuilder,
  *       usingArrayListBuilderWithElementBuilders, usingHashSetBuilder,
  *       usingHashSetBuilderWithElementBuilders, usingHashMapBuilder (all default: true)
+ *   <li><b>Builder Scoping:</b> builderGenerationPackages, builderUsagePackages, builderUsageSuffix
+ *       (default: empty)
  *   <li><b>Integration:</b> generateWithInterface (default: true)
  *   <li><b>Documentation:</b> generateJavaDoc (default: true)
  * </ul>
@@ -679,6 +681,56 @@
      */
     OptionState generateJavaDoc() default OptionState.UNSET;
 
+    // === Builder Scoping ===
+    /**
+     * Comma-separated list of packages for which builders are generated. <br>
+     * Subpackages are included automatically and matching ignores case. When non-empty, builder
+     * generation is restricted to DTOs whose package equals or is a subpackage of a listed package.
+     * Types in this scope are trusted to have their builder generated in the same compilation and
+     * may be referenced without a type-existence search; they are automatically usable as helpers
+     * and do not need to be listed in {@link #builderUsagePackages()}.
+     *
+     * <p>On a single class this is mainly useful to <i>opt back in</i>: annotation options take
+     * precedence over the compiler option, so a type can include its own package even when the
+     * global scope excludes it. Set on a {@link Template} annotation or a base class ({@code
+     * SimpleBuilder} is {@code @Inherited}), it instead filters which inheriting types get a
+     * builder. To exclude a single type, prefer {@link Ignore4BuilderGeneration}.
+     *
+     * <p>Example: {@code "com.example.dto, com.example.shared"}
+     *
+     * <p>Default: "" (empty - builders are generated for all {@code @SimpleBuilder} annotated DTOs,
+     * no type search) <br>
+     * Compiler option: -Asimplebuilder.builderGenerationPackages
+     *
+     * @return the packages for which builders are generated
+     */
+    String builderGenerationPackages() default "";
+
+    /**
+     * Comma-separated list of packages whose builders may be used as helper methods for other DTOs.
+     * <br>
+     * Subpackages are included automatically and matching ignores case. The processor constructs
+     * the candidate builder name using {@link #builderUsageSuffix()} (or {@link #builderSuffix()}
+     * if not configured) and verifies that a class with that name exists on the classpath or was
+     * generated in the current processing round. This allows referencing builders generated with
+     * custom template annotations or different suffixes. If the builder type cannot be resolved,
+     * the field falls back to a plain setter.
+     *
+     * <p>Packages in {@link #builderGenerationPackages()} are automatically part of the usage scope
+     * and never need to be repeated here. When this option is empty, builders from any package may
+     * be referenced; once set, only packages listed here (and generation-scope types) may provide
+     * builder helpers.
+     *
+     * <p>Example: {@code "com.example.library, com.example.external"}
+     *
+     * <p>Default: "" (empty - all types may be referenced as builders; the builder type is not
+     * verified to exist on the classpath, preserving backward-compatible behavior) <br>
+     * Compiler option: -Asimplebuilder.builderUsagePackages
+     *
+     * @return the packages whose builders may be used as helpers
+     */
+    String builderUsagePackages() default "";
+
     // === Naming ===
     /**
      * Suffix to append to the DTO name to generate the builder class name. <br>
@@ -702,6 +754,35 @@
      */
     String builderSuffix() default "Builder";
 
+    /**
+     * Suffix to append to the DTO name when looking up a builder from the usage scope. <br>
+     * The processor constructs the candidate builder name using this suffix and verifies that a
+     * class with that name exists on the classpath. If empty, the value of {@link #builderSuffix()}
+     * is used. This allows referencing builders that were generated with a different suffix (e.g.
+     * by another module using "Factory" as suffix) without changing the suffix used for own builder
+     * generation.
+     *
+     * <p>Example:
+     *
+     * <pre>{@code
+     * @SimpleBuilder(options = @SimpleBuilder.Options(
+     *     builderSuffix = "Builder",
+     *     builderUsageSuffix = "Factory"
+     * ))
+     * public class OwnerDto {
+     *     // Own builder: OwnerDtoBuilder
+     *     // Referenced builders from usage scope: looked up as *Factory
+     * }
+     * }</pre>
+     *
+     * Default: "" (empty - falls back to {@link #builderSuffix()}) <br>
+     * Compiler option: -Asimplebuilder.builderUsageSuffix
+     *
+     * @return the suffix for usage-scope builder class names, or empty to use {@link
+     *     #builderSuffix()}
+     */
+    String builderUsageSuffix() default "";
+
     /**
      * Suffix to append to setter method names in the generated builder. <br>
      * For example, with suffix "with", a field named "name" will generate "withName()". <br>

docs/CONFIGURATION.md

@@ -18,6 +18,7 @@ Simple-builders supports fine-grained configuration through the `@SimpleBuilder.
   - [Conditional Logic](#conditional-logic)
   - [Access Control](#access-control)
   - [Collection Helpers](#collection-helpers)
+  - [Builder Scoping](#builder-scoping)
   - [Component Filtering](#component-filtering)
   - [Integration](#integration)
   - [Documentation](#documentation)
@@ -665,6 +666,55 @@ Generates methods using `HashMapBuilder` for fluent Map construction.
 
 ---
 
+### Builder Scoping
+
+#### `builderGenerationPackages`
+
+**Default**: `""` (empty, unchanged behavior) | **Compiler Option**:
+`-Asimplebuilder.builderGenerationPackages=package1,package2`
+
+Restricts builder generation to annotated DTOs in the listed packages. Packages are
+comma-separated, each listed package includes all of its subpackages, and matching ignores
+case. Types in the generation scope are trusted to have their builders generated in the
+current compilation, so references to their builders do not require a type search.
+
+This option is an allowlist for whole packages: once set, builders are generated only inside
+the listed packages and every other package is excluded implicitly. Excluding a single
+package while generating everywhere else is not expressible; to exclude a single class,
+use `@Ignore4BuilderGeneration` instead. The scope also applies to types that carry
+`@SimpleBuilder` only through inheritance or a template annotation.
+
+#### `builderUsagePackages`
+
+**Default**: `""` (empty, unchanged behavior) | **Compiler Option**:
+`-Asimplebuilder.builderUsagePackages=package1,package2`
+
+Controls which packages may provide builders as nested builder helpers. Packages are
+comma-separated, each listed package includes all of its subpackages, and matching ignores
+case.
+
+The processor constructs the candidate builder name using `builderUsageSuffix`
+(or `builderSuffix` if not configured) and verifies the builder contract: a
+constructor accepting the referenced type and a no-arg `build()` method returning
+it. Any class with the expected name and a matching contract qualifies, allowing
+references to builders generated with custom template annotations, external tools,
+or different suffixes. If the candidate builder cannot be found, the field falls
+back to a plain setter.
+
+Packages listed in `builderGenerationPackages` are automatically included in the usage
+scope — their builders are generated in the same compilation and don't need to be listed
+here.
+
+When `builderUsagePackages` is empty, builders from any package may be referenced (the
+behavior before scoping existed). When set, only packages listed in `builderUsagePackages`
+(and generation-scope types) may provide builder helpers — types outside both scopes fall
+back to a plain setter.
+
+The `example` module contains a runnable demo in package
+`org.javahelpers.simple.builders.example.scoping` ([`ScopedOwnerDto.java`](../example/src/main/java/org/javahelpers/simple/builders/example/scoping/ScopedOwnerDto.java)).
+It demonstrates a generation-scope builder consumer, a usage-scope missing-builder fallback, and
+an out-of-scope plain setter in [`ScopedOwnerDtoBuilder.java`](../example/generated-example-builder/org/javahelpers/simple/builders/example/scoping/ScopedOwnerDtoBuilder.java).
+
 ### Component Filtering
 
 #### `deactivateGenerationComponents`
@@ -912,6 +962,39 @@ public class PersonDto { }
 
 ---
 
+#### `builderUsageSuffix`
+
+**Default**: `""` (empty — falls back to `builderSuffix`) | **Compiler Option**:
+`-Asimplebuilder.builderUsageSuffix=CustomSuffix`
+
+Customizes the suffix used when looking up builders from the usage scope. The processor
+constructs the candidate builder name as `referencedType.getSimpleName() + builderUsageSuffix`.
+If empty, `builderSuffix` is used instead. This allows referencing builders that were generated
+with a different suffix (e.g. by another module using `"Factory"` as suffix) without changing
+the suffix used for own builder generation.
+
+The candidate class must provide a constructor accepting the referenced type and a no-arg
+`build()` method returning it. The contract check is annotation-agnostic, so builders
+generated with custom template annotations or external tools are supported. If the
+candidate class does not exist or does not satisfy this contract, the field falls back
+to a plain setter.
+
+**Example**:
+```java
+@SimpleBuilder.Options(
+    builderSuffix = "Builder",       // own builders: *Builder
+    builderUsageSuffix = "Factory"   // usage-scope builders: *Factory
+)
+public class OwnerDto {
+    private ExternalDto external;
+}
+
+// Own builder: OwnerDtoBuilder
+// External builder looked up as: ExternalDtoFactory (not ExternalDtoBuilder)
+```
+
+---
+
 #### `setterSuffix`
 
 **Default**: `""` (empty) | **Compiler Option**: `-Asimplebuilder.setterSuffix=customPrefix`
@@ -952,7 +1035,7 @@ processing. A summary report is logged to the compiler output at the end of proc
 
 **When enabled**: A hierarchical performance report is printed to the compiler log, including:
 - Total processing time and average time per class
-- Phase breakdown (Configuration Resolution, Builder Definition Extraction, DTO Mapping, Code Generation)
+- Phase breakdown (Element Collection, Configuration Resolution, Builder Definition Extraction, DTO Mapping, Code Generation)
 - Top 20 slowest classes with field and collection counts
 - Top 5 slowest MethodGenerators and BuilderEnhancers
 
@@ -1418,6 +1501,10 @@ methodAccess = AccessModifier.PRIVATE
 # Component Filtering
 -Asimplebuilder.deactivateGenerationComponents=pattern1,pattern2,...
 
+# Builder Scoping
+-Asimplebuilder.builderGenerationPackages=package1,package2
+-Asimplebuilder.builderUsagePackages=package1,package2
+
 # Integration & Annotations
 -Asimplebuilder.generateWithInterface=ENABLED|DISABLED
 -Asimplebuilder.implementsBuilderBase=ENABLED|DISABLED
@@ -1477,6 +1564,10 @@ methodAccess = AccessModifier.PRIVATE
     usingHashSetBuilder = OptionState.ENABLED,
     usingHashSetBuilderWithElementBuilders = OptionState.ENABLED,
     usingHashMapBuilder = OptionState.ENABLED,
+
+    // Builder Scoping
+    builderGenerationPackages = "com.example.dto",
+    builderUsagePackages = "com.example.library",
 
     // Integration & Annotations
     generateWithInterface = OptionState.ENABLED,

docs/CONTRIBUTING.md

@@ -240,6 +240,7 @@ For complete documentation, see [DEBUG_LOGGING.md](DEBUG_LOGGING.md).
 ========== Compilation Diagnostics ==========
 --- NOTES ---
 [DEBUG] simple-builders: Processing round started. Found 1 annotated elements.
+[DEBUG] simple-builders: 1 of 1 annotated element(s) are inside the builderGenerationPackages scope.
 [DEBUG] Processing element: Project
 [DEBUG] ├─ Extracting builder definition from: test.Project
 [DEBUG] │  ├─ Builder will be generated as: test.ProjectBuilder

docs/CUSTOMIZING.md

@@ -28,6 +28,10 @@ Simple-builders is designed to be extensible through custom generators and enhan
 
 All generators are managed by a unified `GeneratorRegistry` that loads both method generators and builder enhancers from a single service file, automatically separating them based on their type (using Java's sealed interface feature)
 
+Builder usage decisions are centralized in `BuilderScopeResolver`. Custom generators and enhancers
+do not need any changes: they continue to rely on `TypeName.getBuilderType().isPresent()` when
+checking whether a builder is available.
+
 ## Generator Interface
 
 Simple-builders uses a sealed `Generator` interface hierarchy that supports two types of functionality:

docs/DEBUG_LOGGING.md

@@ -92,6 +92,7 @@ When debug logging is enabled, you'll see detailed output with visual separators
 ```
 [INFO] simple-builders: PROCESSING ROUND START
 [INFO] [DEBUG] simple-builders: Processing round started. Found 3 annotated elements.
+[INFO] [DEBUG] simple-builders: 3 of 3 annotated element(s) are inside the builderGenerationPackages scope.
 [INFO] [DEBUG] Processing element: PersonDto
 [INFO] [DEBUG] ├─ Extracting builder definition from: org.example.PersonDto
 [INFO] [DEBUG] │  ├─ Builder will be generated as: org.example.PersonDtoBuilder
@@ -123,6 +124,9 @@ When debug logging is enabled, you'll see detailed output with visual separators
 [INFO] [DEBUG] ├─ Code generation for builder: CustomerDtoBuilder
 [INFO] [DEBUG] │  └─ Successfully generated builder: CustomerDtoBuilder
 [INFO]         simple-builders: Successfully generated 3 builder(s) in this processing round
+[INFO] simple-builders: PROCESSING ROUND START
+[INFO] [DEBUG] simple-builders: Processing round started. Found 0 annotated elements.
+[INFO] [DEBUG] simple-builders: 0 of 0 annotated element(s) are inside the builderGenerationPackages scope.
 ```
 
 **Note**: Debug messages are prefixed with `[DEBUG]` and use `Diagnostic.Kind.OTHER` which appears as `[INFO]` in Maven output.