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

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)
+  - [External Type Builder Example](#external-type-builder-example)
   - [Builder Scoping Example](#builder-scoping-example)
 - [Performance Measurement](#performance-measurement)
 - [Contributing](#contributing)
@@ -73,6 +74,7 @@ Value semantics (`equals`, `hashCode`, `toString`) and generating brand-new immu
 - **Annotation Preservation**: Validation annotations are automatically copied to builder methods
 - **With Interface Pattern**: Type-safe object modifications using generated With interfaces
 - **Jackson Support**: Supporting Jackson deserialization via `@JsonPOJOBuilder` and optional generation of `SimpleModule`s (one per package) (both need to be enabled)
+- **External Type Builders**: `@SimpleBuilderFor` generates builders for types that cannot be annotated - for example classes from third-party libraries
 - **JavaDoc Usage Examples**: Generated builder methods include auto-generated usage examples in their JavaDoc (per-method fluent snippets plus a class-level example), so IDE tooltips show exactly how to use each builder
 
 ## Requirements
@@ -466,6 +468,15 @@ 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
 
+### External Type Builder Example
+
+A runnable example of `@SimpleBuilderFor`, which generates builders for types that cannot carry `@SimpleBuilder` themselves:
+
+- **Declaration**: [`package-info.java`](example/src/main/java/org/javahelpers/simple/builders/example/package-info.java) - Declares `@SimpleBuilderFor(ExternalAddress.class)` on the package; generated builders land in the annotated package (a holder class may be used instead)
+- **External type**: [`external/ExternalAddress.java`](example/src/main/java/org/javahelpers/simple/builders/example/external/ExternalAddress.java) - Plain class simulating third-party code, no annotations
+- **Generated Builder**: [`ExternalAddressBuilder.java`](example/generated-example-builder/org/javahelpers/simple/builders/example/ExternalAddressBuilder.java)
+- **Tests**: [`ExternalAddressBuilderTest.java`](example/src/test/java/org/javahelpers/simple/builders/example/ExternalAddressBuilderTest.java)
+
 ### Builder Scoping Example
 
 A runnable example demonstrating package-scoped builder generation and usage:

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

@@ -0,0 +1,129 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2026 Andreas Igel
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+package org.javahelpers.simple.builders.core.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to generate builders for types that cannot or should not be modified, such as classes
+ * from third-party libraries.
+ *
+ * <p>Place this annotation on a dedicated holder class or on the package itself (in {@code
+ * package-info.java}) and list the external types in {@link #value()}. For every listed type a
+ * builder is generated following the same naming and generation conventions as for {@link
+ * SimpleBuilder} annotated classes, without changing the target type and without runtime
+ * reflection.
+ *
+ * <p>The generated builder is placed in the package of the class or package carrying this
+ * annotation. Only members of the target type that are accessible from that package (e.g. public
+ * constructors and setters, or package-visible members when the holder shares the target's package)
+ * are used for builder generation. If no suitable construction mechanism is available, generation
+ * fails with a compile-time error. The target type's own annotations are not consulted - the
+ * explicit declaration wins, so even an {@link Ignore4BuilderGeneration} on the target does not
+ * suppress generation. This annotation is intentionally not {@code @Inherited}: it declares
+ * generation for exactly the types listed on the annotated element.
+ *
+ * <p>See also the <a
+ * href="https://github.com/java-helpers/simple-builders/blob/main/docs/CONFIGURATION.md#generating-builders-for-external-types">
+ * Generating Builders for External Types section in CONFIGURATION.md</a>.
+ *
+ * <p>Example, declared on the package in {@code package-info.java} (generates the builder into
+ * {@code com.example}):
+ *
+ * <pre>{@code
+ * @SimpleBuilderFor(ExternalUser.class)
+ * package com.example;
+ * }</pre>
+ *
+ * <p>or on a dedicated provider class:
+ *
+ * <pre>{@code
+ * @SimpleBuilderFor(ExternalUser.class)
+ * public class ExternalBuildersProvider {
+ * }
+ *
+ * // Generated usage:
+ * ExternalUser user = ExternalUserBuilder.create()
+ *     .name("Ada")
+ *     .email("ada@example.com")
+ *     .build();
+ * }</pre>
+ *
+ * <p>Multiple external types can be listed in a single annotation and {@link #options()} may be
+ * omitted, in which case the compiler defaults apply:
+ *
+ * <pre>{@code
+ * @SimpleBuilderFor({ExternalUser.class, ExternalOrder.class})
+ * public class ExternalBuildersProvider {
+ * }
+ * }</pre>
+ *
+ * <p>Configuration uses the existing {@link SimpleBuilder.Options} model and may be overridden via
+ * compiler options:
+ *
+ * <pre>{@code
+ * @SimpleBuilderFor(
+ *     value = ExternalUser.class,
+ *     options = @SimpleBuilder.Options(
+ *         builderSuffix = "Factory"
+ *     )
+ * )
+ * public class ExternalBuildersProvider {
+ * }
+ * }</pre>
+ *
+ * @see SimpleBuilder
+ * @see SimpleBuilder.Options
+ * @see Ignore4BuilderGeneration
+ */
+@Target({ElementType.TYPE, ElementType.PACKAGE})
+@Retention(RetentionPolicy.CLASS)
+public @interface SimpleBuilderFor {
+
+  /**
+   * The types for which builders are generated. Every listed type must be resolvable on the
+   * classpath or in the current compilation and must be constructible through accessible Java APIs
+   * (e.g. an accessible constructor). At least one type is required.
+   *
+   * @return the external types to generate builders for
+   */
+  Class<?>[] value();
+
+  /**
+   * Configuration options for the generated builders, reusing the {@link SimpleBuilder.Options}
+   * model. When omitted, all members keep their {@code UNSET} default, so each option resolves as
+   * documented for the corresponding {@link SimpleBuilder.Options} member — falling back to the
+   * {@code -Asimplebuilder.*} compiler argument and then to the built-in default listed there. See
+   * the <a
+   * href="https://github.com/java-helpers/simple-builders/blob/main/docs/CONFIGURATION.md#compiler-options">
+   * Compiler Options section in CONFIGURATION.md</a>.
+   *
+   * @return the configuration options, defaulting to all members {@code UNSET}
+   */
+  SimpleBuilder.Options options() default @SimpleBuilder.Options;
+}

docs/CONFIGURATION.md

@@ -8,6 +8,7 @@ Simple-builders supports fine-grained configuration through the `@SimpleBuilder.
 - [Annotation Configuration](#annotation-configuration)
 - [Template Annotations](#template-annotations)
 - [Excluding Types from Builder Generation](#excluding-types-from-builder-generation)
+- [Generating Builders for External Types](#generating-builders-for-external-types)
 - [Compiler Options](#compiler-options)
   - [Maven Configuration](#maven-configuration)
   - [Gradle Configuration](#gradle-configuration)
@@ -169,6 +170,25 @@ public class IgnoredDto extends ParentDto {
 
 A type marked with `@Ignore4BuilderGeneration` is treated as having **no builder available**. Other builders that reference it will fall back to plain setters instead of emitting nested-builder consumers. The annotation is intentionally **not** `@Inherited`, so it only suppresses the exact type it is placed on and does not cascade to further subclasses.
 
+## Generating Builders for External Types
+
+`@SimpleBuilder` has to be placed on the type itself, which is not possible for types you cannot modify - for example classes or records from third-party libraries. `@SimpleBuilderFor` covers this case: declare it on the package itself in `package-info.java` (or on a dedicated provider class in your own code) and list the types a builder is generated for.
+
+```java
+// package-info.java - generates ExternalUserFactory and ExternalOrderFactory into this package
+@SimpleBuilderFor(
+    value = {ExternalUser.class, ExternalOrder.class},
+    options = @SimpleBuilder.Options(builderSuffix = "Factory"))
+package com.example;
+
+import org.javahelpers.simple.builders.core.annotations.SimpleBuilder;
+import org.javahelpers.simple.builders.core.annotations.SimpleBuilderFor;
+```
+
+The generated builders are placed in the annotated package - or in the package of the provider class when a class is annotated instead. `options` reuses `@SimpleBuilder.Options` and is optional - compiler defaults apply when omitted.
+
+The target type must be constructible through accessible Java APIs from the builder's package: it needs a visible type and an accessible constructor, otherwise generation fails with a compile-time diagnostic. The target type's own annotations are not consulted - the explicit declaration wins, so `@Ignore4BuilderGeneration` on the target does not suppress generation either. `@SimpleBuilderFor` is not `@Inherited`, and the provider class or package itself never gets a builder.
+
 ## Compiler Options
 
 Set project-wide defaults via compiler options. These apply to all builders unless overridden by annotations.

docs/CONTRIBUTING.md

@@ -239,7 +239,9 @@ 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: Processing round started.
+[DEBUG] simple-builders: Found 1 annotated elements.
+[DEBUG] simple-builders: Found 0 type(s) for generation with @SimpleBuilderFor.
 [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

docs/DEBUG_LOGGING.md

@@ -91,7 +91,9 @@ 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: Processing round started.
+[INFO] [DEBUG] simple-builders: Found 3 annotated elements.
+[INFO] [DEBUG] simple-builders: Found 0 type(s) for generation with @SimpleBuilderFor.
 [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
@@ -126,7 +128,9 @@ When debug logging is enabled, you'll see detailed output with visual separators
 [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: Processing round started.
+[INFO] [DEBUG] simple-builders: Found 0 annotated elements.
+[INFO] [DEBUG] simple-builders: Found 0 type(s) for generation with @SimpleBuilderFor.
 [INFO] [DEBUG] simple-builders: 0 of 0 annotated element(s) are inside the builderGenerationPackages scope.
 ```